@weftlet/toolkit 0.6.0 → 0.7.0

package/dist/graph/neighborhood.js

@@ -0,0 +1,100 @@
+import { snapshotContext } from './snapshot-context.js';
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { RdfEvidenceGraph } from './rdf.js';
+import { coverageForFacts } from './coverage.js';
+import { parseGraphNeighborsRequest } from './neighborhood-request.js';
+import { renderGraphNeighborhood } from './neighborhood-renderer.js';
+import { selectDiagnostics } from './diagnostics.js';
+export const GRAPH_NEIGHBORHOOD_VERSION = 'exact-neighborhood-v1';
+function pageOffset(token, binding, length, pageSize) {
+    if (token === undefined)
+        return 0;
+    let value;
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(token))
+            throw new Error();
+        value = JSON.parse(Buffer.from(token, 'base64url').toString('utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value) ||
+            Object.keys(value).sort().join(',') !== 'binding,offset,version')
+            throw new Error();
+    }
+    catch {
+        throw new Error('Invalid graph.neighbors continuation');
+    }
+    if (value.version !== GRAPH_NEIGHBORHOOD_VERSION || value.binding !== binding) {
+        throw new Error('Continuation does not match this snapshot, node, filters or page size; restart graph.neighbors');
+    }
+    if (!Number.isSafeInteger(value.offset) || Number(value.offset) < 1 || Number(value.offset) >= length ||
+        Number(value.offset) % pageSize !== 0)
+        throw new Error('Invalid graph.neighbors continuation offset');
+    return Number(value.offset);
+}
+function opposite(fact, nodeId) {
+    return fact.subject.id === nodeId ? fact.object.id : fact.subject.id;
+}
+/** One-hop, exact-ID exploration over the same lossless RDF projection as impact.scan. */
+export class SnapshotGraphExplorationService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async neighbors(input) {
+        const request = parseGraphNeighborsRequest(input);
+        const saved = await this.store.read(request.snapshotId);
+        if (!saved)
+            throw new Error('No graph snapshot is available for that identifier');
+        if (saved.manifest.snapshotId !== request.snapshotId)
+            throw new Error('Saved snapshot identity does not match the requested identifier');
+        const all = await new RdfEvidenceGraph(saved).facts();
+        const adjacency = new Map();
+        const factIds = new Set();
+        for (const fact of all) {
+            if (factIds.has(fact.id))
+                throw new Error('Duplicate fact identities prevent stable graph.neighbors pagination');
+            factIds.add(fact.id);
+            for (const nodeId of new Set([fact.subject.id, fact.object.id])) {
+                const adjacent = adjacency.get(nodeId) ?? [];
+                adjacent.push(fact);
+                adjacency.set(nodeId, adjacent);
+            }
+        }
+        const incident = adjacency.get(request.nodeId) ?? [];
+        const selected = incident.filter(fact => (request.direction === 'both' || (request.direction === 'outgoing' ? fact.subject.id : fact.object.id) === request.nodeId) &&
+            (!request.predicates.length || request.predicates.includes(fact.predicate)))
+            .sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+        const { continuation: _continuation, ...query } = request;
+        // Bind to actual projected facts too: even a corrupt store reusing a manifest digest
+        // must not silently turn a saved continuation into a different neighborhood/frontier.
+        const binding = sha256(stableJson({ version: GRAPH_NEIGHBORHOOD_VERSION, query, manifest: saved.manifest,
+            facts: all, diagnostics: saved.diagnostics, unresolved: saved.unresolved }));
+        const offset = pageOffset(request.continuation, binding, selected.length, request.maxFacts);
+        const facts = selected.slice(offset, offset + request.maxFacts);
+        const end = offset + facts.length;
+        const next = end < selected.length ? Buffer.from(JSON.stringify({
+            version: GRAPH_NEIGHBORHOOD_VERSION, binding, offset: end,
+        })).toString('base64url') : undefined;
+        const neighborIds = (items) => new Set(items.map(fact => opposite(fact, request.nodeId))
+            .filter(id => id !== request.nodeId));
+        const totalNeighbors = neighborIds(selected).size;
+        const neighbors = [...neighborIds(facts)].sort().map(nodeId => ({
+            nodeId,
+            factIds: facts.filter(fact => opposite(fact, request.nodeId) === nodeId).map(fact => fact.id),
+            otherIncidentFacts: adjacency.get(nodeId).filter(fact => fact.subject.id !== request.nodeId && fact.object.id !== request.nodeId).length,
+        }));
+        const manifest = saved.manifest;
+        const plain = {
+            snapshot: snapshotContext(manifest),
+            focus: { nodeId: request.nodeId, status: incident.length ? 'present' : 'absent-from-snapshot' },
+            facts,
+            coverage: coverageForFacts(facts, saved),
+            diagnostics: selectDiagnostics(saved, {}, facts, [], [], new Set([request.nodeId, ...facts.flatMap(fact => [fact.subject.id, fact.object.id])])),
+            selection: { version: GRAPH_NEIGHBORHOOD_VERSION, direction: request.direction, predicates: request.predicates,
+                maxFacts: request.maxFacts, incidentFacts: incident.length, matchingFacts: selected.length,
+                filteredFacts: incident.length - selected.length, offset, returnedFacts: facts.length,
+                remainingFacts: selected.length - end, truncated: Boolean(next), ...(next ? { continuation: next } : {}) },
+            frontier: { scope: 'selected-one-hop-neighborhood', totalNeighbors,
+                remainingNeighbors: totalNeighbors - neighborIds(selected.slice(0, end)).size, neighbors },
+        };
+        return { ...plain, markdown: renderGraphNeighborhood(plain) };
+    }
+}

