@weftlet/toolkit 0.6.1 → 0.7.1

package/docs/ADR-036-contract-obligation-declarations.md

@@ -0,0 +1,124 @@
+# ADR 036: Cited producer and consumer obligations
+
+Status: B4a implemented; validation recorded separately. B4b follows in [ADR 037](ADR-037-selected-contract-compatibility.md).
+
+## Scope and choice
+
+Free-text `governedBy` assertions and explicit routing declarations already preserve business
+rules and asynchronous handoffs. They do not provide structured fields for comparing the two
+sides. B4a adds an optional deterministic declaration in selected Markdown, using existing
+`emits` and `consumes` relations to a shared Contract node. This is an exact opt-in path;
+ordinary prose remains available through existing semantic extraction. No new model prompt,
+provider schema or semantic artifact identity is introduced. Automatic conversion of prose
+into these declarations is not implemented or claimed.
+
+Use one JSON object in a `weftlet-obligation` fenced block:
+
+```weftlet-obligation
+{
+  "schemaVersion": 1,
+  "id": "execution-age",
+  "role": "requirement",
+  "endpoint": "services/execution/src/execute.ts",
+  "contract": {
+    "scope": "readings",
+    "id": "stored-reading",
+    "kind": "stored-data",
+    "version": "1"
+  },
+  "statement": "Execution revalidates reading age immediately before use.",
+  "domain": "sensors",
+  "stage": "execution",
+  "constraint": {
+    "metric": "reading-age",
+    "operator": "at-most",
+    "value": 60,
+    "unit": "seconds"
+  },
+  "revalidation": "required"
+}
+```
+
+Required fields are schemaVersion, id, role, endpoint, contract and statement. Role is
+`guarantee` (producer) or `requirement` (consumer); transport kind is `queue` or `stored-data`.
+Domain, stage, contract version, constraint and consumer revalidation are optional. A constraint
+requires a metric, finite numeric value and operator (`at-most`, `at-least`, `equal`); its unit
+may be unknown. Revalidation accepts `required` or `not-required` on consumers only. Omitted
+values stay absent in JSON/RDF and display as unknown. No default time unit, normalization,
+semantic equivalence, unit conversion or compatibility interpretation is performed.
+
+The endpoint is an exact repository-relative regular committed UTF-8 file. Its canonical physical
+kind is retained, including Evidence for test/spec files. Existing indexed facts let agents
+continue into code, but the declaration establishes neither a particular function mapping nor
+implementation correctness. Function-level mappings remain the explicit selectors in ADR 033.
+
+## Identity and authority
+
+Contract identity hashes repository ID, exact scope, contract ID, transport kind and version.
+Labels, endpoint paths and statement wording do not determine this identity. Missing version is
+unknown and does not join a named version. The namespace is explicit; equal names across scopes,
+repositories, transports or versions never imply a shared contract. Domain is a cited descriptive
+field, not an implicit identity override: contradictory descriptions are retained for review.
+
+`GraphFact.contractObligation` retains the complete typed declaration and endpoint source
+path/digest/SHA. Main provenance cites the exact Markdown fence in the original committed bytes.
+The assertion has inferred authority and deterministic extraction review. Configured source
+approval, role and traversal ownership metadata remain independent. Deterministic parsing is not
+an approval process. Plans and unclassified documents cannot silently become approved intent.
+Validation documents are excluded from obligation assertions with a cited diagnostic, including
+directly selected evidence-root documents without traversal.
+
+Both sides connect through the contract, independently of imports, calls or a particular queue
+library. This is documented dependency evidence, not observed message delivery, shared storage
+access or proof of fulfillment. Existing runtime evidence remains separately authoritative for
+what was observed. Different limits at different stages are not automatically contradictions.
+
+## Integrity, bounds and lifecycle
+
+Unknown fields, duplicate JSON keys, invalid paths, nonfinite values and unsupported enums
+produce cited extraction gaps with no partial declaration. Missing, symlink or submodule
+endpoints cannot create joins. Duplicate declaration IDs within a source retain every valid
+assertion and report ambiguity; no assertion silently wins. Document and endpoint text must
+reproduce the committed Git blob ID, rejecting lossy non-UTF-8 decoding before citing its digest.
+Contracts with only one role in
+the selected structured declarations report the missing counterpart without claiming repository-
+wide absence. No text matching or implied route fills those gaps.
+
+Extraction uses already selected committed sources, including traversal-read validation docs
+solely to report exclusions. It performs no provider call. Each block is limited to 64 KiB;
+overlong blocks report a gap. More than 500 blocks abort extraction before provider/indexer work
+instead of publishing a silently truncated set. Existing document-selection budgets still apply.
+
+RDF exposes each field on its cited assertion record. SHACL checks obligation-specific cardinality,
+types, roles, metadata and authority without adding a broad per-fact disjunction. Deterministic
+integrity checks require canonical contract/endpoint identities, role/predicate agreement, matching
+endpoint/document revision and separate implementation evidence. Shared SPARQL, neighborhoods,
+paths, impact queries, Markdown and viewer details read these same facts. SHACL checks structure;
+it does not establish business compatibility.
+
+Assembly advances from 10 to 11 and records `document-obligation-extractor@1.0.0`. Historical
+snapshots remain readable but are not compatible with current validation until refreshed.
+Unchanged semantic artifacts remain reusable. Clean hydration reproduces declarations. Full
+RDF/SHACL validation is retained; this is not incremental validation or a new graph backend.
+
+Overlays re-read declarations from captured draft bytes and replace prior obligation facts.
+Document/endpoint edits, deletes and renames regenerate or invalidate joins. All draft assertions
+and endpoint citations use the base SHA plus draft content digests, not disposable checkout SHAs.
+Known endpoint paths are included in capture; newly declared endpoints outside captured scope
+require configured scope before rebuilding. Saved committed evidence remains unchanged.
+
+## Acceptance and remaining work
+
+The independent public fixture covers stored-data and queue producers/consumers with actual
+TypeScript indexing, both freshness limits, missing fields, missing endpoints, unrelated same-name
+domains, unknown versions and test-file classification. It exercises bounded agent queries,
+SPARQL/projection parity, strict named/union SHACL, corruption negatives, unchanged semantic reuse,
+clean comparison, dirty queries and renamed/deleted draft declarations. An empty offline provider
+is deliberate: these structured assertions must come from the real declaration extractor.
+Fresh packed-consumer smoke uses the exported API and installed runtime assets.
+
+B4b's bounded compatibility acceptance is implemented in [ADR 037](ADR-037-selected-contract-compatibility.md),
+including consumer revalidation, an explicit documented incompatibility and missing evidence. Any hard failure must come from an
+explicit approved deterministic policy; model findings remain tentative. No such policy or gate
+is introduced here. Live model quality, private consumer usefulness and browser interaction remain
+separate evidence. Release PR stays open until candidate qualification.

