@cosmicdrift/kumiko-samples 0.388.0 → 0.390.0

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-record.ts

@@ -39,6 +39,10 @@ import {
   FALLBACK_CONSENT_LOCALE,
 } from "../web/consumer-protection/consent-locale.ts";
 import { notifyOperator } from "./termination-notify.ts";
+import {
+  TERMINATION_PROVIDER_LOCK_KEY,
+  TERMINATION_PROVIDER_LOCK_NAMESPACE,
+} from "./termination-provider-lock.ts";
 import type { OperatorNoticeReason } from "./termination-texts.ts";
 import { isWithinWithdrawalPeriod } from "./withdrawal-period.ts";
 
@@ -141,7 +145,7 @@ async function cancelAtProvider(
       when,
     });
   } catch (error) {
-    ctx.log?.warn(
+    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" };
@@ -165,7 +169,7 @@ export function createDeclareContractTerminationHandler(): WriteHandlerDef {
     handler: async (event, ctx) => {
       // @cast-boundary engine-payload — dispatcher-zod-validated payload
       const payload = event.payload as z.infer<typeof declareContractTerminationSchema>;
-      const stream = await ctx.fetchForWriting({
+      const stream = await ctx.events.fetchForWriting({
         aggregateId: subscriptionAggregateId(event.user.tenantId),
         aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
       });
@@ -189,38 +193,6 @@ function revokedRecordResult(receivedAtIso: string) {
   };
 }
 
-// A revocation that landed during the provider cancel found nothing to take back yet.
-async function takeBackLateRevokedCancel(
-  ctx: HandlerContext,
-  consumerProtection: ConsumerProtectionOptions,
-  args: {
-    readonly payload: z.infer<typeof recordContractTerminationSchema>;
-    readonly tenantId: string;
-    readonly receivedAtIso: string;
-    readonly providerCancel: ProviderCancelOutcome;
-  },
-): Promise<void> {
-  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: ResolvedBillingFoundationOptions,
   consumerProtection: ConsumerProtectionOptions,
@@ -234,6 +206,11 @@ export function createRecordContractTerminationHandler(
       // @cast-boundary engine-payload — dispatcher-zod-validated payload
       const payload = event.payload as z.infer<typeof recordContractTerminationSchema>;
       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:
@@ -242,7 +219,7 @@ export function createRecordContractTerminationHandler(
       }
 
       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,
       });
@@ -277,30 +254,12 @@ export function createRecordContractTerminationHandler(
         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,
@@ -389,7 +348,7 @@ export async function resumeAtProvider(
       providerSubscriptionId: subscription.providerSubscriptionId,
     });
   } catch (error) {
-    ctx.log?.warn(
+    ctx.obs.log?.warn(
       `[billing-foundation:revoke-contract-termination] provider resume failed: ${error instanceof Error ? error.message : String(error)}`,
     );
     return ["revocation_resume_failed"];
@@ -414,7 +373,7 @@ export function createRecordUnmatchedContractTerminationHandler(): WriteHandlerD
     handler: async (event, ctx) => {
       // @cast-boundary engine-payload — dispatcher-zod-validated payload
       const payload = event.payload as z.infer<typeof recordUnmatchedContractTerminationSchema>;
-      const stream = await ctx.fetchForWriting({
+      const stream = await ctx.events.fetchForWriting({
         aggregateId: terminationUnmatchedAggregateId(payload.requestId),
         aggregateType: CONTRACT_TERMINATION_UNMATCHED_AGGREGATE_TYPE,
       });

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-request.ts

@@ -160,11 +160,13 @@ async function findTerminableTenantIds(
       "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 }),
+    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, {
+    await ctx.dispatch.queryAs(createSystemUser(requestTenantId), TenantQueries.memberships, {
       userId: user.data.id,
     }),
   );
@@ -180,7 +182,7 @@ async function findTerminableTenantIds(
   const terminable: string[] = [];
   for (const tenantId of adminTenantIds) {
     const probe = terminableResultSchema.safeParse(
-      await ctx.queryAs(
+      await ctx.dispatch.queryAs(
         createSystemUser(tenantId),
         SubscriptionFoundationQueries.terminableSubscription,
         {},
@@ -205,7 +207,7 @@ export function createRequestContractTerminationHandler(
     ...(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.",
+        "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
@@ -228,7 +230,7 @@ export function createRequestContractTerminationHandler(
       if (candidates.length === 1 && onlyCandidate !== undefined) {
         matchedTenantId = onlyCandidate;
         const revocation = createRevocationToken();
-        const declared = await ctx.writeAs(
+        const declared = await ctx.dispatch.writeAs(
           createSystemUser(onlyCandidate),
           SubscriptionFoundationHandlers.declareContractTermination,
           {
@@ -253,7 +255,7 @@ export function createRequestContractTerminationHandler(
         }
       } else {
         reasons.push(candidates.length === 0 ? "unmatched" : "ambiguous");
-        const recorded = await ctx.writeAs(
+        const recorded = await ctx.dispatch.writeAs(
           createSystemUser(SYSTEM_TENANT_ID),
           SubscriptionFoundationHandlers.recordUnmatchedContractTermination,
           {
@@ -318,7 +320,7 @@ export function createTerminateContractHandler(
       const { declarationType, terminationKind } = payload;
 
       const caller = authUserRowSchema.safeParse(
-        await ctx.queryAs(createSystemUser(tenantId), UserQueries.findForAuth, {
+        await ctx.dispatch.queryAs(createSystemUser(tenantId), UserQueries.findForAuth, {
           id: event.user.id,
         }),
       );
@@ -332,7 +334,7 @@ export function createTerminateContractHandler(
         });
       }
 
-      const recorded = await ctx.writeAs(
+      const recorded = await ctx.dispatch.writeAs(
         createSystemUser(tenantId),
         SubscriptionFoundationHandlers.recordContractTermination,
         {

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-revoke.ts

@@ -24,6 +24,11 @@ import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from
 import { SubscriptionFoundationHandlers } from "../web/constants.ts";
 import type { ConsentLocale } from "./consent-text.ts";
 import { notifyOperator } from "./termination-notify.ts";
+import { hasOtherOpenProviderCancel } from "./termination-open-cancels.ts";
+import {
+  TERMINATION_PROVIDER_LOCK_KEY,
+  TERMINATION_PROVIDER_LOCK_NAMESPACE,
+} from "./termination-provider-lock.ts";
 import { findRecordedTermination, hasRevocation, resumeAtProvider } from "./termination-record.ts";
 import type { OperatorNoticeReason } from "./termination-texts.ts";
 
@@ -103,7 +108,7 @@ export function createRevokeContractTerminationHandler(): WriteHandlerDef {
     handler: async (event, ctx) => {
       // @cast-boundary engine-payload — dispatcher-zod-validated payload
       const payload = event.payload as z.infer<typeof revokeContractTerminationSchema>;
-      const result = await ctx.writeAs(
+      const result = await ctx.dispatch.writeAs(
         createSystemUser(payload.tenantId),
         SubscriptionFoundationHandlers.recordContractTerminationRevocation,
         { requestId: payload.requestId, token: payload.token },
@@ -129,11 +134,16 @@ export function createRecordContractTerminationRevocationHandler(
       // @cast-boundary engine-payload — dispatcher-zod-validated payload
       const payload = event.payload as z.infer<typeof recordContractTerminationRevocationSchema>;
       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,
+      );
       const outcome = (value: RevocationOutcome) => ({
         isSuccess: true as const,
         data: { outcome: value },
       });
-      const stream = await ctx.fetchForWriting({
+      const stream = await ctx.events.fetchForWriting({
         aggregateId: subscriptionAggregateId(tenantId),
         aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
       });
@@ -162,25 +172,18 @@ export function createRecordContractTerminationRevocationHandler(
       }
 
       const reasons: OperatorNoticeReason[] = ["revoked"];
-      if (requested?.providerCancel === "period-end") {
+      if (
+        requested?.providerCancel === "period-end" &&
+        !hasOtherOpenProviderCancel(stream.events, payload.requestId)
+      ) {
         reasons.push(...(await resumeAtProvider(ctx, subscription)));
       }
       // Re-fetch after the external call, like record-contract-termination.
-      const streamAfterProviderCall = await ctx.fetchForWriting({
+      const streamAfterProviderCall = await ctx.events.fetchForWriting({
         aggregateId: subscriptionAggregateId(tenantId),
         aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
       });
-      // A cancel recorded between the first fetch and now was never resumed above.
-      const requestedMeanwhile =
-        requested === undefined
-          ? findRecordedTermination(streamAfterProviderCall.events, payload.requestId)
-          : undefined;
-      if (requestedMeanwhile?.providerCancel === "period-end") {
-        reasons.push(
-          ...(await resumeAtProvider(ctx, await getSubscriptionForTenant(ctx, tenantId))),
-        );
-      }
-      const providerCancel = (requested ?? requestedMeanwhile)?.providerCancel;
+      const providerCancel = requested?.providerCancel;
       const revoked: ContractTerminationRevokedPayload = {
         requestId: payload.requestId,
         revokedAtIso: now.toString(),

package/packages/bundled-features/src/billing-foundation/events.ts

@@ -19,7 +19,7 @@ import { CONSENT_LOCALES } from "./web/consumer-protection/consent-locale.ts";
 export const SUBSCRIPTION_AGGREGATE_TYPE = "subscription" as const;
 
 // Event-name constants — short form (for r.defineEvent) and qualified
-// FQN (for ctx.unsafeAppendEvent and projection-apply keys).
+// FQN (for ctx.events.unsafeAppend and projection-apply keys).
 export const SUBSCRIPTION_CREATED_EVENT_SHORT = "subscription-created" as const;
 export const SUBSCRIPTION_UPDATED_EVENT_SHORT = "subscription-updated" as const;
 export const SUBSCRIPTION_CANCELED_EVENT_SHORT = "subscription-canceled" as const;

package/packages/bundled-features/src/billing-foundation/feature.ts

@@ -172,7 +172,7 @@ export function createBillingFoundationFeature<TTier extends string = string>(
       r.defineEvent(PAYMENT_RECEIVED_EVENT_SHORT, paymentEventPayloadSchema, { piiFields: "none" });
 
       // Inline projection: materialized current state in `read_subscriptions`.
-      // Apply runs in the same TX as ctx.unsafeAppendEvent — read-your-own-
+      // Apply runs in the same TX as ctx.events.unsafeAppend — read-your-own-
       // write without a dispatcher tick.
       r.projection({
         name: "subscription",
@@ -260,13 +260,18 @@ export function createBillingFoundationFeature<TTier extends string = string>(
         perTenant: true,
         runOnBoot: true,
         handler: async (_payload, ctx) => {
-          const result = await ctx.write(SubscriptionFoundationHandlers.syncSubscription, {});
+          const result = await ctx.dispatch.write(
+            SubscriptionFoundationHandlers.syncSubscription,
+            {},
+          );
           if (!result.isSuccess) {
             throw new Error(
               `billing-foundation:sync-subscriptions: sync-subscription write failed: ${JSON.stringify(result.error)}`,
             );
           }
-          ctx.log.info(`[billing-foundation:sync-subscriptions] ${JSON.stringify(result.data)}`);
+          ctx.obs.log.info(
+            `[billing-foundation:sync-subscriptions] ${JSON.stringify(result.data)}`,
+          );
         },
       });
 

package/packages/bundled-features/src/billing-foundation/get-subscription-for-tenant.ts

@@ -29,7 +29,7 @@ export type SubscriptionView = {
  *  aggregate ID), or null if the tenant has never subscribed. The status
  *  may be active/canceled/past_due/etc.; the caller decides what to do. */
 export async function getSubscriptionForTenant(
-  ctx: HandlerContext,
+  ctx: Pick<HandlerContext, "db">,
   tenantId: string,
 ): Promise<SubscriptionView | null> {
   const aggId = subscriptionAggregateId(tenantId);

package/packages/bundled-features/src/billing-foundation/handlers/process-event.write.ts

@@ -9,7 +9,7 @@
 //      with no second append.
 //   2. Type mapping: SubscriptionEvent.type (= normalized by the plugin)
 //      → one of the 5 ES event types.
-//   3. ctx.unsafeAppendEvent — the inline projection materializes the
+//   3. ctx.events.unsafeAppend — the inline projection materializes the
 //      `read_subscriptions` row in the same TX.
 
 import {
@@ -175,7 +175,7 @@ export async function appendSubscriptionEvent(
   //    streams, optimize via snapshot or a per-tenant dedup table as the
   //    idempotency anchor (like cap-counter).
   // ---------------------------------------------------------------
-  const existingEvents = await ctx.loadAggregate(aggId);
+  const existingEvents = await ctx.events.load(aggId);
   const alreadySeen = existingEvents.some((e) => {
     const headers = e.metadata.headers ?? {};
     return (
@@ -191,7 +191,7 @@ export async function appendSubscriptionEvent(
   // late delivery: appending it would roll the row back (a canceled subscription
   // would come back active). Invoice events carry the live state, not a snapshot.
   if (isLateStateEvent(existingEvents, payload)) {
-    ctx.log?.warn(
+    ctx.obs.log?.warn(
       `[billing-foundation:process-event] dropped late ${payload.type} ${payload.providerEventId}: a newer provider event is already stored`,
     );
     return { duplicate: false, stale: true, subscriptionAggregateId: aggId };
@@ -260,7 +260,7 @@ export async function appendSubscriptionEvent(
     providerEventId: payload.providerEventId,
     providerName: payload.providerName,
   };
-  await ctx.unsafeAppendEvent({
+  await ctx.events.unsafeAppend({
     aggregateId: aggId,
     aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
     type: esEventType,
@@ -311,7 +311,7 @@ export function createProcessEventHandler(now: () => Temporal.Instant): WriteHan
       const payload = event.payload as ProcessEventPayload;
       const current = await getSubscriptionForTenant(ctx, event.user.tenantId);
       if (isStaleSubscriptionEvent(current, payload, now())) {
-        ctx.log?.warn(
+        ctx.obs.log?.warn(
           `[billing-foundation:process-event] dropped stale ${payload.type} ${payload.providerEventId}: tenant already tracks another subscription`,
         );
         return {

package/packages/bundled-features/src/billing-foundation/handlers/process-payment-event.write.ts

@@ -6,7 +6,7 @@
 //   1. Idempotency-check: loads the payment-stream and scans for an
 //      already-seen `metadata.providerEventId`. A provider-replay with
 //      the same event-id → duplicate=true, no second append.
-//   2. ctx.unsafeAppendEvent — inline-projection materializes a new
+//   2. ctx.events.unsafeAppend — inline-projection materializes a new
 //      `read_payments`-row (INSERT-once, not UPSERT — every payment is
 //      its own fact, not a state-update).
 
@@ -55,7 +55,7 @@ export const processPaymentEventHandler: WriteHandlerDef = {
     //    (a tenant with hundreds of purchases scans hundreds of events;
     //    optimize via a per-tenant providerEventId-index if that bites).
     // ---------------------------------------------------------------
-    const existingEvents = await ctx.loadAggregate(aggId);
+    const existingEvents = await ctx.events.load(aggId);
     const alreadySeen = existingEvents.some((e) => {
       const headers = e.metadata.headers ?? {};
       return (
@@ -106,7 +106,7 @@ export const processPaymentEventHandler: WriteHandlerDef = {
         providerCheckoutId: payload.providerCheckoutId,
       }),
     };
-    await ctx.unsafeAppendEvent({
+    await ctx.events.unsafeAppend({
       aggregateId: aggId,
       aggregateType: PAYMENT_AGGREGATE_TYPE,
       type: PAYMENT_RECEIVED_EVENT_QN,

package/packages/bundled-features/src/billing-foundation/plan-catalog.ts

@@ -77,7 +77,7 @@ export async function resolvePlanPrices(
     prices = await plugin.retrievePrices(ctx, allPriceIds);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    ctx.log?.warn("billing-foundation: retrievePrices threw, all plan prices unavailable", {
+    ctx.obs.log?.warn("billing-foundation: retrievePrices threw, all plan prices unavailable", {
       message,
     });
     return result;
@@ -93,7 +93,7 @@ export async function resolvePlanPrices(
       const chosen = active[0];
       if (chosen) result.set(tier, { priceId: chosen.priceId, price: chosen });
     } else if (active.length > 1) {
-      ctx.log?.warn(
+      ctx.obs.log?.warn(
         `billing-foundation: tier "${tier}" has ${active.length} active flat-amount prices — expected exactly one, price stays unavailable`,
       );
     }

package/packages/bundled-features/src/billing-foundation/projection.ts

@@ -1,7 +1,7 @@
 // Inline projection for `read_subscriptions`. Materializes the 5
 // subscription events into one row per tenant.
 //
-// Apply runs in the same transaction as ctx.unsafeAppendEvent, so the caller
+// Apply runs in the same transaction as ctx.events.unsafeAppend, so the caller
 // sees its write state immediately (no dispatcher tick required). The PK is
 // event.aggregateId (= deterministic uuidv5 per tenant), so replays collide
 // on the PK instead of creating duplicate rows.

package/packages/bundled-features/src/billing-foundation/types.ts

@@ -18,7 +18,7 @@
 //   2. **Post-tenant-resolution:** `createPortalSession` +
 //      `cancelSubscription` are called from regular write handlers with
 //      a fully resolved HandlerContext. The plugin can use ctx.config +
-//      ctx.secrets for tenant-specific configuration (e.g. tenant-owned
+//      ctx.services.secrets for tenant-specific configuration (e.g. tenant-owned
 //      customer-id mappings).
 //
 // Foundation uses only the common subset of provider functionality;

package/packages/bundled-features/src/cap-counter/aggregate-id.ts

@@ -38,7 +38,7 @@ export function capCounterAggregateId(
  * different uuidv5 namespace, different output UUID. This also prevents an
  * accidental calendar increment from landing on the rolling stream.
  *
- * **Caller:** `CapCounterHandlers.incrementRolling` (via `ctx.write`) calls
+ * **Caller:** `CapCounterHandlers.incrementRolling` (via `ctx.dispatch.write`) calls
  * this with tenantId + capName and appends increment events to the stream.
  * Race-free because the event store appends with an auto-incrementing version.
  */

package/packages/bundled-features/src/cap-counter/book-cap-usage.ts

@@ -5,6 +5,7 @@ import {
   createEntityExecutor,
   type HandlerContext,
   type JobContext,
+  type ReservationContext,
   type SessionUser,
   type TenantId,
   type WriteResult,
@@ -84,7 +85,7 @@ export type BookCapUsageOptions = {
   readonly guardCurrentValue?: (currentValue: number) => void;
 };
 
-export type CapCounterContext = HandlerContext | JobContext;
+export type CapCounterContext = HandlerContext | JobContext | ReservationContext;
 
 export type CapCounterScope = {
   readonly user: SessionUser;
@@ -104,7 +105,7 @@ function assertDbServesUser(db: TenantDb, user: SessionUser): TenantDb {
 }
 
 // Jobs write in place (their db is not transaction-bound); systemScope handlers reach both dbs via
-// systemDb, because their ctx.db / ctx.dbOutsideTransaction are fail-closed proxies.
+// systemDb, because their ctx.db / ctx.db.outsideTransaction are fail-closed proxies.
 export function resolveCapCounterScope(
   ctx: CapCounterContext,
   outsideTransaction: boolean,
@@ -130,11 +131,11 @@ export function resolveCapCounterScope(
       : readDb;
     return { user, readDb, writeDb };
   }
-  const writeDb = outsideTransaction ? ctx.dbOutsideTransaction : ctx.db;
+  const writeDb = outsideTransaction ? ctx.db.outsideTransaction : ctx.db;
   if (!writeDb) {
     throw new Error(
       outsideTransaction
-        ? "cap-counter: outsideTransaction requested but ctx.dbOutsideTransaction is undefined"
+        ? "cap-counter: outsideTransaction requested but ctx.db.outsideTransaction is undefined"
         : "cap-counter: ctx.db missing — run inside a handler context",
     );
   }

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

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

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

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

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

@@ -13,7 +13,7 @@ export const CAP_COUNTER_ROLLING_AGGREGATE_TYPE = "cap-counter-rolling" as const
 // Custom event types for rolling-window counters. The pair is symmetric:
 //   _SHORT  — matches `r.defineEvent(short, schema)` in the registrar
 //             (the framework automatically prefixes it to the QN)
-//   _QN     — qualified form for `ctx.unsafeAppendEvent({type})`, the
+//   _QN     — qualified form for `ctx.events.unsafeAppend({type})`, the
 //             `events.type` column, and `registry.getEvent(qn)` lookups
 // Both MUST stay consistent; the feature test pins against drift.
 export const ROLLING_INCREMENTED_EVENT_SHORT = "rolling-incremented" as const;

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

@@ -31,7 +31,7 @@
 //     ai-foundation are BYOK by default and currently have no platform pool
 //     to count. cap-counter is generic: an app owner who wants to use the
 //     counter calls `bookCapUsage(...)` /
-//     `ctx.write(CapCounterHandlers.incrementRolling, ...)` from their own handler.
+//     `ctx.dispatch.write(CapCounterHandlers.incrementRolling, ...)` from their own handler.
 //   - **No reset cron for the calendar period.** It works without one: the
 //     periodStartIso part of the aggregate id rolls over to a fresh counter
 //     at the period boundary. Old rows remain for auditing.
@@ -71,6 +71,7 @@ export function createCapCounterFeature() {
   return defineFeature(
     CAP_COUNTER_FEATURE,
     (r) => {
+      r.adoptsBundledLists();
       r.describe(
         "Tracks per-tenant usage against configurable limits using two complementary storage models: calendar-period counters (one projection row per tenant/capName/period, reset implicitly by period rollover) and rolling-window counters (append-only event stream, no projection). Use `enforceCap` / `enforceRollingCap` (or the `withCapEnforcement` / `withRollingCapEnforcement` handler wrappers) in your write-handlers to check limits with soft-warn and hard-block tolerances; call `enforceCapAndMaybeNotify` when you also want to trigger a delivery notification on soft-threshold hits.",
       );
@@ -85,7 +86,7 @@ export function createCapCounterFeature() {
       });
 
       // Custom domain event for the rolling counter. r.defineEvent registers the
-      // schema with the registry; ctx.unsafeAppendEvent in the handler reuses the
+      // schema with the registry; ctx.events.unsafeAppend in the handler reuses the
       // same schema for append-time validation. QN after prefixing:
       // "cap-counter:event:rolling-incremented" (see
       // ROLLING_INCREMENTED_EVENT_QN).

package/packages/bundled-features/src/cap-counter/handlers/increment-rolling.write.ts

@@ -71,7 +71,7 @@ export const incrementRollingCapHandler: WriteHandlerDef = {
     // unsafeAppendEvent: the strict appendEvent is bound to an app's own event map, which
     // bundled-features cannot see. Schema validation still runs because r.defineEvent
     // registered the schema.
-    await ctx.unsafeAppendEvent({
+    await ctx.events.unsafeAppend({
       aggregateId,
       aggregateType: CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
       type: ROLLING_INCREMENTED_EVENT_QN,

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

@@ -30,7 +30,7 @@ export function chainReservations(
       try {
         await innerHandle.release();
       } catch (releaseError) {
-        ctx.log?.error("releasing the inner cap reservation failed", { error: releaseError });
+        ctx.obs.log?.error("releasing the inner cap reservation failed", { error: releaseError });
       }
       throw error;
     }