@weftlet/toolkit 0.6.1 → 0.7.1

package/dist/graph/rdf-records.js

@@ -0,0 +1,90 @@
+import { DataFactory, Store } from 'n3';
+import { contextPackEvidenceAuthority } from './authority.js';
+import { stableJson } from '../infrastructure/util.js';
+import { CG, RDF, XSD } from './shacl-shapes.js';
+import { addBindingEvidence } from './binding-rdf.js';
+import { addCallEvidence } from './call-rdf.js';
+import { addObligationEvidence } from './obligation-rdf.js';
+import { addCodeEvidence, addCodeNodeEvidence } from './code-rdf.js';
+const { namedNode: iri, literal } = DataFactory;
+export const nodeIri = (id) => `urn:context-graph:node:${encodeURIComponent(id)}`;
+export const factIri = (id) => `urn:context-graph:fact:${encodeURIComponent(id)}`;
+export function addFactRecord(dataset, fact, ordinal) {
+    const record = iri(factIri(fact.id));
+    const subject = iri(nodeIri(fact.subject.id));
+    const object = iri(nodeIri(fact.object.id));
+    const predicate = iri(CG + fact.predicate);
+    dataset.addQuad(record, iri(RDF + 'type'), iri(RDF + 'Statement'));
+    dataset.addQuad(record, iri(CG + 'ordinal'), literal(String(ordinal), iri(XSD + 'integer')));
+    for (const [p, value] of [['subject', subject], ['predicate', predicate], ['object', object]]) {
+        dataset.addQuad(record, iri(RDF + p), value);
+    }
+    for (const [p, value] of Object.entries({
+        authority: contextPackEvidenceAuthority(fact), path: fact.provenance.path,
+        commit: fact.provenance.commitSha, sourceDigest: fact.provenance.digest,
+        extractor: `${fact.extractor.id}@${fact.extractor.version}`,
+        snapshotId: fact.snapshotId, record: stableJson(fact),
+        ...(fact.sourceAuthority ? { sourceAuthority: fact.sourceAuthority } : {}),
+        ...(fact.extractionReview ? { extractionReview: fact.extractionReview } : {}),
+        ...(fact.sourceRole !== undefined ? { sourceRole: fact.sourceRole } : {}),
+        ...(fact.sourcePolicyDigest !== undefined ? { sourcePolicyDigest: fact.sourcePolicyDigest } : {}),
+    }))
+        dataset.addQuad(record, iri(CG + p), literal(value));
+    if (fact.sourceOwnership !== undefined) {
+        dataset.addQuad(record, iri(CG + 'ownershipStatus'), literal(fact.sourceOwnership.status));
+        for (const ownerDocument of fact.sourceOwnership.ownerDocuments) {
+            dataset.addQuad(record, iri(CG + 'ownerDocument'), literal(ownerDocument));
+        }
+        for (const mappingId of fact.sourceOwnership.mappingIds) {
+            dataset.addQuad(record, iri(CG + 'ownershipMapping'), literal(mappingId));
+        }
+    }
+    for (const [p, value] of [['startLine', fact.provenance.startLine], ['endLine', fact.provenance.endLine]]) {
+        dataset.addQuad(record, iri(CG + p), literal(String(value), iri(XSD + 'integer')));
+    }
+    dataset.addQuad(record, iri(CG + 'confidence'), literal(String(fact.confidence), iri(XSD + 'decimal')));
+    addCodeEvidence(dataset, record, fact, nodeIri, false);
+    addBindingEvidence(dataset, record, fact, factIri);
+    addCallEvidence(dataset, record, fact, factIri);
+    addObligationEvidence(dataset, record, fact);
+}
+export function addNodeRdf(dataset, node) {
+    const term = iri(nodeIri(node.id));
+    dataset.addQuad(term, iri(RDF + 'type'), iri(CG + 'Node'));
+    dataset.addQuad(term, iri(CG + 'identifier'), literal(node.id));
+    dataset.addQuad(term, iri(CG + 'kind'), literal(node.kind));
+    dataset.addQuad(term, iri(CG + 'label'), literal(node.label));
+    addCodeNodeEvidence(dataset, node, nodeIri);
+}
+export function addAttributes(dataset, node, graph = DataFactory.defaultGraph()) {
+    for (const [key, value] of Object.entries(node.attributes ?? {})) {
+        const datatype = typeof value === 'boolean' ? 'boolean' : typeof value === 'number' ? 'decimal' : 'string';
+        dataset.addQuad(iri(nodeIri(node.id)), iri(`${CG}attribute/${encodeURIComponent(key)}`), literal(String(value), iri(XSD + datatype)), graph);
+    }
+}
+export function addFactEdges(dataset, fact) {
+    const record = iri(factIri(fact.id));
+    dataset.addQuad(iri(nodeIri(fact.subject.id)), iri(CG + fact.predicate), iri(nodeIri(fact.object.id)), record);
+    for (const node of [fact.subject, fact.object])
+        addAttributes(dataset, node, record);
+}
+export function addManifest(dataset, snapshot) {
+    dataset.addQuad(iri('urn:context-graph:snapshot'), iri(CG + 'manifest'), literal(stableJson(snapshot.manifest)));
+    for (const scope of snapshot.manifest.scope ?? []) {
+        dataset.addQuad(iri('urn:context-graph:snapshot'), iri(CG + 'scope'), literal(scope));
+    }
+    if (snapshot.manifest.configurationDigest) {
+        dataset.addQuad(iri('urn:context-graph:snapshot'), iri(CG + 'configurationDigest'), literal(snapshot.manifest.configurationDigest));
+    }
+}
+export function evidenceDataset(snapshot) {
+    const dataset = new Store();
+    for (const [ordinal, fact] of snapshot.facts.entries()) {
+        addFactRecord(dataset, fact, ordinal);
+        addFactEdges(dataset, fact);
+        for (const node of [fact.subject, fact.object])
+            addNodeRdf(dataset, node);
+    }
+    addManifest(dataset, snapshot);
+    return dataset;
+}

