@cosmicdrift/kumiko-samples 0.388.0 → 0.390.0

package/packages/bundled-features/src/sessions/session-revoked-event.ts

@@ -12,7 +12,7 @@ import * as z from "zod";
 // _SHORT/_QN pair mirrors cap-counter's rolling-incremented event:
 //   _SHORT — r.defineEvent(short, schema) in feature.ts, framework prefixes
 //            it to the QN below.
-//   _QN    — ctx.unsafeAppendEvent({ type }) / raw append()'s `type` field.
+//   _QN    — ctx.events.unsafeAppend({ type }) / raw append()'s `type` field.
 export const SESSION_REVOKED_EVENT_SHORT = "session-revoked" as const;
 export const SESSION_REVOKED_EVENT_QN = "sessions:event:session-revoked" as const;
 

package/packages/bundled-features/src/sessions/web/session-device-cell.tsx

@@ -1,19 +1,17 @@
-// Column renderer for the parsed `device` of a session row, registered via `sessionsClient()`.
+// Column renderer for session devices, registered via `sessionsClient()`. Takes the server-made
+// `deviceLabel` string, or the parsed `device` object for screens that bind that column.
 
 import { type ColumnRendererProps, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import type { ReactNode } from "react";
-import { parsedDeviceSchema } from "./user-agent.ts";
+import { formatDeviceLabel, parsedDeviceSchema } from "./user-agent.ts";
+
+function deviceLabelOf(value: unknown): string | null {
+  if (typeof value === "string") return value === "" ? null : value;
+  const parsed = parsedDeviceSchema.safeParse(value);
+  return parsed.success ? formatDeviceLabel(parsed.data) : null;
+}
 
 export function SessionDeviceCell({ value }: ColumnRendererProps): ReactNode {
   const t = useTranslation();
-  const parsed = parsedDeviceSchema.safeParse(value);
-  const device = parsed.success ? parsed.data : null;
-  if (device === null) return t("sessions.device.unknown");
-  const browser =
-    device.browser === null
-      ? null
-      : device.browserMajor === null
-        ? device.browser
-        : `${device.browser} ${device.browserMajor}`;
-  return [browser, device.os].filter((part) => part !== null).join(" · ");
+  return deviceLabelOf(value) ?? t("sessions.device.unknown");
 }

package/packages/bundled-features/src/sessions/web/user-agent.ts

@@ -56,6 +56,18 @@ const OPERATING_SYSTEM_PATTERNS: readonly {
   { os: "Linux", pattern: /\bLinux\b/ },
 ];
 
+export function formatDeviceLabel(device: ParsedDevice): string | null {
+  if (device === null) return null;
+  const browser =
+    device.browser === null
+      ? null
+      : device.browserMajor === null
+        ? device.browser
+        : `${device.browser} ${device.browserMajor}`;
+  const parts = [browser, device.os].filter((part) => part !== null);
+  return parts.length === 0 ? null : parts.join(" · ");
+}
+
 export function parseUserAgent(userAgent: string | null): ParsedDevice {
   if (userAgent === null || userAgent === "") return null;
   let browser: UserAgentBrowser | null = null;

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

@@ -92,5 +92,20 @@ export {
   type SignupHandoverProvider,
 } from "./signup-handover.ts";
 export { createSingleUseTokenStore, hashSingleUseToken } from "./single-use-token-store.ts";
+export {
+  backfillAggregateStreamTenants,
+  type StreamBackfillCandidate,
+  type StreamBackfillFailure,
+  type StreamBackfillOptions,
+  type StreamBackfillResult,
+  type StreamTenantTarget,
+} from "./stream-tenant-backfill.ts";
+export {
+  createSearchBucketCleanup,
+  type DerivedStateMode,
+  rebuildAndReindex,
+  type StreamBackfillStepFailure,
+  stepFailures,
+} from "./stream-tenant-derived-state.ts";
 export type { SystemQueryFn } from "./system-query.ts";
 export { type BurnResult, burnToken, unburnToken } from "./token-burn-store.ts";

package/packages/bundled-features/src/shared/purge-files-reaching-subject.ts

@@ -112,6 +112,29 @@ function fieldsResolvingToSubject(
   });
 }
 
