@weftlet/toolkit 0.1.2 → 0.2.1

package/dist/extraction/document-references.js

@@ -0,0 +1,94 @@
+import { posix } from 'node:path';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+// Markdown destinations are document-relative. Literal paths are repository-relative unless
+// prefixed with ./ or ../. Parsing Markdown keeps examples, URLs and link labels out of the graph.
+const barePath = /(?<![\w/:@.-])(?:\.{1,2}\/|\/)?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+/g;
+const fileName = /\.(?:md|mdx|txt|ts|tsx|mts|cts|js|jsx|mjs|cjs|json|ya?ml|prisma|sh)$/i;
+export function documentReferences(content) {
+    const tree = fromMarkdown(content);
+    const definitions = new Map();
+    const walk = (node, visit) => {
+        visit(node);
+        if ('children' in node)
+            for (const child of node.children)
+                walk(child, visit);
+    };
+    walk(tree, (node) => {
+        if (node.type === 'definition' && !definitions.has(node.identifier)) {
+            definitions.set(node.identifier, node);
+        }
+    });
+    const references = [];
+    const add = (node, target, relativeTo) => {
+        if (node.position)
+            references.push({ target, relativeTo,
+                startLine: node.position.start.line, endLine: node.position.end.line });
+    };
+    const visit = (node) => {
+        if (node.type === 'link') {
+            add(node, node.url, 'document');
+            return;
+        }
+        if (node.type === 'linkReference') {
+            const definition = definitions.get(node.identifier);
+            // Cite the declaration containing the destination, not a path invented from its label.
+            if (definition)
+                add(definition, definition.url, 'document');
+            return;
+        }
+        if (node.type === 'inlineCode') {
+            if (!/\s/.test(node.value) && (node.value.includes('/') || fileName.test(node.value))) {
+                add(node, node.value, 'repository');
+            }
+            return;
+        }
+        if (node.type === 'text' && node.position) {
+            const raw = content.slice(node.position.start.offset, node.position.end.offset);
+            for (const match of raw.matchAll(barePath)) {
+                const target = match[0].replace(/[.,;:]+$/, '');
+                if (!/[A-Za-z]/.test(target))
+                    continue;
+                const startLine = node.position.start.line + raw.slice(0, match.index).split('\n').length - 1;
+                references.push({ target, startLine, endLine: startLine, relativeTo: 'repository' });
+            }
+            return;
+        }
+        // Code blocks, images, HTML and unused reference definitions are not repository mappings.
+        if ('children' in node)
+            for (const child of node.children)
+                visit(child);
+    };
+    visit(tree);
+    return references;
+}
+export function resolveDocumentReference(sourcePath, reference, tracked) {
+    const target = reference.target;
+    // No network, filesystem lookup or guessed basename fallback. A leading / denotes repository root.
+    if (!target || target.startsWith('#') || target.startsWith('//') || /^[a-z][\w+.-]*:/i.test(target)) {
+        return { kind: 'ignored' };
+    }
+    let path;
+    try {
+        path = decodeURIComponent(target.split(/[?#]/, 1)[0]);
+    }
+    catch {
+        return { kind: 'missing', reason: `Malformed repository link destination: ${target}` };
+    }
+    if (/[\\\x00-\x1f\x7f]/.test(path)) {
+        return { kind: 'missing', reason: `Unsupported repository link destination: ${target}` };
+    }
+    const relative = reference.relativeTo === 'document' || /^\.{1,2}\//.test(path);
+    path = posix.normalize(path.startsWith('/') ? path.slice(1)
+        : posix.join(relative ? posix.dirname(sourcePath) : '', path));
+    if (path === '..' || path.startsWith('../') || posix.isAbsolute(path)) {
+        return { kind: 'missing', reason: `Repository link escapes the repository: ${target}` };
+    }
+    if (tracked.has(path))
+        return { kind: 'resolved', path };
+    // Slash-separated prose (RDF/SHACL), package names and example paths are not declarations
+    // of missing repository files. Only an explicit Markdown destination requests link validation.
+    if (reference.relativeTo === 'repository')
+        return { kind: 'ignored' };
+    return { kind: 'missing', path,
+        reason: `Document reference ${target} resolves to ${path}, which is not a committed file. Directory references are not expanded.` };
+}

package/dist/extraction/document.d.ts

@@ -1,5 +1,12 @@
-import type { ExtractionContext, GraphFact, SemanticArtifact, SemanticSource } from "@weftlet/core";
+import type { ExtractionContext, GraphDiagnostic, GraphFact, SemanticArtifact, SemanticSource } from '@weftlet/core';
+export declare const documentLinkerIdentity: {
+    readonly id: "document-linker";
+    readonly version: "2.0.0";
+};
 export declare function linkSemanticDocuments(context: ExtractionContext, hydrated: readonly {
     source: SemanticSource;
     artifact: SemanticArtifact;
-}[], trackedPaths?: readonly string[]): readonly GraphFact[];
+}[], trackedPaths: readonly string[], approvedSourcePaths?: readonly string[]): {
+    readonly facts: readonly GraphFact[];
+    readonly diagnostics: readonly GraphDiagnostic[];
+};

package/dist/extraction/document.js

@@ -1,54 +1,47 @@
-import { sha256, stableJson } from "../infrastructure/util.js";
-const identity = { id: 'document-linker', version: '1.0.0' };
-const repositoryPathPattern = /\b[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+/g;
-function documentNode(path) {
-    return { id: `document:${path}`, kind: 'Document', label: path };
-}
-export function linkSemanticDocuments(context, hydrated, trackedPaths = []) {
-    const facts = [];
-    const makeFact = (source, subject, predicate, object) => ({
-        id: sha256(stableJson({ source: source.path, subject: subject.id, predicate, object: object.id })),
-        subject,
-        predicate,
-        object,
-        provenance: {
-            path: source.path,
-            startLine: 1,
-            endLine: Math.max(1, source.content.split('\n').length),
-            digest: source.digest,
-            commitSha: context.commitSha,
-        },
-        extractor: identity,
-        confidence: 1,
-        authority: 'inferred',
-        extractionReview: predicate === 'contains' ? 'unreviewed' : 'deterministic',
-        snapshotId: context.snapshotId,
-    });
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { documentReferences, resolveDocumentReference } from './document-references.js';
+import { repositoryFileNode as fileNode } from './repository-nodes.js';
+export const documentLinkerIdentity = { id: 'document-linker', version: '2.0.0' };
+export function linkSemanticDocuments(context, hydrated, trackedPaths, approvedSourcePaths = []) {
+    const facts = new Map();
+    const diagnostics = new Map();
+    const tracked = new Set(trackedPaths);
     for (const { source, artifact } of hydrated) {
-        const owner = documentNode(source.path);
-        const nodes = new Map(artifact.facts.flatMap((fact) => [fact.subject, fact.object]).map((node) => [node.id, node]));
-        for (const node of nodes.values())
-            facts.push(makeFact(source, owner, 'contains', node));
-        const references = [
-            ...new Set((source.content.match(repositoryPathPattern) ?? []).map((path) => path.replace(/[.,;:]+$/, ''))),
-        ].sort();
-        const resolvedReferences = new Set();
-        for (const path of references) {
-            if (trackedPaths.includes(path) || /\.(?:md|mdx|txt)$/i.test(path)) {
-                resolvedReferences.add(path);
+        const owner = { id: `document:${source.path}`, kind: 'Document', label: source.path };
+        const span = (startLine, endLine) => ({
+            path: source.path, startLine, endLine, digest: source.digest, commitSha: context.commitSha,
+        });
+        const add = (predicate, object, provenance) => {
+            const id = sha256(stableJson({ subject: owner.id, predicate, object: object.id, provenance,
+                extractor: documentLinkerIdentity }));
+            facts.set(id, { id, subject: owner, predicate, object, provenance,
+                extractor: documentLinkerIdentity, confidence: 1, authority: 'inferred',
+                sourceAuthority: approvedSourcePaths.includes(source.path) ? 'declared' : 'inferred',
+                extractionReview: predicate === 'contains' ? 'unreviewed' : 'deterministic',
+                snapshotId: context.snapshotId });
+        };
+        // Containment follows the assertion's actual cited passage and stays unreviewed.
+        for (const fact of artifact.facts) {
+            for (const node of [fact.subject, fact.object]) {
+                add('contains', node, span(fact.provenance.startLine, fact.provenance.endLine));
+            }
+        }
+        for (const reference of documentReferences(source.content)) {
+            const resolved = resolveDocumentReference(source.path, reference, tracked);
+            if (resolved.kind === 'ignored')
                 continue;
+            const provenance = span(reference.startLine, reference.endLine);
+            if (resolved.kind === 'resolved') {
+                add('references', fileNode(resolved.path), provenance);
             }
-            for (const trackedPath of trackedPaths) {
-                if (trackedPath.startsWith(`${path}/`))
-                    resolvedReferences.add(trackedPath);
+            else {
+                const id = sha256(stableJson({ provenance, reason: resolved.reason, extractor: documentLinkerIdentity }));
+                diagnostics.set(id, { id, kind: 'implementationGaps', reason: resolved.reason,
+                    provenance: [provenance], relatedNodeIds: [owner.id, ...(resolved.path ? [fileNode(resolved.path).id] : [])],
+                    evidenceScope: 'source' });
             }
         }
-        for (const path of [...resolvedReferences].sort()) {
-            const target = /\.(?:md|mdx|txt)$/i.test(path)
-                ? documentNode(path)
-                : { id: `component:file:${path}`, kind: 'Component', label: path };
-            facts.push(makeFact(source, owner, 'references', target));
-        }
     }
-    return facts;
+    return { facts: [...facts.values()].sort((a, b) => a.id.localeCompare(b.id)),
+        diagnostics: [...diagnostics.values()].sort((a, b) => a.id.localeCompare(b.id)) };
 }

package/dist/extraction/module-request.d.ts

@@ -0,0 +1,3 @@
+import type { GraphNode } from '@weftlet/core';
+/** Identity of a literal module request, not a resolved implementation or an existence check. */
+export declare function moduleRequestNode(importer: string, specifier: string): GraphNode;

package/dist/extraction/module-request.js

@@ -0,0 +1,25 @@
+import { posix } from 'node:path';
+import { sha256, stableJson } from '../infrastructure/util.js';
+/** Identity of a literal module request, not a resolved implementation or an existence check. */
+export function moduleRequestNode(importer, specifier) {
+    const relative = specifier === '.' || specifier === '..' ||
+        specifier.startsWith('./') || specifier.startsWith('../');
+    if (!relative)
+        return { id: `contract:module:${specifier}`, kind: 'Contract', label: specifier };
+    // Git paths use POSIX separators on every host. Do not interpret loader suffixes, escapes,
+    // encoded paths or requests outside this repository as canonical local destinations.
+    const location = posix.normalize(posix.join(posix.dirname(importer), specifier));
+    const opaque = /[\\%?#\x00-\x1f\x7f-\x9f]/.test(specifier) || importer.includes('\\') ||
+        location === '..' || location.startsWith('../') || posix.isAbsolute(location);
+    if (opaque)
+        return {
+            id: `contract:module:./?${sha256(stableJson({ importer, specifier }))}`,
+            kind: 'Contract', label: `${specifier} (from ${importer})`,
+            attributes: { identityScope: 'importer-local-request', resolution: 'unresolved' },
+        };
+    // The ./ prefix cannot collide with a bare import; ? is reserved for opaque identities.
+    // Encode the location so distinct literal path characters cannot act as ID delimiters.
+    return { id: `contract:module:./${encodeURIComponent(location)}`, kind: 'Contract',
+        label: `./${location}`,
+        attributes: { identityScope: 'repository-relative-request', resolution: 'unresolved' } };
+}

package/dist/extraction/repository-nodes.d.ts

@@ -0,0 +1,7 @@
+import type { GraphNode } from '@weftlet/core';
+/** Internal cache contract: changing this policy must also change snapshot assembly identity. */
+export declare const repositoryNodeIdentityVersion = 1;
+/** Physical file identity; this does not establish existence, intent, ownership or approval. */
+export declare function repositoryFileNode(path: string): GraphNode;
+/** Normalize only reserved document/file identities, never inferred business concept IDs. */
+export declare function canonicalizeRepositoryDocumentNode(node: GraphNode): GraphNode;

package/dist/extraction/repository-nodes.js

@@ -0,0 +1,20 @@
+/** Internal cache contract: changing this policy must also change snapshot assembly identity. */
+export const repositoryNodeIdentityVersion = 1;
+function isDocumentPath(path) {
+    return /\.(?:md|mdx|txt)$/i.test(path);
+}
+/** Physical file identity; this does not establish existence, intent, ownership or approval. */
+export function repositoryFileNode(path) {
+    if (isDocumentPath(path))
+        return { id: `document:${path}`, kind: 'Document', label: path };
+    return { id: `component:file:${path}`, label: path,
+        kind: /\.(spec|test)\.[^.]+$/i.test(path) ? 'Evidence' : 'Component' };
+}
+/** Normalize only reserved document/file identities, never inferred business concept IDs. */
+export function canonicalizeRepositoryDocumentNode(node) {
+    const match = /^(?:component:file:|document:)(.+)$/.exec(node.id);
+    if (!match || !isDocumentPath(match[1]))
+        return node;
+    const canonical = repositoryFileNode(match[1]);
+    return { ...node, id: canonical.id, kind: canonical.kind };
+}

package/dist/extraction/routing.d.ts

@@ -0,0 +1,14 @@
+import type { ExtractionContext, GraphDiagnostic, GraphFact } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+export declare const routingExtractorIdentity: {
+    readonly id: "routing-declaration-extractor";
+    readonly version: "1.0.0";
+};
+/** Reads explicit mapping declarations, never infers routing from matching topic text. */
+export declare function extractRoutingDeclarations(repository: GitRepository, context: ExtractionContext, paths: readonly string[], options?: {
+    readonly allowMissingSources?: boolean;
+}): Promise<{
+    readonly facts: readonly GraphFact[];
+    readonly diagnostics: readonly GraphDiagnostic[];
+    readonly referencedPaths: readonly string[];
+}>;

package/dist/extraction/routing.js

@@ -0,0 +1,151 @@
+import { posix } from 'node:path';
+import { sha256, stableJson } from '../infrastructure/util.js';
+export const routingExtractorIdentity = { id: 'routing-declaration-extractor', version: '1.0.0' };
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function exactKeys(value, keys) {
+    return Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+function label(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 200 &&
+        value === value.trim() && !/[\x00-\x1f\x7f-\x9f]/.test(value);
+}
+function repositoryPath(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 1024 &&
+        value === value.trim() && !/[\\:*?\[\]{}%#\x00-\x1f\x7f-\x9f]/.test(value) &&
+        !posix.isAbsolute(value) && posix.normalize(value) === value &&
+        value.split('/').every((part) => part !== '' && part !== '.' && part !== '..');
+}
+/** JSON.parse alone silently accepts duplicate keys, which would hide conflicting declarations. */
+function parseUniqueJson(content, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw new Error(`Invalid routing source ${path}: malformed JSON`);
+    }
+    const objects = [];
+    for (const token of content.matchAll(/"(?:\\.|[^"\\])*"|[{}\[\]]/g)) {
+        const value = token[0];
+        if (value === '{' || value === '[')
+            objects.push(value === '{' ? new Set() : undefined);
+        else if (value === '}' || value === ']')
+            objects.pop();
+        else if (/^\s*:/.test(content.slice(token.index + value.length))) {
+            const keys = objects.at(-1);
+            const key = JSON.parse(value);
+            if (keys.has(key))
+                throw new Error(`Invalid routing source ${path}: duplicate JSON key ${key}`);
+            keys.add(key);
+        }
+    }
+    return parsed;
+}
+function parseRoutes(content, path) {
+    if (Buffer.byteLength(content) > 65_536)
+        throw new Error(`Routing source ${path} exceeds 64 KiB`);
+    const parsed = parseUniqueJson(content, path);
+    if (!record(parsed) || !exactKeys(parsed, ['schemaVersion', 'routes']) ||
+        parsed.schemaVersion !== 1 || !Array.isArray(parsed.routes)) {
+        throw new Error(`Invalid routing source ${path}: expected schemaVersion 1 and routes array`);
+    }
+    return parsed.routes.map((route, index) => {
+        if (!record(route) || !exactKeys(route, ['id', 'scope', 'channel', 'producer', 'consumer']) ||
+            !label(route.id) || !label(route.scope) || !label(route.channel) ||
+            !repositoryPath(route.producer) || !repositoryPath(route.consumer)) {
+            throw new Error(`Invalid routing source ${path}: route ${index + 1} requires exact id/scope/channel labels and normalized producer/consumer paths`);
+        }
+        return { id: route.id, scope: route.scope, channel: route.channel,
+            producer: route.producer, consumer: route.consumer };
+    });
+}
+function fileNode(path) {
+    return { id: `component:file:${path}`, label: path,
+        kind: /\.(spec|test)\.[^.]+$/i.test(path) ? 'Evidence' : 'Component' };
+}
+/** Reads explicit mapping declarations, never infers routing from matching topic text. */
+export async function extractRoutingDeclarations(repository, context, paths, options = {}) {
+    if (paths.length > 16 || new Set(paths).size !== paths.length ||
+        paths.some((path) => !repositoryPath(path) || !path.endsWith('.json'))) {
+        throw new Error('Routing sources require at most 16 unique exact repository-relative .json paths');
+    }
+    if (paths.length === 0)
+        return { facts: [], diagnostics: [], referencedPaths: [] };
+    // NUL-delimited tree entries preserve spaces/Unicode regardless of core.quotepath.
+    // A symlink or submodule is not evidence of a regular source file at this path.
+    const entries = (await repository.run(['ls-tree', '-r', '-z', context.commitSha, '--', '.']))
+        .split('\0').filter(Boolean).map((entry) => {
+        const fields = /^(\d{6}) (blob|tree|commit) [a-f0-9]+\t([\s\S]+)$/.exec(entry);
+        if (!fields)
+            throw new Error('Unable to read exact committed routing file entries');
+        return { mode: fields[1], type: fields[2], path: fields[3] };
+    });
+    const tracked = new Set(entries.map((entry) => entry.path));
+    const regular = new Set(entries.filter((entry) => entry.type === 'blob' &&
+        ['100644', '100755'].includes(entry.mode)).map((entry) => entry.path));
+    const cited = [];
+    const diagnostics = [];
+    const addDiagnostic = (reason, provenance, relatedNodeIds) => {
+        diagnostics.push({ id: sha256(stableJson({ reason, provenance, relatedNodeIds,
+                extractor: routingExtractorIdentity, commitSha: context.commitSha })),
+            kind: 'implementationGaps', reason, provenance, relatedNodeIds, evidenceScope: 'source' });
+    };
+    for (const path of [...paths].sort()) {
+        if (!tracked.has(path)) {
+            if (!options.allowMissingSources)
+                throw new Error(`Routing source ${path} is not a committed file at ${context.commitSha}`);
+            addDiagnostic(`Routing source ${path} is absent from this draft; no bindings from that source were retained.`, [], [`document:${path}`]);
+            continue;
+        }
+        if (!regular.has(path))
+            throw new Error(`Routing source ${path} is not a regular committed file at ${context.commitSha}`);
+        const content = await repository.readFileAt(context.commitSha, path);
+        const provenance = { path, startLine: 1, endLine: content.split('\n').length,
+            digest: sha256(content), commitSha: context.commitSha };
+        cited.push(...parseRoutes(content, path).map((route) => ({ route, provenance })));
+        if (cited.length > 500)
+            throw new Error('Routing sources exceed the 500 declaration bound');
+    }
+    const groups = new Map();
+    const referencedPaths = new Set();
+    for (const item of cited) {
+        const key = stableJson({ repositoryId: context.repositoryId, scope: item.route.scope, id: item.route.id });
+        const group = groups.get(key) ?? [];
+        group.push(item);
+        groups.set(key, group);
+        referencedPaths.add(item.route.producer);
+        referencedPaths.add(item.route.consumer);
+    }
+    const facts = [];
+    for (const [key, group] of groups) {
+        const { route, provenance } = group[0];
+        const binding = { id: `workflow:routing:${sha256(key)}`, kind: 'Workflow',
+            label: `Routing ${route.scope}/${route.id}: ${route.channel}`,
+            attributes: { evidenceLayer: 'routing-declaration', routeId: route.id, scope: route.scope,
+                channel: route.channel } };
+        if (group.length > 1) {
+            addDiagnostic(`Ambiguous routing declaration ${route.scope}/${route.id}: ${group.length} records share this scoped identity; all of its bindings were suppressed.`, [...new Map(group.map((item) => [stableJson(item.provenance), item.provenance])).values()], [binding.id, ...new Set(group.flatMap((item) => [fileNode(item.route.producer).id, fileNode(item.route.consumer).id]))]);
+            continue;
+        }
+        const missing = [...new Set([route.producer, route.consumer])].filter((path) => !regular.has(path));
+        if (missing.length > 0) {
+            addDiagnostic(`Routing declaration ${route.scope}/${route.id} names missing or non-regular committed endpoint(s): ${missing.join(', ')}. Both binding relationships were suppressed; no path or case was guessed.`, [provenance], [binding.id, fileNode(route.producer).id, fileNode(route.consumer).id]);
+            continue;
+        }
+        const relationships = [
+            { subject: fileNode(route.producer), predicate: 'emits', object: binding },
+            { subject: binding, predicate: 'routesThrough', object: fileNode(route.consumer) },
+        ];
+        for (const relationship of relationships) {
+            const assertion = { ...relationship, provenance, extractor: routingExtractorIdentity,
+                confidence: 1, authority: 'inferred', sourceAuthority: 'inferred',
+                extractionReview: 'deterministic' };
+            facts.push({ ...assertion, id: sha256(stableJson(assertion)), snapshotId: context.snapshotId });
+        }
+    }
+    return { facts: facts.sort((a, b) => a.id.localeCompare(b.id)),
+        diagnostics: diagnostics.sort((a, b) => a.id.localeCompare(b.id)),
+        referencedPaths: [...referencedPaths].sort() };
+}

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

@@ -0,0 +1,3 @@
+import type { ScipSourceProject } from '../configuration/scip-project.js';
+/** Only writes compiler configuration into a disposable committed tree; never source or dependencies. */
+export declare function prepareScipSourceProject(root: string, project: ScipSourceProject, trackedPaths: readonly string[]): Promise<string>;

package/dist/extraction/scip-project.js

@@ -0,0 +1,33 @@
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { matchesRepositoryGlob } from '../repository/glob.js';
+const generatedProject = '.weftlet-scip-source-project.json';
+/** Only writes compiler configuration into a disposable committed tree; never source or dependencies. */
+export async function prepareScipSourceProject(root, project, trackedPaths) {
+    if (trackedPaths.includes(generatedProject))
+        throw new Error(`Reserved SCIP project path is already tracked: ${generatedProject}`);
+    const files = trackedPaths.filter((path) => /\.(?:[cm]?ts|tsx)$/.test(path) &&
+        project.include.some((pattern) => matchesRepositoryGlob(path, pattern))).sort();
+    if (!files.length || files.length > 5000)
+        throw new Error('SCIP source project must select 1–5000 committed TypeScript files');
+    const tracked = new Set(trackedPaths);
+    const paths = Object.create(null);
+    for (const [name, path] of Object.entries(project.aliases ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+        if (!tracked.has(path))
+            throw new Error(`SCIP source alias ${name} targets an absent committed file: ${path}`);
+        if (!files.includes(path))
+            throw new Error(`SCIP source alias ${name} target must be selected by sourceProject.include: ${path}`);
+        paths[name] = [`./${path}`];
+    }
+    // A separate program deliberately avoids inherited build exclusions, output files,
+    // external tsconfig packages and machine-specific path mappings. This is local-symbol
+    // analysis, not a replacement for the repository's compiler or dependency installation.
+    await writeFile(join(root, generatedProject), JSON.stringify({
+        compilerOptions: {
+            target: 'ES2022', module: 'NodeNext', moduleResolution: 'NodeNext', jsx: 'preserve',
+            noEmit: true, skipLibCheck: true, types: [], baseUrl: '.', paths,
+        },
+        files: files.map((path) => `./${path}`), include: [], exclude: [],
+    }) + '\n', { flag: 'wx' });
+    return generatedProject;
+}

package/dist/extraction/semantic-process.js

@@ -1,4 +1,5 @@
-import { spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
+import { join } from 'node:path';
 export class SemanticProviderError extends Error {
     code;
     retryable;
@@ -25,8 +26,17 @@ export function runSemanticProcess(command, args, cwd, prompt, environment, opti
             try {
                 if (process.platform !== 'win32' && child.pid)
                     process.kill(-child.pid, signal);
-                else
-                    child.kill(signal);
+                else if (child.pid) {
+                    // npm's Windows launcher starts a native child. Terminate its tree, not just the Node wrapper.
+                    const systemRoot = process.env.SystemRoot ?? process.env.SYSTEMROOT;
+                    const taskkill = systemRoot ? join(systemRoot, 'System32', 'taskkill.exe') : 'taskkill.exe';
+                    execFile(taskkill, ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, timeout: 5000 }, error => {
+                        if (error && child.exitCode === null && child.signalCode === null) {
+                            failure = new SemanticProviderError('unavailable', 'Could not terminate the semantic provider process tree');
+                            child.kill('SIGKILL');
+                        }
+                    });
+                }
             }
             catch { /* The process may have already exited. */ }
         };
@@ -35,8 +45,10 @@ export function runSemanticProcess(command, args, cwd, prompt, environment, opti
                 return;
             failure = new SemanticProviderError(code, `Semantic extraction ${code}`);
             kill('SIGTERM');
-            killTimer = setTimeout(() => kill('SIGKILL'), 1000);
-            killTimer.unref();
+            if (process.platform !== 'win32') {
+                killTimer = setTimeout(() => kill('SIGKILL'), 1000);
+                killTimer.unref();
+            }
         };
         const cancel = () => stop('cancelled');
         options.signal?.addEventListener('abort', cancel, { once: true });

package/dist/extraction/semantic.js

@@ -4,10 +4,26 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { prepareCodexAuthentication, readCodexLoginMode } from './codex-auth.js';
 export { semanticCommandEnvironment } from './codex-auth.js';
+import { resolveCodexInvocation } from './codex-command.js';
 import { runSemanticProcess, SemanticProviderError } from "./semantic-process.js";
 export { SemanticProviderError } from "./semantic-process.js";
 import { sha256, stableJson } from "../infrastructure/util.js";
+import { canonicalizeRepositoryDocumentNode, repositoryNodeIdentityVersion } from './repository-nodes.js';
 import { assertSemanticCitation, numberedSemanticSource, semanticCitationSchema, } from "./semantic-citations.js";
+function canonicalizeRepositoryDocuments(output) {
+    const ids = new Map();
+    const assertions = output.assertions.map((assertion) => {
+        const subject = canonicalizeRepositoryDocumentNode(assertion.subject);
+        const object = canonicalizeRepositoryDocumentNode(assertion.object);
+        ids.set(assertion.subject.id, subject.id);
+        ids.set(assertion.object.id, object.id);
+        return { ...assertion, subject, object };
+    });
+    return { ...output, assertions, diagnostics: output.diagnostics?.map((diagnostic) => ({
+            ...diagnostic,
+            relatedNodeIds: diagnostic.relatedNodeIds.map((id) => ids.get(id) ?? id),
+        })) };
+}
 function omlEscape(value) {
     return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\r?\n/g, '\\n');
 }
@@ -75,7 +91,17 @@ function renderOml(key, assertions) {
         '}',
     ].join('\n');
 }
-const spawnSemanticCommand = { run: runSemanticProcess };
+const spawnSemanticCommand = {
+    async run(command, args, cwd, prompt, environment, options) {
+        const started = performance.now();
+        const timeoutMs = options?.timeoutMs ?? 120_000;
+        const invocation = await resolveCodexInvocation(command, environment, process.platform, options);
+        const remaining = Math.ceil(timeoutMs - (performance.now() - started));
+        if (remaining <= 0)
+            throw new SemanticProviderError('timeout', 'Semantic extraction timeout');
+        return runSemanticProcess(invocation.command, [...invocation.prefixArgs, ...args], cwd, prompt, environment, { ...options, timeoutMs: remaining });
+    },
+};
 const kinds = [
     'Project',
     'Document',
@@ -202,14 +228,14 @@ export class CodexCliSemanticExtractor {
         this.config = config;
         this.runner = runner;
         this.loginProbe = loginProbe;
-        this.identity = `codex-cli:${config.model}:${config.reasoningEffort}:${config.promptVersion}:contract-v2`;
+        this.identity = `codex-cli:${config.model}:${config.reasoningEffort}:${config.promptVersion}:contract-v3`;
     }
     async extract(source, context, options = {}) {
         options.signal?.throwIfAborted();
         if (Buffer.byteLength(source.content) > (this.config.maxSourceBytes ?? 65_536)) {
             throw new SemanticProviderError('invalid-output', 'Semantic source exceeds configured byte budget');
         }
-        const command = process.platform === 'win32' ? 'codex.exe' : 'codex';
+        const command = 'codex';
         const environment = await prepareCodexAuthentication(this.config.auth, process.env, command, options, this.loginProbe);
         const runRoot = await mkdtemp(join(tmpdir(), 'context-graph-codex-'));
         const schemaPath = join(runRoot, 'schema.json');
@@ -224,7 +250,7 @@ export class CodexCliSemanticExtractor {
             'Use neutral graph kinds and the allowed precise predicates. Never guess a missing mapping.',
             'Use product-wide canonical IDs derived from durable concepts, not IDs scoped to this file.',
             'Reuse capability, policy, workflow, contract, and component IDs that another source would use for the same concept.',
-            'When the source names a repository path, use component:file:<path> so semantic and static facts join deterministically.',
+            'For a repository document path ending in .md, .mdx or .txt, use document:<path> with kind Document. For other repository files use component:file:<path>; test/spec files have kind Evidence, other files Component. Use exact repository-relative paths; keep business concepts in their own IDs instead of assigning their kind to a file.',
             'Capture why a rule exists, its decision authority, and cross-domain dependencies when the source explicitly states them.',
             'Every assertion must cite inclusive 1-based source line numbers and carry calibrated confidence.',
             `Source lines are explicitly prefixed N| below. Cite those original-source numbers, not prompt lines or visual wraps; valid lines are 1-${lineCount}.`,
@@ -319,6 +345,7 @@ export class SemanticHydrator {
             failOnUnresolved: this.config.failOnUnresolved,
             forceRevision,
             diagnosticContractVersion: 3,
+            repositoryNodeIdentityVersion,
         };
         const key = sha256(stableJson(keyInput));
         const existing = await this.store.read(key);
@@ -329,7 +356,7 @@ export class SemanticHydrator {
         if (typeof extraction.rawModelOutput !== 'string' || Buffer.byteLength(extraction.rawModelOutput) > 2 * 1024 * 1024) {
             throw new SemanticProviderError('invalid-output', 'Invalid or oversized raw semantic output');
         }
-        const output = extraction.parsed;
+        const output = canonicalizeRepositoryDocuments(extraction.parsed);
         const lineCount = source.content.split('\n').length;
         const facts = output.assertions.map((assertion, index) => {
             assertSemanticCitation(assertion.citation, source.path, lineCount, `assertion[${index}]`);

package/dist/extraction/static.d.ts

@@ -1,6 +1,6 @@
 import type { ContextGraphConfig } from "../configuration/config.js";
 import type { ExtractionContext, FactExtractor, GraphFact } from "@weftlet/core";
-import type { GitRepository } from "../repository/git.js";
+import { GitRepository } from "../repository/git.js";
 export interface ScipIndexResult {
     readonly path: string;
     readonly digest: string;
@@ -27,13 +27,17 @@ export declare class ScipSymbolExtractor implements FactExtractor {
     constructor(repository: GitRepository, index: ScipIndexResult);
     extract(context: ExtractionContext): Promise<readonly GraphFact[]>;
 }
+export declare const repositoryFileExtractorIdentity: {
+    readonly id: "repository-file-extractor";
+    readonly version: "2.0.0";
+};
 export declare class RepositoryFileExtractor implements FactExtractor {
     private readonly repository;
     private readonly roots;
     private readonly scipDigest;
     readonly identity: {
-        id: string;
-        version: string;
+        readonly id: "repository-file-extractor";
+        readonly version: "2.0.0";
     };
     constructor(repository: GitRepository, roots: readonly string[], scipDigest: string);
     extract(context: ExtractionContext): Promise<readonly GraphFact[]>;