@astrale-os/kernel-core 0.4.1

package/dist/graph/nav/parse/predicate.js

@@ -0,0 +1,95 @@
+/**
+ * Parse a predicate expression from a token stream.
+ * Expects the stream to be positioned AFTER the opening '(' — i.e., the caller
+ * has already consumed PAREN_OPEN. Reads until the matching PAREN_CLOSE.
+ *
+ * Syntax:
+ *   property=value                          edge property (default scope)
+ *   node.property=value                     node property (explicit scope)
+ *   pred & pred                             AND
+ *   pred | pred                             OR
+ *   !pred  or  !(pred)                      NOT
+ *   (pred)                                  grouping
+ */
+export function parsePredicate(stream) {
+    const pred = parseOr(stream);
+    return pred;
+}
+// ─── Recursive descent: OR has lowest precedence ────────
+function parseOr(stream) {
+    const operands = [parseAnd(stream)];
+    while (stream.peek()?.kind === 'OR') {
+        stream.advance(); // consume '|'
+        operands.push(parseAnd(stream));
+    }
+    return operands.length === 1 ? operands[0] : { kind: 'or', operands };
+}
+function parseAnd(stream) {
+    const operands = [parseNot(stream)];
+    while (stream.peek()?.kind === 'AND') {
+        stream.advance(); // consume '&'
+        operands.push(parseNot(stream));
+    }
+    return operands.length === 1 ? operands[0] : { kind: 'and', operands };
+}
+function parseNot(stream) {
+    if (stream.peek()?.kind === 'NOT') {
+        stream.advance(); // consume '!'
+        return { kind: 'not', operand: parseAtom(stream) };
+    }
+    return parseAtom(stream);
+}
+function parseAtom(stream) {
+    const token = stream.peek();
+    // Grouped sub-expression: (pred)
+    if (token?.kind === 'PAREN_OPEN') {
+        stream.advance(); // consume '('
+        const inner = parseOr(stream);
+        expectToken(stream, 'PAREN_CLOSE', ')');
+        return inner;
+    }
+    // Property predicate: property=value or node.property=value
+    return parsePropertyPredicate(stream);
+}
+function parsePropertyPredicate(stream) {
+    const nameToken = expectToken(stream, 'TEXT', 'property name');
+    let scope = 'edge';
+    let property = nameToken.value;
+    // Check for 'node.' prefix
+    if (property.startsWith('node.')) {
+        scope = 'node';
+        property = property.slice(5);
+        if (property.length === 0) {
+            throw new PredicateParseError(`Empty property name after 'node.' prefix`, nameToken.position);
+        }
+    }
+    expectToken(stream, 'ASSIGN', '=');
+    const valueToken = expectToken(stream, 'TEXT', 'property value');
+    return {
+        kind: 'property',
+        scope,
+        property,
+        op: '=',
+        value: valueToken.value,
+    };
+}
+// ─── Helpers ────────────────────────────────────────────
+function expectToken(stream, kind, description) {
+    const token = stream.peek();
+    if (!token) {
+        throw new PredicateParseError(`Expected ${description}, got end of input`, -1);
+    }
+    if (token.kind !== kind) {
+        throw new PredicateParseError(`Expected ${description}, got '${token.value}'`, token.position);
+    }
+    return stream.advance();
+}
+export class PredicateParseError extends Error {
+    position;
+    constructor(message, position) {
+        super(message);
+        this.position = position;
+        this.name = 'PredicateParseError';
+    }
+}
+//# sourceMappingURL=predicate.js.map

package/dist/graph/nav/parse/predicate.js.map

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

package/dist/graph/nav/parse/steps.d.ts

