@astrale-os/kernel-core 0.4.1

package/dist/graph/graph/indexes/nodes.js

@@ -0,0 +1,20 @@
+/**
+ * Build the primary path-keyed index: `path.raw` → Node.
+ *
+ * Distinct from {@link PathIndex} — this map is keyed only by each
+ * node's primary `AbsolutePath.raw`. The PathIndex is a multi-key
+ * superset that also registers typed-form aliases produced by
+ * registered PathTypes.
+ *
+ * Used by `Graph` for `nodes.at(path)` (O(1) AbsolutePath lookup) and
+ * by the walker's `traverseStep` to advance to an in-graph endpoint
+ * when the edge's target raw is a primary AbsolutePath.
+ */
+export function buildNodeByPath(nodes) {
+    const idx = new Map();
+    for (const n of nodes) {
+        idx.set(n.path.raw, n);
+    }
+    return idx;
+}
+//# sourceMappingURL=nodes.js.map

package/dist/graph/graph/indexes/nodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.js","sourceRoot":"","sources":["../../../../graph/graph/indexes/nodes.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,KAAsB;IACpD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAgB,CAAA;IACnC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;IACxB,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/graph/graph/indexes/path-index.d.ts

@@ -0,0 +1,54 @@
+import type { Path } from '#graph/nav/path';
+import type { PathType } from '#graph/nav/path';
+import type { NodeId } from '#ids';
+import type { Node } from '../../node/node';
+import type { GraphView } from './view';
+/**
+ * Multi-key path-to-node index.
+ *
+ * For every node, the index registers:
+ *   - the node's primary {@link Node.path} raw (always)
+ *   - every typed alias produced by `PathType.identify(node)` for
+ *     each registered {@link PathType} that successfully identifies it
+ *
+ * Replaces the legacy {@link Graph.from} canonicalization fixpoint:
+ * edges hold authored Path forms, the walker resolves any form via a
+ * single `pathIndex.get(raw)` lookup. No edge endpoint rewriting; no
+ * dependency-chain iteration cap.
+ *
+ * Build cost: `O(|nodes| × |types| × walk-back-depth)`. Each
+ * identify is a self-contained graph walk via {@link GraphView} —
+ * no PathType-to-PathType dependencies at this level.
+ */
+export declare class PathIndex {
+    private readonly _byRaw;
+    private constructor();
+    /** Look up a node by any registered raw form. */
+    get(raw: string): Node | null;
+    /** Whether any registered path resolves to a node. */
+    has(raw: string): boolean;
+    /** Total number of (path, node) pairs in the index. */
+    get size(): number;
+    /**
+     * Build the index from a list of nodes plus the PathTypes that
+     * should contribute aliases.
+     *
+     * `makeView` is a *factory* called with the in-progress alias map;
+     * it lets the view resolve edge endpoints whose raw matches a
+     * previously-added typed alias. PathIndex.build iterates until the
+     * map stabilizes, so a typed edge endpoint targeting node A can be
+     * resolved on pass N+1 once A's typed alias was added on pass N.
+     *
+     * `aliases` is an optional pre-computed sidecar of typed aliases,
+     * provided by producers that already walked the canonical chain for
+     * each node (notably the get-tree adapter's `semantic-paths` Cypher
+     * stage). Seeded entries are added BEFORE the walkChain fixpoint, so
+     * the fixpoint becomes redundant for nodes the seed covers — and the
+     * index stays correct even when the local view is too partial for
+     * walkChain to derive the alias itself (e.g., a depth-0 tree whose
+     * parent chain isn't loaded). The fixpoint stays as a fallback for
+     * in-memory producers that don't ship a seed.
+     */
+    static build(nodes: readonly Node[], types: readonly PathType[], makeView: (resolveByRaw: ReadonlyMap<string, Node>) => GraphView, aliases?: ReadonlyArray<readonly [NodeId, Path]>): PathIndex;
+}
+//# sourceMappingURL=path-index.d.ts.map

