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

15.9 KB
Raw Blame
/**
 * Resolve entries in the non-blocking conflict journal (server/lib/conflictJournal.js).
 *
 * Each entry archives a local version that LWW overwrote. Resolution:
 *   - restore-all  — re-apply the archived local snapshot's restorable fields as
 *                    a fresh edit (bumped updatedAt) so it wins LWW and
 *                    re-propagates to peers.
 *   - merge-fields — overlay only the chosen fields from the snapshot onto the
 *                    CURRENT live record (it may have moved since detection).
 *   - discard      — keep the current record; just mark the entry resolved.
 *
 * Writes ALWAYS go through the normal `update*` service path (never the record
 * file directly) so updatedAt bumps and the change propagates via the existing
 * push pipeline.
 *
 * NOTE — restore-all is a FAITHFUL replace of the restorable fields, matching
 * the UI promise ("restore your whole version"). Most restorable fields already
 * patch wholesale through `update*`; the one exception is universe `categories`,
 * which `updateUniverse` normally unions per-key (so a partial PATCH of one
 * category can't wipe the others). restore-all passes `{ replaceCategories: true }`
 * so the archived snapshot's category map replaces the live one wholesale — a
 * category the live record gained since the conflict (e.g. one the user kept
 * after the LWW overwrite) is dropped, because "my whole version" didn't have it.
 *
 * merge-fields stays ADDITIVE: it overlays only the chosen fields onto the
 * CURRENT record, so a selected `categories` field unions per-key (the default
 * `update*` semantics) rather than replacing — you're merging your version of
 * that field in, not reverting the record to the snapshot.
 */

import { existsSync } from 'fs';
import { isSafeRecordId } from '../lib/validation.js';
import { ABSENT_MEANS_FALSE_FIELDS, conflictJournalStore, RESTORABLE_FIELDS } from '../lib/conflictJournal.js';
import { updateUniverse, ERR_NOT_FOUND as UNIVERSE_NOT_FOUND } from './universeBuilder.js';
import { updateSeries, ERR_NOT_FOUND as SERIES_NOT_FOUND } from './pipeline/series.js';
import { updateCollection, getCollection, ERR_NOT_FOUND as COLLECTION_NOT_FOUND } from './mediaCollections.js';
import { updateIssue, ERR_NOT_FOUND as ISSUE_NOT_FOUND } from './pipeline/issues.js';
import { updateProject } from './creativeDirector/local.js';
import { updateProject as updateMusicVideoProject } from './musicVideo/projects.js';
import { restoreBoard } from './moodBoard/index.js';
import { updateWork, restoreFolder, restoreExercise } from './writersRoom/local.js';
import { restoreCommissionFeedback } from './creativeCommissions/feedbackStore.js';
import { restoreCommission } from './creativeCommissions/store.js';
import { restoreDeck } from './decks.js';
import { restoreStoryboard } from './storyboards/index.js';
import { restoreLoom } from './fableLoom/index.js';
import { codedError } from '../lib/codedError.js';

export const ERR_NOT_FOUND = 'CONFLICT_JOURNAL_NOT_FOUND';
export const ERR_VALIDATION = 'CONFLICT_JOURNAL_VALIDATION';
// The conflict entry exists but the record it targets was tombstoned between
// archive time and resolution — distinct from ERR_NOT_FOUND (the entry itself).
export const ERR_TARGET_GONE = 'CONFLICT_TARGET_GONE';

// RESTORABLE_FIELDS (the user-authored content fields a restore/merge may write
// per kind; id/createdAt/server-owned fields are never overlaid) is owned by
// conflictJournal.js so diffSummary and this validator stay in lockstep.

// `kind` is needed for ABSENT_MEANS_FALSE_FIELDS: a snapshot field that is
// only persisted when true (universe `factual`) is simply ABSENT when false,
// so an `in` check alone would drop it and make the clear-direction restore a
// silent no-op. Filling the explicit `false` restores it faithfully; the
// record sanitizer drops that back to absent on write.
const pick = (obj, fields, kind) => {
  const falseWhenAbsent = ABSENT_MEANS_FALSE_FIELDS[kind] || [];
  const out = {};
  for (const f of fields) {
    if (obj && f in obj) out[f] = obj[f];
    else if (falseWhenAbsent.includes(f)) out[f] = false;
  }
  return out;
};

