@weftlet/toolkit 0.3.0 → 0.4.0

package/dist/extraction/semantic.js

@@ -11,6 +11,7 @@ import { sha256, stableJson } from "../infrastructure/util.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();
@@ -334,14 +335,32 @@ export class SemanticHydrator {
         this.extractor = extractor;
     }
     async hydrate(source, context, forceRevision, options = {}) {
-        options.signal?.throwIfAborted();
+        const checkpoint = () => {
+            if (options.signal?.aborted)
+                throw new SemanticProviderError('cancelled', 'Semantic extraction cancelled');
+        };
+        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')
-            return { artifact: cached.artifact, reused: true };
+        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);
-        const extraction = await this.extractor.extract(source, context, options);
+        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');
@@ -351,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,
@@ -398,7 +417,7 @@ 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 = semanticArtifactOutputDigest({ facts, diagnostics, oml: compiledOml, rawModelOutput: extraction.rawModelOutput });
@@ -425,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/index.d.ts

@@ -10,3 +10,6 @@ export * from "./application/overlay.js";
 export * from "./graph/rdf.js";
 export * from "./extraction/providers.js";
 export * from './application/hydration-plan.js';
+export * from './application/cache-adoption.js';
+export * from './application/hydration-failure.js';
+export * from './extraction/semantic-diagnostics.js';

package/dist/index.js

@@ -11,3 +11,6 @@ export * from "./application/overlay.js";
 export * from "./graph/rdf.js";
 export * from "./extraction/providers.js";
 export * from './application/hydration-plan.js';
+export * from './application/cache-adoption.js';
+export * from './application/hydration-failure.js';
+export * from './extraction/semantic-diagnostics.js';

package/dist/interfaces/cli.js

@@ -16,6 +16,8 @@ import { diagnoseSetup } from "./doctor.js";
 import { runInit } from "./init.js";
 import { loadConfig } from "../configuration/config.js";
 import { planHydration } from '../application/hydration-plan.js';
