@dogfood-lab/findings 1.3.2 → 1.5.0

package/reader.js

@@ -4,7 +4,7 @@
  */
 
 import { readdirSync, existsSync, statSync } from 'node:fs';
-import { resolve, join, basename, extname } from 'node:path';
+import { resolve, join, basename, extname, relative } from 'node:path';
 import { parseFinding, validateFinding } from './validate.js';
 
 /**
@@ -25,7 +25,18 @@ export function discoverFindings(rootDir) {
     const orgDir = join(findingsDir, org);
     for (const repo of listDirs(orgDir)) {
       const repoDir = join(orgDir, repo);
-      for (const file of readdirSync(repoDir)) {
+      // Leaf-IO guard (B002): the two OUTER levels go through `listDirs`, whose
+      // statSync is wrapped in try/catch so one unreadable dir is skipped. The
+      // innermost leaf read was bare — a single repo dir going unreadable
+      // (EACCES on a locked/permission-restricted dir, an ENOTDIR, a transient
+      // FS error) would throw an unstructured Node stack out of discoverFindings
+      // and hence out of every consumer (validate / list / derivePatterns /
+      // advise / review queue), so one bad directory sank discovery for EVERY
+      // other repo. Mirror the package standard (load-records.js
+      // walkRecordsWithSkips, lib/safe-yaml-load.js walkDir): skip the bad
+      // repoDir instead of throwing, and name it on stderr so the operator sees
+      // WHICH directory was unreadable in CI logs rather than a raw stack.
+      for (const file of listLeafFiles(repoDir)) {
         if (extname(file) === '.yaml') {
           paths.push(resolve(repoDir, file));
         }
@@ -36,6 +47,40 @@ export function discoverFindings(rootDir) {
   return paths.sort();
 }
 
+/**
+ * List the immediate entries of a leaf repo directory, guarding the bare
+ * `readdirSync` against EACCES/ENOTDIR/transient FS errors.
+ *
+ * On error the directory is SKIPPED (returns `[]`) rather than throwing, and a
+ * structured line naming the offending path is written to stderr so the failure
+ * is operator-visible in CI logs. `discoverFindings` returns a `string[]` of
+ * paths (no structured-skip channel rides the return shape), so this mirrors
+ * the `findRecordFile` precedent (derive/load-records.js) of surfacing the skip
+ * via stderr rather than silently swallowing it — a bad directory must not sink
+ * discovery for every other repo, but it must also not vanish without a trace.
+ *
+ * Exported (package-internal) so the B002 leaf-IO guard can be exercised
+ * directly with a real, portable readdir error (readdir on a non-directory
+ * throws ENOTDIR on every platform), since the listDirs+leaf walk couples
+ * statSync and readdirSync such that the failure cannot be staged through the
+ * full walk cross-platform.
+ *
+ * @param {string} repoDir - Absolute path to a findings/<org>/<repo> directory.
+ * @returns {string[]} Entry names, or `[]` if the directory could not be read.
+ */
+export function listLeafFiles(repoDir) {
+  try {
+    return readdirSync(repoDir);
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.error(
+      `discoverFindings: skipping unreadable findings directory ${repoDir}: ${err.message}. ` +
+      `Fix the directory's permissions/state and re-run; other repos were still discovered.`
+    );
+    return [];
+  }
+}
+
 /**
  * Discover finding files from fixtures directory.
  * @param {string} rootDir - The dogfood-labs repo root.
@@ -84,9 +129,21 @@ export function loadFindings(rootDir, opts = {}) {
  * @returns {{ path: string, data: object, valid: boolean, errors: Array } | null}
  */
 export function findById(rootDir, findingId) {
+  // B-002 — collect torn finding files encountered during the scan. The
+  // finding_id lives INSIDE the file, so a torn file cannot be matched to the
+  // requested id; if the id turns out absent from every clean file, any torn
+  // file may be the one hiding it. Surfacing them on stderr (below) mirrors the
+  // derive CLI's "N finding(s) skipped (torn/unreadable)" honesty so a torn
+  // YAML never silently masquerades as a not-found id.
+  const torn = [];
+
   // Search real findings
   for (const filePath of discoverFindings(rootDir)) {
-    const { data } = parseFinding(filePath);
+    const { data, error } = parseFinding(filePath);
+    if (error) {
+      torn.push({ path: filePath, error });
+      continue;
+    }
     if (data && data.finding_id === findingId) {
       const result = validateFinding(data);
       return { path: filePath, data, ...result };
@@ -95,13 +152,26 @@ export function findById(rootDir, findingId) {
 
   // Search valid fixtures
   for (const filePath of discoverFixtures(rootDir, 'valid')) {
-    const { data } = parseFinding(filePath);
+    const { data, error } = parseFinding(filePath);
+    if (error) {
+      torn.push({ path: filePath, error });
+      continue;
+    }
     if (data && data.finding_id === findingId) {
       const result = validateFinding(data);
       return { path: filePath, data, ...result };
     }
   }
 
+  if (torn.length > 0) {
+    // eslint-disable-next-line no-console
+    console.error(`${torn.length} finding(s) skipped (torn/unreadable):`);
+    for (const t of torn) {
+      // eslint-disable-next-line no-console
+      console.error(`  ${relative(rootDir, t.path)} — ${t.error}`);
+    }
+  }
+
   return null;
 }
 

package/review/event-log.js

@@ -1,36 +1,61 @@
 /**
  * Append-only review event log.
  *
- * Events are stored as YAML arrays in reviews/<YYYY>/<date>-finding-review-log.yaml
+ * Events are stored ONE PER FILE under reviews/<YYYY>/<YYYY-MM-DD>/<event-id>.yaml
+ * (the same sharded-immutable-file pattern the records/ store uses). This
+ * replaced an earlier "daily YAML array, read-modify-rename under a file lock"
+ * design: a Phase-9 50-fork race detector proved that NO lock FILE is reliably
+ * exclusive on NTFS under heavy concurrent create churn — two appenders could
+ * both win the lock, both read N events, both rename, and one clobber the
+ * other's event (~1/3 of saturated runs, every child still exiting 0). A
+ * shared mutable array file cannot be made safe under concurrency on that fs.
+ * One immutable file per event removes the shared mutable state entirely: each
+ * append writes a uniquely-named file, so concurrent appends CANNOT collide or
+ * lose an event, and no lock is needed for correctness. `getAllEventsWithSkips`
+ * already globs reviews/ recursively and merges per-file events.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
+import { mkdirSync, existsSync, openSync, writeSync, closeSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import yaml from 'js-yaml';
 
-import { withFileLock } from '../lib/file-lock.js';
-import { renameWithRetry } from '../lib/rename-with-retry.js';
 import { loadYamlDir } from '../lib/safe-yaml-load.js';
 
 let _eventCounter = 0;
 
 /**
- * Generate a unique event ID.
+ * Generate a unique event ID. Includes a random suffix so the id is unique
+ * ACROSS processes (the `_eventCounter` is per-process, so two forks would
+ * otherwise mint the same `rev-<ts>-<seq>`); this id also names the per-event
+ * file, so cross-process uniqueness keeps two concurrent appends from picking
+ * the same filename.
  */
 export function generateEventId() {
   const ts = Date.now().toString(36);
   const seq = (++_eventCounter).toString(36).padStart(4, '0');
-  return `rev-${ts}-${seq}`;
+  const rand = randomBytes(4).toString('hex');
+  return `rev-${ts}-${seq}-${rand}`;
 }
 
 /**
  * Create a review event object.
+ *
+ * F2-INTEL-001 — back-compat extension for synthesis-artifact review events.
+ * The original event shape is keyed by `finding_id`; the synthesis-artifact
+ * review engine (review/review-artifacts.js) operates on patterns /
+ * recommendations / doctrine, which have no `finding_id`. When `params.artifactId`
+ * is supplied the event carries `artifact_id` + `artifact_kind` INSTEAD of
+ * `finding_id`, so the same append-only log and `getAllEvents` reader serve both
+ * object families. Finding events are byte-for-byte unchanged — the artifact
+ * fields are additive and only appear when `artifactId` is set.
  */
 export function createEvent(params) {
   const event = {
     review_event_id: generateEventId(),
-    finding_id: params.findingId,
+    ...(params.artifactId
+      ? { artifact_id: params.artifactId, artifact_kind: params.artifactKind }
+      : { finding_id: params.findingId }),
     timestamp: new Date().toISOString(),
     actor: params.actor,
     action: params.action,
@@ -60,82 +85,52 @@ export function getLogPath(rootDir, date = new Date()) {
 }
 
 /**
- * Append an event to the review log.
+ * Directory holding one date-sharded set of per-event files:
+ * reviews/<YYYY>/<YYYY-MM-DD>/. Each appended event is its own file inside.
+ */
+export function getEventDir(rootDir, date = new Date()) {
+  const year = String(date.getFullYear());
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return resolve(rootDir, 'reviews', year, `${year}-${month}-${day}`);
+}
+
+/**
+ * Append a review event by writing it to its OWN immutable file
+ * (reviews/<YYYY>/<YYYY-MM-DD>/<event-id>.yaml). See the module header for why
+ * this replaced the daily-array-under-a-lock design: no shared mutable file
+ * means concurrent appends physically cannot collide or lose an event, so no
+ * lock is needed for correctness — the Phase-9 50-fork race detector that lost
+ * an event ~1/3 of saturated runs is structurally impossible here.
  *
- * Atomicity: writes the new event list to a unique temp file then renames it
- * over the canonical log file. `rename` is atomic on POSIX and Windows, so a
- * concurrent reader sees either the old contents or the new contents — never
- * a half-written file. This also makes the operation crash-safe: a Ctrl+C
- * between read and write leaves the original log intact.
+ * Crash-safety: a single `openSync(path, 'wx')` + write of one event is atomic
+ * at the file granularity — a crash mid-write leaves a complete event file or
+ * none, never a torn shared array. The filename is the (cross-process-unique)
+ * event id, so two concurrent appends never target the same path.
  *
- * Concurrency: serialized at the choke point via `withFileLock` on the daily
- * log file (F-PIPELINE-011 / W3-PIPE-001 — Pattern #4 choke-point fix). The
- * read-then-write window is closed by holding a directory-mutex (`<logPath>.lock`)
- * across the read → push → rename sequence. Two concurrent `appendEvent` calls
- * to the SAME daily log serialize against each other; calls to DIFFERENT daily
- * logs (e.g. across a midnight boundary) do not contend. The lock is reclaimed
- * if the holder process dies — see `lib/file-lock.js` for the full design
- * rationale (why a lock dir, why not `O_APPEND`, stale recovery semantics,
- * single-machine scope).
+ * @param {string} rootDir
+ * @param {object} event - a `createEvent()` result.
+ * @returns {string} the path of the event file written.
  */
 export function appendEvent(rootDir, event) {
-  const logPath = getLogPath(rootDir);
-  const dir = dirname(logPath);
+  const dir = getEventDir(rootDir);
   mkdirSync(dir, { recursive: true });
 
-  // FAILS-then-PASSES proof gate (W3-PIPE-001):
-  // Set DISABLE_APPEND_LOCK=1 in the env to bypass the lock for the explicit
-  // purpose of demonstrating the race-detection test fails without the fix.
-  // Wave-30 receipt documents the proof: with the lock, the multi-process
-  // test passes 50/50 forks across 3 iterations, 20 consecutive test runs.
-  // With the lock disabled, the test reliably fails (rename collisions on
-  // unprotected concurrent rebuilds, dropped events).
-  if (process.env.DISABLE_APPEND_LOCK) {
-    let events = [];
-    if (existsSync(logPath)) {
-      const raw = readFileSync(logPath, 'utf-8');
-      events = yaml.load(raw) || [];
-      if (!Array.isArray(events)) events = [events];
-    }
-    events.push(event);
-    const tmpSuffix = randomBytes(4).toString('hex');
-    const tmpPath = `${logPath}.${tmpSuffix}.tmp`;
-    writeFileSync(tmpPath, yaml.dump(events, { lineWidth: 120, noRefs: true }), 'utf-8');
-    // Windows EPERM/EBUSY on rename can fire transiently when AV or
-    // Search Indexer holds a handle to the freshly written temp. Retry.
-    renameWithRetry(tmpPath, logPath);
-    return logPath;
+  const eventId = event.review_event_id || generateEventId();
+  const eventPath = resolve(dir, `${eventId}.yaml`);
+  const body = yaml.dump(event, { lineWidth: 120, noRefs: true });
+
+  // 'wx' = O_EXCL exclusive-create: asserts the unique id has not collided
+  // (it carries a random suffix, so it won't) rather than relying on it. No
+  // temp+rename is needed — there is no shared file to atomically replace; one
+  // event per file is already all-or-nothing.
+  const fd = openSync(eventPath, 'wx');
+  try {
+    writeSync(fd, body);
+  } finally {
+    closeSync(fd);
   }
-
-  return withFileLock(logPath, () => {
-    let events = [];
-    // Read-or-empty without an `existsSync` precheck: the readFileSync call
-    // either returns the bytes or throws ENOENT. Avoiding `existsSync` here
-    // closes a Windows-specific TOCTOU window where the dirent cache could
-    // report `existsSync(logPath) === false` immediately after a sibling
-    // process renamed a fresh file into place — which would cause us to
-    // start with `events = []` and silently OVERWRITE the sibling's events.
-    // The lock alone wasn't enough; the existsSync gate was the bug.
-    try {
-      const raw = readFileSync(logPath, 'utf-8');
-      const parsed = yaml.load(raw);
-      if (parsed) events = Array.isArray(parsed) ? parsed : [parsed];
-    } catch (err) {
-      if (!err || err.code !== 'ENOENT') throw err;
-    }
-
-    events.push(event);
-
-    // Atomic write: temp file → rename. Same pattern persist.js + rebuild-indexes.js use.
-    const tmpSuffix = randomBytes(4).toString('hex');
-    const tmpPath = `${logPath}.${tmpSuffix}.tmp`;
-    writeFileSync(tmpPath, yaml.dump(events, { lineWidth: 120, noRefs: true }), 'utf-8');
-    // renameWithRetry: tolerate the Windows EPERM/EBUSY transient handle race
-    // even though we hold the per-file lock — antivirus/Search Indexer can
-    // still grab a handle on the temp during the rename window.
-    renameWithRetry(tmpPath, logPath);
-    return logPath;
-  });
+  return eventPath;
 }
 
 /**

package/review/review-artifacts.js

@@ -0,0 +1,301 @@
+/**
+ * Review engine for SYNTHESIS ARTIFACTS (patterns / recommendations / doctrine).
+ *
+ * F2-INTEL-001 — closes the intelligence loop. `synthesis/` derives patterns,
+ * recommendations, and doctrine and writes them with `status: 'candidate'`, but
+ * `advise/query.js` (`queryPatterns` / `queryRecommendations` / `queryDoctrine`)
+ * surfaces ONLY `status === 'accepted'`. At HEAD the finding review engine
+ * (`review/review-engine.js`) could promote findings, but NOTHING could promote
+ * a synthesis artifact candidate → accepted, so nothing the intelligence layer
+ * derived ever reached the advise surface. This module is the missing verb.
+ *
+ * It mirrors `performAction` (review/review-engine.js) and REUSES the finding
+ * status law verbatim (`validateTransition`, `ACTION_TARGET_STATUS`,
+ * `REASON_REQUIRED`, `REQUIRES_ACCEPTED`, `REQUIRES_CLOSED` from
+ * review/transitions.js). Persistence goes through the synthesis writers
+ * (`writePattern` / `writeRecommendation` / `writeDoctrine`), which re-validate
+ * the promoted artifact against its JSON Schema before it touches disk.
+ *
+ * Contract reality (load-bearing): the artifact schemas constrain `status` to a
+ * NARROWER set than findings —
+ *   pattern        : candidate | accepted | rejected | invalidated
+ *   recommendation : candidate | accepted | rejected
+ *   doctrine       : candidate | accepted | rejected
+ * None of them permit `reviewed`. The finding law's intermediate `reviewed`
+ * state is therefore not expressible for artifacts: actions whose
+ * `ACTION_TARGET_STATUS` is `reviewed` (`review`, `reopen`) cannot persist a
+ * schema-valid artifact, and so are refused HONESTLY with a structured error
+ * rather than writing an artifact the contract would reject. `invalidate` is the
+ * one special case the contract supports — but only for patterns, which carry a
+ * literal `invalidated` status. Recommendations and doctrine lack it, so
+ * `invalidate` on those is refused with a structured hint. This is honest
+ * partial coverage, not a silent no-op.
+ */
+
+import { relative } from 'node:path';
+
+import { validateTransition, ACTION_TARGET_STATUS, REASON_REQUIRED, REQUIRES_ACCEPTED, REQUIRES_CLOSED } from './transitions.js';
+import { createEvent, appendEvent } from './event-log.js';
+import {
+  resetSeenArtifactWrite,
+  writePattern,
+  writeRecommendation,
+  writeDoctrine,
+  loadPatternsWithSkips,
+  loadRecommendationsWithSkips,
+  loadDoctrinesWithSkips
+} from '../synthesis/write-artifacts.js';
+
+/**
+ * Surface torn/unreadable artifact YAML on stderr — the lookup-path analogue of
+ * the derive CLI's "N pattern(s) skipped (torn/unreadable)" reporting
+ * (cli.js) and `findRecordFile`'s stderr note (derive/load-records.js).
+ *
+ * B-001 — `findArtifactById` / `getArtifactReviewQueue` consumed only the
+ * loader's `entries`, discarding `skipped[]`. A torn artifact YAML for the very
+ * id under accept/show/queue therefore vanished behind a bare "<type> not
+ * found", giving the operator no signal that a file was unreadable. The id
+ * lives INSIDE the file, so a torn file can't be matched to a requested id;
+ * the honest signal is to name the torn files whenever any are present so the
+ * operator can distinguish "absent" from "present but unparseable". Returns the
+ * skipped list so callers can decide whether the not-found was hint-worthy.
+ *
+ * @param {string} rootDir
+ * @param {string} type - artifact kind, for the message prefix
+ * @param {Array<{ path: string, error: string }>} skipped
+ */
+function reportArtifactSkips(rootDir, type, skipped) {
+  if (!skipped || skipped.length === 0) return;
+  // eslint-disable-next-line no-console
+  console.error(`${skipped.length} ${type}(s) skipped (torn/unreadable):`);
+  for (const s of skipped) {
+    // eslint-disable-next-line no-console
+    console.error(`  ${relative(rootDir, s.path)} — ${s.error}`);
+  }
+}
+
+/**
+ * Per-artifact-type configuration: the on-disk directory, the id field name,
+ * the loader (with-skips) and the writer. Mirrors how the finding engine pairs
+ * `findById` + writer; here the type is a first-class parameter.
+ */
+const ARTIFACT_TYPES = {
+  pattern: {
+    dir: 'patterns',
+    idKey: 'pattern_id',
+    loadWithSkips: loadPatternsWithSkips,
+    write: writePattern,
+    statuses: new Set(['candidate', 'accepted', 'rejected', 'invalidated']),
+    hasInvalidatedStatus: true
+  },
+  recommendation: {
+    dir: 'recommendations',
+    idKey: 'recommendation_id',
+    loadWithSkips: loadRecommendationsWithSkips,
+    write: writeRecommendation,
+    statuses: new Set(['candidate', 'accepted', 'rejected']),
+    hasInvalidatedStatus: false
+  },
+  doctrine: {
+    dir: 'doctrine',
+    idKey: 'doctrine_id',
+    loadWithSkips: loadDoctrinesWithSkips,
+    write: writeDoctrine,
+    statuses: new Set(['candidate', 'accepted', 'rejected']),
+    hasInvalidatedStatus: false
+  }
+};
+
+/**
+ * Find a single synthesis artifact by id.
+ *
+ * @param {string} rootDir
+ * @param {'pattern'|'recommendation'|'doctrine'} type
+ * @param {string} id
+ * @returns {{ data: object, path: string, type: string } | null}
+ */
+export function findArtifactById(rootDir, type, id) {
+  const cfg = ARTIFACT_TYPES[type];
+  if (!cfg) return null;
+  const { entries, skipped } = cfg.loadWithSkips(rootDir);
+  for (const entry of entries) {
+    if (entry.data && entry.data[cfg.idKey] === id) {
+      return { data: entry.data, path: entry.path, type };
+    }
+  }
+  // B-001 — id absent from the clean entries. A torn file may be hiding it;
+  // name the torn files rather than letting a bare not-found mislead.
+  reportArtifactSkips(rootDir, type, skipped);
+  return null;
+}
+
+/**
+ * Perform a review action on a synthesis artifact — the artifact analogue of
+ * `performAction`. Promotes a candidate to accepted (closing the loop),
+ * rejects, or invalidates per the reused finding status law.
+ *
+ * @param {string} rootDir
+ * @param {object} params
+ * @param {'pattern'|'recommendation'|'doctrine'} params.type
+ * @param {string} params.id
+ * @param {string} params.action - accept | reject | review | reopen | invalidate
+ * @param {string} params.actor
+ * @param {string} [params.reason]
+ * @param {string} [params.notes]
+ * @returns {{ success: boolean, error?: string, artifact?: object, event?: object }}
+ */
+export function reviewArtifact(rootDir, params) {
+  const { type, id, action, actor } = params;
+
+  if (!type || !ARTIFACT_TYPES[type]) {
+    return { success: false, error: `Unknown artifact type: "${type}". Expected pattern|recommendation|doctrine.` };
+  }
+  if (!id) return { success: false, error: 'id is required' };
+  if (!action) return { success: false, error: 'action is required' };
+  if (!actor) return { success: false, error: 'actor is required' };
+  if (!(action in ACTION_TARGET_STATUS)) {
+    return { success: false, error: `Unknown action: "${action}"` };
+  }
+
+  const cfg = ARTIFACT_TYPES[type];
+
+  // Load the artifact
+  const found = findArtifactById(rootDir, type, id);
+  if (!found) return { success: false, error: `${type} not found: ${id}` };
+
+  const artifact = found.data;
+  const fromStatus = artifact.status;
+
+  // Enforce reason requirement (reused REASON_REQUIRED)
+  if (REASON_REQUIRED.has(action) && !params.reason) {
+    return { success: false, error: `Action "${action}" requires a reason` };
+  }
+
+  // Enforce accepted-only actions (reused REQUIRES_ACCEPTED — invalidate)
+  if (REQUIRES_ACCEPTED.has(action) && fromStatus !== 'accepted') {
+    return { success: false, error: `Action "${action}" requires status "accepted", got "${fromStatus}"` };
+  }
+
+  // Enforce closed-only actions (reused REQUIRES_CLOSED — reopen)
+  if (REQUIRES_CLOSED.has(action) && fromStatus !== 'accepted' && fromStatus !== 'rejected') {
+    return { success: false, error: `Action "${action}" requires status "accepted" or "rejected", got "${fromStatus}"` };
+  }
+
+  // Determine the law's target status (reused ACTION_TARGET_STATUS)
+  const lawTarget = ACTION_TARGET_STATUS[action];
+
+  // Validate the transition under the reused finding law FIRST — an unlawful
+  // transition is refused with the same vocabulary the finding engine uses.
+  if (lawTarget !== null && lawTarget !== fromStatus) {
+    const transResult = validateTransition(fromStatus, lawTarget);
+    if (!transResult.valid) {
+      return { success: false, error: transResult.error };
+    }
+  }
+
+  // Map the law's target status onto the NARROWER artifact contract.
+  // The finding law uses `reviewed` as an intermediate state; artifact schemas
+  // do not permit it. Refuse honestly where the artifact cannot hold the state.
+  let toStatus;
+  if (action === 'invalidate') {
+    if (!cfg.hasInvalidatedStatus) {
+      return {
+        success: false,
+        error: `invalidate is not supported for ${type}: its schema has no "invalidated" status. ` +
+          `Use reject (with a reason) to retire an accepted ${type}.`
+      };
+    }
+    toStatus = 'invalidated';
+  } else if (lawTarget === 'reviewed') {
+    // `review` / `reopen` target the intermediate `reviewed` state, which no
+    // artifact schema permits. Refuse rather than write an invalid artifact.
+    return {
+      success: false,
+      error: `Action "${action}" targets status "reviewed", which the ${type} contract does not allow ` +
+        `(${type} status ∈ {${[...cfg.statuses].join(', ')}}). Use accept or reject instead.`
+    };
+  } else {
+    toStatus = lawTarget;
+  }
+
+  // Defensive: never persist a status the artifact schema forbids.
+  if (!cfg.statuses.has(toStatus)) {
+    return { success: false, error: `Computed status "${toStatus}" is not valid for ${type}.` };
+  }
+
+  const now = new Date().toISOString();
+
+  // Apply status + review metadata. `last_action` mirrors the finding engine's
+  // review block. For invalidate, `last_action: 'invalidate'` is what
+  // queryPatterns checks to exclude the artifact (advise/query.js).
+  artifact.status = toStatus;
+  artifact.review = {
+    reviewed_by: actor,
+    reviewed_at: now,
+    last_action: action,
+    ...(params.reason ? { decision_reason: params.reason } : {})
+  };
+  artifact.updated_at = now;
+
+  // Build the review event (carries artifact id + kind, back-compat).
+  const event = createEvent({
+    artifactId: id,
+    artifactKind: type,
+    actor,
+    action,
+    fromStatus,
+    toStatus,
+    reason: params.reason,
+    notes: params.notes
+  });
+
+  // Persist via the synthesis writer — which RE-VALIDATES the promoted artifact
+  // against its JSON Schema (fail-closed). The reset is the documented opt-in
+  // for a legitimate re-write of an id already touched in this process (the
+  // synthesis collision guard otherwise refuses the second write). B-003 —
+  // scope it to THIS id so a future batch reviewer doesn't disarm the guard for
+  // the other ids it has written this process.
+  try {
+    resetSeenArtifactWrite(rootDir, type, id);
+    cfg.write(rootDir, artifact);
+  } catch (err) {
+    return { success: false, error: err.message, code: err.code };
+  }
+
+  // Append the event only after the artifact persisted successfully.
+  appendEvent(rootDir, event);
+
+  return { success: true, artifact, event };
+}
+
+/**
+ * Get the artifact review queue: candidate artifacts needing operator attention.
+ * Mirrors `getReviewQueue` (review/review-engine.js). With `type` omitted,
+ * scans all three artifact families.
+ *
+ * @param {string} rootDir
+ * @param {'pattern'|'recommendation'|'doctrine'} [type]
+ * @returns {Array<{ data: object, path: string, type: string, queueReason: string }>}
+ */
+export function getArtifactReviewQueue(rootDir, type) {
+  const types = type ? [type] : Object.keys(ARTIFACT_TYPES);
+  const queue = [];
+
+  for (const t of types) {
+    const cfg = ARTIFACT_TYPES[t];
+    if (!cfg) continue;
+    const { entries, skipped } = cfg.loadWithSkips(rootDir);
+    // B-001 — a torn artifact silently shrinks the review queue; name it so the
+    // operator knows the queue is partial rather than complete.
+    reportArtifactSkips(rootDir, t, skipped);
+    for (const entry of entries) {
+      const data = entry.data;
+      if (!data) continue;
+      if (data.status === 'candidate') {
+        queue.push({ data, path: entry.path, type: t, queueReason: 'Unreviewed candidate' });
+      }
+    }
+  }
+
+  return queue;
+}