package/dist/graph/obligation-rdf.d.ts

@@ -0,0 +1,5 @@
+import { type Store, type NamedNode } from 'n3';
+import { type GraphFact } from '@weftlet/core';
+export declare function addObligationEvidence(dataset: Store, record: NamedNode, fact: GraphFact): void;
+/** Structural integrity only: declarations cannot prove fulfillment, compatibility or runtime delivery. */
+export declare function obligationEvidenceIssues(fact: GraphFact, repositoryId: string): readonly string[];

package/dist/graph/obligation-rdf.js

@@ -0,0 +1,67 @@
+import { DataFactory } from 'n3';
+import { obligationContractNode, parseObligationDeclaration, repositoryFileNode } from '@weftlet/core';
+import { CG, RDF, XSD } from './shacl-shapes.js';
+const { namedNode: iri, literal } = DataFactory;
+export function addObligationEvidence(dataset, record, fact) {
+    const evidence = fact.contractObligation;
+    if (!evidence && fact.extractor.id !== 'document-obligation-extractor')
+        return;
+    dataset.addQuad(record, iri(RDF + 'type'), iri(CG + 'ContractObligation'));
+    if (!evidence)
+        return;
+    const prop = (node, key, value, datatype = 'string') => {
+        if (value !== undefined)
+            dataset.addQuad(node, iri(CG + key), literal(String(value), iri(XSD + datatype)));
+    };
+    const item = evidence.declaration ?? {};
+    const contract = item.contract, constraint = item.constraint;
+    prop(record, 'obligationVersion', item.schemaVersion, 'integer');
+    for (const [key, value] of Object.entries({ obligationMethod: evidence.method, obligationRepository: evidence.repositoryId,
+        obligationId: item.id, obligationRole: item.role, obligationStatement: item.statement,
+        obligationScope: contract?.scope, obligationContract: contract?.id, obligationTransport: contract?.kind,
+        obligationContractVersion: contract?.version, obligationDomain: item.domain, obligationStage: item.stage,
+        obligationRevalidation: item.revalidation, obligationMetric: constraint?.metric,
+        obligationOperator: constraint?.operator, obligationUnit: constraint?.unit }))
+        prop(record, key, value);
+    prop(record, 'obligationValue', constraint?.value, 'double');
+    if (evidence.endpointSource) {
+        const endpoint = iri(`${record.value}:obligation-endpoint`);
+        dataset.addQuad(record, iri(CG + 'obligationEndpoint'), endpoint);
+        dataset.addQuad(endpoint, iri(RDF + 'type'), iri(CG + 'ObligationEndpoint'));
+        for (const [key, value] of Object.entries(evidence.endpointSource))
+            prop(endpoint, key, value, typeof value === 'number' ? 'integer' : 'string');
+    }
+}
+function identityMatches(fact, declaration, repositoryId) {
+    const expected = repositoryFileNode(declaration.endpoint);
+    return fact.contractObligation.repositoryId === repositoryId &&
+        fact.object.id === obligationContractNode(repositoryId, declaration.contract).id && fact.object.kind === 'Contract' &&
+        fact.subject.id === expected.id && fact.subject.kind === expected.kind &&
+        fact.predicate === (declaration.role === 'guarantee' ? 'emits' : 'consumes');
+}
+/** Structural integrity only: declarations cannot prove fulfillment, compatibility or runtime delivery. */
+export function obligationEvidenceIssues(fact, repositoryId) {
+    const evidence = fact.contractObligation;
+    if (!evidence)
+        return fact.extractor.id === 'document-obligation-extractor' ? ['Obligation extraction requires declaration metadata'] : [];
+    let declaration;
+    try {
+        declaration = parseObligationDeclaration(evidence.declaration);
+    }
+    catch {
+        return ['Malformed obligation declaration'];
+    }
+    const issues = [], endpoint = evidence.endpointSource;
+    if (!identityMatches(fact, declaration, repositoryId))
+        issues.push('Obligation role or scoped contract/endpoint identity does not match its declaration');
+    if (!endpoint || endpoint.path !== declaration.endpoint || endpoint.commitSha !== fact.provenance.commitSha ||
+        endpoint.endLine < endpoint.startLine)
+        issues.push('Obligation endpoint citation does not match its declared file/revision');
+    if (fact.codeBinding || fact.codeCall || fact.codeOccurrence)
+        issues.push('Obligation declarations must remain separate from implementation evidence');
+    if (fact.sourceRole === 'validation')
+        issues.push('Validation evidence cannot declare product obligations');
+    if (fact.authority === 'draft' && fact.sourceAuthority !== 'draft')
+        issues.push('Draft obligations require draft source authority');
+    return issues;
+}

