@astrale-os/kernel-core 0.4.1

package/dist/graph/sync/remote/fold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.d.ts","sourceRoot":"","sources":["../../../../graph/sync/remote/fold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,KAAK,EAAoB,UAAU,EAAE,UAAU,EAAE,MAAM,MAAM,CAAA;AAEpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AAcxC;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU,CAW3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,EAChC,IAAI,EAAE,UAAU,GACf,UAAU,GAAG,SAAS,CASxB;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAC3B,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,EAChC,IAAI,EAAE,UAAU,GACf,UAAU,GAAG,SAAS,CAIxB"}

package/dist/graph/sync/remote/fold.js

@@ -0,0 +1,74 @@
+/**
+ * Fold and unfold helpers between structured `RemoteSpec` and flat property keys.
+ *
+ * Remote metadata lives as plain properties on the graph — there is no separate
+ * `.remote` field. These helpers give typed access when callers want it:
+ *
+ *   foldRemote(remote, keys) → property bag with domain-qualified keys set
+ *   unfoldRemote(properties, keys) → RemoteSpec view, or undefined if no externalId
+ *
+ * Both are pure and keys-agnostic — the kernel passes `REMOTE_KEYS`, but any
+ * other Remotable-like interface could supply its own key mapping.
+ */
+const CONFLICT_STRATEGIES = new Set([
+    'merge',
+    'replace',
+    'defaults',
+    'skip',
+    'error',
+]);
+function isConflictStrategy(value) {
+    return typeof value === 'string' && CONFLICT_STRATEGIES.has(value);
+}
+/**
+ * Fold a RemoteSpec into a partial property bag. Undefined fields are omitted.
+ *
+ * Empty `externalId` ('') is rejected: `unfoldRemote` treats absent and ''
+ * identically (no remote identity), so writing '' would round-trip to lose
+ * `updatedAt` / `onConflict` silently. Callers must omit `externalId` rather
+ * than pass empty.
+ */
+export function foldRemote(remote, keys) {
+    const out = {};
+    if (remote.externalId !== undefined) {
+        if (remote.externalId === '') {
+            throw new Error('foldRemote: externalId must not be empty (use undefined to omit)');
+        }
+        out[keys.externalId] = remote.externalId;
+    }
+    if (remote.updatedAt !== undefined)
+        out[keys.updatedAt] = remote.updatedAt;
+    if (remote.onConflict !== undefined)
+        out[keys.onConflict] = remote.onConflict;
+    return out;
+}
+/**
+ * Read a RemoteSpec from a property bag. Returns undefined when externalId is absent —
+ * untracked entities have no remote identity.
+ *
+ * `onConflict` is validated against the closed `ConflictStrategy` union.
+ * Unknown / typo'd values are dropped (omitted from the result) rather than
+ * blindly cast — downstream `resolveStrategy` would silently fall back to
+ * 'merge', masking the configuration error.
+ */
+export function unfoldRemote(properties, keys) {
+    const externalId = properties[keys.externalId];
+    if (typeof externalId !== 'string' || externalId === '')
+        return undefined;
+    const out = { externalId: externalId };
+    const updatedAt = properties[keys.updatedAt];
+    if (typeof updatedAt === 'string')
+        out.updatedAt = updatedAt;
+    const onConflict = properties[keys.onConflict];
+    if (isConflictStrategy(onConflict))
+        out.onConflict = onConflict;
+    return out;
+}
+/** Read just the externalId. Returns undefined if absent or empty. */
+export function getExternalId(properties, keys) {
+    const value = properties[keys.externalId];
+    if (typeof value !== 'string' || value === '')
+        return undefined;
+    return value;
+}
+//# sourceMappingURL=fold.js.map

