@astrale-os/kernel-core 0.4.1

package/dist/graph/tree/build/validate.js

@@ -0,0 +1,150 @@
+import { IdPath } from '#graph/nav/path';
+import {} from '#graph/tree/errors';
+import { hasId } from '#graph/tree/helpers';
+import { RelativePath } from '#graph/tree/path';
+/**
+ * Validate a set of nodes + containment edges as a well-formed tree shape.
+ *
+ * Returns a pure result describing:
+ * - which node is the root (or null if absent / multi)
+ * - the parent/child/slug maps
+ * - the address → node index used by edge endpoint resolution
+ * - enumerated violations (if any)
+ */
+export function validateShape(nodes, edges, refs, nodeById, 
+/**
+ * Optional fallback: resolve a typed semantic Path raw (DomainPath /
+ * ClassPath / InterfacePath / MethodPath) back to a node, when the
+ * structural index doesn't have a direct hit. Backed by the host
+ * Graph's PathIndex via `graph.nodes.get(parsePath(raw))`.
+ *
+ * Required when has_parent edges target nodes via a typed semantic
+ * form rather than AbsolutePath — the uniform endpoint-form rule
+ * for the kernel-meta domain produces this shape (e.g. `has_parent`
+ * → `/:my-domain.com` instead of `/some/abs/path`).
+ */
+nodeForRaw) {
+    const violations = [];
+    const addressToNode = new Map();
+    // ── Index every address form a node may be reached by ──
+    for (const n of nodes) {
+        if (n.path)
+            addressToNode.set(n.path.raw, n);
+        if (hasId(n)) {
+            addressToNode.set(String(n.id), n);
+            addressToNode.set(IdPath.from(n.id).raw, n);
+        }
+    }
+    // ── Phase 1: resolve has_parent edges → parent/child/slug maps ──
+    const parentOf = new Map();
+    const childrenOf = new Map();
+    const slugOf = new Map();
+    for (const edge of edges) {
+        if (edge.class?.raw !== refs.has_parent.raw)
+            continue;
+        const child = resolveEndpoint(edge.source, addressToNode, nodeById, nodeForRaw);
+        const parent = resolveEndpoint(edge.target, addressToNode, nodeById, nodeForRaw);
+        if (child === undefined || parent === undefined)
+            continue;
+        if (parentOf.has(child)) {
+            violations.push({ kind: 'multiple_parents', nodeRef: nodeRef(child, slugOf) });
+            continue;
+        }
+        parentOf.set(child, parent);
+        const siblings = childrenOf.get(parent);
+        if (siblings)
+            siblings.push(child);
+        else
+            childrenOf.set(parent, [child]);
+        if (edge.slug)
+            slugOf.set(child, edge.slug);
+    }
+    // ── Register relative slug refs once slugs are known ──
+    for (const n of nodes) {
+        const slug = slugOf.get(n);
+        if (slug) {
+            const slugRef = RelativePath.from(slug).raw;
+            if (!addressToNode.has(slugRef))
+                addressToNode.set(slugRef, n);
+        }
+    }
+    // ── Phase 2: find the root ──
+    // A root is a node with no outgoing has_parent. Per SPEC I1, the source
+    // Graph always has a node at `/` (auto-injected by Graph.from when absent).
+    // The `/` node is the kernel anchor, not necessarily THIS tree's root —
+    // Trees are typically mounted views over a subtree (e.g., rooted at
+    // `/origin`). When `/` coexists with another parent-less candidate, prefer
+    // the other: `/` is implicitly "above" the tree.
+    const allCandidates = [];
+    for (const n of nodes)
+        if (!parentOf.has(n))
+            allCandidates.push(n);
+    const rootCandidates = allCandidates.length > 1 ? allCandidates.filter((n) => n.path.raw !== '/') : allCandidates;
+    if (rootCandidates.length === 0) {
+        violations.push({ kind: 'no_root' });
+        return finalize(null, parentOf, childrenOf, slugOf, addressToNode, violations);
+    }
+    if (rootCandidates.length > 1) {
+        violations.push({
+            kind: 'multiple_roots',
+            nodeRefs: rootCandidates.map((n) => nodeRef(n, slugOf)),
+        });
+        return finalize(null, parentOf, childrenOf, slugOf, addressToNode, violations);
+    }
+    const rootNode = rootCandidates[0];
+    // ── Phase 3: slug validation ──
+    for (const n of nodes) {
+        if (n === rootNode)
+            continue;
+        if (!slugOf.has(n)) {
+            violations.push({ kind: 'missing_slug', nodeRef: hasId(n) ? String(n.id) : '(no id)' });
+        }
+    }
+    for (const [parent, children] of childrenOf) {
+        const slugCounts = new Map();
+        for (const child of children) {
+            const slug = slugOf.get(child);
+            if (!slug)
+                continue;
+            const list = slugCounts.get(slug);
+            if (list)
+                list.push(child);
+            else
+                slugCounts.set(slug, [child]);
+        }
+        for (const [slug, dupes] of slugCounts) {
+            if (dupes.length > 1) {
+                violations.push({
+                    kind: 'duplicate_sibling_slug',
+                    parentRef: nodeRef(parent, slugOf),
+                    slug,
+                    nodeRefs: dupes.map((n) => (hasId(n) ? String(n.id) : nodeRef(n, slugOf))),
+                });
+            }
+        }
+    }
+    return finalize(rootNode, parentOf, childrenOf, slugOf, addressToNode, violations);
+}
+// ─── Helpers ─────────────────────────────────────────────────────────
+function finalize(rootNode, parentOf, childrenOf, slugOf, addressToNode, violations) {
+    return { rootNode, parentOf, childrenOf, slugOf, addressToNode, violations };
+}
+/** Resolve an edge endpoint (any path raw) to a node. */
+function resolveEndpoint(ep, addressToNode, nodeById, nodeForRaw) {
+    const directId = IdPath.tryParse(ep.raw)?.id;
+    const direct = addressToNode.get(ep.raw);
+    if (direct)
+        return direct;
+    if (directId) {
+        return addressToNode.get(directId) ?? nodeById.get(directId);
+    }
+    // Fallback for typed semantic Path raws (DomainPath/ClassPath/etc.)
+    // not present in the local addressToNode index. Backed by the host
+    // Graph's PathIndex when available.
+    return nodeForRaw?.(ep.raw);
+}
+/** Best-effort identifier for a node in error messages. */
+function nodeRef(n, slugOf) {
+    return slugOf.get(n) ?? (hasId(n) ? String(n.id) : (n.path?.raw ?? '(unknown)'));
+}
+//# sourceMappingURL=validate.js.map

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

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

