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

14.1 KB
Raw Blame
/**
 * Writers Room — Phase 4 synchronized prose/script/media review surface.
 *
 * This is a *read-model*: it derives the prose↔script↔media mapping from data
 * that already exists immutably elsewhere rather than persisting a fourth copy.
 *   - prose segments  ← the active draft's `segmentIndex` (built on every save)
 *   - script scenes   ← the `script` analysis snapshot's `result.scenes[]`,
 *                       each carrying `sourceSegmentIds` back to prose
 *   - media refs      ← the same snapshot's `sceneImages` map (scene → image)
 *   - cast integrity  ← the per-work character bible, measured by the shared
 *                       characterIntegrity.js contract and joined to the
 *                       scenes that stage each character (#6415/#6417)
 *
 * Deriving on read (instead of a persisted render-plan store) means there is no
 * second source of truth to keep in sync, and staleness falls straight out of
 * the analysis snapshot's pinned `sourceContentHash` vs. the live draft hash —
 * the same contentHash machinery the rest of Writers Room already uses.
 *
 * The mapping model from docs/features/writers-room.md ("Synchronized Review
 * Surface") is expressed *relationally* across the three pane arrays — every
 * prose segment lists the script scenes mapped to it; every scene lists the
 * prose segments it adapts and the media rendered from it; every media item
 * carries its full provenance back to scene + prose. There is intentionally no
 * separate `mappings[]` array — that would be a redundant denormalization of
 * exactly these cross-references.
 */

import { buildCastIntegrityReport } from '../../lib/characterIntegrity.js';
import { castIntegrityPassed } from '../../lib/characterIntegrityVocabulary.js';
import { normalizeBibleName } from '../../lib/storyBible.js';
import { getWorkWithBody } from './local.js';
import { getAnalysis } from './evaluator.js';
import { listCharacters } from './characters.js';
import { assertValidWorkId } from './_shared.js';

const SCRIPT_ANALYSIS_ID = 'script';

// Pull the active draft's metadata (contentHash, segmentIndex) out of the
// manifest. Returns a stable empty shape when there's no active draft yet so
// callers never have to null-check the index.
function activeDraftMeta(manifest) {
  const activeId = manifest?.activeDraftVersionId || null;
  const draft = (manifest?.drafts || []).find((d) => d.id === activeId) || null;
  return {
    draftVersionId: activeId,
    contentHash: draft?.contentHash || null,
    segmentIndex: Array.isArray(draft?.segmentIndex) ? draft.segmentIndex : [],
  };
}

// One media item per rendered scene image. Provenance points back to the scene
// it was rendered from and (transitively) the prose segments that scene adapts.
// An image whose `sceneId` no longer matches any scene (the script was
// re-extracted with different ids after the render) is surfaced as an orphan —
// honest "source scene no longer in script" rather than silently dropped.
function buildMediaItem(sceneId, img, sceneById) {
  const scene = sceneById.get(sceneId) || null;
  return {
    sceneId,
    sceneHeading: scene?.heading || null,
    orphan: !scene,
    kind: 'image',
    ref: img.filename,
    jobId: img.jobId || null,
    prompt: img.prompt || null,
    generatedAt: img.generatedAt || null,
    proseSegmentIds: scene ? scene.proseSegmentIds : [],
  };
}

/** normalized name/alias → character id, so a scene's cast names resolve to bible ids. */
function castNameIndex(characters) {
  const index = new Map();
  for (const entry of characters) {
    if (!entry?.id) continue;
    const names = [entry.name, ...(Array.isArray(entry.aliases) ? entry.aliases : [])];
    for (const name of names) {
      const key = normalizeBibleName(name);
      // First writer wins: two characters sharing an alias must not make the
      // later one silently steal every scene from the earlier one.
      if (key && !index.has(key)) index.set(key, entry.id);
    }
  }
  return index;
}

/**
 * Cast integrity for the synced review (#6415, and the remaining half of #6417).
 *
 * The synced review is the one Writers Room surface where a COLD READ of the
 * draft (the `script` analysis, which derives scenes and their speaking cast
 * from the prose alone) sits beside AUTHOR KNOWLEDGE (the per-work character
 * bible, which holds the framework the reader never sees). Reporting cast
 * integrity here is what lets the author see the two disagree.
 *
 * The two are deliberately kept apart, in both directions:
 *
 *   - **Script evidence never closes a framework gap.** The integrity findings
 *     are measured by `buildCastIntegrityReport` against the AUTHORED record
 *     only. A character who is vividly on the page and blank in the bible still
 *     reports every gap — an interior that exists only in the author's head is
 *     exactly the defect this contract was written for.
 *   - **The bible never invents a scene, and the cold read never invents a
 *     character.** A name the extraction found that matches no bible entry is
 *     reported as `unmatchedNames`, NOT as a finding: the report has no record
 *     to attach a field path to, and inventing one would be the same failure as
 *     inventing a field. Symmetrically, an authored character no scene stages is
 *     reported `staged: false` and is NOT a finding — an offstage character is a
 *     legitimate authoring choice, not an integrity defect.
 *
 * Zero provider calls, exactly like every other pane here: this is the
 * deterministic completeness pass plus a join against scenes that already
 * exist. The semantic pass is an explicitly-invoked action elsewhere, so
 * `semanticReviewedCount` is 0 and `passed` is false by construction — a
 * deterministic pass alone never licenses "this cast is clean".
 */

