Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

56.2 KB
Raw Blame
/**
 * Creative Commission store + service (#2657, Phase 1 — Autonomous Creation Engine).
 *
 * A CreativeCommission is a standing, recurring creative brief that fires on a
 * schedule and drives the Creative Director's directive pipeline unattended.
 *
 * Storage: `db-primary` (docs/STORAGE.md). Real installs store one row per
 * commission in the `creative_commissions` PostgreSQL table (the full sanitized
 * record in `data` JSONB — see ./db.js). A file backend (collectionStore at
 * `data/creative-commissions/`) is retained ONLY as the dev/test escape hatch
 * (`MEMORY_BACKEND=file` or `NODE_ENV=test`), exactly like universeBuilder — so
 * the unit tests keep exercising a real store without a database. This facade
 * owns the sanitizer + merge semantics uniformly (applied on the service side,
 * not inside a backend) so the two backends can't drift, serializes the
 * scheduler-vs-request read-modify-write on a shared per-id write queue
 * (`createRecordWriteQueue`, identical to universeBuilder), and delegates only
 * plain leaf I/O to the selected backend.
 *
 * The scheduled RUNNER stays MACHINE-LOCAL — schedule/runs/assignment/enabled
 * never cross peers, because a synced schedule would double-run on every
 * machine. The commission BRIEF and feedback federate separately below, with a
 * brief-scoped LWW clock and tombstone so peers converge without arming a cron.
 *
 * FEEDBACK, by contrast, IS federated as of #2686 (split-record federation): the
 * taste reactions live in their own `commissionFeedback` record kind (see
 * ./feedbackStore.js) so a 👍/👎 rated on machine A conditions the SAME
 * commission's next run on machine B, while the `schedule` (+ future home-peer
 * pointer) stays local. The commission's `feedback[]` field is now a READ-THROUGH
 * VIEW hydrated from the federated store on read (listCommissions/getCommission);
 * `submitCommissionFeedback` writes the federated store, not this row. Legacy
 * inline reactions (Phase 2 storage) are split into the federated store lazily on
 * read and by `backfillAllCommissionFeedback()` at boot.
 *
 * The commission BRIEF itself also federates (#2686, record kind
 * `creativeCommission`) so the same commission — and thus the attach point for a
 * synced reaction — exists on every peer. The federated brief fields are
 * name / targetAbility / brief / generation / feedbackWindow (feedbackWindow is
 * part of the brief config, so it carries across machines); `schedule`, `runs`,
 * `assignment`, and `enabled` stay MACHINE-LOCAL (stripped from the wire, kept by
 * the receiver on merge, dormant on a fresh insert) so only the machine you
 * scheduled it on ever fires the cron. The federated LWW key is a brief-scoped
 * clock (`briefUpdatedAt`) that advances only on a federated-field edit (or a
 * delete/restore), NOT the general `updatedAt` that machine-local edits and run
 * appends bump — so a schedule change or a recordCommissionRun can never push a
 * stale brief or make a real brief edit lose.
 *
 * Mutations emit `commission:changed` on `commissionEvents` so the scheduler
 * re-arms crons off the DATA changing (any writer), not off the three REST
 * handlers that happen to change it today — mirroring seriesAutopilot's
 * `settings:updated` seam and keeping the HTTP route decoupled from the
 * scheduler graph.
 */

import { EFFORT_LEVELS } from '../../lib/providerModels.js';
import { join } from 'path';
import { randomUUID } from 'crypto';
import { EventEmitter } from 'events';
import { PATHS } from '../../lib/fileUtils.js';
import { createCollectionStore } from '../../lib/collectionStore.js';
import { createPgFileFacade, resolvePgBackend, isFileBackend } from '../../lib/pgFileFacade.js';
import { createRecordWriteQueue } from '../../lib/fileWriteQueue.js';
import { isValidCron, isValidRecurrence } from '../eventScheduler.js';
import { compareNewerWins } from '../../lib/lwwTimestamp.js';
import {
  contentHashForRecord,
  setSyncBaseHash,
  deleteSyncBaseHash,
  flushBaseHashes,
  withBaseHashFlushBatch,
  maybeJournalBeforeOverwrite,
} from '../../lib/conflictJournal.js';
import { emitRecordUpdated, emitRecordDeleted, emitRecordInvalidated, autoSubscribeRecordToAllPeers } from '../sharing/recordEvents.js';
import { commissionToCron } from './directive.js';
import { getAbilityAdapter } from './abilityAdapters.js';
import { normalizeMusicTasteConfig, sanitizeMusicTasteRecipe, renderMusicTasteRecipePrompt } from './musicTasteRecipe.js';
import {
  recordFeedback,
  listFeedbackForCommission,
  listFeedbackByCommissionIds,
  backfillInlineFeedback,
  tombstoneFeedbackForCommission,
} from './feedbackStore.js';
import { isStr } from '../../lib/textUtils.js';
import { codedError } from '../../lib/codedError.js';

// Emits `commission:changed` on any create/update/delete (not on run-record
// appends, which don't affect scheduling). The scheduler subscribes to re-sync.
export const commissionEvents = new EventEmitter();

export const TYPE = 'creative-commissions';
export const COMMISSIONS_SCHEMA_VERSION = 1;
export const MAX_PERSISTED_RUNS = 50;
// A run's `promptUsed` is an EXCERPT of the directive goal, not a copy of it.
// Two things read it, and neither wants the whole brief: the run ledger keeps
// MAX_PERSISTED_RUNS of them in a record that is rewritten whole on every
// mutation and shipped entire by the list route, and
// `getCommissionMusicContextForProject` hands it to the audio enqueue as the
// authoritative music PROMPT. Since the goal now carries a full instruction set
// (COMMISSION_INTENT_MAX), an uncapped copy would put a planning brief into a
// render payload. 4000 keeps both at roughly their pre-instruction-set size.
export const MAX_RUN_PROMPT_LEN = 4000;
const clampRunPrompt = (value) => (typeof value === 'string' && value.length > MAX_RUN_PROMPT_LEN
  ? `${value.slice(0, MAX_RUN_PROMPT_LEN - 1)}…`
  : value);

/**
 * The authoritative audio prompt for a taste-enabled music run.
 *
 * `promptUsed` is a HEAD excerpt of the directive goal, and the music adapter
 * composes that goal as lead + intent, THEN the taste recipe — so once the intent
 * fills the excerpt, the recipe's anchors and its original-work constraint fall off
 * the end and the render loses them. Re-render the recipe from the run's own stored
 * `tasteRecipe` and reserve room for it, the same reserve-then-clamp shape
 * `composeDirectiveGoal` uses for the feedback digest: the bounded, authoritative
 * part is never what truncation eats.
 */
function composeMusicRunPrompt(run) {
  const brief = isStr(run?.promptUsed) ? run.promptUsed : '';
  const taste = renderMusicTasteRecipePrompt(run?.tasteRecipe);
  // Short goals still carry the recipe verbatim in the excerpt — don't say it twice.
  if (!taste || brief.includes(taste)) return brief;
  const reserve = taste.length + 1; // +1 for the joining space
  const head = clampRunPrompt(brief.slice(0, Math.max(0, MAX_RUN_PROMPT_LEN - reserve)));
  return `${head} ${taste}`.trim();
}
// Feedback is kept inline on the commission record (not a separate federated
// store) — Phase 1's store shape reserved `feedback[]` precisely so Phase 2 adds
// the rate surface without a schema change. Capped like runs so a long-lived
// nightly commission can't grow the row unbounded; the directive builder only
// ever reads the last `feedbackWindow` reactions anyway.
export const MAX_PERSISTED_FEEDBACK = 100;

