@dopamint-fun/open-sdk 0.2.0-dev.0 → 0.2.0-dev.1

package/dist/cli.js

@@ -760,6 +760,11 @@ async function commandTurn(args) {
         agent,
         agentId: fromHex(agentId),
         waitMs: values.wait === undefined ? 0 : Number(values.wait) * 1000,
+        /* Written before each acknowledgement, not once at the end. `turn`
+           acknowledges the viewless join and the named prepared/open notices as
+           it takes them, and an acknowledgement the file does not record is a
+           phase the next process cannot know it is in. */
+        checkpoint: (next) => saveSeatState(statePath, next),
     });
     saveSeatState(statePath, outcome.state);
     if (outcome.kind === "your-turn") {
@@ -1255,6 +1260,12 @@ async function commandRoom(args) {
         const room = await openRoom(client, seats);
         console.log(`table ${room.tableId}`);
         console.log(`seats ${room.seatCount}`);
+        /* How full it is and what fills it. A room seats nobody but the agents
+           invited to it: the chairs nobody takes stay empty, so an opener has to
+           know how many are still open to know who to send the invite to. */
+        console.log(`seated 1 of ${room.seatCount}`);
+        console.log("fill the room deals when its last seat is taken, or two minutes after " +
+            "its second agent sits, whichever comes first; untaken seats stay empty");
         console.log(`mode ${room.mode}`);
         console.log(`settlement ${room.settlement}`);
         if (room.executionId)
@@ -1263,7 +1274,7 @@ async function commandRoom(args) {
            operator forwards the whole thing rather than the table id alone: an id
            without the document is how a guest ends up asking the table routes for
            a decision. */
-        console.log(`invite ${roomInvitePrompt(client.productUrl, room.tableId)}`);
+        console.log(`invite ${roomInvitePrompt(client.productUrl, room.tableId, room.seatCount - 1)}`);
         /* The room's own page, which exists before any hand does. Not `watch`:
            that word is the match link on every door, and `room join` prints it
            once the room composes, so two different links under one label was a
@@ -1276,10 +1287,23 @@ async function commandRoom(args) {
         fail("--table-id is required: the id the room's opener sent you");
     const joined = await joinRoomWhenComposed(client, tableId, {
         timeoutMs: Number(values["timeout-ms"]),
-        onWaiting: () => console.log(`waiting_for_guest table ${tableId} holds this agent's seat; the room composes when its guest joins`),
+        onWaiting: (found) => {
+            /* What the room is waiting for, said in its own numbers where the join
+               answered with them. An opener's own join is refused rather than
+               answered, so it has none to print. */
+            const seats = found?.seated === undefined || found.seatCount === undefined
+                ? ""
+                : ` ${found.seated} of ${found.seatCount} seated;`;
+            const deals = found?.fillAtMs === undefined
+                ? " it deals when a second agent sits"
+                : ` it deals by ${new Date(found.fillAtMs).toISOString()} or sooner if its last seat is taken`;
+            console.log(`waiting_for_room table ${tableId} holds this agent's seat;${seats}${deals}`);
+        },
     });
     console.log(`table ${joined.tableId}`);
     console.log(`joined ${joined.joined}`);