package/dist/graph/rdf.d.ts

@@ -1,29 +1,29 @@
+import type { Writable } from 'node:stream';
 import type { GraphFact, GraphSnapshot } from "@weftlet/core";
 import { type GraphValidationProgress } from './validation-progress.js';
 export { CG } from './shacl-shapes.js';
-export declare const nodeIri: (id: string) => string;
-export declare const factIri: (id: string) => string;
+export { factIri, nodeIri } from './rdf-records.js';
 /** Lossless RDF dataset: one named graph per cited assertion, with provenance in the default graph. */
 export declare class RdfEvidenceGraph {
     readonly snapshot: GraphSnapshot;
-    private readonly dataset;
+    private indexed?;
     constructor(snapshot: GraphSnapshot);
     validate(options?: {
         readonly onProgress?: (event: GraphValidationProgress) => void;
     }): Promise<{
         conforms: boolean;
-        issues: {
-            category: "extraction-gap";
-            focus: string;
-            path: string;
-            message: string;
-        }[];
+        issues: import("./partitioned-shacl.js").ShaclIssue[];
     }>;
     select(sparql: string, maxRows?: number): Promise<{
         rows: Record<string, string>[];
         truncated: boolean;
     }>;
-    /** The traversal projection is read through SPARQL, not a separate fact source. */
+    /** Lossless optimized projection, checked for equivalence with the public SPARQL path. */
     facts(): Promise<readonly GraphFact[]>;
+    /** Complete N-Quads in bounded groups; RDF triple order is not a snapshot identity. */
+    serializeChunks(): IterableIterator<string>;
+    /** Export large datasets with backpressure, without a whole-dataset string/quad array. */
+    serializeTo(destination: Writable): Promise<void>;
+    /** Compatibility convenience for small exports; use serializeTo for large graphs. */
     serialize(): Promise<string>;
 }

package/dist/graph/rdf.js

@@ -1,98 +1,67 @@
 import { QueryEngine } from '@comunica/query-sparql';
-import { DataFactory, Store, Writer } from 'n3';
-import SHACLValidator from 'rdf-validate-shacl';
-import { contextPackEvidenceAuthority } from "./authority.js";
-import { stableJson } from "../infrastructure/util.js";
+import { constants } from 'node:buffer';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { Writer } from 'n3';
 import { createRequire } from 'node:module';
-import { CG, RDF, XSD, evidenceShapes } from './shacl-shapes.js';
+import { CG } from './shacl-shapes.js';
 import { measureValidationPhase } from './validation-progress.js';