// Service-layer error codes (mapped to HTTP status by the route via
// createServiceErrorMapper), mirroring the universeBuilder convention.
export const ERR_NOT_FOUND = 'NOT_FOUND';
export const ERR_VALIDATION = 'VALIDATION_ERROR';

/**
 * Normalize a single feedback reaction (#2657, Phase 2). A reaction MUST carry a
 * meaningful rating — 'up'/'down' or a non-zero number (numeric ratings are
 * preserved verbatim so `renderFeedbackDigest`'s >0/<0 test still works). Returns
 * null for anything without a usable rating so a malformed/id-less entry can't
 * pollute the digest. Applied inside `sanitizeCommission` on every read/write, so
 * both backends return an identical, already-sanitized `feedback[]`.
 */
export function sanitizeFeedbackEntry(raw) {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
  const isUp = raw.rating === 'up' || (typeof raw.rating === 'number' && raw.rating > 0);
  const isDown = raw.rating === 'down' || (typeof raw.rating === 'number' && raw.rating < 0);
  if (!isUp && !isDown) return null;
  const rating = typeof raw.rating === 'number' ? raw.rating : (isUp ? 'up' : 'down');
  return {
    id: isStr(raw.id) && raw.id ? raw.id : `feedback-${randomUUID()}`,
    runId: isStr(raw.runId) ? raw.runId : null,
    rating,
    note: isStr(raw.note) ? raw.note : '',
    tags: Array.isArray(raw.tags) ? raw.tags.filter(isStr).slice(0, 20) : [],
    at: isStr(raw.at) ? raw.at : new Date().toISOString(),
  };
}

function sanitizeMusicGeneration(raw) {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
  const engine = isStr(raw.engine) ? raw.engine.trim().slice(0, 64) : '';
  const modelId = isStr(raw.modelId) ? raw.modelId.trim().slice(0, 200) : '';
  const repo = isStr(raw.repo) ? raw.repo.trim().slice(0, 200) : '';
  const durationSec = Number(raw.durationSec);
  if (!engine || !modelId || !Number.isInteger(durationSec) || durationSec < 1 || durationSec > 600) return null;
  return { engine, modelId, ...(repo ? { repo } : {}), durationSec };
}

function sanitizeMusicOutput(raw) {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
  const filename = isStr(raw.filename) ? raw.filename.trim().slice(0, 240) : '';
  if (!filename) return null;
  return {
    filename,
    durationSec: Number.isFinite(raw.durationSec) ? raw.durationSec : null,
    engine: isStr(raw.engine) ? raw.engine.trim().slice(0, 64) : null,
    modelId: isStr(raw.modelId) ? raw.modelId.trim().slice(0, 200) : null,
    recipeVersion: Number.isInteger(raw.recipeVersion) ? raw.recipeVersion : null,
    sourceHash: isStr(raw.sourceHash) ? raw.sourceHash.trim().slice(0, 64) : null,
    completedAt: isStr(raw.completedAt) ? raw.completedAt : new Date().toISOString(),
  };
}

function sanitizeRunHistoryEntry(raw) {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return raw;
  const next = { ...raw };
  // Also on READ, so a ledger written before the cap (or by a peer) shrinks the
  // first time it is loaded instead of riding along forever.
  if (isStr(raw.promptUsed)) next.promptUsed = clampRunPrompt(raw.promptUsed);
  if ('tasteRecipe' in raw) {
    const tasteRecipe = sanitizeMusicTasteRecipe(raw.tasteRecipe);
    if (tasteRecipe) next.tasteRecipe = tasteRecipe;
    else delete next.tasteRecipe;
  }
  if ('musicGeneration' in raw) {
    const musicGeneration = sanitizeMusicGeneration(raw.musicGeneration);
    if (musicGeneration) next.musicGeneration = musicGeneration;
    else delete next.musicGeneration;
  }
  if ('musicOutput' in raw) {
    const musicOutput = sanitizeMusicOutput(raw.musicOutput);
    if (musicOutput) next.musicOutput = musicOutput;
    else delete next.musicOutput;
  }
  return next;
}

/**
 * Normalize a raw record into the canonical stored shape. Returns null for a
 * non-object / id-less record (so a malformed on-disk / on-row record can't
 * surface). Applied by the service on every read and before every write, so both
 * backends return an identical shape.
 */