+import { adoptSemanticCache } from '../application/cache-adoption.js';
+import { SemanticHydrationError } from '../application/hydration-failure.js';
 function valueAfter(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
@@ -59,7 +61,7 @@ function formatHydrationPlan(plan) {
         `Source/cache/budget checks: ${readiness}`,
     ];
     for (const document of plan.documents) {
-        lines.push(`- ${JSON.stringify(document.path)}: ${document.bytes} bytes, ${document.lines} lines; ${document.role}; source ${document.sourceAuthority}, extraction ${document.extractionReview}; cache ${document.cache.status}; selected by ${document.selectedBy.map((selector) => JSON.stringify(selector)).join(', ')}`);
+        lines.push(`- ${JSON.stringify(document.path)} [${document.sourceId}]: ${document.bytes} bytes, ${document.lines} lines; ${document.role}; source ${document.sourceAuthority}, extraction ${document.extractionReview}; cache ${document.cache.status}; selected by ${document.selectedBy.map((selector) => JSON.stringify(selector)).join(', ')}`);
     }
     for (const selection of plan.selections.filter((item) => item.status !== 'matched')) {
         lines.push(`Selection ${JSON.stringify(selection.selector)}: ${selection.status}`);
@@ -80,7 +82,7 @@ function formatHydrationPlan(plan) {
 async function main() {
     const args = process.argv.slice(2);
     if (args.includes('--help') || !args.length) {
-        process.stdout.write('weftlet init|config show|config validate|doctor|hydrate|overlay|impact scan|sparql|validate|govern|visualize|diagnostics show|invariant check|clean-compare|ontology compile\nUse --config <file>; queries accept --snapshot <id>. impact scan accepts --changed-file, --capability, --max-facts, --max-depth, --continuation.\nhydrate --plan [--json] [--ref <commit>] [--force-semantic] previews scope, cache and budgets without model calls or graph writes. Preview readiness is advisory and does not add a hydration gate.\ninit [--yes] [--directory <project>] [--config <file>] [--repository-id <id>] [--code-root <path>] [--semantic-source <path>] [--evidence-root <path>] [--model <name>] [--no-gitignore]\nSource flags may be repeated. init never overwrites an existing config. See README.md for examples.\n');
+        process.stdout.write('weftlet init|config show|config validate|doctor|hydrate|cache adopt|overlay|impact scan|sparql|validate|govern|visualize|diagnostics show|invariant check|clean-compare|ontology compile\nUse --config <file>; queries accept --snapshot <id>. impact scan accepts --changed-file, --capability, --max-facts, --max-depth, --continuation.\nhydrate --plan [--json] [--ref <commit>] [--force-semantic] previews scope, cache and budgets without model calls or graph writes. Preview readiness is advisory and does not add a hydration gate.\nhydrate --json --quiet emits structured semantic failures on stderr with no progress lines; failure stdout stays empty. hydrate --plan maps opaque source IDs to local document paths.\ncache adopt --from-config <previous.json> [--config <current.json>] [--ref <commit>] [--dry-run] returns JSON and copies only validated compatible artifacts, without model calls or snapshot writes. --dry-run performs no cache writes. Agent configurations accept the same --owner-doc, --task and --capability selection as hydrate.\ninit [--yes] [--directory <project>] [--config <file>] [--repository-id <id>] [--code-root <path>] [--semantic-source <path>] [--evidence-root <path>] [--model <name>] [--no-gitignore]\nSource flags may be repeated. init never overwrites an existing config. See README.md for examples.\n');
         return;
     }
     if (args[0] === 'init') {
@@ -113,6 +115,20 @@ async function main() {
         return;
     }
     const configPath = valueAfter(args, '--config') ?? defaultConfigPath();
+    if (args[0] === 'cache') {
+        const fromConfigPath = valueAfter(args, '--from-config');
+        if (args[1] !== 'adopt' || !fromConfigPath || fromConfigPath.startsWith('--')) {
+            throw new Error('Usage: weftlet cache adopt --from-config <previous.json> [--config <current.json>] [--ref <commit>] [--dry-run]');
+        }
+        const result = await adoptSemanticCache(configPath, {
+            fromConfigPath, ref: valueAfter(args, '--ref') ?? 'HEAD', dryRun: args.includes('--dry-run'),
+            request: impactRequestFromArgs(args),
+        });
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        if (!result.ready)
+            process.exitCode = 1;
+        return;
+    }
     if (args[0] === 'doctor') {
         process.stdout.write(`${JSON.stringify(await diagnoseSetup(configPath), null, 2)}\n`);
         return;
@@ -163,24 +179,29 @@ async function main() {
         const controller = new AbortController();
         const cancel = () => controller.abort();
         process.once('SIGINT', cancel);
-        const ref = valueAfter(args, '--ref') ?? 'HEAD';
-        const scope = await application.scopeResolver?.resolve(impactRequestFromArgs(args), ref);
-        const result = await application.hydrator.hydrate({
-            ref: scope?.commitSha ?? ref,
-            headName: scope?.headName ?? application.headName,
-            semanticSources: scope?.semanticSources,
-            forceSemantic: args.includes('--force-semantic'),
-            signal: controller.signal,
-            onProgress: args.includes('--quiet') ? undefined : (event) => process.stderr.write(`[context-graph] ${event.phase}${event.total === undefined ? '' : ` ${event.completed}/${event.total}`}\n`),
-        });
-        process.removeListener('SIGINT', cancel);
-        process.stdout.write(`${JSON.stringify({
-            snapshotId: result.snapshot.manifest.snapshotId,
-            commitSha: result.snapshot.manifest.commitSha,
-            contentDigest: result.snapshot.manifest.contentDigest,
-            semanticExtracted: result.semanticExtracted,
-            semanticReused: result.semanticReused,
-        }, null, 2)}\n`);
+        try {
+            const ref = valueAfter(args, '--ref') ?? 'HEAD';
+            const scope = await application.scopeResolver?.resolve(impactRequestFromArgs(args), ref);
+            const result = await application.hydrator.hydrate({
+                ref: scope?.commitSha ?? ref,
+                headName: scope?.headName ?? application.headName,
+                semanticSources: scope?.semanticSources,
+                forceSemantic: args.includes('--force-semantic'),
+                signal: controller.signal,
+                onProgress: args.includes('--quiet') ? undefined : (event) => process.stderr.write(`[context-graph] ${event.phase}${event.total === undefined ? '' : ` ${event.completed}/${event.total}`}` +
+                    `${event.sourceId === undefined ? '' : ` ${event.sourceId}`}${event.elapsedMs === undefined ? '' : ` ${event.elapsedMs} ms`}\n`),
+            });
+            process.stdout.write(`${JSON.stringify({
+                snapshotId: result.snapshot.manifest.snapshotId,
+                commitSha: result.snapshot.manifest.commitSha,
+                contentDigest: result.snapshot.manifest.contentDigest,
+                semanticExtracted: result.semanticExtracted,
+                semanticReused: result.semanticReused,
+            }, null, 2)}\n`);
+        }
+        finally {
+            process.removeListener('SIGINT', cancel);
+        }
         return;
     }
     if (command === 'clean-compare') {
@@ -236,6 +257,8 @@ async function main() {
     throw new Error('Usage: weftlet hydrate|clean-compare|impact scan|diagnostics show --snapshot <id>|invariant check|ontology compile|visualize --output <file.html|file.dot|file.svg>');
 }
 main().catch((error) => {
-    process.stderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    process.stderr.write(`${error instanceof SemanticHydrationError
+        ? process.argv.includes('--json') ? JSON.stringify(error.report, null, 2) : error.message
+        : error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
     process.exitCode = 1;
 });

package/dist/storage/storage.d.ts

@@ -9,7 +9,13 @@ export declare class FileSnapshotStore implements SnapshotStore {
 }
 export declare class SemanticArtifactStore {
     private readonly root;
-    constructor(root: string);
+    private readonly legacyRoots;
+    constructor(root: string, legacyRoots?: readonly string[]);
     read(key: string): Promise<SemanticArtifact | undefined>;
+    /** Only explicitly supplied roots are consulted; never enumerate other consumers' profiles. */
+    readEntry(key: string): Promise<{
+        artifact: SemanticArtifact;
+        origin: 'primary' | 'legacy';
+    } | undefined>;
     write(artifact: SemanticArtifact): Promise<void>;
 }

package/dist/storage/storage.js

@@ -87,11 +87,23 @@ export class FileSnapshotStore {
 }
 export class SemanticArtifactStore {
     root;
-    constructor(root) {
+    legacyRoots;
+    constructor(root, legacyRoots = []) {
         this.root = root;
+        this.legacyRoots = legacyRoots;
+    }
+    async read(key) {
+        return (await this.readEntry(key))?.artifact;
     }
-    read(key) {
-        return readJson(join(this.root, 'artifacts', 'semantic', `${safeKey(key)}.json`));
+    /** Only explicitly supplied roots are consulted; never enumerate other consumers' profiles. */
+    async readEntry(key) {
+        const filename = `${safeKey(key)}.json`;
+        for (const [index, root] of [this.root, ...this.legacyRoots].entries()) {
+            const artifact = await readJson(join(root, 'artifacts', 'semantic', filename));
+            if (artifact !== undefined)
+                return { artifact, origin: index === 0 ? 'primary' : 'legacy' };
+        }
+        return undefined;
     }
     async write(artifact) {
         const path = join(this.root, 'artifacts', 'semantic', `${safeKey(artifact.key)}.json`);

package/dist/visualization/visualization.js

@@ -394,6 +394,7 @@ export function renderContextPackHtml(pack, sourceUrlTemplate) {
     <strong>${pack.snapshot.overlayDigest ? 'DRAFT overlay' : pack.evidenceState?.stale ? 'HISTORICAL evidence' : pack.evidenceState ? 'Saved evidence at current commit' : 'Saved evidence — current checkout not assessed'}</strong>
     <p>Configuration: ${escapeXml(pack.snapshot.configurationDigest ?? 'unknown')}; ${pack.evidenceState ? (pack.evidenceState.configurationMatches ? 'matches current configuration' : 'configuration mismatch') : 'configuration match unknown'}.
     Scope: ${escapeXml(pack.snapshot.scope?.join(', ') ?? 'unknown')}.
+    Extraction compatibility: ${pack.evidenceState?.extractionCompatible === undefined ? 'not assessed' : pack.evidenceState.extractionCompatible ? 'current' : `refresh required (${escapeXml(pack.evidenceState.incompatibleExtractors?.join(', ') ?? 'unknown versions')})`}.
     Excluded working paths: ${pack.evidenceState?.excludedWorkingChanges.length ?? 'unknown'}.
     ${pack.snapshot.overlayDigest ? `Overlay freshness: ${escapeXml(pack.evidenceState?.overlayFreshness ?? 'unknown')}.` : ''}
     This view does not validate the current diff.</p>

package/docs/ADR-016-hydration-preview.md

@@ -1,6 +1,6 @@
 # ADR-016: Read-only hydration planning
 
-Status: accepted and implemented for the 0.3.0 release plan; absent from 0.2.1.
+Status: accepted and implemented in 0.3.0; absent from 0.2.1.
 See [validation](VALIDATION.md) for recorded publication evidence.
 
 ## Problem

package/docs/ADR-017-shacl-validation-union.md

@@ -1,6 +1,6 @@
 # ADR-017: Validate a temporary RDF union without changing canonical evidence
 
-Status: accepted and implemented for the focused 0.3.0 release plan; absent from 0.2.1.
+Status: accepted and implemented in the focused 0.3.0 release; absent from 0.2.1.
 See [validation](VALIDATION.md) for checks and recorded publication evidence.
 
 ## Problem and measured mechanism

package/docs/ADR-018-operational-semantic-cache.md

@@ -0,0 +1,100 @@
+# ADR-018: Preserve Codex artifacts across operational configuration changes
+
+Status: accepted and implemented in development source after 0.3.0; release evidence is recorded
+in [validation](VALIDATION.md). This increment does not claim a new npm publication.
+
+## Problem
+
+With `storageScope: "user"`, the storage profile includes the entire configuration and checkout
+path. Increasing a timeout therefore selected a different directory even though the built-in
+Codex artifact key already excluded that timeout. A partially completed run could lose access
+to reusable work without any source or extraction-contract change.
+
+Custom provider modules present a different boundary: they receive the entire semantic
+configuration and may use it to affect their output. Their identities must remain conservative.
+
+## Decision
+
+Keep `resolveStorageRoot`, snapshot profiles, snapshot IDs and full configuration digests unchanged.
+For built-in Codex with user storage, use a separate semantic-artifact partition. Its identity
+includes the resolved checkout and full configuration except these five semantic controls:
+
+| Setting | Why it can share successful Codex artifacts |
+| --- | --- |
+| `timeoutMs` | Bounds execution; it does not change the prompt or model arguments |
+| `retries` | Limits retries of supported transient failures |
+| `concurrency` | Schedules independent source extractions |
+| `maxDocuments` | Bounds the selected workload |
+| `maxSourceBytes` | Bounds each source; it never truncates its contents |
+
+Document and byte limits still apply before hydration, including when every artifact is cached.
+Changing a limit does not waive it. Model/reasoning settings, prompt/schema/extractor/adapter/
+ontology identities, confidence/unresolved policy, authentication descriptors, source identity
+and bytes continue to invalidate reuse through their existing artifact keys and/or partition.
+Unknown configuration fields remain identity inputs. Credential environment values are not read
+or added to the cache partition.
+
+The new user-cache layout is `~/.cache/context-graph/semantic-artifacts-v1/<partition>/artifacts/semantic/`.
+The partition uses a full SHA-256 digest. Different checkouts, repository IDs, namespaces and
+non-operational configurations remain separate. Workspace storage retains its existing paths
+and behavior; it already allowed built-in Codex reuse after these operational changes. Modules
+retain their full semantic-config identity and their existing storage profiles. Sharing a custom
+workspace storage directory remains an explicit operator choice, not a new global cache feature.
+
+Artifact keys and output digests retain the 0.2.1/0.3.0 contract, including the repository-document
+identity policy introduced in 0.2.1. No incompatible 0.2.0 artifact is reinterpreted as current.
+Source approval and assertion review remain distinct; this change never approves an assertion.
+
+## Legacy recovery without model work
+
+The planner and hydrator use the same store factory. It may read the exact legacy user profile
+derived from the current full configuration after checking the new primary store. A corrupt or
+unreadable primary entry stops reuse; a valid legacy entry does not mask it. Planning remains
+read-only. Hydration can atomically retain a validated legacy artifact in the new partition, then
+revalidate the retained entry to handle concurrent winners. Original files, artifact identities,
+source provenance and raw provider output remain intact.
+
+Legacy profile directories contain no reliable checkout/configuration ownership manifest, and an
+interrupted run may have no snapshot. Consequently, the toolkit never scans sibling profiles for
+a matching key. If settings were already changed, the old location cannot safely be inferred.
+
+The explicit `cache adopt --from-config <previous.json>` command handles that case without
+providers, authentication probes, indexing, ontology compilation, adapters or snapshot writes.
+Both configurations must resolve to the same checkout and have the same non-operational
+partition identity. Keep the exact old configuration in its original configuration directory.
+Relocation is safe only when its original, unchanged `repositoryRoot` still resolves to the same
+checkout (for example, an absolute root). Do not edit that field to compensate for relocation:
+it is part of the old profile identity. Preserve the original field values and omissions.
+
+Adoption resolves a committed ref and uses the same configured/agent selection as the hydration
+preview. It looks up only expected keys in the exact old profile, checks the complete artifact
+contract and output digest, and copies valid candidates atomically. `--dry-run` performs no writes.
+Reports identify reused/adopted/planned/missing/corrupt/unavailable/conflicting entries, configured
+budgets and scope omissions. They omit source bodies, raw provider output and configuration values.
+
+Recovery is per artifact: valid copies can complete even if another entry is corrupt or conflicts.
+The report records partial progress and exits unsuccessfully for problems or incomplete scope.
+Missing artifacts are ordinary future extraction work. Corrupt complete artifacts are retained
+for diagnosis; they require an explicit forced refresh or operator repair, not automatic overwrite.
+Incomplete temporary files are not published artifacts and do not satisfy a cache lookup.
+
+Concurrent writers use immutable publication. Different outputs under one key are reported as
+conflicts; a matching `outputDigest` field alone is insufficient to accept malformed metadata.
+Explicit forced extraction still creates a separate revision and preserves existing artifacts.
+
+## Freshness and limits
+
+Semantic reuse does not reuse a snapshot's validation result, skip SCIP or SHACL, or let old
+configuration evidence satisfy current validation. A timeout change still changes the snapshot's
+full configuration digest and user storage profile. Saved evidence remains available under its
+original configuration; this increment does not consolidate historical snapshot directories.
+
+The current module-provider contract does not promise operational independence. Supporting that
+requires a separate tested contract, not silently dropping fields from a provider's identity.
+Credential rotation under an unchanged environment-variable name is not detected by this cache;
+credentials are neither cache contents nor cache-identity inputs. Existing filesystem access
+controls and the configured storage location remain the security boundary.
+
+Validation uses public fixtures, deterministic Codex runners and installed TypeScript indexing.
+Live semantic quality and private consumer acceptance remain separate. See the
+[1.0 plan](RELEASE-1.0-PLAN.md) for timeout diagnostics and document coverage follow-ups.