package/docs/ADR-037-selected-contract-compatibility.md

@@ -0,0 +1,93 @@
+# ADR 037: Advisory comparison of selected contract constraints
+
+Status: implemented for the next candidate, 2026-10-30. Qualification and live usefulness remain B6.
+
+## Problem and decision
+
+[Explicit obligations](ADR-036-contract-obligation-declarations.md) retain both sides of a queue
+or stored-data boundary. A graph connection alone cannot establish that their rules agree.
+Add `graph.compatibility`, a read-only comparison of two exact saved assertion IDs, shared by
+the public API, CLI and MCP. Discover the IDs through `impact.scan` or `graph.neighbors`.
+This is a bounded numeric assessment of declarations, separate from code fulfillment, source
+approval, runtime delivery and deterministic architecture policy. It never returns a CI pass/fail.
+
+```sh
+weftlet graph compatibility --snapshot <id> --producer-fact <fact-id> --consumer-fact <fact-id> --json
+```
+
+MCP fields are `snapshotId`, `producerFactId`, `consumerFactId`. The public
+`SnapshotContractCompatibilityService` accepts a snapshot reader and exposes `assess(request)`.
+The application wrapper adds current checkout/configuration/overlay evidence state. The raw
+service has no checkout knowledge; its `evidenceState` is absent. Neither reads a mutable head,
+hydrates, invokes a model/indexer, changes a snapshot, or promotes historical evidence into a
+current-diff result. Missing storage/invalid snapshot identity is an error; missing assertions
+within a readable snapshot produce `unknown` with any surviving evidence retained.
+
+## Numeric meaning
+
+The two assertions must be a producer `guarantee` and consumer `requirement` on the same exact
+repository/scoped/transport/versioned contract. Known matching domain, metric and unit are
+required. Missing units or versions are unknown, including two absent versions. No conversion,
+name-based equivalence, implicit ownership, elapsed-time model or data transformation is inferred.
+Limits are JSON/JavaScript numbers, finite and no larger in magnitude than `MAX_SAFE_INTEGER`;
+comparisons use their represented values, without claiming arbitrary decimal precision.
+
+At a shared explicit measurement stage, `at-most`, `at-least` and `equal` define inclusive
+half-lines or singleton sets. These are statements about allowed values, not observed values.
+
+| Result | Meaning |
+| --- | --- |
+| `compatible-constraints` | Producer's allowed set is a subset of the consumer's set at the same stage. |
+| `insufficient-guarantee` | Sets overlap, but the producer permits some values the consumer rejects. This is not a contradiction. |
+| `disjoint-constraints` | No untransformed value at that same stage satisfies both declarations. This is a documented range incompatibility, not proof of a product violation. |
+| `revalidation-required` | Different stages or an overlapping insufficient guarantee, with explicit required consumer revalidation. Inspect the check and rejection behavior; its implementation is not inferred. |
+| `unknown` | Missing assertions/context, unrelated contracts, unmatched domains/metrics/units, unsupported numbers, competing declarations or relevant extraction gaps prevent this assessment. |
+
+For example, collection allows readings up to 600 seconds old; execution requires at most 60
+seconds and explicitly revalidates. Different measurement stages prevent a direct contradiction
+claim. The fixture executes a consumer freshness check separately and retrieves its indexed
+implementation/test references; the assessment still says `fulfillment: not-evaluated`. It does
+not prove eventual delivery, successful execution or availability when stale records are rejected.
+A same-stage producer minimum of 120 seconds versus a consumer maximum of 60 is disjoint,
+even if revalidation is required: no *same untransformed accepted value* satisfies both.
+
+## Evidence and bounds
+
+Responses retain at most the two selected facts unchanged, including source/endpoint citations,
+commit, digests, statement, approval and review metadata. Assessment authority is inferred,
+or draft when a selected fact is draft; `gateEligible` is always false. Shared returned-page
+coverage describes only those assertions. The contract and endpoint IDs support further
+neighborhood exploration to implementations, tests and other business declarations.
+
+The service uses the lossless RDF fact projection shared by other queries. It scans saved facts
+for competing declarations of the same endpoint/role/domain/stage/metric, conservatively choosing
+no winner even if duplicate limits agree. At most 20 competing IDs are returned, with total and
+omitted counts; exact contract neighborhoods provide cited continuation. There is no all-pairs
+Cartesian scan. Projection/context work still scales with the saved graph; this is not an indexed
+incremental graph database or a large private-workload performance claim.
+
+Structural validation is restricted to the selected two records on reads, retaining strict
+SHACL and obligation identity/provenance checks. Hydration still validates the complete graph
+before publication. Relevant intent/ambiguity/implementation gaps block a numeric verdict;
+runtime gaps remain visible because runtime fulfillment is never evaluated. This does not claim
+all omitted documents are complete. Old snapshots, configuration changes and draft overlays stay
+explicit and ineligible for current-diff validation.
+
+This query-only increment leaves assembly 11, the obligation extractor identity, provider,
+prompt and semantic cache unchanged. No graph migration or cache invalidation is needed.
+
+## Acceptance and remaining scope
+
+[The public protocol](../evaluations/contract-compatibility/README.md) declares source cases,
+expected outcomes and query bounds before execution. Actual committed Markdown extraction,
+real SCIP, RDF/SHACL, impact → neighborhood → pair comparison → symbol/test retrieval, strict
+authority/provenance negatives, shared API/CLI/MCP, saved dirty queries, repeat cache reuse and
+draft rename/delete invalidation are exercised. A finite-set oracle checks all 81 combinations
+of the three operators and three boundary values. Fresh packed-consumer smoke checks the public
+service, installed MCP discovery and honest unknown/missing-snapshot handling.
+
+This covers explicit structured numeric obligations only. Free-form logical reconciliation,
+automated inference/approval, multiple-property satisfiability, formal temporal compatibility,
+product-wide guarantees and approval/backfill UI remain outside this increment. Hard gates
+still require explicit approved deterministic policy; a model suggestion is not such a policy.
+See [validation](VALIDATION.md) and the [remaining queue](1.0-WORK-QUEUE.md).