export function sanitizeCommission(raw) {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
  if (!isStr(raw.id) || !raw.id) return null;
  const now = new Date().toISOString();
  const brief = raw.brief && typeof raw.brief === 'object' ? raw.brief : {};
  const schedule = raw.schedule && typeof raw.schedule === 'object' ? raw.schedule : {};
  const generation = raw.generation && typeof raw.generation === 'object' ? raw.generation : {};
  // Resolve the output type up front (#2769). A KNOWN type is sanitized through
  // its ability adapter (fills that type's defaults, keeps ONLY that type's keys —
  // an image `imageCount`, a series `episodeCount`). An UNKNOWN non-empty type (a
  // forward-version record synced verbatim from a newer peer) is PRESERVED, not
  // rewritten to `video`: rewriting would corrupt the newer peer's brief on read
  // and could push the downgrade back via LWW (violating the distribution model's
  // forward-compat rule). The scheduler skips an unknown ability rather than
  // mis-generating it, so unknown = inert-but-preserved. A missing/blank type
  // falls back to the default `video`.
  const resolvedAbility = isStr(raw.targetAbility) && raw.targetAbility ? raw.targetAbility : 'video';
  const abilityAdapter = getAbilityAdapter(resolvedAbility);
  const assignment = raw.assignment && typeof raw.assignment === 'object' && !Array.isArray(raw.assignment)
    ? raw.assignment : {};
  // The LLM pin that processes the commission (CD treatment + plan stages). A
  // model without a provider can't be resolved (the runtime keys on the provider
  // first), so a provider-less pin drops the model too — matching
  // normalizeModelOverrides so a stored assignment can't carry a dangling model.
  const assignmentProviderId = isStr(assignment.providerId) && assignment.providerId.trim()
    ? assignment.providerId.trim() : null;
  const assignmentModel = assignmentProviderId && isStr(assignment.model) && assignment.model.trim()
    ? assignment.model.trim() : null;
  const musicTaste = normalizeMusicTasteConfig(brief.musicTaste);
  return {
    id: raw.id,
    name: isStr(raw.name) ? raw.name : 'Untitled Commission',
    enabled: raw.enabled !== false,
    // Preserve the resolved output type as-is (#2769) — known types pass through,
    // an unknown forward-version type round-trips untouched (see above).
    targetAbility: resolvedAbility,
    brief: {
      intent: isStr(brief.intent) ? brief.intent : '',
      genre: isStr(brief.genre) ? brief.genre : null,
      category: isStr(brief.category) ? brief.category : null,
      styleSpec: isStr(brief.styleSpec) ? brief.styleSpec : '',
      constraints: brief.constraints && typeof brief.constraints === 'object' ? brief.constraints : {},
      seedRefs: Array.isArray(brief.seedRefs) ? brief.seedRefs : [],
      ...(musicTaste ? { musicTaste } : {}),
    },
    schedule: {
      kind: isStr(schedule.kind) ? schedule.kind : 'DAILY',
      atLocalTime: isStr(schedule.atLocalTime) ? schedule.atLocalTime : null,
      weekday: Number.isInteger(schedule.weekday) ? schedule.weekday : null,
      weekdaysOnly: schedule.weekdaysOnly === true,
      cron: isStr(schedule.cron) ? schedule.cron : null,
      recurrence: schedule.recurrence && typeof schedule.recurrence === 'object'
        ? { ...schedule.recurrence, weekdays: Array.isArray(schedule.recurrence.weekdays) ? schedule.recurrence.weekdays : [] }
        : null,
      timezone: isStr(schedule.timezone) ? schedule.timezone : null,
    },
    // Per-ability generation (#2769): a known type's adapter fills its defaults
    // and keeps only its keys; an unknown (forward-version) type has no adapter, so
    // preserve the raw generation object verbatim — nothing is lost on round-trip
    // and the scheduler won't fire it anyway.
    generation: abilityAdapter ? abilityAdapter.sanitizeGeneration(generation) : { ...generation },
    // Which AI provider/model processes this commission's CD cognitive stages.
    // `providerId: null` = inherit the install's default AI Assignment.
    assignment: {
      providerId: assignmentProviderId,
      model: assignmentModel,
      ...(assignmentProviderId && EFFORT_LEVELS.includes(assignment.effort) ? { effort: assignment.effort } : {}),
    },
    // Phase 2: deep-sanitize each reaction (drop ratingless/malformed entries)
    // and cap history. Phase 1 records carry an empty array, so this is a no-op
    // for them and preserves stored, already-id'd feedback idempotently.
    feedback: Array.isArray(raw.feedback)
      ? raw.feedback.map(sanitizeFeedbackEntry).filter(Boolean).slice(-MAX_PERSISTED_FEEDBACK)
      : [],
    feedbackWindow: Number.isInteger(raw.feedbackWindow) ? raw.feedbackWindow : 5,
    runs: Array.isArray(raw.runs) ? raw.runs.slice(-MAX_PERSISTED_RUNS).map(sanitizeRunHistoryEntry) : [],
    createdAt: isStr(raw.createdAt) ? raw.createdAt : now,
    updatedAt: isStr(raw.updatedAt) ? raw.updatedAt : (isStr(raw.createdAt) ? raw.createdAt : now),
    // Brief-scoped LWW clock (#2686). The federation compares THIS, not `updatedAt`
    // — because `updatedAt` is bumped by machine-local edits (a schedule change, a
    // recordCommissionRun append) that must NOT let a stale brief win the LWW or a
    // schedule-only edit push a stale brief. `briefUpdatedAt` advances ONLY when a
    // federated field (name/targetAbility/brief/generation/feedbackWindow) changes.
    // Pre-#2686 records fall back to `updatedAt`.
    briefUpdatedAt: isStr(raw.briefUpdatedAt) ? raw.briefUpdatedAt
      : (isStr(raw.updatedAt) ? raw.updatedAt : (isStr(raw.createdAt) ? raw.createdAt : now)),
    // Soft-delete tombstone trio (#2686). The commission BRIEF federates so it
    // exists on every peer (letting a synced reaction attach to the same
    // commission); a delete must therefore propagate as a tombstone, not a hard
    // delete the LWW merge would never carry. `schedule`/`runs`/`assignment` stay
    // machine-local (stripped from the wire — see syncWire's `creativeCommission`
    // case + preserveLocalCommissionFields), so only the OWNING machine fires the
    // cron (no double-run). Pre-#2686 records carry neither field → live.
    deleted: raw.deleted === true,
    deletedAt: raw.deleted === true && isStr(raw.deletedAt) ? raw.deletedAt : null,
  };
}

// The peer-sync record kind + id shape for the federated commission brief (#2686).
export const CREATIVE_COMMISSION_KIND = 'creativeCommission';
export const COMMISSION_ID_RE = /^commission-[0-9a-z-]+$/i;

/**
 * Normalize a raw commission into the canonical wire/stored shape for a sync
 * round-trip (drop-on-floor for a non-object / bad id). Reuses sanitizeCommission
 * (which now normalizes the soft-delete trio) — the machine-local fields
 * (schedule/runs/assignment) are stripped from the actual WIRE form by syncWire's
 * `creativeCommission` case, and carried forward from the local copy on merge by
 * preserveLocalCommissionFields, so they never transit or reset a peer's schedule.
 */
export function sanitizeCommissionForSync(raw) {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
  if (!isStr(raw.id) || !COMMISSION_ID_RE.test(raw.id)) return null;
  return sanitizeCommission(raw);
}

// The MACHINE-LOCAL fields that never travel on the wire — the receiver keeps its
// OWN values for all of these. `enabled` is machine-local too (#2686): a remotely-
// inserted commission must NOT arm a cron on the receiver, so each machine decides
// whether/when it runs. `feedback` is preserved so a remote brief-win can't wipe a
// commission's un-migrated legacy inline reactions before the boot backfill runs.
const LOCAL_COMMISSION_FIELDS = ['schedule', 'runs', 'assignment', 'enabled', 'feedback'];
// The federated brief fields — a patch touching any of these advances the brief
// LWW clock (`briefUpdatedAt`); a machine-local-only patch does not.
const FEDERATED_COMMISSION_FIELDS = ['name', 'targetAbility', 'brief', 'generation', 'feedbackWindow'];

/** Re-attach the receiver's local-only fields onto a winning remote; bump the UI clock. */
function preserveLocalCommissionFields(remote, local) {
  if (!local) return remote;
  const out = { ...remote };
  for (const f of LOCAL_COMMISSION_FIELDS) out[f] = local[f];
  // The wire form set `updatedAt = briefUpdatedAt`; restore a real UI "last-changed"
  // clock (max of the two) while keeping the federated brief clock as the LWW key.
  out.updatedAt = new Date().toISOString();
  return out;
}

// Federated generation keys introduced by `creativeCommissions` v3 (#3135) —
// the per-commission render-backend pin. A v2 sender's sanitizer keeps only the
// generation keys it knows, so its record ALWAYS carries the default here.
const COMMISSION_BACKEND_PIN_KEYS = ['imageMode', 'videoMode', 'imageModelId', 'videoModelId'];

/**
 * Carry the local brief's additive federated fields onto a winning remote from a
 * sender too old to represent them (#8414). The version gate only rejects AHEAD
 * senders, so a behind sender's brief reaches this LWW merge with those fields
 * already sanitized away — its omission means "no slot", not "cleared". A sender
 * at or above the introducing version passes through untouched, so a real clear
 * still applies. A missing/unparseable sender version counts as 0.
 */
