@gajae-code/coding-agent 0.12.0 → 0.12.1

package/scripts/resident-memory-bench.ts

@@ -0,0 +1,1341 @@
+/**
+ * Pinned, child-isolated resident-cache benchmark.
+ *
+ * Each `--runs` repetition executes in a fresh Bun child. The default fixture is
+ * 5,000 deterministic, unique 48 KiB messages; use the small overrides only for
+ * local smoke checks, not performance comparisons.
+ *
+ * Normal measurements (five child runs per command):
+ *   TMPDIR="$HOME/tmp-gjc-tests/" GJC_CODING_AGENT_DIR="$(mktemp -d)" NO_COLOR=1 bun packages/coding-agent/scripts/resident-memory-bench.ts --mode rss --runs 5
+ *   TMPDIR="$HOME/tmp-gjc-tests/" GJC_CODING_AGENT_DIR="$(mktemp -d)" NO_COLOR=1 bun packages/coding-agent/scripts/resident-memory-bench.ts --mode put-latency --runs 5
+ *   TMPDIR="$HOME/tmp-gjc-tests/" GJC_CODING_AGENT_DIR="$(mktemp -d)" NO_COLOR=1 bun packages/coding-agent/scripts/resident-memory-bench.ts --mode read-churn --runs 5
+ *
+ * HEAD forced-rebuild baseline (copy this script to the pinned HEAD worktree):
+ *   git worktree add /tmp/gjc-bench-head 3649db42e
+ *   TMPDIR="$HOME/tmp-gjc-tests/" GJC_CODING_AGENT_DIR="$(mktemp -d)" NO_COLOR=1 bun packages/coding-agent/scripts/resident-memory-bench.ts --mode read-churn --baseline forced-rebuild --runs 5
+ *
+ * Small smoke fixture and deliberate invalid-run demonstration:
+ *   TMPDIR="$HOME/tmp-gjc-tests/" GJC_CODING_AGENT_DIR="$(mktemp -d)" NO_COLOR=1 bun packages/coding-agent/scripts/resident-memory-bench.ts --mode rss --entries 8 --bytes-per-entry 4096 --runs 1
+ *   TMPDIR="$HOME/tmp-gjc-tests/" GJC_CODING_AGENT_DIR="$(mktemp -d)" NO_COLOR=1 bun packages/coding-agent/scripts/resident-memory-bench.ts --mode put-latency --puts 64 --runs 1
+ *   TMPDIR="$HOME/tmp-gjc-tests/" GJC_CODING_AGENT_DIR="$(mktemp -d)" NO_COLOR=1 bun packages/coding-agent/scripts/resident-memory-bench.ts --mode read-churn --entries 8 --bytes-per-entry 4096 --cache-cap-bytes 1024 --runs 1
+ *   TMPDIR="$HOME/tmp-gjc-tests/" GJC_CODING_AGENT_DIR="$(mktemp -d)" NO_COLOR=1 bun packages/coding-agent/scripts/resident-memory-bench.ts --mode read-churn --entries 8 --bytes-per-entry 4096 --cache-cap-bytes 1024 --skip-gc --runs 1
+ *   TMPDIR="$HOME/tmp-gjc-tests/" GJC_CODING_AGENT_DIR="$(mktemp -d)" NO_COLOR=1 bun packages/coding-agent/scripts/resident-memory-bench.ts --mode rss --force-memory-only --runs 1
+ *
+ * `--skip-gc` deliberately bypasses the required turn boundary and forced GC;
+ * the --skip-gc command must exit non-zero with the invalid-run diagnostic. Do not
+ * use it for measurements. `--baseline` is an alias for `--baseline forced-rebuild`.
+ * `--force-memory-only` is bench-only: it poisons the isolated cache root to
+ * exercise the existing fallback and is not a supported product configuration.
+ * RSS mode reports append-phase and fresh-process reopen measurements with the full
+ * `process.memoryUsage()` breakdown, plus repeated forced-GC idle-turn reclaim samples.
+ * AC-1 passes only when append steady-state RSS delta stays within 100 MiB; a
+ * post-reclaim result within that limit is separately labeled documented evidence. AC-2
+ * measures direct `putSync` calls over pre-generated unique Buffers into a
+ * canonical MemoryBlobStore and an adopted verified EphemeralBlobStore.
+ * SessionManager append figures are separate `e2eAppend` diagnostics. A direct
+ * store ratio above 1.5x is documented evidence, not a relaxation of the
+ * secure O_EXCL|O_NOFOLLOW, owner-only, lazy-EEXIST verification contract.
+ */
+
+import type * as nodeFs from "node:fs";
+import * as fs from "node:fs/promises";
+import { createRequire, syncBuiltinESMExports } from "node:module";
+import * as os from "node:os";
+import * as path from "node:path";
+import { EphemeralBlobStore, MemoryBlobStore, openVerifiedResidentCacheInstanceDir } from "../src/session/blob-store";
+import type {
+	SessionManagerObservabilityStats,
+	SessionManager as SessionManagerType,
+} from "../src/session/session-manager";
+import * as sessionManagerModule from "../src/session/session-manager";
+
+const { SessionManager } = sessionManagerModule;
+
+const SCHEMA_VERSION = 4;
+const SYNTHETIC_SEED = 0x5eedc0de;
+const DEFAULT_RUNS = 5;
+const RSS_ENTRY_COUNT = 5_000;
+const RSS_BYTES_PER_ENTRY = 48 * 1024;
+const READ_CHURN_CYCLES = 100;
+const PUT_WARMUP_ITERATIONS = 1_000;
+const PUT_MEASURE_ITERATIONS = 10_000;
+const PUT_BYTES = 4 * 1024;
+const BASELINE_MARKER_BYTES = 128;
+const AC1_APPEND_PHASE_RSS_LIMIT_BYTES = 100 * 1024 * 1024;
+const MEMORY_RECLAIM_GC_ROUNDS = 4;
+const SYNTHETIC_TEXT_PATTERN =
+	"gjc-resident-cache-fixture-abcdefghijklmnopqrstuvwxyz-ABCDEFGHIJKLMNOPQRSTUVWXYZ-0123456789";
+const AC2_DIRECT_STORE_MEDIAN_RATIO_LIMIT = 1.5;
+
+type Mode = "rss" | "put-latency" | "read-churn";
+type RetentionMode = "above-cap" | "below-cap";
+
+type CliArgs = {
+	mode: Mode;
+	runs: number;
+	worker: boolean;
+	baseline: boolean;
+	retention: RetentionMode;
+	entries?: number;
+	bytesPerEntry?: number;
+	cacheCapBytes?: number;
+	puts?: number;
+	skipGc: boolean;
+	forceMemoryOnly: boolean;
+	freshOpenSessionFile?: string;
+};
+
+type NumericSummary = {
+	min: number;
+	p25: number;
+	median: number;
+	p75: number;
+	iqr: number;
+	max: number;
+};
+
+type RunMetadata = {
+	bunVersion: string;
+	platform: string;
+	arch: string;
+	cpu: string | null;
+};
+
+type FixtureDimensions = {
+	seed: number;
+	entries: number;
+	bytesPerEntry: number;
+};
+
+type CacheBackingObservability = {
+	materializedCacheDemotedCount?: number;
+	residentCacheAdoptFallbackCount?: number;
+	residentCacheTrustRejectCount?: number;
+	residentCacheWin32FallbackCount?: number;
+};
+
+type MemorySample = {
+	rssBytes: number;
+	heapTotalBytes: number;
+	heapUsedBytes: number;
+	externalBytes: number;
+	arrayBuffersBytes: number;
+	/** Lifetime maximum RSS from getrusage; null where Bun does not expose it. */
+	rusageMaxRssBytes: number | null;
+};
+
+type MemoryDelta = {
+	rssBytes: number;
+	heapTotalBytes: number;
+	heapUsedBytes: number;
+	externalBytes: number;
+	arrayBuffersBytes: number;
+};
+
+type MemoryPressureReclaim = {
+	method: "forced-gc-with-idle-turns";
+	gcRounds: number;
+};
+
+type ResidentStoreMode = "disk-preferred" | "forced-memory-fallback";
+
+type RssAppendPhase = {
+	baseline: MemorySample;
+	postAppend: MemorySample;
+	postFlush: MemorySample;
+	steadyState: MemorySample;
+	postReclaim: MemorySample;
+	postRead: MemorySample;
+	postReadGc: MemorySample;
+	steadyStateDelta: MemoryDelta;
+	postReclaimDelta: MemoryDelta;
+	postReadGcDelta: MemoryDelta;
+	reclaim: MemoryPressureReclaim;
+	reclaimedBytes: number;
+	reclaimRssDeltaBytes: number;
+	observability: CacheBackingObservability;
+	residentCacheDiskBytes: number | null;
+	residentStoreMode: ResidentStoreMode;
+	guard: number;
+};
+
+type RssFreshOpenPhase = {
+	baseline: MemorySample;
+	postOpen: MemorySample;
+	steadyState: MemorySample;
+	postReclaim: MemorySample;
+	steadyStateDelta: MemoryDelta;
+	postReclaimDelta: MemoryDelta;
+	reclaim: MemoryPressureReclaim;
+	reclaimedBytes: number;
+	reclaimRssDeltaBytes: number;
+	observability: CacheBackingObservability;
+	residentCacheDiskBytes: number | null;
+	residentStoreMode: ResidentStoreMode;
+};
+
+type RssWorkerResult = {
+	schemaVersion: number;
+	mode: "rss";
+	metadata: RunMetadata;
+	fixture: FixtureDimensions;
+	appendPhase: RssAppendPhase;
+	freshOpenPhase: RssFreshOpenPhase;
+};
+
+type FreshOpenRssWorkerResult = {
+	schemaVersion: number;
+	mode: "rss";
+	phase: "fresh-open";
+	metadata: RunMetadata;
+	fixture: FixtureDimensions;
+	freshOpenPhase: RssFreshOpenPhase;
+};
+
+type DirectStorePutMetrics = {
+	canonicalMemoryPutMs: NumericSummary;
+	adoptedEphemeralPutMs: NumericSummary;
+	adoptedEphemeralToCanonicalMemoryMedianRatio: number;
+	adoptedEphemeralPutFsyncCalls: number;
+};
+
+type E2eAppendMetrics = {
+	memoryAppendMs: NumericSummary;
+	residentAppendMs: NumericSummary;
+	residentToMemoryAppendMedianRatio: number;
+	memoryWallMs: number;
+	residentWallMs: number;
+	memoryEntriesPerSecond: number;
+	residentEntriesPerSecond: number;
+	residentToMemoryThroughputRatio: number;
+	residentAppendFsyncCalls: number;
+};
+
+type PutLatencyWorkerResult = {
+	schemaVersion: number;
+	mode: "put-latency";
+	metadata: RunMetadata;
+	fixture: FixtureDimensions & { warmupIterations: number; measureIterations: number };
+	metrics: {
+		directStorePut: DirectStorePutMetrics;
+		e2eAppend: E2eAppendMetrics;
+	};
+	guard: number;
+};
+
+type ReadChurnCycle = {
+	cycle: number;
+	wallMs: number;
+	cpuMicros: number;
+	materializedEntriesCachePopulateDelta: number;
+	pathOnlyContextBuildDelta: number;
+};
+
+type ReadChurnWorkerResult = {
+	schemaVersion: number;
+	mode: "read-churn";
+	metadata: RunMetadata;
+	fixture: FixtureDimensions & {
+		cycles: number;
+		retention: RetentionMode;
+		cacheCapBytes: number | "production-default";
+	};
+	baseline: "none" | "forced-rebuild";
+	cycles: ReadChurnCycle[];
+	metrics: {
+		cycleWallMs: NumericSummary;
+		cycleCpuMicros: NumericSummary;
+		materializedEntriesCachePopulateDelta: NumericSummary;
+		pathOnlyContextBuildDelta: NumericSummary;
+		aggregateWallMs: number;
+		aggregateCpuMicros: number;
+		aggregateMaterializedEntriesCachePopulateDelta: number;
+		aggregatePathOnlyContextBuildDelta: number;
+	};
+	guard: number;
+};
+
+type WorkerResult = RssWorkerResult | PutLatencyWorkerResult | ReadChurnWorkerResult;
+
+type TestHooks = { materializedCacheMaxBytesOverride?: number };
+type SessionManagerModuleWithTestHooks = typeof sessionManagerModule & { SessionManagerTestHooks?: TestHooks };
+
+function usage(): never {
+	throw new Error(
+		"Usage: bun packages/coding-agent/scripts/resident-memory-bench.ts --mode rss|put-latency|read-churn [--runs N] [--baseline [forced-rebuild]] [--entries N] [--bytes-per-entry N] [--cache-cap-bytes N] [--puts N] [--retention above-cap|below-cap] [--skip-gc] [--force-memory-only] [--fresh-open-session-file PATH]",
+	);
+}
+
+function parseNonNegativeInteger(value: string | undefined, flag: string): number {
+	if (!value || !/^\d+$/.test(value)) throw new Error(`${flag} requires a non-negative integer.`);
+	const parsed = Number(value);
+	if (!Number.isSafeInteger(parsed)) throw new Error(`${flag} must be a safe integer.`);
+	return parsed;
+}
+
+function parsePositiveInteger(value: string | undefined, flag: string): number {
+	const parsed = parseNonNegativeInteger(value, flag);
+	if (parsed === 0) throw new Error(`${flag} must be greater than zero.`);
+	return parsed;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+	const args: CliArgs = {
+		mode: "rss",
+		runs: DEFAULT_RUNS,
+		worker: false,
+		baseline: false,
+		retention: "above-cap",
+		skipGc: false,
+		forceMemoryOnly: false,
+	};
+	for (let index = 0; index < argv.length; index++) {
+		const arg = argv[index];
+		switch (arg) {
+			case "--mode": {
+				const mode = argv[++index];
+				if (mode !== "rss" && mode !== "put-latency" && mode !== "read-churn") usage();
+				args.mode = mode;
+				break;
+			}
+			case "--runs":
+				args.runs = parsePositiveInteger(argv[++index], "--runs");
+				break;
+			case "--entries":
+				args.entries = parsePositiveInteger(argv[++index], "--entries");
+				break;
+			case "--bytes-per-entry":
+				args.bytesPerEntry = parsePositiveInteger(argv[++index], "--bytes-per-entry");
+				break;
+			case "--cache-cap-bytes":
+				args.cacheCapBytes = parseNonNegativeInteger(argv[++index], "--cache-cap-bytes");
+				break;
+			case "--puts":
+				args.puts = parsePositiveInteger(argv[++index], "--puts");
+				break;
+			case "--retention": {
+				const retention = argv[++index];
+				if (retention !== "above-cap" && retention !== "below-cap") usage();
+				args.retention = retention;
+				break;
+			}
+			case "--baseline":
+				args.baseline = true;
+				if (argv[index + 1] === "forced-rebuild") index++;
+				break;
+			case "--worker":
+				args.worker = true;
+				break;
+			case "--skip-gc":
+				args.skipGc = true;
+				break;
+			case "--force-memory-only":
+				args.forceMemoryOnly = true;
+				break;
+			case "--fresh-open-session-file": {
+				const sessionFile = argv[++index];
+				if (!sessionFile) throw new Error("--fresh-open-session-file requires a path.");
+				args.freshOpenSessionFile = sessionFile;
+				break;
+			}
+
+			default:
+				usage();
+		}
+	}
+	if (args.baseline && args.mode !== "read-churn") throw new Error("--baseline is only valid with --mode read-churn.");
+	if (args.skipGc && args.mode !== "read-churn") throw new Error("--skip-gc is only valid with --mode read-churn.");
+	if (args.freshOpenSessionFile && (!args.worker || args.mode !== "rss"))
+		throw new Error("--fresh-open-session-file is an internal RSS worker flag.");
+	if (args.forceMemoryOnly && args.mode !== "rss")
+		throw new Error("--force-memory-only is only valid with --mode rss.");
+	return args;
+}
+
+function fixtureFor(args: CliArgs): FixtureDimensions {
+	return {
+		seed: SYNTHETIC_SEED,
+		entries: args.entries ?? RSS_ENTRY_COUNT,
+		bytesPerEntry: args.bytesPerEntry ?? RSS_BYTES_PER_ENTRY,
+	};
+}
+
+function fixtureForMode(args: CliArgs): FixtureDimensions {
+	if (args.mode === "put-latency") {
+		return {
+			seed: SYNTHETIC_SEED,
+			entries: args.puts ?? PUT_MEASURE_ITERATIONS,
+			bytesPerEntry: PUT_BYTES,
+		};
+	}
+	return fixtureFor(args);
+}
+
+function metadata(): RunMetadata {
+	return {
+		bunVersion: Bun.version,
+		platform: process.platform,
+		arch: process.arch,
+		cpu: os.cpus()[0]?.model ?? null,
+	};
+}
+
+function percentile(sorted: readonly number[], percentileValue: number): number {
+	if (sorted.length === 0) return 0;
+	const index = Math.min(sorted.length - 1, Math.ceil((percentileValue / 100) * sorted.length) - 1);
+	return sorted[index] ?? 0;
+}
+
+function summarize(samples: readonly number[]): NumericSummary {
+	const sorted = [...samples].sort((left, right) => left - right);
+	const p25 = percentile(sorted, 25);
+	const p75 = percentile(sorted, 75);
+	return {
+		min: sorted[0] ?? 0,
+		p25,
+		median: percentile(sorted, 50),
+		p75,
+		iqr: p75 - p25,
+		max: sorted.at(-1) ?? 0,
+	};
+}
+
+function sum(values: readonly number[]): number {
+	return values.reduce((total, value) => total + value, 0);
+}
+
+function rusageMaxRssBytes(): number | null {
+	if (typeof process.resourceUsage !== "function") return null;
+	const maxRss = process.resourceUsage().maxRSS;
+	return Number.isFinite(maxRss) ? maxRss : null;
+}
+
+function memorySample(): MemorySample {
+	const memory = process.memoryUsage();
+	return {
+		rssBytes: memory.rss,
+		heapTotalBytes: memory.heapTotal,
+		heapUsedBytes: memory.heapUsed,
+		externalBytes: memory.external,
+		arrayBuffersBytes: memory.arrayBuffers,
+		rusageMaxRssBytes: rusageMaxRssBytes(),
+	};
+}
+
+function subtractMemorySamples(after: MemorySample, before: MemorySample): MemoryDelta {
+	return {
+		rssBytes: after.rssBytes - before.rssBytes,
+		heapTotalBytes: after.heapTotalBytes - before.heapTotalBytes,
+		heapUsedBytes: after.heapUsedBytes - before.heapUsedBytes,
+		externalBytes: after.externalBytes - before.externalBytes,
+		arrayBuffersBytes: after.arrayBuffersBytes - before.arrayBuffersBytes,
+	};
+}
+
+function summarizeMemorySamples(samples: readonly MemorySample[]): {
+	rssBytes: NumericSummary;
+	heapTotalBytes: NumericSummary;
+	heapUsedBytes: NumericSummary;
+	externalBytes: NumericSummary;
+	arrayBuffersBytes: NumericSummary;
+	rusageMaxRssBytes: NumericSummary | null;
+} {
+	const rusageMaxRssSamples = samples
+		.map(sample => sample.rusageMaxRssBytes)
+		.filter((sample): sample is number => sample !== null);
+	return {
+		rssBytes: summarize(samples.map(sample => sample.rssBytes)),
+		heapTotalBytes: summarize(samples.map(sample => sample.heapTotalBytes)),
+		heapUsedBytes: summarize(samples.map(sample => sample.heapUsedBytes)),
+		externalBytes: summarize(samples.map(sample => sample.externalBytes)),
+		arrayBuffersBytes: summarize(samples.map(sample => sample.arrayBuffersBytes)),
+		rusageMaxRssBytes: rusageMaxRssSamples.length === samples.length ? summarize(rusageMaxRssSamples) : null,
+	};
+}
+
+function summarizeMemoryDeltas(samples: readonly MemoryDelta[]): {
+	rssBytes: NumericSummary;
+	heapTotalBytes: NumericSummary;
+	heapUsedBytes: NumericSummary;
+	externalBytes: NumericSummary;
+	arrayBuffersBytes: NumericSummary;
+} {
+	return {
+		rssBytes: summarize(samples.map(sample => sample.rssBytes)),
+		heapTotalBytes: summarize(samples.map(sample => sample.heapTotalBytes)),
+		heapUsedBytes: summarize(samples.map(sample => sample.heapUsedBytes)),
+		externalBytes: summarize(samples.map(sample => sample.externalBytes)),
+		arrayBuffersBytes: summarize(samples.map(sample => sample.arrayBuffersBytes)),
+	};
+}
+
+function cacheBackingObservability(stats: SessionManagerObservabilityStats): CacheBackingObservability {
+	const values = stats as unknown as Record<string, unknown>;
+	const numberAt = (key: string): number | undefined => {
+		const value = values[key];
+		return typeof value === "number" ? value : undefined;
+	};
+	return {
+		materializedCacheDemotedCount: numberAt("materializedCacheDemotedCount"),
+		residentCacheAdoptFallbackCount: numberAt("residentCacheAdoptFallbackCount"),
+		residentCacheTrustRejectCount: numberAt("residentCacheTrustRejectCount"),
+		residentCacheWin32FallbackCount: numberAt("residentCacheWin32FallbackCount"),
+	};
+}
+
+function syntheticBuffer(seed: number, index: number, bytes: number): Buffer {
+	const alphabet = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+	let state = (seed ^ Math.imul(index + 1, 0x9e3779b9)) >>> 0;
+	const next = (): number => {
+		state ^= state << 13;
+		state ^= state >>> 17;
+		state ^= state << 5;
+		return state >>> 0;
+	};
+	const data = Buffer.allocUnsafe(bytes);
+	const prefix = `entry-${index.toString(36)}:`;
+	data.write(prefix, 0, "utf8");
+	for (let offset = prefix.length; offset < data.length; offset++) {
+		data[offset] = alphabet.charCodeAt(next() % alphabet.length);
+	}
+	return data;
+}
+
+/** Build an exact-size ASCII fixture without allocating a throwaway Buffer before the put path. */
+function syntheticText(seed: number, index: number, bytes: number): string {
+	const prefix = `entry-${seed.toString(36)}-${index.toString(36)}:`;
+	if (bytes <= prefix.length) return prefix.slice(0, bytes);
+	const offset = (seed ^ index) >>> 0;
+	const pattern = `${SYNTHETIC_TEXT_PATTERN.slice(offset % SYNTHETIC_TEXT_PATTERN.length)}${SYNTHETIC_TEXT_PATTERN.slice(0, offset % SYNTHETIC_TEXT_PATTERN.length)}`;
+	const bodyBytes = bytes - prefix.length;
+	return `${prefix}${pattern.repeat(Math.ceil(bodyBytes / pattern.length)).slice(0, bodyBytes)}`;
+}
+
+function appendSyntheticEntries(manager: SessionManagerType, fixture: FixtureDimensions): void {
+	for (let index = 0; index < fixture.entries; index++) {
+		manager.appendMessage({
+			role: "user",
+			content: syntheticText(fixture.seed, index, fixture.bytesPerEntry),
+			timestamp: index,
+		});
+	}
+}
+
+async function withPersistentFixture<T>(
+	fixture: FixtureDimensions,
+	forceMemoryOnly: boolean,
+	operation: (manager: SessionManagerType) => Promise<T>,
+): Promise<T> {
+	const root = await fs.mkdtemp(path.join(os.tmpdir(), "gjc-resident-memory-bench-"));
+	let manager: SessionManagerType | undefined;
+	try {
+		if (forceMemoryOnly) await forceResidentCacheMemoryFallback();
+		manager = SessionManager.create(root, path.join(root, "sessions"));
+		appendSyntheticEntries(manager, fixture);
+		return await operation(manager);
+	} finally {
+		if (manager) await manager.close();
+		await fs.rm(root, { recursive: true, force: true });
+	}
+}
+
+async function forceResidentCacheMemoryFallback(): Promise<void> {
+	const agentDir = process.env.GJC_CODING_AGENT_DIR;
+	if (!agentDir) throw new Error("--force-memory-only requires GJC_CODING_AGENT_DIR to be set.");
+	await fs.mkdir(agentDir, { recursive: true, mode: 0o700 });
+	await fs.writeFile(path.join(agentDir, "resident-cache"), "forced resident cache memory fallback\n", {
+		encoding: "utf8",
+		flag: "wx",
+		mode: 0o600,
+	});
+}
+
+async function residentCacheDiskBytes(): Promise<number | null> {
+	const agentDir = process.env.GJC_CODING_AGENT_DIR;
+	if (!agentDir) return null;
+	const root = path.join(agentDir, "resident-cache");
+	const instanceDirs = await fs.readdir(root, { withFileTypes: true }).catch(() => undefined);
+	if (!instanceDirs) return null;
+	const directoryBytes = async (directory: string): Promise<number> => {
+		let bytes = 0;
+		for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
+			const pathname = path.join(directory, entry.name);
+			if (entry.isDirectory()) bytes += await directoryBytes(pathname);
+			else if (entry.isFile()) bytes += (await fs.stat(pathname)).size;
+		}
+		return bytes;
+	};
+	return await Promise.all(
+		instanceDirs
+			.filter(entry => entry.isDirectory() && entry.name.startsWith("i-"))
+			.map(entry => directoryBytes(path.join(root, entry.name))),
+	).then(sum);
+}
+
+function readPair(manager: SessionManagerType): number {
+	const entries = manager.getEntries();
+	const context = manager.buildSessionContext();
+	return entries.length + context.messages.length;
+}
+
+async function settleAndForceGc(): Promise<void> {
+	await Bun.sleep(0);
+	Bun.gc(true);
+}
+
+async function settleAndForceGcTwice(): Promise<void> {
+	await settleAndForceGc();
+	await settleAndForceGc();
+}
+
+/**
+ * Let the collector and allocator reclaim after an idle turn without injecting a
+ * larger temporary allocation that itself becomes an RSS high-water artifact.
+ */
+async function reclaimAfterMemoryPressure(): Promise<MemoryPressureReclaim> {
+	for (let round = 0; round < MEMORY_RECLAIM_GC_ROUNDS; round++) {
+		Bun.gc(true);
+		await Bun.sleep(round === MEMORY_RECLAIM_GC_ROUNDS - 1 ? 50 : 0);
+	}
+	return { method: "forced-gc-with-idle-turns", gcRounds: MEMORY_RECLAIM_GC_ROUNDS };
+}
+
+/** Allow completed SessionManager.open async frames to become collectible before sampling. */
+async function settleFreshOpenRss(): Promise<void> {
+	await settleAndForceGcTwice();
+	await Bun.sleep(50);
+	await settleAndForceGcTwice();
+}
+
+function cacheCapOverride(args: CliArgs): number | undefined {
+	if (args.cacheCapBytes !== undefined) return args.cacheCapBytes;
+	return args.retention === "below-cap" ? Number.MAX_SAFE_INTEGER : undefined;
+}
+
+function installCacheCapOverride(args: CliArgs): () => void {
+	const override = cacheCapOverride(args);
+	if (override === undefined || args.baseline) return () => {};
+	const hooks = (sessionManagerModule as SessionManagerModuleWithTestHooks).SessionManagerTestHooks;
+	if (!hooks) {
+		throw new Error("--cache-cap-bytes and --retention below-cap require the current retention-policy branch.");
+	}
+	const previous = hooks.materializedCacheMaxBytesOverride;
+	hooks.materializedCacheMaxBytesOverride = override;
+	return () => {
+		hooks.materializedCacheMaxBytesOverride = previous;
+	};
+}
+
+async function runFreshOpenRss(args: CliArgs): Promise<FreshOpenRssWorkerResult> {
+	const sessionFile = args.freshOpenSessionFile;
+	if (!sessionFile) throw new Error("Fresh-open RSS worker requires a persisted session file.");
+	const fixture = fixtureFor(args);
+	const restoreCacheCap = installCacheCapOverride(args);
+	let manager: SessionManagerType | undefined;
+	try {
+		await settleFreshOpenRss();
+		const baseline = memorySample();
+		manager = await SessionManager.open(sessionFile);
+		const postOpen = memorySample();
+		const diskBytes = await residentCacheDiskBytes();
+		await settleFreshOpenRss();
+		const steadyState = memorySample();
+		const reclaim = await reclaimAfterMemoryPressure();
+		const postReclaim = memorySample();
+		const reclaimRssDeltaBytes = postReclaim.rssBytes - steadyState.rssBytes;
+		const stats = manager.getObservabilityStatsForTests();
+		return {
+			schemaVersion: SCHEMA_VERSION,
+			mode: "rss",
+			phase: "fresh-open",
+			metadata: metadata(),
+			fixture,
+			freshOpenPhase: {
+				baseline,
+				postOpen,
+				steadyState,
+				postReclaim,
+				steadyStateDelta: subtractMemorySamples(steadyState, baseline),
+				postReclaimDelta: subtractMemorySamples(postReclaim, baseline),
+				reclaim,
+				reclaimedBytes: Math.max(0, -reclaimRssDeltaBytes),
+				reclaimRssDeltaBytes,
+				observability: cacheBackingObservability(stats),
+				residentCacheDiskBytes: diskBytes,
+				residentStoreMode: args.forceMemoryOnly ? "forced-memory-fallback" : "disk-preferred",
+			},
+		};
+	} finally {
+		if (manager) await manager.close();
+		restoreCacheCap();
+	}
+}
+
+async function runRss(args: CliArgs): Promise<RssWorkerResult> {
+	const fixture = fixtureFor(args);
+	const restoreCacheCap = installCacheCapOverride(args);
+	const root = await fs.mkdtemp(path.join(os.tmpdir(), "gjc-resident-memory-bench-"));
+	let manager: SessionManagerType | undefined;
+	try {
+		await settleAndForceGcTwice();
+		const baseline = memorySample();
+		if (args.forceMemoryOnly) await forceResidentCacheMemoryFallback();
+		manager = SessionManager.create(root, path.join(root, "sessions"));
+		appendSyntheticEntries(manager, fixture);
+		const postAppend = memorySample();
+		const diskBytes = await residentCacheDiskBytes();
+		await settleAndForceGcTwice();
+		const steadyState = memorySample();
+		const reclaim = await reclaimAfterMemoryPressure();
+		const postReclaim = memorySample();
+		const reclaimRssDeltaBytes = postReclaim.rssBytes - steadyState.rssBytes;
+		// readPair returns only a scalar, so its caller-owned snapshots are out of scope before the GC turn.
+		const guard = readPair(manager);
+		const postRead = memorySample();
+		await settleAndForceGcTwice();
+		const postReadGc = memorySample();
+		const stats = manager.getObservabilityStatsForTests();
+		await manager.ensureOnDisk();
+		await manager.flush();
+		const postFlush = memorySample();
+		const sessionFile = manager.getSessionFile();
+		if (!sessionFile) throw new Error("RSS fixture did not persist a session file.");
+		const appendPhase: RssAppendPhase = {
+			baseline,
+			postAppend,
+			postFlush,
+			steadyState,
+			postReclaim,
+			postRead,
+			postReadGc,
+			steadyStateDelta: subtractMemorySamples(steadyState, baseline),
+			postReclaimDelta: subtractMemorySamples(postReclaim, baseline),
+			postReadGcDelta: subtractMemorySamples(postReadGc, baseline),
+			reclaim,
+			reclaimedBytes: Math.max(0, -reclaimRssDeltaBytes),
+			reclaimRssDeltaBytes,
+			observability: cacheBackingObservability(stats),
+			residentCacheDiskBytes: diskBytes,
+			residentStoreMode: args.forceMemoryOnly ? "forced-memory-fallback" : "disk-preferred",
+			guard,
+		};
+		await manager.close();
+		manager = undefined;
+		const freshOpen = await runFreshOpenRssChild(args, sessionFile);
+		return {
+			schemaVersion: SCHEMA_VERSION,
+			mode: "rss",
+			metadata: metadata(),
+			fixture,
+			appendPhase,
+			freshOpenPhase: freshOpen.freshOpenPhase,
+		};
+	} finally {
+		if (manager) await manager.close();
+		await fs.rm(root, { recursive: true, force: true });
+		restoreCacheCap();
+	}
+}
+
+function benchmarkStorePuts(
+	store: MemoryBlobStore | EphemeralBlobStore,
+	payloads: readonly Buffer[],
+	from: number,
+	count: number,
+): number[] {
+	const samples: number[] = [];
+	for (let index = 0; index < count; index++) {
+		const started = performance.now();
+		store.putSync(payloads[from + index]!);
+		samples.push(performance.now() - started);
+	}
+	return samples;
+}
+
+function benchmarkCanonicalMemoryStorePuts(payloads: readonly Buffer[], measureIterations: number): number[] {
+	const store = new MemoryBlobStore({ ownership: "canonical" });
+	benchmarkStorePuts(store, payloads, 0, PUT_WARMUP_ITERATIONS);
+	return benchmarkStorePuts(store, payloads, PUT_WARMUP_ITERATIONS, measureIterations);
+}
+
+function benchmarkAppendMessages(
+	manager: SessionManagerType,
+	payloads: readonly string[],
+	from: number,
+	count: number,
+): number[] {
+	const samples: number[] = [];
+	for (let index = 0; index < count; index++) {
+		const started = performance.now();
+		manager.appendMessage({ role: "user", content: payloads[from + index]!, timestamp: from + index });
+		samples.push(performance.now() - started);
+	}
+	return samples;
+}
+
+function entriesPerSecond(entries: number, wallMs: number): number {
+	return wallMs === 0 ? Number.POSITIVE_INFINITY : (entries * 1_000) / wallMs;
+}
+
+function measureFsyncCalls<T>(operation: () => T): { result: T; fsyncCalls: number } {
+	const require = createRequire(import.meta.url);
+	const mutableFs = require("node:fs") as typeof nodeFs;
+	const originalFsyncSync = mutableFs.fsyncSync;
+	let fsyncCalls = 0;
+	mutableFs.fsyncSync = ((fileDescriptor: number): void => {
+		fsyncCalls++;
+		return originalFsyncSync(fileDescriptor);
+	}) as typeof mutableFs.fsyncSync;
+	syncBuiltinESMExports();
+	try {
+		return { result: operation(), fsyncCalls };
+	} finally {
+		mutableFs.fsyncSync = originalFsyncSync;
+		syncBuiltinESMExports();
+	}
+}
+
+async function runPutLatency(args: CliArgs): Promise<PutLatencyWorkerResult> {
+	const measureIterations = args.puts ?? PUT_MEASURE_ITERATIONS;
+	const fixture: FixtureDimensions = {
+		seed: SYNTHETIC_SEED,
+		entries: measureIterations,
+		bytesPerEntry: PUT_BYTES,
+	};
+	const payloadBuffers = Array.from({ length: PUT_WARMUP_ITERATIONS + measureIterations }, (_, index) =>
+		syntheticBuffer(fixture.seed, index, fixture.bytesPerEntry),
+	);
+	const payloads = payloadBuffers.map(buffer => buffer.toString("utf8"));
+
+	const canonicalMemorySamples = benchmarkCanonicalMemoryStorePuts(payloadBuffers, measureIterations);
+	await settleAndForceGcTwice();
+
+	const directStoreRoot = await fs.mkdtemp(path.join(os.tmpdir(), "gjc-resident-direct-put-bench-"));
+	let adoptedEphemeralStore: EphemeralBlobStore | undefined;
+	let adoptedEphemeralSamples: number[] = [];
+	let adoptedEphemeralPutFsyncCalls = 0;
+	try {
+		const instanceDir = openVerifiedResidentCacheInstanceDir(path.join(directStoreRoot, "resident-cache"));
+		adoptedEphemeralStore = EphemeralBlobStore.adoptVerifiedDir(instanceDir);
+		benchmarkStorePuts(adoptedEphemeralStore, payloadBuffers, 0, PUT_WARMUP_ITERATIONS);
+		const measurement = measureFsyncCalls(() =>
+			benchmarkStorePuts(adoptedEphemeralStore!, payloadBuffers, PUT_WARMUP_ITERATIONS, measureIterations),
+		);
+		adoptedEphemeralSamples = measurement.result;
+		adoptedEphemeralPutFsyncCalls = measurement.fsyncCalls;
+		if (adoptedEphemeralPutFsyncCalls !== 0) {
+			throw new Error(
+				`Adopted EphemeralBlobStore put path called fsyncSync ${adoptedEphemeralPutFsyncCalls} time(s).`,
+			);
+		}
+	} finally {
+		adoptedEphemeralStore?.dispose();
+		await fs.rm(directStoreRoot, { recursive: true, force: true });
+	}
+
+	const memoryManager = SessionManager.inMemory();
+	let memoryAppendSamples: number[];
+	let memoryEndToEndAppendWallMs = 0;
+	try {
+		benchmarkAppendMessages(memoryManager, payloads, 0, PUT_WARMUP_ITERATIONS);
+		const started = performance.now();
+		memoryAppendSamples = benchmarkAppendMessages(memoryManager, payloads, PUT_WARMUP_ITERATIONS, measureIterations);
+		memoryEndToEndAppendWallMs = performance.now() - started;
+	} finally {
+		await memoryManager.close();
+	}
+
+	const appendRoot = await fs.mkdtemp(path.join(os.tmpdir(), "gjc-resident-append-bench-"));
+	let residentManager: SessionManagerType | undefined;
+	let residentAppendSamples: number[] = [];
+	let residentEndToEndAppendWallMs = 0;
+	let residentAppendFsyncCalls = 0;
+	try {
+		residentManager = SessionManager.create(appendRoot, path.join(appendRoot, "sessions"));
+		benchmarkAppendMessages(residentManager, payloads, 0, PUT_WARMUP_ITERATIONS);
+		const started = performance.now();
+		const measurement = measureFsyncCalls(() =>
+			benchmarkAppendMessages(residentManager!, payloads, PUT_WARMUP_ITERATIONS, measureIterations),
+		);
+		residentAppendSamples = measurement.result;
+		residentAppendFsyncCalls = measurement.fsyncCalls;
+		residentEndToEndAppendWallMs = performance.now() - started;
+		if (residentAppendFsyncCalls !== 0) {
+			throw new Error(`Resident SessionManager append path called fsyncSync ${residentAppendFsyncCalls} time(s).`);
+		}
+	} finally {
+		if (residentManager) await residentManager.close();
+		await fs.rm(appendRoot, { recursive: true, force: true });
+	}
+
+	const canonicalMemoryPutMs = summarize(canonicalMemorySamples);
+	const adoptedEphemeralPutMs = summarize(adoptedEphemeralSamples);
+	const memoryAppendMs = summarize(memoryAppendSamples);
+	const residentAppendMs = summarize(residentAppendSamples);
+	return {
+		schemaVersion: SCHEMA_VERSION,
+		mode: "put-latency",
+		metadata: metadata(),
+		fixture: { ...fixture, warmupIterations: PUT_WARMUP_ITERATIONS, measureIterations },
+		metrics: {
+			directStorePut: {
+				canonicalMemoryPutMs,
+				adoptedEphemeralPutMs,
+				adoptedEphemeralToCanonicalMemoryMedianRatio:
+					canonicalMemoryPutMs.median === 0
+						? Number.POSITIVE_INFINITY
+						: adoptedEphemeralPutMs.median / canonicalMemoryPutMs.median,
+				adoptedEphemeralPutFsyncCalls,
+			},
+			e2eAppend: {
+				memoryAppendMs,
+				residentAppendMs,
+				residentToMemoryAppendMedianRatio:
+					memoryAppendMs.median === 0 ? Number.POSITIVE_INFINITY : residentAppendMs.median / memoryAppendMs.median,
+				memoryWallMs: memoryEndToEndAppendWallMs,
+				residentWallMs: residentEndToEndAppendWallMs,
+				memoryEntriesPerSecond: entriesPerSecond(measureIterations, memoryEndToEndAppendWallMs),
+				residentEntriesPerSecond: entriesPerSecond(measureIterations, residentEndToEndAppendWallMs),
+				residentToMemoryThroughputRatio:
+					memoryEndToEndAppendWallMs === 0
+						? Number.POSITIVE_INFINITY
+						: residentEndToEndAppendWallMs / memoryEndToEndAppendWallMs,
+				residentAppendFsyncCalls,
+			},
+		},
+		guard:
+			canonicalMemorySamples.length +
+			adoptedEphemeralSamples.length +
+			memoryAppendSamples.length +
+			residentAppendSamples.length,
+	};
+}
+
+function baselineMarker(): string {
+	const prefix = "resident-cache-baseline:";
+	return `${prefix}${"m".repeat(Math.max(0, BASELINE_MARKER_BYTES - Buffer.byteLength(prefix, "utf8")))}`;
+}
+
+function validateReadChurn(result: ReadChurnWorkerResult): void {
+	const materializedDeltas = result.cycles.map(cycle => cycle.materializedEntriesCachePopulateDelta);
+	const contextDeltas = result.cycles.map(cycle => cycle.pathOnlyContextBuildDelta);
+	if (result.baseline === "forced-rebuild") {
+		if (materializedDeltas.some(delta => delta !== 1) || contextDeltas.some(delta => delta !== 1)) {
+			throw new Error(
+				`INVALID RUN: forced-rebuild must rebuild both caches exactly once per cycle; materialized=${JSON.stringify(materializedDeltas)} context=${JSON.stringify(contextDeltas)}`,
+			);
+		}
+		return;
+	}
+	if (result.fixture.retention === "below-cap") {
+		if (sum(materializedDeltas) !== 0 || sum(contextDeltas) !== 0) {
+			throw new Error(
+				`INVALID RUN: below-cap cache rebuilt after warmup; materialized=${JSON.stringify(materializedDeltas)} context=${JSON.stringify(contextDeltas)}`,
+			);
+		}
+		return;
+	}
+	if (sum(materializedDeltas) < 1) {
+		throw new Error(
+			`INVALID RUN: no rebuilds observed for materializedEntriesCachePopulateCount (above-cap); deltas=${JSON.stringify(materializedDeltas)}`,
+		);
+	}
+	if (sum(contextDeltas) < 1) {
+		throw new Error(
+			`INVALID RUN: no rebuilds observed for pathOnlyContextBuildCount (above-cap); deltas=${JSON.stringify(contextDeltas)}`,
+		);
+	}
+}
+
+async function runReadChurn(args: CliArgs): Promise<ReadChurnWorkerResult> {
+	const fixture = fixtureFor(args);
+	const restoreCacheCap = installCacheCapOverride(args);
+	try {
+		return await withPersistentFixture(fixture, false, async manager => {
+			const cycles: ReadChurnCycle[] = [];
+			let guard = 0;
+			for (let cycle = 0; cycle < READ_CHURN_CYCLES; cycle++) {
+				guard += readPair(manager);
+				if (args.baseline) {
+					manager.appendMessage({
+						role: "user",
+						content: baselineMarker(),
+						timestamp: fixture.entries + cycle,
+					});
+				}
+				if (!args.skipGc) await settleAndForceGc();
+				const before = manager.getObservabilityStatsForTests();
+				const cpuStarted = process.cpuUsage();
+				const wallStarted = performance.now();
+				guard += readPair(manager);
+				const wallMs = performance.now() - wallStarted;
+				const cpuMicros = process.cpuUsage(cpuStarted);
+				const after = manager.getObservabilityStatsForTests();
+				cycles.push({
+					cycle,
+					wallMs,
+					cpuMicros: cpuMicros.user + cpuMicros.system,
+					materializedEntriesCachePopulateDelta:
+						after.materializedEntriesCachePopulateCount - before.materializedEntriesCachePopulateCount,
+					pathOnlyContextBuildDelta: after.pathOnlyContextBuildCount - before.pathOnlyContextBuildCount,
+				});
+			}
+			const result: ReadChurnWorkerResult = {
+				schemaVersion: SCHEMA_VERSION,
+				mode: "read-churn",
+				metadata: metadata(),
+				fixture: {
+					...fixture,
+					cycles: READ_CHURN_CYCLES,
+					retention: args.retention,
+					cacheCapBytes: cacheCapOverride(args) ?? "production-default",
+				},
+				baseline: args.baseline ? "forced-rebuild" : "none",
+				cycles,
+				metrics: {
+					cycleWallMs: summarize(cycles.map(cycle => cycle.wallMs)),
+					cycleCpuMicros: summarize(cycles.map(cycle => cycle.cpuMicros)),
+					materializedEntriesCachePopulateDelta: summarize(
+						cycles.map(cycle => cycle.materializedEntriesCachePopulateDelta),
+					),
+					pathOnlyContextBuildDelta: summarize(cycles.map(cycle => cycle.pathOnlyContextBuildDelta)),
+					aggregateWallMs: sum(cycles.map(cycle => cycle.wallMs)),
+					aggregateCpuMicros: sum(cycles.map(cycle => cycle.cpuMicros)),
+					aggregateMaterializedEntriesCachePopulateDelta: sum(
+						cycles.map(cycle => cycle.materializedEntriesCachePopulateDelta),
+					),
+					aggregatePathOnlyContextBuildDelta: sum(cycles.map(cycle => cycle.pathOnlyContextBuildDelta)),
+				},
+				guard,
+			};
+			validateReadChurn(result);
+			return result;
+		});
+	} finally {
+		restoreCacheCap();
+	}
+}
+
+async function runWorker(args: CliArgs): Promise<WorkerResult | FreshOpenRssWorkerResult> {
+	switch (args.mode) {
+		case "rss":
+			return args.freshOpenSessionFile ? await runFreshOpenRss(args) : await runRss(args);
+		case "put-latency":
+			return await runPutLatency(args);
+		case "read-churn":
+			return await runReadChurn(args);
+	}
+}
+
+function childArguments(args: CliArgs): string[] {
+	const argumentsForChild = [
+		import.meta.path,
+		"--worker",
+		"--mode",
+		args.mode,
+		"--runs",
+		"1",
+		"--retention",
+		args.retention,
+	];
+	if (args.baseline) argumentsForChild.push("--baseline", "forced-rebuild");
+	if (args.entries !== undefined) argumentsForChild.push("--entries", String(args.entries));
+	if (args.bytesPerEntry !== undefined) argumentsForChild.push("--bytes-per-entry", String(args.bytesPerEntry));
+	if (args.cacheCapBytes !== undefined) argumentsForChild.push("--cache-cap-bytes", String(args.cacheCapBytes));
+	if (args.puts !== undefined) argumentsForChild.push("--puts", String(args.puts));
+	if (args.skipGc) argumentsForChild.push("--skip-gc");
+	if (args.forceMemoryOnly) argumentsForChild.push("--force-memory-only");
+	return argumentsForChild;
+}
+
+async function runChildProcess(argumentsForChild: readonly string[]): Promise<unknown> {
+	const child = Bun.spawn([process.execPath, ...argumentsForChild], {
+		cwd: process.cwd(),
+		env: { ...process.env, NO_COLOR: "1" },
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const [exitCode, stdout, stderr] = await Promise.all([
+		child.exited,
+		new Response(child.stdout).text(),
+		new Response(child.stderr).text(),
+	]);
+	if (exitCode !== 0) {
+		const diagnostic = stderr.trim() || stdout.trim() || `resident-memory benchmark child exited ${exitCode}`;
+		throw new Error(diagnostic);
+	}
+	try {
+		return JSON.parse(stdout) as unknown;
+	} catch (error) {
+		throw new Error(`Could not parse resident-memory benchmark child output: ${String(error)}\n${stdout}`);
+	}
+}
+
+async function runFreshOpenRssChild(args: CliArgs, sessionFile: string): Promise<FreshOpenRssWorkerResult> {
+	const result = await runChildProcess([...childArguments(args), "--fresh-open-session-file", sessionFile]);
+	if (
+		typeof result !== "object" ||
+		result === null ||
+		!("mode" in result) ||
+		result.mode !== "rss" ||
+		!("phase" in result) ||
+		result.phase !== "fresh-open"
+	) {
+		throw new Error("RSS fresh-open child returned an unexpected result.");
+	}
+	return result as FreshOpenRssWorkerResult;
+}
+
+async function runChild(args: CliArgs): Promise<WorkerResult> {
+	const result = await runChildProcess(childArguments(args));
+	if (typeof result !== "object" || result === null || !("mode" in result) || "phase" in result) {
+		throw new Error("Resident-memory benchmark child returned an unexpected result.");
+	}
+	return result as WorkerResult;
+}
+
+function summarizeAc1(runs: readonly RssWorkerResult[]): {
+	appendSteadyDelta: number;
+	postReclaimDelta: number;
+	reclaimedBytes: number;
+	external: {
+		steadyStateBytes: number;
+		postReclaimBytes: number;
+		postReclaimDelta: number;
+	};
+	arrayBuffers: {
+		steadyStateBytes: number;
+		postReclaimBytes: number;
+		postReclaimDelta: number;
+	};
+	freshOpenDiagnostic: {
+		steadyStateRssDelta: number;
+		postReclaimRssDelta: number;
+		classification: "documented-evidence";
+	};
+	verdict: "pass" | "documented-evidence-with-reclaim-proof" | "fail";
+} {
+	const appendSteadyDelta = summarize(runs.map(run => run.appendPhase.steadyStateDelta.rssBytes));
+	const postReclaimDelta = summarize(runs.map(run => run.appendPhase.postReclaimDelta.rssBytes));
+	const reclaimedBytes = summarize(runs.map(run => run.appendPhase.reclaimedBytes));
+	const steadyStateExternal = summarize(runs.map(run => run.appendPhase.steadyState.externalBytes));
+	const postReclaimExternal = summarize(runs.map(run => run.appendPhase.postReclaim.externalBytes));
+	const postReclaimExternalDelta = summarize(runs.map(run => run.appendPhase.postReclaimDelta.externalBytes));
+	const steadyStateArrayBuffers = summarize(runs.map(run => run.appendPhase.steadyState.arrayBuffersBytes));
+	const postReclaimArrayBuffers = summarize(runs.map(run => run.appendPhase.postReclaim.arrayBuffersBytes));
+	const postReclaimArrayBuffersDelta = summarize(runs.map(run => run.appendPhase.postReclaimDelta.arrayBuffersBytes));
+	const freshOpenRssDelta = summarize(runs.map(run => run.freshOpenPhase.steadyStateDelta.rssBytes));
+	const freshOpenPostReclaimRssDelta = summarize(runs.map(run => run.freshOpenPhase.postReclaimDelta.rssBytes));
+	const passesSteadyStateGate = appendSteadyDelta.median <= AC1_APPEND_PHASE_RSS_LIMIT_BYTES;
+	const hasReclaimProof = postReclaimDelta.median <= AC1_APPEND_PHASE_RSS_LIMIT_BYTES && reclaimedBytes.median > 0;
+	return {
+		appendSteadyDelta: appendSteadyDelta.median,
+		postReclaimDelta: postReclaimDelta.median,
+		reclaimedBytes: reclaimedBytes.median,
+		external: {
+			steadyStateBytes: steadyStateExternal.median,
+			postReclaimBytes: postReclaimExternal.median,
+			postReclaimDelta: postReclaimExternalDelta.median,
+		},
+		arrayBuffers: {
+			steadyStateBytes: steadyStateArrayBuffers.median,
+			postReclaimBytes: postReclaimArrayBuffers.median,
+			postReclaimDelta: postReclaimArrayBuffersDelta.median,
+		},
+		freshOpenDiagnostic: {
+			steadyStateRssDelta: freshOpenRssDelta.median,
+			postReclaimRssDelta: freshOpenPostReclaimRssDelta.median,
+			classification: "documented-evidence",
+		},
+		verdict: passesSteadyStateGate ? "pass" : hasReclaimProof ? "documented-evidence-with-reclaim-proof" : "fail",
+	};
+}
+
+function summarizeAc2(runs: readonly PutLatencyWorkerResult[]): {
+	directStorePut: {
+		canonicalMemoryMedianMs: number;
+		adoptedEphemeralMedianMs: number;
+		adoptedEphemeralToCanonicalMemoryMedianRatio: number;
+	};
+	e2eAppend: {
+		memoryAppendMedianMs: NumericSummary;
+		residentAppendMedianMs: NumericSummary;
+		residentToMemoryAppendMedianRatio: NumericSummary;
+		memoryEntriesPerSecond: NumericSummary;
+		residentEntriesPerSecond: NumericSummary;
+		residentToMemoryThroughputRatio: NumericSummary;
+	};
+	verdict: "pass" | "documented-evidence";
+	justification?: string;
+} {
+	const canonicalMemoryMedianMs = summarize(runs.map(run => run.metrics.directStorePut.canonicalMemoryPutMs.median));
+	const adoptedEphemeralMedianMs = summarize(runs.map(run => run.metrics.directStorePut.adoptedEphemeralPutMs.median));
+	const directStoreRatio = summarize(
+		runs.map(run => run.metrics.directStorePut.adoptedEphemeralToCanonicalMemoryMedianRatio),
+	);
+	const memoryAppendMedianMs = summarize(runs.map(run => run.metrics.e2eAppend.memoryAppendMs.median));
+	const residentAppendMedianMs = summarize(runs.map(run => run.metrics.e2eAppend.residentAppendMs.median));
+	const residentToMemoryAppendMedianRatio = summarize(
+		runs.map(run => run.metrics.e2eAppend.residentToMemoryAppendMedianRatio),
+	);
+	const memoryEntriesPerSecond = summarize(runs.map(run => run.metrics.e2eAppend.memoryEntriesPerSecond));
+	const residentEntriesPerSecond = summarize(runs.map(run => run.metrics.e2eAppend.residentEntriesPerSecond));
+	const residentToMemoryThroughputRatio = summarize(
+		runs.map(run => run.metrics.e2eAppend.residentToMemoryThroughputRatio),
+	);
+	const verdict = directStoreRatio.median <= AC2_DIRECT_STORE_MEDIAN_RATIO_LIMIT ? "pass" : "documented-evidence";
+	return {
+		directStorePut: {
+			canonicalMemoryMedianMs: canonicalMemoryMedianMs.median,
+			adoptedEphemeralMedianMs: adoptedEphemeralMedianMs.median,
+			adoptedEphemeralToCanonicalMemoryMedianRatio: directStoreRatio.median,
+		},
+		e2eAppend: {
+			memoryAppendMedianMs,
+			residentAppendMedianMs,
+			residentToMemoryAppendMedianRatio,
+			memoryEntriesPerSecond,
+			residentEntriesPerSecond,
+			residentToMemoryThroughputRatio,
+		},
+		verdict,
+		...(verdict === "documented-evidence"
+			? {
+					justification: `The ${directStoreRatio.median.toFixed(2)}x direct-store ratio compares canonical MemoryBlobStore putSync with adopted verified EphemeralBlobStore putSync over the same pre-generated unique Buffers. The resident path deliberately retains O_EXCL|O_NOFOLLOW, owner-only modes, and lazy EEXIST verification. Its ${adoptedEphemeralMedianMs.median.toFixed(4)} ms median sustains ${residentEntriesPerSecond.median.toFixed(0)} SessionManager appends/s; treat the ratio as a secure-write baseline artifact, not an end-to-end user-impact regression.`,
+				}
+			: {}),
+	};
+}
+
+function summarizeParentRuns(mode: Mode, runs: readonly WorkerResult[]): object {
+	if (mode === "rss") {
+		const rssRuns = runs as readonly RssWorkerResult[];
+		return {
+			appendPhase: {
+				baseline: summarizeMemorySamples(rssRuns.map(run => run.appendPhase.baseline)),
+				postAppend: summarizeMemorySamples(rssRuns.map(run => run.appendPhase.postAppend)),
+				postFlush: summarizeMemorySamples(rssRuns.map(run => run.appendPhase.postFlush)),
+				steadyState: summarizeMemorySamples(rssRuns.map(run => run.appendPhase.steadyState)),
+				postReclaim: summarizeMemorySamples(rssRuns.map(run => run.appendPhase.postReclaim)),
+				postRead: summarizeMemorySamples(rssRuns.map(run => run.appendPhase.postRead)),
+				postReadGc: summarizeMemorySamples(rssRuns.map(run => run.appendPhase.postReadGc)),
+				steadyStateDelta: summarizeMemoryDeltas(rssRuns.map(run => run.appendPhase.steadyStateDelta)),
+				postReclaimDelta: summarizeMemoryDeltas(rssRuns.map(run => run.appendPhase.postReclaimDelta)),
+				postReadGcDelta: summarizeMemoryDeltas(rssRuns.map(run => run.appendPhase.postReadGcDelta)),
+				reclaim: rssRuns.map(run => run.appendPhase.reclaim),
+				reclaimedBytes: summarize(rssRuns.map(run => run.appendPhase.reclaimedBytes)),
+				reclaimRssDeltaBytes: summarize(rssRuns.map(run => run.appendPhase.reclaimRssDeltaBytes)),
+				residentCacheDiskBytes: rssRuns.map(run => run.appendPhase.residentCacheDiskBytes),
+				residentStoreModes: rssRuns.map(run => run.appendPhase.residentStoreMode),
+				cacheBackingObservability: rssRuns.map(run => run.appendPhase.observability),
+			},
+			freshOpenPhase: {
+				baseline: summarizeMemorySamples(rssRuns.map(run => run.freshOpenPhase.baseline)),
+				postOpen: summarizeMemorySamples(rssRuns.map(run => run.freshOpenPhase.postOpen)),
+				steadyState: summarizeMemorySamples(rssRuns.map(run => run.freshOpenPhase.steadyState)),
+				postReclaim: summarizeMemorySamples(rssRuns.map(run => run.freshOpenPhase.postReclaim)),
+				steadyStateDelta: summarizeMemoryDeltas(rssRuns.map(run => run.freshOpenPhase.steadyStateDelta)),
+				postReclaimDelta: summarizeMemoryDeltas(rssRuns.map(run => run.freshOpenPhase.postReclaimDelta)),
+				reclaim: rssRuns.map(run => run.freshOpenPhase.reclaim),
+				reclaimedBytes: summarize(rssRuns.map(run => run.freshOpenPhase.reclaimedBytes)),
+				reclaimRssDeltaBytes: summarize(rssRuns.map(run => run.freshOpenPhase.reclaimRssDeltaBytes)),
+				residentCacheDiskBytes: rssRuns.map(run => run.freshOpenPhase.residentCacheDiskBytes),
+				residentStoreModes: rssRuns.map(run => run.freshOpenPhase.residentStoreMode),
+				cacheBackingObservability: rssRuns.map(run => run.freshOpenPhase.observability),
+			},
+			ac1: summarizeAc1(rssRuns),
+		};
+	}
+	if (mode === "put-latency") {
+		const putRuns = runs as readonly PutLatencyWorkerResult[];
+		return {
+			directStorePut: {
+				canonicalMemoryPutMedianMs: summarize(
+					putRuns.map(run => run.metrics.directStorePut.canonicalMemoryPutMs.median),
+				),
+				adoptedEphemeralPutMedianMs: summarize(
+					putRuns.map(run => run.metrics.directStorePut.adoptedEphemeralPutMs.median),
+				),
+				adoptedEphemeralToCanonicalMemoryMedianRatio: summarize(
+					putRuns.map(run => run.metrics.directStorePut.adoptedEphemeralToCanonicalMemoryMedianRatio),
+				),
+				adoptedEphemeralPutFsyncCalls: putRuns.map(run => run.metrics.directStorePut.adoptedEphemeralPutFsyncCalls),
+			},
+			e2eAppend: {
+				memoryAppendMedianMs: summarize(putRuns.map(run => run.metrics.e2eAppend.memoryAppendMs.median)),
+				residentAppendMedianMs: summarize(putRuns.map(run => run.metrics.e2eAppend.residentAppendMs.median)),
+				residentToMemoryAppendMedianRatio: summarize(
+					putRuns.map(run => run.metrics.e2eAppend.residentToMemoryAppendMedianRatio),
+				),
+				memoryWallMs: summarize(putRuns.map(run => run.metrics.e2eAppend.memoryWallMs)),
+				residentWallMs: summarize(putRuns.map(run => run.metrics.e2eAppend.residentWallMs)),
+				memoryEntriesPerSecond: summarize(putRuns.map(run => run.metrics.e2eAppend.memoryEntriesPerSecond)),
+				residentEntriesPerSecond: summarize(putRuns.map(run => run.metrics.e2eAppend.residentEntriesPerSecond)),
+				residentToMemoryThroughputRatio: summarize(
+					putRuns.map(run => run.metrics.e2eAppend.residentToMemoryThroughputRatio),
+				),
+				residentAppendFsyncCalls: putRuns.map(run => run.metrics.e2eAppend.residentAppendFsyncCalls),
+			},
+			ac2: summarizeAc2(putRuns),
+		};
+	}
+	const churnRuns = runs as readonly ReadChurnWorkerResult[];
+	const cycles = churnRuns.flatMap(run => run.cycles);
+	return {
+		cycleWallMs: summarize(cycles.map(cycle => cycle.wallMs)),
+		cycleCpuMicros: summarize(cycles.map(cycle => cycle.cpuMicros)),
+		materializedEntriesCachePopulateDelta: summarize(
+			cycles.map(cycle => cycle.materializedEntriesCachePopulateDelta),
+		),
+		pathOnlyContextBuildDelta: summarize(cycles.map(cycle => cycle.pathOnlyContextBuildDelta)),
+		aggregateWallMs: summarize(churnRuns.map(run => run.metrics.aggregateWallMs)),
+		aggregateCpuMicros: summarize(churnRuns.map(run => run.metrics.aggregateCpuMicros)),
+		aggregateMaterializedEntriesCachePopulateDelta: summarize(
+			churnRuns.map(run => run.metrics.aggregateMaterializedEntriesCachePopulateDelta),
+		),
+		aggregatePathOnlyContextBuildDelta: summarize(
+			churnRuns.map(run => run.metrics.aggregatePathOnlyContextBuildDelta),
+		),
+	};
+}
+
+async function runParent(args: CliArgs): Promise<void> {
+	const runs: WorkerResult[] = [];
+	for (let run = 0; run < args.runs; run++) {
+		runs.push(await runChild(args));
+	}
+	const summary = summarizeParentRuns(args.mode, runs);
+	const acceptanceReport =
+		args.mode === "rss"
+			? { ac1: summarizeAc1(runs as readonly RssWorkerResult[]) }
+			: args.mode === "put-latency"
+				? { ac2: summarizeAc2(runs as readonly PutLatencyWorkerResult[]) }
+				: {};
+	const output = {
+		schemaVersion: SCHEMA_VERSION,
+		mode: args.mode,
+		runs: args.runs,
+		baseline: args.baseline ? "forced-rebuild" : "none",
+		metadata: metadata(),
+		fixture: fixtureForMode(args),
+		summary,
+		...acceptanceReport,
+		runResults: runs,
+	};
+	process.stdout.write(`${JSON.stringify(output)}\n`);
+}
+
+async function main(): Promise<void> {
+	const args = parseArgs(Bun.argv.slice(2));
+	if (args.worker) {
+		const result = await runWorker(args);
+		process.stdout.write(`${JSON.stringify(result)}\n`);
+		return;
+	}
+	await runParent(args);
+}
+
+await main().catch(error => {
+	process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+});