mulmoclaude 0.6.2 → 0.6.4

package/server/encore/INVARIANTS.md

@@ -0,0 +1,272 @@
+# Encore — lifecycle invariants
+
+This document records the **non-negotiable rules** that the Encore
+reconciler, tick, and dispatch handlers all rely on. Each rule has a
+short rationale (the failure mode it prevents) and a pointer to the
+code that enforces it today.
+
+Treat this as the rulebook future refactors must keep intact. Most
+classes of bug we have seen in Encore — duplicate-publish, orphaned
+bells, dead chats, dropped clicks — come from one of these rules
+quietly breaking.
+
+If you are about to violate one of these, **stop and read the
+rationale first**. Some of them have non-obvious failure modes that
+only surface days later (orphan prune at 30d) or under crash
+interleavings.
+
+---
+
+## 1. The reconciler owns the bell.
+
+`reconcileCycleNotifications` is the **sole** owner of:
+- `encoreNotifier.publish` (creating a bell entry)
+- `encoreNotifier.clear` (removing a bell entry)
+- ticket file writes and unlinks under `tickets/<pendingId>.json`
+
+No other code path is allowed to call `encoreNotifier.publish` or
+write a ticket. The reconciler re-derives the desired bell state from
+disk on every call and reconciles to match — handlers don't patch bell
+state; they write cycle facts and call the reconciler.
+
+**Documented exceptions** (only two; do not add more without updating
+this list):
+
+- `handlers/resolveNotification.ts` → `handleOrphanResolve` calls
+  `encoreNotifier.clear` directly when the user clicks a bell whose
+  ticket was already swept. There is no ticket to reconcile against,
+  so the reconciler cannot know the bell entry exists.
+- `tick.ts` → `pruneOneTicket` clears bells for orphan tickets older
+  than 30 days. This is age-based, not state-based, so it lives in
+  the time-driven tick rather than the state-driven reconciler.
+
+**Why**: handlers used to carry their own copies of trim/escalate
+logic (snooze had a tick-skip workaround, amend had a bespoke wipe
+path, `markStepDone` had a pendingId-walker). Those copies drifted —
+duplicate-publish and stale-bell regressions traced back to one path
+patching state while the other re-derived it.
+
+**Enforced by**: `test/plugins/test_encore_reconcile.ts` greps for
+forbidden notifier imports in handler files.
+
+---
+
+## 2. Every state mutation funnels through `persistAndReconcile`.
+
+State-mutating handlers (`markStepDone`, `markTargetSkipped`,
+`recordValues`, `snooze`, `unsnooze`) MUST funnel through
+`persistAndReconcile` (`handlers/shared.ts`). That helper writes the
+cycle file and immediately runs `reconcileCycleNotifications` under
+the same lock.
+
+Direct calls to `writeText(cycleFilePath(...), serializeCycleFile(...))`
+in handler code, without a reconcile under the same lock, are
+forbidden — they create state on disk that the bell doesn't reflect
+until the next tick (up to one hour later).
+
+`setup` and `amendDefinition` use the index-write path (not
+`persistAndReconcile`), but each explicitly calls
+`reconcileCycleNotifications` immediately after its `writeText`. Same
+contract: writes are not visible to the user until the reconciler runs
+on the same disk state.
+
+**Why**: keeps cycle-file disk state and bell state in sync within a
+single SSE turn. Without it, the user records a step but the bell
+doesn't clear until the hourly tick.
+
+---
+
+## 3. The per-plugin lock covers mutation AND reconcile together.
+
+`withLock` in `dispatch.ts` wraps each dispatch call. The reconcile
+inside `persistAndReconcile` (and `handleSetup` / `handleAmend`) runs
+under the same lock — not a separate critical section.
+
+Two consequences that must be preserved:
+
+- Two concurrent mutations can't race on `writeFileAtomic` against the
+  same cycle file.
+- A handler-side reconcile can't double-publish with the hourly
+  heartbeat (`tick.ts` calls reconcile from the same per-plugin lock).
+
+**Why**: the reconciler reads disk state, computes a diff against
+tickets, and writes both bell and ticket state. Splitting that across
+locks would let another writer interleave between the read and the
+write, producing a stale-diff publish.
+
+**Enforced by**: `lock.ts` exports one shared mutex; both
+`dispatch.ts` and `tick.ts` use it.
+
+---
+
+## 4. Clear-before-unlink. Never the reverse.
+
+When removing a ticket-bell pair, the bell clear MUST succeed before
+the ticket is unlinked. If the clear fails, leave the ticket on disk
+so the next reconcile or sweep can retry.
+
+This is enforced consistently by `safeClearBell` (`reconcile.ts`):
+
+```ts
+if (await safeClearBell(ticket.notificationId, reason, log)) {
+  await unlink(ticketPath(ticket.pendingId));
+}
+```
+
+**Why**: an unlinked ticket with a still-live bell is an **orphan
+bell** — visible in the bell UI but with no record pointing to it. The
+next reconcile sees an un-fired (target, step) pair on the cycle file
+and publishes a duplicate. The user sees two bells for one obligation.
+
+The exception (clearing the bell BEFORE unlinking) is in `tick.ts` →
+`pruneOneTicket`: an orphan ticket is by definition past its 30-day
+horizon, and we want the bell gone even if the ticket survives.
+
+---
+
+## 5. Publish-then-write-or-rollback.
+
+When publishing a fresh bell, the ticket write MUST succeed; if it
+fails, the just-published bell entry MUST be cleared (rollback).
+
+Both publish call-sites use the same pattern:
+
+```ts
+const { id: notificationId } = await encoreNotifier.publish(...);
+try {
+  await writeTicket(...);
+} catch (err) {
+  await safeClearBell(notificationId, "rollback: ...", log);
+  throw err;
+}
+```
+
+**Why**: a live bell with no matching ticket would be seen by the next
+reconcile as "un-fired" (the cycle-file pair isn't covered by any
+ticket), and a duplicate bell would be published.
+
+---
+
+## 6. A ticket asserts a live bell.
+
+A ticket's existence on disk is a claim that a bell with that
+`notificationId` is alive in the notifier. The reconciler validates
+that claim every pass with `encoreNotifier.bellExists` — when the bell
+has been dismissed out-of-band (host UI dismiss, crashed
+`active.json`), the reconciler republishes at a new id using the
+ticket's existing `pendingId`, `seedPrompt`, `createdAt`, and
+`chatSessionId`.
+
+**Why**: keeps manual bell-dismiss usable as a "see-it-next-tick"
+gesture instead of permanently silencing the obligation. `snooze` is
+the explicit verb for time-bound silence.
+
+The republished entry's `notificationId` changes (the host always
+assigns a new id); everything else on the ticket survives.
+
+---
+
+## 7. `chatSessionId` survives republish.
+
+`chatSessionId` is the only ticket field that is NOT regeneratable
+from disk. It binds the ticket to a user chat that the LLM is
+participating in.
+
+When the reconciler republishes a ticket (severity escalation, ghost
+republish, bundle trim), it MUST preserve `chatSessionId`. The
+republish patch in `clearAndRepublish` does this implicitly via
+`{ ...ticket, notificationId: newId, severity: newSeverity, ... }`.
+
+`resolveNotification`'s idempotency path (reuse existing
+`chatSessionId` on double-click) depends on this — losing the field
+would spawn a duplicate chat on every reconcile.
+
+---
+
+## 8. Cycle closure is derived, never stored.
+
+`isCycleClosed` (in `closure.ts`) computes closure from
+`state.records` — completed steps and skipped targets. There is no
+`closed: true` flag on the cycle file.
+
+When you add a new "step state" notion, add a predicate that reads
+from `records`; do **not** denormalize a status field. Status flags
+drift; predicates don't.
+
+**Why**: status flags are the canonical source of stale-bell bugs.
+Pre-refactor cycle files had `closed` + `lastPublishedSeverity`; both
+could disagree with the records, and the disagreement was invisible
+until a user saw an unexpected bell.
+
+---
+
+## 9. Immutable DSL fields.
+
+`amendDefinition` rejects changes to:
+
+- `id` (would desync directory name from `dsl.id`)
+- `createdAt` (server-generated, not LLM-controlled)
+- `type` (changes the validation discriminator and breaks prior
+  cycle-file naming)
+- `currency` on `type: "payment"` (would invalidate prior cycle
+  records mid-life)
+- `cadence.type` (changes cycle-file naming convention — `2026-05` vs
+  `2026-W20` vs `2026-05-18`)
+
+The retire-and-create path (set `status: "inactive"` on the old
+obligation, `defineEncore` a new one) is the supported way to change
+any of these.
+
+Even when an LLM patch includes `id` or `createdAt` by mistake,
+`handleAmend` force-restores the existing values rather than rejecting
+the call — those mistakes are common and surface in the result.
+
+---
+
+## 10. The tick sweep covers non-latest cycles.
+
+`reconcileCycleNotifications` only touches the obligation's latest
+cycle (and a just-provisioned successor on cycle-close). Tickets on
+older cycles can persist when `safeClearBell` had a transient failure
+during the closing reconcile.
+
+`tick.ts` → `sweepStuckTickets` walks `tickets/*.json` and reconciles
+every `(obligationId, cycleId)` pair found there, regardless of
+"latest". This is the retry path for prior clear failures.
+
+**Why**: without it, a transient notifier hiccup at cycle-close would
+leave a non-latest ticket+bell pair untouched until the 30-day prune.
+
+---
+
+## 11. Orphan prune is age-based and lives in `tick.ts`.
+
+The 30-day orphan-prune in `tick.ts` → `pruneOrphanTickets` is the
+last-resort cleanup for tickets that escaped every state-driven path
+(e.g. cycle file manually deleted, host crashed mid-write). It is
+age-based, not state-based, which is why it lives in the time-driven
+tick rather than the state-driven reconciler.
+
+Do NOT move this into the reconciler: the reconciler is called from
+mutation paths with `now = new Date()` but its job is to make the bell
+match disk state, not to garbage-collect by wall-clock age. Mixing
+those concerns reintroduces the kind of drift this document exists to
+prevent.
+
+---
+
+## Quick reference: where each rule is enforced
+
+| Rule | Enforced in |
+|---|---|
+| 1. Reconciler owns the bell | `reconcile.ts`, `notifier.ts`, lint/test guard |
+| 2. Mutation funnel | `handlers/shared.ts` → `persistAndReconcile` |
+| 3. Lock covers both | `dispatch.ts` → `withLock`; `tick.ts` |
+| 4. Clear-before-unlink | `reconcile.ts` → `safeClearBell` callers |
+| 5. Publish-then-write-or-rollback | `reconcile.ts` → `fireGroup`, `clearAndRepublish` |
+| 6. Ticket asserts live bell | `reconcile.ts` → `bellExists` check in `trimOrEscalateTicket` |
+| 7. `chatSessionId` survives republish | `reconcile.ts` → `clearAndRepublish` spread |
+| 8. Closure derived, not stored | `closure.ts`; cycle file shape |
+| 9. Immutable DSL fields | `handlers/amend.ts` |
+| 10. Sweep covers non-latest cycles | `tick.ts` → `sweepStuckTickets` |
+| 11. Orphan prune is age-based | `tick.ts` → `pruneOrphanTickets` |

