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

37.0 KB
Raw Blame
/**
 * Writers Room — storage orchestration for folders, works, drafts, and exercises.
 *
 * Metadata (folders, work manifests, decomposed draft versions, exercises) is
 * persisted via the storage dispatcher (./store.js): PostgreSQL on a normal
 * install (#1017), or the legacy on-disk JSON layout under data/writers-room/
 * on the dev/test file escape hatch. The draft PROSE BODIES always stay on disk
 * as .md files (file-primary) regardless of backend — this module owns those:
 *   works/<workId>/drafts/<draftVersionId>.md
 *
 * A work manifest holds work metadata + the active-draft pointer + the version
 * history (drafts[]); store.js decomposes drafts[] into draft-version rows on
 * the PG backend and reassembles them on read, so this module's public API and
 * the manifest shape are unchanged. See docs/features/writers-room.md.
 */

import { ServerError } from '../../lib/errorHandler.js';
import { writersRoomWorksQuerySchema } from '../../lib/pipelineValidation.js';
import { randomUUID, createHash } from 'crypto';
import { readFile } from 'fs/promises';
import { atomicWrite, ensureDir, rmGuarded } from '../../lib/fileUtils.js';
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
import { countWords } from '../../lib/textUtils.js';
import { WORK_KINDS, WORK_STATUSES } from '../../lib/writersRoomPresets.js';
import { renderCharacterEvolutionListForPrompt } from '../../lib/characterEvolution.js';
import { sanitizeVoiceExemplars, renderVoiceExemplars } from '../../lib/styleGuide.js';
import { emitRecordUpdated, emitRecordDeleted, autoSubscribeRecordToAllPeers } from '../sharing/recordEvents.js';
import { nowIso, badRequest, notFound, wrWorkDir, wrDraftPath } from './_shared.js';
import { writersRoomStore } from './store.js';
import { WRITERS_ROOM_WORK_KIND, WRITERS_ROOM_FOLDER_KIND, WRITERS_ROOM_EXERCISE_KIND } from './syncLogic.js';

const store = () => writersRoomStore();

// ---------- text analysis ----------

// `countWords` lives in lib/textUtils.js — the one whitespace word count, on
// both sides of the client/server line (`textUtils.test.js` fails the suite on a
// re-spelled copy). Re-exported here so existing importers of this module keep
// working unchanged. The editorial prose checks count LETTER words instead,
// through lib/editorial/proseTics.js#tokenizeWords — a different rule on
// purpose, owned the same way.
export { countWords };

export function contentHash(text) {
  return createHash('sha256').update(text || '').digest('hex');
}

/**
 * Build a segment index over Markdown-flavored prose.
 *
 * Splits on # / ## / ### headings (### collapses to scene; the outline panel
 * doesn't visually distinguish a separate "beat" tier in Phase 1). Anything
 * before the first heading becomes a "preamble" segment. No headings → one
 * "(untitled)" segment covers the whole body. Empty/missing text → empty
 * array (so a brand-new draft doesn't show a phantom segment in the outline).
 * The index powers the outline panel today and will anchor stale-analysis
 * detection in later phases.
 */
function segId(seq) {
  return `seg-${String(seq).padStart(3, '0')}`;
}

