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

24.0 KB
Raw Blame
/**
 * Shared renderers that turn a Universe Builder universe's `categories` map and
 * `compositeSheets` array into prompt-friendly text blocks. Used by both
 * `universeBuilderRefine` (which needs `[LOCKED]` flags) and `arcPlanner` (which
 * does not). The two prior copies in those files had drifted in formatting;
 * consolidating here keeps the LLM input shape consistent across stages.
 */

import { isEntryRevealGated } from './storyBible.js';

export function renderCategoriesForPrompt(categories, { showLocked = false } = {}) {
  const entries = Object.entries(categories || {});
  if (!entries.length) return '';
  return entries
    .map(([key, cat]) => {
      const variations = (cat?.variations || [])
        .map((v) => {
          const flag = showLocked && v.locked ? ' [LOCKED]' : '';
          return `    - "${v.label}"${flag}: ${v.prompt}`;
        })
        .join('\n');
      return `  ${key}:\n${variations || '    (no variations yet)'}`;
    })
    .join('\n');
}

export function renderCompositesForPrompt(composites, { showLocked = false } = {}) {
  if (!composites?.length) return '';
  return composites
    .map((c) => {
      const flag = showLocked && c.locked ? ' [LOCKED]' : '';
      return `  - (${c.kind || 'reference_sheet'}) "${c.label}"${flag}: ${c.prompt}`;
    })
    .join('\n');
}

// Caps for canon → prompt rendering. Sanitized universes can hold up to
// BIBLE_LIMITS.ENTRIES_PER_BIBLE_MAX (200) entries per kind with multi-KB
// descriptions; rendering all of them into every arc/verify prompt would
// inflate token cost + latency by orders of magnitude. Truncate at the
// rendering layer (not in canon storage) so the on-disk universe stays rich
// while LLM context stays bounded.
export const CANON_PROMPT_ENTRIES_PER_KIND_MAX = 40;
export const CANON_PROMPT_DESCRIPTION_MAX = 300;

export const truncDesc = (s) => {
  if (typeof s !== 'string') return '';
  const trimmed = s.trim();
  if (trimmed.length <= CANON_PROMPT_DESCRIPTION_MAX) return trimmed;
  return `${trimmed.slice(0, CANON_PROMPT_DESCRIPTION_MAX - 1).trimEnd()}…`;
};

// Per-canon-kind formatting table — header label + per-entry line builder.
// One row per canon trunk; renderCanonForPrompt iterates this so a future
// kind addition (or field tweak) is a one-line change. formatEntry truncates
// the long description field so a single entry can't dominate the prompt.
// Build a `  - name [role]: physDesc. personality (background). tags: a, b`
// line for a canon character. Trailing metadata is rendered only when
// present so an empty bible doesn't pollute the prompt with empty markers.
const formatCharacter = (c) => {
  const role = c.role ? ` [${c.role}]` : '';
  const tags = Array.isArray(c.tags) && c.tags.length ? ` tags: ${c.tags.join(', ')}` : '';
  const parts = [
    truncDesc(c.physicalDescription || c.description || ''),
    truncDesc(c.personality || ''),
    c.background ? `background: ${truncDesc(c.background)}` : '',
  ].filter(Boolean);
  const body = parts.length ? `: ${parts.join('. ')}` : '';
  return `  - ${c.name}${role}${body}${tags}`;
};

// Place: prefer name; show slugline when present (screenplay-style location
// header used by scene matchers); include recurringDetails — the expand
// contract collects all three and the LLM uses them as continuity anchors.
const formatPlace = (p) => {
  const label = p.name || p.slugline || '(unnamed)';
  const sluglineTag = p.name && p.slugline ? ` (${p.slugline})` : '';
  const palette = p.palette ? ` palette: ${p.palette}` : '';
  const parts = [
    truncDesc(p.description || ''),
    p.recurringDetails ? `recurring: ${truncDesc(p.recurringDetails)}` : '',
  ].filter(Boolean);
  const body = parts.length ? `: ${parts.join('. ')}` : '';
  return `  - ${label}${sluglineTag}${body}${palette}`;
};