+// A user owning many records must not load them all at once; the id cursor keeps each page
+// bounded while rows purged in place stay out of the way.
+export const PURGE_CANDIDATE_PAGE_SIZE = 200;
+
+async function* candidateRowsPaged(
+  db: DbRunner,
+  table: FileEntity["table"],
+  where: WhereObject,
+): AsyncGenerator<Record<string, unknown>> {
+  let cursor: unknown;
+  for (;;) {
+    const pageWhere: WhereObject = cursor === undefined ? where : { ...where, id: { gt: cursor } };
+    const page = await selectMany<Record<string, unknown>>(db, table, pageWhere, {
+      orderBy: { col: "id", direction: "asc" },
+      limit: PURGE_CANDIDATE_PAGE_SIZE,
+    });
+    yield* page;
+    // skip: a short page is the last one
+    if (page.length < PURGE_CANDIDATE_PAGE_SIZE) return;
+    cursor = page[page.length - 1]?.["id"];
+  }
+}
+
 const fileRefExecutor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
   entityName: "fileRef",
 });
@@ -165,8 +188,7 @@ export async function purgeFilesReachingSubject(args: {
   for (const fileEntity of fileEntities) {
     const seenRowIds = new Set<string>();
     for (const where of candidateWheres(subject, recordTenantId, fileEntity)) {
-      const rows = await selectMany<Record<string, unknown>>(db, fileEntity.table, where);
-      for (const row of rows) {
+      for await (const row of candidateRowsPaged(db, fileEntity.table, where)) {
         const rowId = String(row["id"]);
         const tenantId = parseTenantId(row["tenantId"]);
         // skip: a row without a tenant cannot own tenant-scoped file refs
@@ -184,7 +206,12 @@ export async function purgeFilesReachingSubject(args: {
         }
         const deleteBytes = await storagePromise;
         const systemUser = createSystemUser(tenantId);
-        const tdb = createTenantDb({ db, tenantId, mode: "system" });
+        const tdb = createTenantDb({
+          db,
+          tenantId,
+          mode: "system",
+          reason: "subject erasure purges file refs in every tenant that holds them",
+        });
 
         const outcome = await purgeRowFileRefs({
           db,
@@ -331,7 +358,12 @@ async function purgePendingFileRef(
   const forgotten = await fileRefExecutor.forget(
     { id: fileRefId },
     createSystemUser(tenantId),
-    createTenantDb({ db, tenantId, mode: "system" }),
+    createTenantDb({
+      db,
+      tenantId,
+      mode: "system",
+      reason: "subject erasure purges file refs in every tenant that holds them",
+    }),
   );
   return forgotten.isSuccess
     ? undefined

package/packages/bundled-features/src/shared/require-for-tenant.ts

@@ -5,14 +5,16 @@ import type {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 
-// ctx.forTenant is absent for r.systemScope() handlers and without a db; a write handler that
+// ctx.tenants.writeTarget is absent for r.systemScope() handlers and without a db; a write handler that
 // needs a cross-tenant target must fail loudly instead of falling back to ctx.db.
 export function requireForTenant(
-  ctx: Pick<HandlerContext, "forTenant">,
+  ctx: Pick<HandlerContext, "tenants">,
   targetTenantId: TenantId,
 ): TenantWriteTarget {
-  if (!ctx.forTenant) {
-    throw new InternalError({ message: "ctx.forTenant is not available in this handler context" });
+  if (!ctx.tenants.writeTarget) {
+    throw new InternalError({
+      message: "ctx.tenants.writeTarget is not available in this handler context",
+    });
   }
-  return ctx.forTenant(targetTenantId);
+  return ctx.tenants.writeTarget(targetTenantId);
 }

package/packages/bundled-features/src/shared/run-in-sub-transaction.ts

@@ -1,11 +1,11 @@
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 
 // Per-unit sub-transaction (one user, one purged row), nesting-aware across both db shapes:
-//   - top-level connection (postgres-js Sql) → `.begin` (BEGIN)
-//   - TransactionSql (inside the dispatcher's outer tx, where every
+//   - top-level connection (Bun.SQL pool) → `.begin` (BEGIN)
+//   - TransactionSQL (inside the dispatcher's outer tx, where every
 //     writeHandler already runs) → `.savepoint` (SAVEPOINT)
-// A TransactionSql has no `.begin`, so the previous unconditional `.begin`
-// threw "is not a function" on every user when invoked through the dispatcher
+// A transaction handle cannot begin another transaction, so the previous unconditional `.begin`
+// threw on every user when invoked through the dispatcher
 // (the cron path) → zero deletions in production, while direct-connection tests
 // stayed green. Selecting the available method makes the sub-tx work in both
 // contexts; on throw the savepoint rolls back just this user (others survive).
@@ -21,7 +21,7 @@ export async function runInSubTransaction<T>(
     savepoint?: (f: (tx: DbRunner) => Promise<T>) => Promise<T>;
   };
   // savepoint-first: empirically (Bun 1.3.14, not re-checked on 1.4.0) the
-  // surfaces are NOT mutually exclusive — a TransactionSql exposes begin AND
+  // surfaces are NOT mutually exclusive — a TransactionSQL exposes begin AND
   // savepoint, only the top-level connection has begin alone. begin-first
   // picked the nested BEGIN inside a tx (the incident class above);
   // savepoint-first hits the savepoint there and falls back to begin top-level.

package/packages/bundled-features/src/shared/stream-tenant-backfill.ts

@@ -0,0 +1,201 @@
+// One-time migration tooling for event streams that live on the wrong tenant.
+//
+// An aggregate type that became tenant-independent (systemStream) or whose
+// stream must follow the tenant in its payload has older streams on whichever
+// tenant happened to write them. Newer writes then version-conflict against
+// the empty target stream, and a raw tenant_id UPDATE trips
+// events_aggregate_version_uq as soon as an aggregate has BOTH a legacy
+// stream and newer events on the target (split stream).
+//
+// This tool merges per aggregate: all events of the aggregate, ordered by
+// global event id, are renumbered 1..n and retenanted to the target - two-phase
+// version writes (negative interim values) dodge the unique index while the
+// per-aggregate transaction is in flight. Snapshots of migrated aggregates
+// are dropped (version numbering changed; the next snapshotting load
+// recreates them); archived-stream markers move with the stream.
+//
+// Idempotent: candidates are only aggregates that still have events outside
+// their target tenant. One failing aggregate does not abort the run: the rest
+// of the estate migrates, failures are reported.
+//
+// After a run, rebuild the affected projections so read-table tenant_id
+// reflects the stream move.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  asRawClient,
+  toPostgresArrayLiteral,
+  transaction,
+  unsafeReadRetrying,
+} from "@cosmicdrift/kumiko-framework/db";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+
+export type StreamTenantTarget =
+  | { readonly kind: "system" }
+  // The tenantId carried by the aggregate's earliest event payload.
+  | { readonly kind: "payload-tenant" };
+
+export type StreamBackfillCandidate = {
+  readonly aggregateId: string;
+  readonly targetTenantId: string;
+  readonly sourceTenantIds: readonly string[];
+};
+
+export type StreamBackfillFailure = { readonly aggregateId: string; readonly error: string };
+
+export type StreamBackfillResult = {
+  readonly aggregatesMigrated: number;
+  readonly eventsMigrated: number;
+  readonly failed: readonly StreamBackfillFailure[];
+};
+
+export type StreamBackfillOptions = {
+  readonly aggregateType: string;
+  readonly target: StreamTenantTarget;
+  // Runs per candidate before its events move; a throw skips the aggregate
+  // and lands in `failed` (search cleanup must not be lost by a move).
+  readonly beforeMove?: (candidate: StreamBackfillCandidate) => Promise<void>;
+  // Restricts the candidate scan to events on these tenants, which lets Postgres use
+  // events_tenant_type_idx instead of grouping every event of the type. Streams on a tenant
+  // outside the list are not found; omit it for the full scan.
+  readonly scanTenantIds?: readonly string[];
+  // Called once when the scan found candidates, before the first move. "skip" ends the run
+  // with nothing moved (this process cannot do the work); a throw propagates to the caller.
+  readonly onFirstCandidate?: () => Promise<"proceed" | "skip">;
+};
+
+type CandidateRow = {
+  aggregate_id: string;
+  target_tenant_id: string | null;
+  source_tenant_ids: string[];
+};
+
+export async function backfillAggregateStreamTenants(
+  db: DbConnection,
+  options: StreamBackfillOptions,
+): Promise<StreamBackfillResult> {
+  const rows = await readCandidateRows(db, options);
+  if (rows.length > 0 && options.onFirstCandidate) {
+    if ((await options.onFirstCandidate()) === "skip") {
+      return { aggregatesMigrated: 0, eventsMigrated: 0, failed: [] };
+    }
+  }
+
+  let aggregatesMigrated = 0;
+  let eventsMigrated = 0;
+  const failed: StreamBackfillFailure[] = [];
+
+  for (const row of rows) {
+    try {
+      if (!row.target_tenant_id) {
+        throw new Error(`earliest event of the aggregate carries no payload.tenantId`);
+      }
+      const candidate: StreamBackfillCandidate = {
+        aggregateId: row.aggregate_id,
+        targetTenantId: row.target_tenant_id,
+        sourceTenantIds: row.source_tenant_ids,
+      };
+      await options.beforeMove?.(candidate);
+      eventsMigrated += await migrateAggregate(db, options.aggregateType, candidate);
+      aggregatesMigrated++;
+    } catch (e) {
+      failed.push({
+        aggregateId: row.aggregate_id,
+        error: e instanceof Error ? e.message : String(e),
+      });
+    }
+  }
+  return { aggregatesMigrated, eventsMigrated, failed };
+}
+
+async function readCandidateRows(
+  db: DbConnection,
+  options: StreamBackfillOptions,
+): Promise<readonly CandidateRow[]> {
+  const targetSql =
+    options.target.kind === "system"
+      ? `$2::text`
+      : `(SELECT e2."payload"->>'tenantId' FROM "kumiko_events" e2
+           WHERE e2."aggregate_type" = $1 AND e2."aggregate_id" = e."aggregate_id"
+           ORDER BY e2."id" ASC LIMIT 1)`;
+  const params: unknown[] = [options.aggregateType];
+  if (options.target.kind === "system") params.push(SYSTEM_TENANT_ID);
+  let scanSql = "";
+  if (options.scanTenantIds) {
+    // Events already on the SYSTEM target are not legacy; leaving them out keeps the scan to
+    // the legacy events only. A payload target differs per aggregate, so nothing is left out.
+    const scanned =
+      options.target.kind === "system"
+        ? options.scanTenantIds.filter((id) => id !== SYSTEM_TENANT_ID)
+        : options.scanTenantIds;
+    params.push(toPostgresArrayLiteral(scanned));
+    scanSql = ` AND e."tenant_id" = ANY($${params.length}::uuid[])`;
+  }
+  // An aggregate whose earliest event has no payload tenant yields a NULL
+  // target and is reported as failed instead of being silently skipped.
+  return unsafeReadRetrying<CandidateRow>(
+    db,
+    `SELECT e."aggregate_id" AS aggregate_id,
+            ${targetSql} AS target_tenant_id,
+            array_agg(DISTINCT e."tenant_id"::text) AS source_tenant_ids
+       FROM "kumiko_events" e
+      WHERE e."aggregate_type" = $1${scanSql}
+      GROUP BY e."aggregate_id"
+     HAVING bool_or(e."tenant_id"::text IS DISTINCT FROM ${targetSql})`,
+    params,
+  );
+}
+
+async function migrateAggregate(
+  db: DbConnection,
+  aggregateType: string,
+  candidate: StreamBackfillCandidate,
+): Promise<number> {
+  const { aggregateId, targetTenantId } = candidate;
+  return transaction(db, async (tx) => {
+    const raw = asRawClient(tx);
+    // Global id order = commit-adjacent replay order; merges a split stream
+    // into one consistent version sequence.
+    const events = await raw.unsafe<{ id: bigint | string }>(
+      `SELECT "id" FROM "kumiko_events"
+        WHERE "aggregate_type" = $1 AND "aggregate_id" = $2::uuid
+        ORDER BY "id" ASC
+        FOR UPDATE`,
+      [aggregateType, aggregateId],
+    );
+
+    // Negative interim versions: real versions are always >= 1, so nothing
+    // can collide with events_aggregate_version_uq mid-migration.
+    for (const [i, ev] of events.entries()) {
+      await raw.unsafe(
+        `UPDATE "kumiko_events" SET "tenant_id" = $1::uuid, "version" = $2 WHERE "id" = $3`,
+        [targetTenantId, -(i + 1), ev.id],
+      );
+    }
+    for (const [i, ev] of events.entries()) {
+      await raw.unsafe(`UPDATE "kumiko_events" SET "version" = $1 WHERE "id" = $2`, [i + 1, ev.id]);
+    }
+
+    // Version numbering changed, so any snapshot of this aggregate is stale.
+    await raw.unsafe(`DELETE FROM "kumiko_snapshots" WHERE "aggregate_id" = $1::uuid`, [
+      aggregateId,
+    ]);
+
+    // Archived markers key on (tenant_id, aggregate_id): move them with the
+    // stream, keeping an existing target marker if both exist.
+    await raw.unsafe(
+      `INSERT INTO "kumiko_archived_streams" ("tenant_id", "aggregate_id", "aggregate_type", "archived_at", "archived_by", "reason")
+        SELECT $1::uuid, "aggregate_id", "aggregate_type", "archived_at", "archived_by", "reason"
+          FROM "kumiko_archived_streams"
+         WHERE "aggregate_id" = $2::uuid AND "tenant_id" <> $1::uuid
+        ON CONFLICT DO NOTHING`,
+      [targetTenantId, aggregateId],
+    );
+    await raw.unsafe(
+      `DELETE FROM "kumiko_archived_streams" WHERE "aggregate_id" = $1::uuid AND "tenant_id" <> $2::uuid`,
+      [aggregateId, targetTenantId],
+    );
+
+    return events.length;
+  });
+}

package/packages/bundled-features/src/shared/stream-tenant-derived-state.ts

@@ -0,0 +1,107 @@
+// Derived state of a stream-tenant backfill: search docs in the buckets the streams
+// left, projection rows and the index on SYSTEM_TENANT_ID. The stream move itself lives
+// in stream-tenant-backfill.ts; this part is repeatable and safe to run without moves.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { type Registry, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { rebuildProjection } from "@cosmicdrift/kumiko-framework/pipeline";
+import { reindexEntity, type SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
+import type { StreamBackfillCandidate, StreamBackfillFailure } from "./stream-tenant-backfill.ts";
+
+export type StreamBackfillStepFailure = StreamBackfillFailure & { readonly step: string };
+
+// "if-moved" skips rebuild and reindex when no stream moved; "always" repairs
+// derived state after a run that moved streams and then crashed.
+export type DerivedStateMode = "if-moved" | "always";
+
+export function createSearchBucketCleanup(
+  searchAdapter: SearchAdapter | undefined,
+  entityType: string,
+): {
+  readonly beforeMove: (candidate: StreamBackfillCandidate) => Promise<void>;
+  readonly cleanedAggregates: () => number;
+} {
+  let cleaned = 0;
+  return {
+    cleanedAggregates: () => cleaned,
+    beforeMove: async (candidate) => {
+      // skip: no adapter means no search docs to clean
+      if (!searchAdapter) return;
+      const oldBuckets = candidate.sourceTenantIds.filter((id) => id !== candidate.targetTenantId);
+      for (const bucket of oldBuckets) {
+        if (searchAdapter.removeBatch) {
+          await searchAdapter.removeBatch(bucket, [
+            { entityType, entityId: candidate.aggregateId },
+          ]);
+        } else {
+          await searchAdapter.remove(bucket, entityType, candidate.aggregateId);
+        }
+      }
+      if (oldBuckets.length > 0) cleaned++;
+    },
+  };
+}
+
+export type DerivedStateResult = {
+  readonly projectionsRebuilt: readonly string[];
+  readonly reindexedRows: number;
+  readonly failures: readonly StreamBackfillStepFailure[];
+};
+
+export async function rebuildAndReindex(deps: {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+  readonly searchAdapter?: SearchAdapter;
+  readonly projections: readonly string[];
+  readonly searchEntity: string;
+}): Promise<DerivedStateResult> {
+  const { db, registry, searchAdapter, projections, searchEntity } = deps;
+  const failures: StreamBackfillStepFailure[] = [];
+  const projectionsRebuilt: string[] = [];
+  for (const projection of projections) {
+    try {
+      await rebuildProjection(projection, { db, registry });
+      projectionsRebuilt.push(projection);
+    } catch (e) {
+      failures.push({ aggregateId: projection, step: "rebuild", error: messageOf(e) });
+    }
+  }
+
+  let reindexedRows = 0;
+  if (searchAdapter && isEntitySearchable(registry, searchEntity)) {
+    try {
+      const reindex = await reindexEntity(
+        db,
+        registry,
+        searchAdapter,
+        searchEntity,
+        SYSTEM_TENANT_ID,
+      );
+      reindexedRows = reindex.indexedRows;
+      for (const f of reindex.failures) {
+        failures.push({ aggregateId: f.entityId, step: "reindex", error: f.reason });
+      }
+    } catch (e) {
+      failures.push({ aggregateId: searchEntity, step: "reindex", error: messageOf(e) });
+    }
+  }
+  return { projectionsRebuilt, reindexedRows, failures };
+}
+
+function isEntitySearchable(registry: Registry, entityName: string): boolean {
+  return (
+    registry.getSearchableFields(entityName).length > 0 ||
+    registry.getSearchPayloadExtensions(entityName).length > 0
+  );
+}
+
+export function stepFailures(
+  step: string,
+  failed: readonly StreamBackfillFailure[],
+): StreamBackfillStepFailure[] {
+  return failed.map((f) => ({ ...f, step }));
+}
+
+function messageOf(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}

package/packages/bundled-features/src/step-dispatcher/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "fix",
+    "title": "Mail steps do not retry permanent rejections or throws",
+    "detail": "MailDispatchResult failures take an optional smtpCode; 5xx is permanent and recorded after the first attempt. A throwing mail runner is not retried, since the message may already be sent. A mail runner that wants a retry after a transport error should return a failure without smtpCode instead of throwing."
+  },
   {
     "version": "0.388.0",
     "type": "fix",

package/packages/bundled-features/src/step-dispatcher/deliver-dispatch-request.ts

@@ -54,9 +54,17 @@ type DeliveryResult =
   | { readonly ok: true; readonly status: number }
   | { readonly ok: false; readonly error: string; readonly retryable: boolean };
 
-// Mail adapter failures carry no status to classify, so every one is retried.
+const SMTP_PERMANENT_REJECTION_MIN = 500;
+const SMTP_PERMANENT_REJECTION_MAX = 599;
+
+// Without an SMTP code the adapter gave nothing to classify, so the failure counts as transient.
 function mailResultAsDelivery(result: MailDispatchResult): DeliveryResult {
-  return result.ok ? result : { ...result, retryable: true };
+  if (result.ok) return result;
+  const isPermanent =
+    result.smtpCode !== undefined &&
+    result.smtpCode >= SMTP_PERMANENT_REJECTION_MIN &&
+    result.smtpCode <= SMTP_PERMANENT_REJECTION_MAX;
+  return { ok: false, error: result.error, retryable: !isPermanent };
 }
 
 export type DeliverDispatchRequestArgs = {
@@ -205,7 +213,13 @@ async function sendDispatch(
       aggregateId: target.aggregateId,
       errorName: err instanceof Error ? err.name : "unknown",
     });
-    return { ok: false, error: DISPATCH_THREW_ERROR, retryable: true };
+    // A mail adapter has no idempotency key: a throw after the provider accepted the message
+    // would send it again, so only the webhook (which carries one) is retried.
+    return {
+      ok: false,
+      error: DISPATCH_THREW_ERROR,
+      retryable: dispatchSpec.stepKind === "webhook.send",
+    };
   }
 }
 

package/packages/bundled-features/src/step-dispatcher/feature.ts

@@ -94,7 +94,7 @@ export function createStepDispatcherFeature(): FeatureDefinition {
               tenantId,
               userId,
               callerFeature: STEP_DISPATCHER_FEATURE,
-              ...(ctx.secrets && { secrets: ctx.secrets }),
+              ...(ctx.services.secrets && { secrets: ctx.services.secrets }),
             }),
         });
       },

package/packages/bundled-features/src/step-dispatcher/mail-runner.ts

@@ -15,7 +15,8 @@ export type MailSpec = z.infer<typeof mailSpecSchema>;
 
 export type MailDispatchResult =
   | { readonly ok: true; readonly status: number }
-  | { readonly ok: false; readonly error: string };
+  // smtpCode is the adapter's SMTP reply code; a 5xx is a permanent rejection and is not retried.
+  | { readonly ok: false; readonly error: string; readonly smtpCode?: number };
 
 let mailRunner: (spec: MailSpec) => Promise<MailDispatchResult> = async () => ({
   ok: false,

package/packages/bundled-features/src/subscription-dodo/plugin-methods.ts

@@ -225,7 +225,7 @@ async function fillPriceCache(
     } else {
       const message =
         outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
-      ctx.log?.warn("subscription-dodo: product lookup failed", { message });
+      ctx.obs.log?.warn("subscription-dodo: product lookup failed", { message });
     }
   }
 }

package/packages/bundled-features/src/subscription-dodo/runtime.ts

@@ -64,11 +64,11 @@ export function createDodoRuntimes(deps: DodoRuntimeDeps): DodoRuntimes {
 
   async function ctxApiKey(ctx: HandlerContext): Promise<string> {
     let key: string | undefined;
-    if (ctx.secrets) {
-      const got = await requireSecretsContext(ctx, SUBSCRIPTION_DODO_FEATURE).get(
-        SYSTEM_TENANT_ID,
-        deps.apiKeyHandle.name,
-      );
+    if (ctx.services.secrets) {
+      const got = await requireSecretsContext(
+        { secrets: ctx.services.secrets, user: ctx.user },
+        SUBSCRIPTION_DODO_FEATURE,
+      ).get(SYSTEM_TENANT_ID, deps.apiKeyHandle.name);
       key = parseStoredSecret(got?.reveal());
     }
     if (!key && deps.fallback.apiKey && deps.fallback.apiKey.length > 0) {
@@ -102,8 +102,8 @@ export function createDodoRuntimes(deps: DodoRuntimeDeps): DodoRuntimes {
         if (live !== true) return false;
         if (deps.fallback.apiKey !== undefined && deps.fallback.apiKey.length > 0) return true;
         // Existence-only probe on every billing-plans render: must stay un-audited.
-        return ctx.secrets
-          ? await ctx.secrets.has(SYSTEM_TENANT_ID, deps.apiKeyHandle.name)
+        return ctx.services.secrets
+          ? await ctx.services.secrets.has(SYSTEM_TENANT_ID, deps.apiKeyHandle.name)
           : false;
       },
     },

package/packages/bundled-features/src/subscription-stripe/plugin-methods.ts

@@ -169,7 +169,9 @@ export function createStripeCheckoutSession(
       if (!options.providerCustomerId || !isUnknownCustomerStripeError(error)) throw error;
       // Stripe account switch (test -> live) or a customer deleted in the dashboard leaves a
       // stored customer id Stripe no longer knows; checkout creates a fresh customer instead.
-      ctx.log?.warn("subscription-stripe: stored customer unknown to Stripe, retrying without it");
+      ctx.obs.log?.warn(
+        "subscription-stripe: stored customer unknown to Stripe, retrying without it",
+      );
       session = await stripe.checkout.sessions.create(sessionParams(undefined));
     }
 
@@ -383,7 +385,7 @@ async function resolvePricesViaCache(
     } else {
       const message =
         outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
-      ctx.log?.warn("subscription-stripe: prices.retrieve failed", { message });
+      ctx.obs.log?.warn("subscription-stripe: prices.retrieve failed", { message });
     }
   }
 }
@@ -402,7 +404,7 @@ export function createStripeRetrievePrices(runtime: StripeCtxRuntime, cache: Str
       const rawInterval = price.recurring?.interval;
       if (rawInterval && mapped.interval === null && !warnedUnknownIntervalPriceIds.has(priceId)) {
         warnedUnknownIntervalPriceIds.add(priceId);
-        ctx.log?.warn("subscription-stripe: price has an unknown recurring interval", {
+        ctx.obs.log?.warn("subscription-stripe: price has an unknown recurring interval", {
           priceId,
           interval: rawInterval,
         });