@weftlet/toolkit 0.3.0 → 0.4.0

package/dist/application/overlay.js

@@ -5,12 +5,13 @@ 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, repositoryFileExtractorIdentity } from "../extraction/static.js";
+import { RepositoryContractExtractor, RepositoryFileExtractor, ScipSymbolExtractor, ScipTypeScriptIndexer, repositoryFileExtractorIdentity, repositoryContractExtractorIdentity, scipSymbolExtractorIdentity } 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';
+import { graphAssemblyIdentity } from './extraction-identity.js';
 const execute = promisify(execFile);
 const implementationExtractors = new Set([
     'repository-file-extractor', 'repository-contract-extractor', 'scip-symbol-extractor',
@@ -57,7 +58,10 @@ export async function buildWorkingOverlay(repository, config, store, storageRoot
     // 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,
+        assembly: graphAssemblyIdentity,
         repositoryFileExtractor: repositoryFileExtractorIdentity,
+        repositoryContractExtractor: repositoryContractExtractorIdentity,
+        scipSymbolExtractor: scipSymbolExtractorIdentity,
         ...(routingSources.length ? { routingExtractor: routingExtractorIdentity } : {}),
     })).slice(0, 32)}`;
     const affected = new Set(captured.map((file) => file.path));
@@ -120,7 +124,10 @@ export async function buildWorkingOverlay(repository, config, store, storageRoot
         manifest: {
             ...base.manifest, snapshotId, baseSha: head, overlayDigest, overlayCapture,
             extractorVersions: { ...base.manifest.extractorVersions,
+                assembly: graphAssemblyIdentity,
                 [repositoryFileExtractorIdentity.id]: repositoryFileExtractorIdentity.version,
+                [repositoryContractExtractorIdentity.id]: repositoryContractExtractorIdentity.version,
+                [scipSymbolExtractorIdentity.id]: scipSymbolExtractorIdentity.version,
                 ...(routingSources.length ? { [routingExtractorIdentity.id]: routingExtractorIdentity.version } : {}) },
             generatedAt: new Date().toISOString(), contentDigest: sha256(stableJson(routingSources.length
                 ? { facts: allFacts, diagnostics: extracted.diagnostics } : allFacts)),
@@ -136,8 +143,8 @@ export async function buildWorkingOverlay(repository, config, store, storageRoot
         ],
         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 new RdfEvidenceGraph(overlay).validate()).conforms) {
+        throw new Error('Draft overlay failed SHACL validation; saved evidence was preserved');
     }
     if (await repository.resolveRef('HEAD') !== head)
         throw new Error('HEAD changed during overlay capture; retry');

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

@@ -5,20 +5,23 @@ export declare class SavedEvidenceQueryService implements ImpactQueryService {
     private readonly queries;
     private readonly repository;
     private readonly configurationDigest;
-    constructor(queries: ImpactQueryService, repository: GitRepository, configurationDigest: string);
+    private readonly expectedExtractors?;
+    constructor(queries: ImpactQueryService, repository: GitRepository, configurationDigest: string, expectedExtractors?: Readonly<Record<string, string>> | undefined);
     scan(request: ImpactScanRequest): Promise<{
         markdown: string;
         evidenceState: {
+            eligibleForCurrentDiffValidation: false;
+            extractionCompatible?: boolean | undefined;
+            incompatibleExtractors?: readonly string[] | undefined;
             stale: boolean;
             configurationMatches: boolean;
-            eligibleForCurrentDiffValidation: false;
             overlayFreshness?: "current" | "stale" | "unknown" | undefined;
             capturedWorkingChanges?: string[] | undefined;
             changedSinceCapture?: string[] | undefined;
             currentCommit: string | undefined;
             excludedWorkingChanges: string[];
         };
-        snapshot: Pick<import("@weftlet/core").SnapshotManifest, "snapshotId" | "commitSha" | "contentDigest" | "configurationDigest" | "scope" | "baseSha" | "overlayDigest" | "overlayCapture">;
+        snapshot: Pick<import("@weftlet/core").SnapshotManifest, "snapshotId" | "commitSha" | "contentDigest" | "configurationDigest" | "scope" | "baseSha" | "overlayDigest" | "overlayCapture"> & Partial<Pick<import("@weftlet/core").SnapshotManifest, "extractorVersions">>;
         capabilities: readonly import("@weftlet/core").GraphNode[];
         facts: readonly import("@weftlet/core").GraphFact[];
         invariants: readonly import("@weftlet/core").InvariantResult[];

package/dist/application/saved-evidence.js

@@ -1,15 +1,18 @@
 import { MarkdownContextPackRenderer } from "../graph/query.js";
 import { inWorkingScope, readWorkingContent } from "../repository/working-content.js";
 import { sha256 } from "../infrastructure/util.js";
+import { incompatibleSnapshotExtractors } from './extraction-identity.js';
 /** Read-side metadata; never calls an indexer, model, compiler, or refresh operation. */
 export class SavedEvidenceQueryService {
     queries;
     repository;
     configurationDigest;
-    constructor(queries, repository, configurationDigest) {
+    expectedExtractors;
+    constructor(queries, repository, configurationDigest, expectedExtractors) {
         this.queries = queries;
         this.repository = repository;
         this.configurationDigest = configurationDigest;
+        this.expectedExtractors = expectedExtractors;
     }
     async scan(request) {
         const pack = await this.queries.scan(request);
@@ -45,12 +48,15 @@ export class SavedEvidenceQueryService {
             }
         }
         const excludedWorkingChanges = workingChanges.filter((path) => !capturedWorkingChanges.includes(path));
+        const incompatibleExtractors = this.expectedExtractors
+            ? incompatibleSnapshotExtractors(pack.snapshot.extractorVersions, this.expectedExtractors) : undefined;
         const evidenceState = {
             currentCommit,
             excludedWorkingChanges,
             ...(overlayFreshness ? { overlayFreshness, capturedWorkingChanges, changedSinceCapture: [...changedSinceCapture].sort() } : {}),
             stale: currentCommit !== pack.snapshot.commitSha || (overlayFreshness !== undefined && overlayFreshness !== 'current'),
             configurationMatches: pack.snapshot.configurationDigest === this.configurationDigest,
+            ...(incompatibleExtractors ? { extractionCompatible: incompatibleExtractors.length === 0, incompatibleExtractors } : {}),
             eligibleForCurrentDiffValidation: false,
         };
         const result = { ...pack, evidenceState };

package/dist/application/semantic-artifact-store.d.ts

@@ -0,0 +1,4 @@
+import type { ContextGraphConfig } from '../configuration/config.js';
+import { SemanticArtifactStore } from '../storage/storage.js';
+/** Shared by planning and execution; construction never creates directories or reads credentials. */
+export declare function createSemanticArtifactStore(repositoryRoot: string, config: ContextGraphConfig, userCacheRoot?: string): SemanticArtifactStore;

package/dist/application/semantic-artifact-store.js

@@ -0,0 +1,7 @@
+import { resolveSemanticStorageRoots } from '../configuration/cache.js';
+import { SemanticArtifactStore } from '../storage/storage.js';
+/** Shared by planning and execution; construction never creates directories or reads credentials. */
+export function createSemanticArtifactStore(repositoryRoot, config, userCacheRoot) {
+    const { primary, legacy } = resolveSemanticStorageRoots(repositoryRoot, config, userCacheRoot);
+    return new SemanticArtifactStore(primary, legacy ? [legacy] : []);
+}

package/dist/application/semantic-run.d.ts

@@ -0,0 +1,29 @@
+import type { ExtractionContext, SemanticSource } from '@weftlet/core';
+import type { ContextGraphConfig } from '../configuration/config.js';
+import type { SemanticHydrator } from '../extraction/semantic.js';
+export interface HydrationProgressEvent {
+    readonly phase: string;
+    readonly completed?: number;
+    readonly total?: number;
+    readonly sourceId?: string;
+    readonly elapsedMs?: number;
+}
+/** Settle active workers before reporting failure; never publish snapshots here. */
+export declare function hydrateSemanticSources(options: {
+    readonly sources: readonly SemanticSource[];
+    readonly context: ExtractionContext;
+    readonly config: ContextGraphConfig['semantic'];
+    readonly configurationDigest: string;
+    readonly hydrator: SemanticHydrator;
+    readonly forceRevision?: string;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (event: HydrationProgressEvent) => void;
+}): Promise<{
+    hydrated: readonly {
+        artifact: import("@weftlet/core").SemanticArtifact;
+        reused: boolean;
+        source: SemanticSource;
+    }[];
+    semanticExtracted: number;
+    semanticReused: number;
+}>;

package/dist/application/semantic-run.js

@@ -0,0 +1,111 @@
+import { semanticSourceId } from '../extraction/semantic-diagnostics.js';
+import { SemanticHydrationError, semanticFailureCategory, semanticFailureCode } from './hydration-failure.js';
+async function concurrentMap(values, concurrency, worker, shouldStop) {
+    const results = new Array(values.length);
+    let cursor = 0;
+    let failure;
+    let failed = false;
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, values.length)) }, async () => {
+        while (!failed && !shouldStop() && cursor < values.length) {
+            const index = cursor++;
+            try {
+                results[index] = await worker(values[index], index);
+            }
+            catch (error) {
+                failed = true;
+                failure ??= error;
+            }
+        }
+    }));
+    if (failed)
+        throw failure;
+    return results;
+}
+/** Settle active workers before reporting failure; never publish snapshots here. */
+export async function hydrateSemanticSources(options) {
+    const { sources, context, config, configurationDigest, hydrator, forceRevision } = options;
+    const { commitSha } = context;
+    const runStarted = performance.now();
+    let semanticExtracted = 0;
+    let semanticReused = 0;
+    let started = 0;
+    let failed = 0;
+    let cancelled = 0;
+    let firstFailure;
+    const controller = new AbortController();
+    const signal = AbortSignal.any([controller.signal, ...(options.signal ? [options.signal] : [])]);
+    const hydrated = await concurrentMap(sources, config.concurrency, async (source) => {
+        started += 1;
+        const sourceId = semanticSourceId(context.repositoryId, source);
+        const sourceStarted = performance.now();
+        let phase = 'semantic-cache-read';
+        options.onProgress?.({ phase: 'semantic-source-started', sourceId,
+            completed: semanticExtracted + semanticReused, total: sources.length });
+        let result;
+        try {
+            result = await hydrator.hydrate(source, context, forceRevision, { signal, onPhase: value => { phase = value; } });
+        }
+        catch (error) {
+            // Record the initiating failure before abort synchronously notifies other workers.
+            const code = semanticFailureCode(error, phase, signal);
+            if (code === 'cancelled')
+                cancelled += 1;
+            else
+                failed += 1;
+            firstFailure ??= { code, sourceId, phase, elapsedScope: 'source', elapsedMs: Math.round(performance.now() - sourceStarted) };
+            controller.abort();
+            throw error;
+        }
+        if (result.reused)
+            semanticReused += 1;
+        else
+            semanticExtracted += 1;
+        options.onProgress?.({ phase: result.reused ? 'semantic-cache-hit' : 'semantic-extracted',
+            sourceId, elapsedMs: Math.round(performance.now() - sourceStarted),
+            completed: semanticReused + semanticExtracted, total: sources.length });
+        return { source, ...result };
+    }, () => signal.aborted).catch(() => {
+        if (!firstFailure)
+            throw new Error('Semantic hydration failed before source processing could be reported');
+        return undefined;
+    });
+    // Cancellation can arrive during a durable write or completion callback, without
+    // a failed source. Do not relabel successfully retained work as cancelled.
+    if (!firstFailure && signal.aborted)
+        firstFailure = { code: 'cancelled', phase: 'semantic-scheduling',
+            elapsedScope: 'semantic-run', elapsedMs: Math.round(performance.now() - runStarted) };
+    if (firstFailure) {
+        // concurrentMap settles every active worker before returning: these are final counts.
+        const completed = semanticExtracted + semanticReused;
+        const recovery = [
+            'No snapshot was published by this run. Previously published evidence and completed artifacts were retained.',
+            'Inspect hydrate --plan --json locally with the same --config, committed --ref and scope options to map sourceId to its path and check expected reuse. The preview contains local paths; review it before sharing.',
+        ];
+        if (firstFailure.code === 'timeout')
+            recovery.push('Review semantic.timeoutMs before retrying. This limit is per Codex attempt (authentication is separately bounded), or covers module import/factory/extraction; source elapsed time can be longer.');
+        else if (firstFailure.code === 'unavailable')
+            recovery.push('Run doctor with the same configuration to check provider installation and authentication.');
+        else if (firstFailure.code === 'cache-failure')
+            recovery.push('Inspect cache integrity and permissions. Corrupt or conflicting complete artifacts are retained and must be repaired explicitly; a timeout change cannot repair them.');
+        else if (firstFailure.code === 'invalid-output')
+            recovery.push('Review source coverage and extraction policy locally; invalid output is an extraction gap, not an approved rule or a passing validation.');
+        else if (firstFailure.code === 'unresolved' || firstFailure.code === 'low-confidence')
+            recovery.push('Review cited sources and configured confidence/unresolved policy locally. Required evidence needs review; a policy rejection is not approved intent or a passing validation.');
+        else if (firstFailure.code === 'exit' || firstFailure.code === 'provider-failure')
+            recovery.push('Check provider readiness locally. Private provider messages are omitted; this failure is not proof of a timeout.');
+        recovery.push(forceRevision
+            ? 'This run used --force-semantic. Its completed revision artifacts remain stored, but an ordinary rerun or a new forced run does not automatically reuse that revision.'
+            : 'Rerun hydrate without --force-semantic after resolving the failure; only valid compatible completed artifacts are reusable.');
+        recovery.push(config.provider === 'codex-cli'
+            ? 'Built-in Codex supports reuse across operational timeout changes. For profiles created before shared caching, use cache adopt --from-config with the exact previous configuration; preview with --dry-run first.'
+            : 'Custom provider identities include their full semantic configuration; changing a module timeout may invalidate reuse. Preview again before extraction.');
+        throw new SemanticHydrationError({ schemaVersion: 1, kind: 'semantic-hydration-failure', ...firstFailure,
+            category: semanticFailureCategory(firstFailure.code), commitSha, configurationDigest,
+            timeoutMs: config.timeoutMs ?? 120_000,
+            timeoutScope: config.provider === 'codex-cli' ? 'provider-attempt' : 'module-execution',
+            progress: { total: sources.length, completed, extracted: semanticExtracted, reused: semanticReused,
+                failed, cancelled, notStarted: sources.length - started, remaining: sources.length - completed },
+            forced: !!forceRevision, recovery });
+    }
+    return { hydrated: hydrated, semanticExtracted, semanticReused };
+}

package/dist/application/semantic-scope.d.ts

@@ -0,0 +1,13 @@
+import type { ImpactScanRequest } from '@weftlet/core';
+import type { ContextGraphConfig } from '../configuration/config.js';
+import type { GitRepository } from '../repository/git.js';
+export interface SemanticScope {
+    readonly mode: 'configured' | 'agent';
+    readonly selectors: readonly string[];
+    readonly digest: string;
+    readonly headName: string;
+    readonly omittedDocuments: readonly string[];
+    readonly ignoredSearchTerms: number;
+}
+/** Resolve the same committed selection for previews and explicit artifact recovery. */
+export declare function resolveSemanticScope(config: ContextGraphConfig, repository: GitRepository, commitSha: string, request?: ImpactScanRequest): Promise<SemanticScope>;

package/dist/application/semantic-scope.js

@@ -0,0 +1,12 @@
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { AgentSemanticScopeResolver } from './agent-context.js';
+/** Resolve the same committed selection for previews and explicit artifact recovery. */
+export async function resolveSemanticScope(config, repository, commitSha, request = {}) {
+    const agent = config.agentContext
+        ? await new AgentSemanticScopeResolver(config, repository).resolve(request, commitSha)
+        : undefined;
+    const selectors = agent?.semanticSources ?? config.semanticSources;
+    return { mode: agent ? 'agent' : 'configured', selectors, digest: sha256(stableJson(selectors)),
+        headName: agent?.headName ?? 'default', omittedDocuments: agent?.omittedDocuments ?? [],
+        ignoredSearchTerms: agent?.ignoredSearchTerms ?? 0 };
+}

package/dist/application/snapshot-checks.d.ts

@@ -8,7 +8,8 @@ export declare class SnapshotChecks {
     private readonly hydrator;
     private readonly scopeResolver?;
     private readonly configurationDigest?;
-    constructor(store: Pick<SnapshotStore, 'readHead'>, repository: Pick<GitRepository, 'resolveRef'> & Partial<Pick<GitRepository, 'workingChanges'>>, hydrator: Pick<ContextGraphHydrator, 'compareClean'>, scopeResolver?: Pick<AgentSemanticScopeResolver, "resolve"> | undefined, configurationDigest?: string | undefined);
+    private readonly expectedExtractors;
+    constructor(store: Pick<SnapshotStore, 'readHead'>, repository: Pick<GitRepository, 'resolveRef'> & Partial<Pick<GitRepository, 'workingChanges'>>, hydrator: Pick<ContextGraphHydrator, 'compareClean'>, scopeResolver?: Pick<AgentSemanticScopeResolver, "resolve"> | undefined, configurationDigest?: string | undefined, expectedExtractors?: Readonly<Record<string, string>>);
     private target;
     private readTarget;
     read(request: ImpactScanRequest, ref?: string): Promise<import("@weftlet/core").GraphSnapshot>;

package/dist/application/snapshot-checks.js

@@ -1,3 +1,4 @@
+import { incompatibleSnapshotExtractors, requiredSnapshotExtractorVersions } from './extraction-identity.js';
 // Final checks must use the same scope resolver as prepared impact scans, without silently
 // starting hydration or substituting another owner's (or an older commit's) evidence.
 export class SnapshotChecks {
@@ -6,12 +7,14 @@ export class SnapshotChecks {
     hydrator;
     scopeResolver;
     configurationDigest;
-    constructor(store, repository, hydrator, scopeResolver, configurationDigest) {
+    expectedExtractors;
+    constructor(store, repository, hydrator, scopeResolver, configurationDigest, expectedExtractors = requiredSnapshotExtractorVersions()) {
         this.store = store;
         this.repository = repository;
         this.hydrator = hydrator;
         this.scopeResolver = scopeResolver;
         this.configurationDigest = configurationDigest;
+        this.expectedExtractors = expectedExtractors;
     }
     async target(request, ref) {
         if (request.snapshotId)
@@ -38,6 +41,10 @@ export class SnapshotChecks {
         if (this.configurationDigest && snapshot.manifest.configurationDigest !== this.configurationDigest) {
             throw new Error('Snapshot configuration differs from current configuration; refresh required');
         }
+        const incompatible = incompatibleSnapshotExtractors(snapshot.manifest.extractorVersions, this.expectedExtractors);
+        if (incompatible.length) {
+            throw new Error(`Snapshot extraction versions require refresh (${incompatible.join(', ')}). Historical evidence remains queryable; hydrate with the current toolkit before final validation.`);
+        }
         return snapshot;
     }
     async read(request, ref = 'HEAD') {

package/dist/configuration/cache.d.ts

@@ -1,2 +1,8 @@
 import type { ContextGraphConfig } from "./config.js";
 export declare function resolveStorageRoot(repositoryRoot: string, config: ContextGraphConfig, userCacheRoot?: string): string;
+export declare function semanticCachePartition(repositoryRoot: string, config: ContextGraphConfig): string;
+/** Snapshot profiles retain the full configuration. Only Codex user artifacts share operational changes. */
+export declare function resolveSemanticStorageRoots(repositoryRoot: string, config: ContextGraphConfig, userCacheRoot?: string): {
+    primary: string;
+    legacy?: string;
+};

package/dist/configuration/cache.js

@@ -8,3 +8,21 @@ export function resolveStorageRoot(repositoryRoot, config, userCacheRoot = resol
     const profile = sha256(stableJson({ config, checkout: resolve(repositoryRoot) })).slice(0, 20);
     return resolve(userCacheRoot, profile);
 }
+// These controls do not change a successful built-in Codex extraction. Unknown
+// fields and module-provider configuration remain conservative identity inputs.
+const codexOperationalFields = new Set([
+    'timeoutMs', 'retries', 'concurrency', 'maxDocuments', 'maxSourceBytes',
+]);
+export function semanticCachePartition(repositoryRoot, config) {
+    const semantic = config.semantic.provider === 'codex-cli'
+        ? Object.fromEntries(Object.entries(config.semantic).filter(([field]) => !codexOperationalFields.has(field)))
+        : config.semantic;
+    return sha256(stableJson({ config: { ...config, semantic }, checkout: resolve(repositoryRoot) }));
+}
+/** Snapshot profiles retain the full configuration. Only Codex user artifacts share operational changes. */
+export function resolveSemanticStorageRoots(repositoryRoot, config, userCacheRoot = resolve(homedir(), '.cache', 'context-graph')) {
+    const legacy = resolveStorageRoot(repositoryRoot, config, userCacheRoot);
+    if (config.storageScope !== 'user' || config.semantic.provider !== 'codex-cli')
+        return { primary: legacy };
+    return { primary: resolve(userCacheRoot, 'semantic-artifacts-v1', semanticCachePartition(repositoryRoot, config)), legacy };
+}

package/dist/extraction/document.js

@@ -1,6 +1,6 @@
 import { sha256, stableJson } from '../infrastructure/util.js';
 import { documentReferences, resolveDocumentReference } from './document-references.js';
-import { repositoryFileNode as fileNode } from './repository-nodes.js';
+import { repositoryFileNode as fileNode } from '@weftlet/core';
 export const documentLinkerIdentity = { id: 'document-linker', version: '2.0.0' };
 export function linkSemanticDocuments(context, hydrated, trackedPaths, approvedSourcePaths = []) {
     const facts = new Map();

package/dist/extraction/providers.js

@@ -31,14 +31,21 @@ export function createSemanticExtractor(config, repositoryRoot) {
                     Promise.resolve().then(async () => {
                         checkpoint();
                         if (!extractor) {
-                            const module = await import(resolveConsumerModule(modulePath, repositoryRoot));
+                            let module;
+                            try {
+                                module = await import(resolveConsumerModule(modulePath, repositoryRoot));
+                            }
+                            catch {
+                                checkpoint();
+                                throw new SemanticProviderError('unavailable', 'Semantic provider module could not be loaded');
+                            }
                             checkpoint();
                             if (typeof module.createSemanticExtractor !== 'function')
-                                throw new Error('Provider module must export createSemanticExtractor(config)');
+                                throw new SemanticProviderError('unavailable', 'Provider module must export createSemanticExtractor(config)');
                             const candidate = await module.createSemanticExtractor(config, { ...options, signal });
                             checkpoint();
                             if (candidate?.identity !== config.providerIdentity || typeof candidate.extract !== 'function') {
-                                throw new Error('Provider identity/contract does not match configuration');
+                                throw new SemanticProviderError('unavailable', 'Provider identity/contract does not match configuration');
                             }
                             extractor = candidate;
                         }

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

@@ -1,7 +1,6 @@
-import type { GraphNode } from '@weftlet/core';
+import { type GraphNode } from '@weftlet/core';
+export { repositoryFileNode } 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

@@ -1,20 +1,14 @@
+import { repositoryFileNode } from '@weftlet/core';
+export { repositoryFileNode } from '@weftlet/core';
 /** 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]))
+    if (!match)
         return node;
     const canonical = repositoryFileNode(match[1]);
+    if (canonical.kind !== 'Document')
+        return node;
     return { ...node, id: canonical.id, kind: canonical.kind };
 }

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

@@ -7,6 +7,7 @@ export interface SemanticCacheInspection {
     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

@@ -42,8 +42,11 @@ function reusableArtifact(value, key, source, config, modelIdentity) {
 export async function inspectSemanticCache(store, config, source, modelIdentity, forceRevision) {
     const key = semanticArtifactKey(config, source, modelIdentity, forceRevision);
     let value;
+    let origin;
     try {
-        value = await store.read(key);
+        const entry = await store.readEntry(key);
+        value = entry?.artifact;
+        origin = entry?.origin;
     }
     catch (error) {
         return error instanceof SyntaxError
@@ -55,5 +58,9 @@ export async function inspectSemanticCache(store, config, source, modelIdentity,
     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, reason: 'Readable artifact matches the source and extraction contract; reuse remains subject to unchanged inputs.', artifact: value };
+    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.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;
 }