Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
25.3 KB
Raw Blame
/**
 * The dream pass's mutation stage: turn a decided plan into disk state.
 *
 * One reason to change: the ORDER and mechanics of the writes. Nothing
 * here decides anything about the vault's contents — every choice was
 * already made by the planning stages. What this module owns is the
 * sequence that keeps the on-disk invariants true:
 *
 *   1. Write new unconfirmed preferences (so signal moves can find
 *      them).
 *   2. Apply refresh (counters, confidence, promotion) to existing
 *      preferences.
 *   3. Move retiring preferences out (after the refresh has had a
 *      chance to surface the most recent counters in the retired
 *      file). NOTE: refresh skips entries that will retire.
 *   4. Move consumed signals into `processed/`.
 *
 * Log emission is stage 5 and lives in `dream-report.ts`.
 *
 * Workrun checkpoints are emitted here rather than by the orchestrator
 * because a marker must mean "every durable effect attributed to that
 * phase is already on disk" — only the code that performs the writes
 * knows where that point is.
 */

import { legacyVaultOf } from "./no-vault.ts";
import type { Authority } from "../store/constants.ts";
import { existsSync, mkdirSync } from "node:fs";
import { basename } from "node:path";

import { appendDecisionChangeReceipt } from "./decisions/receipts.ts";
import { preferenceSlug, type PlanState } from "./dream-plan.ts";
import { SafeguardAbortError, SafeguardTimeoutError, type Safeguard } from "./safeguard.ts";
import type { RefreshResult } from "./dream-refresh.ts";
import type { DreamGatedRetireEntry } from "./dream-types.ts";
import { WORKRUN_PHASE, type WorkrunHandle } from "./dream-workrun.ts";
import { collectEvidenceForSlug } from "./evidence.ts";
import { runHealEnrichment } from "./heal-run.ts";
import { CHAIN_DECAY_STALE_DAYS } from "./inject-governor.ts";
import { appendLogEvent } from "./log.ts";
import { archivedSignalPath, brainDirs, preferencePathOf, processedSignalPath } from "./paths.ts";
import { loadPreference, moveToRetired } from "./preference.ts";
import { isRetiredEntry, preferencesStoreOnly, storePreferenceEntry } from "./preference-store.ts";
import { writePreferenceTxn } from "./preference-txn.ts";
import { isoSecond } from "./time.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import {
  BRAIN_LOG_EVENT_KIND,
  BRAIN_PREFERENCE_STATUS,
  BRAIN_RETIRED_REASON,
  type BrainConfig,
  type BrainPreference,
  type BrainRetiredReason,
} from "./types.ts";
import { renameWithRetry } from "../fs-atomic.ts";
import { parseFrontmatter } from "../vault.ts";
import { routeSignalState, signalsStoreOnly } from "./signal-state.ts";
import { readStoreEntities } from "../store/read/store-entities.ts";
import { REMOTE_DENY_VISIBILITY_TOKEN } from "../graph/visibility.ts";

/**
 * The authority of every dream write under brain store dual writes: dream
 * is an automatic pass, so it decides as an agent even when an operator
 * started it from the CLI.
 */
const DREAM_AUTHORITY = "agent" satisfies Authority;

const DAY_MS = 24 * 3600 * 1000;

/** Agent of record when the caller declared no name. */
const DEFAULT_DREAM_AGENT = "dream";

export interface DreamApplyInput {
  readonly vault: string | null;
  readonly cfg: BrainConfig;
  readonly now: Date;
  readonly plan: PlanState;
  readonly refresh: RefreshResult;
  /** Identity threaded into edit-history and decision receipts. */
  readonly agentName: string | undefined;
  /** `[[Brain/log/<date>]]`, stamped as `retired_by` on each move. */
  readonly wikilinkToRun: string;
  /** Resolved `dream.heal_enrich` gate for this run. */
  readonly healEnrichEnabled: boolean;
  /**
   * The pass's cooperative deadline, forwarded to the one sub-unit here
   * that is unbounded in the vault's size: the opt-in heal enrichment,
   * which reads and rewrites every user page outside `Brain/`. Nothing
   * else in this module iterates over anything but the decided plan, so
   * nothing else needs it.
   */
  readonly safeguard?: Safeguard;
  readonly workrun: WorkrunHandle | null;
}

