@sagentlab/navarch-runtime 0.1.112 → 0.1.117

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

@@ -0,0 +1,37 @@
+/**
+ * The schema-bundle staleness anchor (spec 14990 FR-006).
+ *
+ * `EXPECTED_SCHEMA_FINGERPRINT` pins the stable protocol-schema fingerprint
+ * this SDK was written against. Two consumers:
+ *
+ *  - Build time: a test asserts this equals `schema/msp/stable/manifest.json`,
+ *    so a schema advance that forgets the SDK reds the SDK lane instead of
+ *    shipping a silently-stale facade. This is the same manifest-pin pattern
+ *    the #210 transcripts use.
+ *  - Runtime: the connection machine compares `InitializeResult.schema
+ *    .fingerprint` against this pin. A mismatch is a WARNING, never an error
+ *    (tdd SS1.4.1) — additive-optional evolution means an older SDK keeps
+ *    working against a newer host.
+ */
+export declare const EXPECTED_SCHEMA_FINGERPRINT = "sha256:eae467ab60cb9a5d5af4de616830f065e59375c987fd59269c8cc33ed2a1137f";
+/**
+ * What a build-time mismatch MEANS, in the words a human needs at 2am.
+ *
+ * A mismatch is the normal, expected consequence of the protocol schema
+ * advancing — it is NOT evidence that the SDK is broken. The remedy is to
+ * re-pin and adapt whatever actually changed. Several lanes have burned time
+ * reading a red fingerprint as an SDK defect, so the message says it plainly.
+ */
+export declare function fingerprintMismatchMessage(pinned: string, actual: string): string;
+/** The runtime arm (tdd SS1.4.1): advisory only, never a connection failure. */
+export interface FingerprintWarning {
+    readonly kind: "schemaFingerprintMismatch";
+    readonly pinned: string;
+    readonly served: string;
+    readonly message: string;
+}
+/**
+ * Compare a host's advertised fingerprint against the pin.
+ * Returns `undefined` when they agree — a mismatch is surfaced, not thrown.
+ */
+export declare function checkServedFingerprint(served: string, pinned?: string): FingerprintWarning | undefined;

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

@@ -0,0 +1,54 @@
+/**
+ * The schema-bundle staleness anchor (spec 14990 FR-006).
+ *
+ * `EXPECTED_SCHEMA_FINGERPRINT` pins the stable protocol-schema fingerprint
+ * this SDK was written against. Two consumers:
+ *
+ *  - Build time: a test asserts this equals `schema/msp/stable/manifest.json`,
+ *    so a schema advance that forgets the SDK reds the SDK lane instead of
+ *    shipping a silently-stale facade. This is the same manifest-pin pattern
+ *    the #210 transcripts use.
+ *  - Runtime: the connection machine compares `InitializeResult.schema
+ *    .fingerprint` against this pin. A mismatch is a WARNING, never an error
+ *    (tdd SS1.4.1) — additive-optional evolution means an older SDK keeps
+ *    working against a newer host.
+ */
+export const EXPECTED_SCHEMA_FINGERPRINT = "sha256:eae467ab60cb9a5d5af4de616830f065e59375c987fd59269c8cc33ed2a1137f";
+/**
+ * What a build-time mismatch MEANS, in the words a human needs at 2am.
+ *
+ * A mismatch is the normal, expected consequence of the protocol schema
+ * advancing — it is NOT evidence that the SDK is broken. The remedy is to
+ * re-pin and adapt whatever actually changed. Several lanes have burned time
+ * reading a red fingerprint as an SDK defect, so the message says it plainly.
+ */
+export function fingerprintMismatchMessage(pinned, actual) {
+    return [
+        "MSP schema fingerprint moved: re-pin after a schema advance.",
+        `  pinned by @muse-code/sdk: ${pinned}`,
+        `  schema/msp/stable/manifest.json: ${actual}`,
+        "",
+        "This does NOT mean the SDK is broken. The stable schema bundle advanced",
+        "(a #206 enrollment or renderer change). Fix it by running",
+        "scripts/regen-msp-pins.sh, which re-pins EXPECTED_SCHEMA_FINGERPRINT and",
+        "every other derived copy from the committed stable manifest, then adapt",
+        "the facade to whatever the advance actually changed. Never hand-edit",
+        "schema/msp/** to match the SDK.",
+    ].join("\n");
+}
+/**
+ * Compare a host's advertised fingerprint against the pin.
+ * Returns `undefined` when they agree — a mismatch is surfaced, not thrown.
+ */
+export function checkServedFingerprint(served, pinned = EXPECTED_SCHEMA_FINGERPRINT) {
+    if (served === pinned)
+        return undefined;
+    return {
+        kind: "schemaFingerprintMismatch",
+        pinned,
+        served,
+        message: `host schema fingerprint ${served} differs from the fingerprint this ` +
+            `SDK pins (${pinned}); proceeding under additive-optional evolution ` +
+            `(SS1.5.4). Re-pin after a schema advance.`,
+    };
+}

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

