mandrel 1.67.0 → 1.69.0

package/.agents/scripts/lib/orchestration/wave-record-io.js

@@ -1,25 +1,23 @@
 /**
- * wave-record-io.js — impure helpers for the record-wave CLI: ticket
- * verification, manifest title lookup, and returns reconciliation.
+ * wave-record-io.js — impure helpers for the per-Story status recorder CLI
+ * (`epic-execute-record-wave.js`): ticket verification, manifest title
+ * lookup, and returns reconciliation.
  *
  * These functions all hit the provider and are intentionally kept out of
- * `wave-record-projection.js`, which is the pure projection layer. The
- * parent CLI imports both modules and threads the I/O results through
- * the projection.
+ * `wave-record-projection.js`, which is the pure helper layer. The parent
+ * CLI imports both modules and threads the I/O results through the
+ * projection.
  *
- * Every entry point here is fire-and-forget on the "best-effort" surfaces
- * (manifest title lookup) and explicit-throw on the authoritative ones
- * (`verifyWaveResults` and `resolveResolvedResults` decide what `complete`
- * actually means after the network call lands).
+ * Story #4155 (Epic #4151) — the wave-batch livelock-recovery path
+ * (`planStoryIdsForWave` + the empty-mode-B reconcile) was deleted along
+ * with the wave checkpoint it keyed off. Under the ready-set runtime a
+ * Story's terminal state is always re-derivable from its live label on the
+ * next `tick`, so there is no falsely-`complete` empty wave to recover from
+ * — the recorder records exactly the Stories it was handed.
  *
- * Story #3909 — the per-wave dispatch-manifest refresh hop
- * (`refreshDispatchManifest`) was deleted. It re-ran the full dispatch
- * pipeline (re-fetch every ticket, recompute waves) on every wave tick
- * only to re-render the `dispatch-manifest` comment, which nothing reads
- * for control flow — `loadManifestTitleMap` reads it for rollup-row titles,
- * and those are fixed at plan time. The manifest is now written once at
- * `epic-deliver-prepare` time and left frozen; the surviving operator-facing
- * surface is the `epic-run-progress` rollup the record-wave CLI re-renders.
+ * Story #3909 — the per-wave dispatch-manifest refresh hop was deleted; the
+ * manifest is written once at `epic-deliver-prepare` time and left frozen.
+ * `loadManifestTitleMap` reads it for rollup-row titles.
  */
 
 import { Logger } from '../Logger.js';
@@ -112,14 +110,14 @@ async function verifySingleResult(r, provider) {
  * stale cache cannot mask the discrepancy. A network failure during
  * verification cannot prove the claim either way, so the row is
  * downgraded to `failed` and a `verify-error` discrepancy is recorded —
- * an unverifiable `done` must not let the wave aggregate to `complete`,
- * which is what callers read as "GitHub agrees everything is done."
+ * an unverifiable `done` must not be recorded as `done`, which is what the
+ * auto-merge predicate reads as "GitHub agrees everything is done."
  *
  * Story #3024 — verification runs through {@link concurrentMap} under a
  * bounded cap (default 4, override via
  * `delivery.deliverRunner.verifyConcurrencyCap`). Per-row failures are
  * captured inside the mapper so one Story's `getTicket` throw cannot
- * abort the whole wave — the per-row try/catch lives in
+ * abort the whole batch — the per-row try/catch lives in
  * {@link verifySingleResult} and turns into a `verify-error`
  * discrepancy rather than a rejected mapper. Input order is preserved
  * (mapper-index → output-index), matching the previous serial behaviour.
@@ -183,84 +181,27 @@ export async function loadManifestTitleMap({ provider, epicId }) {
   }
 }
 
