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

package/dist/index.d.ts

@@ -2,10 +2,10 @@ export { DEFAULT_KEY_FILE, generateKeypair, keypairFromSeed, loadKeypair, saveKe
 export { deriveAgentId, registerCanonicalPayload, registerPayloadDigest, type RegisterAgentPayload, } from "./registration.js";
 export { canonicalIdentityPayload, nameAgent, parseIdentityFields, type AgentIdentityFields, type NameAgentArgs, } from "./identity.js";
 export { actionSigningBytes, encodeActionFrame, encodeJoinFrame, encodeResumeFrame, joinSigningBytes, resumeSigningBytes, SESSION_VERSION, UnsupportedSessionVersionError, type ActionProposal, type ArtifactReference, type JoinRequest, type ResumeRequest, type SessionContext, } from "./sessionWire.js";
-export { encodeAckFrame, SESSION_ERROR_NAMES, sessionErrorHint, sessionErrorName, } from "./sessionCodec.js";
-export { type OpenTableView, type PlayReport, type SeatDecision, type SeatDecisionResult, type SeatPosition, SessionClient, SessionRefusal, chooseSeatAction, playSeat, } from "./session.js";
+export { encodeAckFrame, SESSION_ERROR_NAMES, MAX_PREDICTION_PACING_MS, admitAuthorityEvent, applyPredictionGateStatus, decodeAuthorityMessage, freshSessionBoundary, predictionGateMessage, predictionGatePreparationOf, predictionGateTargetReceipt, sessionErrorHint, sessionErrorName, PredictionGateConflictError, SessionBoundaryError, type AcceptedSessionBoundary, type AuthorityMessage, type PredictionGateMessage, type PredictionGateOpening, type PredictionGatePreparation, type PredictionGateRelease, type PredictionGateStatus, type PredictionWindowRef, type ReceiptRef, type ResumeCursor, type StateRef, type ViewSnapshot, } from "./sessionCodec.js";
+export { type OpenTableView, type PlayReport, type SeatDecision, type SeatDecisionResult, type SeatPosition, SessionClient, SessionRefusal, chooseSeatAction, playSeat, waitForReadyOwner, } from "./session.js";
 export { cardFromByte, decodeLegalActions, decodeParticipantView, encodeAction, pickAction, type Card, type Rank, type Suit, type TexasAction, type TexasLegalActions, type TexasSeatView, } from "./texas.js";
-export { authorityOriginFromSessionBase, buildConsentRequest, digestForPrompt, recomputeSettlementDigest, settlementConsentPath, verifyConsentDisclosure, } from "./settlement.js";
+export { buildConsentRequest, DEFAULT_OPEN_API_BASE_URL, digestForPrompt, recomputeSettlementDigest, settlementConsentPath, verifyConsentDisclosure, } from "./settlement.js";
 export { PACKAGE_NAME, RELEASE_CHANNELS, channelDistTag, installCommand, installSpec, resolveChannel, versionMatchesChannel, type ReleaseChannel, } from "./channel.js";
 export { fromHex, toHex } from "./bytes.js";
 export { AGENT_HTTP_CAPABILITY_HEADER, AGENT_HTTP_CAPABILITY_NONCE_BYTES, MAX_AGENT_HTTP_CAPABILITY_WINDOW_MS, agentHttpCanonicalPayload, agentHttpSigningBytes, decodeAgentHttpHeader, encodeAgentHttpHeader, mintAgentHttpCapability, type AgentHttpBinding, type AgentHttpCapability, } from "./agentHttp.js";
@@ -14,8 +14,8 @@ export { joinRoom, MAX_ROOM_SEATS, MIN_ROOM_SEATS, openRoom, roomInvitePrompt, t
 export { AGENT_CLAIM_INVITE_DOMAIN, AGENT_CLAIM_INVITE_MAX_WINDOW_MS, AGENT_CLAIM_INVITE_TOKEN_BYTES, claimInviteCanonicalPayload, claimInviteLink, claimInviteSigningBytes, decodeClaimInvite, encodeClaimInvite, encodeClaimInviteCompact, mintClaimInvite, type ClaimInvite, } from "./claim.js";
 export { baselineDecision, baselineMove, opponentsStillIn, } from "./decide.js";
 export { handEquity, requiredEquity, cardCode, type HandEquity, type HandEquityOptions, } from "./equity.js";
-export { bestFive, cardIndex, handCategory, scoreHand, HAND_CATEGORIES, RANK_ORDER, SUIT_ORDER, type BestFive, type HandCategory, } from "./handRank.js";
+export { cardIndex, handCategory, scoreHand, HAND_CATEGORIES, RANK_ORDER, SUIT_ORDER, type BestFive, type HandCategory, } from "./handRank.js";
 export { DEFAULT_SEAT_STATE_FILE, loadSeatState, saveSeatState, type SeatSessionState, } from "./seatState.js";
-export { newSeatState, openTurn, submitTurn, type SeatTurnOutcome, type SeatTurnPosition, } from "./seatTurn.js";
-export { chipAddressOf, joinTransaction, leaveTransaction, listTournaments, planJoin, presentToTournament, readAgentEntry, readPass, readOwner, playsHeldBy, giveBackTransaction, readTournament, sponsorAndExecute, tournamentIdArg, tournamentPossessionSignature, JoinRefused, TournamentRefusal, TOURNAMENT_POSSESSION_SEAT, type JoinPlan, type SponsoredExecution, type TournamentAgentEntry, type TournamentPass, type TournamentPlay, type TournamentOwnerView, type TournamentOwnerAgent, type TournamentChainObjects, type TournamentClient, type TournamentOverview, type TournamentQueueEntry, } from "./openTournament.js";
-export { ClientRefusal, describeNext, refusalLines, refusalMessage, refusalMessageFromText, type RefusalBody, type RefusalNext, } from "./refusal.js";
+export { newSeatState, openTurn, submitTurn, type SeatStateCheckpoint, type SeatTurnOutcome, type SeatTurnPosition, } from "./seatTurn.js";
+export { chipAddressOf, joinTransaction, leaveTransaction, listTournaments, planJoin, presentToTournament, readAgentEntry, readAgentEntrySettled, BOOK_CATCHES_UP_MS, readPass, readOwner, playsHeldBy, giveBackTransaction, readTournament, sponsorAndExecute, tournamentIdArg, tournamentPossessionSignature, JoinRefused, TournamentRefusal, TOURNAMENT_POSSESSION_SEAT, type JoinPlan, type SponsoredExecution, type TournamentAgentEntry, type TournamentPass, type TournamentPlay, type TournamentOwnerView, type TournamentOwnerAgent, type TournamentChainObjects, type TournamentClient, type TournamentOverview, type TournamentQueueEntry, } from "./openTournament.js";
+export { ClientRefusal, describeNext, ownershipFencePoll, ownershipFenced, refusalLines, refusalMessage, refusalMessageFromText, type RefusalBody, type RefusalNext, } from "./refusal.js";

package/dist/index.js

@@ -3,16 +3,16 @@
  * Generate and hold an ed25519 keypair (Sui format, `.dopa-keypair`), produce
  * the canonical signatures, and drive the Participant Session against
  * `session_base_url`. Byte parity with the Rust client is pinned by
- * `libs/dopa-open-client-rs/vectors/ts-signer-parity.json`.
+ * `libs/dopa-open/client-rs/vectors/ts-signer-parity.json`.
  */
 export { DEFAULT_KEY_FILE, generateKeypair, keypairFromSeed, loadKeypair, saveKeypair, signOwnerAuthenticator, signRaw, } from "./keypair.js";
 export { deriveAgentId, registerCanonicalPayload, registerPayloadDigest, } from "./registration.js";
 export { canonicalIdentityPayload, nameAgent, parseIdentityFields, } from "./identity.js";
 export { actionSigningBytes, encodeActionFrame, encodeJoinFrame, encodeResumeFrame, joinSigningBytes, resumeSigningBytes, SESSION_VERSION, UnsupportedSessionVersionError, } from "./sessionWire.js";
-export { encodeAckFrame, SESSION_ERROR_NAMES, sessionErrorHint, sessionErrorName, } from "./sessionCodec.js";
-export { SessionClient, SessionRefusal, chooseSeatAction, playSeat, } from "./session.js";
+export { encodeAckFrame, SESSION_ERROR_NAMES, MAX_PREDICTION_PACING_MS, admitAuthorityEvent, applyPredictionGateStatus, decodeAuthorityMessage, freshSessionBoundary, predictionGateMessage, predictionGatePreparationOf, predictionGateTargetReceipt, sessionErrorHint, sessionErrorName, PredictionGateConflictError, SessionBoundaryError, } from "./sessionCodec.js";
+export { SessionClient, SessionRefusal, chooseSeatAction, playSeat, waitForReadyOwner, } from "./session.js";
 export { cardFromByte, decodeLegalActions, decodeParticipantView, encodeAction, pickAction, } from "./texas.js";
-export { authorityOriginFromSessionBase, buildConsentRequest, digestForPrompt, recomputeSettlementDigest, settlementConsentPath, verifyConsentDisclosure, } from "./settlement.js";
+export { buildConsentRequest, DEFAULT_OPEN_API_BASE_URL, digestForPrompt, recomputeSettlementDigest, settlementConsentPath, verifyConsentDisclosure, } from "./settlement.js";
 export { PACKAGE_NAME, RELEASE_CHANNELS, channelDistTag, installCommand, installSpec, resolveChannel, versionMatchesChannel, } from "./channel.js";
 export { fromHex, toHex } from "./bytes.js";
 export { AGENT_HTTP_CAPABILITY_HEADER, AGENT_HTTP_CAPABILITY_NONCE_BYTES, MAX_AGENT_HTTP_CAPABILITY_WINDOW_MS, agentHttpCanonicalPayload, agentHttpSigningBytes, decodeAgentHttpHeader, encodeAgentHttpHeader, mintAgentHttpCapability, } from "./agentHttp.js";
@@ -26,8 +26,8 @@ export { joinRoom, MAX_ROOM_SEATS, MIN_ROOM_SEATS, openRoom, roomInvitePrompt, }
 export { AGENT_CLAIM_INVITE_DOMAIN, AGENT_CLAIM_INVITE_MAX_WINDOW_MS, AGENT_CLAIM_INVITE_TOKEN_BYTES, claimInviteCanonicalPayload, claimInviteLink, claimInviteSigningBytes, decodeClaimInvite, encodeClaimInvite, encodeClaimInviteCompact, mintClaimInvite, } from "./claim.js";
 export { baselineDecision, baselineMove, opponentsStillIn, } from "./decide.js";
 export { handEquity, requiredEquity, cardCode, } from "./equity.js";
-export { bestFive, cardIndex, handCategory, scoreHand, HAND_CATEGORIES, RANK_ORDER, SUIT_ORDER, } from "./handRank.js";
+export { cardIndex, handCategory, scoreHand, HAND_CATEGORIES, RANK_ORDER, SUIT_ORDER, } from "./handRank.js";
 export { DEFAULT_SEAT_STATE_FILE, loadSeatState, saveSeatState, } from "./seatState.js";
 export { newSeatState, openTurn, submitTurn, } from "./seatTurn.js";
-export { chipAddressOf, joinTransaction, leaveTransaction, listTournaments, planJoin, presentToTournament, readAgentEntry, readPass, readOwner, playsHeldBy, giveBackTransaction, readTournament, sponsorAndExecute, tournamentIdArg, tournamentPossessionSignature, JoinRefused, TournamentRefusal, TOURNAMENT_POSSESSION_SEAT, } from "./openTournament.js";
-export { ClientRefusal, describeNext, refusalLines, refusalMessage, refusalMessageFromText, } from "./refusal.js";
+export { chipAddressOf, joinTransaction, leaveTransaction, listTournaments, planJoin, presentToTournament, readAgentEntry, readAgentEntrySettled, BOOK_CATCHES_UP_MS, readPass, readOwner, playsHeldBy, giveBackTransaction, readTournament, sponsorAndExecute, tournamentIdArg, tournamentPossessionSignature, JoinRefused, TournamentRefusal, TOURNAMENT_POSSESSION_SEAT, } from "./openTournament.js";
+export { ClientRefusal, describeNext, ownershipFencePoll, ownershipFenced, refusalLines, refusalMessage, refusalMessageFromText, } from "./refusal.js";

package/dist/offer.js

@@ -52,7 +52,7 @@ function record(raw) {
     };
 }
 export async function readOffer(productUrl, offerId) {
-    const { status, json } = await readJson(`${productUrl.replace(/\/$/, "")}/open/v1/playground/matches/${offerId}`);
+    const { status, json } = await readJson(`${productUrl.replace(/\/$/, "")}/v1/playground/matches/${offerId}`);
     if (status !== 200)
         throw new Error(refusalMessage("offer read", status, json));
     return record(json);
@@ -81,7 +81,7 @@ export async function acceptOffer(productUrl, offerId, seat, agent) {
         signature: Array.from(signed.signature),
         seat_possession_signature: Array.from(signed.seatPossessionSignature),
     });
-    const { status, json } = await readJson(`${productUrl.replace(/\/$/, "")}/open/v1/playground/matches/${offerId}/acceptances`, { method: "POST", headers: { "content-type": "application/json" }, body });
+    const { status, json } = await readJson(`${productUrl.replace(/\/$/, "")}/v1/playground/matches/${offerId}/acceptances`, { method: "POST", headers: { "content-type": "application/json" }, body });
     if (status === 200 || status === 201)
         return;
     if (status === 409)
@@ -89,7 +89,7 @@ export async function acceptOffer(productUrl, offerId, seat, agent) {
     throw new Error(refusalMessage("acceptance", status, json));
 }
 async function admit(productUrl, offerId, agentId, agent) {
-    const target = `/open/v1/playground/matches/${offerId}/admit`;
+    const target = `/v1/playground/matches/${offerId}/admit`;
     const { header } = await mintAgentHttpCapability(agent, agentId, {
         method: "POST",
         requestTarget: target,

package/dist/openTournament.d.ts

@@ -143,6 +143,28 @@ export declare function readTournamentMatches(productUrl: string, tournamentId:
 export declare function disputeHolding(productUrl: string, tournamentId: string, chipAddress: string, fetchImpl?: typeof fetch): Promise<number | undefined>;
 /** The agent's entry in the chip book, or `null` before its first redeem. */
 export declare function readAgentEntry(productUrl: string, tournamentId: string, chipAddress: string, fetchImpl?: typeof fetch): Promise<TournamentAgentEntry | null>;
+/** How long a book read waits for a join that has just landed.
+ *
+ *  The book is the chain's, read a checkpoint behind it: an agent whose
+ *  `queue_join` succeeded a moment ago is on chain and not yet in the book.
+ *  Measured at about a second on a local stack; this is generous enough to
+ *  cover a slower one and short enough that an agent that really is absent is
+ *  told so rather than left waiting. */
+export declare const BOOK_CATCHES_UP_MS = 8000;
+/** The agent's entry, waited for while the book catches up with the chain.
+ *
+ *  For a caller that has just been told its join landed. A plain
+ *  `readAgentEntry` answering `null` in that window is not "this agent never
+ *  queued" — it is "the book has not seen the queue join yet", and the two are
+ *  worth telling apart before refusing somebody. Absent for the whole bound is
+ *  the first answer, and this returns `null` for it. */
+export declare function readAgentEntrySettled(productUrl: string, tournamentId: string, chipAddress: string, options?: {
+    boundMs?: number;
+    pollMs?: number;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): Promise<TournamentAgentEntry | null>;
 /** An owner's pass, or `null` when the owner has claimed none. */
 export declare function readPass(productUrl: string, tournamentId: string, owner: string, fetchImpl?: typeof fetch): Promise<TournamentPass | null>;
 /** An owner's side: its pass and every agent it has claimed, each with the

package/dist/openTournament.js

@@ -26,7 +26,7 @@ function base(productUrl) {
     return productUrl.replace(/\/$/, "");
 }
 function tournamentPath(tournamentId, rest = "") {
-    return `/open/v1/tournaments/${tournamentId}${rest}`;
+    return `/v1/tournaments/${tournamentId}${rest}`;
 }
 async function readJson(fetchImpl, url) {
     const response = await fetchImpl(url);
@@ -57,7 +57,7 @@ export async function readTournament(productUrl, tournamentId, fetchImpl = fetch
 }
 /** The open-entry tournaments the product runs. */
 export async function listTournaments(productUrl, fetchImpl = fetch) {
-    const { status, json } = await readJson(fetchImpl, `${base(productUrl)}/open/v1/tournaments`);
+    const { status, json } = await readJson(fetchImpl, `${base(productUrl)}/v1/tournaments`);
     if (status === 404)
         return [];
     if (status !== 200)
@@ -100,6 +100,37 @@ export async function readAgentEntry(productUrl, tournamentId, chipAddress, fetc
         throw new TournamentRefusal(status, json, "chip book read");
     return json;
 }
+/** How long a book read waits for a join that has just landed.
+ *
+ *  The book is the chain's, read a checkpoint behind it: an agent whose
+ *  `queue_join` succeeded a moment ago is on chain and not yet in the book.
+ *  Measured at about a second on a local stack; this is generous enough to
+ *  cover a slower one and short enough that an agent that really is absent is
+ *  told so rather than left waiting. */
+export const BOOK_CATCHES_UP_MS = 8_000;
+/** The agent's entry, waited for while the book catches up with the chain.
+ *
+ *  For a caller that has just been told its join landed. A plain
+ *  `readAgentEntry` answering `null` in that window is not "this agent never
+ *  queued" — it is "the book has not seen the queue join yet", and the two are
+ *  worth telling apart before refusing somebody. Absent for the whole bound is
+ *  the first answer, and this returns `null` for it. */
+export async function readAgentEntrySettled(productUrl, tournamentId, chipAddress, options = {}) {
+    const boundMs = options.boundMs ?? BOOK_CATCHES_UP_MS;
+    const pollMs = options.pollMs ?? 1_000;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = now() + boundMs;
+    for (;;) {
+        const entry = await readAgentEntry(productUrl, tournamentId, chipAddress, options.fetchImpl ?? fetch);
+        if (entry)
+            return entry;
+        if (now() >= deadline)
+            return null;
+        await sleep(pollMs);
+    }
+}
 /** An owner's pass, or `null` when the owner has claimed none. */
 export async function readPass(productUrl, tournamentId, owner, fetchImpl = fetch) {
     const { status, json } = await readJson(fetchImpl, `${base(productUrl)}${tournamentPath(tournamentId, `/passes/${owner}`)}`);
@@ -178,7 +209,7 @@ plays, owner) {
     if (entry && entry.state !== "idle")
         throw new JoinRefused(`this agent is already ${entry.state}${entry.state === "seated" ? " at a table" : ""}; an agent plays one table at a time`, {
             action: "wait",
-            poll: `/open/v1/tournaments/${overview.tournamentId}/agents/${entry.chipAddress}`,
+            poll: `/v1/tournaments/${overview.tournamentId}/agents/${entry.chipAddress}`,
         });
     const booked = entry?.balance ?? 0;
     const wallet = entry?.walletBalance ?? booked;

package/dist/refusal.d.ts

@@ -29,6 +29,11 @@ export interface RefusalBody {
     docs?: string;
 }
 /** `next …`, as one line an agent can act on. */
+/** True when a refusal body says the writer is fenced and the caller should
+ *  poll committed ownership rather than resend to the same origin. */
+export declare function ownershipFenced(body: unknown): boolean;
+/** The product route a fenced seat polls, when the refusal named one. */
+export declare function ownershipFencePoll(body: unknown): string | undefined;
 export declare function describeNext(next: RefusalNext): string;
 /** The lines a refusal prints: its code, what it said, the move, the entry. */
 export declare function refusalLines(body: unknown): string[];

package/dist/refusal.js

@@ -6,6 +6,27 @@
  * reading a refused command's output reads its move off the same lines rather
  * than off a table in a skill document. */
 /** `next …`, as one line an agent can act on. */
+/** True when a refusal body says the writer is fenced and the caller should
+ *  poll committed ownership rather than resend to the same origin. */
+export function ownershipFenced(body) {
+    if (typeof body !== "object" || body === null)
+        return false;
+    const refusal = body;
+    if (refusal.code !== "ownership_fenced")
+        return false;
+    return (isNext(refusal.next) &&
+        refusal.next.action === "wait" &&
+        typeof refusal.next.poll === "string");
+}
+/** The product route a fenced seat polls, when the refusal named one. */
+export function ownershipFencePoll(body) {
+    if (!ownershipFenced(body))
+        return undefined;
+    const next = body.next;
+    if (next && next.action === "wait")
+        return next.poll;
+    return undefined;
+}
 export function describeNext(next) {
     switch (next.action) {
         case "retry":

package/dist/room.d.ts

@@ -8,20 +8,35 @@ export interface RoomClient {
 /** A room as the product answers it on create. */
 export interface RoomOpened {
     tableId: string;
+    /** The chairs the room was opened for. An upper bound, not a roster: what
+     *  nobody takes stays empty for the sitting. */
     seatCount: number;
     settlement: string;
     mode: string;
     /** Present once the authority has an execution behind the table. */
     executionId?: string;
 }
-/** A join. `offerId` and `seat` are present on an authority stack, which is
- *  where the guest's seat is taken by accepting an offer with its own key. On
- *  a mock stack the room is joined and there is nothing to accept. */
+/** A join. `offerId` and `seat` are present once the room has composed, which
+ *  is where the guest's seat is taken by accepting an offer with its own key.
+ *  A room still filling answers how full it is instead, and when it deals to
+ *  the agents who are already in it. On a mock stack there is never an offer
+ *  and nothing to accept. */
 export interface RoomJoined {
     tableId: string;
     joined: boolean;
     offerId?: string;
     seat?: number;
+    /** How many chairs are taken, of `seatCount`. Absent once composed — every
+     *  seat in the offer holds an agent. */
+    seated?: number;
+    seatCount?: number;
+    /** When the room deals to the agents who are here rather than waiting for
+     *  the rest. Absent while one agent sits alone: a room of one has no sitting
+     *  to start, and waits indefinitely. */
+    fillAtMs?: number;
+    /** `authority` or `mock`, so a caller can tell "no offer because this stack
+     *  composes none" from "no offer yet". */
+    mode?: string;
 }
 /** The seat counts a private room can be opened with, both ends included.
  *
@@ -30,7 +45,12 @@ export interface RoomJoined {
  *  before the agent tells anybody a room exists. */
 export declare const MIN_ROOM_SEATS = 2;
 export declare const MAX_ROOM_SEATS = 10;
-/** Open a room this agent will host. Seats above the two taken are house. */
+/** Open a room this agent will host.
+ *
+ *  `seatCount` is how many agents may come, including this one. No seat is
+ *  ever filled for you: the room deals when its last chair is taken, or when
+ *  its fill window closes with at least two agents in it, and the chairs
+ *  nobody took stay empty for the sitting. */
 export declare function openRoom(client: RoomClient, seatCount: number): Promise<RoomOpened>;
 /** A join the product turned down, with the code it named. */
 export declare class RoomJoinRefusal extends Error {
@@ -53,8 +73,10 @@ export declare function joinRoom(client: RoomClient, tableId: string): Promise<R
 export declare function joinRoomWhenComposed(client: RoomClient, tableId: string, options?: {
     pollMs?: number;
     timeoutMs?: number;
-    /** Called once, the first time the room is found still waiting. */
-    onWaiting?: () => void;
+    /** Called once, the first time the room is found still waiting. Carries
+     *  the join that found it waiting, where there was one: the opener's own
+     *  join is refused rather than answered, so it has nothing to carry. */
+    onWaiting?: (joined?: RoomJoined) => void;
     sleep?: (ms: number) => Promise<void>;
     now?: () => number;
 }): Promise<RoomJoined>;
@@ -63,4 +85,4 @@ export declare function joinRoomWhenComposed(client: RoomClient, tableId: string
  *  A prompt rather than a URL: what the guest needs is the document that says
  *  what to do and the id to do it with, and an operator pasting two things in
  *  the right order is how a room went unjoined. */
-export declare function roomInvitePrompt(productUrl: string, tableId: string): string;
+export declare function roomInvitePrompt(productUrl: string, tableId: string, seatsOpen?: number): string;

package/dist/room.js

@@ -46,13 +46,18 @@ async function signedFetch(client, method, target, body) {
  *  before the agent tells anybody a room exists. */
 export const MIN_ROOM_SEATS = 2;
 export const MAX_ROOM_SEATS = 10;
-/** Open a room this agent will host. Seats above the two taken are house. */
+/** Open a room this agent will host.
+ *
+ *  `seatCount` is how many agents may come, including this one. No seat is
+ *  ever filled for you: the room deals when its last chair is taken, or when
+ *  its fill window closes with at least two agents in it, and the chairs
+ *  nobody took stay empty for the sitting. */
 export async function openRoom(client, seatCount) {
     if (!Number.isInteger(seatCount) ||
         seatCount < MIN_ROOM_SEATS ||
         seatCount > MAX_ROOM_SEATS)
         throw new Error(`a private room seats ${MIN_ROOM_SEATS} to ${MAX_ROOM_SEATS}, not ${seatCount}`);
-    const { status, json } = await signedFetch(client, "POST", "/open/v1/tables/private-rooms", { seatCount });
+    const { status, json } = await signedFetch(client, "POST", "/v1/tables/private-rooms", { seatCount });
     if (status !== 201) {
         if (json?.code === "agent_not_claimed")
             throw notClaimed();
@@ -90,7 +95,7 @@ export class RoomJoinRefusal extends Error {
 }
 /** Join a room by the id its opener handed out. */
 export async function joinRoom(client, tableId) {
-    const target = `/open/v1/tables/private-rooms/${tableId}/join`;
+    const target = `/v1/tables/private-rooms/${tableId}/join`;
     const { status, json } = await signedFetch(client, "POST", target);
     if (status !== 201) {
         if (json?.code === "agent_not_claimed")
@@ -105,6 +110,10 @@ export async function joinRoom(client, tableId) {
         joined: json.joined === true,
         offerId: json.offerId ?? undefined,
         seat: json.seat ?? undefined,
+        seated: json.seated ?? undefined,
+        seatCount: json.seatCount ?? undefined,
+        fillAtMs: json.fillAtMs ?? undefined,
+        mode: json.mode ?? undefined,
     };
 }
 /** Join, and wait for the room to fill when this agent already holds a seat
@@ -125,22 +134,37 @@ export async function joinRoomWhenComposed(client, tableId, options = {}) {
     const now = options.now ?? Date.now;
     const deadline = now() + timeoutMs;
     let told = false;
+    const stillWaiting = () => {
+        if (now() >= deadline)
+            throw new Error(`room ${tableId} had not composed after ${timeoutMs} ms; ` +
+                "send the invite line to the guests you are still waiting for, ask its " +
+                "owner to start the room with whoever is already in it, or open a room again later");
+    };
     for (;;) {
         try {
-            return await joinRoom(client, tableId);
+            const joined = await joinRoom(client, tableId);
+            /* Joined, and the room is still filling: this agent holds a chair and
+               there is no offer to accept until the room deals. A mock stack
+               composes no offer at all, so its join is the answer rather than a step
+               towards one. */
+            if (joined.offerId !== undefined || joined.mode === "mock")
+                return joined;
+            stillWaiting();
+            if (!told) {
+                told = true;
+                options.onWaiting?.(joined);
+            }
         }
         catch (error) {
             if (!(error instanceof RoomJoinRefusal) || error.code !== "already_seated")
                 throw error;
-            if (now() >= deadline)
-                throw new Error(`room ${tableId} still had nobody in its other seat after ${timeoutMs} ms; ` +
-                    "send the invite line to the guest, or open the room again later");
+            stillWaiting();
             if (!told) {
                 told = true;
                 options.onWaiting?.();
             }
-            await sleep(pollMs);
         }
+        await sleep(pollMs);
     }
 }
 /** The one line an opener hands its guest, which is the whole invitation.
@@ -148,7 +172,13 @@ export async function joinRoomWhenComposed(client, tableId, options = {}) {
  *  A prompt rather than a URL: what the guest needs is the document that says
  *  what to do and the id to do it with, and an operator pasting two things in
  *  the right order is how a room went unjoined. */
-export function roomInvitePrompt(productUrl, tableId) {
+export function roomInvitePrompt(productUrl, tableId, seatsOpen) {
     const base = productUrl.replace(/\/$/, "");
-    return `read ${base}/skills/private-room.md and join table ${tableId}`;
+    /* How many can still come, when the caller knows. A room deals to whoever
+       is in it when its window closes, so a guest reading this is being told
+       both what to do and how much room is left to do it in. */
+    const room = seatsOpen === undefined
+        ? ""
+        : ` (${seatsOpen} ${seatsOpen === 1 ? "seat" : "seats"} open)`;
+    return `read ${base}/skills/private-room.md and join table ${tableId}${room}`;
 }

package/dist/seatState.d.ts

@@ -1,5 +1,5 @@
 import type { SessionContext } from "./sessionWire.js";
-import type { ResumeCursor, ViewSnapshot } from "./sessionCodec.js";
+import { type PredictionGateStatus, type ResumeCursor, type ViewSnapshot } from "./sessionCodec.js";
 /** Written beside the key file, as `.dopa-keypair` is. */
 export declare const DEFAULT_SEAT_STATE_FILE = ".dopa-seat";
 export interface SeatSessionState {
@@ -37,6 +37,8 @@ export interface SeatSessionState {
      *  the documented `act` refused its first turn. Absent in a file written
      *  before it existed. */
     agentId?: string | null;
+    predictionGate: SerialisedGate | null;
+    awaitingGatePrefix: boolean;
 }
 interface SerialisedContext {
     wireVersion: number;
@@ -70,22 +72,76 @@ interface SerialisedView {
     participantDeadlineMs: string;
     latestReceipt: SerialisedReceipt | null;
 }
+interface SerialisedWindow {
+    windowId: string;
+    marketId: string;
+    contract: "pokerActionV1";
+}
+interface SerialisedPreparation {
+    window: SerialisedWindow;
+    actingSeat: number;
+    state: SerialisedState;
+    receipt: SerialisedReceipt | null;
+    originalDeadlineMs: string;
+    preparedAtMs: string;
+}
+interface SerialisedOpening {
+    preparation: SerialisedPreparation;
+    openedAtMs: string;
+    closesAtMs: string;
+}
+interface SerialisedRelease {
+    window: SerialisedWindow;
+    actingSeat: number;
+    state: SerialisedState;
+    receipt: SerialisedReceipt | null;
+    terminal: "locked" | "cancelled";
+    originalDeadlineMs: string;
+    arrivalMs: string;
+    lockedAtMs: string;
+    budgetMs: string;
+    terminalDigest: string | null;
+}
+type SerialisedGate = {
+    phase: "prepared";
+    preparation: SerialisedPreparation;
+} | {
+    phase: "open";
+    opening: SerialisedOpening;
+} | {
+    phase: "released";
+    release: SerialisedRelease;
+};
 export declare function encodeContext(context: SessionContext): SerialisedContext;
 export declare function decodeContext(stored: SerialisedContext): SessionContext;
 export declare function encodeCursor(cursor: ResumeCursor): SerialisedCursor;
 export declare function decodeCursor(stored: SerialisedCursor): ResumeCursor;
 export declare function encodeView(view: ViewSnapshot): SerialisedView;
 export declare function decodeView(stored: SerialisedView): ViewSnapshot;
+/** The accepted gate phase, in the file's own vocabulary. */
+export declare function encodeGate(gate: PredictionGateStatus): SerialisedGate;
+export declare function decodeGate(stored: SerialisedGate): PredictionGateStatus;
 /** 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 declare function loadSeatState(path: string): SeatSessionState | null;
-/** 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. */
+/** 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 declare function saveSeatState(path: string, state: SeatSessionState): void;
 export {};