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

package/dist/sessionCodec.js

@@ -4,9 +4,11 @@
  * appends the signature. Authority messages are decoded just far enough for
  * the seat loop: views, commits, terminal, errors, and seat-auth challenges.
  */
-import { ByteReader, ByteWriter } from "./bytes.js";
+import { ByteReader, ByteWriter, equalBytes } from "./bytes.js";
 import { encodeContext, requireSessionVersion, } from "./sessionWire.js";
 const AUTHORITY_EVENT_ACKNOWLEDGEMENT_TAG = 0x09;
+/** The only wire contract this build frames and decodes. */
+const CANONICAL_WIRE_VERSION = 1;
 export const SESSION_JOINED_TAG = 0x02;
 export const PARTICIPANT_VIEW_TAG = 0x03;
 export const ACTION_ACKNOWLEDGED_TAG = 0x05;
@@ -19,6 +21,8 @@ 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 PREDICTION_GATE_PREPARED_TAG = 0x12;
+export const PREDICTION_GATE_OPENED_TAG = 0x13;
 export const MAX_TRANSPORT_FRAME_BYTES = 1 << 20;
 export function encodeAckFrame(context, cursor) {
     const sequence = typeof cursor === "object" ? cursor.sequence : cursor;
@@ -51,6 +55,10 @@ export function decodeEnvelope(envelope) {
         throw new Error("session frame exceeds transport ceiling");
     return new Uint8Array(wire);
 }
+/** ADR-0096's ceiling on added pacing for one next-action prediction window,
+ *  as `arena_session::prediction_gate::MAX_PREDICTION_PACING_MS`. */
+export const MAX_PREDICTION_PACING_MS = 25000n;
+const U64_MAX = (1n << 64n) - 1n;
 /* The authority's session-protocol error tags, by name.
  *
  * `arena-session/src/wire.rs` numbers `SessionProtocolError` on the wire and
@@ -148,6 +156,13 @@ function readView(reader) {
     const legal = readPayload(reader, "legal action schema byte length", "legal action schema bytes");
     const participantDeadlineMs = reader.readU64("participant deadline milliseconds");
     const latestReceipt = readOption(reader, "latest receipt option", () => readReceipt(reader));
+    /* `ParticipantViewSnapshot::new` refuses a receipt whose resulting state is
+       not the state the view is on, and Rust decodes through that constructor.
+       Skipping it here accepts a view whose own commitment and receipt disagree
+       -- which is exactly what a mutated frame looks like, and what a seat would
+       then answer a turn on. */
+    if (latestReceipt && !equalStateRef(latestReceipt.resultingState, state))
+        throw new Error("view receipt does not result in the state the view is on");
     return {
         state,
         participantView: participantView.bytes,
@@ -158,6 +173,156 @@ function readView(reader) {
         latestReceipt,
     };
 }
+/** `validate_authority_event`'s view rule: an event that carries a view names
+ *  that view's own receipt in its cursor. The two are one fact, and a frame
+ *  where they disagree describes a receipt floor no session ever held. */
+function requireViewCursor(view, cursor) {
+    if (!equalReceiptRef(cursor.witnessedReceipt, view.latestReceipt))
+        throw new Error("the event cursor does not name the receipt its view is on");
+}
+/* ── The prediction-gate lifecycle values ────────────────────────────────
+ *
+ * Byte-for-byte the layouts in `arena_session::wire`:
+ * `encode_prediction_gate_preparation`, `_opening` and `_release`. Every
+ * structural refusal the Rust constructors make is made here, so a frame this
+ * side accepts is one the shared crate would also accept — a permissive
+ * client would hand a seat a window identity the authority never committed. */
+export function equalStateRef(left, right) {
+    return (left.nonce === right.nonce && equalBytes(left.commitment, right.commitment));
+}
+export function equalReceiptRef(left, right) {
+    if (left === null || right === null)
+        return left === right;
+    return (equalBytes(left.digest, right.digest) &&
+        equalStateRef(left.resultingState, right.resultingState));
+}
+export function equalPredictionGatePreparation(left, right) {
+    return (left.window.windowId === right.window.windowId &&
+        left.window.marketId === right.window.marketId &&
+        left.window.contract === right.window.contract &&
+        left.actingSeat === right.actingSeat &&
+        equalStateRef(left.state, right.state) &&
+        equalReceiptRef(left.receipt, right.receipt) &&
+        left.originalDeadlineMs === right.originalDeadlineMs &&
+        left.preparedAtMs === right.preparedAtMs);
+}
+export function equalPredictionGateRelease(left, right) {
+    return (left.window.windowId === right.window.windowId &&
+        left.window.marketId === right.window.marketId &&
+        left.window.contract === right.window.contract &&
+        left.actingSeat === right.actingSeat &&
+        equalStateRef(left.state, right.state) &&
+        equalReceiptRef(left.receipt, right.receipt) &&
+        left.terminal === right.terminal &&
+        left.originalDeadlineMs === right.originalDeadlineMs &&
+        left.arrivalMs === right.arrivalMs &&
+        left.lockedAtMs === right.lockedAtMs &&
+        left.budgetMs === right.budgetMs);
+}
+function readPredictionWindow(reader) {
+    const windowId = reader.readU64("prediction window id");
+    const marketId = reader.readU64("prediction market id");
+    const tag = reader.readByte("prediction window contract");
+    if (tag !== 1)
+        throw new Error(`invalid prediction window contract tag ${tag}`);
+    if (windowId === 0n || marketId === 0n)
+        throw new Error("prediction window names neither a window nor a market");
+    return { windowId, marketId, contract: "pokerActionV1" };
+}
+function readPredictionGatePreparation(reader) {
+    const window = readPredictionWindow(reader);
+    const actingSeat = reader.readU16("prediction gate acting seat");
+    const state = readState(reader, "prediction gate state nonce", "prediction gate state commitment");
+    const receipt = readOption(reader, "prediction gate receipt option", () => readReceipt(reader));
+    const originalDeadlineMs = reader.readU64("original participant deadline milliseconds");
+    const preparedAtMs = reader.readU64("prediction gate prepared-at milliseconds");
+    return bindPredictionGatePreparation({
+        window,
+        actingSeat,
+        state,
+        receipt,
+        originalDeadlineMs,
+        preparedAtMs,
+    });
+}
+/** The structural refusals of `PredictionGatePreparation::new`, made wherever
+ *  a preparation enters this process - the wire, or a retained seat state. */
+export function bindPredictionGatePreparation(fields) {
+    if (fields.window.windowId === 0n || fields.window.marketId === 0n)
+        throw new Error("prediction window names neither a window nor a market");
+    if (fields.originalDeadlineMs === 0n)
+        throw new Error("prediction gate preparation has no original deadline");
+    if (fields.preparedAtMs === 0n)
+        throw new Error("prediction gate preparation has no persisted instant");
+    if (fields.receipt &&
+        !equalStateRef(fields.receipt.resultingState, fields.state))
+        throw new Error("prediction gate preparation receipt does not result in its target state");
+    return fields;
+}
+function readPredictionGateOpening(reader) {
+    const preparation = readPredictionGatePreparation(reader);
+    const openedAtMs = reader.readU64("prediction gate opened-at milliseconds");
+    const closesAtMs = reader.readU64("prediction gate closes-at milliseconds");
+    return bindPredictionGateOpening({ preparation, openedAtMs, closesAtMs });
+}
+/** The structural refusals of `PredictionGateOpening::new`. */
+export function bindPredictionGateOpening(fields) {
+    bindPredictionGatePreparation(fields.preparation);
+    if (fields.openedAtMs === 0n)
+        throw new Error("prediction gate opening has no publication instant");
+    if (fields.openedAtMs < fields.preparation.preparedAtMs)
+        throw new Error("prediction gate opened before it was prepared");
+    if (fields.closesAtMs <= fields.openedAtMs)
+        throw new Error("prediction gate closes at or before it opened");
+    return fields;
+}
+function readPredictionGateRelease(reader) {
+    const window = readPredictionWindow(reader);
+    const actingSeat = reader.readU16("prediction gate acting seat");
+    const state = readState(reader, "prediction gate state nonce", "prediction gate state commitment");
+    const receipt = readOption(reader, "prediction gate receipt option", () => readReceipt(reader));
+    const terminalTag = reader.readByte("prediction gate terminal");
+    if (terminalTag !== 1 && terminalTag !== 2)
+        throw new Error(`invalid prediction gate terminal tag ${terminalTag}`);
+    const originalDeadlineMs = reader.readU64("original participant deadline milliseconds");
+    const arrivalMs = reader.readU64("prediction gate arrival milliseconds");
+    const lockedAtMs = reader.readU64("prediction gate locked-at milliseconds");
+    const budgetMs = reader.readU64("participant deadline budget milliseconds");
+    return bindPredictionGateRelease({
+        window,
+        actingSeat,
+        state,
+        receipt,
+        terminal: terminalTag === 1 ? "locked" : "cancelled",
+        originalDeadlineMs,
+        arrivalMs,
+        lockedAtMs,
+        budgetMs,
+    });
+}
+/** 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 function bindPredictionGateRelease(fields) {
+    if (fields.window.windowId === 0n || fields.window.marketId === 0n)
+        throw new Error("prediction window names neither a window nor a market");
+    if (fields.arrivalMs === 0n)
+        throw new Error("prediction gate release has no arrival instant");
+    if (fields.lockedAtMs < fields.arrivalMs)
+        throw new Error("prediction gate closed before the overlay arrived");
+    if (fields.budgetMs === 0n)
+        throw new Error("prediction gate release has no deadline budget");
+    if (fields.receipt &&
+        !equalStateRef(fields.receipt.resultingState, fields.state))
+        throw new Error("prediction gate release receipt does not result in its target state");
+    const uncapped = fields.arrivalMs + MAX_PREDICTION_PACING_MS;
+    const ceiling = uncapped > U64_MAX ? U64_MAX : uncapped;
+    const lockCappedMs = fields.lockedAtMs < ceiling ? fields.lockedAtMs : ceiling;
+    const participantDeadlineMs = lockCappedMs + fields.budgetMs;
+    if (participantDeadlineMs > U64_MAX)
+        throw new Error("prediction gate overlay deadline exceeds u64");
+    return { ...fields, lockCappedMs, participantDeadlineMs };
+}
 function readPolicy(reader) {
     return {
         maxParticipantViewBytes: reader.readU64("maximum participant view bytes"),
@@ -186,12 +351,28 @@ function skipAuthorization(reader) {
             throw new Error(`invalid authorization principal tag ${principalTag}`);
     }
 }
+/* `ActionRejection::retry_disposition` by wire tag: every rejection has one
+   canonical answer, and `validate_authority_event` refuses a frame that names
+   another. Without this a "retry later" byte on an unauthorised key reads as
+   a transient failure and a seat resubmits into a permanent refusal. */
+const REJECTION_RETRY = [
+    /* ProtocolRejected */ 0, /* StaleState */ 2, /* UnauthorizedSeatOrKey */ 0,
+    /* DeadlineExpired */ 2, /* ActionIdentityConflict */ 0,
+    /* ConflictingAlreadyCommitted */ 2, /* UnsupportedSchema */ 0,
+    /* MalformedState */ 0, /* MalformedInput */ 0, /* WrongOrigin */ 0,
+    /* WrongActor */ 0, /* TerminalState */ 0, /* DeadlineMismatch */ 2,
+    /* InvalidTimeEvidence */ 0,
+];
+/** The rejection and the retry disposition that must accompany it. */
 function readActionRejection(reader) {
     const tag = reader.readByte("action rejection tag");
+    if (tag >= REJECTION_RETRY.length)
+        throw new Error(`invalid action rejection tag ${tag}`);
     if (tag === 0 || tag === 6)
         reader.readU16("action rejection extra");
-    if (tag > 13)
-        throw new Error(`invalid action rejection tag ${tag}`);
+    const retry = reader.readByte("retry disposition");
+    if (retry !== REJECTION_RETRY[tag])
+        throw new Error(`action rejection ${tag} names retry disposition ${retry}, not ${REJECTION_RETRY[tag]}`);
 }
 function readSeatAuthChallenge(reader, wireVersion) {
     const context = readContext(reader, wireVersion);
@@ -212,6 +393,10 @@ function readSeatAuthChallenge(reader, wireVersion) {
 export function decodeAuthorityMessage(bytes) {
     const reader = new ByteReader(bytes);
     const wireVersion = reader.readU16("wire version");
+    /* The envelope names the wire contract it was framed under, and this build
+       speaks exactly one. Rust refuses any other value at the same point. */
+    if (wireVersion !== CANONICAL_WIRE_VERSION)
+        throw new Error(`unsupported wire version ${wireVersion}, expected ${CANONICAL_WIRE_VERSION}`);
     const tag = reader.readByte("message tag");
     if (tag === SESSION_ERROR_TAG) {
         // A present selected version is the authority's answer for this session,
@@ -247,8 +432,12 @@ export function decodeAuthorityMessage(bytes) {
     switch (tag) {
         case SESSION_JOINED_TAG: {
             const policy = readPolicy(reader);
-            const view = readView(reader);
+            /* Option-tagged: a seat held behind a committed gate is admitted with
+               no private view, and the tag is the only thing that says so. */
+            const view = readOption(reader, "joined view option", () => readView(reader));
             const cursor = readCursor(reader);
+            if (view)
+                requireViewCursor(view, cursor);
             message = {
                 type: "sessionJoined",
                 context,
@@ -262,6 +451,7 @@ export function decodeAuthorityMessage(bytes) {
         case PARTICIPANT_VIEW_TAG: {
             const view = readView(reader);
             const cursor = readCursor(reader);
+            requireViewCursor(view, cursor);
             message = { type: "participantView", context, sequence, view, cursor };
             break;
         }
@@ -281,9 +471,9 @@ export function decodeAuthorityMessage(bytes) {
         case ACTION_REJECTED_TAG: {
             const actionId = reader.readFixed(32, "action id");
             readActionRejection(reader);
-            reader.readByte("retry disposition");
             const view = readView(reader);
             const cursor = readCursor(reader);
+            requireViewCursor(view, cursor);
             message = {
                 type: "actionRejected",
                 context,
@@ -299,6 +489,11 @@ export function decodeAuthorityMessage(bytes) {
             const receipt = readReceipt(reader);
             const view = readView(reader);
             const cursor = readCursor(reader);
+            /* A commit is the receipt its own view is on: the pair is one committed
+               fact, not two the recipient has to reconcile. */
+            if (!equalReceiptRef(view.latestReceipt, receipt))
+                throw new Error("the commit receipt is not the receipt its view is on");
+            requireViewCursor(view, cursor);
             message = {
                 type: "actionCommitted",
                 context,
@@ -311,10 +506,19 @@ export function decodeAuthorityMessage(bytes) {
             break;
         }
         case SESSION_RESUMED_TAG: {
-            reader.readU64("replay from sequence");
-            const view = readView(reader);
+            const replayFrom = reader.readU64("replay from sequence");
+            const view = readOption(reader, "resumed view option", () => readView(reader));
             const cursor = readCursor(reader);
-            message = { type: "sessionResumed", context, sequence, view, cursor };
+            if (view)
+                requireViewCursor(view, cursor);
+            message = {
+                type: "sessionResumed",
+                context,
+                sequence,
+                replayFrom,
+                view,
+                cursor,
+            };
             break;
         }
         case SESSION_TERMINAL_TAG: {
@@ -322,6 +526,11 @@ export function decodeAuthorityMessage(bytes) {
             const finalState = readState(reader, "final state nonce", "final state commitment");
             const finalReceipt = readOption(reader, "final receipt option", () => readReceipt(reader));
             const cursor = readCursor(reader);
+            if (finalReceipt &&
+                !equalStateRef(finalReceipt.resultingState, finalState))
+                throw new Error("the terminal receipt does not result in its final state");
+            if (!equalReceiptRef(cursor.witnessedReceipt, finalReceipt))
+                throw new Error("the terminal cursor does not name the final receipt");
             message = {
                 type: "sessionTerminal",
                 context,
@@ -333,23 +542,38 @@ export function decodeAuthorityMessage(bytes) {
             };
             break;
         }
+        case PREDICTION_GATE_PREPARED_TAG: {
+            const preparation = readPredictionGatePreparation(reader);
+            const cursor = readCursor(reader);
+            message = {
+                type: "predictionGatePrepared",
+                context,
+                sequence,
+                preparation,
+                cursor,
+            };
+            break;
+        }
+        case PREDICTION_GATE_OPENED_TAG: {
+            const opening = readPredictionGateOpening(reader);
+            const cursor = readCursor(reader);
+            message = {
+                type: "predictionGateOpened",
+                context,
+                sequence,
+                opening,
+                cursor,
+            };
+            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 release = readPredictionGateRelease(reader);
             const cursor = readCursor(reader);
             message = {
                 type: "predictionGateReleased",
                 context,
                 sequence,
+                release,
                 cursor,
             };
             break;
@@ -402,3 +626,402 @@ export function takePrincipalProof(bytes) {
         rest: bytes.slice(reader.consumed()),
     };
 }
+/* ── The named gate lifecycle, as a recipient folds it ───────────────────
+ *
+ * One fold, shared by both consumer loops. The rules are
+ * `arena_session::semantics::{validate_gate_preparation, validate_gate_opening,
+ * validate_gate_release}`: a preparation opens a revision's gate and never
+ * replaces a retained one, an opening must carry the exact stored preparation,
+ * and a release closes a prepared gate only by cancelling it. Writing these
+ * twice - once in `playSeat` and once in `openTurn` - is how the two doors
+ * would come to disagree about which phase a seat is in. */
+/** A refused phase transition, named as the shared crate names it. */
+export class PredictionGateConflictError extends Error {
+    conflict;
+    constructor(conflict, detail) {
+        super(`${conflict}: ${detail}`);
+        this.conflict = conflict;
+        this.name = "PredictionGateConflictError";
+    }
+}
+/** The lifecycle step an authority message carries, or null where it carries
+ *  none. The fold takes the value, not the envelope. */
+export function predictionGateMessage(message) {
+    switch (message.type) {
+        case "predictionGatePrepared":
+            return { kind: "prepared", preparation: message.preparation };
+        case "predictionGateOpened":
+            return { kind: "opened", opening: message.opening };
+        case "predictionGateReleased":
+            return { kind: "released", release: message.release };
+        default:
+            return null;
+    }
+}
+/** The committed preparation behind any phase, or null once released - a
+ *  release carries the identity but not the persisted preparation instant. */
+export function predictionGatePreparationOf(status) {
+    switch (status.phase) {
+        case "prepared":
+            return status.preparation;
+        case "open":
+            return status.opening.preparation;
+        case "released":
+            return 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 function predictionGateTargetReceipt(status) {
+    switch (status.phase) {
+        case "prepared":
+            return status.preparation.receipt;
+        case "open":
+            return status.opening.preparation.receipt;
+        case "released":
+            return status.release.receipt;
+    }
+}
+/** 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 function predictionGateSupersededByPreparation(status, nextTurn) {
+    if (status.phase !== "released")
+        return false;
+    return (nextTurn.state.nonce > status.release.state.nonce &&
+        !equalReceiptRef(nextTurn.receipt, status.release.receipt));
+}
+export function applyPredictionGateStatus(current, message) {
+    switch (message.kind) {
+        case "prepared":
+            if (current !== null &&
+                !predictionGateSupersededByPreparation(current, message.preparation))
+                throw new PredictionGateConflictError("PredictionGatePhaseConflict", "a preparation arrived while this revision still retains a gate");
+            return { phase: "prepared", preparation: message.preparation };
+        case "opened":
+            if (current?.phase !== "prepared" ||
+                !equalPredictionGatePreparation(current.preparation, message.opening.preparation))
+                throw new PredictionGateConflictError("PredictionGatePhaseConflict", "an opening must carry the exact durably prepared window");
+            return { phase: "open", opening: message.opening };
+        case "released": {
+            const release = message.release;
+            if (current === null)
+                throw new PredictionGateConflictError("PredictionGatePhaseConflict", "a release closes no retained gate");
+            if (current.phase === "released") {
+                /* A replayed release is the same overlay again; a different one would
+                   be a second budget for one revision. */
+                if (!equalPredictionGateRelease(current.release, release))
+                    throw new PredictionGateConflictError("PredictionGateReleaseConflict", "a second release for one revision");
+                return current;
+            }
+            const preparation = current.phase === "prepared"
+                ? current.preparation
+                : current.opening.preparation;
+            const identical = release.window.windowId === preparation.window.windowId &&
+                release.window.marketId === preparation.window.marketId &&
+                release.window.contract === preparation.window.contract &&
+                release.actingSeat === preparation.actingSeat &&
+                equalStateRef(release.state, preparation.state) &&
+                equalReceiptRef(release.receipt, preparation.receipt) &&
+                release.originalDeadlineMs === preparation.originalDeadlineMs;
+            if (!identical)
+                throw new PredictionGateConflictError("PredictionGatePhaseConflict", "the release names another window than the retained gate");
+            if (current.phase === "prepared" && release.terminal !== "cancelled")
+                throw new PredictionGateConflictError("PredictionGatePhaseConflict", "a gate that never opened can only close by cancellation");
+            return { phase: "released", release };
+        }
+    }
+}
+/** A refused event, named as `SessionSemanticError` names it. */
+export class SessionBoundaryError extends Error {
+    reason;
+    constructor(reason, detail) {
+        super(`${reason}: ${detail}`);
+        this.reason = reason;
+        this.name = "SessionBoundaryError";
+    }
+}
+/** The boundary a seat that has accepted nothing holds. */
+export function freshSessionBoundary() {
+    return {
+        context: null,
+        sequence: 0n,
+        receiptFloor: null,
+        view: null,
+        predictionGate: null,
+        awaitingGatePrefix: false,
+    };
+}
+function equalContext(left, right) {
+    return (left.wireVersion === right.wireVersion &&
+        left.sessionVersion === right.sessionVersion &&
+        equalBytes(left.sessionId, right.sessionId) &&
+        equalBytes(left.executionId, right.executionId) &&
+        equalBytes(left.executionManifestDigest, right.executionManifestDigest) &&
+        equalBytes(left.protocolId, right.protocolId) &&
+        left.protocolVersion === right.protocolVersion &&
+        equalBytes(left.participantId, right.participantId) &&
+        left.seat === right.seat);
+}
+/** While the gate holds this session's acting seat, the withheld private view
+ *  cannot arrive - whether the event carrying it is new or a re-delivery. A
+ *  bystander's own view of the same receipt is ordinary, so only the acting
+ *  seat is refused. */
+function refuseHeldActingView(accepted, view) {
+    const gate = accepted.predictionGate;
+    if (gate === null || gate.phase === "released")
+        return;
+    if (!equalReceiptRef(predictionGateTargetReceipt(gate), view.latestReceipt))
+        return;
+    if (predictionGatePreparationOf(gate)?.actingSeat !== accepted.context?.seat)
+        return;
+    throw new SessionBoundaryError("PredictionGatePhaseConflict", "a held acting seat cannot be shown the gated view");
+}
+/** A view this seat may be shown, and what it does to the retained gate.
+ *
+ *  The refusals are the two a held seat depends on: the withheld private view
+ *  cannot arrive while this seat's own turn is gated, and a later deadline on
+ *  an unchanged receipt is legal only under the admitted overlay. */
+function admitView(accepted, view) {
+    const gate = accepted.predictionGate;
+    refuseHeldActingView(accepted, view);
+    if (accepted.view &&
+        equalReceiptRef(view.latestReceipt, accepted.receiptFloor) &&
+        view.participantDeadlineMs !== accepted.view.participantDeadlineMs) {
+        const release = gate?.phase === "released" ? gate.release : null;
+        const admitted = release !== null &&
+            equalReceiptRef(release.receipt, view.latestReceipt) &&
+            equalStateRef(release.state, view.state) &&
+            release.participantDeadlineMs === view.participantDeadlineMs &&
+            release.originalDeadlineMs === accepted.view.participantDeadlineMs;
+        if (!admitted)
+            throw new SessionBoundaryError("DeadlineChangesWithoutTransition", `${accepted.view.participantDeadlineMs} to ${view.participantDeadlineMs} with no admitted overlay`);
+    }
+    if (!view.latestReceipt)
+        return { receiptFloor: accepted.receiptFloor, predictionGate: gate };
+    /* A view on a later receipt than the gate targeted leaves the gate facts
+       obsolete; one on the gated receipt keeps the release identity, so a second
+       release for the same revision is still refused. */
+    const superseded = !equalReceiptRef(accepted.receiptFloor, view.latestReceipt) &&
+        gate !== null &&
+        !equalReceiptRef(predictionGateTargetReceipt(gate), view.latestReceipt);
+    return {
+        receiptFloor: view.latestReceipt,
+        predictionGate: superseded ? null : gate,
+    };
+}
+/** Where a preparation may target: the receipt this recipient has witnessed,
+ *  or the immediate next committed one for an actor still behind it. */
+function admitGatePreparation(accepted, preparation) {
+    const view = accepted.view;
+    if (view) {
+        if (equalReceiptRef(preparation.receipt, view.latestReceipt)) {
+            if (!equalStateRef(view.state, preparation.state))
+                throw new SessionBoundaryError("CommittedStateWithoutReceipt", "the preparation targets another state on the witnessed receipt");
+            if (view.participantDeadlineMs !== preparation.originalDeadlineMs)
+                throw new SessionBoundaryError("DeadlineChangesWithoutTransition", "the preparation names another original deadline than the open turn");
+            return;
+        }
+        if (preparation.state.nonce !== view.state.nonce + 1n)
+            throw new SessionBoundaryError("NonSequentialCommittedState", `the preparation targets nonce ${preparation.state.nonce} after ${view.state.nonce}`);
+        return;
+    }
+    if (equalReceiptRef(preparation.receipt, accepted.receiptFloor))
+        return;
+    const floorNonce = accepted.receiptFloor?.resultingState.nonce;
+    if (floorNonce !== undefined && floorNonce + 1n === preparation.state.nonce)
+        return;
+    throw new SessionBoundaryError("PredictionGatePhaseConflict", "the preparation targets neither the retained floor nor the receipt after it");
+}
+/** A re-delivered event moves nothing, but it is not unexamined.
+ *
+ *  `ParticipantSessionState::apply_event` compares a re-delivery against the
+ *  event it recorded at that sequence and refuses any disagreement. This
+ *  boundary keeps facts rather than the event log, so the comparison is
+ *  against those facts: the session it names, the receipt floor it claims,
+ *  and the withheld view it must not carry. Skipping the comparison is how a
+ *  foreign-context event or the gated view of a held seat used to arrive
+ *  unchecked at a consumer that then acted on it. */
+function admitReplay(accepted, message) {
+    const conflict = (detail) => {
+        throw new SessionBoundaryError("SequenceConflict", `${detail} at re-delivered event ${message.sequence}`);
+    };
+    if (message.type === "sessionJoined" && message.sequence !== 1n)
+        conflict("a join outside sequence 1");
+    /* Nothing follows a terminal, so the only terminal a boundary can be handed
+       again is its own last event - the one a resume at the terminal cursor
+       re-delivers. An older sequence claiming to be terminal contradicts every
+       event this seat applied after it. */
+    if (message.type === "sessionTerminal" &&
+        message.sequence !== accepted.sequence)
+        conflict("a terminal before the boundary's own last event");
+    const view = "view" in message ? message.view : null;
+    if (view)
+        refuseHeldActingView(accepted, view);
+    const named = message.cursor.witnessedReceipt;
+    if (!named)
+        return;
+    const floor = accepted.receiptFloor;
+    /* History cannot name a receipt this seat has not witnessed: every event at
+       or below the boundary projected a floor the boundary already passed. */
+    if (!floor)
+        conflict("a receipt where the boundary has witnessed none");
+    else if (named.resultingState.nonce > floor.resultingState.nonce)
+        conflict(`receipt nonce ${named.resultingState.nonce} past the floor`);
+    else if (named.resultingState.nonce === floor.resultingState.nonce &&
+        !equalReceiptRef(named, floor))
+        conflict("another receipt for the floor's own state");
+}
+export function admitAuthorityEvent(accepted, message) {
+    /* Acknowledgements, pendings, errors and challenges carry no cursor: they
+       move no boundary and are not acknowledged. */
+    if (!("cursor" in message))
+        return { disposition: "boundaryless", boundary: accepted };
+    const { context, sequence, cursor } = message;
+    if (cursor.sequence !== sequence)
+        throw new SessionBoundaryError("EventCursorMismatch", `event ${sequence} carries cursor ${cursor.sequence}`);
+    /* A resume names the boundary it replayed from, which must precede it. */
+    if (message.type === "sessionResumed" &&
+        message.replayFrom >= message.sequence)
+        throw new SessionBoundaryError("ReplayFromAhead", `the resume replayed from ${message.replayFrom} at event ${message.sequence}`);
+    /* A join is an admission only against a boundary that has applied nothing.
+       A consumer that joins again hands this seam a fresh boundary, because a
+       join is a new session and nothing retained for the old one describes it;
+       a `SessionJoined` arriving on an established boundary is therefore never
+       an admission, and cannot be used to reset the phase a held seat holds or
+       the floor it witnessed. */
+    const admission = message.type === "sessionJoined" && accepted.sequence === 0n;
+    if (admission) {
+        if (sequence !== 1n)
+            throw new SessionBoundaryError("ExpectedSequenceOne", `the join opens the session at sequence 1, not ${sequence}`);
+        /* A consumer that has already been handed a context - by the very join
+           this event reports - is admitted into that session and no other. */
+        if (accepted.context && !equalContext(accepted.context, context))
+            throw new SessionBoundaryError("ContextMismatch", "the join names another session than the one this boundary opened");
+    }
+    else {
+        /* Before anything is applied the protocol admits exactly one shape: the
+           join at sequence 1. Anything else would process a view or a notice
+           against no session at all. */
+        if (accepted.sequence === 0n || !accepted.context)
+            throw new SessionBoundaryError("ExpectedJoin", `a session opens with its own join, not ${message.type}`);
+        if (!equalContext(accepted.context, context))
+            throw new SessionBoundaryError("ContextMismatch", "the event names another session than the accepted one");
+        if (sequence <= accepted.sequence) {
+            admitReplay(accepted, message);
+            return { disposition: "replay", boundary: accepted };
+        }
+        if (sequence !== accepted.sequence + 1n)
+            throw new SessionBoundaryError("EventGap", `expected ${accepted.sequence + 1n}, got ${sequence}`);
+        if (message.type === "sessionJoined")
+            throw new SessionBoundaryError("UnexpectedJoin", "an established session cannot be joined again");
+    }
+    /* A fresh join is a new session: nothing retained for the previous one
+       describes it, so obsolete context state is dropped rather than carried. */
+    const base = admission
+        ? { ...freshSessionBoundary(), context }
+        : { ...accepted, context };
+    const gateMessage = predictionGateMessage(message);
+    const viewlessResume = message.type === "sessionResumed" && message.view === null;
+    if (base.awaitingGatePrefix &&
+        gateMessage?.kind !== "prepared" &&
+        !viewlessResume)
+        /* The primed prefix: after a viewless admission the next durable event is
+           the matching preparation. A view, an opening or a release before it
+           would either disclose the withheld view or skip a held phase. */
+        throw new SessionBoundaryError("PredictionGatePhaseConflict", "the named prepared prefix must arrive before anything else");
+    let receiptFloor = base.receiptFloor;
+    let view = base.view;
+    let predictionGate = base.predictionGate;
+    let awaitingGatePrefix = base.awaitingGatePrefix;
+    let projected;
+    switch (message.type) {
+        case "sessionJoined":
+        case "sessionResumed":
+            if (message.view) {
+                ({ receiptFloor, predictionGate } = admitView(base, message.view));
+                view = message.view;
+                projected = message.view.latestReceipt;
+            }
+            else if (message.type === "sessionJoined") {
+                /* A held seat's admission cursor names the receipt floor; only a later
+                   real view may advance it. */
+                receiptFloor = cursor.witnessedReceipt;
+                view = null;
+                awaitingGatePrefix = true;
+                projected = cursor.witnessedReceipt;
+            }
+            else {
+                /* A viewless reattach repeats the retained floor and still owes the
+                   prefix it has not been shown. */
+                awaitingGatePrefix = awaitingGatePrefix || predictionGate === null;
+                projected = receiptFloor;
+            }
+            break;
+        case "participantView":
+            ({ receiptFloor, predictionGate } = admitView(base, message.view));
+            view = message.view;
+            projected = message.view.latestReceipt;
+            break;
+        case "actionRejected":
+            if (!equalReceiptRef(message.view.latestReceipt, receiptFloor))
+                throw new SessionBoundaryError("RejectedEventAdvancesReceipt", "a rejection cannot advance the receipt it was rejected on");
+            ({ receiptFloor, predictionGate } = admitView(base, message.view));
+            view = message.view;
+            projected = receiptFloor;
+            break;
+        case "actionCommitted":
+            if (equalReceiptRef(message.receipt, receiptFloor))
+                throw new SessionBoundaryError("CommitDoesNotAdvanceReceipt", "a commit must advance the witnessed receipt");
+            ({ predictionGate } = admitView(base, message.view));
+            receiptFloor = message.receipt;
+            view = message.view;
+            projected = message.receipt;
+            break;
+        case "sessionTerminal":
+            if (message.finalReceipt)
+                receiptFloor = message.finalReceipt;
+            projected = message.finalReceipt;
+            break;
+        default: {
+            /* The three named notices. They never move the floor, never carry a
+               view, and never schedule a decision. */
+            const step = gateMessage;
+            if (!step)
+                throw new SessionBoundaryError("InvalidMessageTag", `${message.type} carries a cursor but no boundary`);
+            if (step.kind === "prepared")
+                admitGatePreparation(base, step.preparation);
+            if (step.kind === "released" && view) {
+                const release = step.release;
+                if (equalReceiptRef(release.receipt, view.latestReceipt) &&
+                    view.participantDeadlineMs !== release.originalDeadlineMs)
+                    throw new SessionBoundaryError("DeadlineChangesWithoutTransition", "the release names another original deadline than the open turn");
+            }
+            predictionGate = applyPredictionGateStatus(predictionGate, step);
+            if (step.kind === "prepared")
+                awaitingGatePrefix = false;
+            projected = receiptFloor;
+            break;
+        }
+    }
+    if (!equalReceiptRef(cursor.witnessedReceipt, projected))
+        throw new SessionBoundaryError("ReceiptHeadMismatch", "the cursor does not name the receipt this event projects");
+    return {
+        disposition: "applied",
+        boundary: {
+            context,
+            sequence,
+            receiptFloor,
+            view,
+            predictionGate,
+            awaitingGatePrefix,
+        },
+    };
+}