@weftlet/toolkit 0.6.0 → 0.7.0

package/dist/visualization/viewer-interaction.js

@@ -1,45 +1,25 @@
-/** One shortest directed path over displayed facts only; it does not add inferred edges. */
-export function findEvidencePath(edges, start, target, maxVisited = 1000) {
-    const queue = [start];
-    const parents = new Map();
-    const visited = new Set([start]);
-    let truncated = false;
-    for (let cursor = 0; cursor < queue.length; cursor++) {
-        const current = queue[cursor];
-        if (current === target) {
-            const edgeIds = [];
-            let node = target;
-            while (parents.has(node)) {
-                const parent = parents.get(node);
-                edgeIds.unshift(parent.edge);
-                node = parent.node;
-            }
-            return { found: true, edgeIds, truncated };
-        }
-        for (const edge of edges.filter((item) => item.from === current)) {
-            if (visited.has(edge.to))
-                continue;
-            if (visited.size >= maxVisited) {
-                truncated = true;
-                continue;
-            }
-            visited.add(edge.to);
-            parents.set(edge.to, { node: current, edge: edge.id });
-            queue.push(edge.to);
-        }
-    }
-    return { found: false, edgeIds: [], truncated };
+import { searchEvidencePaths } from '../graph/path-search.js';
+/** First deterministic simple path over displayed facts; shares the agent search engine. */
+export function findEvidencePath(edges, start, target, maxSteps = 1000) {
+    const result = searchEvidencePaths(edges, start, target, { maxDepth: 32, maxPaths: 1, maxSteps });
+    return { found: result.paths.length > 0, edgeIds: result.paths[0]?.factIds ?? [], truncated: result.search.truncated };
 }
 export function viewerScript() {
     return `
     (() => {
-      const findPath = ${findEvidencePath.toString()};
+      const searchPaths = ${searchEvidencePaths.toString()};
       const model = JSON.parse(document.getElementById('visual-model').textContent);
       const search = document.getElementById('graph-search');
       const cluster = document.getElementById('graph-cluster');
       const detail = document.getElementById('node-detail');
       const target = document.getElementById('path-target');
       const status = document.getElementById('path-status');
+      const nextPath = document.getElementById('next-path');
+      const depth = document.getElementById('path-depth');
+      const direction = document.getElementById('path-direction');
+      const predicate = document.getElementById('path-predicate');
+      let pathOffset = 0;
+      const clearPath = () => { pathOffset = 0; nextPath.disabled = true; pathIds.clear(); status.textContent = ''; };
       const layers = [...document.querySelectorAll('[data-layer]')];
       const edges = [...document.querySelectorAll('[data-visual-edge]')];
       const nodes = [...document.querySelectorAll('[data-visual-node]')];
@@ -74,7 +54,7 @@ export function viewerScript() {
         document.getElementById('visible-count').textContent = count + ' visible relationships from this page';
       };
       const select = (id) => {
-        selected = id; pathIds.clear(); status.textContent = '';
+        selected = id; clearPath();
         detail.replaceChildren();
         const node = model.nodes.find(node => node.id === id);
         const heading = document.createElement('strong');
@@ -88,6 +68,12 @@ export function viewerScript() {
           source.textContent = edge.provenance + ' @ ' + edge.source.commitSha.slice(0,12);
           if (edge.sourceUrl) { source.href = edge.sourceUrl; source.target = '_blank'; source.rel = 'noopener noreferrer'; }
           item.append(document.createElement('br'), source);
+          for (const citation of edge.bindingSources || []) {
+            const link = document.createElement(citation.sourceUrl ? 'a' : 'code');
+            link.textContent = citation.provenance;
+            if (citation.sourceUrl) { link.href = citation.sourceUrl; link.target = '_blank'; link.rel = 'noopener noreferrer'; }
+            item.append(document.createElement('br'), link);
+          }
           const focus = document.createElement('button'); focus.textContent = 'Show source relationships';
           focus.addEventListener('click', () => { search.value = edge.source.path; update(); });
           item.append(document.createElement('br'), focus); detail.append(item);
@@ -98,21 +84,37 @@ export function viewerScript() {
         node.addEventListener('click', () => select(node.dataset.nodeId));
         node.addEventListener('keydown', event => { if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); select(node.dataset.nodeId); } });
       });
-      document.getElementById('highlight-path').addEventListener('click', () => {
+      const showPath = (resume) => {
         if (!selected) { status.textContent = 'Select a start node first.'; return; }
-        const result = findPath(enabledEdges(), selected, target.value);
-        pathIds = new Set(result.edgeIds);
-        status.textContent = result.found ? 'One shortest directed path: ' + result.edgeIds.length + ' relationships.' :
-          'No path found in this displayed page and authority selection. Check coverage and continuation.';
-        if (result.truncated) status.textContent += ' Exploration limit reached.';
-        search.value = ''; cluster.value = ''; document.getElementById('neighbors-only').checked = false;
-        update();
-      });
+        if (!resume) pathOffset = 0;
+        try {
+          const input = enabledEdges().filter(edge => !predicate.value || edge.label === predicate.value).flatMap(edge => {
+            const forward = { id: edge.id, from: edge.from, to: edge.to };
+            const reverse = { id: edge.id, from: edge.to, to: edge.from };
+            return direction.value === 'incoming' ? [reverse] : direction.value === 'outgoing' || edge.from === edge.to ? [forward] : [forward, reverse];
+          });
+          const result = searchPaths(input, selected, target.value, { maxDepth: Number(depth.value), maxPaths: 1, maxSteps: 1000, offset: pathOffset }, new Set(model.nodes.map(node => node.id)));
+          pathOffset = result.search.totalSteps;
+          nextPath.disabled = result.search.exhaustedWithinDepth || result.search.stopReason === 'search-limit';
+          pathIds = new Set(result.paths[0]?.factIds || []);
+          status.textContent = result.paths.length ? 'One cited path: ' + result.paths[0].factIds.length + ' relationships.' : 'No path returned on this search page.';
+          status.textContent += ' Displayed facts and selected authority/relations only; ' + result.search.stopReason + '.';
+          if (!nextPath.disabled) status.textContent += ' Continue to examine remaining branches.';
+          if (result.search.depthLimitReached) status.textContent += ' Depth limit reached; increase depth and restart.';
+          if (result.search.stopReason === 'search-limit') status.textContent += ' Narrow the selection or choose an intermediate node.';
+          status.textContent += ' Pending prefixes: ' + result.frontier.pending.length + '; depth-limited extensions: ' + result.frontier.depthLimited.count + '.';
+          search.value = ''; cluster.value = ''; document.getElementById('neighbors-only').checked = false;
+          update();
+        } catch (error) { clearPath(); status.textContent = error.message; update(); }
+      };
+      document.getElementById('highlight-path').addEventListener('click', () => showPath(false));
+      nextPath.addEventListener('click', () => showPath(true));
+      [target, depth, direction, predicate].forEach(item => item.addEventListener('change', () => { clearPath(); update(); }));
       search.addEventListener('input', update); cluster.addEventListener('change', update);
       document.getElementById('neighbors-only').addEventListener('change', update);
-      layers.forEach(item => item.addEventListener('change', () => { pathIds.clear(); status.textContent = ''; update(); }));
+      layers.forEach(item => item.addEventListener('change', () => { clearPath(); update(); }));
       document.getElementById('reset-filters').addEventListener('click', () => {
-        search.value = ''; cluster.value = ''; selected = undefined; pathIds.clear();
+        search.value = ''; cluster.value = ''; selected = undefined; clearPath();
         document.getElementById('neighbors-only').checked = false;
         layers.forEach(item => { item.checked = true; });
         detail.textContent = 'Select a node to inspect its cited relationships.'; status.textContent = ''; update();

package/dist/visualization/visualization.js

@@ -1,4 +1,7 @@
 // Modified for standalone extraction; see docs/extraction-manifest.json.
+import { factEvidenceDescription } from '../graph/evidence-description.js';
+import { evidenceSources } from './evidence-sources.js';
+import { sourceLocation } from '@weftlet/core';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, extname, resolve } from 'node:path';
 import { repositoryFileNode } from '@weftlet/core';
@@ -136,11 +139,13 @@ function visualModel(pack, sourceUrlTemplate) {
             to: fact.object.id,
             label: fact.predicate,
             authority: contextPackEvidenceAuthority(fact),
-            provenance: `${fact.provenance.path}:${fact.provenance.startLine}`,
-            detail: `confidence ${fact.confidence}; ${fact.extractor.id}@${fact.extractor.version}; source ${fact.sourceAuthority ?? 'see citation'}; extraction ${fact.extractionReview ?? 'unspecified'}` +
+            provenance: `${sourceLocation(fact.provenance)}`,
+            detail: (factEvidenceDescription(fact) ? `${factEvidenceDescription(fact)}; ` : '') + `confidence ${fact.confidence}; ${fact.extractor.id}@${fact.extractor.version}; source ${fact.sourceAuthority ?? 'see citation'}; extraction ${fact.extractionReview ?? 'unspecified'}` +
                 (sourceDescription ? `; ${sourceDescription}` : ''),
             source: fact.provenance,
             sourceUrl: sourceLink(fact.provenance, sourceUrlTemplate),
+            ...(fact.codeBinding || fact.codeCall || fact.contractObligation ? { bindingSources: evidenceSources(fact).map(({ role, provenance }) => ({ provenance: `${role}: ${sourceLocation(provenance)} @ ${provenance.commitSha}`,
+                    sourceUrl: sourceLink(provenance, sourceUrlTemplate) })) } : {}),
         });
     }
     return {
@@ -330,7 +335,7 @@ export function renderContextPackHtml(pack, sourceUrlTemplate) {
         const target = nodes.get(edge.to);
         const sourceLabel = source?.label ?? edge.from;
         const targetLabel = target?.label ?? edge.to;
-        return `<tr data-relationship-row data-edge-id="${escapeXml(edge.id)}" data-authority="${edge.authority}" data-search="${escapeXml(`${sourceLabel} ${edge.from} ${targetLabel} ${edge.to} ${edge.label} ${edge.provenance} ${edge.detail}`.toLowerCase())}"><td><span class="layer layer-${edge.authority}">${edge.authority}</span></td><td><strong>${escapeXml(sourceLabel)}</strong><br /><code>${escapeXml(edge.from)}</code></td><td>${escapeXml(edge.label)}</td><td><strong>${escapeXml(targetLabel)}</strong><br /><code>${escapeXml(edge.to)}</code></td><td>${edge.sourceUrl ? `<a href="${escapeXml(edge.sourceUrl)}" target="_blank" rel="noopener noreferrer">${escapeXml(edge.provenance)}</a>` : escapeXml(edge.provenance)}</td></tr>`;
+        return `<tr data-relationship-row data-edge-id="${escapeXml(edge.id)}" data-authority="${edge.authority}" data-search="${escapeXml(`${sourceLabel} ${edge.from} ${targetLabel} ${edge.to} ${edge.label} ${edge.provenance} ${edge.detail}`.toLowerCase())}"><td><span class="layer layer-${edge.authority}">${edge.authority}</span></td><td><strong>${escapeXml(sourceLabel)}</strong><br /><code>${escapeXml(edge.from)}</code></td><td>${escapeXml(edge.label)}</td><td><strong>${escapeXml(targetLabel)}</strong><br /><code>${escapeXml(edge.to)}</code></td><td>${edge.sourceUrl ? `<a href="${escapeXml(edge.sourceUrl)}" target="_blank" rel="noopener noreferrer">${escapeXml(edge.provenance)}</a>` : escapeXml(edge.provenance)}${(edge.bindingSources ?? []).map(citation => `<br />${citation.sourceUrl ? `<a href="${escapeXml(citation.sourceUrl)}" target="_blank" rel="noopener noreferrer">${escapeXml(citation.provenance)}</a>` : escapeXml(citation.provenance)}`).join('')}</td></tr>`;
     })
         .join('');
     const controls = Object.keys(authorityColors)
@@ -397,8 +402,12 @@ export function renderContextPackHtml(pack, sourceUrlTemplate) {
     ${controls}
     <label>Cluster <select id="graph-cluster"><option value="">All</option>${[...new Set(model.nodes.map(node => node.cluster))].sort().map(cluster => `<option value="${escapeXml(cluster)}">${escapeXml(cluster)}</option>`).join('')}</select></label>
     <label><input type="checkbox" id="neighbors-only" /> Selected node and neighbors</label>
-    <label>Path target <select id="path-target">${model.nodes.map(node => `<option value="${escapeXml(node.id)}">${escapeXml(node.label)}</option>`).join('')}</select></label>
-    <button id="highlight-path" type="button">Highlight directed path</button>
+    <label>Path target <select id="path-target">${model.nodes.map(node => `<option value="${escapeXml(node.id)}">${escapeXml(node.label)} · ${escapeXml(node.id)}</option>`).join('')}</select></label>
+    <label>Direction <select id="path-direction"><option value="outgoing">Outgoing</option><option value="incoming">Incoming</option><option value="both">Both</option></select></label>
+    <label>Relation <select id="path-predicate"><option value="">All</option>${[...new Set(model.edges.map(edge => edge.label))].sort().map(predicate => `<option value="${escapeXml(predicate)}">${escapeXml(predicate)}</option>`).join('')}</select></label>
+    <label>Max depth <input id="path-depth" type="number" min="1" max="32" value="8" /></label>
+    <button id="highlight-path" type="button">Highlight cited path</button>
+    <button id="next-path" type="button" disabled>Continue path search</button>
     <span id="path-status" aria-live="polite"></span>
     <button id="reset-filters" type="button">Reset</button>
     <span id="visible-count" aria-live="polite"></span>

package/docs/1.0-WORK-QUEUE.md

@@ -0,0 +1,38 @@
+# Remaining 1.0 work
+
+This queue tracks implementation increments for [B1–B6](PRE-1.0-BASELINE.md), whose acceptance
+boundaries remain canonical. It supersedes the earlier instruction to rerun the private consumer
+immediately after every patch. On 2026-10-28 the maintainer reported that the filename issue was
+believed to be TradePilot's main blocker and requested the next live test after a new candidate.
+That report is not a recorded private hydration/repeat or product-usefulness pass.
+
+Work in small reviewed increments. Keep a minor candidate version PR open while these changes
+accumulate; publish the next candidate when the agreed scope is ready, then run live acceptance.
+Do not publish official 1.0 solely because deterministic tests or graph hydration succeed.
+
+Maintainer disposition, 2026-11-02: publish **0.7.0** for TradePilot acceptance now. The optional
+B3b proposal feature's live validation is **tentative and deferred**, not a publication blocker
+for this candidate. Prior consumer Codex hydration remains evidence for the established extraction
+flow; it does not validate the new proposal operation. No further feature milestone is scheduled
+before this candidate. B6b and the explicit official 1.0 decision remain open.
+
+| Task | Status / dependency | Deliverable and check |
+| --- | --- | --- |
+| **B1a — Exact node neighborhoods** | Implemented; next candidate pending. Validation in ADR 029 and the change PR | `graph.neighbors` through the shared public API, CLI and MCP. Exact snapshot/node IDs, direction/relation filters, cited assertion pagination, remaining-neighbor counts, further-expansion hints and shared evidence state. Check duplicate labels, cycles, self-links, parallel evidence, missing/deleted nodes, stale/tampered cursors, dirty overlays and real extracted cross-service facts. |
+| **B1b — Bounded dependency paths** | Implemented; next candidate pending. Validation in ADR 030 and the change PR | `graph.paths` enumerates cited simple paths through API/CLI/MCP, with depth/work/output limits, continuation and explicit pending/depth-cut frontier. The offline viewer uses the same search function on displayed facts. Check competing branches, cycles, deep paths, scope omissions and all 4,096 directed four-node graphs against an independent oracle. |
+| **B2a — Freeze code-graph comparison** | Frozen; verifier and fixture typechecks pass | 51 labeled code cases, three explicit gaps, unchanged A1–A3/dispatch controls, eight scenarios, pinned tools and bounded metrics in `evaluations/code-graph`. Read-only verification rejects input/label drift and supports immutable Git refs. No comparative execution or private/model inputs. |
+| **B2b — Run comparison and decide** | Measured; [ADR 031](ADR-031-code-extractor-selection.md) selects richer SCIP projection | Compare current projection, richer raw SCIP and pinned Graphify static extraction. Record correctness, citations, identity stability, cold/edit/repeat cost and packaging. Make an evidence-backed keep/improve/replace decision before B3's code-entity schema. |
+| **B3a — Explicit rule-to-symbol resolution** | Implemented in two increments ([ADR 032](ADR-032-scip-code-evidence.md), [ADR 033](ADR-033-document-symbol-bindings.md)); next candidate pending | Retain local/private symbols, same-file references and repeated source occurrences before resolving explicit document paths/symbol references. Include aliases, overloads, duplicate names, rename/delete and unresolved targets; retain both source spans/revisions and mapping authority. Follow the canonical [same-file acceptance boundary](PRE-1.0-BASELINE.md#same-file-exploration-acceptance). |
+| **B3b — Assess missing mappings** | Deterministic assessment complete ([ADR 034](ADR-034-mapping-gaps.md)); bounded opt-in implementation complete ([ADR 039](ADR-039-mapping-proposals.md)); live validation tentative and deferred by the maintainer for 0.7.0 | Identify gaps remaining after explicit resolution. Evaluate a bounded inference proposal only if justified, with an approved model budget before paid work. Never infer owner approval or silently convert proposed mappings into proven behavior. Record any scoped deferral for maintainer review. |
+| **B3c — Same-file call exploration** | Implemented ([ADR 035](ADR-035-static-call-evidence.md)); next candidate pending | Select and test static call analysis, preserving caller/callee/callsite and unresolved targets. Distinguish direct calls from references and callback registration; never claim observed execution. Meet the public large-file extraction/query acceptance in the canonical boundary, including recursion, unrelated functions, shadowed names, repeated sites and cross-file callers. No duplicate-behavior equivalence or mandatory second indexer. |
+| **B4a — Producer/consumer obligations** | Implemented for explicit declarations ([ADR 036](ADR-036-contract-obligation-declarations.md)); next candidate pending | Represent and retrieve cited guarantees/requirements on queue and stored-data contracts, with domain, stage, units, freshness and version where documented. Keep absent fields unknown. |
+| **B4b — Compatibility acceptance** | Implemented for selected explicit numeric declarations ([ADR 037](ADR-037-selected-contract-compatibility.md)); next candidate pending | Public queue/stored-data cases cover subset, insufficient guarantee, disjoint limits, revalidation and unknowns. Shared `graph.compatibility` retains two cited assertions and follow-up IDs. This is advisory; hard failures require approved deterministic policy. |
+| **B5 — Monorepo coverage** | Implemented for saved TypeScript-family inventory and package boundaries ([ADR 038](ADR-038-monorepo-code-coverage.md)); next candidate pending | `graph.coverage` pages selected/requested/indexed files and package connections; shared overview distinguishes saved scope from returned-page counts. Real barrels, aliases, TSX, independent/omitted services, declaration-only and unresolved external targets are tested. Unknown/zero observations never prove no impact. |
+| **B6a — Candidate qualification** | B1–B5 decisions/increments reviewed | Freeze tasks and expected downstream obligations before measuring. Run public end-to-end, fresh-install and supported Windows/Linux release gates. Publish a minor acceptance candidate with versioned evidence and limitations. |
+| **B6b — Live consumer and 1.0 decision** | Published candidate | TradePilot runs real hydration/repeat and agent follow-up tasks; retain private requests/citations/timings locally and share a sanitized result. Assess usefulness and misses separately from pipeline success. Fix blockers, then explicitly review official 1.0. |
+
+B1a/B1b mechanisms are implemented; candidate qualification and live product usefulness remain B6.
+The measured decision retains SCIP and improves its projection; Graphify is not a runtime dependency. TypeScript/TSX remains the
+tested indexing scope. Browser interaction and live provider quality remain separate evidence;
+the website, bulk documentation generation, approval/backfill workflows and hosted AI remain
+in the [2.0 plan](WEFTLET-2.0-PLAN.md).

package/docs/ADR-028-bounded-artifact-paths.md

@@ -0,0 +1,58 @@
+# ADR 028: bounded physical artifact names
+
+Status: implemented; release status is recorded in [validation](VALIDATION.md).
+
+The consumer reported that long physical artifact/temp names block the traversal → unchanged
+repeat → clean-comparison sequence on Windows. A public regression using traversal, routing and
+an empty runtime-evidence revision reproduces `ENAMETOOLONG` in real SCIP during clean comparison
+on Linux too. Appending `.scip.<UUID>.tmp` to the complete logical identity exceeds the common
+255-byte filename-component limit. RDF and optional OML work directories also embedded the entire
+identity. This is a physical storage defect, not a graph identity, business-rule or SHACL defect.
+
+## Physical names and compatibility
+
+Keep portable literal artifact keys of at most 128 ASCII characters. Longer/nonportable keys
+use `~` followed by the full SHA-256 of the logical key. The `~` namespace is excluded from
+literal logical storage identifiers, preventing a hash from aliasing a user-supplied short key.
+Windows device names are also hashed. Existing logical identifier validation and its 256-character
+limit remain intact; no snapshot, fact, provenance, extractor or cache identity is shortened.
+
+Snapshot JSON, heads, semantic cache storage and SCIP output use this mapping. Generated semantic
+cache keys are already 64-character digests and retain their names. Snapshot reads fall back to
+the old literal filename if the bounded path is absent. Semantic reads retain explicit legacy
+root handling. Skip legacy components that cannot exist within the filename limit (and Windows
+device names on Windows), but propagate other I/O and corrupt-JSON errors.
+
+Existing legacy immutable snapshots/artifacts are checked before publication and retained byte
+for byte. A different content/output digest for the same identity remains an error. Updating a
+long legacy head writes the new bounded head and gives it precedence without modifying history.
+No bulk cache migration, forced extraction or automatic deletion is required. Older toolkit
+versions cannot necessarily read newly hashed long-name entries; use supported store/CLI queries
+with the full logical ID rather than constructing a filename from it.
+
+Staging names are independent UUIDs in the destination directory, preserving same-filesystem
+atomic link/rename publication. Cross-process immutable winner and head replacement semantics
+remain unchanged. SCIP staging files are cleaned after success or failure. RDF/optional OML work
+directories need only a backend prefix and UUID; RDF output digests do not depend on their names.
+The optional OML generated document filenames remain their existing semantic digest keys.
+
+This bounds toolkit-generated components; it does not promise that arbitrary storage-root lengths
+or user source filenames work with every external program's total-path restrictions. The original
+working checkout is not moved or cleaned. Full logical IDs remain in snapshots, head records,
+facts and query responses, and saved evidence remains queryable without providers.
+
+## Validation boundary
+
+The public sequence uses the unchanged Codex adapter with its offline grammar runner, real SCIP,
+RDF/SHACL, document traversal, configured routing and an injected empty runtime provider. First
+hydration extracts six semantic documents; repeat and clean comparison reuse all six. The clean
+identity retains traversal/clean/runtime suffixes and exceeds 215 characters. Content digests and
+all facts/provenance except the containing snapshot ID agree; the original head stays unchanged.
+Generated components are bounded and no staging files remain. The exact sequence is part of the
+existing native Windows traversal suite as well as the Linux suite.
+
+Storage regressions cover 256-character snapshot/artifact/head keys, concurrent immutable writes,
+concurrent head replacement, legacy reads without rewriting bytes, legacy cache roots, collisions
+and unsafe input rejection. Existing cross-process publication tests remain required. Live provider
+calls, private TradePilot acceptance and live openCAESAR compilation are separate; this patch does
+not claim them or change validation constraints, graph semantics or evidence authority.

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.