@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/session/manager.ts

@@ -0,0 +1,128 @@
+import { v7 as uuidv7 } from "uuid";
+import { stateRootRemoved } from "../../core/xdg.js";
+import {
+	atomicWrite,
+	type ClioSessionWriter,
+	type ClioTurnRecord,
+	createSession as engineCreateSession,
+	resumeSession as engineResumeSession,
+	readSessionMeta,
+	type SessionTreeNode,
+	sessionPaths,
+} from "../../engine/session.js";
+import type { SessionEntryInput, SessionMeta, TurnInput } from "./contract.js";
+import { isSessionEntry, type SessionEntry } from "./entries.js";
+import { runMigrations } from "./migrations/index.js";
+
+/**
+ * Wraps engine/session.ts so the session domain can track the single in-memory
+ * current writer + meta. Turn writes go through the engine writer (`append` /
+ * `appendEntry`); metadata-only updates use `persistSessionMeta` so domain
+ * extensions can make newly attached metadata durable without closing.
+ */
+
+export interface SessionManagerState {
+	meta: SessionMeta;
+	writer: ClioSessionWriter;
+}
+
+/**
+ * Generate a v7 UUID for session and turn ids. RFC 9562 § 5.7 defines a 48-bit
+ * unix-ms timestamp prefix makes the ids time-sortable, which lets
+ * history()/tree() order by creation without a separate timestamp index.
+ */
+export function newTurnId(): string {
+	return uuidv7();
+}
+
+export function startSession(input: {
+	cwd: string;
+	model?: string | null;
+	target?: string | null;
+	initialEntries?: ReadonlyArray<unknown>;
+	initialTree?: ReadonlyArray<SessionTreeNode>;
+	parentSession?: string;
+	parentTurnId?: string;
+}): SessionManagerState {
+	const { meta, writer } = engineCreateSession({
+		cwd: input.cwd,
+		model: input.model ?? null,
+		target: input.target ?? null,
+		...(input.initialEntries !== undefined ? { initialEntries: input.initialEntries } : {}),
+		...(input.initialTree !== undefined ? { initialTree: input.initialTree } : {}),
+		...(input.parentSession !== undefined ? { parentSession: input.parentSession } : {}),
+		...(input.parentTurnId !== undefined ? { parentTurnId: input.parentTurnId } : {}),
+	});
+	return { meta: meta as SessionMeta, writer };
+}
+
+export function persistSessionMeta(state: SessionManagerState): void {
+	// The other meta.json writer. `sessionPaths` mkdirs on the way, so a metadata
+	// update landing after `clio-coder uninstall` rebuilds the state root the same way
+	// the shutdown checkpoint did. See core/xdg.ts stateRootRemoved().
+	if (stateRootRemoved()) return;
+	atomicWrite(sessionPaths(state.meta).meta, JSON.stringify(state.meta, null, 2));
+}
+
+export function resumeSessionState(sessionId: string): {
+	state: SessionManagerState;
+	nodes: ReadonlyArray<SessionTreeNode>;
+} {
+	const persistedMeta = readSessionMeta(sessionId) as SessionMeta;
+	const paths = sessionPaths(persistedMeta);
+	runMigrations(persistedMeta, paths.meta);
+	const { meta, writer, tree } = engineResumeSession(sessionId);
+	return { state: { meta: meta as SessionMeta, writer }, nodes: tree };
+}
+
+export function appendTurn(state: SessionManagerState, input: TurnInput): ClioTurnRecord {
+	const record: ClioTurnRecord = {
+		id: input.id ?? newTurnId(),
+		parentId: input.parentId,
+		at: input.at ?? new Date().toISOString(),
+		kind: input.kind,
+		payload: input.payload,
+	};
+	const entry: SessionEntry = {
+		kind: "message",
+		turnId: record.id,
+		parentTurnId: record.parentId,
+		timestamp: record.at,
+		role: record.kind,
+		payload: record.payload,
+	};
+	state.writer.appendEntry(entry, {
+		treeNode: {
+			id: record.id,
+			parentId: record.parentId,
+			at: record.at,
+			kind: record.kind,
+		},
+	});
+	return record;
+}
+
+/**
+ * Append a rich SessionEntry via the engine writer. Non-message kinds are
+ * written as JSON lines to current.jsonl; they do not project into tree.json
+ * in slice 12a. Slice 12b extends the tree model so /fork can pick non-message
+ * branch points too.
+ */
+export function appendEntry(state: SessionManagerState, input: SessionEntryInput): SessionEntry {
+	const turnId = input.turnId ?? newTurnId();
+	const timestamp = input.timestamp ?? new Date().toISOString();
+	// Re-assemble the entry with canonical turnId + timestamp. The caller's
+	// kind-specific fields pass through via the spread; the union's structural
+	// shape is preserved because `input` is SessionEntryInput (distributed).
+	const entry = { ...input, turnId, timestamp } as SessionEntry;
+	if (!isSessionEntry(entry)) throw new Error(`session.appendEntry: invalid ${String(input.kind)} entry`);
+	state.writer.appendEntry(entry);
+	return entry;
+}
+
+export function replaceEntries(state: SessionManagerState, entries: ReadonlyArray<SessionEntry>): void {
+	for (const entry of entries) {
+		if (!isSessionEntry(entry)) throw new Error("session.replaceEntries: invalid entry");
+	}
+	state.writer.replaceEntries(entries);
+}