const formatObject = (o) => {
  const desc = truncDesc(o.description || '');
  const sig = o.significance ? ` (${truncDesc(o.significance)})` : '';
  return `  - ${o.name}${desc ? `: ${desc}` : ''}${sig}`;
};

// --- The single reveal gate for prompt-facing canon ------------------------
//
// A canon entry carrying a hard `spoiler` flag or a `revealIssue` holds
// authored history the audience has not earned yet. Every prompt-facing block
// in this module routes through this ONE gate — the descriptive canon block
// (`renderCanonForPrompt`) and the authored psychology block
// (`renderCharacterNarrativeContext`) — so the two cannot drift into parallel
// rules the way they had before #6426, when the psychology block withheld a
// spoiler character's ghost while the descriptive block rendered that same
// character's `background` in the very next paragraph.
//
// The gate is an ALLOWLIST PROJECTION, not a per-field subtraction: a gated
// entry is rebuilt from `CONCEALMENT_SAFE_CANON_FIELDS` alone and rendered by
// `renderGatedCanonLine` instead of by its per-kind formatter. A field added to
// a canon record (or to a formatter) later is therefore withheld by default and
// has to be argued onto the list — it cannot leak by simply not having been
// thought about here.
//
// What a gated entry may still show:
//   `id`                — callers key pinning/priority off it; carries no fact.
//   `name` / `slugline` — the roster has to be able to name a cast member or a
//                         location; withholding identity makes the block
//                         unusable rather than safe.
//   `role`              — "antagonist" is a cast slot, not the concealed
//                         history behind it.
//   `surfaceDescriptor` — the author's OWN sanctioned pre-reveal stand-in.
//                         `surfaceCanonEntry` in storyBible.js makes exactly
//                         this call for the drafting-context filter; reusing it
//                         keeps one project-wide answer to "what may a gated
//                         entry show" instead of inventing a second one here.
//
// `personality` and `physicalDescription` are deliberately NOT safe — the call
// #6426 left open, recorded here because the next reader will ask. An authored
// bible routinely puts the post-reveal true self in `personality` ("a meek
// clerk who signed the order"), the same concealed-interiority register the
// psychology block already withholds wholesale, and a `physicalDescription`
// just as routinely carries the tell ("the burn scar from the fire she set").
// `surfaceDescriptor` exists precisely to say what the audience is allowed to
// see so far, so masking those two costs an author nothing they cannot state
// deliberately. `background` is the concealed-history field and was the actual
// leak this gate closes.
export const CONCEALMENT_SAFE_CANON_FIELDS = Object.freeze(['id', 'name', 'role', 'slugline', 'surfaceDescriptor']);

const REVEAL_GATED_CANON_NOTE = '(reveal-gated — concealed canon withheld until the story earns it)';

// Project a gated entry down to the safe fields. Returns null when the gate is
// off or the entry is ungated, so callers read as `concealCanonEntry(e, on) ?? e`.
const concealCanonEntry = (entry, respectRevealGates) => {
  if (!respectRevealGates || !isEntryRevealGated(entry)) return null;
  const safe = {};
  for (const field of CONCEALMENT_SAFE_CANON_FIELDS) {
    if (entry[field] !== undefined) safe[field] = entry[field];
  }
  return safe;
};

// One line shape for a gated entry of ANY kind. The per-kind formatter is never
// reached, which is what makes a newly added descriptive field unable to bypass
// the gate even if nobody remembers this comment.
const renderGatedCanonLine = (entry) => {
  const label = entry.name || entry.slugline || '(unnamed)';
  const role = entry.role ? ` [${entry.role}]` : '';
  const surface = truncDesc(entry.surfaceDescriptor || '');
  return `  - ${label}${role}: ${surface ? `${surface} — ` : ''}${REVEAL_GATED_CANON_NOTE}`;
};

const CANON_SECTIONS = [
  { field: 'characters', header: 'characters', formatEntry: formatCharacter },
  { field: 'places', header: 'places', formatEntry: formatPlace },
  { field: 'objects', header: 'objects', formatEntry: formatObject },
];