package/dist/graph/sync/remote/fold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.js","sourceRoot":"","sources":["../../../../graph/sync/remote/fold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAmB;IACpD,OAAO;IACP,SAAS;IACT,UAAU;IACV,MAAM;IACN,OAAO;CACR,CAAC,CAAA;AAEF,SAAS,kBAAkB,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,mBAAmB,CAAC,GAAG,CAAC,KAAyB,CAAC,CAAA;AACxF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,MAAkB,EAAE,IAAgB;IAC7D,MAAM,GAAG,GAAe,EAAE,CAAA;IAC1B,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACpC,IAAI,MAAM,CAAC,UAAU,KAAK,EAAE,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAA;QACrF,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,UAAU,CAAA;IAC1C,CAAC;IACD,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;QAAE,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,SAAS,CAAA;IAC1E,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS;QAAE,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,UAAU,CAAA;IAC7E,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAC1B,UAAgC,EAChC,IAAgB;IAEhB,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IAC9C,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,EAAE;QAAE,OAAO,SAAS,CAAA;IACzE,MAAM,GAAG,GAAe,EAAE,UAAU,EAAE,UAAwB,EAAE,CAAA;IAChE,MAAM,SAAS,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IAC5C,IAAI,OAAO,SAAS,KAAK,QAAQ;QAAE,GAAG,CAAC,SAAS,GAAG,SAAS,CAAA;IAC5D,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IAC9C,IAAI,kBAAkB,CAAC,UAAU,CAAC;QAAE,GAAG,CAAC,UAAU,GAAG,UAAU,CAAA;IAC/D,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,aAAa,CAC3B,UAAgC,EAChC,IAAgB;IAEhB,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,SAAS,CAAA;IAC/D,OAAO,KAAmB,CAAA;AAC5B,CAAC"}

package/dist/graph/sync/remote/index.d.ts

@@ -0,0 +1,4 @@
+export type { RemoteKeys } from './keys';
+export { foldRemote, unfoldRemote, getExternalId } from './fold';
+export type { ExternalId, RemoteSpec, ConflictStrategy } from '#ids';
+//# sourceMappingURL=index.d.ts.map

package/dist/graph/sync/remote/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../graph/sync/remote/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAChE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,MAAM,CAAA"}

package/dist/graph/sync/remote/index.js

@@ -0,0 +1,2 @@
+export { foldRemote, unfoldRemote, getExternalId } from './fold';
+//# sourceMappingURL=index.js.map

package/dist/graph/sync/remote/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../graph/sync/remote/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA"}

package/dist/graph/sync/remote/keys.d.ts

@@ -0,0 +1,17 @@
+/**
+ * RemoteKeys — domain-qualified property keys for Remotable metadata.
+ *
+ * Remote metadata (externalId, updatedAt, onConflict) is stored as plain
+ * properties under domain-qualified keys, e.g.
+ *   "kernel.astrale.ai:interface.Remotable.property.externalId"
+ *
+ * Core/graph has no knowledge of the domain layer, so callers inject the
+ * concrete keys. The kernel's bindings live in `@astrale-os/kernel-core/domain`
+ * as `REMOTE_KEYS`.
+ */
+export interface RemoteKeys {
+    readonly externalId: string;
+    readonly updatedAt: string;
+    readonly onConflict: string;
+}
+//# sourceMappingURL=keys.d.ts.map

package/dist/graph/sync/remote/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../../graph/sync/remote/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B"}

package/dist/graph/sync/remote/keys.js

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

package/dist/graph/sync/remote/keys.js.map

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

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

