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

[issue-11669] Complete character sheets after restart or listener timeout (#11717)

[._.]/cfcc10d00681
diff --git a/server/lib/schemaVersions.js b/server/lib/schemaVersions.js
index 8b0d18c9ce..2737b0fa4c 100644
--- a/server/lib/schemaVersions.js
+++ b/server/lib/schemaVersions.js
@@ -80,7 +80,9 @@ export const PORTOS_SCHEMA_VERSIONS = Object.freeze({
// <=v11 peer would strip it in its `factual`-unaware `sanitizeTemplate`
// and last-writer-wins the loss back, silently reclassifying the user's
// Reality universe as fiction.
- universes: 12,
+ // v13 = durable character sheet request identities (#11669). Older peers
+ // must not strip supersession state during an unrelated canon edit.
+ universes: 13,
// v1 = post-split. Migrations 035/036 introduced the pipeline collection
// layout for issues and series.
// v2 = `stages.audio.audioMode` + `stages.audio.cues[]` added (whole-episode
diff --git a/server/lib/schemaVersions.test.js b/server/lib/schemaVersions.test.js
index 00a973a186..71b70b1a71 100644
--- a/server/lib/schemaVersions.test.js
+++ b/server/lib/schemaVersions.test.js
@@ -25,7 +25,7 @@ describe('PORTOS_SCHEMA_VERSIONS', () => {
// v12 adds the universe factual flag (#7616).
// These are additive + version-gated so an older peer
// cannot strip-then-LWW them.
- expect(PORTOS_SCHEMA_VERSIONS.universes).toBe(12);
+ expect(PORTOS_SCHEMA_VERSIONS.universes).toBe(13);
});
it('declares pipeline collection layout versions', () => {
@@ -91,14 +91,14 @@ describe('buildPortosMeta', () => {
it('returns { portosVersion, schemaVersions } with the live registry', async () => {
const meta = await buildPortosMeta();
expect(meta.portosVersion).toMatch(/^\d+\.\d+\.\d+/);
- expect(meta.schemaVersions.universes).toBe(12);
+ expect(meta.schemaVersions.universes).toBe(13);
expect(meta.schemaVersions.pipelineIssues).toBe(4);
expect(meta.schemaVersions.pipelineSeries).toBe(14);
});
it('overrides merge into schemaVersions', async () => {
const meta = await buildPortosMeta({ schemaVersions: { future: 1 } });
- expect(meta.schemaVersions.universes).toBe(12);
+ expect(meta.schemaVersions.universes).toBe(13);
expect(meta.schemaVersions.future).toBe(1);
});
});
diff --git a/server/lib/storyBible.js b/server/lib/storyBible.js
index 8418d7364c..b75137bfab 100644
--- a/server/lib/storyBible.js
+++ b/server/lib/storyBible.js
@@ -252,8 +252,8 @@ export function findBibleEntryByName(list, name) {
// render-completion mutator is the sole writer. Distinct from the
// `imageRefs[]` gallery — lives in `data/image-refs/`.
//
-// `SERVER_OWNED_CHARACTER_FIELDS` is a strict subset: ONLY the pointers
-// that the *server* writes via render-completion mutators (never the
+// `SERVER_OWNED_CHARACTER_FIELDS` is a strict subset: pointers and request
+// identities that the *server* writes via render mutators (never the
// client, never the LLM). `updateUniverse` preserves these across
// literal-object PATCHes so a stale client body can't clobber a newer
// server stamp (multi-tab / parallel render race). Mutator-form callers
@@ -265,11 +265,11 @@ export const CANON_CONTROL_FIELDS = Object.freeze([
// Sheet pointers — see SHEET_VARIANTS in universeCharacterSheet.js for the
// catalog of styles; legacy 'standard' stays in `referenceSheetImageRef`,
// every other variant lives in `referenceSheets[<id>]`.
- 'referenceSheetImageRef', 'referenceSheets',
+ 'referenceSheetImageRef', 'referenceSheets', 'referenceSheetRequests',
]);
export const SERVER_OWNED_CHARACTER_FIELDS = Object.freeze([
- 'referenceSheetImageRef', 'referenceSheets',
+ 'referenceSheetImageRef', 'referenceSheets', 'referenceSheetRequests',
]);
export function stripCanonControlFields(entry) {
@@ -452,6 +452,8 @@ const ADDITIVE_CHARACTER_FIELD_VERSIONS = Object.freeze({
identityPack: 10,
// v11 — optional structured psychology profile (#6414).
psychology: 11,
+ // v13 — durable per-variant render intent (#11669).
+ referenceSheetRequests: 13,
});
const ADDITIVE_OBJECT_FIELD_VERSIONS = Object.freeze({
// v7 — structured object↔character attachments (#1288).
@@ -463,7 +465,8 @@ const ADDITIVE_OBJECT_FIELD_VERSIONS = Object.freeze({
// sanitizer defaults to `[]` (relationshipLinks, attachments).
export function isLegacyAbsentValue(value) {
return value === undefined || value === null || value === false || value === ''
- || (Array.isArray(value) && value.length === 0);
+ || (Array.isArray(value) && value.length === 0)
+ || (isPlainObject(value) && Object.keys(value).length === 0);
}
/**
@@ -534,7 +537,8 @@ function isValidVariantId(id) {
* immutable-by-convention. */
export function mergePreservedSheetPointers(prev, patchChar, resolveExists) {
if (!prev || !patchChar) return patchChar;
- const out = { ...patchChar };
+ // Intent has no file yet and must survive even if a prior sheet was deleted.
+ const out = { ...patchChar, referenceSheetRequests: prev.referenceSheetRequests ?? {} };
if (prev.referenceSheetImageRef && resolveExists(prev.referenceSheetImageRef)) {
out.referenceSheetImageRef = prev.referenceSheetImageRef;
@@ -1021,6 +1025,9 @@ export function sanitizeCharacter(raw, { idPrefix = DEFAULT_ID_PREFIX.character,
// migration. Sanitizer drops invalid keys and basename-validates every
// value with the same rules as the legacy field.
referenceSheets: deriveReferenceSheets(raw.referenceSheets),
+ referenceSheetRequests: Object.fromEntries(Object.entries(isPlainObject(raw.referenceSheetRequests) ? raw.referenceSheetRequests : {})
+ .filter(([variant, token]) => (variant === LEGACY_SHEET_VARIANT_ID || isValidVariantId(variant))
+ && typeof token === 'string' && /^[0-9a-f-]{36}$/.test(token))),
// Wardrobes (A2): outfit/styling variants applied on top of
// physicalDescription. Empty array stays the legacy shape — every
// existing character keeps rendering through physicalDescription alone.
diff --git a/server/lib/storyBible.test.js b/server/lib/storyBible.test.js
index 8b803c4f98..258b6f382d 100644
--- a/server/lib/storyBible.test.js
+++ b/server/lib/storyBible.test.js
@@ -976,7 +976,7 @@ describe('storyBible — canon control + server-owned field invariants', () => {
// Pin the current set so a new server-owned addition is a deliberate
// change (update both this test AND the corresponding render flow).
expect([...SERVER_OWNED_CHARACTER_FIELDS]).toEqual([
- 'referenceSheetImageRef', 'referenceSheets',
+ 'referenceSheetImageRef', 'referenceSheets', 'referenceSheetRequests',
]);
});
});
@@ -1781,3 +1781,22 @@ describe('storyBible — reveal-gated canon (#2178)', () => {
});
});
});
+
+// The durable render identity must survive canonical storage and stale client
+// edits, while model-generated content cannot create or replace it.
+it('round-trips server-owned sheet request identity and preserves it across stale edits', () => {
+ const requestId = '11111111-1111-4111-8111-111111111111';
+ const current = sanitizeCharacter({ id: 'character-1', name: 'Example', referenceSheetRequests: { standard: requestId, blueprint: requestId } });
+ expect(current.referenceSheetRequests).toEqual({ standard: requestId, blueprint: requestId });
+ const patched = mergePreservedSheetPointers(current, { ...current, name: 'Edited', referenceSheetRequests: {} }, () => false);
+ expect(sanitizeCharacter(patched).referenceSheetRequests).toEqual(current.referenceSheetRequests);
+ expect(stripCanonControlFields(current)).not.toHaveProperty('referenceSheetRequests');
+});
+
+it('preserves sheet request identity from pre-v13 peers but honors current peer supersession', () => {
+ const local = [{ id: 'character-1', referenceSheetRequests: { standard: '11111111-1111-4111-8111-111111111111' } }];
+ const legacy = [{ id: 'character-1', name: 'Peer edit', referenceSheetRequests: {} }];
+ expect(preserveLegacyCharacterFields(legacy, local, 12)[0].referenceSheetRequests).toEqual(local[0].referenceSheetRequests);
+ const newer = [{ id: 'character-1', referenceSheetRequests: { standard: '22222222-2222-4222-8222-222222222222' } }];
+ expect(preserveLegacyCharacterFields(newer, local, 13)).toEqual(newer);
+});
diff --git a/server/services/dataSync.pipelineUniverse.test.js b/server/services/dataSync.pipelineUniverse.test.js
index 1fe1b4c369..f49c373e70 100644
--- a/server/services/dataSync.pipelineUniverse.test.js
+++ b/server/services/dataSync.pipelineUniverse.test.js
@@ -163,19 +163,19 @@ describe('dataSync — universe category', () => {
const snap = await dataSync.getSnapshot('universe');
expect(snap.portosMeta).toBeDefined();
expect(typeof snap.portosMeta.portosVersion).toBe('string');
- expect(snap.portosMeta.schemaVersions.universes).toBe(12);
+ expect(snap.portosMeta.schemaVersions.universes).toBe(13);
});
it('applyRemote rejects when sender schemaVersions are AHEAD of local code', async () => {
writeUniverseState({ universes: [], runs: [] });
const result = await dataSync.applyRemote('universe', {
universes: [{ id: 'u-new', name: 'Foundry', updatedAt: '2026-05-17T10:00:00Z' }],
- }, { portosMeta: { portosVersion: '99.0.0', schemaVersions: { universes: 13 } } });
+ }, { portosMeta: { portosVersion: '99.0.0', schemaVersions: { universes: 14 } } });
expect(result.applied).toBe(false);
expect(result.count).toBe(0);
expect(result.blockedBySchema).toBeDefined();
expect(result.blockedBySchema.ahead).toEqual([
- { category: 'universes', senderV: 13, receiverV: 12 },
+ { category: 'universes', senderV: 14, receiverV: 13 },
]);
expect(result.blockedBySchema.senderPortosVersion).toBe('99.0.0');
// Nothing was written.
@@ -213,6 +213,25 @@ describe('dataSync — universe category', () => {
expect('moodBoardId' in persisted.universes[0]).toBe(false);
});
+ it('preserves durable sheet intent through old-peer sync and accepts current-peer supersession', async () => {
+ const first = '11111111-1111-4111-8111-111111111111';
+ const next = '22222222-2222-4222-8222-222222222222';
+ const base = { id: 'u-sheet', name: 'Example', createdAt: '2026-05-17T09:00:00Z' };
+ writeUniverseState({ universes: [{ ...base, updatedAt: '2026-05-17T10:00:00Z',
+ characters: [{ id: 'character-1', name: 'Example', referenceSheetRequests: { standard: first } }],
+ }], runs: [] });
+ const behind = await dataSync.applyRemote('universe', { universes: [{ ...base,
+ updatedAt: '2026-05-17T11:00:00Z', characters: [{ id: 'character-1', name: 'Peer edit' }],
+ }] }, { portosMeta: { schemaVersions: { universes: 12 } } });
+ expect(behind.applied).toBe(true);
+ expect(readUniverseState().universes[0].characters[0].referenceSheetRequests).toEqual({ standard: first });
+ const current = await dataSync.applyRemote('universe', { universes: [{ ...base,
+ updatedAt: '2026-05-17T12:00:00Z', characters: [{ id: 'character-1', name: 'Peer edit', referenceSheetRequests: { standard: next } }],
+ }] }, { portosMeta: { schemaVersions: { universes: 13 } } });
+ expect(current.applied).toBe(true);
+ expect(readUniverseState().universes[0].characters[0].referenceSheetRequests).toEqual({ standard: next });
+ });
+
it('applyRemote falls through for legacy senders that send NO portosMeta at all', async () => {
writeUniverseState({ universes: [], runs: [] });
const result = await dataSync.applyRemote('universe', {
diff --git a/server/services/sharing/integration.test.js b/server/services/sharing/integration.test.js
index 018300db21..535f2c2942 100644
--- a/server/services/sharing/integration.test.js
+++ b/server/services/sharing/integration.test.js
@@ -2373,7 +2373,7 @@ describe('sharing round-trip', () => {
const exp = await exporter.exportSeries(s.id, bucket.id);
const manifest = JSON.parse(readFileSync(join(tempBucket, 'manifests', exp.filename), 'utf-8'));
expect(manifest.portosSchemaVersions).toBeDefined();
- expect(manifest.portosSchemaVersions.universes).toBe(12);
+ expect(manifest.portosSchemaVersions.universes).toBe(13);
});
it('preserves character production packages when an older peer wins universe LWW', async () => {
diff --git a/server/services/sharing/peerSync.test.js b/server/services/sharing/peerSync.test.js
index 5529f7660e..a91992d2d5 100644
--- a/server/services/sharing/peerSync.test.js
+++ b/server/services/sharing/peerSync.test.js
@@ -4059,17 +4059,17 @@ describe('peerSync', () => {
describe('receiver — applyIncomingPush', () => {
it('rejects when sender schemaVersions.universes is AHEAD of local code', async () => {
- // Local code is at universes:12 (see server/lib/schemaVersions.js).
- // A push from a sender on universes:13 must NOT touch local state.
+ // Local code is at universes:13 (see server/lib/schemaVersions.js).
+ // A push from a sender on universes:14 must NOT touch local state.
const rejection = await applyIncomingPush({
kind: 'universe',
record: { id: 'u1', name: 'Foo' },
assetManifest: [],
sourceInstanceId: 'peer-a',
- portosMeta: { portosVersion: '99.0.0', schemaVersions: { universes: 13 } },
+ portosMeta: { portosVersion: '99.0.0', schemaVersions: { universes: 14 } },
}).catch((err) => err);
expect(rejection.code).toBe('PEER_SYNC_SCHEMA_VERSION_AHEAD');
- expect(rejection.details.ahead).toEqual([{ category: 'universes', senderV: 13, receiverV: 12 }]);
+ expect(rejection.details.ahead).toEqual([{ category: 'universes', senderV: 14, receiverV: 13 }]);
expect(rejection.details.senderPortosVersion).toBe('99.0.0');
// Receiver MUST stamp its OWN PortOS version so the sender can show
// the user "peer X is on PortOS vY" — without this, the sender would
@@ -4362,7 +4362,7 @@ describe('peerSync', () => {
expect(call).toBeDefined();
const body = JSON.parse(call[1].body);
expect(body.portosMeta).toBeDefined();
- expect(body.portosMeta.schemaVersions.universes).toBe(12);
+ expect(body.portosMeta.schemaVersions.universes).toBe(13);
expect(typeof body.portosMeta.portosVersion).toBe('string');
});
diff --git a/server/services/universeAssetBackupAdmission.test.js b/server/services/universeAssetBackupAdmission.test.js
index 0032c7bbd7..ba2ad225c9 100644
--- a/server/services/universeAssetBackupAdmission.test.js
+++ b/server/services/universeAssetBackupAdmission.test.js
@@ -40,11 +40,21 @@ vi.mock('./universeBuilder.js', () => ({
},
}));
+// Retain the same job identity and params from admission through terminal
+// publication, as the persisted queue does across process lifetimes.
+const queuedJobs = new Map();
vi.mock('./mediaJobQueue/index.js', () => ({
mediaJobEvents: new EventEmitter(),
- enqueueJob: async () => ({ jobId: 'sheet-job', position: 1 }),
+ enqueueJob: async ({ kind, params }) => {
+ const job = { id: 'sheet-job', kind, params: structuredClone(params), status: 'queued' };
+ queuedJobs.set(job.id, job);
+ return { jobId: job.id, position: 1, status: job.status };
+ },
+ getJob: id => queuedJobs.get(id),
}));
vi.mock('./mediaCollections.js', () => ({ addItem: vi.fn(), ERR_DUPLICATE: 'DUPLICATE' }));
+// This suite owns universe references; music-video pool cleanup has its own contracts.
+vi.mock('./musicVideo/mediaPool.js', () => ({ forgetDeletedMusicVideoAssets: async () => {} }));
vi.mock('./mediaAssetIndex/index.js', () => ({ indexImage: async () => {}, unindexImage: async () => {} }));
vi.mock('./settings.js', () => ({ getSettings: async () => ({ imageGen: { mode: 'local', local: { modelId: 'dev' } } }) }));
vi.mock('./universeRunTag.js', () => ({ buildUniverseRunTag: async () => null }));
@@ -88,6 +98,7 @@ initUniverseBuilderCollectionHook();
afterAll(cleanupTempDataRoots);
beforeEach(async () => {
beforeRowWrite = async () => {};
+ queuedJobs.clear();
await rm(PATHS.data, { recursive: true, force: true });
await Promise.all([PATHS.images, PATHS.imageRefs].map(directory => mkdir(directory, { recursive: true })));
await writeFile(renderPath(), 'synthetic render');
@@ -115,7 +126,9 @@ describe('render completion listeners', () => {
job: async () => {
const { jobId, destFilename } = await renderCharacterReferenceSheet('universe-1', 'character-1');
sheet = destFilename;
- return { id: jobId, kind: 'image', result: { filename: RENDER } };
+ const completed = { ...queuedJobs.get(jobId), status: 'completed', result: { filename: RENDER } };
+ queuedJobs.set(jobId, completed);
+ return structuredClone(completed);
},
changedFiles: async () => {
expect(await readFile(join(PATHS.imageRefs, sheet), 'utf8')).toBe('synthetic render');
diff --git a/server/services/universeBuilder.test.js b/server/services/universeBuilder.test.js
index 050000d69f..bb408a808d 100644
--- a/server/services/universeBuilder.test.js
+++ b/server/services/universeBuilder.test.js
@@ -774,6 +774,7 @@ describe("universeBuilder service", () => {
await svc.updateUniverse(w.id, (latest) => {
const next = [...(latest.characters || []), {
id: "c-1", name: "Vale", referenceSheetImageRef: "sheet-B.png",
+ referenceSheetRequests: { standard: "11111111-1111-4111-8111-111111111111" },
}];
return { characters: next };
});
@@ -791,6 +792,7 @@ describe("universeBuilder service", () => {
});
const charOmit = afterOmitPatch.characters.find((c) => c.id === "c-1");
expect(charOmit?.referenceSheetImageRef).toBe("sheet-B.png");
+ expect(charOmit?.referenceSheetRequests).toEqual({ standard: "11111111-1111-4111-8111-111111111111" });
// Mutator path (the render-completion handler) IS trusted to update
// referenceSheetImageRef — it constructs the patch from the latest
diff --git a/server/services/universeCharacterSheet.js b/server/services/universeCharacterSheet.js
index a35ee7d102..af1b7f6c8e 100644
--- a/server/services/universeCharacterSheet.js
+++ b/server/services/universeCharacterSheet.js
@@ -14,6 +14,7 @@
*/
import { join, basename } from 'path';
+import { randomUUID } from 'node:crypto';
import { PATHS, ensureDir, shortId, assertSafeFilename, copyFileGuarded, unlinkGuarded } from '../lib/fileUtils.js';
import { ServerError } from '../lib/errorHandler.js';
import { withBackupAssetPublication } from '../lib/backupSnapshotBoundary.js';
@@ -22,7 +23,7 @@ import { getUniverse, updateUniverse } from './universeBuilder.js';
import { purgeReferenceSheetFromAllUniverses } from './universeCanon.js';
import { universeAestheticLine } from '../lib/universeVisualStyle.js';
import { promptAddition } from '../lib/modelInput.js';
-import { enqueueJob, mediaJobEvents } from './mediaJobQueue/index.js';
+import { enqueueJob, getJob, mediaJobEvents } from './mediaJobQueue/index.js';
import { buildUniverseRunTag } from './universeRunTag.js';
import { IMAGE_GEN_MODE } from './imageGen/modes.js';
import { resolveRenderTargetConfig } from './imageGen/cloudProviderConfig.js';
@@ -328,14 +329,6 @@ export function listSheetVariants() {
}));
}
-// `(universeId, characterId) → latest generationId requested` is owned by
-// `./universeCharacterSheetSlot.js` (extracted so universeBuilder.js can
-// clear slots on delete without an import cycle). The supersede-aware
-// contract is unchanged: a render claims the slot at enqueue, the
-// completion handler only stamps `referenceSheetImageRef` when the slot
-// still holds its jobId, and a newer render overwrites the slot so the
-// older one sees itself as superseded.
-
// Single-dispatcher subscription so N pending sheets don't attach 4*N
// listeners on the global `mediaJobEvents` emitter (Node defaults to a
// 10-listener soft cap before warning). Each render claims an entry by
@@ -347,11 +340,34 @@ function ensureSheetDispatchListeners() {
if (_sheetListenersAttached) return;
_sheetListenersAttached = true;
mediaJobEvents.on('started', (job) => sheetSubscribers.get(job?.id)?.onStarted?.(job));
- mediaJobEvents.on('completed', (job) => sheetSubscribers.get(job?.id)?.onCompleted?.(job));
- const onTerminal = (job) => sheetSubscribers.get(job?.id)?.onFailed?.(job);
+ mediaJobEvents.on('completed', (job) => {
+ sheetSubscribers.get(job?.id)?.onCompleted?.(job);
+ const tag = job?.params?.characterSheet;
+ if (!tag) return;
+ // The persisted job owns completion, even after restart or listener expiry.
+ void onSheetComplete({ ...tag, jobId: job.id, sourceFilename: job.result?.filename })
+ .catch((err) => {
+ console.error(`❌ Character sheet post-completion failed [${shortId(job.id)}]: ${err?.message}`);
+ return null;
+ }).then((result) => {
+ releasePendingSheetSlot(tag.universeId, tag.entryId, job.id, tag.variant);
+ mediaJobEvents.emit('reference-sheet:changed', {
+ universeId: tag.universeId, entryId: tag.entryId, jobId: job.id, variant: tag.variant,
+ status: result?.superseded ? 'superseded' : result ? 'ready' : 'failed',
+ });
+ });
+ });
+ const onTerminal = (job) => {
+ sheetSubscribers.get(job?.id)?.onFailed?.(job);
+ const tag = job?.params?.characterSheet;
+ if (tag) releasePendingSheetSlot(tag.universeId, tag.entryId, job.id, tag.variant);
+ };
mediaJobEvents.on('failed', onTerminal);
mediaJobEvents.on('canceled', onTerminal);
}
+// Routes import this module before queue recovery starts at boot.
+ensureSheetDispatchListeners();
+
function subscribeToSheetJob(jobId, handlers) {
ensureSheetDispatchListeners();
sheetSubscribers.set(jobId, handlers);
@@ -484,33 +500,29 @@ export async function renderCharacterReferenceSheet(universeId, entryId, options
params.universeRun = universeRun;
}
- // Enqueue through mediaJobQueue so the render serializes through the right
- // backend lane alongside Image Gen / Universe Builder renders. The queue
- // dispatches by `params.mode` (codex → codex lane, local → GPU lane).
+ // Persist intent BEFORE enqueue can dispatch. The serialized universe write
+ // establishes ordering without timestamps or a process-local pending slot.
+ // Retain the token after completion/failure: an older job must stay superseded.
+ const requestId = randomUUID();
+ await updateUniverse(universeId, (latest) => {
+ const current = latest.characters?.find((entry) => entry.id === entryId);
+ if (!current) throw new ServerError('Character not found in universe', { status: 404, code: 'UNIVERSE_CANON_NOT_FOUND' });
+ return { characters: latest.characters.map((entry) => entry.id === entryId ? {
+ ...entry,
+ referenceSheetRequests: { ...entry.referenceSheetRequests, [variant]: requestId },
+ } : entry) };
+ });
+ params.characterSheet = { universeId, entryId, variant, requestId };
const queued = await enqueueJob({ kind: 'image', params });
const jobId = queued.jobId;
- // Claim the latest-pending slot for this character + variant. onSheetComplete
- // checks it before stamping — guards against an older-but-slower render
- // finishing after a newer one and overwriting the newer pointer. The variant
- // key keeps standard and blueprint slots independent so a blueprint render
- // can't be superseded by an illustrated one or vice versa.
- claimPendingSheetSlot(universeId, entryId, jobId, variant);
-
- // Subscribe to the queue's completion bus via the shared sheet
- // dispatcher (NOT imageGenEvents directly — the queue mediates the
- // imageGen lifecycle and re-emits on mediaJobEvents with the full job
- // record). The shared dispatcher caps listeners at 4 regardless of how
- // many sheets are pending (see `subscribeToSheetJob` above), so a user
- // running 10+ parallel character renders won't trip
- // MaxListenersExceededWarning on the global emitter.
- //
- // Two-stage timeout: a generous queue-wait window covers the pre-start
- // gap (so a sheet queued behind a long video / first-run-download
- // doesn't detach mid-queue), then the `started` event resets the timer
- // to the tighter run window. Without the reset, a sheet waiting 30+
- // minutes behind a video job would lose its bookkeeping listener
- // before onSheetComplete had a chance to run — file copy + character
- // pointer stamp lost.
+ const latest = await getUniverse(universeId);
+ if (latest.characters?.find((entry) => entry.id === entryId)?.referenceSheetRequests?.[variant] === requestId) {
+ claimPendingSheetSlot(universeId, entryId, jobId, variant);
+ }
+
+ // Per-request listeners only track pending UI state. Expiry releases that
+ // state, while the permanent hook still owns publication from the job tag.
+ // Queue wait gets a longer window than active rendering.
const QUEUE_WAIT_MS = 4 * 60 * 60 * 1000; // 4h — generous; survives chained video jobs.
// 30min sits comfortably above the codex backend's 20min CODEX_TIMEOUT_MS
// watchdog and the typical local FLUX.2 ceiling, so a legitimate slow
@@ -528,32 +540,25 @@ export async function renderCharacterReferenceSheet(universeId, entryId, options
}, ms);
timeoutHandle.unref?.();
};
- const detach = () => {
+ const detach = (release = true) => {
if (timeoutHandle) { clearTimeout(timeoutHandle); timeoutHandle = null; }
if (unsubscribe) { unsubscribe(); unsubscribe = null; }
+ if (release) releasePendingSheetSlot(universeId, entryId, jobId, variant);
};
unsubscribe = subscribeToSheetJob(jobId, {
onStarted: () => armTimeout(RUN_TIMEOUT_MS, 'exceeded run window'),
- onCompleted: async (job) => {
- detach();
- const sourceFilename = job.result?.filename;
- const result = await onSheetComplete({ universeId, entryId, jobId, sourceFilename, variant }).catch((err) => {
- console.error(`❌ ${variantConfig.label} post-completion failed [${shortId(jobId)}]: ${err?.message}`);
- });
- releasePendingSheetSlot(universeId, entryId, jobId, variant);
- mediaJobEvents.emit('reference-sheet:changed', {
- universeId, entryId, jobId, variant,
- status: result?.superseded ? 'superseded' : result ? 'ready' : 'failed',
- });
- },
+ onCompleted: () => detach(false),
onFailed: (job) => {
detach();
- // Release the slot so a retry render doesn't get superseded by this dead one.
- releasePendingSheetSlot(universeId, entryId, jobId, variant);
console.log(`⚠️ ${variantConfig.label} render ${job.status} [${shortId(jobId)}]: ${job.error || 'unknown'}`);
},
});
armTimeout(QUEUE_WAIT_MS, 'queue-wait timeout');
+ // Queue admission starts its worker before resolving. A fast completion or
+ // cancellation can precede this subscriber; never leave its terminal job pending.
+ const admittedJob = getJob(jobId);
+ if (['completed', 'failed', 'canceled'].includes(admittedJob?.status ?? queued.status)) detach();
+ else if (admittedJob?.status === 'running') armTimeout(RUN_TIMEOUT_MS, 'exceeded run window');
// Deterministic destination filename — uses the queue's jobId so the client
// can correlate the persisted pointer with this particular render.
@@ -584,7 +589,7 @@ export function onSheetComplete(completion) {
return withBackupAssetPublication(() => publishCompletedSheet(completion));
}
-async function publishCompletedSheet({ universeId, entryId, jobId, sourceFilename, variant = LEGACY_SHEET_VARIANT_ID }) {
+async function publishCompletedSheet({ universeId, entryId, jobId, sourceFilename, requestId, variant = LEGACY_SHEET_VARIANT_ID }) {
if (!sourceFilename) return null;
const variantConfig = getVariantConfig(variant);
await ensureDir(PATHS.imageRefs);
@@ -597,49 +602,21 @@ async function publishCompletedSheet({ universeId, entryId, jobId, sourceFilenam
await copyFileGuarded(srcPath, destPath);
console.log(`📸 ${variantConfig.label} copied to image-refs: ${destFilename}`);
- // If a newer render has been started for this character+variant while ours
- // was in flight (OR the character was deleted, which clears all variants'
- // slots), the slot no longer holds our jobId. Skip the stamp — the newer
- // render will stamp its own filename when it finishes, and a deleted
- // character would re-introduce an orphaned pointer. Without this, an
- // older-but-slower render could overwrite a newer-but-finished pointer.
- if (getPendingSheetSlot(universeId, entryId, variant) !== jobId) {
- console.log(`⏭️ ${variantConfig.label} [${shortId(jobId)}] superseded by newer render — file saved, pointer not stamped`);
- return { filename: destFilename, path: destPath, superseded: true };
- }
- // Stamp ONLY the variant's pointer (legacy field OR `referenceSheets` map
- // slot) inside the write queue against the freshest persisted universe so
- // a concurrent user edit (or sibling render landing close in time) can't
- // clobber unrelated character fields. The sheet file lives in
- // data/image-refs/, distinct from `imageRefs[]` (gallery, /data/images/) —
- // polluting imageRefs would 404 the CanonCard thumbnail.
+ // Compare the durable request identity inside the serialized write. An
+ // absent character/token is superseded too; deletion must not revive a sheet.
let stamped = false;
await updateUniverse(universeId, (latest) => {
- // Recheck inside the serialized write: a newer render can claim the slot
- // while this completion waits for an earlier universe update.
- if (getPendingSheetSlot(universeId, entryId, variant) !== jobId) return null;
const latestList = Array.isArray(latest.characters) ? latest.characters : [];
const latestIdx = latestList.findIndex((c) => c.id === entryId);
- if (latestIdx < 0) return null;
+ if (latestIdx < 0 || !requestId || latestList[latestIdx].referenceSheetRequests?.[variant] !== requestId) return null;
const nextList = latestList.map((e, i) => (
i === latestIdx ? applySheetPointerToCharacter(e, variant, destFilename) : e
));
stamped = true;
return { characters: nextList };
});
- // Release the slot only after a successful stamp AND only if it still
- // belongs to us — between the supersede check and this delete, a newer
- // render could have started, claimed the slot, and arrived here in
- // parallel. An unconditional delete would wipe the newer render's slot
- // and cause its onSheetComplete to see "superseded" (slot empty ≠ jobId)
- // and skip its own stamp — leaving the older filename persisted. A
- // failed stamp leaves the slot owned by us so the next render-start
- // cleanly overwrites it.
releasePendingSheetSlot(universeId, entryId, jobId, variant);
- if (!stamped) {
- console.log(`⚠️ Character ${entryId} not found post-render — ${variantConfig.label.toLowerCase()} saved but not linked`);
- return null;
- }
+ if (!stamped) return { filename: destFilename, path: destPath, superseded: true };
console.log(`📌 Character ${shortId(entryId)} [${variant}] = ${destFilename}`);
return { filename: destFilename, path: destPath, variant };
}
diff --git a/server/services/universeCharacterSheet.modelResolution.test.js b/server/services/universeCharacterSheet.modelResolution.test.js
index 53e6c914dc..a870ffa875 100644
--- a/server/services/universeCharacterSheet.modelResolution.test.js
+++ b/server/services/universeCharacterSheet.modelResolution.test.js
@@ -13,10 +13,11 @@ const mocks = vi.hoisted(() => ({
claimPendingSheetSlot: vi.fn(),
}));
-vi.mock('./universeBuilder.js', () => ({ getUniverse: (...args) => mocks.getUniverse(...args) }));
+vi.mock('./universeBuilder.js', () => ({ getUniverse: (...args) => mocks.getUniverse(...args), updateUniverse: vi.fn() }));
vi.mock('./settings.js', () => ({ getSettings: (...args) => mocks.getSettings(...args) }));
vi.mock('./mediaJobQueue/index.js', () => ({
enqueueJob: (...args) => mocks.enqueueJob(...args),
+ getJob: vi.fn(),
mediaJobEvents: { on: vi.fn(), off: vi.fn() },
}));
vi.mock('./universeRunTag.js', () => ({ buildUniverseRunTag: (...args) => mocks.buildUniverseRunTag(...args) }));
diff --git a/server/services/universeCharacterSheet.publication.test.js b/server/services/universeCharacterSheet.publication.test.js
index 0e6fe905f4..0b5ddd0159 100644
--- a/server/services/universeCharacterSheet.publication.test.js
+++ b/server/services/universeCharacterSheet.publication.test.js
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { it, expect, vi, beforeEach, afterEach } from 'vitest';
vi.mock('../lib/imageCleanDefaults.js', () => ({
resolveImageCleaners: vi.fn(() => ({ cleanC2PA: false, denoise: false })),
@@ -7,7 +7,7 @@ vi.mock('../lib/imageCleanDefaults.js', () => ({
const mocks = vi.hoisted(() => ({
getUniverse: vi.fn(),
getSettings: vi.fn(),
- enqueueJob: vi.fn(),
+ enqueueJob: vi.fn(), getJob: vi.fn(),
getImageModels: vi.fn(),
buildUniverseRunTag: vi.fn(),
copy: vi.fn(), update: vi.fn(),
@@ -17,7 +17,7 @@ vi.mock('./universeBuilder.js', () => ({ getUniverse: (...args) => mocks.getUniv
vi.mock('./settings.js', () => ({ getSettings: (...args) => mocks.getSettings(...args) }));
vi.mock('./mediaJobQueue/index.js', async () => {
const { EventEmitter } = await import('node:events');
- return { enqueueJob: (...args) => mocks.enqueueJob(...args), mediaJobEvents: new EventEmitter() };
+ return { enqueueJob: (...args) => mocks.enqueueJob(...args), getJob: (...args) => mocks.getJob(...args), mediaJobEvents: new EventEmitter() };
});
vi.mock('../lib/fileUtils.js', async importOriginal => ({
...(await importOriginal()), ensureDir: vi.fn(), copyFileGuarded: (...args) => mocks.copy(...args),
@@ -32,31 +32,35 @@ import { renderCharacterReferenceSheet, getCharacterReferenceSheet } from './uni
import { mediaJobEvents } from './mediaJobQueue/index.js';
-import { claimPendingSheetSlot } from './universeCharacterSheetSlot.js';
+import { __testing as slots } from './universeCharacterSheetSlot.js';
let universe;
beforeEach(() => {
vi.clearAllMocks();
+ slots.reset();
universe = { id: 'universe-1', name: 'Example Universe', characters: [{ id: 'character-1', name: 'Example Character' }] };
mocks.getUniverse.mockImplementation(async () => universe);
mocks.getSettings.mockResolvedValue({ imageGen: { mode: 'local', local: { modelId: 'dev' } } });
mocks.getImageModels.mockReturnValue([{ id: 'dev', hardwareCompatibility: { state: 'available' } }]);
mocks.buildUniverseRunTag.mockResolvedValue(null);
+ mocks.getJob.mockReturnValue(null);
mocks.enqueueJob.mockResolvedValue({ jobId: 'job-1', position: 1 });
mocks.copy.mockResolvedValue();
mocks.update.mockImplementation(async (_id, update) => { universe = { ...universe, ...update(universe) }; });
});
-const completed = () => mediaJobEvents.emit('completed', { id: 'job-1', result: { filename: 'render.png' } });
+const queuedJob = (index = 0) => ({ id: `job-${index + 1}`, params: structuredClone(mocks.enqueueJob.mock.calls[index][0].params), result: { filename: 'render.png' } });
+const completed = (job = queuedJob()) => mediaJobEvents.emit('completed', job);
+afterEach(() => vi.useRealTimers());
const publication = () => new Promise(resolve => mediaJobEvents.once('reference-sheet:changed', resolve));
it('announces readiness only after the destination copy and pointer persistence, with correlated recovery state', async () => {
let finishCopy;
mocks.copy.mockImplementation(() => new Promise(resolve => { finishCopy = resolve; }));
+ const queued = await renderCharacterReferenceSheet('universe-1', 'character-1');
let finishWrite;
mocks.update.mockImplementation((_id, update) => new Promise(resolve => {
finishWrite = () => { universe = { ...universe, ...update(universe) }; resolve(); };
}));
- const queued = await renderCharacterReferenceSheet('universe-1', 'character-1');
const listener = vi.fn();
mediaJobEvents.on('reference-sheet:changed', listener);
const result = publication();
@@ -78,18 +82,102 @@ it('reports copy failure and releases pending state for reconnect recovery', asy
const result = publication();
completed();
expect(await result).toMatchObject({ jobId: 'job-1', status: 'failed' });
- expect(mocks.update).not.toHaveBeenCalled();
+ expect(mocks.update).toHaveBeenCalledTimes(1); // Only the durable request claim.
expect(await getCharacterReferenceSheet('universe-1', 'character-1')).toMatchObject({ pendingJobId: null });
});
-it('does not stamp an older render when another job claims the slot during the queued write', async () => {
- mocks.update.mockImplementation(async (_id, update) => {
- claimPendingSheetSlot('universe-1', 'character-1', 'new-job');
- expect(update(universe)).toBeNull();
- });
+it('publishes from persisted job metadata after restart without a subscriber or pending slot', async () => {
+ const requestId = '11111111-1111-4111-8111-111111111111';
+ universe.characters[0].referenceSheetRequests = { blueprint: requestId };
+ const result = publication();
+ completed({ id: 'recovered-job', params: { characterSheet: {
+ universeId: 'universe-1', entryId: 'character-1', variant: 'blueprint', requestId,
+ } }, result: { filename: 'recovered.png' } });
+ expect(await result).toMatchObject({ jobId: 'recovered-job', variant: 'blueprint', status: 'ready' });
+ expect(mocks.copy).toHaveBeenCalledOnce();
+ expect(universe.characters[0].referenceSheets.blueprint).toContain('recovere');
+});
+
+it('releases an expired listener slot and still publishes its later completion', async () => {
+ vi.useFakeTimers();
await renderCharacterReferenceSheet('universe-1', 'character-1');
+ await vi.advanceTimersByTimeAsync(4 * 60 * 60 * 1000);
+ expect(await getCharacterReferenceSheet('universe-1', 'character-1')).toMatchObject({ pendingJobId: null });
const result = publication();
completed();
- await result;
- expect(await getCharacterReferenceSheet('universe-1', 'character-1')).toMatchObject({ pendingJobId: 'new-job' });
+ expect(await result).toMatchObject({ status: 'ready' });
+});
+
+it('keeps newer intent after restart even when its render fails and an older job completes last', async () => {
+ await renderCharacterReferenceSheet('universe-1', 'character-1');
+ const older = queuedJob();
+ mocks.enqueueJob.mockResolvedValue({ jobId: 'job-2', position: 2 });
+ await renderCharacterReferenceSheet('universe-1', 'character-1');
+ const newer = queuedJob(1);
+ mediaJobEvents.emit('failed', newer);
+ slots.reset();
+ const result = publication();
+ completed(older);
+ expect(await result).toMatchObject({ status: 'superseded' });
+ expect(universe.characters[0].referenceSheetImageRef).toBeUndefined();
+});
+
+it('preserves the newest completed pointer and independently rendered variants', async () => {
+ await renderCharacterReferenceSheet('universe-1', 'character-1');
+ const older = queuedJob();
+ mocks.enqueueJob.mockResolvedValue({ jobId: 'job-2', position: 2 });
+ await renderCharacterReferenceSheet('universe-1', 'character-1');
+ const newer = queuedJob(1);
+ const ready = publication();
+ completed(newer);
+ expect(await ready).toMatchObject({ status: 'ready' });
+ const filename = universe.characters[0].referenceSheetImageRef;
+ slots.reset();
+ const stale = publication();
+ completed(older);
+ expect(await stale).toMatchObject({ status: 'superseded' });
+ expect(universe.characters[0].referenceSheetImageRef).toBe(filename);
+
+ mocks.enqueueJob.mockResolvedValue({ jobId: 'job-3', position: 3 });
+ await renderCharacterReferenceSheet('universe-1', 'character-1', { variant: 'blueprint' });
+ const blueprint = publication();
+ completed(queuedJob(2));
+ expect(await blueprint).toMatchObject({ status: 'ready' });
+ expect(universe.characters[0].referenceSheetImageRef).toBe(filename);
+ expect(universe.characters[0].referenceSheets.blueprint).toContain('job-3');
+});
+
+it('does not enqueue if the durable claim fails', async () => {
+ mocks.update.mockRejectedValue(new Error('request write failed'));
+ await expect(renderCharacterReferenceSheet('universe-1', 'character-1')).rejects.toThrow('request write failed');
+ expect(mocks.enqueueJob).not.toHaveBeenCalled();
+});
+
+it('rechecks supersession when the pointer write waits behind a newer request', async () => {
+ await renderCharacterReferenceSheet('universe-1', 'character-1');
+ const job = queuedJob();
+ let finishWrite;
+ mocks.update.mockImplementation((_id, update) => new Promise(resolve => {
+ finishWrite = () => { universe = { ...universe, ...update(universe) }; resolve(); };
+ }));
+ const result = publication();
+ completed(job);
+ await vi.waitFor(() => expect(finishWrite).toBeTypeOf('function'));
+ universe.characters[0].referenceSheetRequests.standard = '22222222-2222-4222-8222-222222222222';
+ finishWrite();
+ expect(await result).toMatchObject({ status: 'superseded' });
+ expect(universe.characters[0].referenceSheetImageRef).toBeUndefined();
+});
+
+it('does not reclaim pending state when a fast job publishes before enqueue returns', async () => {
+ mocks.enqueueJob.mockImplementation(async ({ params }) => {
+ const job = { id: 'fast-job', status: 'completed', params, result: { filename: 'fast.png' } };
+ const result = publication();
+ completed(job);
+ expect(await result).toMatchObject({ status: 'ready' });
+ mocks.getJob.mockReturnValue(job);
+ return { jobId: job.id, position: 1, status: 'queued' };
+ });
+ const queued = await renderCharacterReferenceSheet('universe-1', 'character-1');
+ expect(await getCharacterReferenceSheet('universe-1', 'character-1')).toEqual({ filename: queued.destFilename, pendingJobId: null });
});