@weftlet/toolkit 0.6.1 → 0.7.0

package/dist/graph/binding-rdf.js

@@ -0,0 +1,109 @@
+import { DataFactory } from 'n3';
+import { stableJson } from '../infrastructure/util.js';
+import { CG, RDF, XSD } from './shacl-shapes.js';
+import { invalidCodeRange } from './code-rdf.js';
+const { namedNode: iri, literal } = DataFactory;
+export function addBindingEvidence(dataset, record, fact, factIri) {
+    const binding = fact.codeBinding;
+    if (!binding)
+        return;
+    const prop = (node, key, value) => {
+        if (value !== undefined)
+            dataset.addQuad(node, iri(CG + key), literal(String(value), iri(XSD + (typeof value === 'number' ? 'integer' : 'string'))));
+    };
+    dataset.addQuad(record, iri(RDF + 'type'), iri(CG + 'DocumentCodeBinding'));
+    prop(record, 'bindingVersion', binding.schemaVersion);
+    prop(record, 'bindingMethod', binding.method);
+    for (const [key, value] of Object.entries(binding.selector ?? {}))
+        prop(record, `bindingSelector/${key}`, value);
+    const citations = (key, spans, proofs) => spans.forEach((span, index) => {
+        const term = iri(`${record.value}:${key}:${index}`);
+        dataset.addQuad(record, iri(CG + key), term);
+        dataset.addQuad(term, iri(RDF + 'type'), iri(CG + 'BindingCitation'));
+        for (const [name, value] of Object.entries(span))
+            prop(term, name, value);
+        if (proofs)
+            dataset.addQuad(term, iri(CG + 'bindingFact'), iri(factIri(proofs[index].factId)));
+    });
+    citations('bindingDocument', binding.documentCitations ?? []);
+    citations('bindingSelection', (binding.selectedOccurrences ?? []).map(item => item.provenance), binding.selectedOccurrences);
+    citations('bindingDefinition', (binding.definitions ?? []).map(item => item.provenance), binding.definitions);
+    citations('bindingSubject', (binding.subjectEvidence ?? []).map(item => item.provenance), binding.subjectEvidence);
+}
+function proofIssues(proof, byId) {
+    const issues = [], original = byId.get(proof.factId);
+    if (!original || stableJson(original.provenance) !== stableJson(proof.provenance))
+        issues.push('Binding proof is absent or has different provenance');
+    if (invalidCodeRange(proof.provenance) || proof.provenance.endLine < proof.provenance.startLine)
+        issues.push('Invalid binding proof range');
+    return issues;
+}
+function selectionIssues(proof, fact, byId) {
+    const issues = [...proofIssues(proof, byId)], original = byId.get(proof.factId);
+    const selector = fact.codeBinding.selector;
+    if (!original?.codeOccurrence)
+        return [...issues, 'Binding selection must cite an indexed occurrence'];
+    const target = original.codeOccurrence.role === 'definition' ? original.subject : original.object;
+    if (target.id !== fact.object.id || proof.provenance.path !== selector?.path)
+        issues.push('Binding selection does not identify the target symbol in its selected file');
+    if (selector?.line !== undefined && (selector.line !== proof.provenance.startLine || selector.column !== proof.provenance.startColumn))
+        issues.push('Binding selected occurrence differs from its exact selector');
+    if (selector?.line === undefined && original.codeOccurrence.role !== 'definition')
+        issues.push('A name selector requires a definition');
+    if (proof.provenance.commitSha !== fact.provenance.commitSha)
+        issues.push('Binding selection uses another revision');
+    return issues;
+}
+function definitionIssues(proof, fact, byId) {
+    const issues = [...proofIssues(proof, byId)], original = byId.get(proof.factId);
+    if (original?.codeOccurrence?.role !== 'definition' || original.subject.id !== fact.object.id)
+        issues.push('Binding definition does not define its target symbol');
+    if (proof.provenance.commitSha !== fact.provenance.commitSha)
+        issues.push('Binding definition uses another revision');
+    return issues;
+}
+function subjectIssues(proof, fact, byId) {
+    const issues = [...proofIssues(proof, byId)], original = byId.get(proof.factId);
+    if (!original || ![original.subject, original.object].some(node => node.id === fact.subject.id) ||
+        original.authority !== proof.authority || original.sourceAuthority !== proof.sourceAuthority || original.extractionReview !== proof.extractionReview) {
+        issues.push('Binding subject evidence or its authority was changed');
+    }
+    return issues;
+}
+function documentIssues(fact) {
+    const documents = fact.codeBinding.documentCitations ?? [];
+    if (!documents.some(span => stableJson(span) === stableJson(fact.provenance)) || documents.some(span => span.path !== fact.provenance.path || span.digest !== fact.provenance.digest || span.commitSha !== fact.provenance.commitSha ||
+        span.endLine < span.startLine || invalidCodeRange(span)))
+        return ['Binding document citations do not match their source'];
+    return [];
+}
+function mappingIssues(fact) {
+    const binding = fact.codeBinding, issues = [];
+    if (fact.predicate !== 'references' && !(binding.subjectEvidence?.length))
+        issues.push('Business mapping requires cited subject evidence');
+    if (fact.predicate !== 'references' && !['Capability', 'Workflow', 'Contract', 'Invariant'].includes(fact.subject.kind))
+        issues.push('Business mapping requires a business subject');
+    if (fact.authority === 'draft' && fact.sourceAuthority !== 'draft')
+        issues.push('Draft bindings require draft source authority');
+    if (fact.sourceRole === 'validation' && fact.predicate === 'implementedBy')
+        issues.push('Validation evidence cannot establish an implementation mapping');
+    if (binding.subjectEvidence?.some(proof => proof.extractionReview === 'unreviewed') && fact.extractionReview !== 'unreviewed')
+        issues.push('Binding cannot approve unreviewed subject evidence');
+    return issues;
+}
+/** Supplements shape validation by comparing proofs with the actual same-snapshot assertions. */
+export function bindingEvidenceIssues(fact, byId) {
+    const binding = fact.codeBinding;
+    if (!binding)
+        return [];
+    const issues = [...documentIssues(fact), ...mappingIssues(fact)], selector = binding.selector;
+    const positive = (n) => typeof n === 'number' && Number.isSafeInteger(n) && n > 0;
+    if ((selector?.line !== undefined || selector?.column !== undefined) && (!positive(selector.line) || !positive(selector.column))) {
+        issues.push('Exact occurrence selectors require positive line and column');
+    }
+    return [...issues,
+        ...(binding.selectedOccurrences ?? []).flatMap(proof => selectionIssues(proof, fact, byId)),
+        ...(binding.definitions ?? []).flatMap(proof => definitionIssues(proof, fact, byId)),
+        ...(binding.subjectEvidence ?? []).flatMap(proof => subjectIssues(proof, fact, byId)),
+    ];
+}

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