@@ -0,0 +1,43 @@
+import type { Step } from '#graph/nav/path/step';
+import type { GrammarExtension } from '../grammar/extension';
+import type { ValidationError } from './validation';
+export interface PathParseResult {
+    readonly steps: readonly Step[];
+    readonly errors: readonly ValidationError[];
+}
+/**
+ * Parse a raw string into Step[] using the global {@link GrammarRegistry}.
+ *
+ * Thin wrapper over {@link parseStepsWith} that snapshots the registry's
+ * current extensions. Use this from runtime call sites that don't hold a
+ * specific grammar set (typically `parsePath`-driven flows after the
+ * kernel's bootstrap registrations have run).
+ *
+ * Compile-time call sites (typed-path factories like `ClassPath.from`) close
+ * over their own grammar set and call {@link parseStepsWith} directly so the
+ * result doesn't depend on global state.
+ */
+export declare function parseSteps(input: string): PathParseResult;
+/**
+ * Parse a raw string into Step[] against an explicit grammar set.
+ *
+ * Anchor convention (the IR-level discriminator for absolute vs
+ * relative):
+ *
+ *  - `./…` (relative prefix consumed by the relative grammar) → no
+ *    leading anchor. The Step[] starts directly with traversals.
+ *  - `@id…` → leading {@link IdAnchor} (no implicit root).
+ *  - everything else → leading {@link RootAnchor} prepended automatically.
+ *
+ * The `RootAnchor` is materialized once at parse time; downstream
+ * walkers / compilers / serializers see the anchor in `steps[0]` and
+ * branch on its `target` field. There is no out-of-band `isRelative`
+ * flag any longer.
+ *
+ * Handles core tokens directly (`@id`, `~edgeClass`, `<~edgeClass`,
+ * `(...)` predicate filters); delegates everything else to the supplied
+ * {@link GrammarExtension}s in last-supplied-first order (matching
+ * {@link parseSteps}' last-registered-first semantics).
+ */
+export declare function parseStepsWith(input: string, extensions: readonly GrammarExtension[]): PathParseResult;
+//# sourceMappingURL=steps.d.ts.map

package/dist/graph/nav/parse/steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../../../graph/nav/parse/steps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAA;AAGhD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAWnD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;IAC/B,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAA;CAC5C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAEzD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,SAAS,gBAAgB,EAAE,GACtC,eAAe,CAsGjB"}

package/dist/graph/nav/parse/steps.js

