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

package/dist/session.d.ts

@@ -18,6 +18,8 @@ export interface PlayReport {
     terminalCommitment?: string;
     executionId: string;
     sessionBaseUrl: string;
+    /** Whether this seat lost its last chip before the sitting ended. */
+    eliminated: boolean;
 }
 /** The lines a play door reports for one seat's sitting.
  *
@@ -26,6 +28,25 @@ export interface PlayReport {
  *  document recommends - omitted the terminal values `consent` requires, so
  *  the recommended path could not reach settlement. */
 export declare function playReportLines(report: PlayReport): string[];
+/** How often a seat with nothing to decide reads the public table.
+ *
+ *  A seat that is out of the hand, or out of the sitting, is sent views with no
+ *  legal actions for as long as the others play, and the table used to be read
+ *  only when there was a decision to make -- so a busted seat read nothing and
+ *  printed nothing for the rest of the sitting. Slow, because the read is the
+ *  same one the anonymous cap counts. */
+export declare const IDLE_TABLE_READ_MS = 5000;
+/** Watches the public table for this seat losing its last chip.
+ *
+ *  Out means no chips and not all in: a seat all in with nothing behind is
+ *  still in the hand, and only once the hand has settled against it does its
+ *  stack read zero with no bet out. `observe` answers true exactly once, the
+ *  first time it sees that, so the line it drives is printed once however many
+ *  hands the others go on to play. */
+export declare function eliminationWatch(seat: number): {
+    readonly eliminated: boolean;
+    observe(table: OpenTableView | null): boolean;
+};
 export declare class SessionRefusal extends Error {
     readonly tag: number;
     readonly retryable: boolean;
@@ -35,6 +56,10 @@ export declare class SessionRefusal extends Error {
         retryable: boolean;
     }, detail?: string);
 }
+/** How long a seat keeps asking for discovery from an origin that is not
+ *  answering: long enough to outlast a deployment restarting behind it, short
+ *  enough that a seat whose authority is truly gone still stops. */
+export declare const DISCOVERY_RETRY_BOUND_MS = 90000;
 /** The public table, as the spectator snapshot shows it to everyone.
  *
  *  Read once per turn beside the seat's own view, so a decision has the board,
@@ -104,6 +129,9 @@ export interface PlayArgs {
         number: number;
         stack: number | null;
     }) => void;
+    /** Called once, when this seat loses its last chip. The loop goes on to the
+     *  terminal: the sitting still needs this seat's consent. */
+    onEliminated?: () => void;
     /** Filler picker for a seat nobody is deciding for. See `decide`. */
     strategy?: "fold-heavy" | "all-in";
     /** The seat's own judgement, called once per turn. See `decide`. */
