@weftlet/toolkit 0.6.0 → 0.7.0

package/dist/graph/rdf.js

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

package/dist/graph/shacl-shapes.js

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

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

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

package/dist/graph/snapshot-context.js

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

package/dist/index.d.ts

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

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/artifact-paths.d.ts

@@ -0,0 +1,4 @@
+/** Physical names only. Logical identities and evidence must retain the original value. */
+export declare function physicalArtifactKey(identity: string): string;
+/** Same-directory staging preserves atomic rename/link without repeating a long basename. */
+export declare function temporaryArtifactPath(destination: string): string;

package/dist/infrastructure/artifact-paths.js

@@ -0,0 +1,14 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+/** Physical names only. Logical identities and evidence must retain the original value. */
+export function physicalArtifactKey(identity) {
+    if (/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(identity) &&
+        !/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(identity))
+        return identity;
+    // '~' is excluded from literal logical storage keys, so a digest cannot alias one.
+    return `~${createHash('sha256').update(identity).digest('hex')}`;
+}
+/** Same-directory staging preserves atomic rename/link without repeating a long basename. */
+export function temporaryArtifactPath(destination) {
+    return join(dirname(destination), `.${randomUUID()}.tmp`);
+}

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

@@ -0,0 +1,2 @@
+/** Identity of persisted JSON, excluding undefined optional fields that JSON cannot retain. */
+export declare const jsonDigest: (value: unknown) => string;

package/dist/infrastructure/json-digest.js

@@ -0,0 +1,3 @@
+import { sha256, stableJson } from './util.js';
+/** Identity of persisted JSON, excluding undefined optional fields that JSON cannot retain. */
+export const jsonDigest = (value) => sha256(stableJson(JSON.parse(JSON.stringify(value))));

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

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

@@ -0,0 +1,46 @@
+import type { CodeCoverageService } from '@weftlet/core';
+export declare const graphCoverageTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            projectRoot: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            maxItems: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                default: number;
+            };
+            continuation: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function handleCodeCoverage(service: CodeCoverageService, value: unknown): Promise<import("@weftlet/core").CodeCoverageReport>;
+export declare function codeCoverageRequestFromArgs(args: readonly string[]): {
+    continuation?: string | undefined;
+    projectRoot?: string | undefined;
+    snapshotId: string;
+    maxItems: number;
+};

package/dist/interfaces/code-coverage.js