package/src/domains/session/manifest.ts

@@ -0,0 +1,6 @@
+import type { DomainManifest } from "../../core/domain-loader.js";
+
+export const SessionManifest: DomainManifest = {
+	name: "session",
+	dependsOn: ["config"],
+};

package/src/domains/session/migrations/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Strict session-format version reader.
+ *
+ * Runs before every session resume. Earlier pre-1.0 formats are disposable
+ * local state and must not be transformed into the current format.
+ */
+
+import { CURRENT_SESSION_FORMAT_VERSION } from "../../../engine/session.js";
+import type { SessionMeta } from "../contract.js";
+
+export { CURRENT_SESSION_FORMAT_VERSION };
+
+export interface MigrationResult {
+	migrated: boolean;
+	from: number;
+	to: number;
+}
+
+export function runMigrations(meta: SessionMeta, sessionPath: string): MigrationResult {
+	const from = meta.sessionFormatVersion ?? 1;
+	if (from < CURRENT_SESSION_FORMAT_VERSION) {
+		throw new Error(
+			`session metadata has an unsupported format version (expected version 3, got ${from}): ${sessionPath}. Remove the session directory to start a new session.`,
+		);
+	}
+	return { migrated: false, from, to: from };
+}

package/src/domains/session/prompt-manifest.ts