@@ -0,0 +1,62 @@
+/**
+ * Tree round-trip helpers for the typed-form alias sidecar
+ * (`Graph.aliases`).
+ *
+ * The `Tree` ↔ `Graph` round-trip lifts internal endpoints to relative
+ * paths in `_collectPortable` and re-anchors them in `toGraph` under
+ * `mount`. That round-trip would lose any typed semantic Path
+ * (`DomainPath`/`ClassPath`/`InterfacePath`/`MethodPath`) authored on
+ * an edge endpoint — relative-form normalization collapses everything
+ * to a tree position, then re-mounting produces an `AbsolutePath`.
+ *
+ * These helpers preserve the typed lane across the round-trip:
+ *
+ *   - `seedAddressMapWithAliases` augments `Tree.from`'s
+ *     `addressToRelative` with typed-form keys so portable
+ *     serialization recognizes typed-source has_parent edges as
+ *     covering their underlying nodes (see `collectPortable`'s
+ *     synthesis-coverage check).
+ *
+ *   - `liftPortable` re-anchors a portable subtree to absolute form
+ *     under `mount` and re-applies the typed-form overlay using
+ *     `sourceAliases`, returning a `GraphInputData` shape that
+ *     `Graph.from` consumes directly (with the alias sidecar
+ *     forwarded for downstream consumers).
+ */
+import type { Graph, EdgeSpec, NodeSpec } from '#graph';
+import type { Path } from '#graph/nav/path';
+import type { NodeId } from '#ids';
+import type { AbsolutePath, RelativePath } from './path';
+import type { PortableTreeData } from './serialize';
+import type { InTree } from './types';
+/**
+ * Enrich `addressToRelative` with the producer-supplied typed-form
+ * aliases (`graph.aliases`) so portable serialization recognizes
+ * typed-source edges as covering their underlying nodes. Without
+ * this, `collectPortable`'s synthesis-coverage check uses the typed
+ * `.raw` as a key while the synthesis loop checks the relative path —
+ * they never match, and a duplicate has_parent edge (with empty
+ * props, no externalId) gets synthesized for every typed-source node.
+ *
+ * Mutates `addressToRelative` in place. No-op when there are no
+ * aliases or none of the aliased nodes survived to `nodeByPath`.
+ */
+export declare function seedAddressMapWithAliases<N extends NodeSpec>(addressToRelative: Map<string, RelativePath>, nodeByPath: ReadonlyMap<string, InTree<N>>, aliases: ReadonlyArray<readonly [NodeId, Path]> | null): void;
+/**
+ * Lift a portable subtree to absolute form under `mount`, re-applying
+ * the typed-form overlay carried by `sourceAliases`. The result is a
+ * `GraphInputData`-shaped object ready for `Graph.from`, with the
+ * alias sidecar narrowed to nodes that survived the portable filter.
+ *
+ * Round-trip preservation: typed semantic Paths are mount-agnostic
+ * (they encode the domain origin, not the tree position), so
+ * `sourceAliases` stays valid under any mount the Tree is materialized
+ * at. Endpoints whose underlying node has a typed alias regain the
+ * typed form here; endpoints without an alias stay `AbsolutePath`.
+ */
+export declare function liftPortable<N extends NodeSpec, E extends EdgeSpec>(portable: PortableTreeData<N, E>, mount: AbsolutePath, sourceAliases: Graph['aliases']): {
+    nodes: N[];
+    edges: E[];
+    aliases?: ReadonlyArray<readonly [NodeId, Path]>;
+};
+//# sourceMappingURL=aliases.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../../../graph/tree/aliases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAKrC;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,QAAQ,EAC1D,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EAC5C,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAC1C,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,GAAG,IAAI,GACrD,IAAI,CAeN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EACjE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,EAChC,KAAK,EAAE,YAAY,EACnB,aAAa,EAAE,KAAK,CAAC,SAAS,CAAC,GAC9B;IAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAAC,KAAK,EAAE,CAAC,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAA;CAAE,CAM9E"}

package/dist/graph/tree/aliases.js

