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

package/dist/seatAuth.js

@@ -0,0 +1,285 @@
+import { ByteReader, ByteWriter, concatBytes, equalBytes, frameSigningBytes, textBytes, } from "./bytes.js";
+import { blake2b256, verifyEd25519 } from "./crypto.js";
+import { takePrincipalProof } from "./sessionCodec.js";
+import { decodeAction, decodePlayerActionInput } from "./texas.js";
+const TRANSITION_AUTHORIZATION_DOMAIN = textBytes("arena_tunnel::transition_authorization");
+const ARRIVAL_EVIDENCE_DOMAIN = textBytes("arena_tunnel::arrival_evidence");
+const LOCK_EVIDENCE_DOMAIN = textBytes("arena_tunnel::lock_evidence");
+const SEAT_GENERATION_DOMAIN = textBytes("dopa_open::seat_generation::v1");
+const ROLE_GENERATION_DOMAIN = textBytes("dopa_open::role_generation::v1");
+const TIME_EVIDENCE_ABSENT = 0;
+const TIME_EVIDENCE_PRESENT = 1;
+const ARRIVAL_EVIDENCE_TAG = 0;
+const DEADLINE_EVIDENCE_TAG = 1;
+const LOCK_EVIDENCE_TAG = 2;
+const PARTICIPANT_ACTION_TAG = 0;
+const ALL_OF_TAG = 0;
+const SEAT_PRINCIPAL_TAG = 0;
+const ROLE_PRINCIPAL_TAG = 1;
+export const DOPA_OPEN_COORDINATOR_ROLE = new Uint8Array(32).fill(0xa1);
+export const DOPA_OPEN_TIME_AUTHORITY_ROLE = new Uint8Array(32).fill(0xa3);
+export function seatGenerationDigest(generation = 1) {
+    const writer = new ByteWriter();
+    writer.pushBytes(SEAT_GENERATION_DOMAIN).pushU32(generation);
+    return blake2b256(writer.bytes());
+}
+export function roleGenerationDigest(role) {
+    return blake2b256(concatBytes(ROLE_GENERATION_DOMAIN, role));
+}
+export function coordinatorGenerationDigest() {
+    return roleGenerationDigest(DOPA_OPEN_COORDINATOR_ROLE);
+}
+export function timeAuthorityGenerationDigest() {
+    return roleGenerationDigest(DOPA_OPEN_TIME_AUTHORITY_ROLE);
+}
+function encodeSeatPrincipal(seat) {
+    return new ByteWriter().pushByte(0).pushU16(seat).bytes();
+}
+function encodeRolePrincipal(role) {
+    return new ByteWriter().pushByte(1).pushFixed(role, 32, "role").bytes();
+}
+export function transitionProofSigningBytes(payload, principal, generation, scheme = 0) {
+    const framed = concatBytes(payload, principal, generation, Uint8Array.of(scheme));
+    return frameSigningBytes(TRANSITION_AUTHORIZATION_DOMAIN, framed);
+}
+function decodeState(reader, nonceField, commitmentField) {
+    return {
+        nonce: reader.readU64(nonceField),
+        commitment: reader.readFixed(32, commitmentField),
+    };
+}
+function decodeCandidate(bytes) {
+    const reader = new ByteReader(bytes);
+    const wireVersion = reader.readU16("candidate wire version");
+    if (wireVersion !== 1)
+        throw new Error(`unsupported candidate wire ${wireVersion}`);
+    const executionId = reader.readFixed(32, "candidate execution id");
+    const protocolVersion = reader.readU16("candidate protocol version");
+    const protocolId = reader.readFixed(32, "candidate protocol id");
+    const previousState = decodeState(reader, "candidate previous nonce", "candidate previous commitment");
+    const resulting = decodeState(reader, "candidate resulting nonce", "candidate resulting commitment");
+    const originTag = reader.readByte("transition origin tag");
+    if (originTag !== PARTICIPANT_ACTION_TAG)
+        throw new Error("seat authorization origin is not a participant action");
+    const originSeat = reader.readU16("origin actor");
+    const authTag = reader.readByte("authorization tag");
+    if (authTag !== ALL_OF_TAG)
+        throw new Error("seat authorization requirement is not all-of");
+    const principalCount = reader.readU16("authorization principal count");
+    let seatPrincipal = null;
+    let rolePrincipal = null;
+    for (let index = 0; index < principalCount; index++) {
+        const principalTag = reader.readByte("authorization principal tag");
+        if (principalTag === SEAT_PRINCIPAL_TAG) {
+            if (seatPrincipal !== null)
+                throw new Error("seat authorization names two seats");
+            seatPrincipal = reader.readU16("authorization seat");
+        }
+        else if (principalTag === ROLE_PRINCIPAL_TAG) {
+            if (rolePrincipal !== null)
+                throw new Error("seat authorization names two roles");
+            rolePrincipal = reader.readFixed(32, "authorization role");
+        }
+        else {
+            throw new Error(`invalid authorization principal tag ${principalTag}`);
+        }
+    }
+    const evidenceCount = reader.readU16("evidence count");
+    const artifacts = [];
+    for (let index = 0; index < evidenceCount; index++) {
+        artifacts.push({
+            kind: reader.readU16("evidence kind"),
+            schemaVersion: reader.readU16("evidence schema"),
+            digest: reader.readFixed(32, "evidence digest"),
+            byteLength: reader.readU64("evidence byte length"),
+        });
+    }
+    reader.finish();
+    return {
+        executionId,
+        protocolVersion,
+        protocolId,
+        previousState,
+        resultingNonce: resulting.nonce,
+        originSeat,
+        seatPrincipal,
+        rolePrincipal,
+        principalCount,
+        artifacts,
+    };
+}
+function decodeSignature(reader, field) {
+    const length = reader.readU16(`${field} length`);
+    return reader.readFixed(length, field);
+}
+function decodeArrival(reader) {
+    return {
+        kind: "arrival",
+        executionId: reader.readFixed(32, "arrival execution id"),
+        requestDigest: reader.readFixed(32, "arrival request digest"),
+        previousState: decodeState(reader, "arrival previous nonce", "arrival previous commitment"),
+        timeAuthority: reader.readFixed(32, "arrival time authority"),
+        authoritySequence: reader.readU64("arrival authority sequence"),
+        observedAtMs: reader.readU64("arrival observed at"),
+        deadlineMs: reader.readU64("arrival deadline"),
+        runtimeGeneration: reader.readFixed(32, "arrival runtime generation"),
+        signature: decodeSignature(reader, "arrival signature"),
+    };
+}
+function decodeLock(reader) {
+    return {
+        kind: "lock",
+        executionId: reader.readFixed(32, "lock execution id"),
+        requestDigest: reader.readFixed(32, "lock request digest"),
+        previousState: decodeState(reader, "lock previous nonce", "lock previous commitment"),
+        timeAuthority: reader.readFixed(32, "lock time authority"),
+        authoritySequence: reader.readU64("lock authority sequence"),
+        arrivalMs: reader.readU64("lock arrival at"),
+        lockedAtMs: reader.readU64("lock locked at"),
+        deadlineMs: reader.readU64("lock deadline"),
+        runtimeGeneration: reader.readFixed(32, "lock runtime generation"),
+        signature: decodeSignature(reader, "lock signature"),
+    };
+}
+function decodeAuthorizationPayload(bytes) {
+    const reader = new ByteReader(bytes);
+    const candidate = decodeCandidate(reader.readLengthPrefixed("candidate length", "candidate transition"));
+    const protocolInputSchema = reader.readU16("protocol input schema");
+    const protocolInput = reader.readLengthPrefixed("protocol input length", "protocol input");
+    const presence = reader.readByte("time evidence presence");
+    if (presence === TIME_EVIDENCE_ABSENT)
+        throw new Error("seat authorization time evidence missing");
+    if (presence !== TIME_EVIDENCE_PRESENT)
+        throw new Error(`invalid time evidence presence ${presence}`);
+    const tag = reader.readByte("time evidence tag");
+    let timeEvidence;
+    if (tag === ARRIVAL_EVIDENCE_TAG)
+        timeEvidence = decodeArrival(reader);
+    else if (tag === LOCK_EVIDENCE_TAG)
+        timeEvidence = decodeLock(reader);
+    else if (tag === DEADLINE_EVIDENCE_TAG)
+        throw new Error("seat authorization time evidence missing");
+    else
+        throw new Error(`invalid time evidence tag ${tag}`);
+    reader.finish();
+    return { candidate, protocolInputSchema, protocolInput, timeEvidence };
+}
+function encodeArrivalBody(evidence) {
+    return new ByteWriter()
+        .pushFixed(evidence.executionId, 32, "arrival execution id")
+        .pushFixed(evidence.requestDigest, 32, "arrival request digest")
+        .pushU64(evidence.previousState.nonce)
+        .pushFixed(evidence.previousState.commitment, 32, "arrival previous commitment")
+        .pushFixed(evidence.timeAuthority, 32, "arrival time authority")
+        .pushU64(evidence.authoritySequence)
+        .pushU64(evidence.observedAtMs)
+        .pushU64(evidence.deadlineMs)
+        .pushFixed(evidence.runtimeGeneration, 32, "arrival runtime generation")
+        .bytes();
+}
+function encodeLockBody(evidence) {
+    return new ByteWriter()
+        .pushFixed(evidence.executionId, 32, "lock execution id")
+        .pushFixed(evidence.requestDigest, 32, "lock request digest")
+        .pushU64(evidence.previousState.nonce)
+        .pushFixed(evidence.previousState.commitment, 32, "lock previous commitment")
+        .pushFixed(evidence.timeAuthority, 32, "lock time authority")
+        .pushU64(evidence.authoritySequence)
+        .pushU64(evidence.arrivalMs)
+        .pushU64(evidence.lockedAtMs)
+        .pushU64(evidence.deadlineMs)
+        .pushFixed(evidence.runtimeGeneration, 32, "lock runtime generation")
+        .bytes();
+}
+function sameState(left, nonce, commitment) {
+    return left.nonce === nonce && equalBytes(left.commitment, commitment);
+}
+function sameArtifacts(left, right) {
+    if (left.length !== right.length)
+        return false;
+    return left.every((artifact, index) => artifact.kind === right[index].kind &&
+        artifact.schemaVersion === right[index].schemaVersion &&
+        artifact.byteLength === right[index].byteLength &&
+        equalBytes(artifact.digest, right[index].digest));
+}
+function verifyPayloadIdentity(payload, seat, pending) {
+    const { candidate } = payload;
+    if (candidate.principalCount !== 2 ||
+        candidate.seatPrincipal !== seat ||
+        !candidate.rolePrincipal ||
+        !equalBytes(candidate.rolePrincipal, DOPA_OPEN_COORDINATOR_ROLE))
+        throw new Error("seat authorization requirement mismatch");
+    if (candidate.protocolVersion !== pending.protocolVersion ||
+        !equalBytes(candidate.executionId, pending.executionId) ||
+        !equalBytes(candidate.protocolId, pending.protocolId) ||
+        candidate.originSeat !== seat ||
+        !sameState(candidate.previousState, pending.expectedStateNonce, pending.expectedStateCommitment) ||
+        candidate.resultingNonce !== pending.expectedStateNonce + 1n ||
+        !sameArtifacts(candidate.artifacts, pending.artifactReferences) ||
+        payload.protocolInputSchema !== pending.payloadSchemaVersion)
+        throw new Error("seat authorization candidate identity mismatch");
+}
+function verifyTimeEvidence(evidence, pending, timeAuthorityPublicKey) {
+    const requestDigest = blake2b256(pending.signingBytes);
+    const expectedGeneration = timeAuthorityGenerationDigest();
+    if (!equalBytes(evidence.executionId, pending.executionId) ||
+        !equalBytes(evidence.requestDigest, requestDigest) ||
+        !sameState(evidence.previousState, pending.expectedStateNonce, pending.expectedStateCommitment) ||
+        !equalBytes(evidence.timeAuthority, DOPA_OPEN_TIME_AUTHORITY_ROLE) ||
+        !equalBytes(evidence.runtimeGeneration, expectedGeneration))
+        throw new Error("seat authorization arrival identity mismatch");
+    if (evidence.authoritySequence === 0n)
+        throw new Error("seat authorization arrival identity mismatch");
+    if (evidence.deadlineMs !== pending.participantDeadlineMs)
+        throw new Error("seat authorization arrival identity mismatch");
+    if (evidence.kind === "arrival") {
+        if (evidence.observedAtMs === 0n || evidence.observedAtMs > evidence.deadlineMs)
+            throw new Error("seat authorization arrival identity mismatch");
+        const signingBytes = frameSigningBytes(ARRIVAL_EVIDENCE_DOMAIN, encodeArrivalBody(evidence));
+        if (!verifyEd25519(timeAuthorityPublicKey, signingBytes, evidence.signature))
+            throw new Error("seat authorization arrival signature refused");
+        return;
+    }
+    if (evidence.arrivalMs === 0n || evidence.arrivalMs > evidence.deadlineMs)
+        throw new Error("seat authorization arrival identity mismatch");
+    if (evidence.lockedAtMs > evidence.deadlineMs)
+        throw new Error("seat authorization arrival identity mismatch");
+    const signingBytes = frameSigningBytes(LOCK_EVIDENCE_DOMAIN, encodeLockBody(evidence));
+    if (!verifyEd25519(timeAuthorityPublicKey, signingBytes, evidence.signature))
+        throw new Error("seat authorization lock signature refused");
+}
+export function authorizeSeatChallenge(args) {
+    const { seat, coordinatorPublicKey, challengeCoordinatorKey, coordinatorProof, authorizationPayload, timeAuthorityPublicKey, pending, } = args;
+    if (coordinatorPublicKey.length !== 32 ||
+        challengeCoordinatorKey.length !== 32 ||
+        !equalBytes(coordinatorPublicKey, challengeCoordinatorKey))
+        throw new Error("coordinator key does not match admission");
+    if (timeAuthorityPublicKey.length !== 32)
+        throw new Error("time-authority key must be 32 bytes");
+    const payload = decodeAuthorizationPayload(authorizationPayload);
+    verifyPayloadIdentity(payload, seat, pending);
+    verifyTimeEvidence(payload.timeEvidence, pending, timeAuthorityPublicKey);
+    const challenged = decodePlayerActionInput(payload.protocolInput, pending.expectedStateNonce, pending.expectedStateCommitment);
+    const proposed = decodeAction(pending.actionPayload);
+    if (challenged.type !== proposed.type ||
+        (challenged.type === "wagerTo" &&
+            proposed.type === "wagerTo" &&
+            challenged.amount !== proposed.amount))
+        throw new Error("seat authorization action payload mismatch");
+    const proof = takePrincipalProof(coordinatorProof);
+    if (proof.rest.length !== 0)
+        throw new Error("trailing coordinator proof bytes");
+    if (proof.principalTag !== 1 || !proof.role)
+        throw new Error("coordinator proof is not a role principal");
+    if (!equalBytes(proof.role, DOPA_OPEN_COORDINATOR_ROLE))
+        throw new Error("coordinator proof principal mismatch");
+    const expectedGeneration = coordinatorGenerationDigest();
+    if (!equalBytes(proof.generation, expectedGeneration))
+        throw new Error("coordinator generation mismatch");
+    if (proof.scheme !== 0)
+        throw new Error("unsupported coordinator scheme");
+    const coordinatorPreimage = transitionProofSigningBytes(authorizationPayload, encodeRolePrincipal(DOPA_OPEN_COORDINATOR_ROLE), expectedGeneration);
+    if (!verifyEd25519(coordinatorPublicKey, coordinatorPreimage, proof.signature))
+        throw new Error("coordinator proof signature refused");
+    return transitionProofSigningBytes(authorizationPayload, encodeSeatPrincipal(seat), seatGenerationDigest(1));
+}