@@ -0,0 +1,4 @@
+import { type Store, type NamedNode } from 'n3';
+import { type GraphFact } from '@weftlet/core';
+export declare function addCallEvidence(dataset: Store, record: NamedNode, fact: GraphFact, factIri: (id: string) => string): void;
+export declare function callEvidenceIssues(fact: GraphFact, byId: ReadonlyMap<string, GraphFact>): readonly string[];

package/dist/graph/call-rdf.js

@@ -0,0 +1,94 @@
+import { DataFactory } from 'n3';
+import { repositoryFileNode } from '@weftlet/core';
+import { CG, RDF, XSD } from './shacl-shapes.js';
+import { stableJson } from '../infrastructure/util.js';
+import { invalidCodeRange } from './code-rdf.js';
+const { namedNode: iri, literal } = DataFactory;
+function containsRange(outer, inner) {
+    const compare = (a, b, c, d) => a - c || (b ?? 0) - (d ?? 0);
+    return compare(outer.startLine, outer.startColumn, inner.startLine, inner.startColumn) <= 0 &&
+        compare(outer.endLine, outer.endColumn, inner.endLine, inner.endColumn) >= 0;
+}
+export function addCallEvidence(dataset, record, fact, factIri) {
+    const call = fact.codeCall;
+    if (!call && fact.predicate !== 'calls')
+        return;
+    // Type calls even when metadata is missing so SHACL rejects them without a global OR scan.
+    dataset.addQuad(record, iri(RDF + 'type'), iri(CG + 'CodeCall'));
+    if (!call)
+        return;
+    const prop = (node, key, value) => {
+        if (value !== undefined)
+            dataset.addQuad(node, iri(CG + key), literal(String(value), iri(XSD +
+                (typeof value === 'number' ? 'integer' : typeof value === 'boolean' ? 'boolean' : 'string'))));
+    };
+    for (const [key, value] of Object.entries({ callVersion: call.schemaVersion, callMethod: call.method,
+        callSyntax: call.syntax, callDispatch: call.dispatch, callOptional: call.optional, callCaller: call.caller,
+        callTarget: call.target, callRuntime: call.runtime }))
+        prop(record, key, value);
+    const proofs = (key, values) => values.forEach((proof, index) => {
+        const term = iri(`${record.value}:${key}:${index}`);
+        dataset.addQuad(record, iri(CG + key), term);
+        dataset.addQuad(term, iri(RDF + 'type'), iri(CG + 'CallProof'));
+        dataset.addQuad(term, iri(CG + 'callFact'), iri(factIri(proof.factId)));
+        for (const [key, value] of Object.entries(proof.provenance))
+            prop(term, key, value);
+    });
+    proofs('callCallerDefinition', call.callerDefinitions ?? []);
+    proofs('callOccurrence', call.targetOccurrences ?? []);
+    proofs('callTargetDefinition', call.targetDefinitions ?? []);
+}
+function proofIssues(fact, proof, byId, role, nodeId) {
+    const issues = [];
+    const original = byId.get(proof.factId);
+    if (!original || stableJson(original.provenance) !== stableJson(proof.provenance) || original.codeOccurrence?.role !== role ||
+        (role === 'definition' ? original.subject.id : original.object.id) !== nodeId ||
+        proof.provenance.commitSha !== fact.provenance.commitSha || invalidCodeRange(proof.provenance)) {
+        issues.push('Call proof is missing, changed, from another revision or does not identify its endpoint');
+    }
+    return issues;
+}
+function occurrenceIssues(fact, proof, byId) {
+    const issues = proofIssues(fact, proof, byId, 'reference', fact.object.id);
+    if (proof.provenance.path !== fact.provenance.path || proof.provenance.digest !== fact.provenance.digest ||
+        !containsRange(fact.provenance, proof.provenance))
+        issues.push('Target occurrence must lie within the cited call site');
+    return issues;
+}
+function callerIssues(fact, byId) {
+    const call = fact.codeCall, callers = call.callerDefinitions ?? [], issues = [];
+    if (call.caller !== 'indexed-callable') {
+        if (callers.length || fact.subject.id !== repositoryFileNode(fact.provenance.path).id)
+            issues.push('File-scope calls require their canonical physical file');
+        return issues;
+    }
+    if (!callers.length || fact.subject.kind !== 'CodeSymbol')
+        issues.push('Indexed caller requires callable definition evidence');
+    for (const proof of callers) {
+        issues.push(...proofIssues(fact, proof, byId, 'definition', fact.subject.id));
+        if (proof.provenance.path !== fact.provenance.path || proof.provenance.digest !== fact.provenance.digest)
+            issues.push('Caller and call site must share source bytes');
+    }
+    return issues;
+}
+export function callEvidenceIssues(fact, byId) {
+    const call = fact.codeCall;
+    if (!call)
+        return fact.predicate === 'calls' ? ['A call requires static syntax and indexed proof metadata'] : [];
+    const issues = [];
+    if (fact.codeBinding || fact.codeOccurrence)
+        issues.push('A call assertion must remain separate from its supporting reference');
+    const targets = call.targetDefinitions ?? [], occurrences = call.targetOccurrences ?? [];
+    issues.push(...callerIssues(fact, byId));
+    if ((call.target === 'external') !== (targets.length === 0))
+        issues.push('Call target resolution disagrees with its indexed definitions');
+    if (call.target === 'indexed-class' && call.syntax !== 'construct')
+        issues.push('A class target requires construction syntax');
+    if ((call.syntax === 'construct') !== (call.dispatch === 'construct'))
+        issues.push('Construction and dispatch disagree');
+    for (const proof of targets)
+        issues.push(...proofIssues(fact, proof, byId, 'definition', fact.object.id));
+    for (const proof of occurrences)
+        issues.push(...occurrenceIssues(fact, proof, byId));
+    return issues;
+}

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