@@ -0,0 +1,110 @@
+/**
+ * The item half of the SS4 client fold: upsert-by-revision plus delta
+ * accumulation (spec 14990 FR-007, INV-003/INV-004).
+ *
+ * WHY THIS IS GENERIC. The concrete wire item type (`Item`, `ItemDeltaParams`,
+ * …) is rendered by `crates/protocol` and is not yet in the committed
+ * declarations — the session-view plane is enrolled by #14953. INV-001
+ * forbids hand-writing a protocol type to fill the gap, so this module states
+ * only the *algebraic precondition* its rules need — an item has an identity
+ * and a revision — and takes the payload as a type parameter. When #14953
+ * lands, `SessionFold` binds `T` to `@muse-code/msp`'s `Item` with no change here
+ * and no protocol shape ever restated locally.
+ */
+/** The minimum an upsert needs: identity plus the monotonic ordering guard. */
+export interface RevisionedItem {
+    readonly itemId: string;
+    readonly revision: number;
+}
+/** What an apply did — enough for a consumer to render without re-diffing. */
+export type ItemApplyOutcome = {
+    readonly kind: "inserted";
+    readonly itemId: string;
+} | {
+    readonly kind: "replaced";
+    readonly itemId: string;
+    readonly from: number;
+    readonly to: number;
+}
+/** A stale or replayed re-emission. The store did not change (INV-003). */
+ | {
+    readonly kind: "ignoredStaleRevision";
+    readonly itemId: string;
+    readonly held: number;
+    readonly offered: number;
+};
+/** What a delta did. Deltas bump no revision (tdd SS4.4.1). */
+export type DeltaApplyOutcome = {
+    readonly kind: "appended";
+    readonly itemId: string;
+    readonly field: string;
+    readonly length: number;
+}
+/**
+ * A delta for an item the store does not hold. Deltas are a streaming
+ * optimization and are never a fold's only source of a fact (tdd SS4.7.3),
+ * so this is buffered against the item's arrival rather than dropped or
+ * treated as an error.
+ */
+ | {
+    readonly kind: "bufferedForAbsentItem";
+    readonly itemId: string;
+    readonly field: string;
+};
+/** Client-only annotation required when an ephemeral host dies abnormally. */
+export interface TerminalUnknownItemAnnotation {
+    readonly kind: "terminalUnknown";
+    readonly itemId: string;
+}
+/**
+ * Items in first-opened order (the order tdd SS4.9.1 requires of a snapshot),
+ * each held at its latest revision, with per-field delta accumulators.
+ */
+export declare class ItemStore<T extends RevisionedItem> {
+    #private;
+    /**
+     * Apply an `item/started` | `item/updated` | `item/completed` payload.
+     * Replace iff the incoming revision is strictly higher (INV-003).
+     */
+    apply(item: T): ItemApplyOutcome;
+    /**
+     * Apply an `item/delta`: a UTF-8-safe append to the open item's field named
+     * by `field` (default `"text"`), contiguous and lossless in cursor order.
+     * The concatenation of all deltas for a field path equals that field's
+     * value on the final `item/completed` object (INV-004, tdd SS4.3.1).
+     */
+    applyDelta(itemId: string, delta: string, field?: string): DeltaApplyOutcome;
+    /** The accumulated delta text for a field path, or `undefined` if none. */
+    accumulated(itemId: string, field?: string): string | undefined;
+    /** Every field path that has accumulated deltas for this item. */
+    accumulatedFields(itemId: string): readonly string[];
+    get(itemId: string): T | undefined;
+    has(itemId: string): boolean;
+    /** Items in first-opened order (tdd SS4.9.1). */
+    list(): readonly T[];
+    /** The id of the most recently opened item, or `undefined` when empty. */
+    lastOpenedItemId(): string | undefined;
+    get size(): number;
+    /**
+     * Seed from a snapshot's `state.items` (tdd SS4.9.1): every item at its
+     * latest revision at the snapshot cursor, in first-opened order. Seeding
+     * REPLACES the store — a snapshot is authoritative (tdd SS4.9), never
+     * merged into stale local state.
+     *
+     * Delta accumulators are intentionally NOT seeded: a snapshot carries
+     * streamed fields at their accumulated-so-far values on the item itself,
+     * and `view/page` never replays ephemeral-sourced deltas (tdd SS4.7.3).
+     */
+    seed(items: Iterable<T>): void;
+    /**
+     * Permanently discard an ephemeral session after abnormal host death.
+     *
+     * The last wire item remains byte-for-byte intact: terminal-unknown is a
+     * client display annotation, never a fabricated `item/completed` or wire
+     * status (SS2.13.3b / SS4.4.3). Further events and snapshot seeding are
+     * refused because this session has no resume surface.
+     */
+    markEphemeralHostDeath(isInProgress: (item: T) => boolean): readonly TerminalUnknownItemAnnotation[];
+    isTerminalUnknown(itemId: string): boolean;
+    get ephemeralSessionDiscarded(): boolean;
+}

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

