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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* The OPTIONAL five-stage character evolution lens (#6440, epic #6418).
*
* A story-scoped craft lens layered over the universe-level psychology profile
* in `characterFramework.js` (Ghost → Wound → Lie → Want → Need, theory of
* control, drives). That profile is the character's baseline IDENTITY and is
* owned by the universe; this module models what ONE story does to it — the
* belief it puts under test, the pressure it applies, the choice the character
* makes, and what that choice causes. A series/work/branch's realized change
* must never be written back over world-level identity, which is why the lens
* hangs off the story record (`series.characterArcs[].evolution`,
* `loom.seriesPlan.characterEvolutions[]`) and links to the cast by character
* id alone.
*
* Deliberate non-rules, carried from #6418:
* - The lens is OPTIONAL. Every arc, beat structure and authored transition
* kind stays valid with it unset; nothing here becomes a gate.
* - The five stages are a craft lens over authored beats, NOT a page count,
* a chapter count, or a percentage layout.
* - The changed belief need not be the literal negation of the tested one.
* - Not every character transforms. `tragic-refusal`, `flat-testing` and
* `partial-open` are DECLARED outcomes, not defects — declaring one is what
* stops a downstream review reading a deliberate flat arc as a gap.
* - Stages are SPARSE: a lens with only stages 1 and 3 authored is valid.
*
* A PURE LEAF (imports only `bibleLimits.js` + the dependency-free trim
* helpers in `textUtils.js`), matching `characterFramework.js`, so
* `client/src/lib/characterEvolution.js` can re-export the vocabularies into
* the browser bundle without dragging `crypto` / `fileUtils` along. That
* purity is why a stage has no minted uuid: `stageId` is the identity (one
* record per stage per lens), which needs no id generator and keeps a
* round trip byte-stable.
*
* Embedded by `seriesCharacterArc.js` (`series.characterArcs[].evolution`),
* `services/fableLoom/records.js` (`loom.seriesPlan.characterEvolutions[]`) and
* `lib/storyBible.js`'s `sanitizeCharacter` (`characters[].evolution`, which is
* how a Writers Room work carries the lens per work WITHOUT being promoted to a
* Pipeline series — #6445), all of which sanitize on load/save/sync.
*/
import { BIBLE_LIMITS } from './bibleLimits.js';
import { trimTo, trimToClause, isStr } from './textUtils.js';
// Storr's sequence as #6418 restates it, in order: the control strategy is
// visibly failing; an event forces exploration of another way; the character
// commits to a changed strategy; consequences test whether they can bear its
// cost; a final choice and its aftermath demonstrate enduring change (or
// refusal). An unknown stage id is REJECTED rather than coerced — a beat that
// cannot be placed in the sequence cannot be reasoned about, and silently
// snapping it to a neighbouring stage would fabricate authored intent.
export const EVOLUTION_STAGES = Object.freeze([
'control-strategy-failing',
'pressure-forces-exploration',
'commitment-to-change',
'cost-tested',
'final-proof',
]);
// The four DECLARED outcome kinds. `full-change` = the change endures;
// `tragic-refusal` = the character doubles down on the control belief;
// `flat-testing` = the belief is tested and deliberately holds (the character
// changes the world instead of themselves); `partial-open` = only some of the
// change is earned, or the ending leaves it genuinely open. All four are
// first-class authored endings — none is a finding.
export const EVOLUTION_OUTCOMES = Object.freeze([
'full-change',
'tragic-refusal',
'flat-testing',
'partial-open',
]);
// The prose half of one stage, in authoring order.
export const EVOLUTION_STAGE_TEXT_FIELDS = Object.freeze([
'testedBelief', 'externalPressure', 'characterChoice', 'causalConsequence',
]);
// Per-field caps keyed by field name (mirrors CHARACTER_PSYCHOLOGY_LIMITS) so a
// Zod schema or an editor sizes every input from one map instead of
// re-deriving the `<FIELD>_MAX` naming convention.
export const CHARACTER_EVOLUTION_LIMITS = Object.freeze({
testedBelief: BIBLE_LIMITS.EVOLUTION_TESTED_BELIEF_MAX,
externalPressure: BIBLE_LIMITS.EVOLUTION_EXTERNAL_PRESSURE_MAX,
characterChoice: BIBLE_LIMITS.EVOLUTION_CHARACTER_CHOICE_MAX,
causalConsequence: BIBLE_LIMITS.EVOLUTION_CAUSAL_CONSEQUENCE_MAX,
outcomeNote: BIBLE_LIMITS.EVOLUTION_OUTCOME_NOTE_MAX,
characterName: BIBLE_LIMITS.NAME_MAX,
atSceneAnchor: BIBLE_LIMITS.EVOLUTION_EVIDENCE_ANCHOR_MAX,
// The verbatim manuscript snippet a Writers Room stage quotes. Same cap as
// the free-text scene anchor it plays the same role as: an authored locator,
// not an identifier.
anchorQuote: BIBLE_LIMITS.EVOLUTION_EVIDENCE_ANCHOR_MAX,
evidenceRef: BIBLE_LIMITS.EVOLUTION_EVIDENCE_REF_MAX,
atIssue: BIBLE_LIMITS.STORY_ISSUE_NUMBER_MAX,
STAGES_PER_LENS_MAX: EVOLUTION_STAGES.length,
LENSES_PER_PLAN_MAX: BIBLE_LIMITS.EVOLUTIONS_PER_PLAN_MAX,
});
// How much a stage's evidence anchor actually PROVES. Only `anchored` counts
// as verified — the epic's non-negotiable is that a missing or stale anchor can
// never read as verified, so every other value must fail an "is this proven?"
// test:
// `unanchored` — nothing authored. Not a defect on its own (the lens is a
// plan; evidence arrives when the beat does), just unproven.
// `unverified` — a pointer is authored but the caller supplied no reference
// set to check it against. Unknown, therefore not verified.
// `anchored` — every authored pointer resolves against the host record.
// `stale` — at least one authored pointer names something that no
// longer exists. PRESERVED, never silently dropped, following
// the `sanitizeStoryOutline` precedent that keeps an unknown
// `targetKey` so `DANGLING_TRANSITION` can report it.
export const EVOLUTION_EVIDENCE_STATUSES = Object.freeze([
'unanchored', 'unverified', 'anchored', 'stale',
]);
// Shared per-character story-list primitives. They live in this leaf — the
// lowest module both per-character story lists reach — rather than beside
// either host, because a rule that lives in two places drifts: widen the canon
// id shape on the arc path alone and the same id silently blanks on the lens
// path, or refine the identity key on one side and two records that collapse
// on the pipeline host stay split on the FableLoom host.
const CHARACTER_ID_RE = /^chr-[a-zA-Z0-9-]+$/;
const TRANSITION_ID_RE = /^trn-[a-zA-Z0-9-]+$/;
const EPISODE_ID_RE = /^ep-[a-zA-Z0-9-]+$/;
// A Writers Room manuscript segment (`buildSegmentIndex`). POSITIONAL, unlike
// every other pointer here: `seg-003` is the third heading of the draft as it
// stands, and the whole index is recomputed on every draft save. That is why
// the Writers Room host pairs it with `anchorQuote` below.
const SEGMENT_ID_RE = /^seg-\d+$/;
/** True for a canon cast pointer (`chr-<uuid>`). */
export const isCanonCharacterId = (raw) => isStr(raw) && CHARACTER_ID_RE.test(raw);
/** True for an authored transition-beat id (`trn-<uuid>`). */
export const isStoryBeatId = (raw) => isStr(raw) && TRANSITION_ID_RE.test(raw);
/**
* Dedupe key for a per-character story list: the canon pointer wins, and a
* case-folded name is the fallback so a name-only entry still de-dupes against
* itself. Read by `sanitizeCharacterArcList` and `sanitizeCharacterEvolutionList`.
*/
export const characterIdentityKey = (characterId, characterName) => (
characterId || `name:${String(characterName).trim().toLowerCase()}`
);
/**
* Optional non-negative issue number. Absent / non-finite → null so a caller
* can tell "no issue pinned" from issue 0. Shared with the arc's transition
* anchors, which cap against the same `STORY_ISSUE_NUMBER_MAX`.
*/
export const optIssueNumber = (raw, max) => (
Number.isFinite(raw) ? Math.max(0, Math.min(max, Math.floor(raw))) : null
);
// A pointer is kept only when it matches its host's id shape; anything else
// collapses to '' so a junk value can't masquerade as evidence. A well-shaped
// pointer to a DELETED record is a different case entirely — it survives here
// and `evolutionEvidenceStatus` reports it stale.
const shapedRef = (raw, re) => {
if (!isStr(raw)) return '';
const value = raw.trim();
return re.test(value) ? value.slice(0, CHARACTER_EVOLUTION_LIMITS.evidenceRef) : '';
};
// A host reference set. A Map passes through unchanged (it answers `.has` like
// a Set and additionally carries the passage text a QUOTED_ANCHORS check
// needs), so a host can hand richer refs in without a second parameter.
const asSet = (value) => {
if (value instanceof Set || value instanceof Map) return value;
if (Array.isArray(value)) return new Set(value);
return null;
};
// The anchor fields each host owns, and the ref set each resolves against.
// ONE table so the sanitizer, the status check, the renderer, the Zod schema
// and the client editor never enumerate the vocabulary five different ways.
export const EVOLUTION_EVIDENCE_FIELDS = Object.freeze({
pipelineSeries: Object.freeze(['atIssue', 'atSceneAnchor', 'transitionId']),
fableLoom: Object.freeze(['episodeId', 'sceneKey']),
// Writers Room maps the lens RETROSPECTIVELY onto a manuscript it never
// promotes to a Pipeline series, so its only anchor primitive is the segment
// index. `anchorQuote` is not a second pointer — it is what makes the first
// one checkable across an edit.
writersRoom: Object.freeze(['segmentId', 'anchorQuote']),
});
// Pointer fields that resolve against a host reference set, paired with the
// `refs` key that carries it. `atIssue` / `atSceneAnchor` are deliberately
// absent: they are authored locators with nothing to resolve against.
const RESOLVABLE_ANCHORS = Object.freeze([
['transitionId', 'transitionIds'],
['episodeId', 'episodeIds'],
['sceneKey', 'sceneKeys'],
['segmentId', 'segmentIds'],
]);
// Pointer fields that carry a companion QUOTE: `[pointer, refsKey, quoteField]`.
// When the host hands the matching ref set in as a Map of pointer -> passage
// text, the quote must still appear in that passage. Without it a positional
// pointer proves only that SOMETHING still occupies that slot — and a Writers
// Room `seg-003` is renumbered by any edit that adds a heading above it, so
// "the id resolves" is exactly the false pass #6418 forbids. A host that hands
// in a plain Set (or no set) is unchanged: the quote is then unverifiable, not
// wrong.
const QUOTED_ANCHORS = Object.freeze([['segmentId', 'segmentIds', 'anchorQuote']]);
// Quotes are compared whitespace-collapsed and case-folded: a manuscript edit
// that rewraps a paragraph or re-cases a heading has not moved the passage.
const normalizeQuote = (raw) => (isStr(raw) ? raw.replace(/\s+/g, ' ').trim().toLowerCase() : '');
/**
* Sanitize one stage's evidence anchor. Returns `null` when nothing is
* authored so an evidence-free stage carries no empty husk.
*
* Both hosts' vocabularies live in one block on purpose — the lens shape is
* shared, and each host resolves only the pointers it owns:
* - Pipeline series: `atIssue` / `atSceneAnchor` (the same optional pair
* `sanitizeTransition` accepts) plus `transitionId`, naming the authored
* `trn-` beat that proves the stage.
* - FableLoom: `episodeId` (`ep-<uuid>`) plus `sceneKey` (a
* `storyOutline.scenes[].key`).
* - Writers Room: `segmentId` (a `seg-NNN` from `buildSegmentIndex`) plus
* `anchorQuote`, a verbatim snippet of the passage it names. The segment id
* is positional and is rebuilt on every draft save, so the quote is what
* lets `evolutionEvidenceStatus` tell "still the same passage" from "that
* slot now holds a different chapter".
* A field the host does not use simply stays empty.
*/
export function sanitizeEvolutionEvidence(raw) {
if (!raw || typeof raw !== 'object') return null;
const evidence = {
atIssue: optIssueNumber(raw.atIssue, CHARACTER_EVOLUTION_LIMITS.atIssue),
atSceneAnchor: trimTo(raw.atSceneAnchor, CHARACTER_EVOLUTION_LIMITS.atSceneAnchor),
transitionId: shapedRef(raw.transitionId, TRANSITION_ID_RE),
episodeId: shapedRef(raw.episodeId, EPISODE_ID_RE),
// Outline scene keys are author-chosen slugs with no prefix contract, so
// they are length-bounded rather than shape-matched; resolution against the
// episode's real keys is what separates a live anchor from a stale one.
sceneKey: trimTo(raw.sceneKey, CHARACTER_EVOLUTION_LIMITS.evidenceRef),
segmentId: shapedRef(raw.segmentId, SEGMENT_ID_RE),
// Free text, deliberately not shape-matched: it is a verbatim snippet of
// the author's own prose, and it is PRESERVED when its segment pointer goes
// stale so it can drive the re-anchor.
anchorQuote: trimTo(raw.anchorQuote, CHARACTER_EVOLUTION_LIMITS.anchorQuote),
};
const authored = evidence.atIssue !== null
|| evidence.atSceneAnchor
|| evidence.transitionId
|| evidence.episodeId
|| evidence.sceneKey
|| evidence.segmentId
|| evidence.anchorQuote;
return authored ? evidence : null;
}
/**
* How much this evidence proves, given what the host record actually contains.
* DERIVED on read rather than persisted, so a status can never drift out of
* step with the record it describes and a peer can never assert its own
* anchors verified. Pass whichever reference sets the host owns:
*
* { transitionIds, episodeIds, sceneKeys } // Set | Array | omitted
*
* An omitted set means "not checked here" → `unverified`, never `anchored`.
* Returns one of EVOLUTION_EVIDENCE_STATUSES; only `anchored` is verified.
*/
export function evolutionEvidenceStatus(evidence, refs = {}) {
if (!evidence || typeof evidence !== 'object') return 'unanchored';
const authored = RESOLVABLE_ANCHORS.filter(([field]) => Boolean(evidence[field]));
// A free-text scene anchor / issue number is an authored locator with nothing
// to resolve against — it counts as authored evidence but can never be
// machine-verified, so on its own it stays `unverified`. Checked before the
// ref sets are materialized so the common no-pointer case allocates nothing.
if (authored.length === 0) {
return evidence.atIssue != null || evidence.atSceneAnchor || evidence.anchorQuote
? 'unverified'
: 'unanchored';
}
let unchecked = false;
for (const [field, refsKey] of authored) {
const known = asSet(refs[refsKey]);
if (!known) unchecked = true;
else if (!known.has(evidence[field])) return 'stale';
}
// A quoted pointer that resolved still has to still SAY what it said. The
// check runs only when the host supplied the passage text; otherwise the
// anchor is merely unchecked, which is `unverified` below, never `anchored`.
for (const [field, refsKey, quoteField] of QUOTED_ANCHORS) {
const quote = normalizeQuote(evidence[quoteField]);
if (!evidence[field] || !quote) continue;
const known = refs[refsKey];
if (!(known instanceof Map)) {
unchecked = true;
continue;
}
if (!normalizeQuote(known.get(evidence[field])).includes(quote)) return 'stale';
}
return unchecked ? 'unverified' : 'anchored';
}
/**
* Sanitize one stage. Returns `null` when the stage id is unknown (rejected,
* never coerced) or when nothing is authored under it, so `cleanStages` drops
* it and a sparse lens stays sparse.
*/
export function sanitizeEvolutionStage(raw) {
if (!raw || typeof raw !== 'object') return null;
if (!EVOLUTION_STAGES.includes(raw.stageId)) return null;
const stage = { stageId: raw.stageId };
let authored = false;
for (const field of EVOLUTION_STAGE_TEXT_FIELDS) {
// Prose, not identifiers: `trimToClause` so an over-cap stage ends on a
// sentence (or at worst a whole word) rather than mid-word. A hard clip
// hands the next verify round a belief that stops mid-thought, which reads
// as an authoring gap — see the same note in `seriesCharacterArc.js`.
stage[field] = trimToClause(raw[field], CHARACTER_EVOLUTION_LIMITS[field]);
if (stage[field]) authored = true;
}
stage.evidence = sanitizeEvolutionEvidence(raw.evidence);
// A stage id with no prose and no anchor is an empty marker with nothing to
// render or reason about (mirrors `sanitizeTransition`'s label/note rule).
return authored || stage.evidence ? stage : null;
}
// Stages are stored in canonical sequence order, deduplicated by `stageId`
// (last write wins) — the lens is five ORDERED stages, so a round trip that
// re-sorted arbitrarily would never be byte-stable.
function cleanStages(rawList) {
if (!Array.isArray(rawList)) return [];
const byStage = new Map();
for (const raw of rawList) {
const stage = sanitizeEvolutionStage(raw);
if (stage) byStage.set(stage.stageId, stage);
}
return EVOLUTION_STAGES.map((id) => byStage.get(id)).filter(Boolean);
}
/**
* Sanitize one character's evolution lens. Returns `null` when nothing is
* authored, mirroring `sanitizeCharacterArc`'s "no identifying content ⇒ drop"
* rule — so a record that never opted into the lens round-trips byte-identical.
*
* `outcome` is the DECLARATION that keeps a deliberate flat or tragic arc from
* reading as a defect downstream, and an unknown value is rejected outright
* rather than coerced to a default (which would fabricate a declaration the
* author never made). It is nullable rather than mandatory on purpose: an
* author fills stages before they know how the story lands, a peer may send a
* lens through an older sanitizer, and BOTH host records carry the lens inside
* a wholesale-replaced field — so refusing a lens with no declared outcome
* would delete authored prose on a partial save and 400 an unrelated edit.
* `isDeclaredEvolution` is the gate downstream reviews use instead; an
* undeclared lens is incomplete, never a declared flat arc.
*/
export function sanitizeCharacterEvolution(raw) {
if (!raw || typeof raw !== 'object') return null;
const outcome = EVOLUTION_OUTCOMES.includes(raw.outcome) ? raw.outcome : null;
const outcomeNote = trimToClause(raw.outcomeNote, CHARACTER_EVOLUTION_LIMITS.outcomeNote);
const stages = cleanStages(raw.stages);
if (!outcome && !outcomeNote && stages.length === 0) return null;
return { outcome, outcomeNote, stages };
}
/**
* True only when the author has DECLARED how the arc lands. The epic's
* non-negotiable — a declared flat or tragic-refusal arc is first-class, not a
* finding — applies to declared lenses only; an undeclared one is unfinished
* planning and must read as such.
*/
export const isDeclaredEvolution = (evolution) => (
Boolean(evolution) && EVOLUTION_OUTCOMES.includes(evolution.outcome)
);
/**
* Sanitize a per-character lens LIST (`loom.seriesPlan.characterEvolutions[]`).
* Each entry is `{ characterId, characterName, evolution }`; entries with no
* identity or no authored lens are dropped, and the list dedupes by character
* identity exactly as `sanitizeCharacterArcList` does (canon pointer first,
* case-folded name as the fallback) so two lenses for one character collapse
* last-write-wins. Returns [] for a non-array so a pre-lens plan migrates
* forward without a writer pass.
*
* The pipeline host needs no equivalent: its lens nests inside the already
* per-character, already deduplicated `series.characterArcs[]`.
*/
export function sanitizeCharacterEvolutionList(rawList) {
if (!Array.isArray(rawList)) return [];
const byKey = new Map();
const order = [];
for (const raw of rawList) {
if (!raw || typeof raw !== 'object') continue;
const characterId = isCanonCharacterId(raw.characterId) ? raw.characterId : '';
const characterName = trimTo(raw.characterName, CHARACTER_EVOLUTION_LIMITS.characterName);
if (!characterId && !characterName) continue;
// Identity and cap are settled BEFORE the per-entry walk: a peer payload
// skips the route's `.max()` and reaches this sanitizer directly, so a
// 10k-entry list must not pay five stages of prose trimming per entry only
// to be dropped at the cap.
const key = characterIdentityKey(characterId, characterName);
const known = byKey.has(key);
if (!known && byKey.size >= CHARACTER_EVOLUTION_LIMITS.LENSES_PER_PLAN_MAX) continue;
const evolution = sanitizeCharacterEvolution(raw.evolution);
if (!evolution) continue;
if (!known) order.push(key);
byKey.set(key, { characterId, characterName, evolution });
}
return order.map((k) => byKey.get(k));
}
// Human-readable stage names for a prompt block or an editor heading. Exported
// (rather than kept private) so `client/src/lib/characterEvolution.js` renders
// the same words the review prompts do.
export const EVOLUTION_STAGE_LABELS = Object.freeze({
'control-strategy-failing': 'control strategy failing',
'pressure-forces-exploration': 'pressure forces exploration',
'commitment-to-change': 'commitment to change',
'cost-tested': 'cost tested',
'final-proof': 'final proof',
});
// How each authored stage field reads in a prompt block.
const STAGE_FIELD_LABELS = Object.freeze({
testedBelief: 'belief under test',
externalPressure: 'pressure',
characterChoice: 'choice',
causalConsequence: 'consequence',
});
// One-line description of what a stage's anchor points at, for a prompt block.
// Says nothing about whether it resolves — `evolutionEvidenceStatus` owns that.
const describeEvidence = (evidence) => {
if (!evidence) return 'none';
const bits = [];
if (evidence.atIssue != null) bits.push(`issue ${evidence.atIssue}`);
if (evidence.atSceneAnchor) bits.push(evidence.atSceneAnchor);
for (const [field, label] of [['transitionId', 'transition'], ['episodeId', 'episode'], ['sceneKey', 'scene'], ['segmentId', 'segment']]) {
if (evidence[field]) bits.push(`${label} ${evidence[field]}`);
}
if (evidence.anchorQuote) bits.push(`quote "${evidence.anchorQuote}"`);
return bits.join(', ') || 'none';
};
/**
* Render one lens as a compact prompt block, or `null` when there is nothing
* to render — mirroring `renderCharacterArcsForPrompt` so every later slice of
* #6418 shares one renderer instead of writing three.
*
* `refs` is optional and is forwarded to `evolutionEvidenceStatus`; an anchor
* is annotated only when it is stale or when it resolves, so a prompt can
* never present an unresolvable pointer as proof.
*/
export function renderCharacterEvolutionForPrompt(evolution, refs = {}) {
if (!evolution || typeof evolution !== 'object') return null;
const outcome = EVOLUTION_OUTCOMES.includes(evolution.outcome) ? evolution.outcome : 'undeclared';
const note = isStr(evolution.outcomeNote) && evolution.outcomeNote ? ` — ${evolution.outcomeNote}` : '';
// Materialize the ref sets ONCE rather than per stage — a caller that hands
// in arrays would otherwise rebuild the same Sets five times per lens.
const resolved = Object.fromEntries(RESOLVABLE_ANCHORS
.map(([, refsKey]) => [refsKey, asSet(refs[refsKey])])
.filter(([, known]) => known));
const stageLines = [];
for (const stage of Array.isArray(evolution.stages) ? evolution.stages : []) {
if (!stage || typeof stage !== 'object') continue;
const parts = [];
for (const field of EVOLUTION_STAGE_TEXT_FIELDS) {
if (stage[field]) parts.push(`${STAGE_FIELD_LABELS[field]}: ${stage[field]}`);
}
const status = evolutionEvidenceStatus(stage.evidence, resolved);
if (status !== 'unanchored') parts.push(`evidence: ${describeEvidence(stage.evidence)} [${status}]`);
stageLines.push(` ${EVOLUTION_STAGE_LABELS[stage.stageId] || stage.stageId}: ${parts.join('; ') || '(not yet authored)'}`);
}
// A lens with a declared outcome but no stages is still worth rendering —
// the declaration is the part a review must not mistake for a gap. A lens
// with neither is nothing at all (and the sanitizer would have dropped it).
if (!stageLines.length && outcome === 'undeclared' && !note) return null;
return [`declared outcome: ${outcome}${note}`, ...stageLines].join('\n');
}
/**
* Render every authored lens in a per-character LIST as one prompt block, or
* `null` when nothing in the list carries one.
*
* Both hosts keep a per-character list — `series.characterArcs[]` on the
* pipeline side, `loom.seriesPlan.characterEvolutions[]` on the FableLoom side
* — and each needs the same nesting, the same "null, not ''" contract (which
* is what keeps a consumer's `{{#characterEvolution*}}` section empty and its
* behavior byte-identical to pre-lens), and the same per-entry evidence
* resolution. Written once here rather than per host, because the rule that
* differs is only WHERE the reference sets come from.
*
* `refs` is either one reference-set object shared by every entry (FableLoom:
* episode ids and scene keys are loom-wide) or a function called per entry to
* derive its own (pipeline: a lens resolves against ITS OWN arc's transition
* beats, never the whole cast's).
*/
export function renderCharacterEvolutionListForPrompt(list, refs = {}) {
if (!Array.isArray(list)) return null;
const refsFor = typeof refs === 'function' ? refs : () => refs;
const blocks = [];
for (const entry of list) {
if (!entry || typeof entry !== 'object') continue;
const lens = renderCharacterEvolutionForPrompt(entry.evolution, refsFor(entry));
if (!lens) continue;
const name = entry.characterName || '(unnamed character)';
// Indent the lens body under its character so a multi-character block stays
// readable — the renderer already indents stage lines two spaces relative
// to the outcome line, and this preserves that nesting.
blocks.push(`- ${name}\n${lens.split('\n').map((line) => ` ${line}`).join('\n')}`);
}
return blocks.length ? blocks.join('\n') : null;
}