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
/**
* Storyboard scene/shot durable ids + id-first target resolution (#3413).
*
* Storyboard scenes used to be addressed purely by ARRAY INDEX end to end —
* the route took `sceneIndex`, the media-job owner encoded `scene<idx>`, and
* the stage write patched `scenes[index]`. A reorder or delete landing between
* a caller's read and its (serialized) write therefore retargeted the write
* onto whatever scene now occupied that slot, and the completion hook routed
* the finished render by the same stale index, so the mis-targeting was
* consistent rather than self-correcting.
*
* Both halves of the fix live here:
*
* - `ensureStoryboardIds` stamps a durable `id` on any scene (and shot) that
* lacks one. It is called from `sanitizeVisualStage`'s storyboards branch,
* so every persisted record grows ids on its next write, and from the
* backfill migrations for records already on disk / in Postgres.
* - `resolveStoryboardTarget` resolves a captured id against a FRESH array,
* falling back to the index only for pre-migration records that carry no
* id at all.
*
* Ids are DETERMINISTIC (`scene-01`, `shot-02`, …) rather than random on
* purpose:
* - Two concurrent readers of the same un-migrated record must derive the
* same id, otherwise their writes would disagree about what they targeted.
* - Federated peers each run the backfill over their own copy of a shared
* record; a random id would make every peer stamp something different and
* churn conflicts forever. Deterministic ids converge.
*
* A deterministic base that is already taken gets a `-2`, `-3`, … suffix, so
* an array that already holds `scene-01` never gets a duplicate stamped onto
* it — and an array that ALREADY carries duplicate ids (a duplicated scene, or
* the scene extractor's tolerated duplicate shot ids) has the later copies
* re-stamped. Duplicate ids would make id resolution ambiguous, which is the
* mis-target this module exists to prevent.
*/
import { isNonBlankStr } from './textUtils.js';
const ID_MAX = 80;
export const sceneIdForIndex = (index) => `scene-${String(index + 1).padStart(2, '0')}`;
export const shotIdForIndex = (index) => `shot-${String(index + 1).padStart(2, '0')}`;
// Deterministic collision escape: `scene-03` → `scene-03-2` → `scene-03-3`.
const uniqueId = (base, taken) => {
if (!taken.has(base)) return base;
let n = 2;
while (taken.has(`${base}-${n}`)) n += 1;
return `${base}-${n}`;
};
// Stamp `id` on every entry that lacks one, and re-stamp any entry whose id
// DUPLICATES an earlier entry's. A duplicate id is as bad as no id: the
// resolver tie-breaks on the captured index, so once two same-id entries are
// reordered the write lands on the wrong one — exactly the mis-target this
// module exists to prevent. First occurrence keeps the id (matching
// `sanitizeShots`' first-wins resolution of `continuityFromShotId`), later
// ones are re-stamped.
//
// Returns the ORIGINAL array reference when nothing changed so callers can
// cheaply detect a no-op.
const stampIds = (list, idFor) => {
if (!Array.isArray(list) || list.length === 0) return list;
// Only ids that survive as-is (the FIRST occurrence of each) count as taken;
// a duplicate is about to be replaced, so it must not reserve its own id.
const taken = new Set();
for (const rec of list) {
if (rec && typeof rec === 'object' && isNonBlankStr(rec.id)) taken.add(rec.id);
}
const seen = new Set();
let changed = false;
const out = list.map((rec, i) => {
if (!rec || typeof rec !== 'object' || Array.isArray(rec)) return rec;
if (isNonBlankStr(rec.id) && !seen.has(rec.id)) {
seen.add(rec.id);
return rec;
}
const id = uniqueId(idFor(i).slice(0, ID_MAX), taken);
taken.add(id);
seen.add(id);
changed = true;
return { ...rec, id };
});
return changed ? out : list;
};
/**
* Stamp durable ids onto a storyboard `scenes[]` array (and each scene's
* `shots[]`). Pure: returns a new array only when something was stamped,
* otherwise the input reference. Non-object entries pass through untouched —
* the sanitizer above this is the one that decides what a scene may be.
*/
export function ensureStoryboardIds(scenes) {
if (!Array.isArray(scenes) || scenes.length === 0) return scenes;
let shotsChanged = false;
const withShotIds = scenes.map((scene) => {
if (!scene || typeof scene !== 'object' || !Array.isArray(scene.shots)) return scene;
const shots = stampIds(scene.shots, shotIdForIndex);
if (shots === scene.shots) return scene;
shotsChanged = true;
return { ...scene, shots };
});
const stamped = stampIds(withShotIds, sceneIdForIndex);
if (stamped !== withShotIds) return stamped;
return shotsChanged ? withShotIds : scenes;
}
/**
* Resolve a render target (a scene inside `scenes[]`, or a shot inside
* `scene.shots[]`) against the FRESHEST array, given the id + index captured
* when the caller read the record.
*
* Returns `{ index, record, matchedBy, stale }`:
* - `matchedBy: 'id'` — the captured id is still present (authoritative,
* survives a reorder). When the id appears more than once (a duplicated
* record), the captured index wins the tiebreak, else the first match.
* - `matchedBy: 'index'` — no id was captured (pre-migration record), so the
* index is the only addressing available.
* - `matchedBy: null, stale: true` — an id WAS captured and is gone: the
* target was removed between read and write. Callers surface this as a 409
* (distinct from a never-existed index, which is a 404) and must NOT fall
* back to the index, since that is exactly the mis-target this prevents.
* - `matchedBy: null, stale: false` — no id, and the index is out of range.
*/
export function resolveStoryboardTarget(list, { id = null, index = null } = {}) {
const arr = Array.isArray(list) ? list : [];
// `Number(null)` / `Number('')` are 0 — an absent index must NOT read as
// "index 0" (AGENTS.md sentinel discipline), so coerce only real numerics.
const idx = index === null || index === undefined || index === '' ? NaN : Number(index);
const hasIndex = Number.isInteger(idx) && idx >= 0;
if (isNonBlankStr(id)) {
if (hasIndex && arr[idx] && arr[idx].id === id) {
return { index: idx, record: arr[idx], matchedBy: 'id', stale: false };
}
const found = arr.findIndex((r) => r && r.id === id);
if (found >= 0) return { index: found, record: arr[found], matchedBy: 'id', stale: false };
return { index: -1, record: null, matchedBy: null, stale: true };
}
if (hasIndex && arr[idx]) return { index: idx, record: arr[idx], matchedBy: 'index', stale: false };
return { index: -1, record: null, matchedBy: null, stale: false };
}