@weftlet/toolkit 0.1.1 → 0.2.0

package/README.md

@@ -7,11 +7,13 @@ contracts, implementing code, downstream consumers, tests and observed runtime e
 Agents can query cited evidence and explore dependencies across module and asynchronous
 boundaries. See the [roadmap](docs/ROADMAP.md) and [validation](docs/VALIDATION.md) for
 supported capabilities and limitations.
+For a first real-project evaluation, use the [private consumer trial](docs/CONSUMER-TRIAL.md)
+to retain reproducible queries, logs and human-reviewed findings.
 
 ## Set up a project
 
 Weftlet uses `@weftlet/toolkit`; its neutral `@weftlet/core` dependency is installed
-automatically. Both packages are available on npm at `0.1.0`; source now prepares `0.1.1`.
+automatically. Both packages are available on npm at `0.1.2`.
 See [release status](docs/RELEASING.md). Existing Tently users should follow
 the [migration guide](docs/MIGRATING-TO-WEFTLET.md).
 
@@ -100,6 +102,25 @@ Copy `examples/generic-typescript` into a separate repository, or adapt its
 `context-graph.config.json` beside your own sources. Paths resolve relative to that configuration.
 Configure semantic source selection, TypeScript roots/indexer arguments, contract aliases,
 evidence roots, runtime evidence, storage and optional adapter explicitly.
+For tests excluded by the build config or workspace packages whose outputs are absent from
+committed archives, configure an [explicit TypeScript source project](docs/ADR-010-committed-source-indexing.md)
+with selected files and local package aliases.
+
+In a selected document such as `docs/intent.md`, link a responsibility to its sources:
+
+```md
+Committed snapshots stay queryable during edits. See [snapshot storage](../src/storage.ts)
+and [lifecycle checks](../tests/storage.test.ts).
+```
+
+[Explicit document links](docs/ADR-011-explicit-document-links.md) resolve against the recorded
+commit and retain source-line citations. Missing files produce diagnostics; directory mentions
+are not expanded. A reference does not approve intent or establish that a linked test passed.
+
+For a consumer that shares no typed symbol with its producer, opt into
+[explicit routing declarations](docs/ADR-014-routing-declarations.md) using `routingSources`.
+Each committed JSON record names a scoped binding and exact producer/consumer files. These
+are cited candidate dependencies; they do not assert an approved policy or observed delivery.
 
 Install the locally packed core and toolkit tarballs together. The installed commands are
 `weftlet`, `weftlet-mcp`, and the compatible `context-graph` / `context-graph-mcp` aliases. For example, after preparing a release:
@@ -131,6 +152,16 @@ 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)
+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
+scans whose old continuation tokens are rejected. No snapshot refresh is needed for new ordering.
+
+[Relative import evidence](docs/ADR-013-relative-module-requests.md) now scopes module requests
+to the importing directory. An explicit refresh applies this extraction fix; saved snapshots
+keep their original facts. These requests remain unresolved evidence, while SCIP supplies
+typed-symbol links. Matching queue topic strings alone does not establish a downstream route.
+
 ## Evidence limits
 
 Approved owner documents govern intent. Code describes implementation; tests describe what
@@ -149,14 +180,19 @@ Live provider tests are separate from deterministic CI. The maintainer authorize
 export and migration from the published `@launch-echo` names to `@weftlet`. Registry publication requires
 an authorized npm identity. Repository visibility changes require separate authorization.
 
-See [npm release instructions](docs/RELEASING.md) for prepared archives, integrity checks and
-the core-before-toolkit publication sequence.
+For changes that should ship, run `pnpm changeset` and commit the generated release note.
+The bot prepares a version PR; merging it publishes those committed versions and records release
+tags. See [npm release instructions](docs/RELEASING.md) for checks, trust settings and recovery.
 
 See [provider contract](docs/PROVIDERS.md) for bounded extraction and adapters, and
 [architecture policy](docs/architecture-policy.md) for deterministic governance.
 
 See the [bounded viewer guide](docs/VIEWER.md) and [cloud setup](docs/CLOUD-ENVIRONMENT.md).
 
+For development, `pnpm evaluate:impact` measures bounded candidate-file retrieval on Weftlet's
+own committed source without model calls. See the [evaluation protocol and baseline](docs/IMPACT-EVALUATION.md)
+for observed gaps and the distinction between retrieval measurements and live semantic quality.
+
 ## License and provenance
 
 Apache-2.0. See [LICENSE](LICENSE), [NOTICE](NOTICE), and the

package/THIRD_PARTY_NOTICES.md