const store = () => conflictJournalStore();

export async function listConflicts({ status = null } = {}) {
  const all = await store().loadAll();
  const filtered = status ? all.filter((e) => e.status === status) : all;
  return [...filtered].sort((a, b) => (b.detectedAt || '').localeCompare(a.detectedAt || ''));
}

export async function getConflict(id) {
  const entry = await store().loadOne(id);
  if (!entry) throw codedError(`Conflict entry not found: ${id}`, ERR_NOT_FOUND);
  return entry;
}

// Apply a content patch through the right service's normal update path.
// `replace` (restore-all only) makes per-key-merged fields replace wholesale —
// currently just universe `categories` (every other restorable field already
// patches wholesale through its service).
async function applyToRecord(kind, recordId, patch, { replace = false } = {}) {
  // The target record may have been tombstoned between conflict-archive time and
  // resolution. Translate the services' not-found codes into ERR_TARGET_GONE so
  // the route maps it to a clean 409 ("discard the entry") instead of a 500.
  const translateGone = (err) => {
    if (err?.code === UNIVERSE_NOT_FOUND || err?.code === SERIES_NOT_FOUND
        || err?.code === COLLECTION_NOT_FOUND || err?.code === ISSUE_NOT_FOUND
        // Creative Director's updateProject throws a generic ServerError
        // 'NOT_FOUND' (no module-specific export) when the row is missing OR
        // tombstoned — both mean the conflict target is gone.
        || err?.code === 'NOT_FOUND') {
      throw codedError(`The ${kind} this conflict targets no longer exists — discard the entry.`, ERR_TARGET_GONE);
    }
    throw err;
  };
  if (kind === 'universe') {
    // Mutator form bypasses the literal-patch reference-sheet preservation
    // guard — the restored snapshot is the trusted writer here. `replace`
    // (restore-all) swaps the additive per-key categories merge for a wholesale
    // replace so the restore is faithful to the snapshot.
    await updateUniverse(recordId, () => patch, { replaceCategories: replace }).catch(translateGone);
  } else if (kind === 'series') {
    await updateSeries(recordId, patch).catch(translateGone);
  } else if (kind === 'mediaCollection') {
    // A linked collection (universeId/seriesId set) locks its `name` to the
    // owner record — updateCollection rejects a name change, and a name
    // "conflict" on such a collection is really an owner-rename cascade
    // artifact (the universe/series conflict is journaled separately). Drop
    // `name` from the patch for a linked collection so restore still applies
    // the freely-editable scalars (description, coverKey) instead of 500ing.
    // A standalone collection restores all three.
    const cur = await getCollection(recordId, { includeDeleted: true }).catch(translateGone);
    const { name: _lockedName, ...withoutName } = patch;
    const effective = (cur?.universeId || cur?.seriesId) ? withoutName : patch;
    if (Object.keys(effective).length > 0) await updateCollection(recordId, effective).catch(translateGone);
  } else if (kind === 'issue') {
    // updateIssue merges `stages` per-key (mergeIssuePatch), but unlike universe
    // categories' OPEN custom-key set, `sanitizeStages` seeds a CLOSED, fixed
    // stage-id set with complete field shapes — so the archived snapshot always
    // carries every stage (and every content sub-field). The per-key overlay
    // therefore covers them all and the snapshot's value (even an empty one)
    // wins, making restore-all equivalent to a wholesale replace WITHOUT a
    // replace flag: a stage value the live record gained since the conflict is
    // overwritten. (`runHistory` is intentionally recomputed, not rolled back —
    // it tracks the live undo-history, which a faithful restore should preserve.)
    await updateIssue(recordId, patch).catch(translateGone);
  } else if (kind === 'creativeDirectorProject') {
    // updateProject does a wholesale spread (`{ ...project, ...patch }`), so the
    // restorable scalars + treatment in the snapshot patch overwrite the live
    // values faithfully — restore-all and merge-fields both apply through the
    // same path. updateProject validates `status` and rejects a tombstoned row
    // (404 → translateGone → ERR_TARGET_GONE).
    await updateProject(recordId, patch).catch(translateGone);
  } else if (kind === 'moodBoard') {
    // restoreBoard applies the snapshot's name/description/items wholesale (via
    // applyBoardRestore — the route's applyBoardPatch only touches name/description,
    // so this dedicated path is what brings items[] back), so restore-all and
    // merge-fields both apply faithfully through the same call. It validates +
    // rejects a tombstoned row (404 → translateGone → ERR_TARGET_GONE).
    await restoreBoard(recordId, patch).catch(translateGone);
  } else if (kind === 'musicVideoProject') {
    // updateProject does a wholesale spread (applyProjectPatch → touch), so the
    // restorable scalars + scenes[] in the snapshot patch overwrite the live
    // values faithfully — restore-all and merge-fields both apply through the
    // same path. It validates `status` and rejects a missing/tombstoned row with
    // the generic ServerError 'NOT_FOUND' (→ translateGone → ERR_TARGET_GONE).
    await updateMusicVideoProject(recordId, patch).catch(translateGone);
  } else if (['writersRoomCharacters', 'writersRoomPlaces', 'writersRoomObjects'].includes(kind)) {
    const { restoreWorkBible, BIBLE_CONFLICT_KINDS } = await import('./writersRoom/bibleSync.js');
    const bibleKind = Object.keys(BIBLE_CONFLICT_KINDS).find((key) => BIBLE_CONFLICT_KINDS[key] === kind);
    await restoreWorkBible(recordId, bibleKind, patch).catch(translateGone);
  } else if (kind === 'writersRoomWork') {
    // updateWork applies the snapshot's title/kind/status/folderId/imageStyle/
    // liveMode (the RESTORABLE_FIELDS set) through its allow-list + the liveMode
    // partial merge, so restore-all and merge-fields both apply faithfully. It
    // throws the generic ServerError 'NOT_FOUND' for a missing/tombstoned work
    // (caught by translateGone → ERR_TARGET_GONE). The draft-version structure
    // and prose bodies are not restorable here (they're file-primary + lineage-
    // managed) — RESTORABLE_FIELDS.writersRoomWork omits them.
    await updateWork(recordId, patch).catch(translateGone);
  } else if (kind === 'writersRoomFolder') {
    // restoreFolder merges the snapshot's name/parentId/sortOrder (the
    // RESTORABLE_FIELDS set) and bumps updatedAt so the restore wins the next LWW
    // and re-pushes. A missing/tombstoned folder 404s (→ translateGone →
    // ERR_TARGET_GONE). Body-less, so there are no file-primary structures to restore.
    await restoreFolder(recordId, patch).catch(translateGone);
  } else if (kind === 'writersRoomExercise') {
    // restoreExercise merges the snapshot's sprint fields (appendedText + config)
    // and stamps updatedAt so the restored sprint wins the next LWW. A
    // missing/tombstoned exercise 404s (→ ERR_TARGET_GONE).
    await restoreExercise(recordId, patch).catch(translateGone);
  } else if (kind === 'commissionFeedback') {
    // restoreCommissionFeedback merges the snapshot's rating/note/tags, un-tombstones,
    // and bumps updatedAt so the restore wins the next LWW and re-pushes. It returns
    // null (not throw) for a missing record — translate that to ERR_TARGET_GONE so
    // the route serves a clean 409 (#2686).
    const restored = await restoreCommissionFeedback(recordId, patch).catch(translateGone);
    if (!restored) throw codedError(`The ${kind} this conflict targets no longer exists — discard the entry.`, ERR_TARGET_GONE);
  } else if (kind === 'creativeCommission') {
    // restoreCommission merges the snapshot's brief fields, un-tombstones, and
    // bumps updatedAt so the restore wins the next LWW. Machine-local schedule/
    // runs/assignment are kept as-is. Returns null for a missing record (#2686).
    const restored = await restoreCommission(recordId, patch).catch(translateGone);
    if (!restored) throw codedError(`The ${kind} this conflict targets no longer exists — discard the entry.`, ERR_TARGET_GONE);
  } else if (kind === 'deck') {
    // restoreDeck merges the snapshot's style-guide/identity fields, un-tombstones,
    // and bumps updatedAt so the restore wins the next LWW and re-pushes. Returns
    // null for a deck already hard-pruned by the tombstone sweep (→ ERR_TARGET_GONE).
    const restored = await restoreDeck(recordId, patch).catch(translateGone);
    if (!restored) throw codedError(`The ${kind} this conflict targets no longer exists — discard the entry.`, ERR_TARGET_GONE);
  } else if (kind === 'storyboard') {
    // restoreStoryboard overlays the authored fields, un-tombstones, and bumps
    // updatedAt so the restore wins the next LWW. Null = already hard-pruned.
    const restored = await restoreStoryboard(recordId, patch).catch(translateGone);
    if (!restored) throw codedError(`The ${kind} this conflict targets no longer exists — discard the entry.`, ERR_TARGET_GONE);
  } else if (kind === 'fableLoom') {
    // Restore the authored story graph and playback settings through the normal
    // loom mutation path so the edit is sanitized, timestamped, and re-pushed.
    await restoreLoom(recordId, patch).catch(translateGone);
  } else {
    throw codedError(`Unsupported conflict kind: ${kind}`, ERR_VALIDATION);
  }
}

