@weftlet/toolkit 0.6.1 → 0.7.1

package/docs/ADR-029-exact-graph-neighborhoods.md

@@ -0,0 +1,70 @@
+# ADR 029: exact graph neighborhoods
+
+Status: B1a implemented and locally checked; hosted/merge evidence is recorded in the change PR.
+Not yet published in a candidate. B1b path exploration remains open.
+
+`impact.scan` discovers relevant evidence with text/file selectors and bounded traversal. Agents
+also need a precise follow-up from a returned node ID. Reusing a node ID as a search term can
+match another node's label or citation and widen the result unexpectedly.
+
+## Contract
+
+Add `GraphExplorationService.neighbors`, `weftlet graph neighbors` and the read-only MCP tool
+`graph.neighbors`. Require an explicit saved `snapshotId` and exact, case-sensitive `nodeId`.
+Never resolve a new default/owner head during follow-up. Missing snapshots fail; missing node
+IDs return `absent-from-snapshot`, meaning only that no assertion in this saved scope mentions
+the ID. This does not prove the code/entity is absent from the repository or deleted.
+
+Direction is incoming, outgoing or both (default). Empty predicate selection means all relations;
+nonempty selection is an OR filter using the core predicate vocabulary. Unknown fields/relations,
+invalid bounds and unsupported CLI arguments fail. A page defaults to 60 assertions, with a
+maximum of 200. Snapshot IDs are bounded to 256 characters, node IDs to 8192 and continuations
+to 2048. Exact IDs are operation inputs, not labels, shell commands or SPARQL fragments.
+
+Read the same lossless RDF/SPARQL projection used by impact queries. Do not refresh, validate
+the full graph again, call a provider or change any snapshot/artifact. Preserve each GraphFact
+byte-for-value, including source and assertion authority, review state, confidence, citations,
+document ownership and node attributes. Multiple citations of an edge remain separate facts;
+labels and attributes from different assertions are not silently merged into an authoritative node.
+Duplicate fact identities fail rather than being dropped during pagination.
+
+## Bounds and continuation
+
+Order by fact ID with locale-independent string comparison. A continuation binds the operation
+version, normalized selectors/page size, snapshot manifest and actual projected facts. Reject
+changed snapshots, filters, corrupted cursors, invalid offsets and stale versions. The token is
+an integrity binding for query consistency, not an authentication or authorization credential.
+
+Report total incident assertions, selected assertions, filtered assertions, page offset and
+remaining assertions. Preserve complete assertions even when several share the same endpoints.
+Self-links appear once and do not create a new neighbor. `truncated` describes pending pages of
+the selected one-hop neighborhood; it never means the transitive product graph is exhausted.
+
+Return a bounded frontier for neighbors on the current page, their supporting returned fact IDs,
+and a count of their other incident assertions that do not touch the focus. Those counts ignore
+the request's filters to make further branches visible. Also report how many distinct selected
+neighbors have not appeared across this and earlier pages; continuation reaches their evidence.
+The frontier does not recursively expand those nodes. Call the same operation with a returned
+neighbor ID and the same snapshot to inspect another area. B1b owns multi-hop paths and budgets.
+
+Responses reuse impact coverage semantics and the exact same checkout/overlay freshness helper.
+Diagnostics match exact focus/returned-neighbor IDs or overlapping returned citations, with the
+same per-kind bounds and explicit omitted/legacy counts as impact reports. A missing node can
+still have a relevant extraction-gap diagnostic; unknown legacy text is counted, not dumped.
+Historical evidence remains readable, excluded working changes remain explicit, and saved
+evidence cannot satisfy a current-diff validation gate. Page coverage is not a repository coverage
+percentage or proof of behavior. Extraction gaps and partial document scope remain visible.
+
+## Compatibility and validation
+
+This is an additive query API. Extraction, storage, semantic cache identity and existing
+`impact.scan` behavior stay unchanged. The core predicate list becomes the shared runtime/type
+vocabulary, frozen at runtime; semantic schema ordering and contents stay identical. No new
+backend or language support is introduced. Existing snapshots can be explored without rebuilding.
+
+Use focused graph tests for branching/cycles, exact IDs vs duplicate labels, direction/relations,
+parallel provenance, self-links, page/frontier completeness and cursor rejection. Use actual
+extraction/SCIP/RDF from the public monorepo fixture for cross-service follow-up and real CLI/MCP
+transport. Verify dirty checkout/overlay state and provider-unavailable saved reads. Packed-consumer
+tests must discover and call the new tool. B1a does not establish autonomous-agent usefulness,
+private consumer acceptance, automatic rule-to-function binding or complete path exploration.