@@ -0,0 +1,2 @@
+/** Included in the shared named-dataset/union shape set. */
+export declare const callShapes = "\ncg:CodeCallShape a sh:NodeShape; sh:targetClass cg:CodeCall;\n sh:property [ sh:path rdf:predicate; sh:hasValue cg:calls ];\n sh:property [ sh:path rdf:object; sh:class cg:CodeSymbol ];\n sh:property [ sh:path cg:callVersion; sh:minCount 1; sh:maxCount 1; sh:hasValue 1 ];\n sh:property [ sh:path cg:callMethod; sh:minCount 1; sh:maxCount 1; sh:hasValue \"typescript-ast+scip\" ];\n sh:property [ sh:path cg:callSyntax; sh:minCount 1; sh:maxCount 1; sh:in (\"call\" \"construct\") ];\n sh:property [ sh:path cg:callDispatch; sh:minCount 1; sh:maxCount 1; sh:in (\"lexical\" \"member\" \"construct\") ];\n sh:property [ sh:path cg:callOptional; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:boolean ];\n sh:property [ sh:path cg:callCaller; sh:minCount 1; sh:maxCount 1; sh:in (\"indexed-callable\" \"file-scope\") ];\n sh:property [ sh:path cg:callTarget; sh:minCount 1; sh:maxCount 1; sh:in (\"indexed-body\" \"indexed-class\" \"declaration-only\" \"external\") ];\n sh:property [ sh:path cg:callRuntime; sh:minCount 1; sh:maxCount 1; sh:hasValue \"not-observed\" ];\n sh:property [ sh:path cg:columnEncoding; sh:minCount 1; sh:hasValue \"utf-16\" ];\n sh:property [ sh:path cg:authority; sh:in (\"implemented\" \"draft\") ];\n sh:property [ sh:path cg:extractionReview; sh:minCount 1; sh:hasValue \"deterministic\" ];\n sh:property [ sh:path cg:callOccurrence; sh:minCount 1; sh:class cg:CallProof ];\n sh:property [ sh:path cg:callCallerDefinition; sh:class cg:CallProof ];\n sh:property [ sh:path cg:callTargetDefinition; sh:class cg:CallProof ].\ncg:CallProofShape a sh:NodeShape; sh:targetClass cg:CallProof;\n sh:property [ sh:path cg:callFact; sh:minCount 1; sh:maxCount 1; sh:class rdf:Statement ];\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 ];\n sh:property [ sh:path cg:columnEncoding; sh:minCount 1; sh:hasValue \"utf-16\" ].\n";

package/dist/graph/call-shapes.js