package/docs/ADR-038-monorepo-code-coverage.md

@@ -0,0 +1,105 @@
+# ADR 038: Saved source selection and monorepo coverage
+
+Status: implemented for the next candidate, 2026-10-30. Live consumer acceptance remains B6.
+
+## Problem and decision
+
+Returned-page relationship counts cannot tell an agent whether a service was omitted from
+indexing. Preserve those existing counts and add a separate saved-snapshot code coverage
+overview, plus `graph.coverage` to page package boundaries and their files through the shared
+API, CLI and MCP. Measure actual inputs and outputs; do not equate omitted evidence, absent
+resolution or zero observed connections with zero business impact.
+
+```sh
+weftlet graph coverage --snapshot <id> --max-items 20 --json
+weftlet graph coverage --snapshot <id> --project services/api --max-items 50 --json
+```
+
+MCP takes `snapshotId`, optional exact `projectRoot`, `maxItems` (1–200, default 50) and
+`continuation`. Omit the project to page boundaries; select a returned root to page its files.
+The root fallback is `.`. Continuations bind the exact snapshot manifest, retained facts,
+diagnostics, view and page size. Responses include offset, totals, remaining count and explicit
+continuation. An absent requested project is distinct from an unknown legacy inventory.
+`SnapshotCodeCoverageService` and `projectCodeCoverage` are public exports; the application
+wrapper supplies current checkout/configuration/overlay evidence state. Reads never hydrate
+or call providers/indexers, and never establish current-diff eligibility.
+
+## What is measured
+
+Assembly records `codeInventory`, version `committed-code-inventory-v1`, with its own content
+digest and the normalized SCIP artifact digest. It enumerates regular committed `.ts`, `.tsx`,
+`.mts` and `.cts` files (including declaration/test files), exact Git blob identities and nearest
+regular `package.json` path boundaries. It reads tree metadata, not package contents, dependency
+installations or active checkout files. The boundary is a physical grouping, not inferred PNPM
+workspace membership, a compiler project, an architectural domain or approved ownership.
+Non-TypeScript projects are outside the counted source universe; a boundary with no such files
+is visible without claiming its implementation is covered. Nonregular entries are excluded.
+
+For each file, three independent fields are retained:
+
+- `codeRootSelected`: selected by the existing repository file extractor's Git path selection.
+- `requested`: included/excluded entry selection for `scip.sourceProject.include`; `unknown`
+  for other indexer commands. We do not reinterpret arbitrary tsconfigs or shell arguments.
+- `indexed`: actual presence in the normalized SCIP document list, including empty documents,
+  if emitted. An indexer result without document observations leaves it unknown. A fact count
+  never substitutes for this observation.
+
+The public source-project probe demonstrates that an imported file can be resolvable by the
+TypeScript compiler but absent from SCIP documents when it was not an entry. Selecting a
+directory in `codeRoots` does not automatically add it to SCIP's `include`. The report exposes
+the omitted file and references without an indexed definition. Configure the intended source
+entries/aliases explicitly, then refresh. `indexedOutsideRequest` also handles observed extra
+documents from other invocations; it is not a promise of automatic transitive inclusion.
+`otherIndexedFiles` reports observations outside this TypeScript inventory without pretending
+those languages have the same coverage contract.
+
+## Connections and uncertainty
+
+Coverage derives code connections from retained occurrence facts: a reference's exact symbol
+ID is joined to its indexed definition file(s), then to recorded package boundaries. Repeated
+sites remain distinct; duplicate fact IDs do not inflate reference counts. Project rows expose
+incoming/outgoing reference counts and distinct connected boundary counts. File rows expose
+reference counts, missing indexed definitions, declaration-only targets and cited implementation
+gap counts. File node IDs support follow-up through `graph.neighbors` to exact symbols/citations.
+
+These are code-reference measurements. They do not replace queue/stored-data product links,
+prove calls ran, or establish compatibility/fulfillment. A declaration-only external target is
+not an implementation body. Unresolved external calls retain the existing extraction diagnostics;
+not every missing dynamic/type/module relationship can be observed. Zero gaps or connections
+cannot certify completeness, isolation or no impact.
+
+The full stored inventory and the same retained facts supply the public query, ordinary impact/
+neighborhood/path/compatibility overview, and viewer text. RDF projection equivalence is tested;
+no separate graph topology or guessed cross-service edge is introduced. `coverage.code.scope`
+is `saved-snapshot`; existing lane counts remain `returned-page`. Overview has no file list,
+keeping ordinary agent responses bounded. Detailed package/file lists are paginated separately.
+Projection work still scans the saved inventory and facts, not an incremental graph database.
+
+## Snapshot lifecycle
+
+Assembly advances from 11 to 12. Inventory participates in committed and overlay content digests.
+Draft inventory is rebuilt from the isolated captured tree; Git blob identities are content-based,
+and the overlay manifest supplies base SHA/capture identity. Overlays record their actual SCIP
+digest rather than inheriting the committed artifact's digest. Edits outside captured scope stay
+excluded through the existing evidence-state contract. Historical snapshots remain readable;
+absent inventory is `unavailable`, not zero. Unsupported version/digest mismatches are
+`invalid-inventory`, without fabricated counts. Inventory digests detect mismatches, not signed
+attestation or complete validation of arbitrary hand-edited snapshot JSON.
+
+Provider/prompt/cache identity remains unchanged, so unchanged semantic artifacts can be reused.
+The query adds no model calls, hard gates, dependencies, workspace builds or application changes.
+
+## Acceptance and remaining scope
+
+[The public fixture](../evaluations/monorepo-coverage/README.md) covers actual committed multi-package
+TypeScript/TSX, aliases/barrels, an independent service, an omitted service, declaration-only and
+unresolved external targets, selected-but-unindexed files and empty sources. Tests compare raw
+SCIP documents, RDF facts and coverage; follow exact paginated boundaries/files; preserve unknown
+legacy state; and verify unchanged reuse/clean comparison, dirty unavailable-provider queries,
+CLI/MCP equivalence, rename/delete overlays, changed selection and immutable historical results.
+Packed installation exercises the exported API and installed CLI/MCP. Supported platform results
+are recorded in [validation](VALIDATION.md) and the change PR.
+
+This closes the bounded B5 implementation, not live product acceptance. Arbitrary compiler-project
+discovery, other language indexing, cross-repository federation, B3b's inference decision and B6's
+candidate/usefulness evaluation retain their separate scope.