export function buildSegmentIndex(text) {
  // Whitespace-only counts as empty too — otherwise '   ' would emit a
  // phantom "(untitled)" segment in the outline panel of a brand-new draft
  // where the user has only hit space/enter a couple times.
  if (!text || !String(text).trim()) return [];
  const headingRe = /^(#{1,3})\s+(.+)$/gm;
  const matches = [];
  let m;
  while ((m = headingRe.exec(text)) !== null) {
    matches.push({ index: m.index, hashes: m[1], heading: m[2].trim() });
  }
  let seq = 0;
  if (matches.length === 0) {
    return [{ id: segId(++seq), kind: 'paragraph', heading: '(untitled)', start: 0, end: text.length, wordCount: countWords(text) }];
  }
  const segments = [];
  if (matches[0].index > 0 && text.slice(0, matches[0].index).trim().length > 0) {
    segments.push({
      id: segId(++seq), kind: 'paragraph', heading: '(preamble)',
      start: 0, end: matches[0].index, wordCount: countWords(text.slice(0, matches[0].index)),
    });
  }
  matches.forEach((match, i) => {
    const start = match.index;
    const end = i + 1 < matches.length ? matches[i + 1].index : text.length;
    segments.push({
      id: segId(++seq),
      kind: match.hashes.length === 1 ? 'chapter' : 'scene',
      heading: match.heading,
      start,
      end,
      wordCount: countWords(text.slice(start, end)),
    });
  });
  return segments;
}

// ---------- retrospective evolution-lens anchors (#6445) ----------

/**
 * The reference set a Writers Room evolution-lens anchor resolves against: a
 * Map of `segmentId` -> that segment's prose, ready for
 * `evolutionEvidenceStatus` / `renderCharacterEvolutionForPrompt`.
 *
 * A Map rather than a Set of ids because a `seg-NNN` is POSITIONAL. The index
 * is rebuilt from scratch by every `saveDraftBody`, so inserting one chapter
 * heading renumbers every segment after it: the id `seg-003` survives the edit
 * while naming a different chapter. Resolving the id alone would therefore
 * report a lens stage as proven against prose it was never written for — the
 * exact "silently verified" failure epic #6418 forbids. Handing the passage
 * text in lets the shared leaf check the stage's `anchorQuote` and report
 * `stale` when the anchor has drifted.
 *
 * A stage with no quote gets the weaker existence check the other hosts get;
 * the editor asks for a quote, and the prompt block reports the resulting
 * status verbatim, so an unquoted anchor is never presented as more than it is.
 */
export function segmentEvidenceRefs(segmentIndex, text) {
  const body = typeof text === 'string' ? text : '';
  const segments = (Array.isArray(segmentIndex) ? segmentIndex : [])
    .filter((segment) => segment && typeof segment.id === 'string');
  // Sentinel, not an empty container: OMITTING the key means "not checked
  // here", which the shared leaf reports as `unverified`. An empty Map would
  // mean "checked, and nothing exists" and would condemn every authored anchor
  // as stale the moment a caller forgot to pass the index.
  if (!segments.length) return {};
  return {
    segmentIds: new Map(segments.map((segment) => [segment.id, body.slice(segment.start, segment.end)])),
  };
}

/**
 * Every authored evolution lens across a work's cast, as one compact prompt
 * block — or `null` when nobody has authored one, which is what keeps a work
 * with no lens byte-identical to its pre-#6445 analysis.
 *
 * The Writers Room companion to `renderCharacterEvolutionsForPrompt`
 * (`seriesCharacterArc.js`): same shared renderer, same stage vocabulary, same
 * `[stale]` / `[unverified]` annotations — only the reference set differs,
 * because this host anchors to manuscript segments instead of authored beats.
 * Nothing here promotes the work to a Pipeline series; it is a read over the
 * per-work cast bible and the draft body.
 */
export function renderWorkCharacterEvolutions(characters, { segmentIndex, text } = {}) {
  const refs = segmentEvidenceRefs(segmentIndex, text);
  return renderCharacterEvolutionListForPrompt(
    (Array.isArray(characters) ? characters : [])
      .map((character) => ({ characterName: character?.name, evolution: character?.evolution })),
    refs,
  );
}

// ---------- folder CRUD ----------

export async function listFolders() {
  return store().listFolders();
}

export async function createFolder({ name, parentId = null, sortOrder = 0 }) {
  if (!name || !name.trim()) throw badRequest('Folder name required');
  const folders = await store().listFolders();
  if (parentId && !folders.find((f) => f.id === parentId)) throw notFound('Parent folder');
  const folder = {
    id: `wr-folder-${randomUUID()}`,
    parentId,
    name: name.trim(),
    sortOrder,
    createdAt: nowIso(),
    updatedAt: nowIso(),
  };
  await store().writeFolder(folder);
  // Auto-subscribe every writersRoomFolders-enabled peer so brand-new folders
  // (and their later tombstones) propagate without waiting for a reconnect (#1645).
  autoSubscribeRecordToAllPeers(WRITERS_ROOM_FOLDER_KIND, folder.id).catch(() => {});
  return folder;
}

export async function deleteFolder(id) {
  const folders = await store().listFolders();
  if (!folders.find((f) => f.id === id)) throw notFound('Folder');
  const works = await listWorks();
  if (works.some((w) => w.folderId === id)) {
    throw badRequest('Folder is not empty — move or delete its works first');
  }
  if (folders.some((f) => f.parentId === id)) {
    throw badRequest('Folder has subfolders — delete or reparent them first');
  }
  await store().deleteFolder(id);
  // Push the tombstone so subscribed peers learn of the deletion (the LWW merge
  // never propagates a hard delete — an omitted record gets resurrected) (#1645).
  emitRecordDeleted(WRITERS_ROOM_FOLDER_KIND, id);
  return { ok: true };
}

// Conflict-restore entry point (#1645) for a body-less Writers Room record
// (folder / exercise): re-apply a journaled local snapshot after a sync LWW
// overwrite. Merges only the RESTORABLE_FIELDS the resolver passes, bumps
// updatedAt so the restore wins the next LWW + re-pushes (the exercise wire
// sanitizer prefers a stored updatedAt over its finishedAt/startedAt-derived
// key), and emits so subscribed peers converge. A missing/tombstoned record
// throws notFound (→ translateGone → ERR_TARGET_GONE in the resolver). Mirrors
// moodBoard's restoreBoard.
async function restoreBodylessRecord(id, patch, { read, write, kind, fields, label }) {
  const current = await read(id, { includeDeleted: false });
  if (!current) throw notFound(label);
  const next = { ...current };
  for (const key of fields) {
    if (patch[key] !== undefined) next[key] = patch[key];
  }
  next.updatedAt = nowIso();
  await write(next);
  emitRecordUpdated(kind, id);
  return next;
}

const FOLDER_RESTORABLE = ['name', 'parentId', 'sortOrder'];
export async function restoreFolder(id, patch) {
  return restoreBodylessRecord(id, patch, {
    read: (rid, opts) => store().readFolder(rid, opts),
    write: (f) => store().writeFolder(f),
    kind: WRITERS_ROOM_FOLDER_KIND, fields: FOLDER_RESTORABLE, label: 'Folder',
  });
}

// ---------- work CRUD ----------

// Manifest read/write go through the storage dispatcher (PG metadata, or the
// legacy on-disk JSON on the file escape hatch). The drafts dir is ensured on
// every save because the draft .md bodies are written there independently (the
// file backend also persists manifest.json into the work dir, and ensureDir is
// idempotent + cheap).
async function loadManifest(workId) {
  // Validate the work id (path-traversal guard) before it reaches the backend.
  wrWorkDir(workId);
  return store().readWork(workId);
}

// Announce a persisted work change to the per-record peer-sync pipeline (#1565)
// so any existing subscription pushes the new state (+ its draft-body manifest).
// Routed through the recordEvents subscription adapter (a no-op until peerSync
// registers it at boot) so this store doesn't import peerSync — peerSync
// statically imports mergeWorksFromSync from writersRoom/sync.js, so importing
// it back would close a load-order cycle. Mirrors creativeDirector/local.js.
//
// `announce: false` opts the hot-path live-mode usage-counter writes out of a
// push (they fire once per suggest call) — the bumped counter rides the next
// structural push, exactly as Creative Director's recordRun does NOT emit.
async function saveManifest(workId, manifest, { announce = true } = {}) {
  await ensureDir(`${wrWorkDir(workId)}/drafts`);
  await store().writeWork(manifest);
  if (announce) emitRecordUpdated(WRITERS_ROOM_WORK_KIND, workId);
}

// Lazy-import to break a circular dep (mediaCollections doesn't import us, but
// importing it at module-top would still be fine; the function-level import
// just keeps this helper self-contained next to its caller).
export async function ensureWorkMediaCollection(workId) {
  const manifest = await getWork(workId);
  const { getCollection, createCollection, ERR_NOT_FOUND } = await import('../mediaCollections.js');
  if (manifest.mediaCollectionId) {
    const existing = await getCollection(manifest.mediaCollectionId).catch((err) => {
      // The collection was deleted out-of-band — drop the stale id and recreate.
      if (err?.code === ERR_NOT_FOUND) return null;
      throw err;
    });
    if (existing) return existing;
  }
  const collection = await createCollection({
    name: `Writers Room: ${manifest.title}`.slice(0, 80),
    description: `Auto-generated images for "${manifest.title}"`,
    // Machine-provisioned bucket — this work's renders land here without the
    // user ever asking for a collection (#3311).
    source: 'auto',
  });
  await saveManifest(workId, { ...manifest, mediaCollectionId: collection.id, updatedAt: nowIso() });
  return collection;
}

function summarizeWork(manifest) {
  const activeDraft = (manifest.drafts || []).find((d) => d.id === manifest.activeDraftVersionId);
  return {
    id: manifest.id,
    folderId: manifest.folderId,
    title: manifest.title,
    kind: manifest.kind,
    status: manifest.status,
    activeDraftVersionId: manifest.activeDraftVersionId,
    wordCount: activeDraft?.wordCount ?? 0,
    draftCount: (manifest.drafts || []).length,
    pipelineSeriesId: manifest.pipelineSeriesId || null,
    pipelineIssueId: manifest.pipelineIssueId || null,
    createdAt: manifest.createdAt,
    updatedAt: manifest.updatedAt,
  };
}

export async function listWorks() {
  // The store returns full manifests (rebuilt with drafts[] on the PG backend),
  // dropping any work with a corrupted manifest on the file backend so one bad
  // work doesn't 500 the whole library.
  const manifests = await store().listWorks();
  return manifests
    .filter(Boolean)
    .map(summarizeWork)
    .sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''));
}

