@cosmicdrift/kumiko-bundled-features 0.334.0 → 0.335.0

package/dist/files-tenant-data/index.js

@@ -13,6 +13,7 @@
 import { defineFeature, EXT_STORAGE_PROVIDER, EXT_TENANT_DATA, } from "@cosmicdrift/kumiko-framework/engine";
 import { sweepOrphanedDerivativesJob, sweepOrphanedDerivativesPayloadSchema, } from "./handlers/sweep-orphaned-derivatives.job.js";
 import { fileRefStorageDestroyHook, fileRefTenantDestroyHook } from "./hooks.js";
+const SWEEP_ORPHANED_DERIVATIVES_ESCAPE_HATCH_REASON = "iterates every tenant and checks fileRef owners per tenant";
 export function createFilesTenantDataFeature() {
     return defineFeature("files-tenant-data", (r) => {
         r.describe("GDPR coverage for the `files` feature's `fileRef` entity: tenant-destroy row purge (EXT_TENANT_DATA) and full storage-prefix binary wipe (EXT_STORAGE_PROVIDER), plus a manual backfill/GC job that sweeps derivatives orphaned by a forget/tenant-destroy that ran before #2461 wired binary cleanup into those flows. Requires `tenant-lifecycle`, optionalRequires `files`.");
@@ -31,9 +32,9 @@ export function createFilesTenantDataFeature() {
             concurrency: "skip",
             schema: sweepOrphanedDerivativesPayloadSchema,
             escapeHatch: {
-                reason: "iterates every tenant and checks fileRef owners per tenant",
+                reason: SWEEP_ORPHANED_DERIVATIVES_ESCAPE_HATCH_REASON,
             },
-            handler: (payload, ctx) => sweepOrphanedDerivativesJob(payload, ctx, ctx.db.unsafeRaw("iterates every tenant and checks fileRef owners per tenant")),
+            handler: (payload, ctx) => sweepOrphanedDerivativesJob(payload, ctx, ctx.db.unsafeRaw(SWEEP_ORPHANED_DERIVATIVES_ESCAPE_HATCH_REASON)),
         });
     });
 }

package/dist/folders/handlers/clear-folder.write.js

@@ -1,5 +1,4 @@
-import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import { joinRowParentIsVisible } from "../../shared/index.js";
+import { denyUnlessJoinRowParentVisible } from "../../shared/index.js";
 import { folderAssignmentAggregateId } from "../aggregate-id.js";
 import { DEFAULT_FOLDER_ACCESS } from "../constants.js";
 import { folderAssignmentExecutor } from "../executor.js";