export interface DreamApplyResult {
  /** Signal ids actually moved into `processed/`. */
  readonly moved: string[];
  /** Signal ids actually moved into `inbox/archived/`. */
  readonly archived: string[];
  /** Retires the destructive-from-confirmed gate declined. */
  readonly gatedRetires: DreamGatedRetireEntry[];
  /** User pages the opt-in heal phase enriched. */
  readonly healEnriched: number;
}

/**
 * Signal ids a dry run WOULD move. Reported so the caller's summary is
 * accurate without touching disk.
 */
export function plannedSignalMoveIds(plan: PlanState): string[] {
  return Array.from(plan.signalsToMove.values(), (sig) => sig.id);
}

/** Signal ids a dry run WOULD archive; the archive step's dry-run count. */
export function plannedSignalArchiveIds(plan: PlanState): string[] {
  return Array.from(plan.signalsToArchive.values(), (sig) => sig.id);
}

export function applyDreamPlan(input: DreamApplyInput): DreamApplyResult {
  const { vault, cfg, now, plan, refresh, wikilinkToRun, workrun } = input;
  const agent = input.agentName ?? DEFAULT_DREAM_AGENT;

  // This module renames signal files directly, so it owes the vault-identity
  // assertion on its own entry rather than trusting whoever called it. The
  // check is an idempotent in-memory pin and the caller's `openWorkrun` has
  // already satisfied it for this root, so it never fires twice in anger.
  // With no vault the store writes check the store identity (D14 item 13).
  if (vault !== null) assertVaultIdentityForWrite(vault);

  writePreferences(input, agent);
  writeConfidenceReceipts(vault, refresh, agent, now);

  // Synthesize is durable here and nowhere earlier: every new
  // unconfirmed preference, every refreshed preference and every
  // confidence receipt has landed. `promote_complete` is the pre-F2
  // name for the same writes, so it moves with it rather than being
  // left behind claiming a batch that had not started.
  workrun?.checkpoint(WORKRUN_PHASE.promoteComplete);
  workrun?.checkpoint(WORKRUN_PHASE.synthesizeComplete);

  const gatedRetires = executeRetires(vault, cfg, now, plan, wikilinkToRun);

  // Every planned retire has been moved (or explicitly gated) by here.
  workrun?.checkpoint(WORKRUN_PHASE.retireComplete);

  const moved = moveConsumedSignals(vault, plan);
  const archived = archiveStaleSignals(vault, plan);
  const healEnriched = input.healEnrichEnabled
    ? runHealEnrichmentSafely(vault, input.safeguard)
    : 0;

  // Heal's second half (the optional enrichment) is durable here; its
  // first half was the retire loop above. The marker sits at the later
  // of the two, so it is never a claim about work still to come.
  workrun?.checkpoint(WORKRUN_PHASE.healComplete);

  return { moved, archived, gatedRetires, healEnriched };
}

/**
 * Steps 1 and 2: create the freshly-promoted preferences, then rewrite
 * the refreshed ones.
 *
 * Edit-history (F4): every dream-pass write records its content
 * before/after so a preference's evolution stays auditable. The agent of
 * record is whoever invoked the dream run.
 *
 * v0.12.0 Brain Integrity Suite: both loops route through
 * `writePreferenceTxn` so `_revision` auto-stamps and `_content_hash`
 * lands automatically on confirmed promotions. The empty expectations
 * array is deliberate - dream's plan-time logic has already decided to
 * proceed; the txn just owns the bookkeeping.
 */