-/**
- * Extract the Story IDs planned for `wave` from the checkpoint `plan`
- * (`Story[][]` indexed by wave). Returns `[]` when the plan is missing or
- * the wave index is out of range. Pure helper — exported for unit tests.
- *
- * Story #3907 — the wave-complete livelock recovery (below) keys off this:
- * when mode B records a wave with **no** child returns (the host crashed
- * after the children finished but before `record-wave` ran), every Story in
- * `plan[wave]` is reconciled from GitHub so the wave can record and
- * `currentWave` can advance instead of returning `wave-complete` for the same
- * index forever.
- *
- * @param {object} existing Checkpoint state.
- * @param {number} wave
- * @returns {number[]}
- */
-export function planStoryIdsForWave(existing, wave) {
-  const plan = Array.isArray(existing?.plan) ? existing.plan : [];
-  const entries = Array.isArray(plan[wave]) ? plan[wave] : [];
-  const ids = [];
-  for (const entry of entries) {
-    const id =
-      typeof entry === 'number'
-        ? entry
-        : Number(entry?.id ?? entry?.storyId ?? entry?.number);
-    if (Number.isInteger(id) && id > 0) ids.push(id);
-  }
-  return ids;
-}
-
 /**
  * Parse / reconcile the per-Story returns (or pass `results` through). Posts
  * a single rolled-up friction comment listing every malformed return on
  * failure — non-fatal if the post itself fails.
  *
- * Story #3907 — mode B with an **empty** `returns` array is the
- * wave-complete-livelock recovery path: the host crashed after the wave's
- * children finished but before `record-wave` ran, so no return text survives.
- * Rather than recording an empty (falsely-`complete`) wave, every Story in
- * `plan[wave]` is reconciled from GitHub via {@link reconcileStoryFromGitHub}
- * so the recorded wave reflects the live ticket state. This requires the
- * caller to thread the checkpoint `existing` so the wave's planned Story set
- * is known; without it the empty array degrades to the previous behaviour.
- *
  * @returns {Promise<{ resolvedResults: Array, parseFailures: Array }>}
  */
 export async function resolveResolvedResults({
   provider,
   epicId,
-  wave,
   results,
   returns,
-  existing,
 }) {
   if (returns == null) {
     return { resolvedResults: results, parseFailures: [] };
   }
-  if (Array.isArray(returns) && returns.length === 0 && existing) {
-    const ids = planStoryIdsForWave(existing, wave);
-    if (ids.length > 0) {
-      const resolvedResults = await concurrentMap(
-        ids,
-        (storyId) => reconcileStoryFromGitHub({ provider, storyId }),
-        { concurrency: DEFAULT_VERIFY_CONCURRENCY_CAP },
-      );
-      Logger.warn(
-        `[wave-record-io] Wave ${wave} recorded with no child returns; ` +
-          `reconciled ${ids.length} Story(ies) from GitHub (livelock recovery).`,
-      );
-      return { resolvedResults, parseFailures: [] };
-    }
-  }
   const normalized = await normalizeReturns({ provider, returns });
   if (normalized.parseFailures.length > 0) {
     try {
       const body = renderMalformedReturnsFriction({
         epicId,
-        wave,
         failures: normalized.parseFailures,
       });
       await postStructuredComment(provider, epicId, 'friction', body);

package/.agents/scripts/lib/orchestration/wave-record-notifications.js

@@ -1,14 +1,15 @@
 /**
- * wave-record-notifications.js — webhook-emit helpers extracted from
- * `epic-execute-record-wave.js`.
+ * wave-record-notifications.js — webhook-emit helpers for the per-Story
+ * status recorder CLI (`epic-execute-record-wave.js`).
  *
- * The CLI fires curated webhook events at every wave boundary (started,
- * progress, blocked, unblocked) so the host-LLM-driven `/deliver` path
- * mirrors the wave-loop emits in
- * `lib/orchestration/epic-runner/phases/iterate-waves.js`. Each helper here
- * is fire-and-forget — webhook misconfig or a transient Slack outage must
- * not block the wave loop — so the impure surface is small (the inbound
- * `notifyFn` closure) and the rest is plain control flow.
+ * Story #4155 (Epic #4151) — the Epic `/deliver` runtime cut over from the
+ * wave-batch scheduler to the continuous ready-set core, so these emits are
+ * no longer keyed to a wave boundary. The recorder fires curated webhook
+ * events per recorder beat: `epic-started` once (on the first recorded
+ * Story), `epic-progress` with the run's done/total counts (re-derived from
+ * the checkpoint's flat per-Story `stories` map), and `epic-blocked` when a
+ * Story in this beat blocked or failed. Each helper is fire-and-forget —
+ * webhook misconfig or a transient Slack outage must not block the loop.
  *
  * These helpers stay in their own module to keep the parent CLI a thin
  * runner shell. They are not part of the pure projection layer; they
@@ -20,9 +21,7 @@ import {
   emitEpicBlocked,
   emitEpicProgress,
   emitEpicStarted,
-  emitEpicUnblocked,
 } from './epic-runner/progress-reporter/transport.js';
-import { countDoneStories } from './wave-record-projection.js';
 
 /**
  * Build the notify-bound closure used by the curated webhook emitters. When
@@ -41,25 +40,53 @@ export function buildNotifyFn(injectedNotify, config, provider, defaultNotify) {
 }
 
 /**
- * Fire the curated webhook events for a wave boundary. Each emit is
+ * Count Stories in a terminal `done` state across the checkpoint's flat
+ * per-Story `stories` status map. Pure helper.
+ *
+ * @param {Record<string, { status?: string }>|undefined} stories
+ * @returns {number}
+ */
+export function countDoneStories(stories) {
+  const map = stories && typeof stories === 'object' ? stories : {};
+  let done = 0;
+  for (const rec of Object.values(map)) {
+    if (rec?.status === 'done') done += 1;
+  }
+  return done;
+}
+
+/**
+ * Fire the curated webhook events for a recorder beat. Each emit is
  * fire-and-forget (the emit helpers swallow webhook misconfiguration), but
- * we still serialise them so the order matches the wave-loop emits in
- * `lib/orchestration/epic-runner/phases/iterate-waves.js` for the host-LLM
- * driven /deliver path.
+ * we still serialise them so the order is deterministic.
+ *
+ * - `epic-started` fires exactly once: on the very first recorded Story
+ *   (signalled by `firstRecord === true`), before any Story has been
+ *   recorded on a prior beat.
+ * - `epic-progress` always fires with the run's done/total counts.
+ * - `epic-blocked` fires when this beat recorded at least one blocked or
+ *   failed Story.
+ *
+ * @param {{
+ *   injectedNotify?: Function,
+ *   defaultNotify: Function,
+ *   config: object,
+ *   provider: object,
+ *   epicId: number,
+ *   firstRecord: boolean,
+ *   stories: Record<string, { status?: string }>,
+ *   verified: Array<{ storyId: number, status: string }>,
+ *   blockedStoryIds: number[],
+ * }} args
  */
-export async function emitWaveBoundaryNotifications({
+export async function emitRecordNotifications({
   injectedNotify,
   defaultNotify,
   config,
   provider,
   epicId,
-  wave,
-  status,
-  priorWaves,
-  nextWaves,
-  titleById,
-  totalWaves,
-  nextCurrentWave,
+  firstRecord,
+  stories,
   verified,
   blockedStoryIds,
 }) {
@@ -69,121 +96,50 @@ export async function emitWaveBoundaryNotifications({
     provider,
     defaultNotify,
   );
-  const totalStoriesEstimate = titleById.size;
-  const doneStoriesSoFar = countDoneStories(nextWaves);
-  const priorWaveRecord = priorWaves.find(
-    (w) => Number(w?.index) === Number(wave),
-  );
-  if (priorWaves.length === 0 && wave === 0) {
+  const map = stories && typeof stories === 'object' ? stories : {};
+  const totalStories = Object.keys(map).length;
+  const doneStories = countDoneStories(map);
+
+  if (firstRecord) {
     await emitEpicStarted({
       notify: notifyFn,
       epicId,
-      totalWaves,
-      totalStories: totalStoriesEstimate,
+      totalStories,
       logger: Logger,
     });
   }
-  if (status === 'complete') {
-    await emitCompleteWaveNotifications({
-      notifyFn,
-      epicId,
-      priorWaveRecord,
-      doneStoriesSoFar,
-      totalStoriesEstimate,
-      nextCurrentWave,
-      totalWaves,
-    });
-    return;
-  }
-  await emitFailingWaveNotifications({
-    notifyFn,
-    epicId,
-    status,
-    blockedStoryIds,
-    verified,
-    doneStoriesSoFar,
-    totalStoriesEstimate,
-    nextCurrentWave,
-    totalWaves,
-  });
-}
 
-/** Emit the unblocked-then-progress pair for a `complete` wave. */
-async function emitCompleteWaveNotifications({
-  notifyFn,
-  epicId,
-  priorWaveRecord,
-  doneStoriesSoFar,
-  totalStoriesEstimate,
-  nextCurrentWave,
-  totalWaves,
-}) {
-  const resumedFromHalt =
-    priorWaveRecord &&
-    (priorWaveRecord.status === 'blocked' ||
-      priorWaveRecord.status === 'failed');
-  if (resumedFromHalt) {
-    await emitEpicUnblocked({
+  const blockedIds = Array.isArray(blockedStoryIds) ? blockedStoryIds : [];
+  const failedStoryId = (verified ?? []).find(
+    (r) => r.status === 'failed',
+  )?.storyId;
+  const failingStoryId = blockedIds[0] ?? failedStoryId;
+  const hasFailure = blockedIds.length > 0 || failedStoryId != null;
+
+  if (hasFailure) {
+    await emitEpicBlocked({
       notify: notifyFn,
       epicId,
-      resolvedBlocker: {
-        reason:
-          priorWaveRecord.status === 'blocked'
-            ? 'story_blocked'
-            : 'story_failed',
-      },
+      reason: blockedIds.length > 0 ? 'story_blocked' : 'story_failed',
+      storyId: failingStoryId,
       logger: Logger,
     });
   }
-  await emitEpicProgress({
-    notify: notifyFn,
-    epicId,
-    done: doneStoriesSoFar,
-    total: totalStoriesEstimate,
-    currentWave: nextCurrentWave,
-    totalWaves,
-    phase: 'iterate-waves',
-    openBlockers: [],
-    logger: Logger,
-  });
-  // The `epic-complete` webhook used to fire here, at the post-final-wave
-  // / pre-finalize boundary. That preceded `gh pr create` by minutes — the
-  // operator got an "Epic complete" ping with no PR to click. The fire
-  // moved to `epic-deliver-finalize.js`, which emits it after the PR URL
-  // is captured. See that script for the new emit point.
-}
 
-/** Emit blocked + progress (with open-blocker context) for a non-complete wave. */
-async function emitFailingWaveNotifications({
-  notifyFn,
-  epicId,
-  status,
-  blockedStoryIds,
-  verified,
-  doneStoriesSoFar,
-  totalStoriesEstimate,
-  nextCurrentWave,
-  totalWaves,
-}) {
-  const reason = status === 'blocked' ? 'story_blocked' : 'story_failed';
-  const failingStoryId =
-    blockedStoryIds[0] ?? verified.find((r) => r.status === 'failed')?.storyId;
-  await emitEpicBlocked({
-    notify: notifyFn,
-    epicId,
-    reason,
-    storyId: failingStoryId,
-    logger: Logger,
-  });
   await emitEpicProgress({
     notify: notifyFn,
     epicId,
-    done: doneStoriesSoFar,
-    total: totalStoriesEstimate,
-    currentWave: nextCurrentWave,
-    totalWaves,
-    phase: 'iterate-waves',
-    openBlockers: [{ reason, storyId: failingStoryId }],
+    done: doneStories,
+    total: totalStories,
+    phase: 'wave-loop',
+    openBlockers: hasFailure
+      ? [
+          {
+            reason: blockedIds.length > 0 ? 'story_blocked' : 'story_failed',
+            storyId: failingStoryId,
+          },
+        ]
+      : [],
     logger: Logger,
   });
 }

package/.agents/scripts/lib/orchestration/wave-record-projection.js

@@ -1,37 +1,31 @@
 /**
- * wave-record-projection.js — pure projection helpers for the record-wave CLI.
+ * wave-record-projection.js — pure helpers for the per-Story status
+ * recorder CLI (`epic-execute-record-wave.js`).
  *
- * This module is the post-wave-record projection layer extracted from
- * `.agents/scripts/epic-execute-record-wave.js`. Every export here is pure:
- * no network I/O, no filesystem reads, no spawning. The parent CLI handles
- * the impure work (provider calls, checkpoint reads/writes, webhook emits,
- * manifest refresh) and threads the resolved inputs through these helpers
- * to produce the wave's new checkpoint record, rollup rows, and envelope
- * fields.
+ * Story #4155 (Epic #4151) — the Epic `/deliver` runtime cut over from the
+ * wave-batch scheduler to the continuous ready-set core. The post-dispatch
+ * persistence shrank with it: there is no longer a wave-level aggregation
+ * (`aggregateWaveStatus`), a `currentWave` advance (`nextCurrentWave`), a
+ * next-action classifier (`classifyWaveOutcome`), or a `projectWaveRecord`
+ * splice into a `waves[]` history. The recorder now writes each returned
+ * Story's **terminal status** into the checkpoint's flat per-Story `stories`
+ * map and re-renders the operator rollup from that map.
+ *
+ * Every export here is pure: no network I/O, no filesystem reads, no
+ * spawning. The parent CLI handles the impure work (provider calls,
+ * checkpoint reads/writes, webhook emits) and threads the resolved inputs
+ * through these helpers.
  *
  * Group the exports by responsibility:
  *
  *   - Input validation: `validateResults`, `validateReturnsEntry`,
- *     `classifyParsedReturn`, `validateEpicWave`, `validateResultsReturnsXor`,
- *     `selectInputFlag`, `resolveConcurrencyCap`.
- *   - Aggregation: `aggregateWaveStatus`, `countDoneStories`,
- *     `classifyWaveOutcome`.
- *   - Projection: `toRollupRow`, `projectWaveRecord`.
- *
- * The aggregator `projectWaveRecord` is the entry point: given the verified
- * per-Story rows, the prior checkpoint, the wave index, the resolved
- * concurrency cap, and a `titleById` map, it returns every derived shape the
- * CLI needs to (a) write the next checkpoint, (b) render `epic-run-progress`,
- * (c) classify the next slash-command action, and (d) assemble the stdout
- * envelope. It is the single source of truth for "what does the wave look
- * like after these results land?"
+ *     `classifyParsedReturn`, `validateEpic`, `selectInputFlag`.
+ *   - Normalization: `normalizeReturnsPure`.
+ *   - Projection: `toRollupRow`.
  */
 
 import { parseStoryAgentReturn } from './epic-runner/sub-agent-return.js';
 
-/** Valid wave-level rollup statuses. */
-export const VALID_RESULT_STATUSES = new Set(['complete', 'blocked', 'failed']);
-
 /** Per-Story return statuses we accept off `/deliver` sub-agents. */
 export const VALID_STORY_STATUSES = new Set(['done', 'blocked', 'failed']);
 
@@ -130,57 +124,6 @@ export function classifyParsedReturn(parsed, storyId) {
   return { ok: false, error };
 }
 
-/**
- * Aggregate validated per-Story rows into the wave-level outcome. Pure.
- *
- * @param {Array<{ storyId: number, status: string }>} results
- */
-export function aggregateWaveStatus(results) {
-  const rows = Array.isArray(results) ? results : [];
-  const failed = rows.filter((r) => r.status === 'failed');
-  const blocked = rows.filter((r) => r.status === 'blocked');
-  let status;
-  if (failed.length > 0) {
-    status = 'failed';
-  } else if (blocked.length > 0) {
-    status = 'blocked';
-  } else {
-    status = 'complete';
-  }
-  return {
-    status,
-    blockedStoryIds: blocked.map((r) => r.storyId),
-  };
-}
-
-/**
- * Classify the wave outcome into the next operator action. Pure helper —
- * exported so tests can pin each branch without touching the provider.
- *
- * @param {{ resultStatus: string, currentWave: number, totalWaves: number }} args
- */
-export function classifyWaveOutcome({ resultStatus, currentWave, totalWaves }) {
-  const remainingWaves = Math.max(
-    0,
-    Number(totalWaves) - (Number(currentWave) + 1),
-  );
-  if (resultStatus === 'blocked') {
-    return { nextAction: 'halt-blocked', remainingWaves };
-  }
-  if (resultStatus === 'failed') {
-    return { nextAction: 'halt-failed', remainingWaves };
-  }
-  if (resultStatus === 'complete') {
-    return {
-      nextAction: remainingWaves > 0 ? 'dispatch-next' : 'finalize',
-      remainingWaves,
-    };
-  }
-  throw new RangeError(
-    `classifyWaveOutcome: resultStatus "${resultStatus}" must be one of: ${[...VALID_RESULT_STATUSES].join(', ')}`,
-  );
-}
-
 /**
  * Build the rollup-row shape the unified `epic-run-progress` writer
  * consumes. Returns `{ id, title, state, blockerCommentId? }`.
@@ -197,64 +140,13 @@ export function toRollupRow(verified, titleById) {
   return row;
 }
 
-/** Pure: count Stories already marked `done` across every recorded wave. */
-export function countDoneStories(waves) {
-  return waves.reduce(
-    (acc, w) =>
-      acc +
-      (Array.isArray(w.stories)
-        ? w.stories.filter((s) => s?.state === 'done').length
-        : 0),
-    0,
-  );
-}
-
-/** Validate the core `{ epicId, wave }` invariants. Throws on bad input. */
-export function validateEpicWave(epicId, wave) {
+/** Validate the core `{ epicId }` invariant. Throws on bad input. */
+export function validateEpic(epicId) {
   if (!Number.isInteger(epicId) || epicId <= 0) {
     throw new TypeError(
       'runEpicExecuteRecordWave: --epic must be a positive integer',
     );
   }
-  if (!Number.isInteger(wave) || wave < 0) {
-    throw new TypeError(
-      'runEpicExecuteRecordWave: --wave must be a non-negative integer',
-    );
-  }
-}
-
-/** Validate the `results`/`returns` XOR. Throws on bad input. */
-export function validateResultsReturnsXor(results, returns) {
-  if (results == null && returns == null) {
-    throw new TypeError(
-      'runEpicExecuteRecordWave: either `results` or `returns` is required',
-    );
-  }
-  if (results != null && returns != null) {
-    throw new TypeError(
-      'runEpicExecuteRecordWave: pass `results` OR `returns`, not both',
-    );
-  }
-}
-
-/** Resolve the effective concurrency cap, honouring CLI > checkpoint > config. */
-export function resolveConcurrencyCap(
-  concurrencyCapOverride,
-  existing,
-  deliverRunner,
-) {
-  const cap =
-    concurrencyCapOverride ??
-    Number(existing.concurrencyCap) ??
-    Number(deliverRunner.concurrencyCap) ??
-    1;
-  if (!Number.isInteger(cap) || cap < 1) {
-    throw new RangeError(
-      `runEpicExecuteRecordWave: resolved concurrencyCap "${cap}" must be a positive integer; ` +
-        'pass --concurrency-cap or set `orchestration.runners.deliverRunner.concurrencyCap`.',
-    );
-  }
-  return cap;
 }
 
 /**
@@ -292,7 +184,7 @@ export function selectInputFlag(hasResults, hasReturns) {
  * @param {(args: { storyId: number }) => Promise<object> | object} [args.reconcile]
  *   Optional async hook used to fetch a fallback row when parsing fails. If
  *   omitted, parse failures push a placeholder `{ storyId, status: 'failed' }`
- *   row so the caller can still aggregate without I/O.
+ *   row so the caller can still record without I/O.
  */
 export async function normalizeReturnsPure({ returns, reconcile } = {}) {
   if (!Array.isArray(returns)) {
@@ -318,100 +210,3 @@ export async function normalizeReturnsPure({ returns, reconcile } = {}) {
   }
   return { results, parseFailures };
 }
-
-/**
- * Project the post-wave-record state from verified per-Story rows. Pure
- * end-to-end: every derived field the CLI needs after `verifyWaveResults`
- * lands here. The CLI hands us the verified rows, the existing checkpoint
- * (so we can splice this wave's record), the wave index, the resolved cap,
- * the manifest title map, and a `now` clock.
- *
- * Returns the union of:
- *   - the new `epic-run-state` shape (`nextWaves`, `nextCurrentWave`,
- *     `totalWaves`),
- *   - the rollup payload (`rollupRows`, `rollupWaves`),
- *   - the wave-level outcome (`status`, `blockedStoryIds`),
- *   - the slash-command next action (`nextAction`, `remainingWaves`).
- *
- * The CLI handles I/O around this projection: writing the checkpoint,
- * upserting `epic-run-progress`, emitting webhooks, refreshing the local
- * manifest. None of those impure side-effects live here.
- *
- * @param {object} args
- * @param {number} args.wave
- * @param {Array<object>} args.verified
- * @param {object} args.existing
- * @param {number} args.concurrencyCap
- * @param {Map<number, string>} args.titleById
- * @param {() => Date} [args.now]
- */
-export function projectWaveRecord({
-  wave,
-  verified,
-  existing,
-  concurrencyCap,
-  titleById,
-  now = () => new Date(),
-} = {}) {
-  if (!Number.isInteger(wave) || wave < 0) {
-    throw new TypeError(
-      'projectWaveRecord: wave must be a non-negative integer',
-    );
-  }
-  if (!existing || typeof existing !== 'object') {
-    throw new TypeError('projectWaveRecord: existing checkpoint is required');
-  }
-  if (!(titleById instanceof Map)) {
-    throw new TypeError('projectWaveRecord: titleById must be a Map');
-  }
-
-  const totalWaves = Number(existing.totalWaves ?? 0);
-  const verifiedRows = Array.isArray(verified) ? verified : [];
-
-  const { status, blockedStoryIds } = aggregateWaveStatus(verifiedRows);
-  const rollupRows = verifiedRows.map((r) => toRollupRow(r, titleById));
-
-  const priorWaves = Array.isArray(existing.waves) ? existing.waves : [];
-  const newRecord = {
-    index: wave,
-    status,
-    concurrencyCap,
-    stories: rollupRows,
-    completedAt: now().toISOString(),
-  };
-  const filtered = priorWaves.filter((w) => Number(w?.index) !== Number(wave));
-  const nextWaves = [...filtered, newRecord].sort(
-    (a, b) => Number(a.index) - Number(b.index),
-  );
-
-  const nextCurrentWave =
-    status === 'complete'
-      ? Math.min(totalWaves, wave + 1)
-      : Number(existing.currentWave ?? wave);
-
-  const rollupWaves = nextWaves.map((w) => ({
-    wave: Number(w.index),
-    concurrencyCap: Number(w.concurrencyCap) || concurrencyCap,
-    stories: Array.isArray(w.stories) ? w.stories : [],
-  }));
-
-  const { nextAction, remainingWaves } = classifyWaveOutcome({
-    resultStatus: status,
-    currentWave: wave,
-    totalWaves,
-  });
-
-  return {
-    status,
-    blockedStoryIds,
-    rollupRows,
-    newRecord,
-    priorWaves,
-    nextWaves,
-    nextCurrentWave,
-    totalWaves,
-    rollupWaves,
-    nextAction,
-    remainingWaves,
-  };
-}