package/server/encore/boot.ts

@@ -0,0 +1,39 @@
+// Wire the Encore tick into the host task-manager at server boot.
+// Called from `server/index.ts` after the task-manager is created
+// but before `taskManager.start()`.
+//
+// The tick goes through the per-plugin mutex (`kickTickLocked`) so
+// it serialises with handler-side mutations. Same hourly heartbeat
+// any other Encore tick would use; the dispatch handlers' kick is a
+// best-effort optimisation that surfaces newly-due notifications
+// within the same SSE turn as the mutation that caused them.
+
+import { log } from "../system/logger/index.js";
+import type { ITaskManager } from "../events/task-manager/index.js";
+import { SCHEDULE_TYPES } from "@receptron/task-scheduler";
+import { ONE_HOUR_MS } from "../utils/time.js";
+import { kickTickLocked } from "./lock.js";
+
+const ENCORE_TICK_ID = "encore-tick";
+
+export function registerEncoreTick(taskManager: ITaskManager): void {
+  taskManager.registerTask({
+    id: ENCORE_TICK_ID,
+    description: "Encore — fire and escalate notifications based on each obligation's firingPlan.",
+    schedule: { type: SCHEDULE_TYPES.interval, intervalMs: ONE_HOUR_MS },
+    run: async ({ now }) => {
+      await kickTickLocked({ now }, "encore-tick heartbeat");
+    },
+  });
+
+  // Fire-on-boot. Without this, a phase that came due during a
+  // downtime window (e.g. a daily obligation whose cycle-start is
+  // today, but the server was off all morning) wouldn't surface in
+  // the bell until the next hourly heartbeat — up to ~60 minutes
+  // of silence after reboot. Fire-and-forget so we don't block the
+  // rest of boot; errors are swallowed by tickUnlocked's inner
+  // try/catch and surfaced via log.warn.
+  kickTickLocked({ now: new Date() }, "encore-tick boot").catch((err) => {
+    log.warn("encore", "boot tick: unhandled error", { error: err instanceof Error ? err.message : String(err) });
+  });
+}