function writePreferences(input: DreamApplyInput, agent: string): void {
  const { vault, cfg, now, plan, refresh } = input;
  const historyOpts = { agent, now: () => now };

  for (const np of plan.newUnconfirmed) {
    // Fresh pref has no apply-evidence yet; recentApplied/recentViolated
    // start empty and stay so until the next dream pass after the
    // first `brain_apply_evidence` event.
    writePreferenceTxn(
      vault,
      {
        slug: np.slug,
        topic: np.topic,
        principle: np.principle,
        created_at: isoSecond(now),
        unconfirmed_until: isoSecond(addDays(now, cfg.dream.unconfirmed_window_days)),
        status: BRAIN_PREFERENCE_STATUS.unconfirmed,
        evidenced_by: np.evidencedBy,
        // No evidence yet → Wilson lower bound on (0, 0) is 0. Pre-
        // seed the field so refresh on the next pass does not have
        // to treat `null` as "needs update" (which would lift
        // `changed: false` no-ops into spurious rewrites).
        confidence_value: 0,
        recentApplied: [],
        recentViolated: [],
        ...(np.scope ? { scope: np.scope } : {}),
        // The scope is read back from stored signals: a legacy value
        // must not abort the pass (see `lenientScopeTags`).
        lenientScopeTags: true,
        ...(np.supersedes ? { supersedes: np.supersedes } : {}),
        // F5: bi-temporal validity extracted from the source signal.
        ...(np.valid_from ? { valid_from: np.valid_from } : {}),
        ...(np.valid_until ? { valid_until: np.valid_until } : {}),
        // The strictest visibility of the records it was drafted from.
        ...(np.visibility.length > 0 ? { visibility: np.visibility } : {}),
      },
      [],
      { overwrite: false, authority: DREAM_AUTHORITY },
      historyOpts,
    );
  }

  // Cross-topic rule promotion (t_642bc2b8): the planned rule is an
  // ordinary unconfirmed preference through the same txn chokepoint -
  // `inferred` provenance plus the evidence wikilinks and `related`
  // lineage are what make it a promotion rather than a new claim.
  // `overwrite: false` like the topic plan: the planner's content-slug
  // dedup already decided the file is new, and a surprise collision
  // must fail loudly rather than clobber.
  for (const ct of plan.crossTopicRules) {
    writePreferenceTxn(
      vault,
      {
        slug: ct.slug,
        topic: ct.topic,
        principle: ct.principle,
        created_at: isoSecond(now),
        unconfirmed_until: isoSecond(addDays(now, cfg.dream.unconfirmed_window_days)),
        status: BRAIN_PREFERENCE_STATUS.unconfirmed,
        evidenced_by: ct.evidencedBy,
        // No evidence yet, matching the topic plan's pre-seeding.
        confidence_value: 0,
        recentApplied: [],
        recentViolated: [],
        provenance: "inferred",
        related: ct.related,
        // The strictest visibility of the sources (review finding 63):
        // the rule restates a source's principle verbatim, so it may
        // never land at default visibility behind a restricted source.
        // Written only when non-empty, like the topic plan's stamp.
        ...(ct.visibility.length > 0 ? { visibility: ct.visibility } : {}),
        // The sources' shared owner token, so owner-scoped recall keeps
        // the rule as private as its sources; ownerless rules omit it.
        ...(ct.owner ? { owner: ct.owner } : {}),
      },
      [],
      { overwrite: false, authority: DREAM_AUTHORITY },
      historyOpts,
    );
  }

  for (const update of refresh.updated.values()) {
    // Rebuild the evidence slice from the log on every pass so the
    // pref body stays in sync with the counters even when the
    // counters themselves stayed put (e.g. dropping the
    // v0.9.x placeholder body during a no-counter-change run).
    const ev = collectEvidenceForSlug(vault, update.slug, {
      sinceIso: update.created_at,
    });
    // The freshness trend was classified at PLAN time (planRefresh)
    // so the no-op pre-flight rendered these exact bytes.
    writePreferenceTxn(
      vault,
      {
        slug: update.slug,
        topic: update.topic,
        principle: update.principle,
        created_at: update.created_at,
        unconfirmed_until: update.unconfirmed_until,
        status: update.status,
        evidenced_by: update.evidenced_by,
        confirmed_at: update.confirmed_at,
        applied_count: update.applied_count,
        violated_count: update.violated_count,
        last_evidence_at: update.last_evidence_at,
        confidence: update.confidence,
        confidence_value: update.confidence_value,
        pinned: update.pinned,
        recentApplied: ev.applied,
        recentViolated: ev.violated,
        ...(update.freshness_trend !== undefined
          ? { freshness_trend: update.freshness_trend }
          : {}),
        // Derived-fact fields (finding 77): the update carries a promoted
        // rule's provenance and lineage through its counter changes, in
        // the same render position the writer uses, so the bytes match
        // the no-op pre-flight and the fields survive every rewrite.
        ...(update.provenance !== undefined ? { provenance: update.provenance } : {}),
        ...(update.related !== undefined && update.related.length > 0
          ? { related: update.related }
          : {}),
        // The record's `visibility:` tokens (review round 2), threaded like
        // provenance and related: the update write is the only thing that
        // keeps the line on a restricted rule through its counter changes,
        // and the no-op pre-flight needs the input to carry it to match the
        // bytes on disk. Written only when non-empty, like every stamp.
        ...(update.visibility !== undefined && update.visibility.length > 0
          ? { visibility: update.visibility }
          : {}),
        ...(update.scope ? { scope: update.scope } : {}),
        lenientScopeTags: true,
      },
      [],
      { overwrite: true, authority: DREAM_AUTHORITY },
      historyOpts,
    );
  }
}