@@ -0,0 +1,173 @@
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { cwdHash, sessionPaths } from "../../engine/session.js";
+import type { ProjectPreloadClass } from "../prompts/preload.js";
+import type { SessionMeta } from "./contract.js";
+
+/**
+ * Per-session prompt-manifest ledger. Every prompt compile whose text
+ * changed appends one record to `prompt-manifest.jsonl`, a sibling of
+ * `current.jsonl`, so a finished session's stored artifacts alone state the
+ * exact system-prompt hash, section breakdown, fragment versions, and the
+ * thinking dial active at compile time. The record is a manifest, never the
+ * prompt text: hashes and token estimates keep it cheap while two sessions
+ * stay diffable without recompiling anything.
+ */
+
+export interface PromptManifestSection {
+	id: string;
+	tokenEstimate: number;
+}
+
+export interface PromptManifestFragment {
+	id: string;
+	relPath: string;
+	contentHash: string;
+	dynamic: boolean;
+}
+
+export interface SessionPromptCompileRecord {
+	/** ISO timestamp of the compile. */
+	at: string;
+	/** Hash of the previously served prompt, null on the first compile. */
+	previousHash: string | null;
+	systemPromptHash: string;
+	tokenEstimate: number;
+	/** Thinking dial applied to the live agent when this prompt was compiled. */
+	thinkingLevel: string | null;
+	projectPreload: ProjectPreloadClass | null;
+	sections: PromptManifestSection[];
+	fragments: PromptManifestFragment[];
+}
+
+export interface PromptManifestReadError {
+	line: number | null;
+	message: string;
+}
+
+export interface PromptManifestReadResult {
+	records: SessionPromptCompileRecord[];
+	errors: PromptManifestReadError[];
+}
+
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+
+/**
+ * Canonical UTC only, the same rule capacity-lease.ts and memory/validate.ts
+ * enforce. The previous regex accepted `+05:30` offsets, which parse to a valid
+ * instant but sort wrong against a `Z` row, and manifest records are read back
+ * in file order and compared as strings.
+ */
+function isCanonicalUtcTimestamp(value: unknown): value is string {
+	if (typeof value !== "string") return false;
+	const timestamp = Date.parse(value);
+	return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function isSha256(value: unknown): value is string {
+	return typeof value === "string" && SHA256_HEX.test(value);
+}
+
+function isPromptManifestSection(value: unknown): value is PromptManifestSection {
+	return isRecord(value) && typeof value.id === "string" && isNonNegativeInteger(value.tokenEstimate);
+}
+
+function isPromptManifestFragment(value: unknown): value is PromptManifestFragment {
+	return (
+		isRecord(value) &&
+		typeof value.id === "string" &&
+		typeof value.relPath === "string" &&
+		isSha256(value.contentHash) &&
+		typeof value.dynamic === "boolean"
+	);
+}
+
+function isProjectPreloadClass(value: unknown): value is ProjectPreloadClass {
+	if (!isRecord(value)) return false;
+	return (
+		(value.mode === "full" || value.mode === "synopsis" || value.mode === "none") &&
+		isNonNegativeInteger(value.chars) &&
+		isNonNegativeInteger(value.lines) &&
+		(value.reason === null || value.reason === "size" || value.reason === "lines" || value.reason === "no-clio-md") &&
+		typeof value.nearLimit === "boolean" &&
+		typeof value.label === "string"
+	);
+}
+
+function isSessionPromptCompileRecord(value: unknown): value is SessionPromptCompileRecord {
+	if (!isRecord(value)) return false;
+	return (
+		isCanonicalUtcTimestamp(value.at) &&
+		(value.previousHash === null || isSha256(value.previousHash)) &&
+		isSha256(value.systemPromptHash) &&
+		isNonNegativeInteger(value.tokenEstimate) &&
+		(value.thinkingLevel === null || typeof value.thinkingLevel === "string") &&
+		(value.projectPreload === null || isProjectPreloadClass(value.projectPreload)) &&
+		Array.isArray(value.sections) &&
+		value.sections.every(isPromptManifestSection) &&
+		Array.isArray(value.fragments) &&
+		value.fragments.every(isPromptManifestFragment)
+	);
+}
+
+export function getPromptManifestFilePath(meta: SessionMeta, stateDir?: string): string {
+	const safeMeta = {
+		...meta,
+		cwdHash: meta.cwdHash || cwdHash(meta.cwd || process.cwd()),
+	};
+	if (stateDir !== undefined) {
+		return join(stateDir, "sessions", safeMeta.cwdHash, safeMeta.id, "prompt-manifest.jsonl");
+	}
+	const paths = sessionPaths(safeMeta);
+	return join(dirname(paths.current), "prompt-manifest.jsonl");
+}
+
+/** Best-effort append; prompt provenance must never abort a turn. */
+export function appendPromptCompileRecord(meta: SessionMeta, record: SessionPromptCompileRecord): void {
+	try {
+		const file = getPromptManifestFilePath(meta);
+		appendFileSync(file, `${JSON.stringify(record)}\n`, "utf8");
+	} catch {
+		// Disk pressure or permissions; the live session keeps running.
+	}
+}
+
+export function readPromptCompileManifest(meta: SessionMeta, stateDir?: string): PromptManifestReadResult {
+	const file = getPromptManifestFilePath(meta, stateDir);
+	try {
+		if (!existsSync(file)) return { records: [], errors: [] };
+		const records: SessionPromptCompileRecord[] = [];
+		const errors: PromptManifestReadError[] = [];
+		for (const [index, line] of readFileSync(file, "utf8").split("\n").entries()) {
+			if (line.trim().length === 0) continue;
+			try {
+				const parsed: unknown = JSON.parse(line);
+				if (isSessionPromptCompileRecord(parsed)) {
+					records.push(parsed);
+				} else {
+					errors.push({ line: index + 1, message: "invalid prompt manifest record" });
+				}
+			} catch {
+				errors.push({ line: index + 1, message: "invalid JSON" });
+			}
+		}
+		return { records, errors };
+	} catch (err) {
+		return {
+			records: [],
+			errors: [{ line: null, message: err instanceof Error ? err.message : String(err) }],
+		};
+	}
+}
+
+export function readPromptCompileRecords(meta: SessionMeta): SessionPromptCompileRecord[] {
+	return readPromptCompileManifest(meta).records;
+}

package/src/domains/session/protected-artifact-journal.ts

@@ -0,0 +1,241 @@
+/**
+ * Write-ahead durability for protected-artifact registrations.
+ *
+ * A middleware protection becomes live before the session ledger append can
+ * complete. Stage it here first so an append fault cannot erase the hard
+ * block on reset or process restart. Successful ledger appends remove the
+ * staged file; startup/session reload reconciles any remainder before it
+ * declares the protection state trustworthy.
+ */
+
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { clioStateDir } from "../../core/xdg.js";
+import { atomicWrite } from "../../engine/session.js";
+import type { ProtectedArtifact } from "../safety/protected-artifacts.js";
+import type { ProtectedArtifactProtectEvent } from "../safety/protected-artifacts-registration.js";
+import type { SessionContract } from "./contract.js";
+import { protectedArtifactEntryFromArtifact } from "./protected-artifacts.js";
+
+export interface PendingProtectedArtifactRecord {
+	version: 1;
+	id: string;
+	sessionId: string;
+	artifact: ProtectedArtifact;
+	context: {
+		parentTurnId: string | null;
+		toolName: string;
+		toolCallId?: string;
+		runId?: string;
+		correlationId?: string;
+	};
+	createdAt: string;
+	integrity: { algorithm: "sha256"; digest: string };
+}
+
+export interface PendingProtectedArtifactHandle {
+	record: PendingProtectedArtifactRecord;
+	path: string;
+}
+
+export interface PendingProtectedArtifactReadResult {
+	records: PendingProtectedArtifactHandle[];
+	errors: Array<{ path: string; message: string }>;
+}
+
+function sessionKey(sessionId: string): string {
+	return createHash("sha256").update(sessionId, "utf8").digest("hex");
+}
+
+function journalDirectory(sessionId: string): string {
+	return join(clioStateDir(), "protected-artifact-pending", sessionKey(sessionId));
+}
+
+function artifactPayload(artifact: ProtectedArtifact): Record<string, unknown> {
+	return {
+		path: artifact.path,
+		protectedAt: artifact.protectedAt,
+		reason: artifact.reason,
+		source: artifact.source,
+		...(artifact.validationCommand !== undefined ? { validationCommand: artifact.validationCommand } : {}),
+		...(artifact.validationExitCode !== undefined ? { validationExitCode: artifact.validationExitCode } : {}),
+	};
+}
+
+function recordPayload(record: Omit<PendingProtectedArtifactRecord, "integrity">): Record<string, unknown> {
+	return {
+		contract: "clio.protectedArtifact.pending",
+		version: record.version,
+		id: record.id,
+		sessionId: record.sessionId,
+		artifact: artifactPayload(record.artifact),
+		context: {
+			parentTurnId: record.context.parentTurnId,
+			toolName: record.context.toolName,
+			...(record.context.toolCallId !== undefined ? { toolCallId: record.context.toolCallId } : {}),
+			...(record.context.runId !== undefined ? { runId: record.context.runId } : {}),
+			...(record.context.correlationId !== undefined ? { correlationId: record.context.correlationId } : {}),
+		},
+		createdAt: record.createdAt,
+	};
+}
+
+function digest(record: Omit<PendingProtectedArtifactRecord, "integrity">): string {
+	return createHash("sha256")
+		.update(JSON.stringify(recordPayload(record)), "utf8")
+		.digest("hex");
+}
+
+function withoutIntegrity(record: PendingProtectedArtifactRecord): Omit<PendingProtectedArtifactRecord, "integrity"> {
+	return {
+		version: record.version,
+		id: record.id,
+		sessionId: record.sessionId,
+		artifact: { ...record.artifact },
+		context: { ...record.context },
+		createdAt: record.createdAt,
+	};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseRecord(value: unknown, sessionId: string): PendingProtectedArtifactRecord | null {
+	if (!isRecord(value) || value.version !== 1 || value.sessionId !== sessionId) return null;
+	if (
+		typeof value.id !== "string" ||
+		value.id.length === 0 ||
+		typeof value.createdAt !== "string" ||
+		!isRecord(value.artifact) ||
+		typeof value.artifact.path !== "string" ||
+		typeof value.artifact.protectedAt !== "string" ||
+		typeof value.artifact.reason !== "string" ||
+		(value.artifact.source !== "validation" &&
+			value.artifact.source !== "middleware" &&
+			value.artifact.source !== "user" &&
+			value.artifact.source !== "session") ||
+		!isRecord(value.context) ||
+		(value.context.parentTurnId !== null && typeof value.context.parentTurnId !== "string") ||
+		typeof value.context.toolName !== "string" ||
+		!isRecord(value.integrity) ||
+		value.integrity.algorithm !== "sha256" ||
+		typeof value.integrity.digest !== "string"
+	) {
+		return null;
+	}
+	const artifact: ProtectedArtifact = {
+		path: value.artifact.path,
+		protectedAt: value.artifact.protectedAt,
+		reason: value.artifact.reason,
+		source: value.artifact.source,
+	};
+	if (typeof value.artifact.validationCommand === "string") {
+		artifact.validationCommand = value.artifact.validationCommand;
+	}
+	if (typeof value.artifact.validationExitCode === "number") {
+		artifact.validationExitCode = value.artifact.validationExitCode;
+	}
+	const context: PendingProtectedArtifactRecord["context"] = {
+		parentTurnId: value.context.parentTurnId,
+		toolName: value.context.toolName,
+	};
+	if (typeof value.context.toolCallId === "string") context.toolCallId = value.context.toolCallId;
+	if (typeof value.context.runId === "string") context.runId = value.context.runId;
+	if (typeof value.context.correlationId === "string") context.correlationId = value.context.correlationId;
+	const parsed: PendingProtectedArtifactRecord = {
+		version: 1,
+		id: value.id,
+		sessionId,
+		artifact,
+		context,
+		createdAt: value.createdAt,
+		integrity: { algorithm: "sha256", digest: value.integrity.digest },
+	};
+	return digest(withoutIntegrity(parsed)) === parsed.integrity.digest ? parsed : null;
+}
+
+export function stagePendingProtectedArtifact(
+	sessionId: string,
+	event: ProtectedArtifactProtectEvent,
+): PendingProtectedArtifactHandle {
+	const id = `${Date.now().toString(36)}-${randomBytes(8).toString("hex")}`;
+	const without: Omit<PendingProtectedArtifactRecord, "integrity"> = {
+		version: 1,
+		id,
+		sessionId,
+		artifact: { ...event.artifact },
+		context: {
+			parentTurnId: event.turnId ?? null,
+			toolName: event.toolName,
+			...(event.toolCallId !== undefined ? { toolCallId: event.toolCallId } : {}),
+			...(event.runId !== undefined ? { runId: event.runId } : {}),
+			...(event.correlationId !== undefined ? { correlationId: event.correlationId } : {}),
+		},
+		createdAt: new Date().toISOString(),
+	};
+	const record: PendingProtectedArtifactRecord = {
+		...without,
+		integrity: { algorithm: "sha256", digest: digest(without) },
+	};
+	const directory = journalDirectory(sessionId);
+	mkdirSync(directory, { recursive: true });
+	const path = join(directory, `${id}.json`);
+	atomicWrite(path, JSON.stringify(record, null, 2));
+	return { record, path };
+}
+
+export function clearPendingProtectedArtifact(handle: PendingProtectedArtifactHandle): void {
+	rmSync(handle.path, { force: true });
+}
+
+export function readPendingProtectedArtifacts(sessionId: string): PendingProtectedArtifactReadResult {
+	const directory = journalDirectory(sessionId);
+	if (!existsSync(directory)) return { records: [], errors: [] };
+	const records: PendingProtectedArtifactHandle[] = [];
+	const errors: PendingProtectedArtifactReadResult["errors"] = [];
+	for (const name of readdirSync(directory)
+		.filter((entry) => entry.endsWith(".json"))
+		.sort()) {
+		const path = join(directory, name);
+		try {
+			const parsed = parseRecord(JSON.parse(readFileSync(path, "utf8")) as unknown, sessionId);
+			if (parsed === null) throw new Error("invalid or integrity-mismatched pending protection");
+			records.push({ record: parsed, path });
+		} catch (error) {
+			errors.push({ path, message: error instanceof Error ? error.message : String(error) });
+		}
+	}
+	return { records, errors };
+}
+
+export function reconcilePendingProtectedArtifacts(session: SessionContract): number {
+	const current = session.current();
+	if (current === null) return 0;
+	const pending = readPendingProtectedArtifacts(current.id);
+	if (pending.errors.length > 0) {
+		throw new Error(
+			`pending protection journal is untrustworthy: ${pending.errors.map((entry) => entry.message).join("; ")}`,
+		);
+	}
+	for (const handle of pending.records) {
+		session.appendEntry(
+			protectedArtifactEntryFromArtifact(handle.record.artifact, {
+				parentTurnId: handle.record.context.parentTurnId,
+				toolName: handle.record.context.toolName,
+				...(handle.record.context.toolCallId !== undefined ? { toolCallId: handle.record.context.toolCallId } : {}),
+				...(handle.record.context.runId !== undefined ? { runId: handle.record.context.runId } : {}),
+				...(handle.record.context.correlationId !== undefined
+					? { correlationId: handle.record.context.correlationId }
+					: {}),
+			}),
+		);
+		if (session.flushAppends === undefined) {
+			throw new Error("session does not expose the durable append flush required by protection reconciliation");
+		}
+		session.flushAppends();
+		clearPendingProtectedArtifact(handle);
+	}
+	return pending.records.length;
+}

package/src/domains/session/protected-artifacts.ts

@@ -0,0 +1,90 @@
+import { type ProtectedArtifact, type ProtectedArtifactState, protectArtifact } from "../safety/protected-artifacts.js";
+import type { ProtectedArtifactEntry, ProtectedArtifactEntryArtifact, SessionEntry } from "./entries.js";
+
+export interface ProtectedArtifactEntryContext {
+	parentTurnId: string | null;
+	toolName?: string;
+	toolCallId?: string;
+	runId?: string;
+	correlationId?: string;
+}
+
+export type ProtectedArtifactEntryInput = Omit<ProtectedArtifactEntry, "turnId" | "timestamp"> & {
+	turnId?: string;
+	timestamp?: string;
+};
+
+export function protectedArtifactEntryFromArtifact(
+	artifact: ProtectedArtifact,
+	context: ProtectedArtifactEntryContext,
+): ProtectedArtifactEntryInput {
+	const entry: ProtectedArtifactEntryInput = {
+		kind: "protectedArtifact",
+		parentTurnId: context.parentTurnId,
+		action: "protect",
+		artifact: artifactSnapshot(artifact),
+	};
+	if (context.toolName !== undefined) entry.toolName = context.toolName;
+	if (context.toolCallId !== undefined) entry.toolCallId = context.toolCallId;
+	if (context.runId !== undefined) entry.runId = context.runId;
+	if (context.correlationId !== undefined) entry.correlationId = context.correlationId;
+	return entry;
+}
+
+export function protectedArtifactFromSessionEntry(entry: ProtectedArtifactEntry): ProtectedArtifact {
+	return protectedArtifactFromSnapshot(entry.artifact);
+}
+
+export function protectedArtifactStateFromSessionEntries(entries: ReadonlyArray<SessionEntry>): ProtectedArtifactState {
+	let state: ProtectedArtifactState = { artifacts: [] };
+	const protectedEntries = entries
+		.map((entry, index) => ({ entry, index }))
+		.filter((item): item is { entry: ProtectedArtifactEntry; index: number } => item.entry.kind === "protectedArtifact")
+		.sort(compareProtectedEntryPositions);
+	for (const item of protectedEntries) {
+		if (item.entry.action !== "protect") continue;
+		state = protectArtifact(state, protectedArtifactFromSessionEntry(item.entry));
+	}
+	return state;
+}
+
+function artifactSnapshot(artifact: ProtectedArtifact): ProtectedArtifactEntryArtifact {
+	const snapshot: ProtectedArtifactEntryArtifact = {
+		path: artifact.path,
+		protectedAt: artifact.protectedAt,
+		reason: artifact.reason,
+		source: artifact.source,
+	};
+	if (artifact.validationCommand !== undefined) snapshot.validationCommand = artifact.validationCommand;
+	if (artifact.validationExitCode !== undefined) snapshot.validationExitCode = artifact.validationExitCode;
+	return snapshot;
+}
+
+function protectedArtifactFromSnapshot(snapshot: ProtectedArtifactEntryArtifact): ProtectedArtifact {
+	const artifact: ProtectedArtifact = {
+		path: snapshot.path,
+		protectedAt: snapshot.protectedAt,
+		reason: snapshot.reason,
+		source: snapshot.source,
+	};
+	if (snapshot.validationCommand !== undefined) artifact.validationCommand = snapshot.validationCommand;
+	if (snapshot.validationExitCode !== undefined) artifact.validationExitCode = snapshot.validationExitCode;
+	return artifact;
+}
+
+function compareProtectedEntryPositions(
+	left: { entry: ProtectedArtifactEntry; index: number },
+	right: { entry: ProtectedArtifactEntry; index: number },
+): number {
+	return (
+		compareStrings(left.entry.timestamp, right.entry.timestamp) ||
+		compareStrings(left.entry.turnId, right.entry.turnId) ||
+		left.index - right.index
+	);
+}
+
+function compareStrings(left: string, right: string): number {
+	if (left < right) return -1;
+	if (left > right) return 1;
+	return 0;
+}