package/dist/graph/obligation-shapes.d.ts

@@ -0,0 +1,2 @@
+/** Shapes target only obligation records, keeping ordinary-fact validation cost unchanged. */
+export declare const obligationShapes = "\ncg:ContractObligationShape a sh:NodeShape; sh:targetClass cg:ContractObligation;\n sh:property [ sh:path cg:obligationVersion; sh:minCount 1; sh:maxCount 1; sh:hasValue 1 ];\n sh:property [ sh:path cg:obligationMethod; sh:minCount 1; sh:maxCount 1; sh:hasValue \"explicit-markdown\" ];\n sh:property [ sh:path cg:obligationRole; sh:minCount 1; sh:maxCount 1; sh:in (\"guarantee\" \"requirement\") ];\n sh:property [ sh:path cg:obligationId; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationStatement; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationRepository; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationScope; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationContract; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationTransport; sh:minCount 1; sh:maxCount 1; sh:in (\"queue\" \"stored-data\") ];\n sh:property [ sh:path cg:obligationContractVersion; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationDomain; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationStage; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationRevalidation; sh:maxCount 1; sh:in (\"required\" \"not-required\") ];\n sh:property [ sh:path cg:obligationEndpoint; sh:minCount 1; sh:maxCount 1; sh:class cg:ObligationEndpoint ];\n sh:property [ sh:path cg:authority; sh:in (\"inferred\" \"draft\") ];\n sh:property [ sh:path cg:extractionReview; sh:minCount 1; sh:hasValue \"deterministic\" ];\n sh:property [ sh:path rdf:predicate; sh:in (cg:emits cg:consumes) ].\ncg:ObligationEndpointShape a sh:NodeShape; sh:targetClass cg:ObligationEndpoint;\n sh:property [ sh:path cg:path; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:digest; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:commitSha; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:startLine; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ];\n sh:property [ sh:path cg:endLine; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ].\ncg:ObligationConstraintShape a sh:NodeShape; sh:targetSubjectsOf cg:obligationMetric, cg:obligationOperator, cg:obligationValue, cg:obligationUnit;\n sh:property [ sh:path cg:obligationMetric; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationOperator; sh:minCount 1; sh:maxCount 1; sh:in (\"at-most\" \"at-least\" \"equal\") ];\n sh:property [ sh:path cg:obligationValue; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:double ];\n sh:property [ sh:path cg:obligationUnit; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ].\n";

package/dist/graph/obligation-shapes.js

@@ -0,0 +1,32 @@
+/** Shapes target only obligation records, keeping ordinary-fact validation cost unchanged. */
+export const obligationShapes = `
+cg:ContractObligationShape a sh:NodeShape; sh:targetClass cg:ContractObligation;
+ sh:property [ sh:path cg:obligationVersion; sh:minCount 1; sh:maxCount 1; sh:hasValue 1 ];
+ sh:property [ sh:path cg:obligationMethod; sh:minCount 1; sh:maxCount 1; sh:hasValue "explicit-markdown" ];
+ sh:property [ sh:path cg:obligationRole; sh:minCount 1; sh:maxCount 1; sh:in ("guarantee" "requirement") ];
+ sh:property [ sh:path cg:obligationId; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationStatement; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationRepository; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationScope; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationContract; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationTransport; sh:minCount 1; sh:maxCount 1; sh:in ("queue" "stored-data") ];
+ sh:property [ sh:path cg:obligationContractVersion; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationDomain; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationStage; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationRevalidation; sh:maxCount 1; sh:in ("required" "not-required") ];
+ sh:property [ sh:path cg:obligationEndpoint; sh:minCount 1; sh:maxCount 1; sh:class cg:ObligationEndpoint ];
+ sh:property [ sh:path cg:authority; sh:in ("inferred" "draft") ];
+ sh:property [ sh:path cg:extractionReview; sh:minCount 1; sh:hasValue "deterministic" ];
+ sh:property [ sh:path rdf:predicate; sh:in (cg:emits cg:consumes) ].
+cg:ObligationEndpointShape a sh:NodeShape; sh:targetClass cg:ObligationEndpoint;
+ sh:property [ sh:path cg:path; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:digest; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:commitSha; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:startLine; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ];
+ sh:property [ sh:path cg:endLine; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ].
+cg:ObligationConstraintShape a sh:NodeShape; sh:targetSubjectsOf cg:obligationMetric, cg:obligationOperator, cg:obligationValue, cg:obligationUnit;
+ sh:property [ sh:path cg:obligationMetric; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationOperator; sh:minCount 1; sh:maxCount 1; sh:in ("at-most" "at-least" "equal") ];
+ sh:property [ sh:path cg:obligationValue; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:double ];
+ sh:property [ sh:path cg:obligationUnit; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ].
+`;

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

