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

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;

package/dist/seatTurn.js

@@ -2,8 +2,9 @@ import { randomBytes } from "node:crypto";
 import { toHex0x } from "./bytes.js";
 import { acceptAndAwaitAdmission, readOffer } from "./offer.js";
 import { decodeLegalActions, decodeParticipantView, encodeAction, } from "./texas.js";
+import { admitAuthorityEvent, equalReceiptRef, freshSessionBoundary, predictionGatePreparationOf, predictionGateTargetReceipt, } from "./sessionCodec.js";
 import { agentReadCapability, openSeatSession, readPublicTable, readTableTalk, turnIsStillOpen, SessionRefusal, afterRefusal, readSittingStatus, } from "./session.js";
-import { decodeContext, decodeCursor, decodeView, encodeContext, encodeCursor, encodeView, } from "./seatState.js";
+import { decodeContext, decodeCursor, decodeGate, decodeView, encodeContext, encodeCursor, encodeGate, encodeView, } from "./seatState.js";
 /** Whether `view` is a turn this seat has already answered.
  *
  *  `act` does not move the cursor, so the next `turn` resumes from before the
@@ -87,6 +88,12 @@ export async function attach(session, state, reopen) {
                 clientNonce: toHex0x(nonce),
                 context: joined.context ? encodeContext(joined.context) : null,
                 token: opened.client.token ?? null,
+                /* A fresh admission resets the gate boundary with everything else:
+                   the phase belonged to the session that just ended. */
+                cursor: { sequence: "0", witnessedReceipt: null },
+                view: null,
+                predictionGate: null,
+                awaitingGatePrefix: false,
             },
             context: joined.context ?? null,
             cursor: { sequence: 0n, witnessedReceipt: null },
@@ -124,13 +131,21 @@ const holeFromView = (view) => {
         return null;
     }
 };
