@weftlet/toolkit 0.3.0 → 0.5.0

package/dist/graph/validation-progress.js

@@ -0,0 +1,18 @@
+/** Phase boundaries remain observable even when an operation blocks same-thread timers. */
+export async function measureValidationPhase(phase, counts, onProgress, operation) {
+    const started = performance.now();
+    const emit = (status) => onProgress?.({
+        phase, status, ...counts, elapsedMs: Math.max(0, Math.round(performance.now() - started)),
+    });
+    emit('started');
+    let result;
+    try {
+        result = await operation();
+    }
+    catch (error) {
+        emit('failed');
+        throw error;
+    }
+    emit('completed');
+    return result;
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/interfaces/cli.js

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

package/dist/storage/storage.d.ts

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

package/dist/storage/storage.js

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

package/dist/visualization/visualization.js

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

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

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

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

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

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

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

package/docs/ADR-019-semantic-failure-diagnostics.md

@@ -0,0 +1,82 @@
+# ADR-019: Safe semantic failure diagnostics and settled progress
+
+Status: shipped in 0.4.0; validation and publication are recorded in [validation](VALIDATION.md).
+This decision does not change extraction identity.
+
+## Problem
+
+A generic timeout does not identify which source failed, how much work survived, or how to
+resume. Concurrent workers can also cancel each other: reporting the last error can hide the
+initiating timeout, and reporting before active writes finish can undercount retained artifacts.
+Arbitrary provider exceptions and abort reasons may contain private input.
+
+## Decision
+
+Keep semantic-run scheduling and reporting in `application/semantic-run.ts`, separate from graph
+assembly. Record the first source failure before aborting siblings, stop scheduling queued sources,
+and wait for active workers to settle before constructing `SemanticHydrationError.report`.
+The report has a versioned kind, safe code/category, phase, committed SHA, configuration digest,
+elapsed time and scope, effective timeout and its scope, final counts, and recovery guidance.
+
+Completion means a validated artifact was retained or successfully reused. A write already in
+progress can finish after cancellation and remains a completion. A provider result returned after
+abort is rejected before validation/publication. Late storage failures remain failures, not sibling
+cancellations. Cancellation between sources has phase `semantic-scheduling`, no failing source ID,
+and run elapsed time; it does not relabel successfully retained artifacts as cancelled.
+
+Counts have these meanings:
+
+- `completed = extracted + reused`.
+- `total = completed + failed + cancelled + notStarted` after active workers settle.
+- `remaining = total - completed`; this includes failures, cancellations and queued work. It is
+  not a promise about the number of model calls required by a future run.
+
+Known provider timeouts, cancellations, unavailable infrastructure, process exits and invalid
+output remain distinct. Configured unresolved-mapping and confidence rejections retain separate
+`unresolved` and `low-confidence` codes and remain extraction gaps. Their acceptance criteria are
+unchanged. Unknown extraction exceptions become `provider-failure`, without an
+invented diagnosis. Cache read/write failures have a separate code; invalid extraction validation
+is an extraction gap. Module loading/export/identity problems are unavailable infrastructure.
+No raw exception, cause, provider output, prompt, credential or source path is copied into the
+report. These diagnostics are not approved intent or evidence that a product rule was violated.
+
+The CLI prints safe errors and progress on stderr, leaving stdout for successful results.
+`hydrate --json --quiet` produces a JSON semantic failure report on stderr. The JSON contract
+covers the semantic-source run; configuration, repository, indexing and graph validation errors
+retain their existing interfaces. SIGINT listeners are removed on both success and failure.
+The saved-evidence MCP interface still performs no hydration and writes only protocol messages
+to stdout. Trusted module code must itself avoid logging private inputs; this is not a sandbox.
+
+## Source correlation and timeout meaning
+
+A domain-separated SHA-256 of repository ID and stable semantic ID gives each source an opaque
+`sourceId`. `hydrate --plan` explicitly maps that ID to its local path. The ID is stable across
+retries and source edits when the stable semantic ID stays the same; renames without a declared
+stable ID may change it. It is a correlation aid, not anonymization, encryption or an access
+boundary. Do not publish the local preview without reviewing its paths and other metadata.
+This ID never enters artifact keys, prompts, facts or snapshot configuration digests.
+
+For source failures, elapsed time includes cache checks, authentication, provider attempts and
+retries through failure. Codex's configured limit is per attempt; authentication has a separate
+bounded status check. Module execution has one deadline covering import, factory and extraction.
+The report distinguishes these scopes rather than presenting the limit as an end-to-end deadline.
+No timeout default, retry policy, extraction contract or cache version changes here.
+
+## Recovery and limits
+
+Failures do not reach graph publication. Prior snapshots and completed artifacts remain intact.
+Use the same configuration, committed ref and scope in the no-model preview to inspect current
+reuse before retrying without `--force-semantic`. T03 preserves compatible built-in Codex artifacts
+across supported operational changes; legacy recovery requires the exact previous configuration.
+Custom modules retain conservative full-configuration identity. Completed forced revisions are
+retained but are not automatically adopted by an ordinary rerun or a new forced revision.
+
+The toolkit waits for built-in subprocess termination or the module wrapper's bounded promise.
+It cannot forcibly terminate arbitrary trusted in-process module code. Cancellation before source
+selection and outside semantic processing uses the existing safe cancellation error without
+per-source counts. Phase boundaries remain the progress signal; no synchronous SHACL heartbeat,
+incremental validator or invented percentage is introduced by this milestone.
+
+Public deterministic tests cover failures, cancellation races, durable-write completion, counts,
+privacy, reuse, unchanged snapshot heads, source mapping and installed CLI behavior. They do not
+claim private consumer acceptance or live-provider semantic quality.

package/docs/ADR-020-canonical-physical-file-producers.md

@@ -0,0 +1,97 @@
+# ADR-020: One physical-file policy for deterministic producers and adapters
+
+Status: upstream fix shipped in 0.4.0; release evidence and pending consumer adapter/hydration
+acceptance are recorded separately in [validation](VALIDATION.md).
+
+## Reported defect and ownership
+
+The consumer's bounded replay of installed 0.3.0 extractors reported 120 conflicting file IDs:
+34 from the neutral contract extractor alone, 57 from its local framework adapter alone, and
+29 from both. Actual file/SCIP extraction classified spec/test files as `Evidence`; contract
+consumers and local framework nodes could classify those same physical IDs as `Component`.
+The consumer isolated a neutral file-plus-contract pair that failed strict SHACL single-kind
+validation. This is an extraction identity defect, not conflicting product intent.
+
+Upstream owns the neutral policy and producers. The consumer owns its framework call sites and
+their tests. This work uses public fixtures; it does not reproduce all private IDs, modify the
+consumer repository, patch installed packages or claim successful consumer hydration.
+
+## Public contract
+
+Move the existing pure `repositoryFileNode(path)` implementation into `@weftlet/core` and export
+it publicly. Its module imports only the `GraphNode` type; core gains no runtime package
+dependencies. Keep the toolkit's internal re-export for compatibility, but adapters should use:
+
+```ts
+import { repositoryFileNode } from '@weftlet/core';
+
+const file = {
+  ...repositoryFileNode(path),
+  attributes: { /* adapter-specific evidence metadata */ },
+};
+```
+
+The caller supplies a repository-relative path in its canonical spelling. Existing mappings stay
+unchanged: `.md`, `.mdx` and `.txt` use `document:<path>`/`Document`; `.spec.<extension>` and
+`.test.<extension>` use `component:file:<path>`/`Evidence`; other physical files use that file
+prefix and `Component`. Matching ignores extension case but preserves path spelling. This is not
+filesystem resolution, universal test detection, proof of existence or approved intent. Do not
+rewrite business concepts, contract identities or architectural modules into physical-file IDs.
+
+The producer audit is explicit:
+
+| Producer | Change |
+| --- | --- |
+| Neutral file extractor | Replace duplicated kind logic; preserve source/index attributes |
+| SCIP symbols | Replace duplicated kind logic; preserve symbols, sites and citations |
+| Contract consumers | Replace hard-coded Component; retain conceptual contract and evidence IDs |
+| Document linker | Import the public factory; existing owner/reference behavior stays intact |
+| Routing | Replace duplicated mapping; document endpoints now join document identities |
+| Governance | Use the factory for dependency and membership files and query lookup; retain module/layer concepts |
+| Semantic normalization | Use the shared factory for its existing document-only normalization; see the boundary below |
+
+Facts are retained, including test files with mocked client calls, DI and decorators. We do not
+suppress test evidence, rename conflicting IDs, weaken kind cardinality or change source/assertion
+authority. Graphs and all working overlays require strict SHACL before publication; overlay
+validation no longer depends on routing being configured.
+
+## Identity, saved evidence and artifacts
+
+Contract extraction advances from 1.1.0 to 1.2.0; routing and SCIP fact extraction from 1.0.0 to
+1.1.0; governance analyzer from 2 to 3. The SCIP indexer/tool version is unchanged. Committed
+assembly becomes `standalone-graph-v7`, with `graph-v7`, contract and SCIP fact identity included
+in snapshot IDs. Overlay IDs/metadata also bind assembly, contract and SCIP fact identity,
+so rebuilding identical captured bytes cannot replace an older overlay. Governance records its
+analyzer identity in both snapshot digest inputs and metadata.
+
+Current validation requires matching assembly, contract and SCIP fact versions, plus routing version when
+configured. Missing metadata is not a pass. Final checks reject old versions without initiating
+hydration. Historical saved queries still return the original facts, with extraction compatibility
+reported separately from commit/configuration/working-overlay freshness in JSON, Markdown and
+the viewer. Saved queries remain ineligible to validate a current diff.
+
+The physical policy itself was already correct. Its semantic cache identity stays at version 1;
+provider/prompt/artifact keys and original artifact bytes remain unchanged. The original snapshot
+and any compatible semantic artifacts remain available. A fresh graph must still be assembled,
+indexed and validated. Reuse does not imply that an old graph passes current validation.
+
+## Semantic and consumer boundary
+
+The reported 120 conflicts were reproduced entirely by deterministic producers. This fix does
+not rewrite semantic caches or force paid re-extraction to hide that defect. Existing semantic
+normalization continues correcting repository document IDs/kinds only. Non-document model kinds
+remain asserted, inferred and unreviewed; an incompatible model assertion still fails strict
+SHACL. A broader interpretation migration would need separate provenance/OML parity tests and
+an explicit cache/assembly decision. It is not silently bundled into this deterministic fix.
+
+After upgrading both packages to the reviewed public release, the consumer must change every
+physical-file node emitted by its framework adapter to the public factory and version that
+adapter's extractor deliberately. Add actual adapter regressions for Prisma/DI/decorator-bearing
+spec/test files composed with neutral file facts. Do not change semantic provider/prompt policy
+versions merely to perform this deterministic adapter migration. Preview compatible artifact reuse,
+then run full hydration and repeat acceptance against the committed adapter update.
+
+Public upstream tests compose actual committed-source extractors, real TypeScript indexing,
+document and routing links and a public adapter-shaped fixture. They assert strict SHACL,
+provenance, confidence, authority, stable conceptual identities, saved-byte preservation and
+version guards. They do not establish the private adapter's acceptance or semantic quality.

package/docs/ADR-021-identity-preflight-and-validation-timing.md

@@ -0,0 +1,81 @@
+# ADR-021: Early identity conflicts and honest validation phase timing
+
+Status: implemented in development source after 0.4.0. Publication and consumer acceptance
+are separate checkpoints in [validation](VALIDATION.md). This is the bounded T05a increment.
+
+## Decision
+
+Before ontology compilation, invariant evaluation or RDF construction, scan every assembled
+fact's subject and object identity for multiple kinds. The scan covers semantic, document,
+static, adapter, routing and runtime facts, including conceptual identities. Working overlays
+run the same check over retained and newly extracted facts before RDF construction/publication.
+No fact, kind, ID, citation or authority is changed or discarded by the check.
+This runs after semantic/static extraction; it is separate from no-model `hydrate --plan`.
+
+`inspectGraphIdentities(facts, { repositoryId, includeDetails? })` returns a report;
+`assertGraphIdentities` throws `GraphIdentityConflictError` on conflicts. Both are public toolkit
+exports. A passing report has `passed: true` and **`shaclValidated: false`**. Consistent kinds
+alone do not establish canonical classification, correct intent, valid citations or conformance.
+The existing full RDF/SHACL path and shapes remain mandatory for successful publication. Direct
+`RdfEvidenceGraph.validate()` and the saved `validate` command still run all checks and return
+their existing verdict format. There is no validation cache, incremental validator or backend change.
+
+The two-pass scan is linear in fact occurrences. The common conflict-free path creates no
+per-evidence diagnostic records. On failure it reports every conflicting identity and occurrence,
+including both ends of a self-reference, repeated fact IDs and late conflicts. Counts are complete;
+there is no hidden document, hop or diagnostic cutoff. Reports retain input indices and side so
+duplicate assertion IDs cannot conceal a producer's occurrence.
+
+## Privacy and attribution
+
+There was no general configurable diagnostic privacy policy. This increment therefore makes
+local detail an explicit invocation option, without adding an extraction/configuration field.
+Default reports contain repository-scoped opaque node, fact, source and extractor references,
+counts and recognized kind names. Unknown kind strings are hashed as well. References correlate
+records; they are not encryption or proof that a low-entropy identifier cannot be guessed.
+
+`hydrate --json --quiet` emits a typed identity-failure report on stderr with empty stdout.
+Use `--validation-details` on `hydrate` or `overlay` only when local identities and citations
+may be displayed. That option includes exact node/fact IDs, extractor identity/version, citation
+path/lines/digest/commit, confidence and the original optional authority/review fields. It does
+not include labels, node attributes, source text, prompts or raw provider output. Absent authority
+fields stay absent; source approval is never promoted into assertion approval.
+
+The programmatic equivalent is `HydrationOptions.validationDetails` or the overlay's final
+options argument. Detail changes do not enter snapshot, provider or semantic-cache identities.
+The error message stays safe even when its report includes explicitly requested local details.
+No diagnostic file is written automatically. Existing non-identity SHACL errors retain their
+existing detailed behavior; this is not a claim that every command/error has been redacted.
+
+## Timing and failure preservation
+
+Hydration reports started/completed/failed boundaries and elapsed wall time for identity
+preflight, RDF construction, union construction and full SHACL. Counts describe graph size,
+not validator completion. A completed SHACL phase means the validator returned, including a
+nonconforming verdict. `RdfEvidenceGraph.validate({ onProgress })` exposes its union/SHACL phases.
+
+The synchronous JavaScript work can block same-thread timers. These events are not heartbeats,
+percentages, new timeout controls or interruptible worker execution. Worker isolation remains a
+separate decision. The public profiling harness records preflight and validation phase timings
+alongside its existing construction, resource and runtime measurements.
+
+Failure preserves completed semantic artifacts and prior snapshots/heads. Correcting and
+versioning an adapter still requires a fresh assembly and full validation, but compatible
+semantic artifacts can be reused. This preflight does not rewrite cached model assertions or
+choose an authoritative business rule. Evidence disagreements must be resolved at their owner.
+
+No extraction/assembly version changes are needed: accepted graph facts, cache identities,
+RDF serialization and conformance constraints are unchanged. The check rejects an existing
+single-kind violation earlier; it does not make old snapshots satisfy current validation.
+
+## Evidence and remaining work
+
+Tests cover full cross-source attribution, conceptual and physical nodes, exact authority,
+default privacy, late conflicts, duplicates/self-references, immutable artifacts/snapshots,
+corrected retries and non-kind failures that still reach full SHACL. CLI and packed-consumer
+cases use actual TypeScript SCIP and public adapters. Existing positive/negative named-dataset
+SHACL equivalence tests remain unchanged except for an additional timing/parity case.
+
+Broader T05 work remains: worker-based progress/cancellation, repeated/changed-input performance
+evaluation, and evidence-driven decisions about conformance-result reuse or incremental/native
+backends. This increment does not infer private consumer performance from public fixtures.