package/docs/ADR-030-bounded-evidence-paths.md

@@ -0,0 +1,97 @@
+# ADR 030: bounded cited dependency paths
+
+Status: B1b implemented for the next candidate. Hosted validation and merge identity are recorded
+in the change PR; this entry does not announce npm publication or private consumer acceptance.
+
+## Meaning and scope
+
+`GraphPathQueryService.paths`, `weftlet graph paths` and MCP `graph.paths` take an explicit saved
+snapshot ID and exact `fromNodeId`/`toNodeId`. They enumerate simple paths of cited assertions:
+no node repeats, a target ends a path, parallel assertions produce distinct alternatives, and
+self-links do not create cycles. Equal endpoints that occur in the saved graph yield one
+zero-length identity path with no supporting assertion, even if a relation filter excludes all
+their edges. An absent endpoint never establishes a path or absence from the actual product.
+
+Outgoing (default), incoming and both directions refer to assertion subject/object order.
+Following incoming or undirected evidence does not reverse or rewrite the original assertion.
+An empty predicate list selects all relations; a nonempty list is an OR filter. Paths establish
+cited associations, not causality, compatible business obligations or behavior verification.
+They preserve authority, review state, source citations and node variants on every returned fact.
+
+Read the same lossless RDF/SPARQL projection as other queries. Preserve its existing explicit
+100,000-fact projection ceiling; exceeding it fails rather than truncating silently. No model,
+indexer, SHACL rerun or graph write is involved. Duplicate fact IDs and mismatched stored snapshot
+IDs fail. Responses reuse coverage, scoped diagnostic and checkout/overlay-state helpers.
+Coverage describes the page's supporting evidence, not a repository completion percentage;
+historical/draft evidence cannot validate the current diff. Document selection omissions remain
+in snapshot metadata. An exhausted search says nothing about excluded or unextracted dependencies.
+
+## Enumeration, work and continuation
+
+Use deterministic depth-first traversal with adjacency sorted by assertion ID, independent of
+locale. This is not a shortest-path or importance ranking: alternatives reached later can be
+shorter or more relevant. Do not interpret the first path as the preferred design.
+
+Defaults are depth 8 (maximum 32), five paths per page (maximum 20) and 1,000 new candidate-edge
+examinations per page (maximum 10,000). Every considered edge counts, including cycles and depth
+cuts. A search has a hard total ceiling of 100,000 examinations across continuations. Graph
+loading, RDF projection and adjacency preparation are separate work, not included in that
+candidate count. Adjacency sorts are O(E log E); the existing RDF projection also orders facts.
+There is no wall-clock latency guarantee.
+
+Continuations bind the operation version, normalized selectors and page budgets, saved manifest,
+actual facts and diagnostics. A cursor carries only a step offset, never an external stack or
+assertions. Bounded replay reconstructs state and verifies the offset is a valid page boundary.
+Responses report replayed and new steps separately. Replay is at most the total ceiling; a DFS
+stack is at most depth + 1. This trades bounded repeated CPU work for stateless continuation
+without snapshot/cache writes or a large serialized queue. Tokens provide query consistency,
+not authentication. Changing selectors, depth, budgets or saved evidence requires restarting.
+Cumulative cost over many tiny pages can exceed one search's ceiling because replay is repeated;
+clients should normally retain the default work budget.
+
+The page includes only its completed paths and the union of their unchanged supporting facts.
+Work-limited pages may be empty and still have a continuation. Returned path count is not a
+count of all possible paths. A continuation can lead to a final empty page after dead ends/cycles.
+
+Report every active DFS prefix with its fact-ID prefix, next candidate fact ID and remaining
+adjacency-candidate count. These are not counts of valid paths. Depth cuts retain a total count,
+up to 20 concrete extension examples and an explicit omitted-example count. Frontier IDs refer
+to saved assertions; use `graph.neighbors` at that node/snapshot to retrieve their full citations.
+
+`truncated` is true if pending work or any depth cut remains. A page/path limit supplies a
+continuation. Exhausting the search within the requested depth can still have `truncated: true`
+and no continuation: increase depth and restart, or explore a frontier node separately. Reaching
+the total work ceiling likewise retains frontier and says `search-limit`, without continuation;
+narrow relations or choose an intermediate node. None of these states silently reports no impact.
+
+## Viewer parity and compatibility
+
+The offline HTML viewer embeds the same dependency-free search function used by the service.
+It searches only the displayed Context Pack and selected authority/relation layers; it cannot
+fetch the full snapshot or turn a filtered page into complete repository evidence. Its first/next
+path controls use one result per page, 1,000 new examinations, selectable direction/relation/depth
+and the same total ceiling. Changing selection resets continuation. Targets show exact IDs next
+to labels. Each highlighted edge is an unchanged fact from that displayed pack.
+
+The prior viewer-only shortest-path implementation is replaced by shared deterministic
+enumeration; labels now say "cited path" rather than promising a shortest route. `impact.scan`
+and `graph.neighbors` remain unchanged. No extraction identity, semantic artifact/cache key,
+snapshot format, dependency, rule policy or language support changes.
+
+## Validation boundary
+
+Compare against an independent oracle on every directed four-node graph; test parallel
+assertions, cycles, self-links, competing branches, deep paths, relation/direction filters,
+empty work pages, truncated depth, bounded frontier examples and the cumulative ceiling.
+Reject malformed/stale/non-boundary continuations. Compare supporting facts with RDF queries
+and preserve snapshots with deleted or excluded endpoints.
+
+Exercise actual public prose extraction, SCIP and RDF/SHACL across services through CLI/MCP,
+including unavailable providers/indexers, dirty checkouts and captured/stale overlays. Verify
+fresh installed CLI/MCP assets and continuation. Execute rendered viewer controls in a small
+DOM test harness and compare every highlighted path with the RDF service; this is script and
+projection parity, not interactive browser rendering or autonomous-agent usefulness evidence.
+
+B1a/B1b mechanisms are implemented; qualification and live product usefulness remain B6. B2's
+Graphify/SCIP comparison is next. No backend replacement or business compatibility inference
+is implied by paths through the existing evidence graph.

