@astrale-os/kernel-core 0.4.1

package/dist/graph/tree/path/relative/type.js

@@ -0,0 +1,183 @@
+import { parsePath, Path, PathParseError } from '#graph/nav/path';
+import { INBOUND } from '#graph/nav/path/step';
+import { AbsolutePath } from '#graph/tree/path/absolute';
+import { SEPARATOR_CHAR, SLUG_PROPERTY, SLUG_RE, TREE_EDGE_TYPE, } from '#graph/tree/path/absolute/constants';
+import { RELATIVE_PREFIX, SELF_TOKEN } from './constants';
+/**
+ * Relative tree address — `./`-prefixed slug chain. Discriminator is
+ * structural: a relative path's Step[] has *no* leading anchor (no
+ * RootAnchor), only `has_parent` inbound traversals. Absolute paths
+ * with the same slug chain carry a RootAnchor at `steps[0]`.
+ *
+ * Like AbsolutePath, the steps walk source(child) → target(parent), so
+ * `slugs` reads in human order — `./a/b` exposes `['a', 'b']`.
+ */
+export class RelativePath extends Path {
+    slugs;
+    constructor(steps, raw) {
+        super(steps, raw);
+        this.slugs = Object.freeze(extractSlugs(steps));
+    }
+    // ─── Internal hooks ──────────────────────────────────────
+    /** @internal Build a relative from pre-validated slugs. */
+    static _create(slugs, raw) {
+        return new RelativePath(buildSteps(slugs), raw ?? serializeFromSlugs(slugs));
+    }
+    /** @internal Narrow a base Path into RelativePath without re-parsing. */
+    static _fromPath(path) {
+        return new RelativePath(path.steps, path.raw);
+    }
+    // ─── Static factories ────────────────────────────────────
+    static parse(raw) {
+        const p = parsePath(raw);
+        if (!(p instanceof RelativePath)) {
+            throw new PathParseError(raw, [
+                { kind: 'not-relative', message: 'Path is not relative', position: 0 },
+            ]);
+        }
+        return p;
+    }
+    static tryParse(raw) {
+        try {
+            return RelativePath.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    static from(...slugs) {
+        for (const slug of slugs) {
+            if (!SLUG_RE.test(slug)) {
+                throw new PathParseError(slug, [
+                    { kind: 'invalid-slug', message: `Invalid slug: "${slug}"`, position: 0 },
+                ]);
+            }
+        }
+        return RelativePath._create(slugs);
+    }
+    // ─── Getters ──────────────────────────────────────────────
+    get isRelative() {
+        return true;
+    }
+    get isAbsolute() {
+        return false;
+    }
+    get isSelf() {
+        return this.slugs.length === 0;
+    }
+    get depth() {
+        return this.slugs.length;
+    }
+    // ─── Derivation ───────────────────────────────────────────
+    parent() {
+        if (this.slugs.length <= 1)
+            return null;
+        return RelativePath._create(this.slugs.slice(0, -1));
+    }
+    basename() {
+        if (this.slugs.length === 0)
+            return null;
+        return this.slugs[this.slugs.length - 1];
+    }
+    append(...slugs) {
+        if (slugs.length === 0)
+            return this;
+        for (const slug of slugs) {
+            if (!SLUG_RE.test(slug)) {
+                throw new PathParseError(slug, [
+                    { kind: 'invalid-slug', message: `Invalid slug: "${slug}"`, position: 0 },
+                ]);
+            }
+        }
+        return RelativePath._create([...this.slugs, ...slugs]);
+    }
+    join(other) {
+        if (other.slugs.length === 0)
+            return this;
+        return RelativePath._create([...this.slugs, ...other.slugs]);
+    }
+    toAbsolute(base) {
+        return AbsolutePath.from(...base.slugs, ...this.slugs);
+    }
+    equals(other) {
+        if (!(other instanceof RelativePath))
+            return false;
+        if (this.slugs.length !== other.slugs.length)
+            return false;
+        for (let i = 0; i < this.slugs.length; i++) {
+            if (this.slugs[i] !== other.slugs[i])
+                return false;
+        }
+        return true;
+    }
+}
+/**
+ * The PathType for RelativePath. Custom `matches` checks: no leading
+ * anchor + only has_parent inbound traversals. No segments to register
+ * in the registry (relative paths bypass the segment-based identify
+ * pipeline since you can't recover them from a node alone).
+ */
+export const relativePathType = {
+    name: 'RelativePath',
+    class: null,
+    segments: [],
+    matches(steps) {
+        if (steps.length === 0)
+            return true;
+        if (steps[0].kind === 'anchor')
+            return false;
+        for (const s of steps) {
+            if (s.kind !== 'traversal')
+                return false;
+            if (s.edgeClass !== TREE_EDGE_TYPE)
+                return false;
+            if (s.from !== INBOUND.from || s.to !== INBOUND.to)
+                return false;
+            if (s.predicate &&
+                s.predicate.kind === 'property' &&
+                s.predicate.property !== SLUG_PROPERTY) {
+                return false;
+            }
+        }
+        return true;
+    },
+    build(steps, raw) {
+        return new RelativePath(steps, raw || serializeFromSteps(steps));
+    },
+};
+// ── Helpers (private) ─────────────────────────────────────────────
+function extractSlugs(steps) {
+    const out = [];
+    for (const s of steps) {
+        if (s.kind !== 'traversal')
+            continue;
+        const p = s.predicate;
+        if (p?.kind !== 'property')
+            continue;
+        out.push(p.value);
+    }
+    return out;
+}
+function buildSteps(slugs) {
+    return slugs.map((slug) => ({
+        kind: 'traversal',
+        edgeClass: TREE_EDGE_TYPE,
+        ...INBOUND,
+        predicate: {
+            kind: 'property',
+            scope: 'edge',
+            property: SLUG_PROPERTY,
+            op: '=',
+            value: slug,
+        },
+    }));
+}
+function serializeFromSlugs(slugs) {
+    if (slugs.length === 0)
+        return SELF_TOKEN;
+    return RELATIVE_PREFIX + slugs.join(SEPARATOR_CHAR);
+}
+function serializeFromSteps(steps) {
+    return serializeFromSlugs(extractSlugs(steps));
+}
+//# sourceMappingURL=type.js.map

package/dist/graph/tree/path/relative/type.js.map

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

package/dist/graph/tree/path/relative-path.d.ts

@@ -0,0 +1,2 @@
+export { RelativePath, relativePathType } from '#graph/tree/path/relative';
+//# sourceMappingURL=relative-path.d.ts.map

package/dist/graph/tree/path/relative-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relative-path.d.ts","sourceRoot":"","sources":["../../../../graph/tree/path/relative-path.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA"}

package/dist/graph/tree/path/relative-path.js

@@ -0,0 +1,3 @@
+// RelativePath is canonical at `#graph/tree/path/relative` post-collapse.
+export { RelativePath, relativePathType } from '#graph/tree/path/relative';
+//# sourceMappingURL=relative-path.js.map

package/dist/graph/tree/path/relative-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relative-path.js","sourceRoot":"","sources":["../../../../graph/tree/path/relative-path.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA"}

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

@@ -0,0 +1,4 @@
+import type { AbsolutePath } from '#graph/tree/path/absolute';
+import type { RelativePath } from '#graph/tree/path/relative';
+export type TreePath = AbsolutePath | RelativePath;
+//# sourceMappingURL=tree-path.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree-path.d.ts","sourceRoot":"","sources":["../../../../graph/tree/path/tree-path.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAE7D,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,YAAY,CAAA"}

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

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

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

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

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

@@ -0,0 +1,40 @@
+import type { EdgeSpec, NodeSpec } from '#graph';
+import type { Path } from '#graph/nav/path';
+import type { RelativePath } from './path';
+import type { InTree, TreeRefs } from './types';
+/**
+ * Tree-portable record shapes.
+ *
+ * These narrow NodeSpec / EdgeSpec to the frame Tree serialization produces:
+ * internal nodes and endpoints carry `RelativePath`, external endpoints keep
+ * their original path (typically `AbsolutePath`). The result is mount-free
+ * and can be re-anchored elsewhere.
+ *
+ * Scope is intentionally module-local — callers should go through
+ * `Tree.toWire()` (string form) or `Tree.toGraph()` (mounted absolute form),
+ * not this intermediate.
+ */
+export type PortableNode<N extends NodeSpec> = Omit<N, 'path'> & {
+    readonly path: RelativePath;
+};
+export type PortableEdge<E extends EdgeSpec> = Omit<E, 'source' | 'target'> & {
+    readonly source: Path;
+    readonly target: Path;
+};
+export interface PortableTreeData<N extends NodeSpec, E extends EdgeSpec> {
+    readonly nodes: readonly PortableNode<N>[];
+    readonly edges: readonly PortableEdge<E>[];
+}
+/**
+ * Collect the tree as a portable (mount-free, relative-internal) record set.
+ *
+ * Nodes already carry tree-relative paths (the builder's canonical frame).
+ * The only work here is rewriting edge endpoints to reference nodes by those
+ * same relative paths and synthesizing any missing `has_parent` edges.
+ *
+ * `instance_of` never appears in tree inputs — it is derived from
+ * `node.class` and excluded at the adapter read boundary
+ * (`CypherGraphMap.nonStructuralDirectTypes()`), so no filter is needed here.
+ */
+export declare function collectPortable<N extends NodeSpec, E extends EdgeSpec>(root: InTree<N>, nodes: readonly N[], edges: readonly E[], refs: TreeRefs, addressToRelative: Map<string, RelativePath>): PortableTreeData<N, E>;
+//# sourceMappingURL=serialize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../graph/tree/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAChD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAI/C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,QAAQ,IAAI,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG;IAC/D,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAC5B,CAAA;AACD,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,QAAQ,IAAI,IAAI,CAAC,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC,GAAG;IAC5E,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;CACtB,CAAA;AACD,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ;IACtE,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,CAAA;IAC1C,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,CAAA;CAC3C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EACpE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EACf,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,IAAI,EAAE,QAAQ,EACd,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,GAC3C,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAsDxB"}

package/dist/graph/tree/serialize.js

@@ -0,0 +1,73 @@
+import { hasId } from './helpers';
+/**
+ * Collect the tree as a portable (mount-free, relative-internal) record set.
+ *
+ * Nodes already carry tree-relative paths (the builder's canonical frame).
+ * The only work here is rewriting edge endpoints to reference nodes by those
+ * same relative paths and synthesizing any missing `has_parent` edges.
+ *
+ * `instance_of` never appears in tree inputs — it is derived from
+ * `node.class` and excluded at the adapter read boundary
+ * (`CypherGraphMap.nonStructuralDirectTypes()`), so no filter is needed here.
+ */
+export function collectPortable(root, nodes, edges, refs, addressToRelative) {
+    const mappedNodes = nodes.map((n) => {
+        const path = (hasId(n) ? addressToRelative.get(String(n.id)) : undefined) ??
+            addressToRelative.get(n.path.raw) ??
+            n.path;
+        return { ...n, path };
+    });
+    const hasParentSourceAddresses = new Set();
+    const mappedEdges = [];
+    for (const e of edges) {
+        const srcPath = resolveRelPath(e.source, addressToRelative);
+        const tgtPath = resolveRelPath(e.target, addressToRelative);
+        if (e.class?.raw === refs.has_parent.raw) {
+            hasParentSourceAddresses.add(srcPath.raw);
+        }
+        mappedEdges.push({
+            ...e,
+            source: srcPath,
+            target: tgtPath,
+        });
+    }
+    // Synthesize missing has_parent edges (children that lack an explicit has_parent in the input).
+    const queue = [...root.children];
+    for (let i = 0; i < queue.length; i++) {
+        const tn = queue[i];
+        if (!hasId(tn)) {
+            for (const child of tn.children)
+                queue.push(child);
+            continue;
+        }
+        const srcPath = addressToRelative.get(String(tn.id));
+        if (srcPath && !hasParentSourceAddresses.has(srcPath.raw)) {
+            const tgtPath = tn.parent && hasId(tn.parent) ? addressToRelative.get(String(tn.parent.id)) : undefined;
+            if (tgtPath) {
+                const slug = tn.path.slugs[tn.path.slugs.length - 1];
+                mappedEdges.push({
+                    slug,
+                    class: refs.has_parent,
+                    source: srcPath,
+                    target: tgtPath,
+                    props: {},
+                });
+            }
+        }
+        for (const child of tn.children)
+            queue.push(child);
+    }
+    return { nodes: mappedNodes, edges: mappedEdges };
+}
+/**
+ * Resolve an edge endpoint to its tree-relative path.
+ *
+ * Looks the endpoint up in the builder's address map; endpoints external to
+ * the tree (e.g. an upward has_parent target pointing at a host root) fall
+ * through and keep their original path so the edge stays resolvable on both
+ * sides of the Tree boundary.
+ */
+function resolveRelPath(originalPath, addressToRelative) {
+    return addressToRelative.get(originalPath.raw) ?? originalPath;
+}
+//# sourceMappingURL=serialize.js.map

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

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

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

@@ -0,0 +1,121 @@
+import type { EdgeSpec, NodeSpec } from '#graph';
+import type { NodeId } from '#ids';
+import { Graph } from '#graph';
+import type { TreeEdge } from './edge';
+import type { AbsolutePath } from './path';
+import type { RelativePath } from './path';
+import type { InTree, TreeRefs, TreeOptions } from './types';
+/**
+ * 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 declare class Tree<N extends NodeSpec = NodeSpec, E extends EdgeSpec = EdgeSpec> {
+    /** Source graph (raw). Access raw nodes/edges via `tree.graph`. */
+    readonly graph: Graph;
+    readonly root: InTree<N>;
+    readonly mount: AbsolutePath | null;
+    private readonly _refs;
+    private readonly _nodeByPath;
+    private readonly _treeNodeById;
+    private readonly _pathToId;
+    private readonly _addressToRelative;
+    private _edgesCache;
+    private constructor();
+    /** Resolve a node in this tree by id. */
+    byId(id: NodeId): InTree<N> | undefined;
+    /** Resolve a node in this tree by relative path. */
+    byPath(path: RelativePath | string): InTree<N> | undefined;
+    /** Iterate over all nodes in the tree (BFS order from root). */
+    get nodes(): Iterable<InTree<N>>;
+    /** Count of nodes in this tree. */
+    get nodeCount(): number;
+    /** Count of edges in the source graph (every graph edge produces one TreeEdge). */
+    get edgeCount(): number;
+    /**
+     * 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(): Iterable<TreeEdge<N, E>>;
+    get internalEdges(): Iterable<TreeEdge<N, E>>;
+    get outgoingEdges(): Iterable<TreeEdge<N, E>>;
+    get incomingEdges(): Iterable<TreeEdge<N, E>>;
+    /** Outgoing ∪ incoming — every edge that crosses the tree boundary. */
+    get boundaryEdges(): Iterable<TreeEdge<N, E>>;
+    /** All classified edges touching a given tree node. */
+    edgesOf(node: InTree<N>): readonly TreeEdge<N, E>[];
+    /** Edges with this node as (internal) source. */
+    outgoingFrom(node: InTree<N>): readonly TreeEdge<N, E>[];
+    /** Edges with this node as (internal) target. */
+    incomingTo(node: InTree<N>): readonly TreeEdge<N, E>[];
+    /** Compose a node's intrinsic relative path with the tree's mount. */
+    absolutePathOf(node: InTree<N>): AbsolutePath | null;
+    /** Return a copy with a different (or no) mount. Structure unchanged, O(1). */
+    withMount(mount: AbsolutePath | null): Tree<N, E>;
+    /**
+     * 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: InTree<N>, refs?: TreeRefs): Tree<N, E>;
+    /**
+     * 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(): Graph;
+    /**
+     * 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(): {
+        nodes: unknown[];
+        edges: unknown[];
+    };
+    /** Compute (once) the classified edge view. */
+    private _classifiedEdges;
+    /** Resolve an edge endpoint into the tree's frame. */
+    private _resolveEndpoint;
+    private _collectPortable;
+    /**
+     * 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<N extends NodeSpec = NodeSpec, E extends EdgeSpec = EdgeSpec>(input: Graph | {
+        nodes: N[];
+        edges: E[];
+    }, refs?: TreeRefs, opts?: TreeOptions): Tree<N, E>;
+}
+//# sourceMappingURL=tree.d.ts.map

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

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