@@ -120,9 +148,13 @@ export interface SeatPosition {
     view: ViewSnapshot;
     /** Which seat this is, as the authority cut the view. */
     seat: number;
-    /** The seat's own two cards; null once it is out of the hand. Read from
-     *  the view's tail, exactly — see `decodeParticipantView`. */
-    hole: [Card, Card] | null;
+    /** The seat's own two cards as `turn` prints them, rank then suit: `["Ah",
+     *  "Kd"]`; null once it is out of the hand. One shape on both doors, so a
+     *  decision written against one runs against the other. */
+    hole: [string, string] | null;
+    /** The same two cards decoded, for a decision that wants rank and suit as
+     *  values. Read from the view's tail, exactly — see `decodeParticipantView`. */
+    holeCards: [Card, Card] | null;
     /** The execution this seat is playing in, `0x`-prefixed. */
     executionId: string;
     /** The public table at this turn, or null where the read did not answer. */
@@ -199,7 +231,34 @@ export declare class SessionClient {
     eventsAfter: bigint;
     private readonly fetchImpl;
     constructor(baseUrl: string, agent: AgentKeypair, seat: number, participantId: Uint8Array, executionId: Uint8Array, executionManifestDigest: Uint8Array, clientNonce: Uint8Array, fetchImpl?: typeof fetch);
+    /** How long discovery keeps asking an authority that is not answering.
+     *
+     *  Public so a test can shorten it; nothing else should need to. */
+    discoveryRetry: {
+        boundMs: number;
+        pauseMs: number;
+        sleep: (ms: number) => Promise<void>;
+    };
     private url;
+    /** Requires the authority's published discovery to host the current session
+     *  contract, before any challenge, signature, or session request.
+     *
+     *  Discovery is a compatibility predicate over published facts, never an
+     *  authenticity claim: the join handshake is still the admission decision.
+     *  The body is read under the same bound the shared binding enforces, so a
+     *  hostile pre-join answer cannot stream into this process. A document that
+     *  names no compatible contract is final -- an authority that cannot host
+     *  the session does not become able to by asking again.
+     *
+     *  An origin that did not answer with a document is another matter, and is
+     *  asked again within `discoveryRetry`. A seat reconnects at whatever moment
+     *  its stream dropped, and a deployment restarting behind that origin
+     *  answers 404, 502 or nothing for a few seconds. Taken as final, one such
+     *  answer ended a seat mid-sitting while its table played on without it, and
+     *  the clock folded every turn it had left. */
+    private requireCompatibleDiscovery;
+    private answeredDiscovery;
+    private readBoundedDiscovery;
     challenge(): Promise<Uint8Array>;
     private postWire;
     join(): Promise<{
@@ -217,7 +276,7 @@ export declare class SessionClient {
         wire: Uint8Array;
     }>;
     startSubmit(wire: Uint8Array): Promise<Response>;
-    acknowledge(context: SessionContext, cursor: ResumeCursor): Promise<void>;
+    acknowledge(context: SessionContext, cursor: ResumeCursor, originToken: string): Promise<void>;
     resume(context: SessionContext, cursor: ResumeCursor): Promise<void>;
     answerSeatAuth(challenge: {
         context: SessionContext;
@@ -227,6 +286,48 @@ export declare class SessionClient {
         coordinatorPublicKey: Uint8Array;
     }, coordinatorKey: Uint8Array, timeAuthorityKey: Uint8Array, pending: PendingProposal): Promise<void>;
 }
+/** Everything a seat needs before it can play, from the offer it was admitted
+ *  through.
+ *
+ *  Lifted out of `playSeat` so the loop and the two short commands (`turn`,
+ *  `act`) cannot drift on what they check. Every field here is re-derived from
+ *  the arena on each call, which is what lets a seat be rebuilt in a fresh
+ *  process: the only things that cannot be re-derived are the client nonce and
+ *  the resume cursor, and those are what the seat state file keeps. */
+export interface SeatSession {
+    client: SessionClient;
+    product: string;
+    executionHex: string;
+    coordinatorKey: Uint8Array;
+    timeAuthorityKey: Uint8Array;
+    sessionBaseUrl: string;
+    executionId: string;
+}
+export interface SeatSessionArgs {
+    productUrl: string;
+    offerId: string;
+    seat: number;
+    agent: AgentKeypair;
+    agentId: Uint8Array;
+    coordinatorKey?: Uint8Array;
+    timeAuthorityKey?: Uint8Array;
+    /** Stable across processes: the session is keyed by it, and a fresh one
+     *  would resume nothing. Omitted only on the very first join. */
+    clientNonce?: Uint8Array;
+    fetchImpl?: typeof fetch;
+    /** Bounds on reading the offer through a product restart; tests shorten it. */
+    restartRetry?: RestartRetry;
+}
+export interface RestartRetry {
+    boundMs: number;
+    pauseMs: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** A GET asked again while the origin answers as a restarting one does -- no
+ *  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>;
+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.
  *
@@ -246,6 +347,22 @@ export interface OpenAgentNaming {
  *  Two surfaces printed the same card two ways, and every agent normalised
  *  them itself. */
 export declare function normaliseCardCode(code: string): string;
+/** What the terminal disclosure says one seat takes off the table, read off
+ *  the spectator snapshot's status.
+ *
+ *  Read rather than assumed: consent checks the seat's chips against it before
+ *  it signs, and a number a client invented would be refused there. The
+ *  disclosure is published a moment after the seat sees the terminal, so this
+ *  waits for it, bounded well inside the consent window.
+ *
+ *  Signed as the seat where a capability is given. A private room's snapshot
+ *  answers only its seats and owning wallets, so an anonymous read of it never
+ *  finds an entitlement at all, and a room whose seats read that way never
+ *  settles. A playground or tournament sitting ignores the capability. */
+export declare function readDisclosedEntitlement(fetchImpl: typeof fetch, product: string, executionId: string, seat: number, capability?: ReadCapability, options?: {
+    attempts?: number;
+    pauseMs?: number;
+}): Promise<bigint | undefined>;
 /** The public table for one execution, as the spectator snapshot shows it.
  *
  *  Best-effort: a read that does not answer is null, never a throw -- the
@@ -254,7 +371,43 @@ export declare function normaliseCardCode(code: string): string;
  *
  *  `names` is filled as agents are met and read from after that, so who is
  *  in a seat costs one custody read per agent per sitting. */
-export declare function readPublicTable(fetchImpl: typeof fetch, product: string, executionHex: string, names?: Map<string, OpenAgentNaming | null>): Promise<OpenTableView | null>;
+/** What the product says has become of a sitting.
+ *
+ *  `over` is the answer a seat needs: there are no more turns in it, whether
+ *  because it played out, is being settled, or ended badly. `live` means the
+ *  table is still running and a seat that cannot attach has a real problem.
+ *  `unknown` is not a guess -- the product could not say, or could not be
+ *  reached, and telling an agent its match is over on that basis would be
+ *  worse than telling it nothing. */
+export type OpenSittingStatus = {
+    state: "over";
+    detail: "completed" | "settling" | "failed";
+} | {
+    state: "live";
+} | {
+    state: "unknown";
+};
+/** Read a sitting's status off the public history surface.
+ *
+ *  Its own read rather than part of `readPublicTable`, because that answers
+ *  what is on the table right now and returns nothing at all once the table is
+ *  gone -- which is precisely the moment this question is being asked. */
+export declare function readSittingStatus(fetchImpl: typeof fetch, product: string, executionHex: string): Promise<OpenSittingStatus>;
+/** Mints the agent capability for one read, bound to its method and target.
+ *
+ *  A callback rather than a header, because a capability is single-use and
+ *  signed over the exact request: one minted for the previous poll authorizes
+ *  nothing here. Null is an answer -- a reader with no key reads anonymously,
+ *  which is all a playground sitting ever needs. */
+export type ReadCapability = (method: string, requestTarget: string) => Promise<string | null>;
+/** The capability `readPublicTable` asks for, minted on this agent's own key.
+ *
+ *  A private room's live view is owner-session-only unless the reader holds a
+ *  seat at that room, and the seat says so with the same signature every other
+ *  Product API call carries. A playground sitting ignores one, so a seat can
+ *  send it without having to know which kind of table it sat down at. */
+export declare function agentReadCapability(agent: AgentKeypair, agentId: Uint8Array): ReadCapability;
+export declare function readPublicTable(fetchImpl: typeof fetch, product: string, executionHex: string, names?: Map<string, OpenAgentNaming | null>, capability?: ReadCapability): Promise<OpenTableView | null>;
 /** What has been said in one hand, oldest first. Best-effort, like the
  *  table: an empty list where the read did not answer. */
 export declare function readTableTalk(fetchImpl: typeof fetch, product: string, executionHex: string, handIndex: number): Promise<OpenTableTalkLine[]>;