@zenera/rag 1.1.6 → 1.1.8

package/dist/schema/files.d.ts

@@ -1,8 +1,10 @@
+import { type IndexHead, type IndexSpec } from '../common/manifest.ts';
 import type { ApiGraph } from './graph.ts';
 import type { Schema } from './schema.ts';
 import type { Operation } from './spec.ts';
 export declare const INDEX_VERSION = 3;
-export declare const MANIFEST_FILE = "manifest.json";
+/** How a schema index is found, read, and refused. */
+export declare const SCHEMA_INDEX: IndexSpec;
 export declare const GRAPH_FILE = "graph.json";
 export declare const SCHEMAS_FILE = "schemas.json";
 export declare const OPERATIONS_FILE = "operations.json";
@@ -30,23 +32,9 @@ export interface Counts {
     properties: number;
     entities: number;
 }
-export interface Manifest {
-    version: number;
-    createdAt: string;
-    indexer: string;
-    /** `ref` as it was typed, `id` as the embedder answers to it */
-    embedding: {
-        ref: string;
-        id: string;
-        dimensions: number;
-    };
+export interface Manifest extends IndexHead {
     sources: SourceRecord[];
     counts: Counts;
-    /** whether the table carries an fts index, and whether it carries a vector one */
-    indexes: {
-        fts: boolean;
-        vector: boolean;
-    };
 }
 export interface WrittenIndex {
     manifest: Manifest;
@@ -75,15 +63,5 @@ export declare function openIndex(dir: string): Promise<OpenIndex>;
  * of what the caller can do next.
  */
 export declare function readSource(dir: string, name: string): Promise<string | undefined>;
-export declare function readManifest(dir: string): Promise<Manifest>;
-/**
- * A store answers with the neighbours of a vector, and a vector means nothing
- * without the model that produced it. Asking one model's index a question
- * embedded by another returns rows, in an order that is noise.
- *
- * Either spelling is accepted, because `openai:text-embedding-3-small` and
- * `text-embedding-3-small` are one model and which of them was typed is not
- * something anyone should have to remember.
- */
-export declare function assertSameEmbedding(manifest: Manifest, ref: string): void;
+export declare const readManifest: (dir: string) => Promise<Manifest>;
 //# sourceMappingURL=files.d.ts.map

package/dist/schema/files.js

@@ -2,6 +2,7 @@ import { CliError, EXIT } from '@zenera/cli/lib';
 import { MultiDirectedGraph } from 'graphology';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { MANIFEST_FILE, readHead } from "../common/manifest.js";
 // ---------------------------------------------------------------------------
 // What an index is, on disk
 //
@@ -20,7 +21,13 @@ import { join } from 'node:path';
 // model — without going looking for the files it was made from.
 // ---------------------------------------------------------------------------
 export const INDEX_VERSION = 3;
-export const MANIFEST_FILE = 'manifest.json';
+/** How a schema index is found, read, and refused. */
+export const SCHEMA_INDEX = {
+    kind: 'schema',
+    version: INDEX_VERSION,
+    defaultDir: './schema-db',
+    envName: 'ZEN_SCHEMA_DB',
+};
 export const GRAPH_FILE = 'graph.json';
 export const SCHEMAS_FILE = 'schemas.json';
 export const OPERATIONS_FILE = 'operations.json';
@@ -77,32 +84,5 @@ export async function readSource(dir, name) {
     }
     return await readFile(join(dir, record.path), 'utf8');
 }
-export async function readManifest(dir) {
-    let text;
-    try {
-        text = await readFile(join(dir, MANIFEST_FILE), 'utf8');
-    }
-    catch {
-        throw new CliError(`${dir} does not hold an index`, EXIT.invalid, 'build one with `zen rag schema index`, or name an existing one with --dir or $ZEN_SCHEMA_DB');
-    }
-    const manifest = JSON.parse(text);
-    if (manifest.version !== INDEX_VERSION) {
-        throw new CliError(`${dir} is a version ${manifest.version} index, and this indexer reads version ${INDEX_VERSION}`, EXIT.invalid, 'rebuild it with `zen rag schema index`');
-    }
-    return manifest;
-}
-/**
- * A store answers with the neighbours of a vector, and a vector means nothing
- * without the model that produced it. Asking one model's index a question
- * embedded by another returns rows, in an order that is noise.
- *
- * Either spelling is accepted, because `openai:text-embedding-3-small` and
- * `text-embedding-3-small` are one model and which of them was typed is not
- * something anyone should have to remember.
- */
-export function assertSameEmbedding(manifest, ref) {
-    if (ref !== manifest.embedding.ref && ref !== manifest.embedding.id) {
-        throw new CliError(`this index was built with ${manifest.embedding.ref}, not ${ref}`, EXIT.invalid, `search it with --embedding ${manifest.embedding.ref}, or rebuild it`);
-    }
-}
+export const readManifest = (dir) => readHead(dir, SCHEMA_INDEX);
 //# sourceMappingURL=files.js.map

package/dist/schema/lookup.d.ts

@@ -1,5 +1,5 @@
+import { type Matcher } from '../common/match.ts';
 import { type ApiGraph, type NodeAttrs, type NodeKind } from './graph.ts';
-import { type Matcher } from './match.ts';
 export interface Row extends NodeAttrs {
     id: string;
 }

package/dist/schema/lookup.js

@@ -1,6 +1,6 @@
+import { PatternError } from "../common/match.js";
 import { textOf } from "./entities.js";
 import { methodId } from "./graph.js";
-import { PatternError } from "./match.js";
 /** A scan is bounded, because a pattern may have come from a model. */
 const DEADLINE_MS = 2000;
 const DEADLINE_EVERY = 500;

package/dist/{present.d.ts → schema/present.d.ts}

@@ -1,8 +1,8 @@
-import { type HydrateOptions } from './schema/hydrate.ts';
-import { type RenderOptions } from './schema/render.ts';
-import type { Schema } from './schema/schema.ts';
-import type { Operation } from './schema/spec.ts';
-import type { Subgraph } from './schema/subgraph.ts';
+import { type HydrateOptions } from './hydrate.ts';
+import { type RenderOptions } from './render.ts';
+import type { Schema } from './schema.ts';
+import type { Operation } from './spec.ts';
+import type { Subgraph } from './subgraph.ts';
 export declare const FORMATS: readonly ["text", "mermaid", "mermaid-flowchart", "ts", "openapi"];
 export type Format = (typeof FORMATS)[number];
 export declare function isFormat(value: string): value is Format;

package/dist/{present.js → schema/present.js}

@@ -1,5 +1,5 @@
-import { toOpenApi, toTypeScript } from "./schema/hydrate.js";
-import { render } from "./schema/render.js";
+import { toOpenApi, toTypeScript } from "./hydrate.js";
+import { render } from "./render.js";
 // ---------------------------------------------------------------------------
 // One subgraph, in whichever of the four shapes was asked for
 //

package/dist/{query.d.ts → schema/query.d.ts}

@@ -1,4 +1,4 @@
-import type { SchemaQuery } from './schema/search.ts';
+import type { SchemaQuery } from './search.ts';
 export declare class QueryError extends Error {
 }
 export declare function parseQuery(value: unknown): SchemaQuery;

package/dist/schema/readme.d.ts

@@ -0,0 +1,6 @@
+import type { Report } from '../common/progress.ts';
+import type { Counts, Manifest } from './files.ts';
+export type Phase = 'reading' | 'graph' | 'embedding' | 'writing';
+export declare const PHASES: Record<Phase, string>;
+export declare const SCHEMA_REPORT: Report<Counts, Manifest>;
+//# sourceMappingURL=readme.d.ts.map

package/dist/schema/readme.js

@@ -0,0 +1,122 @@
+import { basename } from 'node:path';
+import { INTERVAL_MS } from "../common/progress.js";
+import { duration, fields, grid, message, plural, searched } from "../common/prose.js";
+export const PHASES = {
+    reading: 'reading the documents',
+    graph: 'building the graph',
+    embedding: 'embedding',
+    writing: 'writing the store',
+};
+export const SCHEMA_REPORT = { building, complete, failed };
+function building(state) {
+    const rows = [
+        ['documents', state.documents.join(', ')],
+        ['embedding', state.embedding],
+        [
+            'started',
+            `${new Date(state.started).toISOString()} (${duration(state.now - state.started)} ago)`,
+        ],
+        ['step', state.step],
+    ];
+    if (state.summary) {
+        rows.push(['found', entities(state.summary)]);
+    }
+    if (state.total > 0) {
+        const percent = Math.round((state.done / state.total) * 100);
+        rows.push(['embedded', `${state.done} of ${state.total} · ${percent}%`]);
+    }
+    rows.push(['updated', new Date(state.now).toISOString()]);
+    return [
+        '# Schema index — being built',
+        '',
+        'A searchable index of the API documents named below, written by `zen rag schema index`.',
+        '**It is incomplete. Nothing should read it yet.**',
+        '',
+        ...fields(rows),
+        '',
+        `These lines are refreshed at most every ${INTERVAL_MS / 1000} seconds while the build runs, and`,
+        'the whole file is replaced by a description of the index when it finishes. If it still says',
+        '"being built" and `.lock` names no living process, the build died part way.',
+        '',
+    ].join('\n');
+}
+function complete(state) {
+    const { manifest } = state;
+    const titles = manifest.sources.map((s) => s.title).filter(Boolean);
+    const what = titles.length > 0 ? titles.join(', ') : basename(state.dir);
+    return [
+        `# Schema index — ${what}`,
+        '',
+        `A searchable index of ${plural(manifest.sources.length, 'API document')}, built with`,
+        `${manifest.embedding.ref} (${manifest.embedding.dimensions}d) in ${duration(state.ms)}.`,
+        'Ask it for the operations and types behind a question and it answers with a subgraph:',
+        'the endpoints that match, the schemas they carry, and the fields inside those — printed',
+        'as text, Mermaid, TypeScript or OpenAPI.',
+        '',
+        '## What it covers',
+        '',
+        ...sourceTable(manifest.sources),
+        '',
+        `${entities(manifest.counts)},`,
+        `${searched(manifest.indexes)}.`,
+        '',
+        '## Files',
+        '',
+        ...fields([
+            ['manifest.json', 'what this index is and what built it — read this first'],
+            ['graph.json', 'the nodes and edges: operations, types, fields'],
+            ['schemas.json', 'the JSON Schema of every type'],
+            ['operations.json', 'every operation, with its parameters and responses'],
+            ...(manifest.sources.some((s) => s.path)
+                ? [['sources/', 'the documents themselves, bundled, exactly as indexed']]
+                : []),
+            ['lance/', 'the LanceDB table: the search text, the vectors, the filter columns'],
+        ]),
+        '',
+        '## Asking it something',
+        '',
+        'From this directory:',
+        '',
+        '```',
+        'zen rag schema search --dir . --all "how do I cancel a subscription"',
+        '```',
+        '',
+        `Built by ${manifest.indexer} on ${manifest.createdAt}.`,
+        '',
+    ].join('\n');
+}
+function failed(state) {
+    return [
+        '# Schema index — failed',
+        '',
+        'This index was not finished and what is here is incomplete. Nothing should read it;',
+        'build it again with `zen rag schema index`.',
+        '',
+        ...fields([
+            ['documents', state.documents.join(', ')],
+            ['step', state.step],
+            ['reason', message(state.reason)],
+            ['started', new Date(state.started).toISOString()],
+            [
+                'failed',
+                `${new Date().toISOString()} (after ${duration(Date.now() - state.started)})`,
+            ],
+        ]),
+        '',
+    ].join('\n');
+}
+// ---------------------------------------------------------------------------
+const HEADERS = ['document', 'dialect', 'paths', 'operations', 'schemas', 'fields'];
+const sourceTable = (sources) => grid(HEADERS, sources.map((s) => [
+    s.file,
+    s.dialect,
+    String(s.paths),
+    String(s.methods),
+    String(s.types),
+    String(s.properties),
+]));
+function entities(counts) {
+    return (`${plural(counts.entities, 'entity', 'entities')}: ` +
+        `${counts.methods} operations, ${counts.types} schemas, ${counts.properties} fields`);
+}
+//# sourceMappingURL=readme.js.map

package/dist/{repl.d.ts → schema/repl.d.ts}

@@ -1,5 +1,5 @@
 import { type Format, type OutputOptions } from './present.ts';
-import type { SchemaIndex, SchemaQuery } from './schema/search.ts';
+import type { SchemaIndex, SchemaQuery } from './search.ts';
 interface Settings extends OutputOptions {
     format: Format;
 }

package/dist/schema/search.js

@@ -1,4 +1,5 @@
-import { assertSameEmbedding, openIndex } from "./files.js";
+import { assertSameEmbedding } from "../common/manifest.js";
+import { openIndex } from "./files.js";
 import { EntityStore } from "./store.js";
 import { DEFAULT_MAX_HOPS, DEFAULT_MAX_NODES, stitch, } from "./subgraph.js";
 export const DEFAULT_LIMIT = 5;

package/dist/schema/tools.d.ts

@@ -1,5 +1,5 @@
 import { type AnyTool } from '@zenera/neo';
-import { type Format } from '../present.ts';
+import { type Format } from './present.ts';
 import type { SchemaIndex } from './search.ts';
 export interface SchemaToolOptions {
     /** what `format` defaults to when the model does not say */

package/dist/schema/tools.js

@@ -1,16 +1,17 @@
 import { tool } from '@zenera/neo';
-import { FORMATS, isFormat, present } from "../present.js";
-import { isEmpty, parseQuery, QueryError } from "../query.js";
+import { loose, matcher, PatternError } from "../common/match.js";
+import { FORMATS, isFormat, present } from "./present.js";
+import { isEmpty, parseQuery, QueryError } from "./query.js";
 import { toTypeScript } from "./hydrate.js";
 import { fields, grepNodes, listNodes, propertyCount } from "./lookup.js";
-import { loose, matcher, PatternError } from "./match.js";
 import { sourceTag } from "./render.js";
 import { stitch } from "./subgraph.js";
+import { chainOf, traceNodes } from "./trace.js";
 // ---------------------------------------------------------------------------
 // The same index, given to an agent
 //
-// Five tools over one engine, and only one of them ranks anything. `search_api`
-// is the way in when the question is vague; the other four are exact, because
+// Six tools over one engine, and only one of them ranks anything. `search_api`
+// is the way in when the question is vague; the other five are exact, because
 // a model that has been told "no results" by a vector search has learned
 // nothing — a ranking returns the top of a list, so an empty answer and an
 // absent thing look identical.
@@ -20,6 +21,12 @@ import { stitch } from "./subgraph.js";
 // model does not need to be reminded what a password is — it needs the list of
 // types that have one. `grep_api` is the same instinct widened: every literal
 // occurrence, counted in full, so "it is not there" can actually be concluded.
+//
+// `trace_api` is the other direction entirely. Having found a field, the next
+// question is always which call carries it. `search_api` stitches part of the
+// way there, but only between the nodes that ranked — and the operation and
+// the field usually share no word at all, which is why the edge between them
+// was built. `trace_api` follows that edge instead of ranking anything.
 // ---------------------------------------------------------------------------
 const GROUP = 'schema';
 /** Kept small on purpose: a tool result is prompt, and the model asked for one thing. */
@@ -29,6 +36,10 @@ const MAX_CANDIDATES = 25;
 /** A listing is lines rather than subgraphs, so it can afford more of them. */
 const DEFAULT_ROWS = 50;
 const MAX_ROWS = 200;
+/** A trace is a paragraph per node, so fewer of them, and fewer routes each. */
+const DEFAULT_TRACES = 5;
+const MAX_TRACES = 25;
+const DEFAULT_ROUTES = 10;
 export function schemaTools(index, options = {}) {
     const fallback = options.format ?? 'text';
     const docs = options.docs ?? true;
@@ -341,7 +352,87 @@ export function schemaTools(index, options = {}) {
             };
         },
     });
