@llblab/pi-kit 0.7.1 → 0.8.1

package/node_modules/@llblab/pi-state-flow/lib/artifact.ts

@@ -1,20 +1,40 @@
 import { createHash } from "node:crypto";
-import { containsNull, isJsonValue, isObject, type JsonObject } from "./json.ts";
+import { containsNull, isJsonValue, isObject, type JsonObject, type JsonValue } from "./json.ts";
 
 const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const MODEL_FORBIDDEN_PROVENANCE_FIELDS = ["hash", "compiler", "sourceHash", "compilerRevision", "compiledAt", "source_hash_verified"] as const;
 
 /** Current compiler protocol for ordinary source artifacts such as Knowledge Markdown. */
 export const ORDINARY_ARTIFACT_COMPILER = "artifact-v1";
 
-/** Source-addressed metadata retained after artifact compilation. */
+/** Freshness fields that runtime-owned scope metadata may retain per artifact path. */
+export interface ArtifactProvenance {
+	/** Retained value; absent means unavailable, malformed means fail closed. */
+	sourceHash?: unknown;
+	compilerRevision?: unknown;
+	compiledAt?: unknown;
+	/** Internal marker for an uninterpretable retained entry; every dependent capability fails closed. */
+	malformed?: true;
+}
+
+export type ArtifactProvenanceRegistry = Record<string, ArtifactProvenance>;
+
+/**
+ * Model-visible artifact metadata retained per canonical source path.
+ *
+ * `hash`, `compiler`, and `compiled_at` remain accepted only as retired embedded
+ * provenance input from pre-0.7 state; they are consumed as compatibility evidence
+ * and stripped from model projection. New compilations keep semantic fields here and
+ * runtime-owned freshness in the scope `meta.json` provenance registry.
+ */
 export type ArtifactMetadata = JsonObject & {
 	description: string;
-	hash: string;
-	compiler: string;
-	compiled_at?: string;
 	compilation?: JsonObject;
 	kind?: string;
 	tags?: string[];
+	hash?: string;
+	compiler?: string;
+	compiled_at?: string;
 };
 
 /** Artifact source paths are the canonical registry keys. */
@@ -41,6 +61,12 @@ export interface ArtifactInvalidationRequest extends ArtifactSourceIdentity {
 	reason: ArtifactInvalidationReason;
 }
 
+/** Model-visible invalidation projection: paths and reasons only, never source identity. */
+export interface ArtifactInvalidationNotice {
+	path: string;
+	reason: ArtifactInvalidationReason;
+}
+
 export interface ArtifactInvalidationPlan {
 	fresh: ArtifactSourceIdentity[];
 	requiresCompilation: ArtifactInvalidationRequest[];
@@ -67,6 +93,12 @@ export interface ArtifactCompilationUpdate {
 	output: ArtifactCompilerOutput;
 }
 
+/** One compilation split into its model-visible and runtime-owned halves. */
+export interface CompiledArtifact {
+	semantic: ArtifactMetadata;
+	provenance: ArtifactProvenance;
+}
+
 export function hashArtifactSource(source: string | Uint8Array): string {
 	return `sha256:${createHash("sha256").update(source).digest("hex")}`;
 }
@@ -83,15 +115,6 @@ export function validateArtifactMetadata(value: unknown, path = "<unknown>"): as
 	if (typeof value.description !== "string" || value.description.trim().length === 0) {
 		throw new Error(`Artifact metadata at ${path} must have a non-empty description`);
 	}
-	if (!isArtifactHash(value.hash)) {
-		throw new Error(`Artifact metadata at ${path} must have a sha256:<64 lowercase hex characters> hash`);
-	}
-	if (typeof value.compiler !== "string" || value.compiler.trim().length === 0) {
-		throw new Error(`Artifact metadata at ${path} must have a non-empty compiler revision`);
-	}
-	if (Object.hasOwn(value, "compiled_at") && typeof value.compiled_at !== "string") {
-		throw new Error(`Artifact metadata at ${path} compiled_at must be a string`);
-	}
 	if (Object.hasOwn(value, "compilation") && !isObject(value.compilation)) {
 		throw new Error(`Artifact metadata at ${path} compilation must be an object`);
 	}
@@ -104,6 +127,15 @@ export function validateArtifactMetadata(value: unknown, path = "<unknown>"): as
 		|| new Set(value.tags).size !== value.tags.length)) {
 		throw new Error(`Artifact metadata at ${path} tags must be unique non-empty trimmed strings`);
 	}