@@ -0,0 +1,28 @@
+/** Included in the shared named-dataset/union shape set. */
+export const callShapes = `
+cg:CodeCallShape a sh:NodeShape; sh:targetClass cg:CodeCall;
+ sh:property [ sh:path rdf:predicate; sh:hasValue cg:calls ];
+ sh:property [ sh:path rdf:object; sh:class cg:CodeSymbol ];
+ sh:property [ sh:path cg:callVersion; sh:minCount 1; sh:maxCount 1; sh:hasValue 1 ];
+ sh:property [ sh:path cg:callMethod; sh:minCount 1; sh:maxCount 1; sh:hasValue "typescript-ast+scip" ];
+ sh:property [ sh:path cg:callSyntax; sh:minCount 1; sh:maxCount 1; sh:in ("call" "construct") ];
+ sh:property [ sh:path cg:callDispatch; sh:minCount 1; sh:maxCount 1; sh:in ("lexical" "member" "construct") ];
+ sh:property [ sh:path cg:callOptional; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:boolean ];
+ sh:property [ sh:path cg:callCaller; sh:minCount 1; sh:maxCount 1; sh:in ("indexed-callable" "file-scope") ];
+ sh:property [ sh:path cg:callTarget; sh:minCount 1; sh:maxCount 1; sh:in ("indexed-body" "indexed-class" "declaration-only" "external") ];
+ sh:property [ sh:path cg:callRuntime; sh:minCount 1; sh:maxCount 1; sh:hasValue "not-observed" ];
+ sh:property [ sh:path cg:columnEncoding; sh:minCount 1; sh:hasValue "utf-16" ];
+ sh:property [ sh:path cg:authority; sh:in ("implemented" "draft") ];
+ sh:property [ sh:path cg:extractionReview; sh:minCount 1; sh:hasValue "deterministic" ];
+ sh:property [ sh:path cg:callOccurrence; sh:minCount 1; sh:class cg:CallProof ];
+ sh:property [ sh:path cg:callCallerDefinition; sh:class cg:CallProof ];
+ sh:property [ sh:path cg:callTargetDefinition; sh:class cg:CallProof ].
+cg:CallProofShape a sh:NodeShape; sh:targetClass cg:CallProof;
+ sh:property [ sh:path cg:callFact; sh:minCount 1; sh:maxCount 1; sh:class rdf:Statement ];
+ 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:columnEncoding; sh:minCount 1; sh:hasValue "utf-16" ].
+`;

package/dist/graph/code-coverage-projection.d.ts

@@ -0,0 +1,9 @@
+import { type CodeCoverageOverview, type CodeFileCoverage, type CodeProjectCoverage, type GraphSnapshot } from '@weftlet/core';
+export declare const codeCoverageLimits: readonly ["Inventory covers regular committed TypeScript-family files and nearest package.json boundaries, not compiler projects or verified workspace membership.", "Code roots, requested entry files and observed SCIP documents are separate measurements. Neither selection nor an import alone proves a file was indexed.", "Connections count retained indexed code references across package boundaries, not asynchronous product links, runtime delivery or business impact.", "Zero observed connections or unresolved references does not prove isolation or complete resolution. Other languages, dynamic targets and absent evidence remain outside this measurement.", "Saved or draft coverage never establishes current-diff validity; use graph.neighbors on file/symbol IDs to inspect cited implementation evidence."];
+/** Derived only from saved inventory and retained occurrence facts; does not invent graph edges. */
+export declare function projectCodeCoverage(snapshot: GraphSnapshot): {
+    overview: CodeCoverageOverview;
+    projects: readonly CodeProjectCoverage[];
+    files: readonly CodeFileCoverage[];
+};
+export declare function codeCoverageDescription(code?: CodeCoverageOverview): string;

package/dist/graph/code-coverage-projection.js