@@ -0,0 +1,11 @@
+export declare function parseGraphPathsRequest(value: unknown): {
+    continuation?: string | undefined;
+    snapshotId: string;
+    fromNodeId: string;
+    toNodeId: string;
+    direction: "incoming" | "outgoing" | "both";
+    predicates: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+    maxDepth: number;
+    maxPaths: number;
+    maxSteps: number;
+};

package/dist/graph/path-request.js

@@ -0,0 +1,24 @@
+import { parseGraphNeighborsRequest } from './neighborhood-request.js';
+const fields = new Set(['snapshotId', 'fromNodeId', 'toNodeId', 'direction', 'predicates', 'maxDepth', 'maxPaths', 'maxSteps', 'continuation']);
+export function parseGraphPathsRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('graph.paths arguments must be an object');
+    const record = value;
+    if (Object.keys(record).some(key => !fields.has(key)))
+        throw new Error('Unknown graph.paths field');
+    const common = { snapshotId: record.snapshotId, direction: record.direction === undefined ? 'outgoing' : record.direction,
+        predicates: record.predicates, continuation: record.continuation };
+    const from = parseGraphNeighborsRequest({ ...common, nodeId: record.fromNodeId });
+    const to = parseGraphNeighborsRequest({ ...common, nodeId: record.toNodeId });
+    const bound = (name, fallback, maximum) => {
+        const item = record[name] === undefined ? fallback : record[name];
+        if (!Number.isInteger(item) || Number(item) < 1 || Number(item) > maximum) {
+            throw new Error(`${name} must be an integer between 1 and ${maximum}`);
+        }
+        return Number(item);
+    };
+    return { snapshotId: from.snapshotId, fromNodeId: from.nodeId, toNodeId: to.nodeId,
+        direction: from.direction, predicates: from.predicates, maxDepth: bound('maxDepth', 8, 32),
+        maxPaths: bound('maxPaths', 5, 20), maxSteps: bound('maxSteps', 1000, 10_000),
+        ...(from.continuation ? { continuation: from.continuation } : {}) };
+}

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

@@ -0,0 +1,45 @@
+import type { EvidencePath } from '@weftlet/core';
+export interface PathEdge {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string;
+}
+export interface PathSearchOptions {
+    readonly maxDepth: number;
+    readonly maxPaths: number;
+    readonly maxSteps: number;
+    readonly offset?: number;
+}
+/** Pure, dependency-free search shared verbatim with the offline viewer. No global visited set:
+ * distinct simple paths and parallel assertions survive; cycles do not repeat a node. */
+export declare function searchEvidencePaths(edges: readonly PathEdge[], start: string, target: string, options: PathSearchOptions, knownNodeIds?: ReadonlySet<string>): {
+    paths: EvidencePath[];
+    frontier: {
+        pending: {
+            nodeId: string;
+            viaFactIds: string[];
+            nextFactId: string;
+            remainingCandidates: number;
+        }[];
+        depthLimited: {
+            count: number;
+            examples: {
+                readonly nodeId: string;
+                readonly viaFactIds: readonly string[];
+                readonly nextFactId: string;
+                readonly nextNodeId: string;
+            }[];
+            omitted: number;
+        };
+    };
+    search: {
+        searchLimit: number;
+        replayedSteps: number;
+        examinedSteps: number;
+        totalSteps: number;
+        stopReason: "exhausted" | "search-limit" | "path-page-limit" | "work-page-limit";
+        exhaustedWithinDepth: boolean;
+        depthLimitReached: boolean;
+        truncated: boolean;
+    };
+};

package/dist/graph/path-search.js

