@cosmicdrift/kumiko-bundled-features 0.365.0 → 0.366.0

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

@@ -14,7 +14,7 @@
 // app owner still wires the supervisor in bin/server.ts:
 //
 //   const supervisor = createInboundMailSupervisor({
-//     providerCtx: { registry: deps.registry, secrets },
+//     providerCtx: { registry: deps.registry, secrets, metricsFor: deps.metricsFor },
 //     db,
 //     dispatchWrite: ({ handlerQn, payload, tenantId }) =>
 //       deps.dispatchSystemWrite({ handlerQn, payload, tenantId: tenantId as TenantId }),
@@ -48,7 +48,7 @@ import { configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/ku
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { InboundMailAccountStatuses, InboundMailFoundationHandlers } from "./constants.js";
-import { MAIL_ACCOUNT_PII_FIELDS, syncCursorTable } from "./entities.js";
+import { MAIL_ACCOUNT_PII_FIELDS, seenMessageTable, syncCursorTable } from "./entities.js";
 import { createOAuthAccessTokenManager, usesFoundationManagedOAuth, } from "./oauth-access-token.js";
 import { mailAccountsProjectionTable } from "./projection.js";
 import { resolveInboundProviderForAccount } from "./provider-factory.js";
@@ -255,6 +255,19 @@ export function createInboundMailSupervisor(deps) {
     // ---------------------------------------------------------------
     // Poll (Reconciliation).
     // ---------------------------------------------------------------
+    function unknownMessageIdsFilterFor(account) {
+        return async (providerMessageIds) => {
+            if (providerMessageIds.length === 0)
+                return new Set();
+            const seen = await selectMany(deps.db, seenMessageTable, {
+                tenantId: account.tenantId,
+                accountId: account.id,
+                providerMessageId: { in: providerMessageIds },
+            }, { fields: ["providerMessageId"] });
+            const seenIds = new Set(seen.map((row) => row.providerMessageId));
+            return new Set(providerMessageIds.filter((id) => !seenIds.has(id)));
+        };
+    }
     async function pollAccount(account, plugin) {
         let cursor = await loadCursor(account.id);
         let budget = maxMessagesPerPoll;
@@ -265,6 +278,7 @@ export function createInboundMailSupervisor(deps) {
                 const result = await plugin.fetch(deps.providerCtx, account, cursor, {
                     backfillWindowDays,
                     maxMessages: budget,
+                    filterUnknownMessageIds: unknownMessageIdsFilterFor(account),
                     ...(accessToken !== undefined && { accessToken }),
                 });
                 await ingestBatch(account, result.messages, JSON.stringify(result.nextCursor));

package/dist/inbound-provider-imap/feature.js

@@ -224,8 +224,8 @@ export const inboundProviderImapFeature = defineFeature(FEATURE_NAME, (r) => {
         category: "notifications",
         recommended: false,
     });
-    r.requires("inbound-mail-foundation");
-    r.requires("secrets");
+    r.requires({ features: ["inbound-mail-foundation"] });
+    r.requires({ features: ["secrets"] });
     r.envSchema(mailAllowedPrivateHostsEnvSchema);
     r.useExtension(INBOUND_MAIL_PROVIDER_EXTENSION, IMAP_PROVIDER_KEY, imapInboundMailPlugin);
 });

package/dist/inbound-provider-inmemory/feature.js

@@ -110,6 +110,6 @@ export const inboundProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) =>
         category: "notifications",
         recommended: false,
     });
-    r.requires("inbound-mail-foundation");
+    r.requires({ features: ["inbound-mail-foundation"] });
     r.useExtension("inboundMailProvider", INMEMORY_PROVIDER_KEY, inMemoryInboundMailPlugin);
 });

package/dist/ledger/feature.js

@@ -28,9 +28,9 @@ function registerLedger(r, access, toggleable) {
     });
     if (toggleable !== undefined)
         r.toggleable(toggleable);
-    r.entity("account", accountEntity);
-    r.entity("transaction", transactionEntity);
-    r.entity("schedule", scheduleEntity);
+    r.entity({ name: "account", ...accountEntity });
+    r.entity({ name: "transaction", ...transactionEntity });
+    r.entity({ name: "schedule", ...scheduleEntity });
     // Chart of accounts — plain CRUD, no custom logic. No delete in v1: removing an
     // account that has postings would orphan them; a posting-aware guard lands with
     // the postings projection (Phase 1).