// Membership snapshots retain IDs only, never prose or draft histories. They are
// process-local and expire after five minutes (including after a server restart).
const workSnapshots = new Map();
const SNAPSHOT_TTL = 5 * 60 * 1000;
const MAX_SNAPSHOTS = 32;

export async function listWorksPage(query = {}) {
  const { limit, offset, cursor } = writersRoomWorksQuerySchema.parse(query);
  const now = Date.now();
  for (const [id, entry] of workSnapshots) if (entry.expires <= now) workSnapshots.delete(id);
  let snapshot;
  let position = offset;
  if (cursor) {
    const [id, index] = cursor.split('.');
    snapshot = workSnapshots.get(id);
    if (!snapshot) throw new ServerError('Library page expired. Restart the library to continue.', {
      status: 409, code: 'CURSOR_EXPIRED',
    });
    position = Number(index);
    if (!Number.isSafeInteger(position) || position > snapshot.ids.length) {
      throw new ServerError('Invalid library cursor', { status: 400, code: 'INVALID_CURSOR' });
    }
  } else {
    snapshot = { id: randomUUID(), ids: await store().listOrderedWorkIds(), expires: now + SNAPSHOT_TTL };
    while (workSnapshots.size >= MAX_SNAPSHOTS) workSnapshots.delete(workSnapshots.keys().next().value);
    workSnapshots.set(snapshot.id, snapshot);
  }
  const ids = snapshot.ids.slice(position, position + limit);
  const items = (await store().readWorksPage(ids)).map(summarizeWork);
  const next = position + ids.length;
  return { items, total: snapshot.ids.length, limit, offset: position,
    nextCursor: next < snapshot.ids.length ? `${snapshot.id}.${next}` : null };
}

