@ttsc/graph 0.30.4 → 0.31.0

package/lib/model/TtscGraphSessionState.js

@@ -0,0 +1,417 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TtscGraphSessionState = void 0;
+const TtscGraphMemory_1 = require("./TtscGraphMemory");
+const TtscGraphShardStore_1 = require("./TtscGraphShardStore");
+const loadGraph_1 = require("./loadGraph");
+const GRAPH_SNAPSHOT_PROTOCOL_VERSION = 1;
+/**
+ * Queue, request correlation and generation ownership for one resident graph.
+ *
+ * The host supplies artifact synchronization and validated line decoding; this
+ * owner accepts typed envelopes, atomically replaces graph generations, and
+ * retires a peer when its transport or generation cannot be trusted. It is
+ * internal to the graph facade, not an alternate public session API.
+ *
+ * @evidence contracts/common.md#principled-implementation Serialized admission and identity-checked reply settlement protect one atomic shard generation across abort, close and peer replacement.
+ * @evidence contracts/common.md#clear-and-simple-design Artifact discovery and generated schema decoding remain host responsibilities; this owner controls queue, pending replies, memory and shard retirement.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Typed receive requires validated envelopes from the actual decoder; it supplies no schema substitute or fabricated fallback facts.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the validated-input premise and internal ownership; receive and failure events distinguish peer identity and lifecycle effects.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms graph/receive/close own admission, frame processing and retirement; this declaration groups their retained state.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work graph/receive/close establish continued peer/model reuse, not the class descriptor independently.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources graph/receive/close control acquisition and release; the class declaration adds no separate lifecycle transition.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation keeps queue and pending-request state in memory and reaches the process only through the Host and Connection operations it is given.
+ */
+class TtscGraphSessionState {
+    host;
+    child;
+    nextId = 0;
+    pending = new Map();
+    queue = Promise.resolve();
+    waiting;
+    current;
+    shardStore = new TtscGraphShardStore_1.TtscGraphShardStore();
+    closed = false;
+    closing;
+    retirements = new Set();
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * Whether artifact refresh currently has a peer to update.
+     *
+     * @evidence contracts/common.md#principled-implementation The presence of owned peer state distinguishes an active publication target from a yet-unopened or retired session.
+     * @evidence contracts/common.md#clear-and-simple-design One read-only query lets the artifact facade retain its original live-peer refresh precondition.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Ownership is observed directly rather than guessed from previous artifact values or a clock.
+     * @evidence contracts/common.md#meaningful-documentation The headline states why the facade asks this ownership question.
+     * @evidence contracts/performance.md#efficient-algorithms This constant-time reference check scans no pending or shard population.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The query returns current ownership and coordinates no completed computation.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources It acquires or releases nothing; graph and close own the queried peer.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation reads one field.
+     */
+    hasPeer() {
+        return this.child !== undefined;
+    }
+    /**
+     * Refresh one graph for callers admitted before its freshness check starts.
+     *
+     * Later arrivals form another group. Cancellation releases only that caller;
+     * the native request is aborted when every caller in its group has left.
+     *
+     * @evidence contracts/common.md#principled-implementation A group closes before refresh starts, so its one validation is after every member's admission; later arrivals cannot inherit a check already in progress. Each consumer settles once and owns only its cancellation.
+     * @evidence contracts/common.md#clear-and-simple-design Admission groups callers, refresh owns artifact synchronization and atomic model replacement, and the group's controller owns the shared producer independently of caller signals.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Sharing is justified by admission before validation, without a clock, cooldown or quiet-watcher assumption. The last active consumer's abort cancels shared work and retires a peer with an outstanding native request rather than returning fabricated facts.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs state the admission boundary and distinguish individual cancellation from producer cancellation; receive separately states its validation premise.
+     * @evidence contracts/performance.md#efficient-algorithms Set insertion/removal is expected constant time per consumer and settlement visits each live consumer once. One frame and artifact validation serve each group; changed transactions retain complete validation and reference scans while equivalent immutable projection components and ordered index buckets are reused.
+     * @evidence contracts/performance.md#reuse-equivalent-work Callers admitted before a refresh starts share its validation and immutable model. A later group validates again, changed responses replace memory atomically, and retirement clears reusable generation state.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Queued groups and live consumer sets grow with outstanding demand. Settlement removes consumers and abort listeners immediately; completed queue callbacks release their groups, while one current peer/model/store remains session-owned.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation queues a request and calls injected host operations; it opens no file or process itself.
+     */
+    graph(options = {}) {
+        if (this.closed) {
+            return Promise.reject(new Error("@ttsc/graph: native session is closed"));
+        }
+        let resolve;
+        let reject;
+        let group = this.waiting;
+        const created = group === undefined;
+        if (group === undefined) {
+            group = {
+                controller: new AbortController(),
+                started: false,
+                consumers: new Set(),
+            };
+            this.waiting = group;
+        }
+        const consumer = {
+            settled: false,
+            resolve: undefined,
+            reject: undefined,
+        };
+        const result = new Promise((res, rej) => {
+            resolve = (graph) => {
+                if (consumer.settled)
+                    return;
+                consumer.settled = true;
+                group.consumers.delete(consumer);
+                options.signal?.removeEventListener("abort", cancelQueued);
+                res(graph);
+            };
+            reject = (error) => {
+                if (consumer.settled)
+                    return;
+                consumer.settled = true;
+                group.consumers.delete(consumer);
+                options.signal?.removeEventListener("abort", cancelQueued);
+                rej(error);
+            };
+        });
+        const cancelQueued = () => {
+            reject(cancelledError(options.signal));
+            if (group.started && group.consumers.size === 0)
+                group.controller.abort(options.signal?.reason);
+        };
+        consumer.resolve = resolve;
+        consumer.reject = reject;
+        group.consumers.add(consumer);
+        if (options.signal?.aborted) {
+            reject(cancelledError(options.signal));
+        }
+        else {
+            options.signal?.addEventListener("abort", cancelQueued, { once: true });
+        }
+        if (!created)
+            return result;
+        this.queue = this.queue
+            .catch(() => undefined)
+            .then(async () => {
+            group.started = true;
+            if (this.waiting === group)
+                this.waiting = undefined;
+            if (group.consumers.size === 0)
+                return;
+            try {
+                const graph = await this.refresh(group.controller.signal);
+                for (const item of group.consumers)
+                    item.resolve(graph);
+            }
+            catch (error) {
+                for (const item of group.consumers)
+                    item.reject(asError(error));
+            }
+        });
+        return result;
+    }
+    /**
+     * Close the native session. Safe to call more than once.
+     *
+     * Retires artifact sidecars and rejects pending native requests. Queued
+     * requests observe the closed state before they can create another child.
+     *
+     * @evidence contracts/common.md#principled-implementation The closed flag precedes sidecar disposal and child failure, so every pending or subsequent native operation observes retired ownership.
+     * @evidence contracts/common.md#clear-and-simple-design The explicit close path reuses failChild/failPending cleanup instead of a second cancellation implementation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Disposing a session cannot trigger a compensating respawn or pretend outstanding requests succeeded.
+     * @evidence contracts/common.md#meaningful-documentation Native prose documents idempotence, pending rejection and queued-request behavior.
+     * @evidence contracts/performance.md#efficient-algorithms Shutdown invokes the artifact host once and visits pending owners once; the actual peer adapter owns any native kill timer.
+     * @evidence contracts/performance.md#reuse-equivalent-work Closure ends this owner's permission to reuse native Program, model and sidecars; subsequent graph calls reject.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The host retires artifact sidecars, pending listeners are removed, current model/shards are cleared and peer.close transfers reader/process disposal to its actual adapter.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation marks the state closed and calls the injected host and peer close operations; the process work lives there.
+     */
+    close() {
+        if (this.closing !== undefined)
+            return this.closing;
+        this.closed = true;
+        const hostClose = Promise.resolve().then(() => this.host.close());
+        void hostClose.catch(() => undefined);
+        const error = new Error("@ttsc/graph: native session closed");
+        if (this.child !== undefined)
+            this.failChild(this.child, error);
+        else
+            this.failPending(error);
+        this.closing = (async () => {
+            await this.queue;
+            const results = await Promise.allSettled([
+                hostClose,
+                ...this.retirements,
+            ]);
+            const failures = results
+                .filter((result) => result.status === "rejected")
+                .map((result) => result.reason);
+            if (failures.length > 0)
+                throw new AggregateError(failures, "@ttsc/graph: session shutdown failed");
+        })();
+        void this.closing.catch(() => undefined);
+        return this.closing;
+    }
+    async refresh(signal) {
+        if (this.closed)
+            throw new Error("@ttsc/graph: native session is closed");
+        await Promise.all(this.retirements);
+        if (this.closed)
+            throw new Error("@ttsc/graph: native session is closed");
+        // The protocol version and envelope shape were settled by the host decoder,
+        // before this frame was ever routed here.
+        await this.host.beforeRequest(signal);
+        if (this.closed)
+            throw new Error("@ttsc/graph: native session is closed");
+        const response = await this.request(signal);
+        this.assertResponseSemantics(response);
+        if (response.error !== undefined) {
+            throw new Error(`@ttsc/graph: ${response.error}`);
+        }
+        if (response.changed) {
+            if (response.snapshot !== undefined) {
+                try {
+                    this.current = this.shardStore.applyProjection(response.snapshot, (dump) => TtscGraphMemory_1.TtscGraphMemory.fromResident(dump, this.current));
+                }
+                catch (error) {
+                    const failure = asError(error);
+                    if (this.child !== undefined)
+                        this.failChild(this.child, failure);
+                    throw failure;
+                }
+            }
+            else if (response.dump !== undefined) {
+                // A serve-protocol-v1 binary predating graph shard negotiation ignores
+                // the optional request field and retains the complete-dump response.
+                this.current = TtscGraphMemory_1.TtscGraphMemory.from(response.dump);
+            }
+            else {
+                throw new Error(`@ttsc/graph: native ${response.mode} response omitted both graph snapshot protocol v${String(GRAPH_SNAPSHOT_PROTOCOL_VERSION)} data and a compatible dump`);
+            }
+        }
+        if (this.current === undefined) {
+            throw new Error("@ttsc/graph: native session returned no initial graph snapshot");
+        }
+        return this.current;
+    }
+    assertResponseSemantics(response) {
+        const bodies = Number(response.dump !== undefined) +
+            Number(response.snapshot !== undefined);
+        let problem;
+        if (response.error !== undefined) {
+            if (response.mode !== "error" || response.changed || bodies !== 0) {
+                problem = "an error response carried snapshot state";
+            }
+        }
+        else if (response.mode === "error") {
+            problem = "an error-mode response omitted its error";
+        }
+        else if (response.changed) {
+            if (response.mode === "unchanged" || bodies !== 1) {
+                problem = "a changed response did not carry exactly one snapshot body";
+            }
+        }
+        else if (response.mode !== "unchanged" || bodies !== 0) {
+            problem = "an unchanged response carried changed mode or snapshot state";
+        }
+        if (problem === undefined)
+            return;
+        const error = new Error(`@ttsc/graph: native session returned ${problem}`);
+        if (this.child !== undefined)
+            this.failChild(this.child, error);
+        throw error;
+    }
+    request(signal) {
+        if (signal?.aborted)
+            throw cancelledError(signal);
+        const child = this.ensureChild();
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            const pending = {
+                child,
+                resolve,
+                reject,
+                signal,
+            };
+            if (signal !== undefined) {
+                pending.abort = () => this.failChild(child, cancelledError(signal, child));
+                signal.addEventListener("abort", pending.abort, { once: true });
+            }
+            this.pending.set(id, pending);
+            if (signal?.aborted) {
+                pending.abort();
+                return;
+            }
+            child.write(`${JSON.stringify({
+                id,
+                graphSnapshotVersion: GRAPH_SNAPSHOT_PROTOCOL_VERSION,
+                // Empty when the project publishes nothing, which withdraws whatever
+                // the server holds: a publisher the user removed must stop being
+                // answered with, and omitting the field instead would say only that
+                // this client has no opinion. Omitted only before a child exists,
+                // which no request reaches.
+                artifacts: this.host.artifacts(),
+            })}\n`, (error) => {
+                if (error === null || error === undefined)
+                    return;
+                if (this.pending.get(id) !== pending)
+                    return;
+                this.failChild(child, new Error(`@ttsc/graph: could not request native snapshot: ${error.message}`));
+            });
+        });
+    }
+    ensureChild() {
+        if (this.closed)
+            throw new Error("@ttsc/graph: native session is closed");
+        if (this.child !== undefined && this.child.alive())
+            return this.child;
+        const child = this.host.open({
+            line: (line) => {
+                if (this.child !== child)
+                    return;
+                try {
+                    this.receive(child, this.host.decode(line));
+                }
+                catch (error) {
+                    this.failChild(child, asError(error));
+                }
+            },
+            error: (error) => this.failChild(child, new Error(`@ttsc/graph: native session failed: ${error.message}`)),
+            exit: (code, signal) => this.failChild(child, new Error(`@ttsc/graph: native session exited (code=${String(code)}, signal=${String(signal)})${stderrSuffix(child)}`)),
+        });
+        this.child = child;
+        return child;
+    }
+    /**
+     * Admit a decoded envelope from the current peer; stale peers cannot publish.
+     *
+     * Callers must supply the actual decoder's validated envelope. This operation
+     * checks body schema agreement and correlation; it does not substitute for
+     * full envelope shape validation.
+     *
+     * @evidence contracts/common.md#principled-implementation Peer identity precedes body compatibility and request-id lookup; only the matching pending owner may receive this typed envelope.
+     * @evidence contracts/common.md#clear-and-simple-design Wire shape belongs to the decoder; body version and pending correlation belong to the state that will consume its generation.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Unknown request ids cannot settle the live caller, and incompatible body versions retire ownership rather than trusting absent fields.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the validated-input premise and the checks this operation actually performs.
+     * @evidence contracts/performance.md#efficient-algorithms Schema checks and pending-map lookup are constant-time before one settlement; body facts are processed by refresh only for the matching request.
+     * @evidence contracts/performance.md#reuse-equivalent-work This routes a validated frame; refresh alone permits memory reuse after an unchanged response, and schema failure clears the reusable peer generation.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Settlement removes exactly one pending entry and its abort listener; mismatch retirement clears this peer's current model/store and fails its pending owners.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation correlates a decoded envelope with its pending request in memory.
+     */
+    receive(child, response) {
+        if (this.child !== child)
+            return;
+        // The envelope's version is not the body's, and only the envelope has been
+        // held to one so far. A producer can speak this protocol and still carry a
+        // dump from another schema — the two move apart the moment a node field is
+        // added without the frame around it changing — and then the facts that field
+        // holds are silently absent rather than refused. `literals` is exactly that
+        // shape: an older producer resolves no value set, so a union comes back
+        // looking like a type with no members. Hold the body to its own number too,
+        // once the frame is understood.
+        if ((response.dump !== undefined &&
+            response.dump.provenance.schemaVersion !== loadGraph_1.DUMP_SCHEMA_VERSION) ||
+            (response.snapshot !== undefined &&
+                response.snapshot.schemaVersion !== loadGraph_1.DUMP_SCHEMA_VERSION)) {
+            // Session-wide, for the same reason the protocol mismatch above is: it is
+            // the wrong binary, not one bad frame.
+            this.failChild(child, new Error(`@ttsc/graph: ttscgraph sends dump schema v${String(response.dump?.provenance.schemaVersion ??
+                response.snapshot?.schemaVersion)}, this client reads v${String(loadGraph_1.DUMP_SCHEMA_VERSION)}. ` +
+                "Install a matching `ttsc` (the binary resolves from the target " +
+                "project, or from TTSC_GRAPH_BINARY)."));
+            return;
+        }
+        const pending = this.pending.get(response.id);
+        if (pending === undefined || pending.child !== child)
+            return;
+        this.settlePending(response.id, pending, response);
+    }
+    failChild(child, error) {
+        if (this.child !== child)
+            return;
+        this.child = undefined;
+        this.current = undefined;
+        this.shardStore = new TtscGraphShardStore_1.TtscGraphShardStore();
+        child.close(false);
+        this.failPending(error, child);
+        // Even an exited process must join its stdio before release is known.
+        const retirement = Promise.resolve(child.close(true));
+        this.retirements.add(retirement);
+        void retirement.then(() => this.retirements.delete(retirement), () => undefined);
+    }
+    failPending(error, child) {
+        for (const [id, pending] of this.pending) {
+            if (child === undefined || pending.child === child) {
+                this.settlePending(id, pending, error);
+            }
+        }
+    }
+    settlePending(id, pending, result) {
+        if (this.pending.get(id) !== pending)
+            return;
+        this.pending.delete(id);
+        if (pending.signal !== undefined && pending.abort !== undefined) {
+            pending.signal.removeEventListener("abort", pending.abort);
+        }
+        if (result instanceof Error)
+            pending.reject(result);
+        else
+            pending.resolve(result);
+    }
+}
+exports.TtscGraphSessionState = TtscGraphSessionState;
+function cancelledError(signal, child) {
+    const error = new Error(`@ttsc/graph: native snapshot request cancelled${abortDetail(signal)}${child === undefined ? "" : stderrSuffix(child)}`);
+    error.name = "AbortError";
+    return error;
+}
+function abortDetail(signal) {
+    const reason = signal?.reason;
+    if (reason === undefined)
+        return "";
+    try {
+        return `: ${reason instanceof Error ? reason.message : String(reason)}`;
+    }
+    catch {
+        return "";
+    }
+}
+function stderrSuffix(child) {
+    const stderr = child.stderr.trim();
+    return stderr === "" ? "" : `: ${stderr}`;
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+//# sourceMappingURL=TtscGraphSessionState.js.map

package/lib/model/TtscGraphSessionState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtscGraphSessionState.js","sourceRoot":"","sources":["../../src/model/TtscGraphSessionState.ts"],"names":[],"mappings":"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"}

package/lib/model/TtscGraphShardStore.d.ts

@@ -1,6 +1,21 @@
 import { ITtscGraphDump } from "../structures/ITtscGraphDump";
 import { ITtscGraphSnapshot } from "../structures/ITtscGraphSnapshot";
-/** Atomic validator and assembler for native `ttscgraph` shard transactions. */
+import { TtscGraphReadonly } from "./TtscGraphReadonly";
+/**
+ * Atomic validator and assembler for native ttscgraph shard transactions.
+ *
+ * A transaction is committed only after base coordinates, digests, ownership
+ * and the complete manifest agree. Rejected transactions preserve prior state.
+ *
+ * @evidence contracts/common.md#principled-implementation Content digests and consecutive base coordinates qualify source-owned shards before cross-shard assembly and atomic state replacement.
+ * @evidence contracts/common.md#clear-and-simple-design The store owns committed generation state; private validation and assembly helpers keep wire checks outside consumers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Stale bases or inconsistent contents are rejected rather than merged under compensating guesses.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the commit boundary and preserved prior state; public methods describe validation and canonical hashing.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms apply owns staged validation and assembly algorithms; this declaration defines committed state.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work apply establishes permission to reuse unchanged shard payloads.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources apply owns population replacement and the session owns store retirement; the class declaration performs no independent lifecycle transition.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation validates and assembles in-memory shard objects; no file, path or process.
+ */
 export declare class TtscGraphShardStore {
     static readonly PROTOCOL_VERSION = 1;
     private sequence;
@@ -8,9 +23,55 @@ export declare class TtscGraphShardStore {
     private project;
     private tsconfig;
     private shards;
-    /** Validate and atomically commit one complete or base-generation delta. */
+    /**
+     * Validate and atomically commit one complete or base-generation delta.
+     *
+     * Throws on invalid coordinates, repeated changes, content/manifest mismatch
+     * or inconsistent ownership. The prior generation remains committed until
+     * full dump assembly succeeds. Retained shard records are detached and
+     * frozen; the returned dump owns mutable copies of those records.
+     *
+     * @evidence contracts/common.md#principled-implementation A staged shard map validates changes, exact manifest and generation hash before assembly establishes node/edge/config ownership and commits state together.
+     * @evidence contracts/common.md#clear-and-simple-design One operation owns transaction staging and the final state swap; helper validators do not independently mutate committed fields.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A bad delta is not retried against an invented base or partially applied to the resident store.
+     * @evidence contracts/common.md#meaningful-documentation Native prose documents rejection causes and the unchanged-state guarantee before the tags.
+     * @evidence contracts/performance.md#efficient-algorithms Map staging and manifest/ownership scans are linear in shards and facts; canonical hashes cost changed content bytes and deterministic dump sorting costs O(N log N + E log E).
+     * @evidence contracts/performance.md#reuse-equivalent-work Unchanged frozen shard payloads retain their validated digest in the staged map; only upserts are rehashed, while the generation manifest validates continued membership and mutable output copies cannot change retained facts.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The store retains only the current manifest's shards and coordinates; commit drops removed payloads and rejection leaves the prior generation intact.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation validates and assembles shard objects in memory and hashes JSON text with node:crypto; no file, path or process.
+     */
     apply(transaction: ITtscGraphSnapshot.ITransaction): ITtscGraphDump;
-    /** SHA-256 over the producer's deterministic Go JSON encoding. */
+    /**
+     * Validate a staged immutable population and commit only after projection.
+     *
+     * The callback borrows store-owned frozen facts, not caller DTOs. A thrown
+     * projection leaves every committed coordinate and shard unchanged.
+     *
+     * @evidence contracts/common.md#principled-implementation Full transaction/manifest/ownership validation precedes projection and the synchronous commit; callback failure cannot publish a partial generation.
+     * @evidence contracts/common.md#clear-and-simple-design Public mutable apply and resident immutable projection share the same staged validator and commit boundary.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Immutable borrowing does not remove any digest, universe, owner or edge check; apply still returns a detached mutable DTO.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states input ownership and callback-failure atomicity.
+     * @evidence contracts/performance.md#efficient-algorithms Changed shards are cloned/hashed once; full manifest/ownership scans and deterministic sorting remain. The resident callback avoids full nested mutable materialization.
+     * @evidence contracts/performance.md#reuse-equivalent-work Retained frozen payload identities survive staged validation, qualifying downstream reuse independently of caller-owned transactions.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Commit retains only current shards; rejected staging and callback values remain local, with prior state intact.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Hashes and validates in-memory records without filesystem or process operations.
+     */
+    applyProjection<T>(transaction: ITtscGraphSnapshot.ITransaction, project: (dump: TtscGraphReadonly<ITtscGraphDump>) => T): T;
+    /**
+     * SHA-256 over the producer's deterministic Go JSON encoding.
+     *
+     * JSON-serializable wire shards use producer field order and Go's escaping
+     * for HTML-sensitive characters and Unicode line separators.
+     *
+     * @evidence contracts/common.md#principled-implementation Canonical Go-compatible JSON escaping and UTF-8 SHA-256 reproduce the producer's content witness for the supplied wire shard.
+     * @evidence contracts/common.md#clear-and-simple-design One helper shares canonical digest logic with generation verification.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Digest checks compare content rather than a size/time proxy or expected fixture hash.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states serializability, ordering and escaping premises needed for cross-language digest equivalence.
+     * @evidence contracts/performance.md#efficient-algorithms Serialization preserves the wire object's insertion order, escapes Go-sensitive characters in one text pass and hashes the resulting bytes once.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This digest primitive computes one shard identity; apply coordinates continued reuse of validated payloads.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The digest string transfers to its caller and the canonical buffer is local to this computation.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation hashes the canonical JSON text of one shard with node:crypto; no file, path or process.
+     */
     static shardDigest(shard: ITtscGraphSnapshot.IShard): string;
     private assertCoordinates;
 }