@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/dist/db/tenant-db.js

@@ -0,0 +1,501 @@
+import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { asEntityTableMeta, asRawClient, countWhere as bunCountWhere, deleteMany as bunDeleteMany, fetchOne as bunFetchOne, insertOne as bunInsertOne, selectMany as bunSelectMany, updateMany as bunUpdateMany, runInNewTransaction, } from "../db/query.js";
+import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
+import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
+import { fallbackEscapeHatchReporter } from "../observability/escape-hatch-report.js";
+import { emitDbQuery, registerStandardMetrics, } from "../observability/index.js";
+import { bindTenantDbRunner, tenantDbRunner } from "./tenant-db-runner.js";
+export { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
+const declaredUnsafeRawRunners = new WeakMap();
+// The CRUD executor writes through tenantDbRunner, not insertOne, so it asks the
+// TenantDb it was handed for its gate. Bound inside createTenantDb so rebound instances
+// (withUnsafeRawGrant, acknowledgeConventionCrossTenant) carry it too.
+const personalDataGates = new WeakMap();
+// Lets createTenantDb(ctx.db.unsafeRaw(reason), ...) inherit the gate. Keyed by a
+// per-grant proxy, never the shared pool/tx: tagging that would gate every sibling TenantDb.
+const runnerPersonalDataGates = new WeakMap();
+function gatedRunner(runner, gate) {
+    const proxy = new Proxy(runner, {
+        // Tagged-template calls need the real driver object as `this`.
+        apply(target, _thisArg, args) {
+            return Reflect.apply(target, target, args);
+        },
+        get(target, prop, _receiver) {
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== "function")
+                return value;
+            if (prop === "begin" || prop === "savepoint") {
+                // createTenantDb(tx, ...) inside the callback must inherit the gate too.
+                return (...args) => {
+                    const callback = args[args.length - 1];
+                    if (typeof callback !== "function") {
+                        return Reflect.apply(value, target, args);
+                    }
+                    const gatedArgs = [
+                        ...args.slice(0, -1),
+                        (tx) => callback(gatedRunner(tx, gate)),
+                    ];
+                    return Reflect.apply(value, target, gatedArgs);
+                };
+            }
+            return value.bind(target);
+        },
+        // @cast-boundary proxy-erasure — Proxy<object> re-tags as the wrapped DbRunner shape.
+    });
+    runnerPersonalDataGates.set(proxy, gate);
+    return proxy;
+}
+// The executor passes its entity so the check does not depend on the table-name lookup.
+export function assertPersonalDataWrite(db, tableName, keys, entity) {
+    personalDataGates.get(db)?.(tableName, keys, entity);
+}
+// Framework-private (not re-exported from db/index.ts): same grant check + audit as unsafeRaw, for engine forwarding.
+export function unsafeRawForDeclaredStep(holder, reason) {
+    if (reason.trim().length === 0) {
+        throw new Error("unsafeRawForDeclaredStep requires a non-empty reason");
+    }
+    const runner = declaredUnsafeRawRunners.get(holder);
+    if (!runner) {
+        throw new InternalError({
+            message: "unsafeRawForDeclaredStep received a holder not built by createTenantDb, " +
+                "createUncheckedSystemDb, or createSystemDbView — no declared unsafeRaw runner bound.",
+        });
+    }
+    return runner(reason);
+}
+const systemDbRebinders = new WeakMap();
+// Rebinds a hook's own escapeHatch onto ctx.systemDb, mirroring withUnsafeRawGrant: always
+// rebuilt from the original db/dbOutsideTransaction/report, never stacked onto a prior rebind.
+// Inputs not built by createUncheckedSystemDb pass through unchanged.
+export function withSystemDbUnsafeRawGrant(systemDb, grant, deniedCallerLabel) {
+    const rebind = systemDbRebinders.get(systemDb);
+    return rebind ? rebind(grant, deniedCallerLabel) : systemDb;
+}
+// Ungated when `gate` is absent (the handler's own ctx.systemDb — systemScope() is
+// itself the grant there). Gated by a hook's own escapeHatch when `gate.kind` is
+// "hook-grant": unsafeRaw then denies without `hasGrant(gate.grant)`, same error shape
+// as ctx.db.unsafeRaw's denial in createTenantDb below. Gated by the source TenantDb's
+// own escapeHatch when `gate.kind` is "source-tenant-db" (createSystemDbView): unsafeRaw
+// defers entirely to db's own declared runner (reason/memberReadOnly/grant check and
+// report) — the view's own `report` is never called for unsafe-raw in that mode, and a
+// source not built by createTenantDb fails closed.
+function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
+    const allowedTenantIds = [db.tenantId, SYSTEM_TENANT_ID];
+    // Fails closed instead of falling back to the in-tx `db` — a silent
+    // fallback would defeat the point of a durability write that must survive
+    // a rollback of the handler's own transaction. InternalError (not
+    // AccessDeniedError) because this is a dispatch wiring fault, not a
+    // tenant-access denial — mirrors the "no database connection configured"
+    // case in dispatch-shared.ts's appendDomainEvent.
+    function requireOutsideTransactionDb() {
+        if (!dbOutsideTransaction) {
+            throw new InternalError({
+                message: "systemScope() outsideTransaction check failed: no outside-transaction database " +
+                    "source is configured for this dispatch.",
+            });
+        }
+        return dbOutsideTransaction;
+    }
+    function grantedUnsafeRawRunner(reason) {
+        if (gate?.kind === "source-tenant-db") {
+            return unsafeRawForDeclaredStep(db, reason);
+        }
+        if (reason.trim().length === 0) {
+            throw new Error("unsafeRaw requires a non-empty reason");
+        }
+        if (gate && !hasGrant(gate.grant)) {
+            throw new AccessDeniedError({
+                message: 'ctx.systemDb.unsafeRaw(reason): rejected — declare `escapeHatch: { reason: "..." }` on ' +
+                    `${gate.deniedCallerLabel} to allow unsafeRaw.`,
+            });
+        }
+        report("unsafe-raw", reason);
+        const runner = tenantDbRunner(db);
+        const personalDataGate = personalDataGates.get(db);
+        return personalDataGate ? gatedRunner(runner, personalDataGate) : runner;
+    }
+    const uncheckedSystemDb = {
+        [SYSTEM_SCOPE_CHECK_BRAND]: true,
+        assertTenantMatch(tenantId) {
+            if (tenantId !== db.tenantId) {
+                throw new AccessDeniedError({
+                    message: `systemScope() tenant self-check failed: expected "${db.tenantId}", got "${tenantId}"`,
+                });
+            }
+            return db;
+        },
+        // Fails closed on any mismatch rather than silently dropping rows.
+        // Reference rows (tenantId === SYSTEM_TENANT_ID) are allowed, mirroring
+        // "tenant"-mode readWhere's own [tenantId, SYSTEM_TENANT_ID] allowlist.
+        assertRowsTenant(rows, tenantField) {
+            const hasOffender = rows.some((row) => !allowedTenantIds.includes(row[tenantField]));
+            if (hasOffender) {
+                throw new AccessDeniedError({
+                    message: `systemScope() row tenant self-check failed on field "${String(tenantField)}"`,
+                });
+            }
+            return rows;
+        },
+        acknowledgeCrossTenant(reason) {
+            if (reason.trim().length === 0) {
+                throw new Error("acknowledgeCrossTenant requires a non-empty reason");
+            }
+            report("acknowledge-cross-tenant", reason);
+            return db;
+        },
+        unsafeRaw: grantedUnsafeRawRunner,
+        outsideTransaction: {
+            assertTenantMatch(tenantId) {
+                if (tenantId !== db.tenantId) {
+                    throw new AccessDeniedError({
+                        message: `systemScope() outsideTransaction tenant self-check failed: expected "${db.tenantId}", got "${tenantId}"`,
+                    });
+                }
+                return requireOutsideTransactionDb();
+            },
+            acknowledgeCrossTenant(reason) {
+                if (reason.trim().length === 0) {
+                    throw new Error("acknowledgeCrossTenant requires a non-empty reason");
+                }
+                const result = requireOutsideTransactionDb();
+                report("acknowledge-cross-tenant", reason);
+                return result;
+            },
+        },
+    };
+    declaredUnsafeRawRunners.set(uncheckedSystemDb, grantedUnsafeRawRunner);
+    if (gate?.kind !== "source-tenant-db") {
+        systemDbRebinders.set(uncheckedSystemDb, (grant, deniedCallerLabel) => buildUncheckedSystemDb(withUnsafeRawGrant(db, grant), dbOutsideTransaction && withUnsafeRawGrant(dbOutsideTransaction, grant), report, { kind: "hook-grant", grant, deniedCallerLabel }));
+    }
+    return uncheckedSystemDb;
+}
+// Framework-private (not re-exported from db/index.ts): buildHandlerContext
+// (pipeline/dispatch-shared.ts) always builds "system" mode from the caller's
+// own tenantId, never a foreign one.
+//
+// dbOutsideTransaction is optional so every existing single-arg call site
+// (jobs/job-runner.ts, tests) keeps compiling — those callers have no
+// outside-tx source to hand in and never needed one. Only
+// buildHandlerContext passes it, which is also the only place `.outsideTransaction`
+// is reachable through `ctx.systemDb`.
+//
+// Ungated here (the handler's own systemScope() is the grant); a hook's own
+// escapeHatch is layered on afterwards via withSystemDbUnsafeRawGrant. Public
+// callers use createSystemDbView instead, whose unsafeRaw follows the source
+// TenantDb's own escapeHatch gate.
+export function createUncheckedSystemDb(db, dbOutsideTransaction, report = fallbackEscapeHatchReporter(db.tenantId)) {
+    return buildUncheckedSystemDb(db, dbOutsideTransaction, report);
+}
+// Public: must never grant more raw access than the source TenantDb — unlike
+// createUncheckedSystemDb (framework-private; r.systemScope()/a job IS the
+// declaration), this view's unsafeRaw defers entirely to db's own escapeHatch gate.
+export function createSystemDbView(db, dbOutsideTransaction, report = fallbackEscapeHatchReporter(db.tenantId)) {
+    return buildUncheckedSystemDb(db, dbOutsideTransaction, report, { kind: "source-tenant-db" });
+}
+// @cast-boundary tenant-db-row
+export function castTenantRows(rows) {
+    return rows;
+}
+export function tableNameOf(table) {
+    const sym = table[KUMIKO_NAME_SYMBOL];
+    if (typeof sym === "string")
+        return sym;
+    return asEntityTableMeta(table)?.tableName ?? "<unknown>";
+}
+// A grant is only real when its reason is non-empty — `{ reason: "" }` must not silently unlock it.
+function hasGrant(decl) {
+    return decl !== undefined && decl.reason.trim().length > 0;
+}
+function isForeignTenantId(tenantIdValue) {
+    return tenantIdValue !== undefined && tenantIdValue !== SYSTEM_TENANT_ID;
+}
+// Checks the canonical EntityTableMeta (branded EntityTable's KUMIKO_META_SYMBOL
+// or a plain deriveEntityTableMeta/defineUnmanagedTable result), not a direct
+// `table.tenantId` property read — the latter only exists on branded EntityTables
+// and silently returned false (no tenant filter!) for plain EntityTableMeta
+// tables like unmanaged direct-write stores, e.g. userSessionTable.
+export function hasTenantColumn(table) {
+    const meta = asEntityTableMeta(table);
+    if (meta)
+        return meta.columns.some((c) => c.name === "tenant_id");
+    return table["tenantId"] !== undefined;
+}
+const unsafeRawRebinders = new WeakMap();
+// Rebinds tenantDb's unsafeRaw grant (e.g. a hook's own escapeHatch); inputs not built by
+// createTenantDb pass through unchanged, without touching any property (ctx.db may be a throwing Proxy).
+export function withUnsafeRawGrant(tenantDb, grant) {
+    const rebind = unsafeRawRebinders.get(tenantDb);
+    return rebind ? rebind(grant) : tenantDb;
+}
+const crossTenantRebinders = new WeakMap();
+// Framework-private (not re-exported from db/index.ts): lifting the tenant filter needs a registered declaration.
+export function acknowledgeConventionCrossTenant(tenantDb, reason) {
+    if (reason.trim().length === 0) {
+        throw new Error("acknowledgeConventionCrossTenant requires a non-empty reason");
+    }
+    const rebind = crossTenantRebinders.get(tenantDb);
+    if (!rebind) {
+        throw new InternalError({
+            message: "acknowledgeConventionCrossTenant received a TenantDb not built by createTenantDb — " +
+                "no cross-tenant rebinder bound.",
+        });
+    }
+    return rebind(reason);
+}
+const ownTransactionRebinders = new WeakMap();
+export async function runInOwnTransaction(tenantDb, fn) {
+    const rebind = ownTransactionRebinders.get(tenantDb);
+    if (!rebind) {
+        throw new InternalError({
+            message: "runInOwnTransaction received a TenantDb not built by createTenantDb — " +
+                "no transaction rebinder bound.",
+        });
+    }
+    return rebind(fn);
+}
+export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, signal, grants) {
+    if (meter)
+        registerStandardMetrics(meter);
+    const report = grants?.report ?? fallbackEscapeHatchReporter(tenantId);
+    const personalDataGate = grants?.personalDataGate ?? runnerPersonalDataGates.get(db);
+    function withDbSpan(operation, table, runner) {
+        signal?.throwIfAborted();
+        if (!tracer && !meter)
+            return runner();
+        const tableName = tableNameOf(table);
+        const start = performance.now();
+        const emitMetric = () => {
+            if (meter) {
+                emitDbQuery(meter, { operation, table: tableName }, (performance.now() - start) / 1000);
+            }
+        };
+        if (!tracer) {
+            return (async () => {
+                try {
+                    return await runner();
+                }
+                finally {
+                    emitMetric();
+                }
+            })();
+        }
+        return tracer.withSpan("db.query", {
+            kind: "client",
+            attributes: {
+                "db.system": "postgresql",
+                "db.operation": operation,
+                "db.table": tableName,
+            },
+        }, async (span) => {
+            try {
+                const result = await runner();
+                if (Array.isArray(result)) {
+                    span.setAttribute("db.row_count", result.length);
+                }
+                return result;
+            }
+            finally {
+                emitMetric();
+            }
+        });
+    }
+    // Reads see own-tenant rows + reference data (tenantId === SYSTEM_TENANT_ID).
+    // Writes never touch reference rows — those are system-mode only.
+    // A caller-supplied `where.tenantId` may only NARROW the enforced scope
+    // (e.g. exclude SYSTEM reference rows at the DB instead of post-filtering
+    // after a limit). Values outside the scope are dropped; if nothing valid
+    // remains, the full enforced scope applies — widening is never possible.
+    function readWhere(table, where) {
+        if (!hasTenantColumn(table) || mode === "system")
+            return where;
+        const allowed = [tenantId, SYSTEM_TENANT_ID];
+        const requested = where?.["tenantId"];
+        if (requested !== undefined) {
+            const requestedList = Array.isArray(requested) ? requested : [requested];
+            const narrowed = requestedList.filter((t) => typeof t === "string" && allowed.includes(t));
+            return { ...where, tenantId: narrowed.length > 0 ? narrowed : allowed };
+        }
+        const tenantFilter = { tenantId: allowed };
+        return where ? { ...where, ...tenantFilter } : tenantFilter;
+    }
+    function writeWhere(table, where) {
+        if (!hasTenantColumn(table) || mode === "system")
+            return where;
+        return { ...where, tenantId };
+    }
+    function insertValues(table, data) {
+        if (!hasTenantColumn(table))
+            return data;
+        if (mode === "system")
+            return { tenantId, ...data };
+        return { ...data, tenantId };
+    }
+    function missingEscapeHatch(table) {
+        if (hasGrant(grants?.globalWrites))
+            return undefined;
+        return new AccessDeniedError({
+            message: `db.global(${tableNameOf(table)}): write rejected — declare ` +
+                `\`escapeHatch: { reason: "..." }\` on the write handler to allow ` +
+                "writes through db.global().",
+        });
+    }
+    function globalWriteReason() {
+        return grants?.globalWrites?.reason ?? "";
+    }
+    function personalDataDenied(table, keys) {
+        if (!personalDataGate)
+            return undefined;
+        try {
+            personalDataGate(tableNameOf(table), keys);
+            return undefined;
+        }
+        catch (e) {
+            if (e instanceof AccessDeniedError)
+                return e;
+            throw e;
+        }
+    }
+    function foreignTenantOnGlobalWrite(table, tenantIdValue, message = `db.global(${tableNameOf(table)}): tenantId "${String(tenantIdValue)}" is not SYSTEM_TENANT_ID — a "global" table's rows must carry the system tenant, not an arbitrary tenant's id.`) {
+        if (!isForeignTenantId(tenantIdValue))
+            return undefined;
+        return new AccessDeniedError({ message });
+    }
+    function globalTable(table) {
+        const meta = asEntityTableMeta(table);
+        if (meta?.tenancy !== "global") {
+            throw new AccessDeniedError({
+                message: `db.global(${tableNameOf(table)}): table is not declared \`tenancy: "global"\`.`,
+            });
+        }
+        return {
+            selectMany(where, options) {
+                return withDbSpan("select", table, async () => bunSelectMany(db, table, where, options));
+            },
+            fetchOne(where) {
+                return withDbSpan("select", table, async () => bunFetchOne(db, table, where));
+            },
+            insertOne(values) {
+                const denied = missingEscapeHatch(table) ??
+                    foreignTenantOnGlobalWrite(table, values["tenantId"]) ??
+                    personalDataDenied(table, Object.keys(values));
+                if (denied)
+                    return Promise.reject(denied);
+                report("global-write", globalWriteReason());
+                return withDbSpan("insert", table, async () => bunInsertOne(db, table, values));
+            },
+            updateMany(set, where) {
+                const denied = missingEscapeHatch(table) ??
+                    foreignTenantOnGlobalWrite(table, set["tenantId"]) ??
+                    personalDataDenied(table, Object.keys(set));
+                if (denied)
+                    return Promise.reject(denied);
+                if (!where || Object.keys(where).length === 0) {
+                    return Promise.reject(new Error("db.global().updateMany without where would mass-update every tenant's rows. Pass at least one where condition."));
+                }
+                report("global-write", globalWriteReason());
+                return withDbSpan("update", table, async () => bunUpdateMany(db, table, set, where));
+            },
+            deleteMany(where) {
+                const denied = missingEscapeHatch(table);
+                if (denied)
+                    return Promise.reject(denied);
+                if (!where || Object.keys(where).length === 0) {
+                    return Promise.reject(new Error("db.global().deleteMany without where would mass-delete every tenant's rows. Pass at least one where condition."));
+                }
+                report("global-write", globalWriteReason());
+                return withDbSpan("delete", table, async () => bunDeleteMany(db, table, where));
+            },
+            // @cast-boundary type-brand — GlobalWrites is only present in the type when TTable is not ExecutorOnly; the object above always carries the methods.
+        };
+    }
+    function grantedUnsafeRawRunner(reason) {
+        if (reason.trim().length === 0) {
+            throw new Error("unsafeRaw requires a non-empty reason");
+        }
+        // Ahead of the grant check: a declared escapeHatch must not buy a raw runner here either.
+        if (grants?.memberReadOnly) {
+            throw memberResolutionReadOnlyDenied();
+        }
+        if (!hasGrant(grants?.unsafeRaw)) {
+            throw new AccessDeniedError({
+                message: 'ctx.db.unsafeRaw(reason): rejected — declare `escapeHatch: { reason: "..." }` on ' +
+                    "the handler or hook to allow unsafeRaw.",
+            });
+        }
+        report("unsafe-raw", reason);
+        return personalDataGate ? gatedRunner(db, personalDataGate) : db;
+    }
+    const tenantDb = {
+        tenantId,
+        mode,
+        global: globalTable,
+        unsafeRaw: grantedUnsafeRawRunner,
+        selectMany(table, where, options) {
+            const filter = readWhere(table, where);
+            return withDbSpan("select", table, async () => bunSelectMany(db, table, filter, options));
+        },
+        fetchOne(table, where) {
+            const filter = readWhere(table, where) ?? {};
+            return withDbSpan("select", table, async () => bunFetchOne(db, table, filter));
+        },
+        count(table, where) {
+            const filter = readWhere(table, where);
+            return withDbSpan("select", table, async () => bunCountWhere(db, table, filter));
+        },
+        insertOne(table, values) {
+            if (mode === "tenant" &&
+                hasTenantColumn(table) &&
+                asEntityTableMeta(table)?.tenancy === "global") {
+                const denied = foreignTenantOnGlobalWrite(table, tenantId, `insertOne(${tableNameOf(table)}): "global" table rows must carry SYSTEM_TENANT_ID; ` +
+                    "use db.global(table) with escapeHatch instead.");
+                if (denied)
+                    return Promise.reject(denied);
+            }
+            const personalDenied = personalDataDenied(table, Object.keys(values));
+            if (personalDenied)
+                return Promise.reject(personalDenied);
+            const data = insertValues(table, values);
+            return withDbSpan("insert", table, async () => bunInsertOne(db, table, data));
+        },
+        updateMany(table, set, where) {
+            if (!where || Object.keys(where).length === 0) {
+                return Promise.reject(new Error("TenantDb.updateMany without where would mass-update all tenant rows. Pass at least one where condition."));
+            }
+            const personalDenied = personalDataDenied(table, Object.keys(set));
+            if (personalDenied)
+                return Promise.reject(personalDenied);
+            const filter = writeWhere(table, where);
+            return withDbSpan("update", table, async () => bunUpdateMany(db, table, set, filter));
+        },
+        deleteMany(table, where) {
+            if (!where || Object.keys(where).length === 0) {
+                return Promise.reject(new Error("TenantDb.deleteMany without where would mass-delete all tenant rows. Pass at least one where condition."));
+            }
+            const filter = writeWhere(table, where);
+            return withDbSpan("delete", table, async () => bunDeleteMany(db, table, filter));
+        },
+    };
+    declaredUnsafeRawRunners.set(tenantDb, grantedUnsafeRawRunner);
+    unsafeRawRebinders.set(tenantDb, (grant) => createTenantDb(db, tenantId, mode, tracer, meter, signal, { ...grants, unsafeRaw: grant }));
+    crossTenantRebinders.set(tenantDb, (reason) => {
+        report("acknowledge-cross-tenant", reason);
+        return createTenantDb(db, tenantId, "system", tracer, meter, signal, grants);
+    });
+    ownTransactionRebinders.set(tenantDb, async (fn) => {
+        if (grants?.memberReadOnly) {
+            throw new InternalError({
+                message: "runInOwnTransaction: memberReadOnly TenantDb — a fresh transaction would escape " +
+                    "the enforced read-only scope.",
+            });
+        }
+        // Carries a runner-bound gate (grants.personalDataGate unset, resolved via the fallback above) forward explicitly, since the fresh tx-handle isn't itself registered in runnerPersonalDataGates.
+        const txGrants = personalDataGate ? { ...grants, personalDataGate } : grants;
+        return runInNewTransaction(db, (tx) => fn(createTenantDb(tx, tenantId, mode, tracer, meter, signal, txGrants)));
+    });
+    bindTenantDbRunner(tenantDb, db);
+    if (personalDataGate)
+        personalDataGates.set(tenantDb, personalDataGate);
+    return tenantDb;
+}
+export { asRawClient };

