@sagentlab/navarch-runtime 0.1.116 → 0.1.118

package/node_modules/@muse-code/sdk/dist/src/fold/session-fold.js

@@ -0,0 +1,427 @@
+/**
+ * `SessionFold` — the SS4 client fold, bound to the generated wire types
+ * (spec 14990 FR-007, tasks.md T019).
+ *
+ * `ItemStore` and `SessionStateStore` are generic because they were written
+ * before the session-view plane entered the generated declarations. This
+ * module is where the generic parameters are BOUND: items are `@muse-code/msp`'s
+ * `Item`, state-family values are the generated `session/*` params objects,
+ * and every event this fold accepts is typed as the params object the wire
+ * actually carries. Nothing here restates a wire shape (INV-001).
+ *
+ * Beyond the two-store composition, the fold owns the parts of the view that
+ * are neither an item nor a state family:
+ *
+ *  - the TURN LIFECYCLE — `turn/started`, `turn/completed`, `turn/retracted`,
+ *    `turn/unqueued`, and the non-terminal `turn/retryScheduled` and
+ *    `turn/foregroundCompleted`;
+ *  - the APPROVAL and USER-INPUT view events as fold INPUTS — the pending
+ *    sets and their first durable terminal. The decision flow (choosing and
+ *    sending a resolution) is the facade's, not the fold's;
+ *  - the DELIVERY marker `view/gap` — it seeds no store, it moves the fold's
+ *    CURRENCY (`pendingGap`/`current`, FM-003). The recovery that fills the
+ *    hole needs client→server I/O and is therefore the facade's (T032).
+ *
+ * INV-006 governs all of it: the fold never invents a terminal. A retract and
+ * a reclaim are not `TurnTerminal` values and are never rendered as one, an
+ * unrecognized `TurnTerminal` is kept verbatim, and a second resolution never
+ * displaces the first durable one.
+ */
+import { ItemStore } from "./item-store.js";
+import { SessionStateStore } from "./state-store.js";
+/**
+ * The whole client-side session view: items, session state, turns, and the
+ * pending approval/user-input sets.
+ */
+export class SessionFold {
+    #itemStore = new ItemStore();
+    #sessionStateStore = new SessionStateStore();
+    /** Items, snapshot-only: the mutators are `apply()`'s, not the consumer's. */
+    get items() {
+        return this.#itemStore;
+    }
+    /**
+     * Discharge the SS2.13.3b ephemeral host-death obligation over the item
+     * half: every item still in progress becomes terminal-unknown and the fold
+     * refuses further events (spec FM-002; slice 3's T030b).
+     *
+     * A FOLD-level method rather than a `FoldItems` entry on purpose. `items` is
+     * snapshot-only — an allowlist whose whole job is that a store mutator can
+     * never leak onto the consumer surface (PR #23087 review round) — and this
+     * IS a mutator. Widening the allowlist to reach it would undo that; routing
+     * it here keeps exactly one caller (`Session.hostExited`) and leaves the
+     * read surface untouched. The in-progress probe stays the caller's, so the
+     * store remains wire-shape-blind (INV-001).
+     */
+    markEphemeralHostDeath(isInProgress) {
+        return this.#itemStore.markEphemeralHostDeath(isInProgress);
+    }
+    /**
+     * The session-state families, keyed by notification method name. Named
+     * `sessionState` rather than `state` because the surface contract reserves
+     * `state` for the FR-008 aggregate that arrives with snapshot ingestion.
+     * Snapshot-only, like `items`.
+     */
+    get sessionState() {
+        // The ONE narrowing cast, here rather than at every consumer. The store
+        // is generic over a `string` family key (it predates the generated
+        // session-view plane, INV-001), but `apply`'s seven `session/*` arms are
+        // its only writers in this fold — an unrecognized method reaches the
+        // ignore arm, never the store — so every key it can hold IS a
+        // `SessionStateMethod`.
+        return this.#sessionStateStore;
+    }
+    #turns = new Map();
+    #pendingApprovals = new Map();
+    #resolvedApprovals = new Map();
+    #pendingUserInputs = new Map();
+    #settledUserInputs = new Map();
+    #activeTurnId;
+    #pendingGap;
+    /** The turn currently running, if one is. */
+    get activeTurnId() {
+        return this.#activeTurnId;
+    }
+    /**
+     * The outstanding delivery hole, or `undefined` when there is none (tdd
+     * SS4.8, FM-003).
+     *
+     * COALESCED, keeping the FIRST `after`: consecutive overflows are one hole
+     * from a filler's point of view, which is the client mirror of the server's
+     * own D-16487-1 bracket rule. A recovery walks `(after, next)` and calls
+     * `gapFilled(next)` with the target it actually reached, so a hole that grew
+     * while the walk was in flight cannot be reported filled.
+     */
+    get pendingGap() {
+        return this.#pendingGap;
+    }
+    /**
+     * Is this fold current with the session view?
+     *
+     * FM-003's "only then reports current": false from the moment a `view/gap`
+     * folds until its hole is filled. Live events keep folding meanwhile — they
+     * are real facts and dropping them would add a second hole — so this flag is
+     * the ONLY statement that the transcript has a hole in it.
+     */
+    get current() {
+        return this.#pendingGap === undefined;
+    }
+    /**
+     * A recovery filled the hole up to `next`. Returns whether it cleared.
+     *
+     * EQUALITY, never a relational compare (tdd SS4.1): the argument is the
+     * target the walk reached, and it clears only when that is still the
+     * outstanding target. A gap that arrived mid-walk left a newer `next`, so
+     * this answers `false` and the fold stays not-current — the truthful answer,
+     * since the second hole is unfilled.
+     *
+     * A fold-level mutator with the same rationale as `markEphemeralHostDeath`:
+     * `items`/`sessionState` are snapshot-only allowlists, and this belongs to
+     * neither store.
+     */
+    gapFilled(next) {
+        if (this.#pendingGap?.next !== next)
+            return false;
+        this.#pendingGap = undefined;
+        return true;
+    }
+    apply(event) {
+        // `params` is optional on the wire, and every recognized arm below
+        // dereferences it. Drop the frame here rather than let one arm throw on
+        // an absent params object — SS1.5.4 tolerance is drop-don't-throw, and a
+        // throw would take out the consumer's notification pump.
+        //
+        // NOT just `=== undefined`. `params: null` is a very common sloppy
+        // JSON-RPC spelling of "no params" and threw the same raw TypeError one
+        // value over; a non-object (`42`, a string) got further still and minted a
+        // phantom turn keyed `undefined`. An ARRAY needs its own clause because
+        // JSON-RPC 2.0 permits positional params and `typeof [] === "object"`, so
+        // it slipped both: `params: []` reached the arms and SETTLED a turn keyed
+        // `undefined`. The classification lives HERE so both this overload pair
+        // and `Session.apply` inherit it from one place.
+        if (event.params === null || typeof event.params !== "object" || Array.isArray(event.params)) {
+            return { kind: "ignoredMissingParams", method: event.method };
+        }
+        const typed = event;
+        switch (typed.method) {
+            case "item/started":
+            case "item/updated":
+            case "item/completed":
+                return { kind: "item", outcome: this.#itemStore.apply(typed.params.item) };
+            case "item/delta":
+                return {
+                    kind: "itemDelta",
+                    outcome: this.#itemStore.applyDelta(typed.params.itemId, typed.params.delta, typed.params.field ?? "text"),
+                };
+            case "turn/started":
+                return this.#turnStarted(typed.params);
+            case "turn/completed":
+                return this.#turnCompleted(typed.params);
+            case "turn/retracted":
+                return this.#turnRetracted(typed.params);
+            case "turn/unqueued":
+                return this.#turnUnqueued(typed.params);
+            case "turn/retryScheduled":
+                return this.#turnRetryScheduled(typed.params);
+            case "turn/foregroundCompleted":
+                return this.#turnForegroundCompleted(typed.params);
+            case "approval/requested":
+                return this.#approvalRequested(typed.params);
+            case "approval/updated":
+                return this.#approvalUpdated(typed.params);
+            case "approval/resolved":
+                return this.#approvalResolved(typed.params);
+            case "userInput/requested":
+                return this.#userInputRequested(typed.params);
+            case "userInput/settled":
+                return this.#userInputSettled(typed.params);
+            case "view/gap":
+                return this.#deliveryGap(typed.params);
+            case "session/modelRouteUnserved":
+                return { kind: "modelRouteUnserved", params: typed.params };
+            case "session/modelChanged":
+            case "session/reasoningEffortChanged":
+            case "session/goalChanged":
+            case "session/todoListChanged":
+            case "session/branchChanged":
+            case "session/tokenUsage":
+            case "session/contextUsage":
+            case "session/approvalModeChanged":
+            case "session/nameChanged":
+                return {
+                    kind: "sessionState",
+                    outcome: this.#sessionStateStore.apply(typed.method, typed.params, typed.params.viewCursor),
+                };
+            default: {
+                const unrecognized = event;
+                return { kind: "ignoredUnrecognizedMethod", method: unrecognized.method };
+            }
+        }
+    }
+    /** Turns in first-observed order. */
+    turns() {
+        return [...this.#turns.values()].map((turn) => SessionFold.#turnSnapshot(turn));
+    }
+    turn(turnId) {
+        const held = this.#turns.get(turnId);
+        return held === undefined ? undefined : SessionFold.#turnSnapshot(held);
+    }
+    /** Approvals awaiting a durable terminal, in first-observed order. */
+    pendingApprovals() {
+        return [...this.#pendingApprovals.entries()].map(([approvalId, held]) => ({
+            approvalId,
+            requested: held.requested,
+            ...(held.latestUpdate !== undefined ? { latestUpdate: held.latestUpdate } : {}),
+        }));
+    }
+    /** The winning durable terminal per approval, in first-observed order. */
+    resolvedApprovals() {
+        return [...this.#resolvedApprovals.values()];
+    }
+    /**
+     * Prompts awaiting a durable settlement, in first-observed order. The
+     * entries ARE the generated request params — the wire shape already carries
+     * `userInputId`, so a wrapper would only duplicate it (unlike
+     * `PendingApproval`, which earns its wrapper with `latestUpdate`).
+     */
+    pendingUserInputs() {
+        return [...this.#pendingUserInputs.values()];
+    }
+    /** The winning durable settlement per prompt, in first-observed order. */
+    settledUserInputs() {
+        return [...this.#settledUserInputs.values()];
+    }
+    // ---- turn lifecycle -----------------------------------------------------
+    #turnStarted(params) {
+        // A turn the fold has already seen leave `running` never re-opens. A
+        // redelivered `turn/started` after a terminal/retract/reclaim would mint
+        // `{state: "running", terminal: …}` — a shape `TurnEntry`'s own docs say
+        // cannot exist — and re-point `activeTurnId` at a turn no completion will
+        // follow, so a renderer keyed on it shows a running turn forever.
+        // `#turnFor` mints fresh entries as `running`, so a first sighting (and a
+        // redelivery while genuinely running) still folds.
+        const turn = this.#turnFor(params.turnId);
+        if (turn.state !== "running") {
+            return { kind: "ignoredStaleFrame", method: "turn/started", id: params.turnId };
+        }
+        turn.commandId = params.commandId;
+        turn.state = "running";
+        this.#activeTurnId = params.turnId;
+        return { kind: "turn", turnId: params.turnId, state: turn.state };
+    }
+    #turnCompleted(params) {
+        // A turn the fold never saw start still settles here: single-shot and
+        // gap-filled turns arrive terminal-first (tdd SS4.4.1's sibling rule).
+        const turn = this.#turnFor(params.turnId);
+        // …but a RETRACTED or RECLAIMED turn stays that way. Replaying the
+        // completion frame that preceded an accepted retract would flip the entry
+        // back to `settled` and lose the retract fact entirely (the same
+        // redelivered-frame class as `#turnStarted` above).
+        if (turn.state === "retracted" || turn.state === "unqueued") {
+            return { kind: "ignoredStaleFrame", method: "turn/completed", id: params.turnId };
+        }
+        turn.state = "settled";
+        turn.terminal = params.terminal;
+        if (params.error !== undefined)
+            turn.error = params.error;
+        // The retry hint is a "retrying in Ns" countdown, and it clears on the
+        // turn's next event — which a completion is (tdd SS4.5.1). Leaving it set
+        // makes a renderer show the countdown on a finished turn.
+        turn.retryScheduled = undefined;
+        // Same for the foreground hint: a finished turn is not background-waiting
+        // (tdd SS4.5.12).
+        turn.foregroundCompleted = undefined;
+        this.#clearActive(params.turnId);
+        return { kind: "turn", turnId: params.turnId, state: turn.state };
+    }
+    #turnRetracted(params) {
+        const turn = this.#turnFor(params.turnId);
+        turn.commandId = params.commandId;
+        // A retract is NOT a `TurnTerminal`; leaving `terminal` unset is the whole
+        // point (INV-006). On accepted, the retracted user message re-arrives via
+        // `item/updated` with `retracted: true`, which the item half folds
+        // (a declined outcome also lands here for now: the entry reads retracted
+        // and the later turn/completed arrives as a stale frame, so its terminal
+        // is dropped too - a known gap in this fold, behavior unchanged).
+        turn.state = "retracted";
+        this.#clearActive(params.turnId);
+        return { kind: "turn", turnId: params.turnId, state: turn.state };
+    }
+    #turnUnqueued(params) {
+        // The reclaim of a QUEUED submit: this turn was pre-minted at admission
+        // and never launched, so no `turn/started` preceded it and no
+        // `turn/completed` will follow (tdd SS3.6, SS4.5.1). It therefore never
+        // becomes the active turn and never carries a terminal.
+        const turn = this.#turnFor(params.turnId);
+        turn.commandId = params.commandId;
+        turn.state = "unqueued";
+        this.#clearActive(params.turnId);
+        return { kind: "turn", turnId: params.turnId, state: turn.state };
+    }
+    #turnRetryScheduled(params) {
+        // Non-terminal by contract: it never resolves a turn-wait (tdd SS3.1.4).
+        const turn = this.#turnFor(params.turnId);
+        // …but it is still a turn frame, so it takes the same redelivery guard as
+        // the other arms. Without it, replaying a whole page re-plants the retry
+        // hint on a turn that already left `running` — and the clear in
+        // `#turnCompleted` can no longer undo that, because the replayed
+        // completion is itself dropped. The turn would show "retrying in Ns"
+        // forever.
+        if (turn.state !== "running") {
+            return { kind: "ignoredStaleFrame", method: "turn/retryScheduled", id: params.turnId };
+        }
+        turn.retryScheduled = params;
+        return { kind: "turn", turnId: params.turnId, state: turn.state };
+    }
+    #turnForegroundCompleted(params) {
+        // Non-terminal by contract: it never resolves a turn-wait (tdd SS4.5.12).
+        const turn = this.#turnFor(params.turnId);
+        // …but it is still a turn frame, so it takes the same redelivery guard
+        // as the retry hint: a replayed page must not re-plant the
+        // background-wait hint on a turn that already left `running`.
+        if (turn.state !== "running") {
+            return { kind: "ignoredStaleFrame", method: "turn/foregroundCompleted", id: params.turnId };
+        }
+        turn.foregroundCompleted = params;
+        return { kind: "turn", turnId: params.turnId, state: turn.state };
+    }
+    #turnFor(turnId) {
+        const held = this.#turns.get(turnId);
+        if (held !== undefined)
+            return held;
+        const fresh = { turnId, state: "running" };
+        this.#turns.set(turnId, fresh);
+        return fresh;
+    }
+    #clearActive(turnId) {
+        if (this.#activeTurnId === turnId)
+            this.#activeTurnId = undefined;
+    }
+    static #turnSnapshot(turn) {
+        return {
+            turnId: turn.turnId,
+            state: turn.state,
+            ...(turn.commandId !== undefined ? { commandId: turn.commandId } : {}),
+            ...(turn.terminal !== undefined ? { terminal: turn.terminal } : {}),
+            ...(turn.error !== undefined ? { error: turn.error } : {}),
+            ...(turn.retryScheduled !== undefined ? { retryScheduled: turn.retryScheduled } : {}),
+            ...(turn.foregroundCompleted !== undefined
+                ? { foregroundCompleted: turn.foregroundCompleted }
+                : {}),
+        };
+    }
+    // ---- the delivery-plane marker ------------------------------------------
+    #deliveryGap(params) {
+        // Coalesced on the FIRST `after`: a second overflow while the first hole
+        // is still open extends the range rather than replacing it. Replacing it
+        // would move the lower bound past events that were never delivered, so a
+        // walk from the newer `after` would skip them permanently — a silent hole
+        // manufactured by the very state that exists to name one.
+        this.#pendingGap = {
+            after: this.#pendingGap?.after ?? params.after,
+            next: params.next,
+            sessionId: params.sessionId,
+        };
+        // The FRAME's own bounds, not the coalesced ones: this is a report of what
+        // arrived. `pendingGap` is the outstanding hole.
+        return { after: params.after, kind: "deliveryGap", next: params.next };
+    }
+    // ---- approvals and user input as fold inputs ----------------------------
+    #approvalRequested(params) {
+        // A request for an approval that already has its durable terminal (a
+        // redelivered or pre-join frame) never re-opens it: no second resolution
+        // is coming, so the resurrected entry would pend forever (tdd SS5's
+        // first-terminal-wins, request side).
+        if (this.#resolvedApprovals.has(params.approvalId)) {
+            return { kind: "ignoredStaleFrame", method: "approval/requested", id: params.approvalId };
+        }
+        // A re-request REPLACES the entry, `latestUpdate` included: a re-issued
+        // request already embodies the latest refresh (tdd SS5.6.3), so pairing
+        // the new request with the OLD update would show stale stage/choices and
+        // a decide against them bounces -32053.
+        this.#pendingApprovals.set(params.approvalId, { requested: params });
+        return { kind: "approvalPending", approvalId: params.approvalId, requested: params };
+    }
+    #approvalUpdated(params) {
+        // An update REFRESHES a pending view; it never opens one. An update for an
+        // approval this fold never saw requested (a pre-join frame) is dropped
+        // rather than synthesized into a request it cannot honestly describe —
+        // and the outcome says so, rather than claiming a pending entry.
+        //
+        // A POST-RESOLVE update lands here too, because the resolve deleted the
+        // entry. Most are redeliveries, but a FAILED `localPersistent`
+        // `policyPersistence` report is a first delivery of a new fact (tdd
+        // SS5.5/SS6.8). This fold drops it and holds no accessor for the reason;
+        // surfacing is deferred to the facade slice — issue #23379.
+        const held = this.#pendingApprovals.get(params.approvalId);
+        if (held === undefined) {
+            return { kind: "ignoredStaleFrame", method: "approval/updated", id: params.approvalId };
+        }
+        held.latestUpdate = params;
+        return { kind: "approvalPending", approvalId: params.approvalId, requested: held.requested };
+    }
+    #approvalResolved(params) {
+        this.#pendingApprovals.delete(params.approvalId);
+        const firstTerminal = !this.#resolvedApprovals.has(params.approvalId);
+        // The FIRST durable terminal decision is the one that stands (tdd SS5); a
+        // later one is a losing racer's echo, never an overwrite.
+        if (firstTerminal)
+            this.#resolvedApprovals.set(params.approvalId, params);
+        return { kind: "approvalResolved", approvalId: params.approvalId, firstTerminal };
+    }
+    #userInputRequested(params) {
+        // Symmetric with `#approvalRequested`: a settled prompt stays settled.
+        if (this.#settledUserInputs.has(params.userInputId)) {
+            return { kind: "ignoredStaleFrame", method: "userInput/requested", id: params.userInputId };
+        }
+        this.#pendingUserInputs.set(params.userInputId, params);
+        return { kind: "userInputPending", userInputId: params.userInputId };
+    }
+    #userInputSettled(params) {
+        this.#pendingUserInputs.delete(params.userInputId);
+        const firstSettlement = !this.#settledUserInputs.has(params.userInputId);
+        if (firstSettlement)
+            this.#settledUserInputs.set(params.userInputId, params);
+        return { kind: "userInputSettled", userInputId: params.userInputId, firstSettlement };
+    }
+}