/**
 * How many works listWorks() would return — without rebuilding a single
 * manifest (#2729). A `COUNT(*)` on PG; the shared live-set read on the file
 * backend. Tombstones are excluded on both, exactly as listWorks filters them.
 *
 * Use this for a tally (the Wordsmith skill's engagement score) so
 * `(await listWorks()).length` — two queries plus every work's drafts[] — never
 * has to run just to produce a number.
 */
export async function countWorks() {
  return store().countWorks();
}

export async function getWork(id) {
  const manifest = await loadManifest(id);
  if (!manifest) throw notFound('Work');
  return manifest;
}

async function readDraftFile(workId, draftId) {
  return readFile(wrDraftPath(workId, draftId), 'utf-8').catch((err) => {
    if (err.code === 'ENOENT') return '';
    throw err;
  });
}

export async function getWorkWithBody(id) {
  const manifest = await getWork(id);
  const activeId = manifest.activeDraftVersionId;
  if (!activeId) return { manifest, body: '' };
  return { manifest, body: await readDraftFile(id, activeId) };
}

export async function createWork({ folderId = null, title, kind = 'short-story' }) {
  if (!title || !title.trim()) throw badRequest('Work title required');
  if (!WORK_KINDS.includes(kind)) throw badRequest(`Invalid kind: ${kind}`);
  if (folderId) {
    const folders = await store().listFolders();
    if (!folders.find((f) => f.id === folderId)) throw notFound('Folder');
  }
  const id = `wr-work-${randomUUID()}`;
  const draftId = `wr-draft-${randomUUID()}`;
  const now = nowIso();
  const manifest = {
    id,
    folderId,
    title: title.trim(),
    kind,
    status: 'drafting',
    activeDraftVersionId: draftId,
    drafts: [
      {
        id: draftId,
        label: 'Draft 1',
        contentFile: `drafts/${draftId}.md`,
        contentHash: contentHash(''),
        wordCount: 0,
        segmentIndex: [],
        createdAt: now,
        createdFromVersionId: null,
      },
    ],
    createdAt: now,
    updatedAt: now,
  };
  // The empty first draft body and the manifest naming it are one backup-admitted
  // workflow (#9982): a snapshot never dumps a work whose draft file its copy missed.
  await withBackupAssetPublication(async () => {
    await ensureDir(`${wrWorkDir(id)}/drafts`);
    await atomicWrite(wrDraftPath(id, draftId), '');
    await saveManifest(id, manifest);
  });
  // Auto-subscribe every writersRoomWorks-enabled peer so brand-new works (and
  // their later tombstones) propagate without waiting for a reconnect (#1565).
  autoSubscribeRecordToAllPeers(WRITERS_ROOM_WORK_KIND, id).catch(() => {});
  return manifest;
}

// Default Phase 5 live-mode config. Stored on the manifest only once the user
// opts in; readers (the suggest path) fall back to this when the field is
// absent. `usage` is the server-tracked daily budget counter for text
// suggestions; `renderUsage` is the distinct counter for live render previews
// (renders cost materially more than text, so they get their own budget knob
// `dailyRenderBudget`). Neither counter is accepted from the client (updateWork
// strips both; only recordLiveModeUsage / recordLiveModeRenderUsage write them).
export const DEFAULT_LIVE_MODE = Object.freeze({
  enabled: false,
  debounceMs: 2500,
  dailyCallBudget: 100,
  dailyRenderBudget: 20,
  usage: Object.freeze({ date: null, count: 0 }),
  renderUsage: Object.freeze({ date: null, count: 0 }),
});