@@ -0,0 +1,18 @@
+import { parseCodeCoverageRequest } from '../graph/code-coverage-request.js';
+import { parseGraphQueryArgs } from './graph-query-args.js';
+export const graphCoverageTool = {
+    name: 'graph.coverage',
+    description: 'Inspect saved TypeScript-family source coverage. Page package boundaries, then select an exact projectRoot to page files. Distinguishes code-root selection, requested index entries, observed SCIP documents, cross-package references and unresolved evidence. Missing or zero observations never prove no impact. Does not rebuild evidence.',
+    inputSchema: { type: 'object', additionalProperties: false, required: ['snapshotId'], properties: {
+            snapshotId: { type: 'string', minLength: 1, maxLength: 256 }, projectRoot: { type: 'string', minLength: 1, maxLength: 8192 },
+            maxItems: { type: 'integer', minimum: 1, maximum: 200, default: 50 }, continuation: { type: 'string', minLength: 1, maxLength: 2048 },
+        } }, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export function handleCodeCoverage(service, value) {
+    return service.coverage(parseCodeCoverageRequest(value));
+}
+export function codeCoverageRequestFromArgs(args) {
+    return parseCodeCoverageRequest(parseGraphQueryArgs(args, 'coverage', {
+        '--snapshot': 'snapshotId', '--project': 'projectRoot', '--max-items': 'maxItems', '--continuation': 'continuation',
+    }));
+}

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

@@ -0,0 +1,35 @@
+import type { ContractCompatibilityService } from '@weftlet/core';
+export declare const graphCompatibilityTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            producerFactId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            consumerFactId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function handleGraphCompatibility(service: ContractCompatibilityService, value: unknown): Promise<import("@weftlet/core").ContractCompatibilityReport>;
+export declare function graphCompatibilityRequestFromArgs(args: readonly string[]): import("@weftlet/core").ContractCompatibilityRequest;

package/dist/interfaces/graph-compatibility.js

@@ -0,0 +1,21 @@
+import { parseContractCompatibilityRequest } from '../graph/compatibility-request.js';
+import { parseGraphQueryArgs } from './graph-query-args.js';
+export const graphCompatibilityTool = {
+    name: 'graph.compatibility',
+    description: 'Compare two exact cited producer/consumer numeric obligations from a saved snapshot. Reports subset, insufficient guarantee, disjoint constraints, required revalidation or unknown. Advisory only: never proves implementation, current-diff validity or a CI policy violation. Discover assertion IDs with graph.neighbors.',
+    inputSchema: { type: 'object', additionalProperties: false,
+        required: ['snapshotId', 'producerFactId', 'consumerFactId'], properties: {
+            snapshotId: { type: 'string', minLength: 1, maxLength: 256 },
+            producerFactId: { type: 'string', minLength: 1, maxLength: 8192 },
+            consumerFactId: { type: 'string', minLength: 1, maxLength: 8192 },
+        } },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export function handleGraphCompatibility(service, value) {
+    return service.assess(parseContractCompatibilityRequest(value));
+}
+export function graphCompatibilityRequestFromArgs(args) {
+    return parseContractCompatibilityRequest(parseGraphQueryArgs(args, 'compatibility', {
+        '--snapshot': 'snapshotId', '--producer-fact': 'producerFactId', '--consumer-fact': 'consumerFactId',
+    }));
+}

package/dist/interfaces/graph-exploration.d.ts

@@ -0,0 +1,59 @@
+import { type GraphExplorationService } from '@weftlet/core';
+export declare const graphNeighborsTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            nodeId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            direction: {
+                type: string;
+                enum: string[];
+            };
+            predicates: {
+                type: string;
+                maxItems: 16;
+                items: {
+                    type: string;
+                    enum: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+                };
+            };
+            maxFacts: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            continuation: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function handleGraphNeighbors(service: GraphExplorationService, value: unknown): Promise<import("@weftlet/core").GraphNeighborhood>;
+export declare function graphNeighborsRequestFromArgs(args: readonly string[]): {
+    continuation?: string | undefined;
+    snapshotId: string;
+    nodeId: string;
+    direction: "incoming" | "outgoing" | "both";
+    predicates: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+    maxFacts: number;
+};

package/dist/interfaces/graph-exploration.js

@@ -0,0 +1,27 @@
+import { parseGraphQueryArgs } from './graph-query-args.js';
+import { graphPredicates } from '@weftlet/core';
+import { parseGraphNeighborsRequest } from '../graph/neighborhood-request.js';
+export const graphNeighborsTool = {
+    name: 'graph.neighbors',
+    description: 'Look up an exact node ID in an explicit saved snapshot and page through its cited one-hop relationships. Follow returned neighbor IDs to explore further; no hydration or model calls.',
+    inputSchema: {
+        type: 'object', additionalProperties: false, required: ['snapshotId', 'nodeId'],
+        properties: {
+            snapshotId: { type: 'string', minLength: 1, maxLength: 256 },
+            nodeId: { type: 'string', minLength: 1, maxLength: 8192 },
+            direction: { type: 'string', enum: ['incoming', 'outgoing', 'both'] },
+            predicates: { type: 'array', maxItems: graphPredicates.length, items: { type: 'string', enum: [...graphPredicates] } },
+            maxFacts: { type: 'integer', minimum: 1, maximum: 200 },
+            continuation: { type: 'string', minLength: 1, maxLength: 2048 },
+        },
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export function handleGraphNeighbors(service, value) {
+    return service.neighbors(parseGraphNeighborsRequest(value));
+}
+export function graphNeighborsRequestFromArgs(args) {
+    const flags = { '--snapshot': 'snapshotId', '--node': 'nodeId',
+        '--direction': 'direction', '--predicate': 'predicates', '--max-facts': 'maxFacts', '--continuation': 'continuation' };
+    return parseGraphNeighborsRequest(parseGraphQueryArgs(args, 'neighbors', flags));
+}

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

@@ -0,0 +1,77 @@
+import { type GraphPathQueryService } from '@weftlet/core';
+export declare const graphPathsTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            fromNodeId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            toNodeId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            direction: {
+                type: string;
+                enum: string[];
+            };
+            predicates: {
+                type: string;
+                maxItems: 16;
+                items: {
+                    type: string;
+                    enum: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+                };
+            };
+            maxDepth: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            maxPaths: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            maxSteps: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            continuation: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function handleGraphPaths(service: GraphPathQueryService, value: unknown): Promise<import("@weftlet/core").GraphPaths>;
+export declare function graphPathsRequestFromArgs(args: readonly string[]): {
+    continuation?: string | undefined;
+    snapshotId: string;
+    fromNodeId: string;
+    toNodeId: string;
+    direction: "incoming" | "outgoing" | "both";
+    predicates: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+    maxDepth: number;
+    maxPaths: number;
+    maxSteps: number;
+};