@weftlet/toolkit 0.6.0 → 0.7.0

package/docs/ADR-033-document-symbol-bindings.md

@@ -0,0 +1,83 @@
+# ADR 033: Resolve explicit document declarations to indexed code symbols
+
+Status: accepted for B3a's second increment; npm candidate pending. This builds on ADR 032,
+without a new indexer, model inference, prompt change or semantic cache invalidation.
+
+## Explicit selection and mapping
+
+An ordinary CommonMark link opts in with `#weftlet-symbol=<exact-name>`. The destination names
+one regular committed repository file. Match an exact name, public symbol ID or qualified name
+built solely from indexed lexical parents. There is no basename search, fuzzy match or inferred
+call. Duplicate identities are a gap, not a first-match selection. Missing native enclosure can
+prevent qualification; an exact indexed occurrence remains available.
+
+Optional `weftlet-line` and `weftlet-column` select a particular definition/reference, using
+one-based UTF-16 start positions. Both are required. The source token must equal the selector
+(or the exact symbol ID must match). This resolves aliases and re-exports through native evidence,
+then cites every indexed definition for that identity, including overloads. Without any indexed
+definition, the target is unresolved. `.d.ts` targets remain explicitly declaration-only.
+
+A link without a mapping title creates Document→references→CodeSymbol. A title of
+`weftlet:implementedBy <business-id>` or `weftlet:verifiedBy <business-id>` instead declares that
+relationship from an existing Capability, Workflow, Contract or Invariant. The ID must already
+be present in non-binding facts in this assembly. Nearby prose and link labels do not declare
+mappings implicitly. Reference-style Markdown retains both use and destination citations;
+conflicting destinations or mapping titles produce diagnostics. Images, code blocks, ordinary
+heading fragments and traversal's existing treatment of titles retain their behavior.
+
+## Authority and evidence
+
+The dependency-free public `DocumentCodeBinding` metadata retains the explicit selector, document
+citations, selected occurrence proofs, all target definition proofs and original business-subject
+proofs. Each proof names an actual fact and exact provenance. Source digest/SHA checks require
+committed regular files and the same indexed revision; stale/missing definitions never resolve.
+
+Bindings have `inferred` authority: a declaration of mapping is not proof of fulfillment. Source
+approval/classification is retained independently. A binding involving unreviewed subject evidence
+remains unreviewed; otherwise resolution is deterministic, never an approval workflow. Validation
+sources can declare `verifiedBy` or reference code, but cannot declare `implementedBy`. No test
+execution is inferred. Contradictory declarations remain evidence; this increment does not resolve
+product-policy conflicts or assess semantic truth. Inferred mapping proposals are B3b.
+
+RDF has queryable binding selectors and citation/proof relationships plus lossless JSON records.
+SHACL checks metadata cardinalities/types, supported relationships, target kinds and authority.
+Deterministic consistency checks compare proof IDs/provenance/review to actual same-snapshot
+assertions, selector positions and revision consistency. No kind constraint is weakened.
+Neighborhoods, paths, impact scans, Markdown and the viewer consume the same facts; the viewer
+exposes navigation to document, selected occurrence, target definition and subject-proof sources.
+
+## Scope, bounds and lifecycle
+
+Only sources already selected for hydration are examined. Read traversal-selected validation
+sources are also checked for explicit links without including them in semantic extraction. Source
+selection/SCIP scope omissions still matter; a missing binding is not evidence of no impact.
+Ordinary file links coexist with symbol bindings. Missing/ambiguous selectors report cited
+`implementationGaps`. Diagnostics include at most 100 candidate IDs and the total count. An
+annotated subject with more than 100 supporting facts, or a binding requiring more than 1,000
+selected/definition proofs, reports an explicit gap instead of publishing a partial binding.
+These are conservative first-release bounds, not a silent best-effort coverage claim.
+
+Assembly advances from 8 to 9 and records `document-code-binding-extractor@1.0.0`. Existing
+snapshots remain readable, but current validation requires refresh. Semantic provider, prompt
+and artifact keys are unchanged; unchanged extraction is reused. Clean comparison reproduces
+bindings. Refresh remains a full assembly/indexing operation, not incremental SHACL.
+
+Draft overlays regenerate all bindings against reindexed captured bytes and only retained semantic
+subjects. Changed/deleted/renamed source documents and targets invalidate old mappings. Draft
+fact IDs and proof references are rewritten together, retain the base SHA plus draft digests, and
+never expose temporary checkout SHAs. A changed rule needs semantic re-extraction before an
+annotated binding to it can return. Old committed evidence stays queryable and cannot become
+current validation merely because it is still useful.
+
+## Validation and boundaries
+
+Public acceptance runs real TypeScript SCIP, offline deterministic prose extraction, hydration,
+RDF/SHACL, SPARQL, agent query facades, repeat/clean reuse and draft edits/renames/deletes. Negative
+cases include stale source/target digests, ambiguous names, conflicting titles, missing definitions
+and subject IDs, malformed positions and authority/provenance tampering. Fresh packed-consumer
+smoke uses the public API and actual installed code evidence. See VALIDATION.md for executed gates.
+
+This completes explicit B3a resolution. It does not provide inferred mappings, actual call edges,
+producer/consumer obligation compatibility or monorepo completeness; those retain separate queue
+items and acceptance criteria. The frozen B2 study is unchanged. No private source or paid model
+run is required by this increment.