package/dist/graph/tree/edge/endpoint.d.ts

@@ -0,0 +1,29 @@
+import type { NodeSpec } from '#graph';
+import type { Path } from '#graph/nav/path';
+import type { InTree } from '#graph/tree/types';
+/**
+ * An endpoint of an edge, resolved against a specific Tree.
+ *
+ * - `internal`: the endpoint is a node in this Tree. The overlay `node` is
+ *   directly accessible.
+ * - `external`: the endpoint points at something outside this Tree. Only
+ *   its raw address is available; it must be resolved elsewhere (another
+ *   Tree, a Graph, or re-fetched) before it can be interpreted as a node.
+ */
+export type Endpoint<N extends NodeSpec> = {
+    readonly kind: 'internal';
+    readonly node: InTree<N>;
+} | {
+    readonly kind: 'external';
+    readonly address: Path;
+};
+/** Type guards for ergonomic filtering. */
+export declare const Endpoint: {
+    isInternal<N extends NodeSpec>(ep: Endpoint<N>): ep is Extract<Endpoint<N>, {
+        kind: 'internal';
+    }>;
+    isExternal<N_1 extends NodeSpec>(ep: Endpoint<N_1>): ep is Extract<Endpoint<N_1>, {
+        kind: 'external';
+    }>;
+};
+//# sourceMappingURL=endpoint.d.ts.map

package/dist/graph/tree/edge/endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../../../../graph/tree/edge/endpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/C;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,QAAQ,IACnC;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,CAAA;AAEzD,2CAA2C;AAC3C,eAAO,MAAM,QAAQ;IACnB,UAAU,CAAC,CAAC,SAAS,QAAQ,MACvB,QAAQ,CAAC,CAAC,CAAC,GACd,EAAE,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,CAAC;IAInD,UAAU,CAAC,GAAC,SAAS,QAAQ,MACvB,QAAQ,CAAC,GAAC,CAAC,GACd,EAAE,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAC,CAAC,EAAE;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,CAAC;CAGpD,CAAA"}

