@aldus-runtime/file-store 0.1.0

package/dist/stores.js

@@ -0,0 +1,210 @@
+/**
+ * File-backed implementations of the contract §7 storage ports.
+ *
+ * Every mutating operation runs under a lock (contract §19.1) and writes atomically, so an
+ * interrupted process leaves either the previous state or the new state, never a mixture. Every
+ * read-modify-write preserves properties written by a newer schema version (ADR-0004 decision 3).
+ *
+ * These stores store and retrieve. They do not decide whether a Run may advance (WP-04), whether
+ * a gate is satisfied (WP-05), or what an artifact's lineage is (WP-03).
+ */
+import { readdir } from "node:fs/promises";
+import { validateRecord, fromStructuredError, } from "@aldus-runtime/core";
+import { appendLineSynced, isNotFound } from "./atomic.js";
+import { appendToCollection, readCollection } from "./collections.js";
+import { mergeForWrite, readDocument, writeDocument } from "./document.js";
+import { FileStoreErrorCodes, fileStoreError } from "./errors.js";
+import { readJsonLines, toJsonLine } from "./jsonl.js";
+import { EPISODE_LOCK_RESOURCE, WorkspaceLayout, runLockResource } from "./layout.js";
+/** Schema backing each per-run collection file (contract §7). */
+export const RUN_COLLECTION_SCHEMAS = {
+    artifacts: "ArtifactRef",
+    approvals: "GateDecision",
+    costs: "CostRecord",
+    release: "ReleaseReceipt",
+};
+/* -------------------------------------------------------------------------------------------
+ * Episode
+ * ---------------------------------------------------------------------------------------- */
+/** `.aldus/episode.json` (contract §6.1, §7). */
+export class FileEpisodeStore {
+    #layout;
+    #locks;
+    constructor(layout, locks) {
+        this.#layout = layout;
+        this.#locks = locks;
+    }
+    async get() {
+        const document = await readDocument(this.#layout.episodePath(), "EpisodeRef");
+        return document?.value;
+    }
+    async put(episode) {
+        await this.#locks.withLock(EPISODE_LOCK_RESOURCE, async () => {
+            await writeDocument(this.#layout.episodePath(), episode);
+        });
+    }
+    async update(mutate) {
+        return this.#locks.withLock(EPISODE_LOCK_RESOURCE, async () => {
+            const path = this.#layout.episodePath();
+            const document = await readDocument(path, "EpisodeRef");
+            if (document === undefined) {
+                throw fileStoreError(FileStoreErrorCodes.RECORD_NOT_FOUND, "This workspace has no Episode record, so there is nothing to update.", { category: "not_found", retryable: false, details: { path } });
+            }
+            const next = mutate(document.value);
+            assertValid("EpisodeRef", next);
+            await writeDocument(path, mergeForWrite(document, next));
+            return next;
+        });
+    }
+}
+/* -------------------------------------------------------------------------------------------
+ * Run
+ * ---------------------------------------------------------------------------------------- */
+/** `.aldus/runs/{run-id}/` (contract §6.2, §7). */
+export class FileRunStore {
+    #layout;
+    #locks;
+    constructor(layout, locks) {
+        this.#layout = layout;
+        this.#locks = locks;
+    }
+    async list() {
+        try {
+            const entries = await readdir(this.#layout.runsDirectory(), { withFileTypes: true });
+            return entries
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => entry.name)
+                .sort();
+        }
+        catch (error) {
+            // A workspace with no runs yet is ordinary, not an error.
+            if (isNotFound(error))
+                return [];
+            throw error;
+        }
+    }
+    async get(runId) {
+        const document = await readDocument(this.#layout.runFilePath(runId, "manifest"), "RunManifest");
+        return document?.value;
+    }
+    async create(manifest) {
+        await this.#locks.withLock(runLockResource(manifest.runId), async () => {
+            const path = this.#layout.runFilePath(manifest.runId, "manifest");
+            const existing = await readDocument(path, "RunManifest");
+            if (existing !== undefined) {
+                throw fileStoreError(FileStoreErrorCodes.RECORD_IDENTITY_MISMATCH, `A Run manifest already exists for "${manifest.runId}". Creating it again would ` +
+                    "overwrite an execution record, which contract §6.3 makes append-only.", { category: "conflict", retryable: false, details: { runId: manifest.runId } });
+            }
+            await writeDocument(path, manifest);
+        });
+    }
+    async update(runId, mutate) {
+        return this.#locks.withLock(runLockResource(runId), async () => {
+            const path = this.#layout.runFilePath(runId, "manifest");
+            const document = await readDocument(path, "RunManifest");
+            if (document === undefined) {
+                throw fileStoreError(FileStoreErrorCodes.RECORD_NOT_FOUND, `No Run manifest exists for "${runId}".`, { category: "not_found", retryable: false, details: { runId } });
+            }
+            const next = mutate(document.value);
+            if (next.runId !== runId) {
+                throw fileStoreError(FileStoreErrorCodes.RECORD_IDENTITY_MISMATCH, `An update to Run "${runId}" returned a manifest identifying itself as ` +
+                    `"${next.runId}". Writing it would file one Run's state under another's identity.`, { category: "conflict", retryable: false, details: { runId, returnedRunId: next.runId } });
+            }
+            assertValid("RunManifest", next);
+            await writeDocument(path, mergeForWrite(document, next));
+            return next;
+        });
+    }
+    async listRecords(runId, collection) {
+        const schema = RUN_COLLECTION_SCHEMAS[collection];
+        const stored = await readCollection(this.#layout.runFilePath(runId, collection), schema);
+        return stored.values;
+    }
+    async addRecord(runId, collection, record) {
+        await this.#locks.withLock(runLockResource(runId), async () => {
+            const schema = RUN_COLLECTION_SCHEMAS[collection];
+            assertValid(schema, record);
+            await appendToCollection(this.#layout.runFilePath(runId, collection), schema, record);
+        });
+    }
+}
+/* -------------------------------------------------------------------------------------------
+ * Events
+ * ---------------------------------------------------------------------------------------- */
+/** `.aldus/runs/{run-id}/events.jsonl` (contract §6.4, §7). */
+export class FileEventStore {
+    #layout;
+    #locks;
+    constructor(layout, locks) {
+        this.#layout = layout;
+        this.#locks = locks;
+    }
+    async append(runId, event) {
+        return this.#locks.withLock(runLockResource(runId), async () => {
+            const path = this.#layout.runFilePath(runId, "events");
+            const existing = await this.#readValidated(path, {});
+            const expected = nextSequenceOf(existing.events);
+            if (event.sequence !== undefined && event.sequence !== expected) {
+                throw fileStoreError(FileStoreErrorCodes.EVENT_OUT_OF_SEQUENCE, `Event sequence ${event.sequence} does not follow the log, which expects ${expected}. ` +
+                    "A per-run sequence is a total order (ADR-0005); a gap or a repeat would make the " +
+                    "log unorderable across concurrent sessions.", {
+                    category: "conflict",
+                    retryable: false,
+                    details: { runId, expected, received: event.sequence },
+                });
+            }
+            if (existing.events.some((stored) => stored.eventId === event.eventId)) {
+                throw fileStoreError(FileStoreErrorCodes.EVENT_DUPLICATE, `Event "${event.eventId}" is already in the log for Run "${runId}". Appending it again ` +
+                    "would record one mutation twice (contract §6.4).", { category: "conflict", retryable: false, details: { runId, eventId: event.eventId } });
+            }
+            const stored = { ...event, sequence: expected };
+            assertValid("AldusEvent", stored);
+            await appendLineSynced(path, toJsonLine(stored));
+            return stored;
+        });
+    }
+    async read(runId, options = {}) {
+        return this.#readValidated(this.#layout.runFilePath(runId, "events"), options);
+    }
+    async nextSequence(runId) {
+        const result = await this.read(runId);
+        return nextSequenceOf(result.events);
+    }
+    async #readValidated(path, options) {
+        const lines = await readJsonLines(path, {
+            path,
+            ...(options.strictTail === undefined ? {} : { strictTail: options.strictTail }),
+        });
+        const events = [];
+        for (let index = 0; index < lines.values.length; index += 1) {
+            const result = validateRecord("AldusEvent", lines.values[index]);
+            if (!result.ok) {
+                const error = fromStructuredError(result.error);
+                throw fileStoreError(FileStoreErrorCodes.EVENT_LOG_CORRUPT, `Line ${index + 1} of the event log parsed as JSON but is not a valid AldusEvent: ${error.message}`, { category: "io", retryable: false, details: { path, line: index + 1 } });
+            }
+            events.push(result.value);
+        }
+        return lines.tornTail === undefined ? { events } : { events, tornTail: lines.tornTail };
+    }
+}
+/**
+ * The sequence the next event should carry.
+ *
+ * Derived from the highest stored sequence rather than the event count, so a log read after a
+ * torn-tail recovery still assigns a sequence strictly greater than anything already durable.
+ */
+export function nextSequenceOf(events) {
+    let highest = -1;
+    for (const event of events) {
+        if (event.sequence !== undefined && event.sequence > highest)
+            highest = event.sequence;
+    }
+    return highest + 1;
+}
+/** Validate before writing, so a malformed record never reaches disk. */
+function assertValid(schema, value) {
+    const result = validateRecord(schema, value);
+    if (!result.ok)
+        throw fromStructuredError(result.error);
+}
+//# sourceMappingURL=stores.js.map