@@ -0,0 +1,139 @@
+/**
+ * Tree round-trip helpers for the typed-form alias sidecar
+ * (`Graph.aliases`).
+ *
+ * The `Tree` ↔ `Graph` round-trip lifts internal endpoints to relative
+ * paths in `_collectPortable` and re-anchors them in `toGraph` under
+ * `mount`. That round-trip would lose any typed semantic Path
+ * (`DomainPath`/`ClassPath`/`InterfacePath`/`MethodPath`) authored on
+ * an edge endpoint — relative-form normalization collapses everything
+ * to a tree position, then re-mounting produces an `AbsolutePath`.
+ *
+ * These helpers preserve the typed lane across the round-trip:
+ *
+ *   - `seedAddressMapWithAliases` augments `Tree.from`'s
+ *     `addressToRelative` with typed-form keys so portable
+ *     serialization recognizes typed-source has_parent edges as
+ *     covering their underlying nodes (see `collectPortable`'s
+ *     synthesis-coverage check).
+ *
+ *   - `liftPortable` re-anchors a portable subtree to absolute form
+ *     under `mount` and re-applies the typed-form overlay using
+ *     `sourceAliases`, returning a `GraphInputData` shape that
+ *     `Graph.from` consumes directly (with the alias sidecar
+ *     forwarded for downstream consumers).
+ */
+import { hasId } from './helpers';
+import { RelativePath as RelativePathClass } from './path';
+/**
+ * Enrich `addressToRelative` with the producer-supplied typed-form
+ * aliases (`graph.aliases`) so portable serialization recognizes
+ * typed-source edges as covering their underlying nodes. Without
+ * this, `collectPortable`'s synthesis-coverage check uses the typed
+ * `.raw` as a key while the synthesis loop checks the relative path —
+ * they never match, and a duplicate has_parent edge (with empty
+ * props, no externalId) gets synthesized for every typed-source node.
+ *
+ * Mutates `addressToRelative` in place. No-op when there are no
+ * aliases or none of the aliased nodes survived to `nodeByPath`.
+ */
+export function seedAddressMapWithAliases(addressToRelative, nodeByPath, aliases) {
+    if (aliases === null || aliases.length === 0)
+        return;
+    // Invert `nodeByPath` (keyed by relative-path raw) into `NodeId →
+    // RelativePath`. `tn.path` IS the relative path because `nodeByPath`
+    // holds the InTree overlay, not the source-graph `Node`.
+    const relByNodeId = new Map();
+    for (const tn of nodeByPath.values()) {
+        if (hasId(tn))
+            relByNodeId.set(tn.id, tn.path);
+    }
+    for (const [nodeId, typed] of aliases) {
+        const rel = relByNodeId.get(nodeId);
+        if (rel && !addressToRelative.has(typed.raw)) {
+            addressToRelative.set(typed.raw, rel);
+        }
+    }
+}
+/**
+ * Lift a portable subtree to absolute form under `mount`, re-applying
+ * the typed-form overlay carried by `sourceAliases`. The result is a
+ * `GraphInputData`-shaped object ready for `Graph.from`, with the
+ * alias sidecar narrowed to nodes that survived the portable filter.
+ *
+ * Round-trip preservation: typed semantic Paths are mount-agnostic
+ * (they encode the domain origin, not the tree position), so
+ * `sourceAliases` stays valid under any mount the Tree is materialized
+ * at. Endpoints whose underlying node has a typed alias regain the
+ * typed form here; endpoints without an alias stay `AbsolutePath`.
+ */
+export function liftPortable(portable, mount, sourceAliases) {
+    const nodes = portable.nodes.map((n) => ({ ...n, path: mount.joinRelative(n.path) }));
+    const typedByAbsRaw = buildTypedByAbsRawMap(nodes, sourceAliases);
+    const edges = portable.edges.map((e) => liftEdge(e, mount, typedByAbsRaw));
+    const aliases = filterAliasesForNodes(sourceAliases, nodes);
+    return { nodes, edges, ...(aliases ? { aliases } : {}) };
+}
+// ── Internals ─────────────────────────────────────────────────────────
+/**
+ * Build `liftedAbsRaw → typed Path` from each lifted node's id → its
+ * alias entry on `sourceAliases`. Used by `liftEdge` to re-apply the
+ * typed-form overlay onto edge endpoints.
+ *
+ * Keyed by the LIFTED node's absolute path raw (post-remount), not the
+ * source graph's. When the Tree is remounted, the edges' lifted
+ * endpoints address the new mount but still resolve to the original
+ * NodeIds — so the lookup must use the lifted form.
+ */
+function buildTypedByAbsRawMap(liftedNodes, sourceAliases) {
+    const out = new Map();
+    if (sourceAliases === null || sourceAliases.length === 0)
+        return out;
+    // Materialize a NodeId→Path lookup once — `sourceAliases` is a tuple
+    // array, and we lookup by id for every lifted node.
+    const aliasById = new Map(sourceAliases);
+    for (const n of liftedNodes) {
+        if (!hasId(n))
+            continue;
+        const typed = aliasById.get(n.id);
+        if (typed)
+            out.set(n.path.raw, typed);
+    }
+    return out;
+}
+/**
+ * Lift one portable edge: relative endpoints → absolute under `mount`,
+ * then swap to the typed-form alias when one is registered for the
+ * lifted endpoint's absolute raw.
+ */
+function liftEdge(edge, mount, typedByAbsRaw) {
+    const sourceAbs = edge.source instanceof RelativePathClass ? mount.joinRelative(edge.source) : edge.source;
+    const targetAbs = edge.target instanceof RelativePathClass ? mount.joinRelative(edge.target) : edge.target;
+    return {
+        ...edge,
+        source: typedByAbsRaw.get(sourceAbs.raw) ?? sourceAbs,
+        target: typedByAbsRaw.get(targetAbs.raw) ?? targetAbs,
+    };
+}
+/**
+ * Narrow `sourceAliases` to nodes that survived the portable filter.
+ * Returns `undefined` (not an empty map) when there's nothing to
+ * forward — keeps `Graph.from` callers' `...(aliases ? { aliases } :
+ * {})` spread idiomatic.
+ */
+function filterAliasesForNodes(sourceAliases, nodes) {
+    if (sourceAliases === null || sourceAliases.length === 0)
+        return undefined;
+    const liftedIds = new Set();
+    for (const n of nodes) {
+        if (hasId(n))
+            liftedIds.add(n.id);
+    }
+    const out = [];
+    for (const [id, typed] of sourceAliases) {
+        if (liftedIds.has(id))
+            out.push([id, typed]);
+    }
+    return out.length > 0 ? out : undefined;
+}
+//# sourceMappingURL=aliases.js.map

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

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

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

