@weftlet/toolkit 0.6.1 → 0.7.0

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/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
 

package/docs/PRE-1.0-BASELINE.md

@@ -6,6 +6,18 @@ automatic rule-to-function discovery or complete agent exploration. The candidat
 available for TradePilot acceptance while the work below is assessed. No new release is
 announced by this plan.
 
+Consumer update: the physical artifact filename blocker shipped in **0.6.1**, with native
+Windows traversal → unchanged repeat → clean comparison passing. Use 0.6.1 for the private
+rerun; [validation](VALIDATION.md) records the public release evidence. This storage fix does
+not close any of B1–B6 below. Resume B1 and the bounded B2 evaluation after the blocker release.
+
+The maintainer now considers this the main reported consumer blocker and requests the next live
+TradePilot test after a new candidate. [The implementation queue](1.0-WORK-QUEUE.md) breaks B1–B6
+into bounded increments; B1a exact-node neighborhoods and B1b bounded paths are implemented for the next candidate.
+B2a's public comparison protocol is frozen; B2b's measured decision retains SCIP and improves its
+projection ([ADR 031](ADR-031-code-extractor-selection.md)). This schedules acceptance;
+it does not claim an additional private run or a full product-usefulness pass.
+
 The product goal is to let an agent starting with a task or code change retrieve the relevant
 product obligations, understand their connections across domains and asynchronous service
 boundaries, and inspect the implementations, contracts and evidence behind those connections.
@@ -61,10 +73,10 @@ blockers take priority when its report arrives. Do not modify or audit its appli
 | --- | --- | --- |
 | **B1** | **Exact graph exploration.** Specify and add bounded node lookup/neighbor expansion and dependency-path exploration through MCP and the shared query layer. | An agent can start from a returned stable node ID, select relation/direction and inspect another business area. Return citations, authority, snapshot identity, incomplete scope, pagination and remaining frontier. Test branches, cycles, ambiguous labels, deleted nodes and stale/mismatched continuations. Keep CLI/MCP/viewer on the same facts; preserve existing `impact.scan`. |
 | **B2** | **Evaluate Graphify and current SCIP representation.** Run the fixed public comparison in [the research note](GRAPHIFY-EVALUATION.md) before choosing a code extraction backend or symbol schema. | Compare the current projection, richer use of raw SCIP and pinned Graphify on identical committed inputs. Measure correct/missing/false links, provenance, identity stability, costs and packaging. Produce a keep/improve/replace decision with evidence. Parallel use during evaluation does not mandate shipping two indexers. |
-| **B3** | **Resolve business-to-implementation links at symbol/function level.** After B2, define canonical scoped code identities and resolve explicit document paths/symbol references to exact code entities. Evaluate a separate bounded inference pass only where explicit evidence is insufficient. | Named functions, methods, aliases, overloads, same-name symbols and renamed/deleted targets resolve correctly or remain unresolved. Separate a cited declared mapping, a proposed inferred mapping and evidence of actual behavior. Record both document and code revisions/spans for derived links. A reviewer can follow a rule to its implementation and back. Code inference never supplies approval; full automatic documentation generation remains 2.0. |
+| **B3** | **Resolve business-to-implementation links at symbol/function level.** After B2, define canonical scoped code identities, retain same-file occurrences and resolve explicit document paths/symbol references to exact code entities. Add bounded static call analysis as a separate increment; evaluate a separate bounded inference pass only where explicit mapping evidence is insufficient. | Named functions, methods, aliases, overloads, same-name symbols and renamed/deleted targets resolve correctly or remain unresolved. Meet the same-file acceptance boundary below. Separate a cited declared mapping, a proposed inferred mapping and evidence of actual behavior. Record both document and code revisions/spans for derived links. A reviewer can follow a rule to its implementation and back. Code inference never supplies approval; full automatic documentation generation remains 2.0. |
 | **B4** | **Cross-boundary obligations.** Represent and retrieve producer guarantees and consumer requirements through explicit data/event contracts, including applicable stage, domain, units, freshness and version where sources provide them. | Public cases cover a queue handoff, a write/read handoff, compatible differing limits with revalidation, a real documented incompatibility, missing links and same-name unrelated domains. Retrieve both sides and the implementation evidence. Potential model findings remain uncertain; hard failures require explicit approved deterministic rules. A graph link or SHACL pass is not a compatibility verdict. General reconciliation/approval UI remains 2.0. |
 | **B5** | **Monorepo selection and coverage.** Assess diagnostics for selected services, client, shared packages, source aliases and excluded/unresolved code; improve the gaps found. | A configured multi-package TypeScript/TSX fixture and the consumer report identify which projects were selected, indexed and actually connected. Test barrel exports, independent service code, external unresolved dependencies and omitted projects. Missing resolution cannot be reported as zero impact or complete coverage. Cross-repository federation is a separate scope decision. |