/**
 * Resolve a conflict entry. `action` ∈ restore-all | merge-fields | discard.
 * `fields` (merge-fields only) selects which snapshot fields to overlay.
 */
export async function resolveConflict(id, { action, fields = [] } = {}) {
  const entry = await getConflict(id);
  if (entry.status !== 'pending') throw codedError(`Conflict already ${entry.status}`, ERR_VALIDATION);
  const allowed = RESTORABLE_FIELDS[entry.recordKind];
  if (!allowed) throw codedError(`Unsupported conflict kind: ${entry.recordKind}`, ERR_VALIDATION);
  const snapshot = entry.localSnapshot || {};

  if (action === 'restore-all') {
    // Faithful restore: replace the keyed fields (universe categories) wholesale.
    await applyToRecord(entry.recordKind, entry.recordId, pick(snapshot, allowed, entry.recordKind), { replace: true });
  } else if (action === 'merge-fields') {
    if (!Array.isArray(fields) || fields.length === 0) {
      throw codedError('merge-fields requires a non-empty `fields` array', ERR_VALIDATION);
    }
    const invalid = fields.filter((f) => !allowed.includes(f));
    if (invalid.length) throw codedError(`Not restorable: ${invalid.join(', ')}`, ERR_VALIDATION);
    await applyToRecord(entry.recordKind, entry.recordId, pick(snapshot, fields, entry.recordKind));
  } else if (action !== 'discard') {
    throw codedError(`Unknown resolution action: ${action}`, ERR_VALIDATION);
  }

  const resolved = { ...entry, status: 'resolved', resolution: action, resolvedAt: new Date().toISOString() };
  await store().saveOne(id, resolved);
  console.log(`🪢 conflictJournal: resolved ${id.slice(0, 12)} via ${action}`);
  return resolved;
}

/** Permanently remove a journal entry (the "dismiss / clear" action). */
export async function deleteConflict(id) {
  // Validate the id BEFORE interpolating it into recordDir(id) — getConflict()
  // (which we no longer call) used to enforce this via the store's isValidId;
  // an unguarded id would make recordDir a path-traversal existence oracle.
  if (!isSafeRecordId(id)) throw codedError(`Conflict entry not found: ${id}`, ERR_NOT_FOUND);
  // Don't gate on getConflict() — it requires a successful parse, so a corrupt
  // journal entry would 404 here and become permanently undeletable. Check raw
  // directory existence instead, then hard-delete (deleteOne is idempotent).
  if (!existsSync(store().recordDir(id))) throw codedError(`Conflict entry not found: ${id}`, ERR_NOT_FOUND);
  await store().deleteOne(id);
  return { id, deleted: true };
}