function resolveUsageCounter(stored) {
  return {
    date: typeof stored?.date === 'string' ? stored.date : null,
    count: Number.isInteger(stored?.count) ? stored.count : 0,
  };
}

export function resolveLiveMode(manifest) {
  const stored = manifest?.liveMode || {};
  return {
    enabled: stored.enabled === true,
    debounceMs: Number.isInteger(stored.debounceMs) ? stored.debounceMs : DEFAULT_LIVE_MODE.debounceMs,
    dailyCallBudget: Number.isInteger(stored.dailyCallBudget) ? stored.dailyCallBudget : DEFAULT_LIVE_MODE.dailyCallBudget,
    dailyRenderBudget: Number.isInteger(stored.dailyRenderBudget) ? stored.dailyRenderBudget : DEFAULT_LIVE_MODE.dailyRenderBudget,
    usage: resolveUsageCounter(stored.usage),
    renderUsage: resolveUsageCounter(stored.renderUsage),
  };
}

export async function updateWork(id, patch) {
  const manifest = await getWork(id);
  const allowed = ['title', 'folderId', 'kind', 'status', 'imageStyle'];
  const next = { ...manifest, updatedAt: nowIso() };
  for (const key of allowed) {
    if (patch[key] === undefined) continue;
    if (key === 'kind' && !WORK_KINDS.includes(patch.kind)) throw badRequest(`Invalid kind: ${patch.kind}`);
    if (key === 'status' && !WORK_STATUSES.includes(patch.status)) throw badRequest(`Invalid status: ${patch.status}`);
    next[key] = patch[key];
  }
  // liveMode is a partial merge (the UI PATCHes one knob at a time) onto the
  // resolved current config — and the client-supplied usage counters are
  // dropped so a crafted PATCH can't reset the server-side daily budgets. Only
  // the user-editable knobs flow through; both server-owned counters carry over.
  if (patch.liveMode !== undefined && patch.liveMode !== null) {
    const current = resolveLiveMode(manifest);
    const p = patch.liveMode;
    next.liveMode = {
      enabled: typeof p.enabled === 'boolean' ? p.enabled : current.enabled,
      debounceMs: Number.isInteger(p.debounceMs) ? p.debounceMs : current.debounceMs,
      dailyCallBudget: Number.isInteger(p.dailyCallBudget) ? p.dailyCallBudget : current.dailyCallBudget,
      dailyRenderBudget: Number.isInteger(p.dailyRenderBudget) ? p.dailyRenderBudget : current.dailyRenderBudget,
      usage: current.usage,
      renderUsage: current.renderUsage,
    };
  }
  // Voice exemplars / anti-exemplars (#2179 Writers Room parity). Sanitized
  // through the SAME helper the series style guide uses (drops empty passages,
  // trims to the char caps, caps the list at 3). Key present → replace (an
  // explicit `[]` clears); key absent → carry the stored value untouched. These
  // are consumed by the live-continuation prompt and the Phase 9 polish loop's
  // revision brief so a freeform work anchors its voice the same way a series
  // does.
  if (patch.voiceExemplars !== undefined) {
    next.voiceExemplars = sanitizeVoiceExemplars(patch.voiceExemplars);
  }
  if (patch.voiceAntiExemplars !== undefined) {
    next.voiceAntiExemplars = sanitizeVoiceExemplars(patch.voiceAntiExemplars);
  }
  // Trim title and reject if it becomes empty after trim — keeps parity with
  // createWork's "title required" guard so a PATCH can't blank a title out.
  if (patch.title !== undefined) {
    const trimmed = String(patch.title ?? '').trim();
    if (!trimmed) throw badRequest('Work title required');
    next.title = trimmed;
  }
  // folderId can be set to a real folder id or to null (unfile the work).
  // Anything else would orphan it from the library tree.
  if (patch.folderId !== undefined && patch.folderId !== null) {
    const folders = await store().listFolders();
    if (!folders.find((f) => f.id === patch.folderId)) throw notFound('Folder');
  }
  await saveManifest(id, next);
  return next;
}

/**
 * Resolve a work's voice exemplars into the rendered "MATCH this voice / NEVER
 * drift toward this" prompt block (#2179 Writers Room parity), or `''` when the
 * work carries no passages. Re-sanitizes on read (defense against a hand-edited
 * manifest) and delegates to the shared styleGuide renderer so the block is
 * byte-identical to the series pipeline's. Consumed by the live-continuation
 * suggest path (liveDirector.js) and the Phase 9 polish loop (polish.js).
 */
export function renderWorkVoiceGuide(manifest) {
  return renderVoiceExemplars({
    voiceExemplars: sanitizeVoiceExemplars(manifest?.voiceExemplars),
    voiceAntiExemplars: sanitizeVoiceExemplars(manifest?.voiceAntiExemplars),
  });
}

