@dogfood-lab/ingest 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+<p align="center">
+  <a href="https://github.com/dogfood-lab/testing-os">
+    <img src="https://raw.githubusercontent.com/dogfood-lab/testing-os/main/assets/logo.png" alt="testing-os" width="280">
+  </a>
+</p>
+
+# @dogfood-lab/ingest
+
+> Ingestion pipeline for testing-os. Thin glue: dispatch → verifier → persist → indexes.
+
+Part of the [`testing-os`](https://github.com/dogfood-lab/testing-os) monorepo — the operating system for testing in the AI era.
+
+Runs on the receiving side of the dogfood loop. Receives `repository_dispatch` payloads from consumer repos, validates them through `@dogfood-lab/verify`, persists records under `records/`, and rebuilds the read-side indexes (`latest-by-repo.json`, `failing.json`, `stale.json`) atomically.
+
+## Install
+
+```bash
+npm install @dogfood-lab/ingest
+```
+
+## Usage — programmatic
+
+```js
+import { run } from '@dogfood-lab/ingest';
+
+const result = await run({
+  payloadPath: './incoming.json',
+  repoRoot: process.cwd(),
+  provenance: 'github',
+});
+
+console.log(result.persisted_records);  // count of new records written
+console.log(result.indexes_rebuilt);    // boolean
+console.log(result.rejected);           // array of rejection reasons (if any)
+```
+
+## Usage — CLI
+
+```bash
+npx @dogfood-lab/ingest run --payload incoming.json --repo-root .
+```
+
+The CLI exits with structured exit codes:
+
+- `0` — ok, all records persisted
+- `1` — user error (bad payload shape, missing files, invalid args)
+- `2` — runtime error (downstream validator failure, I/O failure)
+- `3` — partial success (some records persisted, some rejected)
+
+## Pipeline stages
+
+| Stage | Module | Output |
+|---|---|---|
+| 1. Load context | `load-context.js` | Reads existing `records/`, `policies/`, prior indexes into memory |
+| 2. Validate | delegates to `@dogfood-lab/verify` | Verdict per record: `ok` or `rejection_reasons[]` |
+| 3. Persist | `persist.js` | Two-phase atomic write to `records/<repo>/<record-id>.yaml` |
+| 4. Rebuild indexes | `rebuild-indexes.js` | Regenerates `latest-by-repo.json`, `failing.json`, `stale.json` with crash-safe journaling |
+
+Each stage emits a structured event via `lib/log-stage.js` so the ingest loop is observable end-to-end. Failures at any stage carry a `code`, `message`, and `hint` per the testing-os structured error contract.
+
+## Concurrency + crash safety
+
+- **Per-repo locking**: advisory file lock via `@dogfood-lab/findings/lib/file-lock.js` — Windows-compatible (uses `linkSync` CAS, not `flock`).
+- **Atomic two-phase commit**: `lib/atomic-write.js` writes to a `.tmp-<pid>.json` shadow first, then renames into place with `renameWithRetry` for Windows AV scanner handle-release windows.
+- **Idempotent crash recovery**: `cleanupCrashedJournals` runs at every entry point; partial writes from previous crashes are detected and either completed or rolled back.
+
+## What testing-os ingest does NOT touch
+
+- Consumer source code beyond what's referenced in the dispatch envelope
+- Secrets beyond the dispatch payload's own fields
+- Anything outside the testing-os repo's working tree
+
+The receiver workflow runs with `contents: write` scoped to the testing-os repo only.
+
+## Docs
+
+📖 Full handbook: **<https://dogfood-lab.github.io/testing-os/handbook/>**
+
+## License
+
+MIT © 2026 mcp-tool-shop

package/lib/atomic-write.js

@@ -0,0 +1,101 @@
+/**
+ * Atomic file write — temp+rename so torn writes never silently drop a file
+ * from listings. `rename` is atomic on POSIX and Windows: a concurrent reader
+ * sees either the old contents or the new contents — never a half-written file.
+ *
+ * Sibling of `packages/findings/lib/atomic-write.js`. The two files have the
+ * same contract; the duplication exists because npm workspaces do not allow
+ * `ingest → findings` imports (findings already depends on ingest, and adding
+ * the reverse edge would create a workspace dependency cycle). Class #6
+ * helper-adoption-sweep treats them as a single canonical pattern even though
+ * the source lives in two places — the canonical contract is "one writeFileSync
+ * to a temp suffix, then renameSync; no caller assembles the temp+rename
+ * pattern inline anywhere else under packages/ingest/."
+ *
+ * Used by `rebuild-indexes.js` for the per-file leg of its multi-file commit
+ * group (W3-PIPE-002). The commit group itself is a thin layer on top of
+ * this helper — see `commitGroupRename` in rebuild-indexes for that.
+ */
+
+import fs from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { renameWithRetry } from './rename-with-retry.js';
+
+/**
+ * Atomically write `content` to `path`.
+ *
+ * @param {string} path - Final destination path.
+ * @param {string} content - File contents.
+ * @param {BufferEncoding} [encoding='utf-8'] - Write encoding.
+ * @returns {string} - The path that was written.
+ */
+export function atomicWriteFileSync(path, content, encoding = 'utf-8') {
+  const tmpSuffix = randomBytes(4).toString('hex');
+  const tmpPath = `${path}.${tmpSuffix}.tmp`;
+  try {
+    // Indirect via `fs.*` (not destructured imports) so test mocks of
+    // `fs.writeFileSync` reach this code path. Mirrors findings/lib/atomic-write.js.
+    fs.writeFileSync(tmpPath, content, encoding);
+    // Windows-only: rename can transiently fail with EPERM/EBUSY when AV or
+    // Search Indexer holds a handle on the just-written temp. Bounded retry.
+    renameWithRetry(tmpPath, path);
+  } catch (err) {
+    try { fs.unlinkSync(tmpPath); } catch { /* tmp may not exist */ }
+    throw err;
+  }
+  return path;
+}
+
+/**
+ * Stage `content` to a temp file alongside `path`. Returns the temp path so
+ * a later commit-group operation can rename it. Does NOT remove the temp
+ * if the caller throws — caller owns cleanup via `discardStaged`.
+ *
+ * Why exposed: `rebuild-indexes.js` needs a two-phase-commit shape — write
+ * all 3 temps, THEN rename them all in sequence. The non-staging
+ * `atomicWriteFileSync` couples write+rename, which is exactly what we
+ * cannot do for multi-file atomicity.
+ *
+ * @param {string} path - Final destination path (NOT created here).
+ * @param {string} content
+ * @param {BufferEncoding} [encoding='utf-8']
+ * @returns {string} The temp path holding the staged content.
+ */
+export function stageWriteFileSync(path, content, encoding = 'utf-8') {
+  const tmpSuffix = randomBytes(4).toString('hex');
+  const tmpPath = `${path}.${tmpSuffix}.tmp`;
+  try {
+    fs.writeFileSync(tmpPath, content, encoding);
+    return tmpPath;
+  } catch (err) {
+    try { fs.unlinkSync(tmpPath); } catch { /* tmp may not exist */ }
+    throw err;
+  }
+}
+
+/**
+ * Promote one staged temp path to its final name. Wraps `renameSync` so
+ * call sites don't have to know the rename is the only step. Throws on
+ * failure; partial-failure handling is the caller's responsibility (see
+ * `rebuild-indexes.js`'s `commitGroupRename` for the multi-file case).
+ *
+ * @param {string} tmpPath
+ * @param {string} finalPath
+ */
+export function promoteStaged(tmpPath, finalPath) {
+  // Windows EPERM/EBUSY tolerance — the multi-file commit group in
+  // rebuild-indexes.js relies on each promoteStaged hop succeeding; a
+  // transient AV/Search-Indexer handle would otherwise abort the group
+  // partway through.
+  renameWithRetry(tmpPath, finalPath);
+}
+
+/**
+ * Best-effort cleanup of staged temp files. Safe to call on a path that
+ * doesn't exist.
+ *
+ * @param {string} tmpPath
+ */
+export function discardStaged(tmpPath) {
+  try { fs.unlinkSync(tmpPath); } catch { /* may not exist */ }
+}

package/lib/rename-with-retry.js

@@ -0,0 +1,39 @@
+/**
+ * renameWithRetry — Windows-tolerant atomic rename.
+ *
+ * Sibling of `packages/findings/lib/rename-with-retry.js`. The two files
+ * have the same contract; the duplication exists because npm workspaces do
+ * not allow `ingest → findings` imports (findings already depends on ingest,
+ * and adding the reverse edge would create a workspace dependency cycle).
+ *
+ * On Windows NTFS, `renameSync(tmp, target)` can throw EPERM/EBUSY even when
+ * the calling process holds the file lock, because antivirus / Search Indexer
+ * / backup agents hold transient handles across the rename window. Bounded
+ * exponential backoff retries past the transient handle.
+ *
+ * Synchronous-on-purpose: the call sites (atomic-write helpers, rebuild-indexes,
+ * event-log appender) are themselves synchronous, and an async retry would
+ * leak the boundary into otherwise-deterministic flush paths.
+ *
+ * @param {string} tmp - Source path (the just-written temp file).
+ * @param {string} dest - Destination path (the canonical artifact).
+ * @param {object} [opts]
+ * @param {number} [opts.retries=10] - Max retry attempts after the first failure.
+ * @param {number} [opts.baseMs=15]  - Initial backoff in ms (doubles each step).
+ * @param {number} [opts.maxMs=200]  - Cap on per-step backoff.
+ */
+import { renameSync } from 'node:fs';
+
+export function renameWithRetry(tmp, dest, { retries = 10, baseMs = 15, maxMs = 200 } = {}) {
+  for (let i = 0; i <= retries; i++) {
+    try {
+      renameSync(tmp, dest);
+      return;
+    } catch (err) {
+      if ((err.code !== 'EPERM' && err.code !== 'EBUSY') || i === retries) throw err;
+      const delay = Math.min(baseMs * (1 << i), maxMs);
+      const until = Date.now() + delay;
+      while (Date.now() < until) { /* spin */ }
+    }
+  }
+}

package/lib/unsafe-segment.js

@@ -0,0 +1,36 @@
+/**
+ * unsafe-segment.js — central path-segment safety helper.
+ *
+ * Three callsites previously defined or duplicated this regex (F-916867-005):
+ *   - packages/ingest/persist.js (canonical instance)
+ *   - packages/ingest/load-context.js (loadRepoPolicy + githubScenarioFetcher)
+ *   - packages/findings/derive/load-records.js (the missing third callsite)
+ *
+ * The check rejects path-traversal substrings (`..`) and any path separator
+ * (`/`, `\`). Single dots remain legal because GitHub permits dotted org/repo
+ * names like `next.js`, `mcp-tool-shop.github.io`, `repo.io`. The submission
+ * schema's repo pattern `^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$` agrees.
+ *
+ * F-375053-006 regression — an earlier `/[.\/]/` was over-broad and crashed
+ * legitimate submissions inside writeRecord. The narrower `/\.\.|[/\\]/` has
+ * stood since wave 9; this helper is the productized form.
+ */
+
+/**
+ * Regex matching unsafe substrings in a single path segment.
+ * Use `.test(segment)` — returns true if the segment is unsafe.
+ *
+ * @type {RegExp}
+ */
+export const UNSAFE_SEGMENT = /\.\.|[/\\]/;
+
+/**
+ * Predicate form: returns true when the given segment contains a path-traversal
+ * substring or a path separator.
+ *
+ * @param {string} segment - A single path-segment candidate (e.g. an org or repo name).
+ * @returns {boolean}
+ */
+export function isUnsafeSegment(segment) {
+  return UNSAFE_SEGMENT.test(segment);
+}

package/load-context.js

@@ -0,0 +1,131 @@
+/**
+ * Context loader
+ *
+ * Gathers everything the verifier needs:
+ * - Global policy
+ * - Repo policy (optional, missing is valid)
+ * - Scenario definitions from source repo (optional, missing becomes rejection reason)
+ * - Payload normalization
+ *
+ * Scenario loading uses a fetch adapter so it can be stubbed in tests.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+
+import { isUnsafeSegment } from './lib/unsafe-segment.js';
+
+/**
+ * Load the global policy.
+ *
+ * @param {string} repoRoot
+ * @returns {object}
+ */
+export function loadGlobalPolicy(repoRoot) {
+  const path = join(repoRoot, 'policies', 'global-policy.yaml');
+  return yaml.load(readFileSync(path, 'utf-8'));
+}
+
+/**
+ * Load repo-specific policy. Returns null if no policy exists.
+ *
+ * @param {string} repoSlug - e.g. "mcp-tool-shop-org/dogfood-labs"
+ * @param {string} repoRoot
+ * @returns {object|null}
+ */
+export function loadRepoPolicy(repoSlug, repoRoot) {
+  const [org, repo] = repoSlug.split('/');
+  if (!org || !repo || isUnsafeSegment(org) || isUnsafeSegment(repo)) return null;
+  const path = join(repoRoot, 'policies', 'repos', org, `${repo}.yaml`);
+
+  if (!existsSync(path)) return null;
+  try {
+    return yaml.load(readFileSync(path, 'utf-8'));
+  } catch {
+    console.warn(`load-context: malformed YAML in repo policy for ${repoSlug}`);
+    return null;
+  }
+}
+
+/**
+ * Default scenario fetcher that reads from the local filesystem.
+ * Used when dogfood-labs is dogfooding itself.
+ *
+ * @param {string} repoRoot - Root of the source repo
+ * @returns {object} Scenario fetch adapter
+ */
+export function localScenarioFetcher(repoRoot) {
+  return {
+    async fetch(scenarioId) {
+      if (!/^[\w-]+$/.test(scenarioId)) return null;
+      const path = join(repoRoot, 'dogfood', 'scenarios', `${scenarioId}.yaml`);
+      if (!existsSync(path)) return null;
+      return yaml.load(readFileSync(path, 'utf-8'));
+    }
+  };
+}
+
+/**
+ * GitHub scenario fetcher. Loads scenario definitions from a source repo
+ * via the GitHub API at a specific commit SHA.
+ *
+ * @param {string} token - GitHub PAT
+ * @param {string} repoSlug - e.g. "mcp-tool-shop-org/shipcheck"
+ * @param {string} commitSha - Commit to fetch scenarios from
+ * @returns {object} Scenario fetch adapter
+ */
+export function githubScenarioFetcher(token, repoSlug, commitSha) {
+  const [org, repo] = repoSlug.split('/');
+  if (!org || !repo || isUnsafeSegment(org) || isUnsafeSegment(repo)) {
+    return { async fetch() { return null; } };
+  }
+  return {
+    async fetch(scenarioId) {
+      if (!/^[\w-]+$/.test(scenarioId)) return null;
+      const path = `dogfood/scenarios/${scenarioId}.yaml`;
+      const url = `https://api.github.com/repos/${repoSlug}/contents/${path}?ref=${commitSha}`;
+
+      try {
+        const resp = await globalThis.fetch(url, {
+          headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/vnd.github.raw+json',
+            'X-GitHub-Api-Version': '2022-11-28'
+          }
+        });
+        if (!resp.ok) return null;
+        const text = await resp.text();
+        return yaml.load(text);
+      } catch {
+        return null;
+      }
+    }
+  };
+}
+
+/**
+ * Load all scenario definitions referenced by a submission's scenario_results.
+ *
+ * @param {object} submission
+ * @param {object} scenarioFetcher - { fetch(scenarioId) => Promise<object|null> }
+ * @returns {Promise<{ scenarios: Map<string, object>, errors: string[] }>}
+ */
+export async function loadScenarios(submission, scenarioFetcher) {
+  const scenarios = new Map();
+  const errors = [];
+
+  for (const sr of submission.scenario_results || []) {
+    const id = sr.scenario_id;
+    if (scenarios.has(id)) continue;
+
+    const definition = await scenarioFetcher.fetch(id);
+    if (definition) {
+      scenarios.set(id, definition);
+    } else {
+      errors.push(`scenario "${id}" could not be loaded from source repo`);
+    }
+  }
+
+  return { scenarios, errors };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@dogfood-lab/ingest",
+  "version": "1.2.1",
+  "type": "module",
+  "description": "Ingestion pipeline for testing-os. Thin glue: dispatch → verifier → persist → indexes.",
+  "main": "run.js",
+  "exports": {
+    ".": "./run.js",
+    "./lib/*": "./lib/*"
+  },
+  "scripts": {
+    "test": "node --test",
+    "ingest": "node run.js"
+  },
+  "files": [
+    "run.js",
+    "persist.js",
+    "rebuild-indexes.js",
+    "validate-record.js",
+    "load-context.js",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dogfood-lab/dogfood-swarm": "^1.2.0",
+    "@dogfood-lab/schemas": "^1.2.0",
+    "@dogfood-lab/verify": "^1.2.0",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
+    "js-yaml": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "author": "mcp-tool-shop",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogfood-lab/testing-os.git",
+    "directory": "packages/ingest"
+  },
+  "homepage": "https://github.com/dogfood-lab/testing-os",
+  "bugs": {
+    "url": "https://github.com/dogfood-lab/testing-os/issues"
+  },
+  "keywords": [
+    "testing-os",
+    "dogfood-lab",
+    "ingest",
+    "pipeline",
+    "verification"
+  ]
+}