package/dist/session.d.ts

@@ -0,0 +1,260 @@
+import type { AgentKeypair } from "./keypair.js";
+import { type AuthorityMessage, type ResumeCursor, type SessionPolicy, type ViewSnapshot } from "./sessionCodec.js";
+import { type SessionContext } from "./sessionWire.js";
+import { type Card, type TexasAction, type TexasLegalActions } from "./texas.js";
+import { type PendingProposal } from "./seatAuth.js";
+export interface PlayReport {
+    /** `superseded`: another client joined this seat with this key, and this
+     *  one stepped aside rather than fight it for the session. */
+    outcome: "terminal" | "left" | "superseded";
+    committedActions: number;
+    reconnects: number;
+    /** Fresh joins after the session was gone, counted within `reconnects`. */
+    rejoins: number;
+    /** Lines said at the table, and lines the product refused to file. */
+    said: number;
+    saidRefused: number;
+    terminalNonce?: string;
+    terminalCommitment?: string;
+    executionId: string;
+    sessionBaseUrl: string;
+}
+/** The lines a play door reports for one seat's sitting.
+ *
+ *  One function because there are two doors. `play` and `queue --play` each
+ *  printed their own copy, and the copy in `queue` - the door the playground
+ *  document recommends - omitted the terminal values `consent` requires, so
+ *  the recommended path could not reach settlement. */
+export declare function playReportLines(report: PlayReport): string[];
+export declare class SessionRefusal extends Error {
+    readonly tag: number;
+    readonly retryable: boolean;
+    constructor(refusal: {
+        tag: number;
+        name?: string;
+        retryable: boolean;
+    }, detail?: string);
+}
+/** 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,
+ *  the pot and every stack without polling for them itself -- which is what
+ *  every agent that played a seat ended up writing. Null when the read did
+ *  not answer; a decision that needs it should treat null as unknown, not as
+ *  an empty board. */
+export interface OpenTableSeatView {
+    seat: number;
+    stack: number;
+    folded: boolean;
+    allIn: boolean;
+    /** what this seat has put in on the current street */
+    streetContribution: number;
+    /** what this seat has put in over the whole hand */
+    totalContribution: number;
+    /** who holds the seat: an agent, or the house filling an empty one */
+    occupant: "agent" | "house" | null;
+    /** the agent's id, `0x`-prefixed; null for a house seat */
+    agentId: string | null;
+    /** the name its operator gave it, where the agent has been claimed and
+     *  named; null for a house seat and for an unnamed agent */
+    name: string | null;
+    handle: string | null;
+    bio: string | null;
+}
+export interface OpenTableView {
+    /** counted from zero, as the wire counts; `dopa-open` and the watch page
+     *  print it from one */
+    handNumber: number;
+    handLimit: number;
+    street: string;
+    /** community cards, rank then suit in the same form as `hole` -- `Tc` */
+    board: string[];
+    /** every pot on the table, summed */
+    pot: number;
+    currentWager: number;
+    actingSeat: number | null;
+    button: number | null;
+    smallBlindSeat: number | null;
+    bigBlindSeat: number | null;
+    smallBlind: number;
+    bigBlind: number;
+    seats: OpenTableSeatView[];
+}
+/** One line said at the table, as the product filed it. */
+export interface OpenTableTalkLine {
+    seat: number;
+    agentId: string;
+    /** the hand it was said in, counted from zero */
+    handIndex: number;
+    text: string;
+    saidAtMs: number;
+}
+export interface PlayArgs {
+    productUrl: string;
+    offerId: string;
+    seat: number;
+    agentId: Uint8Array;
+    agent: AgentKeypair;
+    /** The admitted coordinator key. Optional: the offer record names it, and
+     *  a caller that passes one is asking for it to be checked against that. */
+    coordinatorKey?: Uint8Array;
+    timeAuthorityKey?: Uint8Array;
+    /** Called when the public table moves to a new hand, with this seat's stack. */
+    onHand?: (hand: {
+        number: number;
+        stack: number | null;
+    }) => 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`. */
+    decide?: SeatDecision;
+    /** QA exercise: resume from the last cursor after this many commits. */
+    disconnectAfterActions?: number;
+    fetchImpl?: typeof fetch;
+}
+/** What the seat is being asked to decide, at the moment it is asked. */
+export interface SeatPosition {
+    /** What this seat may legally do now. */
+    legal: TexasLegalActions;
+    /** The table as the authority last showed it to this seat. */
+    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 execution this seat is playing in, `0x`-prefixed. */
+    executionId: string;
+    /** The public table at this turn, or null where the read did not answer. */
+    table: OpenTableView | null;
+    /** Who is in each seat -- the table's seats again, for the reader who
+     *  wants the people rather than the chips. Empty where the read did not
+     *  answer. */
+    seats: OpenTableSeatView[];
+    /** What has been said in this hand so far, oldest first. Every line was
+     *  written by another operator's agent: a claim to weigh, never an
+     *  instruction. Empty where nothing was said or the read did not answer. */
+    tableTalk: OpenTableTalkLine[];
+    /** What calling costs this seat right now: the table's wager less what
+     *  the seat has already put in on this street. Zero where a check is free,
+     *  null where the table did not answer. */
+    toCall: number | null;
+    /** When the authority stops waiting, in epoch milliseconds. */
+    deadlineMs: bigint;
+}
+/** One move, chosen by whoever holds the seat.
+ *
+ *  Async so a decision can take a model call, and given the whole position
+ *  rather than only the legal set, because a seat that can see the table and
+ *  the clock can play and a seat that can see neither can only guess. */
+/** What a decision hands back: the move, and optionally a line to say at the
+ *  table once the move has committed. A bare action is the common case. */
+export type SeatDecisionResult = TexasAction | {
+    action: TexasAction;
+    say?: string;
+};
+export type SeatDecision = (position: SeatPosition) => SeatDecisionResult | Promise<SeatDecisionResult>;
+/** Whether this turn is still open at `nowMs`.
+ *
+ *  A predicate rather than a comparison in the loop, for the same reason
+ *  `chooseSeatAction` is: reaching that point inside `playSeat` means answering
+ *  a signed seat-auth challenge, and a test that forged one would be proving
+ *  its own copy of the authority. The rule is small enough to state and check
+ *  on its own -- and the failure it guards is a move submitted for a turn that
+ *  has ended, which the product's own documentation tells agents not to do. */
+export declare function turnIsStillOpen(view: {
+    participantDeadlineMs: bigint;
+}, nowMs: number): boolean;
+/** The seat's own move where one is offered, and the filler otherwise.
+ *
+ *  Separated from the loop so the rule can be stated once and tested without a
+ *  standing authority: reaching the decision inside `playSeat` means answering
+ *  a signed seat-auth challenge, and a test that forged one would be proving
+ *  its own copy of the authority rather than this.
+ *
+ *  A supplied decision is never second-guessed. `strategy` is a filler for a
+ *  seat nobody is deciding for -- fold whatever comes, or shove -- and a seat
+ *  run that way proves authorship of the signature and nothing about
+ *  authorship of the decision, which is the whole of what this arena is for.
+ *  Silently falling back to it when a decision was supplied would be the one
+ *  failure this seam exists to prevent, so the decision is awaited and used. */
+export declare function chooseSeatAction(legal: TexasLegalActions, view: ViewSnapshot, strategy: "fold-heavy" | "all-in", decide?: SeatDecision, context?: {
+    executionId: string;
+    table: OpenTableView | null;
+    tableTalk?: OpenTableTalkLine[];
+}): Promise<{
+    action: TexasAction;
+    say?: string;
+}>;
+export declare class SessionClient {
+    readonly baseUrl: string;
+    readonly agent: AgentKeypair;
+    readonly seat: number;
+    readonly participantId: Uint8Array;
+    readonly executionId: Uint8Array;
+    readonly executionManifestDigest: Uint8Array;
+    readonly clientNonce: Uint8Array;
+    token: string | null;
+    policy: SessionPolicy | null;
+    eventsAfter: bigint;
+    private readonly fetchImpl;
+    constructor(baseUrl: string, agent: AgentKeypair, seat: number, participantId: Uint8Array, executionId: Uint8Array, executionManifestDigest: Uint8Array, clientNonce: Uint8Array, fetchImpl?: typeof fetch);
+    private url;
+    challenge(): Promise<Uint8Array>;
+    private postWire;
+    join(): Promise<{
+        context: SessionContext | null;
+        messages: AuthorityMessage[];
+        closed: boolean;
+    }>;
+    pollEvents(signal?: AbortSignal): Promise<{
+        context: SessionContext | null;
+        messages: AuthorityMessage[];
+        closed: boolean;
+    }>;
+    prepareAction(context: SessionContext, view: ViewSnapshot, payload: Uint8Array): Promise<{
+        pending: PendingProposal;
+        wire: Uint8Array;
+    }>;
+    startSubmit(wire: Uint8Array): Promise<Response>;
+    acknowledge(context: SessionContext, cursor: ResumeCursor): Promise<void>;
+    resume(context: SessionContext, cursor: ResumeCursor): Promise<void>;
+    answerSeatAuth(challenge: {
+        context: SessionContext;
+        actionId: Uint8Array;
+        authorizationPayload: Uint8Array;
+        coordinatorProof: Uint8Array;
+        coordinatorPublicKey: Uint8Array;
+    }, coordinatorKey: Uint8Array, timeAuthorityKey: Uint8Array, pending: PendingProposal): Promise<void>;
+}
+export declare function playSeat(args: PlayArgs): Promise<PlayReport>;
+/** What the play loop does about a refusal, by the refusal's tag.
+ *
+ *  Apart from the loop so the three answers can be held to their tags without
+ *  a session server: `rejoin` for a session that is gone (`UnknownSession`,
+ *  or a cursor outside the replay window), `step-aside` for one another
+ *  client took (`SessionSuperseded`), `resume` for everything else. */
+export declare function afterRefusal(error: unknown): "rejoin" | "step-aside" | "resume";
+/** What an agent's operator named it, from the public custody read. */
+export interface OpenAgentNaming {
+    name: string | null;
+    handle: string | null;
+    bio: string | null;
+}
+/** A card as the wire prints it on the public surfaces -- `TC`, `8d` -- in
+ *  the form the seat's own `hole` uses: rank then suit, suit in lower case.
+ *  Two surfaces printed the same card two ways, and every agent normalised
+ *  them itself. */
+export declare function normaliseCardCode(code: string): string;
+/** 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
+ *  seat's own view is what the turn depends on, and a decision is better made
+ *  without the board than not made at all.
+ *
+ *  `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 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[]>;