/**
 * Belief lifecycle suite (B4): the preference-confidence update path
 * emits a decision-change receipt for each material confidence band
 * change captured this pass. `bandDrops` is the existing, already-
 * computed set of material weakenings (a band actually dropped), so
 * this rides on data the refresh already produced without touching its
 * byte-identical no-op guarantees. The receipt's idempotency key
 * (subject + before + after) makes a re-run a no-op. Fail-soft.
 */
function writeConfidenceReceipts(
  vault: string | null,
  refresh: RefreshResult,
  agent: string,
  now: Date,
): void {
  // Decision-change receipts are a vault lane until the decisions lane has
  // a record kind (design D14 item 2); with no vault they are not written.
  if (vault === null) return;
  for (const d of refresh.bandDrops) {
    const before = `confidence:${d.previous}${d.previous_value !== null ? `(${d.previous_value.toFixed(2)})` : ""}`;
    const after = `confidence:${d.next}(${d.next_value.toFixed(2)})`;
    try {
      appendDecisionChangeReceipt(vault, {
        subject: d.id,
        before,
        after,
        confidenceDelta: d.previous_value !== null ? d.next_value - d.previous_value : null,
        actor: agent,
        rationale: `applied ${d.applied} / violated ${d.violated}`,
        reasonCode: "confidence-refresh",
        ts: now.toISOString(),
      });
    } catch {
      // Accountability mirror is best-effort; the refreshed preference
      // bytes remain authoritative.
    }
  }
}

/** Step 3: move each planned retire into `retired/`, honouring the evidence gate. */
function executeRetires(
  vault: string | null,
  cfg: BrainConfig,
  now: Date,
  plan: PlanState,
  wikilinkToRun: string,
): DreamGatedRetireEntry[] {
  // v0.12.0 Brain Integrity Suite: declined retires accumulate here.
  // Always an array (even when no gate is configured) so the eventual
  // DreamRunSummary.gated_retires field is consistently shaped.
  const gatedRetires: DreamGatedRetireEntry[] = [];
  const gateThreshold = cfg.retire.confirmed_evidence_min_threshold;

  for (const r of plan.retires) {
    const fromPath = preferencePathOf(vault, r.slug);
    // The page on an unswitched machine, the store's fold once switched.
    if (!preferenceHeld(vault, r.slug, fromPath)) continue;
    // v0.12.0 Brain Integrity Suite: destructive-from-confirmed gate.
    // When the operator has set retire.confirmed_evidence_min_threshold,
    // refuse to retire a confirmed (unpinned) pref whose accumulated
    // evidence count is below the configured floor. Operator-initiated
    // retires bypass.
    if (gateThreshold !== undefined && gateThreshold > 0) {
      try {
        const existing = loadPreference(vault, r.slug);
        if (existing !== null && shouldGateRetireFromConfirmed(existing, r.reason, gateThreshold)) {
          gatedRetires.push({
            pref_id: existing.id,
            topic: existing.topic,
            applied_count: existing.applied_count,
            violated_count: existing.violated_count,
            threshold: gateThreshold,
            attempted_reason: r.reason,
          });
          continue;
        }
      } catch {
        // Parse failure - fall through to the normal retire path
        // (moveToRetired will surface the error through stderr below).
      }
    }
    try {
      moveToRetired(vault, fromPath, r.reason, {
        now,
        authority: DREAM_AUTHORITY,
        retired_by: wikilinkToRun,
        ...(r.supersededBy ? { superseded_by: r.supersededBy } : {}),
      });
      // Belief lifecycle suite (A4): record the accelerated retirement of
      // a low-recall superseded ancestor as a dedicated audit event.
      if (r.chainDecay) {
        appendLogEvent(vault, {
          timestamp: isoSecond(now),
          eventType: BRAIN_LOG_EVENT_KIND.chainDecay,
          body: {
            preference: `[[ret-${r.slug}]]`,
            reason: r.reason,
            stale_days: String(CHAIN_DECAY_STALE_DAYS),
          },
        });
      }
    } catch (err) {
      // A retire failure is logged via the `skip-corrupted-frontmatter`
      // pathway only if it stemmed from a parse error during the
      // plan; here the file may have been moved already (rare race).
      // Surface the cause so an operator chasing a missing retire can
      // see which slug tripped.
      process.stderr.write(
        `warning: retire stale pref ${r.slug} failed: ${(err as Error).message}\n`,
      );
    }
  }
  return gatedRetires;
}

