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
/**
* FableLoom record lifecycle — looms, episodes, scene nodes, and intent
* transitions.
*
* A loom is a branching-narrative story: episodes hold a directed graph of
* scene nodes; each node carries prose, image and single-clip video prompts,
* camera direction, rendered media, and a list of intent-triggered transitions
* the play LLM matches against free-text reader input. Legacy nodes without a
* video prompt still render from scene text. All ids are server-minted. Every
* write funnels through `mutateLoom` (per-record write queue + full re-sanitize),
* so a malformed mutation can never persist.
*/
import { sanitizeShot } from '../../lib/fableLoomShots.js';
import { randomUUID } from 'crypto';
import { ServerError } from '../../lib/errorHandler.js';
import { sanitizeLlmRoutePin } from '../../lib/llmRoutePin.js';
import { sanitizeCharacterEvolutionList } from '../../lib/characterEvolution.js';
import { sanitizeSeriesDesign } from '../../lib/storyArc.js';
import { compareNewerWins } from '../../lib/lwwTimestamp.js';
import { sanitizeSoftDeleteFields } from '../../lib/syncWire.js';
import {
contentHashForRecord,
deleteSyncBaseHash,
flushBaseHashes,
maybeJournalBeforeOverwrite,
setSyncBaseHash,
withBaseHashFlushBatch,
} from '../../lib/conflictJournal.js';
import { getUniverse } from '../universeBuilder.js';
import { getSeries } from '../pipeline/series.js';
import {
autoSubscribeRecordToAllPeers,
emitRecordDeleted,
emitRecordUpdated,
} from '../sharing/recordEvents.js';
import {
deleteRaw,
isValidLoomId,
listRaw,
listTombstoneIdsBefore,
queueLoomWrite,
readRaw,
writeRaw,
} from './store.js';
import { LOOM_LIMITS } from './limits.js';
import { asLoomFormat, isLoomFormat } from './formats.js';
import {
asFableLoomPlaybackMode,
FABLELOOM_PROTAGONIST_PRESENCE,
isSafeVideoHistoryId,
sanitizeInteractionWindow,
sanitizePlaybackAssets,
sanitizeVisualConditioning,
} from '../../lib/fableLoomPlayback.js';
import {
FABLELOOM_LEGACY_PARTICIPATION_MODE,
asFableLoomAudienceConnection,
asFableLoomParticipationMode,
} from '../../lib/fableLoomParticipation.js';
import { normalizeFableLoomCameraMovement } from '../../lib/fableLoomCameraMovements.js';
import {
analyzeStoryOutline,
analyzeStoryOutlineTeleplaySync,
FABLELOOM_CHALLENGE_PHASES,
fableLoomEpisodeChallenges,
fableLoomPlotPointKind,
sanitizeStoryOutline,
} from '../../lib/fableLoomOutline.js';
import {
FABLELOOM_RENDER_PREFERENCE_KEYS,
mergeFableLoomRenderSettings,
sanitizeFableLoomRenderSettings,
} from '../../lib/fableLoomProduction.js';
import { isStr, trimTo } from '../../lib/textUtils.js';
export { LOOM_LIMITS };
const isSafeImageFilename = (value) =>
typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]*\.(png|jpg|jpeg|webp)$/i.test(value);
const nullableRef = (value) => (isStr(value) && value.trim() ? value.trim().slice(0, LOOM_LIMITS.REF_ID_MAX) : null);
const sanitizePos = (raw) => (raw && typeof raw === 'object'
&& Number.isFinite(raw.x) && Number.isFinite(raw.y)
? { x: Math.round(raw.x), y: Math.round(raw.y) }
: null);
const sanitizeVisualCanon = (raw) => {
if (!raw || typeof raw !== 'object') return null;
const appearances = (Array.isArray(raw.characterAppearances) ? raw.characterAppearances : [])
.filter((item) => item && typeof item === 'object' && nullableRef(item.characterId))
.slice(0, LOOM_LIMITS.VISUAL_BINDINGS_MAX)
.map((item) => ({
characterId: nullableRef(item.characterId),
wardrobeId: nullableRef(item.wardrobeId),
...(isSafeImageFilename(item.referenceImage) ? { referenceImage: item.referenceImage } : {}),
expression: trimTo(item.expression, LOOM_LIMITS.VISUAL_NOTE_MAX),
continuityNotes: trimTo(item.continuityNotes, LOOM_LIMITS.VISUAL_NOTE_MAX),
}));
return {
mode: raw.mode === 'draft' ? 'draft' : 'locked',
characterAppearances: appearances,
placeId: nullableRef(raw.placeId),
objectIds: (Array.isArray(raw.objectIds) ? raw.objectIds : [])
.map(nullableRef).filter(Boolean).slice(0, LOOM_LIMITS.VISUAL_BINDINGS_MAX),
continuitySourceNodeId: nullableRef(raw.continuitySourceNodeId),
shotNotes: trimTo(raw.shotNotes, LOOM_LIMITS.VISUAL_NOTE_MAX),
storyboardImageApproved: raw.storyboardImageApproved === true,
};
};
function sanitizeTransition(raw) {
if (!raw || typeof raw !== 'object') return null;
const intent = trimTo(raw.intent, LOOM_LIMITS.INTENT_MAX);
const targetNodeId = isStr(raw.targetNodeId) ? raw.targetNodeId : '';
if (!targetNodeId) return null;
return {
id: isStr(raw.id) && raw.id ? raw.id : `tr-${randomUUID()}`,
targetNodeId,
intent,
triggers: (Array.isArray(raw.triggers) ? raw.triggers : [])
.map((t) => trimTo(t, LOOM_LIMITS.TRIGGER_MAX))
.filter(Boolean)
.slice(0, LOOM_LIMITS.TRIGGERS_MAX),
description: trimTo(raw.description, LOOM_LIMITS.TRANSITION_DESC_MAX),
};
}
function sanitizeNode(raw) {
if (!raw || typeof raw !== 'object' || !isStr(raw.id) || !raw.id) return null;
return {
id: raw.id,
title: trimTo(raw.title, LOOM_LIMITS.NODE_TITLE_MAX),
prose: trimTo(raw.prose, LOOM_LIMITS.PROSE_MAX),
...(raw.shot ? { shot: sanitizeShot(raw.shot) } : {}),
plotPointId: isStr(raw.plotPointId)
? raw.plotPointId.trim().slice(0, LOOM_LIMITS.OUTLINE_KEY_MAX)
: null,
challengePhase: FABLELOOM_CHALLENGE_PHASES.includes(raw.challengePhase)
? raw.challengePhase
: null,
imagePrompt: trimTo(raw.imagePrompt, LOOM_LIMITS.IMAGE_PROMPT_MAX),
image: isSafeImageFilename(raw.image) ? raw.image : null,
imageJobId: isStr(raw.imageJobId) && raw.imageJobId ? raw.imageJobId.slice(0, 200) : null,
videoPrompt: trimTo(raw.videoPrompt, LOOM_LIMITS.VIDEO_PROMPT_MAX),
cameraMovement: trimTo(normalizeFableLoomCameraMovement(raw.cameraMovement), LOOM_LIMITS.CAMERA_MOVEMENT_MAX),
visualCanon: sanitizeVisualCanon(raw.visualCanon),
visualConditioning: sanitizeVisualConditioning(raw.visualConditioning),
playbackMode: asFableLoomPlaybackMode(raw.playbackMode),
audienceConnection: asFableLoomAudienceConnection(raw.audienceConnection),
protagonistPresence: FABLELOOM_PROTAGONIST_PRESENCE.includes(raw.protagonistPresence)
? raw.protagonistPresence
: null,
videoHistoryId: isSafeVideoHistoryId(raw.videoHistoryId) ? raw.videoHistoryId : null,
playbackAssets: sanitizePlaybackAssets(raw.playbackAssets),
interactionWindow: sanitizeInteractionWindow(raw.interactionWindow),
isEnding: raw.isEnding === true,
// The format this scene's text is actually WRITTEN in — server-set, not
// patchable. `null` means unknown (authored before the field existed, or
// by hand), which a reformat treats as "needs converting". Without it a
// rewrite that stopped at the per-request ceiling would re-send the scenes
// it already converted and never reach the ones it didn't.
format: isLoomFormat(raw.format) ? raw.format : null,
endingLabel: trimTo(raw.endingLabel, LOOM_LIMITS.ENDING_LABEL_MAX),
transitions: (Array.isArray(raw.transitions) ? raw.transitions : [])
.map(sanitizeTransition)
.filter(Boolean)
.slice(0, LOOM_LIMITS.TRANSITIONS_MAX),
pos: sanitizePos(raw.pos),
};
}
function sanitizeEpisode(raw, participationMode = 'protagonist') {
if (!raw || typeof raw !== 'object' || !isStr(raw.id) || !raw.id) return null;
const nodes = (Array.isArray(raw.nodes) ? raw.nodes : [])
.map(sanitizeNode)
.filter(Boolean)
.slice(0, LOOM_LIMITS.NODES_MAX);
const nodeIds = new Set(nodes.map((n) => n.id));
// Dangling transitions (a target dropped by the node cap, or authored to a
// since-deleted id) are deliberately KEPT — the graph validation surfaces
// them as errors the author resolves, rather than silently rewriting edges.
const now = new Date().toISOString();
const storyOutline = sanitizeStoryOutline(raw.storyOutline, { participationMode });
return {
id: raw.id,
number: Number.isFinite(raw.number) ? Math.max(1, Math.round(raw.number)) : 1,
title: trimTo(raw.title, LOOM_LIMITS.EPISODE_TITLE_MAX),
synopsis: trimTo(raw.synopsis, LOOM_LIMITS.SYNOPSIS_MAX),
startNodeId: isStr(raw.startNodeId) && nodeIds.has(raw.startNodeId) ? raw.startNodeId : (nodes[0]?.id ?? null),
nodes,
...(storyOutline ? { storyOutline } : {}),
createdAt: isStr(raw.createdAt) && raw.createdAt ? raw.createdAt : now,
updatedAt: isStr(raw.updatedAt) && raw.updatedAt ? raw.updatedAt : now,
};
}
const planItemId = (prefix, value, seenIds) => {
const candidate = isStr(value) && value.trim() ? value.trim().slice(0, 80) : '';
const id = candidate && !seenIds.has(candidate) ? candidate : `${prefix}-${randomUUID()}`;
seenIds.add(id);
return id;
};
const planEpisodeRef = (value, episodeIds) => (
isStr(value) && episodeIds.has(value) ? value : null
);
function sanitizeSeriesPlan(raw, episodes) {
const source = raw && typeof raw === 'object' ? raw : {};
const episodeIds = new Set(episodes.map((episode) => episode.id));
const plotIds = new Set();
const questIds = new Set();
const hasDeliveryPlan = source.deliveryOptions && typeof source.deliveryOptions === 'object'
|| Array.isArray(source.interEpisodeVoicemails)
|| source.nextSeasonTeaser !== undefined;
const deliveryOptions = source.deliveryOptions && typeof source.deliveryOptions === 'object'
? {
overnightVoicemails: source.deliveryOptions.overnightVoicemails === true,
nextSeasonTeaser: source.deliveryOptions.nextSeasonTeaser === true,
}
: { overnightVoicemails: false, nextSeasonTeaser: false };
const voicemailIds = new Set();
const interEpisodeVoicemails = (Array.isArray(source.interEpisodeVoicemails)
? source.interEpisodeVoicemails : [])
.slice(0, LOOM_LIMITS.EPISODES_MAX)
.filter((item) => item && typeof item === 'object')
.map((item) => ({
id: planItemId('voicemail', item.id, voicemailIds),
fromEpisodeId: planEpisodeRef(item.fromEpisodeId, episodeIds),
toEpisodeId: planEpisodeRef(item.toEpisodeId, episodeIds),
title: trimTo(item.title, LOOM_LIMITS.PLAN_ITEM_TITLE_MAX),
transcript: trimTo(item.transcript, LOOM_LIMITS.DELIVERY_MESSAGE_MAX),
}));
const teaser = source.nextSeasonTeaser && typeof source.nextSeasonTeaser === 'object'
? {
title: trimTo(source.nextSeasonTeaser.title, LOOM_LIMITS.PLAN_ITEM_TITLE_MAX),
transcript: trimTo(source.nextSeasonTeaser.transcript, LOOM_LIMITS.DELIVERY_MESSAGE_MAX),
}
: null;
// The OPTIONAL five-stage character evolution lens (#6440), one per
// character, keyed by the canon `chr-` id. Evidence anchors (episodeId /
// sceneKey) are PRESERVED as authored even when they no longer resolve —
// `fableLoomEvolutionEvidenceRefs` lets a reader derive `stale` on read,
// the same way `sanitizeStoryOutline` keeps an unknown `targetKey` so
// DANGLING_TRANSITION can report it. Absent on every pre-#6440 plan.
const characterEvolutions = sanitizeCharacterEvolutionList(source.characterEvolutions);
const seriesDesign = sanitizeSeriesDesign(source.seriesDesign);
return {
storyArc: trimTo(source.storyArc, LOOM_LIMITS.STORY_ARC_MAX),
plotPoints: (Array.isArray(source.plotPoints) ? source.plotPoints : [])
.filter((item) => item && typeof item === 'object')
.slice(0, LOOM_LIMITS.PLAN_ITEMS_MAX)
.map((item) => ({
id: planItemId('plot', item.id, plotIds),
kind: fableLoomPlotPointKind(item),
title: trimTo(item.title, LOOM_LIMITS.PLAN_ITEM_TITLE_MAX),
description: trimTo(item.description, LOOM_LIMITS.PLAN_ITEM_DESCRIPTION_MAX),
episodeId: planEpisodeRef(item.episodeId, episodeIds),
})),
sideQuests: (Array.isArray(source.sideQuests) ? source.sideQuests : [])
.filter((item) => item && typeof item === 'object')
.slice(0, LOOM_LIMITS.PLAN_ITEMS_MAX)
.map((item) => ({
id: planItemId('quest', item.id, questIds),
title: trimTo(item.title, LOOM_LIMITS.PLAN_ITEM_TITLE_MAX),
description: trimTo(item.description, LOOM_LIMITS.PLAN_ITEM_DESCRIPTION_MAX),
status: ['idea', 'planned', 'active', 'resolved'].includes(item.status) ? item.status : 'idea',
startEpisodeId: planEpisodeRef(item.startEpisodeId, episodeIds),
endEpisodeId: planEpisodeRef(item.endEpisodeId, episodeIds),
})),
...(hasDeliveryPlan ? {
deliveryOptions,
interEpisodeVoicemails,
nextSeasonTeaser: teaser,
} : {}),
// Omitted entirely when no lens is authored, so a pre-#6440 plan is
// byte-identical after a round trip (same shape rule the delivery plan
// above follows) and `preserveLegacyCharacterEvolutions` can tell "this
// sender cannot represent the field" from "the author cleared it".
...(characterEvolutions.length ? { characterEvolutions } : {}),
// Keep legacy omission byte-identical while preserving an explicit null as
// a clear on current-version records and sync payloads.
...(source.seriesDesign !== undefined ? { seriesDesign } : {}),
};
}
/**
* Reference sets a FableLoom evolution lens's evidence anchors resolve
* against — every episode id, and every scene an anchor can name across the
* loom: expanded teleplay node ids AND authored outline keys. The sync
* contract makes those the same string once an outline is expanded, so the
* union only widens for a graph-first episode whose outline was never written
* — where a live scene must not read as a deleted one.
* Hand it to `evolutionEvidenceStatus` so a stage pointing at a deleted
* episode or a renamed scene reports `stale` rather than passing as proof.
*/
export function fableLoomEvolutionEvidenceRefs(loom) {
const episodes = Array.isArray(loom?.episodes) ? loom.episodes : [];
const sceneKeys = new Set();
for (const episode of episodes) {
for (const node of episode?.nodes || []) {
if (node?.id) sceneKeys.add(node.id);
}
for (const scene of episode?.storyOutline?.scenes || []) {
if (scene?.key) sceneKeys.add(scene.key);
}
}
return { episodeIds: new Set(episodes.map((episode) => episode.id)), sceneKeys };
}
export function sanitizeLoom(raw) {
if (!raw || typeof raw !== 'object') return null;
if (!isStr(raw.id) || !raw.id) return null;
const name = trimTo(raw.name, LOOM_LIMITS.NAME_MAX);
if (!name) return null;
const now = new Date().toISOString();
const { deleted, deletedAt } = sanitizeSoftDeleteFields(raw);
const participationMode = asFableLoomParticipationMode(raw.participationMode);
const episodes = (Array.isArray(raw.episodes) ? raw.episodes : [])
.map((episode) => sanitizeEpisode(episode, participationMode))
.filter(Boolean)
.slice(0, LOOM_LIMITS.EPISODES_MAX)
.sort((a, b) => a.number - b.number || a.createdAt.localeCompare(b.createdAt));
const seriesPlan = sanitizeSeriesPlan(raw.seriesPlan, episodes);
for (const episode of episodes) {
if (episode.storyOutline?.validation?.status !== 'valid') continue;
const outline = analyzeStoryOutline(episode.storyOutline, {
participationMode,
requireAudienceIntroduction: episode === episodes[0],
challenges: fableLoomEpisodeChallenges({ seriesPlan }, episode.id),
});
if (outline.stats.errorCount > 0) {
episode.storyOutline.validation = { status: 'invalid', issues: outline.issues };
continue;
}
const sync = analyzeStoryOutlineTeleplaySync(episode, episode.storyOutline, {
participationMode,
});
if (!sync.stats.matches) {
episode.storyOutline.validation = { status: 'draft', issues: sync.issues };
}
}
const protagonistCharacterId = nullableRef(raw.protagonistCharacterId);
const protagonistWardrobeId = nullableRef(raw.protagonistWardrobeId);
const productionStatus = raw.productionStatus && typeof raw.productionStatus === 'object'
? {
editorialApprovedAt: isStr(raw.productionStatus.editorialApprovedAt)
? raw.productionStatus.editorialApprovedAt.slice(0, 80)
: null,
editorialApprovalSource: ['manual', 'autopilot'].includes(raw.productionStatus.editorialApprovalSource)
? raw.productionStatus.editorialApprovalSource
: null,
deliveryApprovedAt: isStr(raw.productionStatus.deliveryApprovedAt)
? raw.productionStatus.deliveryApprovedAt.slice(0, 80)
: null,
}
: {
editorialApprovedAt: null,
editorialApprovalSource: null,
deliveryApprovedAt: null,
};
return {
id: raw.id,
schemaVersion: 3,
name,
logline: trimTo(raw.logline, LOOM_LIMITS.LOGLINE_MAX),
premise: trimTo(raw.premise, LOOM_LIMITS.PREMISE_MAX),
styleNotes: trimTo(raw.styleNotes, LOOM_LIMITS.STYLE_NOTES_MAX),
participationMode,
audienceCommunicationMedium: trimTo(
raw.audienceCommunicationMedium,
LOOM_LIMITS.AUDIENCE_COMMUNICATION_MEDIUM_MAX,
),
format: asLoomFormat(raw.format),
// The loom's route pin for the play stage — which provider/model/effort
// turns a reader's free text into a path. An unset dimension stays null
// ('fall through to the stage pin / active provider').
playSettings: sanitizeLlmRoutePin(raw.playSettings),
renderSettings: sanitizeFableLoomRenderSettings(raw.renderSettings),
protagonistCharacterId,
protagonistWardrobeId,
protagonistWardrobeLocked: Boolean(protagonistWardrobeId && raw.protagonistWardrobeLocked !== false),
universeId: nullableRef(raw.universeId),
seriesId: nullableRef(raw.seriesId),
seriesPlan,
productionStatus,
episodes,
createdAt: isStr(raw.createdAt) && raw.createdAt ? raw.createdAt : now,
updatedAt: isStr(raw.updatedAt) && raw.updatedAt ? raw.updatedAt : now,
deleted,
deletedAt,
};
}
const editorialVisualCanon = (visualCanon) => {
if (!visualCanon) return null;
const { storyboardImageApproved: _storyboardImageApproved, ...storyCanon } = visualCanon;
return storyCanon;
};
// Approval invalidation is content-aware: authoring edits reopen editorial and
// final delivery, while a completed render only reopens delivery. This avoids
// using loom.updatedAt as a proxy, because media completion also updates it.
const editorialContentSignature = (loom) => JSON.stringify({
name: loom.name,
logline: loom.logline,
premise: loom.premise,
styleNotes: loom.styleNotes,
participationMode: loom.participationMode,
audienceCommunicationMedium: loom.audienceCommunicationMedium,
format: loom.format,
protagonistCharacterId: loom.protagonistCharacterId,
protagonistWardrobeId: loom.protagonistWardrobeId,
protagonistWardrobeLocked: loom.protagonistWardrobeLocked,
universeId: loom.universeId,
seriesId: loom.seriesId,
seriesPlan: loom.seriesPlan,
episodes: loom.episodes.map((episode) => ({
id: episode.id,
number: episode.number,
title: episode.title,
synopsis: episode.synopsis,
startNodeId: episode.startNodeId,
storyOutline: episode.storyOutline ? {
version: episode.storyOutline.version,
startKey: episode.storyOutline.startKey,
scenes: episode.storyOutline.scenes,
} : null,
nodes: episode.nodes.map((node) => ({
id: node.id,
title: node.title,
prose: node.prose,
shot: node.shot,
plotPointId: node.plotPointId,
challengePhase: node.challengePhase,
imagePrompt: node.imagePrompt,
videoPrompt: node.videoPrompt,
cameraMovement: node.cameraMovement,
visualCanon: editorialVisualCanon(node.visualCanon),
playbackMode: node.playbackMode,
audienceConnection: node.audienceConnection,
protagonistPresence: node.protagonistPresence,
interactionWindow: node.interactionWindow,
isEnding: node.isEnding,
format: node.format,
endingLabel: node.endingLabel,
transitions: node.transitions,
})),
})),
});
const deliveryContentSignature = (loom) => JSON.stringify({
renderSettings: loom.renderSettings,
episodes: loom.episodes.map((episode) => ({
id: episode.id,
nodes: episode.nodes.map((node) => ({
id: node.id,
image: node.image,
imageJobId: node.imageJobId,
videoHistoryId: node.videoHistoryId,
playbackAssets: node.playbackAssets,
visualConditioning: node.visualConditioning,
storyboardImageApproved: node.visualCanon?.storyboardImageApproved === true,
})),
})),
});
const notFound = (what = 'Loom') => new ServerError(`${what} not found`, { status: 404, code: 'NOT_FOUND' });
// Soft refs are validated at write time (against the trimmed value that will
// actually persist) so a typo'd id fails loudly here rather than silently
// producing an empty canon digest at weave time. Lives in the service — not
// the route — because createLoom/updateLoom are public barrel exports any
// non-HTTP caller can reach (games' requireApp precedent).
async function assertRefsExist({ universeId, seriesId } = {}) {
const [universe, series] = await Promise.all([
universeId ? getUniverse(universeId).catch(() => null) : null,
seriesId ? getSeries(seriesId).catch(() => null) : null,
]);
if (universeId && !universe) {
throw new ServerError('Linked universe not found', { status: 400, code: 'INVALID_UNIVERSE' });
}
if (seriesId && !series) {
throw new ServerError('Linked series not found', { status: 400, code: 'INVALID_SERIES' });
}
}
const requireLoomRaw = async (id) => {
if (!isValidLoomId(id)) throw notFound();
const loom = sanitizeLoom(await readRaw(id));
if (!loom || loom.deleted) throw notFound();
return loom;
};
export async function listLooms({ includeDeleted = false } = {}) {
const records = (await listRaw()).map(sanitizeLoom).filter(Boolean);
const visible = includeDeleted ? records : records.filter((loom) => !loom.deleted);
return visible.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.name.localeCompare(b.name));
}
/**
* Index-page projection: everything the list UI shows, WITHOUT the episode
* graphs — a woven episode carries up to 20k chars of prose per node, so the
* full records would make the index multi-MB to render three counts.
*
* `seriesId` scopes the list to one pipeline series' linked looms. The link is
* a soft ref, so a series that no longer exists simply matches nothing — this
* never throws on a dangling id.
*/
export async function listLoomSummaries({ seriesId: scopeSeriesId } = {}) {
const looms = await listLooms();
const scoped = scopeSeriesId ? looms.filter((loom) => loom.seriesId === scopeSeriesId) : looms;
return scoped.map(({
id, name, logline, format, participationMode, audienceCommunicationMedium,
universeId, seriesId, createdAt, updatedAt, episodes,
}) => ({
id,
name,
logline,
format,
participationMode,
audienceCommunicationMedium,
universeId,
seriesId,
createdAt,
updatedAt,
episodeCount: episodes.length,
sceneCount: episodes.reduce((sum, e) => sum + e.nodes.length, 0),
endingCount: episodes.reduce((sum, e) => sum + e.nodes.filter((n) => n.isEnding).length, 0),
}));
}
export async function getLoom(id, { includeDeleted = false } = {}) {
if (!isValidLoomId(id)) return null;
const loom = sanitizeLoom(await readRaw(id));
return loom && (includeDeleted || !loom.deleted) ? loom : null;
}
const assertParticipationConfigured = ({ participationMode, audienceCommunicationMedium }) => {
if (asFableLoomParticipationMode(participationMode) === 'helper'
&& !trimTo(audienceCommunicationMedium, LOOM_LIMITS.AUDIENCE_COMMUNICATION_MEDIUM_MAX)) {
throw new ServerError('Helper stories need an audience communication medium', {
status: 400,
code: 'AUDIENCE_MEDIUM_REQUIRED',
});
}
};
export async function createLoom({
name, logline, premise, styleNotes, format, playSettings, renderSettings, seriesPlan,
protagonistCharacterId, protagonistWardrobeId, protagonistWardrobeLocked,
participationMode = FABLELOOM_LEGACY_PARTICIPATION_MODE,
audienceCommunicationMedium, universeId, seriesId,
} = {}) {
const now = new Date().toISOString();
assertParticipationConfigured({ participationMode, audienceCommunicationMedium });
await assertRefsExist({ universeId: nullableRef(universeId), seriesId: nullableRef(seriesId) });
const loom = sanitizeLoom({
id: `loom-${randomUUID()}`,
name,
logline,
premise,
styleNotes,
participationMode,
audienceCommunicationMedium,
format,
playSettings,
renderSettings,
protagonistCharacterId,
protagonistWardrobeId,
protagonistWardrobeLocked,
seriesPlan,
universeId,
seriesId,
episodes: [],
createdAt: now,
updatedAt: now,
});
if (!loom) throw new ServerError('Loom needs a name', { status: 400, code: 'VALIDATION_ERROR' });
await writeRaw(loom.id, loom);
emitRecordUpdated('fableLoom', loom.id);
autoSubscribeRecordToAllPeers('fableLoom', loom.id).catch(() => {});
return loom;
}
/**
* Serialized read-modify-write. `mutator(current)` returns the changed record
* (or a falsy value to skip the write). The result is re-sanitized before
* persisting so a mutation can never store a malformed record.
*/
export async function mutateLoom(id, mutator) {
if (!isValidLoomId(id)) throw notFound();
const result = await queueLoomWrite(id, async () => {
const current = await requireLoomRaw(id);
const currentEditorialSignature = editorialContentSignature(current);
const currentDeliverySignature = deliveryContentSignature(current);
const changed = await mutator(current);
if (!changed) return { loom: current, changed: false };
const next = sanitizeLoom({ ...changed, id, updatedAt: new Date().toISOString() });
if (!next) throw new ServerError('Invalid loom record', { status: 400, code: 'VALIDATION_ERROR' });
const editorialChanged = editorialContentSignature(next) !== currentEditorialSignature;
const deliveryChanged = deliveryContentSignature(next) !== currentDeliverySignature;
if (editorialChanged) {
next.productionStatus.editorialApprovedAt = null;
next.productionStatus.editorialApprovalSource = null;
next.productionStatus.deliveryApprovedAt = null;
} else if (deliveryChanged) {
next.productionStatus.deliveryApprovedAt = null;
}
await writeRaw(id, next);
return { loom: next, changed: true };
});
if (result.changed) emitRecordUpdated('fableLoom', id);
return result.loom;
}
const PATCH_FIELDS = [
'name', 'logline', 'premise', 'styleNotes', 'format', 'playSettings', 'renderSettings', 'seriesPlan',
'productionStatus',
'protagonistCharacterId', 'protagonistWardrobeId', 'protagonistWardrobeLocked',
'participationMode', 'audienceCommunicationMedium', 'universeId', 'seriesId',
];
const RESTORABLE_FIELDS = [
'name', 'logline', 'premise', 'styleNotes', 'format', 'playSettings', 'renderSettings', 'seriesPlan',
'productionStatus',
'protagonistCharacterId', 'protagonistWardrobeId', 'protagonistWardrobeLocked',
'participationMode', 'audienceCommunicationMedium', 'episodes',
];
export async function updateLoom(id, patch = {}) {
await assertRefsExist({
universeId: 'universeId' in patch ? nullableRef(patch.universeId) : null,
seriesId: 'seriesId' in patch ? nullableRef(patch.seriesId) : null,
});
return mutateLoom(id, (loom) => {
const next = { ...loom };
for (const key of PATCH_FIELDS) {
if (key in patch) {
next[key] = key === 'renderSettings'
? mergeFableLoomRenderSettings(loom.renderSettings, patch[key])
: patch[key];
}
}
assertParticipationConfigured(next);
return next;
});
}
/** Reapply a conflict snapshot through the normal mutation/push lifecycle. */
export function restoreLoom(id, patch = {}) {
return mutateLoom(id, (loom) => {
const next = { ...loom };
for (const key of RESTORABLE_FIELDS) {
if (key in patch) {
next[key] = key === 'renderSettings'
? mergeFableLoomRenderSettings(loom.renderSettings, patch[key])
: patch[key];
}
}
assertParticipationConfigured(next);
return next;
});
}
export async function deleteLoom(id) {
if (!isValidLoomId(id)) throw notFound();
await queueLoomWrite(id, async () => {
const current = await requireLoomRaw(id);
const now = new Date().toISOString();
await writeRaw(id, sanitizeLoom({
...current,
deleted: true,
deletedAt: now,
updatedAt: now,
}));
});
emitRecordDeleted('fableLoom', id);
}
// Episode beat outlines arrived with schema v4, alongside the series delivery
// plan. A <=v3 sender round-trips the record through an outline-unaware
// sanitizer, so an absent outline there means "cannot represent" rather than
// "the author deleted it" — restore the local one whole. A v4 sender knows the
// outline but not the v5 plot-point/challenge mapping on its scenes, so its
// outline wins except for those two per-scene fields.
const preserveLegacyStoryOutline = (episode, localEpisode, senderVersion) => {
if (!episode.storyOutline) {
return senderVersion < 4 && localEpisode?.storyOutline
? { storyOutline: localEpisode.storyOutline }
: {};
}
if (senderVersion >= 5) return {};
const localScenes = new Map((localEpisode?.storyOutline?.scenes || [])
.map((scene) => [scene.key, scene]));
return {
storyOutline: {
...episode.storyOutline,
scenes: episode.storyOutline.scenes.map((scene) => ({
...scene,
...(localScenes.has(scene.key) ? {
plotPointId: localScenes.get(scene.key).plotPointId,
challengePhase: localScenes.get(scene.key).challengePhase,
} : {}),
})),
},
};
};
// The series delivery plan (overnight voicemails, inter-episode voicemails, and
// the next-season teaser) also arrived with v4. `sanitizeSeriesPlan` omits the
// three keys entirely when a record predates the feature, so a <=v3 sender that
// omits them means "cannot represent" and the local plan must survive. A v4+
// sender that omits them describes a record with genuinely no delivery plan.
const preserveLegacyDeliveryPlan = (remotePlan, localPlan, senderVersion) => (
senderVersion < 4
&& localPlan
&& Object.prototype.hasOwnProperty.call(localPlan, 'deliveryOptions')
&& !Object.prototype.hasOwnProperty.call(remotePlan || {}, 'deliveryOptions')
? {
deliveryOptions: localPlan.deliveryOptions,
interEpisodeVoicemails: localPlan.interEpisodeVoicemails,
nextSeasonTeaser: localPlan.nextSeasonTeaser,
}
: {}
);
// The per-character evolution lens (#6440) arrived with v8. `sanitizeSeriesPlan`
// omits the key entirely when a plan has none, so a <=v7 sender that omits it
// means "cannot represent" and the local lenses must survive; a v8+ sender that
// omits it describes a plan whose lenses were genuinely cleared. Same shape as
// preserveLegacyDeliveryPlan above — without it, one sync from a not-yet-
// upgraded peer silently drops every authored lens and LWWs the loss back.
const preserveLegacyCharacterEvolutions = (remotePlan, localPlan, senderVersion) => (
senderVersion < 8
&& localPlan
&& Object.prototype.hasOwnProperty.call(localPlan, 'characterEvolutions')
&& !Object.prototype.hasOwnProperty.call(remotePlan || {}, 'characterEvolutions')
? { characterEvolutions: localPlan.characterEvolutions }
: {}
);
// The shared author-owned series brief arrived with v9. A pre-v9 sender's
// omission means it cannot represent the field; a v9 sender's omission is the
// wholesale series-plan PATCH clear used by the local editor.
const preserveLegacySeriesDesign = (remotePlan, localPlan, senderVersion) => (
senderVersion < 9
&& localPlan
&& Object.prototype.hasOwnProperty.call(localPlan, 'seriesDesign')
&& !Object.prototype.hasOwnProperty.call(remotePlan || {}, 'seriesDesign')
? { seriesDesign: localPlan.seriesDesign }
: {}
);
// Everything an older sender cannot represent inside `seriesPlan`, in one
// place: the v4 delivery plan, the v5 plot-point kinds, the v8 evolution
// lenses, and the v9 series design. Returns `remote` BY REFERENCE when there is
// nothing to restore, so the common merge allocates no copy.
const preserveLegacySeriesPlan = (remote, local, senderVersion) => {
const evolutions = preserveLegacyCharacterEvolutions(remote, local, senderVersion);
const seriesDesign = preserveLegacySeriesDesign(remote, local, senderVersion);
if (senderVersion >= 5) {
return evolutions.characterEvolutions || seriesDesign.seriesDesign !== undefined
? { ...remote, ...evolutions, ...seriesDesign }
: remote;
}
const localPlotPoints = new Map((local?.plotPoints || []).map((item) => [item.id, item]));
return {
...remote,
...preserveLegacyDeliveryPlan(remote, local, senderVersion),
plotPoints: (remote?.plotPoints || []).map((item) => ({
...item,
...(localPlotPoints.has(item.id) ? { kind: localPlotPoints.get(item.id).kind } : {}),
})),
// Last, so the key lands where `sanitizeSeriesPlan` puts it — this merge
// result is persisted without a re-sanitize.
...evolutions,
...seriesDesign,
};
};
// An older peer cannot represent newer scene production fields. When that
// peer wins whole-record LWW after an unrelated edit, retain the local fields
// on nodes that still exist instead of letting its unaware sanitizer clear
// them. A sender at the current schema version's present null remains an
// intentional clear.
const preserveLegacyVisualProduction = (remote, local, senderVersion) => {
if (!local || senderVersion >= 9) return remote;
const seriesPlan = preserveLegacySeriesPlan(remote.seriesPlan, local.seriesPlan, senderVersion);
// A v7/v8 sender's only unrepresentable plan fields are restored above —
// every branch below is gated at <7 or lower. Returning early keeps the
// dominant legacy path off the O(episodes x nodes) rebuild it would all skip.
if (senderVersion >= 7) {
return seriesPlan === remote.seriesPlan ? remote : { ...remote, seriesPlan };
}
const localEpisodes = new Map(local.episodes.map((episode) => [episode.id, episode]));
return {
...remote,
...(senderVersion < 6 ? {
// v5 peers understand the aspect-ratio format but would strip the
// provider/model preferences added in v6 during an unrelated update.
renderSettings: senderVersion < 5 ? local.renderSettings : {
...remote.renderSettings,
...Object.fromEntries(FABLELOOM_RENDER_PREFERENCE_KEYS
.filter((key) => Object.prototype.hasOwnProperty.call(local.renderSettings, key))
.map((key) => [key, local.renderSettings[key]])),
},
} : {}),
...(senderVersion < 5 ? {
productionStatus: local.productionStatus,
} : {}),
seriesPlan,
...(senderVersion < 4 ? {
protagonistCharacterId: local.protagonistCharacterId,
protagonistWardrobeId: local.protagonistWardrobeId,
protagonistWardrobeLocked: local.protagonistWardrobeLocked,
} : {}),
episodes: remote.episodes.map((episode) => {
const localEpisode = localEpisodes.get(episode.id);
const localNodes = new Map((localEpisode?.nodes || []).map((node) => [node.id, node]));
return {
...episode,
...preserveLegacyStoryOutline(episode, localEpisode, senderVersion),
nodes: episode.nodes.map((node) => {
const localNode = localNodes.get(node.id);
return localNode ? {
...node,
...(senderVersion < 7 ? {
...(localNode.shot ? { shot: localNode.shot } : {}),
...(senderVersion >= 3 && node.visualCanon ? {
visualCanon: {
...node.visualCanon,
characterAppearances: node.visualCanon.characterAppearances.map((appearance) => {
const previous = localNode.visualCanon?.characterAppearances.find((item) => item.characterId === appearance.characterId);
return previous?.referenceImage ? { ...appearance, referenceImage: previous.referenceImage } : appearance;
}),
},
} : {}),
} : {}),
...(senderVersion < 5 ? {
plotPointId: localNode.plotPointId,
challengePhase: localNode.challengePhase,
} : {}),
...(senderVersion < 4 ? { protagonistPresence: localNode.protagonistPresence } : {}),
...(senderVersion < 3 ? {
visualCanon: localNode.visualCanon,
visualConditioning: localNode.visualConditioning,
playbackAssets: {
...node.playbackAssets,
...(localNode.playbackAssets?.visualConditioningByAsset
? { visualConditioningByAsset: localNode.playbackAssets.visualConditioningByAsset }
: {}),
},
} : {}),
} : node;
}),
};
}),
};
};
/**
* Merge FableLoom records received from a federated peer. Records are
* sanitized before persistence, unioned by id, and resolved by whole-record
* LWW on `updatedAt`; tombstones travel through the same path.
*/
export async function mergeLoomsFromSync(
remoteLooms,
{
source = { via: 'sync', peerId: null },
senderSchemaVersions = { fableLoom: 9 },
} = {},
) {
if (!Array.isArray(remoteLooms)) return { applied: false, count: 0 };
const byId = new Map();
for (const raw of remoteLooms) {
const remote = sanitizeLoom(raw);
if (!remote || !isValidLoomId(remote.id) || byId.has(remote.id)) continue;
byId.set(remote.id, remote);
}
let changed = 0;
for (const remote of byId.values()) {
const applied = await queueLoomWrite(remote.id, async () => {
const local = sanitizeLoom(await readRaw(remote.id));
if (local && !compareNewerWins(remote.updatedAt, local.updatedAt)) return false;
const merged = preserveLegacyVisualProduction(
remote,
local,
Number(senderSchemaVersions?.fableLoom) || 0,
);
if (local) {
await maybeJournalBeforeOverwrite({
kind: 'fableLoom', id: remote.id, local, remote: merged, source,
});
} else {
await setSyncBaseHash(
'fableLoom',
merged.id,
contentHashForRecord('fableLoom', merged),
);
}
await writeRaw(merged.id, merged);
return true;
});
if (applied) changed += 1;
}
await flushBaseHashes();
if (changed > 0) console.log(`🧶 FableLoom sync: merged ${changed} loom(s)`);
return { applied: changed > 0, count: changed };
}
/** Hard-prune tombstones only after the shared federation GC computes a safe cutoff. */
export async function pruneTombstonedLooms(olderThanMs) {
if (!Number.isFinite(olderThanMs)) return { pruned: 0 };
// Id-only candidate scan — SQL projection on Postgres, hydrate+filter on the
// file escape hatch. The sweep almost never finds a tombstone, so this must
// not pay for every loom's JSONB body (episode graphs included) just to
// find zero candidates. The authoritative re-check inside each per-id queue
// below still re-reads and re-sanitizes the record.
const candidateIds = await listTombstoneIdsBefore(olderThanMs);
let pruned = 0;
await withBaseHashFlushBatch(async () => {
for (const id of candidateIds) {
const removed = await queueLoomWrite(id, async () => {
const current = sanitizeLoom(await readRaw(id));
const deletedAtMs = Date.parse(current?.deletedAt || '');
if (!current?.deleted || !Number.isFinite(deletedAtMs) || deletedAtMs >= olderThanMs) return false;
await deleteRaw(id);
await deleteSyncBaseHash('fableLoom', id);
return true;
});
if (removed) pruned += 1;
}
});
return { pruned };
}
// --- Episodes ---------------------------------------------------------------
export const findEpisode = (loom, episodeId) => {
const episode = loom.episodes.find((e) => e.id === episodeId);
if (!episode) throw notFound('Episode');
return episode;
};
export const findNode = (episode, nodeId) => {
const node = episode.nodes.find((n) => n.id === nodeId);
if (!node) throw notFound('Scene');
return node;
};
export const findTransition = (node, transitionId) => {
const transition = (node.transitions || []).find((t) => t.id === transitionId);
if (!transition) throw notFound('Path');
return transition;
};
export function addEpisode(loomId, { title, synopsis } = {}) {
return mutateLoom(loomId, (loom) => {
if (loom.episodes.length >= LOOM_LIMITS.EPISODES_MAX) {
throw new ServerError('Episode limit reached', { status: 400, code: 'LIMIT_REACHED' });
}
const now = new Date().toISOString();
const number = loom.episodes.reduce((max, e) => Math.max(max, e.number), 0) + 1;
loom.episodes.push({
id: `ep-${randomUUID()}`,
number,
title,
synopsis,
startNodeId: null,
nodes: [],
createdAt: now,
updatedAt: now,
});
return loom;
});
}
export function updateEpisode(loomId, episodeId, patch = {}) {
return mutateLoom(loomId, (loom) => {
const episode = findEpisode(loom, episodeId);
for (const key of ['title', 'synopsis', 'number', 'startNodeId']) {
if (key in patch) episode[key] = patch[key];
}
if ('storyOutline' in patch) {
episode.storyOutline = patch.storyOutline
? { ...patch.storyOutline, validation: { status: 'draft', issues: [] } }
: null;
} else if (('title' in patch || 'synopsis' in patch) && episode.storyOutline) {
// A changed synopsis or title can change the dramatic contract the
// outline was validated against, so expansion must pass through the
// outline validation step again.
episode.storyOutline.validation = { status: 'draft', issues: [] };
}
episode.updatedAt = new Date().toISOString();
return loom;
});
}
export function deleteEpisode(loomId, episodeId) {
return mutateLoom(loomId, (loom) => {
findEpisode(loom, episodeId);
loom.episodes = loom.episodes.filter((e) => e.id !== episodeId);
return loom;
});
}
// --- Nodes & transitions ----------------------------------------------------
const NODE_PATCH_FIELDS = [
'shot',
'title', 'prose', 'plotPointId', 'challengePhase', 'imagePrompt', 'videoPrompt', 'cameraMovement', 'playbackMode',
'audienceConnection', 'protagonistPresence', 'visualCanon', 'videoHistoryId', 'playbackAssets', 'interactionWindow',
'isEnding', 'endingLabel', 'pos', 'transitions',
];
export function addNode(loomId, episodeId, fields = {}) {
return mutateLoom(loomId, (loom) => {
const episode = findEpisode(loom, episodeId);
if (episode.nodes.length >= LOOM_LIMITS.NODES_MAX) {
throw new ServerError('Scene limit reached', { status: 400, code: 'LIMIT_REACHED' });
}
const node = { id: `node-${randomUUID()}`, ...fields };
if (asFableLoomParticipationMode(loom.participationMode) === 'helper'
&& asFableLoomAudienceConnection(fields.audienceConnection) !== 'connected'
&& !('playbackMode' in fields)) {
node.playbackMode = 'cut';
}
episode.nodes.push(node);
if (!episode.startNodeId) episode.startNodeId = node.id;
// Optionally wire the new node in as a branch of an existing one. The
// sanitizer mints the transition id and fills triggers/description.
if (isStr(fields.fromNodeId)) {
const from = episode.nodes.find((n) => n.id === fields.fromNodeId);
if (from) {
from.transitions = [...(from.transitions || []), { targetNodeId: node.id, intent: fields.fromIntent }];
}
}
episode.updatedAt = new Date().toISOString();
return loom;
});
}
export function updateNode(loomId, episodeId, nodeId, patch = {}) {
return mutateLoom(loomId, (loom) => {
const episode = findEpisode(loom, episodeId);
const node = findNode(episode, nodeId);
for (const key of NODE_PATCH_FIELDS) {
if (key in patch) node[key] = patch[key];
}
episode.updatedAt = new Date().toISOString();
return loom;
});
}
export function deleteNode(loomId, episodeId, nodeId) {
return mutateLoom(loomId, (loom) => {
const episode = findEpisode(loom, episodeId);
if (!episode.nodes.some((n) => n.id === nodeId)) throw notFound('Scene');
episode.nodes = episode.nodes.filter((n) => n.id !== nodeId);
// Strip inbound edges so deleting a scene never leaves dangling paths.
for (const node of episode.nodes) {
node.transitions = (node.transitions || []).filter((t) => t.targetNodeId !== nodeId);
}
if (episode.startNodeId === nodeId) episode.startNodeId = episode.nodes[0]?.id ?? null;
episode.updatedAt = new Date().toISOString();
return loom;
});
}
// --- Transitions as sub-resources -------------------------------------------
//
// The whole-array `transitions` key on the node PATCH still works (the
// sanitizer owns it, and an older client or a peer on a previous version keeps
// using it). These three add/edit/drop ONE edge, so a second writer — a voice
// action, a CoS agent, the AI branch lane — no longer has to replay the whole
// array off a snapshot that may already be stale.
const TRANSITION_PATCH_FIELDS = ['targetNodeId', 'intent', 'triggers', 'description'];
// The sanitizer re-runs on every write, so the row that comes back out is the
// one that actually persisted (id, trimmed fields, capped triggers) — not the
// input echoed back.
const readTransition = (loom, episodeId, nodeId, transitionId) =>
loom.episodes.find((e) => e.id === episodeId)
?.nodes.find((n) => n.id === nodeId)
?.transitions.find((t) => t.id === transitionId) ?? null;
/**
* Add one path out of a scene. The id is minted here rather than inside the
* sanitizer so the caller can read the stored row back out by it — that is the
* whole point of the sub-resource: the client knows the id at create time and
* never has to reconcile server-minted ids into locally-added rows.
*/
export async function addNodeTransition(loomId, episodeId, nodeId, fields = {}) {
const id = `tr-${randomUUID()}`;
const loom = await mutateLoom(loomId, (record) => {
const episode = findEpisode(record, episodeId);
const node = findNode(episode, nodeId);
if ((node.transitions || []).length >= LOOM_LIMITS.TRANSITIONS_MAX) {
throw new ServerError('Path limit reached', { status: 400, code: 'LIMIT_REACHED' });
}
node.transitions = [...(node.transitions || []), { ...fields, id }];
episode.updatedAt = new Date().toISOString();
return record;
});
return { loom, transition: readTransition(loom, episodeId, nodeId, id) };
}
export function updateNodeTransition(loomId, episodeId, nodeId, transitionId, patch = {}) {
return mutateLoom(loomId, (record) => {
const episode = findEpisode(record, episodeId);
const transition = findTransition(findNode(episode, nodeId), transitionId);
for (const key of TRANSITION_PATCH_FIELDS) {
if (key in patch) transition[key] = patch[key];
}
episode.updatedAt = new Date().toISOString();
return record;
});
}
export function deleteNodeTransition(loomId, episodeId, nodeId, transitionId) {
return mutateLoom(loomId, (record) => {
const episode = findEpisode(record, episodeId);
const node = findNode(episode, nodeId);
findTransition(node, transitionId);
node.transitions = node.transitions.filter((t) => t.id !== transitionId);
episode.updatedAt = new Date().toISOString();
return record;
});
}
/**
* Durable image attach for the media-job completion hook: files a finished
* render onto its node, even when the editor unmounted mid-render. Returns the
* updated node (or null when the loom/episode/node has since been deleted —
* the hook logs and moves on rather than erroring).
*/
export async function attachNodeImage(loomId, episodeId, nodeId, { filename, jobId, visualConditioning = null }) {
if (!isValidLoomId(loomId) || !isSafeImageFilename(filename)) return null;
const updated = await mutateLoom(loomId, (loom) => {
const episode = loom.episodes.find((e) => e.id === episodeId);
const node = episode?.nodes.find((n) => n.id === nodeId);
if (!node) return null;
node.image = filename;
node.imageJobId = isStr(jobId) ? jobId : null;
node.visualConditioning = visualConditioning;
const retainedConditioning = Object.fromEntries(Object.entries(
node.playbackAssets?.visualConditioningByAsset || {},
).filter(([, manifest]) => manifest?.capability?.kind !== 'image'));
if (node.playbackAssets) {
node.playbackAssets = {
...node.playbackAssets,
...(Object.keys(retainedConditioning).length
? { visualConditioningByAsset: retainedConditioning }
: {}),
};
if (!Object.keys(retainedConditioning).length) delete node.playbackAssets.visualConditioningByAsset;
}
if (visualConditioning && isSafeVideoHistoryId(visualConditioning.assetId)) {
node.playbackAssets = {
...(node.playbackAssets || {}),
visualConditioningByAsset: {
...(node.playbackAssets?.visualConditioningByAsset || {}),
[visualConditioning.assetId]: visualConditioning,
},
};
}
if (node.visualCanon) node.visualCanon.storyboardImageApproved = false;
episode.updatedAt = new Date().toISOString();
return loom;
}).catch(() => null);
return updated?.episodes.find((e) => e.id === episodeId)?.nodes.find((n) => n.id === nodeId) ?? null;
}
/**
* Durable video attach for the media-job completion hook. Video history ids
* are also the generated filenames under data/videos, but are kept as ids so
* the node can use the same history/media conventions as other video surfaces.
*/
export async function attachNodeVideo(loomId, episodeId, nodeId, { videoHistoryId, visualConditioning = null }) {
if (!isValidLoomId(loomId) || !isSafeVideoHistoryId(videoHistoryId)) return null;
const updated = await mutateLoom(loomId, (loom) => {
const episode = loom.episodes.find((e) => e.id === episodeId);
const node = episode?.nodes.find((n) => n.id === nodeId);
if (!node) return null;
node.videoHistoryId = videoHistoryId;
node.visualConditioning = visualConditioning;
episode.updatedAt = new Date().toISOString();
return loom;
}).catch(() => null);
return updated?.episodes.find((e) => e.id === episodeId)?.nodes.find((n) => n.id === nodeId) ?? null;
}
/**
* Attach a typed playback asset (entry clip, hold loop, or transition exit) onto
* a node with optional audio occupancy manifest and provenance.
*/
export async function attachNodePlaybackAsset(loomId, episodeId, nodeId, {
role = 'entry',
videoHistoryId,
transitionId = null,
audioOccupancy = null,
provenance = null,
visualConditioning = null,
} = {}) {
if (!isValidLoomId(loomId) || !isSafeVideoHistoryId(videoHistoryId)) return null;
const updated = await mutateLoom(loomId, (loom) => {
const episode = loom.episodes.find((e) => e.id === episodeId);
const node = episode?.nodes.find((n) => n.id === nodeId);
if (!node) return null;
const currentAssets = node.playbackAssets || {
entryVideoHistoryId: null,
holdLoopVideoHistoryIds: [],
exitByTransition: {},
audioOccupancy: {},
};
const nextAssets = {
...currentAssets,
exitByTransition: { ...(currentAssets.exitByTransition || {}) },
audioOccupancy: { ...(currentAssets.audioOccupancy || {}) },
holdLoopVideoHistoryIds: [...(currentAssets.holdLoopVideoHistoryIds || [])],
visualConditioningByAsset: { ...(currentAssets.visualConditioningByAsset || {}) },
};
if (role === 'entry') {
nextAssets.entryVideoHistoryId = videoHistoryId;
node.videoHistoryId = videoHistoryId;
} else if (role === 'hold') {
if (!nextAssets.holdLoopVideoHistoryIds.includes(videoHistoryId)) {
nextAssets.holdLoopVideoHistoryIds.push(videoHistoryId);
}
if (!node.videoHistoryId) node.videoHistoryId = videoHistoryId;
} else if (role === 'exit' && isStr(transitionId)) {
nextAssets.exitByTransition[transitionId] = videoHistoryId;
}
if (audioOccupancy) {
nextAssets.audioOccupancy[videoHistoryId] = audioOccupancy;
}
if (provenance) {
nextAssets.provenance = provenance;
}
if (visualConditioning) {
nextAssets.visualConditioningByAsset[videoHistoryId] = visualConditioning;
node.visualConditioning = visualConditioning;
}
node.playbackAssets = nextAssets;
episode.updatedAt = new Date().toISOString();
return loom;
}).catch(() => null);
return updated?.episodes.find((e) => e.id === episodeId)?.nodes.find((n) => n.id === nodeId) ?? null;
}