@weftlet/toolkit 0.6.1 → 0.7.1

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 { stableJsonDigest } 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 = stableJsonDigest({ 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,6 @@
+import { type Store, type NamedNode } from 'n3';
+import { type GraphFact, type GraphNode, type SourceSpan } from '@weftlet/core';
+export declare function addCodeEvidence(dataset: Store, record: NamedNode, fact: GraphFact, nodeIri: (id: string) => string, includeNodes?: boolean): void;
+export declare function addCodeNodeEvidence(dataset: Store, node: GraphNode, 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,79 @@
+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, includeNodes = true) {
+    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);
+        }
+    }
+    if (includeNodes)
+        for (const node of [fact.subject, fact.object])
+            addCodeNodeEvidence(dataset, node, nodeIri);
+}
+export function addCodeNodeEvidence(dataset, node, nodeIri) {
+    const property = (subject, key, value) => {
+        if (value !== undefined)
+            dataset.addQuad(subject, iri(CG + key), literal(String(value), iri(XSD + (typeof value === 'number' ? 'integer' : 'string'))));
+    };
+    if (node.kind !== 'CodeSymbol' && node.codeSymbol === undefined)
+        return;
+    const term = iri(nodeIri(node.id));
+    dataset.addQuad(term, iri(RDF + 'type'), iri(CG + 'CodeSymbol'));
+    const value = node.codeSymbol;
+    if (value === undefined)
+        return; // 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;

package/dist/graph/compatibility-renderer.js

@@ -0,0 +1,45 @@
+import { sourceLocation } from '@weftlet/core';
+import { factEvidenceDescription } from './evidence-description.js';
+import { diagnosticSummary } from './diagnostics.js';
+import { coverageDescription } from './coverage.js';
+const quoted = (value) => JSON.stringify(value).replace(/[\\`*_{}\[\]()<>!|]/g, '\\$&');
+const explanations = {
+    'missing-assertion': 'One or both exact assertion IDs are absent from this snapshot.',
+    'invalid-evidence': 'The selected records lack valid obligation metadata or matching snapshot/revision provenance.',
+    'wrong-roles': 'Select a producer guarantee first and a consumer requirement second.',
+    'different-contracts': 'The assertions do not identify the same exact repository/scoped/transport/versioned contract.',
+    'unknown-version': 'A contract version is unknown; no version equivalence is assumed.',
+    'missing-context': 'Documented domain, stage, numeric constraint or unit is missing.',
+    'different-domain': 'The documented domains differ.',
+    'different-metric': 'The documented metrics differ; no semantic equivalence is inferred.',
+    'different-unit': 'The units differ; no unit conversion is inferred.',
+    'different-stage': 'The measurement stages differ; no elapsed-time or transformation model is available.',
+    'unsupported-number': 'A numeric limit is nonfinite or outside the supported safe numeric magnitude.',
+    'competing-declarations': 'Other assertions describe this endpoint/property; no winning declaration was selected.',
+    'extraction-gaps': 'Relevant source/extraction gaps remain in the saved evidence.',
+    subset: 'At the same declared stage, every value allowed by the producer constraint is allowed by the consumer constraint.',
+    'overlap-only': 'Some allowed producer values do not satisfy the consumer constraint. This alone is not a contradiction.',
+    disjoint: 'At the same declared stage, no value satisfies both constraints. This is a documented range incompatibility for an untransformed accepted value.',
+    'consumer-revalidation': 'The consumer explicitly requires revalidation. Verify its check and rejection behavior; the declaration alone does not prove them.',
+};
+export function renderContractCompatibility(report) {
+    const { snapshot, assessment, context, evidenceState } = report;
+    return ['# Selected contract constraint assessment',
+        `Snapshot: ${quoted(snapshot.snapshotId)} (${snapshot.commitSha}); configuration ${snapshot.configurationDigest ?? 'unknown'}`,
+        `Scope: ${snapshot.scope?.map(quoted).join(', ') ?? 'unknown'}; selected assertions: ${quoted(report.selection.producerFactId)}, ${quoted(report.selection.consumerFactId)}`,
+        `Result: ${assessment.status}; authority: ${assessment.authority}; method: ${assessment.version}; CI gate eligible: false; fulfillment: not evaluated`,
+        ...assessment.reasons.map(reason => `- ${explanations[reason]}`),
+        ...(evidenceState ? [`Stale: ${evidenceState.stale}; configuration matches: ${evidenceState.configurationMatches}; extraction compatible: ${evidenceState.extractionCompatible ?? 'unknown'}`,
+            `Excluded working changes: ${evidenceState.excludedWorkingChanges.map(quoted).join(', ') || '(none)'}; overlay freshness: ${evidenceState.overlayFreshness ?? 'not an overlay'}`] : []),
+        '', '## Cited declarations', ...report.facts.map(fact => `- ${quoted(fact.id)} [${fact.authority ?? 'unspecified'}; source ${fact.sourceAuthority ?? 'unspecified'}; review ${fact.extractionReview ?? 'unspecified'}] ` +
+            `${quoted(sourceLocation(fact.provenance))}–${fact.provenance.endLine}@${fact.provenance.commitSha}: ${quoted(factEvidenceDescription(fact) ?? 'Not a structured obligation')}`),
+        '', '## Assessment limits', ...assessment.conditions.map(condition => `- ${condition}`),
+        coverageDescription(report.coverage), ...report.coverage.gaps.map(quoted),
+        '', '## Further evidence',
+        `Other contract-incident assertions: ${context.otherIncidentFacts}; competing declarations: ${context.competingFacts}; omitted competing IDs: ${context.omittedCompetingFacts}.`,
+        ...context.competingFactIds.map(id => `- Competing assertion: ${quoted(id)}`),
+        ...context.contractNodeIds.map(id => `- Use graph.neighbors with contract ${quoted(id)} and the same snapshot for all declarations and continuation.`),
+        ...context.endpointNodeIds.map(id => `- Use graph.neighbors with endpoint ${quoted(id)} for indexed definitions, mappings and tests; file existence alone proves no fulfillment.`),
+        '', '## Scoped diagnostics', ...diagnosticSummary(report).map(quoted),
+    ].join('\n');
+}

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

@@ -0,0 +1,3 @@
+import type { ContractCompatibilityRequest } from '@weftlet/core';
+/** No search, implicit current head, policy mutation or caller-supplied authority. */
+export declare function parseContractCompatibilityRequest(value: unknown): ContractCompatibilityRequest;

package/dist/graph/compatibility-request.js

@@ -0,0 +1,18 @@
+/** No search, implicit current head, policy mutation or caller-supplied authority. */
+export function parseContractCompatibilityRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('graph.compatibility arguments must be an object');
+    const item = value, fields = ['snapshotId', 'producerFactId', 'consumerFactId'];
+    if (Object.keys(item).some(key => !fields.includes(key)))
+        throw new Error('Unknown graph.compatibility field');
+    const identifier = (key, maximum) => {
+        const value = item[key];
+        if (typeof value !== 'string' || !value.trim() || value.length > maximum)
+            throw new Error(`${key} must be a nonempty string of at most ${maximum} characters`);
+        return value;
+    };
+    const request = { snapshotId: identifier('snapshotId', 256), producerFactId: identifier('producerFactId', 8192), consumerFactId: identifier('consumerFactId', 8192) };
+    if (request.producerFactId === request.consumerFactId)
+        throw new Error('Select distinct producer and consumer assertion IDs');
+    return request;
+}

package/dist/graph/compatibility.d.ts

@@ -0,0 +1,7 @@
+import type { ContractCompatibilityReport, ContractCompatibilityRequest, ContractCompatibilityService, SnapshotStore } from '@weftlet/core';
+/** Read-only exact pair assessment over the same lossless RDF facts used by exploration and visualization. */
+export declare class SnapshotContractCompatibilityService implements ContractCompatibilityService {
+    private readonly store;
+    constructor(store: Pick<SnapshotStore, 'read'>);
+    assess(input: ContractCompatibilityRequest): Promise<ContractCompatibilityReport>;
+}

package/dist/graph/compatibility.js

@@ -0,0 +1,67 @@
+import { RdfEvidenceGraph } from './rdf.js';
+import { snapshotContext } from './snapshot-context.js';
+import { selectDiagnostics } from './diagnostics.js';
+import { parseContractCompatibilityRequest } from './compatibility-request.js';
+import { compareDeclaredConstraints } from './constraint-comparison.js';
+import { compatibilityContext } from './compatibility-context.js';
+import { renderContractCompatibility } from './compatibility-renderer.js';
+import { coverageForFacts } from './coverage.js';
+const conditions = [
+    'Only the two selected numeric declarations are compared, within this saved scope; other product obligations may exist.',
+    'Matching metric/unit names assume the same meaning. No unit conversion, transformations or elapsed-time model is inferred.',
+    'Source approval and assertion review stay on the cited facts. This assessment supplies no policy approval or CI pass/fail.',
+    'Implementation correctness, runtime delivery, consumer rejection/availability and current-diff validity are not established.',
+];
+async function assessSelected(snapshot, facts, context, diagnostics) {
+    const base = { version: 'declared-constraint-comparison-v1', scope: 'selected-assertion-pair',
+        authority: facts.some(fact => fact.authority === 'draft') ? 'draft' : 'inferred',
+        gateEligible: false, fulfillment: 'not-evaluated', conditions };
+    const unknown = (...reasons) => ({ ...base, status: 'unknown', reasons });
+    if (facts.length !== 2)
+        return unknown('missing-assertion');
+    if (facts.some(fact => !fact.contractObligation || fact.snapshotId !== snapshot.manifest.snapshotId ||
+        fact.provenance.commitSha !== snapshot.manifest.commitSha))
+        return unknown('invalid-evidence');
+    // Bound structural validation to these two records. Never revalidate the complete saved graph on a read query.
+    if (!(await new RdfEvidenceGraph({ ...snapshot, facts }).validate()).conforms)
+        return unknown('invalid-evidence');
+    const [producer, consumer] = facts;
+    if (producer.object.id !== consumer.object.id)
+        return unknown('different-contracts');
+    const gaps = [];
+    if (context.competingFacts)
+        gaps.push('competing-declarations');
+    if (['missingIntent', 'ambiguousIntent', 'implementationGaps'].some(key => {
+        const section = diagnostics[key];
+        return section.items.length || section.omittedRelevant;
+    }))
+        gaps.push('extraction-gaps');
+    if (gaps.length)
+        return unknown(...gaps);
+    return { ...base, ...compareDeclaredConstraints(producer.contractObligation.declaration, consumer.contractObligation.declaration) };
+}
+/** Read-only exact pair assessment over the same lossless RDF facts used by exploration and visualization. */
+export class SnapshotContractCompatibilityService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async assess(input) {
+        const request = parseContractCompatibilityRequest(input), snapshot = await this.store.read(request.snapshotId);
+        if (!snapshot)
+            throw new Error('No graph snapshot is available for that identifier');
+        if (snapshot.manifest.snapshotId !== request.snapshotId)
+            throw new Error('Saved snapshot identity does not match the requested identifier');
+        const all = await new RdfEvidenceGraph(snapshot).facts();
+        const byId = new Map(all.map(fact => [fact.id, fact]));
+        if (byId.size !== all.length)
+            throw new Error('Duplicate fact identities prevent exact compatibility selection');
+        const facts = [request.producerFactId, request.consumerFactId].flatMap(id => byId.has(id) ? [byId.get(id)] : []);
+        const context = compatibilityContext(all, facts);
+        const diagnostics = selectDiagnostics(snapshot, {}, facts, [], [], new Set(context.contractNodeIds));
+        const assessment = await assessSelected(snapshot, facts, context, diagnostics);
+        const plain = { snapshot: snapshotContext(snapshot.manifest), selection: request, facts,
+            coverage: coverageForFacts(facts, snapshot), assessment, context, diagnostics };
+        return { ...plain, markdown: renderContractCompatibility(plain) };
+    }
+}

package/dist/graph/constraint-comparison.d.ts

@@ -0,0 +1,7 @@
+import type { CompatibilityReason, ContractCompatibilityStatus, ObligationDeclaration } from '@weftlet/core';
+export interface ConstraintComparison {
+    readonly status: ContractCompatibilityStatus;
+    readonly reasons: readonly CompatibilityReason[];
+}
+/** Arithmetic on declared numeric sets only. No unit conversion, policy approval or implementation inference. */
+export declare function compareDeclaredConstraints(producer: ObligationDeclaration, consumer: ObligationDeclaration): ConstraintComparison;