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
/**
* Decks — db-primary card-deck design projects (playing cards and tarot).
*
* A deck row holds the style guide (notes + embrace/avoid influences), the
* shared layout clause and face-orientation rule, sample references (gallery
* images the vision step analyzed), per-record render/LLM pins and an optional
* universe link. Each
* card is its own `deck_cards` row so a completed render attaches to exactly
* one card, serialized by the completion hook per deck. Rendered bytes stay in
* the shared gallery (`data/images/`) and are referenced by filename, the same
* way universe canon entries carry `imageRefs`.
*
* Federated (record kind `deck`, sync category `decks`): a deck rides one push
* carrying its own row plus the FULL card roster, merged whole-record LWW on
* the deck's `updatedAt`. The install-capability pins (`imageMode` /
* `imageModelId` / `promptLlm`) and each card's in-flight `render` job state
* are machine-local and stripped from the wire (`syncWire.js`'s `deck` case) —
* a peer may not have the pinned provider, and a jobId means nothing there.
* Rendered gallery bytes flow through the push asset manifest, so a received
* card's `imageRefs` resolve locally. A deck that references a universe carries
* only that universe's id — no canon text crosses with it.
*/
import { randomUUID } from 'node:crypto';
import { query, withTransaction, ensureSchema } from '../lib/db.js';
import { ServerError } from '../lib/errorHandler.js';
import { trimTo, isNonBlankStr } from '../lib/textUtils.js';
import { sanitizeLlmRoutePin } from '../lib/llmRoutePin.js';
import { universeVisualStyleTokens } from '../lib/universeVisualStyle.js';
import {
DECK_CARD_SIZE, DECK_CARD_SIZE_BY_KIND, DEFAULT_DECK_CARD_ORIENTATION, DEFAULT_LAYOUT_PROMPT,
deckCardOrientation, deckCardRoster, deckCompletion,
} from '../lib/deckTemplates.js';
import { DECK_CARD_IMAGE_REFS_MAX, DECK_SAMPLES_MAX } from '../lib/deckValidation.js';
import { recordRenderPin } from '../lib/renderTargets.js';
import { createRecordWriteQueue } from '../lib/fileWriteQueue.js';
import {
contentHashForRecord, setSyncBaseHash, deleteSyncBaseHash, flushBaseHashes,
withBaseHashFlushBatch, maybeJournalBeforeOverwrite,
} from '../lib/conflictJournal.js';
import { emitRecordUpdated, emitRecordDeleted, autoSubscribeRecordToAllPeers } from './sharing/recordEvents.js';
const notFound = (what = 'Deck') => new ServerError(`${what} not found`, {
status: 404, code: what === 'Deck' ? 'DECK_NOT_FOUND' : 'DECK_CARD_NOT_FOUND',
});
const isoOrNull = (v) => (v instanceof Date ? v.toISOString() : (v || null));
// The peer-sync record kind for a deck (see the Federation section below).
export const DECK_KIND = 'deck';
// Per-DECK write tail. EVERY writer goes through it — the REST patches, the
// render-completion hook, the delete, the peer merge and the tombstone sweep —
// because the merge's read-modify-write spans two awaits (read local, then
// upsert) and a REST PATCH landing between them would be silently overwritten.
// Serializing only the merge side would leave exactly that gap open. Card
// writes key on their DECK id, not the card id: a card patch also touches the
// deck row, and the merge rewrites the whole roster, so they contend.
// Nothing inside a queued function may call another queued function — the tail
// is not re-entrant and a nested same-key call would deadlock.
const queueRecordWrite = createRecordWriteQueue();
const filenames = (values) => (Array.isArray(values) ? values : []).map((v) => trimTo(v)).filter(Boolean);
// ── Projections ──────────────────────────────────────────────────────────────
const projectDeck = (row) => {
const d = row.definition && typeof row.definition === 'object' ? row.definition : {};
const pin = recordRenderPin(d);
return {
id: row.id,
name: row.name,
kind: row.kind,
universeId: row.universe_id || null,
description: trimTo(d.description),
styleNotes: trimTo(d.styleNotes),
influences: universeVisualStyleTokens(d),
layoutPrompt: trimTo(d.layoutPrompt) || DEFAULT_LAYOUT_PROMPT[row.kind] || '',
cardOrientation: deckCardOrientation({ kind: row.kind, cardOrientation: d.cardOrientation }),
cardOrientationPrompt: trimTo(d.cardOrientationPrompt) || null,
samples: Array.isArray(d.samples) ? d.samples : [],
imageMode: pin.mode,
imageModelId: pin.modelId,
cardSize: d.cardSize?.width && d.cardSize?.height ? d.cardSize : { ...(DECK_CARD_SIZE_BY_KIND[row.kind] || DECK_CARD_SIZE) },
promptLlm: sanitizeLlmRoutePin(d.promptLlm),
// ISO strings, not the driver's Date objects: these are the LWW clock the
// sync merge compares and the wire form hashes, and a Date compares as
// "not a string" (so every remote would win). JSON output is unchanged.
createdAt: isoOrNull(row.created_at),
updatedAt: isoOrNull(row.updated_at),
deleted: row.deleted === true,
deletedAt: row.deleted === true ? isoOrNull(row.deleted_at) : null,
};
};
const projectCard = (row) => {
const d = row.definition && typeof row.definition === 'object' ? row.definition : {};
return {
id: row.id,
deckId: row.deck_id,
key: row.key,
position: row.position,
name: trimTo(d.name),
group: trimTo(d.group),
groupLabel: trimTo(d.groupLabel),
rank: d.rank ?? null,
motif: trimTo(d.motif) || null,
prompt: trimTo(d.prompt),
negativePrompt: trimTo(d.negativePrompt),
canonRef: d.canonRef && typeof d.canonRef === 'object' ? d.canonRef : null,
imageRefs: filenames(d.imageRefs),
primaryImageRef: trimTo(d.primaryImageRef) || null,
render: d.render && typeof d.render === 'object' ? d.render : null,
updatedAt: isoOrNull(row.updated_at),
};
};
// ── Reads ────────────────────────────────────────────────────────────────────
const loadCards = async (client, deckId) => {
const { rows } = await client.query('SELECT * FROM deck_cards WHERE deck_id = $1 ORDER BY position', [deckId]);
return rows.map(projectCard);
};
const INTERRUPTED_RENDER_ERROR = 'interrupted by restart';
// Same read-time projection as a mood-board note: a queued card whose job is
// gone fails. A missing job id is not a live claim (deck stamps always carry
// one). The wire strips `render`, so this must not move either clock.
function projectInterruptedCardRenders(cards, isLive = () => false) {
const updates = [];
let changed = false;
const next = (Array.isArray(cards) ? cards : []).map((card) => {
const render = card?.render;
if (!render || render.status !== 'queued') return card;
if (render.jobId && isLive(render.jobId)) return card;
changed = true;
updates.push({ id: card.id, jobId: render.jobId || '' });
return { ...card, render: { ...render, status: 'failed', error: INTERRUPTED_RENDER_ERROR } };
});
return { cards: changed ? next : cards, changed, updates };
}
async function reconcileInterruptedCardRenders(deckId, cards) {
if (!cards.some((card) => card.render?.status === 'queued')) return null;
const { getJob } = await import('./mediaJobQueue/index.js');
const isLive = (jobId) => {
const status = getJob(jobId)?.status;
return status === 'queued' || status === 'running';
};
const projected = projectInterruptedCardRenders(cards, isLive);
if (!projected.changed) return null;
const stampedAt = new Date().toISOString();
let wrote = 0;
await queueRecordWrite(deckId, () => withTransaction(async (client) => {
for (const card of projected.updates) {
const { rowCount } = await client.query(
`UPDATE deck_cards
SET definition = jsonb_set(
definition,
'{render}',
(definition->'render') || jsonb_build_object('status', 'failed', 'error', $4::text, 'updatedAt', $5::text)
)
WHERE deck_id = $1 AND id = $2
AND definition->'render'->>'status' = 'queued'
AND COALESCE(definition->'render'->>'jobId', '') = $3`,
[deckId, card.id, card.jobId, INTERRUPTED_RENDER_ERROR, stampedAt],
);
wrote += rowCount;
}
}));
if (wrote) console.warn(`⚠️ Deck ${deckId}: a card render was interrupted by restart`);
return loadCards({ query }, deckId);
}
export async function listDecks({ includeDeleted = false } = {}) {
await ensureSchema();
const { rows } = await query(
`SELECT * FROM decks ${includeDeleted ? '' : 'WHERE deleted IS NOT TRUE'} ORDER BY updated_at DESC, id`,
);
// Completion reads three card fields; project just those instead of every
// card's prompt/history so the index page doesn't pull the whole deck.
// Scoped to the decks actually being returned — a tombstone keeps its roster
// until the GC sweep, so an unscoped scan drags every pending-deletion deck's
// cards through this query for a `byDeck` entry nothing ever looks up.
const { rows: cardRows } = await query(`SELECT deck_id, jsonb_build_object(
'prompt', left(definition->>'prompt', 1), 'imageRefs', COALESCE(definition->'imageRefs', '[]'::jsonb), 'render', definition->'render'
) AS definition FROM deck_cards WHERE deck_id = ANY($1::uuid[])`, [rows.map((r) => r.id)]);
const byDeck = Map.groupBy(cardRows, (r) => r.deck_id);
return rows.map((row) => ({
...projectDeck(row),
completion: deckCompletion((byDeck.get(row.id) || []).map((r) => r.definition)),
}));
}
export async function getDeck(id, { includeDeleted = false, reconcileRenders = true } = {}) {
await ensureSchema();
const { rows } = await query('SELECT * FROM decks WHERE id = $1', [id]);
if (!rows[0] || (!includeDeleted && rows[0].deleted === true)) throw notFound();
let cards = await loadCards({ query }, id);
// Callers already inside this deck's write tail must pass reconcileRenders
// false. The tail is not re-entrant, and a nested heal would deadlock.
if (reconcileRenders) {
const reconciled = await reconcileInterruptedCardRenders(id, cards);
if (reconciled) cards = reconciled;
}
return { ...projectDeck(rows[0]), cards, completion: deckCompletion(cards) };
}
// ── Write helpers ────────────────────────────────────────────────────────────
/**
* Read-mutate-write one deck's definition inside a transaction. `mutate(d, row)`
* edits the definition copy and may return `{ name, universeId }` column
* overrides. Resolves with the fresh deck.
*/
async function patchDeck(id, mutate) {
await ensureSchema();
await queueRecordWrite(id, () => withTransaction(async (client) => {
const { rows } = await client.query('SELECT * FROM decks WHERE id = $1', [id]);
if (!rows[0] || rows[0].deleted === true) throw notFound();
const d = { ...(rows[0].definition || {}) };
const columns = (await mutate(d, rows[0])) || {};
await client.query(
'UPDATE decks SET name = $2, universe_id = $3, definition = $4, updated_at = NOW() WHERE id = $1',
[id, columns.name ?? rows[0].name, columns.universeId === undefined ? rows[0].universe_id : columns.universeId, d],
);
}));
emitRecordUpdated(DECK_KIND, id);
return getDeck(id);
}
/**
* Read-mutate-write one card's definition. `mutate(d)` edits the copy and
* returns false to skip the write. Resolves with the projected card, or null
* when the card is gone / the write was skipped and `missingOk` is set (the
* completion hook's contract: never throw on a card that vanished).
*
* `touch` bumps the DECK's `updatedAt` (the LWW clock the push compares on);
* `touchCard` bumps the CARD row's. Both default on, and both must be off for
* a write that only edits machine-local render bookkeeping: the card's
* `updatedAt` rides the wire and is hashed (only `id`, `deckId` and `render`
* are stripped — `syncWire.js`), so moving it on a purely local write shifts
* the deck's content hash and manufactures a phantom conflict on the next
* push from a peer.
*/
async function patchCard(deckId, cardId, mutate, { missingOk = false, touch = true, touchCard = true } = {}) {
await ensureSchema();
return queueRecordWrite(deckId, () => withTransaction(async (client) => {
const { rows: deckRows } = await client.query('SELECT deleted FROM decks WHERE id = $1', [deckId]);
if (!deckRows[0] || deckRows[0].deleted === true) {
if (missingOk) return null;
throw notFound();
}
const { rows } = await client.query('SELECT * FROM deck_cards WHERE deck_id = $1 AND id = $2', [deckId, cardId]);
if (!rows[0]) {
if (missingOk) return null;
throw notFound('Card');
}
const d = { ...(rows[0].definition || {}) };
if (mutate(d) === false) return null;
const { rows: written } = await client.query(
`UPDATE deck_cards SET definition = $2${touchCard ? ', updated_at = NOW()' : ''} WHERE id = $1 RETURNING *`,
[cardId, d],
);
if (touch) await client.query('UPDATE decks SET updated_at = NOW() WHERE id = $1', [deckId]);
return projectCard(written[0]);
}));
}
// ── Deck CRUD ────────────────────────────────────────────────────────────────
/**
* Create a deck and mint its full card roster. When a universe is linked and
* `seedStyleFromUniverse` is on, the universe's influences + style notes seed
* the deck's style guide (the deck then evolves independently — a sample
* analysis or manual edit never writes back to the universe).
*/
export async function createDeck({ name, kind, description = '', universeId = null, seedStyleFromUniverse = true } = {}) {
await ensureSchema();
let seeded = { styleNotes: '', influences: { embrace: [], avoid: [] } };
if (universeId) {
// Lazy: the universe barrel is heavy and only a linked deck needs it.
const { getUniverse } = await import('./universeBuilder.js');
const universe = await getUniverse(universeId).catch(() => null);
if (!universe) {
throw new ServerError(`Universe not found: ${universeId}`, { status: 400, code: 'DECK_UNIVERSE_NOT_FOUND' });
}
if (seedStyleFromUniverse) {
seeded = { styleNotes: trimTo(universe.styleNotes), influences: universeVisualStyleTokens(universe) };
}
}
const id = randomUUID();
const definition = {
description: trimTo(description),
...seeded,
layoutPrompt: DEFAULT_LAYOUT_PROMPT[kind],
cardOrientation: DEFAULT_DECK_CARD_ORIENTATION[kind] || null,
samples: [],
cardSize: { ...(DECK_CARD_SIZE_BY_KIND[kind] || DECK_CARD_SIZE) },
};
const roster = deckCardRoster(kind);
await withTransaction(async (client) => {
await client.query(
'INSERT INTO decks (id, name, kind, universe_id, definition) VALUES ($1, $2, $3, $4, $5)',
[id, trimTo(name), kind, universeId || null, definition],
);
await client.query(
`INSERT INTO deck_cards (id, deck_id, position, key, definition)
SELECT v.id, $1, v.position, v.key, v.definition
FROM unnest($2::uuid[], $3::int[], $4::text[], $5::jsonb[]) AS v(id, position, key, definition)`,
[
id,
roster.map(() => randomUUID()),
roster.map((_, i) => i),
roster.map((c) => c.key),
roster.map((c) => ({
name: c.name, group: c.group, groupLabel: c.groupLabel, rank: c.rank, motif: c.motif,
prompt: '', negativePrompt: '', imageRefs: [],
})),
],
);
});
console.log(`🃏 deck created "${trimTo(name)}" kind=${kind} cards=${roster.length}${universeId ? ` universe=${universeId}` : ''}`);
// Announce to the per-record push pipeline AND auto-subscribe every
// decks-enabled peer, so a brand-new deck (and its later tombstone)
// propagates without waiting for a manual subscribe. Mirrors the music-video
// / creative-director `announceNewProject` shape.
emitRecordUpdated(DECK_KIND, id);
autoSubscribeRecordToAllPeers(DECK_KIND, id).catch(() => {});
return getDeck(id);
}
/**
* Apply the authored style-guide fields a patch carries onto a deck definition
* copy. Absent keys preserve; a present key applies. Shared by `updateDeck` and
* the conflict-journal `restoreDeck` (whose restorable set is exactly these) so
* a restore can't drift from a normal edit. The install-capability pins are NOT
* here — a restore never carries them (they're stripped from the wire).
*/
function applyDefinitionPatch(d, patch) {
if (patch.description !== undefined) d.description = trimTo(patch.description);
if (patch.styleNotes !== undefined) d.styleNotes = trimTo(patch.styleNotes);
if (patch.influences !== undefined) d.influences = universeVisualStyleTokens({ influences: patch.influences });
if (patch.layoutPrompt !== undefined) d.layoutPrompt = trimTo(patch.layoutPrompt);
if (patch.cardOrientation !== undefined) d.cardOrientation = patch.cardOrientation;
if (patch.cardOrientationPrompt !== undefined) d.cardOrientationPrompt = trimTo(patch.cardOrientationPrompt) || null;
if (patch.samples !== undefined) d.samples = Array.isArray(patch.samples) ? patch.samples.slice(0, DECK_SAMPLES_MAX) : [];
if (patch.cardSize !== undefined) d.cardSize = { width: patch.cardSize.width, height: patch.cardSize.height };
}
/**
* Patch deck-level fields. Absent keys preserve; a present key applies (so
* `universeId: null` unlinks and `imageMode: null` clears the pin — the
* absent-vs-empty rule from root AGENTS.md).
*/
export function updateDeck(id, patch = {}) {
return patchDeck(id, (d) => {
applyDefinitionPatch(d, patch);
if (patch.imageMode !== undefined) d.imageMode = patch.imageMode || null;
if (patch.imageModelId !== undefined) d.imageModelId = patch.imageModelId || null;
if (patch.promptLlm !== undefined) d.promptLlm = sanitizeLlmRoutePin(patch.promptLlm);
return {
...(patch.name !== undefined ? { name: trimTo(patch.name) } : {}),
...(patch.universeId !== undefined ? { universeId: patch.universeId || null } : {}),
};
});
}
/**
* Soft-delete a deck. A hard delete never reaches a peer — the tombstone is
* what converges a subscribed instance, and the GC sweep hard-removes it once
* every peer has had the grace window to see it (`pruneTombstonedDecks`).
* Card rows are kept so a conflict-journal restore can un-tombstone the deck
* with its roster intact; the sweep's ON DELETE CASCADE clears them for good.
*/
export async function deleteDeck(id) {
await ensureSchema();
const rowCount = await queueRecordWrite(id, async () => (await query(
'UPDATE decks SET deleted = TRUE, deleted_at = NOW(), updated_at = NOW() WHERE id = $1 AND deleted IS NOT TRUE',
[id],
)).rowCount);
if (!rowCount) throw notFound();
console.log(`🃏 deck deleted ${id}`);
emitRecordDeleted(DECK_KIND, id);
return { ok: true };
}
// ── Cards ────────────────────────────────────────────────────────────────────
/** Patch one card's authored fields (prompt, negative, name, refs, canon link). */
export async function updateCard(deckId, cardId, patch = {}) {
const card = await patchCard(deckId, cardId, (d) => {
if (patch.name !== undefined) d.name = trimTo(patch.name);
if (patch.prompt !== undefined) { d.prompt = trimTo(patch.prompt); d.promptSource = 'edited'; }
if (patch.negativePrompt !== undefined) d.negativePrompt = trimTo(patch.negativePrompt);
if (patch.canonRef !== undefined) d.canonRef = patch.canonRef || null;
if (patch.imageRefs !== undefined) d.imageRefs = filenames(patch.imageRefs).slice(-DECK_CARD_IMAGE_REFS_MAX);
if (patch.primaryImageRef !== undefined) d.primaryImageRef = patch.primaryImageRef || null;
// A primary that no longer exists in the history falls back to the latest.
if (d.primaryImageRef && !filenames(d.imageRefs).includes(d.primaryImageRef)) d.primaryImageRef = null;
});
emitRecordUpdated(DECK_KIND, deckId);
return card;
}
/**
* Bulk-apply generated prompts / canon assignments. `entries` is
* `[{ cardId, prompt?, canonRef? }]`; a card whose id is unknown is skipped
* (the deck may have been edited between generation and apply).
*/
export async function applyCardGenerations(deckId, entries = []) {
let applied = 0;
for (const entry of entries) {
const card = await patchCard(deckId, entry.cardId, (d) => {
if (entry.prompt !== undefined) { d.prompt = trimTo(entry.prompt); d.promptSource = 'generated'; }
if (entry.canonRef !== undefined) d.canonRef = entry.canonRef || null;
}, { missingOk: true, touch: false });
if (card) applied += 1;
}
if (applied) {
await queueRecordWrite(deckId, () => query('UPDATE decks SET updated_at = NOW() WHERE id = $1', [deckId]));
emitRecordUpdated(DECK_KIND, deckId);
}
return applied;
}
/**
* Stamp freshly queued renders onto their cards in one statement:
* `entries` is `[{ cardId, render }]`. A card the completion hook already
* filed for the SAME job (a backend that finished before the stamp landed)
* keeps its completed record — the queued stamp must not regress it.
*
* Deliberately leaves `updated_at` alone on both tables: which job a card is
* waiting on is machine-local bookkeeping the wire strips, so bumping the
* card's clock would move the deck's sync content hash for a state that means
* nothing on a peer (#7364).
*/
export async function markCardsRenderQueued(deckId, entries = []) {
if (!entries.length) return;
await ensureSchema();
const stampedAt = new Date().toISOString();
await queueRecordWrite(deckId, () => query(
`UPDATE deck_cards c
SET definition = c.definition || jsonb_build_object('render', v.render)
FROM unnest($2::uuid[], $3::jsonb[]) AS v(id, render)
WHERE c.deck_id = $1 AND c.id = v.id
AND COALESCE(c.definition->'render'->>'jobId', '') <> v.render->>'jobId'`,
[deckId, entries.map((e) => e.cardId), entries.map((e) => ({ ...e.render, updatedAt: stampedAt }))],
));
}
/**
* Terminal state for a render that never produced a file. Only the job the
* card is currently waiting on may flip it — a stale failure event for a
* superseded job must not mark a newer queued render as failed. Like the
* queued stamp above this edits only the wire-stripped `render` record, so
* neither clock moves (#7364).
*/
export function markCardRenderTerminal(deckId, cardId, { jobId, status, error = null }) {
return patchCard(deckId, cardId, (d) => {
if (!d.render || d.render.jobId !== jobId) return false;
d.render = { ...d.render, status, error: error || null, updatedAt: new Date().toISOString() };
}, { missingOk: true, touch: false, touchCard: false });
}
/**
* Attach a completed render to its card (called by the completion hook):
* append the gallery filename, promote it to primary, clear the in-flight
* record. Returns the card, or null when the card no longer exists.
*/
export async function attachCardRender({ deckId, cardId, filename, jobId }) {
const card = await patchCard(deckId, cardId, (d) => {
d.imageRefs = [...filenames(d.imageRefs).filter((f) => f !== filename), filename].slice(-DECK_CARD_IMAGE_REFS_MAX);
d.primaryImageRef = filename;
d.render = { ...(d.render || {}), jobId, status: 'completed', error: null, filename, updatedAt: new Date().toISOString() };
}, { missingOk: true });
// `imageRefs` / `primaryImageRef` are wire-visible, so a completed render is
// a real content change peers must receive (the in-flight `render` stamps
// above are stripped from the wire and deliberately announce nothing).
if (card) emitRecordUpdated(DECK_KIND, deckId);
return card;
}
// ── Samples (style references) ───────────────────────────────────────────────
/**
* Persist an analyzed sample; with `adopt`, apply the proposed style guide in
* the same transaction so the pair can't half-land. Idempotent on sample id.
*/
export function addSample(id, sample, { adopt } = {}) {
return patchDeck(id, (d) => {
const samples = (Array.isArray(d.samples) ? d.samples : []).filter((s) => s?.id !== sample.id);
samples.push({
id: sample.id,
title: trimTo(sample.title),
prompt: trimTo(sample.prompt),
imageRef: sample.imageRef,
createdAt: sample.createdAt || new Date().toISOString(),
});
if (samples.length > DECK_SAMPLES_MAX) {
throw new ServerError(`A deck holds at most ${DECK_SAMPLES_MAX} samples`, { status: 400, code: 'DECK_SAMPLES_MAX' });
}
d.samples = samples;
if (adopt) {
d.styleNotes = trimTo(adopt.styleNotes);
d.influences = universeVisualStyleTokens(adopt);
if (trimTo(adopt.layoutPrompt)) d.layoutPrompt = trimTo(adopt.layoutPrompt);
}
});
}
export function removeSample(id, sampleId) {
return patchDeck(id, (d) => {
d.samples = (Array.isArray(d.samples) ? d.samples : []).filter((s) => s?.id !== sampleId);
});
}
// ── Federation (record kind `deck`, sync category `decks`) ───────────────────
//
// A deck rides ONE push carrying the deck row plus its full card roster, merged
// whole-record LWW on the deck's `updatedAt`. Cards are addressed by their
// stable roster `key` (not by row id) so two machines that minted the same deck
// kind converge on the same 52/78 slots instead of doubling them. Card ids stay
// machine-local for the same reason: the receiver keeps its own row id for a key
// it already holds, and mints one for a key it doesn't.
/**
* One deck's sanitized record (tombstone surfaced), or null when unknown. Only
* a genuine miss answers null — a DB fault must NOT read as "absent," or the
* merge would treat an existing deck as new and skip the LWW compare entirely.
*/
export async function getDeckForSync(id) {
return getDeck(id, { includeDeleted: true, reconcileRenders: false }).catch((error) => {
if (error?.code === 'DECK_NOT_FOUND') return null;
throw error;
});
}
/** Every LIVE deck as `{ id, updatedAt }` — the full-sync coverage compare set. */
export async function listDecksForSync() {
await ensureSchema();
const { rows } = await query('SELECT id, updated_at FROM decks WHERE deleted IS NOT TRUE');
return rows.map((r) => ({ id: r.id, updatedAt: isoOrNull(r.updated_at) }));
}
/** Deck ids — live only by default, or all (incl. tombstones) for the sweep. */
export async function listDeckIdsForSync({ includeDeleted = false } = {}) {
await ensureSchema();
const { rows } = await query(
`SELECT id FROM decks ${includeDeleted ? '' : 'WHERE deleted IS NOT TRUE'}`,
);
return rows.map((r) => r.id);
}
// The wire-form card fields the receiver persists. `id` and `render` are
// machine-local (a row id and an in-flight jobId mean nothing on a peer), so a
// remote card never overwrites either.
const cardDefinitionFromRemote = (card) => ({
name: trimTo(card?.name),
group: trimTo(card?.group),
groupLabel: trimTo(card?.groupLabel),
rank: card?.rank ?? null,
motif: trimTo(card?.motif) || null,
prompt: trimTo(card?.prompt),
negativePrompt: trimTo(card?.negativePrompt),
canonRef: card?.canonRef && typeof card.canonRef === 'object' ? card.canonRef : null,
imageRefs: filenames(card?.imageRefs).slice(-DECK_CARD_IMAGE_REFS_MAX),
primaryImageRef: trimTo(card?.primaryImageRef) || null,
});
// The deck-level definition fields that travel. The install-capability pins
// (`imageMode` / `imageModelId` / `promptLlm`) are absent from the wire, so the
// receiver's own pins are carried forward from its local copy instead of being
// reset to null by a remote win.
const definitionFromRemote = (remote, local) => ({
description: trimTo(remote?.description),
styleNotes: trimTo(remote?.styleNotes),
influences: universeVisualStyleTokens(remote),
layoutPrompt: trimTo(remote?.layoutPrompt),
// A pre-v2 peer has no keys to send. Preserve a receiver's authored choice
// in that sender-behind case; a current peer's explicit null still clears a
// prompt override as intended.
cardOrientation: Object.hasOwn(remote || {}, 'cardOrientation')
? deckCardOrientation({ kind: remote?.kind, cardOrientation: remote?.cardOrientation })
: (local?.cardOrientation || DEFAULT_DECK_CARD_ORIENTATION[remote?.kind] || null),
cardOrientationPrompt: Object.hasOwn(remote || {}, 'cardOrientationPrompt')
? (trimTo(remote?.cardOrientationPrompt) || null)
: (local?.cardOrientationPrompt || null),
samples: Array.isArray(remote?.samples) ? remote.samples.slice(0, DECK_SAMPLES_MAX) : [],
cardSize: remote?.cardSize?.width && remote?.cardSize?.height
? { width: remote.cardSize.width, height: remote.cardSize.height }
: undefined,
imageMode: local?.imageMode ?? null,
imageModelId: local?.imageModelId ?? null,
promptLlm: local?.promptLlm ?? null,
});
// Newest ISO timestamp wins; a tie keeps the local copy (no churn on equal clocks).
const remoteWinsOver = (remoteAt, localAt) => {
if (!isNonBlankStr(remoteAt)) return false;
if (!isNonBlankStr(localAt)) return true;
return new Date(remoteAt).getTime() > new Date(localAt).getTime();
};
/**
* Apply one remote deck inside a transaction: upsert the deck row (tombstone
* included) and reconcile its cards by roster `key` — upsert what the remote
* carries, drop the keys it no longer has. A tombstone carries no cards, so it
* leaves the local roster alone (a restore then has something to restore to).
*/
async function writeRemoteDeck(id, remote, local) {
const localDefinition = local ? {
imageMode: local.imageMode,
imageModelId: local.imageModelId,
promptLlm: local.promptLlm,
cardOrientation: local.cardOrientation,
cardOrientationPrompt: local.cardOrientationPrompt,
} : null;
await withTransaction(async (client) => {
const definition = definitionFromRemote(remote, localDefinition);
if (definition.cardSize === undefined) {
definition.cardSize = { ...(DECK_CARD_SIZE_BY_KIND[remote.kind] || DECK_CARD_SIZE) };
}
await client.query(
`INSERT INTO decks (id, name, kind, universe_id, definition, updated_at, deleted, deleted_at)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
ON CONFLICT (id) DO UPDATE SET
name = EXCLUDED.name, kind = EXCLUDED.kind, universe_id = EXCLUDED.universe_id,
definition = EXCLUDED.definition, updated_at = EXCLUDED.updated_at,
deleted = EXCLUDED.deleted, deleted_at = EXCLUDED.deleted_at`,
[
id, trimTo(remote.name), remote.kind, remote.universeId || null, definition,
remote.updatedAt, remote.deleted === true,
remote.deleted === true ? (remote.deletedAt || new Date().toISOString()) : null,
],
);
if (remote.deleted === true) return;
const cards = Array.isArray(remote.cards) ? remote.cards : [];
if (!cards.length) return;
await client.query(
`INSERT INTO deck_cards (id, deck_id, position, key, definition)
SELECT COALESCE(existing.id, v.new_id), $1, v.position, v.key, v.definition
FROM unnest($2::uuid[], $3::int[], $4::text[], $5::jsonb[]) AS v(new_id, position, key, definition)
LEFT JOIN deck_cards existing ON existing.deck_id = $1 AND existing.key = v.key
ON CONFLICT (deck_id, key) DO UPDATE SET
position = EXCLUDED.position, definition = EXCLUDED.definition, updated_at = NOW()`,
[
id,
cards.map(() => randomUUID()),
cards.map((c, i) => (Number.isInteger(c?.position) ? c.position : i)),
cards.map((c) => String(c.key)),
cards.map(cardDefinitionFromRemote),
],
);
await client.query(
'DELETE FROM deck_cards WHERE deck_id = $1 AND key <> ALL($2::text[])',
[id, cards.map((c) => String(c.key))],
);
});
}
/**
* Merge an incoming batch of deck records from a peer (LWW, tombstone-aware).
* Serialized per-id against the REST writers, journals the about-to-be-
* overwritten local version when the remote wins, and re-stamps the
* conflict-journal base hash for the record it just wrote.
*/
export async function mergeDecksFromSync(remoteRecords, { source = { via: 'sync', peerId: null } } = {}) {
if (!Array.isArray(remoteRecords) || !remoteRecords.length) return { applied: false, count: 0 };
await ensureSchema();
let changed = 0;
for (const remote of remoteRecords) {
const id = remote?.id;
// `kind` is a CHECK-constrained column — a record naming an unknown deck
// kind would fail the INSERT, so drop it on the floor like a missing id.
if (!isNonBlankStr(id) || !isNonBlankStr(remote?.kind) || !DECK_CARD_SIZE_BY_KIND[remote.kind]) continue;
const applied = await queueRecordWrite(id, async () => {
const local = await getDeckForSync(id);
if (local && !remoteWinsOver(remote.updatedAt, local.updatedAt)) return false;
// An already-tombstoned local deck re-receiving the same tombstone is a
// no-op — writing it would restart its GC grace period every cycle.
if (local?.deleted === true && remote.deleted === true) return false;
if (local) {
await maybeJournalBeforeOverwrite({ kind: DECK_KIND, id, local, remote, source });
}
await writeRemoteDeck(id, remote, local);
const merged = await getDeckForSync(id);
if (merged) await setSyncBaseHash(DECK_KIND, id, contentHashForRecord(DECK_KIND, merged));
return true;
});
if (applied) changed += 1;
}
await flushBaseHashes();
if (changed > 0) console.log(`🃏 deck sync: merged ${changed} deck(s)`);
return changed === 0 ? { applied: false, count: 0 } : { applied: true, count: changed };
}
/**
* Hard-remove tombstoned decks deleted before `cutoffEpochMs`; evicts each base
* hash. `cutoffEpochMs` is an ABSOLUTE epoch-ms instant (what `cutoffForKind`
* produces), not a duration — matching every other `pruneTombstonedX`.
*/
export async function pruneTombstonedDecks(cutoffEpochMs) {
if (!Number.isFinite(cutoffEpochMs)) return { pruned: 0, ids: [] };
await ensureSchema();
const cutoff = new Date(cutoffEpochMs).toISOString();
const { rows } = await query(
'SELECT id FROM decks WHERE deleted IS TRUE AND deleted_at IS NOT NULL AND deleted_at < $1',
[cutoff],
);
const ids = [];
await withBaseHashFlushBatch(async () => {
for (const row of rows) {
// Re-check the predicate INSIDE the per-id tail: a merge that rewrote
// this tombstone with a fresher deletedAt mid-sweep restarted its grace
// period, and hard-deleting it early would let an offline peer
// resurrect the record. Cards go with it via ON DELETE CASCADE.
const pruned = await queueRecordWrite(row.id, async () => {
const { rowCount } = await query(
'DELETE FROM decks WHERE id = $1 AND deleted IS TRUE AND deleted_at < $2',
[row.id, cutoff],
);
return rowCount > 0;
});
if (!pruned) continue;
ids.push(row.id);
await deleteSyncBaseHash(DECK_KIND, row.id).catch(() => {});
}
});
if (ids.length) console.log(`🃏 deck tombstone GC: pruned ${ids.length} deck(s)`);
return { pruned: ids.length, ids };
}
/**
* Restore a tombstoned/overwritten deck from a conflict-journal snapshot:
* apply the restorable fields, un-tombstone, and bump `updatedAt` so the
* restore wins the next LWW and re-pushes. Returns null for a deck that has
* already been hard-pruned (→ ERR_TARGET_GONE at the route).
*/
export async function restoreDeck(id, patch = {}) {
await ensureSchema();
return queueRecordWrite(id, async () => {
const { rows } = await query('SELECT * FROM decks WHERE id = $1', [id]);
if (!rows[0]) return null;
const d = { ...(rows[0].definition || {}) };
applyDefinitionPatch(d, patch);
await query(
`UPDATE decks SET name = $2, universe_id = $3, definition = $4,
updated_at = NOW(), deleted = FALSE, deleted_at = NULL WHERE id = $1`,
[
id,
patch.name !== undefined ? trimTo(patch.name) : rows[0].name,
patch.universeId !== undefined ? (patch.universeId || null) : rows[0].universe_id,
d,
],
);
emitRecordUpdated(DECK_KIND, id);
return getDeck(id, { reconcileRenders: false });
});
}