function preserveLegacyCommissionFields(remote, local, senderVersion) {
  const sender = Number(senderVersion) || 0;
  let out = remote;
  if (sender < 3 && remote.generation && local.generation) {
    // Only the keys BOTH shapes carry: a sender that also switched the output
    // type has no slot for the old type's pin, and the new type never had one.
    const pins = {};
    for (const key of COMMISSION_BACKEND_PIN_KEYS) {
      if (key in remote.generation && key in local.generation) pins[key] = local.generation[key];
    }
    if (Object.keys(pins).length) out = { ...out, generation: { ...out.generation, ...pins } };
  }
  // v4 — Digital Twin musicTaste config (#4347), persisted only when set.
  if (sender < 4 && !out.brief?.musicTaste && local.brief?.musicTaste) {
    out = { ...out, brief: { ...out.brief, musicTaste: local.brief.musicTaste } };
  }
  return out;
}

/**
 * LWW merge decision for one incoming commission (mirrors mergeWorkRecord): the
 * remote is sanitized here (drop-on-floor → null); a missing local INSERTS the
 * brief in a DORMANT state (enabled:false, no usable schedule) so it never fires
 * on the receiver until the user opts in; else the newer BRIEF clock wins, and the
 * receiver's machine-local schedule/runs/assignment/enabled/feedback carry forward
 * (they never travel), so a peer's brief edit can't arm or reset this machine.
 * `senderSchemaVersions` lets a behind sender's win keep the additive brief
 * fields its version cannot represent (see preserveLegacyCommissionFields).
 */
export function mergeCommissionRecord(local, remoteRaw, { senderSchemaVersions = null } = {}) {
  const remote = sanitizeCommissionForSync(remoteRaw);
  if (!remote) return { next: null, inserted: false, remoteWins: false, changed: false };
  if (!local) {
    // Dormant insert: enabled:false + the sanitizer's null-time schedule (no cron)
    // so editing only the synced brief on the receiver can't silently arm a daily
    // run. The user explicitly enables + schedules it locally to activate.
    return { next: { ...remote, enabled: false }, inserted: true, remoteWins: true, changed: true };
  }
  const sanitizedLocal = sanitizeCommission(local);
  const remoteWins = compareNewerWins(remote.briefUpdatedAt, sanitizedLocal.briefUpdatedAt);
  const next = remoteWins
    ? preserveLocalCommissionFields(
      preserveLegacyCommissionFields(remote, sanitizedLocal, senderSchemaVersions?.creativeCommissions),
      sanitizedLocal,
    )
    : local;
  const changed = JSON.stringify(next) !== JSON.stringify(local);
  return { next, inserted: false, remoteWins, changed };
}

// --- File backend (dev/test escape hatch): wraps collectionStore ---
// No sanitizer on the collectionStore — the facade sanitizes uniformly on the
// service side so file and PG return an identical shape. The type-level index is
// stamped on the first write so the boot verifier reports the real version.
function makeFileBackend(dir) {
  const cs = createCollectionStore({
    dir,
    type: TYPE,
    schemaVersion: COMMISSIONS_SCHEMA_VERSION,
  });
  let stamped = false;
  const ensureTypeIndex = async () => {
    if (stamped) return;
    stamped = true;
    await cs.saveTypeIndex({}).catch(() => { stamped = false; });
  };
  const live = (r) => r && r.deleted !== true;
  return {
    name: 'file',
    listRaw: async ({ includeDeleted = false } = {}) =>
      (await cs.loadAll()).filter((r) => includeDeleted || live(r)),
    readRaw: async (id, { includeDeleted = false } = {}) => {
      const rec = await cs.loadOne(id);
      if (!rec) return null;
      return includeDeleted || live(rec) ? rec : null;
    },
    listIds: async ({ includeDeleted = false } = {}) =>
      (await cs.loadAll()).filter((r) => includeDeleted || live(r)).map((r) => r.id),
    writeRaw: async (id, record) => { await ensureTypeIndex(); await cs.saveOneNow(id, record); return record; },
    deleteRaw: (id) => cs.deleteOneNow(id),
    // Same predicate as pruneTombstoned below — this backend's truth is the JSON.
    listPrunable: async (olderThanMs) => {
      if (!Number.isFinite(olderThanMs)) return [];
      return (await cs.loadAll())
        .filter((r) => r?.deleted === true && isStr(r.deletedAt) && Date.parse(r.deletedAt) < olderThanMs)
        .map((r) => r.id);
    },
    isPrunable: async (id, olderThanMs) => {
      if (!Number.isFinite(olderThanMs)) return false;
      const r = await cs.loadOne(id);
      return !!r && r.deleted === true && isStr(r.deletedAt) && Date.parse(r.deletedAt) < olderThanMs;
    },
    pruneTombstoned: async (olderThanMs) => {
      if (!Number.isFinite(olderThanMs)) return { pruned: 0, ids: [] };
      const stale = (await cs.loadAll()).filter((r) => r?.deleted === true && isStr(r.deletedAt) && Date.parse(r.deletedAt) < olderThanMs);
      for (const r of stale) await cs.deleteOneNow(r.id);
      return { pruned: stale.length, ids: stale.map((r) => r.id) };
    },
    verify: () => cs.verifySchemaVersion(),
  };
}

// --- PostgreSQL backend: pure leaf I/O from ./db.js ---
// No `verify` — the facade's verifySchemaVersion short-circuits the PG case
// without touching the backend (see below), so PG has no type-index to check.
function makePgBackend(db) {
  return {
    name: 'postgres',
    listRaw: db.listRaw,
    readRaw: db.readRaw,
    listIds: db.listIds,
    writeRaw: db.writeRaw,
    deleteRaw: db.deleteRaw,
    listPrunable: db.listPrunable,
    isPrunable: db.isPrunable,
    pruneTombstoned: db.pruneTombstoned,
  };
}

// Self-sufficient PG bring-up: the boot DB gate fail-fasts a required-but-missing
// DB, but an early scheduler warm can call in BEFORE that gate's ensureSchema()
// runs — so resolvePgBackend health-checks + brings the (idempotent) schema up.
// No file→DB migration: commissions are a brand-new record kind that never
// shipped on the file backend.
const pgBackend = () => resolvePgBackend({
  requirement: 'Creative Commissions require PostgreSQL — run `npm run setup:db` (dev/test only: set MEMORY_BACKEND=file for the unsupported file backend)',
  loadDb: () => import('./db.js'),
  makePg: makePgBackend,
});

// --- Facade: memoized backend selection + per-id write queue + verify ---
// Keyed by data dir so a test harness that swaps PATHS.data per-test still sees
// the right root. commissionStore() is the accessor the boot verifier calls.
// The facade owns the scheduler-vs-request serialization via a shared per-id
// write queue (identical to universeBuilder/storyBuilder) rather than a backend
// row lock — commissions are machine-local and written only by the single main
// server process (the scheduler fire + the REST route), so in-process per-id
// serialization is sufficient and keeps both backends serializing identically.
let _facade = null;
let _facadeDir = null;