@@ -0,0 +1,117 @@
+import { repositoryFileNode } from '@weftlet/core';
+import { sha256, stableJson } from '../infrastructure/util.js';
+export const codeCoverageLimits = [
+    'Inventory covers regular committed TypeScript-family files and nearest package.json boundaries, not compiler projects or verified workspace membership.',
+    'Code roots, requested entry files and observed SCIP documents are separate measurements. Neither selection nor an import alone proves a file was indexed.',
+    'Connections count retained indexed code references across package boundaries, not asynchronous product links, runtime delivery or business impact.',
+    'Zero observed connections or unresolved references does not prove isolation or complete resolution. Other languages, dynamic targets and absent evidence remain outside this measurement.',
+    'Saved or draft coverage never establishes current-diff validity; use graph.neighbors on file/symbol IDs to inspect cited implementation evidence.',
+];
+function validInventory(snapshot) {
+    const inventory = snapshot.manifest.codeInventory;
+    if (!inventory || inventory.version !== 'committed-code-inventory-v1' || inventory.scipIndexDigest !== snapshot.manifest.scipIndexDigest)
+        return;
+    const { digest, ...plain } = inventory;
+    if (sha256(stableJson(plain)) !== digest)
+        return;
+    return inventory;
+}
+function totals(files) {
+    const count = (test) => files.filter(test).length;
+    const sum = (key) => files.reduce((n, file) => n + file[key], 0);
+    return { files: files.length, codeRootSelected: count(file => file.codeRootSelected),
+        requested: count(file => file.requested === 'included'), excludedFromRequest: count(file => file.requested === 'excluded'),
+        requestUnknown: count(file => file.requested === 'unknown'), indexed: count(file => file.indexed === true),
+        indexUnknown: count(file => file.indexed === undefined), requestedNotIndexed: count(file => file.requested === 'included' && file.indexed === false),
+        indexedOutsideRequest: count(file => file.requested === 'excluded' && file.indexed === true),
+        references: sum('references'), unresolvedReferences: sum('unresolvedReferences'), declarationOnlyReferences: sum('declarationOnlyReferences'),
+        implementationGaps: sum('implementationGaps') };
+}
+function definitionProjects(facts, byPath) {
+    const definitions = new Map();
+    for (const fact of facts)
+        if (fact.codeOccurrence?.role === 'definition') {
+            const owner = byPath.get(fact.provenance.path)?.projectRoot;
+            if (owner === undefined)
+                continue;
+            const roots = definitions.get(fact.subject.id) ?? new Set();
+            roots.add(owner);
+            definitions.set(fact.subject.id, roots);
+        }
+    return definitions;
+}
+function measureReferences(facts, byPath) {
+    const definitions = definitionProjects(facts, byPath);
+    const connections = new Map();
+    const project = (root) => {
+        if (!connections.has(root))
+            connections.set(root, { peers: new Set(), incoming: new Set(), outgoing: new Set() });
+        return connections.get(root);
+    };
+    const crossReferences = new Set(), seen = new Set();
+    for (const fact of facts) {
+        if (fact.codeOccurrence?.role !== 'reference' || seen.has(fact.id))
+            continue;
+        seen.add(fact.id);
+        const file = byPath.get(fact.provenance.path);
+        if (!file)
+            continue;
+        file.references++;
+        const targets = definitions.get(fact.object.id);
+        if (!targets?.size || fact.object.codeSymbol?.resolution === 'no-indexed-definition')
+            file.unresolvedReferences++;
+        if (fact.object.codeSymbol?.resolution === 'declaration-only')
+            file.declarationOnlyReferences++;
+        for (const root of targets ?? [])
+            if (root !== file.projectRoot) {
+                crossReferences.add(fact.id);
+                project(file.projectRoot).peers.add(root);
+                project(file.projectRoot).outgoing.add(fact.id);
+                project(root).peers.add(file.projectRoot);
+                project(root).incoming.add(fact.id);
+            }
+    }
+    return { project, crossReferences };
+}
+/** Derived only from saved inventory and retained occurrence facts; does not invent graph edges. */
+export function projectCodeCoverage(snapshot) {
+    const inventory = validInventory(snapshot);
+    if (!inventory)
+        return { overview: { scope: 'saved-snapshot', status: snapshot.manifest.codeInventory ? 'invalid-inventory' : 'unavailable',
+                limitations: codeCoverageLimits }, projects: [], files: [] };
+    const files = inventory.files.map(file => ({ ...file, nodeId: repositoryFileNode(file.path).id,
+        references: 0, unresolvedReferences: 0, declarationOnlyReferences: 0, implementationGaps: 0 }));
+    const byPath = new Map(files.map(file => [file.path, file]));
+    const { project, crossReferences } = measureReferences(snapshot.facts, byPath);
+    for (const gap of snapshot.diagnostics ?? [])
+        if (gap.kind === 'implementationGaps') {
+            for (const path of new Set(gap.provenance.map(span => span.path))) {
+                const file = byPath.get(path);
+                if (file)
+                    file.implementationGaps++;
+            }
+        }
+    const groups = new Map();
+    for (const file of files) {
+        const group = groups.get(file.projectRoot) ?? [];
+        group.push(file);
+        groups.set(file.projectRoot, group);
+    }
+    const projects = inventory.projects.map(item => ({ root: item.root, ...(item.manifest ? { manifestPath: item.manifest.path } : {}),
+        counts: totals(groups.get(item.root) ?? []), connectedProjects: project(item.root).peers.size,
+        outgoingReferences: project(item.root).outgoing.size, incomingReferences: project(item.root).incoming.size }));
+    return { overview: { scope: 'saved-snapshot', status: 'recorded', inventoryDigest: inventory.digest, selection: inventory.selection,
+            indexObservation: inventory.indexObservation, projects: projects.length, totals: totals(files),
+            crossProjectReferences: crossReferences.size, otherIndexedFiles: inventory.otherIndexedFiles, limitations: codeCoverageLimits }, projects, files };
+}
+export function codeCoverageDescription(code) {
+    if (!code || code.status !== 'recorded' || !code.totals)
+        return `Saved repository code coverage: ${code?.status ?? 'unavailable'}; absence is not zero coverage.`;
+    const n = code.totals;
+    return `Saved repository code coverage (TypeScript-family files): ${n.files} inventoried; ${n.codeRootSelected} selected by code roots; ` +
+        `${n.requested} requested entries, ${n.excludedFromRequest} outside entries, ${n.requestUnknown} selection unknown; ` +
+        `${n.indexed} observed in SCIP, ${n.indexUnknown} index observation unknown, ${n.requestedNotIndexed} requested but not observed. ` +
+        `${code.crossProjectReferences} observed cross-package references; ${n.unresolvedReferences} references lack an indexed definition; ` +
+        `${n.declarationOnlyReferences} reference declaration-only targets; ${n.implementationGaps} cited implementation gaps. ` +
+        'These are saved-snapshot measurements, not completeness or no-impact claims. Use graph.coverage for package/file pages.';
+}

package/dist/graph/code-coverage-renderer.d.ts

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

package/dist/graph/code-coverage-renderer.js