@@ -0,0 +1,101 @@
+/** Pure, dependency-free search shared verbatim with the offline viewer. No global visited set:
+ * distinct simple paths and parallel assertions survive; cycles do not repeat a node. */
+export function searchEvidencePaths(edges, start, target, options, knownNodeIds) {
+    const searchLimit = 100_000;
+    const offset = options.offset ?? 0;
+    const validateBounds = () => {
+        for (const [value, maximum] of [[options.maxDepth, 32], [options.maxPaths, 20], [options.maxSteps, 10_000]]) {
+            if (!Number.isInteger(value) || value < 1 || value > maximum)
+                throw new Error('Invalid path search bound');
+        }
+        if (!Number.isInteger(offset) || offset < 0 || offset >= searchLimit)
+            throw new Error('Invalid path continuation offset');
+    };
+    validateBounds();
+    const adjacency = new Map();
+    const nodeIds = new Set();
+    for (const edge of [...edges].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0)) {
+        const entries = adjacency.get(edge.from) ?? [];
+        entries.push(edge);
+        adjacency.set(edge.from, entries);
+        nodeIds.add(edge.from);
+        nodeIds.add(edge.to);
+    }
+    const paths = [];
+    const stack = nodeIds.has(start) && nodeIds.has(target) && start !== target ? [{ nodeId: start, next: 0 }] : [];
+    const depthExamples = [];
+    let depthCount = 0;
+    let totalSteps = 0;
+    const trim = () => {
+        while (stack.length && stack.at(-1).next >= (adjacency.get(stack.at(-1).nodeId)?.length ?? 0))
+            stack.pop();
+    };
+    const step = () => {
+        const frame = stack.at(-1);
+        const edge = adjacency.get(frame.nodeId)[frame.next++];
+        totalSteps++;
+        if (stack.some(item => item.nodeId === edge.to))
+            return;
+        const viaFactIds = stack.slice(1).map(item => item.via);
+        if (viaFactIds.length === options.maxDepth) {
+            depthCount++;
+            if (depthExamples.length < 20)
+                depthExamples.push({ nodeId: frame.nodeId, viaFactIds,
+                    nextFactId: edge.id, nextNodeId: edge.to });
+        }
+        else if (edge.to === target) {
+            return { nodeIds: [...stack.map(item => item.nodeId), target], factIds: [...viaFactIds, edge.id] };
+        }
+        else {
+            stack.push({ nodeId: edge.to, next: 0, via: edge.id });
+        }
+    };
+    trim();
+    // Reconstruct only bounded search state. Never accept a caller-supplied stack or facts.
+    const replay = () => {
+        let replayPageSteps = 0;
+        let replayPagePaths = 0;
+        while (totalSteps < offset && stack.length) {
+            if (step())
+                replayPagePaths++;
+            replayPageSteps++;
+            if (replayPagePaths === options.maxPaths || replayPageSteps === options.maxSteps) {
+                replayPagePaths = 0;
+                replayPageSteps = 0;
+            }
+            trim();
+        }
+        if (totalSteps !== offset || (offset && (!stack.length || replayPagePaths || replayPageSteps))) {
+            throw new Error('Invalid path continuation boundary');
+        }
+    };
+    replay();
+    if (!offset && start === target && (nodeIds.has(start) || knownNodeIds?.has(start)))
+        paths.push({ nodeIds: [start], factIds: [] });
+    while (stack.length && paths.length < options.maxPaths && totalSteps - offset < options.maxSteps && totalSteps < searchLimit) {
+        const path = step();
+        if (path)
+            paths.push(path);
+        trim();
+    }
+    const pending = stack.flatMap((frame, index) => {
+        const entries = adjacency.get(frame.nodeId) ?? [];
+        return frame.next < entries.length ? [{ nodeId: frame.nodeId,
+                viaFactIds: stack.slice(1, index + 1).map(item => item.via), nextFactId: entries[frame.next].id,
+                remainingCandidates: entries.length - frame.next }] : [];
+    });
+    const exhaustedWithinDepth = stack.length === 0;
+    const stopReason = () => {
+        if (exhaustedWithinDepth)
+            return 'exhausted';
+        if (totalSteps === searchLimit)
+            return 'search-limit';
+        if (paths.length === options.maxPaths)
+            return 'path-page-limit';
+        return 'work-page-limit';
+    };
+    return { paths, frontier: { pending, depthLimited: { count: depthCount, examples: depthExamples,
+                omitted: depthCount - depthExamples.length } }, search: { searchLimit, replayedSteps: offset,
+            examinedSteps: totalSteps - offset, totalSteps, stopReason: stopReason(), exhaustedWithinDepth,
+            depthLimitReached: depthCount > 0, truncated: !exhaustedWithinDepth || depthCount > 0 } };
+}

package/dist/graph/paths-renderer.d.ts

@@ -0,0 +1,2 @@
+import type { GraphPaths } from '@weftlet/core';
+export declare function renderGraphPaths(result: Omit<GraphPaths, 'markdown'>): string;

package/dist/graph/paths-renderer.js

