@astrale-os/kernel-core 0.4.1

package/dist/graph/tree/tree.js

@@ -0,0 +1,323 @@
+import { Graph } from '#graph';
+import { parsePath } from '#graph/nav/path';
+import { liftPortable, seedAddressMapWithAliases } from './aliases';
+import { buildTree } from './build';
+import { classifyEndpoints } from './edge';
+import { hasId } from './helpers';
+import { collectPortable } from './serialize';
+/**
+ * A rooted, slug-labeled view over a Graph.
+ *
+ * `Tree` is a **value** — immutable, composed over a source `Graph`. It is
+ * NOT a subclass of `Graph`. Tree holds `readonly graph: Graph`; raw
+ * graph access is `tree.graph.nodes`, `tree.graph.edges.all`, etc.
+ *
+ * ## Surfaces
+ *
+ * - `tree.root`                         — InTree<N>, always at relative `.`
+ * - `tree.byId(id)`, `tree.byPath(rel)` — resolve to InTree overlay
+ * - `tree.nodes`                        — Iterable<InTree<N>>, tree-order
+ * - `tree.edges`                        — Iterable<TreeEdge<N, E>>, classified
+ * - `tree.mount`                        — AbsolutePath | null (extrinsic)
+ * - `tree.absolutePathOf(node)`         — mount.joinRelative(node.path) | null
+ * - `tree.withMount(mount)`             — new Tree, same shape, new mount
+ * - `tree.subtree(node)`                — new Tree rooted at node
+ * - `tree.toGraph()`                    — absolute, validated Graph (requires mount)
+ * - `tree.toWire()`                     — portable (mount-free) JSON projection
+ *
+ * Trees are relative by default: `tree.root.path` is `RelativePath.from()`.
+ * Mounting is a late-bound overlay — unmounted trees are valid and portable.
+ */
+export class Tree {
+    /** Source graph (raw). Access raw nodes/edges via `tree.graph`. */
+    graph;
+    root;
+    mount;
+    _refs;
+    _nodeByPath;
+    _treeNodeById;
+    _pathToId;
+    _addressToRelative;
+    _edgesCache;
+    constructor(graph, root, nodeByPath, treeNodeById, pathToId, addressToRelative, refs, mount) {
+        this.graph = graph;
+        this.root = root;
+        this._refs = refs;
+        this._nodeByPath = nodeByPath;
+        this._treeNodeById = treeNodeById;
+        this._pathToId = pathToId;
+        this._addressToRelative = addressToRelative;
+        this.mount = mount;
+    }
+    // ─── Resolve ───────────────────────────────────────────────────
+    /** Resolve a node in this tree by id. */
+    byId(id) {
+        return this._treeNodeById.get(id);
+    }
+    /** Resolve a node in this tree by relative path. */
+    byPath(path) {
+        const raw = typeof path === 'string' ? path : path.raw;
+        return this._nodeByPath.get(raw);
+    }
+    // ─── Iteration ─────────────────────────────────────────────────
+    /** Iterate over all nodes in the tree (BFS order from root). */
+    get nodes() {
+        return this._nodeByPath.values();
+    }
+    /** Count of nodes in this tree. */
+    get nodeCount() {
+        return this._nodeByPath.size;
+    }
+    /** Count of edges in the source graph (every graph edge produces one TreeEdge). */
+    get edgeCount() {
+        return this.graph.edges.all.length;
+    }
+    /**
+     * Iterate over all edges in the source graph, classified against this tree.
+     *
+     * Boundary-crossing edges (outgoing / incoming) are the norm — every edge
+     * is classified so consumers can filter without reinventing resolution.
+     * Results are cached after first access.
+     */
+    get edges() {
+        return this._classifiedEdges();
+    }
+    get internalEdges() {
+        return filterByClass(this._classifiedEdges(), 'internal');
+    }
+    get outgoingEdges() {
+        return filterByClass(this._classifiedEdges(), 'outgoing');
+    }
+    get incomingEdges() {
+        return filterByClass(this._classifiedEdges(), 'incoming');
+    }
+    /** Outgoing ∪ incoming — every edge that crosses the tree boundary. */
+    get boundaryEdges() {
+        return filterByClasses(this._classifiedEdges(), ['outgoing', 'incoming']);
+    }
+    /** All classified edges touching a given tree node. */
+    edgesOf(node) {
+        return this._classifiedEdges().filter((te) => (te.source.kind === 'internal' && te.source.node === node) ||
+            (te.target.kind === 'internal' && te.target.node === node));
+    }
+    /** Edges with this node as (internal) source. */
+    outgoingFrom(node) {
+        return this._classifiedEdges().filter((te) => te.source.kind === 'internal' && te.source.node === node);
+    }
+    /** Edges with this node as (internal) target. */
+    incomingTo(node) {
+        return this._classifiedEdges().filter((te) => te.target.kind === 'internal' && te.target.node === node);
+    }
+    // ─── Frame-of-reference overlay ───────────────────────────────
+    /** Compose a node's intrinsic relative path with the tree's mount. */
+    absolutePathOf(node) {
+        if (!this.mount)
+            return null;
+        return this.mount.joinRelative(node.path);
+    }
+    /** Return a copy with a different (or no) mount. Structure unchanged, O(1). */
+    withMount(mount) {
+        return new Tree(this.graph, this.root, this._nodeByPath, this._treeNodeById, this._pathToId, this._addressToRelative, this._refs, mount);
+    }
+    // ─── Structural ops ───────────────────────────────────────────
+    /**
+     * Extract a new Tree rooted at `node`.
+     *
+     * The subtree's mount composes the current mount with the node's relative
+     * path (if mounted), preserving absolute addressing through the extraction.
+     */
+    subtree(node, refs) {
+        if (hasId(node) && this._treeNodeById.get(node.id) !== node) {
+            throw new Error(`Tree.subtree: node not in this tree`);
+        }
+        const subtreePaths = new Set();
+        const queue = [node];
+        for (let i = 0; i < queue.length; i++) {
+            const qi = queue[i];
+            if (hasId(qi)) {
+                const src = this.graph.nodes.byId(qi.id);
+                if (src?.path)
+                    subtreePaths.add(src.path.raw);
+            }
+            for (const child of qi.children)
+                queue.push(child);
+        }
+        const subNodes = this.graph.nodes.filter((n) => subtreePaths.has(n.path.raw));
+        // Boundary edges survive: any edge whose source OR target is inside the subtree
+        // reaches the extracted Tree, mirroring the parent Tree's edge classification
+        // (internal/outgoing/incoming). External endpoints retain their original path.
+        const subEdges = this.graph.edges.filter((e) => subtreePaths.has(e.source.raw) || subtreePaths.has(e.target.raw));
+        const subMount = this.mount ? this.mount.joinRelative(node.path) : null;
+        return Tree.from({ nodes: subNodes, edges: subEdges }, refs ?? this._refs, {
+            ...(subMount && { mount: subMount }),
+        });
+    }
+    // ─── Conversion ───────────────────────────────────────────────
+    /**
+     * Materialize the Tree as an absolute, validated `Graph`. Requires a mount.
+     *
+     * Internal endpoints are composed with `mount` to produce absolute paths;
+     * external endpoints keep their original addressing. The typed-form alias
+     * sidecar (`graph.aliases`) is re-applied across the round-trip via
+     * `liftPortable` — typed semantic Paths are mount-agnostic by design,
+     * so they survive any remount. This is the form sync (diff / reconcile
+     * / push) operates on.
+     */
+    toGraph() {
+        if (!this.mount) {
+            throw new Error('Tree.toGraph requires a mount. Use withMount() first.');
+        }
+        return Graph.from(liftPortable(this._collectPortable(), this.mount, this.graph.aliases));
+    }
+    /**
+     * Portable, JSON-safe projection — mount-free, relative-internal.
+     *
+     * Internal endpoints are rewritten to relative paths; external endpoints
+     * keep their original addressing. Output can be re-anchored anywhere by
+     * the receiving host, or round-tripped through `Tree.parse`.
+     */
+    toWire() {
+        const portable = this._collectPortable();
+        return {
+            nodes: portable.nodes.map(portableNodeToWire),
+            edges: portable.edges.map(portableEdgeToWire),
+        };
+    }
+    // ─── Internals ────────────────────────────────────────────────
+    /** Compute (once) the classified edge view. */
+    _classifiedEdges() {
+        if (this._edgesCache)
+            return this._edgesCache;
+        const result = [];
+        for (const raw of this.graph.edges.all) {
+            const source = this._resolveEndpoint(raw.source);
+            const target = this._resolveEndpoint(raw.target);
+            result.push({
+                raw: raw,
+                source,
+                target,
+                classification: classifyEndpoints(source, target),
+                class: raw.class,
+            });
+        }
+        this._edgesCache = Object.freeze(result);
+        return this._edgesCache;
+    }
+    /** Resolve an edge endpoint into the tree's frame. */
+    _resolveEndpoint(ep) {
+        // Lookup by the original input address (the builder indexes every form
+        // under which a node may have been referenced).
+        const rel = this._addressToRelative.get(ep.raw);
+        if (rel) {
+            const node = this._nodeByPath.get(rel.raw);
+            if (node)
+                return { kind: 'internal', node };
+        }
+        // External — keep the raw address as-is.
+        return { kind: 'external', address: ep };
+    }
+    _collectPortable() {
+        // SPEC I1: the source Graph always has a virtual `/` root. Tree views
+        // are typically mounted subtrees rooted elsewhere, so exclude the
+        // virtual-root NODE from portable output — mount.joinRelative('.')
+        // would otherwise overwrite the tree's real root with the virtual
+        // root's class. Edges touching `/` (e.g. Domain → root has_parent)
+        // are preserved: `/` is an external endpoint for mounted trees, and
+        // collectPortable already handles externals as opaque addresses.
+        const userNodes = this.graph.nodes.filter((n) => n.path.raw !== '/');
+        return collectPortable(this.root, userNodes, this.graph.edges.all, this._refs, this._addressToRelative);
+    }
+    // ─── Static factories ────────────────────────────────────────
+    /**
+     * Build a validated Tree from a Graph or typed `{ nodes, edges }` data.
+     *
+     * Validation is strict — ill-formed inputs throw `TreeValidationError` with
+     * enumerated violations.
+     */
+    static from(input, refs, opts) {
+        if (!refs)
+            throw new Error('Tree.from requires refs (TreeRefs)');
+        let graph;
+        if (input instanceof Graph) {
+            graph = input;
+        }
+        else {
+            // Graph.from validates and dedupes virtual `/` roots (SPEC I1);
+            // delegate rather than re-running buildIndexes eagerly.
+            graph = Graph.from(input);
+        }
+        // SPEC I1: Graph always has a virtual root at `/`. When the tree is a
+        // subtree view (root at e.g. `/origin`), the `/` node is "above" the
+        // tree and must be excluded from layout/validation — otherwise it
+        // surfaces as a rootless, slugless node. The `graph` itself (available
+        // via `tree.graph`) still contains the root for full-graph reads.
+        const treeNodes = (graph.nodes.filter((n) => n.path.raw !== '/') ??
+            graph.nodes);
+        // Typed-semantic-Path fallback resolver: when has_parent edges
+        // target nodes via a typed form (DomainPath / ClassPath / etc.),
+        // delegate to the host Graph's path-walker for resolution. Scope
+        // the result to `treeNodes` only — Tree.from filters out the
+        // synthetic `/` root, so a typed-Path target that resolves to it
+        // (via the full graph) must NOT be returned, or every tree node
+        // ends up with a parent and the tree has no root.
+        const treeNodeSet = new Set(treeNodes);
+        const nodeForRaw = (raw) => {
+            let resolved;
+            try {
+                resolved = graph.nodes.get(parsePath(raw));
+            }
+            catch {
+                return undefined;
+            }
+            if (resolved === null)
+                return undefined;
+            return treeNodeSet.has(resolved) ? resolved : undefined;
+        };
+        const { root, nodeByPath, pathToId, addressToRelative } = buildTree(treeNodes, graph.edges.all, refs, 
+        // buildTree only reads `nodeById` for endpoint id lookups; we pass a
+        // fresh one so it doesn't reach into Graph's internals.
+        buildNodeByIdMap(treeNodes), nodeForRaw);
+        seedAddressMapWithAliases(addressToRelative, nodeByPath, graph.aliases);
+        const treeNodeById = new Map();
+        for (const tn of nodeByPath.values()) {
+            if (hasId(tn))
+                treeNodeById.set(tn.id, tn);
+        }
+        return new Tree(graph, root, nodeByPath, treeNodeById, pathToId, addressToRelative, refs, opts?.mount ?? null);
+    }
+}
+// ─── Helpers (module-local) ────────────────────────────────────────
+function* filterByClass(edges, cls) {
+    for (const te of edges)
+        if (te.classification === cls)
+            yield te;
+}
+function* filterByClasses(edges, classes) {
+    const set = new Set(classes);
+    for (const te of edges)
+        if (set.has(te.classification))
+            yield te;
+}
+function buildNodeByIdMap(nodes) {
+    const m = new Map();
+    for (const n of nodes)
+        if (hasId(n))
+            m.set(n.id, n);
+    return m;
+}
+// ── Wire projection ─────────────────────────────────────────────
+function portableNodeToWire(n) {
+    const { class: cls, path, ...rest } = n;
+    return { ...rest, class: cls.raw, path: path.raw };
+}
+function portableEdgeToWire(e) {
+    const { class: cls, source, target, slug, ...rest } = e;
+    return {
+        ...rest,
+        class: cls.raw,
+        source: source.raw,
+        target: target.raw,
+        ...(slug !== undefined && { slug }),
+    };
+}
+//# sourceMappingURL=tree.js.map

