@zenodinh/pi-render 0.0.0-stage → 0.1.0

package/src/core/registry.test.ts

@@ -0,0 +1,307 @@
+/**
+ * registry through its seam — createRegistry(store, log), driven with a fake store and fake logger.
+ *
+ * Every scenario's first meaningful action is a createRegistry call; nothing below the seam (the Map,
+ * the validators, readEntry) is imported.
+ *
+ * invented: the two doubles stand in for T-07 core/settings and T-06 core/log, which land in the same
+ * wave; they satisfy the structural contracts and record every call in order.
+ * invented: settings documents are hand-built to the SA §3 literal (version + modules map) — T-07 owns
+ * the on-disk file, so there is no recorded payload to reuse here.
+ */
+import { describe, expect, test } from "vitest";
+import { createRegistry } from "./registry.ts";
+import type { LogEntry, Logger } from "./types/log.ts";
+import type { ModuleDescriptor, SettingSpec } from "./types/registry.ts";
+import type { SettingsDoc, SettingsStore } from "./types/settings.ts";
+
+const EMPTY_DOC: SettingsDoc = { version: 1, modules: {} };
+
+const COLLAPSE_AT: SettingSpec = { name: "collapseAt", kind: "number", default: 5 };
+const COMPACT: SettingSpec = { name: "compact", kind: "toggle", default: false };
+const CODE_THEME: SettingSpec = {
+	name: "codeTheme",
+	kind: "enum",
+	values: ["dracula-soft", "one-dark-pro"],
+	default: "dracula-soft",
+};
+
+const BASH: ModuleDescriptor = { key: "row.bash", name: "Bash row", defaultEnabled: true, settings: [COLLAPSE_AT] };
+const TABLE: ModuleDescriptor = {
+	key: "content.table",
+	name: "Table",
+	defaultEnabled: true,
+	settings: [COLLAPSE_AT, COMPACT],
+};
+const CODETHEME: ModuleDescriptor = {
+	key: "codetheme",
+	name: "Code theme",
+	defaultEnabled: true,
+	settings: [CODE_THEME],
+};
+
+interface FakeStore extends SettingsStore {
+	/** Every store interaction in call order — a read-path disk touch shows up here. Required. */
+	readonly calls: string[];
+	/** Documents handed to save(), in order. Required. */
+	readonly saved: SettingsDoc[];
+}
+
+function fakeStore(initial: SettingsDoc): FakeStore {
+	const calls: string[] = [];
+	const saved: SettingsDoc[] = [];
+	// The store owns its document (T-07 parses the file per instance), so a write cannot leak between tests.
+	let doc = structuredClone(initial);
+	return {
+		calls,
+		saved,
+		load() {
+			calls.push("load");
+			return doc; // cached, like T-07: a re-read must come from an explicit load call, not implicitly
+		},
+		save(next) {
+			calls.push("save");
+			doc = next;
+			saved.push(next);
+		},
+	};
+}
+
+interface FakeLog {
+	readonly log: Logger;
+	readonly entries: LogEntry[];
+}
+
+function fakeLog(): FakeLog {
+	const entries: LogEntry[] = [];
+	const seen = new Set<string>();
+	const log: Logger = {
+		logLine(scope, message) {
+			entries.push({ scope, message, time: 0 });
+		},
+		logOnce(key, scope, message) {
+			if (seen.has(key)) return;
+			seen.add(key);
+			entries.push({ scope, message, time: 0 });
+		},
+		drain() {
+			return entries.splice(0, entries.length);
+		},
+	};
+	return { log, entries };
+}
+
+describe("registry", () => {
+	// spec: defineModule(row.bash, defaultEnabled true); setSettings("row.bash", { enabled: false }) ->
+	//   the NEXT isEnabled("row.bash") is false and the saved doc carries enabled: false.
+	// fails_when: a disable never reaches the next read (the predecessor's toggle freeze).
+	test("AC-1 a settings write lands on the next isEnabled read", () => {
+		const store = fakeStore(EMPTY_DOC);
+		const registry = createRegistry(store, fakeLog().log);
+		registry.defineModule(BASH);
+
+		expect(registry.isEnabled("row.bash")).toBe(true);
+
+		registry.setSettings("row.bash", { enabled: false });
+
+		expect(registry.isEnabled("row.bash")).toBe(false);
+		expect(store.saved).toHaveLength(1);
+		expect(store.saved[0]?.modules["row.bash"]?.enabled).toBe(false);
+	});
+
+	// spec: isEnabled("row.nope") -> false; getSettings("row.nope") -> {}; neither throws.
+	// fails_when: a lookup for a key nothing registered throws.
+	test("AC-2 an unknown key reads false and {} without throwing", () => {
+		const registry = createRegistry(fakeStore(EMPTY_DOC), fakeLog().log);
+
+		expect(registry.isEnabled("row.nope")).toBe(false);
+		expect(registry.getSettings("row.nope")).toEqual({});
+	});
+
+	// spec: defineModule(BASH) then two more descriptors under "row.bash" -> the first name/default/
+	//   settings survive and exactly one log entry fires.
+	// fails_when: a later descriptor overwrites the first, or each duplicate logs again.
+	test("AC-3 a duplicate define keeps the first descriptor and logs exactly once", () => {
+		const store = fakeStore(EMPTY_DOC);
+		const { log, entries } = fakeLog();
+		const registry = createRegistry(store, log);
+
+		registry.defineModule(BASH);
+		registry.defineModule({ ...BASH, name: "Impostor", defaultEnabled: false });
+		registry.defineModule({
+			...BASH,
+			name: "Impostor again",
+			settings: [{ name: "other", kind: "toggle", default: false }],
+		});
+
+		expect(registry.isEnabled("row.bash")).toBe(true);
+		expect(registry.getSettings("row.bash")).toEqual({ collapseAt: 5 });
+		expect(entries).toHaveLength(1);
+		expect(entries[0]?.message).toContain("row.bash");
+	});
+
+	// spec: stored row.bash.settings = { collapseAt: "3" } (a string under a number spec) with
+	//   content.table.settings = { collapseAt: 7, ghost: 1 } -> row.bash reads the default 5, content.table
+	//   reads 7 with the unspec'd "ghost" dropped.
+	// fails_when: one malformed key corrupts the others (or the malformed value is handed to a renderer).
+	test("AC-4 a malformed stored value reads its default while other keys read stored values", () => {
+		const store = fakeStore({
+			version: 1,
+			modules: {
+				"row.bash": { enabled: true, settings: { collapseAt: "3" } },
+				"content.table": { enabled: false, settings: { collapseAt: 7, ghost: 1 } },
+			},
+		});
+		const { log, entries } = fakeLog();
+		const registry = createRegistry(store, log);
+		registry.defineModule(BASH);
+		registry.defineModule(TABLE);
+
+		expect(registry.getSettings("row.bash")).toEqual({ collapseAt: 5 });
+		expect(registry.getSettings("content.table")).toEqual({ collapseAt: 7, compact: false });
+		expect(registry.isEnabled("content.table")).toBe(false);
+		expect(entries).toHaveLength(1);
+	});
+
+	// spec: stored row.bash = 7 (not a slice) -> row.bash reads defaultEnabled true plus spec defaults
+	//   while content.table still reads its stored enabled: false and collapseAt: 7.
+	// fails_when: a malformed module entry poisons its neighbours or throws at boot.
+	test("AC-4 a malformed stored entry reads that module's defaults while other keys read stored values", () => {
+		const incomplete = {
+			version: 1,
+			modules: { "row.bash": 7, "content.table": { enabled: false, settings: { collapseAt: 7 } } },
+		};
+		const store = fakeStore(incomplete as unknown as SettingsDoc); // boundary: the disk can hold any JSON
+		const { log, entries } = fakeLog();
+		const registry = createRegistry(store, log);
+		registry.defineModule(BASH);
+		registry.defineModule(TABLE);
+
+		expect(registry.isEnabled("row.bash")).toBe(true);
+		expect(registry.getSettings("row.bash")).toEqual({ collapseAt: 5 });
+		expect(registry.isEnabled("content.table")).toBe(false);
+		expect(registry.getSettings("content.table")).toEqual({ collapseAt: 7, compact: false });
+		expect(entries).toHaveLength(1);
+	});
+
+	// spec: one createRegistry (one store.load), 5 read invocations, one setSettings -> the store saw
+	//   exactly ["load", "save"]; the reads logged nothing.
+	// fails_when: the registry reaches outside its seam — a per-render disk read or a pushed write.
+	test("AC-5 every call stays inside the injected store and logger seam", () => {
+		const store = fakeStore(EMPTY_DOC);
+		const { log, entries } = fakeLog();
+		const registry = createRegistry(store, log);
+		registry.defineModule(CODETHEME);
+
+		for (let i = 0; i < 5; i++) {
+			registry.isEnabled("codetheme");
+			registry.getSettings("codetheme");
+		}
+		expect(store.calls).toEqual(["load"]);
+		expect(entries).toEqual([]);
+
+		registry.setSettings("codetheme", { codeTheme: "one-dark-pro" });
+
+		expect(store.calls).toEqual(["load", "save"]);
+		expect(registry.getSettings("codetheme")).toEqual({ codeTheme: "one-dark-pro" });
+		expect(store.calls).toEqual(["load", "save"]);
+	});
+
+	// spec: setSettings("content.table", { collapseAt: 9, compact: true }) -> both land on the next read
+	//   and both are in the saved doc.
+	// fails_when: a patch is validated but never applied or never persisted.
+	test("a valid patch merges into the stored settings and persists", () => {
+		const store = fakeStore(EMPTY_DOC);
+		const registry = createRegistry(store, fakeLog().log);
+		registry.defineModule(TABLE);
+
+		registry.setSettings("content.table", { collapseAt: 9, compact: true });
+
+		expect(registry.getSettings("content.table")).toEqual({ collapseAt: 9, compact: true });
+		expect(store.saved[0]?.modules["content.table"]?.settings).toEqual({ collapseAt: 9, compact: true });
+	});
+
+	// spec: setSettings("row.bash", { collapseAt: "3" }) -> no throw, the stored settings stay at the
+	//   default 5, enabled is untouched, exactly one log entry.
+	// fails_when: an invalid patch value is stored, throws, or logs a line per frame it is seen.
+	test("an invalid patch value is rejected with one log entry and never throws", () => {
+		const store = fakeStore(EMPTY_DOC);
+		const { log, entries } = fakeLog();
+		const registry = createRegistry(store, log);
+		registry.defineModule(BASH);
+
+		registry.setSettings("row.bash", { collapseAt: "3" });
+
+		expect(registry.getSettings("row.bash")).toEqual({ collapseAt: 5 });
+		expect(registry.isEnabled("row.bash")).toBe(true);
+		expect(entries).toHaveLength(1);
+		expect(entries[0]?.message).toBe("ignored invalid value for row.bash.collapseAt");
+	});
+
+	// spec: a patch naming a setting no spec declares -> rejected with one log entry and absent from the
+	//   effective settings.
+	// fails_when: an unvalidatable key is written into the doc and handed back to a renderer.
+	test("a patch naming an unknown setting is rejected with one log entry", () => {
+		const store = fakeStore(EMPTY_DOC);
+		const { log, entries } = fakeLog();
+		const registry = createRegistry(store, log);
+		registry.defineModule(BASH);
+
+		registry.setSettings("row.bash", { nope: 1 });
+
+		expect(registry.getSettings("row.bash")).toEqual({ collapseAt: 5 });
+		expect(entries).toHaveLength(1);
+		expect(entries[0]?.message).toBe("ignored invalid value for row.bash.nope");
+	});
+
+	// spec: setSettings("codetheme", { codeTheme: "solarized" }) -> rejected, default kept, one log entry;
+	//   then { codeTheme: "one-dark-pro" } -> accepted.
+	// fails_when: an enum value outside the spec's list reaches the code that uses it.
+	test("an enum value outside the spec is rejected while an allowed value lands", () => {
+		const store = fakeStore(EMPTY_DOC);
+		const { log, entries } = fakeLog();
+		const registry = createRegistry(store, log);
+		registry.defineModule(CODETHEME);
+
+		registry.setSettings("codetheme", { codeTheme: "solarized" });
+		expect(registry.getSettings("codetheme")).toEqual({ codeTheme: "dracula-soft" });
+		expect(entries).toHaveLength(1);
+
+		registry.setSettings("codetheme", { codeTheme: "one-dark-pro" });
+		expect(registry.getSettings("codetheme")).toEqual({ codeTheme: "one-dark-pro" });
+	});
+
+	// spec: setSettings("row.nope", { collapseAt: 9 }) and a non-object patch both no-op with one log
+	//   entry each and never throw or save.
+	// fails_when: a stale panel target or an erased-type patch corrupts the doc.
+	test("a write for an unknown key or a non-object patch is ignored, never throws", () => {
+		const store = fakeStore(EMPTY_DOC);
+		const { log, entries } = fakeLog();
+		const registry = createRegistry(store, log);
+		registry.defineModule(BASH);
+
+		registry.setSettings("row.nope", { collapseAt: 9 });
+		registry.setSettings("row.bash", "collapseAt" as unknown as object); // boundary: TS types are erased
+
+		expect(registry.isEnabled("row.nope")).toBe(false);
+		expect(registry.getSettings("row.bash")).toEqual({ collapseAt: 5 });
+		expect(store.saved).toHaveLength(0);
+		expect(entries).toHaveLength(2);
+	});
+
+	// spec: a stored enabled that is not a boolean ("yes") falls back to spec defaultEnabled (false) and
+	//   logs once, rather than being read as a truthy string.
+	// fails_when: a malformed enabled flag is trusted and a module turns itself on.
+	test("a malformed stored enabled falls back to the default and logs once", () => {
+		const store = fakeStore({
+			version: 1,
+			modules: { "row.bash": { enabled: "yes", settings: {} } },
+		} as unknown as SettingsDoc); // boundary: the disk can hold any JSON
+		const { log, entries } = fakeLog();
+		const registry = createRegistry(store, log);
+		registry.defineModule({ ...BASH, defaultEnabled: false });
+
+		expect(registry.isEnabled("row.bash")).toBe(false);
+		expect(entries).toHaveLength(1);
+	});
+});