@@ -0,0 +1,32 @@
+import type { EdgeSpec, NodeSpec } from '#graph';
+import type { RelativePath as RelativePathType } from '#graph/tree/path';
+import type { InTree, TreeRefs } from '#graph/tree/types';
+import type { NodeId } from '#ids';
+export { layoutTree } from './layout';
+export { validateShape } from './validate';
+export type { LayoutResult } from './layout';
+export type { ValidatedShape } from './validate';
+export interface BuildTreeResult<N extends NodeSpec> {
+    root: InTree<N>;
+    nodeByPath: Map<string, InTree<N>>;
+    pathToId: Map<string, NodeId>;
+    addressToRelative: Map<string, RelativePathType>;
+}
+/**
+ * Build a validated Tree shape from nodes + edges + containment refs.
+ *
+ * Two-phase pipeline:
+ * 1. `validateShape` — pure validation; returns structural violations.
+ * 2. `layoutTree` — computes relative paths + overlays; may detect cycles.
+ *
+ * Any non-empty violation list aborts with `TreeValidationError`. On success,
+ * returns the overlay root + indexes for downstream consumers (Tree class).
+ */
+export declare function buildTree<N extends NodeSpec, E extends EdgeSpec>(nodes: readonly N[], edges: readonly E[], refs: TreeRefs, nodeById: Map<NodeId, N>, 
+/**
+ * Optional resolver for typed semantic Path raws. Threaded into
+ * `validateShape` so has_parent edges targeting nodes via a typed
+ * form (e.g. `/:my-domain.com`) resolve back to the right node.
+ */
+nodeForRaw?: (raw: string) => N | undefined): BuildTreeResult<N>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../graph/tree/build/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAChD,OAAO,KAAK,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAOlC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAC5C,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,QAAQ;IACjD,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;IACf,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;IAClC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CACjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC9D,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;AACxB;;;;GAIG;AACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,GAC1C,eAAe,CAAC,CAAC,CAAC,CAoBpB"}

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