/** Whether the active preference `slug` exists: its page, or the store's fold once switched. */
function preferenceHeld(vault: string | null, slug: string, pagePath: string): boolean {
  if (!preferencesStoreOnly(vault)) return existsSync(pagePath);
  const found = storePreferenceEntry(slug);
  return found !== undefined && !isRetiredEntry(found);
}

/**
 * Step 4: move every consumed signal out of `inbox/`. On a store-only
 * machine (task 2.10) a move is a `signal-state` record (`consumed`) and no
 * file moves; an unswitched machine renames the file and dual-writes the
 * record.
 */
function moveConsumedSignals(vault: string | null, plan: PlanState): string[] {
  const moved: string[] = [];
  const storeOnly = signalsStoreOnly(vault);
  // Read once: recording one signal's move does not change whether another
  // is live, and each append would otherwise invalidate the fold cache.
  const live = storeOnly ? liveStoreSignals() : null;
  for (const sig of plan.signalsToMove.values()) {
    // The legacy destination, resolved only by the legacy move.
    const dest = (): string =>
      processedSignalPath(legacyVaultOf(vault, "moveConsumedSignals"), sig.date, sig.slug);
    try {
      if (live !== null && !live.has(sig.id)) continue;
      // Judged before the move, from the page the scan read.
      const meta = storeOnly ? undefined : readFrontmatterOf(sig.path);
      routeSignalState({
        vault,
        id: sig.id,
        state: "consumed",
        authority: DREAM_AUTHORITY,
        legacyFrontmatter: meta,
        legacy: () => renameWithRetry(sig.path, dest()),
      });
      moved.push(sig.id);
    } catch (err) {
      // Best-effort: a missing source signal (already moved) is
      // benign on rerun. Still surface so a real I/O issue is visible.
      process.stderr.write(
        `warning: move signal ${sig.id} to processed/ failed: ${(err as Error).message}\n`,
      );
    }
  }
  return moved;
}

/**
 * Step 4b: move every signal the archive policy selected (see
 * `signal-archive.ts`) from `inbox/` to `inbox/archived/`, byte for byte.
 *
 * Never overwrites: a destination that exists is left alone and the signal
 * stays in the inbox (the planner already skips names it saw in the
 * archive; this covers a file that appeared since the scan). A failed move
 * is reported and the signal stays where it was, so a rerun picks it up.
 *
 * On a store-only machine (task 2.10) the archive is a `signal-state`
 * record (`archived`); no folder is created and no file moves.
 *
 * No deadline checkpoint inside the loop, like the processed/ move above: a
 * pass stopped half way would leave archived files the run's log never
 * names. The pass's own post-mutation checkpoint follows immediately.
 */
function archiveStaleSignals(vault: string | null, plan: PlanState): string[] {
  const archived: string[] = [];
  if (plan.signalsToArchive.size === 0) return archived;
  const storeOnly = signalsStoreOnly(vault);
  const live = storeOnly ? liveStoreSignals() : null;
  // The legacy destination, resolved only off the store-only path.
  const archivedPath = (path: string): string =>
    archivedSignalPath(legacyVaultOf(vault, "archiveStaleSignals"), basename(path));
  if (!storeOnly) {
    mkdirSync(brainDirs(legacyVaultOf(vault, "archiveStaleSignals")).archived, {
      recursive: true,
    });
  }
  for (const sig of plan.signalsToArchive.values()) {
    try {
      if (live !== null) {
        if (!live.has(sig.id)) continue;
      } else {
        const dest = archivedPath(sig.path);
        if (existsSync(dest)) {
          process.stderr.write(
            `warning: archive signal ${sig.id}: ${basename(dest)} already exists in ` +
              `inbox/archived/; left in the inbox\n`,
          );
          continue;
        }
      }
      routeSignalState({
        vault,
        id: sig.id,
        state: "archived",
        authority: DREAM_AUTHORITY,
        legacyFrontmatter: storeOnly ? undefined : readFrontmatterOf(sig.path),
        legacy: () => renameWithRetry(sig.path, archivedPath(sig.path)),
      });
      archived.push(sig.id);
    } catch (err) {
      process.stderr.write(
        `warning: archive signal ${sig.id} to inbox/archived/ failed: ${(err as Error).message}\n`,
      );
    }
  }
  return archived;
}