@@ -73,8 +73,8 @@ function registerLedger(r, access, toggleable) {
         access,
         description: "Changes a recurring booking template's description, accounts, amount, interval or date window; use it when a standing order's terms change, already confirmed periods stay booked as they were.",
     }));
-    r.hook("preSave", "schedule:create", requireScheduleSubjectPair);
-    r.hook("preSave", "schedule:update", requireScheduleSubjectPair);
+    r.hook({ type: "preSave", target: "schedule:create", handler: requireScheduleSubjectPair });
+    r.hook({ type: "preSave", target: "schedule:update", handler: requireScheduleSubjectPair });
     r.writeHandler(createConfirmSchedulePeriodHandler(access));
     r.queryHandler(defineEntityListHandler("schedule", scheduleEntity, {
         access,

package/dist/legal-pages/feature.js

@@ -35,7 +35,7 @@ export function createLegalPagesFeature(opts = {}) {
             category: "content",
             recommended: false,
         });
-        r.requires("template-resolver");
+        r.requires({ features: ["template-resolver"] });
         // Public HTML routes (default: 4 DACH routes, configurable via opts.routes)
         for (const route of routes) {
             r.httpRoute({

package/dist/mail-foundation/feature.js

@@ -52,7 +52,7 @@ export const mailFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
         category: "notifications",
         recommended: false,
     });
-    r.requires("config");
+    r.requires({ features: ["config"] });
     // Plugin extension-point. Provider-features register here. The
     // entityName at registration time becomes the value tenants pick in
     // `provider` config-key (e.g. "smtp", "brevo-api").

package/dist/mail-transport-inmemory/feature.js

@@ -62,11 +62,11 @@ export function clearInbox(tenantId) {
 // =============================================================================
 export const mailTransportInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
     r.describe('Registers an in-process `"inmemory"` provider for `mail-foundation` that buffers sent mails per tenant instead of contacting an SMTP server. Use `getInbox(tenantId)` and `clearInbox(tenantId)` in demo apps and tests; not for production (buffer is process-memory, lost on restart).');
-    // Kein r.requires("config") + kein r.requires("secrets") — der
+    // Kein requires auf "config" oder "secrets" — der
     // In-Memory-Transport hat keine Config (nichts zu konfigurieren) und
     // kein Secret. Der einzige hard-require ist mail-foundation, das den
     // extension-point "mailTransport" definiert.
-    r.requires("mail-foundation");
+    r.requires({ features: ["mail-foundation"] });
     const plugin = {
         build: async (_ctx, tenantId) => {
             // Returnt den per-tenant Buffer. Identitätsstabil zwischen calls

package/dist/mail-transport-smtp/feature.js

@@ -57,9 +57,9 @@ export const mailTransportSmtpFeature = defineFeature(FEATURE_NAME, (r) => {
         category: "notifications",
         recommended: false,
     });
-    r.requires("config");
-    r.requires("secrets");
-    r.requires("mail-foundation");
+    r.requires({ features: ["config"] });
+    r.requires({ features: ["secrets"] });
+    r.requires({ features: ["mail-foundation"] });
     r.envSchema(mailTransportSmtpEnvSchema);
     // Provider-secret. Sensitive: redact-helper for admin-UI display.
     const password = r.secret("smtp.password", {

package/dist/managed-pages/css-gate.js

@@ -15,7 +15,7 @@ import { MANAGED_PAGES_CSS_FEATURE } from "./branding.js";
 export function createManagedPagesCssFeature() {
     return defineFeature(MANAGED_PAGES_CSS_FEATURE, (r) => {
         r.describe('Per-tenant toggle gate for the managed-pages custom-CSS (raw tenant CSS-inject) capability. Handler-less: composing it makes `managed-pages-css` a toggleable feature defaulting OFF, so an operator/tier can grant raw CSS-inject per tenant. managed-pages reads `ctx.hasFeature("managed-pages-css")` in its branding query and emits tenant CSS only when this toggle is on AND the app passed `allowCustomCss: true`. The tenant CSS is allowlist-sanitized + scoped at render regardless; this gate is the commercial/operator control, not the safety boundary.');
-        r.requires("managed-pages");
+        r.requires({ features: ["managed-pages"] });
         r.toggleable({ default: false });
     });
 }

package/dist/managed-pages/feature.js

@@ -86,8 +86,8 @@ export function createManagedPagesFeature(opts) {
             category: "content",
             recommended: false,
         });
-        r.requires("config");
-        r.entity("page", pageEntity);
+        r.requires({ features: ["config"] });
+        r.entity({ name: "page", ...pageEntity });
         // Per-tenant branding config keys (scope: tenant). Write-validated via
         // keyDef.pattern (hex / https) — see branding.ts. read:all so the
         // anonymous render path may resolve them. The raw-CSS key is added only

package/dist/metrics/feature.js

@@ -103,7 +103,7 @@ export function createMetricsFeature(options) {
             recommended: false,
         });
         for (const feature of requiredFeatures(metrics))
-            r.requires(feature);
+            r.requires({ features: [feature] });
         for (const metric of metrics)
             r.queryHandler(createTenantMetricQuery(metric, now));
         r.translations({ keys: METRICS_I18N });
@@ -122,7 +122,7 @@ export function createSystemMetricsFeature(options) {
         });
         r.systemScope();
         for (const feature of requiredFeatures(metrics))
-            r.requires(feature);
+            r.requires({ features: [feature] });
         for (const metric of metrics)
             r.queryHandler(createSystemMetricQuery(metric, now));
         r.translations({ keys: METRICS_I18N });

package/dist/notes-history/feature.js

@@ -27,13 +27,13 @@ function registerNotesHistory(r, access, ownership, parents) {
         recommended: false,
     });
     const entity = createNoteEntryEntity(ownership, parents);
-    r.entity("note-entry", entity);
+    r.entity({ name: "note-entry", ...entity });
     // No write/query handler of its own — populated only as a side effect of
     // add-note (see handlers/add-note.write.ts), looked up by
     // notes-history-user-data's forget cascade. Registering the entity (not
     // just building it inline in the handler) is what makes it visible to the
     // registry-wide GDPR boot guards and to executor.ts's table/projection setup.
-    r.entity("note-mention", noteMentionEntity);
+    r.entity({ name: "note-mention", ...noteMentionEntity });
     r.writeHandler(createAddNoteHandler(access, createNoteEntryExecutor(ownership)));
     r.queryHandler(defineEntityListHandler("note-entry", entity, {
         access,

package/dist/notes-history-user-data/index.js

@@ -13,7 +13,7 @@ export const notesHistoryUserDataFeature = defineFeature("notes-history-user-dat
     // is OPTIONAL: if it's mounted toggleable(default=false), a hard r.requires
     // would throw an "effectively disabled" boot warning even though the
     // note-entry entity exists and the hooks work fine.
-    r.requires("user-data-rights");
+    r.requires({ features: ["user-data-rights"] });
     r.optionalRequires("notes-history");
     r.useExtension(EXT_USER_DATA, "note-entry", {
         export: noteEntryExportHook,

package/dist/personal-access-tokens/feature.js

@@ -52,7 +52,7 @@ export function createPersonalAccessTokensFeature(options) {
         // roles — make both boot-time deps so a mis-wiring fails validateBoot.
         // auth-foundation owns EXT_TOKEN_VERIFIER, which the useExtension below
         // registers against.
-        r.requires("user", "tenant", "auth-foundation");
+        r.requires({ features: ["user", "tenant", "auth-foundation"] });
         // Self-registers as a bearer-auth provider instead of the app wiring a
         // dedicated patResolver callback — the middleware finds it generically
         // via resolveTokenVerifier(), shape-matched by the PAT token prefix.
@@ -83,18 +83,22 @@ export function createPersonalAccessTokensFeature(options) {
         // #497), so a postSave hook on "user" gets a poisoned ctx.db here. The
         // concrete revoker is bound once run{Prod,Dev}App has a real db handle.
         let autoRevokeOnPasswordChange = options.autoRevokeOnPasswordChange;
-        r.hook("postSave", { allOf: "user" }, async (result) => {
-            // skip: nothing bound — same late-bind pattern as sessions/feature.ts
-            if (!autoRevokeOnPasswordChange)
-                return;
-            // skip: brand-new user, no PATs can exist yet
-            if (result.isNew)
-                return;
-            // skip: handler didn't touch any revoke-triggering field
-            if (!PAT_REVOKE_TRIGGERING_FIELDS.some((field) => result.changes[field] !== undefined)) {
-                return;
-            }
-            await autoRevokeOnPasswordChange(String(result.id));
+        r.hook({
+            type: "postSave",
+            target: { allOf: "user" },
+            handler: async (result) => {
+                // skip: nothing bound — same late-bind pattern as sessions/feature.ts
+                if (!autoRevokeOnPasswordChange)
+                    return;
+                // skip: brand-new user, no PATs can exist yet
+                if (result.isNew)
+                    return;
+                // skip: handler didn't touch any revoke-triggering field
+                if (!PAT_REVOKE_TRIGGERING_FIELDS.some((field) => result.changes[field] !== undefined)) {
+                    return;
+                }
+                await autoRevokeOnPasswordChange(String(result.id));
+            },
         });
         const bindAutoRevokeOnPasswordChange = (revoker) => {
             // explicit constructor option wins over the runtime binding

package/dist/readiness/feature.js

@@ -16,8 +16,8 @@ export const readinessFeature = defineFeature("readiness", (r) => {
         category: "operations",
         recommended: false,
     });
-    r.requires("config");
-    r.requires("secrets");
+    r.requires({ features: ["config"] });
+    r.requires({ features: ["secrets"] });
     const queries = {
         status: r.queryHandler(statusQuery),
     };

package/dist/renderer-foundation/feature.js

@@ -17,7 +17,7 @@ export function createRendererFoundationFeature() {
             category: "notifications",
             recommended: false,
         });
-        r.requires("template-resolver");
+        r.requires({ features: ["template-resolver"] });
         r.extendsRegistrar(RENDERER_EXTENSION, {
             onRegister: () => {
                 // Plugin-Konformitäts-Check könnte hier: shape-validation der

package/dist/renderer-pdf/feature.js

@@ -29,7 +29,7 @@ export function createRendererPdfFeature() {
             category: "notifications",
             recommended: false,
         });
-        r.requires("renderer-foundation");
+        r.requires({ features: ["renderer-foundation"] });
         r.useExtension(RENDERER_EXTENSION, "pdf", {
             kinds: ["document-pdf"],
             render: (req) => renderTablePdfRequest(req),

package/dist/secrets/feature.js

@@ -116,7 +116,7 @@ export function createSecretsFeature(opts = {}) {
         // uniqueIndex are not expressible via the field-DSL (jsonb-without-default,
         // now()-default), so the physical table is the DDL truth. Without this the
         // generated migration omitted those columns → prod-500 (publicstatus#116).
-        r.entity("tenant-secret", tenantSecretEntity, { table: tenantSecretsTable });
+        r.entity({ name: "tenant-secret", ...tenantSecretEntity, backingTable: tenantSecretsTable });
         // Read-audit domain-event. Registered here so ops tools + MSPs can
         // discover the type; secrets-context.get parses payloads against
         // `secretReadSchema` at write time because the low-level append() path

package/dist/seo/feature.js

@@ -108,7 +108,7 @@ export function createSeoFeature(opts) {
         // config keys need the config feature's write/read machinery to actually
         // function (same hard dependency managed-pages has) — only legal-pages/
         // managed-pages are genuinely optional (merged only when opted in).
-        r.requires("config");
+        r.requires({ features: ["config"] });
         r.optionalRequires("legal-pages", "managed-pages");
         r.config({ keys: SEO_CONFIG_KEYS });
         r.queryHandler(seoConfigQuery);

package/dist/sessions/feature.js

@@ -59,7 +59,7 @@ export function createSessionsFeature(options) {
         // sessions-without-user wiring fails validateBoot instead of 500ing live.
         // auth-foundation owns EXT_SESSION_STORE, which the useExtension below
         // registers against.
-        r.requires("user", "auth-foundation");
+        r.requires({ features: ["user", "auth-foundation"] });
         // store_user_sessions is a hot-path direct-write store: sessionCreator
         // inserts and the revoke handlers update rows WITHOUT emitting lifecycle
         // events (the row columns ARE the audit trail). Registering it as
@@ -144,21 +144,25 @@ export function createSessionsFeature(options) {
         // regardless.
         const REVOKE_TRIGGERING_FIELDS = ["passwordHash"];
         let autoRevoke = options?.autoRevokeOnPasswordChange;
-        r.hook("postSave", { allOf: "user" }, async (ctx) => {
-            // skip: nothing bound — stateless-JWT deployments without a runtime
-            // that calls bindAutoRevokeOnPasswordChange keep the old behavior.
-            if (!autoRevoke)
-                return;
-            // skip: brand-new user, no sessions can possibly exist yet. The
-            // initial passwordHash on a user:create would trip the second guard
-            // otherwise — every registration would do a mass-revoke roundtrip
-            // for a user who literally has no rows in user_sessions.
-            if (ctx.isNew)
-                return;
-            // skip: handler didn't touch any revoke-triggering field
-            if (!REVOKE_TRIGGERING_FIELDS.some((field) => ctx.changes[field] !== undefined))
-                return;
-            await autoRevoke(String(ctx.id));
+        r.hook({
+            type: "postSave",
+            target: { allOf: "user" },
+            handler: async (ctx) => {
+                // skip: nothing bound — stateless-JWT deployments without a runtime
+                // that calls bindAutoRevokeOnPasswordChange keep the old behavior.
+                if (!autoRevoke)
+                    return;
+                // skip: brand-new user, no sessions can possibly exist yet. The
+                // initial passwordHash on a user:create would trip the second guard
+                // otherwise — every registration would do a mass-revoke roundtrip
+                // for a user who literally has no rows in user_sessions.
+                if (ctx.isNew)
+                    return;
+                // skip: handler didn't touch any revoke-triggering field
+                if (!REVOKE_TRIGGERING_FIELDS.some((field) => ctx.changes[field] !== undefined))
+                    return;
+                await autoRevoke(String(ctx.id));
+            },
         });
         const bindAutoRevokeOnPasswordChange = (revoker) => {
             // explicit constructor option wins over the runtime binding

package/dist/step-dispatcher/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const STEP_DISPATCHER_FEATURE = "step-dispatcher";
+export declare const StepDispatcherJobNames: {
+    readonly deliver: "deliver";
+};
+export declare const StepDispatcherJobs: {
+    readonly deliver: string;
+};
+export declare function deliverJobId(aggregateId: string): string;
+export declare const DELIVER_MAX_PER_TENANT = 2;
+export declare const DELIVER_RETRIES = 3;

package/dist/step-dispatcher/constants.js

@@ -0,0 +1,17 @@
+import { QnTypes, qn } from "@cosmicdrift/kumiko-framework/engine";
+export const STEP_DISPATCHER_FEATURE = "step-dispatcher";
+export const StepDispatcherJobNames = {
+    deliver: "deliver",
+};
+export const StepDispatcherJobs = {
+    deliver: qn(STEP_DISPATCHER_FEATURE, QnTypes.job, StepDispatcherJobNames.deliver),
+};
+// Stable per dispatch stream: BullMQ ignores a second add() with the same id,
+// so an MSP redelivery cannot enqueue a second delivery.
+export function deliverJobId(aggregateId) {
+    return `step-dispatch-${aggregateId}`;
+}
+// Per-tenant cap on simultaneous deliveries, so one tenant's slow receivers
+// cannot occupy every worker slot.
+export const DELIVER_MAX_PER_TENANT = 2;
+export const DELIVER_RETRIES = 3;

package/dist/step-dispatcher/deliver-dispatch-request.d.ts

@@ -0,0 +1,14 @@
+import type { MultiStreamApplyContext } from "@cosmicdrift/kumiko-framework/pipeline";
+import { type TenantId } from "@cosmicdrift/kumiko-types/identifiers";
+export declare function isDispatchOutcome(e: {
+    readonly type: string;
+}): boolean;
+export declare function eraseDispatchKey(aggregateId: string): Promise<void>;
+export type DeliverDispatchRequestArgs = {
+    readonly aggregateId: string;
+    readonly tenantId: TenantId;
+    readonly attempt: number;
+    readonly finalAttempt: boolean;
+    readonly applyContextFor: (userId: string) => MultiStreamApplyContext;
+};
+export declare function deliverDispatchRequest(args: DeliverDispatchRequestArgs): Promise<void>;

package/dist/step-dispatcher/deliver-dispatch-request.js

@@ -0,0 +1,163 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import { configuredPiiSubjectKms } from "@cosmicdrift/kumiko-framework/crypto";
+import { STEP_DISPATCH_AGGREGATE_TYPE, STEP_DISPATCH_FAILED_TYPE, STEP_DISPATCH_REQUESTED_TYPE, STEP_DISPATCHED_TYPE, } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
+import { redactEmailAddresses } from "../shared/index.js";
+import { buildDispatchSpec, dispatchRequestedPayloadSchema, rawStepKindOf, readPayloadFields, } from "./dispatch-payload.js";
+import { performMailDispatch } from "./mail-runner.js";
+import { performWebhookDispatch } from "./webhook-runner.js";
+const log = createFallbackLogger("step-dispatcher");
+// zod issue messages can echo the invalid value (e.g. a rejected url) back
+// into the tenant-visible dispatch-failed event — keep this generic.
+const INVALID_DISPATCH_PAYLOAD_ERROR = "invalid dispatch payload";
+const PAYLOAD_UNREADABLE_ERROR = "dispatch payload is not readable";
+// Adapter errors (e.g. SMTP 550) usually echo the recipient address; the
+// dispatch-failed text outlives the payload erase, so only this is persisted.
+const MAIL_DELIVERY_FAILED_ERROR = "mail delivery failed";
+const PAYLOAD_ERASED_ERROR = "dispatch payload erased before an outcome was recorded";
+// Thrown messages land in BullMQ's failedReason and the run log, so this never
+// carries the receiver's error text or the target url.
+const DELIVERY_RETRY_ERROR = "step delivery failed, retrying";
+const DISPATCH_THREW_ERROR = "delivery attempt threw unexpectedly";
+const FINAL_ATTEMPT_ABORTED_ERROR = "delivery aborted on the final attempt";
+const FINAL_ATTEMPT_UNRECORDED_ERROR = "step delivery failed and its outcome could not be recorded";
+export function isDispatchOutcome(e) {
+    return e.type === STEP_DISPATCHED_TYPE || e.type === STEP_DISPATCH_FAILED_TYPE;
+}
+export async function eraseDispatchKey(aggregateId) {
+    await configuredPiiSubjectKms()?.eraseKey({ kind: "record", entity: STEP_DISPATCH_AGGREGATE_TYPE, id: aggregateId }, {
+        requestId: requestContext.get()?.requestId ?? "step-dispatcher",
+        eraseReason: "step-dispatch-outcome-recorded",
+    });
+}
+// Mail adapter failures carry no status to classify, so every one is retried.
+function mailResultAsDelivery(result) {
+    return result.ok ? result : { ...result, retryable: true };
+}
+// Outcome events are plaintext and generic; the request payload's per-dispatch
+// key is erased right after, so the PII dies with the dispatch instead of
+// living in the event log. The outcome is appended before the erase on
+// purpose: if the erase throws, the outcome survives and a redelivery only
+// repeats the erase. A crash between the send and the outcome append still
+// re-sends under the same Idempotency-Key — the one remaining double-send case.
+// A transient failure before the final attempt throws without an outcome or
+// erase: the key must survive until the outcome is final.
+export async function deliverDispatchRequest(args) {
+    const { aggregateId, finalAttempt } = args;
+    const stream = await args.applyContextFor(SYSTEM_USER_ID).loadAggregate(aggregateId);
+    if (stream.some(isDispatchOutcome)) {
+        await eraseDispatchKey(aggregateId);
+        // skip: redelivery after an outcome was recorded — only the erase is repeated
+        return;
+    }
+    const requested = stream.find((e) => e.type === STEP_DISPATCH_REQUESTED_TYPE);
+    if (!requested) {
+        // The key ref carries no tenant, so a job triggered with a foreign or
+        // unknown aggregateId must not erase anything or append to that stream.
+        log.warn("step dispatch request not found, nothing delivered", { aggregateId });
+        return;
+    }
+    const ctx = args.applyContextFor(requested.metadata.userId || SYSTEM_USER_ID);
+    const recorder = createOutcomeRecorder(ctx, aggregateId, args.attempt);
+    try {
+        await deliverRequested(args, requested, ctx, recorder);
+    }
+    catch (err) {
+        if (!finalAttempt)
+            throw err;
+        await abortOnFinalAttempt(err, ctx, recorder, aggregateId, requested.payload);
+    }
+}
+function createOutcomeRecorder(ctx, aggregateId, attempt) {
+    const record = async (type, payload) => {
+        await ctx.unsafeAppendEvent({
+            aggregateId,
+            aggregateType: STEP_DISPATCH_AGGREGATE_TYPE,
+            type,
+            payload,
+        });
+        await eraseDispatchKey(aggregateId);
+    };
+    return {
+        record,
+        recordFailure: (stepKind, error) => record(STEP_DISPATCH_FAILED_TYPE, { stepKind, error, attempt }),
+    };
+}
+async function deliverRequested(args, requested, ctx, recorder) {
+    const { aggregateId, tenantId, attempt, finalAttempt } = args;
+    const { record, recordFailure } = recorder;
+    const parsed = dispatchRequestedPayloadSchema.safeParse(requested.payload);
+    if (!parsed.success) {
+        return recordFailure(rawStepKindOf(requested.payload), INVALID_DISPATCH_PAYLOAD_ERROR);
+    }
+    const payload = parsed.data;
+    const read = await readPayloadFields(payload);
+    if (read.kind === "unreadable")
+        return recordFailure(payload.stepKind, PAYLOAD_UNREADABLE_ERROR);
+    if (read.kind === "erased")
+        return recordFailure(payload.stepKind, PAYLOAD_ERASED_ERROR);
+    const dispatchSpec = buildDispatchSpec(payload, read.fields);
+    if (!dispatchSpec)
+        return recordFailure(payload.stepKind, INVALID_DISPATCH_PAYLOAD_ERROR);
+    const result = await sendDispatch(dispatchSpec, {
+        aggregateId,
+        tenantId,
+        userId: requested.metadata.userId || SYSTEM_USER_ID,
+        secrets: ctx.secrets,
+    });
+    if (result.ok) {
+        return record(STEP_DISPATCHED_TYPE, { stepKind: payload.stepKind, status: result.status });
+    }
+    const loggedReason = payload.stepKind === "mail.send" ? redactEmailAddresses(result.error) : result.error;
+    if (result.retryable && !finalAttempt) {
+        log.warn("step delivery failed, will retry", { aggregateId, attempt, reason: loggedReason });
+        throw new Error(DELIVERY_RETRY_ERROR);
+    }
+    if (payload.stepKind === "mail.send") {
+        log.warn("mail dispatch failed", { aggregateId, reason: loggedReason });
+        return recordFailure(payload.stepKind, MAIL_DELIVERY_FAILED_ERROR);
+    }
+    return recordFailure(payload.stepKind, result.error);
+}
+async function sendDispatch(dispatchSpec, target) {
+    try {
+        return dispatchSpec.stepKind === "webhook.send"
+            ? await performWebhookDispatch(dispatchSpec.spec, {
+                tenantId: target.tenantId,
+                userId: target.userId,
+                secrets: target.secrets,
+                idempotencyKey: target.aggregateId,
+            })
+            : await performMailDispatch(dispatchSpec.spec).then(mailResultAsDelivery);
+    }
+    catch (err) {
+        // err.message can echo the url or an address; only the class name is logged.
+        log.warn("step delivery threw", {
+            aggregateId: target.aggregateId,
+            errorName: err instanceof Error ? err.name : "unknown",
+        });
+        return { ok: false, error: DISPATCH_THREW_ERROR, retryable: true };
+    }
+}
+async function abortOnFinalAttempt(err, ctx, recorder, aggregateId, requestedPayload) {
+    // err.message can echo the url or an address; only the class name is logged.
+    log.warn("step delivery aborted on the final attempt", {
+        aggregateId,
+        errorName: err instanceof Error ? err.name : "unknown",
+    });
+    try {
+        // An outcome may already be appended when only the erase threw: repeat the
+        // erase, never a second outcome.
+        const current = await ctx.loadAggregate(aggregateId);
+        if (current.some(isDispatchOutcome)) {
+            await eraseDispatchKey(aggregateId);
+        }
+        else {
+            await recorder.recordFailure(rawStepKindOf(requestedPayload), FINAL_ATTEMPT_ABORTED_ERROR);
+        }
+    }
+    catch {
+        throw new Error(FINAL_ATTEMPT_UNRECORDED_ERROR);
+    }
+}