@weftlet/toolkit 0.2.1 → 0.4.0

package/README.md

@@ -67,6 +67,77 @@ the archive-byte, snapshot replacement and MCP startup regression suite also pas
 Windows CI. Full native Windows release preparation remains separately unvalidated.
 See the [validation record](docs/VALIDATION.md).
 
+## Preview hydration before model work
+
+`hydrate --plan` requires toolkit **0.3.0 or newer**. Releases through 0.2.1 do not support
+this flag. With a supporting version installed, inspect a project's committed inputs:
+
+```sh
+pnpm exec weftlet hydrate --plan --config /path/to/project/context-graph.config.json --ref HEAD
+pnpm exec weftlet hydrate --plan --json --config /path/to/project/context-graph.config.json --ref HEAD
+```
+
+The human summary and JSON identify the resolved commit, current local configuration, selected
+documents and inclusion reasons, UTF-8 byte sizes, source approval, expected cache reuse and
+extraction counts, budget violations, and working changes excluded from the committed input.
+Selection uses configured repository file/directory paths; `approvedIntentSources` uses its
+separate glob matcher. An explicit empty semantic source list selects no documents, fixing the
+earlier accidental expansion to the whole repository.
+
+Planning reads Git objects and existing artifacts without loading a model provider or repository
+adapter, indexing code, collecting runtime evidence, validating the graph or writing snapshots.
+It does not check credentials or estimate tokens or dollars. Cache hits depend on unchanged
+inputs; corrupt or unreadable entries are reported separately from misses. `--force-semantic`
+shows planned re-extraction without allocating or writing a forced revision.
+
+A plan exits 0 when its source/cache/budget checks are ready. It exits 1 with the full plan when
+errors block those checks or incomplete selection needs review. Missing/no-document selectors
+and existing agent-selection limits are warnings; they do not add a new hydration gate that
+would prevent removing the last document and invalidating its relationships. All selected
+documents remain visible when budgets are exceeded.
+
+Source approval does not approve model assertions. Validation-document labels reflect configured
+evidence roots; selected validation documents still undergo semantic extraction today. Recursive
+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.
+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
+validation incremental, and there is no validation-result cache, Rust engine or GraphDB service.
+Saved queries do not rerun SHACL.
+
+The current shapes use subject/predicate/object values independently of graph names. Validation
+now builds one temporary union graph so repeated property lookups avoid scanning every named
+assertion graph. The same shapes and validator run against that union. The original named dataset,
+assertion records and provenance remain the source for SPARQL, queries and serialization.
+
+In bounded, single-run public experiments, 2,000 facts with unique subject/object nodes took
+31.50 seconds in the original SHACL path, compared with 0.153 seconds to build the union and
+0.467 seconds for SHACL on that union. A 10,000-fact union case used about 1.3 GiB process RSS;
+the extra projection has a memory cost. These measurements do not reproduce the private consumer's
+full generation run or guarantee a production duration. See [ADR 017](docs/ADR-017-shacl-validation-union.md)
+for methodology, parity boundaries and remaining work. To run the bounded public benchmark from
+a development checkout:
+
+```sh
+pnpm build
+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
+validation remain separate T05 work; they do not delay the focused cold-validation release.
+
 ## Development
 
 The development source is organized by responsibility; see
@@ -107,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/agent-context.d.ts

@@ -7,12 +7,14 @@ export interface AgentSemanticScope {
     readonly semanticSources: readonly string[];
     readonly headName: string;
     readonly snapshotSuffix: string;
+    readonly omittedDocuments?: readonly string[];
+    readonly ignoredSearchTerms?: number;
 }
 export declare class AgentSemanticScopeResolver {
     private readonly config;
     private readonly repository;
     constructor(config: ContextGraphConfig, repository: GitRepository);
-    resolve(request: ImpactScanRequest): Promise<AgentSemanticScope>;
+    resolve(request: ImpactScanRequest, ref?: string): Promise<AgentSemanticScope>;
 }
 export declare class PreparedImpactQueryService implements ImpactQueryService {
     private readonly store;

package/dist/application/agent-context.js

@@ -16,13 +16,15 @@ export class AgentSemanticScopeResolver {
         this.config = config;
         this.repository = repository;
     }
-    async resolve(request) {
+    async resolve(request, ref = 'HEAD') {
         const agent = this.config.agentContext;
         if (!agent)
             throw new Error('Agent context preparation is not configured');
-        const commitSha = await this.repository.resolveRef('HEAD');
+        const commitSha = await this.repository.resolveRef(ref);
         const available = new Set((await this.repository.listFilesAt(commitSha, this.config.semanticSources)).filter((path) => /\.(?:md|mdx|txt)$/i.test(path)));
         const selected = new Set();
+        const omitted = new Set();
+        let ignoredSearchTerms = 0;
         for (const path of await this.repository.listFilesAt(commitSha, agent.alwaysSemanticSources)) {
             if (available.has(path))
                 selected.add(path);
@@ -42,6 +44,8 @@ export class AgentSemanticScopeResolver {
                     .filter((path) => available.has(path));
                 for (const path of references.slice(0, agent.maxReferencedDocuments))
                     selected.add(path);
+                for (const path of references.slice(agent.maxReferencedDocuments))
+                    omitted.add(path);
             }
             if (agent.includeMatchingEvidence) {
                 const ownerSlug = basename(ownerDocument).replace(/\.md$/i, '');
@@ -51,16 +55,19 @@ export class AgentSemanticScopeResolver {
             }
         }
         else {
-            const terms = [
+            const requestedTerms = [
                 request.task,
                 ...(request.checklistItems ?? []),
                 ...(request.capabilities ?? []),
             ]
-                .filter((term) => Boolean(term))
-                .slice(0, 8);
-            const matches = await this.repository.findTextAt(commitSha, terms, this.config.semanticSources);
+                .filter((term) => Boolean(term));
+            const terms = requestedTerms.slice(0, 8);
+            ignoredSearchTerms = requestedTerms.length - terms.length;
+            const matches = (await this.repository.findTextAt(commitSha, terms, this.config.semanticSources)).filter((match) => available.has(match.path));
             for (const match of matches.slice(0, agent.maxReferencedDocuments))
                 selected.add(match.path);
+            for (const match of matches.slice(agent.maxReferencedDocuments))
+                omitted.add(match.path);
         }
         const semanticSources = [...selected].sort();
         if (semanticSources.length === 0) {
@@ -72,6 +79,8 @@ export class AgentSemanticScopeResolver {
             semanticSources,
             headName: `agent-${scopeDigest}`,
             snapshotSuffix: `agent-${scopeDigest}`,
+            omittedDocuments: [...omitted].filter((path) => !selected.has(path)).sort(),
+            ignoredSearchTerms,
         };
     }
 }

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

@@ -0,0 +1,54 @@
+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;
+    readonly request?: ImpactScanRequest;
+}
+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;
+    readonly lines: number;
+    readonly selectedBy: readonly string[];
+    readonly role: 'semantic-document' | 'validation-evidence';
+    readonly sourceAuthority: 'declared' | 'inferred';
+    readonly approvedBy: readonly string[];
+    readonly extractionReview: 'unreviewed';
+    readonly cache: Omit<SemanticCacheInspection, 'artifact'>;
+}
+export interface HydrationPlan {
+    readonly schemaVersion: 1;
+    readonly kind: 'hydration-plan';
+    readonly repositoryId: string;
+    readonly ref: string;
+    readonly commitSha: string;
+    readonly configurationDigest: string;
+    readonly ready: boolean;
+    readonly scope: SemanticScope & {
+        readonly complete: boolean;
+    };
+    readonly documents: readonly HydrationPlanDocument[];
+    readonly selections: readonly SemanticSelection[];
+    readonly budgets: {
+        readonly maxDocuments: number;
+        readonly maxSourceBytes: number;
+        readonly selectedDocuments: number;
+        readonly totalSourceBytes: number;
+    };
+    readonly estimates: {
+        readonly reusableArtifacts: number;
+        readonly extractions: number;
+        readonly unknownArtifacts: number;
+    };
+    readonly issues: readonly SemanticInputIssue[];
+    readonly excludedWorkingChanges: readonly string[];
+    readonly assumptions: readonly string[];
+}
+/** Inspect only committed source objects, config and existing artifacts; never initialize a provider or adapter. */
+export declare function planHydration(configPath: string, options?: HydrationPlanOptions): Promise<HydrationPlan>;

package/dist/application/hydration-plan.js

@@ -0,0 +1,71 @@
+import { loadConfig } from '../configuration/config.js';
+import { GitRepository } from '../repository/git.js';
+import { matchesRepositoryGlob } from '../repository/glob.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 { 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, 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 };
+}
+/** 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 resolveSemanticScope(config, repository, commitSha, options.request);
+    const selection = await selectSemanticInputs(repository, commitSha, scope.selectors, config.semantic);
+    const issues = [...selection.issues];
+    const { omittedDocuments, ignoredSearchTerms } = scope;
+    const limited = omittedDocuments.length > 0 || 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 ${omittedDocuments.length} documents and ${ignoredSearchTerms} search terms; this plan describes only the selected scope.`,
+            paths: omittedDocuments });
+    const store = createSemanticArtifactStore(repositoryRoot, config);
+    const evidencePaths = new Set(await repository.listFilesAt(commitSha, config.evidenceRoots));
+    const documents = [];
+    for (const source of selection.sources) {
+        const document = await describeDocument(source, selection.selections, config, evidencePaths, store, options.forceSemantic);
+        const { cache } = document;
+        if (cache.status === 'corrupt' || cache.status === 'unavailable')
+            issues.push({
+                code: `cache-${cache.status}`, severity: 'error', message: cache.reason, paths: [source.path],
+            });
+        documents.push(document);
+    }
+    const count = (...states) => documents.filter((doc) => states.includes(doc.cache.status)).length;
+    return {
+        schemaVersion: 1, kind: 'hydration-plan', repositoryId: config.repositoryId, ref, commitSha,
+        configurationDigest: sha256(stableJson(config)), ready: complete && !issues.some((item) => item.severity === 'error'),
+        scope: { ...scope, complete },
+        documents, selections: selection.selections, budgets: selection.budgets,
+        estimates: { reusableArtifacts: count('hit'), extractions: count('miss', 'forced'), unknownArtifacts: count('corrupt', 'unavailable') },
+        issues, excludedWorkingChanges: await repository.workingChanges(),
+        assumptions: [
+            'Sources come from the resolved commit; configuration and cache are read from the current local environment.',
+            'Estimates require unchanged source, configuration, provider contract and readable artifacts; concurrent changes can invalidate them.',
+            'Document and per-document UTF-8 byte limits apply to all selected documents, including cache hits; no token or monetary estimate is made.',
+            'Ready describes semantic inputs and readable cache only. Providers, credentials, adapters, storage writes, indexing, runtime evidence, routing, ontology and graph validation have not been checked.',
+            'Roles reflect configured evidence roots, not inferred prose meaning. Selected validation documents still undergo semantic extraction today; source approval never approves extracted assertions.',
+            'Selection is the configured scope, optionally narrowed by existing bounded agent selection; recursive SOT traversal and complete product coverage are not claimed.',
+            'Unmatched selectors and bounded scope omissions need review. They do not introduce new hydration gates: removing the last document can still publish a graph with its relationships removed.',
+        ],
+    };
+}

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;