@weftlet/toolkit 0.1.2 → 0.2.0

package/dist/graph/query.js

@@ -3,6 +3,7 @@ import { contextPackEvidenceAuthority } from "./authority.js";
 import { RdfEvidenceGraph } from "./rdf.js";
 import { sha256, stableJson } from "../infrastructure/util.js";
 import { diagnosticSummary, selectDiagnostics } from "./diagnostics.js";
+import { factSearchText, IMPACT_RANKING_VERSION, rankImpactFacts } from './ranking.js';
 export const DEFAULT_CONTEXT_PACK_FACTS = 60;
 export const MAX_CONTEXT_PACK_FACTS = 200;
 const contextPackLanes = [
@@ -90,21 +91,6 @@ function focusTerms(values) {
             .filter((value) => value.length >= 4 && !searchStopWords.has(value))),
     ];
 }
-function factSearchText(fact) {
-    return [
-        fact.subject.id,
-        fact.subject.label,
-        fact.predicate,
-        fact.object.id,
-        fact.object.label,
-        fact.provenance.path,
-    ]
-        .join(' ')
-        .toLowerCase();
-}
-function semanticPriority(fact) {
-    return /codex-cli|document-linker/.test(fact.extractor.id) ? 0 : 1;
-}
 function boundedFactLimit(value) {
     if (value === undefined)
         return DEFAULT_CONTEXT_PACK_FACTS;
@@ -121,6 +107,7 @@ export class MarkdownContextPackRenderer {
             `Snapshot: \`${pack.snapshot.snapshotId}\` (${pack.snapshot.commitSha})`,
             `Configuration: ${pack.snapshot.configurationDigest ?? 'legacy/unknown'}; scope: ${pack.snapshot.scope?.join(', ') ?? 'legacy/unknown'}`,
             ...(pack.exploration ? [
+                `Ranking: ${pack.exploration.rankingVersion ?? 'legacy/unknown'}`,
                 `Relationships returned: ${pack.exploration.returned}/${pack.exploration.reachableFacts}; truncated: ${pack.exploration.truncated}; depth limit reached: ${pack.exploration.depthLimitReached}`,
                 ...(pack.exploration.continuation ? [`Continuation: ${pack.exploration.continuation}`] : []),
             ] : []),
@@ -211,7 +198,6 @@ export class SnapshotImpactQueryService {
         const directTerms = anchorTerms.length > 0 ? anchorTerms : focus;
         const direct = snapshot.facts.filter((fact) => this.matches(fact, directTerms));
         const ranked = new Map(direct.map((fact) => [fact.id, fact]));
-        const distance = new Map(direct.map((fact) => [fact.id, 0]));
         let frontier = new Set(direct.flatMap((fact) => [fact.subject, fact.object]
             .filter((node) => node.kind !== 'Project')
             .map((node) => node.id)));
@@ -222,8 +208,6 @@ export class SnapshotImpactQueryService {
                 if (!frontier.has(fact.subject.id) && !frontier.has(fact.object.id))
                     continue;
                 ranked.set(fact.id, fact);
-                if (!distance.has(fact.id))
-                    distance.set(fact.id, depth + 1);
                 for (const node of [fact.subject, fact.object]) {
                     if (node.kind !== 'Project' && !visitedNodes.has(node.id))
                         next.add(node.id);
@@ -233,27 +217,29 @@ export class SnapshotImpactQueryService {
                 visitedNodes.add(node);
             frontier = next;
         }
-        const ordered = [...ranked.values()].sort((left, right) => {
-            const leftText = factSearchText(left);
-            const rightText = factSearchText(right);
-            const leftFocus = focus.filter((term) => leftText.includes(term)).length;
-            const rightFocus = focus.filter((term) => rightText.includes(term)).length;
-            return (rightFocus - leftFocus ||
-                semanticPriority(left) - semanticPriority(right) ||
-                (distance.get(left.id) ?? 4) - (distance.get(right.id) ?? 4) ||
-                left.id.localeCompare(right.id));
-        });
-        const allBalanced = [
-            ...selectBalancedFacts(ordered, ordered.length).facts,
-            ...ordered.filter((fact) => contextPackLaneForFact(fact) === undefined),
-        ];
+        const tiers = new Map();
+        for (const { fact, score } of rankImpactFacts([...ranked.values()], direct, directTerms, focus)) {
+            const tier = tiers.get(score) ?? [];
+            tier.push(fact);
+            tiers.set(score, tier);
+        }
+        // Balance evidence lanes among similarly ranked facts, not across unrelated distance tiers.
+        const allBalanced = [...tiers.values()].flatMap((tier) => [
+            ...selectBalancedFacts(tier, tier.length).facts,
+            ...tier.filter((fact) => contextPackLaneForFact(fact) === undefined),
+        ]);
         const { continuation: _continuation, snapshotId: _snapshotId, ...query } = request;
-        const queryDigest = sha256(stableJson(query));
+        const queryDigest = sha256(stableJson({ ranking: IMPACT_RANKING_VERSION, query }));
         let offset = 0;
         if (request.continuation) {
             if (request.continuation.length > 2048)
                 throw new Error('Invalid continuation');
             const token = JSON.parse(Buffer.from(request.continuation, 'base64url').toString('utf8'));
+            if (!token || typeof token !== 'object' || Array.isArray(token))
+                throw new Error('Invalid continuation');
+            if (token.ranking !== IMPACT_RANKING_VERSION) {
+                throw new Error('Continuation uses a different ranking version; restart the scan without continuation');
+            }
             if (token.snapshot !== snapshot.manifest.snapshotId ||
                 token.digest !== snapshot.manifest.contentDigest || token.query !== queryDigest ||
                 !Number.isInteger(token.offset) || token.offset < 0 || token.offset > allBalanced.length) {
@@ -266,7 +252,7 @@ export class SnapshotImpactQueryService {
         const nextOffset = offset + facts.length;
         const continuation = nextOffset < allBalanced.length ? Buffer.from(JSON.stringify({
             snapshot: snapshot.manifest.snapshotId, digest: snapshot.manifest.contentDigest,
-            query: queryDigest, offset: nextOffset,
+            query: queryDigest, ranking: IMPACT_RANKING_VERSION, offset: nextOffset,
         })).toString('base64url') : undefined;
         const capabilities = [
             ...new Map(facts
@@ -357,6 +343,7 @@ export class SnapshotImpactQueryService {
             },
             diagnostics: selectDiagnostics(snapshot, request, facts, focus, queryDiagnostics),
             exploration: {
+                rankingVersion: IMPACT_RANKING_VERSION,
                 returned: facts.length, reachableFacts: allBalanced.length, maxDepth,
                 depthLimitReached: frontier.size > 0, truncated: Boolean(continuation) || frontier.size > 0,
                 continuation,

package/dist/graph/ranking.d.ts

@@ -0,0 +1,10 @@
+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 function factSearchText(fact: GraphFact): string;
+export interface RankedImpactFact {
+    readonly fact: GraphFact;
+    readonly score: number;
+}
+/** Order an already bounded reachable set. No facts are pruned and no authority is changed. */
+export declare function rankImpactFacts(facts: readonly GraphFact[], direct: readonly GraphFact[], anchorTerms: readonly string[], focus: readonly string[]): readonly RankedImpactFact[];

package/dist/graph/ranking.js

@@ -0,0 +1,85 @@
+import { stableJson } from '../infrastructure/util.js';
+/** Binds continuation offsets to the ordering policy; changing this requires restarting a scan. */
+export const IMPACT_RANKING_VERSION = 'proximity-diversity-v1';
+export function factSearchText(fact) {
+    return [fact.subject.id, fact.subject.label, fact.predicate, fact.object.id,
+        fact.object.label, fact.provenance.path].join(' ').toLowerCase();
+}
+function edgeCost(fact, forward) {
+    // A shared unresolved import is context, not evidence that its co-importers consume this change.
+    if ([fact.subject, fact.object].some((node) => node.id.startsWith('contract:module:')))
+        return 8;
+    // Follow typed definitions towards consumers cheaply; upstream dependencies remain available.
+    if (forward && fact.predicate === 'consumes' && fact.object.kind === 'Contract' &&
+        ['Component', 'Evidence'].includes(fact.subject.kind))
+        return 4;
+    return 1;
+}
+function stableTie(fact) {
+    // Unrelated commit hashes and input order must not decide which otherwise-equal file comes first.
+    return stableJson({ subject: fact.subject.id, predicate: fact.predicate, object: fact.object.id,
+        path: fact.provenance.path, start: fact.provenance.startLine, end: fact.provenance.endLine,
+        extractor: fact.extractor, authority: fact.authority, sourceAuthority: fact.sourceAuthority,
+        extractionReview: fact.extractionReview, confidence: fact.confidence });
+}
+/** Order an already bounded reachable set. No facts are pruned and no authority is changed. */
+export function rankImpactFacts(facts, direct, anchorTerms, focus) {
+    const adjacent = new Map();
+    const connect = (from, to, cost) => {
+        if (from.kind === 'Project' || to.kind === 'Project')
+            return;
+        const edges = adjacent.get(from.id) ?? [];
+        edges.push({ to: to.id, cost });
+        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));
+    }
+    const distance = new Map();
+    // Integer edge costs permit a bucket queue: O(edges + maximum path cost), without a heap dependency.
+    const pending = [];
+    const enqueue = (id, cost) => {
+        if (cost >= (distance.get(id) ?? Infinity))
+            return;
+        distance.set(id, cost);
+        (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)
+            enqueue(node.id, 0);
+    }
+    for (let cost = 0; cost < pending.length; cost++) {
+        for (const id of pending[cost] ?? []) {
+            if (distance.get(id) !== cost)
+                continue;
+            for (const edge of adjacent.get(id) ?? [])
+                enqueue(edge.to, cost + edge.cost);
+        }
+    }
+    const directIds = new Set(direct.map((fact) => fact.id));
+    const rows = facts.map((fact) => {
+        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)),
+            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 counts = new Map();
+    const diverse = rows.map((row) => {
+        const seen = counts.get(row.fact.provenance.path) ?? 0;
+        counts.set(row.fact.provenance.path, seen + 1);
+        // Each additional fact from one source costs one ordinary edge. Details stay on later pages.
+        return { ...row, score: row.proximity + seen };
+    });
+    return diverse.sort((a, b) => a.score - b.score || compare(a, b))
+        .map(({ fact, score }) => ({ fact, score }));
+}

package/dist/interfaces/doctor.js

@@ -3,14 +3,23 @@ import { promisify } from 'node:util';
 import { loadConfig } from "../configuration/config.js";
 import { resolveStorageRoot } from "../configuration/cache.js";
 import { FileSnapshotStore } from "../storage/storage.js";
+import { resolveCodexInvocation } from '../extraction/codex-command.js';
 import { readCodexLoginMode, semanticCommandEnvironment } from '../extraction/codex-auth.js';
 /** Reads readiness only. It never installs tools, prints credentials, or starts a model. */
 export async function diagnoseSetup(configPath) {
     const { config, repositoryRoot } = await loadConfig(configPath);
     const execute = promisify(execFile);
+    const environment = semanticCommandEnvironment(process.env);
     const probe = async (name, args) => {
         try {
-            const result = await execute(name, args, { cwd: repositoryRoot, timeout: 5000, maxBuffer: 8192 });
+            const started = performance.now();
+            const invocation = name === 'codex' ? await resolveCodexInvocation(name, environment) : { command: name, prefixArgs: [] };
+            const remaining = Math.ceil(5000 - (performance.now() - started));
+            if (remaining <= 0)
+                return { available: false, output: '' };
+            const result = await execute(invocation.command, [...invocation.prefixArgs, ...args], {
+                cwd: repositoryRoot, timeout: remaining, maxBuffer: 8192, windowsHide: true, env: name === 'codex' ? environment : process.env,
+            });
             return { available: true, output: `${result.stdout}${result.stderr}` };
         }
         catch {
@@ -18,13 +27,13 @@ export async function diagnoseSetup(configPath) {
         }
     };
     const git = await probe('git', ['--version']);
-    const codex = await probe(process.platform === 'win32' ? 'codex.exe' : 'codex', ['--version']);
+    const codex = await probe('codex', ['--version']);
     const auth = config.semantic.auth;
     const authMode = config.semantic.provider === 'codex-cli' ? auth?.mode ?? 'chatgpt' : undefined;
     const apiKeyEnv = auth?.mode === 'api-key' ? auth.apiKeyEnv ?? 'CODEX_API_KEY' : undefined;
     const apiKeyPresent = apiKeyEnv ? Boolean(process.env[apiKeyEnv]?.trim()) : undefined;
     const loginMode = codex.available && authMode === 'chatgpt'
-        ? await readCodexLoginMode(process.platform === 'win32' ? 'codex.exe' : 'codex', semanticCommandEnvironment(process.env))
+        ? await readCodexLoginMode('codex', environment)
         : undefined;
     const docker = config.ontology.backend === 'opencaesar' ? await probe('docker', ['info']) : undefined;
     const saved = await new FileSnapshotStore(resolveStorageRoot(repositoryRoot, config)).readHead('default');

package/docs/ADR-002-saved-evidence.md

@@ -6,12 +6,18 @@ Status: implemented, with bounded validation.
 Explicit hydration produces committed evidence in disposable archive directories, without
 registering worktrees or requiring the active checkout to be clean. Symlinks/submodules and
 archives larger than 128 MiB are currently rejected; they are not silently partially indexed.
-The archive path requires `git` and `tar`; only Linux is validated.
+The archive path requires `git` and `tar`; Linux and focused hosted Windows checks are
+recorded in [validation](VALIDATION.md). [Committed-tree materialization](../src/repository/committed-tree.ts)
+enforces those isolation and archive bounds.
 
 Snapshot IDs bind configuration and semantic scope in addition to commit and runtime revisions.
 User-scope cache heads are isolated by checkout identity. Snapshots publish via an atomic
 create-if-absent operation; head pointers replace atomically only after a complete snapshot
 exists. Concurrent conflicting content fails instead of replacing a winner.
+[Snapshot storage](../src/storage/storage.ts) and [atomic replacement](../src/storage/atomic-rename.ts)
+implement publication; [hydration](../src/application/hydrator.ts) validates evidence before
+advancing the head. [Lifecycle tests](../tests/snapshot-lifecycle.test.ts) exercise concurrent
+publication and saved querying during edits; their presence alone is not a passing run.
 
 Queries identify source commit, scope, configuration match and excluded working changes.
 Final checks reject dirty working trees, old commits, configuration mismatch and draft overlays.

package/docs/ADR-003-draft-overlays.md

@@ -6,6 +6,8 @@ Status: implemented as a bounded submilestone.
 bytes against checkout HEAD. Identity binds base SHA, base snapshot digest and captured content
 digest, including deletions. Code is reindexed in an independent temporary Git repository;
 the active checkout and its index/branch remain unchanged.
+[Working-content capture](../src/repository/working-content.ts) reads the selected bytes;
+[overlay assembly](../src/application/overlay.ts) performs replacement and publication.
 
 All implementation relationships are rebuilt, so consumer links cannot retain deleted/renamed
 definitions. Affected document assertions and links are invalidated. No model is called and no
@@ -15,6 +17,10 @@ are omitted. Code facts are explicitly draft, including in the viewer.
 Overlay heads are separate from committed heads and isolated by checkout and agent name.
 Select the returned snapshot ID explicitly for querying. Overlay snapshots never satisfy final
 committed-evidence checks.
+[Saved-evidence querying](../src/application/saved-evidence.ts) reports overlay freshness,
+and [snapshot checks](../src/application/snapshot-checks.ts) reject draft evidence for final
+validation. [Overlay tests](../src/application/overlay.test.ts) exercise edits, deletion,
+renames and checkout isolation; this link does not assert a current passing test result.
 
 Bounds: 500 changed paths, 1 MiB per source file, source/configuration scope must match the base.
 Changes outside configured source roots are reported as excluded. This first overlay implementation

package/docs/ADR-004-rdf-query-path.md

@@ -7,6 +7,8 @@ an RDF named graph, with reified provenance, authority, confidence, source diges
 configuration metadata. A structured record preserves compatibility fields. The traversal
 projection is read through SPARQL and has field-for-field equivalence tests, including order.
 The viewer consumes the resulting Context Pack, not an independently extracted graph.
+[RDF projection](../src/graph/rdf.ts) implements the dataset;
+[RDF integration tests](../tests/rdf.test.ts) check projection equivalence and cross-source linkage.
 
 Comunica executes local SELECT queries. Parsed queries reject remote SERVICE/dataset access
 and updates. `rdf-validate-shacl` checks structural integrity and identity-kind consistency.
@@ -19,6 +21,10 @@ depth exhaustion, result truncation and snapshot/query-bound continuation tokens
 results using `--continuation`. Depth exhaustion requires an explicit larger `--max-depth`;
 the result never represents that partial traversal as complete.
 The graph projection itself has a fail-closed 100,000-fact bound.
+[Impact querying](../src/graph/query.ts) produces the [core Context Pack contract](../packages/core/src/core.ts).
+The [MCP interface](../src/interfaces/mcp.ts) exposes that result to agents and the
+[viewer renderer](../src/visualization/visualization.ts) consumes it. [Query tests](../src/graph/query.test.ts)
+exercise bounded retrieval; linked tests are evidence locations, not proof of a passing run.
 
 Only paths explicitly listed in `approvedIntentSources` receive `sourceAuthority: declared`.
 Their extracted assertions remain `authority: inferred` and `extractionReview: unreviewed`.

package/docs/ADR-006-provider-boundaries.md

@@ -9,6 +9,11 @@ CLI subprocesses have cancellation, timeouts, bounded output acceptance and narr
 Errors report safe status metadata instead of private stderr. Hydration limits source scope
 before invoking a provider, stops new work after failures, and reuses immutable artifacts.
 Reasoning settings now participate in Codex cache identity.
+[Semantic hydration](../src/extraction/semantic.ts) owns artifact reuse and validation;
+[Codex command discovery](../src/extraction/codex-command.ts) resolves native/npm launchers,
+and [authentication configuration](../src/extraction/codex-auth.ts) keeps login and API-key modes explicit.
+[Launcher tests](../src/extraction/codex-command.test.ts) exercise synthetic executables without
+claiming live model quality or account authentication.
 
 These changes provide an extension seam, not a claim of interoperability with arbitrary models.
 Additional real adapters require their own live and deterministic tests. The current cloud's

package/docs/ADR-010-committed-source-indexing.md

@@ -0,0 +1,77 @@
+# ADR 010: explicit committed source projects for TypeScript indexing
+
+Status: implemented as an opt-in indexing mode. No product-policy approval or new hard
+architecture rule is implied.
+
+Weftlet's self-evaluation found no SCIP test relationships and no linked shared core
+contract. The build tsconfig excludes tests, and a disposable Git archive has no installed
+workspace links or compiled package outputs. Merely listing `evidenceRoots` does not make
+the TypeScript indexer include those files or resolve their package imports.
+
+Keep ordinary SCIP invocation unchanged. Add `scip.sourceProject` for explicitly selecting
+committed TypeScript files and mapping exact local module names to committed source entry
+points. Generate a separate compiler configuration only in the disposable archive. This
+allows indexing an older SHA without adding a new tsconfig to that commit, installing
+dependencies, running package scripts, rebuilding the consumer, or borrowing dirty files
+or workspace links from its active checkout.
+
+## Configuration
+
+```json
+{
+  "scip": {
+    "version": "0.4.0",
+    "command": "bundled-scip-typescript",
+    "args": ["index", "--no-global-caches"],
+    "sourceProject": {
+      "include": ["src/**/*.ts", "tests/**/*.ts", "packages/core/src/**/*.ts"],
+      "aliases": { "@weftlet/core": "packages/core/src/index.ts" }
+    }
+  }
+}
+```
+
+Paths and globs are relative to the configured repository root, using `/`. Globs support
+`*`, `**` and `?`; list files directly when appropriate. `.ts`, `.tsx`, `.mts` and `.cts`
+files are supported by this selector. Add separate globs for each extension needed.
+Aliases are exact module names, including explicit package subpaths, rather than wildcards.
+Alias targets must exist in the selected commit and match `include`.
+
+Select the files that **define** the contracts as well as their consumers. The pinned SCIP
+indexer emits documents for explicitly selected files; resolving an import does not
+automatically index every file behind it. For example, if an entry point re-exports a type
+from another file, include that definition file too. There is no inferred mapping from
+package `dist` exports to source; the configuration author supplies the source entry point.
+
+This separate program uses ES2022, NodeNext module resolution, preserved JSX, no emit,
+no ambient `types` packages, and the supplied aliases. It does not inherit build tsconfig
+settings. Missing external dependencies and custom build/compiler behavior remain limits;
+this is local symbol analysis, **not** a successful type check or proof of complete dependency
+resolution. Use the existing `scip.args` path with a committed dedicated tsconfig when that
+configuration is more appropriate. Do not combine `sourceProject` with custom commands,
+workspace discovery, inferred configs or additional CLI arguments: this first mode requires
+exactly the command and args above and rejects conflicting choices.
+
+Bounds: 1–100 include patterns, at most 100 aliases and 1–5,000 selected committed files.
+Paths cannot be absolute or escape the repository. Empty selections, missing/unselected
+alias targets and the reserved `.weftlet-scip-source-project.json` path fail before SCIP
+starts. Existing archive protections against symlinks, submodules and oversized archives
+remain in force. The generated project is removed with its disposable tree.
+
+Configuration participates in snapshot/cache identity. Existing immutable snapshots remain
+queryable. Source-project patterns also participate in change tracking and overlay capture,
+including files outside `codeRoots`/`evidenceRoots`. Changed code stays draft; rename/delete
+reindexing replaces relationships. Neither test-file inclusion nor a typed test reference
+establishes that a test ran or passed.
+
+## Evidence and remaining work
+
+Real SCIP regressions cover a workspace entry point, re-exported contract, a test excluded
+by the build config, dirty and ignored files, repeat digest stability, committed renames
+and deletions, and draft capture outside ordinary code roots. A fresh packed consumer
+checks the new runtime assets and an excluded test resolved through a source alias.
+
+The [fixed self-repository evaluation](IMPACT-EVALUATION.md) adds this profile without
+changing its source SHA, expected files, query budgets or ranking. It improves candidate
+retrieval and supplies typed test/core-contract relationships. It does not resolve prose
+intent linkage, external dependency installation, live model quality or query-ranking gaps.

package/docs/ADR-011-explicit-document-links.md

@@ -0,0 +1,48 @@
+# ADR 011: explicit document links with committed targets
+
+Status: implemented; source approval and live semantic review remain separate.
+
+Intent documents can name implementation and test locations using ordinary Markdown links.
+Weftlet parses CommonMark with `mdast-util-from-markdown`, rather than treating every slash
+in prose, code examples and URLs as a repository relationship. Inline and reference-style
+links resolve relative to the source document; a leading `/` denotes the repository root.
+Fragments select the file identity only, not a validated target heading or line. Percent-encoded
+paths are decoded. External URLs, local anchors, images, HTML, fenced code and unused link
+reference definitions do not create mappings. MDX extensions are not interpreted.
+
+For compatibility, literal slash-separated paths in prose and single paths in inline code
+resolve from the repository root. `./` and `../` make a literal path document-relative.
+Use Markdown links for spaces or punctuation in paths. There is no basename search, implicit
+root fallback, extension guessing, directory expansion, remote fetch or active-checkout lookup.
+A stale Markdown link, linked directory or path escaping the repository produces a cited
+`implementationGaps` diagnostic, not a relationship to a guessed target. Unresolved literal
+mentions are ignored: slash-separated prose, package names and examples are not missing-file
+declarations. Use Markdown links when targets need validation. Diagnostics describe extraction gaps;
+this increment does not turn them into hard policy gates. Links to a document verify only
+that its file exists, not that it was selected for semantic extraction.
+
+`document-linker@2.0.0` emits `references` facts using exact committed file identities and the
+source link's line span. Reference-style links cite the definition containing the destination.
+Test filenames use the same Evidence kind as SCIP and repository-file extraction. Distinct
+passages remain distinct facts; repeated identical links within one passage deduplicate.
+Containment of model assertions now cites the assertion's passage, rather than the entire doc.
+Missing targets are rechecked on every committed refresh even when semantic artifacts are reused.
+
+A reference means that the document points to a file. It does not prove that the file fulfills
+intent, that a test passed, or that its prose is correct. Facts stay `authority: inferred`;
+explicit links are `extractionReview: deterministic`. Model containment stays `unreviewed`.
+Only explicit `approvedIntentSources` configuration sets `sourceAuthority: declared`, including
+for links; source approval never approves a model assertion. The Weftlet evaluation continues
+to configure zero approved sources and zero model assertions.
+
+Snapshot assembly advances from `graph-v2` to `graph-v3-links-2.0.0` and binds the linker version
+in both identity and manifest. Refreshes create a different immutable identity; saved v2 snapshots remain readable
+without a provider and are not rewritten. Semantic cache keys are unchanged because model
+extraction is unchanged. Existing overlays conservatively invalidate document references to
+changed/deleted targets and changed prose; they do not invent new approved mappings.
+
+The six evaluation documents now have contributor-facing links attached to descriptions of
+actual responsibilities. These are reviewable navigation evidence, not newly approved policy.
+The original frozen baseline remains intact. A measurement using the new documents changes
+its evidence input and must not be presented as a model-quality or ranking improvement.
+Query ranking, automatic scope expansion and live provider extraction are separate work.

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

@@ -0,0 +1,50 @@
+# ADR 012: order impact evidence by proximity and source diversity
+
+Status: implemented as a query-only heuristic; not 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
+extractor names, before hop distance. Global lane balancing could also bring a distant fact
+forward ahead of close evidence. A large file could contribute many symbol facts before a
+useful downstream consumer appeared.
+
+Keep snapshot extraction, RDF projection, anchor matching, the reachable set, max-depth rules
+and continuation coverage unchanged. Rank the existing bounded set in `graph/ranking.ts`:
+
+- Direct matches start at zero. Other facts use shortest weighted paths from matching anchor
+  nodes. Adapters that identify an anchor only through citations retain endpoint fallback.
+- Ordinary relationships cost one. Following a Component/Evidence `consumes` edge upstream
+  to a typed Contract costs four; following it towards a consumer costs one. This favors
+  downstream consumers while retaining shared contracts and their definitions.
+- Edges touching a generic `contract:module:` import node cost eight in both directions.
+  Sharing a module specifier is weaker impact context than a resolved typed consumer or
+  explicit product relationship. No module name or evaluation target is special-cased.
+- Each additional fact from one provenance path adds one to its ranking score. This trades
+  some repeated detail for earlier evidence from other sources. It is not a per-file cap.
+- Within equal scores, task terms break ties and evidence lanes are balanced. Remaining
+  ties use structural/citation fields with code-point ordering, not commit-derived IDs or
+  runtime locale. Fact IDs only disambiguate otherwise indistinguishable records.
+
+These ordinal weights are reviewable heuristics, not calibrated dependency probabilities.
+They neither change confidence/authority nor claim that proximity proves a product dependency.
+There is no special preference for a model provider, automatic promotion of approved intent,
+new traversal cutoff, or removal of a weak fact. Page through to inspect lower-ranked evidence;
+existing depth exhaustion remains explicit. Snapshot facts, provenance and identities are
+unchanged, so saved evidence can be rescored without an indexer, compiler, provider or refresh.
+
+Responses include `exploration.rankingVersion: proximity-diversity-v1`; the Markdown renderer
+also identifies it. Continuations bind this version as well as snapshot identity/content and
+request. Old or different ranking tokens fail with an instruction to restart the scan, rather
+than reusing an offset against a changed order. Changing this policy requires a version bump.
+The evaluator records the version and rejects changes between pages.
+
+Tests cover many typed consumers of a large source, deep asynchronous relationships, common
+imports with attractive keywords, citation-only adapters, stable order across input shuffles
+and changed commit-derived IDs, full pagination, and old-token rejection. Real TypeScript/RDF
+pipeline integration and packed-consumer queries exercise the same ordering path.
+
+Compare against the exact saved document-link snapshot and unchanged four cases, 60 facts per
+page, three pages, depth 32. Record candidate retrieval and labeled distractions together.
+Even a successful comparison cannot establish exhaustive precision, prove a safe change, or
+replace a broader semantic-quality evaluation. Large-graph performance and interactive browser
+validation remain separate work.

package/docs/ADR-013-relative-module-requests.md

@@ -0,0 +1,58 @@
+# ADR 013: scope relative module request identities
+
+Status: implemented as a correction to literal import evidence. Query ranking is unchanged.
+
+The frozen dispatch evaluation found that two planners importing `./policy.js` shared the
+same generic contract node, although they were in different directories and SCIP correctly
+identified separate policy symbols. This false connection brought refund and audit files
+into dispatch scans. Adjusting ranking cannot correct that underlying identity.
+
+`repository-file-extractor@2.0.0` keeps a literal module request separate from a resolved
+implementation. For ordinary `./` and `../` requests (including `.` and `..`), combine the
+importer's directory with the specifier and normalize POSIX path segments. Git paths use
+the same separators on Windows and Linux. The node ID is `contract:module:./` followed by
+the URI-encoded requested location. Its canonical label and attributes describe a
+`repository-relative-request` with `resolution: unresolved`. Imports from different places
+that request the same location share a node; identical spellings naming different locations
+do not. Labels and attributes stay identical when a node has multiple referring spellings.
+
+Requests escaping the repository, containing backslashes, percent escapes, loader query/hash
+suffixes or control characters remain opaque. Their identity hashes the importer and original
+specifier under the reserved `contract:module:./?` prefix. No path decoding, filesystem lookup,
+basename search, source-suffix substitution, directory-index expansion or module execution occurs.
+The prefixes distinguish these identities from bare imports, whose existing identities remain
+unchanged. Case is preserved. Facts cite the importing line and committed content digest;
+their IDs bind the extractor version and module identity.
+
+This is lexical request identity, not TypeScript/Node resolution. `./policy.js`, `./policy.ts`
+and `./policy/index.js` remain distinct requests even if a consumer's compiler could map them
+to one source. A remaining import after target deletion is still a cited unresolved request;
+it does not assert that the target exists. Importer renames change the relative context,
+and deleted importers contribute no new facts. SCIP remains the source of resolved local
+typed-symbol relationships. Bare aliases, package exports and environment-dependent resolution
+need their own evidence; the simple line-based import recognizer is not a complete parser.
+
+Generic request nodes retain the `contract:module:` prefix and existing ranking treatment.
+No provider preference, confidence/authority promotion, new traversal cutoff or evaluation
+label change accompanies this fix. Typed symbols, explicit document links and queue-routing
+evidence are separate. In particular, matching topic strings still does not establish an
+operational route to the archival consumer in the dispatch evaluation.
+
+Committed refreshes use `graph-v4-links-2.0.0-files-2.0.0` and report both assembly and file
+extractor versions. Draft overlay publication IDs also bind the current file extractor, while
+their capture-v2 digest continues identifying the same working bytes. Overlay manifests report
+the new extraction version even when built on a version-1 base. The committed base and prior
+overlay remain immutable and independently queryable; neither is rewritten or advanced by
+building a draft. Semantic artifact keys are unchanged and unchanged prose remains reusable.
+
+To obtain corrected relationships, explicitly hydrate the desired committed ref or rebuild
+the draft overlay. Querying saved evidence continues to use that evidence's original facts,
+without requiring an indexer, provider, Docker or refresh. A newer extractor does not silently
+repair or reinterpret historical evidence.
+
+Validation covers distinct domains, equivalent requested locations, opaque paths, URI-safe
+identity, preserved bare imports, committed/dirty isolation, importer rename/delete behavior,
+old/new snapshot coexistence, real TypeScript and RDF/SHACL, and installed runtime assets.
+Compare newly extracted facts with the frozen dispatch and Weftlet inputs at the existing
+ranking, case labels and page budgets. Keep missing operational links visible separately
+from retrieval improvements.