// Accept a Set, an array, or a single id and normalize to a Set of non-empty
// string ids. Callers pass whatever they already hold (a bound protagonist id,
// a scoped cast list) without pre-building a Set.
const asIdSet = (ids) => {
  if (ids instanceof Set) return ids;
  const list = Array.isArray(ids) ? ids : (ids == null ? [] : [ids]);
  return new Set(list.filter((id) => typeof id === 'string' && id));
};

// Stable partition: priority entries first (in their original relative order),
// everything else after. Not a sort — a comparator would reorder equal elements
// under an unstable engine and scramble the canon's authored importance order.
const hoistPriorityEntries = (entries, priority) => {
  const first = [];
  const rest = [];
  for (const entry of entries) (priority.has(entry?.id) ? first : rest).push(entry);
  return first.length ? [...first, ...rest] : entries;
};

// Render the universe's canon arrays (characters/places/objects) into a
// prompt-friendly text block. Distinct from renderCategoriesForPrompt because
// canon entries are first-class named entities with rich metadata, not
// exploratory variations — the arc planner references them by name.
// Caps each section at CANON_PROMPT_ENTRIES_PER_KIND_MAX entries; an
// "(… + N more)" footer signals truncation so the LLM doesn't assume the
// canon is complete.
export function renderCanonForPrompt(world, { priorityCharacterIds = null, respectRevealGates = true } = {}) {
  if (!world || typeof world !== 'object') return '';
  const priority = asIdSet(priorityCharacterIds);
  const sections = [];
  for (const { field, header, formatEntry } of CANON_SECTIONS) {
    const raw = Array.isArray(world[field]) ? world[field] : [];
    // A character the caller explicitly bound (the FableLoom protagonist) must
    // survive the per-kind cap — otherwise a 60-character universe can silently
    // drop the one entry the story is ABOUT. Hoisting is stable: the priority
    // entries keep their relative order, and so does everything after them.
    const entries = field === 'characters' && priority.size
      ? hoistPriorityEntries(raw, priority)
      : raw;
    if (!entries.length) continue;
    const shown = entries.slice(0, CANON_PROMPT_ENTRIES_PER_KIND_MAX);
    const hiddenCount = entries.length - shown.length;
    const lines = shown.map((entry) => {
      const concealed = concealCanonEntry(entry, respectRevealGates);
      return concealed ? renderGatedCanonLine(concealed) : formatEntry(entry);
    });
    if (hiddenCount > 0) {
      lines.push(`  - (… + ${hiddenCount} more ${header} not shown — prompt budget reached)`);
    }
    sections.push(`${header}:\n${lines.join('\n')}`);
  }
  return sections.join('\n\n');
}

// Per-kind caps for the compact entity summary. The summary is meant for
// per-issue text stages (prose/teleplay/comic-script) where the full canon
// dump would dominate the prompt — keep one short line per kind so the LLM
// gets continuity anchors without the budget hit.
export const ENTITIES_SUMMARY_MAX_PER_KIND = 8;
export const ENTITIES_SUMMARY_DESCRIPTOR_MAX = 80;

const truncOneLine = (s) => {
  if (typeof s !== 'string') return '';
  const flat = s.trim().replace(/\s+/g, ' ');
  if (!flat) return '';
  if (flat.length <= ENTITIES_SUMMARY_DESCRIPTOR_MAX) return flat;
  return `${flat.slice(0, ENTITIES_SUMMARY_DESCRIPTOR_MAX - 1).trimEnd()}…`;
};

// Pick the most useful 1-line descriptor available per kind. Characters lead
// with role + a sliver of physicalDescription/personality; places use a slice
// of description; objects pull from significance or description. The goal is
// a quick orientation glance, not a substitute for the full canon block.
const summarizeCharacter = (c) => {
  const role = c.role ? `${c.role}` : '';
  const body = truncOneLine(c.physicalDescription || c.personality || c.description || c.background || '');
  if (role && body) return `${c.name} (${role} — ${body})`;
  if (role) return `${c.name} (${role})`;
  if (body) return `${c.name} (${body})`;
  return c.name;
};