@@ -0,0 +1,15 @@
+import { codeCoverageDescription } from './code-coverage-projection.js';
+const quoted = (value) => JSON.stringify(value).replace(/[\\`*_{}\[\]()<>!|]/g, '\\$&');
+export function renderCodeCoverage(report) {
+    const { snapshot, evidenceState, selection, overview } = report;
+    return ['# Saved repository code coverage', `Snapshot: ${quoted(snapshot.snapshotId)} (${snapshot.commitSha}); configuration ${snapshot.configurationDigest ?? 'unknown'}`,
+        codeCoverageDescription(overview),
+        `View: ${report.view}; project: ${quoted(selection.projectRoot ?? '(all boundaries)')}; ${report.projectStatus ?? 'all'}; offset ${selection.offset}; ${selection.remaining}/${selection.total} items remain.`,
+        ...(selection.continuation ? [`Continuation (same request): ${selection.continuation}`] : []),
+        ...(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)'}`] : []),
+        '', ...report.projects.map(p => `- ${quoted(p.root)}: ${p.counts.files} files; ${p.counts.requested} requested; ${p.counts.indexed} indexed; ${p.counts.indexUnknown} index unknown; ${p.connectedProjects} connected package boundaries. Use this exact projectRoot to page files.`),
+        ...report.files.map(f => `- ${quoted(f.path)} (${quoted(f.nodeId)}): code roots ${f.codeRootSelected}; requested ${f.requested}; indexed ${f.indexed ?? 'unknown'}; ${f.unresolvedReferences} unresolved references; ${f.declarationOnlyReferences} declaration-only references; ${f.implementationGaps} cited gaps. Inspect graph.neighbors at this file ID for retained evidence.`),
+        '', '## Measurement limits', ...overview.limitations.map(item => `- ${item}`),
+    ].join('\n');
+}

package/dist/graph/code-coverage-request.d.ts

@@ -0,0 +1,6 @@
+export declare function parseCodeCoverageRequest(value: unknown): {
+    continuation?: string | undefined;
+    projectRoot?: string | undefined;
+    snapshotId: string;
+    maxItems: number;
+};

package/dist/graph/code-coverage-request.js

@@ -0,0 +1,19 @@
+export function parseCodeCoverageRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('graph.coverage arguments must be an object');
+    const item = value;
+    if (Object.keys(item).some(key => !['snapshotId', 'projectRoot', 'maxItems', 'continuation'].includes(key)))
+        throw new Error('Unknown graph.coverage field');
+    const text = (key, max) => {
+        const s = item[key];
+        if (typeof s !== 'string' || !s.trim() || s.length > max)
+            throw new Error(`${key} must be a nonempty string of at most ${max} characters`);
+        return s;
+    };
+    const maxItems = item.maxItems === undefined ? 50 : item.maxItems;
+    if (!Number.isInteger(maxItems) || Number(maxItems) < 1 || Number(maxItems) > 200)
+        throw new Error('maxItems must be an integer between 1 and 200');
+    return { snapshotId: text('snapshotId', 256), maxItems: Number(maxItems),
+        ...(item.projectRoot === undefined ? {} : { projectRoot: text('projectRoot', 8192) }),
+        ...(item.continuation === undefined ? {} : { continuation: text('continuation', 2048) }) };
+}

package/dist/graph/code-coverage.d.ts

@@ -0,0 +1,6 @@
+import type { CodeCoverageReport, CodeCoverageRequest, CodeCoverageService, SnapshotStore } from '@weftlet/core';
+export declare class SnapshotCodeCoverageService implements CodeCoverageService {
+    private readonly store;
+    constructor(store: Pick<SnapshotStore, 'read'>);
+    coverage(input: CodeCoverageRequest): Promise<CodeCoverageReport>;
+}

package/dist/graph/code-coverage.js

@@ -0,0 +1,54 @@
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { projectCodeCoverage } from './code-coverage-projection.js';
+import { parseCodeCoverageRequest } from './code-coverage-request.js';
+import { renderCodeCoverage } from './code-coverage-renderer.js';
+import { RdfEvidenceGraph } from './rdf.js';
+import { snapshotContext } from './snapshot-context.js';
+const version = 'code-coverage-query-v1';
+function pageOffset(token, binding, length, pageSize) {
+    if (token === undefined)
+        return 0;
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(token))
+            throw Error();
+        const item = JSON.parse(Buffer.from(token, 'base64url').toString('utf8'));
+        if (Object.keys(item).sort().join(',') !== 'binding,offset,version' || item.version !== version || item.binding !== binding ||
+            !Number.isSafeInteger(item.offset) || item.offset < 1 || item.offset >= length || item.offset % pageSize)
+            throw Error();
+        return item.offset;
+    }
+    catch {
+        throw Error('Invalid graph.coverage continuation or snapshot/query mismatch; restart graph.coverage');
+    }
+}
+export class SnapshotCodeCoverageService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async coverage(input) {
+        const request = parseCodeCoverageRequest(input), saved = await this.store.read(request.snapshotId);
+        if (!saved)
+            throw Error('No graph snapshot is available for that identifier');
+        if (saved.manifest.snapshotId !== request.snapshotId)
+            throw Error('Saved snapshot identity does not match the requested identifier');
+        const facts = await new RdfEvidenceGraph(saved).facts();
+        if (new Set(facts.map(fact => fact.id)).size !== facts.length)
+            throw Error('Duplicate fact identities prevent stable code coverage');
+        const projected = projectCodeCoverage({ ...saved, facts });
+        const { continuation, ...query } = request;
+        const binding = sha256(stableJson({ version, query, manifest: saved.manifest, facts, diagnostics: saved.diagnostics }));
+        const fileView = request.projectRoot !== undefined;
+        const files = fileView ? projected.files.filter(f => f.projectRoot === request.projectRoot) : [];
+        const length = fileView ? files.length : projected.projects.length;
+        const offset = pageOffset(continuation, binding, length, request.maxItems), end = Math.min(length, offset + request.maxItems);
+        const project = projected.projects.find(p => p.root === request.projectRoot);
+        const next = end < length ? Buffer.from(JSON.stringify({ version, binding, offset: end })).toString('base64url') : undefined;
+        const plain = { snapshot: snapshotContext(saved.manifest), overview: projected.overview,
+            view: fileView ? 'files' : 'projects', ...(fileView ? { project, projectStatus: projected.overview.status !== 'recorded' ? 'unknown' : project ? 'present' : 'absent' } : {}),
+            projects: fileView ? [] : projected.projects.slice(offset, end), files: fileView ? files.slice(offset, end) : [],
+            selection: { ...(fileView ? { projectRoot: request.projectRoot } : {}), maxItems: request.maxItems, offset, total: length,
+                remaining: length - end, truncated: !!next, ...(next ? { continuation: next } : {}) } };
+        return { ...plain, markdown: renderCodeCoverage(plain) };
+    }
+}

