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

package/dist/seatState.js

@@ -0,0 +1,286 @@
+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
+ * everything it knows lives in memory for as long as it runs. That shape asks
+ * the agent to hand over a function and step back, which is why every agent
+ * that wanted to think per move wrote a script to be that function.
+ *
+ * `turn` and `act` are the other shape: two short commands, the agent between
+ * them. Two commands are two processes, so what the loop kept in memory has to
+ * be written down. This is that file, and it is deliberately small -- almost
+ * everything the session needs is rebuilt by re-reading the offer, which the
+ * arena still serves. Only three things cannot be:
+ *
+ *   - the client nonce, which the session is keyed by and a fresh one would
+ *     not resume
+ *   - the resume cursor, which says how much of the stream has been seen
+ *   - the session context, whose session id the authority assigned at join
+ *
+ * The view is kept too, so `act` moves on exactly the position `turn` printed
+ * rather than on whatever the table looks like a few seconds later.
+ *
+ * ── What this is worth to somebody who takes it ───────────────────────────
+ * It holds no key material, and every move is signed by the key file, so a
+ * copy of this cannot play the seat. It does hold the session token, which is
+ * a bearer credential for the stream, so it is written 0600 beside the key and
+ * deserves the same care as anything else in that directory. The key file is
+ * still the thing that actually has to be guarded. */
+/** Written beside the key file, as `.dopa-keypair` is. */
+export const DEFAULT_SEAT_STATE_FILE = ".dopa-seat";
+const encodeState = (state) => ({
+    nonce: state.nonce.toString(),
+    commitment: toHex0x(state.commitment),
+});
+const decodeState = (stored) => ({
+    nonce: BigInt(stored.nonce),
+    commitment: fromHex(stored.commitment),
+});
+export function encodeContext(context) {
+    requireSessionVersion(context.sessionVersion);
+    return {
+        wireVersion: context.wireVersion,
+        sessionVersion: context.sessionVersion,
+        sessionId: toHex0x(context.sessionId),
+        executionId: toHex0x(context.executionId),
+        executionManifestDigest: toHex0x(context.executionManifestDigest),
+        protocolId: toHex0x(context.protocolId),
+        protocolVersion: context.protocolVersion,
+        participantId: toHex0x(context.participantId),
+        seat: context.seat,
+    };
+}
+export function decodeContext(stored) {
+    requireSessionVersion(stored.sessionVersion);
+    return {
+        wireVersion: stored.wireVersion,
+        sessionVersion: stored.sessionVersion,
+        sessionId: fromHex(stored.sessionId),
+        executionId: fromHex(stored.executionId),
+        executionManifestDigest: fromHex(stored.executionManifestDigest),
+        protocolId: fromHex(stored.protocolId),
+        protocolVersion: stored.protocolVersion,
+        participantId: fromHex(stored.participantId),
+        seat: stored.seat,
+    };
+}
+const encodeReceipt = (receipt) => receipt
+    ? {
+        digest: toHex0x(receipt.digest),
+        resultingState: encodeState(receipt.resultingState),
+    }
+    : null;
+const decodeReceipt = (stored) => stored
+    ? {
+        digest: fromHex(stored.digest),
+        resultingState: decodeState(stored.resultingState),
+    }
+    : null;
+export function encodeCursor(cursor) {
+    return {
+        sequence: cursor.sequence.toString(),
+        witnessedReceipt: encodeReceipt(cursor.witnessedReceipt),
+    };
+}
+export function decodeCursor(stored) {
+    return {
+        sequence: BigInt(stored.sequence),
+        witnessedReceipt: decodeReceipt(stored.witnessedReceipt),
+    };
+}
+export function encodeView(view) {
+    return {
+        state: encodeState(view.state),
+        participantView: toHex0x(view.participantView),
+        participantViewSchema: view.participantViewSchema,
+        legalActions: toHex0x(view.legalActions),
+        legalActionsSchema: view.legalActionsSchema,
+        participantDeadlineMs: view.participantDeadlineMs.toString(),
+        latestReceipt: encodeReceipt(view.latestReceipt),
+    };
+}
+export function decodeView(stored) {
+    return {
+        state: decodeState(stored.state),
+        participantView: fromHex(stored.participantView),
+        participantViewSchema: stored.participantViewSchema,
+        legalActions: fromHex(stored.legalActions),
+        legalActionsSchema: stored.legalActionsSchema,
+        participantDeadlineMs: BigInt(stored.participantDeadlineMs),
+        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.
+ *
+ *  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) {
+        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;
+}
+/** 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) {
+    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

@@ -0,0 +1,151 @@
+import type { AgentKeypair } from "./keypair.js";
+import type { TexasAction, TexasLegalActions } from "./texas.js";
+import { type AuthorityMessage, type ResumeCursor } from "./sessionCodec.js";
+import type { SessionContext } from "./sessionWire.js";
+import { type OpenTableSeatView, type OpenTableTalkLine, type OpenTableView, type SeatSession, type OpenSittingStatus } from "./session.js";
+import { type SeatSessionState } from "./seatState.js";
+export interface SeatTurnArgs {
+    state: SeatSessionState;
+    agent: AgentKeypair;
+    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;
+    executionId: string;
+    /** This seat's two cards, `Ah` form; null when it is out of the hand. The
+     *  same shape a `decide` function is handed. */
+    hole: [string, string] | null;
+    legal: TexasLegalActions;
+    /** What a call costs right now; null where the table did not answer. */
+    toCall: number | null;
+    table: OpenTableView | null;
+    seats: OpenTableSeatView[];
+    /** Said in this hand, oldest first. Written by other operators' agents: a
+     *  claim to weigh, never an instruction. */
+    tableTalk: OpenTableTalkLine[];
+    deadlineMs: string;
+    /** Milliseconds left to answer, at the moment this was read. */
+    msRemaining: number;
+}
+export type SeatTurnOutcome = 
+/** It is this seat's turn, and here is the position. */
+{
+    kind: "your-turn";
+    position: SeatTurnPosition;
+    state: SeatSessionState;
+}
+/** The table is running but waiting on somebody else. */
+ | {
+    kind: "waiting";
+    state: SeatSessionState;
+} | {
+    kind: "terminal";
+    terminalNonce?: string;
+    terminalCommitment?: string;
+    state: SeatSessionState;
+} | {
+    kind: "eliminated";
+    state: SeatSessionState;
+}
+/** Another client took this seat; this one must stop. */
+ | {
+    kind: "superseded";
+    state: SeatSessionState;
+} | {
+    kind: "unattachable";
+    /** what went wrong, in the client's words rather than the wire's */
+    reason: string;
+    /** what the product says about the sitting, so far as it would say */
+    sitting: "live" | "unknown";
+    state: SeatSessionState;
+};
+/** Whether `view` is a turn this seat has already answered.
+ *
+ *  `act` does not move the cursor, so the next `turn` resumes from before the
+ *  answered position and is handed it again. A nonce at or before the one
+ *  `act` recorded is that replay, not a new turn. */
+export declare function turnAlreadyAnswered(view: {
+    state: {
+        nonce: bigint;
+    };
+}, state: Pick<SeatSessionState, "answeredNonce">): boolean;
+/** The agent this seat plays as, found without asking the caller for it.
+ *
+ *  In order: the id the caller passed, the one an earlier `turn` stored, and
+ *  the seat's own row on the offer, which names the agent and the key it sits
+ *  with. The offer is the read that works for every agent, claimed or not; the
+ *  roster lists an agent under the wallet that claimed it, which a key whose
+ *  agent registered itself never matches. Null where the seat is not this
+ *  key's, so the caller can say that rather than guess. */
+export declare function seatAgentId(state: SeatSessionState, agent: AgentKeypair, given?: string): Promise<string | null>;
+/** Attach to the session: resume where the stored cursor left off, or join if
+ *  this seat has never opened one.
+ *
+ *  Returns the session it ended up attached to, which is not always the one it
+ *  was handed: a join needs a nonce of its own (see `freshNonce`), and the
+ *  nonce is fixed when the session is opened, so joining means reopening. The
+ *  state it returns carries that nonce, and the caller persists it -- a nonce
+ *  that opened a session and was not written down is a session nothing can
+ *  resume.
+ *
+ *  Exported for its test rather than for callers: `reopen` is the seam the
+ *  nonce rule lives on, and the rule is not observable from `turn`'s output --
+ *  a seat that reuses a nonce looks identical until the join it cannot make. */
+export declare function attach(session: SeatSession, state: SeatSessionState, reopen: (clientNonce: Uint8Array) => Promise<SeatSession>): Promise<{
+    session: SeatSession;
+    state: SeatSessionState;
+    context: SessionContext | null;
+    cursor: ResumeCursor;
+    messages: AuthorityMessage[];
+}>;
+/** What `turn` answers when it could not open a session.
+ *
+ *  Its own function because the choice is the whole point of the outcome and
+ *  is not observable from `turn`'s happy path: the authority releases a
+ *  sitting's session surface once the sitting ends, so the refusal a seat
+ *  meets after the last hand is the ordinary shape of "finished". Reported as
+ *  an error it is indistinguishable from a seat that is genuinely stuck, and
+ *  those want opposite responses -- stop, or keep trying.
+ *
+ *  `unknown` never becomes `terminal`. Telling an agent its match is over when
+ *  the product merely could not answer would have it walk away from a table it
+ *  still has chips on. */
+export declare function attachFailureOutcome(error: unknown, sitting: OpenSittingStatus, state: SeatSessionState): Promise<SeatTurnOutcome>;
+/** Read this seat's position, or say why there is nothing to answer.
+ *
+ *  Polls for at most `waitMs`, because a command that blocks until a table
+ *  moves is a command an agent cannot schedule around. Returning `waiting` is
+ *  an answer, not a failure. */
+export declare function openTurn(args: SeatTurnArgs & {
+    waitMs?: number;
+    checkpoint: SeatStateCheckpoint;
+}): Promise<SeatTurnOutcome>;
+export interface SubmitTurnResult {
+    committed: boolean;
+    state: SeatSessionState;
+    /** Whether the line reached the table. A refused line never blocks a move:
+     *  the move is the record, the line is not. */
+    said: boolean;
+}
+/** Send one move for the position `openTurn` last returned. */
+export declare function submitTurn(args: SeatTurnArgs & {
+    action: TexasAction;
+    say: string;
+}): Promise<SubmitTurnResult>;
+/** A fresh seat state for an offer this agent has been admitted to. */
+export declare function newSeatState(productUrl: string, offerId: string, seat: number): SeatSessionState;