@protoyard/blueprint 0.0.0-stage → 1.1.0

package/dist/services.js

@@ -0,0 +1,898 @@
+import { createRuntimeId, parseInput, ValidationError, } from '@protoyard/core';
+import { z } from 'zod';
+import { blueprintUsesAudit, createAuditWriter } from "./audit.js";
+import { avatarFields, nextAvatar } from "./avatar.js";
+import { mapCsvHeaders, parseCsv, serializeEntityCsv, } from "./csv.js";
+import { createNotificationWriter } from "./notifications.js";
+import { entityTable, } from "./schema.js";
+import { FEATURE_TABLES } from "./storage.js";
+import { deriveInputSchemas, fieldLabel, inputProperty } from "./validation.js";
+/** Thrown when a record does not exist (or was removed meanwhile). */
+export class EntityNotFoundError extends Error {
+    code = 'not-found';
+    constructor(entity, id) {
+        super(`No ${entity} with id "${id}".`);
+        this.name = 'EntityNotFoundError';
+    }
+}
+/** Thrown when `onDelete: 'restrict'` blocks a removal; nothing was deleted. */
+export class EntityInUseError extends Error {
+    code = 'in-use';
+    constructor(entity, references) {
+        const list = Object.entries(references)
+            .map(([name, count]) => `${count} ${name}`)
+            .join(', ');
+        super(`This ${entity} can't be deleted: ${list} still reference it.`);
+        this.name = 'EntityInUseError';
+    }
+}
+/** Thrown when commit is requested and invalid rows remain without `skipInvalid`. */
+export class ImportCsvError extends Error {
+    code = 'import-invalid';
+    report;
+    constructor(report) {
+        super(`CSV import has ${report.errors.length} invalid cell(s) across ${report.rowCount} row(s); nothing was written.`);
+        this.name = 'ImportCsvError';
+        this.report = report;
+    }
+}
+/** Writes larger than this go through several `bulkPut` calls inside the same transaction. */
+export const BULK_CHUNK = 1_000;
+export const UNDO_WINDOW_MS = 30_000;
+const UndoPayloadSchema = z.strictObject({ version: z.literal(2), rootId: z.string().min(1) });
+class UndoTokenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UndoTokenError';
+    }
+}
+function encodeUndoToken(payload) {
+    return `blueprint-undo-v2:${encodeURIComponent(JSON.stringify(payload))}`;
+}
+function decodeUndoToken(token) {
+    const prefix = 'blueprint-undo-v2:';
+    if (!token.startsWith(prefix))
+        throw new UndoTokenError('This undo token is invalid.');
+    try {
+        const result = UndoPayloadSchema.safeParse(JSON.parse(decodeURIComponent(token.slice(prefix.length))));
+        if (!result.success)
+            throw new UndoTokenError('This undo token is invalid.');
+        return result.data;
+    }
+    catch (error) {
+        if (error instanceof UndoTokenError)
+            throw error;
+        throw new UndoTokenError('This undo token is invalid.');
+    }
+}
+async function putChunked(table, rows) {
+    for (let i = 0; i < rows.length; i += BULK_CHUNK) {
+        await table.bulkPut(rows.slice(i, i + BULK_CHUNK));
+    }
+}
+export function createEntityServices(runtime, blueprint) {
+    const db = runtime.db;
+    const { session, environment, clock } = runtime;
+    const byName = new Map(blueprint.entities.map((e) => [e.name, e]));
+    const tables = blueprint.entities.map(entityTable);
+    const filesEnabled = blueprint.entities.some((e) => e.features.files);
+    const notificationsEnabled = blueprint.notifications.length > 0 || blueprint.entities.some((e) => e.features.notifications);
+    const auditEnabled = blueprintUsesAudit(blueprint);
+    const writeTables = [
+        ...tables,
+        ...(filesEnabled ? [FEATURE_TABLES.files] : []),
+        ...(notificationsEnabled ? [FEATURE_TABLES.notifications] : []),
+        ...(auditEnabled ? [FEATURE_TABLES.audit] : []),
+        'py_personas',
+        ...(blueprint.notifications.some((rule) => rule.notify.startsWith('role:'))
+            ? ['py_memberships']
+            : []),
+    ];
+    const notify = createNotificationWriter(runtime, blueprint);
+    const audit = createAuditWriter(runtime, blueprint);
+    /** Relation fields (in any entity) that point at `target`. */
+    const referencesTo = (target) => blueprint.entities.flatMap((entity) => entity.fields.flatMap((field) => field.kind === 'relation' && field.to === target
+        ? [{ entity, table: entityTable(entity), field, property: inputProperty(field) }]
+        : []));
+    const actorId = () => {
+        const principal = session.principal();
+        if (!principal)
+            throw new Error('No active persona. Load a scenario first.');
+        return principal.persona.id;
+    };
+    /**
+     * Resolves a relation cell to a stored id: exact id match first, then a unique
+     * title-field match on the target entity (soft-deleted targets are ignored).
+     */
+    async function resolveRelationCell(field, raw) {
+        const trimmed = raw.trim();
+        if (!trimmed) {
+            throw new ValidationError({
+                [inputProperty(field)]: `${fieldLabel(field)} is required`,
+            });
+        }
+        const target = byName.get(field.to);
+        if (!target) {
+            throw new ValidationError({
+                [inputProperty(field)]: `${fieldLabel(field)} target is unknown`,
+            });
+        }
+        const targetTable = entityTable(target);
+        const byId = await db.table(targetTable).get(trimmed);
+        if (byId && !byId.deletedAt)
+            return byId.id;
+        const titleField = target.fields.find((f) => f.name === target.titleField);
+        const titleProp = titleField ? inputProperty(titleField) : 'id';
+        const matches = (await db.table(targetTable).toArray()).filter((row) => !row.deletedAt && String(row[titleProp] ?? '') === trimmed);
+        if (matches.length === 1)
+            return matches[0].id;
+        if (matches.length === 0) {
+            throw new ValidationError({
+                [inputProperty(field)]: `${fieldLabel(field)} not found`,
+            });
+        }
+        throw new ValidationError({
+            [inputProperty(field)]: `${fieldLabel(field)} matches more than one ${target.name}`,
+        });
+    }
+    async function resolveImportCell(field, raw) {
+        if (!field)
+            return raw;
+        if (field.kind === 'relation') {
+            if (raw.trim() === '')
+                return null;
+            if (field.cardinality === 'many') {
+                const parts = raw
+                    .split(',')
+                    .map((p) => p.trim())
+                    .filter(Boolean);
+                const ids = [];
+                for (const part of parts)
+                    ids.push(await resolveRelationCell(field, part));
+                return ids;
+            }
+            return resolveRelationCell(field, raw);
+        }
+        if (field.kind === 'persona') {
+            if (raw.trim() === '')
+                return null;
+            const trimmed = raw.trim();
+            const byId = await db.table('py_personas').get(trimmed);
+            if (byId)
+                return byId.id;
+            const people = await db.table('py_personas').toArray();
+            const matches = people.filter((row) => String(row.name ?? '') === trimmed ||
+                String(row.displayName ?? '') === trimmed ||
+                String(row.email ?? '') === trimmed);
+            if (matches.length === 1)
+                return matches[0].id;
+            if (matches.length === 0) {
+                throw new ValidationError({
+                    [inputProperty(field)]: `${fieldLabel(field)} not found`,
+                });
+            }
+            throw new ValidationError({
+                [inputProperty(field)]: `${fieldLabel(field)} matches more than one persona`,
+            });
+        }
+        return raw;
+    }
+    /**
+     * Parse + resolve relations/personas by id or title, then validate each row
+     * against the create schema. Does not write.
+     */
+    async function previewImportCsv(entity, text, options = {}) {
+        const matrix = parseCsv(text, options);
+        const [headerRow, ...dataRows] = matrix;
+        if (!headerRow) {
+            return { headers: [], columns: [], valid: [], errors: [], rowCount: 0 };
+        }
+        const columns = mapCsvHeaders(headerRow, entity);
+        const { create } = deriveInputSchemas(entity);
+        const valid = [];
+        const errors = [];
+        let rowCount = 0;
+        for (let index = 0; index < dataRows.length; index += 1) {
+            const cells = dataRows[index];
+            if (cells.every((c) => c.trim() === ''))
+                continue;
+            rowCount += 1;
+            const rowNumber = index + 1;
+            const raw = {};
+            try {
+                for (let colIndex = 0; colIndex < columns.length; colIndex += 1) {
+                    const col = columns[colIndex];
+                    if (!col?.property)
+                        continue;
+                    raw[col.property] = await resolveImportCell(col.field, cells[colIndex] ?? '');
+                }
+                valid.push(parseInput(create, raw));
+            }
+            catch (error) {
+                if (error instanceof ValidationError) {
+                    for (const [field, message] of Object.entries(error.issues)) {
+                        errors.push({ row: rowNumber, field, message });
+                    }
+                }
+                else {
+                    errors.push({
+                        row: rowNumber,
+                        field: 'row',
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }
+        return { headers: headerRow, columns, valid, errors, rowCount };
+    }
+    /** CSV import commits use the same audit writer as live mutations (diff + redaction). */
+    async function writeAuditBatch(entity, rows, action) {
+        if (!entity.features.audit || rows.length === 0)
+            return [];
+        const ids = [];
+        for (const row of rows) {
+            const entry = await audit({
+                action,
+                entity,
+                recordId: row.id,
+                before: null,
+                after: row,
+            });
+            if (entry)
+                ids.push(entry.id);
+        }
+        return ids;
+    }
+    /** Fails with a field-keyed ValidationError when a referenced row is missing. */
+    async function assertReferences(entity, values) {
+        const issues = {};
+        for (const field of entity.fields) {
+            const property = inputProperty(field);
+            const value = values[property];
+            if (value === null || value === undefined)
+                continue;
+            const table = field.kind === 'relation'
+                ? entityTable(byName.get(field.to))
+                : field.kind === 'persona'
+                    ? 'py_personas'
+                    : field.kind === 'file' && filesEnabled
+                        ? FEATURE_TABLES.files
+                        : null;
+            if (!table)
+                continue;
+            const ids = Array.isArray(value) ? value : [value];
+            for (const id of ids) {
+                const target = await db.table(table).get(id);
+                if (!target || (field.kind === 'relation' && Boolean(target.deletedAt))) {
+                    issues[property] = `${fieldLabel(field)} not found`;
+                    break;
+                }
+            }
+        }
+        if (Object.keys(issues).length > 0)
+            throw new ValidationError(issues);
+    }
+    /**
+     * Deletes `ids` of `entity` and applies every `onDelete` rule in the current
+     * transaction: cascades are followed first, then restrict blocks and
+     * nullify clears references from rows that survive.
+     */
+    async function collectDeleteEffects(entity, ids, softDelete = false) {
+        const doomed = new Map();
+        const queue = [[entity, [...ids]]];
+        while (queue.length > 0) {
+            const [current, batch] = queue.shift();
+            const set = doomed.get(current.name) ?? new Set();
+            doomed.set(current.name, set);
+            const fresh = batch.filter((id) => !set.has(id));
+            for (const id of fresh)
+                set.add(id);
+            if (fresh.length === 0)
+                continue;
+            for (const ref of referencesTo(current.name)) {
+                if (ref.field.onDelete !== 'cascade')
+                    continue;
+                const rows = (await db.table(ref.table).where(ref.property).anyOf(fresh).toArray()).filter((row) => !softDelete || !row.deletedAt);
+                if (rows.length > 0)
+                    queue.push([ref.entity, rows.map((r) => r.id)]);
+            }
+        }
+        const blocked = {};
+        const nullified = new Map();
+        const originalReferences = new Map();
+        for (const [name, set] of doomed) {
+            const removed = [...set];
+            for (const ref of referencesTo(name)) {
+                if (ref.field.onDelete === 'cascade')
+                    continue;
+                const survivors = (await db.table(ref.table).where(ref.property).anyOf(removed).toArray()).filter((row) => !doomed.get(ref.entity.name)?.has(row.id) && (!softDelete || !row.deletedAt));
+                if (survivors.length === 0)
+                    continue;
+                if (ref.field.onDelete === 'restrict') {
+                    blocked[ref.entity.plural] = (blocked[ref.entity.plural] ?? 0) + survivors.length;
+                    continue;
+                }
+                const pending = nullified.get(ref.table) ?? new Map();
+                nullified.set(ref.table, pending);
+                const originals = originalReferences.get(ref.table) ?? new Map();
+                originalReferences.set(ref.table, originals);
+                for (const row of survivors) {
+                    const next = { ...(pending.get(row.id) ?? row) };
+                    const value = next[ref.property];
+                    const rowOriginals = originals.get(row.id) ?? {};
+                    if (!(ref.property in rowOriginals)) {
+                        rowOriginals[ref.property] = Array.isArray(value)
+                            ? [...value]
+                            : typeof value === 'string'
+                                ? value
+                                : null;
+                    }
+                    originals.set(row.id, rowOriginals);
+                    next[ref.property] = Array.isArray(value)
+                        ? value.filter((id) => !set.has(id))
+                        : null;
+                    next.updatedAt = clock.now().toISOString();
+                    pending.set(row.id, next);
+                }
+            }
+        }
+        if (Object.keys(blocked).length > 0)
+            throw new EntityInUseError(entity.name, blocked);
+        return { doomed, nullified, originalReferences, blocked };
+    }
+    async function deleteWithEffects(entity, ids, softDeleteAt, deletedBy, deleteGroupId) {
+        const effects = await collectDeleteEffects(entity, ids, softDeleteAt !== undefined);
+        for (const [table, rows] of effects.nullified) {
+            const originals = effects.originalReferences.get(table);
+            const updated = [...rows.values()].map((row) => {
+                if (!softDeleteAt || !deleteGroupId)
+                    return row;
+                const fields = originals?.get(row.id) ?? {};
+                const order = row.deleteGroupReferenceOrder && typeof row.deleteGroupReferenceOrder === 'object'
+                    ? { ...row.deleteGroupReferenceOrder }
+                    : {};
+                for (const [property, value] of Object.entries(fields)) {
+                    if (!(property in order) && Array.isArray(value))
+                        order[property] = value;
+                }
+                return {
+                    ...row,
+                    deleteGroupId,
+                    deleteGroupReferences: {
+                        ...(row.deleteGroupReferences && typeof row.deleteGroupReferences === 'object'
+                            ? row.deleteGroupReferences
+                            : {}),
+                        [deleteGroupId]: fields,
+                    },
+                    deleteGroupReferenceOrder: order,
+                };
+            });
+            await putChunked(db.table(table), updated);
+        }
+        let count = 0;
+        const undoRows = [];
+        if (softDeleteAt !== undefined) {
+            for (const [name, set] of effects.doomed) {
+                const idsToDelete = [...set];
+                const target = byName.get(name);
+                const targetTable = db.table(entityTable(target));
+                const updated = [];
+                for (const id of idsToDelete) {
+                    const row = await targetTable.get(id);
+                    if (!row || row.deletedAt)
+                        continue;
+                    updated.push({
+                        ...row,
+                        deletedAt: softDeleteAt,
+                        deletedBy,
+                        ...(deleteGroupId ? { deleteGroupId } : {}),
+                        updatedAt: softDeleteAt,
+                    });
+                }
+                if (updated.length > 0) {
+                    await putChunked(targetTable, updated);
+                    undoRows.push({ entity: name, ids: updated.map((row) => row.id) });
+                    count += updated.length;
+                }
+            }
+            const nullified = [...effects.originalReferences.entries()].flatMap(([targetTable, rows]) => {
+                const tableEntity = blueprint.entities.find((item) => entityTable(item) === targetTable);
+                if (!tableEntity)
+                    return [];
+                return [...rows.entries()].map(([id, fields]) => ({
+                    entity: tableEntity.name,
+                    id,
+                    fields,
+                }));
+            });
+            return { rows: undoRows, nullified, count };
+        }
+        for (const [name, set] of effects.doomed) {
+            count += set.size;
+            const target = byName.get(name);
+            const targetTable = db.table(entityTable(target));
+            const doomedRows = await Promise.all([...set].map((id) => targetTable.get(id)));
+            if (filesEnabled) {
+                const fileIds = target.fields
+                    .filter((field) => field.kind === 'file')
+                    .flatMap((field) => doomedRows.flatMap((row) => {
+                    const value = row?.[inputProperty(field)];
+                    return Array.isArray(value) ? value : typeof value === 'string' ? [value] : [];
+                }));
+                if (fileIds.length > 0)
+                    await db.table(FEATURE_TABLES.files).bulkDelete(fileIds);
+            }
+            await targetTable.bulkDelete([...set]);
+        }
+        return count;
+    }
+    function serviceFor(entity) {
+        const table = entityTable(entity);
+        const cap = (action) => `${entity.name}:${action}`;
+        const op = (name) => `${entity.name}.${name}`;
+        const schemas = () => deriveInputSchemas(entity);
+        const ownerField = entity.fields.find((f) => f.name === entity.ownerField);
+        const ownerProperty = ownerField ? inputProperty(ownerField) : undefined;
+        const sort = entity.defaultSort ?? { field: 'createdAt', direction: 'asc' };
+        const sortField = entity.fields.find((f) => f.name === sort.field);
+        const sortProperty = sortField ? inputProperty(sortField) : sort.field;
+        const sortRows = (rows) => {
+            const dir = sort.direction === 'desc' ? -1 : 1;
+            return rows.sort((a, b) => {
+                const x = a[sortProperty];
+                const y = b[sortProperty];
+                if (x === y)
+                    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+                if (x === null || x === undefined)
+                    return 1;
+                if (y === null || y === undefined)
+                    return -1;
+                return (x < y ? -1 : 1) * dir;
+            });
+        };
+        async function restoreGroup(root, checkExpiry) {
+            const groupId = typeof root.deleteGroupId === 'string' ? root.deleteGroupId : '';
+            const expiresAt = root.deleteGroupExpiresAt;
+            if (!groupId || !Array.isArray(root.deleteGroupRows)) {
+                throw new UndoTokenError('This undo set is no longer available.');
+            }
+            if (checkExpiry && (typeof expiresAt !== 'number' || clock.nowMs() > expiresAt)) {
+                throw new UndoTokenError('The undo window has expired.');
+            }
+            const restored = [];
+            for (const item of root.deleteGroupRows) {
+                const target = byName.get(item.entity);
+                if (!target || !Array.isArray(item.ids))
+                    throw new UndoTokenError('This undo set is invalid.');
+                const targetTable = db.table(entityTable(target));
+                const rows = await Promise.all(item.ids.map((id) => targetTable.get(id)));
+                if (rows.some((row) => !row || row.deleteGroupId !== groupId || !row.deletedAt)) {
+                    throw new UndoTokenError('The rows in this undo set are no longer available.');
+                }
+                restored.push({
+                    entity: target,
+                    rows: rows.map((row) => ({
+                        ...row,
+                        deletedAt: null,
+                        deletedBy: null,
+                        deleteGroupId: null,
+                        updatedAt: clock.now().toISOString(),
+                    })),
+                });
+            }
+            // Restore the deleted targets before restoring survivor references.
+            let count = 0;
+            for (const group of restored) {
+                await putChunked(db.table(entityTable(group.entity)), group.rows);
+                count += group.rows.length;
+            }
+            const nullified = Array.isArray(root.deleteGroupNullified)
+                ? root.deleteGroupNullified
+                : [];
+            const changed = new Map();
+            for (const item of nullified) {
+                const target = byName.get(item.entity);
+                if (!target)
+                    continue;
+                const targetTable = entityTable(target);
+                const row = await db.table(targetTable).get(item.id);
+                if (!row || row.deletedAt)
+                    continue;
+                const groupReferences = row.deleteGroupReferences;
+                if (!groupReferences ||
+                    typeof groupReferences !== 'object' ||
+                    Array.isArray(groupReferences))
+                    continue;
+                const fields = groupReferences[groupId];
+                if (!fields || typeof fields !== 'object' || Array.isArray(fields))
+                    continue;
+                const next = { ...row };
+                const restoreFields = {};
+                for (const [property, original] of Object.entries(fields)) {
+                    const current = next[property];
+                    if (Array.isArray(original)) {
+                        const values = Array.isArray(current) ? [...current] : [];
+                        const storedOrder = row.deleteGroupReferenceOrder;
+                        const order = storedOrder &&
+                            typeof storedOrder === 'object' &&
+                            !Array.isArray(storedOrder) &&
+                            Array.isArray(storedOrder[property])
+                            ? storedOrder[property]
+                            : original;
+                        const field = target.fields.find((candidate) => inputProperty(candidate) === property);
+                        const eligible = [];
+                        for (const id of order) {
+                            if (typeof id !== 'string')
+                                continue;
+                            if (field?.kind === 'relation') {
+                                const targetEntity = byName.get(field.to);
+                                const targetRow = targetEntity
+                                    ? await db.table(entityTable(targetEntity)).get(id)
+                                    : undefined;
+                                if (!targetRow || targetRow.deletedAt)
+                                    continue;
+                            }
+                            eligible.push(id);
+                        }
+                        const restoredValues = [...eligible, ...values.filter((id) => !order.includes(id))];
+                        next[property] = restoredValues;
+                        restoreFields[property] = restoredValues;
+                    }
+                    else if (current === null || current === undefined) {
+                        next[property] = original;
+                        restoreFields[property] = original;
+                    }
+                }
+                await assertReferences(target, restoreFields);
+                const remaining = { ...groupReferences };
+                delete remaining[groupId];
+                next.deleteGroupReferences = Object.keys(remaining).length > 0 ? remaining : null;
+                next.deleteGroupReferenceOrder =
+                    Object.keys(remaining).length > 0 ? row.deleteGroupReferenceOrder : null;
+                if (Object.keys(remaining).length === 0)
+                    next.deleteGroupId = null;
+                next.updatedAt = clock.now().toISOString();
+                const rows = changed.get(targetTable) ?? new Map();
+                rows.set(item.id, next);
+                changed.set(targetTable, rows);
+            }
+            for (const [targetTable, rows] of changed)
+                await putChunked(db.table(targetTable), [...rows.values()]);
+            const rootAfter = await db.table(table).get(root.id);
+            if (rootAfter) {
+                const after = {
+                    ...rootAfter,
+                    deleteGroupId: null,
+                    deleteGroupRows: null,
+                    deleteGroupNullified: null,
+                    deleteGroupExpiresAt: null,
+                    updatedAt: clock.now().toISOString(),
+                };
+                await db.table(table).put(after);
+                await audit({ action: 'restore', entity, recordId: root.id, before: root, after });
+            }
+            return count;
+        }
+        /** `:own` actions fall back to the record rule; denial names the full capability. */
+        const assertOn = (action, row) => {
+            if (session.can(cap(action)) || session.can(cap(`${action}:own`), row))
+                return;
+            session.assert(cap(action), row);
+        };
+        const load = async (id) => {
+            const row = await db.table(table).get(id);
+            if (!row || row.deletedAt)
+                throw new EntityNotFoundError(entity.name, id);
+            return row;
+        };
+        const visible = (row) => !row.deletedAt;
+        const readVisibleRows = async () => {
+            session.assert(cap('read'));
+            return sortRows((await db.table(table).toArray()).filter(visible));
+        };
+        return {
+            entity,
+            table,
+            async list() {
+                return readVisibleRows();
+            },
+            async trash() {
+                session.assert(cap('read'));
+                if (!entity.features.softDelete)
+                    return [];
+                const rows = await db.table(table).where('deletedAt').above('').toArray();
+                return sortRows(rows);
+            },
+            async get(id) {
+                session.assert(cap('read'));
+                const row = await db.table(table).get(id);
+                return row && visible(row) ? row : undefined;
+            },
+            async create(input) {
+                session.assert(cap('create'));
+                const values = parseInput(schemas().create, input);
+                if (ownerProperty &&
+                    (values[ownerProperty] === null || values[ownerProperty] === undefined)) {
+                    values[ownerProperty] = actorId();
+                }
+                return environment.run(op('create'), () => db.transaction('rw', writeTables, async () => {
+                    await assertReferences(entity, values);
+                    const now = clock.now().toISOString();
+                    const row = {
+                        ...values,
+                        id: createRuntimeId(entity.name.replace(/-/g, '_')),
+                        createdAt: now,
+                        updatedAt: now,
+                    };
+                    await db.table(table).put(row);
+                    await audit({ action: 'create', entity, recordId: row.id, before: null, after: row });
+                    await notify({ on: 'create', entity, row });
+                    return row;
+                }));
+            },
+            async update(id, patch) {
+                const existing = await load(id);
+                assertOn('update', existing);
+                const values = parseInput(schemas().update, patch);
+                return environment.run(op('update'), () => db.transaction('rw', writeTables, async () => {
+                    const current = await load(id);
+                    await assertReferences(entity, values);
+                    const row = { ...current, ...values, id, updatedAt: clock.now().toISOString() };
+                    await db.table(table).put(row);
+                    await audit({
+                        action: 'update',
+                        entity,
+                        recordId: id,
+                        before: current,
+                        after: row,
+                    });
+                    await notify({ on: 'update', entity, row, previous: current });
+                    return row;
+                }));
+            },
+            async remove(id) {
+                const existing = await load(id);
+                assertOn('delete', existing);
+                if (entity.features.softDelete) {
+                    return environment.run(op('remove'), () => db.transaction('rw', writeTables, async () => {
+                        const current = await load(id);
+                        const deletedAt = clock.now().toISOString();
+                        const deleteGroupId = createRuntimeId('delete_group');
+                        const result = await deleteWithEffects(entity, [id], deletedAt, actorId(), deleteGroupId);
+                        if (typeof result === 'number')
+                            throw new Error('Soft delete did not create an undo set.');
+                        const storedRoot = await db.table(table).get(id);
+                        if (storedRoot) {
+                            await db.table(table).put({
+                                ...storedRoot,
+                                deleteGroupRows: result.rows,
+                                deleteGroupNullified: result.nullified.map(({ entity: name, id: rowId }) => ({
+                                    entity: name,
+                                    id: rowId,
+                                })),
+                                deleteGroupExpiresAt: clock.nowMs() + UNDO_WINDOW_MS,
+                            });
+                        }
+                        await audit({
+                            action: 'delete',
+                            entity,
+                            recordId: id,
+                            before: current,
+                            after: { ...current, deletedAt, deletedBy: actorId(), deleteGroupId },
+                        });
+                        const payload = { version: 2, rootId: id };
+                        return encodeUndoToken(payload);
+                    }));
+                }
+                await environment.run(op('remove'), () => db.transaction('rw', writeTables, async () => {
+                    const current = await load(id);
+                    await deleteWithEffects(entity, [id]);
+                    await audit({
+                        action: 'delete',
+                        entity,
+                        recordId: id,
+                        before: current,
+                        after: null,
+                    });
+                }));
+                return undefined;
+            },
+            async restore(undoToken) {
+                const payload = decodeUndoToken(undoToken);
+                const root = await db.table(table).get(payload.rootId);
+                if (!root?.deletedAt || typeof root.deleteGroupId !== 'string')
+                    throw new EntityNotFoundError(entity.name, payload.rootId);
+                assertOn('delete', root);
+                return environment.run(op('restore'), () => db.transaction('rw', writeTables, async () => {
+                    const current = await db.table(table).get(payload.rootId);
+                    if (!current?.deletedAt)
+                        throw new EntityNotFoundError(entity.name, payload.rootId);
+                    assertOn('delete', current);
+                    return restoreGroup(current, true);
+                }));
+            },
+            async restoreTrashed(id) {
+                const recordId = parseInput(z.string().min(1), id);
+                if (!entity.features.softDelete)
+                    throw new EntityNotFoundError(entity.name, recordId);
+                const existing = await db.table(table).get(recordId);
+                if (!existing?.deletedAt)
+                    throw new EntityNotFoundError(entity.name, recordId);
+                assertOn('delete', existing);
+                return environment.run(op('restore'), () => db.transaction('rw', writeTables, async () => {
+                    const root = await db.table(table).get(recordId);
+                    if (!root?.deletedAt)
+                        throw new EntityNotFoundError(entity.name, recordId);
+                    assertOn('delete', root);
+                    return restoreGroup(root, false);
+                }));
+            },
+            async purge(id) {
+                const existing = await db.table(table).get(id);
+                if (!existing?.deletedAt)
+                    throw new EntityNotFoundError(entity.name, id);
+                session.assert(cap('delete'), existing);
+                return environment.run(op('purge'), () => db.transaction('rw', writeTables, async () => {
+                    const current = await db.table(table).get(id);
+                    if (!current?.deletedAt)
+                        throw new EntityNotFoundError(entity.name, id);
+                    const deleted = await deleteWithEffects(entity, [id]);
+                    if (typeof deleted !== 'number')
+                        throw new Error('Purge did not hard delete rows.');
+                    await audit({
+                        action: 'purge',
+                        entity,
+                        recordId: id,
+                        before: current,
+                        after: null,
+                    });
+                    return deleted;
+                }));
+            },
+            async shuffleAvatar(id, field) {
+                const existing = await load(id);
+                assertOn('update', existing);
+                const fields = avatarFields(entity);
+                const avatarField = field === undefined ? fields[0] : fields.find((candidate) => candidate.name === field);
+                if (!avatarField) {
+                    throw new ValidationError({
+                        field: fields.length === 0
+                            ? `${entity.label ?? entity.name} has no avatar field`
+                            : `Pick one of: ${fields.map((f) => f.name).join(', ')}`,
+                    });
+                }
+                const property = inputProperty(avatarField);
+                const key = `${entity.name}:${id}:${avatarField.name}`;
+                const values = parseInput(schemas().update, {
+                    [property]: nextAvatar(existing[property], key),
+                });
+                return environment.run(op('shuffleAvatar'), () => db.transaction('rw', writeTables, async () => {
+                    const current = await load(id);
+                    const row = { ...current, ...values, id, updatedAt: clock.now().toISOString() };
+                    await db.table(table).put(row);
+                    await audit({ action: 'update', entity, recordId: id, before: current, after: row });
+                    await notify({ on: 'update', entity, row, previous: current });
+                    return row;
+                }));
+            },
+            async bulkUpdate(ids, patch) {
+                const unique = [...new Set(ids)];
+                const existing = await Promise.all(unique.map(load));
+                for (const row of existing)
+                    assertOn('update', row);
+                const values = parseInput(schemas().update, patch);
+                return environment.run(op('bulkUpdate'), () => db.transaction('rw', writeTables, async () => {
+                    await assertReferences(entity, values);
+                    const now = clock.now().toISOString();
+                    const current = await Promise.all(unique.map(load));
+                    const rows = current.map((row) => ({ ...row, ...values, id: row.id, updatedAt: now }));
+                    await putChunked(db.table(table), rows);
+                    for (let i = 0; i < rows.length; i += 1) {
+                        const previous = current[i];
+                        const next = rows[i];
+                        await audit({
+                            action: 'update',
+                            entity,
+                            recordId: next.id,
+                            before: previous,
+                            after: next,
+                        });
+                        await notify({ on: 'update', entity, row: next, previous });
+                    }
+                    return rows;
+                }));
+            },
+            async bulkRemove(ids) {
+                const unique = [...new Set(ids)];
+                const existing = await Promise.all(unique.map(load));
+                for (const row of existing)
+                    assertOn('delete', row);
+                return environment.run(op('bulkRemove'), () => db.transaction('rw', writeTables, async () => {
+                    const current = await Promise.all(unique.map(load));
+                    const result = await deleteWithEffects(entity, unique);
+                    for (const row of current) {
+                        await audit({
+                            action: 'delete',
+                            entity,
+                            recordId: row.id,
+                            before: row,
+                            after: null,
+                        });
+                    }
+                    return typeof result === 'number' ? result : result.count;
+                }));
+            },
+            async exportCsv(filter, options) {
+                session.assert(cap('export'));
+                let rows = await readVisibleRows();
+                if (filter?.ids && filter.ids.length > 0) {
+                    const want = new Set(filter.ids);
+                    rows = rows.filter((row) => want.has(row.id));
+                }
+                if (filter?.where)
+                    rows = rows.filter(filter.where);
+                const records = rows.map((row) => {
+                    const input = {};
+                    for (const field of entity.fields) {
+                        const property = inputProperty(field);
+                        if (property in row)
+                            input[property] = row[property];
+                    }
+                    return input;
+                });
+                return serializeEntityCsv(entity, records, options);
+            },
+            async importCsv(text, options = {}) {
+                session.assert(cap('import'));
+                const mode = options.mode ?? 'preview';
+                const skipInvalid = options.skipInvalid === true;
+                const preview = await previewImportCsv(entity, text, options);
+                const base = {
+                    ...preview,
+                    mode,
+                    created: [],
+                    auditIds: [],
+                };
+                if (mode === 'preview')
+                    return base;
+                if (preview.errors.length > 0 && !skipInvalid) {
+                    throw new ImportCsvError(base);
+                }
+                if (preview.valid.length === 0) {
+                    return base;
+                }
+                return environment.run(op('import'), () => db.transaction('rw', writeTables, async () => {
+                    const actor = actorId();
+                    const now = clock.now().toISOString();
+                    const created = [];
+                    for (const values of preview.valid) {
+                        await assertReferences(entity, values);
+                        const row = {
+                            ...values,
+                            id: createRuntimeId(entity.name.replace(/-/g, '_')),
+                            createdAt: now,
+                            updatedAt: now,
+                        };
+                        if (ownerProperty &&
+                            (row[ownerProperty] === null || row[ownerProperty] === undefined)) {
+                            row[ownerProperty] = actor;
+                        }
+                        created.push(row);
+                    }
+                    await putChunked(db.table(table), created);
+                    const auditIds = await writeAuditBatch(entity, created, 'import');
+                    for (const row of created) {
+                        await notify({ on: 'create', entity, row });
+                    }
+                    return {
+                        ...base,
+                        mode: 'commit',
+                        created,
+                        auditIds,
+                    };
+                }));
+            },
+        };
+    }
+    return Object.fromEntries(blueprint.entities.map((entity) => [entity.name, serviceFor(entity)]));
+}