package/node_modules/@muse-code/sdk/dist/src/fold/state-store.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The session-state half of the SS4 client fold (spec 14990 FR-007, INV-005).
+ *
+ * State events are NOT items: they carry replace-wholesale session facts,
+ * cursor-ordered, latest-wins (tdd SS4.6). An explicit `null` is a fact — it
+ * clears the family — never "unchanged" (the `session/goalChanged` and
+ * `session/branchChanged` rules). `session/tokenUsage` is the one
+ * accumulate-only family; its running totals arrive server-computed in
+ * `cumulative`, so the client stores rather than sums (tdd SS4.6.5).
+ *
+ * Generic for the same reason `ItemStore` is: the concrete params types are
+ * enrolled by #14953 and INV-001 forbids restating them locally. The family
+ * KEY is the notification method name, which is protocol vocabulary the
+ * generated layer already owns as `MspNotification`; this store treats it as
+ * an opaque string so a family added additively (tdd SS1.5.4) folds without
+ * a code change.
+ */
+/** A stored family value. `null` is a real value: the family was cleared. */
+export type StateValue<V> = V | null;
+/**
+ * What one state event changed: the family it targeted, the value it
+ * replaced, the value now stored, and whether it was applied or refused as
+ * a replay.
+ */
+export interface StateApplyOutcome<V> {
+    readonly family: string;
+    readonly previous: StateValue<V> | undefined;
+    readonly current: StateValue<V>;
+    /** False when the incoming value was refused as an exact-cursor replay. */
+    readonly applied: boolean;
+}
+/**
+ * Last-write-wins per family, in arrival order.
+ *
+ * Cursors are opaque strings and MUST NOT be parsed or ordered (tdd SS4.1),
+ * so ordering here is by arrival: the server emits view events in cursor
+ * order on every connection, and a page's events are ascending. The one
+ * cursor use is EXACT-EQUALITY replay de-duplication, and it remembers only
+ * the family's LATEST cursor — it refuses only a back-to-back replay of the
+ * family's most recent event. The SS4.8 splice caller must skip
+ * already-applied page events itself, which it does by construction: the
+ * splice pages forward from `after` (the last delivered cursor) and
+ * discards paged events at cursors >= `next` as duplicates of the live
+ * buffer, so no sanctioned path re-delivers an older event. No relational
+ * comparison exists: string order diverges from cursor order at every digit
+ * rollover ("v:s:10" < "v:s:9" as strings), which would drop genuinely
+ * newer events.
+ */
+export declare class SessionStateStore<V = unknown> {
+    #private;
+    /**
+     * Apply a state event. `cursor` is the event's `viewCursor`; when omitted
+     * (a snapshot seed, which carries one cursor for the whole state) the value
+     * is taken unconditionally.
+     */
+    apply(family: string, value: StateValue<V>, cursor?: string): StateApplyOutcome<V>;
+    /**
+     * Read a family. `undefined` means no fact has ever landed — distinct from
+     * `null`, which means a fact cleared it. Absent is never fabricated
+     * (tdd SS4.9.1).
+     */
+    get(family: string): StateValue<V> | undefined;
+    has(family: string): boolean;
+    /** Every family that holds a value, in insertion order. */
+    families(): readonly string[];
+    /** Seed from a snapshot's state block: authoritative, replaces wholesale. */
+    seed(entries: Iterable<readonly [string, StateValue<V>]>, cursor?: string): void;
+}