-| **B6** | **End-to-end product acceptance and release decision.** Combine the public evidence, B1–B5 decisions and TradePilot's actual 0.6.0 report; ship bounded candidate changes as needed. | Predeclare tasks, correct downstream business obligations/implementations, known unrelated matches and query budgets before measuring. Retain actual requests, follow-up decisions and citations. Assess helpfulness and misses separately from hydration success. Complete full hydration/repeat and supported release checks; review any remaining limitations before a versioned 1.0 publication. |
+| **B6** | **End-to-end product acceptance and release decision.** Combine the public evidence, B1–B5 decisions and TradePilot's next candidate report; ship bounded candidate changes as needed. | Predeclare tasks, correct downstream business obligations/implementations, known unrelated matches and query budgets before measuring. Retain actual requests, follow-up decisions and citations. Assess helpfulness and misses separately from hydration success. Complete full hydration/repeat and supported release checks; review any remaining limitations before a versioned 1.0 publication. |
 
 Order: retain this A1–A3 baseline; triage incoming consumer blockers; specify B1 and run the
 bounded B2 comparison; use that decision for B3; implement B4/B5 in independently testable
@@ -72,6 +84,41 @@ increments; close B6. Each implementation can ship in a minor candidate before 1
 retrieval semantics, extraction/cache identity or snapshot compatibility need explicit decisions
 and regression evidence; no silent migration or history rewrite.
 
+## Same-file exploration acceptance
+
+The maintainer explicitly identified large files with many internal calls as a 1.0 concern after
+the B2 comparison. Retain SCIP and address this gap without waiting for an application rewrite.
+The following requirements extend B3; they do not change the frozen B2 cases or scores and are
+not implementation or private consumer validation results.
+
+1. Preserve local/private functions, methods, same-file references and multiple occurrences of
+   the same reference. Return exact source spans and enclosing callable where established;
+   file membership alone must not imply a call or make every function relevant.
+2. In a separately testable call-analysis increment, distinguish a statically resolved direct
+   call from a type use, passing a function as a value, or registering a callback. Retain caller,
+   callee, callsite, resolution basis and uncertainty. A static edge does not prove runtime
+   execution; unresolved dispatch/callback targets remain explicit.
+3. Starting with one exact function, let an agent retrieve incoming references/callers and
+   outgoing references/callees, follow a helper chain and inspect applicable documented rules
+   through the shared bounded API/MCP queries. Preserve direction, citations, authority, scope
+   and continuation. Avoid requiring the entire containing file as the initial context response.
+4. Use an independently authored public fixture of roughly 3,000 lines with meaningful internal
+   helper chains, unrelated methods, private/local functions, recursion, shadowed names and
+   repeated callsites. Include a cross-file caller and a similar-looking implementation with a
+   distinct identity. Predeclare expected retrievals and query budgets before measuring; verify
+   extraction and actual agent-facing query results rather than hand-assembled edges. Record
+   bounded response size and misses. File length is a workload characteristic, not an
+   architectural violation or proof of modularity.
+5. Check edits, line shifts, rename/delete, dirty overlays, historical evidence, strict RDF/SHACL
+   and shared-query parity. Preserve explicit rule-binding authority. Similar code or names do
+   not establish equivalent business behavior or justify merging identities; existing duplication
+   signals still require semantic review. Duplicate-behavior detection is not added by this task.
+
+Implement richer entities/occurrences first, then explicit document bindings and the separate
+call-analysis increment. Select the call producer using focused evidence; this does not select
+Graphify as a dependency or promise complete call/data-flow analysis. Agent usefulness still
+needs B6's live consumer evaluation after the candidate is published.
+
 ## Consumer report to reconcile when available
 
 Retain the private configuration, documents, snapshots and transcripts with TradePilot. Share