package/docs/ADR-039-mapping-proposals.md

@@ -0,0 +1,119 @@
+# ADR 039: Opt-in, unreviewed rule-to-function proposals
+
+Status: implementation and public protocol prepared, November 2, 2026. The maintainer authorized
+the 0.7.0 acceptance release with live proposal validation tentative and deferred. Live model
+accuracy and independent usefulness assessment remain unproven.
+
+## Decision and scope
+
+The maintainer accepted the bounded inference recommendation after ADR 034's deterministic
+assessment. Add an explicit proposal operation alongside saved graph evidence. It addresses
+documented rules with file associations or document links but no exact symbol binding. It does
+not generate missing intent, approve mappings, prove compliance, backfill documents, alter
+semantic hydration or insert proposed relationships into the canonical graph.
+
+One request chooses an exact saved snapshot, business rule ID, approved source document and
+one to four already-linked files. Eligible business nodes are Invariant, Capability, Workflow
+and Contract. A source must be declared, with intent role or legacy unspecified role; recorded
+ownership must be resolved or not-required. Existing extracted subject assertions retain their
+review state. Source approval never approves their interpretation or a proposed mapping.
+
+The no-model plan checks existing explicit bindings, source intent/mapping diagnostics, recorded
+code coverage, regular committed files, exact source digests/revisions and indexed callable name
+occurrences. It rejects unknown/omitted indexing and ambiguous named callable identities. Syntax
+must have an actual implementation body. Canonical test/spec file identities are validation
+evidence and cannot be proposed as product implementations by this operation. Ambient declarations
+and anonymous callables are counted as excluded; this increment does not invent identities for
+them. Code is joined by exact indexed
+positions, never label similarity. Co-location supplies candidate scope, not an implementation claim.
+
+The selected source document and callable excerpts are read at the saved commit, independently
+of the active checkout. An old snapshot can be used deliberately and remains labeled stale with
+excluded working changes; it cannot pass current-diff validation. Draft-overlay proposal creation
+is deferred because captured source bytes need a distinct durable input contract. Existing
+overlay graphs remain queryable.
+
+## Bounds and authority
+
+Defaults: at most eight candidates, 32 KiB of prompt/schema input, and one provider request.
+Explicit request ceilings are 20 candidates and 128 KiB input. There are at most five source reads,
+each at most 1 MiB according to immutable Git tree metadata. A candidate/input overflow blocks
+execution rather than selecting an unreported subset. The configured semantic timeout (up to
+600000 ms) applies to the provider phase; mapping does not inherit semantic automatic retries.
+Oversized previews bound retained candidate metadata and report observed/returned counts with
+`candidateEnumeration.complete: false`; incomplete enumeration never runs a provider. Candidate
+`excerptBytes` exposes a body that exceeds the input limit without retaining its oversized text.
+For blocked plans, `inputBytes` counts only prepared input, not omitted candidate material.
+These are request/byte/time bounds, not a token billing or dollar cap.
+
+Provider output must select exact candidates and cite both the documented rule's supporting
+source span and the candidate's implementation extent. Unknown/duplicate IDs, unsupported line
+ranges, extra fields, invalid confidence and inconsistent proposal/abstention states fail before
+storage. Model-reported confidence is uncalibrated. Structural citation validation cannot prove
+the proposed interpretation is correct. Rationale and source text remain untrusted content.
+
+The result is either a proposed set or an explicit abstention. Every saved result is permanently
+`authority: inferred`, `extractionReview: unreviewed`, `establishesCompliance: false`. Original
+subject/association facts and code-definition proofs are retained, including their independent
+authority and provenance. No rule violation, test success, compatibility or approval is inferred.
+
+## Provider, cache and failure contract
+
+Use the existing Codex CLI authentication configuration: ChatGPT by default; API-key mode only
+when explicitly configured. The runner is isolated, read-only, ephemeral, ignores user rules and
+configuration, disables shell tools, and requires structured output. Authentication never falls
+back to another billing mode. Fake-transport tests cover the invocation; live operation is a
+separate validation. Module providers must explicitly export `createMappingProposalProvider`
+with a matching configured identity and a `propose(input, { signal, timeoutMs })` method. The
+semantic-provider interface alone does not qualify. Local modules are trusted code and must honor
+abort signals, bound their own work, and keep input/credentials out of logs.
+
+The outer deadline/cancellation race rejects uncooperative providers and prevents late results
+from publication. Progress contains only phase, opaque operation ID and elapsed time. Unknown
+provider errors never expose stderr/prompts. Publication after validation is a single atomic
+commit point; cancelling after a completed publication does not erase a valid artifact.
+
+Proposals use their own versioned identity and `artifacts/mapping-proposals` namespace. Keys bind
+the exact saved snapshot/facts, requested scope/budgets, source input digest, provider/model and
+reasoning configuration. Operational timeout/retry changes do not invalidate artifacts. Module
+authors must version their identity when implementation or output-affecting configuration changes;
+deadline/retry fields are operational under this contract. Identity
+hashes use persisted JSON semantics so optional undefined fields survive a write/read round trip.
+Input/plan/output checks run again on reuse; model/prompt/code/source changes require a new key.
+This initial cache is conservative and snapshot-bound: it does not reuse across a new snapshot,
+even when an unrelated file changed. No force overwrite or automatic baseline acceptance exists.
+
+Bounded hash filenames and atomic hard-link publication preserve a concurrent winner. Concurrent
+cache misses can each spend their independently authorized request; there is no cross-process
+provider single-flight lock. Conflicting
+outputs fail without overwriting it. Existing graph heads, snapshots and semantic artifacts are
+unchanged. Saved proposal reads require neither provider initialization nor source re-extraction;
+they bind the exact snapshot and report current evidence state. Integrity hashes detect mismatches,
+not malicious rewriting of a local artifact and all its hashes.
+
+## Interfaces and acceptance
+
+`mappings plan --request request.json` previews scope, candidate proofs, exclusions, bytes,
+cache identity, readiness and expected request count. `mappings propose --request request.json
+--allow-model` explicitly permits one new request; a cache hit needs no model permission.
+`mappings read --snapshot ID --key KEY` reads a saved result. CLI JSON is the shared API result.
+MCP exposes only `mapping.plan` and `mapping.proposals`, both read-only and unable to spend model
+requests. Follow returned exact symbol IDs through `graph.neighbors`/`graph.paths`. Normal graph
+queries and the viewer do not silently acquire proposed edges.
+
+Deterministic public tests cover real prose extraction/SCIP, misleading-name candidates,
+cross-domain file rejection, declared versus unreviewed authority, citations, missing/omitted/
+declaration-only code, budgets, model consent, reuse with unavailable provider and dirty checkout,
+rename/delete invalidation, historical reads, timeout/cancellation and immutable concurrent writes.
+Fresh packed installation exercises actual CLI/MCP and exported APIs with a visibly canned module.
+No canned result is semantic-quality evidence.
+
+[The predeclared live protocol](../evaluations/mapping-proposals/README.md) permits three bounded
+public requests only after usage approval. It separates target accuracy, abstention, output
+validity, infrastructure failure and independent rationale/usefulness review. On November 2,
+the maintainer requested publication before live integration testing. This scoped deferral permits
+the optional feature in the 0.7.0 acceptance candidate; it does not record a live proposal pass or
+official 1.0 approval. Existing consumer Codex hydration validates the established extraction flow,
+not this new proposal operation or its semantic accuracy. B6 still owns candidate hydration/repeat,
+real agent usefulness and the final 1.0 decision. The public three-request protocol remains
+available for later separately authorized evaluation; this release performs no model requests.