package/dist/graph/graph/indexes/path-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-index.d.ts","sourceRoot":"","sources":["../../../../graph/graph/indexes/path-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAMlC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAEvC;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAE1C,OAAO,eAEN;IAED,iDAAiD;IACjD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAE5B;IAED,sDAAsD;IACtD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExB;IAED,uDAAuD;IACvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,KAAK,CACV,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,QAAQ,EAAE,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,SAAS,EAChE,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,GAC/C,SAAS,CA8CX;CACF"}

package/dist/graph/graph/indexes/path-index.js

@@ -0,0 +1,140 @@
+import { walkChain } from '#graph/nav/path';
+import { IdentifyError } from '#graph/nav/path';
+import { serializeSteps } from '#graph/nav/path';
+/**
+ * Multi-key path-to-node index.
+ *
+ * For every node, the index registers:
+ *   - the node's primary {@link Node.path} raw (always)
+ *   - every typed alias produced by `PathType.identify(node)` for
+ *     each registered {@link PathType} that successfully identifies it
+ *
+ * Replaces the legacy {@link Graph.from} canonicalization fixpoint:
+ * edges hold authored Path forms, the walker resolves any form via a
+ * single `pathIndex.get(raw)` lookup. No edge endpoint rewriting; no
+ * dependency-chain iteration cap.
+ *
+ * Build cost: `O(|nodes| × |types| × walk-back-depth)`. Each
+ * identify is a self-contained graph walk via {@link GraphView} —
+ * no PathType-to-PathType dependencies at this level.
+ */
+export class PathIndex {
+    _byRaw;
+    constructor(byRaw) {
+        this._byRaw = byRaw;
+    }
+    /** Look up a node by any registered raw form. */
+    get(raw) {
+        return this._byRaw.get(raw) ?? null;
+    }
+    /** Whether any registered path resolves to a node. */
+    has(raw) {
+        return this._byRaw.has(raw);
+    }
+    /** Total number of (path, node) pairs in the index. */
+    get size() {
+        return this._byRaw.size;
+    }
+    /**
+     * Build the index from a list of nodes plus the PathTypes that
+     * should contribute aliases.
+     *
+     * `makeView` is a *factory* called with the in-progress alias map;
+     * it lets the view resolve edge endpoints whose raw matches a
+     * previously-added typed alias. PathIndex.build iterates until the
+     * map stabilizes, so a typed edge endpoint targeting node A can be
+     * resolved on pass N+1 once A's typed alias was added on pass N.
+     *
+     * `aliases` is an optional pre-computed sidecar of typed aliases,
+     * provided by producers that already walked the canonical chain for
+     * each node (notably the get-tree adapter's `semantic-paths` Cypher
+     * stage). Seeded entries are added BEFORE the walkChain fixpoint, so
+     * the fixpoint becomes redundant for nodes the seed covers — and the
+     * index stays correct even when the local view is too partial for
+     * walkChain to derive the alias itself (e.g., a depth-0 tree whose
+     * parent chain isn't loaded). The fixpoint stays as a fallback for
+     * in-memory producers that don't ship a seed.
+     */
+    static build(nodes, types, makeView, aliases) {
+        const byRaw = new Map();
+        for (const n of nodes) {
+            byRaw.set(n.path.raw, n);
+        }
+        if (aliases && aliases.length > 0) {
+            // Index nodes by id once, lazily — aliases is keyed by id.
+            const byId = new Map();
+            for (const n of nodes)
+                byId.set(n.id, n);
+            for (const [id, alias] of aliases) {
+                const node = byId.get(id);
+                if (!node)
+                    continue;
+                // Same skip-if-has rule as the fixpoint: never overwrite a raw
+                // form already claimed (whether by primary or earlier seed).
+                if (byRaw.has(alias.raw))
+                    continue;
+                byRaw.set(alias.raw, node);
+            }
+        }
+        const view = makeView(byRaw);
+        let changed = true;
+        let pass = 0;
+        // Bound by registered scheme count + a small slack: each pass adds
+        // ≥1 alias for ≥1 node when making progress, and the deepest
+        // chained scheme requires at most one pass per dependency level
+        // (length of the segment chain). +2 covers the empty-pass after
+        // stabilization plus one defensive slot.
+        const MAX_PASSES = types.length + 2;
+        while (changed && pass < MAX_PASSES) {
+            changed = false;
+            for (const n of nodes) {
+                for (const type of types) {
+                    const alias = tryIdentifyAs(type, n, view);
+                    if (alias === null)
+                        continue;
+                    if (byRaw.has(alias.raw))
+                        continue;
+                    byRaw.set(alias.raw, n);
+                    changed = true;
+                }
+            }
+            pass++;
+        }
+        if (pass >= MAX_PASSES && changed) {
+            throw new Error(`PathIndex.build: did not stabilize within ${MAX_PASSES} passes — possible cyclic scheme dependency`);
+        }
+        return new PathIndex(byRaw);
+    }
+}
+/**
+ * Attempt to identify `target` as `type`. Returns the typed Path on
+ * success or `null` when identify reports any failure mode (orphan,
+ * cardinality, missing slug, broken parent, etc.).
+ *
+ * PathIndex.build is best-effort: a node that can't be aliased simply
+ * doesn't get the typed-form alias. Graph integrity violations are
+ * the responsibility of {@link validatePaths} and the schema-level
+ * validators — surfacing them here would conflate "this type doesn't
+ * fit this node" with "the graph is broken," and the former is the
+ * common case.
+ */
+function tryIdentifyAs(type, target, view) {
+    // Types with no segments have no walk-back recipe and produce no
+    // typed alias. The universal id-anchored fallback lives in
+    // `buildPath`, not here.
+    if (type.segments.length === 0)
+        return null;
+    try {
+        const steps = walkChain(type, target, view);
+        return type.build(steps, serializeSteps(steps));
+    }
+    catch (e) {
+        if (e instanceof IdentifyError)
+            return null;
+        throw e;
+    }
+}
+// Step serialization uses the shared {@link serializeSteps}
+// (`#graph/nav/path`) so PathIndex aliases stay byte-equivalent with
+// the raws emitted by `buildPath`.
+//# sourceMappingURL=path-index.js.map