@@ -388,10 +388,13 @@ Do not edit this file manually.
 | `@traqula/parser-sparql-1-2` | 1.4.0 | MIT | [link](https://github.com/comunica/traqula#readme) |
 | `@traqula/rules-sparql-1-1` | 1.4.0 | MIT | [link](https://github.com/comunica/traqula#readme) |
 | `@traqula/rules-sparql-1-2` | 1.4.0 | MIT | [link](https://github.com/comunica/traqula#readme) |
+| `@types/debug` | 4.1.13 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/debug) |
 | `@types/http-cache-semantics` | 4.2.0 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/http-cache-semantics) |
 | `@types/http-link-header` | 1.0.7 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/http-link-header) |
 | `@types/imurmurhash` | 0.1.4 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/imurmurhash) |
+| `@types/mdast` | 4.0.4 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/mdast) |
 | `@types/minimist` | 1.2.5 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/minimist) |
+| `@types/ms` | 2.1.0 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/ms) |
 | `@types/n3` | 1.26.1 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/n3) |
 | `@types/node` | 18.19.130, 20.19.11, 24.19.2 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node) |
 | `@types/rdfjs__namespace` | 2.0.10 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/rdfjs__namespace) |
@@ -400,6 +403,7 @@ Do not edit this file manually.
 | `@types/spark-md5` | 3.0.5 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/spark-md5) |
 | `@types/sparqljs` | 3.1.12 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/sparqljs) |
 | `@types/triple-beam` | 1.3.5 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/triple-beam) |
+| `@types/unist` | 3.0.3 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/unist) |
 | `@types/uritemplate` | 0.3.6 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/uritemplate) |
 | `@types/uuid` | 10.0.0 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/uuid) |
 | `@types/yargs` | 17.0.35 | MIT | [link](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/yargs) |