@@ -0,0 +1,169 @@
+/**
+ * The item half of the SS4 client fold: upsert-by-revision plus delta
+ * accumulation (spec 14990 FR-007, INV-003/INV-004).
+ *
+ * WHY THIS IS GENERIC. The concrete wire item type (`Item`, `ItemDeltaParams`,
+ * …) is rendered by `crates/protocol` and is not yet in the committed
+ * declarations — the session-view plane is enrolled by #14953. INV-001
+ * forbids hand-writing a protocol type to fill the gap, so this module states
+ * only the *algebraic precondition* its rules need — an item has an identity
+ * and a revision — and takes the payload as a type parameter. When #14953
+ * lands, `SessionFold` binds `T` to `@muse-code/msp`'s `Item` with no change here
+ * and no protocol shape ever restated locally.
+ */
+import { MuseSessionDiscardedError } from "../errors.js";
+/**
+ * Items in first-opened order (the order tdd SS4.9.1 requires of a snapshot),
+ * each held at its latest revision, with per-field delta accumulators.
+ */
+export class ItemStore {
+    #items = new Map();
+    /** itemId -> field path -> accumulated text. */
+    #deltas = new Map();
+    /** First-opened order; an itemId appears exactly once. */
+    #order = [];
+    #terminalUnknown = new Set();
+    #ephemeralSessionDiscarded = false;
+    /**
+     * Apply an `item/started` | `item/updated` | `item/completed` payload.
+     * Replace iff the incoming revision is strictly higher (INV-003).
+     */
+    apply(item) {
+        this.#assertSessionActive();
+        const held = this.#items.get(item.itemId);
+        if (held === undefined) {
+            this.#items.set(item.itemId, item);
+            this.#order.push(item.itemId);
+            return { kind: "inserted", itemId: item.itemId };
+        }
+        if (item.revision <= held.revision) {
+            return {
+                kind: "ignoredStaleRevision",
+                itemId: item.itemId,
+                held: held.revision,
+                offered: item.revision,
+            };
+        }
+        this.#items.set(item.itemId, item);
+        return {
+            kind: "replaced",
+            itemId: item.itemId,
+            from: held.revision,
+            to: item.revision,
+        };
+    }
+    /**
+     * Apply an `item/delta`: a UTF-8-safe append to the open item's field named
+     * by `field` (default `"text"`), contiguous and lossless in cursor order.
+     * The concatenation of all deltas for a field path equals that field's
+     * value on the final `item/completed` object (INV-004, tdd SS4.3.1).
+     */
+    applyDelta(itemId, delta, field = "text") {
+        this.#assertSessionActive();
+        let fields = this.#deltas.get(itemId);
+        if (fields === undefined) {
+            fields = new Map();
+            this.#deltas.set(itemId, fields);
+        }
+        fields.set(field, (fields.get(field) ?? "") + delta);
+        if (!this.#items.has(itemId)) {
+            return { kind: "bufferedForAbsentItem", itemId, field };
+        }
+        return {
+            kind: "appended",
+            itemId,
+            field,
+            length: (fields.get(field) ?? "").length,
+        };
+    }
+    /** The accumulated delta text for a field path, or `undefined` if none. */
+    accumulated(itemId, field = "text") {
+        return this.#deltas.get(itemId)?.get(field);
+    }
+    /** Every field path that has accumulated deltas for this item. */
+    accumulatedFields(itemId) {
+        const fields = this.#deltas.get(itemId);
+        return fields === undefined ? [] : [...fields.keys()].sort();
+    }
+    get(itemId) {
+        return this.#items.get(itemId);
+    }
+    has(itemId) {
+        return this.#items.has(itemId);
+    }
+    /** Items in first-opened order (tdd SS4.9.1). */
+    list() {
+        const out = [];
+        for (const id of this.#order) {
+            const item = this.#items.get(id);
+            if (item !== undefined)
+                out.push(item);
+        }
+        return out;
+    }
+    /** The id of the most recently opened item, or `undefined` when empty. */
+    lastOpenedItemId() {
+        return this.#order.at(-1);
+    }
+    get size() {
+        return this.#items.size;
+    }
+    /**
+     * Seed from a snapshot's `state.items` (tdd SS4.9.1): every item at its
+     * latest revision at the snapshot cursor, in first-opened order. Seeding
+     * REPLACES the store — a snapshot is authoritative (tdd SS4.9), never
+     * merged into stale local state.
+     *
+     * Delta accumulators are intentionally NOT seeded: a snapshot carries
+     * streamed fields at their accumulated-so-far values on the item itself,
+     * and `view/page` never replays ephemeral-sourced deltas (tdd SS4.7.3).
+     */
+    seed(items) {
+        this.#assertSessionActive();
+        this.#items.clear();
+        this.#deltas.clear();
+        this.#terminalUnknown.clear();
+        this.#order.length = 0;
+        for (const item of items) {
+            if (!this.#items.has(item.itemId))
+                this.#order.push(item.itemId);
+            this.#items.set(item.itemId, item);
+        }
+    }
+    /**
+     * Permanently discard an ephemeral session after abnormal host death.
+     *
+     * The last wire item remains byte-for-byte intact: terminal-unknown is a
+     * client display annotation, never a fabricated `item/completed` or wire
+     * status (SS2.13.3b / SS4.4.3). Further events and snapshot seeding are
+     * refused because this session has no resume surface.
+     */
+    markEphemeralHostDeath(
+    // The store never knows wire shapes (INV-001), so the caller supplies the
+    // in-progress probe — the slice-3 `SessionFold` binding passes
+    // `(item) => item.status === "inProgress"` against the generated `Item`
+    // type, where the compiler checks the field (review round 2026-08-15).
+    isInProgress) {
+        if (!this.#ephemeralSessionDiscarded) {
+            for (const item of this.#items.values()) {
+                if (isInProgress(item))
+                    this.#terminalUnknown.add(item.itemId);
+            }
+            this.#ephemeralSessionDiscarded = true;
+        }
+        return this.#order
+            .filter((itemId) => this.#terminalUnknown.has(itemId))
+            .map((itemId) => ({ kind: "terminalUnknown", itemId }));
+    }
+    isTerminalUnknown(itemId) {
+        return this.#terminalUnknown.has(itemId);
+    }
+    get ephemeralSessionDiscarded() {
+        return this.#ephemeralSessionDiscarded;
+    }
+    #assertSessionActive() {
+        if (this.#ephemeralSessionDiscarded) {
+            throw new MuseSessionDiscardedError("ephemeral session was discarded after abnormal host death");
+        }
+    }
+}