@@ -0,0 +1,234 @@
+import { SLUG_PROPERTY } from '../ast/slug';
+import { idAnchor, INBOUND, OUTBOUND, ROOT_ANCHOR } from '../ast/step';
+import { CORE_TOKENS } from '../grammar/core';
+import { GrammarRegistry } from '../grammar/registry';
+import { buildTokenTable } from '../lex/table';
+import { tokenize } from '../lex/tokenize';
+import { parsePredicate, PredicateParseError } from './predicate';
+import { TokenStream } from './stream';
+/**
+ * Parse a raw string into Step[] using the global {@link GrammarRegistry}.
+ *
+ * Thin wrapper over {@link parseStepsWith} that snapshots the registry's
+ * current extensions. Use this from runtime call sites that don't hold a
+ * specific grammar set (typically `parsePath`-driven flows after the
+ * kernel's bootstrap registrations have run).
+ *
+ * Compile-time call sites (typed-path factories like `ClassPath.from`) close
+ * over their own grammar set and call {@link parseStepsWith} directly so the
+ * result doesn't depend on global state.
+ */
+export function parseSteps(input) {
+    return parseStepsWith(input, GrammarRegistry.extensions());
+}
+/**
+ * Parse a raw string into Step[] against an explicit grammar set.
+ *
+ * Anchor convention (the IR-level discriminator for absolute vs
+ * relative):
+ *
+ *  - `./…` (relative prefix consumed by the relative grammar) → no
+ *    leading anchor. The Step[] starts directly with traversals.
+ *  - `@id…` → leading {@link IdAnchor} (no implicit root).
+ *  - everything else → leading {@link RootAnchor} prepended automatically.
+ *
+ * The `RootAnchor` is materialized once at parse time; downstream
+ * walkers / compilers / serializers see the anchor in `steps[0]` and
+ * branch on its `target` field. There is no out-of-band `isRelative`
+ * flag any longer.
+ *
+ * Handles core tokens directly (`@id`, `~edgeClass`, `<~edgeClass`,
+ * `(...)` predicate filters); delegates everything else to the supplied
+ * {@link GrammarExtension}s in last-supplied-first order (matching
+ * {@link parseSteps}' last-registered-first semantics).
+ */
+export function parseStepsWith(input, extensions) {
+    if (input.length === 0) {
+        return {
+            steps: [],
+            errors: [{ kind: 'empty-input', message: 'Path cannot be empty', position: 0 }],
+        };
+    }
+    const tokens = extensions.flatMap((e) => e.tokens ?? []);
+    const grammar = buildTokenTable(CORE_TOKENS, tokens);
+    const tokenList = tokenize(input, grammar);
+    const stream = new TokenStream(tokenList);
+    const steps = [];
+    const errors = [];
+    const exts = extensions;
+    let isRelative = false;
+    for (let i = exts.length - 1; i >= 0; i--) {
+        const ext = exts[i];
+        if (!ext.parsePrefix)
+            continue;
+        const mark = stream.mark();
+        const prefixResult = ext.parsePrefix(stream);
+        if (prefixResult) {
+            isRelative = prefixResult.isRelative;
+            break;
+        }
+        stream.restore(mark);
+    }
+    while (stream.hasMore()) {
+        const token = stream.peek();
+        if (token.kind === 'AT') {
+            stream.advance();
+            const idToken = stream.peek();
+            if (!idToken || idToken.kind !== 'TEXT') {
+                errors.push({
+                    kind: 'missing-id',
+                    message: 'Expected node ID after @',
+                    position: token.position,
+                });
+                continue;
+            }
+            stream.advance();
+            steps.push(idAnchor(idToken.value));
+            continue;
+        }
+        if (token.kind === 'LT') {
+            const mark = stream.mark();
+            stream.advance();
+            const next = stream.peek();
+            if (next?.kind === 'TILDE') {
+                stream.advance();
+                const t = parseTraversalBody(stream, INBOUND, errors);
+                if (t)
+                    steps.push(t);
+                continue;
+            }
+            stream.restore(mark);
+            errors.push({
+                kind: 'unexpected-token',
+                message: `Unexpected '<' at position ${token.position}`,
+                position: token.position,
+            });
+            stream.advance();
+            continue;
+        }
+        if (token.kind === 'TILDE') {
+            stream.advance();
+            const t = parseTraversalBody(stream, OUTBOUND, errors);
+            if (t)
+                steps.push(t);
+            continue;
+        }
+        let handled = false;
+        for (let i = exts.length - 1; i >= 0; i--) {
+            const ext = exts[i];
+            const mark = stream.mark();
+            const result = ext.parseStep(stream);
+            if (result !== null) {
+                for (const s of result)
+                    steps.push(s);
+                handled = true;
+                break;
+            }
+            stream.restore(mark);
+        }
+        if (handled)
+            continue;
+        errors.push({
+            kind: 'unexpected-token',
+            message: `Unexpected token '${token.value}' at position ${token.position}`,
+            position: token.position,
+        });
+        stream.advance();
+    }
+    if (!isRelative && (steps.length === 0 || steps[0].kind !== 'anchor')) {
+        steps.unshift(ROOT_ANCHOR);
+    }
+    return { steps, errors };
+}
+function parseTraversalBody(stream, direction, errors) {
+    const edgeClassToken = stream.peek();
+    if (!edgeClassToken || edgeClassToken.kind !== 'TEXT') {
+        errors.push({
+            kind: 'missing-edge-class',
+            message: 'Expected edge class after traversal operator',
+            position: edgeClassToken?.position ?? -1,
+        });
+        return null;
+    }
+    stream.advance();
+    const edgeClass = edgeClassToken.value;
+    if (stream.peek()?.kind !== 'PAREN_OPEN') {
+        return { kind: 'traversal', edgeClass, ...direction };
+    }
+    stream.advance(); // consume '('
+    if (stream.peek()?.kind === 'PAREN_CLOSE') {
+        stream.advance();
+        return { kind: 'traversal', edgeClass, ...direction };
+    }
+    const filterMark = stream.mark();
+    let hasAssign = false;
+    let depth = 0;
+    while (stream.hasMore()) {
+        const t = stream.peek();
+        if (t.kind === 'PAREN_OPEN')
+            depth++;
+        else if (t.kind === 'PAREN_CLOSE') {
+            if (depth === 0)
+                break;
+            depth--;
+        }
+        else if (t.kind === 'ASSIGN' && depth === 0) {
+            hasAssign = true;
+            break;
+        }
+        stream.advance();
+    }
+    stream.restore(filterMark);
+    if (!hasAssign) {
+        const parts = [];
+        while (stream.hasMore() && stream.peek().kind !== 'PAREN_CLOSE') {
+            parts.push(stream.advance().value);
+        }
+        if (stream.peek()?.kind === 'PAREN_CLOSE')
+            stream.advance();
+        return {
+            kind: 'traversal',
+            edgeClass,
+            ...direction,
+            predicate: {
+                kind: 'property',
+                scope: 'edge',
+                property: SLUG_PROPERTY,
+                op: '=',
+                value: parts.join(''),
+            },
+        };
+    }
+    try {
+        const predicate = parsePredicate(stream);
+        if (stream.peek()?.kind === 'PAREN_CLOSE')
+            stream.advance();
+        else {
+            errors.push({
+                kind: 'unclosed-filter',
+                message: 'Expected closing ) for predicate filter',
+                position: stream.peek()?.position ?? -1,
+            });
+        }
+        return { kind: 'traversal', edgeClass, ...direction, predicate };
+    }
+    catch (e) {
+        if (e instanceof PredicateParseError) {
+            errors.push({ kind: 'invalid-predicate', message: e.message, position: e.position });
+            skipToClose(stream);
+            return { kind: 'traversal', edgeClass, ...direction };
+        }
+        throw e;
+    }
+}
+function skipToClose(stream) {
+    let depth = 1;
+    while (stream.hasMore() && depth > 0) {
+        const t = stream.advance();
+        if (t.kind === 'PAREN_OPEN')
+            depth++;
+        else if (t.kind === 'PAREN_CLOSE')
+            depth--;
+    }
+}
+//# sourceMappingURL=steps.js.map