-const { namedNode: iri, literal } = DataFactory;
+import { bindingEvidenceIssues } from './binding-rdf.js';
+import { callEvidenceIssues } from './call-rdf.js';
+import { obligationEvidenceIssues } from './obligation-rdf.js';
+import { codeEvidenceIssues, invalidCodeRange } from './code-rdf.js';
 export { CG } from './shacl-shapes.js';
-export const nodeIri = (id) => `urn:context-graph:node:${encodeURIComponent(id)}`;
-export const factIri = (id) => `urn:context-graph:fact:${encodeURIComponent(id)}`;
+import { factIri } from './rdf-records.js';
+import { RdfPartitions } from './rdf-partitions.js';
+import { validatePartitions } from './partitioned-shacl.js';
+import { projectRdfFacts } from './rdf-projection.js';
+export { factIri, nodeIri } from './rdf-records.js';
 const engine = new QueryEngine();
 const SparqlParser = createRequire(import.meta.url)('sparqljs').Parser;
 /** Lossless RDF dataset: one named graph per cited assertion, with provenance in the default graph. */
 export class RdfEvidenceGraph {
     snapshot;
-    dataset = new Store();
+    indexed;
     constructor(snapshot) {
         this.snapshot = snapshot;
-        for (const [ordinal, fact] of snapshot.facts.entries()) {
-            const record = iri(factIri(fact.id));
-            const subject = iri(nodeIri(fact.subject.id));
-            const object = iri(nodeIri(fact.object.id));
-            const predicate = iri(CG + fact.predicate);
-            this.dataset.addQuad(subject, predicate, object, record);
-            this.dataset.addQuad(record, iri(RDF + 'type'), iri(RDF + 'Statement'));
-            this.dataset.addQuad(record, iri(CG + 'ordinal'), literal(String(ordinal), iri(XSD + 'integer')));
-            for (const [p, value] of [['subject', subject], ['predicate', predicate], ['object', object]]) {
-                this.dataset.addQuad(record, iri(RDF + p), value);
-            }
-            for (const [p, value] of Object.entries({
-                authority: contextPackEvidenceAuthority(fact), path: fact.provenance.path,
-                commit: fact.provenance.commitSha, sourceDigest: fact.provenance.digest,
-                extractor: `${fact.extractor.id}@${fact.extractor.version}`,
-                snapshotId: fact.snapshotId, record: stableJson(fact),
-                ...(fact.sourceAuthority ? { sourceAuthority: fact.sourceAuthority } : {}),
-                ...(fact.extractionReview ? { extractionReview: fact.extractionReview } : {}),
-                ...(fact.sourceRole !== undefined ? { sourceRole: fact.sourceRole } : {}),
-                ...(fact.sourcePolicyDigest !== undefined ? { sourcePolicyDigest: fact.sourcePolicyDigest } : {}),
-            }))
-                this.dataset.addQuad(record, iri(CG + p), literal(value));
-            if (fact.sourceOwnership !== undefined) {
-                this.dataset.addQuad(record, iri(CG + 'ownershipStatus'), literal(fact.sourceOwnership.status));
-                for (const ownerDocument of fact.sourceOwnership.ownerDocuments) {
-                    this.dataset.addQuad(record, iri(CG + 'ownerDocument'), literal(ownerDocument));
-                }
-                for (const mappingId of fact.sourceOwnership.mappingIds) {
-                    this.dataset.addQuad(record, iri(CG + 'ownershipMapping'), literal(mappingId));
-                }
-            }
-            for (const [p, value] of [['startLine', fact.provenance.startLine], ['endLine', fact.provenance.endLine]]) {
-                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')));
-            for (const node of [fact.subject, fact.object]) {
-                const term = iri(nodeIri(node.id));
-                this.dataset.addQuad(term, iri(RDF + 'type'), iri(CG + 'Node'));
-                this.dataset.addQuad(term, iri(CG + 'identifier'), literal(node.id));
-                this.dataset.addQuad(term, iri(CG + 'kind'), literal(node.kind));
-                this.dataset.addQuad(term, iri(CG + 'label'), literal(node.label));
-                for (const [key, value] of Object.entries(node.attributes ?? {})) {
-                    const datatype = typeof value === 'boolean' ? 'boolean' : typeof value === 'number' ? 'decimal' : 'string';
-                    this.dataset.addQuad(term, iri(`${CG}attribute/${encodeURIComponent(key)}`), literal(String(value), iri(XSD + datatype)), record);
-                }
-            }
-        }
-        this.dataset.addQuad(iri('urn:context-graph:snapshot'), iri(CG + 'manifest'), literal(stableJson(snapshot.manifest)));
-        for (const scope of snapshot.manifest.scope ?? []) {
-            this.dataset.addQuad(iri('urn:context-graph:snapshot'), iri(CG + 'scope'), literal(scope));
-        }
-        if (snapshot.manifest.configurationDigest) {
-            this.dataset.addQuad(iri('urn:context-graph:snapshot'), iri(CG + 'configurationDigest'), literal(snapshot.manifest.configurationDigest));
-        }
     }
     async validate(options = {}) {
-        // These graph-independent shapes already read the dataset as a union. Index
-        // that union once so every property lookup avoids scanning one graph per fact.
-        // Keep every triple; the original named dataset retains assertion provenance
-        // and remains the source for queries and serialization.
         const counts = { factCount: this.snapshot.facts.length };
-        const validationGraph = await measureValidationPhase('build-validation-union', counts, options.onProgress, () => {
-            const union = new Store();
-            for (const { subject, predicate, object } of this.dataset)
-                union.addQuad(subject, predicate, object);
-            return union;
+        const { partitions, types } = await measureValidationPhase('build-validation-union', counts, options.onProgress, () => {
+            const started = performance.now();
+            const partitions = new RdfPartitions(this.snapshot);
+            return { partitions, types: partitions.types(completed => {
+                    if (completed % 10 === 0)
+                        options.onProgress?.({ phase: 'build-validation-union', status: 'progress',
+                            elapsedMs: Math.round(performance.now() - started), ...counts, completed, total: partitions.count });
+                }) };
         });
-        const report = await measureValidationPhase('validate-shacl', counts, options.onProgress, () => new SHACLValidator(new Store(evidenceShapes)).validate(validationGraph));
-        const issues = report.results.map((result) => ({
-            category: 'extraction-gap',
-            focus: result.focusNode?.value,
-            path: result.path?.value,
-            message: result.message.map((message) => message.value).join('; '),
+        const started = performance.now();
+        const report = await measureValidationPhase('validate-shacl', counts, options.onProgress, () => validatePartitions(partitions, types, completed => {
+            if (completed % 10 === 0)
+                options.onProgress?.({ phase: 'validate-shacl', status: 'progress',
+                    elapsedMs: Math.round(performance.now() - started), ...counts, completed, total: partitions.count });
         }));
+        const issues = report.issues;
+        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' });
@@ -114,7 +83,12 @@ export class RdfEvidenceGraph {
         if (ast.type !== 'query' || ast.queryType !== 'SELECT' || ast.from || hasService(ast)) {
             throw new Error('Only local read queries are supported; remote datasets and updates are disabled');
         }
-        const stream = await engine.queryBindings(sparql, { sources: [this.dataset], unionDefaultGraph: true });
+        const indexed = this.indexed ??= new RdfPartitions(this.snapshot);
+        const source = {
+            match: (s, p, o, g) => Readable.from(indexed.match(s, p, o, g)),
+            countQuads: (s, p, o, g) => indexed.countMatches(s, p, o, g),
+        };
+        const stream = await engine.queryBindings(sparql, { sources: [{ type: 'rdfjs', value: source }], unionDefaultGraph: true });
         const rows = [];
         let truncated = false;
         for await (const binding of stream) {
@@ -127,18 +101,39 @@ export class RdfEvidenceGraph {
         }
         return { rows, truncated };
     }
-    /** The traversal projection is read through SPARQL, not a separate fact source. */
+    /** Lossless optimized projection, checked for equivalence with the public SPARQL path. */
     async facts() {
-        const result = await this.select(`SELECT ?record WHERE {
-      ?fact <${CG}record> ?record; <${CG}ordinal> ?ordinal
-    } ORDER BY ?ordinal`, 100_000);
-        if (result.truncated)
-            throw new Error('Graph exceeds the 100000-fact projection bound');
-        return result.rows.map((row) => JSON.parse(row.record));
+        return projectRdfFacts(this.snapshot.facts);
     }
-    serialize() {
+    /** Complete N-Quads in bounded groups; RDF triple order is not a snapshot identity. */
+    *serializeChunks() {
         const writer = new Writer({ format: 'N-Quads' });
-        writer.addQuads(this.dataset.getQuads(null, null, null, null));
-        return new Promise((resolve, reject) => writer.end((error, text) => error ? reject(error) : resolve(text)));
+        let buffer = '';
+        for (const batch of new RdfPartitions(this.snapshot).named())
+            for (const quad of batch) {
+                buffer += writer.quadToString(quad.subject, quad.predicate, quad.object, quad.graph);
+                if (buffer.length >= 64 * 1024) {
+                    yield buffer;
+                    buffer = '';
+                }
+            }
+        if (buffer)
+            yield buffer;
+    }
+    /** Export large datasets with backpressure, without a whole-dataset string/quad array. */
+    async serializeTo(destination) {
+        await pipeline(this.serializeChunks(), destination);
+    }
+    /** Compatibility convenience for small exports; use serializeTo for large graphs. */
+    async serialize() {
+        const chunks = [];
+        let length = 0;
+        for (const chunk of this.serializeChunks()) {
+            length += chunk.length;
+            if (length > constants.MAX_STRING_LENGTH)
+                throw new Error('RDF exceeds the JavaScript string limit; use serializeTo() or serializeChunks()');
+            chunks.push(chunk);
+        }
+        return chunks.join('');
     }
 }

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/graph/validation-progress.d.ts

@@ -1,7 +1,10 @@
 export type GraphValidationPhase = 'validate-identities' | 'build-rdf-evidence' | 'build-validation-union' | 'validate-shacl';
 export interface GraphValidationProgress {
     readonly phase: GraphValidationPhase;
-    readonly status: 'started' | 'completed' | 'failed';
+    readonly status: 'started' | 'completed' | 'failed' | 'progress';
+    /** Completed bounded RDF subject groups, when available. */
+    readonly completed?: number;
+    readonly total?: number;
     /** Wall time for this phase, not a completion estimate or in-phase heartbeat. */
     readonly elapsedMs: number;
     readonly factCount: number;

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';

package/dist/index.js

@@ -20,3 +20,25 @@ export * from './application/document-coverage.js';
 export * from './extraction/document-traversal.js';
 export * from './extraction/document-classification.js';
 export * from './extraction/document-evidence.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 { 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';

package/dist/infrastructure/json-digest.d.ts

@@ -0,0 +1,3 @@
+import { persistedJsonDigest } from './util.js';
+/** Identity of persisted JSON, excluding undefined optional fields that JSON cannot retain. */
+export declare const jsonDigest: typeof persistedJsonDigest;

package/dist/infrastructure/json-digest.js

@@ -0,0 +1,3 @@
+import { persistedJsonDigest } from './util.js';
+/** Identity of persisted JSON, excluding undefined optional fields that JSON cannot retain. */
+export const jsonDigest = persistedJsonDigest;

package/dist/infrastructure/unique-json.d.ts

@@ -0,0 +1,2 @@
+/** JSON.parse silently accepts duplicate keys, including differently escaped spellings. */
+export declare function parseUniqueJson(content: string): unknown;

package/dist/infrastructure/unique-json.js

@@ -0,0 +1,20 @@
+/** JSON.parse silently accepts duplicate keys, including differently escaped spellings. */
+export function parseUniqueJson(content) {
+    const parsed = JSON.parse(content);
+    const objects = [];
+    for (const token of content.matchAll(/"(?:\\.|[^"\\])*"|[{}\[\]]/g)) {
+        const value = token[0];
+        if (value === '{' || value === '[')
+            objects.push(value === '{' ? new Set() : undefined);
+        else if (value === '}' || value === ']')
+            objects.pop();
+        else if (/^\s*:/.test(content.slice(token.index + value.length))) {
+            const keys = objects.at(-1);
+            const key = JSON.parse(value);
+            if (keys.has(key))
+                throw new Error('Duplicate JSON key');
+            keys.add(key);
+        }
+    }
+    return parsed;
+}

package/dist/interfaces/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // Modified for standalone extraction; see docs/extraction-manifest.json.
 import "../../runtime-check.mjs";
+import { runMappingsCommand } from './mapping-proposals.js';
 import { resolve } from 'node:path';
 import process from 'node:process';
 import { createContextGraphApplication } from "../application/application.js";
@@ -20,6 +21,10 @@ import { adoptSemanticCache } from '../application/cache-adoption.js';
 import { SemanticHydrationError } from '../application/hydration-failure.js';
 import { GraphIdentityConflictError } from '../graph/identity-preflight.js';
 import { runDocumentCoverage } from './document-coverage.js';
+import { graphNeighborsRequestFromArgs } from './graph-exploration.js';
+import { graphPathsRequestFromArgs } from './graph-paths.js';
+import { graphCompatibilityRequestFromArgs } from './graph-compatibility.js';
+import { codeCoverageRequestFromArgs } from './code-coverage.js';
 function valueAfter(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
@@ -98,7 +103,7 @@ function formatHydrationPlan(plan) {
 async function main() {
     const args = process.argv.slice(2);
     if (args.includes('--help') || !args.length) {
-        process.stdout.write('weftlet documents plan|init|config show|config validate|doctor|hydrate|cache adopt|overlay|impact scan|sparql|validate|govern|visualize|diagnostics show|invariant check|clean-compare|ontology compile\nUse --config <file>; queries accept --snapshot <id>. impact scan accepts --changed-file, --capability, --max-facts, --max-depth, --continuation.\ndocuments plan --entry <document> [--entry <document>] [--root <path>] [--document-policy <json-file>] [--ref <commit>] [--json] previews prospective committed link coverage; it does not change hydration inputs or estimate model/cache work. Source classification/ownership completeness is separate from traversal readiness. The preview policy is an operation input. Set documentTraversal in configuration to activate traversal hydration; hydrate --plan describes its execution inputs. Safety limits: --max-read-documents, --max-read-bytes, --max-document-bytes.\nhydrate --plan [--json] [--ref <commit>] [--force-semantic] previews scope, cache and budgets without model calls or graph writes. Traversal coverage and role ambiguity block new model work; direct-source selection retains its existing behavior.\nhydrate --json --quiet emits structured semantic failures on stderr with no progress lines; failure stdout stays empty. hydrate --plan maps opaque source IDs to local document paths.\nhydrate|overlay --validation-details explicitly includes local node/fact identities, extractor names and source citations in identity-conflict errors; default reports use opaque references. This flag writes no diagnostic file. Use --json --quiet for structured identity-conflict stderr and empty failure stdout. Validation timings report phase boundaries, not a live heartbeat or percentage.\ncache adopt --from-config <previous.json> [--config <current.json>] [--ref <commit>] [--dry-run] returns JSON and copies only validated compatible artifacts, without model calls or snapshot writes. --dry-run performs no cache writes. Agent configurations accept the same --owner-doc, --task and --capability selection as hydrate.\ninit [--yes] [--directory <project>] [--config <file>] [--repository-id <id>] [--code-root <path>] [--semantic-source <path>] [--evidence-root <path>] [--model <name>] [--no-gitignore]\nSource flags may be repeated. init never overwrites an existing config. See README.md for examples.\n');
+        process.stdout.write('weftlet mappings plan|mappings propose|mappings read|documents plan|init|config show|config validate|doctor|hydrate|cache adopt|overlay|impact scan|graph neighbors|graph paths|graph compatibility|graph coverage|sparql|validate|govern|visualize|diagnostics show|invariant check|clean-compare|ontology compile\nmappings plan|propose --request <json-file> [--allow-model for propose] previews or runs one opt-in proposal; mappings read --snapshot <id> --key <key> reads saved unreviewed results.\nUse --config <file>; queries accept --snapshot <id>. impact scan accepts --changed-file, --capability, --max-facts, --max-depth, --continuation.\ngraph neighbors --snapshot <id> --node <exact-id> [--direction incoming|outgoing|both] [--predicate <relation>] [--max-facts <1..200>] [--continuation <token>] [--json] reads one-hop saved evidence; repeat --predicate to select multiple relations.\ngraph paths --snapshot <id> --from <exact-id> --to <exact-id> [--direction incoming|outgoing|both] [--predicate <relation>] [--max-depth <1..32>] [--max-paths <1..20>] [--max-steps <1..10000>] [--continuation <token>] [--json] explores cited simple paths; incomplete searches report frontier and limits.\ngraph coverage --snapshot <id> [--project <exact-package-root>] [--max-items <1..200>] [--continuation <token>] [--json] pages saved package/file coverage; absence or zero references is not proof of no impact.\ngraph compatibility --snapshot <id> --producer-fact <assertion-id> --consumer-fact <assertion-id> [--json] compares two documented numeric obligations; advisory only, with explicit unknowns and no implementation or CI verdict.\ndocuments plan --entry <document> [--entry <document>] [--root <path>] [--document-policy <json-file>] [--ref <commit>] [--json] previews prospective committed link coverage; it does not change hydration inputs or estimate model/cache work. Source classification/ownership completeness is separate from traversal readiness. The preview policy is an operation input. Set documentTraversal in configuration to activate traversal hydration; hydrate --plan describes its execution inputs. Safety limits: --max-read-documents, --max-read-bytes, --max-document-bytes.\nhydrate --plan [--json] [--ref <commit>] [--force-semantic] previews scope, cache and budgets without model calls or graph writes. Traversal coverage and role ambiguity block new model work; direct-source selection retains its existing behavior.\nhydrate --json --quiet emits structured semantic failures on stderr with no progress lines; failure stdout stays empty. hydrate --plan maps opaque source IDs to local document paths.\nhydrate|overlay --validation-details explicitly includes local node/fact identities, extractor names and source citations in identity-conflict errors; default reports use opaque references. This flag writes no diagnostic file. Use --json --quiet for structured identity-conflict stderr and empty failure stdout. Validation reports phase boundaries, elapsed time and completed groups; group counts are not completion-time estimates.\ncache adopt --from-config <previous.json> [--config <current.json>] [--ref <commit>] [--dry-run] returns JSON and copies only validated compatible artifacts, without model calls or snapshot writes. --dry-run performs no cache writes. Agent configurations accept the same --owner-doc, --task and --capability selection as hydrate.\ninit [--yes] [--directory <project>] [--config <file>] [--repository-id <id>] [--code-root <path>] [--semantic-source <path>] [--evidence-root <path>] [--model <name>] [--no-gitignore]\nSource flags may be repeated. init never overwrites an existing config. See README.md for examples.\n');
         return;
     }
     if (await runDocumentCoverage(args, defaultConfigPath))
@@ -164,6 +169,13 @@ async function main() {
     }
     const application = await createContextGraphApplication(configPath);
     const [command, subcommand] = args;
+    if (command === 'mappings') {
+        const report = await runMappingsCommand(application.mappingProposalService, args.slice(1));
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        if ('ready' in report && !report.ready)
+            process.exitCode = 1;
+        return;
+    }
     if (command === 'sparql' || command === 'validate') {
         const id = valueAfter(args, '--snapshot');
         const snapshot = id ? await application.snapshotStore.read(id) :
@@ -235,6 +247,26 @@ async function main() {
         process.stdout.write(args.includes('--json') ? `${JSON.stringify(pack, null, 2)}\n` : `${pack.markdown}\n`);
         return;
     }
+    if (command === 'graph' && subcommand === 'compatibility') {
+        const result = await application.compatibilityService.assess(graphCompatibilityRequestFromArgs(args.slice(2)));
+        process.stdout.write(`${args.includes('--json') ? JSON.stringify(result, null, 2) : result.markdown}\n`);
+        return;
+    }
+    if (command === 'graph' && subcommand === 'coverage') {
+        const result = await application.codeCoverageService.coverage(codeCoverageRequestFromArgs(args.slice(2)));
+        process.stdout.write(`${args.includes('--json') ? JSON.stringify(result, null, 2) : result.markdown}\n`);
+        return;
+    }
+    if (command === 'graph' && subcommand === 'paths') {
+        const result = await application.pathService.paths(graphPathsRequestFromArgs(args.slice(2)));
+        process.stdout.write(`${args.includes('--json') ? JSON.stringify(result, null, 2) : result.markdown}\n`);
+        return;
+    }
+    if (command === 'graph' && subcommand === 'neighbors') {
+        const result = await application.explorationService.neighbors(graphNeighborsRequestFromArgs(args.slice(2)));
+        process.stdout.write(`${args.includes('--json') ? JSON.stringify(result, null, 2) : result.markdown}\n`);
+        return;
+    }
     if (command === 'visualize') {
         const outputPath = valueAfter(args, '--output');
         if (!outputPath)