package/dist/derivatives/delete-stored-file.d.ts

@@ -0,0 +1,6 @@
+export type StoredFileStore = {
+    list(prefix: string): Promise<readonly string[]>;
+    delete(key: string): Promise<void>;
+};
+export declare function listDerivativeKeys(originalKey: string, store: Pick<StoredFileStore, "list">, errorContext: string): Promise<readonly string[]>;
+export declare function deleteStoredFileAndDerivatives(originalKey: string, store: StoredFileStore, errorContext: string): Promise<readonly string[]>;

package/dist/derivatives/delete-stored-file.js

@@ -0,0 +1,70 @@
+// Shared binary-deletion helper: deletes an original storage key plus every
+// derivative rendered from it (thumbnails/resized variants — see
+// derivatives-context.ts). Derivatives are never tracked anywhere but the
+// storage layer: they're rendered under a deterministic key (deriveKey +
+// variantSuffix) computed from the original's key, on demand, and nothing
+// writes that key back onto a FileRef row. Listing the original's key-prefix
+// and keeping only candidates whose suffix matches the derivative grammar,
+// anchored to the original's own basename AND extension, means a
+// same-directory sibling (a different file, possibly another tenant's) shares
+// the list prefix but fails the extension/suffix check and is never touched.
+//
+// Used by both the user-data-rights-defaults forget hook and the
+// data-retention hardDelete cleanup — moved here so neither copies the logic.
+import { assertSafeStorageKey } from "../files/types.js";
+import { derivativeListPrefix, isDerivativeKeyOf } from "./variant-key.js";
+// Wrap rather than let a raw provider error (e.g. S3 AccessDenied) surface
+// unexplained — list() is a requirement on top of delete(); a bucket policy
+// granting only s3:DeleteObject would otherwise fail every run instead of
+// just leaving derivatives behind. Name the likely cause so an operator
+// doesn't have to guess. `errorContext` names the caller for the message
+// prefix (e.g. "user-data-rights-defaults:fileRef", "data-retention:hardDelete").
+export async function listDerivativeKeys(originalKey, store, errorContext) {
+    let candidates;
+    try {
+        candidates = await store.list(derivativeListPrefix(originalKey));
+    }
+    catch (err) {
+        throw new Error(`[${errorContext}] provider.list() failed while looking up derivatives of key=${originalKey} — forget/erasure requires list permission on the storage bucket (e.g. s3:ListBucket), not just delete. Original error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const derivativeKeys = [];
+    for (const candidate of candidates) {
+        if (!isDerivativeKeyOf(originalKey, candidate))
+            continue;
+        try {
+            assertSafeStorageKey(candidate);
+        }
+        catch {
+            // ponytail: a listing hit that fails the storage-key grammar can't be
+            // a real derivative (every derivative is written via a validated
+            // write()) — skip rather than pass a malformed key to delete().
+            continue;
+        }
+        derivativeKeys.push(candidate);
+    }
+    return derivativeKeys;
+}
+// Deletes the original key + every derivative. Returns the keys whose delete
+// threw — callers fail closed on a non-empty list (delete is idempotent, so a
+// retry on the next run converges). assertSafeStorageKey guards the original
+// AND every derivative right before the delete call, not just at listing time.
+export async function deleteStoredFileAndDerivatives(originalKey, store, errorContext) {
+    assertSafeStorageKey(originalKey);
+    const keysToDelete = [
+        originalKey,
+        ...(await listDerivativeKeys(originalKey, store, errorContext)),
+    ];
+    const failedKeys = [];
+    for (const key of keysToDelete) {
+        try {
+            assertSafeStorageKey(key);
+            await store.delete(key);
+        }
+        catch (err) {
+            failedKeys.push(key);
+            // biome-ignore lint/suspicious/noConsole: operator-visibility for binary-cleanup-failure
+            console.warn(`[${errorContext}] storage delete failed key=${key} err=${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return failedKeys;
+}

package/dist/derivatives/derivatives-context.d.ts

@@ -0,0 +1,21 @@
+import type { DerivativeRendererPlugin, DerivativesContext } from "@cosmicdrift/kumiko-types/derivatives-types";
+import { type AnyDb } from "../bun-db/query.js";
+import type { Registry, TenantId } from "../engine/types/index.js";
+import type { FileContext } from "../files/file-handle.js";
+export type DerivativesContextDeps = {
+    readonly files: FileContext;
+    readonly registry: Registry;
+    readonly db: AnyDb;
+    readonly tenantId: TenantId;
+};
+export declare function resolveRenderer(registry: Registry, mimeType: string): DerivativeRendererPlugin | undefined;
+export type OverlayResolverArgs = {
+    readonly entityId: string;
+    readonly tenantId: TenantId;
+    readonly fieldName: string;
+    readonly dataToken: string;
+};
+export type OverlayResolverPlugin = {
+    readonly resolve: (args: OverlayResolverArgs) => string | Promise<string>;
+};
+export declare function createDerivativesContext(deps: DerivativesContextDeps): DerivativesContext;