@weftlet/toolkit 0.3.0 → 0.5.0

package/dist/application/hydrator.js

@@ -1,6 +1,6 @@
 import { scipSourcePatterns } from '../configuration/scip-project.js';
 import { contractPatternRoots } from "../repository/glob.js";
-import { repositoryFileExtractorIdentity } from '../extraction/static.js';
+import { repositoryFileExtractorIdentity, repositoryContractExtractorIdentity, scipSymbolExtractorIdentity } from '../extraction/static.js';
 import { sha256, stableJson } from "../infrastructure/util.js";
 import { documentLinkerIdentity, linkSemanticDocuments } from "../extraction/document.js";
 import { repositoryNodeIdentityVersion } from '../extraction/repository-nodes.js';
@@ -9,27 +9,11 @@ import { runtimeEvidenceFacts } from "../extraction/runtime-evidence.js";
 import { matchesRepositoryGlob } from "../repository/glob.js";
 import { RdfEvidenceGraph } from "../graph/rdf.js";
 import { extractRoutingDeclarations, routingExtractorIdentity } from '../extraction/routing.js';
-async function concurrentMap(values, concurrency, worker) {
-    const results = new Array(values.length);
-    let cursor = 0;
-    let failure;
-    let failed = false;
-    await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, values.length)) }, async () => {
-        while (!failed && 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;
-}
+import { SemanticProviderError } from '../extraction/semantic-process.js';
+import { hydrateSemanticSources } from './semantic-run.js';
+import { graphAssemblyVersion, graphAssemblyIdentity } from './extraction-identity.js';
+import { assertGraphIdentities } from '../graph/identity-preflight.js';
+import { measureValidationPhase } from '../graph/validation-progress.js';
 export class ContextGraphHydrator {
     dependencies;
     constructor(dependencies) {
@@ -57,7 +41,11 @@ export class ContextGraphHydrator {
         };
     }
     async hydrate(options) {
-        options.signal?.throwIfAborted();
+        const checkpoint = () => {
+            if (options.signal?.aborted)
+                throw new SemanticProviderError('cancelled', 'Hydration cancelled');
+        };
+        checkpoint();
         options.onProgress?.({ phase: 'resolve-committed-sources' });
         const { config, repository, snapshotStore } = this.dependencies;
         const commitSha = await repository.resolveRef(options.ref);
@@ -99,7 +87,9 @@ export class ContextGraphHydrator {
             : undefined;
         const configurationDigest = sha256(stableJson(config));
         const scopeDigest = sha256(stableJson(selectedSemanticSources)).slice(0, 12);
-        const effectiveSuffix = ['graph-v6', `links-${documentLinkerIdentity.version}`, `files-${repositoryFileExtractorIdentity.version}`,
+        const effectiveSuffix = [`graph-v${graphAssemblyVersion}`, `links-${documentLinkerIdentity.version}`, `files-${repositoryFileExtractorIdentity.version}`,
+            `contracts-${repositoryContractExtractorIdentity.version}`,
+            `symbols-${scipSymbolExtractorIdentity.version}`,
             ...(config.routingSources?.length ? [`routes-${routingExtractorIdentity.version}`] : []),
             configurationDigest.slice(0, 16), scopeDigest, baseSuffix, runtimeSuffix].filter(Boolean).join('-');
         const snapshotId = effectiveSuffix ? `${commitSha}-${effectiveSuffix}` : commitSha;
@@ -117,26 +107,10 @@ export class ContextGraphHydrator {
         };
         // Validate committed routing inputs before invoking any provider or indexer.
         const routing = await extractRoutingDeclarations(repository, context, config.routingSources ?? []);
-        let semanticExtracted = 0;
-        let semanticReused = 0;
-        const controller = new AbortController();
-        const signal = AbortSignal.any([controller.signal, ...(options.signal ? [options.signal] : [])]);
-        const hydrated = await concurrentMap(sources, config.semantic.concurrency, async (source) => {
-            let result;
-            try {
-                result = await this.dependencies.semanticHydrator.hydrate(source, context, forceRevision, { signal });
-            }
-            catch (error) {
-                controller.abort();
-                throw error;
-            }
-            if (result.reused)
-                semanticReused += 1;
-            else
-                semanticExtracted += 1;
-            options.onProgress?.({ phase: result.reused ? 'semantic-cache-hit' : 'semantic-extracted',
-                completed: semanticReused + semanticExtracted, total: sources.length });
-            return { source, ...result };
+        const { hydrated, semanticExtracted, semanticReused } = await hydrateSemanticSources({
+            sources, context, config: config.semantic, configurationDigest,
+            hydrator: this.dependencies.semanticHydrator, forceRevision,
+            signal: options.signal, onProgress: options.onProgress,
         });
         const artifacts = hydrated.map((result) => result.artifact);
         const diagnostics = hydrated.flatMap(({ source, artifact }) => (artifact.diagnostics ?? []).map((item) => ({
@@ -163,7 +137,7 @@ export class ContextGraphHydrator {
             extractionReview: 'unreviewed',
             sourceAuthority: (config.approvedIntentSources?.some((pattern) => matchesRepositoryGlob(source.path, pattern)) ? 'declared' : 'inferred'),
         })));
-        options.signal?.throwIfAborted();
+        checkpoint();
         options.onProgress?.({ phase: 'index-typescript' });
         const scip = await this.dependencies.staticIndexer.index(context);
         const extractorFacts = (await Promise.all(this.dependencies.extractorFactory(scip).map((extractor) => extractor.extract(context)))).flat();
@@ -184,12 +158,20 @@ export class ContextGraphHydrator {
         const documents = linkSemanticDocuments(context, hydrated, trackedPaths, sources.filter((source) => config.approvedIntentSources?.some((pattern) => matchesRepositoryGlob(source.path, pattern))).map((source) => source.path));
         diagnostics.push(...documents.diagnostics);
         diagnostics.push(...routing.diagnostics);
-        options.signal?.throwIfAborted();
-        options.onProgress?.({ phase: 'compile-semantic-rdf' });
-        const ontology = await this.dependencies.ontologyCompiler.compile(snapshotId, artifacts, context);
+        checkpoint();
         const runtimeEvidence = runtimeRevision.references;
         const runtimeFacts = runtimeEvidenceFacts(context, runtimeEvidence);
         const facts = [...semanticFacts, ...documents.facts, ...extractorFacts, ...routing.facts, ...runtimeFacts].sort((left, right) => left.id.localeCompare(right.id));
+        const validationCounts = { factCount: facts.length };
+        await measureValidationPhase('validate-identities', validationCounts, options.onProgress, () => {
+            const report = assertGraphIdentities(facts, {
+                repositoryId: config.repositoryId, includeDetails: options.validationDetails,
+            });
+            validationCounts.nodeCount = report.nodeCount;
+        });
+        checkpoint();
+        options.onProgress?.({ phase: 'compile-semantic-rdf' });
+        const ontology = await this.dependencies.ontologyCompiler.compile(snapshotId, artifacts, context);
         const invariants = (await Promise.all(this.dependencies.invariantEvaluators.map((evaluator) => evaluator.evaluate(snapshotId, facts)))).flat();
         const failures = invariants.filter((invariant) => invariant.status === 'fail');
         if (failures.length > 0) {
@@ -230,7 +212,9 @@ export class ContextGraphHydrator {
                 scope: selectedSemanticSources,
                 ontologyVersion: config.semantic.ontologyVersion,
                 extractorVersions: {
-                    assembly: 'standalone-graph-v6',
+                    assembly: graphAssemblyIdentity,
+                    [repositoryContractExtractorIdentity.id]: repositoryContractExtractorIdentity.version,
+                    [scipSymbolExtractorIdentity.id]: scipSymbolExtractorIdentity.version,
                     'repository-node-identity': String(repositoryNodeIdentityVersion),
                     [documentLinkerIdentity.id]: documentLinkerIdentity.version,
                     ...(config.routingSources?.length ? { [routingExtractorIdentity.id]: routingExtractorIdentity.version } : {}),
@@ -256,12 +240,13 @@ export class ContextGraphHydrator {
             unresolved,
             diagnostics,
         };
-        options.signal?.throwIfAborted();
-        options.onProgress?.({ phase: 'validate-shacl' });
-        const validation = await new RdfEvidenceGraph(snapshot).validate();
+        checkpoint();
+        const graph = await measureValidationPhase('build-rdf-evidence', validationCounts, options.onProgress, () => new RdfEvidenceGraph(snapshot));
+        const validation = await graph.validate({ onProgress: (event) => options.onProgress?.({ ...event, nodeCount: validationCounts.nodeCount }) });
         if (!validation.conforms) {
             throw new Error(`Graph extraction failed SHACL validation: ${JSON.stringify(validation.issues)}`);
         }
+        checkpoint();
         options.onProgress?.({ phase: 'publish-snapshot' });
         await snapshotStore.write(snapshot);
         await snapshotStore.updateHead(options.headName, snapshotId);

package/dist/application/overlay.d.ts

@@ -3,4 +3,6 @@ import type { GraphSnapshot } from "@weftlet/core";
 import { GitRepository } from "../repository/git.js";
 import { FileSnapshotStore } from "../storage/storage.js";
 /** Conservative code overlay: reindex implementation; invalidate changed prose, never synthesize intent. */
-export declare function buildWorkingOverlay(repository: GitRepository, config: ContextGraphConfig, store: FileSnapshotStore, storageRoot: string, baseSnapshotId: string, agent?: string): Promise<GraphSnapshot>;
+export declare function buildWorkingOverlay(repository: GitRepository, config: ContextGraphConfig, store: FileSnapshotStore, storageRoot: string, baseSnapshotId: string, agent?: string, options?: {
+    readonly validationDetails?: boolean;
+}): Promise<GraphSnapshot>;

package/dist/application/overlay.js

@@ -5,19 +5,21 @@ 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';
+import { assertGraphIdentities } from '../graph/identity-preflight.js';
 const execute = promisify(execFile);
 const implementationExtractors = new Set([
     'repository-file-extractor', 'repository-contract-extractor', 'scip-symbol-extractor',
     routingExtractorIdentity.id,
 ]);
 /** Conservative code overlay: reindex implementation; invalidate changed prose, never synthesize intent. */
-export async function buildWorkingOverlay(repository, config, store, storageRoot, baseSnapshotId, agent = 'default') {
+export async function buildWorkingOverlay(repository, config, store, storageRoot, baseSnapshotId, agent = 'default', options = {}) {
     const base = await store.read(baseSnapshotId);
     if (!base || base.manifest.overlayDigest)
         throw new Error('Overlay requires a committed base snapshot');
@@ -57,7 +59,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));
@@ -115,12 +120,16 @@ export async function buildWorkingOverlay(repository, config, store, storageRoot
         !affected.has(fact.provenance.path) &&
         ![fact.subject, fact.object].some((node) => [...affected].some((path) => node.id === `component:file:${path}` || node.id === `document:${path}` || node.label === path))).map((fact) => ({ ...fact, snapshotId }));
     const allFacts = [...retained, ...extracted.facts].sort((a, b) => a.id.localeCompare(b.id));
+    assertGraphIdentities(allFacts, { repositoryId: config.repositoryId, includeDetails: options.validationDetails });
     const overlay = {
         ...base,
         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 +145,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,32 @@
+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;
+    readonly status?: 'started' | 'completed' | 'failed';
+    readonly factCount?: number;
+    readonly nodeCount?: 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/configuration/config.js

@@ -113,7 +113,7 @@ function validateConfig(value, absolutePath) {
                 requireConfig(auth.apiKeyEnv === undefined || (typeof auth.apiKeyEnv === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(auth.apiKeyEnv)), 'semantic.auth.apiKeyEnv must name an environment variable', absolutePath);
             }
         }
-        for (const [field, max] of [['timeoutMs', 300_000], ['retries', 2], ['maxDocuments', 1000], ['maxSourceBytes', 1_048_576]]) {
+        for (const [field, max] of [['timeoutMs', 600_000], ['retries', 2], ['maxDocuments', 1000], ['maxSourceBytes', 1_048_576]]) {
             const item = value.semantic[field];
             if (item !== undefined)
                 requireConfig(Number.isInteger(item) && Number(item) >= (field === 'retries' ? 0 : 1) && Number(item) <= max, `semantic.${field} exceeds supported bounds`, absolutePath);

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;