package/dist/graph/graph/indexes/path-index.js.map

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

package/dist/graph/graph/indexes/view.d.ts

@@ -0,0 +1,60 @@
+import type { EdgeId, NodeId } from '#ids';
+import type { Edge } from '../../edge';
+import type { Node } from '../../node';
+/**
+ * Build-time projection of an in-progress kernel graph that the
+ * backward walker (`#graph/nav/scheme/walk`) consumes during
+ * `PathIndex.build`'s alias fixpoint.
+ *
+ * Distinct from the public `Graph.nodes` / `Graph.edges` namespaces
+ * because those are post-construction immutable views. The view
+ * exposes growing state mid-build: each pass adds typed-form path
+ * aliases to a shared `byRaw` map, and the walker has to be able to
+ * resolve edge endpoints whose authored raw matches an alias added
+ * on a previous pass.
+ *
+ * Operates on kernel `Node` / `Edge` directly — no parallel reader
+ * type, no projection. `edgeSource` / `edgeTarget` resolve an edge's
+ * Path-shaped endpoints to nodes; both return `null` when the
+ * endpoint is unresolvable in the current alias map (the walker
+ * surfaces that as `'broken-target'` via `IdentifyError`).
+ */
+export interface GraphView {
+    getNode(id: NodeId): Node | null;
+    edgesIncoming(target: NodeId, edgeClass: string): readonly Edge[];
+    edgesOutgoing(source: NodeId, edgeClass: string): readonly Edge[];
+    edgeSource(edge: Edge): Node | null;
+    edgeTarget(edge: Edge): Node | null;
+}
+/**
+ * Concrete `GraphView` over a graph-being-built. Resolves edge
+ * endpoints by consulting an externally-managed `byRaw` map that the
+ * caller (`PathIndex.build`) mutates between fixpoint passes — the
+ * view holds the same reference and observes the growing state.
+ *
+ * `edgesIncoming` / `edgesOutgoing` filter by the requested NodeId
+ * resolving against the shared map. The opposite endpoint's
+ * resolvability is *not* a filter — unresolvable endpoints surface as
+ * `null` from `edgeSource` / `edgeTarget` and the walker handles that
+ * via its existing `'broken-target'` `IdentifyError` path.
+ */
+export declare class BuildTimeView implements GraphView {
+    private readonly _nodeById;
+    private readonly _resolveByRaw;
+    private readonly _edgesByEdgeClass;
+    constructor(_nodeById: ReadonlyMap<NodeId, Node>, _resolveByRaw: ReadonlyMap<string, Node>, _edgesByEdgeClass: ReadonlyMap<string, readonly Edge[]>);
+    getNode(id: NodeId): Node | null;
+    edgesIncoming(target: NodeId, edgeClass: string): readonly Edge[];
+    edgesOutgoing(source: NodeId, edgeClass: string): readonly Edge[];
+    edgeSource(edge: Edge): Node | null;
+    edgeTarget(edge: Edge): Node | null;
+}
+/**
+ * Re-exported edge-id type for callers that need to address a
+ * specific edge by id from a `GraphView`. Currently informational —
+ * the view itself does not provide an id-keyed lookup, but consumers
+ * working with `GraphView`-returned edges already have the id on
+ * hand.
+ */
+export type { EdgeId };
+//# sourceMappingURL=view.d.ts.map