package/docs/ADR-034-mapping-gaps.md

@@ -0,0 +1,80 @@
+# ADR 034: Remaining business-to-symbol mapping gaps
+
+Status: B3b deterministic assessment complete, 2026-10-29. A bounded inference proposal is
+justified for review; no model quality result or inference implementation is claimed.
+
+## Evidence
+
+The [public study](../evaluations/mapping-gaps/README.md) froze ten cases and source hashes in
+`01f7cb6` before measurement. [The recorded run](../evaluations/mapping-gaps/results/2026-10-29.json)
+used clean evaluator commit `e3a3d375733121c1c9a3006ce17a5b765dbafc8d`, real SCIP and ordinary
+hydration/publication through strict RDF/SHACL. Its offline prose grammar recognizes only the
+inventoried rule/workflow and file-claim sentences; it does not evaluate language-model quality.
+
+All ten observed classifications match the predeclared states. The graph has 111 facts.
+Cold hydration extracted eight documents in 849 ms; the repeat extracted zero, reused eight
+and retained snapshot identity/content digest in 841 ms. These tiny-fixture timings are not a
+monorepo performance claim. Exact neighborhoods returned every direct binding within budget,
+with no forbidden misleading-name mappings. Structural paths were intentionally bounded;
+seven searches report truncation, one exhausts with an absent rule and two are skipped for
+ambiguous or unindexed targets. No completeness claim is made for truncated paths.
+
+| Observed case | Count | Meaning / appropriate response |
+| --- | ---: | --- |
+| Explicit implementation binding | 1 | Rule points to the declared indexed function, with both source proofs. Still a declaration, not proof of compliance. |
+| Explicit test binding | 1 | Rule points to a test function. No test execution is claimed. |
+| Declaration-only binding | 1 | Declaration resolves; the implementation body is absent. Index the implementation before claiming coverage. |
+| File-only claims | 2 | A file association survives. Neither a misleading matching name nor ordinary prose supplies an exact selector. |
+| Document-symbol reference only | 1 | Two rules share a document; proximity does not assign either rule to either function. |
+| Unresolved selectors | 3 | Ambiguous name, excluded source and stale selector remain cited gaps. Qualify, index or repair the source respectively. |
+| Missing intent | 1 | Code exists without an owner rule. Owner intent must be supplied; the evaluator cannot approve inferred business policy. |
+
+The file-only and co-located cases can have structural paths to the desired symbol. Those
+paths are not equivalent to an `implementedBy` assertion. This distinction prevents graph
+reachability or returned implementation counts from overstating semantic mapping coverage.
+All explicit bindings remain inferred/unreviewed assertions with declared source authority and
+retained subject evidence. Neither source approval nor syntax upgrades their review state.
+
+## Decision and next boundary
+
+Keep explicit bindings as the deterministic path. Do not automatically add mapping edges based
+on name similarity, document co-location or shortest paths. Three cases justify evaluating an
+optional proposal pass: the two file claims and the shared-document reference. Repair missing
+evidence/configuration before invoking a model for the other gaps.
+
+A separate, opt-in proposal experiment should:
+
+- Limit candidates to existing cited business IDs and current indexed code definitions in an
+  explicit repository/domain scope. Preserve document and code revisions, spans and digests.
+- Run coverage checks first; distinguish ambiguous, stale, excluded, external/declaration-only
+  and missing-intent cases. Permit abstention; never synthesize approved intent.
+- Emit a separate inferred, unreviewed mapping proposal with rationale and supporting evidence.
+  A proposal is neither an approved mapping nor proof that code satisfies the rule.
+- Use a distinct extraction/cache identity, bounded candidates/output/cost, cancellation and
+  privacy-safe progress. Retain unchanged artifacts without allowing stale code evidence.
+- Predeclare positive and misleading-name/cross-domain negatives before a live evaluation.
+  Report precision, misses, abstentions, citation validity, retrieval usefulness and cost
+  separately. Compare against explicit bindings and file-level context; require evidence that
+  the additional pass improves agent decisions.
+
+This is a proposal specification, not authorization for paid runs or automatic promotion. The
+B3b inference implementation/evaluation or a scoped deferral remains a maintainer decision
+before 1.0 qualification. Continue the already requested B3c static-call work independently.
+Bulk intent generation, document backfill, approval UI and hosted AI remain in the 2.0 plan.
+
+## CI reliability follow-up
+
+PR #58's successful retry and main checks resolved its immediate failed run. Older Windows
+runs also hit the 30-second frozen-study test limit and worker-update timeout. The verifier now
+reads selected immutable Git blobs in one length-framed batch instead of launching Git once
+per file. Test fixture inputs are cached only where immutable; each disposable repository's
+dirty-content/CRLF checks still read fresh bytes. Yielding between synchronous cases lets worker
+updates flush. Binary/CRLF/empty blobs and malformed frames are covered. The original timeout,
+negative assertions, frozen B2 labels and Git-content safety checks are retained.
+
+## November 2 implementation decision
+
+The maintainer approved the bounded opt-in proposal recommendation. [ADR 039](ADR-039-mapping-proposals.md)
+records its separate operation, authority, exact code/source eligibility, provider and immutable
+cache contract. This supersedes the earlier pending implementation/deferral decision. It does not
+supply a live model-quality result or close B6 acceptance.