@@ -0,0 +1,36 @@
+import { factEvidenceDescription } from './evidence-description.js';
+import { sourceLocation } from '@weftlet/core';
+import { contextPackEvidenceAuthority } from './authority.js';
+import { coverageDescription } from './coverage.js';
+import { diagnosticSummary } from './diagnostics.js';
+import { documentSelectionDescription } from './document-role-description.js';
+const quoted = (value) => JSON.stringify(value).replace(/[\\`*_{}\[\]()<>!|]/g, '\\$&');
+export function renderGraphPaths(result) {
+    const { snapshot, endpoints, search, frontier, evidenceState } = result;
+    return [
+        '# Cited evidence paths',
+        `Snapshot: ${quoted(snapshot.snapshotId)} (${snapshot.commitSha}); configuration: ${snapshot.configurationDigest ?? 'unknown'}`,
+        `Scope: ${snapshot.scope?.map(quoted).join(', ') ?? 'unknown'}`,
+        documentSelectionDescription(snapshot.documentSelection),
+        `From ${quoted(endpoints.from.nodeId)} (${endpoints.from.status}) to ${quoted(endpoints.to.nodeId)} (${endpoints.to.status})`,
+        `Direction: ${search.direction}; predicates: ${search.predicates.join(', ') || 'all'}; order: ${search.order}`,
+        `Depth: ${search.maxDepth}; paths on page: ${result.paths.length}/${search.maxPaths}; stop: ${search.stopReason}; truncated: ${search.truncated}`,
+        `Candidate steps: ${search.examinedSteps} new + ${search.replayedSteps} replay; ${search.totalSteps}/${search.searchLimit} total ceiling.`,
+        `Unexamined prefixes: ${frontier.pending.length}; depth-limited extensions: ${frontier.depthLimited.count} (${frontier.depthLimited.omitted} examples omitted).`,
+        ...(search.continuation ? [`Continuation (same request): ${search.continuation}`] : []),
+        ...(search.depthLimitReached ? ['Depth limit reached: restart with a larger maxDepth or explore a frontier node. Continuation does not lift the depth bound.'] : []),
+        ...(search.stopReason === 'search-limit' ? ['Total search limit reached: narrow the relations or explore an intermediate node; no further continuation is available.'] : []),
+        ...(evidenceState ? [`Stale: ${evidenceState.stale}; configuration matches: ${evidenceState.configurationMatches}; extraction compatible: ${evidenceState.extractionCompatible ?? 'unknown'}; overlay freshness: ${evidenceState.overlayFreshness ?? 'not an overlay'}`,
+            `Excluded working changes: ${evidenceState.excludedWorkingChanges.map(quoted).join(', ') || '(none)'}`] : []),
+        'Paths are cited associations, not proof of causality, business compatibility or current-diff validation. A completed search covers only the selected saved facts and depth; absence is not proof of no product dependency.',
+        coverageDescription(result.coverage), ...result.coverage.gaps.map(quoted),
+        '', '## Paths',
+        ...result.paths.map((path, index) => `${index + 1}. ${path.nodeIds.map(quoted).join(' → ')}; facts: ${path.factIds.map(quoted).join(', ') || '(zero-length identity path)'}`),
+        '', '## Supporting assertions',
+        ...result.facts.map(fact => `- ${quoted(fact.id)} [${contextPackEvidenceAuthority(fact)}] ${quoted(fact.subject.id)} —${fact.predicate}→ ${quoted(fact.object.id)} (${quoted(sourceLocation(fact.provenance))}–${fact.provenance.endLine}${fact.provenance.endColumn === undefined ? '' : `:${fact.provenance.endColumn}`}; confidence ${fact.confidence}; source ${fact.sourceAuthority ?? 'unspecified'}; extraction ${fact.extractionReview ?? 'unspecified'}${factEvidenceDescription(fact) ? `; ${factEvidenceDescription(fact)}` : ''})`),
+        '', '## Unexplored frontier',
+        ...frontier.pending.map(item => `- ${quoted(item.nodeId)} via ${item.viaFactIds.map(quoted).join(', ') || '(start)'}: ${item.remainingCandidates} candidates; next ${quoted(item.nextFactId)}`),
+        ...frontier.depthLimited.examples.map(item => `- Depth boundary: ${quoted(item.nodeId)} → ${quoted(item.nextNodeId)} via ${quoted(item.nextFactId)}`),
+        '', '## Scoped diagnostics', ...diagnosticSummary(result).map(quoted),
+    ].filter(line => line !== undefined).join('\n');
+}

package/dist/graph/paths.d.ts

@@ -0,0 +1,7 @@
+import type { GraphPathQueryService, GraphPaths, GraphPathsRequest, SnapshotStore } from '@weftlet/core';
+export declare const GRAPH_PATHS_VERSION = "simple-evidence-paths-v1";
+export declare class SnapshotGraphPathService implements GraphPathQueryService {
+    private readonly store;
+    constructor(store: Pick<SnapshotStore, 'read'>);
+    paths(input: GraphPathsRequest): Promise<GraphPaths>;
+}

package/dist/graph/paths.js

@@ -0,0 +1,74 @@
+import { snapshotContext } from './snapshot-context.js';
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { RdfEvidenceGraph } from './rdf.js';
+import { coverageForFacts } from './coverage.js';
+import { selectDiagnostics } from './diagnostics.js';
+import { parseGraphPathsRequest } from './path-request.js';
+import { searchEvidencePaths } from './path-search.js';
+import { renderGraphPaths } from './paths-renderer.js';
+export const GRAPH_PATHS_VERSION = 'simple-evidence-paths-v1';
+function continuationOffset(token, binding) {
+    if (!token)
+        return 0;
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(token))
+            throw new Error();
+        const value = JSON.parse(Buffer.from(token, 'base64url').toString('utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value) ||
+            Object.keys(value).sort().join(',') !== 'binding,offset,version' ||
+            value.version !== GRAPH_PATHS_VERSION || value.binding !== binding ||
+            !Number.isInteger(value.offset) || value.offset < 1 || value.offset >= 100_000)
+            throw new Error();
+        return value.offset;
+    }
+    catch {
+        throw new Error('Invalid graph.paths continuation or query/snapshot mismatch; restart graph.paths');
+    }
+}
+export class SnapshotGraphPathService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async paths(input) {
+        const request = parseGraphPathsRequest(input);
+        const saved = await this.store.read(request.snapshotId);
+        if (!saved)
+            throw new Error('No graph snapshot is available for that identifier');
+        if (saved.manifest.snapshotId !== request.snapshotId)
+            throw new Error('Saved snapshot identity does not match the requested identifier');
+        const all = await new RdfEvidenceGraph(saved).facts();
+        if (new Set(all.map(fact => fact.id)).size !== all.length)
+            throw new Error('Duplicate fact identities prevent stable graph.paths pagination');
+        const { continuation, ...query } = request;
+        const binding = sha256(stableJson({ version: GRAPH_PATHS_VERSION, query, manifest: saved.manifest,
+            facts: all, diagnostics: saved.diagnostics, unresolved: saved.unresolved }));
+        const offset = continuationOffset(continuation, binding);
+        const selected = all.filter(fact => !request.predicates.length || request.predicates.includes(fact.predicate));
+        const edges = selected.flatMap(fact => {
+            const forward = { id: fact.id, from: fact.subject.id, to: fact.object.id };
+            const reverse = { id: fact.id, from: fact.object.id, to: fact.subject.id };
+            return request.direction === 'incoming' ? [reverse] : request.direction === 'outgoing' || forward.from === forward.to
+                ? [forward] : [forward, reverse];
+        });
+        const nodes = new Set(all.flatMap(fact => [fact.subject.id, fact.object.id]));
+        const result = searchEvidencePaths(edges, request.fromNodeId, request.toNodeId, { ...request, offset }, nodes);
+        const factIds = new Set(result.paths.flatMap(path => path.factIds));
+        const facts = all.filter(fact => factIds.has(fact.id));
+        const endpoint = (nodeId) => ({ nodeId, status: nodes.has(nodeId) ? 'present' : 'absent-from-snapshot' });
+        const next = !result.search.exhaustedWithinDepth && result.search.stopReason !== 'search-limit'
+            ? Buffer.from(JSON.stringify({ version: GRAPH_PATHS_VERSION, binding, offset: result.search.totalSteps })).toString('base64url') : undefined;
+        const manifest = saved.manifest;
+        const plain = {
+            snapshot: snapshotContext(manifest),
+            endpoints: { from: endpoint(request.fromNodeId), to: endpoint(request.toNodeId) },
+            paths: result.paths, facts, coverage: coverageForFacts(facts, saved),
+            diagnostics: selectDiagnostics(saved, {}, facts, [], [], new Set([request.fromNodeId, request.toNodeId,
+                ...facts.flatMap(fact => [fact.subject.id, fact.object.id])])),
+            search: { version: GRAPH_PATHS_VERSION, order: 'fact-id-depth-first', direction: request.direction,
+                predicates: request.predicates, maxDepth: request.maxDepth, maxPaths: request.maxPaths, maxSteps: request.maxSteps,
+                ...result.search, ...(next ? { continuation: next } : {}) }, frontier: result.frontier,
+        };
+        return { ...plain, markdown: renderGraphPaths(plain) };
+    }
+}

package/dist/graph/query.js

@@ -1,4 +1,7 @@
 // Modified for standalone extraction; see docs/extraction-manifest.json.
+import { unexpandedCodeDescription } from './code-description.js';
+import { factEvidenceDescription } from './evidence-description.js';
+import { sourceLocation } from '@weftlet/core';
 import { contextPackEvidenceAuthority } from "./authority.js";
 import { RdfEvidenceGraph } from "./rdf.js";
 import { sha256, stableJson } from "../infrastructure/util.js";
@@ -61,7 +64,8 @@ function markdownFactDetails(fact) {
     const document = sourceDocumentDescription(fact)?.replace(/[\\`*_{}\[\]()<>!|]/g, '\\$&').replace(/[\r\n]/g, ' ');
     return `confidence ${fact.confidence}` +
         (fact.sourceAuthority ? `; source ${fact.sourceAuthority}; extraction ${fact.extractionReview ?? 'unknown'}` : '') +
