@weftlet/toolkit 0.6.1 → 0.7.1

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.1` and `@weftlet/core@0.7.1`.
 <!-- weftlet:release:end -->
 
 Weftlet uses `@weftlet/toolkit`; its neutral `@weftlet/core` dependency is installed
@@ -228,24 +228,31 @@ its sidecar policy is not automatically adopted by hydration. See
 
 Starting with **0.5.0**, identity preflight runs before ontology/RDF work.
 `hydrate --json --quiet` reports conflicts using opaque references; `--validation-details` explicitly
-includes local identities, producer versions and citations. Validation emits phase-boundary times
-and graph counts, without a percentage or live heartbeat. Full SHACL remains required after a
+includes local identities, producer versions and citations. Validation emits phase timings,
+graph counts and completed validation groups. These are not completion-time estimates. Full SHACL remains required after a
 passing preflight. See [ADR 021](docs/ADR-021-identity-preflight-and-validation-timing.md).
 
 Version 0.5.0 also accepts `semantic.timeoutMs: 600000` for an approved ten-minute extraction
 attempt; the default remains two minutes. See [provider limits and reuse](docs/PROVIDERS.md#limits-and-reuse)
 before retrying with compatible cached artifacts.
 
-Starting with 0.3.0, the toolkit indexes a temporary union to accelerate cold validation.
-The toolkit uses JavaScript `rdf-validate-shacl` and an in-memory
-N3 store. Each hydration validates the complete graph; semantic artifact reuse does not make
-validation incremental, and there is no validation-result cache, Rust engine or GraphDB service.
-Saved queries do not rerun SHACL.
+The toolkit uses JavaScript `rdf-validate-shacl` with bounded N3 subject groups. Each hydration
+validates the complete graph; semantic artifact reuse does not make validation incremental.
+There is no validation-result cache, Rust engine or GraphDB service. Saved queries do not rerun SHACL.
 
-The current shapes use subject/predicate/object values independently of graph names. Validation
-now builds one temporary union graph so repeated property lookups avoid scanning every named
-assertion graph. The same shapes and validator run against that union. The original named dataset,
-assertion records and provenance remain the source for SPARQL, queries and serialization.
+Complete identity groups preserve conflicting assertions, and graph-wide class membership retains
+cross-record proof checks. The same strict shapes run on every target. The RDF encoder also serves
+streamed N-Quads exports and SPARQL; traversal projections have SPARQL equivalence tests. Hashing and
+snapshot JSON persistence/reload avoid a whole-graph string. Existing canonical digests, cache keys
+and immutable snapshot bytes are preserved. See [ADR 040](docs/ADR-040-bounded-graph-io.md) for the
+partition correctness boundary, public corpus regression and remaining memory limits.
+
+For large programmatic RDF exports, use `await graph.serializeTo(writable)` or consume
+`graph.serializeChunks()`. The `serialize()` convenience returns a single string and therefore
+remains subject to JavaScript's string-size limit.
+
+The 0.3.0 optimization built a complete temporary validation union. The measurements below describe
+that earlier implementation; they are not timings for the current richer code graph.
 
 In bounded, single-run public experiments, 2,000 facts with unique subject/object nodes took
 31.50 seconds in the original SHACL path, compared with 0.153 seconds to build the union and
@@ -260,12 +267,11 @@ pnpm build
 pnpm benchmark:shacl
 ```
 
-The [T05 closeout](docs/ADR-027-validation-closeout.md) measures cold, repeated and changed inputs,
-plus worker, exact-result-key and Rust prototypes. Direct full validation remains the 1.0 choice:
+The historical [T05 closeout](docs/ADR-027-validation-closeout.md) measures cold, repeated and changed inputs,
+plus worker, exact-result-key and Rust prototypes:
 the 10,000-fact public cases measured about 2.9–5.7 seconds, with material memory use. These are
 fixture measurements, not a private consumer capacity guarantee. The prototypes are development
-tools, not runtime options; every hydration still performs full validation. Current progress reports
-phase boundaries because synchronous work blocks same-thread timers. Reproduce the lifecycle study
+tools, not runtime options; every hydration still performs full validation. Reproduce that lifecycle study
 from a development checkout with `pnpm benchmark:validation`; raw results and commands are linked
 from the ADR.
 
@@ -349,6 +355,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).
+
+Starting with 0.7.0, Weftlet 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).
+Weftlet 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.
+
+Version 0.7.0 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). Optional inferred-mapping proposals are available separately; see
+[ADR 039](docs/ADR-039-mapping-proposals.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).
+These declarations are supported starting with 0.7.0.
+
+For two retrieved obligation facts, the published CLI 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 and is available starting with 0.7.0.
+
+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.
@@ -366,8 +489,8 @@ ahead of repeated detail and shared-import context. Ranking changes ordering, no
 the reachable scope. Responses identify the ranking version; after a ranking upgrade, restart
 scans whose old continuation tokens are rejected. No snapshot refresh is needed for new ordering.
 
-This source includes a [coverage reporting correction](docs/ADR-024-implementation-coverage.md)
-for the next release: code relationships displayed under contracts also count as implementation
+The published toolkit includes a [coverage reporting correction](docs/ADR-024-implementation-coverage.md)
+that counts code relationships displayed under contracts as implementation
 evidence. New reports identify `coverage.scope: "returned-page"` and `countsAreNonExclusive: true`.
 Counts can overlap and describe returned evidence; they are not completeness percentages or proof
 that behavior is correct. Document/model claims and test-only evidence do not establish production
@@ -413,3 +536,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) |
@@ -363,6 +363,7 @@ Do not edit this file manually.
 | `@comunica/utils-metadata` | 5.4.0 | MIT | [link](https://comunica.dev/) |
 | `@comunica/utils-query-operation` | 5.4.0 | MIT | [link](https://comunica.dev/) |
 | `@dabh/diagnostics` | 2.0.9 | MIT | [link](https://github.com/DABH/diagnostics) |
+| `@discoveryjs/json-ext` | 1.1.0 | MIT | [link](https://github.com/discoveryjs/json-ext#readme) |
 | `@hono/node-server` | 2.1.5 | MIT | [link](https://github.com/honojs/node-server) |
 | `@jeswr/prefixcc` | 1.2.1 | MIT | [link](https://github.com/jeswr/prefixcc.js#readme) |
 | `@jeswr/stream-to-string` | 2.0.0 | MIT | [link](https://github.com/jeswr/stream-to-string/README.md) |
@@ -376,6 +377,7 @@ Do not edit this file manually.
 | `@rdfjs/to-ntriples` | 3.0.1 | MIT | [link](https://github.com/rdfjs-base/to-ntriples) |
 | `@rdfjs/types` | 1.1.2, 2.0.1 | MIT | [link](http://rdf.js.org/) |
 | `@so-ric/colorspace` | 1.1.6 | MIT | [link](https://github.com/so-ric/colorspace) |
+| `@streamparser/json` | 0.0.26 | MIT | [link](https://github.com/juanjoDiaz/jsonparse2#readme) |
 | `@tpluscode/rdf-ns-builders` | 5.1.0 | MIT | [link](https://github.com/tpluscode/rdf-ns-builders#readme) |
 | `@traqula/algebra-sparql-1-1` | 1.4.0 | MIT | [link](https://github.com/comunica/traqula#readme) |
 | `@traqula/algebra-sparql-1-2` | 1.4.0 | MIT | [link](https://github.com/comunica/traqula#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) };
+}