function createFacade(dir) {
  const { getBackend, getBackendName } = createPgFileFacade({
    makeFile: () => makeFileBackend(dir),
    makePg: () => pgBackend(),
  });
  // Tail-chained per id: two RMW cycles on the SAME id serialize while different
  // ids fan out. Backend-agnostic, so file and PG serialize the same way.
  const queueRecordWrite = createRecordWriteQueue();
  return {
    dir,
    type: TYPE,
    getBackendName,
    listRaw: async (opts) => (await getBackend()).listRaw(opts),
    readRaw: async (id, opts) => (await getBackend()).readRaw(id, opts),
    listIds: async (opts) => (await getBackend()).listIds(opts),
    writeRaw: async (id, record) => (await getBackend()).writeRaw(id, record),
    deleteRaw: async (id) => (await getBackend()).deleteRaw(id),
    listPrunable: async (olderThanMs) => (await getBackend()).listPrunable(olderThanMs),
    isPrunable: async (id, olderThanMs) => (await getBackend()).isPrunable(id, olderThanMs),
    pruneTombstoned: async (olderThanMs) => (await getBackend()).pruneTombstoned(olderThanMs),
    queueRecordWrite,
    // Under PG, report ok WITHOUT forcing backend selection (the early boot
    // verifier runs before the dbReady gate); under the file escape hatch, read
    // the on-disk type index. The env check matches the selection predicate.
    verifySchemaVersion: async () => {
      if (!isFileBackend()) {
        return { ok: true, type: TYPE, onDisk: null, expected: null,
          message: `collection "${TYPE}" @ postgres (#2657)` };
      }
      return (await getBackend()).verify();
    },
  };
}

/** Get the memoized commission store facade (the boot verifier calls this). */
export function commissionStore() {
  const dir = join(PATHS.data, TYPE);
  if (_facade && _facadeDir === dir) return _facade;
  _facade = createFacade(dir);
  _facadeDir = dir;
  return _facade;
}

/** Reset the memoized facade — test seam only. */
export function _resetCommissionStore() {
  _facade = null;
  _facadeDir = null;
}

/**
 * Assert a schedule composes into a cron the scheduler will honor. Throws
 * ERR_VALIDATION otherwise (surfaced as HTTP 400). Kept here — not in the Zod
 * schema — so validation.js stays a leaf free of the eventScheduler import.
 */
export function assertValidSchedule(schedule) {
  const recurrence = schedule?.kind === 'RECURRENCE' ? schedule.recurrence : null;
  if (recurrence) {
    if (!isValidRecurrence(recurrence)) {
      throw codedError('Invalid schedule: could not derive a valid recurrence', ERR_VALIDATION);
    }
    return recurrence;
  }
  const cron = commissionToCron(schedule);
  if (!cron || !isValidCron(cron)) {
    throw codedError('Invalid schedule: could not derive a valid cron expression', ERR_VALIDATION);
  }
  return cron;
}

/**
 * Persist `feedback: []` on the machine-local commission after its legacy inline
 * reactions have been split into the federated store — WITHOUT bumping
 * `updatedAt` (the storage migration doesn't change scheduling, so it must not
 * re-arm crons or win an LWW it has no business in). Serialized on the per-id
 * queue like every other RMW here.
 */
/**
 * Union the federated feedback view with any still-stored legacy INLINE reactions,
 * deduped by runId (the deterministic `cfeedback-<runId>` key) or, for run-less
 * reactions, by id. Federated wins on a collision. This keeps reads complete
 * during the migration window: if `backfillInlineFeedback` migrated only a PREFIX
 * before throwing (inline retained for retry), neither the list page nor the
 * scheduler directive silently omits the un-migrated tail. After a full migration
 * the inline array is empty, so this is just the federated view.
 */
function unionInlineFeedback(federated, inline) {
  if (!Array.isArray(inline) || inline.length === 0) return federated;
  const seenRun = new Set(federated.filter((f) => f.runId).map((f) => f.runId));
  const seenId = new Set(federated.map((f) => f.id));
  // A run-less legacy inline entry is stored federated under the backfill's
  // remapped id (`cfeedback-<sanitized legacy id>`), so match that form too —
  // otherwise the reaction counts twice while the inline copy is retained.
  const backfilledId = (f) => `cfeedback-${String(f?.id || '').replace(/[^0-9a-z-]/gi, '-')}`;
  const extra = inline.filter((f) => (f?.runId
    ? !seenRun.has(f.runId)
    : !(seenId.has(f?.id) || seenId.has(backfilledId(f)))));
  if (extra.length === 0) return federated;
  return [...federated, ...extra].sort((a, b) => String(a.at).localeCompare(String(b.at)));
}

async function clearInlineFeedback(id) {
  const store = commissionStore();
  await store.queueRecordWrite(id, async () => {
    const currentRaw = await store.readRaw(id);
    if (!currentRaw) return;
    const current = sanitizeCommission(currentRaw);
    if (current.feedback.length === 0) return;
    await store.writeRaw(id, { ...current, feedback: [] });
  });
}

export async function listCommissions({ strict = false } = {}) {
  const raw = await commissionStore().listRaw();
  const recs = raw.map(sanitizeCommission).filter(Boolean);
  // Hydrate the federated feedback view (read-through) in ONE pass — feedback is
  // no longer stored inline on the machine-local commission (#2686). Read-only:
  // any un-migrated legacy inline feedback is split lazily by getCommission /
  // backfillAllCommissionFeedback, not on this hot list path.
  const byId = strict
    ? await listFeedbackByCommissionIds(recs.map((r) => r.id))
    : await listFeedbackByCommissionIds(recs.map((r) => r.id)).catch(() => new Map());
  // Prefer the federated view; fall back to the record's own (sanitized) inline
  // feedback only when NO federated reaction exists for it yet — the transient
  // pre-migration window before getCommission / backfillAllCommissionFeedback has
  // split its legacy inline reactions. `byId.has` (not `|| []`) distinguishes
  // "federated store has this commission's reactions" (authoritative, even if the
  // array is non-empty) from "not yet migrated" (show the legacy inline so the
  // list page doesn't transiently under-report), without ever double-counting
  // (post-migration the inline array is empty).
  for (const r of recs) r.feedback = unionInlineFeedback(byId.get(r.id) || [], r.feedback);
  return recs;
}

export async function getCommission(id) {
  const raw = await commissionStore().readRaw(id);
  const rec = raw ? sanitizeCommission(raw) : null;
  if (!rec) throw codedError(`Commission not found: ${id}`, ERR_NOT_FOUND);
  // Lazily migrate any legacy inline feedback (Phase 2 storage) into the
  // federated store, then clear it — so the scheduler's pre-fire read and the
  // route GET always see the federated feedback even before the boot backfill
  // runs. Idempotent (deterministic ids, never-clobber upsert).
  const inlineLegacy = rec.feedback;
  if (inlineLegacy.length > 0) {
    // Clear the inline array ONLY if the split SUCCEEDED. A mid-batch DB failure
    // in backfillInlineFeedback (after ≥1 reaction was federated) must leave the
    // inline array intact so a later read/boot can retry — clearing on a swallowed
    // throw would permanently drop the un-migrated reactions. Gate on "didn't
    // throw", NOT on the boolean return (which is legitimately false on an
    // idempotent re-run where everything is already federated — clearing is still
    // correct then).
    let split = false;
    try { await backfillInlineFeedback(id, inlineLegacy); split = true; } catch { /* leave inline for retry */ }
    if (split) await clearInlineFeedback(id).catch(() => {});
  }
  // No catch: a FAILED federated read must not collapse into "no feedback" —
  // the scheduler's pre-fire read would spend generation budget ignoring the
  // user's ratings. Let it throw: the route surfaces the error, the scheduler
  // aborts the fire and retries next tick. (listCommissions keeps its display
  // fallback — a degraded list page is fine; a mis-directed generation is not.)
  const federated = await listFeedbackForCommission(id);
  // Union with the legacy inline reactions so a PARTIAL migration (backfill wrote
  // a prefix then threw, inline retained for retry) never hides the un-migrated
  // tail from the scheduler directive or the UI. After a full migration the inline
  // array is empty, so this is just the federated view (dedup drops the overlap).
  rec.feedback = unionInlineFeedback(federated, inlineLegacy);
  return rec;
}

