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

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,179 @@ 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(),
+                    terminalDigest: gate.release.terminalDigest
+                        ? toHex0x(gate.release.terminalDigest)
+                        : null,
+                },
+            };
+    }
+}
+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),
+                    terminalDigest: stored.release.terminalDigest
+                        ? fromHex(stored.release.terminalDigest)
+                        : null,
+                }),
+            };
+        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;

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,
@@ -403,7 +478,7 @@ async function sayAtTable(fetchImpl, session, agent, agentId, say) {
     if (!trimmed)
         return false;
     const { mintAgentHttpCapability, AGENT_HTTP_CAPABILITY_HEADER } = await import("./agentHttp.js");
-    const target = `/open/v1/executions/${session.executionHex}/talk`;
+    const target = `/v1/executions/${session.executionHex}/talk`;
     const body = new TextEncoder().encode(JSON.stringify({ say: trimmed }));
     try {
         const { header } = await mintAgentHttpCapability(agent, agentId, {
@@ -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.d.ts

@@ -327,6 +327,18 @@ export interface RestartRetry {
  *  answer, 408, 429 or a 5xx -- until `bound` has passed. Any other answer is
  *  returned as it came, so a refusal stays the caller's to read. */
 export declare function fetchWhileRestarting(fetchImpl: typeof fetch, url: string, retry?: RestartRetry): Promise<Response>;
+/** Poll product until the committed owner is ready, then return its origin. */
+export declare function waitForReadyOwner(args: {
+    productUrl: string;
+    executionId: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    pauseMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<{
+    sessionOrigin: string;
+    version: number;
+}>;
 export declare function openSeatSession(args: SeatSessionArgs): Promise<SeatSession>;
 export declare function playSeat(args: PlayArgs): Promise<PlayReport>;
 /** What the play loop does about a refusal, by the refusal's tag.