package/persist.js

@@ -0,0 +1,172 @@
+/**
+ * Persist layer
+ *
+ * Writes verified records to the canonical sharded path.
+ * Handles: accepted/rejected routing, atomic write (temp+rename),
+ * duplicate detection by run_id, directory creation.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, renameSync, openSync, closeSync, unlinkSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+import { validateRecord } from './validate-record.js';
+import { isUnsafeSegment } from './lib/unsafe-segment.js';
+
+/**
+ * Error thrown when writeRecord loses a TOCTOU race for the same canonical path.
+ * The first concurrent writer wins; the loser sees this error.
+ */
+export class DuplicateRunIdError extends Error {
+  constructor(runId, path) {
+    super(`duplicate run_id: ${runId} — another writer won the race for ${path}`);
+    this.name = 'DuplicateRunIdError';
+    this.code = 'DUPLICATE_RUN_ID';
+    this.runId = runId;
+    this.path = path;
+  }
+}
+
+/**
+ * Compute the canonical file path for a persisted record.
+ *
+ * Accepted:  records/<org>/<repo>/YYYY/MM/DD/run-<run_id>.json
+ * Rejected:  records/_rejected/<org>/<repo>/YYYY/MM/DD/run-<run_id>.json
+ *
+ * @param {object} record - Persisted record
+ * @param {string} repoRoot - Absolute path to dogfood-labs repo root
+ * @returns {string} Absolute file path
+ */
+export function computeRecordPath(record, repoRoot) {
+  const status = record.verification?.status;
+  const base = status === 'rejected' ? 'records/_rejected' : 'records';
+
+  const [org, repo] = (record.repo || '').split('/');
+  if (!org || !repo) {
+    throw new Error(`invalid repo format: ${record.repo}`);
+  }
+
+  // Path-traversal guard: reject `..` substrings and any path separator.
+  // Single dots are legal in GitHub org/repo names (e.g. `next.js`,
+  // `mcp-tool-shop.github.io`) and the submission schema's repo pattern
+  // `^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$` allows them. Centralized in
+  // ./lib/unsafe-segment.js so all three callsites (persist, load-context,
+  // findings/derive/load-records) agree by import — F-916867-005.
+  if (isUnsafeSegment(org) || isUnsafeSegment(repo)) {
+    throw new Error(`unsafe repo segment: ${record.repo}`);
+  }
+
+  if (!/^[\w-]+$/.test(record.run_id)) {
+    throw new Error(`unsafe run_id: ${record.run_id}`);
+  }
+
+  const finishedAt = record.timing?.finished_at;
+  if (!finishedAt) {
+    throw new Error('record missing timing.finished_at');
+  }
+
+  const date = new Date(finishedAt);
+  if (isNaN(date.getTime())) {
+    throw new Error('Invalid finished_at timestamp');
+  }
+  const year = String(date.getUTCFullYear());
+  const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(date.getUTCDate()).padStart(2, '0');
+
+  const filename = `run-${record.run_id}.json`;
+
+  return join(repoRoot, base, org, repo, year, month, day, filename);
+}
+
+/**
+ * Check if a record with this run_id already exists (accepted or rejected).
+ *
+ * @param {string} runId
+ * @param {object} record - The record (used for repo/timing to compute path)
+ * @param {string} repoRoot
+ * @returns {boolean}
+ */
+export function isDuplicate(runId, record, repoRoot) {
+  // Check accepted path
+  const acceptedRecord = { ...record, verification: { ...record.verification, status: 'accepted' } };
+  const acceptedPath = computeRecordPath(acceptedRecord, repoRoot);
+  if (existsSync(acceptedPath)) return true;
+
+  // Check rejected path
+  const rejectedRecord = { ...record, verification: { ...record.verification, status: 'rejected' } };
+  const rejectedPath = computeRecordPath(rejectedRecord, repoRoot);
+  if (existsSync(rejectedPath)) return true;
+
+  return false;
+}
+
+/**
+ * Write a record atomically: write to temp file, then exclusive-rename into place.
+ *
+ * Race semantics: the canonical path is created via `open(path, 'wx')` (exclusive
+ * create — fails if the path exists). Two concurrent ingests for the same run_id
+ * can both pass `isDuplicate` (no file yet); the FIRST `open(wx)` wins and the
+ * SECOND throws `DuplicateRunIdError` instead of silently overwriting. The
+ * temp+rename pattern still provides crash-atomicity — the canonical file is
+ * either fully written or absent, never partial.
+ *
+ * Why not just `existsSync` then `writeFileSync`? That's the original race —
+ * the existsSync check and the write are not atomic. `open(wx)` collapses both
+ * into a single OS-level call.
+ *
+ * @param {object} record - Persisted record
+ * @param {string} repoRoot - Absolute path to dogfood-labs repo root
+ * @returns {{ path: string, written: boolean }} path and whether a write occurred
+ * @throws {DuplicateRunIdError} when a concurrent writer won the race
+ */
+export function writeRecord(record, repoRoot) {
+  if (isDuplicate(record.run_id, record, repoRoot)) {
+    const path = computeRecordPath(record, repoRoot);
+    return { path, written: false };
+  }
+
+  // Enforce dogfood-record.schema.json BEFORE touching the filesystem.
+  // Better to throw loudly than silently persist a malformed record — the
+  // schema is the contract every downstream consumer relies on.
+  validateRecord(record);
+
+  const path = computeRecordPath(record, repoRoot);
+  const dir = dirname(path);
+
+  mkdirSync(dir, { recursive: true });
+
+  // Race-safe atomic create: try to claim the canonical path with O_EXCL first.
+  // If another writer already won the race, fail closed with DuplicateRunIdError
+  // — never silently overwrite. On success, hold an empty file we'll fill via
+  // temp+rename so the visible bytes are still atomic.
+  let claimed = false;
+  try {
+    const fd = openSync(path, 'wx');
+    closeSync(fd);
+    claimed = true;
+  } catch (err) {
+    if (err && err.code === 'EEXIST') {
+      throw new DuplicateRunIdError(record.run_id, path);
+    }
+    throw err;
+  }
+
+  // Atomic write: temp file → rename over the empty placeholder.
+  const tmpSuffix = randomBytes(4).toString('hex');
+  const tmpPath = `${path}.${tmpSuffix}.tmp`;
+
+  try {
+    writeFileSync(tmpPath, JSON.stringify(record, null, 2) + '\n', 'utf-8');
+    renameSync(tmpPath, path);
+  } catch (err) {
+    // On any failure after we claimed the path, release the claim so a retry
+    // can succeed. The tmp file is best-effort cleanup.
+    if (claimed) {
+      try { unlinkSync(path); } catch { /* placeholder already gone */ }
+    }
+    try { unlinkSync(tmpPath); } catch { /* tmp may not exist */ }
+    throw err;
+  }
+
+  return { path, written: true };
+}