package/docs/ADR-031-code-extractor-selection.md

@@ -0,0 +1,91 @@
+# ADR 031: retain SCIP and expose its code occurrences
+
+Status: B2b decision recorded on 2026-10-29. Implementation belongs to B3a; no production
+extractor, public schema, dependency or published package changes in this experiment.
+
+## Decision
+
+Keep SCIP TypeScript as the default. Build a versioned, richer projection of its declarations
+and reference occurrences for explicit rule-to-symbol resolution. Do not replace it with
+Graphify or require both indexers. Preserve an adapter seam for a future producer with a
+measured capability that justifies its installation and maintenance cost.
+
+The current Weftlet projection discards useful information already present in the index.
+Improving it addresses the immediate need for cited function identities and document bindings
+without introducing another runtime. SCIP references do not prove calls, execution, data flow
+or business intent. Native calls remain unsupported by this projection; a separate measured
+producer could address that gap later.
+
+## Evidence and interpretation
+
+Inputs were frozen at `f1844f31717341f5ff95314a68def80eae509734`; the unchanged baseline engine
+is `f3b0f99cc7f01227925bf7372f3ab7a60f0de62c`. See the [complete measurement record](../evaluations/code-graph-results/2026-10-29/README.md),
+including pinned versions, commands, exported native artifacts, exact citations, per-case results,
+costs, retained failed attempts and scoring amendments. No paid/model calls or private inputs.
+
+Cold results combine two public corpora, without counting repeats as more independent cases:
+
+| Evidence requested | Current Weftlet projection | Richer raw SCIP | Pinned Graphify static API |
+| --- | --- | --- | --- |
+| Declaration families, 15 positive cases | Exact track unsupported; 7 coarse candidates | 15/15 | 14/15 |
+| References, 16 positive cases | Exact track unsupported; 12 coarse candidates | 16/16 | 8/16, including one ambiguous re-export counted as missing |
+| Native calls, 10 positive cases | Unsupported | Unsupported | 7/10; retains native inferred/extracted tags |
+| Ten named false-join negatives | Unsupported in exact track | None asserted | None asserted |
+| Citation/identity failures in these scored outputs | 0 | 0 | 0 |
+
+These are labeled-case results, not whole-graph precision estimates. Hundreds of other references
+are unjudged. Graphify's line-only evidence receives source credit only where the labeled token
+has an unambiguous native target; it does not acquire column precision. Its overload implementation
+counts as a family, while two missing signature spans remain missing. The ambient vendor declaration
+is absent. Other misses include type-use occurrences, test top-level calls and an execution call;
+raw artifacts retain coarser import edges even when exact-use credit is unavailable.
+
+Graphify is faster and lighter on these tiny TypeScript fixtures. For the 21-file business corpus,
+two-sample median extraction phases were 0.808 s for SCIP indexing and 0.035 s for Graphify static
+extraction. Whole worker times were 2.056 s and 1.087 s respectively, including startup; the SCIP
+worker also assembles the unchanged baseline graph. Sampled aggregate process RSS was about
+335 MiB versus 75 MiB, with shared pages potentially counted more than once. Cgroup peaks are
+recorded separately. Small unequal sample counts, warm host caches and different phase boundaries
+do not establish production speed ratios or large-monorepo behavior.
+
+All 96 corrected experimental graph assemblies pass strict SHACL and exact RDF/SPARQL fact
+projection parity. Every arm retrieves the documented collection → execution → notifications →
+mobile chain, relevant test and both freshness rules, and loses the chain when its handoff sentence
+is removed. Billing remains unrelated. Shared Status connects API and mobile in every arm.
+Fixed-document/routing dispatch retrieves 16/16 expected files with zero of seven named distractions;
+code-only retrieves 13/16. Some dispatch queries retain explicit continuation after the three-page
+budget: these are successful labeled retrievals, not exhaustive graph searches.
+
+The fixed business layer is identical across arms. Its documents are declared fixture intent;
+grammar-derived assertions remain inferred/unreviewed. None of these results proves model
+extraction quality, rule compatibility, delivery over a queue, or a function implementing a rule.
+Both tools leave dynamic-target and undeclared-queue gaps silent. Only the richer SCIP adapter
+explicitly reports the external implementation as declaration-only. B3–B5 must address binding,
+obligations and coverage rather than treating absent edges as zero impact.
+
+Repeat and dirty committed-source runs preserve normalized content and identities. Graphify's raw
+dirty output differs only in its absolute `extracted_sources` inventory; nodes/edges are unchanged.
+Edits preserve unrelated identities, rename/delete remove old current spans, omitted worker inputs
+are explicitly excluded, and old snapshots remain unchanged. This tests full re-extraction with
+cached document artifacts, not incremental code indexing. Graphify's pinned JS/TS path does not
+prove useful incremental parse reuse merely because it accepts a cache directory.
+
+## Limits and next implementation boundary
+
+The comparison used Linux, Python 3.12.14, Node 24.19.0, SCIP TypeScript 0.4.0, and pinned Graphify
+source `0a8cd4e1e342235fe53e881fb5d591bf0460071f`. Its source API imports with 30 locked runtime
+distributions; the manifest/lock project-version mismatch is explicitly handled without installing
+a project distribution. This is not a Graphify package, Windows/macOS, multi-language or managed
+service validation. No upstream code or dependency enters the npm packages.
+
+B3a will add first-class code entities and cited occurrences with stable identities, containing
+file/project, declaration spans, references and explicit unresolved/declaration-only states. It
+must retain canonical physical-file kinds, distinguish overload families from spans, and avoid
+joining duplicate names. Explicit document bindings must preserve both source revisions/spans,
+source approval and assertion-review authority. Rename/delete, dirty overlays, cache/version
+identity, historical snapshots, RDF/query parity and fresh installation need regressions before
+publication. Do not copy this experiment's legacy file-to-symbol projection into the public schema
+and call that function-level binding. B3b separately assesses remaining inferred-mapping needs.
+
+The next candidate remains unreleased until the agreed B1–B5 increments and B6 qualification.
+This decision does not mark official 1.0 or private consumer acceptance complete.

