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

package/dist/sessionCodec.js

@@ -5,7 +5,7 @@
  * the seat loop: views, commits, terminal, errors, and seat-auth challenges.
  */
 import { ByteReader, ByteWriter } from "./bytes.js";
-import { encodeContext } from "./sessionWire.js";
+import { encodeContext, requireSessionVersion, } from "./sessionWire.js";
 const AUTHORITY_EVENT_ACKNOWLEDGEMENT_TAG = 0x09;
 export const SESSION_JOINED_TAG = 0x02;
 export const PARTICIPANT_VIEW_TAG = 0x03;
@@ -18,6 +18,7 @@ export const SESSION_TERMINAL_TAG = 0x0c;
 export const SESSION_ERROR_TAG = 0x0d;
 export const SEAT_AUTHORIZATION_CHALLENGE_TAG = 0x0f;
 export const SEAT_AUTHORIZATION_RESPONSE_TAG = 0x10;
+export const PREDICTION_GATE_RELEASED_TAG = 0x11;
 export const MAX_TRANSPORT_FRAME_BYTES = 1 << 20;
 export function encodeAckFrame(context, cursor) {
     const sequence = typeof cursor === "object" ? cursor.sequence : cursor;
@@ -97,9 +98,11 @@ export function sessionErrorHint(tag) {
     }
 }
 function readContext(reader, wireVersion) {
+    const sessionVersion = reader.readU16("session version");
+    requireSessionVersion(sessionVersion);
     return {
         wireVersion,
-        sessionVersion: reader.readU16("session version"),
+        sessionVersion,
         sessionId: reader.readFixed(32, "session id"),
         executionId: reader.readFixed(32, "execution id"),
         executionManifestDigest: reader.readFixed(32, "execution manifest digest"),
@@ -211,7 +214,14 @@ export function decodeAuthorityMessage(bytes) {
     const wireVersion = reader.readU16("wire version");
     const tag = reader.readByte("message tag");
     if (tag === SESSION_ERROR_TAG) {
-        readOption(reader, "session version option", () => reader.readU16("session version"));
+        // A present selected version is the authority's answer for this session,
+        // so it has to be one this build can speak; the unsupported-version
+        // payload read below is a raw diagnostic and stays readable without one.
+        readOption(reader, "session version option", () => {
+            const version = reader.readU16("session version");
+            requireSessionVersion(version);
+            return version;
+        });
         const errorTag = reader.readByte("session protocol error tag");
         if (errorTag === 0 || errorTag === 1)
             reader.readU16("unsupported version");
@@ -323,6 +333,27 @@ export function decodeAuthorityMessage(bytes) {
             };
             break;
         }
+        case PREDICTION_GATE_RELEASED_TAG: {
+            reader.readU64("prediction window id");
+            reader.readU64("prediction market id");
+            reader.readByte("prediction window contract");
+            reader.readU16("prediction gate acting seat");
+            readState(reader, "prediction gate state nonce", "prediction gate state commitment");
+            readOption(reader, "prediction gate receipt option", () => readReceipt(reader));
+            reader.readByte("prediction gate terminal");
+            reader.readU64("original participant deadline milliseconds");
+            reader.readU64("prediction gate arrival milliseconds");
+            reader.readU64("prediction gate locked-at milliseconds");
+            reader.readU64("participant deadline budget milliseconds");
+            const cursor = readCursor(reader);
+            message = {
+                type: "predictionGateReleased",
+                context,
+                sequence,
+                cursor,
+            };
+            break;
+        }
         default:
             throw new Error(`unknown authority message tag ${tag}`);
     }

package/dist/sessionWire.d.ts

@@ -1,4 +1,24 @@
 import { ByteWriter } from "./bytes.js";
+/** The participant session version this build speaks.
+ *
+ *  It is the contract that carries the named `PredictionGateReleased` overlay
+ *  event, so an authority that cannot name it in its join advertisement is
+ *  refused at discovery and a selected context from any other version is
+ *  refused rather than re-encoded. */
+export declare const SESSION_VERSION = 2;
+/** A selected participant session version this build cannot speak.
+ *
+ *  Thrown where a *selected* version enters or leaves the process -- a
+ *  retained seat state, a signed context, or an authority event. It is never
+ *  thrown for a raw join advertisement, which may carry any ascending `u16`
+ *  values for the authority to choose among. */
+export declare class UnsupportedSessionVersionError extends Error {
+    readonly version: number;
+    constructor(version: number);
+}
+/** The selected-context guard. Call it wherever a session context, or the
+ *  selected version on an authority message, is about to be acted on. */
+export declare function requireSessionVersion(version: number): void;
 export interface SessionContext {
     wireVersion: number;
     sessionVersion: number;

package/dist/sessionWire.js

@@ -12,7 +12,50 @@ const RESUME_DOMAIN = textBytes("arena_session::resume");
 const SESSION_JOIN_REQUEST_TAG = 0x01;
 const ACTION_PROPOSAL_TAG = 0x04;
 const SESSION_RESUME_REQUEST_TAG = 0x0a;
+/** The participant session version this build speaks.
+ *
+ *  It is the contract that carries the named `PredictionGateReleased` overlay
+ *  event, so an authority that cannot name it in its join advertisement is
+ *  refused at discovery and a selected context from any other version is
+ *  refused rather than re-encoded. */
+export const SESSION_VERSION = 2;
+/** A selected participant session version this build cannot speak.
+ *
+ *  Thrown where a *selected* version enters or leaves the process -- a
+ *  retained seat state, a signed context, or an authority event. It is never
+ *  thrown for a raw join advertisement, which may carry any ascending `u16`
+ *  values for the authority to choose among. */
+export class UnsupportedSessionVersionError extends Error {
+    version;
+    constructor(version) {
+        super(`unsupported participant session version ${version}; expected 2`);
+        this.version = version;
+        this.name = "UnsupportedSessionVersionError";
+    }
+}
+/** The selected-context guard. Call it wherever a session context, or the
+ *  selected version on an authority message, is about to be acted on. */
+export function requireSessionVersion(version) {
+    if (version !== SESSION_VERSION)
+        throw new UnsupportedSessionVersionError(version);
+}
+/** Structural validation of a join advertisement, mirroring the shared codec:
+ *  the list is raw, so it need not name a version this build supports, but an
+ *  empty, non-u16, or non-ascending list is not encodable at all. */
+function requireRawVersionList(versions) {
+    if (versions.length === 0)
+        throw new Error("supported session versions must not be empty");
+    if (versions.length > 0xffff)
+        throw new Error("supported session versions exceed the u16 count limit");
+    for (const [index, version] of versions.entries()) {
+        if (!Number.isInteger(version) || version < 0 || version > 0xffff)
+            throw new Error(`supported session version ${version} is not a u16`);
+        if (index > 0 && versions[index - 1] >= version)
+            throw new Error("supported session versions must be strictly ascending");
+    }
+}
 export function encodeContext(writer, context) {
+    requireSessionVersion(context.sessionVersion);
     writer
         .pushU16(context.sessionVersion)
         .pushFixed(context.sessionId, 32, "session id")
@@ -36,6 +79,7 @@ export function signedFrame(body, signature) {
         .bytes();
 }
 export function joinBodyBytes(request) {
+    requireRawVersionList(request.supportedSessionVersions);
     const writer = new ByteWriter()
         .pushU16(request.wireVersion)
         .pushByte(SESSION_JOIN_REQUEST_TAG)

package/dist/tour.d.ts

@@ -11,8 +11,16 @@ export type TourEntry = {
     waiting: number;
     seatsNeeded: number;
     fillAtMs: number;
-    /** how many seats the house will take at `fillAtMs` if nobody else comes */
+    /** how many seats the house will take at `fillAtMs` if nobody else
+     *  comes; 0 when the fill will not seat this agent at all */
     houseSeatsAtFill?: number;
+    /** what the fill at `fillAtMs` does with this agent: `stays_queued` when
+     *  its floor (`minAgents`) cannot be met by who is queued, so it is not
+     *  seated and waits for another real agent to arrive. Absent from an
+     *  arena that predates floors, like `houseSeatsAtFill` before it */
+    atFill?: "seated" | "stays_queued";
+    /** the floor this agent stated, when above one */
+    minAgents?: number;
 }
 /** The queue composed an offer this agent accepts and plays itself. Since
  *  ADR-0175 this is the answer for every external agent: the product holds
@@ -37,8 +45,25 @@ export type TourEntry = {
     state: "closed" | "unpaid";
     [key: string]: unknown;
 };
-export declare function enterTour(client: TourClient, tour: TourKind): Promise<TourEntry>;
-export interface QueueOptions {
+/** What an agent states when it enters the playground. */
+export interface PlaygroundFloor {
+    /** The fewest real agents, this one included, it will sit with: 1 to 3.
+     *  Omitted, the playground seats it with house seats after the wait, as it
+     *  always has. */
+    minAgents?: number;
+}
+/** The origin answering as a restarting one does -- no answer at all, 408,
+ *  429 or a 5xx -- rather than the tour refusing the entry. A queue waits it
+ *  out; every other refusal is the caller's to read. */
+export declare class TourEntryUnavailable extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** How long a queue keeps entering while the origin stays unavailable. Long
+ *  enough to cover a product restart, which is what this is for. */
+export declare const QUEUE_RESTART_BOUND_MS = 90000;
+export declare function enterTour(client: TourClient, tour: TourKind, floor?: PlaygroundFloor): Promise<TourEntry>;
+export interface QueueOptions extends PlaygroundFloor {
     /** How long to keep polling before giving up. */
     timeoutMs?: number;
     /** Gap between polls. The queue answers immediately; this paces the caller. */
@@ -46,6 +71,12 @@ export interface QueueOptions {
     onWaiting?: (entry: Extract<TourEntry, {
         state: "waiting";
     }>) => void;
+    /** Told each time the origin answers as a restarting one does, so a run can
+     *  say why it is still waiting. */
+    onUnavailable?: (error: unknown) => void;
+    /** How long the entry keeps being re-sent while the origin stays that way;
+     *  tests shorten it. */
+    restartBoundMs?: number;
 }
 /** Enter and poll until seated.
  *
@@ -89,13 +120,33 @@ export interface TourPlayReport {
     outcome: string;
     committedActions: number;
     hands: number;
+    /** Whether this seat lost its last chip before the sitting ended. Kept
+     *  separately from `outcome`, which is the table's ending rather than the
+     *  seat's: a seat that busts on hand two and a seat that wins are both at the
+     *  table when it reaches its terminal, and both have to be reported as
+     *  having seen it. */
+    eliminated: boolean;
 }
 /** Drive a seated tour table to a terminal disposition.
  *
  *  A lapsed turn is not an error: the authority acts for a silent seat on its
  *  own clock, so a slow decision costs the hand rather than the match, and the
- *  loop keeps reading. Only a refusal the server calls terminal stops it. */
+ *  loop keeps reading. Only a refusal the server calls terminal stops it.
+ *
+ *  **Being eliminated does not end the sitting.** This used to return the
+ *  moment the seat lost its last chip, which reads as the natural thing to do —
+ *  there is no turn coming — and is how a seat ends up reporting a result
+ *  before the table has one and walking away from a settlement the whole table
+ *  is waiting on. A busted seat keeps watching to the table's terminal, which
+ *  the route answers as `complete` for an out seat too, and says it busted in
+ *  the report instead. */
 export declare function playTour(client: TourClient, tableId: string, decide?: (turn: TurnView) => TableMove, options?: {
     pollMs?: number;
+    /** How long to keep watching before giving up, as `queueUntilSeated` does.
+     *  A table that stops dealing without reaching a terminal would otherwise
+     *  hold this loop for as long as the process lives. */
+    timeoutMs?: number;
     onTurn?: (turn: TurnView, move: TableMove) => void;
+    /** Called once, when this seat loses its last chip. */
+    onEliminated?: () => void;
 }): Promise<TourPlayReport>;

package/dist/tour.js

@@ -13,6 +13,7 @@
  */
 import { AGENT_HTTP_CAPABILITY_HEADER, mintAgentHttpCapability, } from "./agentHttp.js";
 import { textBytes } from "./bytes.js";
+import { refusalMessage } from "./refusal.js";
 /** One signed Product API call. `target` is origin-form, exactly as the server
  *  will reconstruct it - a leading-slash path plus any query string. */
 async function signedFetch(client, method, target, body) {
@@ -41,13 +42,41 @@ async function signedFetch(client, method, target, body) {
         json: text.length === 0 ? undefined : JSON.parse(text),
     };
 }
-export async function enterTour(client, tour) {
+/** The origin answering as a restarting one does -- no answer at all, 408,
+ *  429 or a 5xx -- rather than the tour refusing the entry. A queue waits it
+ *  out; every other refusal is the caller's to read. */
+export class TourEntryUnavailable extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = "TourEntryUnavailable";
+        this.status = status;
+    }
+}
+/** How long a queue keeps entering while the origin stays unavailable. Long
+ *  enough to cover a product restart, which is what this is for. */
+export const QUEUE_RESTART_BOUND_MS = 90_000;
+function unavailable(error) {
+    /* A fetch that never reached an origin throws `TypeError`; a stopped product
+       behind a proxy answers 502, and one coming back answers 5xx or 429. */
+    return error instanceof TourEntryUnavailable || error instanceof TypeError;
+}
+export async function enterTour(client, tour, floor = {}) {
     const target = tour === "playground"
         ? "/open/v1/tours/playground/entries"
         : "/open/v1/tours/tournament/entries";
-    const { status, json } = await signedFetch(client, "POST", target);
-    if (status !== 200)
-        throw new Error(`tour entry refused (${status}): ${JSON.stringify(json)}`);
+    if (floor.minAgents !== undefined && tour !== "playground")
+        throw new Error("a floor of real agents only applies to the playground");
+    /* No body at all when nothing is stated: the join every client sent before
+       floors existed, signed over the same empty bytes. */
+    const body = floor.minAgents === undefined ? undefined : { minAgents: floor.minAgents };
+    const { status, json } = await signedFetch(client, "POST", target, body);
+    if (status !== 200) {
+        const said = refusalMessage("tour entry", status, json);
+        if (status === 408 || status === 429 || status >= 500)
+            throw new TourEntryUnavailable(status, said);
+        throw new Error(said);
+    }
     return json;
 }
 /** Enter and poll until seated.
@@ -60,28 +89,50 @@ export async function queueUntilSeated(client, tour, options = {}) {
     const timeoutMs = options.timeoutMs ?? 300_000;
     const pollMs = options.pollMs ?? 3_000;
     const deadline = Date.now() + timeoutMs;
+    /* When the origin first went quiet on us, or null while it is answering. A
+       product restarted under a queued agent used to end its run on the proxy's
+       502, which is a deployment rather than a refusal. */
+    let unavailableSince = null;
     for (;;) {
-        const entry = await enterTour(client, tour);
+        let entry;
+        try {
+            entry = await enterTour(client, tour, { minAgents: options.minAgents });
+            unavailableSince = null;
+        }
+        catch (error) {
+            if (!unavailable(error))
+                throw error;
+            unavailableSince ??= Date.now();
+            const bound = options.restartBoundMs ?? QUEUE_RESTART_BOUND_MS;
+            if (Date.now() - unavailableSince >= bound || Date.now() >= deadline)
+                throw error;
+            options.onUnavailable?.(error);
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+            continue;
+        }
         if (entry.state === "seated" || entry.state === "offered")
             return entry;
         if (entry.state !== "waiting")
             throw new Error(`tour is not open: ${JSON.stringify(entry)}`);
         options.onWaiting?.(entry);
         if (Date.now() >= deadline)
-            throw new Error(`still waiting for a seat after ${timeoutMs} ms; the tour fills at ${entry.fillAtMs}`);
+            throw new Error(entry.atFill === "stays_queued"
+                ? `still waiting for a seat after ${timeoutMs} ms; no fill seats this agent until ` +
+                    `${entry.minAgents ?? options.minAgents} real agents are queued`
+                : `still waiting for a seat after ${timeoutMs} ms; the tour fills at ${entry.fillAtMs}`);
         await new Promise((resolve) => setTimeout(resolve, pollMs));
     }
 }
 export async function readPosition(client, tableId) {
     const { status, json } = await signedFetch(client, "GET", `/open/v1/tables/${tableId}/decision`);
     if (status !== 200)
-        throw new Error(`decision read refused (${status}): ${JSON.stringify(json)}`);
+        throw new Error(refusalMessage("decision read", status, json));
     return json;
 }
 export async function act(client, tableId, move) {
     const { status, json } = await signedFetch(client, "POST", `/open/v1/tables/${tableId}/actions`, move);
     if (status !== 200)
-        throw new Error(`action refused (${status}): ${JSON.stringify(json)}`);
+        throw new Error(refusalMessage("action", status, json));
     return json;
 }
 /** The reference strategy: never wager, call only what is free. It exists so
@@ -98,15 +149,41 @@ export function foldHeavy(turn) {
  *
  *  A lapsed turn is not an error: the authority acts for a silent seat on its
  *  own clock, so a slow decision costs the hand rather than the match, and the
- *  loop keeps reading. Only a refusal the server calls terminal stops it. */
+ *  loop keeps reading. Only a refusal the server calls terminal stops it.
+ *
+ *  **Being eliminated does not end the sitting.** This used to return the
+ *  moment the seat lost its last chip, which reads as the natural thing to do —
+ *  there is no turn coming — and is how a seat ends up reporting a result
+ *  before the table has one and walking away from a settlement the whole table
+ *  is waiting on. A busted seat keeps watching to the table's terminal, which
+ *  the route answers as `complete` for an out seat too, and says it busted in
+ *  the report instead. */
 export async function playTour(client, tableId, decide = foldHeavy, options = {}) {
     const pollMs = options.pollMs ?? 1_000;
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const deadline = Date.now() + timeoutMs;
     let committedActions = 0;
+    let eliminated = false;
     const hands = new Set();
     for (;;) {
+        if (Date.now() >= deadline)
+            throw new Error(`the table reached no terminal after ${timeoutMs} ms; it committed ${committedActions} action(s) over ${hands.size} hand(s)`);
         const turn = await readPosition(client, tableId);
-        if (turn.state === "complete" || turn.state === "eliminated")
-            return { outcome: turn.state, committedActions, hands: hands.size };
+        if (turn.state === "complete")
+            return {
+                outcome: turn.state,
+                committedActions,
+                hands: hands.size,
+                eliminated,
+            };
+        if (turn.state === "eliminated") {
+            if (!eliminated) {
+                eliminated = true;
+                options.onEliminated?.();
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+            continue;
+        }
         if (turn.state !== "your_turn") {
             await new Promise((resolve) => setTimeout(resolve, pollMs));
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dopamint-fun/open-sdk",
-  "version": "0.1.0-dev.0",
+  "version": "0.2.0-dev.0",
   "description": "DOPA-OPEN client SDK: generate and hold your own agent key, sign registrations, and play a Participant Session",
   "license": "Apache-2.0",
   "repository": {