@weftlet/toolkit 0.4.0 → 0.5.0

package/README.md

@@ -109,6 +109,16 @@ 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
@@ -135,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

package/dist/application/hydrator.d.ts

@@ -14,6 +14,8 @@ export interface HydrationOptions {
     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;
 }

package/dist/application/hydrator.js

@@ -12,6 +12,8 @@ import { extractRoutingDeclarations, routingExtractorIdentity } from '../extract
 import { SemanticProviderError } from '../extraction/semantic-process.js';
 import { hydrateSemanticSources } from './semantic-run.js';
 import { graphAssemblyVersion, graphAssemblyIdentity } from './extraction-identity.js';
+import { assertGraphIdentities } from '../graph/identity-preflight.js';
+import { measureValidationPhase } from '../graph/validation-progress.js';
 export class ContextGraphHydrator {
     dependencies;
     constructor(dependencies) {
@@ -157,11 +159,19 @@ export class ContextGraphHydrator {
         diagnostics.push(...documents.diagnostics);
         diagnostics.push(...routing.diagnostics);
         checkpoint();
-        options.onProgress?.({ phase: 'compile-semantic-rdf' });
-        const ontology = await this.dependencies.ontologyCompiler.compile(snapshotId, artifacts, context);
         const runtimeEvidence = runtimeRevision.references;
         const runtimeFacts = runtimeEvidenceFacts(context, runtimeEvidence);
         const facts = [...semanticFacts, ...documents.facts, ...extractorFacts, ...routing.facts, ...runtimeFacts].sort((left, right) => left.id.localeCompare(right.id));
+        const validationCounts = { factCount: facts.length };
+        await measureValidationPhase('validate-identities', validationCounts, options.onProgress, () => {
+            const report = assertGraphIdentities(facts, {
+                repositoryId: config.repositoryId, includeDetails: options.validationDetails,
+            });
+            validationCounts.nodeCount = report.nodeCount;
+        });
+        checkpoint();
+        options.onProgress?.({ phase: 'compile-semantic-rdf' });
+        const ontology = await this.dependencies.ontologyCompiler.compile(snapshotId, artifacts, context);
         const invariants = (await Promise.all(this.dependencies.invariantEvaluators.map((evaluator) => evaluator.evaluate(snapshotId, facts)))).flat();
         const failures = invariants.filter((invariant) => invariant.status === 'fail');
         if (failures.length > 0) {
@@ -231,8 +241,8 @@ export class ContextGraphHydrator {
             diagnostics,
         };
         checkpoint();
-        options.onProgress?.({ phase: 'validate-shacl' });
-        const validation = await new RdfEvidenceGraph(snapshot).validate();
+        const graph = await measureValidationPhase('build-rdf-evidence', validationCounts, options.onProgress, () => new RdfEvidenceGraph(snapshot));
+        const validation = await graph.validate({ onProgress: (event) => options.onProgress?.({ ...event, nodeCount: validationCounts.nodeCount }) });
         if (!validation.conforms) {
             throw new Error(`Graph extraction failed SHACL validation: ${JSON.stringify(validation.issues)}`);
         }

package/dist/application/overlay.d.ts

@@ -3,4 +3,6 @@ import type { GraphSnapshot } from "@weftlet/core";
 import { GitRepository } from "../repository/git.js";
 import { FileSnapshotStore } from "../storage/storage.js";
 /** Conservative code overlay: reindex implementation; invalidate changed prose, never synthesize intent. */
-export declare function buildWorkingOverlay(repository: GitRepository, config: ContextGraphConfig, store: FileSnapshotStore, storageRoot: string, baseSnapshotId: string, agent?: string): Promise<GraphSnapshot>;
+export declare function buildWorkingOverlay(repository: GitRepository, config: ContextGraphConfig, store: FileSnapshotStore, storageRoot: string, baseSnapshotId: string, agent?: string, options?: {
+    readonly validationDetails?: boolean;
+}): Promise<GraphSnapshot>;

package/dist/application/overlay.js

@@ -12,13 +12,14 @@ import { inWorkingScope, readWorkingContent } from "../repository/working-conten
 import { extractRoutingDeclarations, routingExtractorIdentity } from '../extraction/routing.js';
 import { RdfEvidenceGraph } from '../graph/rdf.js';
 import { graphAssemblyIdentity } from './extraction-identity.js';
+import { assertGraphIdentities } from '../graph/identity-preflight.js';
 const execute = promisify(execFile);
 const implementationExtractors = new Set([
     'repository-file-extractor', 'repository-contract-extractor', 'scip-symbol-extractor',
     routingExtractorIdentity.id,
 ]);
 /** Conservative code overlay: reindex implementation; invalidate changed prose, never synthesize intent. */
-export async function buildWorkingOverlay(repository, config, store, storageRoot, baseSnapshotId, agent = 'default') {
+export async function buildWorkingOverlay(repository, config, store, storageRoot, baseSnapshotId, agent = 'default', options = {}) {
     const base = await store.read(baseSnapshotId);
     if (!base || base.manifest.overlayDigest)
         throw new Error('Overlay requires a committed base snapshot');
@@ -119,6 +120,7 @@ export async function buildWorkingOverlay(repository, config, store, storageRoot
         !affected.has(fact.provenance.path) &&
         ![fact.subject, fact.object].some((node) => [...affected].some((path) => node.id === `component:file:${path}` || node.id === `document:${path}` || node.label === path))).map((fact) => ({ ...fact, snapshotId }));
     const allFacts = [...retained, ...extracted.facts].sort((a, b) => a.id.localeCompare(b.id));
+    assertGraphIdentities(allFacts, { repositoryId: config.repositoryId, includeDetails: options.validationDetails });
     const overlay = {
         ...base,
         manifest: {

package/dist/application/semantic-run.d.ts

@@ -7,6 +7,9 @@ export interface HydrationProgressEvent {
     readonly total?: number;
     readonly sourceId?: string;
     readonly elapsedMs?: number;
+    readonly status?: 'started' | 'completed' | 'failed';
+    readonly factCount?: number;
+    readonly nodeCount?: number;
 }
 /** Settle active workers before reporting failure; never publish snapshots here. */
 export declare function hydrateSemanticSources(options: {

package/dist/configuration/config.js

@@ -113,7 +113,7 @@ function validateConfig(value, absolutePath) {
                 requireConfig(auth.apiKeyEnv === undefined || (typeof auth.apiKeyEnv === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(auth.apiKeyEnv)), 'semantic.auth.apiKeyEnv must name an environment variable', absolutePath);
             }
         }
-        for (const [field, max] of [['timeoutMs', 300_000], ['retries', 2], ['maxDocuments', 1000], ['maxSourceBytes', 1_048_576]]) {
+        for (const [field, max] of [['timeoutMs', 600_000], ['retries', 2], ['maxDocuments', 1000], ['maxSourceBytes', 1_048_576]]) {
             const item = value.semantic[field];
             if (item !== undefined)
                 requireConfig(Number.isInteger(item) && Number(item) >= (field === 'retries' ? 0 : 1) && Number(item) <= max, `semantic.${field} exceeds supported bounds`, absolutePath);

package/dist/graph/identity-preflight.d.ts

@@ -0,0 +1,57 @@
+import { type ExtractorIdentity, type GraphFact, type GraphNodeKind, type SourceSpan } from '@weftlet/core';
+/** Diagnostic detail is an invocation option, not extraction policy or a cache identity input. */
+export interface GraphIdentityPreflightOptions {
+    readonly repositoryId: string;
+    readonly includeDetails?: boolean;
+}
+export type ReportedIdentityKind = GraphNodeKind | `unknown-kind-${string}`;
+export interface GraphIdentityOccurrenceDetails {
+    readonly nodeId: string;
+    readonly nodeKind: GraphNodeKind;
+    readonly factId: string;
+    readonly extractor: ExtractorIdentity;
+    readonly provenance: SourceSpan;
+    readonly confidence: number;
+    readonly authority?: GraphFact['authority'];
+    readonly sourceAuthority?: GraphFact['sourceAuthority'];
+    readonly extractionReview?: GraphFact['extractionReview'];
+}
+export interface GraphIdentityOccurrence {
+    readonly factIndex: number;
+    readonly side: 'subject' | 'object';
+    readonly kind: ReportedIdentityKind;
+    readonly factRef: string;
+    readonly sourceRef: string;
+    readonly extractorRef: string;
+    readonly details?: GraphIdentityOccurrenceDetails;
+}
+export interface GraphIdentityConflict {
+    readonly nodeRef: string;
+    readonly kinds: readonly ReportedIdentityKind[];
+    readonly occurrences: readonly GraphIdentityOccurrence[];
+    readonly details?: {
+        readonly nodeId: string;
+    };
+}
+export interface GraphIdentityPreflightReport {
+    readonly schemaVersion: 1;
+    readonly kind: 'graph-identity-preflight';
+    readonly category: 'extraction-gap';
+    readonly phase: 'validate-identities';
+    readonly passed: boolean;
+    /** A passing identity preflight never establishes full graph conformance. */
+    readonly shaclValidated: false;
+    readonly factCount: number;
+    readonly nodeCount: number;
+    readonly conflictCount: number;
+    readonly conflicts: readonly GraphIdentityConflict[];
+}
+/** Find the single-kind constraint's conflicts without constructing RDF or changing any fact. */
+export declare function inspectGraphIdentities(facts: readonly GraphFact[], options: GraphIdentityPreflightOptions): GraphIdentityPreflightReport;
+/** The message is safe even when the caller explicitly requested local report details. */
+export declare class GraphIdentityConflictError extends Error {
+    readonly report: GraphIdentityPreflightReport;
+    readonly code = "node-kind-conflict";
+    constructor(report: GraphIdentityPreflightReport);
+}
+export declare function assertGraphIdentities(facts: readonly GraphFact[], options: GraphIdentityPreflightOptions): GraphIdentityPreflightReport;

package/dist/graph/identity-preflight.js

@@ -0,0 +1,71 @@
+import { sha256, stableJson } from '@weftlet/core';
+const publicKinds = new Set([
+    'Project', 'Document', 'Capability', 'Workflow', 'Component', 'Contract', 'Evidence',
+    'Invariant', 'Snapshot', 'Provider', 'PersistenceModel', 'Scope',
+]);
+/** Find the single-kind constraint's conflicts without constructing RDF or changing any fact. */
+export function inspectGraphIdentities(facts, options) {
+    const identities = new Map();
+    for (const fact of facts)
+        for (const node of [fact.subject, fact.object]) {
+            let kinds = identities.get(node.id);
+            if (!kinds)
+                identities.set(node.id, kinds = new Set());
+            kinds.add(node.kind);
+        }
+    const ref = (domain, ...values) => `identity-${domain}-${sha256(stableJson(['graph-identity-preflight-v1', options.repositoryId, domain, ...values]))}`;
+    const reportedKind = (kind) => publicKinds.has(kind)
+        ? kind : `unknown-kind-${sha256(stableJson(['graph-identity-kind-v1', options.repositoryId, kind]))}`;
+    const conflicts = new Map();
+    for (const [id, kinds] of identities)
+        if (kinds.size > 1) {
+            conflicts.set(id, { nodeRef: ref('node', id), kinds: [...kinds].map(reportedKind), occurrences: [],
+                ...(options.includeDetails ? { details: { nodeId: id } } : {}) });
+        }
+    // The common conflict-free path allocates no evidence reports. Preserve every conflicting
+    // occurrence, including duplicate fact IDs and the two ends of a self-reference.
+    if (conflicts.size)
+        for (const [factIndex, fact] of facts.entries()) {
+            const sides = ['subject', 'object'].filter(side => conflicts.has(fact[side].id));
+            if (!sides.length)
+                continue;
+            const references = { factRef: ref('fact', fact.id), sourceRef: ref('source', fact.provenance.path),
+                extractorRef: ref('extractor', fact.extractor.id, fact.extractor.version) };
+            for (const side of sides) {
+                const node = fact[side];
+                conflicts.get(node.id).occurrences.push({ factIndex, side, kind: reportedKind(node.kind), ...references,
+                    ...(options.includeDetails ? { details: {
+                            nodeId: node.id, nodeKind: node.kind, factId: fact.id,
+                            extractor: { id: fact.extractor.id, version: fact.extractor.version },
+                            provenance: { path: fact.provenance.path, startLine: fact.provenance.startLine,
+                                endLine: fact.provenance.endLine, digest: fact.provenance.digest, commitSha: fact.provenance.commitSha },
+                            confidence: fact.confidence,
+                            ...(fact.authority === undefined ? {} : { authority: fact.authority }),
+                            ...(fact.sourceAuthority === undefined ? {} : { sourceAuthority: fact.sourceAuthority }),
+                            ...(fact.extractionReview === undefined ? {} : { extractionReview: fact.extractionReview }),
+                        } } : {}) });
+            }
+        }
+    return { schemaVersion: 1, kind: 'graph-identity-preflight', category: 'extraction-gap',
+        phase: 'validate-identities', passed: conflicts.size === 0, shaclValidated: false,
+        factCount: facts.length, nodeCount: identities.size, conflictCount: conflicts.size,
+        conflicts: [...conflicts.values()] };
+}
+/** The message is safe even when the caller explicitly requested local report details. */
+export class GraphIdentityConflictError extends Error {
+    report;
+    code = 'node-kind-conflict';
+    constructor(report) {
+        super(`Graph identity preflight found ${report.conflictCount} node kind conflict(s) across ${report.factCount} facts. ` +
+            'Full SHACL validation was not run. Use --validation-details for local node and cited evidence details. ' +
+            'Correct the extractor or assertion identity disagreement, then retry; no graph facts were rewritten by this check.');
+        this.report = report;
+        this.name = 'GraphIdentityConflictError';
+    }
+}
+export function assertGraphIdentities(facts, options) {
+    const report = inspectGraphIdentities(facts, options);
+    if (!report.passed)
+        throw new GraphIdentityConflictError(report);
+    return report;
+}

package/dist/graph/rdf.d.ts

@@ -1,4 +1,5 @@
 import type { GraphFact, GraphSnapshot } from "@weftlet/core";
+import { type GraphValidationProgress } from './validation-progress.js';
 export { CG } from './shacl-shapes.js';
 export declare const nodeIri: (id: string) => string;
 export declare const factIri: (id: string) => string;
@@ -7,7 +8,9 @@ export declare class RdfEvidenceGraph {
     readonly snapshot: GraphSnapshot;
     private readonly dataset;
     constructor(snapshot: GraphSnapshot);
-    validate(): Promise<{
+    validate(options?: {
+        readonly onProgress?: (event: GraphValidationProgress) => void;
+    }): Promise<{
         conforms: boolean;
         issues: {
             category: "extraction-gap";

package/dist/graph/rdf.js

@@ -5,6 +5,7 @@ import { contextPackEvidenceAuthority } from "./authority.js";
 import { stableJson } from "../infrastructure/util.js";
 import { createRequire } from 'node:module';
 import { CG, RDF, XSD, evidenceShapes } from './shacl-shapes.js';
+import { measureValidationPhase } from './validation-progress.js';
 const { namedNode: iri, literal } = DataFactory;
 export { CG } from './shacl-shapes.js';
 export const nodeIri = (id) => `urn:context-graph:node:${encodeURIComponent(id)}`;
@@ -61,16 +62,19 @@ export class RdfEvidenceGraph {
             this.dataset.addQuad(iri('urn:context-graph:snapshot'), iri(CG + 'configurationDigest'), literal(snapshot.manifest.configurationDigest));
         }
     }
-    async validate() {
+    async validate(options = {}) {
         // These graph-independent shapes already read the dataset as a union. Index
         // that union once so every property lookup avoids scanning one graph per fact.
         // Keep every triple; the original named dataset retains assertion provenance
         // and remains the source for queries and serialization.
-        const validationGraph = new Store();
-        for (const { subject, predicate, object } of this.dataset) {
-            validationGraph.addQuad(subject, predicate, object);
-        }
-        const report = await new SHACLValidator(new Store(evidenceShapes)).validate(validationGraph);
+        const counts = { factCount: this.snapshot.facts.length };
+        const validationGraph = await measureValidationPhase('build-validation-union', counts, options.onProgress, () => {
+            const union = new Store();
+            for (const { subject, predicate, object } of this.dataset)
+                union.addQuad(subject, predicate, object);
+            return union;
+        });
+        const report = await measureValidationPhase('validate-shacl', counts, options.onProgress, () => new SHACLValidator(new Store(evidenceShapes)).validate(validationGraph));
         const issues = report.results.map((result) => ({
             category: 'extraction-gap',
             focus: result.focusNode?.value,

package/dist/graph/validation-progress.d.ts

@@ -0,0 +1,14 @@
+export type GraphValidationPhase = 'validate-identities' | 'build-rdf-evidence' | 'build-validation-union' | 'validate-shacl';
+export interface GraphValidationProgress {
+    readonly phase: GraphValidationPhase;
+    readonly status: 'started' | 'completed' | 'failed';
+    /** Wall time for this phase, not a completion estimate or in-phase heartbeat. */
+    readonly elapsedMs: number;
+    readonly factCount: number;
+    readonly nodeCount?: number;
+}
+/** Phase boundaries remain observable even when an operation blocks same-thread timers. */
+export declare function measureValidationPhase<T>(phase: GraphValidationPhase, counts: {
+    readonly factCount: number;
+    readonly nodeCount?: number;
+}, onProgress: ((event: GraphValidationProgress) => void) | undefined, operation: () => T | Promise<T>): Promise<T>;

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

@@ -13,3 +13,5 @@ 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

@@ -14,3 +14,5 @@ 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

@@ -18,6 +18,7 @@ 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;
@@ -82,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|cache adopt|overlay|impact scan|sparql|validate|govern|visualize|diagnostics show|invariant check|clean-compare|ontology compile\nUse --config <file>; queries accept --snapshot <id>. impact scan accepts --changed-file, --capability, --max-facts, --max-depth, --continuation.\nhydrate --plan [--json] [--ref <commit>] [--force-semantic] previews scope, cache and budgets without model calls or graph writes. Preview readiness is advisory and does not add a hydration gate.\nhydrate --json --quiet emits structured semantic failures on stderr with no progress lines; failure stdout stays empty. hydrate --plan maps opaque source IDs to local document paths.\ncache adopt --from-config <previous.json> [--config <current.json>] [--ref <commit>] [--dry-run] returns JSON and copies only validated compatible artifacts, without model calls or snapshot writes. --dry-run performs no cache writes. Agent configurations accept the same --owner-doc, --task and --capability selection as hydrate.\ninit [--yes] [--directory <project>] [--config <file>] [--repository-id <id>] [--code-root <path>] [--semantic-source <path>] [--evidence-root <path>] [--model <name>] [--no-gitignore]\nSource flags may be repeated. init never overwrites an existing config. See README.md for examples.\n');
+        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') {
@@ -171,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;
     }
@@ -187,8 +188,11 @@ async function main() {
                 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({
@@ -257,8 +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 SemanticHydrationError
-        ? process.argv.includes('--json') ? JSON.stringify(error.report, null, 2) : error.message
-        : 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/docs/ADR-018-operational-semantic-cache.md

@@ -1,7 +1,7 @@
 # ADR-018: Preserve Codex artifacts across operational configuration changes
 
-Status: accepted and implemented in development source after 0.3.0; release evidence is recorded
-in [validation](VALIDATION.md). This increment does not claim a new npm publication.
+Status: accepted and shipped in 0.4.0; release and validation evidence is recorded in
+[validation](VALIDATION.md).
 
 ## Problem
 

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

@@ -1,7 +1,7 @@
 # ADR-019: Safe semantic failure diagnostics and settled progress
 
-Status: implemented in development source after 0.3.0; validation and publication are recorded
-separately in [validation](VALIDATION.md). This decision does not change extraction identity.
+Status: shipped in 0.4.0; validation and publication are recorded in [validation](VALIDATION.md).
+This decision does not change extraction identity.
 
 ## Problem
 

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

@@ -1,7 +1,7 @@
 # ADR-020: One physical-file policy for deterministic producers and adapters
 
-Status: implemented in development source after 0.3.0; release/consumer acceptance is recorded
-separately in [validation](VALIDATION.md).
+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
 

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.

package/docs/PROVIDERS.md

@@ -87,6 +87,13 @@ Codex attempt (or module execution), no retries, and the configured concurrency
 before any model call. `maxDocuments`, `maxSourceBytes`, `timeoutMs`, and `retries` may be configured
 within validated limits. Review scope and cost before raising them; these byte/document limits
 are not dollar or token estimates. Ask the operator before substantial paid runs.
+Starting with 0.5.0, `semantic.timeoutMs` accepts integer values from 1 through **600000**
+(ten minutes); 0.4.0 and earlier reject values above 300000. The default remains 120000.
+For the approved ten-minute retry, set `"timeoutMs": 600000` inside the existing `semantic`
+configuration, preview reuse with `hydrate --plan`, then rerun hydration without forcing
+re-extraction. The limit applies to each Codex attempt, or the whole module execution, rather
+than the entire hydration. Codex authentication/discovery checks retain their separate five-second
+bounds. This setting does not raise a CI job's overall timeout or change retry policy.
 Only explicit transient exit status 75 is retryable, at most twice; authentication, invalid
 output, cancellation and ambiguous failures are not retried. Ctrl-C cancels live CLI extraction.
 Indexing cancellation is checked between phases, not inside the indexer process.

package/docs/RELEASE-1.0-PLAN.md

@@ -1,15 +1,20 @@
 # Consumer hardening and the 1.0 release plan
 
-Status: maintainer-directed work; release checkpoint on 2026-10-26 after verified 0.3.0 publication.
-**New adoption blocker: T08, deterministic physical-file kind conflicts.** This takes release
-priority over the remaining planned increments; T04 was completed first as requested.
-The report concerned `@weftlet/toolkit@0.2.0`. **T01's upstream patch shipped in 0.2.1**;
-genuine consumer acceptance remains pending. T02 and T05's focused cold-validation optimization
-shipped in 0.3.0. T03 and T04 are implemented in development source after that release. Broader T05
-follow-ups and T06 and T07 remain open. These tasks improve setup, reuse, diagnostics and document coverage
-without expanding the consumer's migration. An official 1.0
-follows this work and genuine consumer acceptance, with its exact release scope reviewed when
-the evidence is available.
+Status: maintainer-directed work; release checkpoint on 2026-10-26 after verified 0.4.0 publication.
+**T08's upstream deterministic physical-file fix has shipped; the maintainer reports the consumer
+updated and working on 2026-10-27. Detailed full hydration/repeat evidence remains pending.** T04 was completed before
+the T08 fix as requested.
+
+**Release priority T09:** 0.4.0 rejects the approved ten-minute extraction timeout. Support for
+`semantic.timeoutMs: 600000` is implemented for the next release alongside ready T05a work;
+the consumer's ten-minute retry has not run. This bounded blocker precedes T06/T07.
+
+The original report concerned `@weftlet/toolkit@0.2.0`. T01's upstream document-identity patch
+shipped in 0.2.1; T02 and T05's focused cold-validation optimization shipped in 0.3.0.
+T03 operational cache reuse, T04 semantic failure diagnostics and T08's public core file factory
+shipped in 0.4.0. Broader T05 follow-ups, T06 documentation consistency and T07 document coverage
+remain open. Official 1.0 follows the agreed remaining scope and genuine consumer acceptance,
+with its exact release scope reviewed when the evidence is available.
 
 This is the near-term release task list. The [Weftlet 2.0 product plan](WEFTLET-2.0-PLAN.md)
 remains a separate future direction for generation, approvals, a companion website and hosted
@@ -36,21 +41,23 @@ integration. Consumer acceptance is reported separately from upstream determinis
 
 | ID | Task | Priority/status | Dependencies and release boundary |
 | --- | --- | --- | --- |
-| **T08** | Canonical physical-file kinds and public adapter factory | **Merged; local and hosted Ubuntu/Windows checks passed; release pending** | Neutral contract consumers conflict with test Evidence; consumer framework migration remains separately required |
+| **T09** | Accept the approved ten-minute extraction timeout | **Source fix implemented; release pending** | Raise only the config ceiling to 600000; preserve defaults/cache/retry behavior; consumer retry has not run |
+| **T08** | Canonical physical-file kinds and public adapter factory | **Shipped in 0.4.0; consumer reported working; detailed acceptance pending** | Public core factory and neutral producers agree; record consumer commit, adapter tests and full hydration/repeat evidence |
 | **T01** | Coherent repository-document identity and kind | **Upstream patch shipped in 0.2.1; consumer acceptance pending** | SHACL and assertions preserved; genuine consumer re-run is still required |
 | **T02** | No-model hydration/setup preview | Shipped in 0.3.0 | Shared selection/cache inspection, human/JSON plans; extend with T07 traversal coverage |
-| **T03** | Artifact reuse across operational configuration changes | Merged; local and hosted Ubuntu/Windows checks passed; unreleased | Built-in Codex user artifacts share five operational changes; custom providers remain conservative; exact legacy recovery without model calls |
-| **T04** | Actionable, privacy-safe timeout diagnostics | Merged; local and hosted Ubuntu/Windows checks passed; unreleased | Safe source IDs, settled counts, failure classification and T02/T03 recovery; no extraction/cache identity change |
-| **T05** | Early identity checks and validation progress/profiling | **Cold-validation fix shipped in 0.3.0; consumer acceptance pending** | Full validation preserved; early checks, detailed progress and validation reuse remain open |
+| **T03** | Artifact reuse across operational configuration changes | Shipped in 0.4.0 | Built-in Codex user artifacts share five operational changes; custom providers remain conservative; exact legacy recovery without model calls |
+| **T04** | Actionable, privacy-safe timeout diagnostics | Shipped in 0.4.0 | Safe source IDs, settled counts, failure classification and T02/T03 recovery; no extraction/cache identity change |
+| **T05** | Early identity checks and validation progress/profiling | **Cold fix shipped in 0.3.0; T05a merged with local/hosted checks passing, unreleased** | Full validation preserved; worker progress, reuse and broader profiling remain separate |
 | **T06** | Packaged release-documentation consistency | Open; README version pins removed in 0.2.1 | Automated archive/version consistency check remains to be implemented |
 | **T07** | Coverage-aware traversal from SOT/roadmap entry points | Planned bounded feature work | Use canonical identity from T01, preview from T02 and incremental reuse from T03; split selection/classification/extraction changes |
 
-T02 and the focused T05 fix passed local publication checks and hosted Ubuntu/Windows checks,
-then shipped in [0.3.0](https://github.com/jchewitt/weftlet/releases/tag/%40weftlet/toolkit%400.3.0).
-Registry archives match the independently reviewed export; source commit, provenance and release
-tags are recorded in [validation](VALIDATION.md). T03, T04, T06 and T07 remain independently
-useful increments, separate from the optional platform work. A genuine consumer hydration and
-repeat against the current release remain required; upstream fixtures do not establish that result.
+T02 and the focused T05 fix shipped in 0.3.0; T03, T04 and T08 shipped in
+[0.4.0](https://github.com/jchewitt/weftlet/releases/tag/%40weftlet/toolkit%400.4.0), following
+local/hosted checks, independent archive review and fresh packed/public-registry installation.
+Source, registry integrity, provenance and release tags are recorded in [validation](VALIDATION.md).
+Broader T05, T06 and T07 remain bounded follow-ups.
+The consumer must migrate its framework adapter to the public core factory, then complete full
+hydration and repeat reuse; upstream fixtures do not establish that result.
 
 ## T08 — Resolve deterministic physical-file kind conflicts
 
@@ -64,12 +71,12 @@ routes physical-file producers through one policy, preserves strict SHACL/proven
 and distinguishes historical graph versions from current validation. Public tests include real
 SCIP and actual extractor composition, plus negative overlay validation without routing.
 
-Release requires local publication checks, hosted Ubuntu/Windows checks, reviewed archives and
-fresh installed-package verification. Consumer acceptance then requires the published packages
-plus its own framework adapter migration and composed Prisma/DI/decorator spec/test regressions,
-followed by full hydration and repeat reuse. Neither an upstream-only release nor a local-only
-adapter patch closes both ownership boundaries. Do not rewrite semantic caches or force model
-work to work around the proven deterministic defect.
+The 0.4.0 release passed local publication checks, hosted Ubuntu/Windows checks, independent archive
+review and fresh packed/public-registry installation. Consumer acceptance still requires the
+published packages plus its own framework adapter migration and composed Prisma/DI/decorator
+spec/test regressions, followed by full hydration and repeat reuse.
+Neither an upstream-only release nor a local-only adapter patch closes both ownership boundaries.
+Do not rewrite semantic caches or force model work to work around the proven deterministic defect.
 
 ## T01 — Resolve repository-document identity conflicts
 
@@ -110,7 +117,8 @@ Upstream completion evidence:
   [validation record](VALIDATION.md) for commits, checks and result boundaries.
 
 The private consumer has not yet supplied a successful full hydration/repeat with the identity
-patch. Use the current 0.3.0 release, which also includes the cold-validation improvement.
+patch. Use both 0.4.0 packages and migrate the framework adapter to the public core factory;
+this release retains the cold-validation improvement and adds the T08 deterministic producer fix.
 Upstream publication and regression success do not close that acceptance gate or diagnose the
 separate full-graph validation latency observation.
 
@@ -126,9 +134,9 @@ Missing or unsupported-only selectors and bounded agent omissions remain visible
 incomplete plans need review and exit 1. They do not introduce new hydration gates that would
 break deletion of the last document. Budget, duplicate-ID and corrupt/unavailable cache errors
 block planning checks without truncating selected sources. An explicit empty source list selects
-none. Requested refs now govern agent scope; corrected snapshots use graph-v6 while valid 0.2.1
-semantic artifacts remain reusable. T03's operational cache changes and T07's traversal/default
-validation-document separation remain separate work.
+none. Requested refs govern agent scope. Release 0.3.0 introduced graph-v6; 0.4.0 advances assembly
+to graph-v7 for T08 while compatible semantic artifacts remain reusable. T03 operational cache
+reuse shipped in 0.4.0; T07 traversal/default validation-document separation remains open.
 
 Acceptance:
 
@@ -143,8 +151,8 @@ Acceptance:
 
 ## T03 — Reuse valid artifacts after operational changes
 
-Merged in [PR 22](https://github.com/jchewitt/weftlet/pull/22) after 0.3.0, with local publication
-and hosted Ubuntu/Windows checks passing. This source checkpoint does not claim npm publication.
+Shipped in 0.4.0 after merging [PR 22](https://github.com/jchewitt/weftlet/pull/22) and passing
+local publication and hosted Ubuntu/Windows checks; release evidence is in [validation](VALIDATION.md).
 [ADR 018](ADR-018-operational-semantic-cache.md) separates built-in Codex user artifacts from
 full snapshot profiles. Timeout, retry, concurrency and document/byte limits can change without
 hiding completed artifacts. Model/policy/authentication descriptors and unknown fields remain
@@ -179,8 +187,8 @@ Acceptance:
 
 ## T04 — Explain timeouts and recovery
 
-Merged in [PR 25](https://github.com/jchewitt/weftlet/pull/25) after 0.3.0, with local publication
-and hosted Ubuntu/Windows checks passing. This development checkpoint does not claim npm publication.
+Shipped in 0.4.0 after merging [PR 25](https://github.com/jchewitt/weftlet/pull/25) and passing
+local publication and hosted Ubuntu/Windows checks; release evidence is in [validation](VALIDATION.md).
 [ADR 019](ADR-019-semantic-failure-diagnostics.md) records opaque source IDs and explicit local
 preview mapping, final counts after active workers settle, safe typed errors and recovery.
 Concurrent sibling cancellation preserves the initiating failure. Completed writes stay counted
@@ -205,17 +213,26 @@ Acceptance:
 
 ## T05 — Detect inexpensive conflicts early and explain validation work
 
+T05a implements [early identity attribution and phase timing](ADR-021-identity-preflight-and-validation-timing.md)
+after 0.4.0, merged with local and hosted Ubuntu/Windows checks passing but not yet published.
+Hydration and overlays reject all conflicting subject/object kinds before RDF construction;
+opaque default reports have explicit local detail opt-in.
+Completed semantic artifacts and prior snapshots remain intact. Valid preflight results still
+require full SHACL. Timings report actual phase boundaries, not in-phase heartbeat or percentage.
+This does not close the broader evaluation/reuse/backend items below or claim publication.
+
 The implementation uses JavaScript on Node:
 `rdf-validate-shacl` validates an in-memory N3 dataset. Hydration constructs and validates the
 entire assembled graph, including when semantic artifacts were reused. There is no persistent
 GraphDB backend or incremental validation. Querying a saved snapshot does not rerun SHACL.
 
-The maintainer reports that validation pushes the consumer's overall generation beyond its
+The maintainer originally reported that validation pushed the consumer's overall generation beyond its
 30-minute timeout, preventing snapshot publication and making adoption unusable. That report made
 cold validation a release priority ahead of the remaining 1.0 work. Upstream has measured a specific
 named-graph lookup cost in public synthetic fixtures, but has not measured that consumer graph or
 diagnosed its complete timeout. The focused cold-validation fix shipped in 0.3.0, ahead of the
-remaining 1.0 tasks. Consumer acceptance remains pending; broader T05 items stay open.
+remaining 1.0 tasks. The consumer is now reported working after 0.4.0; exact performance and
+repeat-hydration acceptance evidence remains unrecorded. Broader T05 items stay open.
 
 [ADR 017](ADR-017-shacl-validation-union.md) records the implemented cold-validation optimization:
 build a temporary union of every SPO triple for the same validator/shapes, while keeping original
@@ -226,15 +243,15 @@ took 0.467 seconds. A 10,000-fact unique-node union case used about 1.3 GiB proc
 are synthetic phase measurements, not a private consumer reproduction or end-to-end guarantee.
 
 The focused change still validates the whole graph each time. It does not add Rust, GraphDB,
-incremental validation or a validation-result cache. Early checks and broader observability/reuse
-remain follow-ups rather than reasons to delay the cold-path fix. Native code or a database does
+incremental validation or a validation-result cache. T05a now adds early checks and phase timing;
+worker progress and broader observability/reuse remain follow-ups. Native code or a database does
 not by itself establish faster or correct incremental SHACL.
 
 Acceptance:
 
-- Early errors identify the conflicting identity/kinds and relevant evidence using the configured
-  privacy policy. Preserve all underlying assertions for diagnosis; early checks are not a
-  substitute for RDF/SHACL validation.
+- Early errors identify the conflicting identity/kinds and relevant evidence through opaque
+  defaults and explicit local detail opt-in. Preserve all underlying assertions for diagnosis;
+  early checks are not a substitute for RDF/SHACL validation.
 - Report elapsed time and honest progress for long validation. Current phase boundaries remain
   the supported progress signal: the synchronous validator blocks same-thread timers. Evaluate
   bounded worker execution before promising an in-phase heartbeat or cancellation; never display

package/docs/ROADMAP.md

@@ -1,21 +1,25 @@
 # Delivery roadmap
 
-Release checkpoint: 2026-10-26, after verified 0.3.0 publication. Evidence is recorded in
+Release checkpoint: 2026-10-26, after verified 0.4.0 publication. Evidence is recorded in
 [validation](VALIDATION.md); this roadmap is not a live registry status.
 
 Project: `jchewitt/weftlet`. Extraction provenance is recorded in the
 [source inventory](SOURCE-INVENTORY.md).
 
+Current release priority: the consumer's approved ten-minute retry is blocked by 0.4.0's
+five-minute configuration ceiling. T09 raises the accepted timeout to 600000 ms and will ship
+with ready T05a work. The actual consumer retry has not run; this does not change default limits.
+
 Forward direction is captured in the [Weftlet 2.0 product plan](WEFTLET-2.0-PLAN.md):
 consumer hardening, cited code-derived drafts, scoped approvals and reconciliation, an optional
 review website, source publication, managed AI and guided setup. “2.0” is a planning label;
-the verified release at this checkpoint is 0.3.0. The received consumer findings are tracked in the
+the verified release at this checkpoint is 0.4.0. The received consumer findings are tracked in the
 [consumer hardening and 1.0 task list](RELEASE-1.0-PLAN.md): the document-identity patch is
 published and passes upstream checks; genuine consumer acceptance remains pending. T02's
-no-model preview and T05's cold-validation improvement shipped in 0.3.0. Operational cache reuse
-and timeout diagnostics are development increments; document coverage and other acceptance work
-remain open before official 1.0.
-The 2.0 plan distinguishes proposed work from delivered capability.
+no-model preview and T05's cold-validation improvement shipped in 0.3.0. T03 operational cache
+reuse, T04 timeout diagnostics and T08 deterministic physical-file consistency shipped in 0.4.0.
+Document coverage, broader validation follow-ups and genuine consumer acceptance remain open
+before official 1.0. The 2.0 plan distinguishes proposed work from delivered capability.
 
 The maintainer reported SHACL pushing generation past a 30-minute timeout before graph
 publication. T02 and the focused T05 optimization shipped together in 0.3.0 through
@@ -32,25 +36,27 @@ in one temporary validation graph, preserving the same shapes and canonical name
 Bounded public experiments measured substantial cold-path improvement, alongside about 1.3 GiB
 RSS in the prototype at 10,000 unique-node facts; the production harness including serialization
 peaked near 1.6 GiB. They do not reproduce the private consumer's overall timeout.
-Early checks, in-phase progress, result reuse and incremental validation remain open; no Rust
-engine, graph database or validation-result cache is introduced by this focused release.
-
-[T03 operational cache reuse](ADR-018-operational-semantic-cache.md) is merged with local and
-hosted checks passing and is not part of published 0.3.0. Built-in Codex user
-artifacts can survive changes to timeout/retry/concurrency/document/byte limits while snapshots
-retain their full configuration identity. Exact legacy reads and explicit no-model adoption
-preserve prior artifacts; custom providers remain conservative.
-[T04 diagnostics](ADR-019-semantic-failure-diagnostics.md) add safe failure reports, opaque source
-mapping and accurate settled progress without changing extraction/cache identity. T04 is merged
-with local and hosted Ubuntu/Windows checks passing; release remains pending. Broader T05 and
-T06/T07 work remain open.
-
-A subsequent 0.3.0 consumer report makes [T08 physical-file kind consistency](ADR-020-canonical-physical-file-producers.md)
-the next release priority. Its neutral contract consumer fix and public core factory are merged
-with deterministic producer adoption, version guards and passing local/hosted Ubuntu/Windows
-checks. Publication is pending; the consumer's framework adapter migration and full acceptance
-remain consumer-owned.
-This fix preserves semantic artifacts and does not reinterpret model assertions to hide conflicts.
+T05a adds [early identity checks and phase timing](ADR-021-identity-preflight-and-validation-timing.md)
+after 0.4.0, merged with local/hosted checks passing and publication pending. Full validation
+remains mandatory. In-phase worker progress, result reuse and incremental validation remain
+open; no Rust engine, graph database or
+validation-result cache is introduced by these increments.
+
+[T03 operational cache reuse](ADR-018-operational-semantic-cache.md) shipped in 0.4.0. Built-in
+Codex user artifacts can survive changes to timeout/retry/concurrency/document/byte limits while
+snapshots retain their full configuration identity. Exact legacy reads and explicit no-model
+adoption preserve prior artifacts; custom providers remain conservative.
+[T04 diagnostics](ADR-019-semantic-failure-diagnostics.md) shipped in the same release, adding
+safe failure reports, opaque source mapping and settled progress without changing extraction/cache
+identity. Broader T05 and T06/T07 work remain open.
+
+[T08 physical-file kind consistency](ADR-020-canonical-physical-file-producers.md) also shipped in
+0.4.0 after local/hosted Ubuntu/Windows checks, independent archive review and fresh packed and
+public-registry installation. The public core factory and deterministic producers share one policy
+under strict SHACL. Historical snapshots remain queryable, with version guards for current validation.
+On 2026-10-27 the maintainer reported the consumer updated and working; exact adapter and full
+hydration/repeat evidence remain unrecorded. This fix preserves semantic artifacts and
+does not reinterpret model assertions to hide conflicts.
 
 | Milestone | Delivered and checked | Remaining limits |
 | --- | --- | --- |

package/docs/VALIDATION.md

@@ -8,6 +8,145 @@ The milestone entries below record the original cloud checks. Subsequent
 establishes live Codex success on Windows and the full deterministic checks on WSL,
 while identifying remaining native Windows issues.
 
+## Ten-minute timeout blocker, 2026-10-27
+
+The maintainer reports that published 0.4.0 rejects the approved `semantic.timeoutMs: 600000`.
+The consumer's ten-minute retry has **not run**. This is a configuration ceiling defect, separate
+from the corrected physical-file kinds and earlier positive consumer update below.
+
+The source patch raises only the accepted maximum from 300000 to 600000 ms. Omitted timeout
+still defaults to 120000; finite positive integer validation, retries, cancellation and the
+separate authentication/discovery limits are unchanged. No provider/prompt/artifact identity
+changes or forced model re-extraction are introduced.
+
+Focused checks pass: config acceptance/boundary rejection, Codex propagation across retries,
+per-call override/cancellation, a cancellable module deadline, and real artifact reuse/preview
+after an interrupted run switches to 600000. The provider tests use an injected runner/local
+module and finish immediately; they are not a live ten-minute extraction. Independent review
+found no blocker. Local `pnpm context-graph:publication-check` passed: 408 deterministic tests
+(17 core, 391 toolkit), one optional OML skip, 13 unchanged advisory architecture findings,
+inventory, licenses and fresh packed-consumer checks. The installed CLI accepts 600000 in
+no-model preview and reports the same limit on an immediate missing-provider failure.
+All 79 original source path/hash pairs remain intact. Hosted checks and publication are recorded
+after completion; the consumer's live ten-minute retry remains unrun.
+
+## Consumer update after 0.4.0, 2026-10-27
+
+The maintainer reports that the consumer updated and appears to be working. This is positive
+consumer feedback after the T08 release. No exact consumer commit, graph scope, adapter test
+report, full-run timing or repeated-hydration report was supplied with that update, so those
+detailed acceptance results remain unrecorded. No private consumer files were inspected or changed.
+
+## T05a identity preflight and validation phase timing, 2026-10-27
+
+Implemented in development source after 0.4.0; no new publication is claimed.
+[ADR 021](ADR-021-identity-preflight-and-validation-timing.md) records the bounded scope:
+complete identity/kind attribution before compilation/RDF, explicit local diagnostic detail,
+and elapsed phase boundaries. Full SHACL shapes, accepted facts and cache identities are unchanged.
+
+- Twelve pure preflight cases pass: both endpoints, cross-source kinds, conceptual IDs,
+  duplicates/self-references, all late conflicts, exact copied provenance/authority, absent
+  authority preservation and opaque defaults including unknown kinds. A pass explicitly says
+  `shaclValidated: false`; it does not infer canonical classification or approved intent.
+- Two hydration composition cases pass with actual committed file/contract/document producers
+  and a deterministic semantic provider. A kind conflict skips compilation, invariants and RDF;
+  previous head/snapshot and completed artifact bytes remain intact. Correcting the fixture
+  reuses the artifact and runs full SHACL. Invalid confidence with consistent kinds still fails
+  real SHACL. Indexing is stubbed in these scheduling cases; real SCIP is covered separately.
+- Four CLI subprocess cases pass with real SCIP and public adapters: default human/JSON privacy,
+  explicit exact attribution, empty failure stdout, preserved artifacts/snapshots, overlay detail
+  propagation and valid full-validation timing. The existing four semantic-failure CLI cases pass.
+- All 26 full SHACL parity/timing cases pass, including original named-dataset positive/negative
+  equivalence and the 2,200-fact late failure. Phase events do not change verdicts or serialization;
+  completed means the operation returned, not that its graph conformed.
+- Local `pnpm context-graph:publication-check` passed: 403 deterministic tests (17 core,
+  386 toolkit), one optional OML skip, 13 unchanged advisory architecture findings, inventory,
+  licenses and fresh packed-consumer checks. The installed public API detects kind conflicts,
+  preserves exact opt-in citations, reports phase timing and still rejects the same pair under
+  full SHACL. All 79 original extraction source path/hash pairs remain intact.
+- Independent runtime/test review found no blocker. No live model or private consumer
+  performance result is implied.
+
+[PR 30](https://github.com/jchewitt/weftlet/pull/30) merged at
+`c8db1f0b871f5e6f3d1d2e9eda1b045aa45469df`. Exact feature head
+`dc01421aa3953963e411430266b9035f2852cfd8` passed hosted Ubuntu and native Windows checks
+in [push run 40451305862](https://github.com/jchewitt/weftlet/actions/runs/40451305862) and
+[PR run 40451332221](https://github.com/jchewitt/weftlet/actions/runs/40451332221).
+T05a is merged but unpublished; npm 0.4.0 remains the verified public release.
+
+A bounded public profile ran the unique-node fixture in three fresh processes: 500 facts,
+the same 500 facts again, then 501 facts. Command: `node scripts/benchmark-shacl.mjs --counts 500
+--topologies unique --modes optimized --deadline-ms 15000` (use 501 for the final case), after
+`pnpm build`. Linux x64, Node 24.19.0, N3 2.7.2 and rdf-validate-shacl 0.6.5; built RDF module
+SHA-256 `8a66e0266d812b742103d42de3572faf4ab9873d0f37424b563962ea7473fae1`.
+
+| Facts / nodes | Preflight ms | RDF construction ms | Union ms | SHACL ms | Process peak RSS KiB |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| 500 / 1,000 | 0.84 | 67.90 | 32 | 186 | 330,496 |
+| 500 / 1,000 repeat | 0.74 | 57.15 | 32 | 174 | 334,356 |
+| 501 / 1,002 | 0.74 | 59.88 | 54 | 185 | 333,584 |
+
+All three ran full validation and preserved serialization; the repeated input's serialization
+digest matched, and the added-fact digest differed. These single-run smoke measurements establish
+phase visibility, not a speedup or production capacity. RSS includes imports, fixture and
+serialization; no successful-result reuse or dependency-aware incremental validation was used.
+
+## 0.4.0 publication and installed-package checks, 2026-10-26
+
+`@weftlet/core@0.4.0` and `@weftlet/toolkit@0.4.0` ship T03 operational cache reuse,
+T04 semantic failure diagnostics and T08 canonical physical-file kinds. This is an upstream
+release; private consumer adapter migration and full hydration acceptance remain pending.
+
+[Release PR 23](https://github.com/jchewitt/weftlet/pull/23) merged at
+`9c6c2625ce2f5d3a28d2be40610130c745b416d4`. Trusted publishing
+[run 40421791942](https://github.com/jchewitt/weftlet/actions/runs/40421791942)
+completed preparation, publication and release records on attempt 1. Both versions are public
+and tagged `latest`; downloaded registry archives are byte-identical to the independently
+reviewed archives. npm provenance identifies that merge commit and workflow attempt. The
+[core](https://github.com/jchewitt/weftlet/releases/tag/%40weftlet/core%400.4.0) and
+[toolkit](https://github.com/jchewitt/weftlet/releases/tag/%40weftlet/toolkit%400.4.0)
+package tags and GitHub Releases resolve to the same commit.
+
+- Exact reviewed version head `8ea26c7f538202b4acb67ceeda6adbf220a85e93` passed
+  `pnpm release:prepare`: 384 deterministic tests (17 core, 367 toolkit), one optional OML skip,
+  13 advisory architecture findings, inventory, licenses and fresh packed-consumer checks.
+  Hosted Ubuntu and native Windows checks passed in
+  [run 40421253221](https://github.com/jchewitt/weftlet/actions/runs/40421253221).
+- Independent source/archive review found no release blocker. Core contains 13 files/8,212 bytes;
+  toolkit contains 213 files/244,424 bytes. Archive digests match the reviewed manifest; all
+  non-manifest files match the reviewed checkout. Public exports, CLI/runtime assets, Apache-2.0
+  licenses and attribution are present. Core has no runtime dependencies; toolkit requires
+  core `^0.4.0`. No forbidden local-state entries or credential-signature matches were found.
+  All 79 original extraction source path/hash pairs are unchanged.
+- A separate offline rehearsal installed those exact archives with lifecycle scripts disabled.
+  Its public fixture produced 54 facts, including four contract consumers, 24 SCIP facts and two
+  public adapter facts. Strict SHACL, immutable repeat reuse and provider-unavailable saved reads
+  passed. This rehearsal is distinct from public-registry acceptance.
+- Fresh public-registry installation passed on Linux/Node 24.19.0 with lifecycle scripts disabled.
+  Its lockfile registry URLs and SHA-512 values match the reviewed archives. The committed public
+  fixture produced 54 total facts, including two semantic facts, four contract consumers, 24 real SCIP facts,
+  two public adapter facts and nine document facts; the impact query returned 53 facts.
+  Cold hydration extracted two artifacts; repeat hydration extracted zero and reused both with
+  identical snapshot identity, content digest and stored bytes. Removing the provider module
+  preserved no-model preview and saved queries, with no additional provider invocations.
+  Fixture commit: `41d0c4fa68f7a358d52471dbbd2a6186adb22fa5`; content digest:
+  `f5a8fbde346d070074164edf970bfd98246c4e34718b43f5850757501daf50ca`.
+
+The installed-package fixture uses a deterministic public provider, actual contract/document
+extractors, real TypeScript SCIP and a public adapter that imports only the core file factory.
+It checks retained citations, digests and authority, strict RDF/SHACL, projection/query results,
+repeat artifact reuse and unchanged snapshot bytes. It makes no live model calls and does not
+establish private adapter correctness, semantic quality or the consumer's full-graph performance.
+The T03/T04 test checkpoints below remain the evidence for operational Codex cache partitioning
+and structured failure handling; ordinary fixture reuse is not a substitute for those tests.
+
+Reviewed and public archive integrity:
+
+| Package | SHA-512 integrity |
+| --- | --- |
+| `@weftlet/core@0.4.0` | `sha512-hNiLpfFaL/o+uQJlRdW+jN/cdMIY8QxTAgwTA7F1kN8f1KhHWH8qsxc4RgC8mP+4huLsWLk8m0v14xrq5prMdA==` |
+| `@weftlet/toolkit@0.4.0` | `sha512-UrHRBuz3v7Olfqk0iaSyvZ1+9xnCHMAjh0ZGj+HWde4zAR0M2zEHjeOxkyC2B2d63gPAqttlQ5kzpauRdfd0Jg==` |
+
 ## T08 deterministic physical-file kinds, 2026-10-26
 
 Implemented after 0.3.0; this checkpoint does not claim npm publication or private consumer

package/docs/extraction-manifest.json

@@ -108,7 +108,7 @@
       "destinationPath": "package.json",
       "sourceSha256": "a575dbb2fed8c554b95e8e9b3e03a0c21cab1be7249860bbebc18e046b2ff78d",
       "modified": true,
-      "destinationSha256": "1e5ae982ffbb2cb02071bbf6c4f8040836dcc451c5e478f10b07cc5646f0e1eb"
+      "destinationSha256": "3e56a3b6a6200e15f684bb490360f2aec0d305dc6c475a176971b188ac5b725d"
     },
     {
       "sourcePath": "tools/context-graph/packages/core/LICENSE",
@@ -143,7 +143,7 @@
       "destinationPath": "packages/core/package.json",
       "sourceSha256": "2a29066eb8452f22fafcb06bb035a84dda93c5705dba32aba600a1b7e5aaf19c",
       "modified": true,
-      "destinationSha256": "090d8d90cbf775e6edf1656215d75200f9961009ef75f2ab4de55fe5603814ea"
+      "destinationSha256": "cde075a193be99f3d50895d9f764e8fd5848f54a2e5acb0155ce69f454bf8623"
     },
     {
       "sourcePath": "tools/context-graph/packages/core/src/core.ts",
@@ -192,7 +192,7 @@
       "destinationPath": "scripts/check-publication.mjs",
       "sourceSha256": "88692c21d34cef2d2e5b20c92ab3ec26cbe6336889dbb7b534c681ded7f466b2",
       "modified": true,
-      "destinationSha256": "2b92ad80a6a193b4628d4caec2bd29b6fbf3c6c97066bda2fe91ceb173d06158"
+      "destinationSha256": "6cc62cdbd4bed65d8eff4749fba7003b3fa59c2e5ddcf8e333950468c40986bf"
     },
     {
       "sourcePath": "tools/context-graph/scripts/generate-third-party-notices.mjs",
@@ -241,21 +241,21 @@
       "destinationPath": "src/interfaces/cli.ts",
       "sourceSha256": "c68f5f35a5325cc03811b0d4ffb6d58c31a9b4e6115fcb2c5e4fda9560a34714",
       "modified": true,
-      "destinationSha256": "c333051df80a274410351b0ba1eef1a1e004f790fa457fd3ebb7909197c4ca29"
+      "destinationSha256": "21cdbc817983e788a5aac48ea8b32c55a7dda98868eb48b5df470c8d99eea44a"
     },
     {
       "sourcePath": "tools/context-graph/src/config.test.ts",
       "destinationPath": "src/configuration/config.test.ts",
       "sourceSha256": "70bcda6d6b48ff6fa03223c9420fe3e0e3e32c688e0a14f11034515e0707dee4",
       "modified": true,
-      "destinationSha256": "ff4d15018ec35d21a95c589cf2c74bce2e340f9042b2d3ecaabca5889609e3aa"
+      "destinationSha256": "f9bedfd754d937023f7d06ff9a0fb8e9e4c9d122178446d2e70ac6914e184156"
     },
     {
       "sourcePath": "tools/context-graph/src/config.ts",
       "destinationPath": "src/configuration/config.ts",
       "sourceSha256": "e9ee8cf2134d274aa6f6a21545959fbec97e958181d9032c073293f28e04d6ca",
       "modified": true,
-      "destinationSha256": "5e34e4dfa38219570bd6f13239609b432830e76162f44a768a929895f66dc02a"
+      "destinationSha256": "7c79bcd696102f89d3dcadaf01ab2311f68b37172b54b21a667de7f15bdec69a"
     },
     {
       "sourcePath": "tools/context-graph/src/core.ts",
@@ -318,14 +318,14 @@
       "destinationPath": "src/application/hydrator.ts",
       "sourceSha256": "bb41c5b53b26da10274d8b967b99c78ff12b485df16bfc66445252e35c94fb9d",
       "modified": true,
-      "destinationSha256": "1833e788ca0c162947c626ff611f724d53f349b8d1dc019f204bd433726f9be9"
+      "destinationSha256": "ef6e21f322915b3bf25589d748f379becea5a0ef188bf875caaca10cc479cd2c"
     },
     {
       "sourcePath": "tools/context-graph/src/index.ts",
       "destinationPath": "src/index.ts",
       "sourceSha256": "a3545649f67fc0bf0496298e3f1dca1e91aa7cb68ec112c34b99a5785fa83f3c",
       "modified": true,
-      "destinationSha256": "2dff4c9bca049dc1607cce7cf709494aae24a7f27b05fcb9353dd19de4546fac"
+      "destinationSha256": "b185467e660715806fc914bef5db068e90199ee32b0226452d4adb4c09991d8b"
     },
     {
       "sourcePath": "tools/context-graph/src/mcp-facade.ts",
@@ -613,6 +613,7 @@
     "docs/ADR-018-operational-semantic-cache.md",
     "docs/ADR-019-semantic-failure-diagnostics.md",
     "docs/ADR-020-canonical-physical-file-producers.md",
+    "docs/ADR-021-identity-preflight-and-validation-timing.md",
     "docs/CLOUD-ENVIRONMENT.md",
     "docs/CONSUMER-TRIAL.md",
     "docs/ENVIRONMENT-VALIDATION.md",
@@ -778,15 +779,19 @@
     "src/governance/governance.ts",
     "src/governance/physical-file-kinds.test.ts",
     "src/graph/authority.ts",
+    "src/graph/identity-preflight.test.ts",
+    "src/graph/identity-preflight.ts",
     "src/graph/ranking.test.ts",
     "src/graph/ranking.ts",
     "src/graph/rdf.ts",
     "src/graph/shacl-shapes.ts",
+    "src/graph/validation-progress.ts",
     "src/infrastructure/module-resolution.ts",
     "src/interfaces/cache-adoption.test.ts",
     "src/interfaces/doctor.ts",
     "src/interfaces/hydration-failure.test.ts",
     "src/interfaces/hydration-plan.test.ts",
+    "src/interfaces/identity-preflight.test.ts",
     "src/interfaces/init.test.ts",
     "src/interfaces/init.ts",
     "src/mcp.ts",
@@ -802,6 +807,7 @@
     "tests/extractor-compatibility.test.ts",
     "tests/hydration-failure.test.ts",
     "tests/hydration-plan.test.ts",
+    "tests/identity-preflight.test.ts",
     "tests/module-boundaries.test.ts",
     "tests/physical-file-kinds.test.ts",
     "tests/rdf-ontology.test.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weftlet/toolkit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Evidence-backed context graphs for AI development agents: product intent, contracts, code, tests and runtime behavior",
   "license": "Apache-2.0",
   "type": "module",
@@ -63,7 +63,7 @@
     "n3": "2.7.2",
     "rdf-validate-shacl": "0.6.5",
     "sparqljs": "3.7.4",
-    "@weftlet/core": "^0.4.0"
+    "@weftlet/core": "^0.5.0"
   },
   "devDependencies": {
     "@changesets/cli": "3.0.3",