/**
 * Bidirectional bridge link: record that this work was promoted to a pipeline
 * series + first issue. Set once by `promoteToPipeline`; the WR side reads it
 * to render the "Open in pipeline" CTA on the work detail page. Distinct from
 * `updateWork` because the link isn't user-editable. Pass `null` to unlink.
 */
export async function linkToPipeline(id, { seriesId = null, issueId = null } = {}) {
  const manifest = await getWork(id);
  const next = {
    ...manifest,
    pipelineSeriesId: seriesId ? String(seriesId).slice(0, 64) : null,
    pipelineIssueId: issueId ? String(issueId).slice(0, 64) : null,
    updatedAt: nowIso(),
  };
  await saveManifest(id, next);
  return next;
}

/**
 * Bidirectional bridge link: record that this work seeded a Creative Director
 * project (Phase 5 CD-bridge slice). Set once by liveDirector.sendToCreativeDirector;
 * the WR side reads it to render the "Open in Creative Director" CTA on the work
 * detail page. Distinct from `updateWork` because the link isn't user-editable
 * (the allow-list in updateWork excludes it, so a crafted PATCH can't set it).
 * Mirrors `linkToPipeline`. Pass `null` to unlink.
 */
export async function linkToCreativeDirector(id, { projectId = null } = {}) {
  const manifest = await getWork(id);
  const next = {
    ...manifest,
    cdProjectId: projectId ? String(projectId).slice(0, 64) : null,
    updatedAt: nowIso(),
  };
  await saveManifest(id, next);
  return next;
}

// UTC day key (YYYY-MM-DD) for the daily budget window. UTC (not local) so the
// reset boundary is deterministic across machines a single user federates.
// Exported so the live-director's pre-call budget check compares against the
// same boundary recordLiveModeUsage rolls over on.
export function utcDayKey() {
  return nowIso().slice(0, 10);
}

/**
 * Bump the live-mode daily usage counter for a work, rolling over to a fresh
 * count when the stored date is not today (UTC). Set once per successful
 * suggest call by the live-director path — distinct from `updateWork` because
 * the counter is server-owned, not user-editable. Returns the resolved live
 * config with the new usage so the caller can echo remaining budget.
 */
export async function recordLiveModeUsage(id) {
  const manifest = await getWork(id);
  const live = resolveLiveMode(manifest);
  const today = utcDayKey();
  const count = live.usage.date === today ? live.usage.count + 1 : 1;
  const nextLive = { ...live, usage: { date: today, count } };
  // Do NOT bump updatedAt: this counter is a local-only daily budget (never
  // announced, #1565). updatedAt is the federation LWW key, so advancing it here
  // would let a local counter bump on one peer win LWW over a real manuscript
  // edit pushed from another — silently dropping the edit. Preserving updatedAt
  // keeps the counter local without disturbing the merge order.
  await saveManifest(id, { ...manifest, liveMode: nextLive }, { announce: false });
  return nextLive;
}

/**
 * Bump the live-mode daily RENDER usage counter for a work, rolling over to a
 * fresh count on a new UTC day. Distinct from `recordLiveModeUsage` because
 * render previews carry a different cost profile and their own budget knob
 * (`dailyRenderBudget`). Set once per reserved render-preview by the
 * live-director path. Returns the resolved live config with the new
 * `renderUsage` so the caller can echo remaining render budget.
 */
export async function recordLiveModeRenderUsage(id) {
  const manifest = await getWork(id);
  const live = resolveLiveMode(manifest);
  const today = utcDayKey();
  const count = live.renderUsage.date === today ? live.renderUsage.count + 1 : 1;
  const nextLive = { ...live, renderUsage: { date: today, count } };
  // Same as recordLiveModeUsage above: a local-only render-budget bump must not
  // advance the federation LWW key (updatedAt) and risk dropping a peer's edit.
  await saveManifest(id, { ...manifest, liveMode: nextLive }, { announce: false });
  return nextLive;
}

export async function deleteWork(id) {
  // 404 the caller if the manifest is missing; rm() with force:true would
  // silently succeed on a non-existent dir and the user gets no signal.
  // Tolerate CORRUPTED_MANIFEST so a user can recover from on-disk corruption
  // by deleting the work via the API/UI instead of resorting to `rm -rf`.
  let corrupt = false;
  await getWork(id).catch((err) => {
    if (err?.code === 'CORRUPTED_MANIFEST') {
      console.warn(`⚠️  wr: deleting work ${id} despite corrupted manifest`);
      corrupt = true;
      return;
    }
    throw err;
  });
  if (corrupt) {
    // A tombstone needs a parseable manifest to soft-delete + federate, but a
    // corrupt manifest can't be sanitized for the wire anyway (sanitizeWorkForSync
    // would drop it), so it was never syncable. Hard-remove the dir so the API's
    // "delete a broken work to recover" path still works (the soft-delete store
    // call would otherwise no-op on the unreadable manifest and strand it).
    await withBackupAssetPublication(() => rmGuarded(wrWorkDir(id), { recursive: true, force: true }));
    return { ok: true };
  }
  // Soft-delete tombstone (#1565) so the deletion federates and an out-of-date
  // peer can't resurrect the work via the LWW merge. The work row/manifest + its
  // draft rows + the on-disk .md bodies all stay until tombstone GC hard-prunes
  // them (sync.js pruneTombstonedWorks). The record drops out of every user-facing
  // read immediately (readWork/listWorks filter `deleted`).
  await store().deleteWork(id);
  // Push the tombstone to subscribed peers immediately.
  emitRecordDeleted(WRITERS_ROOM_WORK_KIND, id);
  return { ok: true };
}