package/dist/graph/tree/tree.js.map

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

package/dist/graph/tree/types.d.ts

@@ -0,0 +1,41 @@
+import type { ClassPath } from '#domain';
+import type { Node, NodeSpec } from '#graph';
+import type { AbsolutePath, RelativePath } from './path';
+/**
+ * Tree overlay — nodes addressed by their intrinsic relative position in the tree.
+ *
+ * `path` is always a `RelativePath` (root = `RelativePath.from()`, raw '.').
+ * For the absolute view, use `tree.absolutePathOf(node)` which composes with
+ * the tree's optional `mount`.
+ *
+ * The `Omit<N, 'path'>` is intentional: input nodes may carry `AbsolutePath`
+ * (e.g. `Node.path`), which would otherwise collide with `RelativePath` under
+ * an intersection and yield `never`.
+ */
+export type InTree<N extends NodeSpec = NodeSpec> = Omit<N, 'path'> & {
+    readonly path: RelativePath;
+    /**
+     * Tree-order children of this node.
+     *
+     * Typed as `Iterable` so the backing structure can move from an eager
+     * frozen array to a lazy persistent index without a breaking change.
+     * Consumers must iterate (`for..of`, spread, `Array.from`) rather than
+     * reach for array-specific methods like `.length` or `.map`.
+     */
+    readonly children: Iterable<InTree<N>>;
+    readonly parent: InTree<N> | null;
+};
+/** Convenience alias — materialized node in a tree (has id from Node). */
+export type TreeNode = InTree<Node>;
+export interface TreeRefs {
+    readonly has_parent: ClassPath;
+}
+export interface TreeOptions {
+    /**
+     * Where this tree sits in its host graph, if known. When set,
+     * `tree.absolutePathOf(node)` returns `mount.joinRelative(node.path)`.
+     * When absent, the tree is a pure relative frame (portable, transplantable).
+     */
+    mount?: AbsolutePath;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/graph/tree/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../graph/tree/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAE5C,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAExD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAAI,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG;IACpE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;CAClC,CAAA;AAED,0EAA0E;AAC1E,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAA;AAEnC,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAA;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAA;CACrB"}

package/dist/graph/tree/types.js

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

package/dist/graph/tree/types.js.map

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

package/dist/graph/tree/zod.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Zod schema factories for TreePath variants.
+ *
+ * See `#graph/nav/path/zod` for the `pathLike` factory and the base
+ * `pathSchema` — this file only owns the tree-flavored subtypes.
+ *
+ * `TreePath` is a type alias for `AbsolutePath | RelativePath` (no
+ * runtime class), so its schema is a union of the two variant
+ * schemas.
+ */
+import { z } from 'zod';
+import { AbsolutePath, RelativePath } from '#graph/tree';
+/** AbsolutePath only — rejects RelativePath. */
+export declare const absolutePathSchema: () => z.ZodType<AbsolutePath, string | AbsolutePath, z.core.$ZodTypeInternals<AbsolutePath, string | AbsolutePath>>;
+/** RelativePath only — rejects AbsolutePath. */
+export declare const relativePathSchema: () => z.ZodType<RelativePath, string | RelativePath, z.core.$ZodTypeInternals<RelativePath, string | RelativePath>>;
+/** TreePath — either an AbsolutePath or a RelativePath. */
+export declare const treePathSchema: () => z.ZodType<AbsolutePath | RelativePath>;
+//# sourceMappingURL=zod.d.ts.map

package/dist/graph/tree/zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../../../graph/tree/zod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAExD,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,qHAA+D,CAAA;AAE9F,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,qHAA+D,CAAA;AAE9F,2DAA2D;AAC3D,eAAO,MAAM,cAAc,QAAO,CAAC,CAAC,OAAO,CAAC,YAAY,GAAG,YAAY,CAChB,CAAA"}

package/dist/graph/tree/zod.js

@@ -0,0 +1,20 @@
+/**
+ * Zod schema factories for TreePath variants.
+ *
+ * See `#graph/nav/path/zod` for the `pathLike` factory and the base
+ * `pathSchema` — this file only owns the tree-flavored subtypes.
+ *
+ * `TreePath` is a type alias for `AbsolutePath | RelativePath` (no
+ * runtime class), so its schema is a union of the two variant
+ * schemas.
+ */
+import { z } from 'zod';
+import { pathLike } from '#graph/nav/path/zod';
+import { AbsolutePath, RelativePath } from '#graph/tree';
+/** AbsolutePath only — rejects RelativePath. */
+export const absolutePathSchema = pathLike(AbsolutePath, 'AbsolutePath', 'path:tree.absolute');
+/** RelativePath only — rejects AbsolutePath. */
+export const relativePathSchema = pathLike(RelativePath, 'RelativePath', 'path:tree.relative');
+/** TreePath — either an AbsolutePath or a RelativePath. */
+export const treePathSchema = () => z.union([absolutePathSchema(), relativePathSchema()]);
+//# sourceMappingURL=zod.js.map

package/dist/graph/tree/zod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.js","sourceRoot":"","sources":["../../../graph/tree/zod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAExD,gDAAgD;AAChD,MAAM,CAAC,MAAM,kBAAkB,GAAG,QAAQ,CAAC,YAAY,EAAE,cAAc,EAAE,oBAAoB,CAAC,CAAA;AAE9F,gDAAgD;AAChD,MAAM,CAAC,MAAM,kBAAkB,GAAG,QAAQ,CAAC,YAAY,EAAE,cAAc,EAAE,oBAAoB,CAAC,CAAA;AAE9F,2DAA2D;AAC3D,MAAM,CAAC,MAAM,cAAc,GAAG,GAA2C,EAAE,CACzE,CAAC,CAAC,KAAK,CAAC,CAAC,kBAAkB,EAAE,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAA"}

package/dist/graph/types.d.ts

@@ -0,0 +1,33 @@
+import type { NodeId } from '#ids';
+import type { Edge } from './edge';
+import type { Path } from './nav/path';
+import type { Node } from './node';
+/**
+ * Graph result — what you read (from DB queries) and what crosses the
+ * wire. JSON-compatible by construction: `Path.toJSON` collapses
+ * embedded Path instances on `nodes`/`edges`/`aliases` to their raw
+ * strings, so `JSON.stringify(graphData)` round-trips losslessly
+ * through `parseGraph` / `Graph.fromWire`.
+ *
+ * `aliases` is an optional advisory sidecar of pre-computed typed
+ * semantic Paths by node id, supplied by producers that already walked
+ * the structure to produce them (notably the `get-tree` adapter, which
+ * computes them server-side as the source of truth for edge target
+ * upgrades). `Graph.from` seeds `PathIndex` with them so consumers can
+ * resolve any registered form (typed or absolute) to the same node
+ * regardless of how partial the local subgraph is.
+ *
+ * Tuple-array (not Map) shape for `aliases`: a `Map` collapses to `{}`
+ * under `JSON.stringify`, but a tuple array survives the wire intact —
+ * Path leaves serialize via `Path.toJSON`. Same shape on both sides of
+ * the wire. Drop the seed and any `Graph.from(getTreeResult)` over a
+ * partial subgraph silently misses typed-form lookups for nodes whose
+ * parent chain didn't fit in the requested depth — that's the bug
+ * class this primitive exists to kill.
+ */
+export type GraphData = {
+    nodes: Node[];
+    edges: Edge[];
+    aliases?: ReadonlyArray<readonly [NodeId, Path]>;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../graph/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAClC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAIlC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,EAAE,IAAI,EAAE,CAAA;IACb,KAAK,EAAE,IAAI,EAAE,CAAA;IACb,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAA;CACjD,CAAA"}

package/dist/graph/types.js

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

package/dist/graph/types.js.map

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

package/dist/graph/zod.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Zod schemas for Graph records — the boundary parse layer.
+ *
+ * `parseGraph(unknown)` routes untrusted input through this schema and then
+ * hands the validated payload to `Graph.from`. Custom narrower validators
+ * should extend `graphSchema` / `nodeSchema` / `edgeSchema` with zod's
+ * `.refine` / `.extend` operators, then call `Graph.from(schema.parse(input))`.
+ */
+import { z } from 'zod';
+import { Graph } from './graph';
+/**
+ * Wire-accepting schema for a graph payload.
+ *
+ * `aliases` is the optional producer-supplied typed-form alias sidecar
+ * (`Array<[nodeId, pathRaw]>` post-JSON). See {@link Graph.toWire} /
+ * {@link Graph.fromWire} for how it round-trips. Tuple-array shape is
+ * the same on the wire and in-process — `Path.toJSON` collapses each
+ * Path leaf to its raw string on serialize, and `aliasesFromWire`
+ * reverses that on parse. Each pair is validated structurally only —
+ * the `pathRaw` string is parsed via `parsePath` inside
+ * `aliasesFromWire`, which surfaces malformed paths as
+ * `PathParseError` at construction time, not here.
+ */
+export declare const graphSchema: z.ZodObject<{
+    nodes: z.ZodArray<z.ZodObject<{
+        class: z.ZodType<import("../domain").ClassPath, string | import("../domain").ClassPath, z.core.$ZodTypeInternals<import("../domain").ClassPath, string | import("../domain").ClassPath>>;
+        path: z.ZodType<import("./tree").AbsolutePath, string | import("./tree").AbsolutePath, z.core.$ZodTypeInternals<import("./tree").AbsolutePath, string | import("./tree").AbsolutePath>>;
+        props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        id: z.ZodOptional<z.ZodString>;
+        __labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        class: z.ZodType<import("../domain").ClassPath, string | import("../domain").ClassPath, z.core.$ZodTypeInternals<import("../domain").ClassPath, string | import("../domain").ClassPath>>;
+        source: z.ZodType<import("./nav").Path, string | import("./nav").Path, z.core.$ZodTypeInternals<import("./nav").Path, string | import("./nav").Path>>;
+        target: z.ZodType<import("./nav").Path, string | import("./nav").Path, z.core.$ZodTypeInternals<import("./nav").Path, string | import("./nav").Path>>;
+        slug: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./nav").Slug, string>>>;
+        props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        id: z.ZodOptional<z.ZodString>;
+        __labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        __type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>>>;
+}, z.core.$strip>;
+/**
+ * Boundary parse — validate untrusted JSON input via `graphSchema` and
+ * construct a `Graph`. Throws on schema violations (zod) or structural
+ * violations (`GraphValidationError`).
+ *
+ * Routes through {@link Graph.fromWire} so the producer-supplied
+ * `aliases` sidecar (when present) survives the boundary parse and
+ * seeds `PathIndex` — without this, a wire-shaped input round-tripped
+ * through `parseGraph` would silently lose its typed-form aliases on
+ * any partial subgraph.
+ *
+ * For trusted typed input, use `Graph.from` — it skips the schema step and
+ * only runs structural validation.
+ */
+export declare function parseGraph(input: unknown): Graph;
+export { nodeSchema } from './node/zod';
+export { edgeSchema } from './edge/zod';
+//# sourceMappingURL=zod.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"zod.d.ts","sourceRoot":"","sources":["../../graph/zod.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAOvB,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAG/B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;iBAItB,CAAA;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAOhD;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA"}

package/dist/graph/zod.js

@@ -0,0 +1,55 @@
+/**
+ * Zod schemas for Graph records — the boundary parse layer.
+ *
+ * `parseGraph(unknown)` routes untrusted input through this schema and then
+ * hands the validated payload to `Graph.from`. Custom narrower validators
+ * should extend `graphSchema` / `nodeSchema` / `edgeSchema` with zod's
+ * `.refine` / `.extend` operators, then call `Graph.from(schema.parse(input))`.
+ */
+import { z } from 'zod';
+import { edgeSchema } from './edge/zod';
+import { Graph } from './graph';
+import { nodeSchema } from './node/zod';
+/**
+ * Wire-accepting schema for a graph payload.
+ *
+ * `aliases` is the optional producer-supplied typed-form alias sidecar
+ * (`Array<[nodeId, pathRaw]>` post-JSON). See {@link Graph.toWire} /
+ * {@link Graph.fromWire} for how it round-trips. Tuple-array shape is
+ * the same on the wire and in-process — `Path.toJSON` collapses each
+ * Path leaf to its raw string on serialize, and `aliasesFromWire`
+ * reverses that on parse. Each pair is validated structurally only —
+ * the `pathRaw` string is parsed via `parsePath` inside
+ * `aliasesFromWire`, which surfaces malformed paths as
+ * `PathParseError` at construction time, not here.
+ */
+export const graphSchema = z.object({
+    nodes: z.array(nodeSchema),
+    edges: z.array(edgeSchema),
+    aliases: z.array(z.tuple([z.string(), z.string()])).optional(),
+});
+/**
+ * Boundary parse — validate untrusted JSON input via `graphSchema` and
+ * construct a `Graph`. Throws on schema violations (zod) or structural
+ * violations (`GraphValidationError`).
+ *
+ * Routes through {@link Graph.fromWire} so the producer-supplied
+ * `aliases` sidecar (when present) survives the boundary parse and
+ * seeds `PathIndex` — without this, a wire-shaped input round-tripped
+ * through `parseGraph` would silently lose its typed-form aliases on
+ * any partial subgraph.
+ *
+ * For trusted typed input, use `Graph.from` — it skips the schema step and
+ * only runs structural validation.
+ */
+export function parseGraph(input) {
+    const validated = graphSchema.parse(input);
+    return Graph.fromWire({
+        nodes: validated.nodes,
+        edges: validated.edges,
+        ...(validated.aliases ? { aliases: validated.aliases } : {}),
+    });
+}
+export { nodeSchema } from './node/zod';
+export { edgeSchema } from './edge/zod';
+//# sourceMappingURL=zod.js.map

package/dist/graph/zod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.js","sourceRoot":"","sources":["../../graph/zod.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAMvB,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC;IAC1B,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC;IAC1B,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC/D,CAAC,CAAA;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAC1C,OAAO,KAAK,CAAC,QAAQ,CAAC;QACpB,KAAK,EAAE,SAAS,CAAC,KAA4B;QAC7C,KAAK,EAAE,SAAS,CAAC,KAA4B;QAC7C,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,OAAiC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvF,CAAC,CAAA;AACJ,CAAC;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA"}