@cosmicdrift/kumiko-samples 0.387.0 → 0.389.0

package/packages/bundled-features/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -324,11 +324,6 @@ async function sweepDerivedSubjectData(
   audit: { readonly requestId: string; readonly erasedBy: string },
   rawSubject: SubjectIdInput,
 ): Promise<string | undefined> {
-  const recordTenantId = await owningTenantOfRecordSubject(
-    crossTenantRunner,
-    ctx.registry.features,
-    rawSubject,
-  );
   const failureLabels: string[] = [];
   const runStep = async (step: (runner: DbRunner) => Promise<void>): Promise<void> => {
     try {
@@ -367,8 +362,14 @@ async function sweepDerivedSubjectData(
   });
 
   // File columns hold only the fileRef id, so the key erase never reaches the bytes.
-  await runStep((crossTenantSubjectRunner) =>
-    purgeFilesReachingSubject({
+  await runStep(async (crossTenantSubjectRunner) => {
+    // Inside the step: a failing owner lookup must land in the audit label, not abort the handler.
+    const recordTenantId = await owningTenantOfRecordSubject(
+      crossTenantSubjectRunner,
+      ctx.registry.features,
+      rawSubject,
+    );
+    await purgeFilesReachingSubject({
       registry: ctx.registry,
       db: crossTenantSubjectRunner,
       subject,
@@ -376,8 +377,8 @@ async function sweepDerivedSubjectData(
       ...(recordTenantId !== undefined && { recordTenantId }),
       resolveDeleteBytes: resolveFileBytesDeleter(ctx),
       missingStorage: { mode: "fail" },
-    }),
-  );
+    });
+  });
 
   return failureLabels[0];
 }
@@ -561,7 +562,7 @@ export const forgetSubjectWrite = defineWriteHandler({
     //   - user.updated as lifecycle event (updateUserLifecycle), so a
     //     read_users rebuild doesn't wipe the flip
     //   - sessions don't need active revocation — session-callbacks
-    //     re-validate user.status on every request (isPrincipalBlocked
+    //     re-validate the user row on every request (isPrincipalRowBlocked
     //     blocks Deleted).
     // Both idempotent (status set / revokedAt IS NULL filter), retry after
     // crash recovery is safe. User-feature guard: without the user feature

package/packages/bundled-features/src/custom-fields/lib/parse-serialized-field.ts

@@ -1,7 +1,7 @@
 // Centralised parser for `fieldDefinition.serializedField`.
 //
 // The column is stored as `text` in B1 (entity.ts) — what the db row hands
-// back depends on the driver: postgres-js returns text as a `string`, but
+// back depends on the driver: text normally arrives as a `string`, but
 // jsonb-tolerant drivers and middleware can deliver an already-parsed
 // object. This helper normalises both, validates the shape, and centralises
 // the single boundary cast so callers don't sprinkle `as { … }`-narrowings

package/packages/bundled-features/src/delivery/changes.json

@@ -1,4 +1,46 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Unsubscribe link origin is looked up once per notify call",
+    "detail": "The tenantOrigin callback runs once per tenant for a notify call with many recipients, and a fallback warning is logged once. A callback that hangs is still not guarded by a timeout, so keep it fast."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "buildSystemChannelContext for system tenant mails outside a handler",
+    "detail": "buildSystemChannelContext(deps, { config, secrets }) returns a ChannelContext for the system tenant whose readAttachment reads file and inline attachments. SystemWireDeps (wire hook and runWorkerApp wireComponents) has a new required filesForTenant that deps can pass straight in."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Preferences query reports renamed notification types under the current name",
+    "detail": "Rows stored under a former notification name are returned with the current name and collapsed per channel with the delivery precedence (current-name row wins, otherwise any disabled row disables), so settings screens show the effective state."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Inline mail image retries on transient storage errors",
+    "detail": "Only a missing file storage for the file's tenant sends the mail without the inline image; any other read error (timeout, provider failure, DB) is rethrown so the send job retries instead of mailing without the logo."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Unsubscribe tenant origin resolved once per notify call",
+    "detail": "The app's tenantOrigin callback runs once per notify call and tenant instead of once per recipient and channel, so a newsletter no longer causes one lookup and one fallback warning per address. The docs state the callback must only return verified, active domains."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "One-click unsubscribe POST keeps the JSON rejection",
+    "detail": "RFC 8058 one-click POSTs (form body List-Unsubscribe=One-Click) answer an invalid or expired token with the JSON 400 again and skip the branding lookup; only browser form submits get the HTML page."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Resubscribe limit page has its own text",
+    "detail": "A browser that hits the resubscribe limit sees that the address cannot be subscribed again here, instead of the generic \"try again later\" error (new key mail.unsubscribe.resubscribeLimitReached in en, de, es, fr, it)."
+  },
   {
     "version": "0.383.0",
     "type": "fix",

package/packages/bundled-features/src/delivery/channel-context.ts

@@ -5,7 +5,11 @@ import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import { type FileRefContent, readFileRefContent } from "../file-foundation/index.ts";
+import {
+  type FileRefContent,
+  FileStorageUnavailableError,
+  readFileRefContent,
+} from "../file-foundation/index.ts";
 import {
   collectRendererPlugins,
   createRendererFoundationApi,
@@ -86,7 +90,8 @@ function createPdfRenderer(
   };
 }
 
-// A decorative inline image (logo) that cannot be read must not fail the whole mail.
+// A decorative inline image (logo) of a tenant without file storage must not fail the whole mail;
+// transient read errors rethrow so the send job retries.
 async function readInlineImageOrNull(
   fileRefId: string,
   read: () => Promise<FileRefContent | null>,
@@ -94,9 +99,10 @@ async function readInlineImageOrNull(
   try {
     return await read();
   } catch (err) {
+    if (!(err instanceof FileStorageUnavailableError)) throw err;
     createFallbackLogger("delivery").warn("inline image could not be read, sending without it", {
       fileRefId,
-      errorName: err instanceof Error ? err.name : typeof err,
+      errorName: err.name,
     });
     return null;
   }

package/packages/bundled-features/src/delivery/db/queries/preferences.ts

@@ -1,5 +1,5 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
+import { toPostgresArrayLiteral, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 
 export type NotificationPreferenceRow = {
@@ -27,6 +27,6 @@ export async function selectNotificationPreferences(
          OR (notification_type = '*' AND channel = $4)
          OR (notification_type = ANY($3::text[]) AND channel = '*')
        )`,
-    [tenantId, userId, notificationTypeNames, channelName],
+    [tenantId, userId, toPostgresArrayLiteral(notificationTypeNames), channelName],
   );
 }

package/packages/bundled-features/src/delivery/delivery-service.ts

@@ -484,9 +484,37 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     }
   }
 
+  // The app's tenantOrigin callback typically hits the DB: once per run and tenant, not per recipient.
+  const unsubscribeOriginsByRun = new WeakMap<NotifyRun, Map<TenantId, Promise<string>>>();
+
+  function unsubscribeOriginOnce(
+    run: NotifyRun,
+    links: UnsubscribeLinkConfig,
+    channelCtx: ChannelContext,
+    notificationType: string,
+  ): Promise<string> {
+    let originsByTenant = unsubscribeOriginsByRun.get(run);
+    if (originsByTenant === undefined) {
+      originsByTenant = new Map();
+      unsubscribeOriginsByRun.set(run, originsByTenant);
+    }
+    let origin = originsByTenant.get(channelCtx.tenantId);
+    if (origin === undefined) {
+      origin = unsubscribeLinkOrigin(links, channelCtx, (reason) =>
+        logError.warn(`unsubscribe link falls back to the app origin: ${reason}`, {
+          tenantId: channelCtx.tenantId,
+          notificationType,
+        }),
+      );
+      originsByTenant.set(channelCtx.tenantId, origin);
+    }
+    return origin;
+  }
+
   // A caller-supplied unsubscribeUrl wins; the recipient comes from the server-side notify
   // context, never from the notification data.
   async function withUnsubscribeUrl(
+    run: NotifyRun,
     message: ChannelMessage,
     channelName: string,
     recipient: UnsubscribeLinkRecipient,
@@ -498,11 +526,11 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     }
     const supplied = message.data?.["unsubscribeUrl"];
     if (typeof supplied === "string" && supplied !== "") return message;
-    const origin = await unsubscribeLinkOrigin(unsubscribeLinks, channelCtx, (reason) =>
-      logError.warn(`unsubscribe link falls back to the app origin: ${reason}`, {
-        tenantId: channelCtx.tenantId,
-        notificationType: message.notificationType,
-      }),
+    const origin = await unsubscribeOriginOnce(
+      run,
+      unsubscribeLinks,
+      channelCtx,
+      message.notificationType,
     );
     const unsubscribeUrl = await buildUnsubscribeUrl(unsubscribeLinks, origin, recipient, {
       tenantId: channelCtx.tenantId,
@@ -811,6 +839,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           channel,
           address,
           message: await withUnsubscribeUrl(
+            run,
             message,
             channel.name,
             { kind: "user", userId },
@@ -914,6 +943,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           channel,
           address,
           message: await withUnsubscribeUrl(
+            run,
             message,
             channel.name,
             { kind: "address", address },

package/packages/bundled-features/src/delivery/feature.ts

@@ -62,6 +62,7 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
   const resolvedAccess = options?.access ?? access.admin;
   const attemptLogRetentionDays = resolveAttemptLogRetentionDays(options?.attemptLogRetentionDays);
   return defineFeature("delivery", (r) => {
+    r.adoptsBundledLists();
     r.describe(
       "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (the `runProdApp` and `runDevApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. An app serving its own (e.g. legacy) unsubscribe links renders the same result page with `renderUnsubscribeResultPage({ kind, locale })`. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.",
     );

package/packages/bundled-features/src/delivery/handlers/preferences.query.ts

@@ -2,6 +2,7 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { currentNotificationType } from "../notification-type-aliases.ts";
 import { notificationPreferencesTable } from "../tables.ts";
 
 export const preferencesQuery = defineQueryHandler({
@@ -37,6 +38,24 @@ export const preferencesQuery = defineQueryHandler({
       userId: query.user.id,
     });
 
-    return { rows };
+    // Rows stored under a former notification name are reported under the current
+    // one, collapsed with the same precedence as delivery: an exact row wins,
+    // otherwise any disabled former-name row disables.
+    const collapsed = new Map<string, { row: (typeof rows)[number]; isExact: boolean }>();
+    for (const row of rows) {
+      const notificationType = currentNotificationType(ctx.registry, row.notificationType);
+      const key = `${notificationType}\u0000${row.channel}`;
+      const isExact = row.notificationType === notificationType;
+      const existing = collapsed.get(key);
+      if (existing?.isExact) continue;
+      const formerNameRowDisablesAlready =
+        existing !== undefined &&
+        !isExact &&
+        (existing.row.enabled === false || row.enabled !== false);
+      if (formerNameRowDisablesAlready) continue;
+      collapsed.set(key, { row: { ...row, notificationType }, isExact });
+    }
+
+    return { rows: [...collapsed.values()].map((entry) => entry.row) };
   },
 });

package/packages/bundled-features/src/delivery/handlers/unsubscribe-page-chrome.query.ts

@@ -33,7 +33,7 @@ export const unsubscribePageChromeQuery = defineQueryHandler({
   // or createUnsubscribePageChromeReader for a tenant the app resolved server-side.
   agent: { expose: false },
   description:
-    "Returns the tenant's mail brand row and footer resolved for one locale, or null without a mail renderer; dispatched by the signed unsubscribe route to dress its pages like the mail, not meant for UI callers.",
+    "Returns the tenant's mail brand row and footer resolved for one locale, or null without a mail renderer; dispatched by the signed unsubscribe route or by createUnsubscribePageChromeReader for a tenant the app resolved server-side, to dress its pages like the mail; not meant for UI callers.",
   handler: async (query, ctx): Promise<MailChrome | null> => {
     const { tenantId } = query.user;
     if (!ctx.systemDb) {

package/packages/bundled-features/src/delivery/index.ts

@@ -73,6 +73,11 @@ export {
 } from "./handlers/unsubscribe-address.write.ts";
 export { currentNotificationType } from "./notification-type-aliases.ts";
 export { createDeliveryNotifyFactory } from "./notify-factory.ts";
+export {
+  buildSystemChannelContext,
+  type SystemChannelContextDeps,
+  type SystemChannelContextOptions,
+} from "./system-channel-context.ts";
 export {
   deliveryAttemptsTable,
   notificationAddressOptOutEntity,

package/packages/bundled-features/src/delivery/system-channel-context.ts

@@ -0,0 +1,33 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { ConfigAccessor, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { buildChannelContext } from "./channel-context.ts";
+import type { ChannelContext } from "./types.ts";
+
+export type SystemChannelContextDeps = {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+  readonly filesForTenant: (tenantId: string) => FileContext | undefined;
+};
+
+export type SystemChannelContextOptions = {
+  readonly config?: ConfigAccessor;
+  readonly secrets?: SecretsContext;
+};
+
+export function buildSystemChannelContext(
+  deps: SystemChannelContextDeps,
+  options: SystemChannelContextOptions = {},
+): ChannelContext {
+  return buildChannelContext(
+    deps.db,
+    deps.registry,
+    undefined,
+    SYSTEM_TENANT_ID,
+    options.secrets,
+    options.config,
+    deps.filesForTenant,
+  );
+}

package/packages/bundled-features/src/delivery/unsubscribe-link.ts

@@ -10,7 +10,9 @@ export type UnsubscribeLinkConfig = {
   readonly secret: string;
   readonly baseUrl: string;
   /** The sending tenant's own public origin (subdomain or custom domain), null when it has
-   *  none. The host must serve this app's `/api` routes. Null, a throw or an unusable value
+   *  none. The host must serve this app's `/api` routes, and the callback must only return a
+   *  verified, active domain of the tenant (the check that lets the app serve under it), else null:
+   *  the link carries a bearer token that unsubscribes and yields a resubscribe token. Null, a throw or an unusable value
    *  fall back to `baseUrl`, so a missing tenant origin never fails a send. */
   readonly tenantOrigin?: (ctx: ChannelContext) => Promise<string | null | undefined>;
 };

package/packages/bundled-features/src/delivery/unsubscribe-page-strings.ts

@@ -14,6 +14,7 @@ export const UNSUBSCRIBE_PAGE_EN = {
   "mail.unsubscribe.resubscribedMessage": "You have been subscribed again.",
   "mail.unsubscribe.failed": "That did not work. Please try again later.",
   "mail.unsubscribe.failedTitle": "Something went wrong",
+  "mail.unsubscribe.resubscribeLimitReached": "This address cannot be subscribed again here.",
   "mail.unsubscribe.invalidTitle": "Link no longer valid",
   "mail.unsubscribe.invalidMessage":
     "This link is invalid or has expired. Please use the unsubscribe link in a more recent email.",

package/packages/bundled-features/src/delivery/unsubscribe-page.ts

@@ -11,6 +11,7 @@ export type UnsubscribePageState =
   | { readonly kind: "unsubscribed"; readonly resubscribeToken?: string }
   | { readonly kind: "resubscribed" }
   | { readonly kind: "failed" }
+  | { readonly kind: "resubscribeLimitReached" }
   | { readonly kind: "invalid" };
 
 export type UnsubscribePageInput = {
@@ -162,6 +163,11 @@ ${tokenForm(DELIVERY_RESUBSCRIBE_PATH, state.resubscribeToken, mailT(lang, "mail
         title: mailT(lang, "mail.unsubscribe.failedTitle"),
         bodyHtml: paragraph("mail.unsubscribe.failed"),
       };
+    case "resubscribeLimitReached":
+      return {
+        title: mailT(lang, "mail.unsubscribe.failedTitle"),
+        bodyHtml: paragraph("mail.unsubscribe.resubscribeLimitReached"),
+      };
     case "invalid":
       return {
         title: mailT(lang, "mail.unsubscribe.invalidTitle"),

package/packages/bundled-features/src/delivery/unsubscribe.ts

@@ -569,11 +569,20 @@ async function verifyPost(
   encodedSecret: Uint8Array,
   purpose: TokenPurpose,
 ): Promise<VerifiedUnsubscribe | RejectedForPage> {
-  return isFormRequest(request.headers["content-type"])
+  return isFormRequest(request.headers["content-type"]) && !isOneClickPost(request)
     ? verifyForPage(token, encodedSecret, purpose, request.headers)
     : verifyUnsubscribeToken(token, encodedSecret, purpose);
 }
 
+// RFC 8058 mail-provider POSTs are form-encoded too, but nobody looks at the answer: they keep
+// the JSON rejection and get no branded page.
+function isOneClickPost(request: SignatureExtraRouteVerifyRequest): boolean {
+  return (
+    isFormRequest(request.headers["content-type"]) &&
+    request.rawBody.trim() === DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE
+  );
+}
+
 function isFormRequest(contentType: string | undefined): boolean {
   return contentType?.includes("application/x-www-form-urlencoded") === true;
 }
@@ -635,22 +644,37 @@ export function createUnsubscribeRoutes(
         : pageResponse(c, deps, { kind: "confirm", token: verified.token }, verified, 200),
   });
 
-  const writeRoute = signatureRoute<VerifiedUnsubscribe | RejectedForPage>({
+  const writeRoute = signatureRoute<
+    (VerifiedUnsubscribe & { readonly oneClick: boolean }) | RejectedForPage
+  >({
     method: "POST",
     path: DELIVERY_UNSUBSCRIBE_PATH,
     entry: "signature",
-    verify: async (request) =>
-      verifyPost(request, tokenFromPostRequest(request), encodedSecret, "unsubscribe"),
+    verify: async (request) => {
+      const verified = await verifyPost(
+        request,
+        tokenFromPostRequest(request),
+        encodedSecret,
+        "unsubscribe",
+      );
+      return verified.kind === "rejected"
+        ? verified
+        : { ...verified, oneClick: isOneClickPost(request) };
+    },
     handler: async (c, verified, deps) => {
       if (verified.kind === "rejected") {
         return pageResponse(c, deps, { kind: "invalid" }, verified, 400);
       }
+      // No chrome lookup for a one-click client: it never renders the page.
+      const pageScope: PageScope = verified.oneClick
+        ? { tenantId: undefined, locale: verified.locale }
+        : verified;
       // Token-verify passed — everything below is a legitimate write. Don't
       // swallow write-errors as "invalid token", that would mask real bugs
       // (e.g. events-table missing, DB down) behind a misleading 400.
       const succeeded = await dispatchUnsubscribeWrite(verified, deps);
       if (!succeeded) {
-        return pageResponse(c, deps, { kind: "failed" }, verified, 500);
+        return pageResponse(c, deps, { kind: "failed" }, pageScope, 500);
       }
       return pageResponse(
         c,
@@ -659,7 +683,7 @@ export function createUnsubscribeRoutes(
           kind: "unsubscribed",
           resubscribeToken: await signResubscribeToken(verified, encodedSecret),
         },
-        verified,
+        pageScope,
         200,
       );
     },
@@ -681,15 +705,12 @@ export function createUnsubscribeRoutes(
       const outcome = await dispatchResubscribeWrite(verified, deps);
       // The undo button on the unsubscribed page posts a form; a browser should land on a page.
       if (isFormRequest(c.req.header("content-type"))) {
-        return outcome === "success"
-          ? pageResponse(c, deps, { kind: "resubscribed" }, verified, 200)
-          : pageResponse(
-              c,
-              deps,
-              { kind: "failed" },
-              verified,
-              outcome === "limit_reached" ? 409 : 500,
-            );
+        if (outcome === "success") {
+          return pageResponse(c, deps, { kind: "resubscribed" }, verified, 200);
+        }
+        return outcome === "limit_reached"
+          ? pageResponse(c, deps, { kind: "resubscribeLimitReached" }, verified, 409)
+          : pageResponse(c, deps, { kind: "failed" }, verified, 500);
       }
       if (outcome === "limit_reached") {
         return c.json(

package/packages/bundled-features/src/document-ingest-foundation/append-missing-extract-event.ts

@@ -0,0 +1,84 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry, SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  appendEventInTenantDb,
+  getStreamVersionInTenantDb,
+} from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  DOCUMENT_EXTRACT_AGGREGATE_TYPE,
+  documentExtractFailedPayloadSchema,
+  documentExtractReadyPayloadSchema,
+} from "./events.ts";
+
+export type ExistingDocumentExtract = {
+  readonly id: string;
+  readonly meta: { readonly error?: unknown } | null;
+};
+
+export type AppendMissingExtractEventDeps = {
+  readonly tenantDb: TenantDb;
+  readonly registry: Registry;
+  readonly actor: SessionUser;
+  readonly tenantId: string;
+};
+
+export type AppendMissingExtractEventOptions = {
+  readonly readyEventQn: string;
+  readonly failedEventQn: string;
+  readonly mapError?: (error: string) => string;
+};
+
+export type AppendMissingExtractEventResult =
+  | "appended-ready"
+  | "appended-failed"
+  | "already-terminal";
+
+// Version 1 of the stream is the extract's created event; anything beyond it is the terminal event.
+const CREATED_ONLY_STREAM_VERSION = 1;
+const UNKNOWN_EXTRACT_ERROR = "unknown extract error";
+
+// A previous delivery created the extract but died before appending its ready/failed event.
+// Without the event, consumers waiting on it hang forever.
+export async function appendMissingDocumentExtractEvent(
+  deps: AppendMissingExtractEventDeps,
+  existing: ExistingDocumentExtract,
+  fileRefId: string,
+  options: AppendMissingExtractEventOptions,
+): Promise<AppendMissingExtractEventResult> {
+  if (deps.tenantDb.tenantId !== deps.tenantId) {
+    throw new InternalError({
+      message: `document-ingest-foundation: tenantDb is bound to tenant ${deps.tenantDb.tenantId}, not ${deps.tenantId}`,
+    });
+  }
+  const version = await getStreamVersionInTenantDb(deps.tenantDb, existing.id);
+  // A missing stream means a wrong id; appending would make the terminal event the first event of a new stream.
+  if (version === 0) {
+    throw new InternalError({
+      message: `document-ingest-foundation: no document extract stream for id ${existing.id}`,
+    });
+  }
+  // skip: the terminal event was already written, nothing to catch up
+  if (version > CREATED_ONLY_STREAM_VERSION) return "already-terminal";
+  const metaError = existing.meta?.error;
+  const failed = typeof metaError === "string";
+  await appendEventInTenantDb(
+    deps.tenantDb,
+    {
+      aggregateId: existing.id,
+      aggregateType: DOCUMENT_EXTRACT_AGGREGATE_TYPE,
+      expectedVersion: version,
+      type: failed ? options.failedEventQn : options.readyEventQn,
+      payload: failed
+        ? documentExtractFailedPayloadSchema.parse({
+            documentExtractId: existing.id,
+            fileRefId,
+            error: options.mapError?.(metaError) || metaError || UNKNOWN_EXTRACT_ERROR,
+          })
+        : documentExtractReadyPayloadSchema.parse({ documentExtractId: existing.id, fileRefId }),
+      metadata: { userId: deps.actor.id },
+    },
+    { registry: deps.registry },
+  );
+  return failed ? "appended-failed" : "appended-ready";
+}

package/packages/bundled-features/src/document-ingest-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "appendMissingDocumentExtractEvent and shared ready/failed payload schemas",
+    "detail": "A provider whose job died after creating the extract calls appendMissingDocumentExtractEvent(deps, existing, fileRefId, { readyEventQn, failedEventQn, mapError }) to append the missing terminal event; it returns appended-ready, appended-failed or already-terminal. documentExtractReadyPayloadSchema and documentExtractFailedPayloadSchema are exported so providers register their own event names with the shared payload shape."
+  },
   {
     "version": "0.379.0",
     "type": "fix",

package/packages/bundled-features/src/document-ingest-foundation/events.ts

@@ -47,3 +47,18 @@ export const documentIngestSkippedPayloadSchema = z.object({
   reason: z.enum(["file-too-large", "unsupported-mime-type"]),
 });
 export type DocumentIngestSkippedPayload = z.infer<typeof documentIngestSkippedPayloadSchema>;
+
+// Terminal events of a document-extract stream. The QNs belong to the provider that registers
+// them; the foundation only owns the shared payload shape.
+export const documentExtractReadyPayloadSchema = z.object({
+  documentExtractId: z.string().min(1),
+  fileRefId: z.string().min(1),
+});
+export type DocumentExtractReadyPayload = z.infer<typeof documentExtractReadyPayloadSchema>;
+
+export const documentExtractFailedPayloadSchema = z.object({
+  documentExtractId: z.string().min(1),
+  fileRefId: z.string().min(1),
+  error: z.string().min(1),
+});
+export type DocumentExtractFailedPayload = z.infer<typeof documentExtractFailedPayloadSchema>;

package/packages/bundled-features/src/document-ingest-foundation/index.ts

@@ -1,6 +1,13 @@
 // Public API of the document-ingest-foundation bundled-feature.
 
 export { documentIngestAggregateId } from "./aggregate-id.ts";
+export {
+  type AppendMissingExtractEventDeps,
+  type AppendMissingExtractEventOptions,
+  type AppendMissingExtractEventResult,
+  appendMissingDocumentExtractEvent,
+  type ExistingDocumentExtract,
+} from "./append-missing-extract-event.ts";
 export {
   type DocumentExtractMeta,
   documentExtractEntity,
@@ -14,8 +21,12 @@ export {
   DOCUMENT_INGEST_REQUESTED_EVENT_SHORT,
   DOCUMENT_INGEST_SKIPPED_EVENT_QN,
   DOCUMENT_INGEST_SKIPPED_EVENT_SHORT,
+  type DocumentExtractFailedPayload,
+  type DocumentExtractReadyPayload,
   type DocumentIngestRequestedPayload,
   type DocumentIngestSkippedPayload,
+  documentExtractFailedPayloadSchema,
+  documentExtractReadyPayloadSchema,
   documentIngestRequestedPayloadSchema,
   documentIngestSkippedPayloadSchema,
 } from "./events.ts";

package/packages/bundled-features/src/feature-toggles/feature.ts

@@ -44,6 +44,7 @@ export function createFeatureTogglesFeature(
   options: FeatureTogglesOptions = {},
 ): FeatureDefinition {
   return defineFeature("feature-toggles", (r) => {
+    r.adoptsBundledLists();
     r.describe(
       'Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: "shared"` syncs the snapshot across instances whenever a `toggle-set` event is appended.',
     );

package/packages/bundled-features/src/file-foundation/index.ts

@@ -10,6 +10,7 @@ export {
 export {
   type FileRefContent,
   FileRefTooLargeError,
+  FileStorageUnavailableError,
   fileContextForTenant,
   fileContextFromResolver,
   readFileRefContent,