/** The ids the store's signal fold holds in the inbox (store-only moves). */
function liveStoreSignals(): ReadonlySet<string> {
  const live = new Set<string>();
  for (const [id, signal] of readStoreEntities()?.signals ?? []) {
    if (signal.state === "active") live.add(id);
  }
  return live;
}

/**
 * The frontmatter of a signal page, judged for the dual write before it
 * moves. A page that cannot be read is judged private (fail closed).
 */
function readFrontmatterOf(path: string): Record<string, unknown> {
  try {
    return parseFrontmatter(path)[0];
  } catch {
    return { visibility: [REMOTE_DENY_VISIBILITY_TOKEN] };
  }
}

/**
 * Heal phase (F6): opt-in deterministic vault enrichment, run after the
 * retire/move mutations (heal-after-mutations). Off by default so the
 * default install stays byte-identical; a failure is a warning, never
 * fatal to the dream pass.
 *
 * A SAFEGUARD STOP IS NOT SUCH A FAILURE, and the difference is the whole
 * reason this catch is narrowed. "Heal could not enrich a page" is a
 * hygiene miss the pass survives; "the operator cancelled" and "the pass
 * is past its budget" are decisions about the RUN, and swallowing either
 * into a stderr warning plus `0` would report a pass that enriched
 * nothing where the truth is a pass that was stopped. The pass's own
 * post-mutation checkpoint would throw an instant later anyway - so
 * absorbing it here only ever bought a wrong `heal_enriched: 0` on the
 * way to the same error.
 */
function runHealEnrichmentSafely(vault: string | null, safeguard: Safeguard | undefined): number {
  // Heal enrichment rewrites user notes; with no vault there are none.
  if (vault === null) return 0;
  try {
    return runHealEnrichment(vault, safeguard ? { safeguard } : {}).enriched;
  } catch (err) {
    if (err instanceof SafeguardTimeoutError || err instanceof SafeguardAbortError) throw err;
    process.stderr.write(`warning: heal enrichment failed: ${(err as Error).message}\n`);
    return 0;
  }
}

/**
 * Brain Integrity Suite (v0.12.0). Pure decision function for the
 * destructive-from-confirmed gate. Exported so the gate logic can be
 * unit-tested without driving a full dream run.
 *
 * Returns `true` when the candidate retire MUST be held back. The
 * caller is responsible for recording a {@link DreamGatedRetireEntry}
 * and skipping the actual `moveToRetired` call.
 */
export function shouldGateRetireFromConfirmed(
  existing: BrainPreference,
  reason: BrainRetiredReason,
  threshold: number | undefined,
): boolean {
  if (threshold === undefined || threshold <= 0) return false;
  if (reason === BRAIN_RETIRED_REASON.userRejected) return false;
  if (reason === BRAIN_RETIRED_REASON.mergedInto) return false;
  if (existing.status !== BRAIN_PREFERENCE_STATUS.confirmed) return false;
  if (existing.pinned) return false;
  const evidenceCount = (existing.applied_count ?? 0) + (existing.violated_count ?? 0);
  return evidenceCount < threshold;
}

/**
 * Slugs whose retire the gate declined. The log body and the
 * DreamRunSummary must agree on this set, or the next dream pass would
 * parse a `pref-foo` log claiming the pref was retired while the file is
 * still in `preferences/`.
 */
export function gatedRetireSlugs(gatedRetires: ReadonlyArray<DreamGatedRetireEntry>): Set<string> {
  return new Set(gatedRetires.map((g) => preferenceSlug(g.pref_id)));
}

function addDays(d: Date, days: number): Date {
  return new Date(d.getTime() + days * DAY_MS);
}