package/node_modules/@muse-code/sdk/dist/src/fold/state-store.js

@@ -0,0 +1,89 @@
+/**
+ * The session-state half of the SS4 client fold (spec 14990 FR-007, INV-005).
+ *
+ * State events are NOT items: they carry replace-wholesale session facts,
+ * cursor-ordered, latest-wins (tdd SS4.6). An explicit `null` is a fact — it
+ * clears the family — never "unchanged" (the `session/goalChanged` and
+ * `session/branchChanged` rules). `session/tokenUsage` is the one
+ * accumulate-only family; its running totals arrive server-computed in
+ * `cumulative`, so the client stores rather than sums (tdd SS4.6.5).
+ *
+ * Generic for the same reason `ItemStore` is: the concrete params types are
+ * enrolled by #14953 and INV-001 forbids restating them locally. The family
+ * KEY is the notification method name, which is protocol vocabulary the
+ * generated layer already owns as `MspNotification`; this store treats it as
+ * an opaque string so a family added additively (tdd SS1.5.4) folds without
+ * a code change.
+ */
+/**
+ * Last-write-wins per family, in arrival order.
+ *
+ * Cursors are opaque strings and MUST NOT be parsed or ordered (tdd SS4.1),
+ * so ordering here is by arrival: the server emits view events in cursor
+ * order on every connection, and a page's events are ascending. The one
+ * cursor use is EXACT-EQUALITY replay de-duplication, and it remembers only
+ * the family's LATEST cursor — it refuses only a back-to-back replay of the
+ * family's most recent event. The SS4.8 splice caller must skip
+ * already-applied page events itself, which it does by construction: the
+ * splice pages forward from `after` (the last delivered cursor) and
+ * discards paged events at cursors >= `next` as duplicates of the live
+ * buffer, so no sanctioned path re-delivers an older event. No relational
+ * comparison exists: string order diverges from cursor order at every digit
+ * rollover ("v:s:10" < "v:s:9" as strings), which would drop genuinely
+ * newer events.
+ */
+export class SessionStateStore {
+    #values = new Map();
+    #cursors = new Map();
+    /**
+     * Apply a state event. `cursor` is the event's `viewCursor`; when omitted
+     * (a snapshot seed, which carries one cursor for the whole state) the value
+     * is taken unconditionally.
+     */
+    apply(family, value, cursor) {
+        const previous = this.#values.get(family);
+        if (cursor !== undefined) {
+            const seen = this.#cursors.get(family);
+            // An equal cursor is a replay of the same event (idempotent): refuse.
+            // That is the ONLY cursor comparison — cursors are opaque (SS4.1) and
+            // any relational order (string order included) mis-sorts at a digit
+            // rollover; arrival order carries the LWW truth.
+            if (seen !== undefined && cursor === seen) {
+                return {
+                    family,
+                    previous,
+                    current: previous ?? null,
+                    applied: false,
+                };
+            }
+            this.#cursors.set(family, cursor);
+        }
+        this.#values.set(family, value);
+        return { family, previous, current: value, applied: true };
+    }
+    /**
+     * Read a family. `undefined` means no fact has ever landed — distinct from
+     * `null`, which means a fact cleared it. Absent is never fabricated
+     * (tdd SS4.9.1).
+     */
+    get(family) {
+        return this.#values.get(family);
+    }
+    has(family) {
+        return this.#values.has(family);
+    }
+    /** Every family that holds a value, in insertion order. */
+    families() {
+        return [...this.#values.keys()];
+    }
+    /** Seed from a snapshot's state block: authoritative, replaces wholesale. */
+    seed(entries, cursor) {
+        this.#values.clear();
+        this.#cursors.clear();
+        for (const [family, value] of entries) {
+            this.#values.set(family, value);
+            if (cursor !== undefined)
+                this.#cursors.set(family, cursor);
+        }
+    }
+}

package/node_modules/@muse-code/sdk/dist/src/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @packageDocumentation
+ * `@muse-code/sdk` — the MSP TypeScript facade (tdd SS7.1).
+ *
+ * (The tag above is load-bearing: without it TypeDoc attaches this header to
+ * the first re-export, whose generated reference page then publishes this
+ * prose instead of the export's own TSDoc.)
+ *
+ * Slices 1 and 2 (spec `14990-muse-sdk`, plan.md) ship the workspace, the schema
+ * fingerprint pin, and the transport-less core: the item/state fold algebra,
+ * `SessionFold` binding it to the generated wire types, the complete SS4.13
+ * pending-command fold, and the duplex-agnostic NDJSON connection with its
+ * typed stdio handshake.
+ *
+ * Slice 3 ships the SS7.1 facade: `MuseClient` (incl. `spawn`), `Session`,
+ * `TurnHandle`'s iterators and INV-014 turn-wait, the SS2.13.3b host-death
+ * discharge on BOTH notifications (process exit and transport EOF), the
+ * `sendUserTurn` and `approval/decide` submit verbs, the SS4.13 retirement
+ * drivers those verbs made reachable, and the SS4.8 gap splice-fill inside the
+ * iterators (FR-020).
+ *
+ * Not here yet, each with its named dependency; the condition and the command
+ * that re-derives it live once, in `specs/14990-muse-sdk/tasks.md` under "The
+ * slice-3 blocker".
+ *  - Snapshot ingestion (FR-008) — sequenced behind spec 210 T061's corpus
+ *    regeneration, not behind a shape.
+ *  - Corpus replay + checkpoint equality (slice 1c) — runnable now; own PR.
+ */
+export { EXPECTED_SCHEMA_FINGERPRINT, checkServedFingerprint, fingerprintMismatchMessage, } from "./fingerprint.js";
+export type { FingerprintWarning } from "./fingerprint.js";
+export { ItemStore } from "./fold/item-store.js";
+export type { DeltaApplyOutcome, ItemApplyOutcome, RevisionedItem, TerminalUnknownItemAnnotation, } from "./fold/item-store.js";
+export { SessionStateStore } from "./fold/state-store.js";
+export type { StateApplyOutcome, StateValue } from "./fold/state-store.js";
+export { SessionFold } from "./fold/session-fold.js";
+export type { 
+/**
+ * Exported because it is CONSUMER SURFACE, not an internal pin: every
+ * getter on `SessionFold` returns `DeepReadonly<…>`, so a consumer naming
+ * one of those values needs the type. Without it they are stuck with
+ * `ReturnType<>` gymnastics or a deep `dist/` import (#23556 item 4).
+ */
+DeepReadonly, FoldItems, FoldOutcome, FoldSessionState, PendingApproval, SessionStateMethod, SessionStateParams, StaleDroppableMethod, TurnEntry, TurnState, ViewEvent, } from "./fold/session-fold.js";
+export { COMMAND_REJECTED_CODE, COMMAND_REJECTED_KIND, PendingCommandSet, } from "./pending/pending-command-set.js";
+export type { CommandErrorResponse, PendingCommandAck, PendingCommandEntry, PendingCommandSetOptions, PendingDisposition, PendingJoinPlan, PendingRetirement, ReplayAnswer, SnapshotJoinFacts, } from "./pending/pending-command-set.js";
+export { Connection, createUuidV7Mint, MspError, ProtocolError, } from "./connection/connection.js";
+export type { CommandOptions, ConnectionOptions, DuplexTransport, NotificationHandler, ProtocolErrorHandler, ServerRequestHandler, } from "./connection/connection.js";
+export { MspHandshake, MuseServeChild, SpawnedMspConnection, spawnMspConnection, } from "./connection/spawn.js";
+export { MuseClient } from "./facade/client.js";
+export type { MuseClientOptions, MuseClientSpawnOptions, ResumeSessionOptions, StartSessionOptions, } from "./facade/client.js";
+export type { ExitClassification, MuseServeChildOptions, ProcessExit, SpawnMspConnectionOptions, } from "./connection/spawn.js";
+export { DiscardedSessions } from "./facade/discarded.js";
+export { MuseForeignSessionError, MuseGapFillError, MuseSessionDiscardedError, PermissionProfileNotApplied, } from "./errors.js";
+export type { GapFillFailureReason } from "./errors.js";
+export type { GapFillFailureHandler } from "./facade/gap-fill.js";
+export { MuseHostDiedError, readSessionDurability } from "./facade/host-death.js";
+export { MuseHostStartError } from "./facade/host-start.js";
+export type { HostStartFailure } from "./facade/host-start.js";
+export type { AbnormalExit, HostDeathDischarge, HostDeathNotification, SessionDurabilityProfile, TransportEof, } from "./facade/host-death.js";
+export { Session } from "./facade/session.js";
+export type { PendingCommandView, SessionApplyOutcome, SessionApplyRefusal, SessionFoldView, SessionGapBuffered, SessionGapOverlap, SessionOpening, SessionOptions, } from "./facade/session.js";
+export type { ApprovalDecisionInput, ApprovalFailure, ApprovalFailureHandler, ApprovalHandler, } from "./facade/approval.js";
+export type { SendUserTurnOptions } from "./facade/turn-submit.js";
+export { isLaunchFailure } from "./facade/turn-handle.js";
+export type { FoldedItem, Turn, TurnOutcome } from "./facade/turn-handle.js";