@weftlet/toolkit 0.2.1 → 0.4.0

package/dist/extraction/routing.d.ts

@@ -2,7 +2,7 @@ import type { ExtractionContext, GraphDiagnostic, GraphFact } from '@weftlet/cor
 import type { GitRepository } from '../repository/git.js';
 export declare const routingExtractorIdentity: {
     readonly id: "routing-declaration-extractor";
-    readonly version: "1.0.0";
+    readonly version: "1.1.0";
 };
 /** Reads explicit mapping declarations, never infers routing from matching topic text. */
 export declare function extractRoutingDeclarations(repository: GitRepository, context: ExtractionContext, paths: readonly string[], options?: {

package/dist/extraction/routing.js

@@ -1,6 +1,7 @@
 import { posix } from 'node:path';
+import { repositoryFileNode as fileNode } from '@weftlet/core';
 import { sha256, stableJson } from '../infrastructure/util.js';
-export const routingExtractorIdentity = { id: 'routing-declaration-extractor', version: '1.0.0' };
+export const routingExtractorIdentity = { id: 'routing-declaration-extractor', version: '1.1.0' };
 function record(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -61,10 +62,6 @@ function parseRoutes(content, path) {
             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 ||
@@ -96,7 +93,7 @@ export async function extractRoutingDeclarations(repository, context, paths, opt
         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}`]);
+            addDiagnostic(`Routing source ${path} is absent from this draft; no bindings from that source were retained.`, [], [fileNode(path).id]);
             continue;
         }
         if (!regular.has(path))

package/dist/extraction/semantic-cache.d.ts

@@ -0,0 +1,13 @@
+import type { SemanticArtifact, SemanticSource } from '@weftlet/core';
+import type { ContextGraphConfig } from '../configuration/config.js';
+import type { SemanticArtifactStore } from '../storage/storage.js';
+export type SemanticCacheStatus = 'hit' | 'miss' | 'forced' | 'corrupt' | 'unavailable';
+export interface SemanticCacheInspection {
+    readonly status: SemanticCacheStatus;
+    readonly key?: string;
+    readonly reason: string;
+    readonly artifact?: SemanticArtifact;
+    readonly origin?: 'primary' | 'legacy';
+}
+/** Read-only; a broken artifact is not an extraction miss or permission to overwrite evidence. */
+export declare function inspectSemanticCache(store: SemanticArtifactStore, config: ContextGraphConfig['semantic'], source: SemanticSource, modelIdentity: string, forceRevision?: string): Promise<SemanticCacheInspection>;

package/dist/extraction/semantic-cache.js

@@ -0,0 +1,66 @@
+import { semanticArtifactKey, semanticArtifactOutputDigest } from './semantic-identity.js';
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function strings(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function matchesIdentity(value, key, source, config, modelIdentity) {
+    return value.key === key && value.stableSemanticId === source.stableSemanticId &&
+        value.sourceDigest === source.digest && value.modelIdentity === modelIdentity &&
+        ['promptVersion', 'extractorVersion', 'adapterVersion', 'ontologyVersion'].every((field) => value[field] === config[field]);
+}
+function reusableArtifact(value, key, source, config, modelIdentity) {
+    if (!record(value) || !matchesIdentity(value, key, source, config, modelIdentity) ||
+        !record(value.source) || value.source.digest !== source.digest ||
+        typeof value.source.path !== 'string' || typeof value.source.commitSha !== 'string' ||
+        !Array.isArray(value.facts) || !Array.isArray(value.diagnostics) || !strings(value.unresolvedMappings) ||
+        typeof value.oml !== 'string' || typeof value.rawModelOutput !== 'string' ||
+        typeof value.outputDigest !== 'string')
+        return false;
+    const lineCount = source.content.split('\n').length;
+    const span = (item) => record(item) && typeof item.path === 'string' &&
+        item.digest === source.digest && typeof item.commitSha === 'string' &&
+        Number.isInteger(item.startLine) && Number.isInteger(item.endLine) &&
+        Number(item.startLine) >= 1 && Number(item.endLine) >= Number(item.startLine) && Number(item.endLine) <= lineCount;
+    const node = (item) => record(item) && typeof item.id === 'string' && item.id.length > 0 &&
+        typeof item.kind === 'string' && typeof item.label === 'string';
+    if (!span(value.source) || !value.facts.every((fact) => record(fact) && typeof fact.id === 'string' &&
+        node(fact.subject) && node(fact.object) && typeof fact.predicate === 'string' && span(fact.provenance) &&
+        record(fact.extractor) && fact.extractor.id === modelIdentity && fact.extractor.version === config.extractorVersion &&
+        typeof fact.confidence === 'number' && fact.confidence >= config.minimumConfidence && fact.confidence <= 1))
+        return false;
+    if (!value.diagnostics.every((item) => record(item) && typeof item.id === 'string' &&
+        typeof item.kind === 'string' && typeof item.reason === 'string' && strings(item.relatedNodeIds) &&
+        Array.isArray(item.provenance) && item.provenance.length > 0 && item.provenance.every(span)))
+        return false;
+    if (config.failOnUnresolved && (value.unresolvedMappings.length || value.diagnostics.length))
+        return false;
+    return semanticArtifactOutputDigest(value) === value.outputDigest;
+}
+/** Read-only; a broken artifact is not an extraction miss or permission to overwrite evidence. */
+export async function inspectSemanticCache(store, config, source, modelIdentity, forceRevision) {
+    const key = semanticArtifactKey(config, source, modelIdentity, forceRevision);
+    let value;
+    let origin;
+    try {
+        const entry = await store.readEntry(key);
+        value = entry?.artifact;
+        origin = entry?.origin;
+    }
+    catch (error) {
+        return error instanceof SyntaxError
+            ? { status: 'corrupt', key, reason: 'Cached artifact is not valid JSON; retain it for diagnosis or use an explicit forced refresh.' }
+            : { status: 'unavailable', key, reason: 'Cached artifact could not be read; check local storage access before hydrating.' };
+    }
+    if (value === undefined)
+        return { status: 'miss', key, reason: 'No artifact exists for the current source and extraction contract.' };
+    if (!reusableArtifact(value, key, source, config, modelIdentity)) {
+        return { status: 'corrupt', key, reason: 'Cached artifact identity, structure or content digest is invalid; retain it for diagnosis or use an explicit forced refresh.' };
+    }
+    return { status: 'hit', key, origin,
+        reason: origin === 'legacy'
+            ? 'Validated artifact is available in the exact legacy configuration profile; hydration can retain a copy in the operationally stable cache.'
+            : 'Readable artifact matches the source and extraction contract; reuse remains subject to unchanged inputs.',
+        artifact: value };
+}

package/dist/extraction/semantic-diagnostics.d.ts

@@ -0,0 +1,9 @@
+import type { SemanticSource } from '@weftlet/core';
+export type SemanticHydrationPhase = 'semantic-cache-read' | 'semantic-extract' | 'semantic-validate' | 'semantic-cache-write';
+/** Preserve policy distinctions without copying source-specific messages into run reports. */
+export declare class SemanticPolicyError extends Error {
+    readonly code: 'unresolved' | 'low-confidence';
+    constructor(code: 'unresolved' | 'low-confidence', message: string);
+}
+/** Correlation only: never used as an artifact key or an authorization boundary. */
+export declare function semanticSourceId(repositoryId: string, source: Pick<SemanticSource, 'stableSemanticId'>): string;

package/dist/extraction/semantic-diagnostics.js

@@ -0,0 +1,15 @@
+import { sha256, stableJson } from '../infrastructure/util.js';
+/** Preserve policy distinctions without copying source-specific messages into run reports. */
+export class SemanticPolicyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SemanticPolicyError';
+    }
+}
+/** Correlation only: never used as an artifact key or an authorization boundary. */
+export function semanticSourceId(repositoryId, source) {
+    return `source-${sha256(stableJson({ kind: 'weftlet-semantic-source-v1', repositoryId,
+        stableSemanticId: source.stableSemanticId }))}`;
+}

package/dist/extraction/semantic-identity.d.ts

@@ -0,0 +1,7 @@
+import type { SemanticArtifact, SemanticSource } from '@weftlet/core';
+import type { ContextGraphConfig } from '../configuration/config.js';
+/** Pure identity: inspecting planned work must not load providers or probe credentials. */
+export declare function semanticProviderIdentity(config: ContextGraphConfig['semantic']): string;
+/** Preserve the 0.2.1 artifact contract, including identity-policy invalidation. */
+export declare function semanticArtifactKey(config: ContextGraphConfig['semantic'], source: SemanticSource, modelIdentity: string, forceRevision?: string): string;
+export declare function semanticArtifactOutputDigest(artifact: Pick<SemanticArtifact, 'facts' | 'diagnostics' | 'oml' | 'rawModelOutput'>): string;

package/dist/extraction/semantic-identity.js

@@ -0,0 +1,29 @@
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { repositoryNodeIdentityVersion } from './repository-nodes.js';
+/** Pure identity: inspecting planned work must not load providers or probe credentials. */
+export function semanticProviderIdentity(config) {
+    return config.provider === 'codex-cli'
+        ? `codex-cli:${config.model}:${config.reasoningEffort}:${config.promptVersion}:contract-v3`
+        : `${config.providerIdentity}:${sha256(stableJson(config))}:contract-v2`;
+}
+/** Preserve the 0.2.1 artifact contract, including identity-policy invalidation. */
+export function semanticArtifactKey(config, source, modelIdentity, forceRevision) {
+    return sha256(stableJson({
+        stableSemanticId: source.stableSemanticId,
+        sourceDigest: source.digest,
+        promptVersion: config.promptVersion,
+        extractorVersion: config.extractorVersion,
+        modelIdentity,
+        adapterVersion: config.adapterVersion,
+        ontologyVersion: config.ontologyVersion,
+        minimumConfidence: config.minimumConfidence,
+        failOnUnresolved: config.failOnUnresolved,
+        forceRevision,
+        diagnosticContractVersion: 3,
+        repositoryNodeIdentityVersion,
+    }));
+}
+export function semanticArtifactOutputDigest(artifact) {
+    return sha256(stableJson({ facts: artifact.facts, diagnostics: artifact.diagnostics ?? [],
+        compiledOml: artifact.oml, rawModelOutput: artifact.rawModelOutput }));
+}

package/dist/extraction/semantic-sources.d.ts

@@ -0,0 +1,27 @@
+import type { SemanticSource } from '@weftlet/core';
+import type { ContextGraphConfig } from '../configuration/config.js';
+import type { GitRepository } from '../repository/git.js';
+export interface SemanticSelection {
+    readonly selector: string;
+    readonly paths: readonly string[];
+    readonly excludedPaths: readonly string[];
+    readonly status: 'matched' | 'no-documents' | 'missing';
+}
+export interface SemanticInputIssue {
+    readonly code: string;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly paths: readonly string[];
+}
+/** Git path selection, source bytes and limits are shared by preview and execution. */
+export declare function selectSemanticInputs(repository: GitRepository, commitSha: string, selectors: readonly string[], config: ContextGraphConfig['semantic']): Promise<{
+    sources: readonly SemanticSource[];
+    selections: SemanticSelection[];
+    budgets: {
+        maxDocuments: number;
+        maxSourceBytes: number;
+        selectedDocuments: number;
+        totalSourceBytes: number;
+    };
+    issues: SemanticInputIssue[];
+}>;

package/dist/extraction/semantic-sources.js

@@ -0,0 +1,35 @@
+/** Git path selection, source bytes and limits are shared by preview and execution. */
+export async function selectSemanticInputs(repository, commitSha, selectors, config) {
+    const selections = [];
+    for (const selector of [...new Set(selectors)]) {
+        const files = await repository.listFilesAt(commitSha, [selector]);
+        const paths = files.filter((path) => /\.(?:md|mdx|txt)$/i.test(path));
+        selections.push({ selector, paths, excludedPaths: files.filter((path) => !paths.includes(path)),
+            status: paths.length ? 'matched' : files.length ? 'no-documents' : 'missing' });
+    }
+    const sources = await repository.semanticSources({ commitSha }, selectors);
+    const budgets = { maxDocuments: config.maxDocuments ?? 8, maxSourceBytes: config.maxSourceBytes ?? 65_536,
+        selectedDocuments: sources.length, totalSourceBytes: sources.reduce((sum, source) => sum + Buffer.byteLength(source.content), 0) };
+    const issues = selections.filter((item) => item.status !== 'matched').map((item) => ({
+        code: item.status === 'missing' ? 'missing-source' : 'unsupported-source', severity: 'warning',
+        message: item.status === 'missing' ? `Semantic selector ${item.selector} matches no committed files.`
+            : `Semantic selector ${item.selector} matches no supported Markdown/text documents.`, paths: [item.selector],
+    }));
+    if (sources.length > budgets.maxDocuments)
+        issues.push({ code: 'document-budget', severity: 'error',
+            message: `Semantic source budget exceeded: ${sources.length} documents exceed maxDocuments ${budgets.maxDocuments}.`,
+            paths: sources.map((source) => source.path) });
+    const oversized = sources.filter((source) => Buffer.byteLength(source.content) > budgets.maxSourceBytes);
+    if (oversized.length)
+        issues.push({ code: 'source-byte-budget', severity: 'error',
+            message: `Semantic source budget exceeded: ${oversized.length} documents exceed the per-document maxSourceBytes ${budgets.maxSourceBytes}.`,
+            paths: oversized.map((source) => source.path) });
+    const byId = new Map();
+    for (const source of sources)
+        byId.set(source.stableSemanticId, [...(byId.get(source.stableSemanticId) ?? []), source.path]);
+    for (const [id, paths] of byId)
+        if (paths.length > 1)
+            issues.push({ code: 'duplicate-semantic-id', severity: 'error',
+                message: `Duplicate stable semantic ID: ${id}`, paths });
+    return { sources, selections, budgets, issues };
+}

package/dist/extraction/semantic.d.ts

@@ -7,6 +7,7 @@ export type { SemanticRunOptions } from "./semantic-process.js";
 import type { ExtractionContext, GraphNodeKind, GraphPredicate, SemanticArtifact, SemanticSource, DiagnosticKind } from "@weftlet/core";
 import type { ContextGraphConfig } from "../configuration/config.js";
 import type { SemanticArtifactStore } from "../storage/storage.js";
+import { type SemanticHydrationPhase } from './semantic-diagnostics.js';
 export interface ExtractedAssertion {
     readonly subject: {
         readonly id: string;
@@ -66,8 +67,11 @@ export declare class SemanticHydrator {
     private readonly store;
     private readonly extractor;
     constructor(config: ContextGraphConfig['semantic'], store: SemanticArtifactStore, extractor: SemanticExtractor);
-    hydrate(source: SemanticSource, context: ExtractionContext, forceRevision?: string, options?: SemanticRunOptions): Promise<{
+    hydrate(source: SemanticSource, context: ExtractionContext, forceRevision?: string, options?: SemanticRunOptions & {
+        readonly onPhase?: (phase: SemanticHydrationPhase) => void;
+    }): Promise<{
         artifact: SemanticArtifact;
         reused: boolean;
     }>;
+    private promoteLegacy;
 }

package/dist/extraction/semantic.js

@@ -8,7 +8,10 @@ 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 { canonicalizeRepositoryDocumentNode } from './repository-nodes.js';
+import { semanticArtifactKey, semanticArtifactOutputDigest, semanticProviderIdentity } from './semantic-identity.js';
+import { inspectSemanticCache } from './semantic-cache.js';
+import { SemanticPolicyError } from './semantic-diagnostics.js';
 import { assertSemanticCitation, numberedSemanticSource, semanticCitationSchema, } from "./semantic-citations.js";
 function canonicalizeRepositoryDocuments(output) {
     const ids = new Map();
@@ -228,7 +231,7 @@ export class CodexCliSemanticExtractor {
         this.config = config;
         this.runner = runner;
         this.loginProbe = loginProbe;
-        this.identity = `codex-cli:${config.model}:${config.reasoningEffort}:${config.promptVersion}:contract-v3`;
+        this.identity = semanticProviderIdentity(config);
     }
     async extract(source, context, options = {}) {
         options.signal?.throwIfAborted();
@@ -332,26 +335,32 @@ export class SemanticHydrator {
         this.extractor = extractor;
     }
     async hydrate(source, context, forceRevision, options = {}) {
-        options.signal?.throwIfAborted();
-        const keyInput = {
-            stableSemanticId: source.stableSemanticId,
-            sourceDigest: source.digest,
-            promptVersion: this.config.promptVersion,
-            extractorVersion: this.config.extractorVersion,
-            modelIdentity: this.extractor.identity,
-            adapterVersion: this.config.adapterVersion,
-            ontologyVersion: this.config.ontologyVersion,
-            minimumConfidence: this.config.minimumConfidence,
-            failOnUnresolved: this.config.failOnUnresolved,
-            forceRevision,
-            diagnosticContractVersion: 3,
-            repositoryNodeIdentityVersion,
+        const checkpoint = () => {
+            if (options.signal?.aborted)
+                throw new SemanticProviderError('cancelled', 'Semantic extraction cancelled');
         };
-        const key = sha256(stableJson(keyInput));
-        const existing = await this.store.read(key);
-        if (existing)
-            return { artifact: existing, reused: true };
-        const extraction = await this.extractor.extract(source, context, options);
+        checkpoint();
+        options.onPhase?.('semantic-cache-read');
+        const key = semanticArtifactKey(this.config, source, this.extractor.identity, forceRevision);
+        const cached = await inspectSemanticCache(this.store, this.config, source, this.extractor.identity, forceRevision);
+        if (cached.status === 'hit') {
+            // Planning remains read-only. Execution can copy an inspected legacy hit
+            // atomically without rewriting its original artifact or extraction identity.
+            checkpoint();
+            if (cached.origin === 'legacy')
+                options.onPhase?.('semantic-cache-write');
+            const artifact = cached.origin === 'legacy'
+                ? await this.promoteLegacy(source, cached.artifact, forceRevision) : cached.artifact;
+            return { artifact, reused: true };
+        }
+        if (cached.status !== 'miss')
+            throw new Error(cached.reason);
+        checkpoint();
+        options.onPhase?.('semantic-extract');
+        // Phase observation belongs to hydration, not the provider extension contract.
+        const extraction = await this.extractor.extract(source, context, { signal: options.signal, timeoutMs: options.timeoutMs });
+        checkpoint();
+        options.onPhase?.('semantic-validate');
         assertSemanticOutput(extraction.parsed, source);
         if (typeof extraction.rawModelOutput !== 'string' || Buffer.byteLength(extraction.rawModelOutput) > 2 * 1024 * 1024) {
             throw new SemanticProviderError('invalid-output', 'Invalid or oversized raw semantic output');
@@ -361,7 +370,7 @@ export class SemanticHydrator {
         const facts = output.assertions.map((assertion, index) => {
             assertSemanticCitation(assertion.citation, source.path, lineCount, `assertion[${index}]`);
             if (assertion.confidence < this.config.minimumConfidence) {
-                throw new Error(`Low-confidence semantic assertion for ${source.path}`);
+                throw new SemanticPolicyError('low-confidence', `Low-confidence semantic assertion for ${source.path}`);
             }
             const provenance = {
                 path: source.path,
@@ -408,10 +417,10 @@ export class SemanticHydrator {
         });
         const unresolvedMappings = output.unresolvedMappings ?? [];
         if (this.config.failOnUnresolved && (unresolvedMappings.length > 0 || diagnostics.length > 0)) {
-            throw new Error(`Unresolved semantic mappings for ${source.path}: ${[...unresolvedMappings, ...diagnostics.map((item) => item.reason)].join('; ')}`);
+            throw new SemanticPolicyError('unresolved', `Unresolved semantic mappings for ${source.path}: ${[...unresolvedMappings, ...diagnostics.map((item) => item.reason)].join('; ')}`);
         }
         const compiledOml = renderOml(key, output.assertions);
-        const outputDigest = sha256(stableJson({ facts, diagnostics, compiledOml, rawModelOutput: extraction.rawModelOutput }));
+        const outputDigest = semanticArtifactOutputDigest({ facts, diagnostics, oml: compiledOml, rawModelOutput: extraction.rawModelOutput });
         const artifact = {
             key,
             stableSemanticId: source.stableSemanticId,
@@ -435,7 +444,21 @@ export class SemanticHydrator {
             rawModelOutput: extraction.rawModelOutput,
             outputDigest,
         };
+        checkpoint();
+        options.onPhase?.('semantic-cache-write');
         await this.store.write(artifact);
         return { artifact, reused: false };
     }
+    async promoteLegacy(source, artifact, forceRevision) {
+        await this.store.write(artifact);
+        // A concurrent winner must satisfy the full contract, not merely expose the
+        // same outputDigest field. Never publish using an invalid retained artifact.
+        const retained = await inspectSemanticCache(this.store, this.config, source, this.extractor.identity, forceRevision);
+        if (retained.status !== 'hit')
+            throw new Error(retained.reason);
+        if (retained.origin !== 'primary' || retained.artifact.outputDigest !== artifact.outputDigest) {
+            throw new Error('Concurrent semantic artifact changed during legacy promotion; inspect cache integrity before retrying.');
+        }
+        return retained.artifact;
+    }
 }

package/dist/extraction/static.d.ts

@@ -1,5 +1,5 @@
 import type { ContextGraphConfig } from "../configuration/config.js";
-import type { ExtractionContext, FactExtractor, GraphFact } from "@weftlet/core";
+import { type ExtractionContext, type FactExtractor, type GraphFact } from "@weftlet/core";
 import { GitRepository } from "../repository/git.js";
 export interface ScipIndexResult {
     readonly path: string;
@@ -17,12 +17,16 @@ export declare class ScipTypeScriptIndexer implements StaticIndexer {
     index(context: ExtractionContext): Promise<ScipIndexResult>;
 }
 export declare function normalizeScipCheckout(bytes: Uint8Array, checkoutRoot: string): Uint8Array;
+export declare const scipSymbolExtractorIdentity: {
+    readonly id: "scip-symbol-extractor";
+    readonly version: "1.1.0";
+};
 export declare class ScipSymbolExtractor implements FactExtractor {
     private readonly repository;
     private readonly index;
     readonly identity: {
-        id: string;
-        version: string;
+        readonly id: "scip-symbol-extractor";
+        readonly version: "1.1.0";
     };
     constructor(repository: GitRepository, index: ScipIndexResult);
     extract(context: ExtractionContext): Promise<readonly GraphFact[]>;
@@ -42,14 +46,18 @@ export declare class RepositoryFileExtractor implements FactExtractor {
     constructor(repository: GitRepository, roots: readonly string[], scipDigest: string);
     extract(context: ExtractionContext): Promise<readonly GraphFact[]>;
 }
+export declare const repositoryContractExtractorIdentity: {
+    readonly id: "repository-contract-extractor";
+    readonly version: "1.2.0";
+};
 export declare class RepositoryContractExtractor implements FactExtractor {
     private readonly repository;
     private readonly patterns;
     private readonly consumerRoots;
     private readonly aliases;
     readonly identity: {
-        id: string;
-        version: string;
+        readonly id: "repository-contract-extractor";
+        readonly version: "1.2.0";
     };
     constructor(repository: GitRepository, patterns: readonly string[], consumerRoots: readonly string[], aliases?: Readonly<Record<string, readonly string[]>>);
     extract(context: ExtractionContext): Promise<readonly GraphFact[]>;

package/dist/extraction/static.js

@@ -5,6 +5,7 @@ import { copyFile, mkdir, readFile, rename, stat, writeFile } from 'node:fs/prom
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { repositoryFileNode } from "@weftlet/core";
 import { GitRepository } from "../repository/git.js";
 import { assertScipSourceProject, assertSourceProjectInvocation } from '../configuration/scip-project.js';
 import { prepareScipSourceProject } from './scip-project.js';
@@ -90,10 +91,11 @@ export function normalizeScipCheckout(bytes, checkoutRoot) {
     }
     return index.serializeBinary();
 }
+export const scipSymbolExtractorIdentity = { id: 'scip-symbol-extractor', version: '1.1.0' };
 export class ScipSymbolExtractor {
     repository;
     index;
-    identity = { id: 'scip-symbol-extractor', version: '1.0.0' };
+    identity = scipSymbolExtractorIdentity;
     constructor(repository, index) {
         this.repository = repository;
         this.index = index;
@@ -105,11 +107,7 @@ export class ScipSymbolExtractor {
             const path = document.relative_path.replace(/\\/g, '/');
             const content = await this.repository.readFileAt(context.commitSha, path);
             const digest = sha256(content);
-            const component = {
-                id: `component:file:${path}`,
-                kind: (/\.(spec|test)\.[^.]+$/i.test(path) ? 'Evidence' : 'Component'),
-                label: path,
-            };
+            const component = repositoryFileNode(path);
             for (const occurrence of document.occurrences) {
                 if (!occurrence.symbol || occurrence.symbol.startsWith('local '))
                     continue;
@@ -195,9 +193,7 @@ export class RepositoryFileExtractor {
             const content = await this.repository.readFileAt(context.commitSha, path);
             const digest = sha256(content);
             const component = {
-                id: `component:file:${path}`,
-                kind: (/\.(spec|test)\.[^.]+$/i.test(path) ? 'Evidence' : 'Component'),
-                label: path,
+                ...repositoryFileNode(path),
                 attributes: { scipIndexDigest: this.scipDigest },
             };
             const provenance = {
@@ -239,12 +235,13 @@ export class RepositoryFileExtractor {
         return facts;
     }
 }
+export const repositoryContractExtractorIdentity = { id: 'repository-contract-extractor', version: '1.2.0' };
 export class RepositoryContractExtractor {
     repository;
     patterns;
     consumerRoots;
     aliases;
-    identity = { id: 'repository-contract-extractor', version: '1.1.0' };
+    identity = repositoryContractExtractorIdentity;
     constructor(repository, patterns, consumerRoots, aliases = {}) {
         this.repository = repository;
         this.patterns = patterns;
@@ -306,11 +303,7 @@ export class RepositoryContractExtractor {
                     digest: sha256(consumerContent),
                     commitSha: context.commitSha,
                 };
-                const consumer = {
-                    id: `component:file:${match.path}`,
-                    kind: 'Component',
-                    label: match.path,
-                };
+                const consumer = repositoryFileNode(match.path);
                 facts.push({
                     id: sha256(stableJson({ consumer, contract, consumerProvenance })),
                     subject: consumer,

package/dist/governance/governance.js

@@ -2,10 +2,12 @@ import { readFile, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { createRequire } from 'node:module';
+import { repositoryFileNode } from '@weftlet/core';
 import { GitRepository } from "../repository/git.js";
 import { RdfEvidenceGraph, CG, nodeIri } from "../graph/rdf.js";
 import { sha256, stableJson } from "../infrastructure/util.js";
 import { runProcess } from "../infrastructure/process.js";
+const architectureAnalyzerVersion = '3';
 export async function analyzeArchitecture(root, policy, policyPath = 'architecture.policy.json') {
     const findings = [];
     const add = (category, ruleId, from, to, message) => {
@@ -86,11 +88,11 @@ export async function analyzeArchitecture(root, policy, policyPath = 'architectu
                 const lines = content.split('\n');
                 facts.push({
                     id: sha256(stableJson({ from: module.source, to: dependency.resolved, digest: inputs[module.source] })),
-                    subject: { id: `component:file:${module.source}`, kind: 'Component', label: module.source,
+                    subject: { ...repositoryFileNode(module.source),
                         attributes: membership[0] ? { domain: membership[0].domain, layer: membership[0].layer,
                             module: membership[0].id, adapter: Boolean(membership[0].adapter) } : {} },
                     predicate: 'consumes',
-                    object: { id: `component:file:${dependency.resolved}`, kind: 'Component', label: dependency.resolved },
+                    object: repositoryFileNode(dependency.resolved),
                     provenance: { path: module.source, startLine: 1, endLine: lines.length, digest: inputs[module.source], commitSha },
                     extractor: { id: 'dependency-cruiser', version: '18.7.0' }, confidence: 1,
                     authority: dirtyPaths.has(module.source) ? 'draft' : 'implemented', snapshotId: 'pending',
@@ -128,7 +130,7 @@ export async function analyzeArchitecture(root, policy, policyPath = 'architectu
             attributes: { domain: module.domain, layer: module.layer, adapter: Boolean(module.adapter) } };
         addPolicyFact(node, 'governedBy', { id: `layer:${module.layer}`, kind: 'Scope', label: module.layer });
         for (const path of Object.keys(inputs).filter((path) => new RegExp(module.path).test(path))) {
-            addPolicyFact(node, 'contains', { id: `component:file:${path}`, kind: 'Component', label: path });
+            addPolicyFact(node, 'contains', repositoryFileNode(path));
         }
     }
     for (const contract of policy.contracts ?? []) {
@@ -137,14 +139,16 @@ export async function analyzeArchitecture(root, policy, policyPath = 'architectu
     if (!Object.keys(inputs).length)
         add('extraction-gap', 'source-coverage', '', '', 'No source files were analyzed');
     const contentDigest = sha256(stableJson({ inputs, policyDigest, commitSha, dirtyPaths: [...dirtyPaths].sort(),
-        tools: { dependencyCruiser: '18.7.0', eslint: '10.13.0', jscpd: '5.4.1', analyzer: '2' } }));
+        tools: { dependencyCruiser: '18.7.0', eslint: '10.13.0', jscpd: '5.4.1', analyzer: architectureAnalyzerVersion } }));
     const snapshotId = `architecture-${contentDigest}`;
     const snapshot = {
         manifest: {
             schemaVersion: 1, repositoryId: 'architecture-analysis', ref: 'HEAD', commitSha, snapshotId,
             configurationDigest: policyDigest, scope: policy.roots, contentDigest,
             ...(dirtyPaths.size ? { baseSha: commitSha, overlayDigest: contentDigest } : {}),
-            ontologyVersion: 'architecture-v1', extractorVersions: { 'dependency-cruiser': '18.7.0' },
+            ontologyVersion: 'architecture-v1', extractorVersions: {
+                'dependency-cruiser': '18.7.0', 'architecture-analyzer': architectureAnalyzerVersion,
+            },
             semanticModel: 'none', semanticPromptVersion: 'none', generatedAt: new Date().toISOString(),
             semanticArtifactKeys: [], scipIndexDigest: '', rdfDigest: '',
         },
@@ -158,8 +162,8 @@ export async function analyzeArchitecture(root, policy, policyPath = 'architectu
         if (result.truncated)
             add('extraction-gap', rule.id, '', '', 'Transitive dependency query truncated');
         for (const row of result.rows) {
-            const from = modules.find((m) => nodeIri(`component:file:${m.source}`) === row.from)?.source;
-            const to = modules.find((m) => nodeIri(`component:file:${m.source}`) === row.to)?.source;
+            const from = modules.find((m) => nodeIri(repositoryFileNode(m.source).id) === row.from)?.source;
+            const to = modules.find((m) => nodeIri(repositoryFileNode(m.source).id) === row.to)?.source;
             if (from && to && new RegExp(rule.from).test(from) && new RegExp(rule.to).test(to)) {
                 add(rule.approved ? 'rule-violation' : 'advisory', rule.id, from, to, 'Transitive dependency inferred by SPARQL property path from source import evidence');
             }

package/dist/graph/query.js

@@ -113,6 +113,7 @@ export class MarkdownContextPackRenderer {
             ] : []),
             ...(pack.evidenceState ? [
                 `Stale relative to checkout: ${pack.evidenceState.stale}; configuration matches: ${pack.evidenceState.configurationMatches}`,
+                `Extraction compatibility: ${pack.evidenceState.extractionCompatible === undefined ? 'not assessed' : pack.evidenceState.extractionCompatible ? 'current' : `refresh required (${pack.evidenceState.incompatibleExtractors?.join(', ') || 'unknown versions'})`}`,
                 `Excluded working changes: ${pack.evidenceState.excludedWorkingChanges.join(', ') || '(none)'}`,
                 ...(pack.evidenceState.overlayFreshness ? [
                     `Overlay freshness: ${pack.evidenceState.overlayFreshness}`,
@@ -327,6 +328,7 @@ export class SnapshotImpactQueryService {
                 baseSha: snapshot.manifest.baseSha,
                 overlayDigest: snapshot.manifest.overlayDigest,
                 overlayCapture: snapshot.manifest.overlayCapture,
+                extractorVersions: snapshot.manifest.extractorVersions,
             },
             capabilities,
             facts,

package/dist/graph/rdf.d.ts

@@ -1,5 +1,5 @@
 import type { GraphFact, GraphSnapshot } from "@weftlet/core";
-export declare const CG = "https://context-graph.dev/record#";
+export { CG } from './shacl-shapes.js';
 export declare const nodeIri: (id: string) => string;
 export declare const factIri: (id: string) => string;
 /** Lossless RDF dataset: one named graph per cited assertion, with provenance in the default graph. */