package/dist/graph/code-description.d.ts

@@ -0,0 +1,4 @@
+import type { GraphFact, ContextPack } from '@weftlet/core';
+/** Human-readable labels for the same typed evidence returned to CLI/MCP clients. */
+export declare function codeEvidenceDescription(fact: GraphFact): string | undefined;
+export declare function unexpandedCodeDescription(exploration: ContextPack['exploration']): readonly string[];

package/dist/graph/code-description.js

@@ -0,0 +1,24 @@
+/** Human-readable labels for the same typed evidence returned to CLI/MCP clients. */
+export function codeEvidenceDescription(fact) {
+    if (fact.codeCall) {
+        const call = fact.codeCall;
+        return `static ${call.syntax}; ${call.dispatch} selection; ${call.target}; ${call.caller}; ` +
+            `${call.optional ? 'optional invocation; ' : ''}runtime dispatch/value mutation not evaluated; execution not observed`;
+    }
+    const binding = fact.codeBinding;
+    if (binding) {
+        const sites = binding.definitions.map(proof => `${proof.provenance.path}:${proof.provenance.startLine}:${proof.provenance.startColumn ?? 1}@${proof.provenance.commitSha}`).join(', ');
+        const selected = binding.selectedOccurrences.map(proof => `${proof.provenance.path}:${proof.provenance.startLine}:${proof.provenance.startColumn ?? 1}@${proof.provenance.commitSha}`).join(', ');
+        return `explicit mapping declaration; target ${binding.selector.symbol}; selected ${selected}; definitions ${sites}; not proof of fulfillment or test execution`;
+    }
+    const code = fact.codeOccurrence;
+    if (!code)
+        return undefined;
+    const symbol = code.role === 'definition' ? fact.subject : fact.object;
+    return `static ${code.role}; ${symbol.codeSymbol?.resolution ?? 'unknown resolution'}; ` +
+        `${code.enclosure} lexical enclosure; ${code.locationKind}; UTF-16 columns`;
+}
+export function unexpandedCodeDescription(exploration) {
+    const count = exploration?.unexpandedCodeTargetCount ?? 0;
+    return count ? [`Unresolved code targets left unexpanded: ${count}; up to 100 example IDs are included in exploration metadata. Use graph.neighbors with their exact IDs to inspect shared references; no implementation or call is established.`] : [];
+}

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

@@ -0,0 +1,5 @@
+import { type Store, type NamedNode } from 'n3';
+import { type GraphFact, type SourceSpan } from '@weftlet/core';
+export declare function addCodeEvidence(dataset: Store, record: NamedNode, fact: GraphFact, nodeIri: (id: string) => string): void;
+export declare function invalidCodeRange(range: Pick<SourceSpan, 'startLine' | 'endLine' | 'startColumn' | 'endColumn' | 'columnEncoding'>): boolean;
+export declare function codeEvidenceIssues(fact: GraphFact): readonly string[];

package/dist/graph/code-rdf.js

