@weftlet/toolkit 0.3.0 → 0.4.0

package/README.md

@@ -101,6 +101,12 @@ evidence roots; selected validation documents still undergo semantic extraction
 SOT traversal and default validation-document separation remain T07 work. See
 [ADR 016](docs/ADR-016-hydration-preview.md) and the [1.0 task list](docs/RELEASE-1.0-PLAN.md).
 
+Starting with **0.4.0**, preview also maps opaque diagnostic source IDs to local paths. Semantic
+failures report completed/remaining work and recovery guidance; `hydrate --json --quiet` emits
+their structured report on stderr. Built-in Codex can reuse completed artifacts after supported
+operational changes such as increasing a timeout. See [provider recovery](docs/PROVIDERS.md#limits-and-reuse)
+for preview, retry and explicit legacy-cache adoption instructions.
+
 ## SHACL validation and performance
 
 Starting with 0.3.0, the toolkit indexes a temporary union to accelerate cold validation.
@@ -172,6 +178,15 @@ For tests excluded by the build config or workspace packages whose outputs are a
 committed archives, configure an [explicit TypeScript source project](docs/ADR-010-committed-source-indexing.md)
 with selected files and local package aliases.
 
+Repository adapters using **0.4.0 or newer** should import `repositoryFileNode` from
+`@weftlet/core` for physical-file nodes. It preserves canonical document IDs, spec/test Evidence
+and production Component kinds, including test files containing mocked calls or decorators.
+Keep business-concept nodes separate; see the [core API example](packages/core/README.md) and
+[producer decision](docs/ADR-020-canonical-physical-file-producers.md). After upgrading, rebuild
+the graph with compatible cached artifacts; historical snapshots remain queryable but cannot
+satisfy current validation with old extraction versions. Consumer-owned adapters must be migrated
+as well; the toolkit cannot correct nodes they still classify independently.
+
 In a selected document such as `docs/intent.md`, link a responsibility to its sources:
 
 ```md

package/dist/application/application.js

@@ -10,11 +10,13 @@ import { OpenCaesarOntologyCompiler, DirectRdfOntologyCompiler } from "../extrac
 import { SnapshotImpactQueryService } from "../graph/query.js";
 import { SemanticHydrator } from "../extraction/semantic.js";
 import { createSemanticExtractor } from "../extraction/providers.js";
-import { SemanticArtifactStore, FileSnapshotStore } from "../storage/storage.js";
+import { FileSnapshotStore } from "../storage/storage.js";
+import { createSemanticArtifactStore } from './semantic-artifact-store.js';
 import { RepositoryContractExtractor, RepositoryFileExtractor, ScipSymbolExtractor, ScipTypeScriptIndexer, } from "../extraction/static.js";
 import { OtlpJsonRuntimeEvidenceProvider } from "../extraction/telemetry.js";
 import { SnapshotChecks } from "./snapshot-checks.js";
 import { resolveConsumerModule } from "../infrastructure/module-resolution.js";
+import { requiredSnapshotExtractorVersions } from './extraction-identity.js';
 const emptyAdapter = {
     factExtractors: [],
     invariantEvaluators: [],
@@ -45,7 +47,7 @@ export async function createContextGraphApplication(configPath) {
     const repository = new GitRepository(repositoryRoot);
     const adapter = await loadContextGraphAdapterModule(config.adapter, repository, repositoryRoot);
     const snapshotStore = new FileSnapshotStore(storageRoot);
-    const artifactStore = new SemanticArtifactStore(storageRoot);
+    const artifactStore = createSemanticArtifactStore(repositoryRoot, config);
     const semanticExtractor = createSemanticExtractor(config.semantic, repositoryRoot);
     const semanticHydrator = new SemanticHydrator(config.semantic, artifactStore, semanticExtractor);
     const staticIndexer = new ScipTypeScriptIndexer(config.scip, storageRoot);
@@ -75,7 +77,8 @@ export async function createContextGraphApplication(configPath) {
     const rawQueryService = scopeResolver
         ? new PreparedImpactQueryService(snapshotStore, hydrator, scopeResolver)
         : new SnapshotImpactQueryService(snapshotStore, headName);
-    const queryService = new SavedEvidenceQueryService(rawQueryService, repository, sha256(stableJson(config)));
+    const expectedExtractors = requiredSnapshotExtractorVersions(config);
+    const queryService = new SavedEvidenceQueryService(rawQueryService, repository, sha256(stableJson(config)), expectedExtractors);
     return {
         ...loaded,
         storageRoot,
@@ -84,7 +87,7 @@ export async function createContextGraphApplication(configPath) {
         ontologyCompiler,
         hydrator,
         queryService,
-        snapshotChecks: new SnapshotChecks(snapshotStore, repository, hydrator, scopeResolver, sha256(stableJson(config))),
+        snapshotChecks: new SnapshotChecks(snapshotStore, repository, hydrator, scopeResolver, sha256(stableJson(config)), expectedExtractors),
         scopeResolver,
         headName,
     };

package/dist/application/cache-adoption.d.ts

@@ -0,0 +1,43 @@
+import type { ImpactScanRequest } from '@weftlet/core';
+import { type SemanticInputIssue, type SemanticSelection } from '../extraction/semantic-sources.js';
+import { type SemanticScope } from './semantic-scope.js';
+export interface SemanticCacheAdoptionOptions {
+    readonly fromConfigPath: string;
+    readonly ref?: string;
+    readonly dryRun?: boolean;
+    readonly request?: ImpactScanRequest;
+}
+export type SemanticCacheAdoptionStatus = 'adopted' | 'reusable' | 'planned' | 'missing' | 'corrupt' | 'unavailable' | 'conflict';
+export interface SemanticCacheAdoptionRecord {
+    readonly path: string;
+    readonly key: string;
+    readonly status: SemanticCacheAdoptionStatus;
+    readonly reason: string;
+}
+export interface SemanticCacheAdoption {
+    readonly schemaVersion: 1;
+    readonly kind: 'semantic-cache-adoption';
+    readonly repositoryId: string;
+    readonly ref: string;
+    readonly commitSha: string;
+    readonly configurationDigest: string;
+    readonly previousConfigurationDigest: string;
+    readonly dryRun: boolean;
+    readonly ready: boolean;
+    readonly scope: SemanticScope & {
+        readonly complete: boolean;
+    };
+    readonly records: readonly SemanticCacheAdoptionRecord[];
+    readonly counts: Readonly<Record<SemanticCacheAdoptionStatus, number>>;
+    readonly selections: readonly SemanticSelection[];
+    readonly budgets: {
+        readonly maxDocuments: number;
+        readonly maxSourceBytes: number;
+        readonly selectedDocuments: number;
+        readonly totalSourceBytes: number;
+    };
+    readonly issues: readonly SemanticInputIssue[];
+    readonly assumptions: readonly string[];
+}
+/** Explicitly adopts only committed-source artifacts from a compatible, named legacy profile. */
+export declare function adoptSemanticCache(configPath: string, options: SemanticCacheAdoptionOptions): Promise<SemanticCacheAdoption>;

package/dist/application/cache-adoption.js

@@ -0,0 +1,129 @@
+import { loadConfig } from '../configuration/config.js';
+import { resolveSemanticStorageRoots, resolveStorageRoot, semanticCachePartition } from '../configuration/cache.js';
+import { inspectSemanticCache } from '../extraction/semantic-cache.js';
+import { semanticProviderIdentity } from '../extraction/semantic-identity.js';
+import { selectSemanticInputs } from '../extraction/semantic-sources.js';
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { GitRepository } from '../repository/git.js';
+import { SemanticArtifactStore } from '../storage/storage.js';
+import { resolveSemanticScope } from './semantic-scope.js';
+const problemStatuses = new Set(['corrupt', 'unavailable', 'conflict']);
+function problem(inspection, source, location) {
+    if (inspection.status !== 'corrupt' && inspection.status !== 'unavailable')
+        return undefined;
+    return { path: source.path, key: inspection.key, status: inspection.status,
+        reason: `${location} cache: ${inspection.reason}` };
+}
+async function inspectCandidate(source, config, identity, previous, current) {
+    const [before, existing] = await Promise.all([
+        inspectSemanticCache(previous, config, source, identity),
+        inspectSemanticCache(current, config, source, identity),
+    ]);
+    const failure = problem(existing, source, 'Current') ?? problem(before, source, 'Previous');
+    if (failure)
+        return { source, record: failure };
+    const base = { path: source.path, key: existing.key };
+    if (existing.status === 'hit') {
+        const conflict = before.status === 'hit' && before.artifact.outputDigest !== existing.artifact.outputDigest;
+        return { source, record: { ...base, status: conflict ? 'conflict' : 'reusable', reason: conflict
+                    ? 'Current and previous caches contain different valid artifacts for this key; neither was overwritten.'
+                    : 'A validated artifact is already available in the current cache.' } };
+    }
+    if (before.status === 'miss')
+        return { source, record: { ...base, status: 'missing',
+                reason: 'The explicit previous profile has no complete artifact for this source and extraction contract.' } };
+    if (before.status !== 'hit' || existing.status !== 'miss')
+        throw new Error('Unexpected cache inspection state');
+    return { source, artifact: before.artifact, record: { ...base, status: 'planned',
+            reason: 'A validated previous artifact can be copied without extraction or changing its provenance.' } };
+}
+async function publishCandidate(candidate, config, identity, current) {
+    let publicationError;
+    let published = false;
+    try {
+        await current.write(candidate.artifact);
+        published = true;
+    }
+    catch (error) {
+        publicationError = error;
+    }
+    // Reinspect even after a successful write: an immutable-key winner can have
+    // matching output but corrupt identity metadata. A digest match alone is not
+    // permission to report that artifact as reusable.
+    const existing = await inspectSemanticCache(current, config, candidate.source, identity);
+    const failure = problem(existing, candidate.source, 'Current');
+    if (failure)
+        return failure;
+    if (existing.status === 'hit' && existing.artifact.outputDigest !== candidate.artifact.outputDigest) {
+        return { ...candidate.record, status: 'conflict',
+            reason: 'A concurrent writer published a different valid artifact; neither artifact was overwritten.' };
+    }
+    if (!published) {
+        throw new Error('Unable to adopt a semantic artifact because storage publication failed.', { cause: publicationError });
+    }
+    if (existing.status !== 'hit')
+        return { ...candidate.record, status: 'unavailable',
+            reason: 'Published artifact is no longer readable; no successful adoption is claimed.' };
+    return { ...candidate.record, status: 'adopted',
+        reason: 'Validated artifact is available in the current cache; the previous artifact is unchanged.' };
+}
+/** Explicitly adopts only committed-source artifacts from a compatible, named legacy profile. */
+export async function adoptSemanticCache(configPath, options) {
+    const [loaded, previous] = await Promise.all([loadConfig(configPath), loadConfig(options.fromConfigPath)]);
+    const { config, repositoryRoot } = loaded;
+    if (repositoryRoot !== previous.repositoryRoot) {
+        throw new Error('Cache adoption requires both configurations to resolve to the same checkout.');
+    }
+    if (semanticCachePartition(repositoryRoot, config) !== semanticCachePartition(repositoryRoot, previous.config)) {
+        throw new Error('Cache adoption requires matching non-operational configuration and provider contracts.');
+    }
+    const repository = new GitRepository(repositoryRoot);
+    const ref = options.ref ?? 'HEAD';
+    const commitSha = await repository.resolveRef(ref);
+    const scope = await resolveSemanticScope(config, repository, commitSha, options.request);
+    const selection = await selectSemanticInputs(repository, commitSha, scope.selectors, config.semantic);
+    const issues = [...selection.issues];
+    const limited = scope.omittedDocuments.length > 0 || scope.ignoredSearchTerms > 0;
+    const complete = !limited && selection.selections.every((item) => item.status === 'matched');
+    if (limited)
+        issues.push({ code: 'selection-limited', severity: 'warning',
+            message: `Existing agent selection limits omitted ${scope.omittedDocuments.length} documents and ${scope.ignoredSearchTerms} search terms; adoption describes only the selected scope.`,
+            paths: scope.omittedDocuments });
+    const dryRun = options.dryRun ?? false;
+    const records = [];
+    if (!issues.some((issue) => issue.severity === 'error')) {
+        const current = new SemanticArtifactStore(resolveSemanticStorageRoots(repositoryRoot, config).primary);
+        // Do not scan sibling profiles or infer ownership from an artifact key. The
+        // supplied old configuration proves the exact legacy location to inspect.
+        const old = new SemanticArtifactStore(resolveStorageRoot(repositoryRoot, previous.config));
+        const identity = semanticProviderIdentity(config.semantic);
+        for (const source of selection.sources) {
+            const candidate = await inspectCandidate(source, config.semantic, identity, old, current);
+            const result = candidate.artifact && !dryRun
+                ? await publishCandidate(candidate, config.semantic, identity, current) : candidate.record;
+            records.push(result);
+            if (problemStatuses.has(result.status))
+                issues.push({ code: `cache-${result.status}`, severity: 'error',
+                    message: result.reason, paths: [result.path] });
+        }
+    }
+    const counts = {
+        adopted: 0, reusable: 0, planned: 0, missing: 0, corrupt: 0, unavailable: 0, conflict: 0,
+    };
+    for (const record of records)
+        counts[record.status]++;
+    return {
+        schemaVersion: 1, kind: 'semantic-cache-adoption', repositoryId: config.repositoryId,
+        ref, commitSha, configurationDigest: sha256(stableJson(config)),
+        previousConfigurationDigest: sha256(stableJson(previous.config)), dryRun,
+        ready: complete && !issues.some((issue) => issue.severity === 'error'), scope: { ...scope, complete },
+        records, counts, selections: selection.selections, budgets: selection.budgets, issues,
+        assumptions: [
+            'Selection uses the same configured or bounded agent scope as hydration planning at the resolved commit; only expected keys in the explicitly named previous profile are inspected.',
+            'Missing or incomplete previous artifacts need later extraction. Corrupt or conflicting complete artifacts are retained for diagnosis.',
+            'Adoption preserves original artifact identity and provenance; it does not validate or publish a current snapshot.',
+            'Artifacts are adopted independently; earlier valid copies remain available if a later artifact or storage operation fails.',
+            'No provider, authentication, indexing, ontology or repository adapter is initialized. Dry runs do not write cache files.',
+        ],
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { ContextGraphConfig } from '../configuration/config.js';
+export declare const graphAssemblyVersion = 7;
+export declare const graphAssemblyIdentity = "standalone-graph-v7";
+/** Runtime expectations are separate from source/configuration identity and artifact reuse. */
+export declare function requiredSnapshotExtractorVersions(config?: Pick<ContextGraphConfig, 'routingSources'>): Readonly<Record<string, string>>;
+export declare function incompatibleSnapshotExtractors(actual: Readonly<Record<string, string>> | undefined, expected: Readonly<Record<string, string>>): readonly string[];

package/dist/application/extraction-identity.js

@@ -0,0 +1,15 @@
+import { repositoryContractExtractorIdentity, scipSymbolExtractorIdentity } from '../extraction/static.js';
+import { routingExtractorIdentity } from '../extraction/routing.js';
+export const graphAssemblyVersion = 7;
+export const graphAssemblyIdentity = `standalone-graph-v${graphAssemblyVersion}`;
+/** Runtime expectations are separate from source/configuration identity and artifact reuse. */
+export function requiredSnapshotExtractorVersions(config) {
+    return { assembly: graphAssemblyIdentity,
+        [repositoryContractExtractorIdentity.id]: repositoryContractExtractorIdentity.version,
+        [scipSymbolExtractorIdentity.id]: scipSymbolExtractorIdentity.version,
+        ...(config?.routingSources?.length ? { [routingExtractorIdentity.id]: routingExtractorIdentity.version } : {}),
+    };
+}
+export function incompatibleSnapshotExtractors(actual, expected) {
+    return Object.keys(expected).filter((id) => actual?.[id] !== expected[id]).sort();
+}

package/dist/application/hydration-failure.d.ts

@@ -0,0 +1,41 @@
+import { SemanticProviderError } from '../extraction/semantic-process.js';
+import { SemanticPolicyError, type SemanticHydrationPhase } from '../extraction/semantic-diagnostics.js';
+export type SemanticFailureCode = SemanticProviderError['code'] | SemanticPolicyError['code'] | 'cache-failure' | 'provider-failure';
+export interface SemanticRunProgress {
+    readonly total: number;
+    readonly completed: number;
+    readonly extracted: number;
+    readonly reused: number;
+    readonly failed: number;
+    readonly cancelled: number;
+    readonly notStarted: number;
+    /** Includes failed, cancelled and not-started sources; it is not an extraction estimate. */
+    readonly remaining: number;
+}
+export interface SemanticHydrationFailure {
+    readonly schemaVersion: 1;
+    readonly kind: 'semantic-hydration-failure';
+    readonly code: SemanticFailureCode;
+    readonly category: 'timeout' | 'cancellation' | 'provider' | 'infrastructure' | 'extraction-gap';
+    readonly phase: SemanticHydrationPhase | 'semantic-scheduling';
+    /** Absent when cancellation occurs between sources, without one failing source. */
+    readonly sourceId?: string;
+    readonly commitSha: string;
+    readonly configurationDigest: string;
+    /** Processing time through failure, including cache checks/retries for a source. */
+    readonly elapsedMs: number;
+    readonly elapsedScope: 'source' | 'semantic-run';
+    readonly timeoutMs: number;
+    readonly timeoutScope: 'provider-attempt' | 'module-execution';
+    readonly progress: SemanticRunProgress;
+    readonly forced: boolean;
+    readonly recovery: readonly string[];
+}
+export declare function semanticFailureCode(error: unknown, phase: SemanticHydrationPhase, signal?: AbortSignal): SemanticFailureCode;
+export declare function semanticFailureCategory(code: SemanticFailureCode): SemanticHydrationFailure['category'];
+/** Public failure envelope deliberately excludes raw errors, causes and provider output. */
+export declare class SemanticHydrationError extends Error {
+    readonly report: SemanticHydrationFailure;
+    readonly code: SemanticFailureCode;
+    constructor(report: SemanticHydrationFailure);
+}

package/dist/application/hydration-failure.js

@@ -0,0 +1,43 @@
+import { SemanticProviderError } from '../extraction/semantic-process.js';
+import { SemanticPolicyError } from '../extraction/semantic-diagnostics.js';
+export function semanticFailureCode(error, phase, signal) {
+    if (signal?.aborted && (error === signal.reason ||
+        (error instanceof Error && error.name === 'AbortError') ||
+        (phase === 'semantic-extract' && !(error instanceof SemanticProviderError))))
+        return 'cancelled';
+    if (error instanceof SemanticProviderError &&
+        ['timeout', 'cancelled', 'unavailable', 'exit', 'invalid-output'].includes(error.code))
+        return error.code;
+    if (error instanceof SemanticPolicyError && ['unresolved', 'low-confidence'].includes(error.code))
+        return error.code;
+    if (phase === 'semantic-cache-read' || phase === 'semantic-cache-write')
+        return 'cache-failure';
+    return phase === 'semantic-validate' ? 'invalid-output' : 'provider-failure';
+}
+export function semanticFailureCategory(code) {
+    if (code === 'timeout')
+        return 'timeout';
+    if (code === 'cancelled')
+        return 'cancellation';
+    if (code === 'unavailable' || code === 'cache-failure')
+        return 'infrastructure';
+    if (code === 'invalid-output' || code === 'unresolved' || code === 'low-confidence')
+        return 'extraction-gap';
+    return 'provider';
+}
+/** Public failure envelope deliberately excludes raw errors, causes and provider output. */
+export class SemanticHydrationError extends Error {
+    report;
+    code;
+    constructor(report) {
+        const p = report.progress;
+        super(`Semantic hydration ${report.code}: ${report.sourceId ?? 'between semantic sources'}; phase ${report.phase}; ` +
+            `${report.elapsedScope} elapsed ${report.elapsedMs} ms; configured ${report.timeoutScope} timeout ${report.timeoutMs} ms. ` +
+            `${p.completed}/${p.total} completed (${p.extracted} extracted, ${p.reused} reused); ` +
+            `${p.remaining} remaining (${p.failed} failed, ${p.cancelled} cancelled, ${p.notStarted} not started).\n` +
+            report.recovery.join('\n'));
+        this.report = report;
+        this.name = 'SemanticHydrationError';
+        this.code = report.code;
+    }
+}

package/dist/application/hydration-plan.d.ts

@@ -1,6 +1,7 @@
 import type { ImpactScanRequest } from '@weftlet/core';
 import { type SemanticCacheInspection } from '../extraction/semantic-cache.js';
 import { type SemanticInputIssue, type SemanticSelection } from '../extraction/semantic-sources.js';
+import { type SemanticScope } from './semantic-scope.js';
 export interface HydrationPlanOptions {
     readonly ref?: string;
     readonly forceSemantic?: boolean;
@@ -8,6 +9,8 @@ export interface HydrationPlanOptions {
 }
 export interface HydrationPlanDocument {
     readonly path: string;
+    /** Local mapping for opaque IDs in semantic progress and failure reports. */
+    readonly sourceId: string;
     readonly stableSemanticId: string;
     readonly sourceDigest: string;
     readonly bytes: number;
@@ -27,14 +30,8 @@ export interface HydrationPlan {
     readonly commitSha: string;
     readonly configurationDigest: string;
     readonly ready: boolean;
-    readonly scope: {
-        readonly mode: 'configured' | 'agent';
-        readonly selectors: readonly string[];
-        readonly digest: string;
-        readonly headName: string;
+    readonly scope: SemanticScope & {
         readonly complete: boolean;
-        readonly omittedDocuments: readonly string[];
-        readonly ignoredSearchTerms: number;
     };
     readonly documents: readonly HydrationPlanDocument[];
     readonly selections: readonly SemanticSelection[];

package/dist/application/hydration-plan.js

@@ -1,42 +1,34 @@
 import { loadConfig } from '../configuration/config.js';
-import { resolveStorageRoot } from '../configuration/cache.js';
 import { GitRepository } from '../repository/git.js';
 import { matchesRepositoryGlob } from '../repository/glob.js';
-import { SemanticArtifactStore } from '../storage/storage.js';
+import { createSemanticArtifactStore } from './semantic-artifact-store.js';
 import { inspectSemanticCache } from '../extraction/semantic-cache.js';
 import { semanticProviderIdentity } from '../extraction/semantic-identity.js';
 import { selectSemanticInputs } from '../extraction/semantic-sources.js';
 import { sha256, stableJson } from '../infrastructure/util.js';
-import { AgentSemanticScopeResolver } from './agent-context.js';
+import { resolveSemanticScope } from './semantic-scope.js';
+import { semanticSourceId } from '../extraction/semantic-diagnostics.js';
 async function describeDocument(source, selections, config, evidencePaths, store, forceSemantic = false) {
     const inspection = forceSemantic
         ? { status: 'forced', reason: 'Explicit force bypasses existing artifacts; a new revision is allocated only during hydration.' }
         : await inspectSemanticCache(store, config.semantic, source, semanticProviderIdentity(config.semantic));
     const { artifact: _artifact, ...cache } = inspection;
     const approvedBy = (config.approvedIntentSources ?? []).filter((pattern) => matchesRepositoryGlob(source.path, pattern));
-    return { path: source.path, stableSemanticId: source.stableSemanticId, sourceDigest: source.digest,
+    return { path: source.path, sourceId: semanticSourceId(config.repositoryId, source),
+        stableSemanticId: source.stableSemanticId, sourceDigest: source.digest,
         bytes: Buffer.byteLength(source.content), lines: source.content.split('\n').length,
         selectedBy: selections.filter((item) => item.paths.includes(source.path)).map((item) => item.selector),
         role: evidencePaths.has(source.path) ? 'validation-evidence' : 'semantic-document',
         sourceAuthority: approvedBy.length ? 'declared' : 'inferred', approvedBy,
         extractionReview: 'unreviewed', cache };
 }
-async function resolvePlanningScope(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 };
-}
 /** Inspect only committed source objects, config and existing artifacts; never initialize a provider or adapter. */
 export async function planHydration(configPath, options = {}) {
     const { config, repositoryRoot } = await loadConfig(configPath);
     const repository = new GitRepository(repositoryRoot);
     const ref = options.ref ?? 'HEAD';
     const commitSha = await repository.resolveRef(ref);
-    const scope = await resolvePlanningScope(config, repository, commitSha, options.request);
+    const scope = await resolveSemanticScope(config, repository, commitSha, options.request);
     const selection = await selectSemanticInputs(repository, commitSha, scope.selectors, config.semantic);
     const issues = [...selection.issues];
     const { omittedDocuments, ignoredSearchTerms } = scope;
@@ -46,7 +38,7 @@ export async function planHydration(configPath, options = {}) {
         issues.push({ code: 'selection-limited', severity: 'warning',
             message: `Existing agent selection limits omitted ${omittedDocuments.length} documents and ${ignoredSearchTerms} search terms; this plan describes only the selected scope.`,
             paths: omittedDocuments });
-    const store = new SemanticArtifactStore(resolveStorageRoot(repositoryRoot, config));
+    const store = createSemanticArtifactStore(repositoryRoot, config);
     const evidencePaths = new Set(await repository.listFilesAt(commitSha, config.evidenceRoots));
     const documents = [];
     for (const source of selection.sources) {

package/dist/application/hydrator.d.ts

@@ -4,13 +4,11 @@ import type { GitRepository } from "../repository/git.js";
 import type { OntologyCompiler } from "../extraction/ontology.js";
 import type { SemanticHydrator } from "../extraction/semantic.js";
 import type { ScipIndexResult, StaticIndexer } from "../extraction/static.js";
+import { type HydrationProgressEvent } from './semantic-run.js';
+export type { HydrationProgressEvent } from './semantic-run.js';
 export interface HydrationOptions {
     readonly signal?: AbortSignal;
-    readonly onProgress?: (event: {
-        phase: string;
-        completed?: number;
-        total?: number;
-    }) => void;
+    readonly onProgress?: (event: HydrationProgressEvent) => void;
     readonly ref: string;
     readonly headName: string;
     readonly forceSemantic?: boolean;

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,9 @@ 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';
 export class ContextGraphHydrator {
     dependencies;
     constructor(dependencies) {
@@ -57,7 +39,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 +85,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 +105,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 +135,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,7 +156,7 @@ 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();
+        checkpoint();
         options.onProgress?.({ phase: 'compile-semantic-rdf' });
         const ontology = await this.dependencies.ontologyCompiler.compile(snapshotId, artifacts, context);
         const runtimeEvidence = runtimeRevision.references;
@@ -230,7 +202,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 +230,13 @@ export class ContextGraphHydrator {
             unresolved,
             diagnostics,
         };
-        options.signal?.throwIfAborted();
+        checkpoint();
         options.onProgress?.({ phase: 'validate-shacl' });
         const validation = await new RdfEvidenceGraph(snapshot).validate();
         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);