@weftlet/toolkit 0.6.1 → 0.7.0

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,

package/dist/graph/rdf.js

@@ -6,6 +6,10 @@ import { stableJson } from "../infrastructure/util.js";
 import { createRequire } from 'node:module';
 import { CG, RDF, XSD, evidenceShapes } from './shacl-shapes.js';
 import { measureValidationPhase } from './validation-progress.js';
+import { addBindingEvidence, bindingEvidenceIssues } from './binding-rdf.js';
+import { addCallEvidence, callEvidenceIssues } from './call-rdf.js';
+import { addObligationEvidence, obligationEvidenceIssues } from './obligation-rdf.js';
+import { addCodeEvidence, codeEvidenceIssues, invalidCodeRange } from './code-rdf.js';
 const { namedNode: iri, literal } = DataFactory;
 export { CG } from './shacl-shapes.js';
 export const nodeIri = (id) => `urn:context-graph:node:${encodeURIComponent(id)}`;
@@ -53,6 +57,10 @@ export class RdfEvidenceGraph {
                 this.dataset.addQuad(record, iri(CG + p), literal(String(value), iri(XSD + 'integer')));
             }
             this.dataset.addQuad(record, iri(CG + 'confidence'), literal(String(fact.confidence), iri(XSD + 'decimal')));
+            addCodeEvidence(this.dataset, record, fact, nodeIri);
+            addBindingEvidence(this.dataset, record, fact, factIri);
+            addCallEvidence(this.dataset, record, fact, factIri);
+            addObligationEvidence(this.dataset, record, fact);
             for (const node of [fact.subject, fact.object]) {
                 const term = iri(nodeIri(node.id));
                 this.dataset.addQuad(term, iri(RDF + 'type'), iri(CG + 'Node'));
@@ -92,7 +100,25 @@ export class RdfEvidenceGraph {
             path: result.path?.value,
             message: result.message.map((message) => message.value).join('; '),
         }));