const summarizePlace = (p) => {
  const label = p.name || p.slugline || '(unnamed)';
  const desc = truncOneLine(p.description || p.recurringDetails || '');
  return desc ? `${label} (${desc})` : label;
};

const summarizeObject = (o) => {
  const desc = truncOneLine(o.significance || o.description || '');
  return desc ? `${o.name} (${desc})` : o.name;
};

const SUMMARY_SECTIONS = [
  { field: 'characters', header: 'Characters', formatEntry: summarizeCharacter },
  { field: 'places',     header: 'Places',     formatEntry: summarizePlace },
  { field: 'objects',    header: 'Objects',    formatEntry: summarizeObject },
];

/**
 * Render a compact one-line-per-kind synopsis of the universe's named canon.
 *
 * Shape: each non-empty kind becomes `<Header>: name (descriptor); name; …`
 * joined with newlines. Top-N entries per kind (canon list order = LLM-
 * generated importance order). Returns an empty string when there is no
 * canon — callers gate against that for the `(none)` placeholder.
 *
 * Distinct from `renderCanonForPrompt`:
 *   - canon block: multi-line, rich metadata per entry, intended for arc-
 *     level prompts that benefit from the full bible.
 *   - this summary: terse one-line tags meant for per-issue text stages
 *     (prose/teleplay/comic-script) where the budget can't afford the full
 *     dump but the LLM still needs continuity anchors.
 */
// `maxPerKind` accepts either a single number (applied to every kind) or a
// per-kind map (`{ characters, places, objects }`) so a caller can lift the cap
// on one kind while leaving the others at the default — e.g. the per-issue text
// stages render the roster with the WHOLE non-scoped character cast (continuity
// safety net) while keeping places/objects terse. A missing per-kind key falls
// back to the default cap.
const capForKind = (maxPerKind, field) => (
  typeof maxPerKind === 'object' && maxPerKind !== null
    ? (maxPerKind[field] ?? ENTITIES_SUMMARY_MAX_PER_KIND)
    : maxPerKind
);

// `excludeCharacterNames` (a Set of lower-cased names) drops characters already
// rendered in full elsewhere in the same prompt — e.g. the per-issue text stages
// list the SCOPED characters as full bible records, so re-listing them in this
// terse roster is pure duplication. Places/objects are never excluded (they have
// no full-record block to overlap with). The exclusion happens BEFORE the top-N
// slice so the "+N more" count reflects what's actually withheld.
export function renderEntitiesSummary(world, { maxPerKind = ENTITIES_SUMMARY_MAX_PER_KIND, excludeCharacterNames = null } = {}) {
  if (!world || typeof world !== 'object') return '';
  const exclude = excludeCharacterNames instanceof Set ? excludeCharacterNames : null;
  const lines = [];
  for (const { field, header, formatEntry } of SUMMARY_SECTIONS) {
    let entries = Array.isArray(world[field]) ? world[field] : [];
    if (field === 'characters' && exclude && exclude.size) {
      entries = entries.filter((e) => !exclude.has((e?.name || '').trim().toLowerCase()));
    }
    if (!entries.length) continue;
    const shown = entries.slice(0, capForKind(maxPerKind, field));
    const hidden = entries.length - shown.length;
    const tags = shown.map(formatEntry).filter(Boolean);
    if (!tags.length) continue;
    const joined = tags.join('; ');
    lines.push(hidden > 0 ? `${header}: ${joined}; (+${hidden} more)` : `${header}: ${joined}`);
  }
  return lines.join('\n');
}

// --- Authored character psychology (the "engines" block) -------------------
//
// A character's Ghost/Wound/Lie/Want/Need chain, motivations, relationship
// pressure and declared arc intent are PLOT inputs — the causal machinery that
// makes a character drive the story instead of decorating it. `formatCharacter`
// above deliberately renders only the descriptive/visual half of a canon
// record, so every consumer that reasons about CHOICE needs this second block.
//
// One vocabulary, one renderer: the Series arc planner
// (`renderCharacterFoundationForArc`), the FableLoom canon digest, and the
// series-concept seed all render through here so the labels the LLM learns in
// one stage mean the same thing in the next.

