@weftlet/toolkit 0.6.1 → 0.7.0

package/README.md

@@ -14,7 +14,7 @@ Proposed future capabilities are recorded in the [Weftlet 2.0 product plan](docs
 ## Set up a project
 
 <!-- weftlet:release:start -->
-Package versions in this checkout/archive: `@weftlet/toolkit@0.6.1` and `@weftlet/core@0.6.1`.
+Package versions in this checkout/archive: `@weftlet/toolkit@0.7.0` and `@weftlet/core@0.7.0`.
 <!-- weftlet:release:end -->
 
 Weftlet uses `@weftlet/toolkit`; its neutral `@weftlet/core` dependency is installed
@@ -349,6 +349,123 @@ context-graph impact scan --config context-graph.config.json --capability search
 context-graph visualize --config context-graph.config.json --capability search --output graph.html
 ```
 
+**Available starting with 0.7.0:** for precise follow-up, copy the returned
+snapshot ID and a node ID from a cited fact:
+
+```sh
+weftlet graph neighbors --snapshot <snapshot-id> --node <node-id> --direction both --max-facts 20 --json
+```
+
+MCP exposes the same read-only operation as `graph.neighbors` with `snapshotId` and `nodeId`.
+Use `predicates` (CLI: repeat `--predicate`) to select relations and `direction` for incoming,
+outgoing or both. Follow `selection.continuation` with the same arguments to retrieve more
+assertions. `frontier.neighbors` identifies returned neighbors with other incident evidence;
+query one of those IDs with the same snapshot to investigate another area. These are exact-ID,
+one-hop reads of saved evidence: no model or indexer is invoked. Each assertion retains its own
+citations, authority and review state, including multiple assertions about the same edge.
+Page completion does not establish complete product coverage. See [the query contract](docs/ADR-029-exact-graph-neighborhoods.md).
+
+The development checkout now preserves typed `CodeSymbol` definitions and individual SCIP
+references, including local symbols, repeated same-file uses and one-based UTF-16 columns.
+From a physical-file node, request incoming `definedBy` facts to discover its symbols; from a
+symbol, request incoming/outgoing `references` to inspect exact occurrences. Native lexical
+enclosure is not a call graph. Resolution distinguishes indexed definitions, declaration-only
+targets and absent indexed definitions. Local ordinal IDs are scoped to the exact index; refresh
+code evidence before comparing revisions. See [code evidence and limits](docs/ADR-032-scip-code-evidence.md).
+The development checkout also resolves explicit Markdown symbol selectors in selected documents:
+
+```md
+[helper](../src/worker.ts#weftlet-symbol=Engine.execute)
+[implementation](../src/worker.ts#weftlet-symbol=execute "weftlet:implementedBy invariant:max-age")
+[check](../test/worker.test.ts#weftlet-symbol=check "weftlet:verifiedBy invariant:max-age")
+```
+
+The first link creates a Document→references→CodeSymbol relationship. The annotated forms require
+an exact existing business-node ID from the graph; discover it with `impact.scan`/`graph.neighbors`.
+They declare a mapping and retain its supporting assertions and review state. They do not prove
+that the implementation fulfills the rule or that a test passed. No function name or nearby prose
+automatically creates an implementation mapping. Approved source documents remain distinguishable
+from unreviewed extracted assertions.
+
+Selectors match an exact indexed name, symbol ID, or unambiguous native lexical name such as
+`Engine.execute` in the named file. For an alias or a specific occurrence, supply both one-based
+UTF-16 coordinates, for example `#weftlet-symbol=publicAlias&weftlet-line=1&weftlet-column=23`.
+The graph retains both the selected occurrence and all indexed target definitions, with digests
+and commit SHAs. Missing/ambiguous targets produce cited `implementationGaps`, with no guessed link.
+An indexed `.d.ts` declaration stays declaration-only. These links use the existing configured
+semantic/document-traversal scope and SCIP selection; they require no extra provider call.
+Validation documents stay outside intent extraction and can declare `verifiedBy`, not `implementedBy`.
+See [ADR 033](docs/ADR-033-document-symbol-bindings.md) for bounds and draft-overlay behavior.
+
+These capabilities are pending the next npm candidate. The development checkout now also derives
+`calls` from actual TypeScript call/new syntax and exact SCIP identities. Query a function's
+incoming/outgoing `calls` to inspect callers/callees, or follow a bounded path using `calls` and
+`implementedBy`. Each assertion retains callsite and endpoint proofs, with explicit bodyless,
+external, optional and member-dispatch limits. Runtime execution is not implied. Values, callbacks
+and dynamic dispatch without a known target remain references and cited gaps. See
+[ADR 035](docs/ADR-035-static-call-evidence.md). The remaining inferred-mapping proposal is
+recorded separately in [ADR 034](docs/ADR-034-mapping-gaps.md).
+
+Selected Markdown documents can now declare producer guarantees and consumer requirements in
+optional `weftlet-obligation` JSON fences. Both sides name an exact scoped/versioned queue or
+stored-data contract and a repository endpoint. Agents retrieve these through `emits`/`consumes`
+neighborhoods and paths, with the original statement, citations and any documented domain, stage,
+constraint/unit and consumer revalidation requirement. Missing fields remain unknown. Declarations
+do not establish fulfillment, runtime delivery or compatibility; ordinary prose is not automatically
+converted into this format. See [the declaration format and example](docs/ADR-036-contract-obligation-declarations.md).
+This addition is also pending the next npm candidate.
+
+For two retrieved obligation facts, the development checkout also supports:
+
+```sh
+weftlet graph compatibility --snapshot <snapshot-id> --producer-fact <fact-id> --consumer-fact <fact-id> --json
+```
+
+MCP `graph.compatibility` uses `snapshotId`, `producerFactId` and `consumerFactId`. It compares
+explicit numeric constraints with matching domain, measurement stage, units and contract version.
+Results distinguish compatible limits, an insufficient guarantee, disjoint limits, required
+consumer revalidation and unknowns. Both original citations and source approvals remain visible.
+This advisory assessment does not establish code fulfillment or a CI policy violation. See
+[comparison semantics and limits](docs/ADR-037-selected-contract-compatibility.md). The command
+reads saved evidence during edits without rebuilding it; it is pending the next npm candidate.
+
+Saved repository code coverage is separate from the returned-page relationship counts:
+
+```sh
+weftlet graph coverage --snapshot <snapshot-id> --max-items 20 --json
+weftlet graph coverage --snapshot <snapshot-id> --project services/api --max-items 50 --json
+```
+
+MCP `graph.coverage` accepts the same snapshot and an optional exact `projectRoot`; follow
+`selection.continuation` with identical arguments. It first pages package boundaries, then files
+within a chosen boundary. Reports distinguish `codeRoots`, requested SCIP entries, actual indexed
+documents, omitted files/packages, cross-package code references and unresolved/declaration-only
+targets. A selected directory or an import does not guarantee its files were indexed: configure
+`scip.sourceProject.include` and aliases for the intended code scope. Other indexer invocations
+retain unknown entry selection. Old snapshots without inventory report unknown coverage.
+The overview also appears in agent queries and the viewer; zero observations never prove no
+business impact. This is TypeScript-family source coverage grouped by nearest `package.json`,
+not universal language or compiler-project coverage. See [ADR 038](docs/ADR-038-monorepo-code-coverage.md).
+This feature requires a fresh snapshot from 0.7.0 or later (assembly 12); unchanged semantic
+artifacts remain reusable.
+
+The CLI also supports paths between two exact IDs:
+
+```sh
+weftlet graph paths --snapshot <snapshot-id> --from <node-id> --to <node-id> --direction both --max-depth 8 --json
+```
+
+MCP `graph.paths` takes `snapshotId`, `fromNodeId` and `toNodeId`. Direction defaults to outgoing;
+use `predicates` to select relations. `maxPaths` (default 5, up to 20) bounds page results;
+`maxSteps` (default 1000, up to 10000) bounds new candidate-edge examinations. Depth is 1–32;
+the search's total ceiling is 100,000 examinations. Responses report replay work separately.
+Follow `search.continuation` with identical inputs even if a work page contains no completed
+path. Depth cuts and total-work exhaustion remain explicit without pretending all dependencies
+were checked; inspect `frontier` and restart with greater depth or narrower endpoints/relations.
+Paths are deterministic cited associations, not shortest routes or proof of business compatibility.
+The HTML viewer uses the same engine and continuation on its displayed facts and selected layers.
+See [path semantics and limits](docs/ADR-030-bounded-evidence-paths.md).
+
 Semantic hydration requires a working configured provider. Direct RDF is the default;
 Docker/openCAESAR is an optional explicit backend. Run `context-graph doctor` for setup diagnostics.
 Committed indexing and ontology input use disposable archives, preserving the active checkout.
@@ -413,3 +530,53 @@ for observed gaps and the distinction between retrieval measurements and live se
 
 Apache-2.0. See [LICENSE](LICENSE), [NOTICE](NOTICE), and the
 [source inventory](docs/SOURCE-INVENTORY.md) for attribution and extraction history.
+
+## Optional mapping proposals (0.7.0)
+
+When an approved document describes a rule and links implementation files without naming the
+function, Weftlet can propose an exact rule-to-function mapping. This is opt-in, unreviewed
+inference; it never approves intent, proves compliance, or adds edges to the saved graph.
+Live model accuracy and usefulness validation are tentative and deferred to acceptance testing.
+The maintainer authorized including this optional feature in the 0.7.0 acceptance candidate;
+existing Codex hydration results do not establish the quality of these new proposals.
+
+Create `mapping-request.json` using a saved snapshot and its exact graph IDs:
+
+```json
+{
+  "snapshotId": "<saved-snapshot-id>",
+  "ruleId": "invariant:freshness",
+  "documentPath": "docs/owner.md",
+  "files": ["src/observations.ts"],
+  "maxCandidates": 8,
+  "maxInputBytes": 32768
+}
+```
+
+```sh
+weftlet mappings plan --request mapping-request.json
+# Review readiness, source/code proofs, exclusions, input size and expected requests.
+weftlet mappings propose --request mapping-request.json --allow-model
+weftlet mappings read --snapshot <saved-snapshot-id> --key <returned-key>
+```
+
+No configuration switch enables automatic inference. The proposal command reuses the existing
+`semantic` model, reasoning and explicit authentication selection: Codex ChatGPT login remains
+the default; configured API-key mode is optional. A compatible module must separately export
+`createMappingProposalProvider(config)` with matching `identity` and
+`propose(input, { signal, timeoutMs })`; an ordinary semantic module is insufficient. There is
+one provider request per invocation, no automatic retry, and cache hits require no `--allow-model`.
+Prompt/schema bytes and candidate count are bounded; these do not represent a dollar/token cap.
+
+MCP `mapping.plan` returns the same no-model preview; `mapping.proposals` reads a saved result by
+snapshot/key. Neither MCP tool invokes a provider. Agents must treat rationale as untrusted model
+content and follow the cited rule and exact symbol IDs. The CLI reports progress on stderr using
+opaque IDs; `--quiet` suppresses progress. Provider failures preserve all existing graph evidence.
+
+Refresh a committed snapshot using this candidate to record code coverage before proposing.
+Missing indexing/ownership, unresolved document selectors and budget overflow block inference.
+Historical evidence stays labeled historical; working edits are excluded and draft-overlay
+proposal generation is not yet supported. Saved artifacts live in the configured graph storage
+under `artifacts/mapping-proposals`; they may contain private rule/code identities and rationale.
+Keep them with the consumer. See [ADR 039](docs/ADR-039-mapping-proposals.md) for exact scope,
+caching and authority, and [the public evaluation protocol](evaluations/mapping-proposals/README.md).

package/THIRD_PARTY_NOTICES.md

@@ -20,7 +20,7 @@ Do not edit this file manually.
 | `@sourcegraph/scip-typescript` | 0.4.0 | Apache-2.0 | [link](https://github.com/sourcegraph/scip-typescript#readme) |
 | `@traqula/chevrotain` | 1.1.0 | Apache-2.0 | [link](https://github.com/comunica/traqula#readme) |
 | `canonicalize` | 1.0.8, 2.1.0 | Apache-2.0 | [link](https://github.com/erdtman/canonicalize#readme) |
-| `typescript` | 5.9.3 | Apache-2.0 | [link](https://www.typescriptlang.org/) |
+| `typescript` | 5.5.4, 5.9.3 | Apache-2.0 | [link](https://www.typescriptlang.org/) |
 | `lru-cache` | 11.5.3 | BlueOak-1.0.0 | [link](https://github.com/isaacs/node-lru-cache#readme) |
 | `domelementtype` | 2.3.0 | BSD-2-Clause | [link](https://github.com/fb55/domelementtype#readme) |
 | `domhandler` | 5.0.3 | BSD-2-Clause | [link](https://github.com/fb55/domhandler#readme) |

package/dist/application/application.d.ts

@@ -1,3 +1,7 @@
+import { SavedGraphExplorationService } from "./saved-exploration.js";
+import { SavedGraphPathService } from './saved-paths.js';
+import { SavedContractCompatibilityService } from './saved-compatibility.js';
+import { SavedCodeCoverageService } from './saved-code-coverage.js';
 import { SavedEvidenceQueryService } from "./saved-evidence.js";
 import { AgentSemanticScopeResolver } from "./agent-context.js";
 import type { ContextGraphAdapter, ContextGraphRepository } from "@weftlet/core";
@@ -6,6 +10,7 @@ import { ContextGraphHydrator } from "./hydrator.js";
 import { OpenCaesarOntologyCompiler, DirectRdfOntologyCompiler } from "../extraction/ontology.js";
 import { FileSnapshotStore } from "../storage/storage.js";
 import { SnapshotChecks } from "./snapshot-checks.js";
+import { MappingProposalService } from './mapping-proposals.js';
 export declare function loadContextGraphAdapterModule(moduleSpecifier: string | undefined, repository: ContextGraphRepository, repositoryRoot?: string): Promise<ContextGraphAdapter>;
 export declare function createContextGraphApplication(configPath: string): Promise<{
     storageRoot: string;
@@ -14,9 +19,14 @@ export declare function createContextGraphApplication(configPath: string): Promi
     ontologyCompiler: OpenCaesarOntologyCompiler | DirectRdfOntologyCompiler;
     hydrator: ContextGraphHydrator;
     queryService: SavedEvidenceQueryService;
+    explorationService: SavedGraphExplorationService;
+    pathService: SavedGraphPathService;
+    compatibilityService: SavedContractCompatibilityService;
+    codeCoverageService: SavedCodeCoverageService;
     snapshotChecks: SnapshotChecks;
     scopeResolver: AgentSemanticScopeResolver | undefined;
     headName: string;
+    mappingProposalService: MappingProposalService;
     config: import("../configuration/config.js").ContextGraphConfig;
     configPath: string;
     repositoryRoot: string;

package/dist/application/application.js

@@ -1,4 +1,12 @@
 // Modified for standalone extraction; see docs/extraction-manifest.json.
+import { SavedGraphExplorationService } from "./saved-exploration.js";
+import { SnapshotGraphExplorationService } from "../graph/neighborhood.js";
+import { SnapshotGraphPathService } from '../graph/paths.js';
+import { SavedGraphPathService } from './saved-paths.js';
+import { SnapshotContractCompatibilityService } from '../graph/compatibility.js';
+import { SavedContractCompatibilityService } from './saved-compatibility.js';
+import { SnapshotCodeCoverageService } from '../graph/code-coverage.js';
+import { SavedCodeCoverageService } from './saved-code-coverage.js';
 import { SavedEvidenceQueryService } from "./saved-evidence.js";
 import { sha256, stableJson } from "../infrastructure/util.js";
 import { AgentSemanticScopeResolver, PreparedImpactQueryService } from "./agent-context.js";
@@ -17,6 +25,9 @@ import { OtlpJsonRuntimeEvidenceProvider } from "../extraction/telemetry.js";
 import { SnapshotChecks } from "./snapshot-checks.js";
 import { resolveConsumerModule } from "../infrastructure/module-resolution.js";
 import { requiredSnapshotExtractorVersions } from './extraction-identity.js';
+import { MappingProposalService } from './mapping-proposals.js';
+import { FileMappingProposalStore } from '../storage/mapping-proposals.js';
+import { createMappingProvider, mappingProviderIdentity } from '../extraction/mapping-provider.js';
 const emptyAdapter = {
     factExtractors: [],
     invariantEvaluators: [],
@@ -87,8 +98,17 @@ export async function createContextGraphApplication(configPath) {
         ontologyCompiler,
         hydrator,
         queryService,
+        explorationService: new SavedGraphExplorationService(new SnapshotGraphExplorationService(snapshotStore), repository, sha256(stableJson(config)), expectedExtractors),
+        pathService: new SavedGraphPathService(new SnapshotGraphPathService(snapshotStore), repository, sha256(stableJson(config)), expectedExtractors),
+        compatibilityService: new SavedContractCompatibilityService(new SnapshotContractCompatibilityService(snapshotStore), repository, sha256(stableJson(config)), expectedExtractors),
+        codeCoverageService: new SavedCodeCoverageService(new SnapshotCodeCoverageService(snapshotStore), repository, sha256(stableJson(config)), expectedExtractors),
         snapshotChecks: new SnapshotChecks(snapshotStore, repository, hydrator, scopeResolver, sha256(stableJson(config)), expectedExtractors),
         scopeResolver,
         headName,
+        mappingProposalService: new MappingProposalService(repository, snapshotStore, new FileMappingProposalStore(storageRoot), {
+            repositoryId: config.repositoryId, configurationDigest: sha256(stableJson(config)), expectedExtractors,
+            providerIdentity: mappingProviderIdentity(config.semantic), timeoutMs: config.semantic.timeoutMs ?? 120_000,
+            provider: () => createMappingProvider(config.semantic, repositoryRoot),
+        }),
     };
 }

package/dist/application/document-code-bindings.d.ts

@@ -0,0 +1,11 @@
+import type { ExtractionContext, GraphFact } from '@weftlet/core';
+import type { ContextGraphConfig } from '../configuration/config.js';
+import type { GitRepository } from '../repository/git.js';
+import type { HydrationInputs } from './hydration-inputs.js';
+import { type BindingSource } from '../extraction/document-code-bindings.js';
+/** Uses the already selected committed scope; validation documents remain separately classified. */
+export declare function assembleDocumentCodeBindings(repository: GitRepository, context: ExtractionContext, inputs: HydrationInputs, config: ContextGraphConfig, codeFacts: readonly GraphFact[], subjectFacts: readonly GraphFact[]): Promise<{
+    facts: readonly GraphFact[];
+    diagnostics: readonly import("@weftlet/core").GraphDiagnostic[];
+}>;
+export declare function selectedDocumentSources(repository: GitRepository, context: ExtractionContext, inputs: HydrationInputs, config: ContextGraphConfig): Promise<readonly BindingSource[]>;

package/dist/application/document-code-bindings.js

@@ -0,0 +1,25 @@
+import { extractDocumentCodeBindings } from '../extraction/document-code-bindings.js';
+import { matchesRepositoryGlob } from '../repository/glob.js';
+/** Uses the already selected committed scope; validation documents remain separately classified. */
+export async function assembleDocumentCodeBindings(repository, context, inputs, config, codeFacts, subjectFacts) {
+    return extractDocumentCodeBindings(repository, context, await selectedDocumentSources(repository, context, inputs, config), codeFacts, subjectFacts);
+}
+export async function selectedDocumentSources(repository, context, inputs, config) {
+    const byPath = new Map(inputs.sources.map(source => [source.path, source]));
+    const evidence = inputs.documentEvidence;
+    const classified = new Map(evidence?.classification.documents.map(document => [document.path, document]));
+    const sources = [];
+    const paths = evidence ? evidence.traversal.documents.filter(document => document.status === 'read').map(document => document.path) : [...byPath.keys()];
+    for (const path of paths) {
+        let source = byPath.get(path);
+        if (!source) {
+            const document = evidence.traversal.documents.find(document => document.path === path);
+            source = { path, content: await repository.readFileAt(context.commitSha, path), digest: document.digest, stableSemanticId: `document:${path}` };
+        }
+        const classification = classified.get(path);
+        sources.push({ ...source, metadata: classification ? { sourceAuthority: classification.sourceAuthority,
+                sourceRole: classification.sourceRole, sourceOwnership: classification.ownership, sourcePolicyDigest: evidence.classification.policyDigest }
+                : { sourceAuthority: config.approvedIntentSources?.some(pattern => matchesRepositoryGlob(path, pattern)) ? 'declared' : 'inferred' } });
+    }
+    return sources;
+}

package/dist/application/document-obligations.d.ts

@@ -0,0 +1,8 @@
+import type { ExtractionContext } from '@weftlet/core';
+import type { ContextGraphConfig } from '../configuration/config.js';
+import type { GitRepository } from '../repository/git.js';
+import type { HydrationInputs } from './hydration-inputs.js';
+export declare function assembleDocumentObligations(repository: GitRepository, context: ExtractionContext, inputs: HydrationInputs, config: ContextGraphConfig): Promise<{
+    facts: readonly import("@weftlet/core").GraphFact[];
+    diagnostics: readonly import("@weftlet/core").GraphDiagnostic[];
+}>;

package/dist/application/document-obligations.js

@@ -0,0 +1,11 @@
+import { selectedDocumentSources } from './document-code-bindings.js';
+import { matchesRepositoryGlob } from '../repository/glob.js';
+import { extractDocumentObligations } from '../extraction/document-obligations.js';
+export async function assembleDocumentObligations(repository, context, inputs, config) {
+    const sources = await selectedDocumentSources(repository, context, inputs, config);
+    const validation = (path) => config.evidenceRoots.some(root => root === '.' || path === root ||
+        path.startsWith(`${root.replace(/\/$/, '')}/`) || matchesRepositoryGlob(path, root) || matchesRepositoryGlob(path, `${root}/**`));
+    return extractDocumentObligations(repository, context, sources.map(source => ({ ...source,
+        metadata: { ...source.metadata, sourceRole: source.metadata.sourceRole ?? (validation(source.path) ? 'validation' :
+                source.metadata.sourceAuthority === 'declared' ? 'intent' : 'unclassified') } })));
+}

package/dist/application/draft-facts.d.ts

@@ -0,0 +1,3 @@
+import type { GraphFact } from '@weftlet/core';
+/** Rewrite proof references after code facts receive draft identities; never retain disposable Git SHAs. */
+export declare function draftFacts(facts: readonly GraphFact[], snapshotId: string, baseSha: string): readonly GraphFact[];

package/dist/application/draft-facts.js

@@ -0,0 +1,37 @@
+import { sha256, stableJson } from '../infrastructure/util.js';
+/** Rewrite proof references after code facts receive draft identities; never retain disposable Git SHAs. */
+export function draftFacts(facts, snapshotId, baseSha) {
+    const rewritten = new Map();
+    const span = (citation) => ({ ...citation, commitSha: baseSha });
+    const make = ({ id: previousId, ...fact }) => {
+        const rewrite = (binding) => {
+            const proofs = (items) => items.map(item => ({ ...item, factId: rewritten.get(item.factId)?.id ?? item.factId, provenance: span(item.provenance) }));
+            return { ...binding, documentCitations: binding.documentCitations.map(span), selectedOccurrences: proofs(binding.selectedOccurrences),
+                definitions: proofs(binding.definitions), subjectEvidence: binding.subjectEvidence.map(item => {
+                    const updated = rewritten.get(item.factId);
+                    return updated ? { factId: updated.id, provenance: updated.provenance,
+                        ...(updated.authority === undefined ? {} : { authority: updated.authority }),
+                        ...(updated.sourceAuthority === undefined ? {} : { sourceAuthority: updated.sourceAuthority }),
+                        ...(updated.extractionReview === undefined ? {} : { extractionReview: updated.extractionReview }) } : item;
+                }) };
+        };
+        const draft = { ...fact, snapshotId, authority: 'draft',
+            ...(fact.codeBinding || fact.extractor.id === 'routing-declaration-extractor' || fact.sourceRole !== undefined ? { sourceAuthority: 'draft' } : {}),
+            ...(fact.codeBinding ? { codeBinding: rewrite(fact.codeBinding) } : {}), provenance: span(fact.provenance) };
+        if (draft.codeCall) {
+            const proofs = (items) => items.map(item => ({
+                factId: rewritten.get(item.factId)?.id ?? item.factId, provenance: span(item.provenance)
+            }));
+            draft.codeCall = { ...draft.codeCall, callerDefinitions: proofs(draft.codeCall.callerDefinitions),
+                targetOccurrences: proofs(draft.codeCall.targetOccurrences), targetDefinitions: proofs(draft.codeCall.targetDefinitions) };
+        }
+        if (draft.contractObligation)
+            draft.contractObligation = { ...draft.contractObligation,
+                endpointSource: span(draft.contractObligation.endpointSource) };
+        const result = { ...draft, id: sha256(stableJson(draft)) };
+        rewritten.set(previousId, result);
+        return result;
+    };
+    return [...facts.filter(fact => !fact.codeBinding && !fact.codeCall).map(make),
+        ...facts.filter(fact => fact.codeCall).map(make), ...facts.filter(fact => fact.codeBinding).map(make)];
+}

package/dist/application/extraction-identity.d.ts

@@ -1,6 +1,6 @@
 import type { ContextGraphConfig } from '../configuration/config.js';
-export declare const graphAssemblyVersion = 7;
-export declare const graphAssemblyIdentity = "standalone-graph-v7";
+export declare const graphAssemblyVersion = 12;
+export declare const graphAssemblyIdentity = "standalone-graph-v12";
 export declare function documentExtractionVersions(config?: Pick<ContextGraphConfig, 'documentTraversal'>): Readonly<Record<string, string>>;
 /** Runtime expectations are separate from source/configuration identity and artifact reuse. */
 export declare function requiredSnapshotExtractorVersions(config?: Pick<ContextGraphConfig, 'routingSources' | 'documentTraversal'>): Readonly<Record<string, string>>;

package/dist/application/extraction-identity.js

@@ -1,8 +1,11 @@
+import { documentCodeBindingIdentity } from '../extraction/document-code-bindings.js';
+import { staticCallIdentity } from '../extraction/static-calls.js';
+import { documentObligationIdentity } from '../extraction/document-obligations.js';
 import { repositoryContractExtractorIdentity, scipSymbolExtractorIdentity } from '../extraction/static.js';
 import { routingExtractorIdentity } from '../extraction/routing.js';
 import { documentEvidenceExtractorIdentity } from '../extraction/document-evidence.js';
 import { documentSelectionIdentity } from './hydration-inputs.js';
-export const graphAssemblyVersion = 7;
+export const graphAssemblyVersion = 12;
 export const graphAssemblyIdentity = `standalone-graph-v${graphAssemblyVersion}`;
 export function documentExtractionVersions(config) {
     return config?.documentTraversal ? { 'document-selection': documentSelectionIdentity,
@@ -11,6 +14,9 @@ export function documentExtractionVersions(config) {
 /** Runtime expectations are separate from source/configuration identity and artifact reuse. */
 export function requiredSnapshotExtractorVersions(config) {
     return { assembly: graphAssemblyIdentity,
+        [documentCodeBindingIdentity.id]: documentCodeBindingIdentity.version,
+        [staticCallIdentity.id]: staticCallIdentity.version,
+        [documentObligationIdentity.id]: documentObligationIdentity.version,
         ...documentExtractionVersions(config),
         [repositoryContractExtractorIdentity.id]: repositoryContractExtractorIdentity.version,
         [scipSymbolExtractorIdentity.id]: scipSymbolExtractorIdentity.version,

package/dist/application/extractor-results.d.ts

@@ -0,0 +1,6 @@
+import type { ExtractionContext, FactExtractor } from '@weftlet/core';
+/** Stateless per-invocation results retain adapter gaps without changing existing adapters. */
+export declare function extractEvidence(extractors: readonly FactExtractor[], context: ExtractionContext): Promise<{
+    facts: import("@weftlet/core").GraphFact[];
+    diagnostics: import("@weftlet/core").GraphDiagnostic[];
+}>;

package/dist/application/extractor-results.js

@@ -0,0 +1,6 @@
+/** Stateless per-invocation results retain adapter gaps without changing existing adapters. */
+export async function extractEvidence(extractors, context) {
+    const results = await Promise.all(extractors.map(async (extractor) => extractor.extractWithDiagnostics
+        ? extractor.extractWithDiagnostics(context) : { facts: await extractor.extract(context), diagnostics: [] }));
+    return { facts: results.flatMap(result => result.facts), diagnostics: results.flatMap(result => result.diagnostics) };
+}

package/dist/application/hydrator.js

@@ -1,7 +1,14 @@
 import { scipSourcePatterns } from '../configuration/scip-project.js';
+import { buildCodeInventory } from '../extraction/code-inventory.js';
 import { contractPatternRoots } from "../repository/glob.js";
 import { repositoryFileExtractorIdentity, repositoryContractExtractorIdentity, scipSymbolExtractorIdentity } from '../extraction/static.js';
 import { sha256, stableJson } from "../infrastructure/util.js";
+import { assembleDocumentCodeBindings } from './document-code-bindings.js';
+import { documentCodeBindingIdentity } from '../extraction/document-code-bindings.js';
+import { documentObligationIdentity } from '../extraction/document-obligations.js';
+import { assembleDocumentObligations } from './document-obligations.js';
+import { staticCallIdentity } from '../extraction/static-calls.js';
+import { extractEvidence } from './extractor-results.js';
 import { documentLinkerIdentity, linkSemanticDocuments } from "../extraction/document.js";
 import { repositoryNodeIdentityVersion } from '../extraction/repository-nodes.js';
 import { selectHydrationInputs, classifyHydratedFacts, documentSelectionIdentity } from './hydration-inputs.js';
@@ -114,6 +121,7 @@ export class ContextGraphHydrator {
         };
         // Validate committed routing inputs before invoking any provider or indexer.
         const routing = await extractRoutingDeclarations(repository, context, config.routingSources ?? []);
+        const obligations = await assembleDocumentObligations(repository, context, selection, config);
         const { hydrated, semanticExtracted, semanticReused } = await hydrateSemanticSources({
             sources, context, config: config.semantic, configurationDigest,
             hydrator: this.dependencies.semanticHydrator, forceRevision,
@@ -147,7 +155,10 @@ export class ContextGraphHydrator {
         checkpoint();
         options.onProgress?.({ phase: 'index-typescript' });
         const scip = await this.dependencies.staticIndexer.index(context);
-        const extractorFacts = (await Promise.all(this.dependencies.extractorFactory(scip).map((extractor) => extractor.extract(context)))).flat();
+        const codeInventory = buildCodeInventory(await repository.listEntriesAt(commitSha), await repository.listFilesAt(commitSha, config.codeRoots), config.codeRoots, config.scip.sourceProject, scip);
+        const extracted = await extractEvidence(this.dependencies.extractorFactory(scip), context);
+        const extractorFacts = extracted.facts;
+        diagnostics.push(...extracted.diagnostics);
         const trackedPaths = await repository.listAllFilesAt(commitSha);
         const tracked = new Set(trackedPaths);
         for (const fact of semanticFacts) {
@@ -163,14 +174,15 @@ export class ContextGraphHydrator {
             }
         }
         const documents = linkSemanticDocuments(context, hydrated, trackedPaths, sources.filter((source) => config.approvedIntentSources?.some((pattern) => matchesRepositoryGlob(source.path, pattern))).map((source) => source.path), { canonicalReferences: !config.documentTraversal });
-        diagnostics.push(...documents.diagnostics);
+        const bindings = await assembleDocumentCodeBindings(repository, context, selection, config, extractorFacts, [...semanticFacts, ...extractorFacts, ...routing.facts, ...obligations.facts]);
+        diagnostics.push(...documents.diagnostics, ...bindings.diagnostics, ...obligations.diagnostics);
         diagnostics.push(...routing.diagnostics, ...(selection.documentEvidence?.diagnostics ?? []));
         checkpoint();
         const runtimeEvidence = runtimeRevision.references;
         const runtimeFacts = runtimeEvidenceFacts(context, runtimeEvidence);
         const structuralFacts = selection.documentEvidence?.facts.map(fact => ({ ...fact, snapshotId })) ?? [];
         const facts = [...semanticFacts, ...classifyHydratedFacts(documents.facts, selection.documentEvidence),
-            ...structuralFacts, ...extractorFacts, ...routing.facts, ...runtimeFacts].sort((left, right) => left.id.localeCompare(right.id));
+            ...structuralFacts, ...extractorFacts, ...bindings.facts, ...routing.facts, ...obligations.facts, ...runtimeFacts].sort((left, right) => left.id.localeCompare(right.id));
         const validationCounts = { factCount: facts.length };
         await measureValidationPhase('validate-identities', validationCounts, options.onProgress, () => {
             const report = assertGraphIdentities(facts, {
@@ -207,6 +219,7 @@ export class ContextGraphHydrator {
             unresolved,
             diagnostics,
             semanticSources: selectedSemanticSources,
+            codeInventory,
             ...(selection.documentSelection ? { documentSelection: selection.documentSelection } : {}),
         };
         const contentDigest = sha256(stableJson(logical));
@@ -220,6 +233,7 @@ export class ContextGraphHydrator {
                 snapshotId,
                 configurationDigest,
                 scope: scopePaths,
+                codeInventory,
                 ...(selection.documentSelection ? { documentSelection: selection.documentSelection } : {}),
                 ontologyVersion: config.semantic.ontologyVersion,
                 extractorVersions: {
@@ -227,8 +241,11 @@ export class ContextGraphHydrator {
                     ...documentExtractionVersions(config),
                     [repositoryContractExtractorIdentity.id]: repositoryContractExtractorIdentity.version,
                     [scipSymbolExtractorIdentity.id]: scipSymbolExtractorIdentity.version,
+                    [staticCallIdentity.id]: staticCallIdentity.version,
                     'repository-node-identity': String(repositoryNodeIdentityVersion),
                     [documentLinkerIdentity.id]: documentLinkerIdentity.version,
+                    [documentCodeBindingIdentity.id]: documentCodeBindingIdentity.version,
+                    [documentObligationIdentity.id]: documentObligationIdentity.version,
                     ...(config.routingSources?.length ? { [routingExtractorIdentity.id]: routingExtractorIdentity.version } : {}),
                     semantic: config.semantic.extractorVersion,
                     scip: scip.version,

package/dist/application/mapping-proposals.d.ts

@@ -0,0 +1,108 @@
+import type { ContextPack, MappingProposalArtifact, MappingProposalProvider, MappingProposalRequest, MappingProposalStore, SnapshotStore } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+export interface MappingOperationOptions {
+    readonly allowModel?: boolean;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (event: {
+        phase: 'plan' | 'reuse' | 'provider' | 'validate' | 'saved';
+        operationId: string;
+        elapsedMs: number;
+    }) => void;
+}
+export declare class MappingProposalService {
+    private readonly repository;
+    private readonly snapshots;
+    private readonly artifacts;
+    private readonly settings;
+    constructor(repository: GitRepository, snapshots: Pick<SnapshotStore, 'read'>, artifacts: MappingProposalStore, settings: {
+        repositoryId: string;
+        configurationDigest: string;
+        expectedExtractors: Readonly<Record<string, string>>;
+        providerIdentity: string;
+        timeoutMs: number;
+        provider: () => MappingProposalProvider;
+    });
+    private snapshot;
+    private evidence;
+    private key;
+    private validate;
+    plan(value: MappingProposalRequest): Promise<{
+        evidenceState: {
+            readonly currentCommit?: string;
+            readonly excludedWorkingChanges: readonly string[];
+            readonly capturedWorkingChanges?: readonly string[];
+            readonly changedSinceCapture?: readonly string[];
+            readonly overlayFreshness?: "current" | "stale" | "unknown";
+            readonly stale: boolean;
+            readonly configurationMatches: boolean;
+            readonly extractionCompatible?: boolean;
+            readonly incompatibleExtractors?: readonly string[];
+            readonly eligibleForCurrentDiffValidation: false;
+        };
+        key: string;
+        cached: boolean;
+        expectedModelRequests: number;
+        timeoutMs: number;
+        automaticRetries: number;
+        markdown: string;
+        ready: boolean;
+        issues: {
+            readonly code: string;
+            readonly path?: string;
+        }[];
+        version: "mapping-proposal-v1";
+        request: Required<MappingProposalRequest>;
+        snapshot: ContextPack["snapshot"];
+        snapshotDigest: string;
+        subjectEvidence: readonly import("@weftlet/core").GraphFact[];
+        associations: readonly import("@weftlet/core").GraphFact[];
+        candidates: readonly import("@weftlet/core").MappingCandidate[];
+        candidateEnumeration: {
+            readonly complete: boolean;
+            readonly observed: number;
+            readonly returned: number;
+        };
+        excluded: readonly {
+            readonly path: string;
+            readonly reason: string;
+            readonly count: number;
+        }[];
+        inputBytes: number;
+        inputDigest: string;
+    }>;
+    read(snapshotId: string, key: string): Promise<{
+        artifact: MappingProposalArtifact;
+        reused: boolean;
+        evidenceState: {
+            readonly currentCommit?: string;
+            readonly excludedWorkingChanges: readonly string[];
+            readonly capturedWorkingChanges?: readonly string[];
+            readonly changedSinceCapture?: readonly string[];
+            readonly overlayFreshness?: "current" | "stale" | "unknown";
+            readonly stale: boolean;
+            readonly configurationMatches: boolean;
+            readonly extractionCompatible?: boolean;
+            readonly incompatibleExtractors?: readonly string[];
+            readonly eligibleForCurrentDiffValidation: false;
+        } | undefined;
+        markdown: string;
+    }>;
+    private report;
+    propose(value: MappingProposalRequest, options?: MappingOperationOptions): Promise<{
+        artifact: MappingProposalArtifact;
+        reused: boolean;
+        evidenceState: {
+            readonly currentCommit?: string;
+            readonly excludedWorkingChanges: readonly string[];
+            readonly capturedWorkingChanges?: readonly string[];
+            readonly changedSinceCapture?: readonly string[];
+            readonly overlayFreshness?: "current" | "stale" | "unknown";
+            readonly stale: boolean;
+            readonly configurationMatches: boolean;
+            readonly extractionCompatible?: boolean;
+            readonly incompatibleExtractors?: readonly string[];
+            readonly eligibleForCurrentDiffValidation: false;
+        } | undefined;
+        markdown: string;
+    }>;
+}