package/dist/stores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.js","sourceRoot":"","sources":["../src/stores.ts"],"names":[],"mappings":"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"}

package/dist/workspace.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A file-backed Aldus workspace.
+ *
+ * Wires the contract §7 layout, the lock manager, and the three stores into one object, so a
+ * caller binds to a workspace once rather than threading paths through every call. Contract
+ * §19.2 requires workspace binding to be explicit; constructing this is that binding.
+ */
+import { WorkspaceLayout } from "./layout.js";
+import { type FileLockManagerOptions, type LockManager } from "./lock.js";
+import { FileEpisodeStore, FileEventStore, FileRunStore } from "./stores.js";
+/** Options for opening a workspace. */
+export interface OpenWorkspaceOptions {
+    /** Replace the default file-based lock manager, e.g. with a distributed lease. */
+    locks?: LockManager;
+    /** Tuning for the default lock manager. Ignored when `locks` is supplied. */
+    lockOptions?: FileLockManagerOptions;
+}
+/** The file-backed stores for one workspace. */
+export declare class FileWorkspace {
+    readonly layout: WorkspaceLayout;
+    readonly locks: LockManager;
+    readonly episodes: FileEpisodeStore;
+    readonly runs: FileRunStore;
+    readonly events: FileEventStore;
+    constructor(workspaceRoot: string, options?: OpenWorkspaceOptions);
+}
+/**
+ * Create the `.aldus` directory structure for a workspace.
+ *
+ * Idempotent. Writing a `.gitignore` inside `locks/` is deliberate: §7 recommends a Git-friendly
+ * layout, and a committed lockfile would carry another machine's PID into everyone's checkout and
+ * block the workspace until someone deleted it by hand.
+ */
+export declare function initWorkspace(workspaceRoot: string): Promise<WorkspaceLayout>;
+/** Open a workspace, creating its directory structure if absent. */
+export declare function openWorkspace(workspaceRoot: string, options?: OpenWorkspaceOptions): Promise<FileWorkspace>;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAmB,KAAK,sBAAsB,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7E,uCAAuC;AACvC,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,sBAAsB,CAAC;CACtC;AAED,gDAAgD;AAChD,qBAAa,aAAa;IACxB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC,YAAY,aAAa,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,EAOpE;CACF;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAUnF;AAED,oEAAoE;AACpE,wBAAsB,aAAa,CACjC,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CAGxB"}