package/docs/ADR-032-scip-code-evidence.md

@@ -0,0 +1,73 @@
+# ADR 032: Preserve native SCIP symbols and occurrences
+
+Status: accepted for B3a's first increment. Explicit document-to-symbol bindings and static
+call analysis remain separate work. This implements the projection decision in ADR 031;
+Graphify does not become a runtime dependency.
+
+## Evidence model
+
+`@weftlet/core` exposes `CodeSymbol`, its descriptor, `CodeOccurrence`, `CodeRange` and the
+`codeSymbolNode` factory. The neutral package adds no dependencies. Global symbol IDs hash
+provider, repository identity and the native SCIP symbol. Native `local N` IDs additionally
+include the document path and normalized SCIP index digest: native local ordinals cannot be
+trusted across index revisions. Labels and resolution status are evidence, not ID inputs.
+Renames, package-version changes and tool-native symbol changes can change global IDs; this
+is not automatic identity continuity across refactors.
+
+The toolkit retains every distinct native definition/reference occurrence. Definitions connect
+`CodeSymbol —definedBy→ physical file`. References connect the narrowest unambiguous native
+declaration range's symbol to the target; without such a range, the subject is the cited file
+and enclosure is `file` or `ambiguous`. Multiple spans, overload signatures, recursive references,
+private/local symbols and repeated same-line uses remain separate assertions. Exact duplicate
+native entries deduplicate. Existing file-to-Contract relationships remain for compatibility.
+This is additive evidence, not a claim that the two node types are interchangeable.
+
+Citations carry one-based UTF-16 start/end columns with an exclusive end, committed source digest
+and SHA. A leading UTF-8 BOM stripped by TypeScript is mapped back into committed first-line
+columns. Source files are read as UTF-8; UTF-16 here describes column units, not file encoding.
+Native declaration/body ranges are retained separately; arrow initializer extents may
+exclude the variable name. A zero-width module anchor can precede
+its declaration extent; `locationKind: zero-width-anchor` distinguishes it from an actual name.
+Invalid source ranges fail extraction. Test files retain canonical Evidence identity; static
+inspection is `implemented`/`deterministic`, not proof of a passed test. Overlays are `draft`.
+
+Resolution is `indexed-definition`, `declaration-only` or `no-indexed-definition`. The latter
+includes external or unselected implementations; it does not assert that the target is missing
+from the product. Enclosure is lexical, not execution: SCIP 0.4.0 supplies no declaration extent
+for some local arrow variables, so a nested reference may be attributed to the enclosing outer
+range. Neither a function kind nor a call is inferred from hover text or symbol spelling.
+
+## Shared queries, validation and limits
+
+The complete typed JSON facts and queryable RDF properties use the same snapshot. SHACL checks
+code metadata, scopes, resolution, predicate/role/enclosure structure and column completeness;
+deterministic consistency checks verify role flags, canonical cited files, range ordering and
+zero-width anchor consistency. Existing kind cardinality and intent authority constraints remain intact.
+The optimized union and original named-dataset paths agree on new shape failures.
+
+`graph.neighbors` and `graph.paths` expose exact symbols, spans and bounded continuation through
+the existing API/CLI/MCP. The viewer and Markdown show columns and static-evidence labels.
+Automatic `impact.scan` leaves unresolved code targets terminal, so shared built-ins do not
+create a false impact path between co-users. It reports `codeTraversalVersion: indexed-symbols-v1`
+and `unexpandedCodeTargetCount`, with at most 100 `unexpandedCodeTargets` example IDs and an
+explicit truncation flag; exact neighborhood/path exploration remains available. Continuation
+identity includes this traversal policy. Shared unresolved import behavior is otherwise unchanged.
+
+Occurrence retention increases graph size and can require more query pages. The existing
+100,000-fact projection ceiling still fails explicitly rather than truncating; this is not
+qualification for arbitrary monorepos. Indexing remains full, not incremental SCIP or incremental
+SHACL. B5/B6 must assess project coverage, volume and useful bounded retrieval on the candidate.
+
+## Compatibility and validation
+
+`scip-symbol-extractor` advances from 1.1.0 to 2.0.0 and graph assembly from 7 to 8. Existing saved
+snapshots remain readable, but freshness checks require refresh for current validation. Semantic
+extractor/cache identity is unchanged. Protocol loading, symbol projection and range handling are
+separate modules behind the retained `static.ts` exports; runtime assets are checked in packed installs.
+
+Tests use actual committed public source, real SCIP, hydration, strict RDF/SHACL, SPARQL projection,
+agent-facade pagination and paths, unchanged repeat, dirty saved querying and draft rename/delete.
+The 3,000-line fixture uses explicit comment padding around meaningful functions; it is a location
+and isolation regression, not a production-size performance claim. Unit negatives cover malformed
+ranges, ambiguous scopes, missing targets, native local identity and invalid metadata. The prior
+frozen comparison and scores are unchanged. See VALIDATION.md for executed gates.

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.