package/server/encore/closure.ts

@@ -0,0 +1,36 @@
+// Closure derivation — pure functions over the cycle file's
+// recorded-data shape.
+//
+// On-disk per-cycle state holds only DATA, not status flags:
+//   - values[fieldName] — what the user told us
+//   - skipped — explicit "this target is opted out for this cycle"
+//   - completedSteps[stepId] — timestamp set by markStepDone
+//
+// "Closed" is derived from those three. There's no `status: closed`
+// field anywhere; if there were, it could disagree with the data
+// (and did, in the original landing — bug fixed by this refactor).
+
+import type { EncoreDsl, StepDef } from "../../src/types/encore-dsl/schema.js";
+import type { TargetRecord, CycleState } from "./cycle.js";
+
+/** A step is closed if the target is skipped, OR if markStepDone
+ *  has explicitly recorded completion in `completedSteps[step.id]`.
+ *  The recorded `values` are evidence the user collected — they're
+ *  data, not the closure signal. markStepDone is the one verb that
+ *  says "this step is done"; recordValues writes partial info
+ *  without closure. */
+export function isStepClosed(record: TargetRecord | undefined, step: StepDef): boolean {
+  if (!record) return false;
+  if (record.skipped) return true;
+  return Boolean(record.completedSteps?.[step.id]);
+}
+
+export function isTargetClosed(record: TargetRecord | undefined, dsl: EncoreDsl): boolean {
+  if (!record) return false;
+  if (record.skipped) return true;
+  return dsl.steps.every((step) => isStepClosed(record, step));
+}
+
+export function isCycleClosed(state: CycleState, dsl: EncoreDsl): boolean {
+  return dsl.targets.every((target) => isTargetClosed(state.records[target.id], dsl));
+}