package/dist/workspace.js

@@ -0,0 +1,48 @@
+/**
+ * A file-backed Aldus workspace.
+ *
+ * Wires the contract §7 layout, the lock manager, and the three stores into one object, so a
+ * caller binds to a workspace once rather than threading paths through every call. Contract
+ * §19.2 requires workspace binding to be explicit; constructing this is that binding.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { WorkspaceLayout } from "./layout.js";
+import { FileLockManager } from "./lock.js";
+import { FileEpisodeStore, FileEventStore, FileRunStore } from "./stores.js";
+/** The file-backed stores for one workspace. */
+export class FileWorkspace {
+    layout;
+    locks;
+    episodes;
+    runs;
+    events;
+    constructor(workspaceRoot, options = {}) {
+        this.layout = new WorkspaceLayout(workspaceRoot);
+        this.locks =
+            options.locks ?? new FileLockManager(this.layout.locksDirectory(), options.lockOptions ?? {});
+        this.episodes = new FileEpisodeStore(this.layout, this.locks);
+        this.runs = new FileRunStore(this.layout, this.locks);
+        this.events = new FileEventStore(this.layout, this.locks);
+    }
+}
+/**
+ * Create the `.aldus` directory structure for a workspace.
+ *
+ * Idempotent. Writing a `.gitignore` inside `locks/` is deliberate: §7 recommends a Git-friendly
+ * layout, and a committed lockfile would carry another machine's PID into everyone's checkout and
+ * block the workspace until someone deleted it by hand.
+ */
+export async function initWorkspace(workspaceRoot) {
+    const layout = new WorkspaceLayout(workspaceRoot);
+    await mkdir(layout.runsDirectory(), { recursive: true });
+    await mkdir(layout.locksDirectory(), { recursive: true });
+    await writeFile(join(layout.locksDirectory(), ".gitignore"), "# Lockfiles are machine-local runtime state and must never be committed.\n*\n!.gitignore\n", "utf8");
+    return layout;
+}
+/** Open a workspace, creating its directory structure if absent. */
+export async function openWorkspace(workspaceRoot, options = {}) {
+    await initWorkspace(workspaceRoot);
+    return new FileWorkspace(workspaceRoot, options);
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAiD,MAAM,WAAW,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAU7E,gDAAgD;AAChD,MAAM,OAAO,aAAa;IACf,MAAM,CAAkB;IACxB,KAAK,CAAc;IACnB,QAAQ,CAAmB;IAC3B,IAAI,CAAe;IACnB,MAAM,CAAiB;IAEhC,YAAY,aAAqB,EAAE,OAAO,GAAyB,EAAE;QACnE,IAAI,CAAC,MAAM,GAAG,IAAI,eAAe,CAAC,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,KAAK;YACR,OAAO,CAAC,KAAK,IAAI,IAAI,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;QAChG,IAAI,CAAC,QAAQ,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9D,IAAI,CAAC,IAAI,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACtD,IAAI,CAAC,MAAM,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5D,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,aAAqB;IACvD,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,aAAa,CAAC,CAAC;IAClD,MAAM,KAAK,CAAC,MAAM,CAAC,aAAa,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,MAAM,KAAK,CAAC,MAAM,CAAC,cAAc,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,MAAM,SAAS,CACb,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,EAAE,YAAY,CAAC,EAC3C,4FAA4F,EAC5F,MAAM,CACP,CAAC;IACF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,oEAAoE;AACpE,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,aAAqB,EACrB,OAAO,GAAyB,EAAE;IAElC,MAAM,aAAa,CAAC,aAAa,CAAC,CAAC;IACnC,OAAO,IAAI,aAAa,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@aldus-runtime/file-store",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Aldus File Store \u2014 file-backed Episode, Run, and Event stores with atomic writes and crash recovery.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jamchen/aldus",
+    "directory": "packages/aldus-file-store"
+  },
+  "homepage": "https://github.com/jamchen/aldus/tree/main/packages/aldus-file-store#readme",
+  "bugs": {
+    "url": "https://github.com/jamchen/aldus/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --pretty",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck:test": "tsc -p tsconfig.test.json"
+  },
+  "dependencies": {
+    "@aldus-runtime/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@aldus-runtime/testkit": "0.1.0",
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/atomic.ts

@@ -0,0 +1,185 @@
+/**
+ * Crash-safe file primitives.
+ *
+ * Architecture contract §19.1 requires "recovery from partial success" and "recovery from
+ * interrupted writes" (§22 WP-02). The failure this module exists to prevent is concrete: an
+ * operator's machine sleeps, a process is killed, or a container is evicted midway through
+ * rewriting `run.json`, and the next read finds a half-written file where the Run's state used
+ * to be. Contract §3.4 makes files authoritative, so a truncated manifest is not an
+ * inconvenience — it is the loss of the only authoritative record.
+ *
+ * The durability sequence is write-to-temp, fsync the file, rename, fsync the directory. Each
+ * step is load-bearing:
+ *
+ * - **Temp file in the same directory.** `rename` is only atomic within a filesystem. A temp
+ *   file in `os.tmpdir()` may be on a different device, which silently degrades the rename into
+ *   a copy — exactly the non-atomic write this is meant to avoid.
+ * - **fsync the file** before renaming, or the rename can be durable while the contents are not,
+ *   leaving a correctly named empty file after a power loss.
+ * - **fsync the directory** after renaming, or the rename itself may not survive a crash.
+ */
+
+import { constants as fsConstants } from "node:fs";
+import { mkdir, open, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+/** Injection point for the durability sequence, so tests can interrupt it at a chosen step. */
+export interface AtomicWriteHooks {
+  /** Invoked after the temp file is written and synced, before the rename. */
+  beforeRename?: (temporaryPath: string) => void | Promise<void>;
+}
+
+/** Options for {@link writeFileAtomic}. */
+export interface AtomicWriteOptions {
+  /** Test seam; unused in production paths. */
+  hooks?: AtomicWriteHooks;
+}
+
+let temporaryCounter = 0;
+
+/**
+ * Write `contents` to `path` so that a reader sees either the previous bytes or the new bytes,
+ * never a mixture.
+ *
+ * Parent directories are created as needed. The temp file is removed if any step fails, so an
+ * interrupted write leaves no debris for the next reader to mistake for real state.
+ */
+export async function writeFileAtomic(
+  path: string,
+  contents: string,
+  options: AtomicWriteOptions = {},
+): Promise<void> {
+  const directory = dirname(path);
+  await mkdir(directory, { recursive: true });
+
+  // Same directory, therefore same filesystem, therefore a genuinely atomic rename. The counter
+  // plus pid keeps two writers in one process from colliding on the temp name.
+  temporaryCounter += 1;
+  const temporaryPath = join(
+    directory,
+    `.${basenameOf(path)}.${process.pid}.${temporaryCounter}.tmp`,
+  );
+
+  try {
+    const handle = await open(temporaryPath, "w");
+    try {
+      await handle.writeFile(contents, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+
+    await options.hooks?.beforeRename?.(temporaryPath);
+
+    await rename(temporaryPath, path);
+    await syncDirectory(directory);
+  } catch (error) {
+    await unlink(temporaryPath).catch(() => undefined);
+    throw error;
+  }
+}
+
+/**
+ * Append a single line to a file, creating it if absent, and sync before returning.
+ *
+ * Used for the append-only event log (contract §6.4). `O_APPEND` makes each write land at the
+ * current end of file even with concurrent writers, so an interleaved append can never overwrite
+ * another writer's bytes — it can only ever be interleaved *between* lines, or torn at the tail
+ * if the process dies mid-write. {@link readJsonLines} handles the torn tail.
+ */
+export async function appendLineSynced(path: string, line: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const handle = await open(path, "a");
+  try {
+    await handle.writeFile(`${line}\n`, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Read a file, returning `undefined` rather than throwing when it does not exist. */
+export async function readFileOrUndefined(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (isNotFound(error)) return undefined;
+    throw error;
+  }
+}
+
+/** True if `error` is a Node `ENOENT`. */
+export function isNotFound(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+/** True if `error` is a Node `EEXIST`, i.e. an `O_EXCL` create lost the race. */
+export function isAlreadyExists(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "EEXIST";
+}
+
+/**
+ * Create a file only if it does not already exist, returning `false` if it did.
+ *
+ * `O_CREAT | O_EXCL` is the primitive the lock is built on: the check and the create are one
+ * syscall, so two processes racing cannot both believe they created it.
+ */
+export async function createExclusive(path: string, contents: string): Promise<boolean> {
+  await mkdir(dirname(path), { recursive: true });
+  try {
+    const handle = await open(
+      path,
+      fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY,
+    );
+    try {
+      await handle.writeFile(contents, "utf8");
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    return true;
+  } catch (error) {
+    if (isAlreadyExists(error)) return false;
+    throw error;
+  }
+}
+
+/** Overwrite a file in place without the rename dance. Used for lock heartbeats only. */
+export async function overwrite(path: string, contents: string): Promise<void> {
+  await writeFile(path, contents, "utf8");
+}
+
+/** Remove a file, tolerating its absence. */
+export async function removeIfPresent(path: string): Promise<void> {
+  try {
+    await unlink(path);
+  } catch (error) {
+    if (!isNotFound(error)) throw error;
+  }
+}
+
+/**
+ * fsync a directory so that a rename within it survives a crash.
+ *
+ * Not portable: some platforms refuse to open a directory for the purpose. A failure here means
+ * the rename may not be durable across a power loss, which is strictly weaker than the
+ * within-process atomicity the rename already guarantees — so it is tolerated rather than
+ * escalated into a failed write.
+ */
+async function syncDirectory(directory: string): Promise<void> {
+  try {
+    const handle = await open(directory, "r");
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    // Best effort by design; see the doc comment.
+  }
+}
+
+function basenameOf(path: string): string {
+  const index = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return index === -1 ? path : path.slice(index + 1);
+}

package/src/collections.ts

@@ -0,0 +1,94 @@
+/**
+ * Per-run collection files (contract §7: `artifacts.json`, `approvals.json`, `costs.json`,
+ * `release.json`).
+ *
+ * Each holds a JSON array of records that each carry their own `schemaVersion`, so the array
+ * itself needs no envelope. Appending writes back the **raw** parsed array with one element
+ * added, which preserves unknown properties on every existing element for free — there is no
+ * merge to get wrong, because nothing already stored is ever re-serialised from a validated
+ * value (ADR-0004 decision 3).
+ */
+
+import {
+  validateRecord,
+  fromStructuredError,
+  type SchemaTypeFor,
+  type VersionedSchemaName,
+} from "@aldus-runtime/core";
+
+import { readFileOrUndefined, type AtomicWriteOptions } from "./atomic.js";
+import { writeDocument } from "./document.js";
+import { FileStoreErrorCodes, fileStoreError } from "./errors.js";
+
+/** A collection read: validated records plus the raw array they were parsed from. */
+export interface StoredCollection<T> {
+  values: T[];
+  raw: unknown[];
+}
+
+/**
+ * Read and validate a collection file.
+ *
+ * An absent file reads as an empty collection: a Run that has produced no artifacts yet is an
+ * ordinary state (contract §6.2 `created`), not a missing record.
+ */
+export async function readCollection<N extends VersionedSchemaName>(
+  path: string,
+  schema: N,
+): Promise<StoredCollection<SchemaTypeFor<N>>> {
+  const contents = await readFileOrUndefined(path);
+  if (contents === undefined || contents.trim().length === 0) return { values: [], raw: [] };
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(contents);
+  } catch {
+    throw fileStoreError(
+      FileStoreErrorCodes.RECORD_MALFORMED,
+      `The stored ${schema} collection is not valid JSON. Atomic writes make a torn file ` +
+        "impossible, so this means the file was edited or replaced by something other than the store.",
+      { category: "io", retryable: false, details: { path, schema, byteLength: contents.length } },
+    );
+  }
+
+  if (!Array.isArray(parsed)) {
+    throw fileStoreError(
+      FileStoreErrorCodes.RECORD_MALFORMED,
+      `The stored ${schema} collection is valid JSON but not an array.`,
+      { category: "io", retryable: false, details: { path, schema } },
+    );
+  }
+
+  const values: SchemaTypeFor<N>[] = [];
+  for (let index = 0; index < parsed.length; index += 1) {
+    const result = validateRecord(schema, parsed[index]);
+    if (!result.ok) {
+      const error = fromStructuredError(result.error);
+      // Name the offending index. Without it, a 200-element artifacts file reports "one of these
+      // is wrong" and leaves an operator to bisect by hand.
+      throw fileStoreError(
+        FileStoreErrorCodes.RECORD_MALFORMED,
+        `Element ${index} of the stored ${schema} collection is not a valid ${schema}: ${error.message}`,
+        {
+          category: "io",
+          retryable: false,
+          details: { path, schema, index },
+        },
+      );
+    }
+    values.push(result.value);
+  }
+
+  return { values, raw: parsed };
+}
+
+/** Append one record to a collection file, preserving every existing element byte for byte. */
+export async function appendToCollection<N extends VersionedSchemaName>(
+  path: string,
+  schema: N,
+  record: SchemaTypeFor<N>,
+  options: AtomicWriteOptions = {},
+): Promise<void> {
+  const existing = await readCollection(path, schema);
+  await writeDocument(path, [...existing.raw, record], options);
+}