-function persisted(session, state, context, cursor, view) {
+/** The file as it stands after one accepted event: the session it belongs to,
+ *  the boundary that was accepted, and the position to answer if there is one.
+ *  The gate phase travels with the cursor because they are one promise - a
+ *  cursor that outran its phase is a seat that forgot it was held. */
+function persisted(session, state, context, cursor, view, boundary) {
     return {
         ...state,
         context: context ? encodeContext(context) : state.context,
         token: session.client.token ?? state.token,
         cursor: encodeCursor(cursor),
         view: view ? encodeView(view) : state.view,
+        predictionGate: boundary.predictionGate
+            ? encodeGate(boundary.predictionGate)
+            : null,
+        awaitingGatePrefix: boundary.awaitingGatePrefix,
     };
 }
 /** What `turn` answers when it could not open a session.
@@ -201,18 +216,66 @@ export async function openTurn(args) {
     session = attached.session;
     args = { ...args, state: attached.state };
     let { context, cursor, messages } = attached;
+    /* What this seat has already accepted, restored from the file: the sequence
+       and receipt floor its cursor names, the gate phase it holds, and whether a
+       viewless admission still owes its prepared prefix. The view is not
+       restored - a restart drops it exactly as
+       `ParticipantSessionState::restore` does, and the committed floor carries
+       what the boundary still needs. */
+    let boundary = {
+        ...freshSessionBoundary(),
+        context,
+        sequence: cursor.sequence,
+        receiptFloor: cursor.witnessedReceipt,
+        predictionGate: args.state.predictionGate
+            ? decodeGate(args.state.predictionGate)
+            : null,
+        awaitingGatePrefix: args.state.awaitingGatePrefix,
+    };
     const until = Date.now() + (args.waitMs ?? 0);
+    /* Accept, persist, acknowledge - in that order, for every event this door
+       takes. The acknowledgement tells the authority this seat holds the event,
+       and it may drop the event from the replay window on the strength of it; a
+       promise made before the file is on disk is one a restart cannot keep.
+  
+       A refusal from `admitAuthorityEvent` throws out of here with nothing
+       written and nothing acknowledged, which is what leaves the previously
+       persisted boundary resumable. A re-delivery answers `null`: it was
+       persisted and acknowledged by the process that first applied it, and
+       writing its cursor again would walk this seat's boundary backwards. */
+    const accept = async (message, view) => {
+        const admitted = admitAuthorityEvent(boundary, message);
+        if (admitted.disposition !== "applied")
+            return null;
+        const originToken = session.client.token;
+        if (!originToken)
+            throw new Error("session token missing");
+        /* A fresh join is a new session: the view the previous one printed
+           describes a turn that no longer exists. */
+        const previous = message.type === "sessionJoined"
+            ? { ...args.state, view: null }
+            : args.state;
+        const state = persisted(session, previous, message.context, message.cursor, view, admitted.boundary);
+        await args.checkpoint(state);
+        boundary = admitted.boundary;
+        context = message.context;
+        cursor = message.cursor;
+        args = { ...args, state };
+        await session.client.acknowledge(message.context, message.cursor, originToken);
+        return state;
+    };
     for (;;) {
         for (const message of messages) {
             if (message.type === "error" && !message.retryable)
                 throw new SessionRefusal(message);
-            if ("context" in message)
-                context = message.context;
+            /* Acknowledgements, pendings, errors and challenges carry no boundary. */
+            if (!("cursor" in message))
+                continue;
             if (message.type === "sessionTerminal") {
-                const originToken = session.client.token;
-                if (!originToken)
-                    throw new Error("session token missing");
-                await session.client.acknowledge(message.context, message.cursor, originToken);
+                const state = await accept(message, null);
+                /* A re-delivered terminal is this file's own last event: a resume at
+                   the terminal cursor repeats it, so there is nothing to write or
+                   promise again - and the sitting is still over. */
                 return {
                     kind: "terminal",
                     /* Carried out rather than dropped: `consent` takes exactly these two,
@@ -220,21 +283,21 @@ export async function openTurn(args) {
                        two-command tour had no settle at all. */
                     terminalNonce: message.finalState.nonce.toString(),
                     terminalCommitment: toHex0x(message.finalState.commitment),
-                    state: persisted(session, args.state, context, message.cursor, null),
+                    state: state ?? args.state,
                 };
             }
-            if (message.type === "predictionGateReleased") {
-                const originToken = session.client.token;
-                if (!originToken)
-                    throw new Error("session token missing");
-                await session.client.acknowledge(message.context, message.cursor, originToken);
-                cursor = message.cursor;
-                continue;
-            }
+            /* A named notice and a viewless admission are acknowledged and waited
+               on: no private view arrived, so there is nothing here to answer and
+               nothing to decide. The phase they carry is persisted first. */
             const view = "view" in message ? message.view : null;
-            if (!view || !("cursor" in message))
+            const state = await accept(message, view);
+            /* A re-delivery is not a turn: the view it carries was answered or
+               waited out by the process that applied it, and nothing was written
+               here to hand back. */
+            if (!state)
+                continue;
+            if (!view)
                 continue;
-            cursor = message.cursor;
             /* A view with no legal actions is the table moving without this seat.
                One whose deadline has passed is this seat's turn already lost, and
                answering it would sign for a turn that is closed. And one at or before
@@ -275,11 +338,11 @@ export async function openTurn(args) {
                     deadlineMs: view.participantDeadlineMs.toString(),
                     msRemaining: Number(view.participantDeadlineMs) - Date.now(),
                 },
-                state: persisted(session, args.state, context, cursor, view),
+                state,
             };
         }
         if (Date.now() >= until) {
-            const waiting = persisted(session, args.state, context, cursor, null);
+            const waiting = persisted(session, args.state, context, cursor, null, boundary);
             /* Asked only here, where the loop is about to say "waiting" anyway: a
                seat with no chips is not waiting for a turn, it is out, and a caller
                polling `waiting` at the default `--wait 0` would spin at full rate for
@@ -309,6 +372,18 @@ export async function submitTurn(args) {
     const view = decodeView(args.state.view);
     if (!turnIsStillOpen(view, Date.now()))
         throw new Error("the deadline for that turn has passed; run `turn` again for the next one");
+    /* A retained gate that still holds this seat's own turn means the authority
+       has not released it: answering the stored position would be inferring on
+       a turn nobody may act in yet. `turn` refuses to hand such a view out, so
+       this only fires on a stored position the gate later reclaimed. */
+    const retained = args.state.predictionGate
+        ? decodeGate(args.state.predictionGate)
+        : null;
+    if (retained &&
+        retained.phase !== "released" &&
+        equalReceiptRef(predictionGateTargetReceipt(retained), view.latestReceipt) &&
+        predictionGatePreparationOf(retained)?.actingSeat === args.state.seat)
+        throw new Error("this turn is held behind a prediction gate; run `turn` again once it releases");
     const openWith = (clientNonce) => openSeatSession({
         productUrl: args.state.productUrl,
         offerId: args.state.offerId,
@@ -438,5 +513,7 @@ export function newSeatState(productUrl, offerId, seat) {
         token: null,
         cursor: { sequence: "0", witnessedReceipt: null },
         view: null,
+        predictionGate: null,
+        awaitingGatePrefix: false,
     };
 }

package/dist/session.js

@@ -3,7 +3,7 @@ import { blake2b256 } from "./crypto.js";
 import { equalBytes, fromHex, textBytes, toHex0x } from "./bytes.js";
 import { AGENT_HTTP_CAPABILITY_HEADER, mintAgentHttpCapability, } from "./agentHttp.js";
 import { signRaw } from "./keypair.js";
-import { MAX_TRANSPORT_FRAME_BYTES, decodeAuthorityMessage, decodeEnvelope, encodeAckFrame, encodeEnvelope, encodeSeatAuthSuccessFrame, sessionErrorHint, sessionErrorName, } from "./sessionCodec.js";
+import { MAX_TRANSPORT_FRAME_BYTES, PredictionGateConflictError, SessionBoundaryError, admitAuthorityEvent, decodeAuthorityMessage, freshSessionBoundary, decodeEnvelope, encodeAckFrame, encodeEnvelope, encodeSeatAuthSuccessFrame, sessionErrorHint, sessionErrorName, } from "./sessionCodec.js";
 import { actionSigningBytes, encodeActionFrame, encodeJoinFrame, encodeResumeFrame, joinSigningBytes, requireSessionVersion, resumeSigningBytes, SESSION_VERSION, UnsupportedSessionVersionError, } from "./sessionWire.js";
 import { decodeLegalActions, decodeParticipantView, encodeAction, pickAction, } from "./texas.js";
 import { authorizeSeatChallenge } from "./seatAuth.js";
@@ -245,7 +245,7 @@ export class SessionClient {
             typeof ceiling !== "number" ||
             !Number.isFinite(ceiling) ||
             ceiling < MAX_TRANSPORT_FRAME_BYTES)
-            throw new Error("authority discovery does not support participant session V2");
+            throw new Error("authority discovery does not support participant session V3");
     }
     async answeredDiscovery() {
         const { boundMs, pauseMs, sleep } = this.discoveryRetry;
@@ -611,6 +611,11 @@ export async function playSeat(args) {
     let pending = null;
     let lastContext = null;
     let lastCursor = { sequence: 0n, witnessedReceipt: null };
+    /* What this seat has accepted: the event sequence, the receipt floor, the
+       view it was last shown, and the named gate phase it holds. Every event
+       goes through it before anything is acknowledged, so the two doors -- this
+       loop and `openTurn` -- refuse the same streams for the same reasons. */
+    let accepted = freshSessionBoundary();
     const inbox = [];
     let joined = await client.join();
     if (joined.context)
@@ -634,7 +639,17 @@ export async function playSeat(args) {
         if (message.type === "actionPending" ||
             message.type === "actionAcknowledged")
             return null;
-        if (message.type === "predictionGateReleased") {
+        if (message.type === "predictionGatePrepared" ||
+            message.type === "predictionGateOpened" ||
+            message.type === "predictionGateReleased") {
+            /* A named notice moves no receipt and carries no view: it is accepted,
+               acknowledged, and waited on. Only the real view that follows a
+               release is a turn to decide. */
+            const admitted = admitAuthorityEvent(accepted, message);
+            if (admitted.disposition !== "applied")
+                return null;
+            accepted = admitted.boundary;
+            lastContext = message.context;
             await client.acknowledge(message.context, message.cursor, originToken);
             lastCursor = message.cursor;
             return null;
@@ -642,8 +657,16 @@ export async function playSeat(args) {
         if ("context" in message)
             lastContext = message.context;
         if (message.type === "sessionTerminal") {
-            await client.acknowledge(message.context, message.cursor, originToken);
-            lastCursor = message.cursor;
+            const admitted = admitAuthorityEvent(accepted, message);
+            /* A re-delivered terminal is this boundary's own last event - a resume
+               at the terminal cursor repeats it. There is nothing to apply and its
+               acknowledgement is spent, but the sitting is over either way and the
+               caller still needs what `consent` takes. */
+            if (admitted.disposition === "applied") {
+                accepted = admitted.boundary;
+                await client.acknowledge(message.context, message.cursor, originToken);
+                lastCursor = message.cursor;
+            }
             return {
                 outcome: "terminal",
                 committedActions,
@@ -660,52 +683,61 @@ export async function playSeat(args) {
         }
         let view = null;
         let cursor = null;
-        if (message.type === "sessionJoined") {
-            view = message.view;
-            cursor = message.cursor;
-        }
-        else if (message.type === "participantView") {
-            view = message.view;
-            cursor = message.cursor;
-        }
-        else if (message.type === "actionCommitted") {
-            pending = null;
-            committedActions += 1;
-            view = message.view;
-            cursor = message.cursor;
-        }
-        else if (message.type === "actionRejected") {
-            pending = null;
-            view = message.view;
-            cursor = message.cursor;
-        }
-        else if (message.type === "sessionResumed") {
+        if (message.type === "sessionJoined" ||
+            message.type === "participantView" ||
+            message.type === "actionCommitted" ||
+            message.type === "actionRejected" ||
+            message.type === "sessionResumed") {
             view = message.view;
             cursor = message.cursor;
         }
-        if (view &&
-            view.legalActions.length === 0 &&
-            !elimination.eliminated &&
-            Date.now() - lastIdleTableReadMs >= IDLE_TABLE_READ_MS) {
-            /* Nothing to decide: somebody else's turn, a hand this seat folded, or
-               a sitting this seat is out of. Read now and then, so the hand lines go
-               on and a seat that has lost its last chip says so once. */
-            lastIdleTableReadMs = Date.now();
-            const idle = await readPublicTable(fetchImpl, product, executionHex, names, tableCapability);
-            if (idle && idle.handNumber !== lastHandSeen) {
-                lastHandSeen = idle.handNumber;
-                args.onHand?.({
-                    number: idle.handNumber,
-                    stack: idle.seats.find((entry) => entry.seat === args.seat)?.stack ?? null,
-                });
+        if (cursor !== null && lastContext) {
+            /* Accepted before anything else happens: a refusal here leaves the
+               retained boundary untouched and nothing acknowledged. */
+            const admitted = admitAuthorityEvent(accepted, message);
+            /* A re-delivery is the suffix a resume repeats. It was applied and
+               acknowledged once, so nothing here moves for it: no view, no pending
+               resolution, no commit count, no table read, no decision, no
+               acknowledgement. */
+            if (admitted.disposition !== "applied")
+                return null;
+            accepted = admitted.boundary;
+            /* Resolved only for the applied event, so a replayed commit cannot
+               count twice or drop a proposal that is still in flight. */
+            if (message.type === "actionCommitted") {
+                pending = null;
+                committedActions += 1;
             }
-            if (elimination.observe(idle))
-                args.onEliminated?.();
-        }
-        if (view && cursor !== null && lastContext) {
-            const nonceKey = view.state.nonce.toString();
+            else if (message.type === "actionRejected")
+                pending = null;
+            if (view &&
+                view.legalActions.length === 0 &&
+                !elimination.eliminated &&
+                Date.now() - lastIdleTableReadMs >= IDLE_TABLE_READ_MS) {
+                /* Nothing to decide: somebody else's turn, a hand this seat folded, or
+                   a sitting this seat is out of. Read now and then, so the hand lines go
+                   on and a seat that has lost its last chip says so once. */
+                lastIdleTableReadMs = Date.now();
+                const idle = await readPublicTable(fetchImpl, product, executionHex, names, tableCapability);
+                if (idle && idle.handNumber !== lastHandSeen) {
+                    lastHandSeen = idle.handNumber;
+                    args.onHand?.({
+                        number: idle.handNumber,
+                        stack: idle.seats.find((entry) => entry.seat === args.seat)?.stack ??
+                            null,
+                    });
+                }
+                if (elimination.observe(idle))
+                    args.onEliminated?.();
+            }
+            const nonceKey = view?.state.nonce.toString() ?? "";
             const now = BigInt(Date.now());
-            if (view.legalActions.length > 0 &&
+            if (
+            /* A viewless admission is acknowledged and waited on: a held seat has
+               nothing to answer, and nothing to infer on, until its gate releases
+               and the real view arrives. */
+            view !== null &&
+                view.legalActions.length > 0 &&
                 !acted.has(nonceKey) &&
                 view.participantDeadlineMs > now) {
                 const legal = decodeLegalActions(view.legalActions);
@@ -876,6 +908,12 @@ export async function playSeat(args) {
                look successful while the seat cannot read the gated stream. */
             if (error instanceof UnsupportedSessionVersionError)
                 throw error;
+            /* Nor is a refused projection: the event the authority sent is one this
+               contract forbids, and resuming would fetch the same bytes again while
+               the loop reported it as flaky transport. */
+            if (error instanceof SessionBoundaryError ||
+                error instanceof PredictionGateConflictError)
+                throw error;
             if (!lastContext || reconnects >= 5)
                 throw error;
             /* Three refusals, three answers. A gone session (`UnknownSession`, or a
@@ -907,6 +945,12 @@ export async function playSeat(args) {
                 if (joined.context)
                     lastContext = joined.context;
                 lastCursor = { sequence: 0n, witnessedReceipt: null };
+                /* A rejoin is a new session: nothing the old one retained - its phase,
+                   its floor, its sequence - describes this one, and only a boundary
+                   this loop opened itself may be reset. The stale inbox belongs to
+                   the session that is gone. */
+                accepted = freshSessionBoundary();
+                inbox.length = 0;
                 inbox.push(...joined.messages);
                 rejoins += 1;
                 reconnects += 1;

package/dist/sessionCodec.d.ts

@@ -11,6 +11,8 @@ export declare const SESSION_ERROR_TAG = 13;
 export declare const SEAT_AUTHORIZATION_CHALLENGE_TAG = 15;
 export declare const SEAT_AUTHORIZATION_RESPONSE_TAG = 16;
 export declare const PREDICTION_GATE_RELEASED_TAG = 17;
+export declare const PREDICTION_GATE_PREPARED_TAG = 18;
+export declare const PREDICTION_GATE_OPENED_TAG = 19;
 export declare const MAX_TRANSPORT_FRAME_BYTES: number;
 export interface WireEnvelope {
     message: string;
@@ -57,12 +59,80 @@ export interface SeatAuthChallenge {
     coordinatorProof: Uint8Array;
     coordinatorPublicKey: Uint8Array;
 }
+/** ADR-0096's ceiling on added pacing for one next-action prediction window,
+ *  as `arena_session::prediction_gate::MAX_PREDICTION_PACING_MS`. */
+export declare const MAX_PREDICTION_PACING_MS = 25000n;
+/** The in-play window a gate names. The session reuses this identity; it
+ *  never mints a second one. */
+export interface PredictionWindowRef {
+    windowId: bigint;
+    marketId: bigint;
+    /** The only contract kind a gate can hold a seat behind (wire tag 1). */
+    contract: "pokerActionV1";
+}
+/** A durably committed preparation: the frozen window identity, the target
+ *  the acting seat is held on, its original committed deadline, and the
+ *  persisted instant publication started. */
+export interface PredictionGatePreparation {
+    window: PredictionWindowRef;
+    actingSeat: number;
+    state: StateRef;
+    receipt: ReceiptRef | null;
+    originalDeadlineMs: bigint;
+    preparedAtMs: bigint;
+}
+/** Acknowledged publication. `closesAtMs` is the service-committed close
+ *  instant, never the action deadline. */
+export interface PredictionGateOpening {
+    preparation: PredictionGatePreparation;
+    openedAtMs: bigint;
+    closesAtMs: bigint;
+}
+/** The terminal overlay: how the gate closed, and the bounded same-receipt
+ *  deadline it admits. `lockCappedMs` and `participantDeadlineMs` are derived
+ *  the way the shared crate derives them, so a recipient never has to repeat
+ *  the arithmetic to know which later deadline is legal. */
+export interface PredictionGateRelease {
+    window: PredictionWindowRef;
+    actingSeat: number;
+    state: StateRef;
+    receipt: ReceiptRef | null;
+    terminal: "locked" | "cancelled";
+    originalDeadlineMs: bigint;
+    arrivalMs: bigint;
+    lockedAtMs: bigint;
+    lockCappedMs: bigint;
+    budgetMs: bigint;
+    participantDeadlineMs: bigint;
+}
+/** The gate facts a participant retains for one revision. */
+export type PredictionGateStatus = {
+    phase: "prepared";
+    preparation: PredictionGatePreparation;
+} | {
+    phase: "open";
+    opening: PredictionGateOpening;
+} | {
+    phase: "released";
+    release: PredictionGateRelease;
+};
+/** One named lifecycle step, as a value: what the fold below applies. */
+export type PredictionGateMessage = {
+    kind: "prepared";
+    preparation: PredictionGatePreparation;
+} | {
+    kind: "opened";
+    opening: PredictionGateOpening;
+} | {
+    kind: "released";
+    release: PredictionGateRelease;
+};
 export type AuthorityMessage = {
     type: "sessionJoined";
     context: SessionContext;
     sequence: bigint;
     policy: SessionPolicy;
-    view: ViewSnapshot;
+    view: ViewSnapshot | null;
     cursor: ResumeCursor;
 } | {
     type: "participantView";
@@ -98,7 +168,10 @@ export type AuthorityMessage = {
     type: "sessionResumed";
     context: SessionContext;
     sequence: bigint;
-    view: ViewSnapshot;
+    /** The boundary the authority replayed from. It must precede the event
+        itself, or the resume names a suffix it cannot have replayed. */
+    replayFrom: bigint;
+    view: ViewSnapshot | null;
     cursor: ResumeCursor;
 } | {
     type: "sessionTerminal";
@@ -108,10 +181,23 @@ export type AuthorityMessage = {
     finalState: StateRef;
     cursor: ResumeCursor;
     finalReceipt: ReceiptRef | null;
+} | {
+    type: "predictionGatePrepared";
+    context: SessionContext;
+    sequence: bigint;
+    preparation: PredictionGatePreparation;
+    cursor: ResumeCursor;
+} | {
+    type: "predictionGateOpened";
+    context: SessionContext;
+    sequence: bigint;
+    opening: PredictionGateOpening;
+    cursor: ResumeCursor;
 } | {
     type: "predictionGateReleased";
     context: SessionContext;
     sequence: bigint;
+    release: PredictionGateRelease;
     cursor: ResumeCursor;
 } | {
     type: "error";
@@ -131,6 +217,19 @@ export declare function sessionErrorName(tag: number): string;
  *  join supersedes the older binding, and the older client's next message
  *  finds its session gone. Both used to read as transport flakiness. */
 export declare function sessionErrorHint(tag: number): string | null;
+export declare function equalStateRef(left: StateRef, right: StateRef): boolean;
+export declare function equalReceiptRef(left: ReceiptRef | null, right: ReceiptRef | null): boolean;
+export declare function equalPredictionGatePreparation(left: PredictionGatePreparation, right: PredictionGatePreparation): boolean;
+export declare function equalPredictionGateRelease(left: PredictionGateRelease, right: PredictionGateRelease): boolean;
+/** The structural refusals of `PredictionGatePreparation::new`, made wherever
+ *  a preparation enters this process - the wire, or a retained seat state. */
+export declare function bindPredictionGatePreparation(fields: PredictionGatePreparation): PredictionGatePreparation;
+/** The structural refusals of `PredictionGateOpening::new`. */
+export declare function bindPredictionGateOpening(fields: PredictionGateOpening): PredictionGateOpening;
+/** The structural refusals of `PredictionGateRelease::new`, with the bounded
+ *  overlay derived here rather than trusted from a sender or a stored file:
+ *  the lock instant capped at the pacing ceiling, plus the budget. */
+export declare function bindPredictionGateRelease(fields: Omit<PredictionGateRelease, "lockCappedMs" | "participantDeadlineMs">): PredictionGateRelease;
 export declare function decodeAuthorityMessage(bytes: Uint8Array): AuthorityMessage;
 export declare function encodeSeatAuthSuccessFrame(context: SessionContext, actionId: Uint8Array, signature: Uint8Array): Uint8Array;
 export declare function extractProtocolInput(payload: Uint8Array): Uint8Array;
@@ -143,3 +242,60 @@ export declare function takePrincipalProof(bytes: Uint8Array): {
     signature: Uint8Array;
     rest: Uint8Array;
 };
+/** A refused phase transition, named as the shared crate names it. */
+export declare class PredictionGateConflictError extends Error {
+    readonly conflict: "PredictionGatePhaseConflict" | "PredictionGateReleaseConflict";
+    constructor(conflict: "PredictionGatePhaseConflict" | "PredictionGateReleaseConflict", detail: string);
+}
+/** The lifecycle step an authority message carries, or null where it carries
+ *  none. The fold takes the value, not the envelope. */
+export declare function predictionGateMessage(message: AuthorityMessage): PredictionGateMessage | null;
+/** The committed preparation behind any phase, or null once released - a
+ *  release carries the identity but not the persisted preparation instant. */
+export declare function predictionGatePreparationOf(status: PredictionGateStatus): PredictionGatePreparation | null;
+/** The receipt the gate targets. A recipient behind it still receives every
+ *  notice, because each notice cursor names that recipient's own floor. */
+export declare function predictionGateTargetReceipt(status: PredictionGateStatus): ReceiptRef | null;
+/** Whether a newly named preparation supersedes the retained facts.
+ *
+ *  Only a released gate can be superseded: a held gate's turn has not closed,
+ *  so a second preparation contradicts it. Once released, the next selected
+ *  turn always targets a later committed state and therefore its own receipt.
+ *  A seat that is itself withheld for that next turn never witnesses the view
+ *  that would otherwise retire the closed gate - which is exactly the second
+ *  window of a hand, held on the seat that was a bystander for the first. A
+ *  preparation naming the same revision is the same-target conflict, not a
+ *  supersession. */
+export declare function predictionGateSupersededByPreparation(status: PredictionGateStatus, nextTurn: PredictionGatePreparation): boolean;
+export declare function applyPredictionGateStatus(current: PredictionGateStatus | null, message: PredictionGateMessage): PredictionGateStatus;
+export interface AcceptedSessionBoundary {
+    context: SessionContext | null;
+    /** The last accepted authority event sequence; zero before the first. */
+    sequence: bigint;
+    receiptFloor: ReceiptRef | null;
+    /** The view last disclosed to this seat, or null while it is withheld. */
+    view: ViewSnapshot | null;
+    predictionGate: PredictionGateStatus | null;
+    /** Whether a viewless admission still owes its named prepared prefix. */
+    awaitingGatePrefix: boolean;
+}
+/** A refused event, named as `SessionSemanticError` names it. */
+export declare class SessionBoundaryError extends Error {
+    readonly reason: string;
+    constructor(reason: string, detail: string);
+}
+/** The boundary a seat that has accepted nothing holds. */
+export declare function freshSessionBoundary(): AcceptedSessionBoundary;
+/** What the seam did with an event.
+ *
+ *  `applied` is the only disposition that moved the boundary, and so the only
+ *  one a consumer may act on: a re-delivery was applied and acknowledged once
+ *  already, and acting on it a second time would decide a turn that is over,
+ *  count a commit twice, or walk the acknowledged cursor backwards. */
+export type AuthorityEventDisposition = "applied" | "replay" | "boundaryless";
+export interface AdmittedAuthorityEvent {
+    disposition: AuthorityEventDisposition;
+    /** The boundary to retain. Unchanged unless the event was applied. */
+    boundary: AcceptedSessionBoundary;
+}
+export declare function admitAuthorityEvent(accepted: AcceptedSessionBoundary, message: AuthorityMessage): AdmittedAuthorityEvent;