// ---------- draft body / version snapshots ----------

function buildDraftMeta(text, base = {}) {
  return {
    ...base,
    contentHash: contentHash(text),
    wordCount: countWords(text),
    segmentIndex: buildSegmentIndex(text),
  };
}

// The draft body replaces its .md in place and the manifest row records its new
// hash, word count and segment index, so the pair is one backup-admitted workflow
// (#9982): a cut never copies the old prose beside a row that describes the new.
export function saveDraftBody(workId, body, { referencedIngredientIds } = {}) {
  return withBackupAssetPublication(async () => {
    const manifest = await getWork(workId);
    const activeId = manifest.activeDraftVersionId;
    if (!activeId) throw badRequest('Work has no active draft');
    const text = String(body ?? '');
    await atomicWrite(wrDraftPath(workId, activeId), text);
    const draftIdx = manifest.drafts.findIndex((d) => d.id === activeId);
    if (draftIdx < 0) throw notFound('Active draft');
    const meta = buildDraftMeta(text, manifest.drafts[draftIdx]);
    // Distinguish "caller omitted the field" (preserve the existing snapshot of
    // referenced ids) from "caller passed an empty array" (the prose no longer
    // mentions any linked ingredient — clear it). An absent field must NOT wipe
    // a previously-computed reference list.
    if (Array.isArray(referencedIngredientIds)) {
      meta.referencedIngredientIds = referencedIngredientIds;
    }
    manifest.drafts[draftIdx] = meta;
    manifest.updatedAt = nowIso();
    await saveManifest(workId, manifest);
    console.log(`📝 wr: saved draft ${activeId.slice(0, 14)}… (${manifest.drafts[draftIdx].wordCount} words)`);
    return { manifest, body: text };
  });
}

// The new version's body file and the manifest row that adds it are one
// backup-admitted workflow (#9982).
export function snapshotDraft(workId, { label } = {}) {
  return withBackupAssetPublication(async () => {
    const { manifest, body } = await getWorkWithBody(workId);
    const newDraftId = `wr-draft-${randomUUID()}`;
    const fromId = manifest.activeDraftVersionId;
    const fromDraft = manifest.drafts.find((d) => d.id === fromId);
    const draftLabel = label || `Draft ${manifest.drafts.length + 1}`;
    await atomicWrite(wrDraftPath(workId, newDraftId), body);
    // The new draft copies the source's body verbatim, so carry its referenced
    // ingredient ids forward — otherwise the freshly-snapshotted version would
    // render no chips (despite identical prose) until the next save re-scans.
    manifest.drafts.push(buildDraftMeta(body, {
      id: newDraftId,
      label: draftLabel,
      contentFile: `drafts/${newDraftId}.md`,
      createdAt: nowIso(),
      createdFromVersionId: fromId,
      ...(Array.isArray(fromDraft?.referencedIngredientIds)
        ? { referencedIngredientIds: fromDraft.referencedIngredientIds }
        : {}),
    }));
    manifest.activeDraftVersionId = newDraftId;
    manifest.updatedAt = nowIso();
    await saveManifest(workId, manifest);
    console.log(`📚 wr: snapshot ${draftLabel} for ${manifest.title}`);
    return manifest;
  });
}

export async function setActiveDraft(workId, draftId) {
  const manifest = await getWork(workId);
  if (!manifest.drafts.find((d) => d.id === draftId)) throw notFound('Draft version');
  manifest.activeDraftVersionId = draftId;
  manifest.updatedAt = nowIso();
  await saveManifest(workId, manifest);
  return manifest;
}

export async function getDraftBody(workId, draftId) {
  const manifest = await getWork(workId);
  if (!manifest.drafts.find((d) => d.id === draftId)) throw notFound('Draft version');
  return readDraftFile(workId, draftId);
}

// ---------- exercise sessions ----------

export async function listExercises({ workId } = {}) {
  const all = await store().listExercises();
  const filtered = workId ? all.filter((e) => e.workId === workId) : all;
  return filtered.sort((a, b) => (b.startedAt || '').localeCompare(a.startedAt || ''));
}