package/src/core/registry.ts

@@ -0,0 +1,135 @@
+/**
+ * registry.ts — the pluggable module registry: descriptors in, enabled flags and settings out.
+ *
+ * Boundary: the /render panel writes through setSettings; renderers poll isEnabled/getSettings per
+ * invocation and never write. A write lands on the next read — the registry pushes no redraw, and the
+ * injected store plus logger are the only collaborators it touches. The stored document and the patch
+ * both arrive as untrusted JSON, so every field is narrowed here before it is trusted.
+ *
+ * shape: closure returning an object literal — trigger #4, one Map of state plus methods, no subclassing.
+ */
+
+import type { Logger } from "./types/log.ts";
+import type { ModuleDescriptor, Registry, SettingSpec } from "./types/registry.ts";
+import type { ModuleSettings, SettingsDoc, SettingsStore } from "./types/settings.ts";
+
+const SCOPE = "registry";
+
+/** One registered module with its resolved state — the Map value the isEnabled hot path reads. */
+interface ModuleEntry {
+	readonly descriptor: ModuleDescriptor;
+	enabled: boolean;
+	settings: Record<string, unknown>;
+}
+
+/** boundary: a persisted slice and a settings patch both cross as untrusted JSON and narrow here. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// shape: dispatch object — trigger #1, 3 setting kinds, validators stateless.
+const FITS: Record<SettingSpec["kind"], (value: unknown, values: string[] | undefined) => boolean> = {
+	toggle: (value) => typeof value === "boolean",
+	number: (value) => typeof value === "number" && Number.isFinite(value),
+	enum: (value, values) => typeof value === "string" && (values ?? []).includes(value),
+};
+
+function fitsSpec(spec: SettingSpec, value: unknown): boolean {
+	return FITS[spec.kind](value, spec.values);
+}
+
+function logRejected(log: Logger, key: string, name: string): void {
+	log.logOnce(`invalid:${key}:${name}`, SCOPE, `ignored invalid value for ${key}.${name}`);
+}
+
+/** Reads one module's persisted slice into resolved state; anything malformed falls back, logged once. */
+function readEntry(doc: SettingsDoc, descriptor: ModuleDescriptor, log: Logger): ModuleEntry {
+	const stored: unknown = doc.modules[descriptor.key];
+	const slice = isRecord(stored) ? stored : {};
+	const enabled = slice.enabled;
+	const bag = slice.settings;
+	const settings: Record<string, unknown> = {};
+	let malformed = stored !== undefined && !isRecord(stored);
+	malformed ||= enabled !== undefined && typeof enabled !== "boolean";
+	malformed ||= bag !== undefined && !isRecord(bag);
+
+	for (const spec of descriptor.settings) {
+		// Object.hasOwn, not a bare lookup: a declared name must not read an inherited member.
+		const value = isRecord(bag) && Object.hasOwn(bag, spec.name) ? bag[spec.name] : undefined;
+		if (value === undefined) continue;
+		if (fitsSpec(spec, value)) settings[spec.name] = value;
+		else malformed = true;
+	}
+	if (malformed)
+		log.logOnce(`stored:${descriptor.key}`, SCOPE, `malformed stored entry for ${descriptor.key} — using defaults`);
+
+	return { descriptor, enabled: typeof enabled === "boolean" ? enabled : descriptor.defaultEnabled, settings };
+}
+
+export function createRegistry(store: SettingsStore, log: Logger): Registry {
+	const modules = new Map<string, ModuleEntry>();
+	// One read at boot: no render path may touch the disk, so a later write updates this cache directly.
+	const doc = store.load();
+
+	return {
+		defineModule(descriptor: ModuleDescriptor): void {
+			if (modules.has(descriptor.key)) {
+				log.logOnce(
+					`duplicate:${descriptor.key}`,
+					SCOPE,
+					`duplicate module ${descriptor.key} ignored — first definition wins`,
+				);
+				return;
+			}
+			modules.set(descriptor.key, readEntry(doc, descriptor, log));
+		},
+
+		isEnabled(key: string): boolean {
+			return modules.get(key)?.enabled ?? false;
+		},
+
+		getSettings(key: string): Record<string, unknown> {
+			const entry = modules.get(key);
+			if (entry === undefined) return {};
+			const out: Record<string, unknown> = {};
+			for (const spec of entry.descriptor.settings) {
+				out[spec.name] = Object.hasOwn(entry.settings, spec.name) ? entry.settings[spec.name] : spec.default;
+			}
+			return out;
+		},
+
+		setSettings(key: string, patch: object): void {
+			const entry = modules.get(key);
+			if (entry === undefined) {
+				log.logOnce(`unknown:${key}`, SCOPE, `ignored settings write for unknown module ${key}`);
+				return;
+			}
+			const raw: unknown = patch;
+			if (!isRecord(raw)) {
+				log.logOnce(`patch:${key}`, SCOPE, `ignored non-object settings patch for ${key}`);
+				return;
+			}
+
+			let enabled = entry.enabled;
+			const bag: Record<string, unknown> = { ...entry.settings };
+			const enabledPatch = raw.enabled;
+			if (enabledPatch !== undefined) {
+				if (typeof enabledPatch === "boolean") enabled = enabledPatch;
+				else logRejected(log, key, "enabled");
+			}
+			for (const name of Object.keys(raw)) {
+				if (name === "enabled") continue;
+				const spec = entry.descriptor.settings.find((s) => s.name === name);
+				const value = raw[name];
+				if (spec !== undefined && fitsSpec(spec, value)) bag[name] = value;
+				else logRejected(log, key, name);
+			}
+
+			const next: ModuleSettings = { enabled, settings: bag };
+			doc.modules[key] = next;
+			entry.enabled = enabled;
+			entry.settings = bag;
+			store.save(doc);
+		},
+	};
+}