export async function createCommission(input) {
  assertValidSchedule(input.schedule);
  const now = new Date().toISOString();
  const id = `commission-${randomUUID()}`;
  // sanitizeCommission defaults runs/feedback to [] and the create schema carries
  // neither key, so no explicit empties are needed here.
  const record = sanitizeCommission({ ...input, id, createdAt: now, updatedAt: now });
  await commissionStore().writeRaw(id, record);
  commissionEvents.emit('commission:changed', { id, action: 'create' });
  // Federate the commission BRIEF (#2686) so it exists on every peer and a synced
  // reaction can attach to the same commission. The schedule/runs/assignment stay
  // machine-local (stripped from the wire), so the peer holds the brief but never
  // fires the cron.
  autoSubscribeRecordToAllPeers(CREATIVE_COMMISSION_KIND, id).catch(() => {});
  emitRecordUpdated(CREATIVE_COMMISSION_KIND, id);
  return record;
}

export async function updateCommission(id, patch) {
  if (patch.schedule) assertValidSchedule(patch.schedule);
  const store = commissionStore();
  // Serialize the load→merge→save on the per-id write queue so a concurrent
  // scheduler fire (recordCommissionRun, also queued) can't have its run-history
  // append clobbered by a stale pre-read here — the scheduler-vs-request race
  // AGENTS.md requires serializing at the record level.
  const merged = await store.queueRecordWrite(id, async () => {
    const currentRaw = await store.readRaw(id);
    if (!currentRaw) return null;
    const current = sanitizeCommission(currentRaw);
    const nowIso = new Date().toISOString();
    const next = sanitizeCommission({
      ...current,
      ...patch,
      // Deep-merge the nested objects so a partial brief/generation patch doesn't
      // wipe unspecified fields. The update-path brief/generation schemas carry
      // no defaults (unlike the create schemas), so an omitted key stays omitted
      // and is preserved here rather than overwritten with a defaulted empty.
      // `constraints` is merged one level deeper too, so `{ universeId }` in a
      // patch doesn't drop a stored `seriesId`.
      brief: patch.brief ? {
        ...current.brief,
        ...patch.brief,
        musicTaste: Object.hasOwn(patch.brief, 'musicTaste')
          ? (patch.brief.musicTaste === null
            ? null
            : { ...(current.brief.musicTaste || {}), ...patch.brief.musicTaste })
          : current.brief.musicTaste,
        constraints: patch.brief.constraints
          ? { ...current.brief.constraints, ...patch.brief.constraints }
          : current.brief.constraints,
      } : current.brief,
      schedule: patch.schedule ? { ...current.schedule, ...patch.schedule } : current.schedule,
      generation: patch.generation ? { ...current.generation, ...patch.generation } : current.generation,
      // Whole-object replace (not a deep merge): the client always sends the full
      // { providerId, model } pin, and a clear sends both null. Merging would keep
      // a stale `model` when the provider is cleared. sanitizeCommission then drops
      // a provider-less model, so the stored pin can never dangle.
      assignment: patch.assignment ? patch.assignment : current.assignment,
      id,
      createdAt: current.createdAt,
      updatedAt: nowIso,
      // Advance the federated BRIEF clock ONLY when a federated field changes —
      // a machine-local edit (schedule/assignment) must not poison the LWW key or
      // it could push a stale brief to peers / make a real brief edit lose. When it
      // DOES advance, it equals `updatedAt` (same `nowIso`); a local-only edit
      // leaves it at the prior value (< updatedAt).
      briefUpdatedAt: FEDERATED_COMMISSION_FIELDS.some((k) => k in patch)
        ? nowIso : current.briefUpdatedAt,
    });
    await store.writeRaw(id, next);
    // The keys whose VALUE actually changed — not the keys the patch mentioned.
    // The commission editor posts the whole form on every save (its `assignment`
    // rides along even when the user only fixed a typo in the brief), so a
    // patch-key list would tell the project reconciler "the provider changed" on
    // every single save and it would kill a healthy in-flight agent each time.
    const changedFields = Object.keys(next).filter(
      (k) => JSON.stringify(next[k]) !== JSON.stringify(current[k]),
    );
    return { next, changedFields };
  });
  if (!merged) throw codedError(`Commission not found: ${id}`, ERR_NOT_FOUND);
  const { next: mergedRecord, changedFields } = merged;
  // Carry the CHANGED key set: the project reconciler only cares about `enabled`
  // and `assignment`, so an edit that touched neither skips its project lookup —
  // and, more importantly, never tears down a healthy in-flight agent stage.
  // Absent (other emitters) must mean "reconcile" — we cannot prove a change was
  // irrelevant — never "skip".
  commissionEvents.emit('commission:changed', { id, action: 'update', fields: changedFields });
  // Push the brief change to subscribed peers (the schedule/runs/assignment are
  // stripped from the wire, so only the brief travels).
  emitRecordUpdated(CREATIVE_COMMISSION_KIND, id);
  return mergedRecord;
}

export async function deleteCommission(id) {
  const store = commissionStore();
  // SOFT-delete (tombstone) now that the commission BRIEF federates (#2686): a
  // hard delete would never propagate (the LWW merge only adds/updates), so an
  // out-of-date peer would resurrect the commission on the next sync. Tombstone
  // instead — the deletion rides the same push path and the peer converges.
  // Serialized on the SAME per-id write queue as update/recordRun/submitFeedback
  // so an in-flight feedback/run write can't interleave and resurrect a live row.
  const existed = await store.queueRecordWrite(id, async () => {
    const currentRaw = await store.readRaw(id);
    if (!currentRaw) return false;
    const current = sanitizeCommission(currentRaw);
    if (current.deleted) return false;
    const now = new Date().toISOString();
    // Bump the BRIEF clock too — the tombstone is a brief-level change that must
    // win the briefUpdatedAt-keyed LWW on peers (otherwise it ties the pre-delete
    // brief and never propagates).
    await store.writeRaw(id, { ...current, deleted: true, deletedAt: now, updatedAt: now, briefUpdatedAt: now });
    return true;
  });
  if (!existed) throw codedError(`Commission not found: ${id}`, ERR_NOT_FOUND);
  // Re-sync schedules (the scheduler cancels the now-tombstoned commission's cron)
  // and push the tombstone to peers.
  commissionEvents.emit('commission:changed', { id, action: 'delete' });
  emitRecordDeleted(CREATIVE_COMMISSION_KIND, id);
  return { id, deleted: true };
}