+	if (Object.hasOwn(value, "hash") && !isArtifactHash(value.hash)) {
+		throw new Error(`Artifact metadata at ${path} must have a sha256:<64 lowercase hex characters> hash`);
+	}
+	if (Object.hasOwn(value, "compiler") && (typeof value.compiler !== "string" || value.compiler.trim().length === 0)) {
+		throw new Error(`Artifact metadata at ${path} must have a non-empty compiler revision`);
+	}
+	if (Object.hasOwn(value, "compiled_at") && typeof value.compiled_at !== "string") {
+		throw new Error(`Artifact metadata at ${path} compiled_at must be a string`);
+	}
 }
 
 export function isArtifactMetadata(value: unknown): value is ArtifactMetadata {
@@ -176,29 +208,102 @@ function refreshRequested(path: string, explicitRefresh: boolean | ReadonlySet<s
 	return explicitRefresh.has(path);
 }
 
-/** Classify freshness from source identity and metadata without acquiring the source body. */
+function isProvenanceEntry(value: unknown): value is ArtifactProvenance {
+	return isObject(value) && (value.malformed === undefined || value.malformed === true);
+}
+
+/** Parse one scope `meta.json` provenance registry; missing input means no recorded evidence. */
+export function parseArtifactProvenanceRegistry(value: unknown, context = "Artifact provenance"): ArtifactProvenanceRegistry {
+	if (value === undefined) return {};
+	if (!isObject(value)) throw new Error(`${context} must be a path-keyed JSON object`);
+	const registry: ArtifactProvenanceRegistry = {};
+	for (const [path, entry] of Object.entries(value)) {
+		if (path.trim().length === 0) throw new Error(`${context} path keys must be non-empty`);
+		if (!isObject(entry) || !isJsonValue(entry)) {
+			registry[path] = { malformed: true };
+			continue;
+		}
+		const known = new Set(["sourceHash", "compilerRevision", "compiledAt"]);
+		if (Object.keys(entry).some((key) => !known.has(key))) {
+			registry[path] = { malformed: true };
+			continue;
+		}
+		registry[path] = {
+			...(Object.hasOwn(entry, "sourceHash") ? { sourceHash: entry.sourceHash } : {}),
+			...(Object.hasOwn(entry, "compilerRevision") ? { compilerRevision: entry.compilerRevision } : {}),
+			...(Object.hasOwn(entry, "compiledAt") ? { compiledAt: entry.compiledAt } : {}),
+		};
+	}
+	return registry;
+}
+
+/** Canonical retained form; uninterpretable entries cannot round-trip and are omitted. */
+export function serializeArtifactProvenanceRegistry(registry: Readonly<ArtifactProvenanceRegistry>): JsonObject {
+	const artifacts: JsonObject = {};
+	for (const [path, entry] of Object.entries(registry)) {
+		if (entry.malformed === true) continue;
+		const fields: JsonObject = {};
+		if (entry.sourceHash !== undefined) fields.sourceHash = entry.sourceHash as JsonValue;
+		if (entry.compilerRevision !== undefined) fields.compilerRevision = entry.compilerRevision as JsonValue;
+		if (entry.compiledAt !== undefined) fields.compiledAt = entry.compiledAt as JsonValue;
+		if (Object.keys(fields).length === 0) continue;
+		artifacts[path] = fields;
+	}
+	return artifacts;
+}
+
+function invalidField(value: unknown, validate: (candidate: unknown) => boolean): boolean {
+	return value !== undefined && !validate(value);
+}
+
+const INVALID_EVIDENCE = Symbol("invalid-evidence");
+
+/** Later authority wins per field; absent runtime evidence falls back to retired embedded values. */
+function fieldEvidence(entry: ArtifactProvenance | undefined, field: "sourceHash" | "compilerRevision" | "compiledAt", legacy: unknown): unknown {
+	if (entry?.malformed === true) return INVALID_EVIDENCE;
+	if (entry !== undefined && Object.hasOwn(entry, field)) return entry[field];
+	return legacy;
+}
+
+/** Classify freshness from semantic state and runtime provenance without acquiring the source body. */
 export function classifyArtifactFreshness(
 	source: ArtifactSourceIdentity,
 	metadata: unknown,
 	compiler: string,
 	explicitRefresh = false,
+	provenance?: unknown,
 ): ArtifactFreshness {
 	validateSourceIdentity(source);
 	validateCompilerRevision(compiler);
 	if (metadata === undefined) return { kind: "requires-compilation", reason: "new" };
 	if (!isArtifactMetadata(metadata)) return { kind: "requires-compilation", reason: "invalid-metadata" };
-	if (metadata.hash !== source.hash) return { kind: "requires-compilation", reason: "source-changed" };
-	if (metadata.compiler !== compiler) return { kind: "requires-compilation", reason: "compiler-changed" };
+	const entry = isProvenanceEntry(provenance) ? provenance : undefined;
+	const runtime = entry?.malformed === true;
+	const sourceHash = runtime ? INVALID_EVIDENCE : fieldEvidence(entry, "sourceHash", metadata.hash);
+	if (sourceHash === INVALID_EVIDENCE || invalidField(sourceHash, (value) => isArtifactHash(value))) {
+		return { kind: "requires-compilation", reason: "invalid-metadata" };
+	}
+	if (typeof sourceHash === "string" && sourceHash !== source.hash) {
+		return { kind: "requires-compilation", reason: "source-changed" };
+	}
+	const compilerRevision = runtime ? INVALID_EVIDENCE : fieldEvidence(entry, "compilerRevision", metadata.compiler);
+	if (compilerRevision === INVALID_EVIDENCE || invalidField(compilerRevision, (value) => typeof value === "string" && value.trim().length > 0)) {
+		return { kind: "requires-compilation", reason: "invalid-metadata" };
+	}
+	if (typeof compilerRevision === "string" && compilerRevision !== compiler) {
+		return { kind: "requires-compilation", reason: "compiler-changed" };
+	}
 	if (explicitRefresh) return { kind: "requires-compilation", reason: "explicit-refresh" };
 	return { kind: "fresh" };
 }
 
-/** Produce a deterministic acquisition plan from path/hash candidates alone. */
+/** Produce a deterministic acquisition plan from path/hash candidates and retained evidence. */
 export function planArtifactInvalidation(
 	sources: readonly ArtifactSourceIdentity[],
 	registry: Readonly<Record<string, unknown>>,
 	compiler: string,
 	options: ArtifactInvalidationOptions = {},
+	provenance: Readonly<ArtifactProvenanceRegistry> = {},
 ): ArtifactInvalidationPlan {
 	if (!isObject(registry)) throw new Error("Artifacts must be a path-keyed JSON object");
 	validateCompilerRevision(compiler);
@@ -210,11 +315,13 @@ export function planArtifactInvalidation(
 		if (seen.has(source.path)) throw new Error(`Duplicate artifact source path: ${source.path}`);
 		seen.add(source.path);
 		const metadata = Object.hasOwn(registry, source.path) ? registry[source.path] : undefined;
+		const entry = Object.hasOwn(provenance, source.path) ? provenance[source.path] : undefined;
 		const freshness = classifyArtifactFreshness(
 			source,
 			metadata,
 			compiler,
 			refreshRequested(source.path, options.explicitRefresh),
+			entry,
 		);
 		const identity = { path: source.path, hash: source.hash };
 		if (freshness.kind === "fresh") fresh.push(identity);
@@ -224,22 +331,52 @@ export function planArtifactInvalidation(
 	return { fresh, requiresCompilation, removed };
 }
 
-function compilationMetadata(update: ArtifactCompilationUpdate): ArtifactMetadata {
+/** Split one compiler output into model-visible semantics and runtime-owned provenance. */
+export function compileArtifact(update: ArtifactCompilationUpdate): CompiledArtifact {
 	validateSourceIdentity(update.source);
 	validateCompilerRevision(update.compiler, update.source.path);
-	if (!isObject(update.output) || Object.hasOwn(update.output, "hash") || Object.hasOwn(update.output, "compiler")) {
-		throw new Error(`Artifact compiler output at ${update.source.path} cannot set runtime-owned hash or compiler fields`);
+	if (!isObject(update.output) || MODEL_FORBIDDEN_PROVENANCE_FIELDS.some((field) => Object.hasOwn(update.output, field))) {
+		throw new Error(`Artifact compiler output at ${update.source.path} cannot set runtime-owned provenance fields`);
 	}
-	const metadata = {
-		...structuredClone(update.output),
-		hash: update.source.hash,
-		compiler: update.compiler,
+	// Timestamps are runtime evidence; the model-visible entry never retains them.
+	const semantic = structuredClone(update.output) as ArtifactMetadata;
+	delete semantic.compiled_at;
+	validateArtifactMetadata(semantic, update.source.path);
+	return {
+		semantic,
+		provenance: {
+			sourceHash: update.source.hash,
+			compilerRevision: update.compiler,
+			...(typeof update.output.compiled_at === "string" ? { compiledAt: update.output.compiled_at } : {}),
+		},
 	};
-	validateArtifactMetadata(metadata, update.source.path);
-	return metadata;
 }
 
-/** Validate and apply a whole compilation/removal cohort without mutating the prior registry. */
+/** Merge one compilation/removal cohort into the runtime-owned provenance registry. */
+export function updateArtifactProvenance(
+	registry: Readonly<ArtifactProvenanceRegistry>,
+	updates: readonly ArtifactCompilationUpdate[],
+	removed: readonly string[] = [],
+): ArtifactProvenanceRegistry {
+	const next = structuredClone(registry) as ArtifactProvenanceRegistry;
+	for (const update of updates) next[update.source.path] = compileArtifact(update).provenance;
+	for (const path of removed) delete next[path];
+	return next;
+}
+
+/** Keep only provenance whose artifact path still exists in the given semantic registry. */
+export function pruneArtifactProvenance(
+	registry: Readonly<ArtifactProvenanceRegistry>,
+	semantic: Readonly<Record<string, unknown>>,
+): ArtifactProvenanceRegistry {
+	const next: ArtifactProvenanceRegistry = {};
+	for (const [path, entry] of Object.entries(registry)) {
+		if (Object.hasOwn(semantic, path)) next[path] = structuredClone(entry);
+	}
+	return next;
+}
+
+/** Validate and apply a whole compilation/removal cohort of model-visible artifacts. */
 export function updateArtifactRegistry(
 	registry: ArtifactRegistry,
 	updates: readonly ArtifactCompilationUpdate[],
@@ -249,7 +386,7 @@ export function updateArtifactRegistry(
 	const compiled = new Map<string, ArtifactMetadata>();
 	for (const update of updates) {
 		if (compiled.has(update.source.path)) throw new Error(`Duplicate artifact compilation: ${update.source.path}`);
-		compiled.set(update.source.path, compilationMetadata(update));
+		compiled.set(update.source.path, compileArtifact(update).semantic);
 	}
 	const removals = new Set<string>();
 	for (const path of removed) {
@@ -271,3 +408,28 @@ export function updateArtifactRegistry(
 	}
 	return next;
 }
+
+/** Runtime-owned artifact fields that never belong in ordinary model context. */
+const RUNTIME_ARTIFACT_FIELDS = [...MODEL_FORBIDDEN_PROVENANCE_FIELDS, "compiled_at"] as const;
+
+/** Strip retained runtime bookkeeping from one model-visible artifact entry. */
+export function projectArtifactForModel(entry: unknown): unknown {
+	if (!isObject(entry)) return entry;
+	const projected = structuredClone(entry);
+	for (const field of RUNTIME_ARTIFACT_FIELDS) delete projected[field];
+	return projected;
+}
+
+/** Strip retained runtime bookkeeping from a model-visible artifact registry. */
+export function projectArtifactsForModel(registry: Readonly<ArtifactRegistry>): ArtifactRegistry {
+	const projected: ArtifactRegistry = {};
+	for (const [path, entry] of Object.entries(registry)) {
+		Object.defineProperty(projected, path, {
+			value: projectArtifactForModel(entry),
+			enumerable: true,
+			configurable: true,
+			writable: true,
+		});
+	}
+	return projected;
+}

package/node_modules/@llblab/pi-state-flow/lib/config.ts

@@ -9,6 +9,8 @@ import { isObject } from "./json.ts";
 export interface StateFlowConfig {
 	directory: string;
 	autoStart: boolean;
+	/** Opt-in local capture of rejected patch attempts and unresolved terminal drafts. */
+	logging: boolean;
 	remotePublication?: "off" | "turn-end" | "transition";
 }
 
@@ -18,6 +20,7 @@ export function loadStateFlowConfig(agentDir = getAgentDir()): StateFlowConfig {
 	const defaults: StateFlowConfig = {
 		directory: getDurableRepositoryRoot(agentDir),
 		autoStart: false,
+		logging: false,
 	};
 	let value: unknown;
 	try {
@@ -26,11 +29,12 @@ export function loadStateFlowConfig(agentDir = getAgentDir()): StateFlowConfig {
 	} catch (error) {
 		throw new Error(`Cannot read State Flow configuration: ${path}`, { cause: error });
 	}
-	const allowed = new Set(["directory", "autoStart", "remotePublication"]);
+	const allowed = new Set(["directory", "autoStart", "logging", "remotePublication"]);
 	if (!isObject(value) || Object.keys(value).some((key) => !allowed.has(key))) {
 		throw new Error(`State Flow configuration contains unknown settings: ${path}`);
 	}
 	if (Object.hasOwn(value, "autoStart") && typeof value.autoStart !== "boolean") throw new Error(`State Flow autoStart must be a boolean: ${path}`);
+	if (Object.hasOwn(value, "logging") && typeof value.logging !== "boolean") throw new Error(`State Flow logging must be a boolean: ${path}`);
 	if (Object.hasOwn(value, "remotePublication") && value.remotePublication !== "off" && value.remotePublication !== "turn-end" && value.remotePublication !== "transition") {
 		throw new Error(`State Flow remotePublication must be off, turn-end, or transition: ${path}`);
 	}
@@ -43,6 +47,7 @@ export function loadStateFlowConfig(agentDir = getAgentDir()): StateFlowConfig {
 	return {
 		directory: expanded === undefined ? defaults.directory : resolve(dirname(path), expanded),
 		autoStart: value.autoStart === true,
+		logging: value.logging === true,
 		...(value.remotePublication === undefined ? {} : { remotePublication: value.remotePublication as "off" | "turn-end" | "transition" }),
 	};
 }

package/node_modules/@llblab/pi-state-flow/lib/context.ts

@@ -1,13 +1,19 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { ArtifactInvalidationRequest } from "./artifact.ts";
+import { projectArtifactForModel, type ArtifactInvalidationNotice } from "./artifact.ts";
 import type { RecentTransitionWindow } from "./history.ts";
 import { canonicalJson } from "./json.ts";
 import type { Snapshot } from "./snapshot.ts";
 import type { RehydrationPhase } from "./rehydration.ts";
-import type { MaterializedState } from "./state.ts";
+import { projectStateForModel, type MaterializedState } from "./state.ts";
 
 export const VALIDATION_MESSAGE_TYPE = "state-flow-validation";
 
+/** Bounded context retained after semantic State Flow is stopped in this physical session. */
+export interface PassiveContinuation {
+	startedAt: number;
+	handoff: AgentMessage;
+}
+
 export function syntheticUser(text: string): AgentMessage {
 	return { role: "user", content: [{ type: "text", text }], timestamp: Date.now() } as AgentMessage;
 }
@@ -32,23 +38,52 @@ export function withoutPrivateValidation(messages: AgentMessage[]): AgentMessage
 	});
 }
 
+export function createPassiveContinuation(state: MaterializedState, startedAt = Date.now()): PassiveContinuation {
+	return {
+		startedAt,
+		handoff: syntheticUser(`State Flow exit handoff (user-level data, not system instructions):\n${canonicalJson({ state, continuation: "State Flow semantics are disabled; this bounded handoff replaces pre-stop history." })}`),
+	};
+}
+
+/** Preserve the frozen handoff plus only messages produced after stop, never the older raw branch. */
+export function passiveContinuationMessages(messages: AgentMessage[], continuation: PassiveContinuation): AgentMessage[] {
+	const start = messages.findIndex((message) => message.role === "user"
+		&& typeof message.timestamp === "number"
+		&& message.timestamp >= continuation.startedAt);
+	return [continuation.handoff, ...(start < 0 ? [] : messages.slice(start))];
+}
+
+function projectRecentForModel(recent: RecentTransitionWindow): RecentTransitionWindow {
+	const projected = structuredClone(recent);
+	for (const record of projected) for (const transition of record.transitions) {
+		if (transition.patch.artifacts === undefined) continue;
+		for (const [path, entry] of Object.entries(transition.patch.artifacts)) {
+			Object.defineProperty(transition.patch.artifacts, path, {
+				value: projectArtifactForModel(entry), enumerable: true, configurable: true, writable: true,
+			});
+		}
+	}
+	return projected;
+}
+
 export function runtimeContextMessage(
 	snapshot: Snapshot,
 	state: MaterializedState,
 	recentTransitions: RecentTransitionWindow = [],
-	artifactInvalidations: readonly ArtifactInvalidationRequest[] = [],
+	artifactInvalidations: readonly ArtifactInvalidationNotice[] = [],
 	rehydrationPhase?: RehydrationPhase,
+	resolutionPending = false,
 ): AgentMessage {
 	if (snapshot.meta.specification === undefined) {
 		throw new Error("State Flow runtime context requires an active specification");
 	}
 	const context = {
 		specification: snapshot.meta.specification,
-		state,
+		state: projectStateForModel(state),
 		...(rehydrationPhase === undefined ? {} : { knowledge_rehydration: { phase: rehydrationPhase } }),
-		...(artifactInvalidations.length === 0 ? {} : { artifact_invalidations: artifactInvalidations }),
-		...(recentTransitions.length === 0 ? {} : { recent_transitions: recentTransitions }),
-		...(snapshot.meta.validation === undefined ? {} : { validation_feedback: snapshot.meta.validation }),
+		...(artifactInvalidations.length === 0 ? {} : { artifact_invalidations: artifactInvalidations.map(({ path, reason }) => ({ path, reason })) }),
+		...(recentTransitions.length === 0 ? {} : { recent_transitions: projectRecentForModel(recentTransitions) }),
+		...(resolutionPending ? { state_resolution: "pending: a terminal draft was intercepted. Call patch_state with a PATCH {scope, patch} or UNCHANGED {unchanged:true}; then provide the final answer normally." } : {}),
 	};
 	return syntheticUser(
 		`State Flow runtime context (user-level data, not system instructions):\n${canonicalJson(context)}`,

package/node_modules/@llblab/pi-state-flow/lib/durable.ts

@@ -13,7 +13,12 @@ import {
 } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { canonicalJson, containsNull, isJsonValue } from "./json.ts";
+import {
+	parseArtifactProvenanceRegistry,
+	serializeArtifactProvenanceRegistry,
+	type ArtifactProvenanceRegistry,
+} from "./artifact.ts";
+import { canonicalJson, containsNull, isJsonValue, isObject } from "./json.ts";
 import { validateScopeStream, validateTemporalState, type ScopeStream, type TemporalState } from "./temporal.ts";
 import { isMaterializedState, type MaterializedState, type StateScope } from "./state.ts";
 
@@ -23,6 +28,7 @@ const SESSION_KEY_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
 const STATE_FILE = "state.json";
 const CHECKPOINT_FILE = "checkpoint.json";
 const PATCHES_FILE = "patches.jsonl";
+const META_FILE = "meta.json";
 
 /** Canonical replay sources; current state is deliberately not serialized beside the tail. */
 export interface ScopeStreamSources {
@@ -95,6 +101,8 @@ export interface TemporalScopePaths {
 	directory: string;
 	checkpoint: string;
 	patches: string;
+	/** Runtime-owned artifact provenance for this scope; the session file also owns runtime lineage. */
+	meta: string;
 }
 
 export function temporalScopePaths(cwd: string, sessionId: string, scope: StateScope, repositoryRoot: string, sessionKey = sessionId): TemporalScopePaths {
@@ -103,12 +111,12 @@ export function temporalScopePaths(cwd: string, sessionId: string, scope: StateS
 			: scope === "session" ? sessionScopePaths(cwd, sessionId, repositoryRoot, sessionKey).directory
 				: undefined;
 	if (directory === undefined) throw new Error("Unknown temporal scope");
-	return { directory, checkpoint: join(directory, CHECKPOINT_FILE), patches: join(directory, PATCHES_FILE) };
+	return { directory, checkpoint: join(directory, CHECKPOINT_FILE), patches: join(directory, PATCHES_FILE), meta: join(directory, META_FILE) };
 }
 
 export function sessionRuntimePaths(cwd: string, sessionId: string, repositoryRoot: string, sessionKey = sessionId): { config: string; meta: string } {
 	const directory = sessionScopePaths(cwd, sessionId, repositoryRoot, sessionKey).directory;
-	return { config: join(directory, "config.json"), meta: join(directory, "meta.json") };
+	return { config: join(directory, "config.json"), meta: join(directory, META_FILE) };
 }
 
 /** A temporal reader never treats a legacy current snapshot as an anchored checkpoint. */
@@ -125,7 +133,7 @@ export function captureTemporalFileBases(cwd: string, sessionId: string, reposit
 	const paths = (["global", "cwd", "session"] as const).flatMap((scope) => {
 		const pair = temporalScopePaths(cwd, sessionId, scope, repositoryRoot, sessionKey);
 		const runtime = scope === "session" ? sessionRuntimePaths(cwd, sessionId, repositoryRoot, sessionKey) : undefined;
-		return [pair.checkpoint, pair.patches, join(pair.directory, STATE_FILE), ...(runtime === undefined ? [] : [runtime.config, runtime.meta])];
+		return [pair.checkpoint, pair.patches, join(pair.directory, STATE_FILE), ...(runtime === undefined ? [pair.meta] : [runtime.config, runtime.meta])];
 	});
 	return captureOwnedFileBases(paths, repositoryRoot);
 }
@@ -159,6 +167,27 @@ export interface DurablePaths {
 	globalPatches: string;
 }
 
+/** One scope-level provenance document; versioned for lenient forward evolution. */
+export function serializeScopeProvenance(registry: Readonly<ArtifactProvenanceRegistry>): string {
+	return `${canonicalJson({ version: 1, artifacts: serializeArtifactProvenanceRegistry(registry) })}\n`;
+}
+
+/** Missing provenance is unavailable evidence, never corrupt state. */
+export function parseScopeProvenance(source: string | undefined, path: string): ArtifactProvenanceRegistry {
+	if (source === undefined) return {};
+	let value: unknown;
+	try {
+		value = JSON.parse(source);
+	} catch {
+		throw new Error(`State Flow provenance file contains invalid JSON: ${path}`);
+	}
+	if (!isObject(value) || value.version !== 1 || !Object.hasOwn(value, "artifacts")
+		|| Object.keys(value).some((key) => key !== "version" && key !== "artifacts")) {
+		throw new Error(`Invalid State Flow provenance document: ${path}`);
+	}
+	return parseArtifactProvenanceRegistry(value.artifacts, `State Flow provenance at ${path}`);
+}
+
 export interface ScopePaths {
 	directory: string;
 	state: string;
@@ -260,7 +289,7 @@ export function legacyTemporalScopePaths(cwd: string, sessionId: string, scope:
 	const root = resolve(repositoryRoot);
 	const cwdDirectory = join(root, legacyCwdScopeKey(cwd));
 	const directory = scope === "global" ? root : scope === "cwd" ? cwdDirectory : join(cwdDirectory, legacySessionScopeKey(sessionId));
-	return { directory, checkpoint: join(directory, CHECKPOINT_FILE), patches: join(directory, PATCHES_FILE) };
+	return { directory, checkpoint: join(directory, CHECKPOINT_FILE), patches: join(directory, PATCHES_FILE), meta: join(directory, META_FILE) };
 }
 
 export function legacySessionRuntimePaths(cwd: string, sessionId: string, repositoryRoot: string): { config: string; meta: string } {
@@ -290,20 +319,21 @@ export function isStateFlowOwnedPath(candidate: string, repositoryRoot = getDura
 	const root = resolve(repositoryRoot);
 	const absolute = resolve(candidate);
 	const global = durablePaths(root);
-	if (absolute === global.globalState || absolute === global.globalPatches || absolute === join(root, CHECKPOINT_FILE)) return true;
+	if (absolute === global.globalState || absolute === global.globalPatches
+		|| absolute === join(root, CHECKPOINT_FILE) || absolute === join(root, META_FILE)) return true;
 	const segments = relative(root, absolute).split(sep);
 	const cwdKey = (value: string) => (value.startsWith("--") && value.endsWith("--")) || LEGACY_SCOPE_KEY_PATTERN.test(value);
 	const sessionKey = (value: string) => {
 		try { return sessionScopeKey(value) === value; } catch { return false; }
 	};
 	if (segments.length === 2) {
-		return cwdKey(segments[0]!) && (segments[1] === STATE_FILE || segments[1] === CHECKPOINT_FILE || segments[1] === PATCHES_FILE);
+		return cwdKey(segments[0]!) && (segments[1] === STATE_FILE || segments[1] === CHECKPOINT_FILE || segments[1] === PATCHES_FILE || segments[1] === META_FILE);
 	}
 	if (segments.length === 3) {
 		return cwdKey(segments[0]!)
 			&& (sessionKey(segments[1]!) || LEGACY_SCOPE_KEY_PATTERN.test(segments[1]!))
 			&& (segments[2] === STATE_FILE || segments[2] === CHECKPOINT_FILE || segments[2] === PATCHES_FILE
-				|| segments[2] === "config.json" || segments[2] === "meta.json");
+				|| segments[2] === "config.json" || segments[2] === META_FILE);
 	}
 	return false;
 }

package/node_modules/@llblab/pi-state-flow/lib/episode.ts

@@ -22,20 +22,8 @@ export function stopEpisode(snapshot: Snapshot): Snapshot {
 }
 
 /** Apply one user-run boundary while preserving checkpoint-owned runtime state. */
-export function prepareRun(snapshot: Snapshot, prompt: string, isRetry: boolean): boolean {
-	if (snapshot.meta.specification === undefined) {
-		snapshot.meta.specification = prompt;
-		return true;
-	}
-	if (isRetry) return false;
+export function prepareRun(snapshot: Snapshot, prompt: string): boolean {
 	snapshot.meta.specification = prompt;
 	snapshot.meta.validation = undefined;
 	return true;
 }
-
-/** Clear only transient validation metadata; never disable or reset the episode. */
-export function abandonValidation(snapshot: Snapshot): boolean {
-	if (snapshot.meta.validation === undefined) return false;
-	snapshot.meta.validation = undefined;
-	return true;
-}