package/src/core/settings.test.ts

@@ -0,0 +1,183 @@
+// Fixture provenance — every document below is invented: pi-render itself writes this file, so there
+// is no upstream payload to record; the file bytes are the fixture. The log double and the fs mock are
+// local, so this ticket stays independent of T-06's logger implementation.
+
+// The `node:fs` ESM namespace is not configurable, so read/write/rename are wrapped to *observe* the
+// real syscalls without replacing them.
+vi.mock("node:fs", async (importOriginal) => {
+	const actual = await importOriginal<typeof import("node:fs")>();
+	return {
+		...actual,
+		readFileSync: vi.fn(actual.readFileSync),
+		writeFileSync: vi.fn(actual.writeFileSync),
+		renameSync: vi.fn(actual.renameSync),
+	};
+});
+
+// shape: none — test module: every behavior is asserted only through the createSettingsStore seam.
+import * as fs from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { LogEntry, Logger, SettingsDoc } from "../core/types.ts";
+import { createSettingsStore } from "./settings.ts";
+
+const DEFAULTS: SettingsDoc = { version: 1, modules: {} };
+
+function readCount(): number {
+	return vi.mocked(fs.readFileSync).mock.calls.length;
+}
+
+function createRecordingLogger(): Logger & { entries: LogEntry[] } {
+	const entries: LogEntry[] = [];
+	const push = (scope: string, message: string): void => {
+		entries.push({ scope, message, time: Date.now() });
+	};
+	return {
+		entries,
+		logLine: push,
+		logOnce: (_key, scope, message) => push(scope, message),
+		drain: () => entries.splice(0),
+	};
+}
+
+describe("core/settings — persisted settings document", () => {
+	let dir: string;
+	let path: string;
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		dir = fs.mkdtempSync(join(tmpdir(), "pi-render-settings-"));
+		path = join(dir, "settings.json");
+	});
+
+	afterEach(() => {
+		vi.unstubAllEnvs();
+		fs.rmSync(dir, { recursive: true, force: true });
+	});
+
+	test("default path: with no injected path the doc lands under the host agent dir", () => {
+		vi.stubEnv("PI_CODING_AGENT_DIR", dir);
+		const doc: SettingsDoc = { version: 1, modules: { "row.bash": { enabled: false } } };
+		createSettingsStore().save(doc);
+
+		expect(JSON.parse(fs.readFileSync(join(dir, "pi-render", "settings.json"), "utf8"))).toEqual(doc);
+	});
+
+	test("AC-1: after the first load every load is served from memory, not the disk", () => {
+		const store = createSettingsStore({ path });
+		expect(store.load()).toEqual(DEFAULTS);
+		expect(readCount()).toBe(1); // the one and only disk read
+
+		expect(store.load()).toEqual(DEFAULTS);
+		expect(store.load()).toEqual(DEFAULTS);
+		expect(readCount()).toBe(1); // a re-read per call is the #21 contributor returning
+
+		// A cache miss would be observable: the file now holds a different doc, yet the cached one reads back.
+		fs.writeFileSync(path, JSON.stringify({ version: 1, modules: { "row.bash": { enabled: false } } }));
+		expect(store.load()).toEqual(DEFAULTS);
+		expect(readCount()).toBe(1);
+	});
+
+	test("AC-1: save() reaches the disk and refreshes the cache without a read", () => {
+		const store = createSettingsStore({ path });
+		store.load();
+		const doc2: SettingsDoc = { version: 1, modules: { "row.bash": { enabled: false, settings: { collapseAt: 3 } } } };
+		store.save(doc2);
+
+		expect(readCount()).toBe(1); // save wrote; it did not read
+		expect(store.load()).toEqual(doc2);
+		expect(readCount()).toBe(1);
+		expect(createSettingsStore({ path }).load()).toEqual(doc2); // fresh store: the save is durable
+		expect(readCount()).toBe(2);
+
+		// Cached: replacing the file's content does not change what this store returns.
+		fs.writeFileSync(path, JSON.stringify({ version: 1, modules: {} }));
+		expect(store.load()).toEqual(doc2);
+		expect(readCount()).toBe(2);
+	});
+
+	test("AC-2: a malformed doc returns defaults with exactly one log line, no throw", () => {
+		fs.writeFileSync(path, "{ not json");
+		const log = createRecordingLogger();
+		const store = createSettingsStore({ path, logger: log });
+
+		expect(() => store.load()).not.toThrow();
+		expect(store.load()).toEqual(DEFAULTS);
+		expect(log.entries).toHaveLength(1);
+	});
+
+	test("AC-2: a parseable non-document returns defaults with exactly one log line, no throw", () => {
+		fs.writeFileSync(path, JSON.stringify({ version: 1, modules: "not-a-map" }));
+		const log = createRecordingLogger();
+		const store = createSettingsStore({ path, logger: log });
+
+		expect(() => store.load()).not.toThrow();
+		expect(store.load()).toEqual(DEFAULTS);
+		expect(log.entries).toHaveLength(1);
+	});
+
+	test("AC-2: an absent file is a first run, not a fault — defaults with no log line", () => {
+		const log = createRecordingLogger();
+		const store = createSettingsStore({ path, logger: log });
+
+		expect(store.load()).toEqual(DEFAULTS);
+		expect(log.entries).toHaveLength(0);
+	});
+
+	test("AC-3: an entry missing its fields reads defaults while the other entry persists", () => {
+		fs.writeFileSync(
+			path,
+			JSON.stringify({
+				modules: {
+					"row.bash": { enabled: false, settings: { collapseAt: 3 } },
+					"content.table": {},
+				},
+			}),
+		);
+
+		const doc = createSettingsStore({ path }).load();
+		expect(doc.version).toBe(1); // doc-level default filled
+		expect(doc.modules["row.bash"]).toEqual({ enabled: false, settings: { collapseAt: 3 } });
+		expect(doc.modules["content.table"]).toEqual({ enabled: true });
+	});
+
+	test("AC-3: a module key absent from the doc does not wipe the other keys", () => {
+		fs.writeFileSync(path, JSON.stringify({ version: 1, modules: { "row.bash": { enabled: false } } }));
+
+		const doc = createSettingsStore({ path }).load();
+		expect(doc.version).toBe(1);
+		expect(doc.modules["row.bash"]).toEqual({ enabled: false });
+		expect("content.table" in doc.modules).toBe(false); // absent here; the caller applies that module's defaults
+	});
+
+	test("AC-4: the final path is never written in place — only swapped by rename", () => {
+		const store = createSettingsStore({ path });
+		const doc1: SettingsDoc = { version: 1, modules: { "row.bash": { enabled: true } } };
+		const doc2: SettingsDoc = { version: 1, modules: { "content.table": { enabled: false } } };
+		store.save(doc1);
+
+		const writeSpy = vi.mocked(fs.writeFileSync);
+		const renameSpy = vi.mocked(fs.renameSync);
+		writeSpy.mockClear();
+		renameSpy.mockClear();
+		store.save(doc2);
+
+		// A write to `path` itself is the torn-write case: the final file is only ever complete.
+		expect(writeSpy.mock.calls.map(([file]) => String(file))).toEqual([`${path}.tmp`]);
+		expect(renameSpy.mock.calls.map(([from, to]) => [String(from), String(to)])).toEqual([[`${path}.tmp`, path]]);
+		expect(JSON.parse(fs.readFileSync(path, "utf8"))).toEqual(doc2);
+		expect(fs.existsSync(`${path}.tmp`)).toBe(false); // no leftover temp file
+	});
+
+	test("AC-4: a reader of the final path sees the old doc complete, then the new doc complete", () => {
+		const store = createSettingsStore({ path });
+		const doc1: SettingsDoc = { version: 1, modules: { "row.bash": { enabled: true } } };
+		const doc2: SettingsDoc = { version: 1, modules: { "content.table": { enabled: false } } };
+		store.save(doc1);
+		expect(JSON.parse(fs.readFileSync(path, "utf8"))).toEqual(doc1);
+
+		store.save(doc2);
+		expect(JSON.parse(fs.readFileSync(path, "utf8"))).toEqual(doc2);
+	});
+});