@@ -423,6 +427,7 @@ Do not edit this file manually.
 | `bytes` | 3.1.2 | MIT | [link](https://github.com/visionmedia/bytes.js#readme) |
 | `call-bind-apply-helpers` | 1.0.2 | MIT | [link](https://github.com/ljharb/call-bind-apply-helpers#readme) |
 | `call-bound` | 1.0.4 | MIT | [link](https://github.com/ljharb/call-bound#readme) |
+| `character-entities` | 2.0.2 | MIT | [link](https://github.com/wooorm/character-entities#readme) |
 | `clownface` | 2.0.3 | MIT | [link](https://zazuko.github.io/clownface/#/) |
 | `color` | 5.0.3 | MIT | [link](https://github.com/Qix-/color#readme) |
 | `color-convert` | 2.0.1, 3.1.3 | MIT | [link](https://github.com/Qix-/color-convert#readme) |
@@ -438,7 +443,10 @@ Do not edit this file manually.
 | `cross-fetch` | 3.2.0 | MIT | [link](https://github.com/lquixada/cross-fetch) |
 | `cross-spawn` | 7.0.6 | MIT | [link](https://github.com/moxystudio/node-cross-spawn) |
 | `debug` | 4.4.3 | MIT | [link](https://github.com/debug-js/debug#readme) |
+| `decode-named-character-reference` | 1.3.0 | MIT | [link](https://github.com/wooorm/decode-named-character-reference#readme) |
 | `depd` | 2.0.0 | MIT | [link](https://github.com/dougwilson/nodejs-depd#readme) |
+| `dequal` | 2.0.3 | MIT | [link](https://github.com/lukeed/dequal#readme) |
+| `devlop` | 1.1.0 | MIT | [link](https://github.com/wooorm/devlop#readme) |
 | `dom-serializer` | 2.0.0 | MIT | [link](https://github.com/cheeriojs/dom-serializer#readme) |
 | `dunder-proto` | 1.0.1 | MIT | [link](https://github.com/es-shims/dunder-proto#readme) |
 | `ee-first` | 1.1.1 | MIT | [link](https://github.com/jonathanong/ee-first#readme) |
@@ -495,9 +503,33 @@ Do not edit this file manually.
 | `kuler` | 2.0.0 | MIT | [link](https://github.com/3rd-Eden/kuler) |
 | `logform` | 2.7.0 | MIT | [link](https://github.com/winstonjs/logform#readme) |
 | `math-intrinsics` | 1.1.0 | MIT | [link](https://github.com/es-shims/math-intrinsics#readme) |
+| `mdast-util-from-markdown` | 2.1.0 | MIT | [link](https://github.com/syntax-tree/mdast-util-from-markdown#readme) |
+| `mdast-util-to-string` | 4.0.0 | MIT | [link](https://github.com/syntax-tree/mdast-util-to-string#readme) |
 | `media-typer` | 1.1.1 | MIT | [link](https://github.com/jshttp/media-typer#readme) |
 | `merge-descriptors` | 2.0.0 | MIT | [link](https://github.com/sindresorhus/merge-descriptors#readme) |
 | `microdata-rdf-streaming-parser` | 2.0.1, 3.0.0 | MIT | [link](https://github.com/rubensworks/microdata-rdf-streaming-parser.js#readme) |
+| `micromark` | 4.0.3 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-core-commonmark` | 2.0.4 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-factory-destination` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-factory-label` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-factory-space` | 2.1.0 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-factory-title` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-factory-whitespace` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-character` | 2.1.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-chunked` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-classify-character` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-combine-extensions` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-decode-numeric-character-reference` | 2.0.2 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-decode-string` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-edit-map` | 1.0.0 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-encode` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-html-tag-name` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-normalize-identifier` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-resolve-all` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-sanitize-uri` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-subtokenize` | 2.1.0 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-symbol` | 2.0.1 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
+| `micromark-util-types` | 2.0.3 | MIT | [link](https://github.com/micromark/micromark/tree/main#readme) |
 | `mime-db` | 1.54.0 | MIT | [link](https://github.com/jshttp/mime-db#readme) |
 | `mime-types` | 3.0.2 | MIT | [link](https://github.com/jshttp/mime-types#readme) |
 | `minimist` | 1.2.8 | MIT | [link](https://github.com/minimistjs/minimist) |
@@ -576,6 +608,7 @@ Do not edit this file manually.
 | `type-is` | 2.1.0 | MIT | [link](https://github.com/jshttp/type-is#readme) |
 | `undici` | 8.12.3 | MIT | [link](https://undici.nodejs.org) |
 | `undici-types` | 5.26.5, 6.21.0, 7.24.6 | MIT | [link](https://undici.nodejs.org) |
+| `unist-util-stringify-position` | 4.0.0 | MIT | [link](https://github.com/syntax-tree/unist-util-stringify-position#readme) |
 | `unpipe` | 1.0.0 | MIT | [link](https://github.com/stream-utils/unpipe#readme) |
 | `uritemplate` | 0.3.4 | MIT | [link](https://www.github.com/fxa/uritemplate-js) |
 | `util-deprecate` | 1.0.2 | MIT | [link](https://github.com/TooTallNate/util-deprecate) |

package/dist/application/hydrator.js

@@ -1,9 +1,12 @@
+import { scipSourcePatterns } from '../configuration/scip-project.js';
 import { contractPatternRoots } from "../repository/glob.js";
+import { repositoryFileExtractorIdentity } from '../extraction/static.js';
 import { sha256, stableJson } from "../infrastructure/util.js";
-import { linkSemanticDocuments } from "../extraction/document.js";
+import { documentLinkerIdentity, linkSemanticDocuments } from "../extraction/document.js";
 import { runtimeEvidenceFacts } from "../extraction/runtime-evidence.js";
 import { matchesRepositoryGlob } from "../repository/glob.js";
 import { RdfEvidenceGraph } from "../graph/rdf.js";
+import { extractRoutingDeclarations, routingExtractorIdentity } from '../extraction/routing.js';
 async function concurrentMap(values, concurrency, worker) {
     const results = new Array(values.length);
     let cursor = 0;
@@ -70,6 +73,8 @@ export class ContextGraphHydrator {
                 ...config.codeRoots,
                 ...config.evidenceRoots,
                 ...contractPatternRoots(config.contractPatterns),
+                ...contractPatternRoots(scipSourcePatterns(config.scip.sourceProject)),
+                ...(config.routingSources ?? []),
             ]),
         ];
         const delta = await repository.delta(baseSha, commitSha, allRoots);
@@ -87,7 +92,9 @@ export class ContextGraphHydrator {
             : undefined;
         const configurationDigest = sha256(stableJson(config));
         const scopeDigest = sha256(stableJson(selectedSemanticSources)).slice(0, 12);
-        const effectiveSuffix = ['graph-v2', configurationDigest.slice(0, 16), scopeDigest, baseSuffix, runtimeSuffix].filter(Boolean).join('-');
+        const effectiveSuffix = ['graph-v4', `links-${documentLinkerIdentity.version}`, `files-${repositoryFileExtractorIdentity.version}`,
+            ...(config.routingSources?.length ? [`routes-${routingExtractorIdentity.version}`] : []),
+            configurationDigest.slice(0, 16), scopeDigest, baseSuffix, runtimeSuffix].filter(Boolean).join('-');
         const snapshotId = effectiveSuffix ? `${commitSha}-${effectiveSuffix}` : commitSha;
         const context = {
             repositoryRoot: repository.root,
@@ -101,6 +108,8 @@ export class ContextGraphHydrator {
             renamedPaths: delta.renamedPaths,
             semanticPaths: selectedSemanticSources,
         };
+        // Validate committed routing inputs before invoking any provider or indexer.
+        const routing = await extractRoutingDeclarations(repository, context, config.routingSources ?? []);
         const sources = await repository.semanticSources(context, selectedSemanticSources);
         if (sources.length > (config.semantic.maxDocuments ?? 8) ||
             sources.some((source) => Buffer.byteLength(source.content) > (config.semantic.maxSourceBytes ?? 65_536))) {
@@ -177,13 +186,15 @@ export class ContextGraphHydrator {
                     });
             }
         }
-        const documentFacts = linkSemanticDocuments(context, hydrated, trackedPaths);
+        const documents = linkSemanticDocuments(context, hydrated, trackedPaths, sources.filter((source) => config.approvedIntentSources?.some((pattern) => matchesRepositoryGlob(source.path, pattern))).map((source) => source.path));
+        diagnostics.push(...documents.diagnostics);
+        diagnostics.push(...routing.diagnostics);
         options.signal?.throwIfAborted();
         options.onProgress?.({ phase: 'compile-semantic-rdf' });
         const ontology = await this.dependencies.ontologyCompiler.compile(snapshotId, artifacts, context);
         const runtimeEvidence = runtimeRevision.references;
         const runtimeFacts = runtimeEvidenceFacts(context, runtimeEvidence);
-        const facts = [...semanticFacts, ...documentFacts, ...extractorFacts, ...runtimeFacts].sort((left, right) => left.id.localeCompare(right.id));
+        const facts = [...semanticFacts, ...documents.facts, ...extractorFacts, ...routing.facts, ...runtimeFacts].sort((left, right) => left.id.localeCompare(right.id));
         const invariants = (await Promise.all(this.dependencies.invariantEvaluators.map((evaluator) => evaluator.evaluate(snapshotId, facts)))).flat();
         const failures = invariants.filter((invariant) => invariant.status === 'fail');
         if (failures.length > 0) {
@@ -224,7 +235,9 @@ export class ContextGraphHydrator {
                 scope: selectedSemanticSources,
                 ontologyVersion: config.semantic.ontologyVersion,
                 extractorVersions: {
-                    assembly: 'standalone-graph-v2',
+                    assembly: 'standalone-graph-v4',
+                    [documentLinkerIdentity.id]: documentLinkerIdentity.version,
+                    ...(config.routingSources?.length ? { [routingExtractorIdentity.id]: routingExtractorIdentity.version } : {}),
                     semantic: config.semantic.extractorVersion,
                     scip: scip.version,
                     ontology: config.ontology.toolVersion,

package/dist/application/overlay.js

@@ -2,15 +2,19 @@ import { execFile } from 'node:child_process';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { promisify } from 'node:util';
+import { scipSourcePatterns } from '../configuration/scip-project.js';
 import { GitRepository } from "../repository/git.js";
 import { withCommittedTree } from "../repository/committed-tree.js";
-import { RepositoryContractExtractor, RepositoryFileExtractor, ScipSymbolExtractor, ScipTypeScriptIndexer } from "../extraction/static.js";
+import { RepositoryContractExtractor, RepositoryFileExtractor, ScipSymbolExtractor, ScipTypeScriptIndexer, repositoryFileExtractorIdentity } from "../extraction/static.js";
 import { sha256, stableJson } from "../infrastructure/util.js";
 import { contextPackEvidenceAuthority } from "../graph/query.js";
 import { inWorkingScope, readWorkingContent } from "../repository/working-content.js";
+import { extractRoutingDeclarations, routingExtractorIdentity } from '../extraction/routing.js';
+import { RdfEvidenceGraph } from '../graph/rdf.js';
 const execute = promisify(execFile);
 const implementationExtractors = new Set([
     'repository-file-extractor', 'repository-contract-extractor', 'scip-symbol-extractor',
+    routingExtractorIdentity.id,
 ]);
 /** Conservative code overlay: reindex implementation; invalidate changed prose, never synthesize intent. */
 export async function buildWorkingOverlay(repository, config, store, storageRoot, baseSnapshotId, agent = 'default') {
@@ -27,8 +31,14 @@ export async function buildWorkingOverlay(repository, config, store, storageRoot
     if (changed.length > 500)
         throw new Error('Overlay exceeds the 500 changed-path bound');
     const captured = [];
+    const routingSources = config.routingSources ?? [];
+    const baseRouting = await extractRoutingDeclarations(repository, {
+        repositoryRoot: repository.root, repositoryId: config.repositoryId, ref: head,
+        commitSha: head, snapshotId: baseSnapshotId, changedPaths: [], deletedPaths: [], renamedPaths: {},
+    }, routingSources, { allowMissingSources: true });
     const roots = [...config.codeRoots, ...config.semanticSources, ...config.evidenceRoots,
-        ...config.contractPatterns];
+        ...config.contractPatterns, ...scipSourcePatterns(config.scip.sourceProject),
+        ...routingSources, ...baseRouting.referencedPaths];
     const excluded = [];
     for (const path of changed) {
         if (!inWorkingScope(path, roots)) {
@@ -43,9 +53,15 @@ export async function buildWorkingOverlay(repository, config, store, storageRoot
         sourcePatterns: roots, excludedPaths: excluded,
     };
     const overlayDigest = sha256(stableJson({ version: 2, ...overlayCapture }));
-    const snapshotId = `${head}-overlay-${sha256(base.manifest.contentDigest + overlayDigest).slice(0, 32)}`;
+    // Capture identity describes the same working bytes across extractor upgrades. Publication
+    // identity also binds the extractor so rebuilding an old base cannot replace an old overlay.
+    const snapshotId = `${head}-overlay-${sha256(stableJson({
+        baseContentDigest: base.manifest.contentDigest, overlayDigest,
+        repositoryFileExtractor: repositoryFileExtractorIdentity,
+        ...(routingSources.length ? { routingExtractor: routingExtractorIdentity } : {}),
+    })).slice(0, 32)}`;
     const affected = new Set(captured.map((file) => file.path));
-    const facts = await withCommittedTree(repository.root, head, async (root) => {
+    const extracted = await withCommittedTree(repository.root, head, async (root) => {
         for (const file of captured) {
             const target = join(root, file.path);
             if (file.content === null)
@@ -57,7 +73,9 @@ export async function buildWorkingOverlay(repository, config, store, storageRoot
         }
         const git = (...args) => execute('git', args, { cwd: root });
         await git('init', '--quiet');
-        await git('add', '.');
+        // The archive already contains only committed files plus explicitly captured changes.
+        // Preserve tracked inputs even when their repository .gitignore also matches them.
+        await git('add', '--force', '.');
         await git('-c', 'user.name=Context Graph Draft', '-c', 'user.email=draft@example.invalid', '-c', 'commit.gpgsign=false', 'commit', '--quiet', '-m', 'Isolated overlay input');
         const draftRepository = new GitRepository(root);
         const context = {
@@ -68,28 +86,44 @@ export async function buildWorkingOverlay(repository, config, store, storageRoot
             renamedPaths: {},
         };
         const scip = await new ScipTypeScriptIndexer(config.scip, storageRoot).index(context);
+        const routing = await extractRoutingDeclarations(draftRepository, context, routingSources, { allowMissingSources: true });
+        const uncapturedEndpoints = routing.referencedPaths.filter((path) => !inWorkingScope(path, roots));
+        if (uncapturedEndpoints.length) {
+            throw new Error(`Draft routing endpoints are outside captured source scope; add them to configured source scope before rebuilding: ${uncapturedEndpoints.join(', ')}`);
+        }
         const extractors = [
             new RepositoryFileExtractor(draftRepository, config.codeRoots, scip.digest),
             new RepositoryContractExtractor(draftRepository, config.contractPatterns, config.contractConsumerRoots ?? config.codeRoots, config.contractAliases),
             new ScipSymbolExtractor(draftRepository, scip),
         ];
-        return (await Promise.all(extractors.map((e) => e.extract(context)))).flat().map(({ id: _id, ...fact }) => {
+        const facts = [...(await Promise.all(extractors.map((e) => e.extract(context)))).flat(),
+            ...routing.facts].map(({ id: _id, ...fact }) => {
             const draft = { ...fact, snapshotId, authority: 'draft',
+                ...(fact.extractor.id === routingExtractorIdentity.id ? { sourceAuthority: 'draft' } : {}),
                 provenance: { ...fact.provenance, commitSha: head } };
             return { ...draft, id: sha256(stableJson(draft)) };
         });
+        const diagnostics = routing.diagnostics.map(({ id: _id, ...item }) => {
+            const draft = { ...item, provenance: item.provenance.map((span) => ({ ...span, commitSha: head })) };
+            return { ...draft, id: sha256(stableJson(draft)) };
+        }).sort((a, b) => a.id.localeCompare(b.id));
+        return { facts, diagnostics };
     });
     const retained = base.facts.filter((fact) => !implementationExtractors.has(fact.extractor.id) &&
         contextPackEvidenceAuthority(fact) !== 'implemented' &&
         fact.extractor.id !== 'otlp-runtime-evidence' &&
         !affected.has(fact.provenance.path) &&
         ![fact.subject, fact.object].some((node) => [...affected].some((path) => node.id === `component:file:${path}` || node.id === `document:${path}` || node.label === path))).map((fact) => ({ ...fact, snapshotId }));
-    const allFacts = [...retained, ...facts].sort((a, b) => a.id.localeCompare(b.id));
+    const allFacts = [...retained, ...extracted.facts].sort((a, b) => a.id.localeCompare(b.id));
     const overlay = {
         ...base,
         manifest: {
             ...base.manifest, snapshotId, baseSha: head, overlayDigest, overlayCapture,
-            generatedAt: new Date().toISOString(), contentDigest: sha256(stableJson(allFacts)),
+            extractorVersions: { ...base.manifest.extractorVersions,
+                [repositoryFileExtractorIdentity.id]: repositoryFileExtractorIdentity.version,
+                ...(routingSources.length ? { [routingExtractorIdentity.id]: routingExtractorIdentity.version } : {}) },
+            generatedAt: new Date().toISOString(), contentDigest: sha256(stableJson(routingSources.length
+                ? { facts: allFacts, diagnostics: extracted.diagnostics } : allFacts)),
         },
         facts: allFacts,
         invariants: base.invariants.map((rule) => ({
@@ -100,8 +134,11 @@ export async function buildWorkingOverlay(repository, config, store, storageRoot
             'Draft implementation overlay: changed semantic documents require explicit re-extraction.',
             `Changes outside configured source scope are excluded: ${excluded.join(', ') || '(none)'}`,
         ],
-        diagnostics: [],
+        diagnostics: extracted.diagnostics,
     };
+    if (routingSources.length && !(await new RdfEvidenceGraph(overlay).validate()).conforms) {
+        throw new Error('Draft routing overlay failed SHACL validation; saved evidence was preserved');
+    }
     if (await repository.resolveRef('HEAD') !== head)
         throw new Error('HEAD changed during overlay capture; retry');
     await store.write(overlay);

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

@@ -27,6 +27,7 @@ export declare class SavedEvidenceQueryService implements ImpactQueryService {
         coverage: import("@weftlet/core").ContextPackCoverage;
         diagnostics: import("@weftlet/core").DiagnosticReport;
         exploration?: {
+            readonly rankingVersion?: string;
             readonly returned: number;
             readonly reachableFacts: number;
             readonly maxDepth: number;

package/dist/configuration/config.d.ts

@@ -1,3 +1,4 @@
+import { type ScipSourceProject } from './scip-project.js';
 export interface ContextGraphConfig {
     readonly schemaVersion: 1;
     readonly repositoryRoot?: string;
@@ -12,6 +13,8 @@ export interface ContextGraphConfig {
     readonly contractConsumerRoots?: readonly string[];
     readonly contractAliases?: Readonly<Record<string, readonly string[]>>;
     readonly evidenceRoots: readonly string[];
+    /** Exact committed JSON routing declarations; opt-in, not approved intent or runtime evidence. */
+    readonly routingSources?: readonly string[];
     readonly semantic: {
         readonly provider: 'codex-cli' | 'module';
         /** Codex authentication only; secrets stay in the process environment. */
@@ -41,6 +44,7 @@ export interface ContextGraphConfig {
         readonly version: string;
         readonly command: string;
         readonly args: readonly string[];
+        readonly sourceProject?: ScipSourceProject;
     };
     readonly ontology: {
         readonly backend?: 'rdf' | 'opencaesar';

package/dist/configuration/config.js

@@ -2,6 +2,7 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
+import { assertScipSourceProject, assertSourceProjectInvocation } from './scip-project.js';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -33,6 +34,13 @@ function validateConfig(value, absolutePath) {
     if (value.approvedIntentSources !== undefined) {
         requireConfig(isStringArray(value.approvedIntentSources), 'approvedIntentSources must be an array of strings', absolutePath);
     }
+    if (value.routingSources !== undefined) {
+        requireConfig(isStringArray(value.routingSources) && value.routingSources.length <= 16 &&
+            new Set(value.routingSources).size === value.routingSources.length &&
+            value.routingSources.every((path) => path.endsWith('.json') && path === path.trim() && path.length <= 1024 &&
+                !/[\\:*?#[\]{}%\x00-\x1f\x7f-\x9f]/.test(path) &&
+                path.split('/').every((part) => part.length > 0 && part !== '.' && part !== '..')), 'routingSources must contain at most 16 unique exact repository-relative .json paths', absolutePath);
+    }
     for (const field of [
         'semanticSources',
         'codeRoots',
@@ -131,6 +139,10 @@ function validateConfig(value, absolutePath) {
         requireConfig(isNonEmptyString(value.scip.version), 'scip.version is required', absolutePath);
         requireConfig(isNonEmptyString(value.scip.command), 'scip.command is required', absolutePath);
         requireConfig(isStringArray(value.scip.args), 'scip.args must be an array of strings', absolutePath);
+        if (value.scip.sourceProject !== undefined) {
+            assertScipSourceProject(value.scip.sourceProject);
+            assertSourceProjectInvocation(value.scip.command, value.scip.args);
+        }
     }
     requireConfig(isRecord(value.ontology), 'ontology must be an object', absolutePath);
     if (isRecord(value.ontology)) {

package/dist/configuration/scip-project.d.ts

@@ -0,0 +1,9 @@
+/** Explicit source-only indexing, independent of a consumer's build tsconfig. */
+export interface ScipSourceProject {
+    readonly include: readonly string[];
+    readonly aliases?: Readonly<Record<string, string>>;
+}
+/** Also used by direct indexer callers, which need not pass through loadConfig. */
+export declare function assertScipSourceProject(value: unknown): asserts value is ScipSourceProject;
+export declare function assertSourceProjectInvocation(command: string, args: readonly string[]): void;
+export declare function scipSourcePatterns(project: ScipSourceProject | undefined): readonly string[];

package/dist/configuration/scip-project.js

@@ -0,0 +1,40 @@
+function repositoryPath(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 512 &&
+        !/[\\:\x00-\x1f]/.test(value) &&
+        value.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}
+/** Also used by direct indexer callers, which need not pass through loadConfig. */
+export function assertScipSourceProject(value) {
+    const error = (reason) => { throw new Error(`Invalid scip.sourceProject: ${reason}`); };
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        error('expected an object');
+    const record = value;
+    if (Object.keys(record).some((key) => !['include', 'aliases'].includes(key)))
+        error('unknown field');
+    if (!Array.isArray(record.include) || record.include.length === 0 || record.include.length > 100 ||
+        !record.include.every(repositoryPath))
+        error('include requires 1–100 repository-relative paths/globs');
+    if (record.aliases !== undefined) {
+        if (!record.aliases || typeof record.aliases !== 'object' || Array.isArray(record.aliases))
+            error('aliases must be an object');
+        const entries = Object.entries(record.aliases);
+        if (entries.length > 100)
+            error('at most 100 exact aliases are supported');
+        for (const [name, path] of entries) {
+            if (!/^(?:@[\w.-]+\/)?[\w.-]+(?:\/[\w.-]+)*$/.test(name) ||
+                name.split('/').some((segment) => segment === '.' || segment === '..') ||
+                !repositoryPath(path) || /[*?]/.test(path) || !/\.(?:[cm]?ts|tsx)$/.test(path)) {
+                error(`alias ${name} must map an exact module name to a repository TypeScript file`);
+            }
+        }
+    }
+}
+export function assertSourceProjectInvocation(command, args) {
+    if (command !== 'bundled-scip-typescript' || args.length !== 2 ||
+        args[0] !== 'index' || args[1] !== '--no-global-caches') {
+        throw new Error('scip.sourceProject requires bundled-scip-typescript and args ["index", "--no-global-caches"]');
+    }
+}
+export function scipSourcePatterns(project) {
+    return project ? [...project.include, ...Object.values(project.aliases ?? {})] : [];
+}

package/dist/extraction/codex-auth.js

@@ -1,6 +1,7 @@
 // Environment allowlist adapted from the extracted semantic.ts; see docs/extraction-manifest.json.
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { resolveCodexInvocation } from './codex-command.js';
 import { SemanticProviderError } from './semantic-process.js';
 const semanticEnvironmentAllowlist = [
     'APPDATA',
@@ -35,8 +36,14 @@ export function semanticCommandEnvironment(source) {
 /** Read-only status check. Never expose output: API login status may contain key fragments. */
 export const readCodexLoginMode = async (command, environment, options = {}) => {
     try {
-        const result = await promisify(execFile)(command, ['login', 'status'], {
-            env: environment, timeout: Math.min(options.timeoutMs ?? 5000, 5000),
+        const started = performance.now();
+        const timeoutMs = Math.min(options.timeoutMs ?? 5000, 5000);
+        const invocation = await resolveCodexInvocation(command, environment, process.platform, { ...options, timeoutMs });
+        const remaining = Math.ceil(timeoutMs - (performance.now() - started));
+        if (remaining <= 0)
+            return 'unavailable';
+        const result = await promisify(execFile)(invocation.command, [...invocation.prefixArgs, 'login', 'status'], {
+            env: environment, timeout: remaining,
             signal: options.signal, maxBuffer: 8192, windowsHide: true,
         });
         const output = `${result.stdout}\n${result.stderr}`;

package/dist/extraction/codex-command.d.ts

@@ -0,0 +1,8 @@
+import { type SemanticRunOptions } from './semantic-process.js';
+interface CodexInvocation {
+    readonly command: string;
+    readonly prefixArgs: readonly string[];
+}
+/** Bound discovery too: a disconnected drive in PATH must not leave a provider call waiting indefinitely. */
+export declare function resolveCodexInvocation(command: string, environment: Readonly<Record<string, string | undefined>>, platform?: NodeJS.Platform, options?: SemanticRunOptions): Promise<CodexInvocation>;
+export {};

package/dist/extraction/codex-command.js

@@ -0,0 +1,81 @@
+import { readFile, stat } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { SemanticProviderError } from './semantic-process.js';
+async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch (error) {
+        if (['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+            return false;
+        throw new SemanticProviderError('unavailable', 'Cannot inspect the Codex installation on PATH');
+    }
+}
+async function npmEntry(directory, shim) {
+    const packageRoot = basename(directory).toLowerCase() === '.bin'
+        ? join(dirname(directory), '@openai', 'codex')
+        : join(directory, 'node_modules', '@openai', 'codex');
+    try {
+        const pkg = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
+        const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.codex;
+        if (pkg.name !== '@openai/codex' || typeof bin !== 'string' || !/\.(?:c|m)?js$/i.test(bin))
+            return;
+        const entry = resolve(packageRoot, bin);
+        const within = relative(packageRoot, entry);
+        if (within.startsWith('..') || isAbsolute(within) || !await isFile(entry))
+            return;
+        // Recognize standard npm cmd-shim targets; never execute or evaluate the batch file.
+        const target = relative(directory, entry).replaceAll('\\', '/').toLowerCase();
+        const launcher = (await readFile(shim, 'utf8')).replaceAll('\\', '/').toLowerCase();
+        if (launcher.includes(`%dp0%/${target}"`) || launcher.includes(`%~dp0${target}"`))
+            return entry;
+    }
+    catch { /* Missing/invalid metadata or an unsupported launcher is reported without its contents. */ }
+}
+/** Native binaries and standard npm installations; no cmd.exe, PowerShell, or implicit cwd lookup. */
+async function findWindowsCodex(environment) {
+    const pathKey = Object.keys(environment).find(key => key.toUpperCase() === 'PATH');
+    for (const item of (pathKey ? environment[pathKey] ?? '' : '').split(';')) {
+        const path = item.replace(/^"(.*)"$/, '$1');
+        if (!path)
+            continue;
+        const directory = resolve(path);
+        const native = join(directory, 'codex.exe');
+        if (await isFile(native))
+            return { command: native, prefixArgs: [] };
+        const shim = join(directory, 'codex.cmd');
+        if (!await isFile(shim))
+            continue;
+        const entry = await npmEntry(directory, shim);
+        if (entry)
+            return { command: process.execPath, prefixArgs: [entry] };
+        throw new SemanticProviderError('unavailable', 'Unsupported Codex launcher on PATH. Use a standard npm @openai/codex installation or a native codex.exe; batch wrappers are not executed');
+    }
+    throw new SemanticProviderError('unavailable', 'Codex CLI was not found on PATH; install @openai/codex with npm or add a native codex.exe');
+}
+/** Bound discovery too: a disconnected drive in PATH must not leave a provider call waiting indefinitely. */
+export async function resolveCodexInvocation(command, environment, platform = process.platform, options = {}) {
+    if (options.signal?.aborted)
+        throw new SemanticProviderError('cancelled', 'Codex executable discovery cancelled');
+    if (platform !== 'win32' || command !== 'codex')
+        return { command, prefixArgs: [] };
+    let timer;
+    let cancel = () => { };
+    try {
+        return await Promise.race([
+            findWindowsCodex(environment),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new SemanticProviderError('timeout', 'Codex executable discovery timed out')), Math.min(options.timeoutMs ?? 5000, 5000));
+                cancel = () => reject(new SemanticProviderError('cancelled', 'Codex executable discovery cancelled'));
+                options.signal?.addEventListener('abort', cancel, { once: true });
+                if (options.signal?.aborted)
+                    cancel();
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        options.signal?.removeEventListener('abort', cancel);
+    }
+}

package/dist/extraction/document-references.d.ts

@@ -0,0 +1,18 @@
+export interface DocumentReference {
+    readonly target: string;
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly relativeTo: 'document' | 'repository';
+}
+export declare function documentReferences(content: string): readonly DocumentReference[];
+export type ReferenceResolution = {
+    readonly kind: 'resolved';
+    readonly path: string;
+} | {
+    readonly kind: 'ignored';
+} | {
+    readonly kind: 'missing';
+    readonly path?: string;
+    readonly reason: string;
+};
+export declare function resolveDocumentReference(sourcePath: string, reference: DocumentReference, tracked: ReadonlySet<string>): ReferenceResolution;