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
import { assertCatalogIdentityWritable } from './catalogDB/identityAccess.js';
/**
* Catalog image-attach hook (issue #1359).
*
* Subscribes to mediaJobEvents and, for each completed image job that carries
* `params.catalogAttach.ingredientId`, attaches the rendered filename onto that
* catalog ingredient — server-side, independent of any mounted client. This is
* the durable counterpart to CatalogIngredient.jsx's mounted `onFilename`
* callback: a long-running local/Codex render that completes after the user has
* navigated away, refreshed, or switched ingredients still lands a portrait or
* reference row (previously the image reached the media library but no row was
* ever created, so the attachment was silently lost).
*
* Decision mirrors the client's optimistic path (`handleGeneratedImage`): the
* first image becomes the portrait, later ones attach as references — unless an
* explicit `kind` was requested. Idempotent against the client path: when the
* filename is already attached (the still-mounted client won the race), the hook
* is a no-op, so the same render never lands as both portrait AND reference.
*
* The shared completion-hook scaffold (tag-decode, per-ingredient
* serialization, best-effort error handling, idempotent init/reset) lives in
* `createMediaJobImageHook` (#1791) — this file is just the catalog-specific
* config plus the portrait newest-render-wins guard below. Mounted once at
* server boot from server/index.js (after the media job queue is running).
*/
import { createMediaJobImageHook } from './mediaJobImageHook.js';
import { attachMedia, setPortraitMedia, listMediaForIngredient, getIngredient } from './catalogDB.js';
import { readImageGenerationMetadata } from './catalogMedia.js';
import { createNewestWinsGuard } from '../lib/createNewestWinsGuard.js';
// Newest-render-wins for the PORTRAIT slot only (#1791). The per-ingredient
// serialize already stops two concurrent renders from clobbering each other,
// but an OLDER render completing AFTER a newer portrait (e.g. an out-of-order
// Codex regenerate) would still demote the newer one. Unlike the scene-frame
// hooks — which drop a stale render outright — catalog references are additive,
// so instead of losing the image we file a stale would-be-portrait as a
// reference. Keyed per ingredient; absent `queuedAt` is never stale, so the
// guard is inert for renders the queue didn't timestamp.
const portraitGuard = createNewestWinsGuard();
// Resolve the render onto the ingredient. Returns the kind attached
// ('portrait' | 'reference'), 'duplicate' when the client already filed it,
// 'gone' when the target ingredient no longer exists, or throws on a real DB
// error (caught by the factory).
async function attachGeneratedImage({ ingredientId, kind, role, filename, queuedAt }) {
await assertCatalogIdentityWritable(ingredientId);
// The ingredient can be deleted between enqueue and completion (a render
// outlives its editor by minutes). `getIngredient` filters `deleted = false`,
// so this skips a hard-deleted ingredient (FK would throw) AND a soft-deleted
// one (FK is satisfied — attaching would silently file media onto a tombstone
// and fan those rows to peers via sync_sequence).
if (!(await getIngredient(ingredientId))) return 'gone';
const existing = await listMediaForIngredient(ingredientId);
// Idempotent against the optimistic client path: it already attached this
// exact render (under any kind) — don't double-file it as a second kind.
const existingRow = existing.find((m) => m.mediaKey === filename);
if (existingRow) {
// The mounted client won the optimistic attach for this render. If it
// landed as the PORTRAIT, still record its queuedAt in the guard — otherwise
// a later OLDER portrait render isn't seen as stale and would clobber this
// newer one (the guard's mark normally happens on our own setPortraitMedia
// write below, which this duplicate path skips).
if (existingRow.kind === 'portrait') portraitGuard.mark(ingredientId, queuedAt);
return 'duplicate';
}
const hasPortrait = existing.some((m) => m.kind === 'portrait');
// A role-tagged render (a reference sheet, `sheet:<variant>`) is always a
// reference: it must never take the portrait slot. Otherwise explicit kind
// wins; else auto: first image → portrait, later → reference (mirrors
// CatalogIngredient.jsx `handleGeneratedImage`).
const mediaRole = typeof role === 'string' && role.trim() ? role.trim() : null;
let target = mediaRole ? 'reference'
: kind === 'portrait' || kind === 'reference'
? kind
: (hasPortrait ? 'reference' : 'portrait');
// A stale would-be-portrait must not demote a newer portrait. Keep the image
// as a reference rather than dropping it (references are additive).
if (target === 'portrait' && portraitGuard.isStale(ingredientId, queuedAt)) {
target = 'reference';
}
const metadata = await readImageGenerationMetadata(filename);
const metadataOptions = Object.keys(metadata).length > 0 ? { metadata } : null;
if (target === 'portrait') {
if (metadataOptions) await setPortraitMedia(ingredientId, filename, metadataOptions);
else await setPortraitMedia(ingredientId, filename);
portraitGuard.mark(ingredientId, queuedAt);
} else {
const referenceOptions = { ...(mediaRole ? { role: mediaRole } : {}), ...(metadataOptions || {}) };
if (Object.keys(referenceOptions).length > 0) await attachMedia(ingredientId, filename, 'reference', referenceOptions);
else await attachMedia(ingredientId, filename, 'reference');
}
return target;
}
const hook = createMediaJobImageHook({
label: 'catalog image-attach',
initLog: '🏷️ Catalog image-attach hook initialized',
tagKey: 'catalogAttach',
identify: (tag) => (typeof tag?.ingredientId === 'string' && tag.ingredientId
? { ingredientId: tag.ingredientId }
: null),
// Serialize the read→decide→write per ingredient so two renders for the SAME
// ingredient don't both read an empty media list, both pick 'portrait', and
// have the second demote the first. Different ingredients attach concurrently.
serializeKey: ({ ingredientId }) => ingredientId,
describe: ({ ingredientId }) => ingredientId,
attach: ({ ingredientId, tag, filename, queuedAt }) => attachGeneratedImage({
ingredientId, kind: tag.kind, role: tag.role, filename, queuedAt,
}),
onAttached: ({ ingredientId, filename }, status) => {
if (status === 'portrait' || status === 'reference') {
console.log(`🏷️ catalog ingredient ${ingredientId.slice(0, 8)} ← ${status} ${filename}`);
}
},
});
export function initCatalogImageAttachHook() {
hook.init();
}
// Test-only reset — also clears the portrait guard the factory doesn't own.
export const __testing = {
reset: () => {
hook.__testing.reset();
portraitGuard.clear();
},
settled: hook.__testing.settled,
};