package/docs/RELEASE-1.0-PLAN.md

@@ -4,8 +4,14 @@ Status: original T01–T10 engineering work complete; 0.6.0 candidate publicatio
 The maintainer has requested additional [business-context baseline work](PRE-1.0-BASELINE.md)
 before official 1.0: precise exploration, symbol-level implementation links, cross-boundary
 obligations, monorepo coverage and a measured Graphify/SCIP decision. Its A1–A3 public checks
-pass within recorded limits; B1–B6 remain open. Both npm packages remain available for
-TradePilot acceptance while this additional scope is assessed.
+pass within recorded limits; B1 query mechanisms are implemented for the next candidate, while
+B2's measured decision retains SCIP. B3a explicit bindings and B3b's deterministic gap assessment
+are complete; B3c static calls, B4a explicit obligations and B4b selected numeric comparison are
+implemented, along with B5's saved TypeScript/package coverage. Inference decisions and B6
+remain open. Both npm packages remain available for
+TradePilot acceptance while this additional scope is assessed. The maintainer requested the
+next live test after a new candidate; [the implementation queue](1.0-WORK-QUEUE.md) tracks
+the intervening B1–B6 work.
 **T08's upstream deterministic physical-file fix has shipped; the maintainer reports the consumer
 updated and working on 2026-10-27. Detailed full hydration/repeat evidence remains pending.** T04 was completed before
 the T08 fix as requested.
@@ -32,6 +38,12 @@ This is the near-term release task list. The [Weftlet 2.0 product plan](WEFTLET-
 remains a separate future direction for generation, approvals, a companion website and hosted
 AI. None of those platform features is a dependency of the fixes here.
 
+The subsequent consumer filename blocker shipped in **0.6.1** on 2026-10-28: bounded physical
+artifact/temp names, unchanged full logical identities/provenance, legacy reads and the requested
+Windows traversal → repeat → clean regression. Registry archives, provenance, tags and a fresh
+packaged CLI sequence are verified in [validation](VALIDATION.md). Use this patch for the next
+consumer rerun; B1–B6 and actual product acceptance remain open.
+
 ## Reported evidence and boundaries
 
 The consumer reported a cold extraction in which two source documents referred to the same

package/docs/RELEASING.md

@@ -202,14 +202,14 @@ Verify the matching public version in a fresh disposable project after publicati
 
 ```sh
 npm init -y
-npx --yes @weftlet/toolkit@0.6.1 init --yes
-npx --yes @weftlet/toolkit@0.6.1 config validate
+npx --yes @weftlet/toolkit@0.7.0 init --yes
+npx --yes @weftlet/toolkit@0.7.0 config validate
 ```
 
 For local installation, use both prepared archives from the same reviewed release:
 
 ```sh
-npm install --save-dev "/path/to/weftlet/.release/weftlet-core-0.6.1.tgz" "/path/to/weftlet/.release/weftlet-toolkit-0.6.1.tgz"
+npm install --save-dev "/path/to/weftlet/.release/weftlet-core-0.7.0.tgz" "/path/to/weftlet/.release/weftlet-toolkit-0.7.0.tgz"
 ```
 <!-- weftlet:release:end -->