package/docs/ADR-040-bounded-graph-io.md

@@ -0,0 +1,90 @@
+# ADR 040: Preserve evidence while removing whole-graph string and RDF copies
+
+Status: implemented; public large-corpus lifecycle and hosted Linux/Windows checks pass.
+Consumer acceptance remains open.
+
+## Problem
+
+The 0.7.0 consumer report reaches 561,777 facts / 174,710 nodes, reusing 18 semantic artifacts
+without model calls, then fails at `sha256(stableJson(logical))`. Node's string ceiling is
+536,870,888 UTF-16 code units; increasing the heap does not remove it. Snapshot JSON writing,
+JSON reload and full RDF exports had similar allocations. The old internal SPARQL projection
+also rejected more than 100,000 facts.
+
+A generated public TypeScript corpus additionally demonstrated the memory cost of retaining a
+full named N3 dataset and its validation union simultaneously. The fix must retain every assertion,
+test fact, citation, confidence, authority and review state. It does not change extraction scope.
+
+## Decision
+
+- `stableJsonDigest` incrementally hashes the **existing encoding**, including sorted keys,
+  escaping, number formatting and legacy undefined-field behavior. `persistedJsonDigest` retains
+  the existing JSON-normalized digest contract. Neither is a new canonicalization standard.
+- Stream ordinary snapshot/artifact JSON to exclusive temporary files, then publish with the
+  existing atomic hard-link/head replacement rules. Read JSON incrementally with a strict parser.
+  Header-only checks parse the complete document but retain only the manifest. Old files need no
+  migration and existing immutable winners are never rewritten.
+- Stream default semantic N-Triples and optional openCAESAR file digests, preserving their existing
+  byte encodings and hashes. No Docker or provider is required to query saved evidence.
+- Use one RDF encoder for named exports, SPARQL matching and validation partitions. RDF/JS matching
+  streams complete groups and indexes subject/graph lookups; Comunica remains the SPARQL engine.
+  Cardinalities are exact, never guessed for optimizer shortcuts. The traversal record projection
+  has equivalence tests against SPARQL, including duplicate-ID join multiplicity, and no graph-size
+  response cap. Public query result limits still report truncation.
+- `serializeChunks()` / `serializeTo(writable)` export complete N-Quads with backpressure. The
+  legacy `serialize(): Promise<string>` convenience necessarily remains limited by the JavaScript
+  string ceiling. N-Quads ordering can differ from 0.7.0; its quad set is unchanged. Export order
+  is not a snapshot identity. Snapshot JSON encoding and semantic RDF digests are preserved.
+
+## Strict SHACL without two complete RDF stores
+
+Keep `rdf-validate-shacl` and every current constraint. Group all outgoing triples for a subject
+together, including every occurrence of a shared identity; do not validate isolated conflicting
+assertions as if each were a separate node. Current shapes inspect direct outgoing properties;
+their only cross-subject constraint is `sh:class`. Supply complete graph-wide `rdf:type` membership
+for those references. Determine the original targets before adding support-only type triples and
+express those same targets as `sh:targetNode` for the batch. Support-only nodes are checked with
+their complete records in their own batch.
+
+Every subject and constraint is evaluated. Missing proof targets, contradictory metadata, kind
+conflicts, corrupt citations and malformed code evidence still fail. Existing TypeScript proof
+and provenance checks run over all facts after SHACL. No validation result is reused or inferred
+from semantic cache hits. An allowlist rejects new SHACL vocabulary or non-direct paths until
+partition locality is reviewed; unsupported constraints cannot silently pass. Batch progress
+reports completed groups and elapsed time, not an estimated completion time.
+
+This changes execution/storage, not asserted semantics: assembly 12, extractor identities,
+semantic cache keys, schema version and logical snapshot IDs remain unchanged. Old snapshots stay
+addressable; existing extraction incompatibility checks still apply.
+
+## Validation and limits
+
+Tests compare against a frozen 0.7.0 RDF builder at
+`073edab3f1cef875f2fc058ffbc0ddc59cf934d2`. They compare complete named and union quad sets,
+positive/negative verdicts and issues, real SCIP/code-proof metadata, cross-partition class
+references, aggregates and traversal projections. Hash compatibility includes Unicode, surrogate
+boundaries, optional fields and an encoding larger than V8's actual string ceiling. Storage tests
+cover malformed/truncated JSON, special property names, legacy files and concurrent publication.
+
+The repeatable public workload is generated TypeScript with shared helpers, same-file and
+cross-file calls, spec files and 18 prose documents. Its provider is a deterministic fixture
+parser, not a live model. It exercises real SCIP, strict hydration, snapshot reload, streaming
+N-Quads parsing and bounded SPARQL, unchanged repeat and clean comparison; it asserts canonical
+encoding size above the actual string ceiling, exact provenance, semantic reuse, unchanged
+versions and immutable snapshot/artifact bytes.
+
+```sh
+pnpm build
+pnpm exec vitest run tests/large-graph-lifecycle.test.ts tests/rdf-scaling-parity.test.ts
+node --max-old-space-size=8192 --import tsx scripts/large-graph/run.ts 1100 40 --require-large
+```
+
+The large run is deliberately separate from ordinary CI; its scaled fixture runs in CI.
+The [recorded full run](benchmarks/large-graph-2026-11-02/result.json) passes with 554,516 facts,
+a 1 GB snapshot and a complete 5.3 GB RDF export. Each strict SHACL pass takes about 35–37 minutes;
+this does not establish a 30-minute hydration budget. Linux capacity results do not establish
+native Windows consumer acceptance. See VALIDATION.md for source/checkpoint distinctions. This is a capacity regression, not a
+semantic-quality or universal performance guarantee. Parsed graph objects and indexes still use
+memory; a single very large record/identity can exceed a group target. Arbitrary SPARQL joins,
+sorts and aggregates have their own time/memory costs. There is no persistent graph database,
+incremental-validation cache or Rust validator in this change.