/**
 * Append a run entry to a commission (fire history). Runs are capped to the last
 * MAX_PERSISTED_RUNS. Serialized per-record on the write queue. Best-effort:
 * called from the scheduler's fire handler (outside the request lifecycle) — the
 * caller wraps errors. Returns the appended run, or null if the commission is gone.
 */
export async function recordCommissionRun(id, runEntry) {
  const store = commissionStore();
  return store.queueRecordWrite(id, async () => {
    const currentRaw = await store.readRaw(id);
    if (!currentRaw) return null;
    const current = sanitizeCommission(currentRaw);
    const tasteRecipe = sanitizeMusicTasteRecipe(runEntry.tasteRecipe);
    const musicGeneration = sanitizeMusicGeneration(runEntry.musicGeneration);
    const run = {
      id: runEntry.id || `run-${randomUUID()}`,
      ranAt: runEntry.ranAt || new Date().toISOString(),
      status: runEntry.status || 'started',
      // 'manual' = a user-initiated "Run Now" fire; anything else is a scheduled
      // cron tick. Pre-trigger runs (persisted without the field) read as
      // scheduled, which is what they were.
      trigger: runEntry.trigger === 'manual' ? 'manual' : 'schedule',
      projectId: runEntry.projectId || null,
      promptUsed: isStr(runEntry.promptUsed) ? clampRunPrompt(runEntry.promptUsed) : null,
      reason: isStr(runEntry.reason) ? runEntry.reason : null,
      error: isStr(runEntry.error) ? runEntry.error : null,
      ...(tasteRecipe ? { tasteRecipe } : {}),
      ...(musicGeneration ? { musicGeneration } : {}),
    };
    const runs = [...(current.runs || []), run].slice(-MAX_PERSISTED_RUNS);
    await store.writeRaw(id, { ...current, runs, updatedAt: new Date().toISOString() });
    emitRecordInvalidated(CREATIVE_COMMISSION_KIND, id);
    return run;
  });
}

/**
 * Resolve the machine-local taste run that owns a Creative Director project.
 * The caller uses this to override planner-authored audio params; raw Digital
 * Twin evidence never leaves the commission store.
 */
export async function getCommissionMusicContextForProject(projectId) {
  if (!isStr(projectId) || !projectId) return null;
  const raw = await commissionStore().listRaw();
  for (const value of raw) {
    const commission = sanitizeCommission(value);
    if (!commission || commission.targetAbility !== 'music') continue;
    const run = [...commission.runs].reverse().find((entry) => entry?.projectId === projectId);
    if (!run?.tasteRecipe || !run?.musicGeneration) continue;
    return {
      commissionId: commission.id,
      runId: run.id,
      prompt: composeMusicRunPrompt(run),
      tasteRecipe: run.tasteRecipe,
      musicGeneration: run.musicGeneration,
    };
  }
  return null;
}

/** Persist completed render provenance on the local run without syncing it. */
export async function recordCommissionMusicOutput(id, runId, output) {
  const musicOutput = sanitizeMusicOutput(output);
  if (!musicOutput || !isStr(runId) || !runId) return null;
  const store = commissionStore();
  return store.queueRecordWrite(id, async () => {
    const currentRaw = await store.readRaw(id);
    if (!currentRaw) return null;
    const current = sanitizeCommission(currentRaw);
    const index = current.runs.findIndex((entry) => entry?.id === runId);
    if (index < 0) return null;
    if (!current.runs[index]?.tasteRecipe || !current.runs[index]?.musicGeneration) return null;
    const runs = [...current.runs];
    runs[index] = { ...runs[index], musicOutput };
    await store.writeRaw(id, { ...current, runs, updatedAt: new Date().toISOString() });
    emitRecordInvalidated(CREATIVE_COMMISSION_KIND, id);
    return runs[index];
  });
}

/**
 * Record a user reaction to a commission run (#2657, Phase 2 — the taste
 * feedback loop). Appends a sanitized `CommissionFeedback` entry onto the
 * commission's inline `feedback[]`, keyed to the run being rated. The next
 * scheduled fire's `buildCommissionDirective` folds the last `feedbackWindow`
 * reactions into the directive, so a 👍/👎 + note demonstrably steers the next
 * run (the epic's core acceptance criterion).
 *
 * Serialized per-record on the SAME write queue as recordCommissionRun/
 * updateCommission, so a rating submitted while the scheduler is appending a run
 * can't clobber it (load→merge→save merges against the freshest persisted row).
 * Throws ERR_NOT_FOUND (→404) for an unknown commission and ERR_VALIDATION
 * (→400) when the referenced run isn't on the commission or the rating is
 * unusable. Returns the full updated commission so the UI updates reactively.
 *
 * Does NOT emit `commission:changed`: feedback never alters the schedule
 * signature, so a scheduler re-sync would be a pure no-op (mirrors
 * recordCommissionRun, which also stays silent).
 */
export async function submitCommissionFeedback(id, input) {
  // getCommission validates existence (→404), hydrates the federated feedback
  // view, and lazily splits any legacy inline reactions into the federated store.
  const commission = await getCommission(id);
  // The UI always rates a specific run; reject a runId that isn't on the record
  // so feedback can't dangle against a non-existent run.
  if (input?.runId && !commission.runs.some((r) => r.id === input.runId)) {
    throw codedError(`Run not found on commission: ${input.runId}`, ERR_VALIDATION);
  }
  // Write to the FEDERATED feedback store (#2686): one record per reaction,
  // deterministic id per run so a re-rating LWW-updates in place (one reaction
  // per run) and the change propagates to every sync peer — the machine-local
  // commission no longer carries feedback inline.
  const rec = await recordFeedback({
    commissionId: id,
    runId: input?.runId ?? null,
    rating: input?.rating,
    note: input?.note,
    tags: input?.tags,
  });
  if (!rec) throw codedError('Invalid feedback: a non-zero rating (up/down) is required', ERR_VALIDATION);
  emitRecordInvalidated(CREATIVE_COMMISSION_KIND, id);
  commission.feedback = await listFeedbackForCommission(id).catch(() => []);
  return commission;
}

/**
 * Boot-time backfill (#2686 split-record migration): move every commission's
 * legacy INLINE feedback into the federated store and clear the inline array.
 * Idempotent — after the first pass commissions carry `feedback: []`, so a
 * re-run is a no-op. Invoked from server boot after the DB is ready (the
 * scripts/migrations runner executes before the pool is up, so the data move
 * can't live there — see migration 194's registration stub).
 */
export async function backfillAllCommissionFeedback() {
  const raw = await commissionStore().listRaw();
  let migrated = 0;
  for (const r of raw) {
    const rec = sanitizeCommission(r);
    if (!rec || rec.feedback.length === 0) continue;
    // Same non-atomic guard as getCommission: clear the inline array only after
    // the split succeeded, so a transient failure mid-batch leaves the un-migrated
    // reactions in place for the next boot/read instead of silently dropping them.
    try { await backfillInlineFeedback(rec.id, rec.feedback); } catch { continue; }
    await clearInlineFeedback(rec.id).catch(() => {});
    migrated += 1;
  }
  if (migrated > 0) console.log(`🎯 Commission feedback: split ${migrated} commission(s)' inline reactions into the federated store (#2686)`);
  return { migrated };
}