package/dist/graph/graph/indexes/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../../graph/graph/indexes/view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAE1C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAChC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,IAAI,EAAE,CAAA;IACjE,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,IAAI,EAAE,CAAA;IACjE,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;IACnC,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;CACpC;AAID;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,YAAW,SAAS;IAE3C,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAHpC,YACmB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,EACpC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,EACxC,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC,EACtE;IAEJ,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAE/B;IAED,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,IAAI,EAAE,CAKhE;IAED,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,IAAI,EAAE,CAKhE;IAED,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAElC;IAED,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAElC;CACF;AAED;;;;;;GAMG;AACH,YAAY,EAAE,MAAM,EAAE,CAAA"}

package/dist/graph/graph/indexes/view.js

@@ -0,0 +1,47 @@
+const EMPTY_EDGES = Object.freeze([]);
+/**
+ * Concrete `GraphView` over a graph-being-built. Resolves edge
+ * endpoints by consulting an externally-managed `byRaw` map that the
+ * caller (`PathIndex.build`) mutates between fixpoint passes — the
+ * view holds the same reference and observes the growing state.
+ *
+ * `edgesIncoming` / `edgesOutgoing` filter by the requested NodeId
+ * resolving against the shared map. The opposite endpoint's
+ * resolvability is *not* a filter — unresolvable endpoints surface as
+ * `null` from `edgeSource` / `edgeTarget` and the walker handles that
+ * via its existing `'broken-target'` `IdentifyError` path.
+ */
+export class BuildTimeView {
+    _nodeById;
+    _resolveByRaw;
+    _edgesByEdgeClass;
+    constructor(_nodeById, _resolveByRaw, _edgesByEdgeClass) {
+        this._nodeById = _nodeById;
+        this._resolveByRaw = _resolveByRaw;
+        this._edgesByEdgeClass = _edgesByEdgeClass;
+    }
+    getNode(id) {
+        return this._nodeById.get(id) ?? null;
+    }
+    edgesIncoming(target, edgeClass) {
+        const candidates = this._edgesByEdgeClass.get(edgeClass) ?? EMPTY_EDGES;
+        const targetNode = this._nodeById.get(target);
+        if (!targetNode)
+            return EMPTY_EDGES;
+        return candidates.filter((e) => this._resolveByRaw.get(e.target.raw) === targetNode);
+    }
+    edgesOutgoing(source, edgeClass) {
+        const candidates = this._edgesByEdgeClass.get(edgeClass) ?? EMPTY_EDGES;
+        const sourceNode = this._nodeById.get(source);
+        if (!sourceNode)
+            return EMPTY_EDGES;
+        return candidates.filter((e) => this._resolveByRaw.get(e.source.raw) === sourceNode);
+    }
+    edgeSource(edge) {
+        return this._resolveByRaw.get(edge.source.raw) ?? null;
+    }
+    edgeTarget(edge) {
+        return this._resolveByRaw.get(edge.target.raw) ?? null;
+    }
+}
+//# sourceMappingURL=view.js.map

