@cosmicdrift/kumiko-bundled-features 0.388.0 → 0.390.0

package/dist/auth-mfa/handlers/enable-start.write.js

@@ -53,7 +53,7 @@ export function createEnableStartHandler(opts) {
             if (!accountLabel) {
                 // The declarative secretMint screen has no client component left to
                 // read the session email off — derive the otpauth label server-side.
-                accountLabel = readableAccountLabel(await ctx.queryAs(event.user, UserQueries.me, {}));
+                accountLabel = readableAccountLabel(await ctx.dispatch.queryAs(event.user, UserQueries.me, {}));
             }
             const secret = generateTotpSecret();
             const recoveryCodes = generateRecoveryCodes();

package/dist/auth-mfa/handlers/reencrypt.job.js

@@ -47,12 +47,12 @@ export async function mfaReencryptJob(rawPayload, ctx, db) {
     // hoisted function declarations below capture this — pin the narrowed
     // type explicitly so TS keeps it inside the closures.
     const cipher = maybeCipher;
-    if (!ctx.masterKeyProvider) {
+    if (!ctx.services.masterKeyProvider) {
         throw new InternalError({
-            message: "[auth-mfa:reencrypt] ctx.masterKeyProvider missing — wire it via extraContext.masterKeyProvider at boot.",
+            message: "[auth-mfa:reencrypt] ctx.services.masterKeyProvider missing — wire it via extraContext.masterKeyProvider at boot.",
         });
     }
-    const provider = ctx.masterKeyProvider;
+    const provider = ctx.services.masterKeyProvider;
     // Undefined = per-subject crypto-shredding isn't configured for this app —
     // both fields are then plain envelope strings, no PII layer to peel.
     const piiKms = configuredPiiSubjectKms();
@@ -65,7 +65,12 @@ export async function mfaReencryptJob(rawPayload, ctx, db) {
     function tdbFor(tenantId) {
         let existing = tdbCache.get(tenantId);
         if (!existing) {
-            existing = createTenantDb({ db, tenantId, mode: "system" });
+            existing = createTenantDb({
+                db,
+                tenantId,
+                mode: "system",
+                reason: "MFA key re-encryption job rewrites enrollments of every tenant",
+            });
             tdbCache.set(tenantId, existing);
         }
         return existing;
@@ -101,7 +106,7 @@ export async function mfaReencryptJob(rawPayload, ctx, db) {
         const totpClass = classifyStoredEnvelope(envelopeValues.totpSecret, targetVersion);
         const recoveryClass = classifyStoredEnvelope(envelopeValues.recoveryCodes, targetVersion);
         if (totpClass === "unrecognized" || recoveryClass === "unrecognized") {
-            ctx.log?.warn?.(`[auth-mfa:reencrypt] row ${row.id} has a field that is not a current-cipher envelope, not re-encryptable`);
+            ctx.obs.log?.warn?.(`[auth-mfa:reencrypt] row ${row.id} has a field that is not a current-cipher envelope, not re-encryptable`);
             return "failed";
         }
         if (totpClass === "current" && recoveryClass === "current") {
@@ -128,7 +133,7 @@ export async function mfaReencryptJob(rawPayload, ctx, db) {
         if (!result.isSuccess) {
             if (result.error.code === "version_conflict")
                 return "skipped";
-            ctx.log?.warn?.(`[auth-mfa:reencrypt] executor rejected row ${row.id}`, {
+            ctx.obs.log?.warn?.(`[auth-mfa:reencrypt] executor rejected row ${row.id}`, {
                 code: result.error.code,
             });
             return "failed";
@@ -140,9 +145,9 @@ export async function mfaReencryptJob(rawPayload, ctx, db) {
         migrateRow,
         maxFailures,
         deadlineAt: deadline,
-        signal: ctx.signal,
+        signal: ctx.lifecycle.signal,
         onRowError: (row, err) => {
-            ctx.log?.warn?.(`[auth-mfa:reencrypt] failed to re-encrypt row ${row.id}`, { err });
+            ctx.obs.log?.warn?.(`[auth-mfa:reencrypt] failed to re-encrypt row ${row.id}`, { err });
         },
     });
     const result = {
@@ -152,5 +157,5 @@ export async function mfaReencryptJob(rawPayload, ctx, db) {
         batchesProcessed: outcome.batchesProcessed,
         stoppedReason: outcome.stoppedReason,
     };
-    ctx.log?.info?.(`[auth-mfa:reencrypt] complete: ${JSON.stringify(result)}`);
+    ctx.obs.log?.info?.(`[auth-mfa:reencrypt] complete: ${JSON.stringify(result)}`);
 }

package/dist/auth-mfa/handlers/regenerate-recovery.write.js

@@ -37,16 +37,16 @@ export function createRegenerateRecoveryHandler(opts) {
             // afterward.
             //
             // Fail closed, matching verify.write.ts/enable-confirm-preauth.write.ts:
-            // without ctx.redis, verifyMfaFactor's TOTP-replay burn is skipped,
+            // without ctx.services.redis, verifyMfaFactor's TOTP-replay burn is skipped,
             // letting an observed code be replayed within the ±1-step window to
             // regenerate (and thus invalidate) recovery codes — a session-authed
             // route, so pre-unwiring JWTs stay a valid attack path.
-            if (!ctx.redis) {
+            if (!ctx.services.redis) {
                 return writeFailure(new InternalError({
-                    message: "regenerate-recovery (mfa) requires ctx.redis for TOTP replay protection",
+                    message: "regenerate-recovery (mfa) requires ctx.services.redis for TOTP replay protection",
                 }));
             }
-            const replay = { redis: ctx.redis, userId: event.user.id };
+            const replay = { redis: ctx.services.redis, userId: event.user.id };
             const verify = await verifyMfaFactor(row, event.payload.code, replay);
             if (!verify.ok)
                 return invalidTotpCode();

package/dist/auth-mfa/handlers/verify.write.js

@@ -29,8 +29,8 @@ export function createMfaVerifyHandler(opts) {
         rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
         escapeHatch: {
             grants: ["systemIdentity", "unsafeRaw"],
-            reason: "Pre-auth MFA step has no session yet — re-derives it via ctx.queryAs(SYSTEM, " +
-                "user:findForAuth) and ctx.resolveActiveMembership for the user the challenge token names. " +
+            reason: "Pre-auth MFA step has no session yet — re-derives it via ctx.dispatch.queryAs(SYSTEM, " +
+                "user:findForAuth) and ctx.auth.resolveActiveMembership for the user the challenge token names. " +
                 "Also reads the MFA enrollment of the tenant named in the signed login/setup token, not the " +
                 "guest dispatch tenant.",
         },
@@ -46,19 +46,19 @@ export function createMfaVerifyHandler(opts) {
             // this route sits behind a challenge token from a successful login,
             // but its own secret is still just a short TOTP/recovery code —
             // silently skipping the brute-force cap and single-use burn when
-            // ctx.redis is absent would let a stolen challenge token be guessed
+            // ctx.services.redis is absent would let a stolen challenge token be guessed
             // against unboundedly, and let a recovery code be replayed via a
             // reissued challenge (mfa-verify-attempts.ts's counter is deliberately
             // NOT reset by reissuance, precisely to survive this).
-            if (!ctx.redis) {
+            if (!ctx.services.redis) {
                 return writeFailure(new InternalError({
-                    message: "verify (mfa) requires ctx.redis for the brute-force cap and single-use burn",
+                    message: "verify (mfa) requires ctx.services.redis for the brute-force cap and single-use burn",
                 }));
             }
             // Per-account brute-force cap — survives challenge-token reissuance
             // on purpose (see mfa-verify-attempts.ts header). Checked BEFORE the
             // TOTP/recovery verify so a locked account can't be guessed against.
-            const state = await getMfaVerifyLockoutState(ctx.redis, userId);
+            const state = await getMfaVerifyLockoutState(ctx.services.redis, userId);
             if (state?.lockedUntil !== null && state?.lockedUntil !== undefined) {
                 const now = Date.now();
                 if (state.lockedUntil > now) {
@@ -69,7 +69,12 @@ export function createMfaVerifyHandler(opts) {
             // "system" mode: this handler runs with a guest identity whose own
             // tenantId is meaningless here — the challenge token is the source
             // of truth for which tenant's row to read.
-            const scopedDb = createTenantDb({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
+            const scopedDb = createTenantDb({
+                db: ctx.db.unsafeRaw(),
+                tenantId,
+                mode: "system",
+                reason: "MFA challenge has no session, the tenant comes from the verified challenge token",
+            });
             const scopedUser = { id: userId, tenantId, roles: ["User"] };
             const row = await findUserMfaRow(scopedDb, scopedUser);
             // MFA got disabled between login and verify (race, or a stale
@@ -77,10 +82,10 @@ export function createMfaVerifyHandler(opts) {
             // bad code, no detail leak about account state.
             if (!row)
                 return invalidChallengeToken();
-            const replay = { redis: ctx.redis, userId };
+            const replay = { redis: ctx.services.redis, userId };
             const verify = await verifyMfaFactor(row, event.payload.code, replay);
             if (!verify.ok) {
-                await recordFailedMfaVerifyAttempt(ctx.redis, userId, maxAttempts, lockoutMinutes);
+                await recordFailedMfaVerifyAttempt(ctx.services.redis, userId, maxAttempts, lockoutMinutes);
                 return invalidTotpCode();
             }
             // Burn the challenge token only after a successful code check — a
@@ -91,7 +96,7 @@ export function createMfaVerifyHandler(opts) {
             // is reached, so this burn only needs to guard a DIFFERENT code
             // (recovery, or a still-valid-but-not-yet-burned TOTP step) reused
             // against the same challenge token.
-            const burnResult = await burnToken(ctx.redis, "mfa-challenge", userId, verified.expiresAtMs);
+            const burnResult = await burnToken(ctx.services.redis, "mfa-challenge", userId, verified.expiresAtMs);
             if (burnResult === "already-used")
                 return invalidChallengeToken();
             // Recovery-code use consumes the code — persist the reduced hash-list
@@ -106,12 +111,12 @@ export function createMfaVerifyHandler(opts) {
                 if (!updateResult.isSuccess)
                     return updateResult;
             }
-            await clearMfaVerifyAttempts(ctx.redis, userId);
+            await clearMfaVerifyAttempts(ctx.services.redis, userId);
             // Re-derive the full session the way login.write.ts would have, for
             // the SAME tenant the challenge token already committed to (no
             // "pick a tenant" step here — that already happened at login time).
             const systemUser = createSystemUser(tenantId, ["SystemAdmin"]);
-            const userRow = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+            const userRow = (await ctx.dispatch.queryAs(systemUser, UserQueries.findForAuth, {
                 id: userId,
             })); // @cast-boundary engine-payload
             // Re-check status + membership the way login.write.ts does after its
@@ -130,7 +135,7 @@ export function createMfaVerifyHandler(opts) {
             const globalRoles = parseRoles(userRow?.roles ?? null);
             // Membership revoked or principal blocked between login and verify —
             // mirror login.write.ts's refusal instead of falling back to globalRoles only.
-            const active = await ctx.resolveActiveMembership(userId, tenantId);
+            const active = await ctx.auth.resolveActiveMembership(userId, tenantId);
             if (active.kind === "rejected")
                 return invalidChallengeToken();
             // buildSessionRoles calls stripForbiddenMembershipRoles to strip reserved
@@ -144,7 +149,7 @@ export function createMfaVerifyHandler(opts) {
                 ...sessionTimezoneField(userRow?.timezone),
                 ...sessionLocaleField(userRow?.locale),
             };
-            const claims = await ctx.resolveAuthClaims(baseSession);
+            const claims = await ctx.auth.resolveClaims(baseSession);
             const session = Object.keys(claims).length > 0 ? { ...baseSession, claims } : baseSession;
             return { isSuccess: true, data: { kind: "mfa-verify-success", session } };
         },

package/dist/auth-mfa/mfa-code-verifier.js

@@ -14,15 +14,20 @@ export function createMfaCodeVerifier() {
         declareEscapeHatch({
             reason: "reads the MFA enrollment of the user being re-authenticated on the caller's handler context; the calling handler declares its own escapeHatch",
         });
-        const scopedDb = createTenantDb({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
+        const scopedDb = createTenantDb({
+            db: ctx.db.unsafeRaw(),
+            tenantId,
+            mode: "system",
+            reason: "re-authentication reads the MFA enrollment of the user's own tenant, not the handler's dispatch tenant",
+        });
         const row = await findUserMfaRow(scopedDb, { id: userId, tenantId, roles: [] });
         if (!row)
             return { enrolled: false, ok: false };
-        // Fail closed without ctx.redis, matching disable.write.ts/verify.write.ts —
+        // Fail closed without ctx.services.redis, matching disable.write.ts/verify.write.ts —
         // skipping the TOTP-replay burn would let an observed code be replayed.
-        if (!code || !ctx.redis)
+        if (!code || !ctx.services.redis)
             return { enrolled: true, ok: false };
-        const verify = await verifyMfaFactor(row, code, { redis: ctx.redis, userId });
+        const verify = await verifyMfaFactor(row, code, { redis: ctx.services.redis, userId });
         return { enrolled: true, ok: verify.ok && verify.method === "totp" };
     };
 }

package/dist/auth-mfa/mfa-status-checker.js

@@ -1,3 +1,4 @@
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { access, declareEscapeHatch, } from "@cosmicdrift/kumiko-framework/engine";
 import { mfaRequiredConfigHandle, mfaRequiredConfigKey } from "./config.js";
@@ -10,7 +11,12 @@ export function createMfaStatusChecker(opts) {
         declareEscapeHatch({
             reason: "reads the MFA enrollment of the tenant named in the signed login/setup token, not the guest dispatch tenant, on the caller's handler context; the calling handler declares its own escapeHatch",
         });
-        const scopedDb = createTenantDb({ db: ctx.db.unsafeRaw(), tenantId, mode: "system" });
+        const scopedDb = createTenantDb({
+            db: ctx.db.unsafeRaw(),
+            tenantId,
+            mode: "system",
+            reason: "login/setup token names the tenant to check, the guest dispatch tenant is meaningless",
+        });
         const scopedUser = { id: userId, tenantId, roles: ["User"] };
         const row = await findUserMfaRow(scopedDb, scopedUser);
         if (row) {
@@ -21,20 +27,21 @@ export function createMfaStatusChecker(opts) {
             return { required: true, challengeToken: token };
         }
         // ctx.config is bound to the CALLING user's tenant (the anonymous
-        // identity's tenant for login) — wrong tenant here. ctx.configResolver takes tenantId
+        // identity's tenant for login) — wrong tenant here. ctx.services.configResolver takes tenantId
         // explicitly, which is what a pre-session check against the LOGGING-IN
         // user's tenant needs.
         // @cast-boundary engine-payload — "select" config values are validated
         // against the declared `options` at write-time by the config feature.
-        const policy = ((await ctx.configResolver?.get(mfaRequiredConfigHandle.name, mfaRequiredConfigKey(opts.requiredPolicy), tenantId, userId, scopedDb)) ?? "optional");
+        const policy = ((await ctx.services.configResolver?.get(mfaRequiredConfigHandle.name, mfaRequiredConfigKey(opts.requiredPolicy), tenantId, userId, scopedDb)) ?? "optional");
         if (policy === "optional")
             return { required: false };
         const buildSetupToken = () => signMfaPreauthSetupToken({ userId, tenantId }, MFA_PREAUTH_SETUP_TOKEN_TTL_MINUTES, 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/dist/auth-mfa/verify-factor.js

@@ -13,7 +13,7 @@ import { STEP_SECONDS, verifyTotp } from "./totp.js";
 // must not verify again within its ±1-step window — otherwise a code an
 // attacker observed once, via phishing proxy or shoulder-surfing, stays
 // usable for ~90s of parallel logins). Omitted where a caller has no
-// ctx.redis available; the code-verify itself still works, just without
+// ctx.services.redis available; the code-verify itself still works, just without
 // replay protection for that call.
 export async function verifyMfaFactor(row, code, replay) {
     const secret = base32Decode(row.totpSecret);

package/dist/billing-foundation/billing-info-query.js

@@ -39,8 +39,8 @@ export function createBillingInfoQueryConfig(deps) {
             const billingLive = ctx.config
                 ? (await ctx.config(STRIPE_BILLING_LIVE_CONFIG_QN)) === true
                 : false;
-            const apiKeySet = ctx.secrets
-                ? await ctx.secrets.has(SYSTEM_TENANT_ID, STRIPE_API_KEY_CONFIG_QN)
+            const apiKeySet = ctx.services.secrets
+                ? await ctx.services.secrets.has(SYSTEM_TENANT_ID, STRIPE_API_KEY_CONFIG_QN)
                 : false;
             const sub = await ctx.db.fetchOne(subscriptionsProjectionTable, { id: subscriptionAggregateId(ctx.user.tenantId) });
             return {

package/dist/billing-foundation/consumer-protection/consent-gate.js

@@ -112,7 +112,7 @@ export async function recordConsent(ctx, prepared, details) {
     };
     const tenantId = ctx.user.tenantId;
     const isSubscription = prepared.mode === "subscription";
-    await ctx.unsafeAppendEvent({
+    await ctx.events.unsafeAppend({
         aggregateId: isSubscription ? subscriptionAggregateId(tenantId) : paymentAggregateId(tenantId),
         aggregateType: isSubscription ? SUBSCRIPTION_AGGREGATE_TYPE : PAYMENT_AGGREGATE_TYPE,
         type: CHECKOUT_CONSENT_RECORDED_EVENT_QN,

package/dist/billing-foundation/consumer-protection/issue-confirmation.js

@@ -64,7 +64,7 @@ export function createIssueContractConfirmationHandler(options, consumerProtecti
                     message: `billing-foundation: ${payload.sourceAggregateId} is not the subscription or payment stream of tenant ${tenantId}`,
                 });
             }
-            const stream = await ctx.fetchForWriting({
+            const stream = await ctx.events.fetchForWriting({
                 aggregateId: payload.sourceAggregateId,
                 aggregateType: isSubscription ? SUBSCRIPTION_AGGREGATE_TYPE : PAYMENT_AGGREGATE_TYPE,
             });
@@ -81,7 +81,7 @@ export function createIssueContractConfirmationHandler(options, consumerProtecti
                 }
             }
             if (!consentEvent || !consent) {
-                ctx.log?.warn(`[billing-foundation:issue-contract-confirmation] no recorded consent ${payload.consentId} on the stream; no mail sent`);
+                ctx.obs.log?.warn(`[billing-foundation:issue-contract-confirmation] no recorded consent ${payload.consentId} on the stream; no mail sent`);
                 return {
                     isSuccess: true,
                     data: {
@@ -104,14 +104,14 @@ export function createIssueContractConfirmationHandler(options, consumerProtecti
             }
             // Everything that can fail runs before the append, so a failed run
             // leaves no marker behind and the job retry starts clean.
-            const recipient = recipientRowSchema.safeParse(await ctx.queryAs(createSystemUser(tenantId), UserQueries.findForAuth, {
+            const recipient = recipientRowSchema.safeParse(await ctx.dispatch.queryAs(createSystemUser(tenantId), UserQueries.findForAuth, {
                 id: consent.actorUserId,
             }));
             const recipientEmail = recipient.success && recipient.data.isDeleted !== true
                 ? await decryptStoredUserEmail(recipient.data.email, "billing-foundation:issue-contract-confirmation")
                 : null;
             if (!recipient.success || recipientEmail === null) {
-                ctx.log?.warn(`[billing-foundation:issue-contract-confirmation] recipient of consent ${payload.consentId} not found; no mail sent`);
+                ctx.obs.log?.warn(`[billing-foundation:issue-contract-confirmation] recipient of consent ${payload.consentId} not found; no mail sent`);
                 return {
                     isSuccess: true,
                     data: {
@@ -128,7 +128,7 @@ export function createIssueContractConfirmationHandler(options, consumerProtecti
                 locale,
             });
             if (terms.version !== consent.termsTemplateVersion) {
-                ctx.log?.warn(`[billing-foundation:issue-contract-confirmation] terms text block changed since consent ${payload.consentId} (version ${consent.termsTemplateVersion} -> ${terms.version}); the mail carries the current text`);
+                ctx.obs.log?.warn(`[billing-foundation:issue-contract-confirmation] terms text block changed since consent ${payload.consentId} (version ${consent.termsTemplateVersion} -> ${terms.version}); the mail carries the current text`);
             }
             const i18n = createI18n(ctx.registry, { defaultLocale: "en" });
             const tierLabel = consent.tier !== null && options.catalog

package/dist/billing-foundation/consumer-protection/register-consent.js

@@ -49,7 +49,7 @@ export function registerConsumerProtection(r, options, consumerProtection) {
             // user), never from payload data.
             const tenantId = ctx.systemUser.tenantId;
             const currentPeriodEndIso = payload["currentPeriodEndIso"];
-            const result = await ctx.write(SubscriptionFoundationHandlers.issueContractConfirmation, {
+            const result = await ctx.dispatch.write(SubscriptionFoundationHandlers.issueContractConfirmation, {
                 consentId,
                 sourceAggregateId: isSubscriptionEvent
                     ? subscriptionAggregateId(tenantId)

package/dist/billing-foundation/consumer-protection/register-termination.js

@@ -37,7 +37,7 @@ export function registerContractTermination(r, options, consumerProtection) {
         // skip: trigger event carries no usable declaration
         if (!declared.success)
             return;
-        const result = await ctx.write(SubscriptionFoundationHandlers.recordContractTermination, {
+        const result = await ctx.dispatch.write(SubscriptionFoundationHandlers.recordContractTermination, {
             requestId: declared.data.requestId,
             declarationType: declared.data.declarationType,
             terminationKind: declared.data.terminationKind,

package/dist/billing-foundation/consumer-protection/termination-open-cancels.d.ts

@@ -0,0 +1,4 @@
+export declare function hasOtherOpenProviderCancel(events: readonly {
+    type: string;
+    payload: unknown;
+}[], requestId: string): boolean;

package/dist/billing-foundation/consumer-protection/termination-open-cancels.js

@@ -0,0 +1,14 @@
+import { CONTRACT_TERMINATION_REQUESTED_EVENT_QN, contractTerminationRequestedPayloadSchema, } from "../events.js";
+import { hasRevocation } from "./termination-record.js";
+// A revoked declaration must not resume a subscription another declaration still cancels at the provider.
+export function hasOtherOpenProviderCancel(events, requestId) {
+    return events.some((e) => {
+        if (e.type !== CONTRACT_TERMINATION_REQUESTED_EVENT_QN)
+            return false;
+        const recorded = contractTerminationRequestedPayloadSchema.safeParse(e.payload).data;
+        return (recorded !== undefined &&
+            recorded.requestId !== requestId &&
+            recorded.providerCancel !== "none" &&
+            !hasRevocation(events, recorded.requestId));
+    });
+}

package/dist/billing-foundation/consumer-protection/termination-provider-lock.d.ts

@@ -0,0 +1,2 @@
+export declare const TERMINATION_PROVIDER_LOCK_NAMESPACE = 1651798124;
+export declare const TERMINATION_PROVIDER_LOCK_KEY = "subscription";

package/dist/billing-foundation/consumer-protection/termination-provider-lock.js

@@ -0,0 +1,3 @@
+// pg_advisory_xact_lock namespace (int4): 'btpl' as ASCII, disjoint from the other fixed advisory-lock keys.
+export const TERMINATION_PROVIDER_LOCK_NAMESPACE = 0x6274706c;
+export const TERMINATION_PROVIDER_LOCK_KEY = "subscription";

package/dist/billing-foundation/consumer-protection/termination-receipt-limit.js

@@ -14,22 +14,22 @@ function receiptBucketKey(ctx, email) {
  *  recorded, a missing receipt is the lesser harm. */
 export async function mayMailReceipt(ctx, email) {
     // skip: no rate limiter wired, nothing to count against
-    if (!ctx.rateLimit)
+    if (!ctx.services.rateLimit)
         return "allowed";
     try {
         const bucketKey = receiptBucketKey(ctx, email);
         if (bucketKey === undefined) {
-            ctx.log?.warn("[billing-foundation:termination] no rate-limit digest available, receipt mail withheld");
+            ctx.obs.log?.warn("[billing-foundation:termination] no rate-limit digest available, receipt mail withheld");
             return "unavailable";
         }
-        const decision = await ctx.rateLimit.check(bucketKey, {
+        const decision = await ctx.services.rateLimit.check(bucketKey, {
             limit: RECEIPT_MAILS_PER_RECIPIENT,
             windowSeconds: RECEIPT_WINDOW_SECONDS,
         });
         return decision.allowed ? "allowed" : "limited";
     }
     catch (error) {
-        ctx.log?.warn(`[billing-foundation:termination] receipt rate limiter failed: ${error instanceof Error ? error.message : String(error)}`);
+        ctx.obs.log?.warn(`[billing-foundation:termination] receipt rate limiter failed: ${error instanceof Error ? error.message : String(error)}`);
         return "unavailable";
     }
 }

package/dist/billing-foundation/consumer-protection/termination-record.js

@@ -12,6 +12,7 @@ import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
 import { isTerminalSubscriptionStatus, SubscriptionCancelTimings } from "../web/constants.js";
 import { CONSENT_LOCALES, FALLBACK_CONSENT_LOCALE, } from "../web/consumer-protection/consent-locale.js";
 import { notifyOperator } from "./termination-notify.js";
+import { TERMINATION_PROVIDER_LOCK_KEY, TERMINATION_PROVIDER_LOCK_NAMESPACE, } from "./termination-provider-lock.js";
 import { isWithinWithdrawalPeriod } from "./withdrawal-period.js";
 const REQUESTED_CANCEL_TIMINGS = [
     SubscriptionCancelTimings.periodEnd,
@@ -85,7 +86,7 @@ async function cancelAtProvider(ctx, tenantId, when, receivedAtIso) {
         });
     }
     catch (error) {
-        ctx.log?.warn(`[billing-foundation:record-contract-termination] provider cancel failed for tenant ${tenantId}: ${error instanceof Error ? error.message : String(error)}`);
+        ctx.obs.log?.warn(`[billing-foundation:record-contract-termination] provider cancel failed for tenant ${tenantId}: ${error instanceof Error ? error.message : String(error)}`);
         return { providerCancel: "none", effectiveAtIso: null, noticeReason: "provider_error" };
     }
     return {
@@ -105,7 +106,7 @@ export function createDeclareContractTerminationHandler() {
         handler: async (event, ctx) => {
             // @cast-boundary engine-payload — dispatcher-zod-validated payload
             const payload = event.payload;
-            const stream = await ctx.fetchForWriting({
+            const stream = await ctx.events.fetchForWriting({
                 aggregateId: subscriptionAggregateId(event.user.tenantId),
                 aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
             });
@@ -127,30 +128,6 @@ function revokedRecordResult(receivedAtIso) {
         },
     };
 }
-// A revocation that landed during the provider cancel found nothing to take back yet.
-async function takeBackLateRevokedCancel(ctx, consumerProtection, args) {
-    const { payload, tenantId, receivedAtIso, providerCancel } = args;
-    // skip: nothing was cancelled at the provider, nothing to resume
-    if (providerCancel !== "period-end")
-        return;
-    const reasons = await resumeAtProvider(ctx, await getSubscriptionForTenant(ctx, tenantId));
-    // skip: resumed cleanly, the revocation notice already tells the operator
-    if (reasons.length === 0)
-        return;
-    await notifyOperator(ctx, consumerProtection, {
-        locale: payload.locale ?? FALLBACK_CONSENT_LOCALE,
-        requestId: payload.requestId,
-        receivedAtIso,
-        channel: "public",
-        declaration: {
-            declarationType: payload.declarationType,
-            terminationKind: payload.terminationKind,
-        },
-        reasons,
-        tenantId,
-        providerCancel,
-    });
-}
 export function createRecordContractTerminationHandler(options, consumerProtection) {
     return {
         name: "record-contract-termination",
@@ -161,13 +138,15 @@ export function createRecordContractTerminationHandler(options, consumerProtecti
             // @cast-boundary engine-payload — dispatcher-zod-validated payload
             const payload = event.payload;
             const tenantId = event.user.tenantId;
+            // The provider cancel/resume and the stream append must not interleave across declarations of the same subscription.
+            await ctx.db.advisoryXactLock(TERMINATION_PROVIDER_LOCK_NAMESPACE, TERMINATION_PROVIDER_LOCK_KEY);
             if (payload.channel === "public" && payload.when === SubscriptionCancelTimings.immediately) {
                 throw new UnprocessableError("immediate_cancel_not_allowed", {
                     message: "billing-foundation: the public channel never cancels at the provider immediately",
                 });
             }
             const receivedAtIso = payload.receivedAtIso ?? options.now().toString();
-            const stream = await ctx.fetchForWriting({
+            const stream = await ctx.events.fetchForWriting({
                 aggregateId: subscriptionAggregateId(tenantId),
                 aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
             });
@@ -193,28 +172,12 @@ export function createRecordContractTerminationHandler(options, consumerProtecti
                 effectiveAtIso,
                 providerCancel,
             };
-            // Re-fetch after the external call: a webhook appended meanwhile would
-            // otherwise fail the append on a stale expectedVersion although the
-            // provider already cancelled.
-            const streamAfterProviderCall = await ctx.fetchForWriting({
+            // Re-fetch after the external call: webhooks append to this stream without the lock, so a
+            // stale expectedVersion would fail the append although the provider already cancelled.
+            const streamAfterProviderCall = await ctx.events.fetchForWriting({
                 aggregateId: subscriptionAggregateId(tenantId),
                 aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
             });
-            // A concurrent run with the same requestId may have recorded while we were
-            // at the provider; a second append would duplicate the event and the notice.
-            const recordedMeanwhile = findRecordedTermination(streamAfterProviderCall.events, payload.requestId);
-            if (recordedMeanwhile)
-                return recordedTerminationResult(recordedMeanwhile);
-            // A revocation that landed during the provider call found no cancel to take back.
-            if (hasRevocation(streamAfterProviderCall.events, payload.requestId)) {
-                await takeBackLateRevokedCancel(ctx, consumerProtection, {
-                    payload,
-                    tenantId,
-                    receivedAtIso,
-                    providerCancel,
-                });
-                return revokedRecordResult(receivedAtIso);
-            }
             await streamAfterProviderCall.appendOne({
                 type: CONTRACT_TERMINATION_REQUESTED_EVENT_QN,
                 payload: recorded,
@@ -285,7 +248,7 @@ export async function resumeAtProvider(ctx, subscription) {
         });
     }
     catch (error) {
-        ctx.log?.warn(`[billing-foundation:revoke-contract-termination] provider resume failed: ${error instanceof Error ? error.message : String(error)}`);
+        ctx.obs.log?.warn(`[billing-foundation:revoke-contract-termination] provider resume failed: ${error instanceof Error ? error.message : String(error)}`);
         return ["revocation_resume_failed"];
     }
     return [];
@@ -307,7 +270,7 @@ export function createRecordUnmatchedContractTerminationHandler() {
         handler: async (event, ctx) => {
             // @cast-boundary engine-payload — dispatcher-zod-validated payload
             const payload = event.payload;
-            const stream = await ctx.fetchForWriting({
+            const stream = await ctx.events.fetchForWriting({
                 aggregateId: terminationUnmatchedAggregateId(payload.requestId),
                 aggregateType: CONTRACT_TERMINATION_UNMATCHED_AGGREGATE_TYPE,
             });

package/dist/billing-foundation/consumer-protection/termination-request.js

@@ -95,10 +95,12 @@ async function findTerminableTenantIds(ctx, options, requestTenantId, email) {
     declareEscapeHatch({
         reason: "anonymous declarant has no session — finds the contract by email via user:find-for-auth and tenant:memberships as a system user; the calling handler declares its own escapeHatch",
     });
-    const user = authUserRowSchema.safeParse(await ctx.queryAs(createSystemUser(requestTenantId), UserQueries.findForAuth, { email }));
+    const user = authUserRowSchema.safeParse(await ctx.dispatch.queryAs(createSystemUser(requestTenantId), UserQueries.findForAuth, {
+        email,
+    }));
     if (!user.success || user.data.isDeleted === true)
         return [];
-    const memberships = membershipRowsSchema.safeParse(await ctx.queryAs(createSystemUser(requestTenantId), TenantQueries.memberships, {
+    const memberships = membershipRowsSchema.safeParse(await ctx.dispatch.queryAs(createSystemUser(requestTenantId), TenantQueries.memberships, {
         userId: user.data.id,
     }));
     if (!memberships.success)
@@ -111,7 +113,7 @@ async function findTerminableTenantIds(ctx, options, requestTenantId, email) {
     ];
     const terminable = [];
     for (const tenantId of adminTenantIds) {
-        const probe = terminableResultSchema.safeParse(await ctx.queryAs(createSystemUser(tenantId), SubscriptionFoundationQueries.terminableSubscription, {}));
+        const probe = terminableResultSchema.safeParse(await ctx.dispatch.queryAs(createSystemUser(tenantId), SubscriptionFoundationQueries.terminableSubscription, {}));
         if (probe.success && probe.data.terminable)
             terminable.push(tenantId);
     }
@@ -126,7 +128,7 @@ export function createRequestContractTerminationHandler(options, consumerProtect
         rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 600 },
         ...(consumerProtection.terminationScope === "platform" && { tenantlessAnonymous: true }),
         escapeHatch: {
-            reason: "Anonymous declarant has no session — finds the contract by email via ctx.queryAs(system, user:find-for-auth) and tenant:memberships; the tenant written to comes only from those lookups.",
+            reason: "Anonymous declarant has no session — finds the contract by email via ctx.dispatch.queryAs(system, user:find-for-auth) and tenant:memberships; the tenant written to comes only from those lookups.",
         },
         handler: async (event, ctx) => {
             // @cast-boundary engine-payload — dispatcher-zod-validated payload
@@ -143,7 +145,7 @@ export function createRequestContractTerminationHandler(options, consumerProtect
             if (candidates.length === 1 && onlyCandidate !== undefined) {
                 matchedTenantId = onlyCandidate;
                 const revocation = createRevocationToken();
-                const declared = await ctx.writeAs(createSystemUser(onlyCandidate), SubscriptionFoundationHandlers.declareContractTermination, {
+                const declared = await ctx.dispatch.writeAs(createSystemUser(onlyCandidate), SubscriptionFoundationHandlers.declareContractTermination, {
                     requestId,
                     declarationType,
                     terminationKind,
@@ -166,7 +168,7 @@ export function createRequestContractTerminationHandler(options, consumerProtect
             }
             else {
                 reasons.push(candidates.length === 0 ? "unmatched" : "ambiguous");
-                const recorded = await ctx.writeAs(createSystemUser(SYSTEM_TENANT_ID), SubscriptionFoundationHandlers.recordUnmatchedContractTermination, {
+                const recorded = await ctx.dispatch.writeAs(createSystemUser(SYSTEM_TENANT_ID), SubscriptionFoundationHandlers.recordUnmatchedContractTermination, {
                     requestId,
                     declarationType,
                     terminationKind,
@@ -218,7 +220,7 @@ export function createTerminateContractHandler(options, consumerProtection) {
             const tenantId = event.user.tenantId;
             const requestId = generateId();
             const { declarationType, terminationKind } = payload;
-            const caller = authUserRowSchema.safeParse(await ctx.queryAs(createSystemUser(tenantId), UserQueries.findForAuth, {
+            const caller = authUserRowSchema.safeParse(await ctx.dispatch.queryAs(createSystemUser(tenantId), UserQueries.findForAuth, {
                 id: event.user.id,
             }));
             const callerEmail = caller.success && caller.data.email && caller.data.isDeleted !== true
@@ -229,7 +231,7 @@ export function createTerminateContractHandler(options, consumerProtection) {
                     message: "billing-foundation:terminate-contract: calling user has no email on record",
                 });
             }
-            const recorded = await ctx.writeAs(createSystemUser(tenantId), SubscriptionFoundationHandlers.recordContractTermination, {
+            const recorded = await ctx.dispatch.writeAs(createSystemUser(tenantId), SubscriptionFoundationHandlers.recordContractTermination, {
                 requestId,
                 declarationType,
                 terminationKind,