package/docs/GRAPHIFY-EVALUATION.md

@@ -1,9 +1,26 @@
 # Graphify evaluation for the pre-1.0 baseline
 
-Status: preliminary source/document review on 2026-10-28. **No comparative execution or
-replacement decision yet.** This is B2 of the [baseline plan](PRE-1.0-BASELINE.md).
-No Graphify dependency, code, binary, skill or service was installed into Weftlet. Public source
-was read at a pinned revision outside the repository; no private consumer material was used.
+Status: B2b measured on 2026-10-29. [ADR 031](ADR-031-code-extractor-selection.md) selects
+**keeping SCIP and improving its declaration/reference projection**. Production implementation
+is B3a; no Graphify runtime or dependency is added to Weftlet.
+
+The [durable public measurement record](../evaluations/code-graph-results/2026-10-29/README.md)
+contains tool receipts, native outputs, per-case scores, costs, failed attempts and disclosed
+harness corrections. On the 51 frozen cases, raw SCIP resolves 15/15 declaration families and
+16/16 references; Graphify resolves 14/15 families, 8/16 references and 7/10 native calls.
+Current Weftlet discards useful raw SCIP detail. Calls remain unsupported by the SCIP projections.
+No named false-join negative was asserted, but these are labeled-case metrics, not whole-graph
+precision. Graphify is faster on these tiny inputs; the small Linux-only study does not establish
+production performance or universal language support.
+
+All arms preserve fixed, cited business controls and strict RDF/SHACL parity. They do not infer
+missing queue wiring or prove undocumented rule-to-function mappings. Those remain B3–B5 work.
+No paid/model calls or private consumer material were used. The pinned Graphify source API was
+installed only in an isolated experiment, using its unchanged lock and 30 runtime distributions.
+Its 0.9.97 manifest/0.9.96 lock-project discrepancy is recorded; no project distribution was installed.
+
+The remainder records the preliminary source review and the predeclared comparison protocol.
+The frozen corpus, labels and budgets at `f1844f31717341f5ff95314a68def80eae509734` remain unchanged.
 
 ## Reviewed candidate