package/dist/graph/nav/parse/steps.js.map

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

package/dist/graph/nav/parse/stream.d.ts

@@ -0,0 +1,24 @@
+import type { Token } from '../lex/token';
+/** Cursor over a Token array for parser consumption. */
+export declare class TokenStream {
+    private readonly tokens;
+    private pos;
+    constructor(tokens: readonly Token[]);
+    /** Look at the current token without advancing. */
+    peek(): Token | undefined;
+    /** Consume and return the current token. Throws if at end. */
+    advance(): Token;
+    /** Save the current position for backtracking. */
+    mark(): number;
+    /** Restore to a previously saved position. */
+    restore(mark: number): void;
+    /** Number of tokens consumed since the mark. */
+    consumed(mark: number): number;
+    /** Whether there are more tokens. */
+    hasMore(): boolean;
+    /** Current position in the stream. */
+    get position(): number;
+    /** Look at the token immediately before the current position. */
+    peekPrevious(): Token | undefined;
+}
+//# sourceMappingURL=stream.d.ts.map

package/dist/graph/nav/parse/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../../graph/nav/parse/stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AAEzC,wDAAwD;AACxD,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,GAAG,CAAI;IAEf,YAA6B,MAAM,EAAE,SAAS,KAAK,EAAE,EAAI;IAEzD,mDAAmD;IACnD,IAAI,IAAI,KAAK,GAAG,SAAS,CAExB;IAED,8DAA8D;IAC9D,OAAO,IAAI,KAAK,CAKf;IAED,kDAAkD;IAClD,IAAI,IAAI,MAAM,CAEb;IAED,8CAA8C;IAC9C,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE1B;IAED,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7B;IAED,qCAAqC;IACrC,OAAO,IAAI,OAAO,CAEjB;IAED,sCAAsC;IACtC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,iEAAiE;IACjE,YAAY,IAAI,KAAK,GAAG,SAAS,CAEhC;CACF"}