package/server/encore/cycle.ts

@@ -0,0 +1,276 @@
+// Per-cycle state file.
+//
+// One cycle = one markdown file at obligations/<id>/<cycleId>.md.
+// Frontmatter holds ONLY user-recorded data — no status flags, no
+// notification ids. Closure ("is this step/target/cycle done?") is
+// derived on the fly by `./closure.ts` from the recorded data; if
+// it were stored as a flag, the flag could disagree with the data
+// (and did — see PR #1416 follow-up).
+//
+// Three things on disk per target:
+//   - `values` — what was collected (markStepDone / recordValues)
+//   - `skipped` — explicit per-target skip for this cycle
+//   - `completedSteps[stepId]` — timestamp set by markStepDone
+//
+// Notification-bell tracking (`activeNotificationId`,
+// `lastPublishedSeverity`) lives in tickets, NOT in this file.
+// One ticket = one live bell entry; the tick scans
+// `tickets/*.json` to know what's active.
+
+import { parseEncoreFrontmatter as parseFrontmatter, serializeEncoreFrontmatter as serializeWithFrontmatter } from "./yaml-fm.js";
+import type { EncoreDsl } from "../../src/types/encore-dsl/schema.js";
+import type { CycleSlot } from "../../src/types/encore-dsl/cadence.js";
+import { cycleDeadline, cycleStart, formatCycleId } from "../../src/types/encore-dsl/cadence.js";
+
+export interface TargetRecord {
+  /** Per-cycle field values keyed by formSchema field name.
+   *  Sparse — fields the user hasn't told us about yet are absent
+   *  (or null). Optional pre-fill from `targets[].defaults`. */
+  values?: Record<string, unknown>;
+  /** Explicit "skip this target for this cycle" marker. Set by
+   *  markTargetSkipped. Presence means the entire target counts
+   *  as closed regardless of values / completedSteps. */
+  skipped?: string;
+  /** stepId → ISO timestamp when markStepDone was called for this
+   *  (target, step). Set by markStepDone; the only signal that a
+   *  step is closed. Steps with no required fields can only close
+   *  via this map; steps with required fields ALSO require this
+   *  marker (recordValues alone never closes anything). */
+  completedSteps?: Record<string, string>;
+  /** stepId → ISO timestamp until which the step is snoozed. The
+   *  tick skips steps whose snooze hasn't expired (treats them as
+   *  un-firable). Set by `snooze`; once the timestamp passes, the
+   *  next tick re-evaluates and may re-fire. NOT closure — a
+   *  snoozed step is still considered open by closure.ts. */
+  snoozedSteps?: Record<string, string>;
+}
+
+export interface CycleState {
+  cycleId: string;
+  cycleStart: string;
+  cycleDeadline: string;
+  /** Sparse — targets the user hasn't touched are absent. */
+  records: Record<string, TargetRecord>;
+}
+
+/** Build a fresh CycleState for a new cycle of the obligation.
+ *  Pre-fills per-target defaults into `values` where the DSL
+ *  provides them. */
+export function buildCycleState(dsl: EncoreDsl, slot: CycleSlot): CycleState {
+  const startIso = cycleStart(dsl.cadence, slot);
+  const deadlineIso = cycleDeadline(dsl.cadence, slot);
+
+  const records: Record<string, TargetRecord> = {};
+  for (const target of dsl.targets) {
+    if (target.defaults && Object.keys(target.defaults).length > 0) {
+      records[target.id] = { values: { ...target.defaults } };
+    }
+  }
+
+  return {
+    cycleId: formatCycleId(slot),
+    cycleStart: startIso,
+    cycleDeadline: deadlineIso,
+    records,
+  };
+}
+
+// ── pure mutators — write data, never flags ──────────────────────
+
+/** Record a step as done for one target. Stamps
+ *  `completedSteps[stepId]` AND merges any provided values. The
+ *  closure-derivation reads `completedSteps`; values are kept as
+ *  data the LLM can quote back later. */
+export function recordStepDone(state: CycleState, targetId: string, stepId: string, values?: Record<string, unknown>): CycleState {
+  const next = cloneState(state);
+  const record = upsertRecord(next, targetId);
+  record.completedSteps = { ...(record.completedSteps ?? {}), [stepId]: new Date().toISOString() };
+  if (values && Object.keys(values).length > 0) {
+    record.values = { ...(record.values ?? {}), ...values };
+  }
+  return next;
+}
+
+/** Skip an entire target for this cycle. Derivation treats this
+ *  as closed without inspecting individual steps. */
+export function recordTargetSkip(state: CycleState, targetId: string): CycleState {
+  const next = cloneState(state);
+  const record = upsertRecord(next, targetId);
+  record.skipped = new Date().toISOString();
+  return next;
+}
+
+/** Mark a step snoozed until `untilIso` for one target. The tick
+ *  will skip it until the timestamp passes. Not closure — once
+ *  the snooze expires the step is firable again. */
+export function recordStepSnooze(state: CycleState, targetId: string, stepId: string, untilIso: string): CycleState {
+  const next = cloneState(state);
+  const record = upsertRecord(next, targetId);
+  record.snoozedSteps = { ...(record.snoozedSteps ?? {}), [stepId]: untilIso };
+  return next;
+}
+
+/** Inverse of `recordStepSnooze`. Idempotent — no-op if the entry
+ *  was already absent. Used by the `unsnooze` dispatch kind so the
+ *  bell can republish in the same turn (the reconciler sees the
+ *  pair eligible to fire again). */
+export function recordStepUnsnooze(state: CycleState, targetId: string, stepId: string): CycleState {
+  const next = cloneState(state);
+  const record = next.records[targetId];
+  if (record?.snoozedSteps && stepId in record.snoozedSteps) {
+    const rest: Record<string, string> = {};
+    for (const [key, value] of Object.entries(record.snoozedSteps)) {
+      if (key !== stepId) rest[key] = value;
+    }
+    record.snoozedSteps = Object.keys(rest).length > 0 ? rest : undefined;
+  }
+  return next;
+}
+
+/** True iff the target's `snoozedSteps[stepId]` is present AND its
+ *  ISO timestamp hasn't passed yet. Used by the reconciler both for
+ *  "should this bundle target trim?" and "is this un-fired pair
+ *  eligible to fire?" — the symmetry the pre-reconciler code lacked.
+ *
+ *  Use a full ISO timestamp for `nowIso` (not date-only `YYYY-MM-DD`).
+ *  `snoozedUntil` is written by `recordStepSnooze` via
+ *  `toISOString()`; comparing it lexically against a date-only
+ *  string would over-block by ~24h for any snooze that doesn't land
+ *  on midnight. */
+export function isStepSnoozed(record: TargetRecord | undefined, stepId: string, nowIso: string): boolean {
+  const until = record?.snoozedSteps?.[stepId];
+  return Boolean(until && until > nowIso);
+}
+
+/** Merge new field values onto a target without marking any step
+ *  done. This is `recordValues` semantics — partial info, no
+ *  closure. */
+export function applyValues(state: CycleState, targetId: string, values: Record<string, unknown>): CycleState {
+  const next = cloneState(state);
+  const record = upsertRecord(next, targetId);
+  record.values = { ...(record.values ?? {}), ...values };
+  return next;
+}
+
+function upsertRecord(state: CycleState, targetId: string): TargetRecord {
+  let record = state.records[targetId];
+  if (!record) {
+    record = {};
+    state.records[targetId] = record;
+  }
+  return record;
+}
+
+function cloneState(state: CycleState): CycleState {
+  return JSON.parse(JSON.stringify(state)) as CycleState;
+}
+
+// ── parse / serialize ─────────────────────────────────────────────
+
+/** Parse a cycle file's raw markdown into (state, body). Tolerant
+ *  of extra fields in the frontmatter (old-shape `status` /
+ *  `activeNotificationId` / etc. from pre-refactor files are
+ *  silently dropped). The first write through `serializeCycleFile`
+ *  normalises the file to the new shape. */
+export function parseCycleFile(raw: string): { state: CycleState; body: string } {
+  const parsed = parseFrontmatter(raw);
+  if (!parsed.hasHeader) {
+    throw new Error("cycle file: missing YAML frontmatter");
+  }
+  const meta = parsed.meta as Partial<CycleState> & Record<string, unknown>;
+  if (
+    typeof meta.cycleId !== "string" ||
+    typeof meta.cycleStart !== "string" ||
+    typeof meta.cycleDeadline !== "string" ||
+    typeof meta.records !== "object" ||
+    meta.records === null ||
+    Array.isArray(meta.records)
+  ) {
+    throw new Error("cycle file: frontmatter missing required fields (cycleId/cycleStart/cycleDeadline/records)");
+  }
+  return {
+    state: {
+      cycleId: meta.cycleId,
+      cycleStart: meta.cycleStart,
+      cycleDeadline: meta.cycleDeadline,
+      records: normaliseRecords(meta.records as Record<string, unknown>),
+    },
+    body: parsed.body,
+  };
+}
+
+/** Strip old-shape fields (status, steps with stepDeadline/
+ *  activeNotificationId/lastPublishedSeverity) from each target
+ *  record. New-shape fields pass through verbatim. */
+/** Pick only string-valued entries from a map. Used to validate
+ *  `completedSteps` / `snoozedSteps` so a malformed object/boolean
+ *  doesn't get treated as a truthy completion marker. */
+function pickStringMap(raw: unknown): Record<string, string> | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const filtered: Record<string, string> = {};
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof value === "string") filtered[key] = value;
+  }
+  return Object.keys(filtered).length > 0 ? filtered : undefined;
+}
+
+function normaliseSkipped(raw: unknown): string | undefined {
+  if (typeof raw === "string") return raw;
+  // Tolerate boolean form from any intermediate iteration.
+  if (raw === true) return new Date(0).toISOString();
+  return undefined;
+}
+
+function normaliseOneRecord(raw: Record<string, unknown>): TargetRecord {
+  const normalised: TargetRecord = {};
+  // Reject arrays here — `typeof [] === "object"` would otherwise
+  // accept a malformed `values: [...]` and normalize it into an
+  // invalid field-map.
+  if (raw.values && typeof raw.values === "object" && !Array.isArray(raw.values)) {
+    normalised.values = raw.values as Record<string, unknown>;
+  }
+  const skipped = normaliseSkipped(raw.skipped);
+  if (skipped) normalised.skipped = skipped;
+  const completed = pickStringMap(raw.completedSteps);
+  if (completed) normalised.completedSteps = completed;
+  const snoozed = pickStringMap(raw.snoozedSteps);
+  if (snoozed) normalised.snoozedSteps = snoozed;
+  return normalised;
+}
+
+function normaliseRecords(raw: Record<string, unknown>): Record<string, TargetRecord> {
+  const out: Record<string, TargetRecord> = {};
+  for (const [targetId, value] of Object.entries(raw)) {
+    // `typeof [] === "object"` would otherwise accept a malformed
+    // `records.<targetId>: []` and normalise it to `{}`, silently
+    // swallowing the malformed shape. Reject arrays here.
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    out[targetId] = normaliseOneRecord(value as Record<string, unknown>);
+  }
+  return out;
+}
+
+/** Serialize a CycleState + body back to markdown. Empty per-target
+ *  `values` / `completedSteps` maps are dropped so the file stays
+ *  minimal (a target the user hasn't touched serialises as `{}`,
+ *  or is absent entirely from `records` — both shapes round-trip). */
+export function serializeCycleFile(state: CycleState, body: string): string {
+  const records: Record<string, unknown> = {};
+  for (const [targetId, record] of Object.entries(state.records)) {
+    const out: Record<string, unknown> = {};
+    if (record.values && Object.keys(record.values).length > 0) out.values = record.values;
+    if (record.skipped) out.skipped = record.skipped;
+    if (record.completedSteps && Object.keys(record.completedSteps).length > 0) out.completedSteps = record.completedSteps;
+    if (record.snoozedSteps && Object.keys(record.snoozedSteps).length > 0) out.snoozedSteps = record.snoozedSteps;
+    records[targetId] = out;
+  }
+  return serializeWithFrontmatter(
+    {
+      cycleId: state.cycleId,
+      cycleStart: state.cycleStart,
+      cycleDeadline: state.cycleDeadline,
+      records,
+    },
+    body,
+  );
+}