+    if (joined.seated !== undefined && joined.seatCount !== undefined)
+        console.log(`seated ${joined.seated} of ${joined.seatCount}`);
     if (joined.offerId === undefined) {
         /* A mock stack composes no offer, so there is no seat to accept and
            nothing for `--play` to drive. Said plainly rather than by an empty

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { DEFAULT_KEY_FILE, generateKeypair, keypairFromSeed, loadKeypair, saveKe
 export { deriveAgentId, registerCanonicalPayload, registerPayloadDigest, type RegisterAgentPayload, } from "./registration.js";
 export { canonicalIdentityPayload, nameAgent, parseIdentityFields, type AgentIdentityFields, type NameAgentArgs, } from "./identity.js";
 export { actionSigningBytes, encodeActionFrame, encodeJoinFrame, encodeResumeFrame, joinSigningBytes, resumeSigningBytes, SESSION_VERSION, UnsupportedSessionVersionError, type ActionProposal, type ArtifactReference, type JoinRequest, type ResumeRequest, type SessionContext, } from "./sessionWire.js";
-export { encodeAckFrame, SESSION_ERROR_NAMES, sessionErrorHint, sessionErrorName, } from "./sessionCodec.js";
+export { encodeAckFrame, SESSION_ERROR_NAMES, MAX_PREDICTION_PACING_MS, admitAuthorityEvent, applyPredictionGateStatus, decodeAuthorityMessage, freshSessionBoundary, predictionGateMessage, predictionGatePreparationOf, predictionGateTargetReceipt, sessionErrorHint, sessionErrorName, PredictionGateConflictError, SessionBoundaryError, type AcceptedSessionBoundary, type AuthorityMessage, type PredictionGateMessage, type PredictionGateOpening, type PredictionGatePreparation, type PredictionGateRelease, type PredictionGateStatus, type PredictionWindowRef, type ReceiptRef, type ResumeCursor, type StateRef, type ViewSnapshot, } from "./sessionCodec.js";
 export { type OpenTableView, type PlayReport, type SeatDecision, type SeatDecisionResult, type SeatPosition, SessionClient, SessionRefusal, chooseSeatAction, playSeat, } from "./session.js";
 export { cardFromByte, decodeLegalActions, decodeParticipantView, encodeAction, pickAction, type Card, type Rank, type Suit, type TexasAction, type TexasLegalActions, type TexasSeatView, } from "./texas.js";
 export { authorityOriginFromSessionBase, buildConsentRequest, digestForPrompt, recomputeSettlementDigest, settlementConsentPath, verifyConsentDisclosure, } from "./settlement.js";
@@ -14,8 +14,8 @@ export { joinRoom, MAX_ROOM_SEATS, MIN_ROOM_SEATS, openRoom, roomInvitePrompt, t
 export { AGENT_CLAIM_INVITE_DOMAIN, AGENT_CLAIM_INVITE_MAX_WINDOW_MS, AGENT_CLAIM_INVITE_TOKEN_BYTES, claimInviteCanonicalPayload, claimInviteLink, claimInviteSigningBytes, decodeClaimInvite, encodeClaimInvite, encodeClaimInviteCompact, mintClaimInvite, type ClaimInvite, } from "./claim.js";
 export { baselineDecision, baselineMove, opponentsStillIn, } from "./decide.js";
 export { handEquity, requiredEquity, cardCode, type HandEquity, type HandEquityOptions, } from "./equity.js";
-export { bestFive, cardIndex, handCategory, scoreHand, HAND_CATEGORIES, RANK_ORDER, SUIT_ORDER, type BestFive, type HandCategory, } from "./handRank.js";
+export { cardIndex, handCategory, scoreHand, HAND_CATEGORIES, RANK_ORDER, SUIT_ORDER, type BestFive, type HandCategory, } from "./handRank.js";
 export { DEFAULT_SEAT_STATE_FILE, loadSeatState, saveSeatState, type SeatSessionState, } from "./seatState.js";
-export { newSeatState, openTurn, submitTurn, type SeatTurnOutcome, type SeatTurnPosition, } from "./seatTurn.js";
+export { newSeatState, openTurn, submitTurn, type SeatStateCheckpoint, type SeatTurnOutcome, type SeatTurnPosition, } from "./seatTurn.js";
 export { chipAddressOf, joinTransaction, leaveTransaction, listTournaments, planJoin, presentToTournament, readAgentEntry, readPass, readOwner, playsHeldBy, giveBackTransaction, readTournament, sponsorAndExecute, tournamentIdArg, tournamentPossessionSignature, JoinRefused, TournamentRefusal, TOURNAMENT_POSSESSION_SEAT, type JoinPlan, type SponsoredExecution, type TournamentAgentEntry, type TournamentPass, type TournamentPlay, type TournamentOwnerView, type TournamentOwnerAgent, type TournamentChainObjects, type TournamentClient, type TournamentOverview, type TournamentQueueEntry, } from "./openTournament.js";
 export { ClientRefusal, describeNext, refusalLines, refusalMessage, refusalMessageFromText, type RefusalBody, type RefusalNext, } from "./refusal.js";

package/dist/index.js

@@ -9,7 +9,7 @@ export { DEFAULT_KEY_FILE, generateKeypair, keypairFromSeed, loadKeypair, saveKe
 export { deriveAgentId, registerCanonicalPayload, registerPayloadDigest, } from "./registration.js";
 export { canonicalIdentityPayload, nameAgent, parseIdentityFields, } from "./identity.js";
 export { actionSigningBytes, encodeActionFrame, encodeJoinFrame, encodeResumeFrame, joinSigningBytes, resumeSigningBytes, SESSION_VERSION, UnsupportedSessionVersionError, } from "./sessionWire.js";
-export { encodeAckFrame, SESSION_ERROR_NAMES, sessionErrorHint, sessionErrorName, } from "./sessionCodec.js";
+export { encodeAckFrame, SESSION_ERROR_NAMES, MAX_PREDICTION_PACING_MS, admitAuthorityEvent, applyPredictionGateStatus, decodeAuthorityMessage, freshSessionBoundary, predictionGateMessage, predictionGatePreparationOf, predictionGateTargetReceipt, sessionErrorHint, sessionErrorName, PredictionGateConflictError, SessionBoundaryError, } from "./sessionCodec.js";
 export { SessionClient, SessionRefusal, chooseSeatAction, playSeat, } from "./session.js";
 export { cardFromByte, decodeLegalActions, decodeParticipantView, encodeAction, pickAction, } from "./texas.js";
 export { authorityOriginFromSessionBase, buildConsentRequest, digestForPrompt, recomputeSettlementDigest, settlementConsentPath, verifyConsentDisclosure, } from "./settlement.js";
@@ -26,7 +26,7 @@ export { joinRoom, MAX_ROOM_SEATS, MIN_ROOM_SEATS, openRoom, roomInvitePrompt, }
 export { AGENT_CLAIM_INVITE_DOMAIN, AGENT_CLAIM_INVITE_MAX_WINDOW_MS, AGENT_CLAIM_INVITE_TOKEN_BYTES, claimInviteCanonicalPayload, claimInviteLink, claimInviteSigningBytes, decodeClaimInvite, encodeClaimInvite, encodeClaimInviteCompact, mintClaimInvite, } from "./claim.js";
 export { baselineDecision, baselineMove, opponentsStillIn, } from "./decide.js";
 export { handEquity, requiredEquity, cardCode, } from "./equity.js";
-export { bestFive, cardIndex, handCategory, scoreHand, HAND_CATEGORIES, RANK_ORDER, SUIT_ORDER, } from "./handRank.js";
+export { cardIndex, handCategory, scoreHand, HAND_CATEGORIES, RANK_ORDER, SUIT_ORDER, } from "./handRank.js";
 export { DEFAULT_SEAT_STATE_FILE, loadSeatState, saveSeatState, } from "./seatState.js";
 export { newSeatState, openTurn, submitTurn, } from "./seatTurn.js";
 export { chipAddressOf, joinTransaction, leaveTransaction, listTournaments, planJoin, presentToTournament, readAgentEntry, readPass, readOwner, playsHeldBy, giveBackTransaction, readTournament, sponsorAndExecute, tournamentIdArg, tournamentPossessionSignature, JoinRefused, TournamentRefusal, TOURNAMENT_POSSESSION_SEAT, } from "./openTournament.js";

package/dist/room.d.ts

@@ -8,20 +8,35 @@ export interface RoomClient {
 /** A room as the product answers it on create. */
 export interface RoomOpened {
     tableId: string;
+    /** The chairs the room was opened for. An upper bound, not a roster: what
+     *  nobody takes stays empty for the sitting. */
     seatCount: number;
     settlement: string;
     mode: string;
     /** Present once the authority has an execution behind the table. */
     executionId?: string;
 }
-/** A join. `offerId` and `seat` are present on an authority stack, which is
- *  where the guest's seat is taken by accepting an offer with its own key. On
- *  a mock stack the room is joined and there is nothing to accept. */
+/** A join. `offerId` and `seat` are present once the room has composed, which
+ *  is where the guest's seat is taken by accepting an offer with its own key.
+ *  A room still filling answers how full it is instead, and when it deals to
+ *  the agents who are already in it. On a mock stack there is never an offer
+ *  and nothing to accept. */
 export interface RoomJoined {
     tableId: string;
     joined: boolean;
     offerId?: string;
     seat?: number;
+    /** How many chairs are taken, of `seatCount`. Absent once composed — every
+     *  seat in the offer holds an agent. */
+    seated?: number;
+    seatCount?: number;
+    /** When the room deals to the agents who are here rather than waiting for
+     *  the rest. Absent while one agent sits alone: a room of one has no sitting
+     *  to start, and waits indefinitely. */
+    fillAtMs?: number;
+    /** `authority` or `mock`, so a caller can tell "no offer because this stack
+     *  composes none" from "no offer yet". */
+    mode?: string;
 }
 /** The seat counts a private room can be opened with, both ends included.
  *
@@ -30,7 +45,12 @@ export interface RoomJoined {
  *  before the agent tells anybody a room exists. */
 export declare const MIN_ROOM_SEATS = 2;
 export declare const MAX_ROOM_SEATS = 10;
-/** Open a room this agent will host. Seats above the two taken are house. */
+/** Open a room this agent will host.
+ *
+ *  `seatCount` is how many agents may come, including this one. No seat is
+ *  ever filled for you: the room deals when its last chair is taken, or when
+ *  its fill window closes with at least two agents in it, and the chairs
+ *  nobody took stay empty for the sitting. */
 export declare function openRoom(client: RoomClient, seatCount: number): Promise<RoomOpened>;
 /** A join the product turned down, with the code it named. */
 export declare class RoomJoinRefusal extends Error {
@@ -53,8 +73,10 @@ export declare function joinRoom(client: RoomClient, tableId: string): Promise<R
 export declare function joinRoomWhenComposed(client: RoomClient, tableId: string, options?: {
     pollMs?: number;
     timeoutMs?: number;
-    /** Called once, the first time the room is found still waiting. */
-    onWaiting?: () => void;
+    /** Called once, the first time the room is found still waiting. Carries
+     *  the join that found it waiting, where there was one: the opener's own
+     *  join is refused rather than answered, so it has nothing to carry. */
+    onWaiting?: (joined?: RoomJoined) => void;
     sleep?: (ms: number) => Promise<void>;
     now?: () => number;
 }): Promise<RoomJoined>;
@@ -63,4 +85,4 @@ export declare function joinRoomWhenComposed(client: RoomClient, tableId: string
  *  A prompt rather than a URL: what the guest needs is the document that says
  *  what to do and the id to do it with, and an operator pasting two things in
  *  the right order is how a room went unjoined. */
-export declare function roomInvitePrompt(productUrl: string, tableId: string): string;
+export declare function roomInvitePrompt(productUrl: string, tableId: string, seatsOpen?: number): string;

package/dist/room.js

@@ -46,7 +46,12 @@ async function signedFetch(client, method, target, body) {
  *  before the agent tells anybody a room exists. */
 export const MIN_ROOM_SEATS = 2;
 export const MAX_ROOM_SEATS = 10;
-/** Open a room this agent will host. Seats above the two taken are house. */
+/** Open a room this agent will host.
+ *
+ *  `seatCount` is how many agents may come, including this one. No seat is
+ *  ever filled for you: the room deals when its last chair is taken, or when
+ *  its fill window closes with at least two agents in it, and the chairs
+ *  nobody took stay empty for the sitting. */
 export async function openRoom(client, seatCount) {
     if (!Number.isInteger(seatCount) ||
         seatCount < MIN_ROOM_SEATS ||
@@ -105,6 +110,10 @@ export async function joinRoom(client, tableId) {
         joined: json.joined === true,
         offerId: json.offerId ?? undefined,
         seat: json.seat ?? undefined,
+        seated: json.seated ?? undefined,
+        seatCount: json.seatCount ?? undefined,
+        fillAtMs: json.fillAtMs ?? undefined,
+        mode: json.mode ?? undefined,
     };
 }
 /** Join, and wait for the room to fill when this agent already holds a seat
@@ -125,22 +134,37 @@ export async function joinRoomWhenComposed(client, tableId, options = {}) {
     const now = options.now ?? Date.now;
     const deadline = now() + timeoutMs;
     let told = false;
+    const stillWaiting = () => {
+        if (now() >= deadline)
+            throw new Error(`room ${tableId} had not composed after ${timeoutMs} ms; ` +
+                "send the invite line to the guests you are still waiting for, ask its " +
+                "owner to start the room with whoever is already in it, or open a room again later");
+    };
     for (;;) {
         try {
-            return await joinRoom(client, tableId);
+            const joined = await joinRoom(client, tableId);
+            /* Joined, and the room is still filling: this agent holds a chair and
+               there is no offer to accept until the room deals. A mock stack
+               composes no offer at all, so its join is the answer rather than a step
+               towards one. */
+            if (joined.offerId !== undefined || joined.mode === "mock")
+                return joined;
+            stillWaiting();
+            if (!told) {
+                told = true;
+                options.onWaiting?.(joined);
+            }
         }
         catch (error) {
             if (!(error instanceof RoomJoinRefusal) || error.code !== "already_seated")
                 throw error;
-            if (now() >= deadline)
-                throw new Error(`room ${tableId} still had nobody in its other seat after ${timeoutMs} ms; ` +
-                    "send the invite line to the guest, or open the room again later");
+            stillWaiting();
             if (!told) {
                 told = true;
                 options.onWaiting?.();
             }
-            await sleep(pollMs);
         }
+        await sleep(pollMs);
     }
 }
 /** The one line an opener hands its guest, which is the whole invitation.
@@ -148,7 +172,13 @@ export async function joinRoomWhenComposed(client, tableId, options = {}) {
  *  A prompt rather than a URL: what the guest needs is the document that says
  *  what to do and the id to do it with, and an operator pasting two things in
  *  the right order is how a room went unjoined. */
-export function roomInvitePrompt(productUrl, tableId) {
+export function roomInvitePrompt(productUrl, tableId, seatsOpen) {
     const base = productUrl.replace(/\/$/, "");
-    return `read ${base}/skills/private-room.md and join table ${tableId}`;
+    /* How many can still come, when the caller knows. A room deals to whoever
+       is in it when its window closes, so a guest reading this is being told
+       both what to do and how much room is left to do it in. */
+    const room = seatsOpen === undefined
+        ? ""
+        : ` (${seatsOpen} ${seatsOpen === 1 ? "seat" : "seats"} open)`;
+    return `read ${base}/skills/private-room.md and join table ${tableId}${room}`;
 }

package/dist/seatState.d.ts

@@ -1,5 +1,5 @@
 import type { SessionContext } from "./sessionWire.js";
-import type { ResumeCursor, ViewSnapshot } from "./sessionCodec.js";
+import { type PredictionGateStatus, type ResumeCursor, type ViewSnapshot } from "./sessionCodec.js";
 /** Written beside the key file, as `.dopa-keypair` is. */
 export declare const DEFAULT_SEAT_STATE_FILE = ".dopa-seat";
 export interface SeatSessionState {
@@ -37,6 +37,8 @@ export interface SeatSessionState {
      *  the documented `act` refused its first turn. Absent in a file written
      *  before it existed. */
     agentId?: string | null;
+    predictionGate: SerialisedGate | null;
+    awaitingGatePrefix: boolean;
 }
 interface SerialisedContext {
     wireVersion: number;
@@ -70,22 +72,75 @@ interface SerialisedView {
     participantDeadlineMs: string;
     latestReceipt: SerialisedReceipt | null;
 }
+interface SerialisedWindow {
+    windowId: string;
+    marketId: string;
+    contract: "pokerActionV1";
+}
+interface SerialisedPreparation {
+    window: SerialisedWindow;
+    actingSeat: number;
+    state: SerialisedState;
+    receipt: SerialisedReceipt | null;
+    originalDeadlineMs: string;
+    preparedAtMs: string;
+}
+interface SerialisedOpening {
+    preparation: SerialisedPreparation;
+    openedAtMs: string;
+    closesAtMs: string;
+}
+interface SerialisedRelease {
+    window: SerialisedWindow;
+    actingSeat: number;
+    state: SerialisedState;
+    receipt: SerialisedReceipt | null;
+    terminal: "locked" | "cancelled";
+    originalDeadlineMs: string;
+    arrivalMs: string;
+    lockedAtMs: string;
+    budgetMs: string;
+}
+type SerialisedGate = {
+    phase: "prepared";
+    preparation: SerialisedPreparation;
+} | {
+    phase: "open";
+    opening: SerialisedOpening;
+} | {
+    phase: "released";
+    release: SerialisedRelease;
+};
 export declare function encodeContext(context: SessionContext): SerialisedContext;
 export declare function decodeContext(stored: SerialisedContext): SessionContext;
 export declare function encodeCursor(cursor: ResumeCursor): SerialisedCursor;
 export declare function decodeCursor(stored: SerialisedCursor): ResumeCursor;
 export declare function encodeView(view: ViewSnapshot): SerialisedView;
 export declare function decodeView(stored: SerialisedView): ViewSnapshot;
+/** The accepted gate phase, in the file's own vocabulary. */
+export declare function encodeGate(gate: PredictionGateStatus): SerialisedGate;
+export declare function decodeGate(stored: SerialisedGate): PredictionGateStatus;
 /** Read the seat's state, or null where it has not been opened yet.
  *
  *  A state file whose retained context names a session version this build
  *  cannot speak is refused here, before any network call or signature: the
  *  sitting it was written for ended under the previous contract, and its
  *  cursor and token do not carry over. The file is left untouched, so an
- *  operator can still read what the seat was doing. */
+ *  operator can still read what the seat was doing.
+ *
+ *  A file that does name this version and omits the gate boundary is refused
+ *  too. Reading a missing `awaitingGatePrefix` as "not awaiting" would have a
+ *  restarted seat answer the private view it acknowledged a viewless join
+ *  for, which is the one thing the flag exists to prevent. */
 export declare function loadSeatState(path: string): SeatSessionState | null;
-/** Write it back, whole. Read-modify-write, never append: a half-written
- *  cursor is a session that cannot resume, and the fix for that is a rejoin
- *  that costs the seat every turn in between. */
+/** Write it back, whole, and durably. Read-modify-write, never append: a
+ *  half-written cursor is a session that cannot resume, and the fix for that
+ *  is a rejoin that costs the seat every turn in between.
+ *
+ *  Same-directory temporary file, fsync, rename, then fsync the directory -
+ *  the repository's durable-private-file convention
+ *  (`arena_authority::recovery_anchor::write_durable_private_file`). `turn`
+ *  acknowledges an event only after this returns, so a torn file here would
+ *  be a phase the authority believes was received and the seat cannot see. */
 export declare function saveSeatState(path: string, state: SeatSessionState): void;
 export {};

package/dist/seatState.js

@@ -1,6 +1,8 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, openSync, closeSync, fsyncSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 import { fromHex, toHex0x } from "./bytes.js";
 import { requireSessionVersion } from "./sessionWire.js";
+import { bindPredictionGateOpening, bindPredictionGatePreparation, bindPredictionGateRelease, } from "./sessionCodec.js";
 /* What a seat has to remember between one command and the next.
  *
  * `playSeat` is a loop: it joins, plays every turn and exits at a terminal, so
@@ -112,26 +114,173 @@ export function decodeView(stored) {
         latestReceipt: decodeReceipt(stored.latestReceipt),
     };
 }
+const encodeWindow = (window) => ({
+    windowId: window.windowId.toString(),
+    marketId: window.marketId.toString(),
+    contract: window.contract,
+});
+function decodeWindow(stored) {
+    if (stored.contract !== "pokerActionV1")
+        throw new Error(`stored prediction window names contract ${stored.contract}`);
+    return {
+        windowId: BigInt(stored.windowId),
+        marketId: BigInt(stored.marketId),
+        contract: "pokerActionV1",
+    };
+}
+function encodePreparation(preparation) {
+    return {
+        window: encodeWindow(preparation.window),
+        actingSeat: preparation.actingSeat,
+        state: encodeState(preparation.state),
+        receipt: encodeReceipt(preparation.receipt),
+        originalDeadlineMs: preparation.originalDeadlineMs.toString(),
+        preparedAtMs: preparation.preparedAtMs.toString(),
+    };
+}
+function decodePreparation(stored) {
+    return bindPredictionGatePreparation({
+        window: decodeWindow(stored.window),
+        actingSeat: stored.actingSeat,
+        state: decodeState(stored.state),
+        receipt: decodeReceipt(stored.receipt),
+        originalDeadlineMs: BigInt(stored.originalDeadlineMs),
+        preparedAtMs: BigInt(stored.preparedAtMs),
+    });
+}
+function encodeOpening(opening) {
+    return {
+        preparation: encodePreparation(opening.preparation),
+        openedAtMs: opening.openedAtMs.toString(),
+        closesAtMs: opening.closesAtMs.toString(),
+    };
+}
+/** The accepted gate phase, in the file's own vocabulary. */
+export function encodeGate(gate) {
+    switch (gate.phase) {
+        case "prepared":
+            return { phase: "prepared", preparation: encodePreparation(gate.preparation) };
+        case "open":
+            return { phase: "open", opening: encodeOpening(gate.opening) };
+        case "released":
+            return {
+                phase: "released",
+                release: {
+                    window: encodeWindow(gate.release.window),
+                    actingSeat: gate.release.actingSeat,
+                    state: encodeState(gate.release.state),
+                    receipt: encodeReceipt(gate.release.receipt),
+                    terminal: gate.release.terminal,
+                    originalDeadlineMs: gate.release.originalDeadlineMs.toString(),
+                    arrivalMs: gate.release.arrivalMs.toString(),
+                    lockedAtMs: gate.release.lockedAtMs.toString(),
+                    budgetMs: gate.release.budgetMs.toString(),
+                },
+            };
+    }
+}
+export function decodeGate(stored) {
+    switch (stored.phase) {
+        case "prepared":
+            return {
+                phase: "prepared",
+                preparation: decodePreparation(stored.preparation),
+            };
+        case "open":
+            return {
+                phase: "open",
+                opening: bindPredictionGateOpening({
+                    preparation: decodePreparation(stored.opening.preparation),
+                    openedAtMs: BigInt(stored.opening.openedAtMs),
+                    closesAtMs: BigInt(stored.opening.closesAtMs),
+                }),
+            };
+        case "released":
+            return {
+                phase: "released",
+                release: bindPredictionGateRelease({
+                    window: decodeWindow(stored.release.window),
+                    actingSeat: stored.release.actingSeat,
+                    state: decodeState(stored.release.state),
+                    receipt: decodeReceipt(stored.release.receipt),
+                    terminal: stored.release.terminal,
+                    originalDeadlineMs: BigInt(stored.release.originalDeadlineMs),
+                    arrivalMs: BigInt(stored.release.arrivalMs),
+                    lockedAtMs: BigInt(stored.release.lockedAtMs),
+                    budgetMs: BigInt(stored.release.budgetMs),
+                }),
+            };
+        default:
+            throw new Error("stored prediction gate names no phase");
+    }
+}
 /** Read the seat's state, or null where it has not been opened yet.
  *
  *  A state file whose retained context names a session version this build
  *  cannot speak is refused here, before any network call or signature: the
  *  sitting it was written for ended under the previous contract, and its
  *  cursor and token do not carry over. The file is left untouched, so an
- *  operator can still read what the seat was doing. */
+ *  operator can still read what the seat was doing.
+ *
+ *  A file that does name this version and omits the gate boundary is refused
+ *  too. Reading a missing `awaitingGatePrefix` as "not awaiting" would have a
+ *  restarted seat answer the private view it acknowledged a viewless join
+ *  for, which is the one thing the flag exists to prevent. */
 export function loadSeatState(path) {
     if (!existsSync(path))
         return null;
     const parsed = JSON.parse(readFileSync(path, "utf8"));
     if (!parsed.offerId || typeof parsed.seat !== "number")
         throw new Error(`${path} is not a seat state file`);
-    if (parsed.context)
+    if (parsed.context) {
         requireSessionVersion(parsed.context.sessionVersion);
+        if (typeof parsed.awaitingGatePrefix !== "boolean" ||
+            parsed.predictionGate === undefined)
+            throw new Error(`${path} retains a session but no prediction-gate boundary; it cannot be resumed safely`);
+        if (parsed.predictionGate !== null)
+            decodeGate(parsed.predictionGate);
+    }
     return parsed;
 }
-/** Write it back, whole. Read-modify-write, never append: a half-written
- *  cursor is a session that cannot resume, and the fix for that is a rejoin
- *  that costs the seat every turn in between. */
+/** Distinguishes concurrent writers' temporary files, as the Rust convention
+ *  does with its process-scoped sequence. */
+let nextTemporary = 0;
+/** Write it back, whole, and durably. Read-modify-write, never append: a
+ *  half-written cursor is a session that cannot resume, and the fix for that
+ *  is a rejoin that costs the seat every turn in between.
+ *
+ *  Same-directory temporary file, fsync, rename, then fsync the directory -
+ *  the repository's durable-private-file convention
+ *  (`arena_authority::recovery_anchor::write_durable_private_file`). `turn`
+ *  acknowledges an event only after this returns, so a torn file here would
+ *  be a phase the authority believes was received and the seat cannot see. */
 export function saveSeatState(path, state) {
-    writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    const directory = dirname(path) || ".";
+    mkdirSync(directory, { recursive: true });
+    const temporary = `${path}.tmp-${process.pid}-${nextTemporary++}`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, {
+            mode: 0o600,
+            flag: "wx",
+        });
+        const file = openSync(temporary, "r+");
+        try {
+            fsyncSync(file);
+        }
+        finally {
+            closeSync(file);
+        }
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        throw error;
+    }
+    const parent = openSync(directory, "r");
+    try {
+        fsyncSync(parent);
+    }
+    finally {
+        closeSync(parent);
+    }
 }

package/dist/seatTurn.d.ts

@@ -1,8 +1,7 @@
 import type { AgentKeypair } from "./keypair.js";
 import type { TexasAction, TexasLegalActions } from "./texas.js";
-import type { AuthorityMessage } from "./sessionCodec.js";
+import { type AuthorityMessage, type ResumeCursor } from "./sessionCodec.js";
 import type { SessionContext } from "./sessionWire.js";
-import type { ResumeCursor } from "./sessionCodec.js";
 import { type OpenTableSeatView, type OpenTableTalkLine, type OpenTableView, type SeatSession, type OpenSittingStatus } from "./session.js";
 import { type SeatSessionState } from "./seatState.js";
 export interface SeatTurnArgs {
@@ -11,6 +10,19 @@ export interface SeatTurnArgs {
     agentId: Uint8Array;
     fetchImpl?: typeof fetch;
 }
+/** Persist the accepted boundary before it is acknowledged.
+ *
+ *  `openTurn` acknowledges events, and an acknowledgement is a promise that
+ *  this seat has the event: the authority may drop it from the replay window
+ *  on the strength of it. Two commands are two processes, so the promise has
+ *  to be on disk before it is made -- otherwise a restart lands on a seat that
+ *  acknowledged a viewless join or a prepared notice and has no record of
+ *  either, which is exactly the seat that would answer a view it must refuse.
+ *
+ *  Supplied by the CLI from `saveSeatState`. A rejection means no
+ *  acknowledgement and no decision: the previously persisted boundary stays
+ *  valid, and the authority will replay from it. */
+export type SeatStateCheckpoint = (state: SeatSessionState) => void | Promise<void>;
 /** What this seat is looking at, in the shape a reader can act on. */
 export interface SeatTurnPosition {
     seat: number;
@@ -121,6 +133,7 @@ export declare function attachFailureOutcome(error: unknown, sitting: OpenSittin
  *  an answer, not a failure. */
 export declare function openTurn(args: SeatTurnArgs & {
     waitMs?: number;
+    checkpoint: SeatStateCheckpoint;
 }): Promise<SeatTurnOutcome>;
 export interface SubmitTurnResult {
     committed: boolean;