@ttsc/graph 0.30.4 → 0.31.0

package/lib/model/TtscGraphMemory.d.ts

@@ -1,7 +1,10 @@
 import { ITtscGraphDump } from "../structures/ITtscGraphDump";
 import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { type TtscGraphReadonly } from "./TtscGraphReadonly";
 import { TtscGraphSourceReader } from "./TtscGraphSourceReader";
+type SnapshotNode = TtscGraphReadonly<ITtscGraphNode>;
+type SnapshotEdge = TtscGraphReadonly<ITtscGraphEdge>;
 /**
  * The in-memory resident graph the MCP tools answer from.
  *
@@ -12,8 +15,23 @@ import { TtscGraphSourceReader } from "./TtscGraphSourceReader";
  * implementation relationships are checker facts already present in the dump.
  * Every tool call is then a lookup or traversal over the indexes built here;
  * nothing recompiles.
+ *
+ * Snapshot records are owned copies and recursively frozen. Borrowed node
+ * records and edge buckets have recursively readonly types, so caller changes
+ * cannot invalidate generation-keyed indexes and caches.
+ *
+ * @evidence contracts/common.md#principled-implementation Native facts are preserved while module/file folding, exact owner suffixes and artifact parents synthesize only this layer's structural relationships.
+ * @evidence contracts/common.md#clear-and-simple-design One snapshot owns node, name, relation and citation indexes; individual accessors expose that shared model.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Export surfaces remain checker relationships rather than guessed from local export flags or fixture paths.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs distinguish compiler facts from synthesized structure, and accessors explain lookup and absence semantics.
+ * @evidenceExclude contracts/performance.md#efficient-algorithms from and fromResident own projection/index construction through their private helpers; this class declaration describes the resulting representation.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work from and fromResident establish each shared generation; the declaration does not independently coordinate requests.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources from and fromResident transfer generation storage to their caller; session/caller release owns its duration rather than this declaration.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation an in-memory index over parsed facts; the source reader it owns is the only file reader.
  */
 export declare class TtscGraphMemory {
+    private readonly projection?;
+    private readonly nodeKeys;
     private readonly byId;
     private readonly outEdges;
     private readonly inEdges;
@@ -23,26 +41,129 @@ export declare class TtscGraphMemory {
     /** The absolute project root the dump was built for. */
     readonly project: string;
     /** Every post-fold node, including refined properties and file containers. */
-    readonly nodes: readonly ITtscGraphNode[];
+    readonly nodes: readonly SnapshotNode[];
     /** Every edge, raw plus synthesized containment. */
-    readonly edges: readonly ITtscGraphEdge[];
+    readonly edges: readonly SnapshotEdge[];
     /** Provenance-gated source display facts cached for this exact snapshot. */
     readonly source: TtscGraphSourceReader;
     private constructor();
-    /** Build a model from a parsed dump, synthesizing structural relationships. */
+    /**
+     * Build a model from a parsed dump, synthesizing structural relationships.
+     *
+     * The parsed dump must describe one valid generation. Node records are copied
+     * before member-kind refinement so the caller's dump is unchanged.
+     *
+     * @evidence contracts/common.md#principled-implementation Synthesis reanchors native module exports and derives containment from exact owner handles and disambiguating declaration ranges before constructing the indexes for that generation.
+     * @evidence contracts/common.md#clear-and-simple-design Synthesis owns representation changes; the private constructor owns index construction.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No export edges are guessed from flags, and artifact ownership follows its producer rather than TypeScript id heuristics.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the valid-generation precondition and caller-dump preservation.
+     * @evidence contracts/performance.md#efficient-algorithms Synthesis indexes nodes by file and handle, scanning only colliding owner buckets once per member; owned snapshot copying and index construction scan nodes, edges and facets; per-node target sets make citation deduplication linear in tag population without repeatedly scanning carrier buckets.
+     * @evidence contracts/performance.md#reuse-equivalent-work One model builds all indexes once over owned frozen facts and buckets, so external mutation cannot invalidate shared generation identity.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources The model retains node/edge arrays, lookup indexes and source cache proportional to its generation; the session or direct caller releases the whole model when no longer needed.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation builds indexes from a parsed dump object and reads no file; source text goes through TtscGraphSourceReader.
+     */
     static from(dump: ITtscGraphDump): TtscGraphMemory;
-    /** The node with this id, or undefined. */
-    node(id: string): ITtscGraphNode | undefined;
-    /** Edges leaving a node (the node is the `from`). */
-    outgoing(id: string): readonly ITtscGraphEdge[];
-    /** Edges entering a node (the node is the `to`). */
-    incoming(id: string): readonly ITtscGraphEdge[];
-    /** Every node whose simple name equals `name`. */
-    named(name: string): readonly ITtscGraphNode[];
-    /** Every non-file node whose simple or owner-qualified symbol handle matches. */
-    symbols(handle: string): readonly ITtscGraphNode[];
-    /** Every workspace node on its module's export surface. */
-    exported(): ITtscGraphNode[];
+    /**
+     * Project validated frozen resident facts while retaining equivalent work.
+     *
+     * The shard store invokes this before committing its staged generation. Each
+     * model owns new index maps and a new source reader; unchanged facts and
+     * ordered index buckets may be shared with the previous immutable model.
+     *
+     * @evidence contracts/common.md#principled-implementation Validated frozen fact identity and complete projection dependencies qualify component reuse; construction never mutates the preceding model.
+     * @evidence contracts/common.md#clear-and-simple-design The projection owner handles synthesis components and this model owns ordered query indexes and source authority.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts This internal path requires the store's complete validation; public from still detaches caller DTOs and no graph facts or validation are omitted.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states the validated-input premise, staged commit and per-generation source-reader boundary.
+     * @evidence contracts/performance.md#efficient-algorithms Projection scans references and rebuilds only invalidated components; index scans retain equal buckets without allocating their arrays, while maps and generation arrays remain linear in facts.
+     * @evidence contracts/performance.md#reuse-equivalent-work Same-file owner/module dependencies and metadata qualify immutable components; exact ordered reference equality qualifies node/relation/citation buckets. New source adjudication is intentionally independent.
+     * @evidence contracts/performance.md#bound-retention-and-release-resources Each model retains only its current components, facts, indexes and source reader; unchanged values may also belong to retained old models, without a link retaining prior model generations.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation Processes only frozen in-memory facts; source IO remains with the per-generation reader.
+     */
+    static fromResident(dump: TtscGraphReadonly<ITtscGraphDump>, previous?: TtscGraphMemory): TtscGraphMemory;
+    /**
+     * The node with this exact stable id, or undefined when absent.
+     *
+     * @evidence contracts/common.md#principled-implementation The id index returns the snapshot's exact node without conflating same-named declarations.
+     * @evidence contracts/common.md#clear-and-simple-design This accessor delegates identity lookup to the single model index.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Missing identities are not replaced by name-matched candidates.
+     * @evidence contracts/common.md#meaningful-documentation The native headline states exact-id and missing-result semantics.
+     * @evidence contracts/performance.md#efficient-algorithms Exact identity requires one construction-time map lookup and no node scan.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The accessor borrows a completed id index; from owns shared construction.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Returning an existing node acquires no handle or independent retained entry.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation one Map lookup over in-memory facts.
+     */
+    node(id: string): SnapshotNode | undefined;
+    /**
+     * Edges leaving a node (the node is the from endpoint), empty when absent.
+     *
+     * @evidence contracts/common.md#principled-implementation The outgoing index preserves native and synthesized edge direction for the exact node id.
+     * @evidence contracts/common.md#clear-and-simple-design The accessor exposes one readonly bucket without rescanning the edge population.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Absence returns no edges rather than inferred calls from matching names.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states endpoint direction, missing behavior and the readonly return contract.
+     * @evidence contracts/performance.md#efficient-algorithms A map lookup returns the outgoing bucket without traversing unrelated edges.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work from owns the reused adjacency computation; the accessor only borrows its result.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Existing buckets remain generation-owned; the accessor acquires no separate resource.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation one Map lookup over in-memory edges.
+     */
+    outgoing(id: string): readonly SnapshotEdge[];
+    /**
+     * Edges entering a node (the node is the to endpoint), empty when absent.
+     *
+     * @evidence contracts/common.md#principled-implementation The incoming index selects edges by their original target identity.
+     * @evidence contracts/common.md#clear-and-simple-design The accessor shares construction-time adjacency instead of implementing another traversal.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts No callers are guessed from text or substituted when the bucket is absent.
+     * @evidence contracts/common.md#meaningful-documentation Native prose states incoming direction and empty absence before the tags.
+     * @evidence contracts/performance.md#efficient-algorithms A map lookup returns the incoming bucket without scanning graph edges.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This accessor borrows the index already shared by from rather than coordinating another producer.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources It retains no state beyond the generation's existing edge bucket.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation one Map lookup over in-memory edges.
+     */
+    incoming(id: string): readonly SnapshotEdge[];
+    /**
+     * Every node whose simple name equals name, empty when absent.
+     *
+     * @evidence contracts/common.md#principled-implementation The exact simple-name index returns all matching identities, preserving ambiguity.
+     * @evidence contracts/common.md#clear-and-simple-design A readonly bucket supplies name lookup independently of ranked search.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts Multiple declarations remain candidates rather than selecting the expected fixture's declaration.
+     * @evidence contracts/common.md#meaningful-documentation Native prose describes exact matching and empty absence.
+     * @evidence contracts/performance.md#efficient-algorithms Exact-name lookup performs one map access instead of filtering all nodes.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work Name-index construction and validity belong to from, not this borrowed bucket lookup.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The returned bucket remains generation-owned with no separately retained cache or handle.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation one Map lookup over in-memory facts.
+     */
+    named(name: string): readonly SnapshotNode[];
+    /**
+     * Every non-file node whose simple or owner-qualified symbol handle matches.
+     *
+     * Matches borrow a frozen generation-owned bucket; no match returns an empty
+     * readonly list, and several matches remain distinct.
+     *
+     * @evidence contracts/common.md#principled-implementation The symbol index includes simple and qualified handles but excludes file containers from symbol resolution.
+     * @evidence contracts/common.md#clear-and-simple-design One shared index serves all exact-handle consumers without duplicate resolution policy.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The accessor preserves ambiguity rather than fabricating a unique resolution.
+     * @evidence contracts/common.md#meaningful-documentation Native prose explains non-file selection, qualified handles and multiple/missing matches.
+     * @evidence contracts/performance.md#efficient-algorithms Both simple and qualified handles use the construction-time symbol index, so this accessor performs one map lookup without scanning candidates.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work This borrows one already-built symbol bucket; model construction owns shared work.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Existing candidates remain frozen generation-owned records in a borrowed bucket; the accessor acquires no separate resource or retained entry.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation one Map lookup over in-memory facts.
+     */
+    symbols(handle: string): readonly SnapshotNode[];
+    /**
+     * Every workspace node marked exported by the native declaration facts.
+     *
+     * External declarations are omitted. Module-specific re-export membership is
+     * available separately through exports edges.
+     *
+     * @evidence contracts/common.md#principled-implementation Filtering exported flags and excluding external nodes yields local exported declarations, not a guessed package front door.
+     * @evidence contracts/common.md#clear-and-simple-design The accessor performs one explicit population filter; per-module surface remains in relation indexes.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The API does not equate declaring-file export flags with all barrel export relationships.
+     * @evidence contracts/common.md#meaningful-documentation Native prose distinguishes exported declarations from module-specific re-exports and states external omission.
+     * @evidence contracts/performance.md#efficient-algorithms One O(V) filter over generation nodes selects exported nonexternal declarations; no separate export-flag index is built.
+     * @evidence contracts/performance.md#reuse-equivalent-work Completed exported-list memoization is not implemented; every call returns a new mutable array over the shared generation nodes.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources The projected array belongs to its caller; this method retains no separate state.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation filters the in-memory node array; no file, path or process.
+     */
+    exported(): SnapshotNode[];
     /**
      * Every declaration whose documentation names this address — the reverse of
      * the citation question.
@@ -58,8 +179,17 @@ export declare class TtscGraphMemory {
      * part of a tag's text names a thing belongs to whatever convention wrote the
      * tag, so this is a selection rule of the consuming layer rather than a fact
      * the producer claims.
+     *
+     * @evidence contracts/common.md#principled-implementation Exact target lookup returns indexed declaration carriers under documentationTarget's explicit consumer-side selection rule.
+     * @evidence contracts/common.md#clear-and-simple-design The reverse citation index is built once alongside node indexes instead of rescanning tags per query.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts A match identifies a written citation, not a coverage or truth verdict about its target.
+     * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain reverse lookup, exact spelling and the consumer heuristic's authority boundary.
+     * @evidence contracts/performance.md#efficient-algorithms Reverse citation lookup uses the constructed target index instead of scanning all tags per request.
+     * @evidenceExclude contracts/performance.md#reuse-equivalent-work The accessor borrows the shared citation index; from owns synthesis and its validity key.
+     * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources It returns an existing readonly carrier list and acquires no resource or historical cache.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation one Map lookup over in-memory facts.
      */
-    citing(target: string): readonly ITtscGraphNode[];
+    citing(target: string): readonly SnapshotNode[];
 }
 /**
  * The first whitespace-delimited token, or the whole brace group it opens.
@@ -67,5 +197,15 @@ export declare class TtscGraphMemory {
  * An unclosed brace group is not a token: `{@link ISale` with the brace
  * forgotten would otherwise fall through to the whitespace split and index the
  * address `{@link`, which every link in the project shares.
+ *
+ * @evidence contracts/common.md#principled-implementation Trim and first whitespace preserve the opening token; a leading brace group is returned whole only when closed.
+ * @evidence contracts/common.md#clear-and-simple-design This lexical helper is shared by citation selection rather than parsing tag semantics itself.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Malformed brace groups return absence instead of being coerced into a ubiquitous partial link.
+ * @evidence contracts/common.md#meaningful-documentation Native prose explains brace grouping and the malformed-token reason before acknowledgment tags.
+ * @evidence contracts/performance.md#efficient-algorithms A single bounded text scan finds the token boundary without constructing a parser or scanning unrelated tags.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work This pure per-string extraction does not coordinate reusable producer work.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources Only the returned token survives the call; no retained map or handle is acquired.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation splits a string at whitespace or a brace group; the token is never resolved or opened.
  */
 export declare function leadingToken(text: string | undefined): string | undefined;
+export {};