/**
 * Assemble the cast block described above. No I/O.
 *
 * Reads the already-derived scenes (which carry their validated
 * `proseSegmentIds`) rather than re-deriving the mapping, and stamps each one
 * with the `castCharacterIds` its cold-read names resolved to, so the script
 * pane can cross-highlight without a second join on the client.
 */
function buildCastPane({ characters, scenes, scriptAvailable, scriptStale }) {
  const cast = characters.filter((c) => c?.id);
  const index = castNameIndex(cast);
  const sceneIdsByCharacter = new Map();
  const proseIdsByCharacter = new Map();
  const unmatched = new Map();

  for (const scene of scenes) {
    const resolved = [];
    for (const name of scene.characters) {
      const key = normalizeBibleName(name);
      const characterId = index.get(key);
      if (!characterId) {
        // Keep the first spelling the extraction used rather than the lowercased
        // key — the author is going to read this name and add the character.
        if (key && !unmatched.has(key)) unmatched.set(key, String(name).trim());
        continue;
      }
      if (resolved.includes(characterId)) continue;
      resolved.push(characterId);
      const sceneIds = sceneIdsByCharacter.get(characterId) || [];
      sceneIds.push(scene.id);
      sceneIdsByCharacter.set(characterId, sceneIds);
      const proseIds = proseIdsByCharacter.get(characterId) || new Set();
      for (const segId of scene.proseSegmentIds) proseIds.add(segId);
      proseIdsByCharacter.set(characterId, proseIds);
    }
    scene.castCharacterIds = resolved;
  }

  const report = buildCastIntegrityReport(cast);
  const coverage = report.coverage.map((row) => {
    const sceneIds = sceneIdsByCharacter.get(row.characterId) || [];
    return {
      ...row,
      // The cold read's view of this character, kept as its own field so it can
      // never be mistaken for part of the authored assessment above.
      staged: sceneIds.length > 0,
      scriptSceneIds: sceneIds,
      proseSegmentIds: [...(proseIdsByCharacter.get(row.characterId) || [])],
    };
  });

  return {
    available: cast.length > 0,
    findings: report.findings,
    coverage,
    castCount: report.castCount,
    reviewedCount: report.reviewedCount,
    semanticReviewedCount: report.semanticReviewedCount,
    // Always false here — see the module note. Carried explicitly so a consumer
    // reads the contract's answer rather than inferring one from `findings`.
    passed: castIntegrityPassed(report),
    staging: {
      // Without a script analysis nothing is staged, and that is not evidence
      // the cast is absent from the page — it is evidence nobody has looked.
      available: scriptAvailable,
      // The join is only as fresh as the script it joined against.
      stale: scriptStale,
      stagedCount: coverage.filter((row) => row.staged).length,
      unstagedCount: coverage.filter((row) => !row.staged).length,
      unmatchedNames: [...unmatched.values()],
    },
  };
}

/**
 * Pure assembler — no I/O. Given the work manifest, the active draft body, and
 * the (possibly absent / failed) `script` analysis snapshot, produce the full
 * synced-review payload. Kept pure so the mapping logic is unit-testable
 * without touching the filesystem.
 */
