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

package/dist/sessionCodec.d.ts

@@ -10,6 +10,9 @@ export declare const SESSION_TERMINAL_TAG = 12;
 export declare const SESSION_ERROR_TAG = 13;
 export declare const SEAT_AUTHORIZATION_CHALLENGE_TAG = 15;
 export declare const SEAT_AUTHORIZATION_RESPONSE_TAG = 16;
+export declare const PREDICTION_GATE_RELEASED_TAG = 17;
+export declare const PREDICTION_GATE_PREPARED_TAG = 18;
+export declare const PREDICTION_GATE_OPENED_TAG = 19;
 export declare const MAX_TRANSPORT_FRAME_BYTES: number;
 export interface WireEnvelope {
     message: string;
@@ -56,12 +59,80 @@ export interface SeatAuthChallenge {
     coordinatorProof: Uint8Array;
     coordinatorPublicKey: Uint8Array;
 }
+/** ADR-0096's ceiling on added pacing for one next-action prediction window,
+ *  as `arena_session::prediction_gate::MAX_PREDICTION_PACING_MS`. */
+export declare const MAX_PREDICTION_PACING_MS = 25000n;
+/** The in-play window a gate names. The session reuses this identity; it
+ *  never mints a second one. */
+export interface PredictionWindowRef {
+    windowId: bigint;
+    marketId: bigint;
+    /** The only contract kind a gate can hold a seat behind (wire tag 1). */
+    contract: "pokerActionV1";
+}
+/** A durably committed preparation: the frozen window identity, the target
+ *  the acting seat is held on, its original committed deadline, and the
+ *  persisted instant publication started. */
+export interface PredictionGatePreparation {
+    window: PredictionWindowRef;
+    actingSeat: number;
+    state: StateRef;
+    receipt: ReceiptRef | null;
+    originalDeadlineMs: bigint;
+    preparedAtMs: bigint;
+}
+/** Acknowledged publication. `closesAtMs` is the service-committed close
+ *  instant, never the action deadline. */
+export interface PredictionGateOpening {
+    preparation: PredictionGatePreparation;
+    openedAtMs: bigint;
+    closesAtMs: bigint;
+}
+/** The terminal overlay: how the gate closed, and the bounded same-receipt
+ *  deadline it admits. `lockCappedMs` and `participantDeadlineMs` are derived
+ *  the way the shared crate derives them, so a recipient never has to repeat
+ *  the arithmetic to know which later deadline is legal. */
+export interface PredictionGateRelease {
+    window: PredictionWindowRef;
+    actingSeat: number;
+    state: StateRef;
+    receipt: ReceiptRef | null;
+    terminal: "locked" | "cancelled";
+    originalDeadlineMs: bigint;
+    arrivalMs: bigint;
+    lockedAtMs: bigint;
+    lockCappedMs: bigint;
+    budgetMs: bigint;
+    participantDeadlineMs: bigint;
+}
+/** The gate facts a participant retains for one revision. */
+export type PredictionGateStatus = {
+    phase: "prepared";
+    preparation: PredictionGatePreparation;
+} | {
+    phase: "open";
+    opening: PredictionGateOpening;
+} | {
+    phase: "released";
+    release: PredictionGateRelease;
+};
+/** One named lifecycle step, as a value: what the fold below applies. */
+export type PredictionGateMessage = {
+    kind: "prepared";
+    preparation: PredictionGatePreparation;
+} | {
+    kind: "opened";
+    opening: PredictionGateOpening;
+} | {
+    kind: "released";
+    release: PredictionGateRelease;
+};
 export type AuthorityMessage = {
     type: "sessionJoined";
     context: SessionContext;
     sequence: bigint;
     policy: SessionPolicy;
-    view: ViewSnapshot;
+    view: ViewSnapshot | null;
     cursor: ResumeCursor;
 } | {
     type: "participantView";
@@ -97,7 +168,10 @@ export type AuthorityMessage = {
     type: "sessionResumed";
     context: SessionContext;
     sequence: bigint;
-    view: ViewSnapshot;
+    /** The boundary the authority replayed from. It must precede the event
+        itself, or the resume names a suffix it cannot have replayed. */
+    replayFrom: bigint;
+    view: ViewSnapshot | null;
     cursor: ResumeCursor;
 } | {
     type: "sessionTerminal";
@@ -107,6 +181,24 @@ export type AuthorityMessage = {
     finalState: StateRef;
     cursor: ResumeCursor;
     finalReceipt: ReceiptRef | null;
+} | {
+    type: "predictionGatePrepared";
+    context: SessionContext;
+    sequence: bigint;
+    preparation: PredictionGatePreparation;
+    cursor: ResumeCursor;
+} | {
+    type: "predictionGateOpened";
+    context: SessionContext;
+    sequence: bigint;
+    opening: PredictionGateOpening;
+    cursor: ResumeCursor;
+} | {
+    type: "predictionGateReleased";
+    context: SessionContext;
+    sequence: bigint;
+    release: PredictionGateRelease;
+    cursor: ResumeCursor;
 } | {
     type: "error";
     retryable: boolean;
@@ -125,6 +217,19 @@ export declare function sessionErrorName(tag: number): string;
  *  join supersedes the older binding, and the older client's next message
  *  finds its session gone. Both used to read as transport flakiness. */
 export declare function sessionErrorHint(tag: number): string | null;
+export declare function equalStateRef(left: StateRef, right: StateRef): boolean;
+export declare function equalReceiptRef(left: ReceiptRef | null, right: ReceiptRef | null): boolean;
+export declare function equalPredictionGatePreparation(left: PredictionGatePreparation, right: PredictionGatePreparation): boolean;
+export declare function equalPredictionGateRelease(left: PredictionGateRelease, right: PredictionGateRelease): boolean;
+/** The structural refusals of `PredictionGatePreparation::new`, made wherever
+ *  a preparation enters this process - the wire, or a retained seat state. */
+export declare function bindPredictionGatePreparation(fields: PredictionGatePreparation): PredictionGatePreparation;
+/** The structural refusals of `PredictionGateOpening::new`. */
+export declare function bindPredictionGateOpening(fields: PredictionGateOpening): PredictionGateOpening;
+/** The structural refusals of `PredictionGateRelease::new`, with the bounded
+ *  overlay derived here rather than trusted from a sender or a stored file:
+ *  the lock instant capped at the pacing ceiling, plus the budget. */
+export declare function bindPredictionGateRelease(fields: Omit<PredictionGateRelease, "lockCappedMs" | "participantDeadlineMs">): PredictionGateRelease;
 export declare function decodeAuthorityMessage(bytes: Uint8Array): AuthorityMessage;
 export declare function encodeSeatAuthSuccessFrame(context: SessionContext, actionId: Uint8Array, signature: Uint8Array): Uint8Array;
 export declare function extractProtocolInput(payload: Uint8Array): Uint8Array;
@@ -137,3 +242,60 @@ export declare function takePrincipalProof(bytes: Uint8Array): {
     signature: Uint8Array;
     rest: Uint8Array;
 };
+/** A refused phase transition, named as the shared crate names it. */
+export declare class PredictionGateConflictError extends Error {
+    readonly conflict: "PredictionGatePhaseConflict" | "PredictionGateReleaseConflict";
+    constructor(conflict: "PredictionGatePhaseConflict" | "PredictionGateReleaseConflict", detail: string);
+}
+/** The lifecycle step an authority message carries, or null where it carries
+ *  none. The fold takes the value, not the envelope. */
+export declare function predictionGateMessage(message: AuthorityMessage): PredictionGateMessage | null;
+/** The committed preparation behind any phase, or null once released - a
+ *  release carries the identity but not the persisted preparation instant. */
+export declare function predictionGatePreparationOf(status: PredictionGateStatus): PredictionGatePreparation | null;
+/** The receipt the gate targets. A recipient behind it still receives every
+ *  notice, because each notice cursor names that recipient's own floor. */
+export declare function predictionGateTargetReceipt(status: PredictionGateStatus): ReceiptRef | null;
+/** Whether a newly named preparation supersedes the retained facts.
+ *
+ *  Only a released gate can be superseded: a held gate's turn has not closed,
+ *  so a second preparation contradicts it. Once released, the next selected
+ *  turn always targets a later committed state and therefore its own receipt.
+ *  A seat that is itself withheld for that next turn never witnesses the view
+ *  that would otherwise retire the closed gate - which is exactly the second
+ *  window of a hand, held on the seat that was a bystander for the first. A
+ *  preparation naming the same revision is the same-target conflict, not a
+ *  supersession. */
+export declare function predictionGateSupersededByPreparation(status: PredictionGateStatus, nextTurn: PredictionGatePreparation): boolean;
+export declare function applyPredictionGateStatus(current: PredictionGateStatus | null, message: PredictionGateMessage): PredictionGateStatus;
+export interface AcceptedSessionBoundary {
+    context: SessionContext | null;
+    /** The last accepted authority event sequence; zero before the first. */
+    sequence: bigint;
+    receiptFloor: ReceiptRef | null;
+    /** The view last disclosed to this seat, or null while it is withheld. */
+    view: ViewSnapshot | null;
+    predictionGate: PredictionGateStatus | null;
+    /** Whether a viewless admission still owes its named prepared prefix. */
+    awaitingGatePrefix: boolean;
+}
+/** A refused event, named as `SessionSemanticError` names it. */
+export declare class SessionBoundaryError extends Error {
+    readonly reason: string;
+    constructor(reason: string, detail: string);
+}
+/** The boundary a seat that has accepted nothing holds. */
+export declare function freshSessionBoundary(): AcceptedSessionBoundary;
+/** What the seam did with an event.
+ *
+ *  `applied` is the only disposition that moved the boundary, and so the only
+ *  one a consumer may act on: a re-delivery was applied and acknowledged once
+ *  already, and acting on it a second time would decide a turn that is over,
+ *  count a commit twice, or walk the acknowledged cursor backwards. */
+export type AuthorityEventDisposition = "applied" | "replay" | "boundaryless";
+export interface AdmittedAuthorityEvent {
+    disposition: AuthorityEventDisposition;
+    /** The boundary to retain. Unchanged unless the event was applied. */
+    boundary: AcceptedSessionBoundary;
+}
+export declare function admitAuthorityEvent(accepted: AcceptedSessionBoundary, message: AuthorityMessage): AdmittedAuthorityEvent;