@@ -0,0 +1,72 @@
+import { DataFactory } from 'n3';
+import { repositoryFileNode } from '@weftlet/core';
+import { CG, RDF, XSD } from './shacl-shapes.js';
+const { namedNode: iri, literal } = DataFactory;
+export function addCodeEvidence(dataset, record, fact, nodeIri) {
+    const property = (subject, key, value) => {
+        if (value === undefined)
+            return;
+        dataset.addQuad(subject, iri(CG + key), literal(String(value), iri(XSD + (typeof value === 'number' ? 'integer' : 'string'))));
+    };
+    for (const key of ['startColumn', 'endColumn', 'columnEncoding'])
+        property(record, key, fact.provenance[key]);
+    const code = fact.codeOccurrence;
+    if (code !== undefined) {
+        dataset.addQuad(record, iri(RDF + 'type'), iri(CG + 'CodeOccurrence'));
+        for (const [key, value] of Object.entries({ codeVersion: code.schemaVersion, codeRole: code.role, codeLocationKind: code.locationKind,
+            codeNativeRoles: code.nativeRoles, codeEnclosure: code.enclosure }))
+            property(record, key, value);
+        if (code.enclosingSymbolId !== undefined)
+            dataset.addQuad(record, iri(CG + 'enclosingSymbol'), iri(nodeIri(code.enclosingSymbolId)));
+        if (code.declarationRange !== undefined) {
+            const range = iri(record.value + ':declaration-range');
+            dataset.addQuad(record, iri(CG + 'declarationRange'), range);
+            dataset.addQuad(range, iri(RDF + 'type'), iri(CG + 'CodeRange'));
+            for (const [key, value] of Object.entries(code.declarationRange))
+                property(range, key, value);
+        }
+    }
+    for (const node of [fact.subject, fact.object]) {
+        if (node.kind !== 'CodeSymbol' && node.codeSymbol === undefined)
+            continue;
+        const term = iri(nodeIri(node.id));
+        dataset.addQuad(term, iri(RDF + 'type'), iri(CG + 'CodeSymbol'));
+        const value = node.codeSymbol;
+        if (value === undefined)
+            continue; // The shape reports missing required metadata.
+        for (const [key, item] of Object.entries({ codeVersion: value.schemaVersion, codeProvider: value.provider,
+            codeRepository: value.repositoryId, nativeSymbol: value.nativeSymbol, codeIdentityScope: value.identityScope,
+            codeDocument: value.documentPath, codeIndex: value.indexDigest, codeResolution: value.resolution }))
+            property(term, key, item);
+    }
+}
+export function invalidCodeRange(range) {
+    if (range.startColumn === undefined && range.endColumn === undefined && range.columnEncoding === undefined)
+        return false;
+    return !Number.isSafeInteger(range.startColumn) || !Number.isSafeInteger(range.endColumn) ||
+        range.startColumn < 1 || range.endColumn < 1 || range.columnEncoding !== 'utf-16' ||
+        range.endLine < range.startLine || (range.endLine === range.startLine && range.endColumn < range.startColumn);
+}
+export function codeEvidenceIssues(fact) {
+    const code = fact.codeOccurrence;
+    if (!code)
+        return [];
+    const issues = [];
+    const file = repositoryFileNode(fact.provenance.path);
+    if ((code.nativeRoles & 1) !== (code.role === 'definition' ? 1 : 0))
+        issues.push('Code role disagrees with native definition flag');
+    if (code.role === 'definition' && (fact.object.id !== file.id || fact.object.kind !== file.kind)) {
+        issues.push('Code definition must identify its canonical cited physical file');
+    }
+    if (code.role === 'reference') {
+        if (code.declarationRange !== undefined)
+            issues.push('A reference cannot declare a definition range');
+        const sourceId = code.enclosure === 'native-range' ? code.enclosingSymbolId : file.id;
+        if (fact.subject.id !== sourceId)
+            issues.push('Reference source disagrees with lexical enclosure');
+    }
+    const zeroWidth = fact.provenance.startLine === fact.provenance.endLine && fact.provenance.startColumn === fact.provenance.endColumn;
+    if (zeroWidth !== (code.locationKind === 'zero-width-anchor'))
+        issues.push('Code location kind disagrees with source span');
+    return issues;
+}

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

@@ -0,0 +1,2 @@
+import type { ContractCompatibilityReport, GraphFact } from '@weftlet/core';
+export declare function compatibilityContext(all: readonly GraphFact[], selected: readonly GraphFact[]): ContractCompatibilityReport['context'];

package/dist/graph/compatibility-context.js

@@ -0,0 +1,18 @@
+/** Other declarations of the same endpoint/property remain visible; never choose a winning assertion. */
+function competes(selected, other) {
+    const left = selected.contractObligation?.declaration, right = other.contractObligation?.declaration;
+    if (!left || !right || other.id === selected.id || selected.object.id !== other.object.id)
+        return false;
+    return left.role === right.role && left.endpoint === right.endpoint && left.domain === right.domain &&
+        left.stage === right.stage && left.constraint?.metric === right.constraint?.metric;
+}
+export function compatibilityContext(all, selected) {
+    const contractNodeIds = [...new Set(selected.filter(fact => fact.contractObligation).map(fact => fact.object.id))].sort();
+    const endpointNodeIds = [...new Set(selected.filter(fact => fact.contractObligation).map(fact => fact.subject.id))].sort();
+    const selectedIds = new Set(selected.map(fact => fact.id));
+    const competing = [...new Set(all.filter(other => !selectedIds.has(other.id) && selected.some(fact => competes(fact, other))).map(fact => fact.id))].sort();
+    return { contractNodeIds, endpointNodeIds,
+        otherIncidentFacts: all.filter(fact => !selectedIds.has(fact.id) &&
+            [fact.subject.id, fact.object.id].some(id => contractNodeIds.includes(id))).length,
+        competingFactIds: competing.slice(0, 20), competingFacts: competing.length, omittedCompetingFacts: Math.max(0, competing.length - 20) };
+}

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

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