package/dist/graph/graph/indexes/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../../../graph/graph/indexes/view.ts"],"names":[],"mappings":"AA+BA,MAAM,WAAW,GAAoB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;AAEtD;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,aAAa;IAEL,SAAS;IACT,aAAa;IACb,iBAAiB;IAHpC,YACmB,SAAoC,EACpC,aAAwC,EACxC,iBAAuD;yBAFvD,SAAS;6BACT,aAAa;iCACb,iBAAiB;IACjC,CAAC;IAEJ,OAAO,CAAC,EAAU;QAChB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAA;IACvC,CAAC;IAED,aAAa,CAAC,MAAc,EAAE,SAAiB;QAC7C,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,WAAW,CAAA;QACvE,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QAC7C,IAAI,CAAC,UAAU;YAAE,OAAO,WAAW,CAAA;QACnC,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,UAAU,CAAC,CAAA;IACtF,CAAC;IAED,aAAa,CAAC,MAAc,EAAE,SAAiB;QAC7C,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,WAAW,CAAA;QACvE,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QAC7C,IAAI,CAAC,UAAU;YAAE,OAAO,WAAW,CAAA;QACnC,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,UAAU,CAAC,CAAA;IACtF,CAAC;IAED,UAAU,CAAC,IAAU;QACnB,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,CAAA;IACxD,CAAC;IAED,UAAU,CAAC,IAAU;QACnB,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,CAAA;IACxD,CAAC;CACF"}

package/dist/graph/graph/namespaces.d.ts

@@ -0,0 +1,53 @@
+import type { ClassPath } from '#domain';
+import type { Path } from '#graph/nav/path';
+import type { Traversal } from '#graph/nav/path/step';
+import type { EdgeId, NodeId } from '#ids';
+import type { Edge } from '../edge';
+import type { Node } from '../node';
+import type { AbsolutePath } from '../tree/path/absolute-path';
+/**
+ * Node sub-namespace surface (typed queries + Array-iteration ergonomics).
+ *
+ * - `all` / `length` / iterator / `filter`+`find`+`map`+`some`+`every`+`forEach` — the array.
+ * - `byId(id)` — O(1) by NodeId.
+ * - `at(path)` — O(1) direct primary-path index hit (AbsolutePath only, I3/I9).
+ * - `get(path)` — walker-backed resolution for any Path; escape collapses to null.
+ */
+export interface NodeNamespace extends Iterable<Node> {
+    readonly all: readonly Node[];
+    readonly length: number;
+    byId(id: NodeId): Node | undefined;
+    at(path: AbsolutePath): Node | undefined;
+    get(path: Path): Node | null;
+    filter(predicate: (n: Node, i: number, a: readonly Node[]) => boolean): Node[];
+    find(predicate: (n: Node, i: number, a: readonly Node[]) => boolean): Node | undefined;
+    map<T>(fn: (n: Node, i: number, a: readonly Node[]) => T): T[];
+    some(predicate: (n: Node, i: number, a: readonly Node[]) => boolean): boolean;
+    every(predicate: (n: Node, i: number, a: readonly Node[]) => boolean): boolean;
+    forEach(fn: (n: Node, i: number, a: readonly Node[]) => void): void;
+}
+/**
+ * Edge sub-namespace surface (typed queries + Array-iteration ergonomics).
+ *
+ * - `all` / `length` / iterator / array-ergonomic methods — the array.
+ * - `byId(id)` — O(1) by EdgeId.
+ * - `at(path)` — edges incident at a raw address.
+ * - `byClass(cls)` / `byStep(step)` — edges filtered by class or step.
+ * - `incident(from, step)` — the unique edge at `from` satisfying `step` (raises on multi-match).
+ */
+export interface EdgeNamespace extends Iterable<Edge> {
+    readonly all: readonly Edge[];
+    readonly length: number;
+    byId(id: EdgeId): Edge | undefined;
+    at(path: AbsolutePath): readonly Edge[];
+    byClass(cls: ClassPath): readonly Edge[];
+    byStep(step: Traversal): readonly Edge[];
+    incident(from: Node, step: Traversal): Edge | null;
+    filter(predicate: (e: Edge, i: number, a: readonly Edge[]) => boolean): Edge[];
+    find(predicate: (e: Edge, i: number, a: readonly Edge[]) => boolean): Edge | undefined;
+    map<T>(fn: (e: Edge, i: number, a: readonly Edge[]) => T): T[];
+    some(predicate: (e: Edge, i: number, a: readonly Edge[]) => boolean): boolean;
+    every(predicate: (e: Edge, i: number, a: readonly Edge[]) => boolean): boolean;
+    forEach(fn: (e: Edge, i: number, a: readonly Edge[]) => void): void;
+}
+//# sourceMappingURL=namespaces.d.ts.map