@@ -0,0 +1,40 @@
+import { TreeValidationError } from '#graph/tree/errors';
+import { layoutTree } from './layout';
+import { validateShape } from './validate';
+export { layoutTree } from './layout';
+export { validateShape } from './validate';
+/**
+ * Build a validated Tree shape from nodes + edges + containment refs.
+ *
+ * Two-phase pipeline:
+ * 1. `validateShape` — pure validation; returns structural violations.
+ * 2. `layoutTree` — computes relative paths + overlays; may detect cycles.
+ *
+ * Any non-empty violation list aborts with `TreeValidationError`. On success,
+ * returns the overlay root + indexes for downstream consumers (Tree class).
+ */
+export function buildTree(nodes, edges, refs, nodeById, 
+/**
+ * Optional resolver for typed semantic Path raws. Threaded into
+ * `validateShape` so has_parent edges targeting nodes via a typed
+ * form (e.g. `/:my-domain.com`) resolve back to the right node.
+ */
+nodeForRaw) {
+    const shape = validateShape(nodes, edges, refs, nodeById, nodeForRaw);
+    // Structural violations that prevent layout (missing/multiple roots): abort.
+    if (!shape.rootNode) {
+        throw new TreeValidationError([...shape.violations]);
+    }
+    const layout = layoutTree(nodes, shape);
+    const allViolations = [...shape.violations, ...layout.violations];
+    if (allViolations.length > 0) {
+        throw new TreeValidationError(allViolations);
+    }
+    return {
+        root: layout.root,
+        nodeByPath: layout.nodeByPath,
+        pathToId: layout.pathToId,
+        addressToRelative: layout.addressToRelative,
+    };
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../graph/tree/build/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAW1C;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CACvB,KAAmB,EACnB,KAAmB,EACnB,IAAc,EACd,QAAwB;AACxB;;;;GAIG;AACH,UAA2C;IAE3C,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAA;IAErE,6EAA6E;IAC7E,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACpB,MAAM,IAAI,mBAAmB,CAAC,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,CAAA;IACtD,CAAC;IAED,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;IACvC,MAAM,aAAa,GAAG,CAAC,GAAG,KAAK,CAAC,UAAU,EAAE,GAAG,MAAM,CAAC,UAAU,CAAC,CAAA;IACjE,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,mBAAmB,CAAC,aAAa,CAAC,CAAA;IAC9C,CAAC;IAED,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;KAC5C,CAAA;AACH,CAAC"}

package/dist/graph/tree/build/layout.d.ts

@@ -0,0 +1,29 @@
+import type { EdgeSpec, NodeSpec } from '#graph';
+import type { RelativePath as RelativePathType } from '#graph/tree/path';
+import type { InTree } from '#graph/tree/types';
+import type { NodeId } from '#ids';
+import { type TreeViolation } from '#graph/tree/errors';
+import type { ValidatedShape } from './validate';
+/**
+ * Result of the layout phase — produces the final, consumer-facing shape.
+ *
+ * `buildTree` (in `build/index.ts`) orchestrates validate → layout and
+ * throws if validation produced violations that prevent layout, or if
+ * layout itself detects late violations (cycles).
+ */
+export interface LayoutResult<N extends NodeSpec> {
+    readonly root: InTree<N>;
+    readonly nodeByPath: Map<string, InTree<N>>;
+    readonly pathToId: Map<string, NodeId>;
+    readonly addressToRelative: Map<string, RelativePathType>;
+    readonly violations: readonly TreeViolation[];
+}
+/**
+ * Compute relative paths via BFS from the validated root, then build
+ * the frozen overlay `InTree<N>` nodes.
+ *
+ * Pre-conditions: `shape.rootNode` is non-null and `shape.violations`
+ * (structural) was already checked by the caller.
+ */
+export declare function layoutTree<N extends NodeSpec, E extends EdgeSpec>(nodes: readonly N[], shape: ValidatedShape<N, E>): LayoutResult<N>;
+//# sourceMappingURL=layout.d.ts.map

package/dist/graph/tree/build/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../../graph/tree/build/layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAChD,OAAO,KAAK,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAIvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,QAAQ;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;IAC3C,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACtC,QAAQ,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;IACzD,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAA;CAC9C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAC/D,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAC1B,YAAY,CAAC,CAAC,CAAC,CA6FjB"}

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

@@ -0,0 +1,98 @@
+import {} from '#graph/tree/errors';
+import { hasId } from '#graph/tree/helpers';
+import { RelativePath } from '#graph/tree/path';
+/**
+ * Compute relative paths via BFS from the validated root, then build
+ * the frozen overlay `InTree<N>` nodes.
+ *
+ * Pre-conditions: `shape.rootNode` is non-null and `shape.violations`
+ * (structural) was already checked by the caller.
+ */
+export function layoutTree(nodes, shape) {
+    const rootNode = shape.rootNode;
+    if (!rootNode) {
+        throw new Error('layoutTree: shape.rootNode is null — caller must have stopped on violations');
+    }
+    const { childrenOf, parentOf, slugOf, addressToNode } = shape;
+    const violations = [];
+    // ── BFS relative paths ────────────────────────────────────────
+    const nodeToPath = new Map();
+    const visited = new Set();
+    nodeToPath.set(rootNode, RelativePath.from());
+    visited.add(rootNode);
+    const bfs = [rootNode];
+    for (let i = 0; i < bfs.length; i++) {
+        const current = bfs[i];
+        const currentPath = nodeToPath.get(current);
+        for (const child of childrenOf.get(current) ?? []) {
+            if (visited.has(child)) {
+                violations.push({
+                    kind: 'cycle',
+                    nodeRefs: [refName(current, slugOf), refName(child, slugOf)],
+                });
+                continue;
+            }
+            visited.add(child);
+            const childSlug = slugOf.get(child) ?? '(unknown)';
+            nodeToPath.set(child, currentPath.append(childSlug));
+            bfs.push(child);
+        }
+    }
+    for (const n of nodes) {
+        if (!visited.has(n)) {
+            violations.push({ kind: 'missing_parent', nodeRef: refName(n, slugOf) });
+        }
+    }
+    // ── Frozen overlay nodes ──────────────────────────────────────
+    const treeNodeOf = new Map();
+    const pathToId = new Map();
+    for (const n of nodes) {
+        const computedPath = nodeToPath.get(n);
+        if (!computedPath)
+            continue; // skipped (missing_parent); already reported
+        const tn = { ...n, path: computedPath };
+        treeNodeOf.set(n, tn);
+        if (hasId(n)) {
+            pathToId.set(computedPath.raw, n.id);
+        }
+    }
+    for (const [n, tn] of treeNodeOf) {
+        const childNodes = (childrenOf.get(n) ?? []).map((c) => treeNodeOf.get(c)).filter(Boolean);
+        Object.defineProperty(tn, 'children', {
+            value: Object.freeze(childNodes),
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+        const parentNode = parentOf.get(n);
+        Object.defineProperty(tn, 'parent', {
+            value: parentNode ? (treeNodeOf.get(parentNode) ?? null) : null,
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+    }
+    // ── Address → relative (for edge serialization) ───────────────
+    const nodeByPath = new Map();
+    for (const [n, tn] of treeNodeOf) {
+        nodeByPath.set(nodeToPath.get(n).raw, tn);
+    }
+    const addressToRelative = new Map();
+    for (const [addr, n] of addressToNode) {
+        const rel = nodeToPath.get(n);
+        if (rel)
+            addressToRelative.set(addr, rel);
+    }
+    return {
+        root: treeNodeOf.get(rootNode),
+        nodeByPath,
+        pathToId,
+        addressToRelative,
+        violations,
+    };
+}
+// ─── Helpers ─────────────────────────────────────────────────────────
+function refName(n, slugOf) {
+    return slugOf.get(n) ?? (hasId(n) ? String(n.id) : (n.path?.raw ?? '(unknown)'));
+}
+//# sourceMappingURL=layout.js.map

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

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

package/dist/graph/tree/build/validate.d.ts

@@ -0,0 +1,43 @@
+import type { EdgeSpec, NodeSpec } from '#graph';
+import type { TreeRefs } from '#graph/tree/types';
+import type { NodeId } from '#ids';
+import { type TreeViolation } from '#graph/tree/errors';
+/**
+ * Result of the validation phase — pure, no throw.
+ *
+ * Downstream (layout) consumes this to produce paths and overlays.
+ * A non-empty `violations` array means the input cannot be laid out;
+ * `build/index.ts` is responsible for throwing `TreeValidationError`.
+ */
+export interface ValidatedShape<N extends NodeSpec, E extends EdgeSpec> {
+    readonly rootNode: N | null;
+    readonly parentOf: ReadonlyMap<N, N>;
+    readonly childrenOf: ReadonlyMap<N, N[]>;
+    readonly slugOf: ReadonlyMap<N, string>;
+    readonly addressToNode: ReadonlyMap<string, N>;
+    readonly violations: readonly TreeViolation[];
+    readonly _edge?: E;
+}
+/**
+ * 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 declare function validateShape<N extends NodeSpec, E extends EdgeSpec>(nodes: readonly N[], edges: readonly E[], refs: TreeRefs, nodeById: Map<NodeId, N>, 
+/**
+ * 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?: (raw: string) => N | undefined): ValidatedShape<N, E>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/graph/tree/build/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../../graph/tree/build/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAGlC,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAIvD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ;IACpE,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;IACxC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;IACvC,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IAC9C,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAA;IAE7C,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAClE,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;AACxB;;;;;;;;;;GAUG;AACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,GAC1C,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAwGtB"}