export const CHARACTER_NARRATIVE_FIELD_MAX = 220;

// Default caps per purpose. Arc planning keeps the historical top-six engine
// (it rides inside an already-long shape-guidance block); the FableLoom canon
// digest and the series-concept seed can afford a wider ensemble because the
// psychology block is the only place those prompts see causal motivation.
export const CHARACTER_NARRATIVE_ARC_MAX = 6;
const CHARACTER_NARRATIVE_DIGEST_MAX = 12;

/**
 * Ordered field spec. A newly authored psychology field (theory of control,
 * drives, …) becomes ONE row here and reaches the arc planner, the FableLoom
 * canon digest and the series seed in the same commit — that is the seam the
 * schema work plugs into, and the reason this table is not inlined per caller.
 *
 * `secrets` is deliberately absent: it is the one authored field whose whole
 * purpose is to stay unsaid, and this block feeds generation prompts.
 */
const CHARACTER_NARRATIVE_FIELD_SPECS = Object.freeze([
  { field: 'role', label: 'role', identity: true },
  { field: 'ghost', label: 'ghost' },
  { field: 'wound', label: 'wound' },
  { field: 'lie', label: 'lie' },
  { field: 'want', label: 'want' },
  { field: 'need', label: 'need' },
  { field: 'motivations', label: 'motives' },
  { field: 'relationships', label: 'relationships' },
  { field: 'arcType', label: 'arc intent' },
]);

const CORE_ROLE_RE = /protagonist|lead|hero|antagonist|villain|deuteragonist|mentor/i;

const compactCharacterField = (value, max = CHARACTER_NARRATIVE_FIELD_MAX) => {
  const flat = typeof value === 'string' ? value.trim().replace(/\s+/g, ' ') : '';
  return flat.length > max ? `${flat.slice(0, max - 1).trimEnd()}…` : flat;
};

// How many psychology fields (identity excluded — `role` is already the
// core-role signal) the author actually filled in. Used as the ranking
// tiebreak: a fully authored supporting player is worth more prompt budget
// than a name-only walk-on.
const narrativeDepth = (character) => CHARACTER_NARRATIVE_FIELD_SPECS
  .filter(({ field, identity }) => !identity && compactCharacterField(character?.[field]))
  .length;

/**
 * Rank a cast for prompt inclusion and report what fell off the end.
 *
 * Order: caller-pinned ids (a bound protagonist) → recognized core roles →
 * authored depth → original canon order. Returns `{ shown, omitted }` so the
 * caller can render an explicit coverage footer instead of letting the model
 * assume it saw the whole ensemble.
 */
function rankCharactersForNarrativeContext(characters, {
  max = CHARACTER_NARRATIVE_ARC_MAX,
  priorityIds = null,
} = {}) {
  const list = (Array.isArray(characters) ? characters : []).filter((c) => c && typeof c === 'object');
  const priority = asIdSet(priorityIds);
  const ranked = list
    .map((character, index) => ({
      character,
      index,
      pinned: priority.has(character.id),
      coreRole: CORE_ROLE_RE.test(character.role || ''),
      depth: narrativeDepth(character),
    }))
    .sort((a, b) => Number(b.pinned) - Number(a.pinned)
      || Number(b.coreRole) - Number(a.coreRole)
      || b.depth - a.depth
      || a.index - b.index)
    .map(({ character }) => character);
  return { shown: ranked.slice(0, max), omitted: ranked.slice(max) };
}

/**
 * Render the authored psychology block.
 *
 * `respectRevealGates` is the safety valve: a character carrying a hard
 * `spoiler` flag or a `revealIssue` has authored history the audience has NOT
 * earned yet, so the gated entry renders as a named placeholder rather than
 * handing a generation prompt the concealed origin. Author-side planning
 * surfaces must explicitly turn it off: the arc planner (`pipeline/arcPlanner/context.js`)
 * and FableLoom editorial (`fableLoom/editorial.js`) need the unrevealed canon.
 * The gate defaults ON in all three renderers. It is the SAME
 * predicate and allowlist the descriptive block uses (`concealCanonEntry`) —
 * see the gate comment above; do not add a second rule here.
 *
 * `reportOmitted` appends a coverage footer naming how many cast members the
 * cap withheld — a reviewer that is told the ensemble is complete when it is
 * not will confidently report on characters it never saw.
 */
