@weftlet/toolkit 0.7.1 → 0.7.2

package/README.md

@@ -14,7 +14,7 @@ Proposed future capabilities are recorded in the [Weftlet 2.0 product plan](docs
 ## Set up a project
 
 <!-- weftlet:release:start -->
-Package versions in this checkout/archive: `@weftlet/toolkit@0.7.1` and `@weftlet/core@0.7.1`.
+Package versions in this checkout/archive: `@weftlet/toolkit@0.7.2` and `@weftlet/core@0.7.2`.
 <!-- weftlet:release:end -->
 
 Weftlet uses `@weftlet/toolkit`; its neutral `@weftlet/core` dependency is installed
@@ -468,7 +468,9 @@ the search's total ceiling is 100,000 examinations. Responses report replay work
 Follow `search.continuation` with identical inputs even if a work page contains no completed
 path. Depth cuts and total-work exhaustion remain explicit without pretending all dependencies
 were checked; inspect `frontier` and restart with greater depth or narrower endpoints/relations.
-Paths are deterministic cited associations, not shortest routes or proof of business compatibility.
+Paths enumerate shorter cited routes first, prioritizing a direct connection before unrelated branches.
+They are associations, not proof of business compatibility. Pending frontiers report exact counts
+and up to 32 examples with explicit omissions; candidate-work and depth limits still apply.
 The HTML viewer uses the same engine and continuation on its displayed facts and selected layers.
 See [path semantics and limits](docs/ADR-030-bounded-evidence-paths.md).
 
@@ -484,9 +486,12 @@ pending re-extraction. Queries compare captured file digests with current workin
 report subsequent edits separately from captured and excluded changes. Older overlays without
 capture metadata have unknown freshness. Historical or draft evidence cannot validate a current diff.
 
-Impact queries [rank nearby consumers and varied evidence sources](docs/ADR-012-impact-ranking.md)
+Impact queries [rank nearby consumers and varied evidence sources](docs/ADR-041-bounded-relationship-retrieval.md)
 ahead of repeated detail and shared-import context. Ranking changes ordering, not saved facts or
-the reachable scope. Responses identify the ranking version; after a ranking upgrade, restart
+the reachable scope. Saved local calls, their exact references and consumer relationships precede dense local-variable
+detail within each source; unindexed symbol hubs receive a penalty unless explicitly queried.
+These are ordering signals, not new assertions or proof of execution. All evidence remains in
+the reachable set. Responses identify the ranking version; after a ranking upgrade, restart
 scans whose old continuation tokens are rejected. No snapshot refresh is needed for new ordering.
 
 The published toolkit includes a [coverage reporting correction](docs/ADR-024-implementation-coverage.md)

package/dist/application/saved-paths.d.ts

@@ -37,7 +37,7 @@ export declare class SavedGraphPathService implements GraphPathQueryService {
         diagnostics: import("@weftlet/core").ContextPack["diagnostics"];
         search: {
             readonly version: string;
-            readonly order: "fact-id-depth-first";
+            readonly order: "fact-id-depth-first" | "shortest-first-target-first";
             readonly direction: import("@weftlet/core").GraphDirection;
             readonly predicates: readonly import("@weftlet/core").GraphPredicate[];
             readonly maxDepth: number;

package/dist/graph/impact-signals.d.ts

@@ -0,0 +1,7 @@
+import type { GraphFact, GraphNode } from '@weftlet/core';
+/** Query-order signals from saved evidence, never new assertions or authority. */
+export declare function impactRankingSignals(facts: readonly GraphFact[], anchorTerms: readonly string[]): {
+    penalty: (fact: GraphFact) => 0 | 8;
+    seedNodes: (fact: GraphFact) => GraphNode[];
+    relationshipOrder: (fact: GraphFact) => 0 | 2 | 1;
+};

package/dist/graph/impact-signals.js

@@ -0,0 +1,54 @@
+/** Query-order signals from saved evidence, never new assertions or authority. */
+export function impactRankingSignals(facts, anchorTerms) {
+    const definitions = new Map();
+    const callsiteReferences = new Set();
+    const callableNativeSymbols = new Set();
+    const localCall = (fact) => fact.predicate === 'calls' && fact.codeCall !== undefined &&
+        fact.codeCall.target !== 'external' && fact.codeCall.targetDefinitions.length > 0;
+    for (const fact of facts) {
+        if (fact.codeOccurrence?.role === 'definition' && fact.predicate === 'definedBy') {
+            const paths = definitions.get(fact.subject.id) ?? new Set();
+            paths.add(fact.provenance.path);
+            definitions.set(fact.subject.id, paths);
+        }
+        if (localCall(fact)) {
+            for (const proof of fact.codeCall.targetOccurrences)
+                callsiteReferences.add(proof.factId);
+            if (fact.object.codeSymbol)
+                callableNativeSymbols.add(fact.object.codeSymbol.nativeSymbol);
+        }
+    }
+    const explicit = (node) => anchorTerms.some(term => `${node.id} ${node.label} ${node.codeSymbol?.nativeSymbol ?? ''}`.toLowerCase().includes(term));
+    const unindexed = (node) => node.kind === 'CodeSymbol' &&
+        node.codeSymbol?.resolution === 'no-indexed-definition';
+    const hub = (node) => unindexed(node) && !explicit(node);
+    const penalty = (fact) => [fact.subject, fact.object].some(hub) ? 8 : 0;
+    const seedNodes = (fact) => {
+        const eligible = [fact.subject, fact.object].filter(node => node.kind !== 'Project');
+        const matching = eligible.filter(explicit);
+        if (matching.length)
+            return matching;
+        // A cited local operation's library references must not turn those shared
+        // library identities into zero-distance anchors for all their co-users.
+        const local = eligible.filter(node => !unindexed(node));
+        return local.length ? local : eligible;
+    };
+    const relationshipOrder = (fact) => {
+        if (localCall(fact) || callsiteReferences.has(fact.id))
+            return 0;
+        if (fact.predicate === 'consumes' && fact.object.id.startsWith('symbol:scip:') &&
+            callableNativeSymbols.has(fact.object.label))
+            return 0;
+        if (fact.codeOccurrence?.role === 'reference') {
+            if (explicit(fact.object))
+                return 0;
+            const targetPaths = definitions.get(fact.object.id);
+            if (targetPaths && [...targetPaths].some(path => path !== fact.provenance.path))
+                return 1;
+        }
+        if (fact.codeOccurrence || fact.codeCall)
+            return 2;
+        return 0; // Keep intent, queue/data contracts, validation and legacy adapter relations available.
+    };
+    return { penalty, seedNodes, relationshipOrder };
+}

package/dist/graph/path-search.d.ts

@@ -16,11 +16,13 @@ export declare function searchEvidencePaths(edges: readonly PathEdge[], start: s
     paths: EvidencePath[];
     frontier: {
         pending: {
-            nodeId: string;
-            viaFactIds: string[];
-            nextFactId: string;
-            remainingCandidates: number;
+            readonly nodeId: string;
+            readonly viaFactIds: readonly string[];
+            readonly nextFactId: string;
+            readonly remainingCandidates: number;
         }[];
+        pendingCount: number;
+        omittedPending: number;
         depthLimited: {
             count: number;
             examples: {

package/dist/graph/path-search.js

@@ -14,7 +14,10 @@ export function searchEvidencePaths(edges, start, target, options, knownNodeIds)
     validateBounds();
     const adjacency = new Map();
     const nodeIds = new Set();
-    for (const edge of [...edges].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0)) {
+    // Building adjacency already visits every input edge. Prefer closing edges in
+    // that index; candidate examination below still counts every selected edge.
+    for (const edge of [...edges].sort((a, b) => Number(b.to === target) - Number(a.to === target) ||
+        (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
         const entries = adjacency.get(edge.from) ?? [];
         entries.push(edge);
         adjacency.set(edge.from, entries);
@@ -22,40 +25,55 @@ export function searchEvidencePaths(edges, start, target, options, knownNodeIds)
         nodeIds.add(edge.to);
     }
     const paths = [];
-    const stack = nodeIds.has(start) && nodeIds.has(target) && start !== target ? [{ nodeId: start, next: 0 }] : [];
+    // At most one prefix is allocated per examined edge, bounded by searchLimit.
+    // Parent links retain distinct simple paths without copying whole path arrays.
+    const queue = nodeIds.has(start) && nodeIds.has(target) && start !== target
+        ? [{ nodeId: start, next: 0, depth: 0 }] : [];
+    let head = 0;
     const depthExamples = [];
     let depthCount = 0;
     let totalSteps = 0;
     const trim = () => {
-        while (stack.length && stack.at(-1).next >= (adjacency.get(stack.at(-1).nodeId)?.length ?? 0))
-            stack.pop();
+        while (head < queue.length && queue[head].next >= (adjacency.get(queue[head].nodeId)?.length ?? 0))
+            head++;
+    };
+    const prefixPath = (frame) => {
+        const nodeIds = [], factIds = [];
+        for (let cursor = frame; cursor; cursor = cursor.parent) {
+            nodeIds.push(cursor.nodeId);
+            if (cursor.via !== undefined)
+                factIds.push(cursor.via);
+        }
+        return { nodeIds: nodeIds.reverse(), factIds: factIds.reverse() };
     };
     const step = () => {
-        const frame = stack.at(-1);
+        const frame = queue[head];
         const edge = adjacency.get(frame.nodeId)[frame.next++];
         totalSteps++;
-        if (stack.some(item => item.nodeId === edge.to))
-            return;
-        const viaFactIds = stack.slice(1).map(item => item.via);
-        if (viaFactIds.length === options.maxDepth) {
+        for (let cursor = frame; cursor; cursor = cursor.parent) {
+            if (cursor.nodeId === edge.to)
+                return;
+        }
+        if (frame.depth === options.maxDepth) {
             depthCount++;
             if (depthExamples.length < 20)
-                depthExamples.push({ nodeId: frame.nodeId, viaFactIds,
+                depthExamples.push({ nodeId: frame.nodeId, viaFactIds: prefixPath(frame).factIds,
                     nextFactId: edge.id, nextNodeId: edge.to });
         }
         else if (edge.to === target) {
-            return { nodeIds: [...stack.map(item => item.nodeId), target], factIds: [...viaFactIds, edge.id] };
+            const path = prefixPath(frame);
+            return { nodeIds: [...path.nodeIds, target], factIds: [...path.factIds, edge.id] };
         }
-        else {
-            stack.push({ nodeId: edge.to, next: 0, via: edge.id });
+        else if (adjacency.has(edge.to)) {
+            queue.push({ nodeId: edge.to, next: 0, depth: frame.depth + 1, via: edge.id, parent: frame });
         }
     };
     trim();
-    // Reconstruct only bounded search state. Never accept a caller-supplied stack or facts.
+    // Reconstruct bounded search state; never accept a caller-supplied queue or facts.
     const replay = () => {
         let replayPageSteps = 0;
         let replayPagePaths = 0;
-        while (totalSteps < offset && stack.length) {
+        while (totalSteps < offset && head < queue.length) {
             if (step())
                 replayPagePaths++;
             replayPageSteps++;
@@ -65,26 +83,33 @@ export function searchEvidencePaths(edges, start, target, options, knownNodeIds)
             }
             trim();
         }
-        if (totalSteps !== offset || (offset && (!stack.length || replayPagePaths || replayPageSteps))) {
+        if (totalSteps !== offset || (offset && (head === queue.length || replayPagePaths || replayPageSteps))) {
             throw new Error('Invalid path continuation boundary');
         }
     };
     replay();
     if (!offset && start === target && (nodeIds.has(start) || knownNodeIds?.has(start)))
         paths.push({ nodeIds: [start], factIds: [] });
-    while (stack.length && paths.length < options.maxPaths && totalSteps - offset < options.maxSteps && totalSteps < searchLimit) {
+    while (head < queue.length && paths.length < options.maxPaths && totalSteps - offset < options.maxSteps && totalSteps < searchLimit) {
         const path = step();
         if (path)
             paths.push(path);
         trim();
     }
-    const pending = stack.flatMap((frame, index) => {
+    const pending = [];
+    let pendingCount = 0;
+    for (let index = head; index < queue.length; index++) {
+        const frame = queue[index];
         const entries = adjacency.get(frame.nodeId) ?? [];
-        return frame.next < entries.length ? [{ nodeId: frame.nodeId,
-                viaFactIds: stack.slice(1, index + 1).map(item => item.via), nextFactId: entries[frame.next].id,
-                remainingCandidates: entries.length - frame.next }] : [];
-    });
-    const exhaustedWithinDepth = stack.length === 0;
+        if (frame.next >= entries.length)
+            continue;
+        pendingCount++;
+        if (pending.length < 32)
+            pending.push({ nodeId: frame.nodeId,
+                viaFactIds: prefixPath(frame).factIds, nextFactId: entries[frame.next].id,
+                remainingCandidates: entries.length - frame.next });
+    }
+    const exhaustedWithinDepth = head === queue.length;
     const stopReason = () => {
         if (exhaustedWithinDepth)
             return 'exhausted';
@@ -94,7 +119,8 @@ export function searchEvidencePaths(edges, start, target, options, knownNodeIds)
             return 'path-page-limit';
         return 'work-page-limit';
     };
-    return { paths, frontier: { pending, depthLimited: { count: depthCount, examples: depthExamples,
+    return { paths, frontier: { pending, pendingCount, omittedPending: pendingCount - pending.length,
+            depthLimited: { count: depthCount, examples: depthExamples,
                 omitted: depthCount - depthExamples.length } }, search: { searchLimit, replayedSteps: offset,
             examinedSteps: totalSteps - offset, totalSteps, stopReason: stopReason(), exhaustedWithinDepth,
             depthLimitReached: depthCount > 0, truncated: !exhaustedWithinDepth || depthCount > 0 } };

package/dist/graph/paths-renderer.js

@@ -16,7 +16,7 @@ export function renderGraphPaths(result) {
         `Direction: ${search.direction}; predicates: ${search.predicates.join(', ') || 'all'}; order: ${search.order}`,
         `Depth: ${search.maxDepth}; paths on page: ${result.paths.length}/${search.maxPaths}; stop: ${search.stopReason}; truncated: ${search.truncated}`,
         `Candidate steps: ${search.examinedSteps} new + ${search.replayedSteps} replay; ${search.totalSteps}/${search.searchLimit} total ceiling.`,
-        `Unexamined prefixes: ${frontier.pending.length}; depth-limited extensions: ${frontier.depthLimited.count} (${frontier.depthLimited.omitted} examples omitted).`,
+        `Unexamined prefixes: ${frontier.pendingCount ?? frontier.pending.length} (${frontier.omittedPending ?? 0} examples omitted); depth-limited extensions: ${frontier.depthLimited.count} (${frontier.depthLimited.omitted} examples omitted).`,
         ...(search.continuation ? [`Continuation (same request): ${search.continuation}`] : []),
         ...(search.depthLimitReached ? ['Depth limit reached: restart with a larger maxDepth or explore a frontier node. Continuation does not lift the depth bound.'] : []),
         ...(search.stopReason === 'search-limit' ? ['Total search limit reached: narrow the relations or explore an intermediate node; no further continuation is available.'] : []),

package/dist/graph/paths.d.ts

@@ -1,5 +1,5 @@
 import type { GraphPathQueryService, GraphPaths, GraphPathsRequest, SnapshotStore } from '@weftlet/core';
-export declare const GRAPH_PATHS_VERSION = "simple-evidence-paths-v1";
+export declare const GRAPH_PATHS_VERSION = "simple-evidence-paths-v2";
 export declare class SnapshotGraphPathService implements GraphPathQueryService {
     private readonly store;
     constructor(store: Pick<SnapshotStore, 'read'>);

package/dist/graph/paths.js

@@ -6,7 +6,7 @@ import { selectDiagnostics } from './diagnostics.js';
 import { parseGraphPathsRequest } from './path-request.js';
 import { searchEvidencePaths } from './path-search.js';
 import { renderGraphPaths } from './paths-renderer.js';
-export const GRAPH_PATHS_VERSION = 'simple-evidence-paths-v1';
+export const GRAPH_PATHS_VERSION = 'simple-evidence-paths-v2';
 function continuationOffset(token, binding) {
     if (!token)
         return 0;
@@ -65,7 +65,7 @@ export class SnapshotGraphPathService {
             paths: result.paths, facts, coverage: coverageForFacts(facts, saved),
             diagnostics: selectDiagnostics(saved, {}, facts, [], [], new Set([request.fromNodeId, request.toNodeId,
                 ...facts.flatMap(fact => [fact.subject.id, fact.object.id])])),
-            search: { version: GRAPH_PATHS_VERSION, order: 'fact-id-depth-first', direction: request.direction,
+            search: { version: GRAPH_PATHS_VERSION, order: 'shortest-first-target-first', direction: request.direction,
                 predicates: request.predicates, maxDepth: request.maxDepth, maxPaths: request.maxPaths, maxSteps: request.maxSteps,
                 ...result.search, ...(next ? { continuation: next } : {}) }, frontier: result.frontier,
         };

package/dist/graph/ranking.d.ts

@@ -1,6 +1,6 @@
 import type { GraphFact } from '@weftlet/core';
 /** Binds continuation offsets to the ordering policy; changing this requires restarting a scan. */
-export declare const IMPACT_RANKING_VERSION = "proximity-diversity-v1";
+export declare const IMPACT_RANKING_VERSION = "local-relationships-diversity-v2";
 export declare function factSearchText(fact: GraphFact): string;
 export interface RankedImpactFact {
     readonly fact: GraphFact;

package/dist/graph/ranking.js

@@ -1,6 +1,7 @@
 import { stableJson } from '../infrastructure/util.js';
+import { impactRankingSignals } from './impact-signals.js';
 /** Binds continuation offsets to the ordering policy; changing this requires restarting a scan. */
-export const IMPACT_RANKING_VERSION = 'proximity-diversity-v1';
+export const IMPACT_RANKING_VERSION = 'local-relationships-diversity-v2';
 export function factSearchText(fact) {
     return [fact.subject.id, fact.subject.label, fact.predicate, fact.object.id,
         fact.object.label, fact.provenance.path].join(' ').toLowerCase();
@@ -24,6 +25,9 @@ function stableTie(fact) {
 }
 /** Order an already bounded reachable set. No facts are pruned and no authority is changed. */
 export function rankImpactFacts(facts, direct, anchorTerms, focus) {
+    const signals = impactRankingSignals(facts, anchorTerms);
+    const costs = new Map(facts.map(fact => [fact, signals.penalty(fact)]));
+    const cost = (fact, forward) => Math.max(edgeCost(fact, forward), costs.get(fact));
     const adjacent = new Map();
     const connect = (from, to, cost) => {
         if (from.kind === 'Project' || to.kind === 'Project')
@@ -33,8 +37,8 @@ export function rankImpactFacts(facts, direct, anchorTerms, focus) {
         adjacent.set(from.id, edges);
     };
     for (const fact of facts) {
-        connect(fact.subject, fact.object, edgeCost(fact, true));
-        connect(fact.object, fact.subject, edgeCost(fact, false));
+        connect(fact.subject, fact.object, cost(fact, true));
+        connect(fact.object, fact.subject, cost(fact, false));
     }
     const distance = new Map();
     // Integer edge costs permit a bucket queue: O(edges + maximum path cost), without a heap dependency.
@@ -46,10 +50,8 @@ export function rankImpactFacts(facts, direct, anchorTerms, focus) {
         (pending[cost] ??= []).push(id);
     };
     for (const fact of direct) {
-        const eligible = [fact.subject, fact.object].filter((node) => node.kind !== 'Project');
-        const matching = eligible.filter((node) => anchorTerms.some((term) => `${node.id} ${node.label}`.toLowerCase().includes(term)));
         // Some adapters only identify an anchor through its citation. Keep those queries supported.
-        for (const node of matching.length ? matching : eligible)
+        for (const node of signals.seedNodes(fact))
             enqueue(node.id, 0);
     }
     for (let cost = 0; cost < pending.length; cost++) {
@@ -65,14 +67,20 @@ export function rankImpactFacts(facts, direct, anchorTerms, focus) {
         const text = factSearchText(fact);
         return {
             fact,
-            proximity: directIds.has(fact.id) ? 0 : Math.min((distance.get(fact.subject.id) ?? Infinity) + edgeCost(fact, true), (distance.get(fact.object.id) ?? Infinity) + edgeCost(fact, false)),
+            proximity: costs.get(fact) + (directIds.has(fact.id) ? 0 : Math.min((distance.get(fact.subject.id) ?? Infinity) + cost(fact, true), (distance.get(fact.object.id) ?? Infinity) + cost(fact, false))),
+            relationshipOrder: signals.relationshipOrder(fact),
             focus: focus.filter((term) => text.includes(term)).length,
             tie: stableTie(fact),
         };
     });
     const lexical = (a, b) => a < b ? -1 : a > b ? 1 : 0;
-    const compare = (a, b) => b.focus - a.focus || lexical(a.tie, b.tie) || lexical(a.fact.id, b.fact.id);
-    rows.sort((a, b) => a.proximity - b.proximity || compare(a, b));
+    const compare = (a, b) => a.relationshipOrder - b.relationshipOrder || b.focus - a.focus || lexical(a.tie, b.tie) || lexical(a.fact.id, b.fact.id);
+    // Allocate each source's early slots to relationships before local occurrence
+    // detail. Otherwise hundreds of nearer variable references consume a file's
+    // diversity allowance before its file-to-symbol consumer can be considered.
+    // Final ordering below still charges distance and shared-library penalties.
+    rows.sort((a, b) => costs.get(a.fact) - costs.get(b.fact) ||
+        a.relationshipOrder - b.relationshipOrder || a.proximity - b.proximity || compare(a, b));
     const counts = new Map();
     const diverse = rows.map((row) => {
         const seen = counts.get(row.fact.provenance.path) ?? 0;

package/dist/visualization/viewer-interaction.js

@@ -102,7 +102,7 @@ export function viewerScript() {
           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 + '.';
+          status.textContent += ' Pending prefixes: ' + result.frontier.pendingCount + ' (' + result.frontier.omittedPending + ' examples omitted); 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(); }

package/docs/1.0-WORK-QUEUE.md

@@ -21,6 +21,13 @@ strict SHACL/publication. [ADR 040](ADR-040-bounded-graph-io.md) tracks the hash
 RDF/query and bounded-validation patch. Its public large-corpus lifecycle and hosted Linux/Windows checks
 pass; patch publication and private acceptance remain separate steps. No 1.0 approval is implied.
 
+Consumer follow-up: **0.7.1 is published**. The maintainer reports successful strict hydration,
+persistence/reload and unchanged repeat of 561,777 facts / 174,710 nodes with all 18 cached
+artifacts preserved. That capacity blocker is resolved in the reported run. B6b remains open:
+known direct paths and specific worker `references`/`consumes` assertions were displaced outside
+fixed retrieval budgets. [ADR 041](ADR-041-bounded-relationship-retrieval.md) tracks the bounded
+query-order patch and its public regression; no extraction refresh is needed for that patch.
+
 All three public 554,516-fact strict SHACL passes succeeded but took about 35–37 minutes each
 in this cloud. This is a capacity result, not a 30-minute hydration qualification. B6b must record
 full hydration and agent-query latency on the consumer workload as well as correctness.

package/docs/ADR-012-impact-ranking.md

@@ -1,6 +1,7 @@
 # ADR 012: order impact evidence by proximity and source diversity
 
-Status: implemented as a query-only heuristic; not product policy or an evidence gate.
+Status: historical v1 query heuristic. [ADR 041](ADR-041-bounded-relationship-retrieval.md)
+records the v2 library-hub and relationship-priority revision. Neither is product policy or an evidence gate.
 
 The self-repository evaluation found distractions connected through common imports such as
 `node:fs/promises`. The previous ordering prioritized keyword counts, then Codex/document-link

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

@@ -1,7 +1,7 @@
 # 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.
+Status: B1b shipped in 0.7.0. The query-order revision in [ADR 041](ADR-041-bounded-relationship-retrieval.md)
+replaces depth-first enumeration; publication and consumer acceptance are recorded separately.
 
 ## Meaning and scope
 
@@ -18,8 +18,8 @@ An empty predicate list selects all relations; a nonempty list is an OR filter.
 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,
+Read the same lossless RDF/SPARQL projection as other queries. The 0.7.1 streaming changes
+removed the former 100,000-fact projection ceiling without truncating evidence. 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;
@@ -28,9 +28,10 @@ in snapshot metadata. An exhausted search says nothing about excluded or unextra
 
 ## 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.
+Use deterministic breadth-first traversal. Within each adjacency list, edges ending at the
+requested target precede other edges, followed by assertion ID order independent of locale.
+Completed paths arrive in nondecreasing edge count; a known direct connection is considered
+first even on a high-branching source. This is not relevance, causality or a 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
@@ -40,10 +41,11 @@ candidate count. Adjacency sorts are O(E log E); the existing RDF projection als
 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
+actual facts and diagnostics. A cursor carries only a step offset, never an external queue 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
+Responses report replayed and new steps separately. Replay is at most the total ceiling.
+At most one queued prefix is allocated per examined edge (100,001 including the root); parent
+links share path prefixes, whose depth is bounded by 32. This trades 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;
@@ -53,8 +55,9 @@ The page includes only its completed paths and the union of their unchanged supp
 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,
+Report the exact pending-prefix count and up to 32 examples with fact-ID prefixes, next
+candidate fact IDs and remaining adjacency-candidate counts. Report the omitted example count
+explicitly. 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.
 
@@ -73,9 +76,9 @@ path controls use one result per page, 1,000 new examinations, selectable direct
 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,
+The viewer and service share this deterministic enumeration; labels say "cited path".
+ADR 041 separately revises `impact.scan` ranking; `graph.neighbors` is unchanged.
+No extraction identity, semantic artifact/cache key,
 snapshot format, dependency, rule policy or language support changes.
 
 ## Validation boundary
@@ -92,6 +95,6 @@ fresh installed CLI/MCP assets and continuation. Execute rendered viewer control
 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.
+B1a/B1b mechanisms are implemented; qualification and live product usefulness remain B6.
+No backend replacement or business compatibility inference is implied by paths through the
+existing evidence graph.

package/docs/ADR-041-bounded-relationship-retrieval.md

@@ -0,0 +1,77 @@
+# ADR 041: useful relationships within bounded retrieval
+
+Status: query-only patch; validation and publication status are recorded in VALIDATION.md.
+
+## Evidence and scope
+
+The maintainer reports successful 0.7.1 hydration, strict validation, persistence/reload and
+unchanged repeat on the consumer's 561,777-fact graph, preserving all 18 cached artifacts.
+Two subsequent failures concern retrieval: a known direct path was displaced by deep branches,
+and specific consumer assertions were displaced by standard-library references.
+
+The consumer independently confirmed that the missing `references` and `consumes` assertions
+exist in the same snapshot and are reachable in expansion round two. Their calculated balanced
+positions were 24,801 and 69,207, outside three pages of 60 assertions at depth three. The
+diagnostic reproduced all 180 original result IDs in order without fetching larger pages or
+modifying evidence. This is ranking displacement for those assertions, not missing extraction.
+No private source, artifact or prompt was imported into this repository.
+
+## Path order
+
+Replace fact-ID depth-first traversal with breadth-first traversal. Adjacency preparation places
+edges closing on the exact target first, then sorts by fact ID. A known direct edge therefore
+appears before unrelated branches consume the first page. All distinct simple paths and parallel
+assertions remain eligible; no global visited-node pruning is introduced. Completed paths are
+ordered by nondecreasing edge count, not business importance or causal confidence.
+
+Retain the existing depth, page, candidate-step and cumulative work limits, including counted
+cycle/depth-cut examinations. Graph loading/indexing is still outside the candidate-step budget.
+The FIFO queue allocates at most one parent-linked prefix per examined edge, bounded by 100,001
+including the root. Return exact pending counts, 32 pending-prefix examples and an explicit
+omitted count; retain the existing bounded depth-cut examples. Stateless replay validates page
+boundaries. `simple-evidence-paths-v2` rejects old cursors; the shared HTML engine uses the same
+search. No full-graph completeness or latency guarantee is added.
+
+## Impact order
+
+Keep the reachable set, extraction, depth semantics and evidence-lane balancing unchanged.
+The `local-relationships-diversity-v2` policy revises the existing weighted-distance/source
+diversity heuristic:
+
+- A citation-only match seeds local endpoints before unresolved symbol endpoints. Referencing a
+  common library symbol in a changed function must not make all its co-users distance-zero peers.
+- Edges touching a `CodeSymbol` with `no-indexed-definition` cost at least eight, and assertions
+  touching such a symbol receive eight additional ordering points. Explicit node/label/native-symbol
+  anchor-text matches exempt that node. Missing definitions are not classified as proven libraries;
+  omitted repository code can also be unindexed. All those assertions remain retrievable.
+- Allocate early slots within each provenance source to saved local `calls`, their exact cited
+  reference proofs, and legacy file-to-symbol consumers matching saved local callable identities.
+  Other cross-file references follow before local occurrence detail. Existing product intent,
+  queue/data contracts, validation and adapter assertions retain their ordinary category.
+- Within these categories use distance, focus and stable semantic tie keys. Add the per-source
+  ordinal to the distance score, then retain the existing evidence-lane balancing among equal
+  scores. Distant relationships still pay distance; local variable repetition cannot consume
+  all of a file's early slots before its consumer relationship is considered.
+
+These are explainable ordering signals, not business rules or authority changes. A file-level
+`consumes` relationship still does not establish invocation; a saved static call does not prove
+runtime execution. Explicit library-symbol queries remain supported. Pagination retains every
+reachable assertion exactly once; old ranking cursors fail with restart instructions.
+
+## Acceptance and compatibility
+
+The frozen [public protocol](../evaluations/relationship-retrieval/protocol.md) uses three actual
+TypeScript producer/queue/worker/test flows, real SCIP and call extraction, and deterministic
+cited prose. It scores 36 specific calls, callsite references and legacy consumers separately
+from 12-file discovery. The budget remains depth three, three pages of 60, all 540 assertions
+in the denominator. Compare the same immutable saved snapshot and unchanged reachable counts.
+Report standard-library share independently of the production unindexed-symbol heuristic.
+
+Also check a 1,500-branch direct-edge case at 1,000 steps, every directed four-node graph against
+an exhaustive path oracle, continuation/replay, incoming/both directions, authority/citation
+preservation, shared viewer parity, explicit library queries and strict extraction/publication.
+
+No extractor/assembly identity, semantic cache, persisted encoding, RDF constraints or snapshot
+content changes. Existing 0.7.1 snapshots use the new ordering without hydration or model calls.
+The 0.7.1 streaming/canonical-hash fixes remain intact. This public regression does not close
+private consumer acceptance; TradePilot must retry the original cases with unchanged budgets.

package/docs/RELEASING.md

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

package/docs/VALIDATION.md

@@ -1,5 +1,42 @@
 # Validation evidence
 
+## 0.7.1 consumer follow-up and bounded retrieval patch, 2026-11-03
+
+**Maintainer-reported consumer pass:** the published 0.7.1 toolkit hydrates, strictly validates,
+persists and reloads TradePilot's 561,777 facts / 174,710 nodes. Unchanged repeat preserves the
+snapshot and all 18 semantic artifacts. This closes the reported whole-string capacity blocker
+for that workload; it is not general query-usefulness or official 1.0 acceptance.
+
+**Maintainer-reported remaining defect:** a direct connection was absent from a work-limited
+path page, and relevant worker `references`/`consumes` assertions were absent from three 60-fact
+impact pages at depth three. A read-only consumer diagnostic independently reproduced all
+180 query IDs and the 420,837 reachable count. Both assertions exist in that same snapshot,
+are reached in expansion round two, and were ranked at 24,801 and 69,207. This establishes
+ranking displacement for those assertions. No private source or graph was accessed here.
+
+**Public patch evidence:** [ADR 041](ADR-041-bounded-relationship-retrieval.md) and the
+[frozen comparison](../evaluations/relationship-retrieval/README.md) record query-only changes.
+On the same strictly validated 15,549-fact public TypeScript snapshot, both policies retain
+5,128 reachable assertions per case and the full 540 returned-assertion denominator. Expected
+call, callsite-reference and legacy-consumer retrieval improves from **0/36 to 36/36**;
+12/12 file discovery is unchanged. TypeScript standard-library references change from
+450/540 to 0/540 on those bounded pages. Library facts remain stored/reachable, and explicit
+library-symbol queries pass. Seven evidence files, including all three semantic artifacts,
+retain their exact byte digests after rescoring. No hydration or model calls occur in comparison.
+
+A fresh public extraction/strict-publication test passes with all 36 targets, exact repeated
+page IDs and unchanged evidence bytes. The high-branching query-service regression returns the
+same cited direct edge as impact.scan on page one at depth three, three paths and 1,000 steps,
+with explicit pending/omitted frontier counts. Exhaustive four-node path and shared viewer
+parity checks pass. Extraction/assembly identities, canonical hashing, storage and strict SHACL
+constraints are unchanged. Old query cursors require restart; old snapshots need no refresh.
+
+Exact-head release qualification and hosted platform results are recorded on
+[PR 67](https://github.com/jchewitt/weftlet/pull/67); the evidence above records the local focused checks.
+Private fixed-budget retrieval acceptance remains open; the public comparison is not a claim
+about TradePilot's new result positions. Browser interaction and live provider quality retain
+their existing separate validation status.
+
 ## 0.7.0 large-graph field blocker follow-up, 2026-11-02
 
 Status: public capacity qualification and hosted Linux/Windows checks pass; patch release pending.

package/docs/extraction-manifest.json

@@ -108,7 +108,7 @@
       "destinationPath": "package.json",
       "sourceSha256": "a575dbb2fed8c554b95e8e9b3e03a0c21cab1be7249860bbebc18e046b2ff78d",
       "modified": true,
-      "destinationSha256": "0a47b52a4b8b852572adb9104ea383b243793342ef62f58126991e2f8054284c"
+      "destinationSha256": "5ca2ea1f62e6b8393e731f761a1732a8ccf464948a905ab9fe246ae5d941dda8"
     },
     {
       "sourcePath": "tools/context-graph/packages/core/LICENSE",
@@ -129,7 +129,7 @@
       "destinationPath": "packages/core/README.md",
       "sourceSha256": "6044bf7b9a3dc793f41e2ff048546ed11938957d10a5b143eb1739ac4cd7477c",
       "modified": true,
-      "destinationSha256": "0e2b6e8a2f81fb8ed1cd158964fbaad66b7f4cad12dc099a78f41399aacd79d3"
+      "destinationSha256": "1c0c80c8a85f9240ace5a2f01d102646fa293ef246a5f056eb94c7efa0f6e401"
     },
     {
       "sourcePath": "tools/context-graph/packages/core/THIRD_PARTY_NOTICES.md",
@@ -143,7 +143,7 @@
       "destinationPath": "packages/core/package.json",
       "sourceSha256": "2a29066eb8452f22fafcb06bb035a84dda93c5705dba32aba600a1b7e5aaf19c",
       "modified": true,
-      "destinationSha256": "8651c8521653e12aeb1c7bf32a25dde3c82b76b1bdb455d234a6f45a43dd64c2"
+      "destinationSha256": "4a17cd04c7ec5a3a96ec0767d3883d588dfe6724822f254ed91f452b30b939bc"
     },
     {
       "sourcePath": "tools/context-graph/packages/core/src/core.ts",
@@ -388,7 +388,7 @@
       "destinationPath": "src/graph/query.test.ts",
       "sourceSha256": "ba07c52566da979fcbb451b0c0c99b466521993cb49415ff8b35df2b01d4ecaf",
       "modified": true,
-      "destinationSha256": "7b6653f767c2e7445ec19f0cafc9d3fe97494ae139835ec63d335a7210e62c6c"
+      "destinationSha256": "20f0766299e66d4b5e7bc4577b6b0937c5bf87f2f1858f7b0205172231f0bb4c"
     },
     {
       "sourcePath": "tools/context-graph/src/query.ts",
@@ -634,6 +634,7 @@
     "docs/ADR-038-monorepo-code-coverage.md",
     "docs/ADR-039-mapping-proposals.md",
     "docs/ADR-040-bounded-graph-io.md",
+    "docs/ADR-041-bounded-relationship-retrieval.md",
     "docs/CLOUD-ENVIRONMENT.md",
     "docs/CONSUMER-TRIAL.md",
     "docs/ENVIRONMENT-VALIDATION.md",
@@ -779,6 +780,10 @@
     "evaluations/mapping-proposals/inputs.lock.json",
     "evaluations/mapping-proposals/protocol.json",
     "evaluations/monorepo-coverage/README.md",
+    "evaluations/relationship-retrieval/README.md",
+    "evaluations/relationship-retrieval/baseline.json",
+    "evaluations/relationship-retrieval/candidate.json",
+    "evaluations/relationship-retrieval/protocol.md",
     "evaluations/static-calls/README.md",
     "evaluations/static-calls/results/2026-10-29.json",
     "evaluations/weftlet/baseline.json",
@@ -894,6 +899,8 @@
     "scripts/release-records.test.ts",
     "scripts/release.mjs",
     "scripts/restore-publication-state.mjs",
+    "scripts/retrieval-study/preservation.ts",
+    "scripts/retrieval-study/run.ts",
     "scripts/smoke-mapping-proposals.mjs",
     "scripts/smoke-traversal.mjs",
     "scripts/update-inventory.mjs",
@@ -1012,6 +1019,7 @@
     "src/graph/evidence-description.ts",
     "src/graph/identity-preflight.test.ts",
     "src/graph/identity-preflight.ts",
+    "src/graph/impact-signals.ts",
     "src/graph/neighborhood-renderer.ts",
     "src/graph/neighborhood-request.ts",
     "src/graph/neighborhood.test.ts",
@@ -1095,6 +1103,7 @@
     "tests/fixtures/monorepo-project.ts",
     "tests/fixtures/obligation-project.ts",
     "tests/fixtures/rdf-070-reference.ts",
+    "tests/fixtures/relationship-retrieval-project.ts",
     "tests/fixtures/shacl.ts",
     "tests/fixtures/static-call-project.ts",
     "tests/fixtures/symbol-bindings.ts",
@@ -1111,6 +1120,7 @@
     "tests/rdf-ontology.test.ts",
     "tests/rdf-scaling-parity.test.ts",
     "tests/rdf.test.ts",
+    "tests/relationship-retrieval.test.ts",
     "tests/routing.test.ts",
     "tests/runtime.test.ts",
     "tests/semantic-cache-reuse.test.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weftlet/toolkit",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Evidence-backed context graphs for AI development agents: product intent, contracts, code, tests and runtime behavior",
   "license": "Apache-2.0",
   "type": "module",
@@ -66,7 +66,7 @@
     "rdf-validate-shacl": "0.6.5",
     "sparqljs": "3.7.4",
     "typescript": "5.5.4",
-    "@weftlet/core": "^0.7.1"
+    "@weftlet/core": "^0.7.2"
   },
   "devDependencies": {
     "@changesets/cli": "3.0.3",
@@ -121,6 +121,7 @@
     "release:prepare": "pnpm context-graph:publication-check && node scripts/release.mjs --prepare",
     "release:publish": "node scripts/release.mjs --publish",
     "govern": "tsx src/cli.ts govern --policy architecture.policy.json --output .context-graph/architecture-report.json",
+    "evaluate:retrieval": "tsx scripts/retrieval-study/run.ts",
     "evaluate:impact": "tsx scripts/evaluation/run.ts",
     "evaluate:code:check": "node scripts/code-graph-study/check.mjs",
     "benchmark:shacl": "node scripts/benchmark-shacl.mjs",