@@ -19,15 +18,9 @@ export function createClearFolderHandler(access = DEFAULT_FOLDER_ACCESS) {
         description: "Unfiles a host entity so it sits in no folder at all, reporting success when it was already unfiled; use it to take an entity out of its folder without touching the folder itself.",
         handler: async (event, ctx) => {
             const payload = event.payload; // @cast-boundary engine-payload
-            // entityType/entityId are client input: the caller must be able to see
-            // the host row through that entity's own read path (tenant scope plus its
-            // `access.read` ownership) before its assignment row may be written.
-            // Checked FIRST, ahead of every lookup below, so a denied caller can't tell
-            // an invisible parent apart from a missing assignment or an unknown folder —
-            // every path answers with the same NotFoundError.
-            if (!(await joinRowParentIsVisible(ctx.registry, "folder-assignment", payload, event.user, ctx.db))) {
-                return writeFailure(new NotFoundError(payload.entityType, payload.entityId));
-            }
+            const denied = await denyUnlessJoinRowParentVisible(ctx.registry, "folder-assignment", payload, event.user, ctx.db);
+            if (denied)
+                return denied;
             const id = folderAssignmentAggregateId(event.user.tenantId, payload.entityType, payload.entityId);
             const existing = await folderAssignmentExecutor.detail({ id }, event.user, ctx.db);
             if (!existing) {

package/dist/folders/handlers/set-folder.write.js

@@ -1,5 +1,5 @@
 import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
-import { joinRowParentIsVisible } from "../../shared/index.js";
+import { denyUnlessJoinRowParentVisible } from "../../shared/index.js";
 import { folderAssignmentAggregateId } from "../aggregate-id.js";
 import { DEFAULT_FOLDER_ACCESS } from "../constants.js";
 import { folderAssignmentExecutor, folderExecutor } from "../executor.js";
@@ -35,15 +35,9 @@ export function createSetFolderHandler(access = DEFAULT_FOLDER_ACCESS) {
         description: "Files a host entity into one existing folder and moves it out of whatever folder it was in, since an entity belongs to at most one folder; use it for both the first filing and every later move.",
         handler: async (event, ctx) => {
             const payload = event.payload; // @cast-boundary engine-payload
-            // entityType/entityId are client input: the caller must be able to see
-            // the host row through that entity's own read path (tenant scope plus its
-            // `access.read` ownership) before its assignment row may be written.
-            // Checked FIRST, ahead of every lookup below, so a denied caller can't tell
-            // an invisible parent apart from a missing assignment or an unknown folder —
-            // every path answers with the same NotFoundError.
-            if (!(await joinRowParentIsVisible(ctx.registry, "folder-assignment", payload, event.user, ctx.db))) {
-                return writeFailure(new NotFoundError(payload.entityType, payload.entityId));
-            }
+            const denied = await denyUnlessJoinRowParentVisible(ctx.registry, "folder-assignment", payload, event.user, ctx.db);
+            if (denied)
+                return denied;
             const id = folderAssignmentAggregateId(event.user.tenantId, payload.entityType, payload.entityId);
             const folder = await folderExecutor.detail({ id: payload.folderId }, event.user, ctx.db);
             if (!folder)

package/dist/form-draft/feature.js

@@ -12,6 +12,7 @@ import { discardDraftWrite } from "./handlers/discard.write.js";
 import { getDraftQuery } from "./handlers/get.query.js";
 import { listDraftsQuery } from "./handlers/list.query.js";
 import { saveDraftWrite } from "./handlers/save.write.js";
+const CLEANUP_ESCAPE_HATCH_REASON = "purges stale drafts of every tenant";
 function registerFormDraft(r) {
     r.describe("Per-user, per-tenant working copy of an in-progress form, saved BEFORE the real domain entity exists. Owns one event-sourced entity, `form-draft` (`read_form_drafts`), keyed by a caller-assigned draftKey (typically screenId + optional hostEntityId), unique per (tenant, owner, draftKey). `save` upserts the draft blob ({ values, stepIndex, savedAt } — savedAt stamped server-side), `discard` deletes it (called once the real submit succeeds), `get` resumes it, `list` finds a user's open drafts for a given screenId (draftKey prefix match) — the fallback when a client-generated draftId is lost. Ownership is enforced by a per-row owner filter in every handler, not by roles — a foreign user's save/discard/get/list for someone else's draftKey never sees or touches that row. Never holds anything that already lives in a domain stream; the consuming app is responsible for discarding once the domain write succeeds. A daily cron job hard-deletes drafts past a configurable retention window (`form-draft:config:retention-days`, SystemAdmin-writable, default 30 days).");
     r.uiHints({
@@ -36,8 +37,8 @@ function registerFormDraft(r) {
         name: "cleanup",
         trigger: { cron: "0 3 * * *" },
         concurrency: "skip",
-        escapeHatch: { reason: "purges stale drafts of every tenant" },
-        handler: (payload, ctx) => cleanupDraftsJob(payload, ctx, ctx.db.unsafeRaw("purges stale drafts of every tenant")),
+        escapeHatch: { reason: CLEANUP_ESCAPE_HATCH_REASON },
+        handler: (payload, ctx) => cleanupDraftsJob(payload, ctx, ctx.db.unsafeRaw(CLEANUP_ESCAPE_HATCH_REASON)),
     });
 }
 export const formDraftFeature = defineFeature(FORM_DRAFT_FEATURE_NAME, registerFormDraft);

package/dist/form-draft/handlers/discard.write.js

@@ -73,18 +73,17 @@ export const discardDraftWrite = defineWriteHandler({
             const keys = ownedRefs.map((ref) => ref.storageKey);
             const log = ctx.log;
             const schedule = ctx.scheduleAfterCommit;
+            const release = async () => {
+                await releaseDraftFileRefs(keys, async (key) => {
+                    await files.ref(key).delete();
+                }, log);
+            };
             if (schedule) {
-                schedule(async () => {
-                    await releaseDraftFileRefs(keys, async (key) => {
-                        await files.ref(key).delete();
-                    }, log);
-                });
+                schedule(release);
             }
             else {
                 // Unit/harness paths without a commit sink — best-effort inline.
-                await releaseDraftFileRefs(keys, async (key) => {
-                    await files.ref(key).delete();
-                }, log);
+                await release();
             }
         }
         return { isSuccess: true, data: { discarded: true } };

package/dist/form-draft/handlers/get.query.js

@@ -16,6 +16,12 @@ export const getDraftQuery = defineQueryHandler({
         if (!row)
             return { draft: null };
         const parsed = formDraftBlobSchema.safeParse(row.draft);
-        return { draft: parsed.success ? parsed.data : null };
+        if (!parsed.success) {
+            // Schema evolution or a corrupt jsonb row: surface it to operators
+            // instead of silently making the user's draft vanish.
+            ctx.log?.warn?.(`[form-draft:get] stored blob for draftKey=${query.payload.draftKey} failed schema, treating as absent: ${parsed.error.message}`);
+            return { draft: null };
+        }
+        return { draft: parsed.data };
     },
 });

package/dist/foundation-shared/host-allowlist.d.ts

@@ -0,0 +1,4 @@
+/** Parses a comma-separated operator host allowlist env var. Never throws —
+ *  an unset or empty value just means no bypass. */
+export declare function readHostAllowlistFromEnv(envVar: string, env?: Readonly<Record<string, string | undefined>>): readonly string[];
+export declare function isHostAllowlisted(host: string, allowlist: readonly string[]): boolean;

package/dist/foundation-shared/host-allowlist.js

@@ -0,0 +1,14 @@
+/** Parses a comma-separated operator host allowlist env var. Never throws —
+ *  an unset or empty value just means no bypass. */
+export function readHostAllowlistFromEnv(envVar, env = process.env) {
+    const raw = env[envVar];
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((host) => host.trim())
+        .filter((host) => host.length > 0);
+}
+export function isHostAllowlisted(host, allowlist) {
+    return allowlist.some((candidate) => candidate.toLowerCase() === host.toLowerCase());
+}

package/dist/foundation-shared/index.d.ts

@@ -1,2 +1,3 @@
 export { requireDefined, requireNonEmpty, requireSecretSet } from "./config-helpers.js";
+export { isHostAllowlisted, readHostAllowlistFromEnv } from "./host-allowlist.js";
 export { BlockedHostError, HostResolutionError, MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR, type MailConnectTarget, type MailHostGuardOptions, readAllowedPrivateMailHostsFromEnv, resolveMailConnectTarget, } from "./mail-host-policy.js";

package/dist/foundation-shared/index.js

@@ -1,4 +1,5 @@
 // Public API of foundation-shared — utilities consumed by the per-tenant
 // Foundation packages (ai-foundation, mail-foundation, file-foundation).
 export { requireDefined, requireNonEmpty, requireSecretSet } from "./config-helpers.js";
+export { isHostAllowlisted, readHostAllowlistFromEnv } from "./host-allowlist.js";
 export { BlockedHostError, HostResolutionError, MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR, readAllowedPrivateMailHostsFromEnv, resolveMailConnectTarget, } from "./mail-host-policy.js";

package/dist/foundation-shared/mail-host-policy.d.ts

@@ -1,7 +1,5 @@
 import type { lookup } from "node:dns/promises";
 export declare const MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR = "KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS";
-/** Parses the comma-separated operator allowlist env var. Never throws —
- *  an unset or empty value just means no bypass. */
 export declare function readAllowedPrivateMailHostsFromEnv(env?: Readonly<Record<string, string | undefined>>): readonly string[];
 export type MailHostGuardOptions = {
     readonly allowedPrivateMailHosts?: readonly string[];

package/dist/foundation-shared/mail-host-policy.js

@@ -16,23 +16,13 @@
 // conflict check tripping when both features are mounted together.
 import { isIP } from "node:net";
 import { resolvePublicHostname } from "@cosmicdrift/kumiko-framework/http";
+import { isHostAllowlisted, readHostAllowlistFromEnv } from "./host-allowlist.js";
 export const MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR = "KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS";
-/** Parses the comma-separated operator allowlist env var. Never throws —
- *  an unset or empty value just means no bypass. */
 export function readAllowedPrivateMailHostsFromEnv(env = process.env) {
-    const raw = env[MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR];
-    if (!raw)
-        return [];
-    return raw
-        .split(",")
-        .map((host) => host.trim())
-        .filter((host) => host.length > 0);
-}
-function isAllowedPrivateMailHost(host, allowed) {
-    return allowed.some((candidate) => candidate.toLowerCase() === host.toLowerCase());
+    return readHostAllowlistFromEnv(MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR, env);
 }
 export async function resolveMailConnectTarget(host, options = {}) {
-    if (isAllowedPrivateMailHost(host, options.allowedPrivateMailHosts ?? [])) {
+    if (isHostAllowlisted(host, options.allowedPrivateMailHosts ?? [])) {
         return { host };
     }
     const resolved = await resolvePublicHostname(host, options.lookupFn);

package/dist/inbound-mail-foundation/connect-routes.js

@@ -73,6 +73,12 @@ export function createInboundMailConnectRoutes(options) {
         verify: async (request) => verifyCallbackRequest(request, options.stateSecret),
         handler: async (c, verified, deps) => {
             const { code, state } = verified;
+            // Checked before exchangeCode/connectAccount: the code is single-use and
+            // an account created without a persistable refresh token is an orphan.
+            // `deps.secrets` is optional on SignatureExtraRouteDeps.
+            if (!deps.secrets) {
+                return errorJson(c, 500, "secrets_context_missing", `${INBOUND_MAIL_FOUNDATION_FEATURE}: no secrets context wired for the oauth callback route — the refresh token cannot be persisted`);
+            }
             const providerCtx = { registry: deps.registry, secrets: deps.secrets, config: undefined };
             let plugin;
             try {
@@ -123,11 +129,7 @@ export function createInboundMailConnectRoutes(options) {
             }
             // Refresh-token into the per-account secret slot (Slot = accountId).
             // Access tokens (~1h) are NEVER persisted — refresh-before-poll in the
-            // sync path. `deps.secrets` is optional on SignatureExtraRouteDeps —
-            // without it the token would be silently lost, so fail loud instead.
-            if (!deps.secrets) {
-                return errorJson(c, 500, "secrets_context_missing", `${INBOUND_MAIL_FOUNDATION_FEATURE}: no secrets context wired for the oauth callback route — the refresh token cannot be persisted`);
-            }
+            // sync path.
             await deps.secrets.set(state.tenantId, inboundCredentialSecretKey(accountId), tokens.refreshToken, {
                 redact: (plaintext) => `${plaintext.slice(0, 4)}…`,
                 hint: `OAuth refresh token for inbound mail account ${accountId}`,

package/dist/inbound-mail-foundation/watch-supervisor.js

@@ -121,7 +121,8 @@ export function createInboundMailSupervisor(deps) {
             return null; // korrupter Cursor = wie kein Cursor → Backfill, Dedup fängt Dubletten
         }
     }
-    async function saveCursor(accountId, cursor) {
+    async function saveCursor(account, cursor) {
+        const accountId = account.id;
         const now = Temporal.Now.instant().toString();
         const serialized = JSON.stringify(cursor);
         const existing = await fetchOne(deps.db, syncCursorTable, {
@@ -135,6 +136,8 @@ export function createInboundMailSupervisor(deps) {
         }
         await insertOne(deps.db, syncCursorTable, {
             id: crypto.randomUUID(),
+            // Direct-write store: no executor stamps the NOT NULL tenant_id for us.
+            tenantId: account.tenantId,
             accountId,
             scope: CURSOR_SCOPE,
             cursor: serialized,
@@ -227,7 +230,7 @@ export function createInboundMailSupervisor(deps) {
                     maxMessages: budget,
                 });
                 await ingestBatch(account, result.messages, JSON.stringify(result.nextCursor));
-                await saveCursor(account.id, result.nextCursor);
+                await saveCursor(account, result.nextCursor);
                 cursor = result.nextCursor;
                 budget -= result.messages.length;
                 if (!result.hasMore || budget <= 0)
@@ -267,51 +270,52 @@ export function createInboundMailSupervisor(deps) {
     // lifecycle — it keeps renewing across reconnect backoff, not just while
     // `plugin.watch()` is actually connected, so a flaky IMAP link doesn't
     // make this worker lose the account to a peer mid-backoff.
-    // kumiko-lint-ignore complexity-budget watch lease renew backoff/re-acquire loop
     function scheduleRenew(account, state, generation) {
         state.renewTimer = setTimeout(() => {
-            // kumiko-lint-ignore complexity-budget renew timer callback (renew/backoff/re-acquire)
-            void (async () => {
-                state.renewTimer = null;
-                // skip: supervisor stopped, generation superseded, or lease already lost — stale timer fire, nothing to renew.
-                if (!running || state.generation !== generation || !state.lockToken || !deps.lock)
-                    return;
-                let renewed;
-                try {
-                    renewed = await deps.lock.renew(account.id, state.lockToken, leaseTtlSeconds);
-                }
-                catch (err) {
-                    log(`inbound-mail: watch lease renew for account ${account.id} failed: ${err instanceof Error ? err.message : String(err)}`);
-                    state.renewFailures += 1;
-                    // After failures spanning a full lease TTL, tear down — otherwise a
-                    // peer can acquire the expired key while we still hold an IDLE conn.
-                    if (state.renewFailures * renewIntervalMs >= leaseTtlSeconds * 1000) {
-                        log(`inbound-mail: watch lease renew for account ${account.id} failed across TTL — tearing down local watcher`);
-                        state.lockToken = null;
-                        await stopWatcher(account.id);
-                        // skip: local watcher torn down after renew failures spanning a full lease TTL.
-                        return;
-                    }
-                    if (running && state.generation === generation && state.lockToken) {
-                        scheduleRenew(account, state, generation);
-                    }
-                    // skip: renew already rescheduled above (or conditions no longer hold) — nothing left to do this tick.
-                    return;
-                }
-                state.renewFailures = 0;
-                if (!renewed) {
-                    log(`inbound-mail: watch lease for account ${account.id} lost — tearing down local watcher`);
-                    state.lockToken = null;
-                    await stopWatcher(account.id);
-                    // skip: watcher already torn down by stopWatcher() above — nothing left to do.
-                    return;
-                }
-                if (running && state.generation === generation && state.lockToken) {
-                    scheduleRenew(account, state, generation);
-                }
-            })();
+            void renewLeaseOnce(account, state, generation);
         }, renewIntervalMs);
     }
+    async function tearDownAfterRenewFailures(account, state, reason) {
+        log(`inbound-mail: watch lease ${reason} for account ${account.id} — tearing down local watcher`);
+        state.lockToken = null;
+        await stopWatcher(account.id);
+    }
+    async function renewLeaseOnce(account, state, generation) {
+        state.renewTimer = null;
+        // skip: supervisor stopped, generation superseded, or lease already lost — stale timer fire, nothing to renew.
+        if (!running || state.generation !== generation || !state.lockToken || !deps.lock)
+            return;
+        let renewed;
+        try {
+            renewed = await deps.lock.renew(account.id, state.lockToken, leaseTtlSeconds);
+        }
+        catch (err) {
+            log(`inbound-mail: watch lease renew for account ${account.id} failed: ${err instanceof Error ? err.message : String(err)}`);
+            state.renewFailures += 1;
+            // After failures spanning a full lease TTL, tear down — otherwise a
+            // peer can acquire the expired key while we still hold an IDLE conn.
+            if (state.renewFailures * renewIntervalMs >= leaseTtlSeconds * 1000) {
+                await tearDownAfterRenewFailures(account, state, "renew failed across TTL");
+                // skip: connection torn down, no reschedule
+                return;
+            }
+            rescheduleIfStillHeld(account, state, generation);
+            // skip: renew failed but TTL not yet exhausted, retry already scheduled
+            return;
+        }
+        state.renewFailures = 0;
+        if (!renewed) {
+            await tearDownAfterRenewFailures(account, state, "lost");
+            // skip: lease lost and torn down, nothing to reschedule
+            return;
+        }
+        rescheduleIfStillHeld(account, state, generation);
+    }
+    function rescheduleIfStillHeld(account, state, generation) {
+        if (running && state.generation === generation && state.lockToken) {
+            scheduleRenew(account, state, generation);
+        }
+    }
     // kumiko-lint-ignore complexity-budget yield-point stale-map check after acquire is intentional (#2460)
     async function acquireWatchLease(account, state) {
         if (!deps.lock || state.lockToken)

package/dist/jobs/handlers/list.query.d.ts

@@ -8,9 +8,14 @@ export declare const listQuery: import("@cosmicdrift/kumiko-types/define-handler
         running: "running";
     }>>;
     filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        field: z.ZodString;
+        field: z.ZodLiteral<"status">;
         op: z.ZodLiteral<"in">;
-        value: z.ZodArray<z.ZodString>;
+        value: z.ZodArray<z.ZodEnum<{
+            completed: "completed";
+            failed: "failed";
+            queued: "queued";
+            running: "running";
+        }>>;
     }, z.core.$strip>>>;
     sort: z.ZodOptional<z.ZodEnum<{
         duration: "duration";

package/dist/jobs/handlers/list.query.js

@@ -5,6 +5,7 @@ import * as z from "zod";
 import { decryptStoredPii, mapWithConcurrency } from "../../shared/index.js";
 import { jobRunsTable } from "../job-run-table.js";
 const KMS_POOL_CONCURRENCY = 4;
+const jobRunStatusSchema = z.enum(["queued", "running", "completed", "failed"]);
 async function decryptRunRow(row) {
     let result = row;
     if (typeof result["payload"] === "string") {
@@ -23,9 +24,13 @@ export const listQuery = defineQueryHandler({
     description: "Lists job runs across all tenants newest-first, optionally filtered by job name and status; use it to check whether a job ran and whether it succeeded.",
     schema: z.object({
         jobName: z.string().optional(),
-        status: z.enum(["queued", "running", "completed", "failed"]).optional(),
+        status: jobRunStatusSchema.optional(),
         filters: z
-            .array(z.object({ field: z.string(), op: z.literal("in"), value: z.array(z.string()) }))
+            .array(z.object({
+            field: z.literal("status"),
+            op: z.literal("in"),
+            value: z.array(jobRunStatusSchema),
+        }))
             .optional(),
         sort: z.enum(["jobName", "status", "startedAt", "duration"]).optional(),
         sortDirection: z.enum(["asc", "desc"]).optional(),
@@ -47,6 +52,8 @@ export const listQuery = defineQueryHandler({
         const statuses = statusFilter?.value ?? (query.payload.status ? [query.payload.status] : []);
         if (statuses.length === 1)
             where["status"] = statuses[0];
+        else if (statuses.length > 1)
+            where["status"] = { in: statuses };
         const sortColumn = query.payload.sort ?? "startedAt";
         const rows = await selectMany(db, jobRunsTable, where, {
             orderBy: { col: sortColumn, direction: query.payload.sortDirection ?? "desc" },

package/dist/jobs/handlers/retry.write.js

@@ -1,5 +1,5 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
-import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-framework/crypto";
+import { isPiiCiphertext, PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-framework/crypto";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, NotFoundError, UnprocessableError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
 import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
@@ -44,7 +44,8 @@ export const retryWrite = defineWriteHandler({
         let decryptedPayloadJson = null;
         if (run.payload) {
             const decryptedPayload = await decryptStoredPii(run.payload, "payload", `job run ${event.payload.runId} payload`);
-            if (decryptedPayload === PII_ERASED_SENTINEL) {
+            // Still-ciphertext means no KMS could decrypt it (rollout mode); not JSON either.
+            if (decryptedPayload === PII_ERASED_SENTINEL || isPiiCiphertext(decryptedPayload)) {
                 return writeFailure(new UnprocessableError(JobErrors.payloadErased, {
                     i18nKey: "jobs.errors.payloadErased",
                 }));

package/dist/jobs/handlers/tenant-failures.query.js

@@ -1,17 +1,11 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { serializeJobSubject } from "@cosmicdrift/kumiko-framework/jobs";
 import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
 import { tenantJobFailuresTable } from "../tenant-job-failure-table.js";
 const DEFAULT_LIMIT = 50;
-// Mirrors job-runner.ts's jobSubjectKey: sorted field names, so a caller that
-// passes the same subject values gets the same string the writer stored.
-function subjectKey(subject) {
-    return JSON.stringify(Object.keys(subject)
-        .sort()
-        .map((field) => [field, subject[field] ?? null]));
-}
 function isSubjectEntry(value) {
     return Array.isArray(value) && typeof value[0] === "string";
 }
@@ -28,7 +22,7 @@ function parseSubject(stored) {
 }
 export const tenantFailuresQuery = defineQueryHandler({
     name: "failures",
-    description: "Lists the calling tenant's own failed jobs — one record per job and subject, newest first, each carrying a translation key for the reason, never the provider's own error message; use it to tell a tenant that their asynchronous job failed instead of leaving the screen waiting.",
+    description: "Lists the calling tenant's own failed jobs — one record per job and subject, newest first, each carrying a translation key for the reason, never the provider's own error message; the optional subject filter matches exactly: all declared subjectFields with the same JSON types as the job payload; use it to tell a tenant that their asynchronous job failed instead of leaving the screen waiting.",
     schema: z.object({
         jobName: z.string().optional(),
         subject: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
@@ -52,7 +46,7 @@ export const tenantFailuresQuery = defineQueryHandler({
         if (query.payload.jobName)
             where["jobName"] = query.payload.jobName;
         if (query.payload.subject)
-            where["subject"] = subjectKey(query.payload.subject);
+            where["subject"] = serializeJobSubject(query.payload.subject);
         const rows = await selectMany(db, tenantJobFailuresTable, where, {
             orderBy: { col: "failedAt", direction: "desc" },
             limit: query.payload.limit ?? DEFAULT_LIMIT,

package/dist/jobs/job-run-logger.js

@@ -1,6 +1,7 @@
 import { deleteMany, fetchOne, insertMany, insertOne, updateMany, } from "@cosmicdrift/kumiko-framework/bun-db";
 import { configuredPiiSubjectKms, encryptPiiValueForSubject, KeyErasedError, PII_ERASED_SENTINEL, } from "@cosmicdrift/kumiko-framework/crypto";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { mapWithConcurrency } from "../shared/index.js";
 import { runCompletedSchema, runFailedSchema, runStartedSchema } from "./events.js";
@@ -128,6 +129,21 @@ async function clearTenantJobFailure(db, jobName, outcome) {
         return;
     await deleteMany(db, tenantJobFailuresTable, where);
 }
+const log = createFallbackLogger("job-run-logger");
+// The tenant failure record is an optional side write: a throw here must not
+// skip the run-row update or turn a completed run into a BullMQ retry.
+async function isolateTenantFailureWrite(write, jobName, bullJobId) {
+    try {
+        await write();
+    }
+    catch (e) {
+        log.error("tenant job failure record write failed", {
+            jobName,
+            bullJobId,
+            error: e instanceof Error ? e.message : String(e),
+        });
+    }
+}
 export function createJobRunLogger(opts) {
     const { db } = opts;
     const runIdByBullJobId = new Map();
@@ -210,7 +226,7 @@ export function createJobRunLogger(opts) {
             // Before the run-row write and independent of it: a successful run
             // clears the tenant's failure record even when the run row itself is
             // unreachable (the state-loss return below).
-            await clearTenantJobFailure(db, jobName, outcome);
+            await isolateTenantFailureWrite(() => clearTenantJobFailure(db, jobName, outcome), jobName, bullJobId);
             const resolved = await resolveRun(bullJobId);
             // skip: state loss between start + complete (worker restart, cache
             // evicted AND DB has no matching bull_job_id). Rare edge case; we
@@ -255,7 +271,7 @@ export function createJobRunLogger(opts) {
         onJobFailed: async (jobName, bullJobId, error, logs, outcome) => {
             // Mirror of onJobComplete: recorded independently of the run row, so a
             // tenant still learns their job failed if the row is unreachable.
-            await recordTenantJobFailure(db, jobName, outcome);
+            await isolateTenantFailureWrite(() => recordTenantJobFailure(db, jobName, outcome), jobName, bullJobId);
             const resolved = await resolveRun(bullJobId);
             // skip: same rare state-loss case as in onJobComplete — drop the
             // failure write rather than forge a run row from scratch.

package/dist/jobs/tenant-job-failure-table.js

@@ -1,4 +1,4 @@
-import { asEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
+import { requireEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
 import { instant, table as pgTable, serial, sql, text, uuid, } from "@cosmicdrift/kumiko-framework/db";
 // The tenant's own view of a failed job (fw#3079). Direct-write store like
 // store_job_runs: job-run-logger.ts writes it from the BullMQ callbacks,
@@ -22,8 +22,4 @@ export const tenantJobFailuresTable = pgTable("store_tenant_job_failures", {
     messageKey: text("message_key").notNull(),
     failedAt: instant("failed_at").default(sql `now()`).notNull(),
 });
-const derivedTenantJobFailuresTableMeta = asEntityTableMeta(tenantJobFailuresTable);
-if (!derivedTenantJobFailuresTableMeta) {
-    throw new Error("tenantJobFailuresTable: table carries no EntityTableMeta — built via table()?");
-}
-export const tenantJobFailuresTableMeta = derivedTenantJobFailuresTableMeta;
+export const tenantJobFailuresTableMeta = requireEntityTableMeta(tenantJobFailuresTable, "tenantJobFailuresTable");

package/dist/ledger/handlers/confirm-schedule-period.write.js

@@ -4,6 +4,7 @@ import { DEFAULT_LEDGER_ACCESS } from "../constants.js";
 import { accountExecutor, scheduleExecutor, transactionExecutor, transactionTable, } from "../executor.js";
 import { findReversedIds, isoMonth, scheduleReference } from "../recurring.js";
 import { confirmSchedulePeriodPayloadSchema, } from "../schemas.js";
+import { readSubjectReference } from "../subject-reference.js";
 // confirm-schedule-period — turn ONE projected period of a schedule into a posted,
 // balanced transaction (debit +amount / credit −amount), tagged with
 // scheduleReference(scheduleId, period) so the host can merge Soll vs. Ist.
@@ -70,8 +71,7 @@ export function createConfirmSchedulePeriodHandler(access = DEFAULT_LEDGER_ACCES
             const amount = payload.amount ?? Number(schedule["amount"]);
             // The subject is a property of the schedule, not the confirm call — a
             // period without one stays without one, no backfill/error.
-            const subjectType = typeof schedule["subjectType"] === "string" ? schedule["subjectType"] : null;
-            const subjectId = typeof schedule["subjectId"] === "string" ? schedule["subjectId"] : null;
+            const { subjectType, subjectId } = readSubjectReference(schedule);
             const created = await transactionExecutor.create({
                 id: generateId(),
                 date: payload.date ?? `${payload.period}-01`,

package/dist/ledger/handlers/reverse-transaction.write.js

@@ -4,6 +4,7 @@ import { DEFAULT_LEDGER_ACCESS } from "../constants.js";
 import { transactionExecutor, transactionTable } from "../executor.js";
 import { normalizeLines } from "../reports.js";
 import { reverseTransactionPayloadSchema } from "../schemas.js";
+import { readSubjectReference } from "../subject-reference.js";
 // reverse-transaction (Storno) — the ONLY correction path for a posted entry.
 // Books the mirror image (every amount negated) as a new posted entry that
 // references the original, leaving the original untouched. This is why
@@ -51,8 +52,7 @@ export function createReverseTransactionHandler(access = DEFAULT_LEDGER_ACCESS)
             }));
             // The reversal shares its subject with the original so filtering by
             // subjectId still finds the Storno; unset on the original stays unset.
-            const subjectType = typeof original["subjectType"] === "string" ? original["subjectType"] : null;
-            const subjectId = typeof original["subjectId"] === "string" ? original["subjectId"] : null;
+            const { subjectType, subjectId } = readSubjectReference(original);
             return transactionExecutor.create({
                 id: generateId(),
                 // Pass the original's date through untyped — create takes Record<string,

package/dist/ledger/subject-reference.d.ts

@@ -0,0 +1,4 @@
+export declare function readSubjectReference(row: Record<string, unknown>): {
+    subjectType: string | null;
+    subjectId: string | null;
+};

package/dist/ledger/subject-reference.js

@@ -0,0 +1,7 @@
+// Subject columns are nullable; anything that is not a string reads as unset.
+export function readSubjectReference(row) {
+    return {
+        subjectType: typeof row["subjectType"] === "string" ? row["subjectType"] : null,
+        subjectId: typeof row["subjectId"] === "string" ? row["subjectId"] : null,
+    };
+}

package/dist/legal-pages/feature.js

@@ -36,6 +36,12 @@ export function createLegalPagesFeature(opts = {}) {
     const routes = opts.routes ?? LEGAL_ROUTES;
     const requiredBlocks = opts.requiredBlocks ?? LEGAL_REQUIRED_BLOCKS;
     validateRoutes(routes);
+    if (opts.routes !== undefined && opts.routes.length > 0 && opts.requiredBlocks === undefined) {
+        const coversDefaultBlock = LEGAL_REQUIRED_BLOCKS.some((block) => opts.routes?.some((route) => route.slug === block.slug && route.lang === block.lang));
+        if (!coversDefaultBlock) {
+            throw new Error("legal-pages: custom `routes` without `requiredBlocks` — pass `requiredBlocks` explicitly (or `[]`)");
+        }
+    }
     return defineFeature("legal-pages", (r) => {
         r.describe("Opt-in wrapper around `template-resolver` text-blocks that registers public HTML routes (default: `/legal/impressum`, `/legal/datenschutz`, `/legal/imprint`, `/legal/privacy`) with Markdown-to-HTML rendering and a boot-time job that hard-fails in production when the required blocks (default: `imprint/de`, `privacy/de`) are not seeded in `SYSTEM_TENANT`. Both are configurable via `routes`/`requiredBlocks` for apps with a different default language or additional pages. Requires `anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID }` and `extraContext.templateResolver` to be wired at app bootstrap; for per-tenant imprints or a custom layout call `template-resolver:query:by-slug` directly.");
         r.uiHints({
@@ -75,9 +81,10 @@ export function createLegalPagesFeature(opts = {}) {
                     }
                     const etag = computeRevisionEtag([
                         SYSTEM_TENANT_ID,
+                        route.path,
                         route.slug,
                         route.lang,
-                        data.updatedAt,
+                        String(data.modifiedAt ?? ""),
                     ]);
                     const extra = { "content-type": "text/html; charset=utf-8" };
                     // 304 (Revision unverändert) und HEAD überspringen beide das

package/dist/managed-pages/handlers/branding.query.js

@@ -18,7 +18,7 @@ export function createBrandingQuery(opts) {
         name: "branding",
         schema: z.object({}),
         access: { roles: ["anonymous", "User", "TenantAdmin", "SystemAdmin"] },
-        rateLimit: { per: "ip", limit: 60, windowSeconds: 60 },
+        rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
         description: "Reads the tenant's public branding values for the rendered page shell, adding the raw custom CSS only when the app opted in and the per-tenant CSS toggle is on; anonymous callers may read it because it dresses public pages.",
         handler: async (_query, ctx) => {
             const base = await readBranding(ctx.config);