export function renderCharacterNarrativeContext(characters, {
  max = CHARACTER_NARRATIVE_ARC_MAX,
  priorityIds = null,
  respectRevealGates = true,
  reportOmitted = false,
} = {}) {
  const { shown, omitted } = rankCharactersForNarrativeContext(characters, { max, priorityIds });
  if (!shown.length) return '';
  const lines = shown.map((character) => {
    const name = character.name || 'Unnamed';
    // Same projection the descriptive block uses — one predicate, one
    // allowlist. The psychology block replaces the WHOLE line rather than
    // rendering the safe fields, because every spec row below `role` is
    // concealed interiority by construction.
    if (concealCanonEntry(character, respectRevealGates)) {
      return `- ${name}: (reveal-gated — authored psychology withheld until the story earns it)`;
    }
    const fields = CHARACTER_NARRATIVE_FIELD_SPECS
      .map(({ field, label }) => [label, compactCharacterField(character[field])])
      .filter(([, value]) => value)
      .map(([label, value]) => `${label}=${value}`);
    return `- ${name}: ${fields.join(' | ') || '(framework not authored)'}`;
  });
  if (reportOmitted && omitted.length) {
    lines.push(`- (… + ${omitted.length} more characters not shown — prompt budget reached; do not treat this cast list as complete)`);
  }
  return lines.join('\n');
}

// Header for the psychology block inside a canon digest. Carries the standing
// craft constraint with it (behavior, not exposition) so every stage template
// that renders `{{canonDigest}}` inherits the rule without a template edit.
const CHARACTER_ENGINES_HEADER = 'character engines (author-only canon — motivate behavior and choices with these; do not have characters recite them as exposition, and do not reveal concealed history before the story earns it):';

/**
 * Compose the full story-facing canon digest for a linked universe: the
 * verified protagonist binding, the descriptive canon block, and the authored
 * psychology block. Shared by FableLoom generation/review (`weave.js`) and the
 * author-side editorial pass (`editorial.js`) so both reason from the same
 * facts — before this, both rendered `renderCanonForPrompt` alone and the
 * Ghost/Wound/Lie/Want/Need chain never reached the model at all (#6416).
 *
 * NOT for reader-facing surfaces. The play turn and the cold-opening
 * first-time-viewer review deliberately withhold canon; they must keep passing
 * their own placeholder rather than calling this.
 *
 * `respectRevealGates` defaults ON and drives BOTH blocks from the one gate
 * above, so a spoiler character's concealed `background` can no longer ride the
 * descriptive block into a generation prompt while the psychology block masks
 * that same character (#6426). Read-only author-side surfaces that are supposed
 * to reason over the whole bible — the editorial pass, whose continuity checks
 * exist precisely to catch a premature reveal — pass `false` explicitly.
 */
export function renderStoryCanonDigest(universe, { protagonistCharacterId = null, respectRevealGates = true } = {}) {
  if (!universe || typeof universe !== 'object') return '';
  const characters = Array.isArray(universe.characters) ? universe.characters : [];
  const protagonist = protagonistCharacterId
    ? characters.find((character) => character?.id === protagonistCharacterId)
    : null;
  const priorityIds = protagonist ? [protagonist.id] : null;
  const narrative = renderCharacterNarrativeContext(characters, {
    max: CHARACTER_NARRATIVE_DIGEST_MAX,
    priorityIds,
    respectRevealGates,
    reportOmitted: true,
  });
  return [
    protagonist ? `Verified Universe protagonist: id=${protagonist.id}; name=${protagonist.name}.` : '',
    renderCanonForPrompt(universe, { priorityCharacterIds: priorityIds, respectRevealGates }),
    narrative ? `${CHARACTER_ENGINES_HEADER}\n${narrative}` : '',
  ].filter(Boolean).join('\n\n');
}