+        const byId = new Map(this.snapshot.facts.map(fact => [fact.id, fact]));
         for (const fact of this.snapshot.facts) {
+            for (const message of obligationEvidenceIssues(fact, this.snapshot.manifest.repositoryId))
+                issues.push({ category: 'extraction-gap',
+                    focus: factIri(fact.id), path: CG + 'obligationRole', message });
+            for (const message of callEvidenceIssues(fact, byId))
+                issues.push({ category: 'extraction-gap',
+                    focus: factIri(fact.id), path: CG + 'callTarget', message });
+            for (const message of bindingEvidenceIssues(fact, byId))
+                issues.push({ category: 'extraction-gap',
+                    focus: factIri(fact.id), path: CG + 'bindingDefinition', message });
+            for (const message of codeEvidenceIssues(fact))
+                issues.push({ category: 'extraction-gap',
+                    focus: factIri(fact.id), path: CG + 'codeRole', message });
+            if (invalidCodeRange(fact.provenance) ||
+                (fact.codeOccurrence?.declarationRange && invalidCodeRange(fact.codeOccurrence.declarationRange))) {
+                issues.push({ category: 'extraction-gap', focus: factIri(fact.id), path: CG + 'startColumn',
+                    message: 'Invalid UTF-16 source range' });
+            }
             if (fact.provenance.endLine < fact.provenance.startLine) {
                 issues.push({ category: 'extraction-gap', focus: factIri(fact.id), path: CG + 'endLine',
                     message: 'Citation ends before it starts' });

package/dist/graph/shacl-shapes.js

@@ -1,4 +1,6 @@
 import { Parser } from 'n3';
+import { callShapes } from './call-shapes.js';
+import { obligationShapes } from './obligation-shapes.js';
 export const CG = 'https://context-graph.dev/record#';
 export const RDF = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#';
 export const XSD = 'http://www.w3.org/2001/XMLSchema#';
@@ -8,6 +10,8 @@ export const evidenceShapes = new Parser().parse(`
 @prefix rdf: <${RDF}>.
 @prefix sh: <http://www.w3.org/ns/shacl#>.
 @prefix xsd: <${XSD}>.
+${callShapes}
+${obligationShapes}
 cg:FactShape a sh:NodeShape; sh:targetClass rdf:Statement;
  sh:property [ sh:path cg:record; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string ];
  sh:property [ sh:path rdf:subject; sh:minCount 1; sh:maxCount 1; sh:nodeKind sh:IRI ];
@@ -25,6 +29,72 @@ cg:FactShape a sh:NodeShape; sh:targetClass rdf:Statement;
 cg:NodeShape a sh:NodeShape; sh:targetClass cg:Node;
  sh:property [ sh:path cg:kind; sh:minCount 1; sh:maxCount 1 ].
 
+cg:ColumnsShape a sh:NodeShape;
+ sh:targetSubjectsOf cg:startColumn, cg:endColumn, cg:columnEncoding;
+ sh:property [ sh:path cg:startColumn; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ];
+ sh:property [ sh:path cg:endColumn; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ];
+ sh:property [ sh:path cg:columnEncoding; sh:minCount 1; sh:maxCount 1; sh:in ("utf-16") ].
+cg:CodeRangeShape a sh:NodeShape; sh:targetClass cg:CodeRange;
+ 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 ];
+ sh:property [ sh:path cg:columnEncoding; sh:minCount 1; sh:hasValue "utf-16" ].
+cg:CodeOccurrenceShape a sh:NodeShape; sh:targetClass cg:CodeOccurrence; sh:targetSubjectsOf cg:codeRole;
+ sh:property [ sh:path cg:codeVersion; sh:minCount 1; sh:maxCount 1; sh:hasValue 1 ];
+ sh:property [ sh:path cg:codeRole; sh:minCount 1; sh:maxCount 1; sh:in ("definition" "reference") ];
+ sh:property [ sh:path cg:codeLocationKind; sh:minCount 1; sh:maxCount 1; sh:in ("name" "zero-width-anchor") ];
+ sh:property [ sh:path cg:codeNativeRoles; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:integer; sh:minInclusive 0 ];
+ sh:property [ sh:path cg:columnEncoding; sh:minCount 1; sh:hasValue "utf-16" ];
+ sh:property [ sh:path cg:codeEnclosure; sh:minCount 1; sh:maxCount 1; sh:in ("native-range" "file" "ambiguous") ];
+ sh:property [ sh:path cg:enclosingSymbol; sh:maxCount 1; sh:class cg:CodeSymbol ];
+ sh:property [ sh:path cg:declarationRange; sh:maxCount 1; sh:class cg:CodeRange ];
+ sh:or (
+   [ sh:property [ sh:path cg:codeEnclosure; sh:hasValue "native-range" ]; sh:property [ sh:path cg:enclosingSymbol; sh:minCount 1 ] ]
+   [ sh:property [ sh:path cg:codeEnclosure; sh:in ("file" "ambiguous") ]; sh:property [ sh:path cg:enclosingSymbol; sh:maxCount 0 ] ]
+ );
+ sh:or (
+   [ sh:property [ sh:path cg:codeRole; sh:hasValue "definition" ]; sh:property [ sh:path rdf:subject; sh:class cg:CodeSymbol ]; sh:property [ sh:path rdf:predicate; sh:hasValue cg:definedBy ] ]
+   [ sh:property [ sh:path cg:codeRole; sh:hasValue "reference" ]; sh:property [ sh:path rdf:object; sh:class cg:CodeSymbol ]; sh:property [ sh:path rdf:predicate; sh:hasValue cg:references ] ]
+ ).
+cg:CodeSymbolShape a sh:NodeShape; sh:targetClass cg:CodeSymbol;
+ sh:property [ sh:path cg:kind; sh:hasValue "CodeSymbol" ];
+ sh:property [ sh:path cg:codeVersion; sh:minCount 1; sh:maxCount 1; sh:hasValue 1 ];
+ sh:property [ sh:path cg:codeProvider; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:codeRepository; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:nativeSymbol; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:codeResolution; sh:minCount 1; sh:maxCount 1; sh:in ("indexed-definition" "declaration-only" "no-indexed-definition") ];
+ sh:property [ sh:path cg:codeIdentityScope; sh:minCount 1; sh:maxCount 1; sh:in ("repository" "index-document") ];
+ sh:or (
+   [ sh:property [ sh:path cg:codeIdentityScope; sh:hasValue "repository" ]; sh:property [ sh:path cg:codeDocument; sh:maxCount 0 ]; sh:property [ sh:path cg:codeIndex; sh:maxCount 0 ] ]
+   [ sh:property [ sh:path cg:codeIdentityScope; sh:hasValue "index-document" ];
+     sh:property [ sh:path cg:codeDocument; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+     sh:property [ sh:path cg:codeIndex; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ] ]
+ ).
+
+cg:DocumentCodeBindingShape a sh:NodeShape; sh:targetClass cg:DocumentCodeBinding;
+ sh:property [ sh:path cg:bindingVersion; sh:minCount 1; sh:maxCount 1; sh:hasValue 1 ];
+ sh:property [ sh:path cg:bindingMethod; sh:minCount 1; sh:maxCount 1; sh:hasValue "explicit-markdown" ];
+ sh:property [ sh:path <${CG}bindingSelector/path>; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path <${CG}bindingSelector/symbol>; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:bindingDocument; sh:minCount 1; sh:class cg:BindingCitation ];
+ sh:property [ sh:path cg:bindingSelection; sh:minCount 1; sh:class cg:BindingCitation ];
+ sh:property [ sh:path cg:bindingDefinition; sh:minCount 1; sh:class cg:BindingCitation ];
+ sh:property [ sh:path cg:bindingSubject; sh:class cg:BindingCitation ];
+ sh:property [ sh:path rdf:object; sh:class cg:CodeSymbol ];
+ sh:property [ sh:path rdf:predicate; sh:in (cg:references cg:implementedBy cg:verifiedBy) ];
+ sh:property [ sh:path cg:authority; sh:in ("inferred" "draft") ];
+ sh:property [ sh:path cg:extractionReview; sh:minCount 1; sh:in ("deterministic" "unreviewed") ].
+cg:BindingCitationShape a sh:NodeShape; sh:targetClass cg:BindingCitation;
+ 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 ];
+ sh:property [ sh:path cg:bindingFact; sh:maxCount 1; sh:class rdf:Statement ].
+cg:BindingSelectorPositionShape a sh:NodeShape;
+ sh:targetSubjectsOf <${CG}bindingSelector/line>, <${CG}bindingSelector/column>;
+ sh:property [ sh:path <${CG}bindingSelector/line>; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ];
+ sh:property [ sh:path <${CG}bindingSelector/column>; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ].
+
 # Optional source metadata targets only assertions that carry those predicates.
 # Legacy facts do not acquire additional property or ownership consistency checks.
 cg:SourceRoleShape a sh:NodeShape; sh:targetSubjectsOf cg:sourceRole;

package/dist/graph/snapshot-context.d.ts

@@ -0,0 +1,3 @@
+import type { ContextPack, SnapshotManifest } from '@weftlet/core';
+/** The saved identity/scope carried by exact graph queries; never resolve a new head. */
+export declare function snapshotContext(manifest: SnapshotManifest): ContextPack['snapshot'];

package/dist/graph/snapshot-context.js

@@ -0,0 +1,8 @@
+/** The saved identity/scope carried by exact graph queries; never resolve a new head. */
+export function snapshotContext(manifest) {
+    return { snapshotId: manifest.snapshotId, commitSha: manifest.commitSha, contentDigest: manifest.contentDigest,
+        configurationDigest: manifest.configurationDigest, scope: manifest.scope, baseSha: manifest.baseSha,
+        overlayDigest: manifest.overlayDigest, overlayCapture: manifest.overlayCapture,
+        extractorVersions: manifest.extractorVersions,
+        ...(manifest.documentSelection ? { documentSelection: manifest.documentSelection } : {}) };
+}

package/dist/index.d.ts

@@ -20,3 +20,26 @@ export * from './extraction/document-traversal.js';
 export * from './extraction/document-classification.js';
 export * from './extraction/document-evidence.js';
 export type { DocumentTraversalConfig } from './configuration/document-traversal.js';
+export * from './graph/neighborhood.js';
+export * from './graph/neighborhood-request.js';
+export * from './graph/neighborhood-renderer.js';
+export * from './graph/paths.js';
+export * from './graph/path-request.js';
+export * from './graph/paths-renderer.js';
+export * from './extraction/document-code-bindings.js';
+export * from './extraction/document-obligations.js';
+export * from './graph/compatibility.js';
+export * from './graph/compatibility-request.js';
+export * from './graph/compatibility-renderer.js';
+export * from './graph/code-coverage.js';
+export * from './graph/code-coverage-projection.js';
+export * from './graph/code-coverage-request.js';
+export * from './graph/code-coverage-renderer.js';
+export { MappingProposalService } from './application/mapping-proposals.js';
+export { createMappingProposalService } from './application/mapping-service.js';
+export type { MappingOperationOptions } from './application/mapping-proposals.js';
+export { prepareMappingProposal } from './extraction/mapping-plan.js';
+export { createMappingProvider, mappingProviderIdentity } from './extraction/mapping-provider.js';
+export { parseMappingRequest } from './extraction/mapping-request.js';
+export { validateMappingOutput } from './extraction/mapping-output.js';
+export { FileMappingProposalStore } from './storage/mapping-proposals.js';