package/dist/graph/graph/namespaces.d.ts.map

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

package/dist/graph/graph/namespaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=namespaces.js.map

package/dist/graph/graph/namespaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespaces.js","sourceRoot":"","sources":["../../../graph/graph/namespaces.ts"],"names":[],"mappings":""}

package/dist/graph/graph/root.d.ts

@@ -0,0 +1,36 @@
+import type { Node } from '../node';
+/**
+ * Identify the auto-injected virtual root. Any node with
+ * `id === __SYSTEM__` is the virtual root produced by `ensureRoot`
+ * (I1). Consumers that care about user-owned content (diff, toWire,
+ * merge dedup) skip it. The reserved `__SYSTEM__` sentinel alone is
+ * sufficient — no real node mints that id.
+ */
+export declare function isVirtualRoot(n: Node): boolean;
+/**
+ * Factory for the virtual root node (I1). The `class` field
+ * structurally needs a `ClassPath`-shaped value; the kernel's real
+ * `K.Root.path.class` isn't reachable from here (importing it cycles
+ * through `#kernel → #domain → #graph`). Reusing `AbsolutePath.root()`
+ * is the honest structural placeholder: it's a real `Path` instance
+ * with `raw === '/'`, it round-trips cleanly, and consumers that
+ * discriminate the virtual root do so by `isVirtualRoot` (id), never
+ * by class identity.
+ */
+export declare function makeVirtualRoot(): Node;
+/**
+ * Collapse duplicate virtual roots (auto-injected `__SYSTEM__` at `/`)
+ * that appear when merging graphs. A caller-supplied real root wins
+ * over any virtual root; otherwise keep the first virtual root.
+ */
+export declare function dedupeVirtualRoots(nodes: readonly Node[]): readonly Node[];
+/**
+ * Ensure the node set has exactly one root at `/`. If a `/` node
+ * exists, return it; if multiple exist, raise `GraphValidationError`.
+ * If none exists, prepend a virtual root and return it.
+ */
+export declare function ensureRoot(nodes: readonly Node[]): {
+    nodes: readonly Node[];
+    root: Node;
+};
+//# sourceMappingURL=root.d.ts.map

package/dist/graph/graph/root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../../../graph/graph/root.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAKnC;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,GAAG,OAAO,CAE9C;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAOtC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,SAAS,IAAI,EAAE,CAsB1E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG;IAAE,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,CAezF"}

package/dist/graph/graph/root.js

