@weftlet/toolkit 0.3.0 → 0.5.0

package/README.md

@@ -101,8 +101,24 @@ 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.5.0**, identity preflight runs before ontology/RDF work.
+`hydrate --json --quiet` reports conflicts using opaque references; `--validation-details` explicitly
+includes local identities, producer versions and citations. Validation emits phase-boundary times
+and graph counts, without a percentage or live heartbeat. Full SHACL remains required after a
+passing preflight. See [ADR 021](docs/ADR-021-identity-preflight-and-validation-timing.md).
+
+Version 0.5.0 also accepts `semantic.timeoutMs: 600000` for an approved ten-minute extraction
+attempt; the default remains two minutes. See [provider limits and reuse](docs/PROVIDERS.md#limits-and-reuse)
+before retrying with compatible cached artifacts.
+
 Starting with 0.3.0, the toolkit indexes a temporary union to accelerate cold validation.
 The toolkit uses JavaScript `rdf-validate-shacl` and an in-memory
 N3 store. Each hydration validates the complete graph; semantic artifact reuse does not make
@@ -129,7 +145,7 @@ pnpm benchmark:shacl
 
 Current hydration progress reports phase boundaries. The validator performs synchronous work,
 so an ordinary timer cannot provide an honest heartbeat while that work blocks Node's main
-thread. Worker-based progress, early identity checks, validation-result reuse and incremental
+thread. Worker-based progress, validation-result reuse and incremental
 validation remain separate T05 work; they do not delay the focused cold-validation release.
 
 ## Development
@@ -172,6 +188,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,18 +4,18 @@ 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;
     readonly snapshotSuffix?: string;
     readonly requireClean?: boolean;
+    /** Explicit local diagnostics may disclose repository identities, producers and citations. */
+    readonly validationDetails?: boolean;
     readonly semanticSources?: readonly string[];
     readonly runtimeEvidenceRevision?: RuntimeEvidenceRevision;
 }