-        (document ? `; ${document}` : '');
+        (document ? `; ${document}` : '') +
+        (factEvidenceDescription(fact) ? `; ${factEvidenceDescription(fact)}` : '');
 }
 export class MarkdownContextPackRenderer {
     render(pack) {
@@ -106,7 +110,7 @@ export class MarkdownContextPackRenderer {
                 ...pack.facts
                     .filter((fact) => contextPackLaneForFact(fact) === lane)
                     .map((fact) => `- [${contextPackEvidenceAuthority(fact)}] ${fact.subject.label} —${fact.predicate}→ ${fact.object.label} ` +
-                    `(\`${fact.provenance.path}:${fact.provenance.startLine}\`, ${markdownFactDetails(fact)})`),
+                    `(\`${sourceLocation(fact.provenance)}\`, ${markdownFactDetails(fact)})`),
             ]),
             '',
             '## Runtime evidence',
@@ -122,6 +126,7 @@ export class MarkdownContextPackRenderer {
             '## Suggested files',
             ...pack.suggestedFiles.map((path) => `- \`${path}\``),
             '',
+            ...unexpandedCodeDescription(pack.exploration),
             '## Scoped diagnostics',
             ...diagnosticSummary(pack).map((item) => `- ${item}`),
         ];
@@ -165,8 +170,16 @@ export class SnapshotImpactQueryService {
         const directTerms = anchorTerms.length > 0 ? anchorTerms : focus;
         const direct = snapshot.facts.filter((fact) => this.matches(fact, directTerms));
         const ranked = new Map(direct.map((fact) => [fact.id, fact]));
+        const unexpandedCodeTargets = new Set();
+        const expand = (node) => {
+            if (node.kind === 'CodeSymbol' && node.codeSymbol?.resolution === 'no-indexed-definition') {
+                unexpandedCodeTargets.add(node.id);
+                return false;
+            }
+            return node.kind !== 'Project';
+        };
         let frontier = new Set(direct.flatMap((fact) => [fact.subject, fact.object]
-            .filter((node) => node.kind !== 'Project')
+            .filter(expand)
             .map((node) => node.id)));
         const visitedNodes = new Set(frontier);
         for (let depth = 0; depth < maxDepth && frontier.size > 0; depth += 1) {
@@ -176,7 +189,7 @@ export class SnapshotImpactQueryService {
                     continue;
                 ranked.set(fact.id, fact);
                 for (const node of [fact.subject, fact.object]) {
-                    if (node.kind !== 'Project' && !visitedNodes.has(node.id))
+                    if (expand(node) && !visitedNodes.has(node.id))
                         next.add(node.id);
                 }
             }
@@ -196,7 +209,7 @@ export class SnapshotImpactQueryService {
             ...tier.filter((fact) => contextPackLaneForFact(fact) === undefined),
         ]);
         const { continuation: _continuation, snapshotId: _snapshotId, ...query } = request;
-        const queryDigest = sha256(stableJson({ ranking: IMPACT_RANKING_VERSION, query }));
+        const queryDigest = sha256(stableJson({ ranking: IMPACT_RANKING_VERSION, codeTraversal: 'indexed-symbols-v1', query }));
         let offset = 0;
         if (request.continuation) {
             if (request.continuation.length > 2048)
@@ -215,7 +228,7 @@ export class SnapshotImpactQueryService {
             offset = token.offset;
         }
         const facts = allBalanced.slice(offset, offset + maxFacts);
-        const coverage = coverageForFacts(facts);
+        const coverage = coverageForFacts(facts, snapshot);
         const nextOffset = offset + facts.length;
         const continuation = nextOffset < allBalanced.length ? Buffer.from(JSON.stringify({
             snapshot: snapshot.manifest.snapshotId, digest: snapshot.manifest.contentDigest,
@@ -306,6 +319,10 @@ export class SnapshotImpactQueryService {
             diagnostics: selectDiagnostics(snapshot, request, facts, focus, queryDiagnostics),
             exploration: {
                 rankingVersion: IMPACT_RANKING_VERSION,
+                codeTraversalVersion: 'indexed-symbols-v1',
+                unexpandedCodeTargets: [...unexpandedCodeTargets].sort().slice(0, 100),
+                unexpandedCodeTargetCount: unexpandedCodeTargets.size,
+                unexpandedCodeTargetsTruncated: unexpandedCodeTargets.size > 100,
                 returned: facts.length, reachableFacts: allBalanced.length, maxDepth,
                 depthLimitReached: frontier.size > 0, truncated: Boolean(continuation) || frontier.size > 0,
                 continuation,