@@ -0,0 +1,85 @@
+import { __SYSTEM__ } from '#ids';
+import { GraphValidationError } from '../errors';
+import { AbsolutePath } from '../tree/path/absolute-path';
+/**
+ * Identify the auto-injected virtual root. Any node with
+ * `id === __SYSTEM__` is the virtual root produced by `ensureRoot`
+ * (I1). Consumers that care about user-owned content (diff, toWire,
+ * merge dedup) skip it. The reserved `__SYSTEM__` sentinel alone is
+ * sufficient — no real node mints that id.
+ */
+export function isVirtualRoot(n) {
+    return n.id === __SYSTEM__;
+}
+/**
+ * Factory for the virtual root node (I1). The `class` field
+ * structurally needs a `ClassPath`-shaped value; the kernel's real
+ * `K.Root.path.class` isn't reachable from here (importing it cycles
+ * through `#kernel → #domain → #graph`). Reusing `AbsolutePath.root()`
+ * is the honest structural placeholder: it's a real `Path` instance
+ * with `raw === '/'`, it round-trips cleanly, and consumers that
+ * discriminate the virtual root do so by `isVirtualRoot` (id), never
+ * by class identity.
+ */
+export function makeVirtualRoot() {
+    return {
+        id: __SYSTEM__,
+        class: AbsolutePath.root(),
+        path: AbsolutePath.root(),
+        props: Object.freeze({}),
+    };
+}
+/**
+ * Collapse duplicate virtual roots (auto-injected `__SYSTEM__` at `/`)
+ * that appear when merging graphs. A caller-supplied real root wins
+ * over any virtual root; otherwise keep the first virtual root.
+ */
+export function dedupeVirtualRoots(nodes) {
+    let rootsAt = 0;
+    let hasReal = false;
+    for (const n of nodes) {
+        if (n.path.raw !== '/')
+            continue;
+        rootsAt++;
+        if (!isVirtualRoot(n))
+            hasReal = true;
+    }
+    if (rootsAt <= 1)
+        return nodes;
+    let keptVirtual = false;
+    const out = [];
+    for (const n of nodes) {
+        if (n.path.raw !== '/' || !isVirtualRoot(n)) {
+            out.push(n);
+            continue;
+        }
+        if (hasReal || keptVirtual)
+            continue;
+        keptVirtual = true;
+        out.push(n);
+    }
+    return out;
+}
+/**
+ * Ensure the node set has exactly one root at `/`. If a `/` node
+ * exists, return it; if multiple exist, raise `GraphValidationError`.
+ * If none exists, prepend a virtual root and return it.
+ */
+export function ensureRoot(nodes) {
+    let root;
+    for (const n of nodes) {
+        if (n.path.raw !== '/')
+            continue;
+        if (root !== undefined) {
+            throw new GraphValidationError([
+                { kind: 'duplicate_node_id', nodeId: root.id ?? '' },
+            ]);
+        }
+        root = n;
+    }
+    if (root !== undefined)
+        return { nodes, root };
+    const virtualRoot = makeVirtualRoot();
+    return { nodes: [virtualRoot, ...nodes], root: virtualRoot };
+}
+//# sourceMappingURL=root.js.map

package/dist/graph/graph/root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.js","sourceRoot":"","sources":["../../../graph/graph/root.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAA;AAIjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAEzD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,CAAO;IACnC,OAAO,CAAC,CAAC,EAAE,KAAK,UAAU,CAAA;AAC5B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO;QACL,EAAE,EAAE,UAAU;QACd,KAAK,EAAE,YAAY,CAAC,IAAI,EAA0B;QAClD,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE;QACzB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;KACzB,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAsB;IACvD,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,KAAK,GAAG;YAAE,SAAQ;QAChC,OAAO,EAAE,CAAA;QACT,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;YAAE,OAAO,GAAG,IAAI,CAAA;IACvC,CAAC;IACD,IAAI,OAAO,IAAI,CAAC;QAAE,OAAO,KAAK,CAAA;IAE9B,IAAI,WAAW,GAAG,KAAK,CAAA;IACvB,MAAM,GAAG,GAAW,EAAE,CAAA;IACtB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACX,SAAQ;QACV,CAAC;QACD,IAAI,OAAO,IAAI,WAAW;YAAE,SAAQ;QACpC,WAAW,GAAG,IAAI,CAAA;QAClB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACb,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC/C,IAAI,IAAsB,CAAA;IAC1B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,KAAK,GAAG;YAAE,SAAQ;QAChC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,oBAAoB,CAAC;gBAC7B,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAK,EAAa,EAAE;aACjE,CAAC,CAAA;QACJ,CAAC;QACD,IAAI,GAAG,CAAC,CAAA;IACV,CAAC;IACD,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAE9C,MAAM,WAAW,GAAG,eAAe,EAAE,CAAA;IACrC,OAAO,EAAE,KAAK,EAAE,CAAC,WAAW,EAAE,GAAG,KAAK,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAA;AAC9D,CAAC"}