function settled(exercise) {
  return exercise.status === 'finished' || exercise.status === 'discarded';
}

export async function createExercise({ workId = null, prompt = '', durationSeconds = 600, startingWords = 0 }) {
  if (workId) await getWork(workId); // 404 if missing
  const exercise = {
    id: `wr-ex-${randomUUID()}`,
    workId,
    prompt: String(prompt || '').trim(),
    durationSeconds: Math.max(60, Math.min(durationSeconds, 60 * 60)),
    startingWords,
    endingWords: null,
    wordsAdded: null,
    appendedText: null,
    status: 'running',
    startedAt: nowIso(),
    finishedAt: null,
    updatedAt: nowIso(),
  };
  await store().writeExercise(exercise);
  // Auto-subscribe every writersRoomExercises-enabled peer so brand-new sprints
  // propagate; later finish/discard transitions ride emitRecordUpdated (#1645).
  autoSubscribeRecordToAllPeers(WRITERS_ROOM_EXERCISE_KIND, exercise.id).catch(() => {});
  return exercise;
}

export async function finishExercise(id, { endingWords, appendedText = null } = {}) {
  const all = await store().listExercises();
  const existing = all.find((e) => e.id === id);
  if (!existing) throw notFound('Exercise');
  if (settled(existing)) throw badRequest('Exercise is already settled');
  // Default missing endingWords to startingWords so wordsAdded never goes
  // negative when the caller forgets to send it; clamp the delta as a final
  // backstop for the case where the user backspaces past their starting count.
  const startingWords = existing.startingWords || 0;
  const resolvedEnding = endingWords ?? startingWords;
  const wordsAdded = Math.max(0, resolvedEnding - startingWords);
  const now = nowIso();
  const finished = {
    ...existing,
    endingWords: resolvedEnding,
    wordsAdded,
    appendedText: appendedText ?? null,
    status: 'finished',
    finishedAt: now,
    updatedAt: now,
  };
  await store().writeExercise(finished);
  // The settle transition stamps a fresh updatedAt (the LWW key) — push it so
  // subscribed peers converge on the finished state. updatedAt must be bumped
  // explicitly (not left to the finishedAt-derived fallback): a sync-seeded
  // exercise already carries a stored updatedAt the sanitizer would otherwise
  // prefer over the new finishedAt, so the finish wouldn't advance the key (#1645).
  emitRecordUpdated(WRITERS_ROOM_EXERCISE_KIND, id);
  return finished;
}

export async function promoteExercise(id) {
  const all = await store().listExercises();
  const existing = all.find((exercise) => exercise.id === id);
  if (!existing) throw notFound('Exercise');
  if (existing.promotedAt) throw badRequest('Exercise already promoted');
  if (existing.status !== 'finished') throw badRequest('Exercise must be finished before promotion');
  if (!existing.workId) throw badRequest('Exercise is not linked to a work');
  const text = typeof existing.appendedText === 'string' ? existing.appendedText.trim() : '';
  if (!text) throw badRequest('Exercise has no text to promote');

  const { body } = await getWorkWithBody(existing.workId);
  const nextBody = body.trimEnd() === '' ? text : `${body.trimEnd()}\n\n${text}\n`;
  const { manifest: updatedManifest } = await saveDraftBody(existing.workId, nextBody);
  const promoted = {
    ...existing,
    promotedAt: nowIso(),
    promotedDraftVersionId: updatedManifest.activeDraftVersionId,
    updatedAt: nowIso(),
  };
  await store().writeExercise(promoted);
  emitRecordUpdated(WRITERS_ROOM_EXERCISE_KIND, id);
  return { exercise: promoted, work: { ...updatedManifest, activeDraftBody: nextBody } };
}

export async function discardExercise(id) {
  const all = await store().listExercises();
  const existing = all.find((e) => e.id === id);
  if (!existing) throw notFound('Exercise');
  if (settled(existing)) throw badRequest('Exercise is already settled');
  const now = nowIso();
  const discarded = { ...existing, status: 'discarded', finishedAt: now, updatedAt: now };
  await store().writeExercise(discarded);
  emitRecordUpdated(WRITERS_ROOM_EXERCISE_KIND, id);
  return discarded;
}

// Conflict-restore for an exercise sprint — see restoreBodylessRecord above.
const EXERCISE_RESTORABLE = ['workId', 'prompt', 'durationSeconds', 'startingWords', 'endingWords', 'wordsAdded', 'appendedText', 'status', 'finishedAt', 'promotedAt', 'promotedDraftVersionId'];
export async function restoreExercise(id, patch) {
  return restoreBodylessRecord(id, patch, {
    read: (rid, opts) => store().readExercise(rid, opts),
    write: (e) => store().writeExercise(e),
    kind: WRITERS_ROOM_EXERCISE_KIND, fields: EXERCISE_RESTORABLE, label: 'Exercise',
  });
}