// ---------- commission BRIEF federation facades (#2686) ----------
// The peer-sync layer imports these exactly as it imports writersRoom/sync.js.
// The commission record federates (so a synced reaction attaches to the same
// commission on every peer) while schedule/runs/assignment stay machine-local
// (stripped from the wire by syncWire, carried forward on merge).

/** One commission's sanitized record (tombstone surfaced), or null. */
export async function getCommissionForSync(id) {
  const raw = await commissionStore().readRaw(id, { includeDeleted: true });
  return raw ? sanitizeCommissionForSync(raw) : null;
}

/** Every LIVE commission as `{ id, updatedAt }` for full-sync coverage compare.
 *  `updatedAt` is the BRIEF clock (the wire LWW key), so coverage compares like-for-like. */
export async function listCommissionsForSync() {
  const raw = await commissionStore().listRaw();
  return raw.map(sanitizeCommissionForSync).filter(Boolean).map((r) => ({ id: r.id, updatedAt: r.briefUpdatedAt }));
}

/** Every commission id — live only by default, or all (incl. tombstones) for the sweep. */
export async function listCommissionIdsForSync(options = {}) {
  return commissionStore().listIds(options);
}

/**
 * Merge an incoming batch of commission records from a peer (LWW, tombstone-aware).
 * Serialized per-id on the same write queue as the REST writers so a user edit
 * can't clobber the merge. Journals the about-to-be-overwritten local version
 * when the remote wins, seeds the conflict-journal base hash, and re-syncs the
 * scheduler (a merged brief/tombstone can change what's armed). Mirrors
 * writersRoom's `mergeBodylessFromSync`, minus the PG row lock.
 */
export async function mergeCommissionsFromSync(remoteRecords, { source = { via: 'sync', peerId: null }, senderSchemaVersions = null } = {}) {
  if (!Array.isArray(remoteRecords)) return { applied: false, count: 0 };
  const store = commissionStore();
  let changed = 0;
  // Commissions whose tombstone arrived in THIS batch. The batch event below
  // carries no id, so the project reconciler can't act on it — but a delete the
  // user performed on another machine still has to stop the work THIS machine is
  // running for that commission (the projects live here; only the brief travels).
  // Collected on the transition only: re-emitting for an already-tombstoned record
  // on every sync would re-stop a project the user had since resumed.
  const newlyDeleted = [];
  for (const remote of remoteRecords) {
    const id = remote?.id;
    if (!isStr(id) || !COMMISSION_ID_RE.test(id)) continue;
    const applied = await store.queueRecordWrite(id, async () => {
      const local = await store.readRaw(id, { includeDeleted: true });
      const { next, inserted, remoteWins, changed: didChange } = mergeCommissionRecord(local, remote, { senderSchemaVersions });
      if (!next) return false;
      if (!inserted && (!remoteWins || !didChange)) return false;
      if (!inserted) {
        await maybeJournalBeforeOverwrite({ kind: CREATIVE_COMMISSION_KIND, id: next.id, local, remote: next, source });
      }
      await store.writeRaw(id, next);
      emitRecordInvalidated(CREATIVE_COMMISSION_KIND, id);
      await setSyncBaseHash(CREATIVE_COMMISSION_KIND, next.id, contentHashForRecord(CREATIVE_COMMISSION_KIND, next));
      if (next.deleted === true && local?.deleted !== true) newlyDeleted.push(id);
      return true;
    });
    if (applied) changed += 1;
  }
  await flushBaseHashes();
  if (changed > 0) commissionEvents.emit('commission:changed', { action: 'merge' });
  for (const id of newlyDeleted) commissionEvents.emit('commission:changed', { id, action: 'delete' });
  return changed === 0 ? { applied: false, count: 0 } : { applied: true, count: changed };
}

/** Hard-remove tombstoned commissions older than the cutoff; evicts each base hash. */
export async function pruneTombstonedCommissions(olderThanMs) {
  if (!Number.isFinite(olderThanMs)) return { pruned: 0, ids: [] };
  const store = commissionStore();
  // Eligibility comes from the BACKEND's own predicate (`listPrunable` mirrors
  // pruneTombstoned's — on PG that is the normalized `deleted_at` column, which
  // writeRaw corrects while leaving the JSON verbatim), so the set we tombstone
  // feedback for is exactly the set the delete would remove. Then each id is
  // revalidated and deleted INSIDE its per-id write queue — the same queue
  // restoreCommission and the peer merge write through — so a restore or
  // fresher tombstone landing mid-sweep either runs before us (the record no
  // longer passes the prune predicate and keeps its feedback) or after (it
  // finds the record gone and reports ERR_TARGET_GONE, exactly as if it raced
  // the old bulk prune). Feedback is tombstoned before
  // the row delete: a failure there throws, the commission tombstone stays
  // put, and the next sweep retries both halves — never an orphaned rating.
  const candidates = await store.listPrunable(olderThanMs);
  const ids = [];
  await withBaseHashFlushBatch(async () => {
    for (const id of candidates) {
      const pruned = await store.queueRecordWrite(id, async () => {
        // Recheck the backend's FULL prune predicate, not just deleted:true — a
        // peer merge that rewrote this tombstone with a fresher deletedAt mid-
        // sweep restarted its GC grace period, and hard-deleting it early would
        // let an offline peer resurrect the stale record.
        if (!(await store.isPrunable(id, olderThanMs))) return false;
        await tombstoneFeedbackForCommission(id);
        await store.deleteRaw(id);
        return true;
      });
      if (!pruned) continue;
      ids.push(id);
      await deleteSyncBaseHash(CREATIVE_COMMISSION_KIND, id).catch(() => {});
    }
  });
  return { pruned: ids.length, ids };
}

/**
 * Restore a tombstoned/edited commission from a conflict-journal snapshot. Merges
 * the RESTORABLE brief fields, un-tombstones, bumps updatedAt so the restore wins
 * the next LWW and re-pushes. Returns null for a missing record (→ ERR_TARGET_GONE).
 */
export async function restoreCommission(id, patch) {
  const store = commissionStore();
  const result = await store.queueRecordWrite(id, async () => {
    const currentRaw = await store.readRaw(id, { includeDeleted: true });
    if (!currentRaw) return null;
    const current = sanitizeCommission(currentRaw);
    const next = sanitizeCommission({
      ...current,
      ...(patch && typeof patch === 'object' ? patch : {}),
      id, createdAt: current.createdAt,
      // Never let a snapshot restore resurrect the machine-local fields — keep ours.
      schedule: current.schedule, runs: current.runs, assignment: current.assignment,
      enabled: current.enabled,
      // Advance the brief clock so the restore wins the next LWW and re-pushes.
      deleted: false, deletedAt: null, updatedAt: new Date().toISOString(), briefUpdatedAt: new Date().toISOString(),
    });
    await store.writeRaw(id, next);
    return next;
  });
  if (!result) return null;
  commissionEvents.emit('commission:changed', { id, action: 'restore' });
  emitRecordUpdated(CREATIVE_COMMISSION_KIND, id);
  return result;
}