package/docs/ADR-035-static-call-evidence.md

@@ -0,0 +1,78 @@
+# ADR 035: Static call evidence from TypeScript syntax and SCIP
+
+Status: implemented for the next candidate, 2026-10-29. Live consumer acceptance remains B6.
+
+## Decision
+
+Use the TypeScript parser to recognize `CallExpression`/`NewExpression` sites in the exact
+committed documents already read by the SCIP extractor. Join callee tokens to exact SCIP
+occurrence positions, and callable names to indexed definitions. Keep native identities.
+This adds no second indexer or type-resolution program and rereads no source files. The parser
+is an explicit pinned runtime dependency (`typescript@5.5.4`), included in license notices and
+the packed-consumer test. Existing SCIP indexing continues to supply resolution.
+
+Each `calls` assertion retains caller, selected target, full invocation span, optional/member/
+construction syntax and proofs of caller definitions, target occurrences and all indexed target
+definitions. Caller proof selection uses the actual AST callable, including assigned arrows;
+native lexical enclosure alone does not identify a caller. Repeated callsites remain separate.
+Top-level calls use the canonical physical-file node. Imports/re-exports follow SCIP identities.
+CodeSymbol IDs and ordinary `references`/`definedBy` evidence remain available independently.
+
+`codeCall.target` distinguishes an indexed body, indexed class construction, bodyless declaration
+and external symbol. A member call selects the declaration referenced by the index; it does not
+prove runtime receiver type or rule out overrides, monkey-patching, proxies or reassignment.
+Even lexical calls are static evidence, not guaranteed execution. Authority is implemented
+(draft in overlays), extraction review is deterministic and runtime is explicitly not observed.
+
+Callbacks passed as values, type uses and ordinary references do not become calls to those
+values. Invocation through a parameter, computed dispatch, value alias or unsupported expression
+produces a cited gap rather than an invented concrete target. Anonymous callbacks/initializers
+without an exact indexed callable identity do not inherit the enclosing method as their caller.
+Decorators/computed names remain in their enclosing evaluation context; instance field and static
+block initializers currently report gaps. Defaults are attributed to their callable. Ambient files/namespaces provide declarations only; their decorator/default syntax produces no
+runtime call assertions. Syntax errors cause explicit file-level abstention. Implicit JSX factory, getter, operator and framework
+invocations are not synthesized. This is neither complete data flow nor whole-program analysis.
+
+## Shared evidence and compatibility
+
+The same assertions and proofs are projected into RDF, SPARQL, `graph.neighbors`, `graph.paths`,
+impact packs and viewer source links. A `calls` predicate requires typed metadata; SHACL rejects
+missing fields, invalid kinds/ranges and authority promotion. Consistency checks compare proof
+IDs, endpoints, revisions and source spans against actual same-snapshot code facts. Validation
+targets call records directly rather than scanning every ordinary fact through a new disjunction.
+The validator remains JavaScript and still validates the complete published graph.
+
+`FactExtractor.extractWithDiagnostics(context)` is an additive optional core contract returning
+facts and gaps together without mutable last-result state. Hydration and overlays prefer it;
+existing adapters implementing only `extract` remain supported. The built-in SCIP extractor's
+legacy `extract` returns facts; callers needing its gap report should use the complete method.
+
+SCIP projection is version 2.1.0, call extraction 1.0.0 and graph assembly 10. These identities
+require refreshed code evidence for current validation while historical snapshots stay queryable.
+The semantic schema still has its original predicate list: model output cannot invent `calls`.
+Prompt/provider/artifact identity is unchanged. No semantic-cache rewrite or forced paid run is
+required. Draft proof IDs and revisions are remapped after code extraction; renamed/deleted
+relationships are replaced while committed snapshots retain their original bytes.
+
+## Acceptance and limits
+
+The public fixture/expectations were introduced in `0afbd19` and its data representation bounded
+in `d69d65c`, before extraction. Later supplements cover import aliases and evaluation scopes.
+The roughly 3,000-line file contains a real public string catalog between meaningful helper
+chains and distant definitions. It tests location/isolation, not 3,000 lines of algorithmic
+complexity or representative monorepo performance. Budgets: 800 total facts, 90-second hydration,
+four two-fact neighborhood pages and 80,000 response bytes; helper-to-rule paths have explicit
+depth six, three-path and 500-step limits. Truncation is retained, never treated as completeness.
+
+Real indexing/hydration tests cover repeated sites, recursion, private/local functions, shadowed
+names, overloads, re-export/import aliases, TSX, BOM/Unicode columns, cross-file callers, values
+and callbacks, declarations without bodies, decorators/defaults/initializers and unresolved
+dispatch. Actual query follow-ups reach a cited rule with its unreviewed mapping authority intact.
+RDF projection and named/union SHACL agree, negative provenance/approval cases fail, and repeat,
+dirty querying, line shifts, rename/delete and draft proof regeneration are exercised.
+
+Run `pnpm evaluate:calls` in a development checkout for the public observation report. It uses
+the fixed offline grammar provider, never private inputs or a model. Reports retain original
+assertions, requests/responses, budgets, source hashes, configuration and runtime identity. Tests
+provide the full acceptance assertions; this observation command is not a model-quality grader.
+Browser interaction and live TradePilot usefulness remain separate evidence.

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.