package/dist/graph/tree/edge/endpoint.js

@@ -0,0 +1,10 @@
+/** Type guards for ergonomic filtering. */
+export const Endpoint = {
+    isInternal(ep) {
+        return ep.kind === 'internal';
+    },
+    isExternal(ep) {
+        return ep.kind === 'external';
+    },
+};
+//# sourceMappingURL=endpoint.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.js","sourceRoot":"","sources":["../../../../graph/tree/edge/endpoint.ts"],"names":[],"mappings":"AAiBA,2CAA2C;AAC3C,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,UAAU,CACR,EAAe;QAEf,OAAO,EAAE,CAAC,IAAI,KAAK,UAAU,CAAA;IAC/B,CAAC;IAED,UAAU,CACR,EAAe;QAEf,OAAO,EAAE,CAAC,IAAI,KAAK,UAAU,CAAA;IAC/B,CAAC;CACF,CAAA"}

package/dist/graph/tree/edge/index.d.ts

@@ -0,0 +1,5 @@
+export type { Endpoint } from './endpoint';
+export { Endpoint as EndpointGuards } from './endpoint';
+export type { EdgeClass, TreeEdge } from './tree-edge';
+export { classifyEndpoints } from './tree-edge';
+//# sourceMappingURL=index.d.ts.map

package/dist/graph/tree/edge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../graph/tree/edge/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,YAAY,CAAA;AACvD,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA"}

package/dist/graph/tree/edge/index.js

@@ -0,0 +1,3 @@
+export { Endpoint as EndpointGuards } from './endpoint';
+export { classifyEndpoints } from './tree-edge';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../graph/tree/edge/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,YAAY,CAAA;AAEvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA"}

package/dist/graph/tree/edge/tree-edge.d.ts

@@ -0,0 +1,35 @@
+import type { ClassPath } from '#domain';
+import type { EdgeSpec, NodeSpec } from '#graph';
+import type { Endpoint } from './endpoint';
+/**
+ * Where each endpoint of an edge lives relative to a given Tree.
+ *
+ * - `internal`  — both endpoints are nodes in the Tree.
+ * - `outgoing`  — source is internal, target is external.
+ * - `incoming`  — source is external, target is internal.
+ * - `disconnected` — neither endpoint resolves into the Tree.
+ */
+export type EdgeClass = 'internal' | 'outgoing' | 'incoming' | 'disconnected';
+/**
+ * An edge seen through the lens of a Tree.
+ *
+ * `raw` is the underlying graph edge (unchanged). `source` and `target` are
+ * resolved against the Tree's membership — internal endpoints carry the
+ * overlay node, external endpoints carry only the raw address.
+ *
+ * `classification` is the combined internal/outgoing/incoming/disconnected
+ * label, precomputed for ergonomic filtering.
+ */
+export interface TreeEdge<N extends NodeSpec, E extends EdgeSpec> {
+    readonly raw: E;
+    readonly source: Endpoint<N>;
+    readonly target: Endpoint<N>;
+    readonly classification: EdgeClass;
+    readonly class: ClassPath;
+}
+/**
+ * Compute the classification from two endpoints.
+ * @internal
+ */
+export declare function classifyEndpoints<N extends NodeSpec>(source: Endpoint<N>, target: Endpoint<N>): EdgeClass;
+//# sourceMappingURL=tree-edge.d.ts.map

package/dist/graph/tree/edge/tree-edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-edge.d.ts","sourceRoot":"","sources":["../../../../graph/tree/edge/tree-edge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEhD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1C;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,cAAc,CAAA;AAE7E;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ;IAC9D,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAA;IACf,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;IAC5B,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAA;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAC1B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,QAAQ,EAClD,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,GAClB,SAAS,CAOX"}

package/dist/graph/tree/edge/tree-edge.js