-    return [searchApi, describeTypes, findTypesWithProperty, listApi, grepApi];
+    const traceApi = tool({
+        name: 'trace_api',
+        group: GROUP,
+        description: 'Answers "which calls can reach this?" for a field or a schema: walks up the ' +
+            'graph from everything of that name to the operations that accept or return it, ' +
+            'and gives the chain in between. Use it whenever a field has been found and the ' +
+            'endpoint to call is what is actually wanted — searching for the operation will ' +
+            'not work, because a call almost never repeats the name of a field nested inside ' +
+            'its body. An empty answer means nothing in the API carries it.',
+        parameters: {
+            type: 'object',
+            properties: {
+                of: {
+                    type: 'string',
+                    description: 'The field or schema name to trace up from, or a node id such as ' +
+                        '"Type:User". A plain word matches anywhere in the name; * and ? ' +
+                        'match the whole of it.',
+                },
+                kind: {
+                    type: 'string',
+                    enum: ['type', 'property'],
+                    description: 'Only trace from schemas, or only from fields.',
+                },
+                direction: {
+                    type: 'string',
+                    enum: ['input', 'output', 'any'],
+                    description: 'Keep only the calls that accept it, or that return it.',
+                },
+                source: {
+                    type: 'string',
+                    description: 'Only this document, when the index holds more than one.',
+                },
+                limit: {
+                    type: 'integer',
+                    description: `Nodes to trace from. Default ${DEFAULT_TRACES}.`,
+                },
+                routes: {
+                    type: 'integer',
+                    description: `Operations per node. Default ${DEFAULT_ROUTES}.`,
+                },
+            },
+            required: ['of'],
+            additionalProperties: false,
+        },
+        execute: async ({ of: wanted, kind, direction, source: only, limit, routes }) => {
+            let result;
+            try {
+                result = traceNodes(index.graph, {
+                    ids: index.graph.hasNode(wanted) ? [wanted] : undefined,
+                    kinds: kind ? [kind] : undefined,
+                    name: index.graph.hasNode(wanted) ? undefined : [loose(wanted)],
+                    source: only,
+                    limit: Math.min(limit ?? DEFAULT_TRACES, MAX_TRACES),
+                    maxRoutes: Math.min(routes ?? DEFAULT_ROUTES, MAX_ROWS),
+                });
+            }
+            catch (err) {
+                return { error: err instanceof PatternError ? err.message : String(err) };
+            }
+            if (result.found === 0) {
+                return {
+                    found: 0,
+                    hint: `nothing in the API is called "${wanted}" — try grep_api for it`,
+                };
+            }
+            const side = enumerated(direction);
+            return {
+                found: result.found,
+                truncated: result.truncated,
+                traced: result.traces.map((t) => ({
+                    id: t.id,
+                    reached_by: t.found,
+                    operations: t.routes
+                        .filter((r) => !side || r.direction === side || r.direction === 'both')
+                        .map((r) => `${r.attributes.httpMethod} ${r.attributes.path}  ` +
+                        `${r.attributes.name}  (${r.direction})${source ? `  ${sourceTag(r.attributes.source)}` : ''}  ${chainOf(index.graph, t.id, r)}`),
+                })),
+            };
+        },
+    });
+    return [searchApi, describeTypes, findTypesWithProperty, listApi, grepApi, traceApi];
 }
 // ---------------------------------------------------------------------------
 const SUBJECTS = {

package/dist/schema/trace.d.ts

@@ -0,0 +1,52 @@
+import type { Matcher } from '../common/match.ts';
+import type { ApiGraph, NodeAttrs, NodeKind } from './graph.ts';
+export type Side = 'input' | 'output' | 'both';
+export interface Route {
+    /** the operation node */
+    id: string;
+    attributes: NodeAttrs;
+    /** whether the call accepts what was traced, returns it, or both */
+    direction: Side;
+    /** the nodes in between, nearest the operation first */
+    via: string[];
+    hops: number;
+}
+export interface Trace {
+    id: string;
+    attributes: NodeAttrs;
+    /** how many operations reach it, whatever was kept */
+    found: number;
+    routes: Route[];
+    truncated: boolean;
+}
+export interface Traced {
+    /** how many nodes were traced, whatever was kept */
+    found: number;
+    traces: Trace[];
+    truncated: boolean;
+}
+export interface TraceFilter {
+    /** node ids to start from, taken as given */
+    ids?: readonly string[];
+    /** which kinds a `name` may match; all three when unset */
+    kinds?: readonly NodeKind[];
+    name?: readonly Matcher[];
+    source?: string;
+    /** starting nodes kept */
+    limit?: number;
+    /** routes kept per starting node */
+    maxRoutes?: number;
+    maxHops?: number;
+}
+/** How far containment is read backwards before a route is too indirect to mean anything. */
+export declare const DEFAULT_TRACE_HOPS = 8;
+export declare function traceNodes(graph: ApiGraph, filter: TraceFilter): Traced;
+export declare function traceOne(graph: ApiGraph, id: string, filter?: TraceFilter): Trace;
+/**
+ * The chain from an operation down to the node that was traced, as one line.
+ * A field is written onto the type above it (`User.email`) and a parameter is
+ * marked (`?page_size`), so the shape of the call can be read off the route
+ * without going and looking any of it up.
+ */
+export declare function chainOf(graph: ApiGraph, start: string, route: Route): string;
+//# sourceMappingURL=trace.d.ts.map

package/dist/schema/trace.js

@@ -0,0 +1,144 @@
+import { listNodes } from "./lookup.js";
+/** How far containment is read backwards before a route is too indirect to mean anything. */
+export const DEFAULT_TRACE_HOPS = 8;
+/** A walk is bounded; a document can always be larger than the one this was written against. */
+const MAX_VISITS = 20_000;
+/**
+ * What a bare pattern matches. Operations are left out on purpose: they are
+ * where a trace ends, so starting one at an operationId that happens to share
+ * a word adds a row saying only that it found itself. Naming a `Method:` id
+ * outright still works.
+ */
+const KINDS = ['type', 'property'];
+/** The edges an operation holds its payload by. Reaching one of these is arriving. */
+const ENTRY = new Set(['TAKES_INPUT', 'RETURNS_OUTPUT', 'HAS_PARAM']);
+/** Containment, read backwards: a type to the fields that hold it, a field to its owner. */
+const UPWARD = new Set(['HAS_PROPERTY', 'OF_TYPE', 'COMPOSES', 'ITEM_OF']);
+export function traceNodes(graph, filter) {
+    const starts = select(graph, filter);
+    const kept = filter.limit && filter.limit < starts.length ? starts.slice(0, filter.limit) : starts;
+    return {
+        found: starts.length,
+        truncated: kept.length < starts.length,
+        traces: kept.map((id) => traceOne(graph, id, filter)),
+    };
+}
+export function traceOne(graph, id, filter = {}) {
+    const attributes = graph.getNodeAttributes(id);
+    // An operation is already where a trace ends; it reaches itself and nothing above it.
+    const routes = attributes.kind === 'method'
+        ? [{ id, attributes, direction: 'both', via: [], hops: 0 }]
+        : climb(graph, id, filter.maxHops ?? DEFAULT_TRACE_HOPS);
+    const limit = filter.maxRoutes;
+    return {
+        id,
+        attributes,
+        found: routes.length,
+        routes: limit && limit < routes.length ? routes.slice(0, limit) : routes,
+        truncated: Boolean(limit && limit < routes.length),
+    };
+}
+/**
+ * The chain from an operation down to the node that was traced, as one line.
+ * A field is written onto the type above it (`User.email`) and a parameter is
+ * marked (`?page_size`), so the shape of the call can be read off the route
+ * without going and looking any of it up.
+ */
+export function chainOf(graph, start, route) {
+    let out = '';
+    for (const id of [...route.via, start]) {
+        const label = labelOf(graph, id);
+        out += out === '' || label.startsWith('.') ? label : ` → ${label}`;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+function labelOf(graph, id) {
+    const a = graph.getNodeAttributes(id);
+    if (a.kind !== 'property') {
+        return a.name;
+    }
+    // A parameter belongs to a call rather than to a type, so it cannot be
+    // written as a field of the thing before it.
+    return id.includes('#') ? `?${a.name}` : `.${a.name}`;
+}
+function select(graph, filter) {
+    const out = new Set((filter.ids ?? []).filter((id) => graph.hasNode(id)));
+    if (filter.name) {
+        for (const kind of filter.kinds ?? KINDS) {
+            for (const row of listNodes(graph, { kind, name: filter.name, source: filter.source })
+                .rows) {
+                out.add(row.id);
+            }
+        }
+    }
+    return [...out].sort((a, b) => a.localeCompare(b));
+}
+/**
+ * Breadth-first up containment, recording an operation the moment one is
+ * reached. Breadth-first is what makes the answer the *shortest* way in: a
+ * type held by a wrapper held by a request body should be reported through
+ * the body, not through whichever branch happened to be walked first.
+ */
+function climb(graph, start, maxHops) {
+    const previous = new Map();
+    const seen = new Set([start]);
+    const found = new Map();
+    let frontier = [start];
+    for (let hop = 0; hop <= maxHops && frontier.length > 0 && seen.size < MAX_VISITS; hop++) {
+        const next = [];
+        for (const node of frontier) {
+            for (const edge of graph.inEdges(node)) {
+                const relation = graph.getEdgeAttribute(edge, 'relation');
+                const from = graph.source(edge);
+                if (ENTRY.has(relation)) {
+                    arrive(found, {
+                        id: from,
+                        attributes: graph.getNodeAttributes(from),
+                        direction: sideOf(relation),
+                        via: upward(previous, start, node),
+                        hops: hop + 1,
+                    });
+                }
+                else if (UPWARD.has(relation) && !seen.has(from)) {
+                    seen.add(from);
+                    previous.set(from, node);
+                    next.push(from);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return [...found.values()].sort((a, b) => a.hops - b.hops ||
+        a.attributes.path.localeCompare(b.attributes.path) ||
+        a.attributes.httpMethod.localeCompare(b.attributes.httpMethod));
+}
+/**
+ * One operation, once. A call that both accepts and returns the same type is
+ * two edges and one answer, and the honest word for that answer is `both`.
+ */
+function arrive(found, route) {
+    const existing = found.get(route.id);
+    if (!existing) {
+        found.set(route.id, route);
+    }
+    else if (existing.direction !== route.direction) {
+        existing.direction = 'both';
+    }
+}
+const sideOf = (relation) => (relation === 'RETURNS_OUTPUT' ? 'output' : 'input');
+/** The nodes walked through, from the one holding the entry edge back down towards the start. */
+function upward(previous, start, from) {
+    const out = [];
+    let at = from;
+    while (at !== start) {
+        out.push(at);
+        const below = previous.get(at);
+        if (below === undefined) {
+            break;
+        }
+        at = below;
+    }
+    return out;
+}
+//# sourceMappingURL=trace.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/rag",
-    "version": "1.1.6",
+    "version": "1.1.8",
     "description": "Retrieval over API descriptions: openapi/swagger documents as a searchable graph.",
     "keywords": [
         "agents",
@@ -53,7 +53,7 @@
         "@apidevtools/swagger-parser": "^12.0.0",
         "@lancedb/lancedb": "^0.38.0",
         "graphology": "^0.26.0",
-        "@zenera/cli": "^1.1.6",
-        "@zenera/neo": "^1.1.6"
+        "@zenera/cli": "^1.1.8",
+        "@zenera/neo": "^1.1.8"
     }
 }