export function buildSyncedReview({ manifest, body = '', scriptAnalysis = null, characters = [] }) {
  const { draftVersionId, contentHash, segmentIndex } = activeDraftMeta(manifest);
  const text = String(body || '');

  // Prose segments with their sliced text. Offsets come from the segment index
  // computed at save time, so they line up with the persisted body.
  const proseSegments = segmentIndex.map((seg) => ({
    id: seg.id,
    kind: seg.kind,
    heading: seg.heading,
    start: seg.start,
    end: seg.end,
    wordCount: seg.wordCount,
    text: text.slice(seg.start, seg.end).trim(),
    // filled in below once we know which scenes map back to each segment
    scriptSceneIds: [],
    media: [],
    castCharacterIds: [],
  }));
  const proseSegmentIds = new Set(proseSegments.map((s) => s.id));
  const proseById = new Map(proseSegments.map((s) => [s.id, s]));

  const rawScenes = Array.isArray(scriptAnalysis?.result?.scenes)
    ? scriptAnalysis.result.scenes
    : [];
  const sceneImages = scriptAnalysis?.sceneImages && typeof scriptAnalysis.sceneImages === 'object'
    ? scriptAnalysis.sceneImages
    : {};

  // Script scenes. `sourceSegmentIds` from the LLM is validated against the
  // live prose index — hallucinated or stale segment refs are dropped so a
  // mapping never points at a segment that isn't on screen.
  const scenes = rawScenes.map((s) => {
    const validProseIds = (Array.isArray(s.sourceSegmentIds) ? s.sourceSegmentIds : [])
      .filter((id) => proseSegmentIds.has(id));
    const img = sceneImages[s.id];
    return {
      id: s.id,
      heading: s.heading || null,
      slugline: s.slugline || null,
      summary: s.summary || null,
      characters: Array.isArray(s.characters) ? s.characters : [],
      proseSegmentIds: validProseIds,
      media: img?.filename
        ? { kind: 'image', ref: img.filename, jobId: img.jobId || null, prompt: img.prompt || null, generatedAt: img.generatedAt || null }
        : null,
    };
  });
  const sceneById = new Map(scenes.map((s) => [s.id, s]));

  // Back-fill prose → scene and prose → media from the validated scene mappings.
  for (const scene of scenes) {
    for (const segId of scene.proseSegmentIds) {
      const seg = proseById.get(segId);
      if (!seg) continue;
      seg.scriptSceneIds.push(scene.id);
      if (scene.media) seg.media.push({ ...scene.media, sceneId: scene.id });
    }
  }

  // Media pane — every rendered scene image, including orphans.
  const mediaItems = Object.entries(sceneImages)
    .filter(([, img]) => img && img.filename)
    .map(([sceneId, img]) => buildMediaItem(sceneId, img, sceneById))
    .sort((a, b) => (b.generatedAt || '').localeCompare(a.generatedAt || ''));

  const sceneCount = scenes.length;
  const available = sceneCount > 0;
  const stale = available
    && !!scriptAnalysis?.sourceContentHash
    && !!contentHash
    && scriptAnalysis.sourceContentHash !== contentHash;

  // Cast integrity last: it joins the authored bible against the scenes above,
  // and stamps each scene with the bible ids its cold-read names resolved to.
  const cast = buildCastPane({
    characters: Array.isArray(characters) ? characters : [],
    scenes,
    scriptAvailable: available,
    scriptStale: stale,
  });
  // Mirror scene → cast onto prose, so selecting a segment can highlight the
  // characters the script says it stages.
  for (const scene of scenes) {
    for (const segId of scene.proseSegmentIds) {
      const seg = proseById.get(segId);
      if (!seg) continue;
      for (const characterId of scene.castCharacterIds) {
        if (!seg.castCharacterIds.includes(characterId)) seg.castCharacterIds.push(characterId);
      }
    }
  }

  return {
    workId: manifest?.id || null,
    title: manifest?.title || null,
    draftVersionId,
    activeContentHash: contentHash,
    prose: { segments: proseSegments },
    script: {
      available,
      status: scriptAnalysis?.status || null,
      stale,
      analysisId: scriptAnalysis ? SCRIPT_ANALYSIS_ID : null,
      providerId: scriptAnalysis?.providerId || null,
      model: scriptAnalysis?.model || null,
      completedAt: scriptAnalysis?.completedAt || null,
      error: scriptAnalysis?.status === 'failed' ? (scriptAnalysis.error || 'Script analysis failed') : null,
      title: scriptAnalysis?.result?.title || null,
      logline: scriptAnalysis?.result?.logline || null,
      scenes,
    },
    media: { items: mediaItems },
    cast,
  };
}

/**
 * Orchestrator — load the work + active body + script analysis + cast bible and
 * assemble the synced-review read-model. A missing script analysis (never run,
 * or a fresh work) is a normal empty state, not an error.
 *
 * The cast bible is a local file read, not a provider call — opening the review
 * still starts no AI work.
 */
export async function getSyncedReview(workId) {
  assertValidWorkId(workId);
  const { manifest, body } = await getWorkWithBody(workId);
  const [scriptAnalysis, characters] = await Promise.all([
    getAnalysis(workId, SCRIPT_ANALYSIS_ID).catch((err) => {
      if (err?.code === 'NOT_FOUND') return null;
      throw err;
    }),
    listCharacters(workId),
  ]);
  return buildSyncedReview({ manifest, body, scriptAnalysis, characters });
}