@cosmicdrift/kumiko-samples 0.388.0 → 0.389.0

package/packages/bundled-features/src/auth-email-password/web/reset-password-screen.tsx

@@ -13,6 +13,7 @@ import { type FormEvent, type ReactNode, useState } from "react";
 import { resetPassword } from "./auth-client.ts";
 import { passwordPairIssue } from "./auth-form-logic.ts";
 import { AuthCard, useUrlToken } from "./auth-form-primitives.tsx";
+import { buildLoginRedirectUrl, readReturnToFromWindow } from "./auth-redirect.ts";
 
 export type ResetPasswordScreenProps = {
   readonly title?: string;
@@ -37,6 +38,7 @@ export function ResetPasswordScreen({
   const [submitting, setSubmitting] = useState(false);
   const [done, setDone] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [afterResetHref, setAfterResetHref] = useState(loginHref);
 
   const doSubmit = async (): Promise<void> => {
     setError(null);
@@ -53,6 +55,10 @@ export function ResetPasswordScreen({
     const res = await resetPassword(token, newPassword);
     setSubmitting(false);
     if (res.ok) {
+      const returnTo = readReturnToFromWindow();
+      if (returnTo !== null) {
+        setAfterResetHref(buildLoginRedirectUrl(loginHref, returnTo, window.location.origin));
+      }
       setDone(true);
       return;
     }
@@ -97,7 +103,7 @@ export function ResetPasswordScreen({
             <p className="font-medium text-foreground">{t("auth.resetPassword.successTitle")}</p>
             <p className="mt-1">{t("auth.resetPassword.successBody")}</p>
           </Banner>
-          <Link href={loginHref} variant="button">
+          <Link href={afterResetHref} variant="button">
             {t("auth.resetPassword.goToLogin")}
           </Link>
         </>

package/packages/bundled-features/src/auth-email-password/web/return-path.ts

@@ -0,0 +1,35 @@
+// Shared by the server (mail link) and the web pages (landing page), so it is plain string logic:
+// no DOM, no window, no `new URL` (React Native's URL getters throw).
+
+export const RETURN_TO_QUERY_PARAM = "returnTo";
+export const MAX_RETURN_PATH_LENGTH = 2048;
+
+const DOT_SEGMENTS = new Set([".", "..", ".%2e", "%2e.", "%2e%2e", "%2e"]);
+
+function hasForbiddenCharacter(candidate: string): boolean {
+  for (let i = 0; i < candidate.length; i++) {
+    const code = candidate.charCodeAt(i);
+    if (code <= 0x20 || code === 0x7f || (code >= 0x80 && code <= 0x9f)) return true;
+    if (code === 0x5c) return true;
+  }
+  return false;
+}
+
+// A dot segment is resolved by URL normalization, so "/.//evil" would become "//evil".
+function hasDotSegment(candidate: string): boolean {
+  const pathEnd = candidate.search(/[?#]/);
+  const path = pathEnd === -1 ? candidate : candidate.slice(0, pathEnd);
+  return path.split("/").some((segment) => DOT_SEGMENTS.has(segment.toLowerCase()));
+}
+
+export function isSafeReturnPath(candidate: unknown): candidate is string {
+  if (typeof candidate !== "string") return false;
+  if (candidate.length < 1 || candidate.length > MAX_RETURN_PATH_LENGTH) return false;
+  if (!candidate.startsWith("/") || candidate[1] === "/") return false;
+  return !hasForbiddenCharacter(candidate) && !hasDotSegment(candidate);
+}
+
+export function readReturnToFromSearch(search: string): string | null {
+  const candidate = new URLSearchParams(search).get(RETURN_TO_QUERY_PARAM);
+  return isSafeReturnPath(candidate) ? candidate : null;
+}

package/packages/bundled-features/src/auth-email-password/web/session.tsx

@@ -14,6 +14,7 @@ import {
   useSessionEndedSignal,
 } from "@cosmicdrift/kumiko-renderer";
 import { readCsrfToken } from "@cosmicdrift/kumiko-renderer/live";
+import { clearRememberedListState } from "@cosmicdrift/kumiko-renderer/web";
 import {
   createContext,
   type ReactNode,
@@ -216,6 +217,8 @@ export function SessionProvider({
 
   const logout = useCallback<SessionApi["logout"]>(async () => {
     await logoutApi();
+    // The reload below would hide the identity change from the list-state boot.
+    clearRememberedListState();
     if (postLogoutUrl !== undefined && typeof window !== "undefined") {
       // State stays untouched: flipping to unauthenticated would let an AuthGate
       // with loginUrl race this navigation to its own redirect.
@@ -251,6 +254,7 @@ export function SessionProvider({
   const userEmail = profile?.email;
   const userDisplayName = profile?.displayName;
   const userTimeZone = profile?.effectiveTimeZone;
+  const activeTenantId = state.activeTenantId ?? undefined;
   const currentUser = useMemo<CurrentUser | undefined>(
     () =>
       userId === undefined || userEmail === undefined || userDisplayName === undefined
@@ -260,8 +264,9 @@ export function SessionProvider({
             email: userEmail,
             displayName: userDisplayName,
             ...(userTimeZone !== undefined && { timeZone: userTimeZone }),
+            ...(activeTenantId !== undefined && { tenantId: activeTenantId }),
           },
-    [userId, userEmail, userDisplayName, userTimeZone],
+    [userId, userEmail, userDisplayName, userTimeZone, activeTenantId],
   );
   return (
     <SessionContext.Provider value={api}>

package/packages/bundled-features/src/auth-email-password/web/signup-complete-screen.tsx

@@ -21,7 +21,7 @@ import { type FormEvent, type ReactNode, useState } from "react";
 import { confirmSignup, type SignupConfirmSuccess } from "./auth-client.ts";
 import { passwordPairIssue, resolvePostAuthHref } from "./auth-form-logic.ts";
 import { AuthCard, useUrlToken } from "./auth-form-primitives.tsx";
-import { buildLoginRedirectUrl } from "./auth-redirect.ts";
+import { buildLoginRedirectUrl, readReturnToFromWindow } from "./auth-redirect.ts";
 
 export type SignupCompleteScreenProps = {
   readonly title?: string;
@@ -74,15 +74,23 @@ export function SignupCompleteScreen({
     const res = await confirmSignup(token, password);
     setSubmitting(false);
     if (res.ok) {
+      // The page the signup started from beats the server's landing path.
+      const returnTo = readReturnToFromWindow();
       if (res.data.kind === "mfa-pending") {
         setMfaPending(true);
+        const next = returnTo ?? res.data.landingPath;
         setContinueHref(
-          res.data.landingPath === undefined
+          next === undefined
             ? loginHref
-            : buildLoginRedirectUrl(loginHref, res.data.landingPath, window.location.origin),
+            : buildLoginRedirectUrl(loginHref, next, window.location.origin),
         );
         return;
       }
+      // A claimed handover keeps its app-defined target.
+      if (returnTo !== null && res.data.handover === undefined) {
+        setContinueHref(returnTo);
+        return;
+      }
       // Cookies are already set (auto-login). Show a confirmation with an
       // explicit continue button instead of navigating away silently —
       // the user otherwise gets no signal that activation worked.

package/packages/bundled-features/src/auth-email-password/web/signup-screen.tsx

@@ -16,6 +16,8 @@ import { type FormEvent, type ReactNode, useState } from "react";
 import { requestSignup } from "./auth-client.ts";
 import { retryAfterMinutes } from "./auth-form-logic.ts";
 import { AuthCard } from "./auth-form-primitives.tsx";
+import { readReturnToFromWindow } from "./auth-redirect.ts";
+import { isSafeReturnPath } from "./return-path.ts";
 
 export type SignupScreenProps = {
   readonly title?: string;
@@ -23,12 +25,20 @@ export type SignupScreenProps = {
   /** href for the "Already have an account?" link. App-specific; defaults to
    *  "/login". */
   readonly loginHref?: string;
+  /** Page the activation mail should lead to after signup; defaults to the `returnTo` query
+   *  parameter of this page. Unsafe values are dropped. */
+  readonly returnTo?: string;
 };
 
+function resolveReturnTo(prop: string | undefined): string | undefined {
+  return (isSafeReturnPath(prop) ? prop : readReturnToFromWindow()) ?? undefined;
+}
+
 export function SignupScreen({
   title,
   subtitle,
   loginHref = "/login",
+  returnTo,
 }: SignupScreenProps): ReactNode {
   const t = useTranslation();
   const { Form, Field, Input, Button, Banner, Link } = usePrimitives();
@@ -41,7 +51,7 @@ export function SignupScreen({
     setSubmitting(true);
     setError(null);
     try {
-      const res = await requestSignup(email);
+      const res = await requestSignup(email, undefined, resolveReturnTo(returnTo));
       if (res.ok) {
         setDone(true);
       } else if (res.error.reason === "rate_limited") {
@@ -73,7 +83,7 @@ export function SignupScreen({
     setSubmitting(true);
     setError(null);
     try {
-      await requestSignup(email);
+      await requestSignup(email, undefined, resolveReturnTo(returnTo));
     } finally {
       setSubmitting(false);
     }

package/packages/bundled-features/src/auth-mfa/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "requiredPolicy \"systemAdmins\"",
+    "detail": "The new auth-mfa:config:required value systemAdmins (between optional and admins) forces MFA enrollment only for users whose merged global and tenant roles contain SystemAdmin. TenantAdmins and other roles log in as before; enrolled users are always challenged regardless of policy. No locale labels are involved, the option list has none."
+  },
   {
     "version": "0.388.0",
     "type": "improvement",

package/packages/bundled-features/src/auth-mfa/config.ts

@@ -2,19 +2,15 @@
 // they haven't opted in themselves? Default "optional" means the feature
 // is fully opt-in (existing tenants/users unaffected — no migration step).
 //
-// ponytail: "admins"/"all" HARD-BLOCK login for an unenrolled user (see
-// mfa-status-checker.ts's setupRequired branch) — there is no in-band way
-// for a blocked user to complete enrollment yet (that flow ships in PR3's
-// UI). Flipping this away from "optional" before PR3 locks out every
-// unenrolled matching user with no recovery path. Fine for a tenant that
-// enrolls its admins out-of-band first; a footgun otherwise.
+// Every non-optional policy blocks login for an unenrolled matching user until
+// they finish the pre-auth enrollment step (mfa-status-checker.ts setupRequired).
 import {
   access,
   type ConfigKeyHandle,
   createTenantConfig,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-export const MFA_REQUIRED_POLICIES = ["optional", "admins", "all"] as const;
+export const MFA_REQUIRED_POLICIES = ["optional", "systemAdmins", "admins", "all"] as const;
 export type MfaRequiredPolicy = (typeof MFA_REQUIRED_POLICIES)[number];
 
 export const mfaRequiredConfigHandle: ConfigKeyHandle<"select"> = {

package/packages/bundled-features/src/auth-mfa/mfa-status-checker.ts

@@ -1,3 +1,4 @@
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
@@ -31,8 +32,8 @@ export type MfaStatusChecker = (
   ctx: HandlerContext,
   userId: string,
   tenantId: TenantId,
-  // Merged global+tenant roles — needed to evaluate the "admins" policy
-  // value. Must be the MERGED set (see login.write.ts caller): a
+  // Merged global+tenant roles — needed to evaluate the "admins" and "systemAdmins"
+  // policies. Must be the MERGED set (see login.write.ts caller): a
   // SystemAdmin whose admin-ness lives only in global roles would be
   // missed if the caller passed tenant-membership roles alone.
   roles: readonly string[],
@@ -84,9 +85,11 @@ export function createMfaStatusChecker(opts: {
         opts.challengeTokenSecret,
       ).token;
     if (policy === "all") return { setupRequired: true, preauthSetupToken: buildSetupToken() };
-    // policy === "admins"
-    const isAdmin = roles.some((role) => access.admin.includes(role));
-    return isAdmin
+    const isEnforced =
+      policy === "systemAdmins"
+        ? roles.includes(ROLES.SystemAdmin)
+        : roles.some((role) => access.admin.includes(role));
+    return isEnforced
       ? { setupRequired: true, preauthSetupToken: buildSetupToken() }
       : { required: false };
   };

package/packages/bundled-features/src/cap-counter/cap-reservation.ts

@@ -350,6 +350,21 @@ function bookCalendarDelta(
   );
 }
 
+// Asked after a missed or lost claim. A released tombstone committed since the first read does not
+// count: the caller's own tombstone insert then conflicts with it, and the retry claims that row.
+async function hasSettledTombstone(
+  txDb: TenantDb,
+  user: SessionUser,
+  id: string,
+): Promise<boolean> {
+  const settled = await txDb.fetchOne<CapReservationRow>(capReservationsTable, {
+    id,
+    tenantId: user.tenantId,
+    settledAt: { ne: null },
+  });
+  return settled !== undefined;
+}
+
 async function settleInTransaction(
   txDb: TenantDb,
   user: SessionUser,
@@ -386,12 +401,10 @@ async function settleInTransaction(
     );
     return booked;
   }
-  // The claim lost to a concurrent settle or release: a tombstone means the amount is booked.
-  if (await txDb.fetchOne<CapReservationRow>(capReservationsTable, ownRow)) {
-    return NOTHING_TO_RELEASE;
-  }
+  if (await hasSettledTombstone(txDb, user, id)) return NOTHING_TO_RELEASE;
   // Row swept or released: its amount was given back, so the full actual amount is booked and a
-  // tombstone makes a repeated settle a no-op. A parallel settle inserting first fails this insert.
+  // tombstone makes a repeated settle a no-op. A parallel settle or consume inserting first fails
+  // this insert.
   // Booking first: a lost counter race returns a result instead of throwing, so the transaction
   // commits and a tombstone written before it would turn the retry into a no-op.
   const booked = await bookCalendarDelta(txDb, user, options, options.actualAmount);
@@ -497,7 +510,7 @@ async function consumeClaimedRow(
 }
 
 // Row already expired away: the units are booked directly and a released tombstone remembers them
-// so a later settle subtracts them. A parallel consume inserting first fails this insert.
+// so a later settle subtracts them. A parallel consume or settle inserting first fails this insert.
 async function consumeWithoutRow(
   txDb: TenantDb,
   user: SessionUser,
@@ -542,7 +555,7 @@ async function consumeInTransaction(
   }
   const claimed = open && (await claimReservationRow(txDb, user, open));
   if (claimed) return consumeClaimedRow(txDb, user, claimed, options);
-  if (await txDb.fetchOne<CapReservationRow>(capReservationsTable, ownRow)) {
+  if (await hasSettledTombstone(txDb, user, id)) {
     throw new CapReservationSettledError(options.capName);
   }
   return consumeWithoutRow(txDb, user, id, options);

package/packages/bundled-features/src/cap-counter/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Settle and consume racing on a swept reservation book their units",
+    "detail": "After the sweep deleted a reservation's row, a consume could commit its released tombstone between the two reads of a parallel settle or consume. That call took the released tombstone for a settled one, so settle reported success without booking its amount and a second consume was rejected with cap_reservation_settled. Only a settled tombstone counts as settled now; a released one runs into the insert conflict and the retry books against it."
+  },
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Settle after a sweep survives a lost counter race",
+    "detail": "The amount is booked first and the tombstone written afterwards, so a version conflict on the counter retries the whole settle instead of leaving a tombstone that turns the retry into a no-op and drops the usage from the cap."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

package/packages/bundled-features/src/cap-counter/feature.ts

@@ -71,6 +71,7 @@ export function createCapCounterFeature() {
   return defineFeature(
     CAP_COUNTER_FEATURE,
     (r) => {
+      r.adoptsBundledLists();
       r.describe(
         "Tracks per-tenant usage against configurable limits using two complementary storage models: calendar-period counters (one projection row per tenant/capName/period, reset implicitly by period rollover) and rolling-window counters (append-only event stream, no projection). Use `enforceCap` / `enforceRollingCap` (or the `withCapEnforcement` / `withRollingCapEnforcement` handler wrappers) in your write-handlers to check limits with soft-warn and hard-block tolerances; call `enforceCapAndMaybeNotify` when you also want to trigger a delivery notification on soft-threshold hits.",
       );

package/packages/bundled-features/src/cap-overview/feature.ts

@@ -61,6 +61,7 @@ export function createCapOverviewFeature(opts: CreateCapOverviewOptions): Featur
   }
 
   return defineFeature(CAP_OVERVIEW_FEATURE, (r) => {
+    r.adoptsBundledLists();
     r.describe(
       "Read-only visibility into per-tenant tier assignment and cap usage. SystemAdmin gets a platform-wide tenant list with usage bars; tenant admins (or the roles in `usageVisibleTo`) get their own tenant's usage as dashboard cards. Reads tier-engine, billing-foundation, and tenant data plus app-owned usage tables via caller-supplied CapSpec callbacks — never writes.",
     );

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "config:write:set passes readCascade to validators",
+    "detail": "The set handler binds readCascade to the config resolver, the tenant-scoped db and the secrets reader, so validators see the same cascade as the value queries."
+  },
   {
     "version": "0.388.0",
     "type": "improvement",

package/packages/bundled-features/src/config/handlers/set.write.ts

@@ -18,7 +18,7 @@ import {
   writeFailure,
 } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { requireConfigEncryption, requireSystemDb } from "../feature.ts";
+import { requireConfigEncryption, requireConfigResolver, requireSystemDb } from "../feature.ts";
 import { MASKED } from "../read-redaction.ts";
 import { configValueEntity, configValuesTable } from "../table.ts";
 import {
@@ -106,13 +106,30 @@ export const setWrite = defineWriteHandler({
     if (patternError) return writeFailure(patternError);
 
     if (keyDef.validate) {
+      const validateDb = scopeTenantDbToTenant(db, tenantId);
       try {
         await keyDef.validate(event.payload.value, {
           key: event.payload.key,
           scope,
           tenantId,
           userId,
-          db: scopeTenantDbToTenant(db, tenantId),
+          db: validateDb,
+          readCascade: (qualifiedKey) => {
+            const cascadeKeyDef = ctx.registry.getConfigKey(qualifiedKey);
+            if (!cascadeKeyDef) {
+              throw new InternalError({
+                message: `[config:write:set] readCascade: unknown config key "${qualifiedKey}"`,
+              });
+            }
+            return requireConfigResolver(ctx, "config:write:set").getCascade(
+              qualifiedKey,
+              cascadeKeyDef,
+              tenantId,
+              event.user.id,
+              validateDb,
+              ctx.secrets,
+            );
+          },
         });
       } catch (error) {
         if (isKumikoError(error)) return writeFailure(error);

package/packages/bundled-features/src/crypto-shredding/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "Tests pin the erasure write purpose in forget-subject and the forget cleanup",
+    "detail": "A pre-KMS user whose key was already erased still ends deleted, loses its tokens and gets the erased sentinel in the update event."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "The subject file purge reads candidate rows in pages",
+    "detail": "A user owning many records no longer loads them all into memory at once; every page is purged, not only the first."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

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

@@ -562,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,16 @@
 [
+  {
+    "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",

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/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/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>;