package/dist/graph/nav/parse/stream.js

@@ -0,0 +1,45 @@
+/** Cursor over a Token array for parser consumption. */
+export class TokenStream {
+    tokens;
+    pos = 0;
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    /** Look at the current token without advancing. */
+    peek() {
+        return this.tokens[this.pos];
+    }
+    /** Consume and return the current token. Throws if at end. */
+    advance() {
+        const token = this.tokens[this.pos];
+        if (!token)
+            throw new Error('Unexpected end of token stream');
+        this.pos++;
+        return token;
+    }
+    /** Save the current position for backtracking. */
+    mark() {
+        return this.pos;
+    }
+    /** Restore to a previously saved position. */
+    restore(mark) {
+        this.pos = mark;
+    }
+    /** Number of tokens consumed since the mark. */
+    consumed(mark) {
+        return this.pos - mark;
+    }
+    /** Whether there are more tokens. */
+    hasMore() {
+        return this.pos < this.tokens.length;
+    }
+    /** Current position in the stream. */
+    get position() {
+        return this.pos;
+    }
+    /** Look at the token immediately before the current position. */
+    peekPrevious() {
+        return this.tokens[this.pos - 1];
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/graph/nav/parse/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../../../graph/nav/parse/stream.ts"],"names":[],"mappings":"AAEA,wDAAwD;AACxD,MAAM,OAAO,WAAW;IAGO,MAAM;IAF3B,GAAG,GAAG,CAAC,CAAA;IAEf,YAA6B,MAAwB;sBAAxB,MAAM;IAAqB,CAAC;IAEzD,mDAAmD;IACnD,IAAI;QACF,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAC9B,CAAC;IAED,8DAA8D;IAC9D,OAAO;QACL,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACnC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAA;QAC7D,IAAI,CAAC,GAAG,EAAE,CAAA;QACV,OAAO,KAAK,CAAA;IACd,CAAC;IAED,kDAAkD;IAClD,IAAI;QACF,OAAO,IAAI,CAAC,GAAG,CAAA;IACjB,CAAC;IAED,8CAA8C;IAC9C,OAAO,CAAC,IAAY;QAClB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAA;IACjB,CAAC;IAED,gDAAgD;IAChD,QAAQ,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,GAAG,GAAG,IAAI,CAAA;IACxB,CAAC;IAED,qCAAqC;IACrC,OAAO;QACL,OAAO,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAA;IACtC,CAAC;IAED,sCAAsC;IACtC,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,GAAG,CAAA;IACjB,CAAC;IAED,iEAAiE;IACjE,YAAY;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAA;IAClC,CAAC;CACF"}

package/dist/graph/nav/parse/validation.d.ts

@@ -0,0 +1,12 @@
+export interface ValidationError {
+    readonly kind: string;
+    readonly message: string;
+    readonly position: number;
+}
+export interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly ValidationError[];
+}
+export declare function validResult(): ValidationResult;
+export declare function invalidResult(...errors: ValidationError[]): ValidationResult;
+//# sourceMappingURL=validation.d.ts.map

package/dist/graph/nav/parse/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../../graph/nav/parse/validation.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAA;CAC5C;AAED,wBAAgB,WAAW,IAAI,gBAAgB,CAE9C;AAED,wBAAgB,aAAa,CAAC,GAAG,MAAM,EAAE,eAAe,EAAE,GAAG,gBAAgB,CAE5E"}

package/dist/graph/nav/parse/validation.js

@@ -0,0 +1,7 @@
+export function validResult() {
+    return { valid: true, errors: [] };
+}
+export function invalidResult(...errors) {
+    return { valid: false, errors };
+}
+//# sourceMappingURL=validation.js.map

package/dist/graph/nav/parse/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../../graph/nav/parse/validation.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,WAAW;IACzB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;AACpC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAG,MAAyB;IACxD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AACjC,CAAC"}

package/dist/graph/nav/path/build.d.ts

@@ -0,0 +1,21 @@
+import type { GraphView } from '#graph';
+import type { Node } from '#graph/node/node';
+import type { PathType } from './kinds/path-type';
+import type { Path } from './path';
+/**
+ * Build the canonical typed path for a node by walking the graph
+ * backward through a PathType's segment chain.
+ *
+ * With `hint`, force a specific type (typically when a caller wants a
+ * known scheme even if a more specific one would otherwise be picked).
+ *
+ * Without a hint, types are tried longest-segment-chain first; the
+ * first one whose `walkChain` succeeds and whose `matches` accepts
+ * the steps wins. Types with `segments: []` are skipped — they have
+ * no walk-back recipe.
+ *
+ * If no type matches, falls back to the universal {@link IdPath} —
+ * every node has an id, so every node has an id-anchored path.
+ */
+export declare function buildPath(target: Node, graph: GraphView, hint?: PathType): Path;
+//# sourceMappingURL=build.d.ts.map

package/dist/graph/nav/path/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../../graph/nav/path/build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AACvC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAE5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAQlC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CA6B/E"}

package/dist/graph/nav/path/build.js

@@ -0,0 +1,53 @@
+import { idAnchor } from '../ast/step';
+import { serializeSteps } from '../serialize/steps';
+import { IdentifyError } from './errors';
+import { matchesChain, walkChain } from './kinds/chain';
+import { PathTypeRegistry } from './kinds/registry';
+/**
+ * Build the canonical typed path for a node by walking the graph
+ * backward through a PathType's segment chain.
+ *
+ * With `hint`, force a specific type (typically when a caller wants a
+ * known scheme even if a more specific one would otherwise be picked).
+ *
+ * Without a hint, types are tried longest-segment-chain first; the
+ * first one whose `walkChain` succeeds and whose `matches` accepts
+ * the steps wins. Types with `segments: []` are skipped — they have
+ * no walk-back recipe.
+ *
+ * If no type matches, falls back to the universal {@link IdPath} —
+ * every node has an id, so every node has an id-anchored path.
+ */
+export function buildPath(target, graph, hint) {
+    if (hint) {
+        const steps = walkChain(hint, target, graph);
+        return hint.build(steps, serializeSteps(steps));
+    }
+    const ordered = [...PathTypeRegistry.all()].sort((a, b) => b.segments.length - a.segments.length);
+    for (const type of ordered) {
+        if (type.segments.length === 0)
+            continue;
+        try {
+            const steps = walkChain(type, target, graph);
+            const accepted = (type.matches ?? ((s) => matchesChain(type.segments, s)))(steps);
+            if (!accepted)
+                continue;
+            return type.build(steps, serializeSteps(steps));
+        }
+        catch (e) {
+            if (e instanceof IdentifyError)
+                continue;
+            throw e;
+        }
+    }
+    // Universal fallback: every node has an id, every node has an
+    // id-anchored path. Tried last so structural types win when they
+    // apply.
+    const idType = PathTypeRegistry.all().find((t) => t.name === 'IdPath');
+    if (idType !== undefined) {
+        const steps = [idAnchor(target.id)];
+        return idType.build(steps, serializeSteps(steps));
+    }
+    throw new IdentifyError(`No PathType could build a path for node ${target.id}`);
+}
+//# sourceMappingURL=build.js.map

package/dist/graph/nav/path/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../../graph/nav/path/build.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAEnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CAAC,MAAY,EAAE,KAAgB,EAAE,IAAe;IACvE,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAA;QAC5C,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAA;IACjD,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,GAAG,gBAAgB,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IACjG,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,SAAQ;QACxC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAA;YAC5C,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;YACjF,IAAI,CAAC,QAAQ;gBAAE,SAAQ;YACvB,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAA;QACjD,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,aAAa;gBAAE,SAAQ;YACxC,MAAM,CAAC,CAAA;QACT,CAAC;IACH,CAAC;IAED,8DAA8D;IAC9D,iEAAiE;IACjE,SAAS;IACT,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAA;IACtE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAA;QACnC,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAA;IACnD,CAAC;IACD,MAAM,IAAI,aAAa,CAAC,2CAA2C,MAAM,CAAC,EAAE,EAAE,CAAC,CAAA;AACjF,CAAC"}

package/dist/graph/nav/path/errors.d.ts

@@ -0,0 +1,50 @@
+import type { NodeId } from '#ids';
+import type { ValidationError } from '../parse/validation';
+/**
+ * Raised when a string cannot be parsed into a valid path. Carries the
+ * original input alongside one or more lex/parse-level diagnostics.
+ */
+export declare class PathParseError extends Error {
+    readonly name = "PathParseError";
+    readonly input: string;
+    readonly errors: readonly ValidationError[];
+    constructor(input: string, errors: readonly ValidationError[]);
+    /** Alias for `input` — older callsites read `error.raw`. */
+    get raw(): string;
+}
+/**
+ * Raised when a node cannot be identified into a typed path — the
+ * walk-back terminated early or hit a graph state that violates the
+ * scheme's anchoring-edge invariant.
+ */
+export declare class IdentifyError extends Error {
+    readonly name = "IdentifyError";
+    readonly reason: string;
+    constructor(message: string, reason?: string);
+}
+export declare class PathNotFoundError extends Error {
+    readonly path: {
+        raw: string;
+    };
+    readonly failedAtStep: string;
+    readonly context?: NodeId | undefined;
+    readonly name = "PathNotFoundError";
+    constructor(path: {
+        raw: string;
+    }, failedAtStep: string, context?: NodeId | undefined);
+}
+export declare class AmbiguousPathError extends Error {
+    readonly path: {
+        raw: string;
+    };
+    readonly name = "AmbiguousPathError";
+    constructor(path: {
+        raw: string;
+    });
+}
+export declare class MissingContextError extends Error {
+    readonly reason: string;
+    readonly name = "MissingContextError";
+    constructor(reason: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/graph/nav/path/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../graph/nav/path/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAElC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAE1D;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAkB,IAAI,oBAAmB;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAA;IAE3C,YAAY,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,eAAe,EAAE,EAI5D;IAED,4DAA4D;IAC5D,IAAI,GAAG,IAAI,MAAM,CAEhB;CACF;AAED;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,SAAkB,IAAI,mBAAkB;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IAEvB,YAAY,OAAO,EAAE,MAAM,EAAE,MAAM,SAAqB,EAGvD;CACF;AAED,qBAAa,iBAAkB,SAAQ,KAAK;aAGxB,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE;aACrB,YAAY,EAAE,MAAM;aACpB,OAAO,CAAC,EAAE,MAAM;IAJlC,SAAkB,IAAI,uBAAsB;IAC5C,YACkB,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,EACrB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,MAAM,YAAA,EAIjC;CACF;AAED,qBAAa,kBAAmB,SAAQ,KAAK;aAEf,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE;IADjD,SAAkB,IAAI,wBAAuB;IAC7C,YAA4B,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,EAEhD;CACF;AAED,qBAAa,mBAAoB,SAAQ,KAAK;aAEhB,MAAM,EAAE,MAAM;IAD1C,SAAkB,IAAI,yBAAwB;IAC9C,YAA4B,MAAM,EAAE,MAAM,EAEzC;CACF"}