@@ -0,0 +1,16 @@
+/**
+ * Compute the classification from two endpoints.
+ * @internal
+ */
+export function classifyEndpoints(source, target) {
+    const srcIn = source.kind === 'internal';
+    const tgtIn = target.kind === 'internal';
+    if (srcIn && tgtIn)
+        return 'internal';
+    if (srcIn)
+        return 'outgoing';
+    if (tgtIn)
+        return 'incoming';
+    return 'disconnected';
+}
+//# sourceMappingURL=tree-edge.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree-edge.js","sourceRoot":"","sources":["../../../../graph/tree/edge/tree-edge.ts"],"names":[],"mappings":"AAiCA;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAmB,EACnB,MAAmB;IAEnB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,KAAK,UAAU,CAAA;IACxC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,KAAK,UAAU,CAAA;IACxC,IAAI,KAAK,IAAI,KAAK;QAAE,OAAO,UAAU,CAAA;IACrC,IAAI,KAAK;QAAE,OAAO,UAAU,CAAA;IAC5B,IAAI,KAAK;QAAE,OAAO,UAAU,CAAA;IAC5B,OAAO,cAAc,CAAA;AACvB,CAAC"}

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

@@ -0,0 +1,32 @@
+export type TreeViolation = {
+    kind: 'no_root';
+} | {
+    kind: 'multiple_roots';
+    nodeRefs: string[];
+} | {
+    kind: 'missing_parent';
+    nodeRef: string;
+} | {
+    kind: 'multiple_parents';
+    nodeRef: string;
+} | {
+    kind: 'cycle';
+    nodeRefs: string[];
+} | {
+    kind: 'parent_not_found';
+    nodeRef: string;
+    targetRef: string;
+} | {
+    kind: 'missing_slug';
+    nodeRef: string;
+} | {
+    kind: 'duplicate_sibling_slug';
+    parentRef: string;
+    slug: string;
+    nodeRefs: string[];
+};
+export declare class TreeValidationError extends Error {
+    readonly violations: readonly TreeViolation[];
+    constructor(violations: TreeViolation[]);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../graph/tree/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAC3F,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAA;IAE7C,YAAY,UAAU,EAAE,aAAa,EAAE,EAyBtC;CACF"}

package/dist/graph/tree/errors.js

@@ -0,0 +1,30 @@
+export class TreeValidationError extends Error {
+    violations;
+    constructor(violations) {
+        const summary = violations.slice(0, 5).map((v) => {
+            switch (v.kind) {
+                case 'no_root':
+                    return 'no root node found';
+                case 'multiple_roots':
+                    return `multiple roots: [${v.nodeRefs.join(', ')}]`;
+                case 'missing_parent':
+                    return `node "${v.nodeRef}" has no has_parent edge`;
+                case 'multiple_parents':
+                    return `node "${v.nodeRef}" has multiple has_parent edges`;
+                case 'cycle':
+                    return `cycle detected involving [${v.nodeRefs.join(', ')}]`;
+                case 'parent_not_found':
+                    return `node "${v.nodeRef}" references missing parent "${v.targetRef}"`;
+                case 'missing_slug':
+                    return `node "${v.nodeRef}" has no slug`;
+                case 'duplicate_sibling_slug':
+                    return `duplicate slug "${v.slug}" under parent "${v.parentRef}"`;
+            }
+        });
+        const suffix = violations.length > 5 ? ` (and ${violations.length - 5} more)` : '';
+        super(`Tree validation failed: ${summary.join('; ')}${suffix}`);
+        this.name = 'TreeValidationError';
+        this.violations = Object.freeze(violations);
+    }
+}
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../graph/tree/errors.ts"],"names":[],"mappings":"AASA,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,UAAU,CAA0B;IAE7C,YAAY,UAA2B;QACrC,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YAC/C,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;gBACf,KAAK,SAAS;oBACZ,OAAO,oBAAoB,CAAA;gBAC7B,KAAK,gBAAgB;oBACnB,OAAO,oBAAoB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAA;gBACrD,KAAK,gBAAgB;oBACnB,OAAO,SAAS,CAAC,CAAC,OAAO,0BAA0B,CAAA;gBACrD,KAAK,kBAAkB;oBACrB,OAAO,SAAS,CAAC,CAAC,OAAO,iCAAiC,CAAA;gBAC5D,KAAK,OAAO;oBACV,OAAO,6BAA6B,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAA;gBAC9D,KAAK,kBAAkB;oBACrB,OAAO,SAAS,CAAC,CAAC,OAAO,gCAAgC,CAAC,CAAC,SAAS,GAAG,CAAA;gBACzE,KAAK,cAAc;oBACjB,OAAO,SAAS,CAAC,CAAC,OAAO,eAAe,CAAA;gBAC1C,KAAK,wBAAwB;oBAC3B,OAAO,mBAAmB,CAAC,CAAC,IAAI,mBAAmB,CAAC,CAAC,SAAS,GAAG,CAAA;YACrE,CAAC;QACH,CAAC,CAAC,CAAA;QACF,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAA;QAClF,KAAK,CAAC,2BAA2B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,CAAA;QAC/D,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;QACjC,IAAI,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;IAC7C,CAAC;CACF"}

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

@@ -0,0 +1,12 @@
+import type { NodeId } from '#ids';
+/**
+ * Type guard: node has a database identity (id field).
+ *
+ * Constrained on `object` rather than `NodeSpec` so the tree overlay
+ * (`InTree<N>`, whose `path` is `RelativePath`) is also accepted — the
+ * predicate only reads `.id` and is orthogonal to the path frame.
+ */
+export declare function hasId<N extends object>(n: N): n is N & {
+    id: NodeId;
+};
+//# sourceMappingURL=helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../graph/tree/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAErE"}

package/dist/graph/tree/helpers.js

@@ -0,0 +1,11 @@
+/**
+ * Type guard: node has a database identity (id field).
+ *
+ * Constrained on `object` rather than `NodeSpec` so the tree overlay
+ * (`InTree<N>`, whose `path` is `RelativePath`) is also accepted — the
+ * predicate only reads `.id` and is orthogonal to the path frame.
+ */
+export function hasId(n) {
+    return 'id' in n && n.id !== undefined;
+}
+//# sourceMappingURL=helpers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../graph/tree/helpers.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAmB,CAAI;IAC1C,OAAO,IAAI,IAAI,CAAC,IAAK,CAAsB,CAAC,EAAE,KAAK,SAAS,CAAA;AAC9D,CAAC"}

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

@@ -0,0 +1,12 @@
+export type { InTree, TreeNode, TreeRefs, TreeOptions } from './types';
+export { hasId } from './helpers';
+export { Tree } from './tree';
+export { buildTree } from './build';
+export { TreeValidationError, type TreeViolation } from './errors';
+export type { EdgeClass, TreeEdge, Endpoint } from './edge';
+export { classifyEndpoints } from './edge';
+export type { TreePath } from './path';
+export { AbsolutePath, RelativePath } from './path';
+export { TREE_EDGE_TYPE, SLUG_PROPERTY, SLUG_RE, SEPARATOR_CHAR } from './path';
+export { treePathSchema, absolutePathSchema, relativePathSchema } from './zod';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../graph/tree/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACtE,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACnC,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAA;AAGlE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAA;AAG1C,YAAY,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAG/E,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAA"}

package/dist/graph/tree/index.js

@@ -0,0 +1,10 @@
+export { hasId } from './helpers';
+export { Tree } from './tree';
+export { buildTree } from './build';
+export { TreeValidationError } from './errors';
+export { classifyEndpoints } from './edge';
+export { AbsolutePath, RelativePath } from './path';
+export { TREE_EDGE_TYPE, SLUG_PROPERTY, SLUG_RE, SEPARATOR_CHAR } from './path';
+// ─── Zod factories ──────────────────────────────────────────
+export { treePathSchema, absolutePathSchema, relativePathSchema } from './zod';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../graph/tree/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACnC,OAAO,EAAE,mBAAmB,EAAsB,MAAM,UAAU,CAAA;AAIlE,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAA;AAI1C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAA;AAE/E,+DAA+D;AAC/D,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAA"}

package/dist/graph/tree/path/absolute/constants.d.ts

@@ -0,0 +1,8 @@
+export { SLUG_PROPERTY, SLUG_RE } from '#graph/nav/ast/slug';
+/** Edge type for parent-child tree relationships. */
+export declare const TREE_EDGE_TYPE = "has_parent";
+/** Separator character for tree path segments. */
+export declare const SEPARATOR_CHAR = "/";
+/** The root node's class string (opaque, schema-side ground truth). */
+export declare const ROOT_CLASS = "Root";
+//# sourceMappingURL=constants.d.ts.map

package/dist/graph/tree/path/absolute/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../../graph/tree/path/absolute/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE5D,qDAAqD;AACrD,eAAO,MAAM,cAAc,eAAe,CAAA;AAE1C,kDAAkD;AAClD,eAAO,MAAM,cAAc,MAAM,CAAA;AAEjC,uEAAuE;AACvE,eAAO,MAAM,UAAU,SAAS,CAAA"}

package/dist/graph/tree/path/absolute/constants.js

@@ -0,0 +1,8 @@
+export { SLUG_PROPERTY, SLUG_RE } from '#graph/nav/ast/slug';
+/** Edge type for parent-child tree relationships. */
+export const TREE_EDGE_TYPE = 'has_parent';
+/** Separator character for tree path segments. */
+export const SEPARATOR_CHAR = '/';
+/** The root node's class string (opaque, schema-side ground truth). */
+export const ROOT_CLASS = 'Root';
+//# sourceMappingURL=constants.js.map

package/dist/graph/tree/path/absolute/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../graph/tree/path/absolute/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE5D,qDAAqD;AACrD,MAAM,CAAC,MAAM,cAAc,GAAG,YAAY,CAAA;AAE1C,kDAAkD;AAClD,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAA;AAEjC,uEAAuE;AACvE,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAA"}

package/dist/graph/tree/path/absolute/grammar.d.ts

@@ -0,0 +1,12 @@
+import type { GrammarExtension } from '#graph/nav/grammar';
+/**
+ * Absolute-tree sugar: `/`-separated slugs.
+ *
+ * A leading `/` plus an identifier (`/foo`) emits one inbound
+ * `has_parent` traversal keyed by the slug. Sequences chain:
+ * `/foo/bar/baz` → three steps. Bare `/` (root) consumes nothing.
+ *
+ * Pure of any graph access — round-trips characters ↔ Step[].
+ */
+export declare const absoluteGrammar: GrammarExtension;
+//# sourceMappingURL=grammar.d.ts.map

package/dist/graph/tree/path/absolute/grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../../../../graph/tree/path/absolute/grammar.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAmB,MAAM,oBAAoB,CAAA;AAO3E;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,gBA2F7B,CAAA"}

package/dist/graph/tree/path/absolute/grammar.js

@@ -0,0 +1,110 @@
+import { INBOUND, isRootAnchor } from '#graph/nav/path/step';
+import { SEPARATOR_CHAR, SLUG_PROPERTY, SLUG_RE, TREE_EDGE_TYPE } from './constants';
+/**
+ * Absolute-tree sugar: `/`-separated slugs.
+ *
+ * A leading `/` plus an identifier (`/foo`) emits one inbound
+ * `has_parent` traversal keyed by the slug. Sequences chain:
+ * `/foo/bar/baz` → three steps. Bare `/` (root) consumes nothing.
+ *
+ * Pure of any graph access — round-trips characters ↔ Step[].
+ */
+export const absoluteGrammar = {
+    name: 'absolute',
+    tokens: [{ chars: SEPARATOR_CHAR, kind: 'SEPARATOR', priority: 0 }],
+    parseStep(stream) {
+        const head = stream.peek();
+        // Bare `<slug>` after a relative prefix is consumed — the relative
+        // grammar consumes `./` but leaves the slug chain untouched, so we
+        // claim the leading bare slug here. Subsequent slugs come through
+        // SEPARATOR-led iterations.
+        if (head?.kind === 'TEXT') {
+            if (!SLUG_RE.test(head.value))
+                return null;
+            const lookMark = stream.mark();
+            stream.advance();
+            const next = stream.peek();
+            if (next &&
+                next.kind !== 'SEPARATOR' &&
+                next.kind !== 'TILDE' &&
+                next.kind !== 'LT' &&
+                next.kind !== 'PAREN_OPEN' &&
+                next.kind !== 'DOMAIN_SEP' &&
+                next.kind !== 'INSTANCE_SEP') {
+                stream.restore(lookMark);
+                return null;
+            }
+            return [slugTraversal(head.value)];
+        }
+        if (!head || head.kind !== 'SEPARATOR')
+            return null;
+        const mark = stream.mark();
+        stream.advance(); // consume '/'
+        const slug = stream.peek();
+        // `/<slug>` — emit one inbound has_parent traversal.
+        if (slug?.kind === 'TEXT') {
+            if (!SLUG_RE.test(slug.value)) {
+                stream.restore(mark);
+                return null;
+            }
+            stream.advance();
+            return [slugTraversal(slug.value)];
+        }
+        // `//` (consecutive separators) or `/<core-token>` (`/~edge`, `/<~edge`,
+        // `/@id`, `/(...)`) — these are not valid absolute sugar. Restore so the
+        // outer dispatch can either let another extension claim them or emit an
+        // unexpected-token error. Restoring + returning `null` gives the outer
+        // loop a chance to make progress on the offending token directly.
+        if (!slug ||
+            slug.kind === 'SEPARATOR' ||
+            slug.kind === 'AT' ||
+            slug.kind === 'TILDE' ||
+            slug.kind === 'LT' ||
+            slug.kind === 'PAREN_OPEN') {
+            // End-of-stream `/` (root path) is the one exception: consume the
+            // separator and emit no steps. Caller assembles the empty Step[] into
+            // an AbsolutePath via the registry.
+            if (!slug)
+                return [];
+            stream.restore(mark);
+            return null;
+        }
+        // `/<extension-token>` (e.g. `/:domain`): the `/` is absolute-scheme
+        // sugar, the next token belongs to a different extension. Consume the
+        // `/`, emit no step, let the next iteration claim the extension token.
+        return [];
+    },
+    serializeStep(step) {
+        // The root anchor at the start of every absolute path serializes
+        // to nothing — the leading `/` of the first traversal carries the
+        // absolute prefix on the wire. The `'' || '/'` fallback in the
+        // root-only path case handles `[ROOT_ANCHOR]` → `/`.
+        if (step.kind === 'anchor') {
+            return isRootAnchor(step) ? '' : null;
+        }
+        if (step.edgeClass !== TREE_EDGE_TYPE)
+            return null;
+        if (step.from !== INBOUND.from || step.to !== INBOUND.to)
+            return null;
+        const p = step.predicate;
+        if (!p || p.kind !== 'property' || p.scope !== 'edge' || p.property !== SLUG_PROPERTY) {
+            return null;
+        }
+        return `${SEPARATOR_CHAR}${p.value}`;
+    },
+};
+function slugTraversal(slug) {
+    return {
+        kind: 'traversal',
+        edgeClass: TREE_EDGE_TYPE,
+        ...INBOUND,
+        predicate: {
+            kind: 'property',
+            scope: 'edge',
+            property: SLUG_PROPERTY,
+            op: '=',
+            value: slug,
+        },
+    };
+}
+//# sourceMappingURL=grammar.js.map

package/dist/graph/tree/path/absolute/grammar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar.js","sourceRoot":"","sources":["../../../../../graph/tree/path/absolute/grammar.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAE5D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEpF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAqB;IAC/C,IAAI,EAAE,UAAU;IAEhB,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,EAAE,CAA6B;IAE/F,SAAS,CAAC,MAAmB;QAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;QAE1B,mEAAmE;QACnE,mEAAmE;QACnE,kEAAkE;QAClE,4BAA4B;QAC5B,IAAI,IAAI,EAAE,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAA;YAC1C,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;YAC9B,MAAM,CAAC,OAAO,EAAE,CAAA;YAChB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;YAC1B,IACE,IAAI;gBACJ,IAAI,CAAC,IAAI,KAAK,WAAW;gBACzB,IAAI,CAAC,IAAI,KAAK,OAAO;gBACrB,IAAI,CAAC,IAAI,KAAK,IAAI;gBAClB,IAAI,CAAC,IAAI,KAAK,YAAY;gBAC1B,IAAI,CAAC,IAAI,KAAK,YAAY;gBAC1B,IAAI,CAAC,IAAI,KAAK,cAAc,EAC5B,CAAC;gBACD,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;gBACxB,OAAO,IAAI,CAAA;YACb,CAAC;YACD,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;QACpC,CAAC;QAED,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW;YAAE,OAAO,IAAI,CAAA;QAEnD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;QAC1B,MAAM,CAAC,OAAO,EAAE,CAAA,CAAC,cAAc;QAC/B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;QAE1B,qDAAqD;QACrD,IAAI,IAAI,EAAE,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC9B,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;gBACpB,OAAO,IAAI,CAAA;YACb,CAAC;YACD,MAAM,CAAC,OAAO,EAAE,CAAA;YAChB,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;QACpC,CAAC;QAED,yEAAyE;QACzE,yEAAyE;QACzE,wEAAwE;QACxE,uEAAuE;QACvE,kEAAkE;QAClE,IACE,CAAC,IAAI;YACL,IAAI,CAAC,IAAI,KAAK,WAAW;YACzB,IAAI,CAAC,IAAI,KAAK,IAAI;YAClB,IAAI,CAAC,IAAI,KAAK,OAAO;YACrB,IAAI,CAAC,IAAI,KAAK,IAAI;YAClB,IAAI,CAAC,IAAI,KAAK,YAAY,EAC1B,CAAC;YACD,kEAAkE;YAClE,sEAAsE;YACtE,oCAAoC;YACpC,IAAI,CAAC,IAAI;gBAAE,OAAO,EAAE,CAAA;YACpB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;YACpB,OAAO,IAAI,CAAA;QACb,CAAC;QAED,qEAAqE;QACrE,sEAAsE;QACtE,uEAAuE;QACvE,OAAO,EAAE,CAAA;IACX,CAAC;IAED,aAAa,CAAC,IAAU;QACtB,iEAAiE;QACjE,kEAAkE;QAClE,+DAA+D;QAC/D,qDAAqD;QACrD,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3B,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;QACvC,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,KAAK,cAAc;YAAE,OAAO,IAAI,CAAA;QAClD,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE;YAAE,OAAO,IAAI,CAAA;QACrE,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAA;QACxB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM,IAAI,CAAC,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;YACtF,OAAO,IAAI,CAAA;QACb,CAAC;QACD,OAAO,GAAG,cAAc,GAAG,CAAC,CAAC,KAAK,EAAE,CAAA;IACtC,CAAC;CACF,CAAA;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,SAAS,EAAE,cAAc;QACzB,GAAG,OAAO;QACV,SAAS,EAAE;YACT,IAAI,EAAE,UAAU;YAChB,KAAK,EAAE,MAAM;YACb,QAAQ,EAAE,aAAa;YACvB,EAAE,EAAE,GAAG;YACP,KAAK,EAAE,IAAI;SACZ;KACF,CAAA;AACH,CAAC"}

package/dist/graph/tree/path/absolute/index.d.ts

@@ -0,0 +1,6 @@
+export { AbsolutePath, absolutePathType } from './type';
+export { absoluteGrammar } from './grammar';
+export { absoluteSegment } from './segment';
+export { registerAbsolutePath } from './register';
+export { TREE_EDGE_TYPE, SLUG_PROPERTY, SEPARATOR_CHAR, SLUG_RE, ROOT_CLASS } from './constants';
+//# sourceMappingURL=index.d.ts.map

package/dist/graph/tree/path/absolute/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../graph/tree/path/absolute/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA"}

package/dist/graph/tree/path/absolute/index.js

@@ -0,0 +1,6 @@
+export { AbsolutePath, absolutePathType } from './type';
+export { absoluteGrammar } from './grammar';
+export { absoluteSegment } from './segment';
+export { registerAbsolutePath } from './register';
+export { TREE_EDGE_TYPE, SLUG_PROPERTY, SEPARATOR_CHAR, SLUG_RE, ROOT_CLASS } from './constants';
+//# sourceMappingURL=index.js.map

package/dist/graph/tree/path/absolute/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../graph/tree/path/absolute/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA"}

package/dist/graph/tree/path/absolute/register.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Wire the absolute scheme into the new nav registries.
+ *
+ * Idempotent — registries dedupe identity-equal registrations, so it's
+ * safe to call this from the kernel boot path and from individual
+ * tests that want absolute paths available.
+ */
+export declare function registerAbsolutePath(): void;
+//# sourceMappingURL=register.d.ts.map