Module oneshot 

The shared one-shot coordinator (303-PUBLIC-SQL-COORDINATOR-EXTRACTION-PLAN.md, PRs 1–4): the public-SQL batch, DDL, script, and migration orchestrations — validation, replay decisions, the statement loops with their byte accounting, the lost-race re-reads, and the migration replay/adopt matrix inside the host-owned barrier — written once over the OneShotBackend trait so a second write host implements the trait instead of re-deriving the control flow.

The trait is required, not defaulted (decision C1): a host implements it or the one-shot routes don’t exist, so one-shot support is a compile-time property. It is disjoint from the interactive SessionBackend — nothing in this flow calls the interactive begin/exec/commit, and session.rs imports nothing from this module.

No function here reads a clock (decision C2): entry points take now_ms and the backend’s floor method injects the host’s own clock.

Structs

PublicMigrateAck

The typed outcome of one public migration: applied is false on an exact replay. The cursor is required — a fresh apply always commits one, and a replay either resolves the exact stored cursor or refuses MIGRATION_OUTCOME_UNAVAILABLE (extraction plan C6).

PublicOperationCommit

The typed outcome of one committed — or exactly replayed — public one-shot operation. results are wire-encoded statement results (the dedicated tagged SQL codec), so a stored replay is byte-equivalent to the fresh commit; the hosts wrap this in their own success envelope (decision C7 — routing metadata and the HTTP layer stay per-host).

ScriptOutcome

The typed outcome of one public script (execute-multiple). A script never fails at the top level — failure is data: the completed prefix’s wire-encoded results, the last committed statement’s cursor, and the failing statement’s index with its pre-classified error. The hosts render failure through render_public_script_error and wrap success per-host (decision C7).

Traits

MigrationSection

The migration-store view OneShotBackend::with_migration_barrier passes to its closure. Reads carry NO decisions — the replay/adopt matrix over them is execute_public_migration’s, the same compiled code on every host; every op executes under the barrier’s exclusion span.

OneShotBackend

The backend contract of the one-shot public SQL surface. The master implements it over its session-transaction primitives; a standalone daemon implements it over its own store (303 S5). Every method returns pre-classified WritePlaneError — classification happens once, host-side, and there is no conversion back out (decision C3).

PublicReplayReads

The three reads behind the shared replay spine, generic over the host’s error currency. The coordinator instantiates it over OneShotBackend (with WritePlaneError); the replicator’s transaction-outcome cursor path instantiates it over a raw connection with MasterError — ONE decision matrix and ONE resolver, no twin, which is what decision C4 means by “generic by construction”.

Functions

execute_public_batch

Execute one public SQL batch: validate the idempotency key against the caller’s now_ms (future skew bounded — the coordinator reads no clock), check for an exact replay, then run every statement inside one backend transaction while bounding the encoded result array — the JSON array delimiters (2 bytes) and inter-result separators count toward aggregate_result_byte_limit — and commit with the outcome row. Any statement or accounting error rolls the unit back. A commit error is re-read: a concurrent request carrying the same identity may have won while this attempt was open, and its co-transactional outcome is authoritative — the exact stored bytes are returned instead of a duplicate-key/conflict error.

execute_public_ddl

Execute one public DDL operation: validate the idempotency key against the caller’s now_ms, refuse non-DDL statements before any backend call, check for an exact replay, then hand the fresh apply to the backend’s critical section as one atomic unit (OneShotBackend::apply_public_ddl).

execute_public_migration

Execute one public migration (extraction plan C6): apply a permanent, checksum-guarded migration identity, where reusing an id with identical bytes is an exact replay and reusing it for different DDL is refused instead of silently accepting schema drift.

execute_public_script

Execute one public script (execute-multiple): an ORDERED sequence of autocommit units, each dispatched by statement class into execute_public_batch (reads/writes) or execute_public_ddl (DDL) under a per-index derived idempotency key — sql-script:<key>:<index>. Replay identity across retries depends on that exact format: every completed statement’s outcome is stored under its derived key, so a retry of the whole script replays the durable prefix instead of re-applying it, then resumes at the statement that failed. Transaction-control statements and classes outside the v1 surface are refused without reaching the backend.

resolve_public_outcome_cursor

Resolve the exact cursor carried by one retained outcome row — resolve_replay_cursor wired to the outcome surface: the run_id scan, and the durable outcome row as the GC-race re-read.

resolve_replay_cursor

The ONE exact-cursor resolution algorithm (decision C4), generic over the durable row it resolves: the stored cursor short-circuits, then the legacy run_id scan, then the GC-race re-read of the durable row filtered on the same run_id — journal GC may have backfilled the row and removed the run frame between the first read and the scan, so the re-read is what carries correctness. The outcome surface wires it to the outcome row (resolve_public_outcome_cursor); the migration surface wires it to the section’s scan with record() as the re-read leg, inside the barrier.

stored_public_operation

The replay spine at the coordinator surface: stored_public_operation_over driven through the backend trait. Used by both the batch and DDL flows.

stored_public_operation_over

The shared replay decision matrix (decision C4), generic over the host error: a miss whose key minted at or below the retention floor fails closed (OPERATION_OUTCOME_EXPIRED); a stored request identity that differs from the retry refuses (OPERATION_ID_MISMATCH); a run_id-bearing outcome whose exact cursor cannot be resolved refuses (OPERATION_OUTCOME_EXPIRED) rather than answer with a fabricated cursor.