package/dist/graph/graph/walker.d.ts

@@ -0,0 +1,80 @@
+import type { Path } from '#graph/nav/path';
+import type { Step, Traversal } from '#graph/nav/path/step';
+import type { NodeId } from '#ids';
+import type { Edge } from '../edge';
+import type { Node } from '../node';
+import type { PathIndex } from './indexes/path-index';
+/**
+ * Tagged result of `walkSteps`.
+ *
+ * - `node` — every step consumed and the cursor landed on an in-graph
+ *   Node.
+ * - `escape` — the cursor reached a typed endpoint Path that
+ *   self-identifies the unconsumed residue (I7).
+ * - `miss` — a step had no matching edge, or escape verification
+ *   failed.
+ */
+export type WalkResult = {
+    readonly kind: 'node';
+    readonly node: Node;
+} | {
+    readonly kind: 'escape';
+    readonly endpoint: Path;
+} | {
+    readonly kind: 'miss';
+};
+/**
+ * The minimum graph state the walker reads from.
+ *
+ * `Graph` builds one of these inline from its private index fields
+ * and passes it to {@link walkSteps}. Pulling the walk algorithm out
+ * of the class keeps `graph.ts` focused on namespace wiring +
+ * delegation, and lets the walker be exercised against any compatible
+ * context (e.g., specialized read-only views in the future).
+ */
+export interface WalkContext {
+    readonly root: Node;
+    readonly nodeById: ReadonlyMap<NodeId, Node>;
+    readonly nodeByPath: ReadonlyMap<string, Node>;
+    readonly edgesByEdgeClass: ReadonlyMap<string, readonly Edge[]>;
+    readonly pathIndex: PathIndex | null;
+}
+/**
+ * Walk `steps` from `start` against the in-memory graph, returning a
+ * tagged result:
+ *
+ * - `node` — every step consumed and the cursor landed on an in-graph
+ *   Node.
+ * - `escape` — the cursor reached a typed endpoint Path that
+ *   self-identifies the unconsumed residue (I7).
+ * - `miss` — a step had no matching edge, or escape verification
+ *   failed.
+ *
+ * Strictly non-recursive (I5 / T2): never re-enters the graph's
+ * `nodes.get` / `nodes.at`.
+ */
+export declare function walkSteps(steps: readonly Step[], start: Node, ctx: WalkContext): WalkResult;
+/**
+ * Advance one step from a node. Returns the next Node (in-graph
+ * endpoint) or the endpoint Path (typed endpoint — next iteration
+ * decides escape or miss). Uses the raw index map directly; never
+ * calls `Graph.nodes.get` / `nodes.at` (I5 / T2).
+ */
+export declare function traverseStep(from: Node, step: Step, ctx: WalkContext): Node | Path | null;
+/**
+ * The unique edge at `from` that satisfies `step`. Raises
+ * `AmbiguousWalkError` on multi-match (I6).
+ */
+export declare function edgeIncident(from: Node, step: Traversal, ctx: WalkContext): Edge | null;
+/**
+ * Every edge whose class + predicate satisfies `step`, regardless of
+ * role. Used by reverse-walk candidate enumeration in the resolver.
+ */
+export declare function edgesByStep(step: Traversal, ctx: WalkContext): readonly Edge[];
+/**
+ * Distinguish Node from Path at runtime. Nodes have `class`, `path`,
+ * `props`; Paths have `steps`. Negating `'steps' in x` narrows the
+ * union.
+ */
+export declare function isNode(x: Node | Path): x is Node;
+//# sourceMappingURL=walker.d.ts.map

package/dist/graph/graph/walker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walker.d.ts","sourceRoot":"","sources":["../../../graph/graph/walker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAMlC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AACnC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAKrD;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7B;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAC5C,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAC9C,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC,CAAA;IAC/D,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;CACrC;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,GAAG,UAAU,CAa3F;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAWzF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAWvF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,SAAS,IAAI,EAAE,CAQ9E;AA0CD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,IAAI,CAEhD"}