@cosmicdrift/kumiko-samples 0.365.1 → 0.367.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.365.1",
+  "version": "0.367.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.365.1",
+  "version": "0.367.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/src/admin-shell/feature.ts

@@ -65,15 +65,15 @@ export function createAdminShellFeature(options: CreateAdminShellOptions = {}):
       category: "operations",
       recommended: false,
     });
-    r.requires("user");
-    r.requires("tenant");
-    r.requires("audit");
-    r.requires("jobs");
-    r.requires("metrics");
-    r.requires("metrics-system");
-    if (includeTierAdmin) r.requires("tier-engine");
-    if (includeCapOverview) r.requires("cap-overview");
-    if (includeDocumentDesigner) r.requires("document-designer");
+    r.requires({ features: ["user"] });
+    r.requires({ features: ["tenant"] });
+    r.requires({ features: ["audit"] });
+    r.requires({ features: ["jobs"] });
+    r.requires({ features: ["metrics"] });
+    r.requires({ features: ["metrics-system"] });
+    if (includeTierAdmin) r.requires({ features: ["tier-engine"] });
+    if (includeCapOverview) r.requires({ features: ["cap-overview"] });
+    if (includeDocumentDesigner) r.requires({ features: ["document-designer"] });
 
     r.translations({ keys: ADMIN_SHELL_I18N });
 

package/packages/bundled-features/src/agent-tools/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.366.0",
+    "type": "improvement",
+    "title": "Agent tool failures are classified instead of passing raw messages through",
+    "detail": "dispatchToolCall now adds a code to failed tool results. Client errors keep their message, rate limits also set retryable and retryAfterSeconds. Server errors and unknown throws are logged with their cause and returned to the model as \"Tool failed unexpectedly\", so internal details such as database messages no longer reach the model. ToolCallRequest accepts an optional log."
+  },
   {
     "version": "0.353.0",
     "type": "fix",

package/packages/bundled-features/src/agent-tools/tool-dispatch.ts

@@ -1,5 +1,7 @@
 import type { SessionUser, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import { isKumikoError } from "@cosmicdrift/kumiko-framework/errors";
 import { runAsDirectCallEntry } from "@cosmicdrift/kumiko-framework/internal/request-context";
+import { createFallbackLogger, type Logger } from "@cosmicdrift/kumiko-framework/logging";
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { FILTER_OPS, isRecord } from "./filter-ops.js";
 import type { ToolDispatchDescriptor } from "./types.js";
@@ -23,7 +25,13 @@ export type ToolDispatcher = {
 
 export type ToolCallResult =
   | { readonly ok: true; readonly data: unknown }
-  | { readonly ok: false; readonly error: string };
+  | {
+      readonly ok: false;
+      readonly error: string;
+      readonly code?: string;
+      readonly retryable?: boolean;
+      readonly retryAfterSeconds?: number;
+    };
 
 export type ToolCallRequest = {
   readonly dispatcher: ToolDispatcher;
@@ -37,8 +45,62 @@ export type ToolCallRequest = {
   /** Idempotency scope: `${runId}:${toolCallId}` becomes the write requestId. */
   readonly runId: string;
   readonly toolCallId: string;
+  /** Receives the cause of unexpected (5xx) failures, which the tool result never carries. */
+  readonly log?: Pick<Logger, "error">;
+};
+
+type ToolFailure = {
+  readonly code: string;
+  readonly httpStatus: number;
+  readonly message: string;
+  readonly retryAfterSeconds: number | undefined;
 };
 
+type FailureClassifier = (failure: ToolFailure, cause: unknown) => ToolCallResult;
+
+const HTTP_TOO_MANY_REQUESTS = 429;
+const HTTP_SERVER_ERROR = 500;
+const UNEXPECTED_FAILURE_MESSAGE = "Tool failed unexpectedly";
+const fallbackLog = createFallbackLogger("agent-tools");
+
+function toolFailureOf(err: unknown): ToolFailure {
+  if (isKumikoError(err)) {
+    return {
+      code: err.code,
+      httpStatus: err.httpStatus,
+      message: err.message,
+      retryAfterSeconds: err.retryAfterSeconds,
+    };
+  }
+  return {
+    code: "internal_error",
+    httpStatus: HTTP_SERVER_ERROR,
+    message: err instanceof Error ? err.message : String(err),
+    retryAfterSeconds: undefined,
+  };
+}
+
+function createFailureClassifier(toolName: string, log: Pick<Logger, "error">): FailureClassifier {
+  return (failure, cause) => {
+    if (failure.httpStatus === HTTP_TOO_MANY_REQUESTS) {
+      return {
+        ok: false,
+        error: failure.message,
+        code: failure.code,
+        retryable: true,
+        ...(failure.retryAfterSeconds !== undefined && {
+          retryAfterSeconds: failure.retryAfterSeconds,
+        }),
+      };
+    }
+    if (failure.httpStatus < HTTP_SERVER_ERROR) {
+      return { ok: false, error: failure.message, code: failure.code };
+    }
+    log.error("agent tool call failed unexpectedly", { toolName, code: failure.code, cause });
+    return { ok: false, error: UNEXPECTED_FAILURE_MESSAGE, code: failure.code };
+  };
+}
+
 const SEARCH_RESULT_LIMIT = 10;
 const DEFAULT_LIST_LIMIT = 10;
 const MAX_LIST_LIMIT = 200;
@@ -216,6 +278,7 @@ async function dispatchServerWrite(
   input: Readonly<Record<string, unknown>>,
   runId: string,
   toolCallId: string,
+  classifyFailure: FailureClassifier,
 ): Promise<ToolCallResult> {
   let payload: Readonly<Record<string, unknown>> = input;
 
@@ -240,7 +303,15 @@ async function dispatchServerWrite(
   const result = await dispatcher.write(descriptor.qn, payload, user, requestId);
 
   if (!result.isSuccess) {
-    return { ok: false, error: result.error.message };
+    return classifyFailure(
+      {
+        code: result.error.code,
+        httpStatus: result.error.httpStatus,
+        message: result.error.message,
+        retryAfterSeconds: result.error.retryAfterSeconds,
+      },
+      result.error,
+    );
   }
 
   const { id, version } = extractIdAndVersion(result.data);
@@ -343,10 +414,13 @@ function dispatchClient(
 /** Executes one LLM-issued tool call. Never throws — a missing tool, a missing argument, a
  *  disallowed filter field, or a rejected handler call (cap check, validation, ...) all come
  *  back as `{ ok: false }` so the agent loop can feed the error back to the model instead of
- *  crashing. `request.user` must be the caller's real identity — every server-kind tool runs
+ *  crashing. Client errors (< 500) keep their message and carry a `code`; 429 adds
+ *  `retryable`. Server-side failures (>= 500, unknown throws) are logged and returned as a
+ *  generic message so internals never reach the model. `request.user` must be the caller's real identity — every server-kind tool runs
  *  through the same permission-checked dispatcher pipeline as a normal HTTP request. */
 export async function dispatchToolCall(request: ToolCallRequest): Promise<ToolCallResult> {
   const { dispatcher, user, toolName, input, dispatchTable, runId, toolCallId } = request;
+  const classifyFailure = createFailureClassifier(toolName, request.log ?? fallbackLog);
   const descriptor = dispatchTable.get(toolName);
   if (!descriptor) {
     return { ok: false, error: `Unknown tool "${toolName}"` };
@@ -366,10 +440,18 @@ export async function dispatchToolCall(request: ToolCallRequest): Promise<ToolCa
         case "server":
           return descriptor.op === "query"
             ? await dispatchServerQuery(descriptor, dispatcher, user, input)
-            : await dispatchServerWrite(descriptor, dispatcher, user, input, runId, toolCallId);
+            : await dispatchServerWrite(
+                descriptor,
+                dispatcher,
+                user,
+                input,
+                runId,
+                toolCallId,
+                classifyFailure,
+              );
       }
     });
   } catch (err) {
-    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    return classifyFailure(toolFailureOf(err), err);
   }
 }

package/packages/bundled-features/src/audit/feature.ts

@@ -44,7 +44,7 @@ export function createAuditFeature(): FeatureDefinition {
         recommended: false,
       });
       r.translations({ keys: AUDIT_I18N });
-      r.requires("tenant", "user", "config");
+      r.requires({ features: ["tenant", "user", "config"] });
 
       // Registered so ops tools/MSPs can discover the type — escape-hatch-audit-sink.ts appends it via the low-level event-store API.
       r.defineEvent("escape-hatch-used", escapeHatchUsedSchema, { piiFields: "none" });

package/packages/bundled-features/src/auth-email-password/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.366.0",
+    "type": "fix",
+    "title": "Removed unused AuthHandlers.inviteCancel constant",
+    "detail": "AuthHandlers.inviteCancel pointed at auth-email-password:write:invite-cancel, a handler that never existed. The constant is removed.",
+    "migration": "If you referenced AuthHandlers.inviteCancel, use tenant:write:cancel-invitation."
+  },
+  {
+    "version": "0.366.0",
+    "type": "fix",
+    "title": "invite-create is no longer exposed to agents",
+    "detail": "The admin invite-create handler is now opted out of the agent tool catalog with agent: { expose: false }, like the other invite handlers, because it mails an accept link to an arbitrary address."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/packages/bundled-features/src/auth-email-password/constants.ts

@@ -38,7 +38,6 @@ export const AuthHandlers = {
   //   inviteAccept: logged-in user → POST token (membership-add)
   //   inviteAcceptWithLogin: anon user with existing email → POST token + email + password
   //   inviteSignupComplete: anon user with new email → POST token + password
-  //   inviteCancel: admin cancels a pending invite
   inviteCreate: "auth-email-password:write:invite-create",
   // System-only variant (access.system) that may carry global roles — see
   // invite-create.write.ts. Dispatched in-process by runBootstrap.
@@ -47,7 +46,6 @@ export const AuthHandlers = {
   inviteAcceptWithLogin: "auth-email-password:write:invite-accept-with-login",
   inviteSignupComplete: "auth-email-password:write:invite-signup-complete",
   switchTenantMfaGate: "auth-email-password:write:switch-tenant-mfa-gate",
-  inviteCancel: "auth-email-password:write:invite-cancel",
 } as const;
 
 // Qualified query names. Anonymous-readable status so the (unauthenticated)

package/packages/bundled-features/src/auth-email-password/feature.ts

@@ -196,12 +196,12 @@ export function createAuthEmailPasswordFeature(
         { key: "accountUnlock", label: "Account-Unlock-Flow", type: "boolean", default: false },
       ],
     });
-    r.requires("user");
-    r.requires("tenant");
+    r.requires({ features: ["user"] });
+    r.requires({ features: ["tenant"] });
     // All five magic-link flows (reset/verify/signup/invite/unlock) dispatch
     // via ctx.notify → delivery must be mounted. Fail closed at boot instead
     // of silently dropping the mail.
-    if (sendsMagicLinkMail(opts)) r.requires("delivery");
+    if (sendsMagicLinkMail(opts)) r.requires({ features: ["delivery"] });
     r.envSchema(authEmailPasswordEnvSchema);
     r.translations({ keys: AUTH_EMAIL_PASSWORD_MAIL_I18N });
 

package/packages/bundled-features/src/auth-email-password/handlers/invite-create.write.ts

@@ -292,6 +292,7 @@ export function createInviteCreateHandler(opts: InviteCreateOptions) {
     name: "invite-create",
     schema: InviteCreateSchema,
     access: { roles: access.admin },
+    agent: { expose: false },
     description:
       "Invites an email address into the caller's tenant with a chosen membership role, creating or reusing the invitation and mailing the invitee a fresh accept link; re-inviting the same address invalidates the previous link.",
     handler: async (event, ctx) => {

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

@@ -128,12 +128,12 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
     // shared variable; an app mounting auth-mfa without `secrets` still gets the
     // KEK slot (and its _CIPHERTEXT twin) declared.
     r.envSchema(secretsEnvSchema);
-    r.requires("user");
-    r.requires("config");
+    r.requires({ features: ["user"] });
+    r.requires({ features: ["config"] });
     // verify.write.ts dispatches "tenant:query:memberships" — without this
     // the app boots clean and the first MFA login dies at runtime on an
     // unknown handler instead of failing at mount time.
-    r.requires("tenant");
+    r.requires({ features: ["tenant"] });
     r.config("required", mfaRequiredConfigKey(opts.requiredPolicy));
 
     // Declarative secretMint screen — mint (no input) -> reveal QR/secret/
@@ -162,7 +162,7 @@ export function createAuthMfaFeature(opts: AuthMfaFeatureOptions): FeatureDefini
         ),
     });
 
-    r.entity("user-mfa", userMfaEntity);
+    r.entity({ name: "user-mfa", ...userMfaEntity });
 
     // Late-bound by run-prod-app once the sessions feature (if mounted) has
     // produced a concrete `sessionRevokeAllOthers` callback — mirrors

package/packages/bundled-features/src/auth-mfa-user-data/index.ts

@@ -12,7 +12,7 @@ export const authMfaUserDataFeature = defineFeature("auth-mfa-user-data", (r) =>
   r.describe(
     "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `auth-mfa` feature's `user-mfa` entity. Mounts the EXT_USER_DATA export + delete hooks so 2FA enrollment status is included in the user-data export bundle and a user's TOTP secret + recovery codes are hard-deleted (via executor.forget, rebuild-safe) on a data-subject erasure request. Kept separate from `auth-mfa` so consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `auth-mfa`.",
   );
-  r.requires("user-data-rights");
+  r.requires({ features: ["user-data-rights"] });
   r.optionalRequires("auth-mfa");
   r.useExtension(EXT_USER_DATA, "user-mfa", {
     export: userMfaExportHook,

package/packages/bundled-features/src/billing-foundation/consumer-protection/register-consent.ts

@@ -46,7 +46,7 @@ export function registerConsumerProtection(
   options: ResolvedBillingFoundationOptions,
   consumerProtection: ConsumerProtectionOptions,
 ): void {
-  r.requires("template-resolver", "delivery", "user", "tenant");
+  r.requires({ features: ["template-resolver", "delivery", "user", "tenant"] });
   registerConsumerProtectionMails(r);
   registerContractTermination(r, options, consumerProtection);
   r.defineEvent(CHECKOUT_CONSENT_RECORDED_EVENT_SHORT, checkoutConsentRecordedPayloadSchema, {

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

@@ -143,7 +143,7 @@ export function createBillingFoundationFeature<TTier extends string = string>(
       category: "billing",
       recommended: false,
     });
-    r.requires("tenant-lifecycle", "compliance-profiles");
+    r.requires({ features: ["tenant-lifecycle", "compliance-profiles"] });
     // 5 fine-grained domain-events. All 5 share the same payload shape (a
     // subscription-state snapshot); the event type tags what happened.
     // Future consumers (billing-history, accounting) listen directly on

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

@@ -1,4 +1,9 @@
-import { deleteMany, runInOwnTransaction, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  deleteMany,
+  isUniqueViolation,
+  runInOwnTransaction,
+  type TenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
 import { reraiseAsKumikoError } from "@cosmicdrift/kumiko-framework/errors";
 import {
@@ -25,6 +30,7 @@ import {
 import {
   CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
   CAP_RESERVATION_TTL_MINUTES,
+  CAP_SETTLED_TOMBSTONE_TTL_MINUTES,
   ROLLING_INCREMENTED_EVENT_QN,
   ROLLING_RELEASED_EVENT_QN,
 } from "./constants.js";
@@ -38,6 +44,7 @@ type CapReservationRow = {
   readonly amount: number;
   readonly expiresAt: Temporal.Instant;
   readonly createdAt: Temporal.Instant;
+  readonly settledAt: Temporal.Instant | null;
 };
 
 const NOTHING_TO_RELEASE: WriteResult = { isSuccess: true, data: {} };
@@ -61,6 +68,7 @@ async function insertReservationRow(
     amount: draft.amount,
     expiresAt: now.add({ minutes: CAP_RESERVATION_TTL_MINUTES }),
     createdAt: now,
+    settledAt: null,
   });
 }
 
@@ -185,7 +193,11 @@ async function confirmCapReservation(
   confirm: ReservationConfirmContext,
   id: string,
 ): Promise<void> {
-  await deleteMany(confirm.tx, capReservationsTable, { id, tenantId: confirm.tenantId });
+  await deleteMany(confirm.tx, capReservationsTable, {
+    id,
+    tenantId: confirm.tenantId,
+    settledAt: null,
+  });
 }
 
 async function giveBackCalendar(
@@ -229,7 +241,10 @@ async function giveBackReservation(
   id: string,
 ): Promise<WriteResult> {
   const ownRow = { id, tenantId: user.tenantId };
-  const row = await txDb.fetchOne<CapReservationRow>(capReservationsTable, ownRow);
+  const row = await txDb.fetchOne<CapReservationRow>(capReservationsTable, {
+    ...ownRow,
+    settledAt: null,
+  });
   if (!row) return NOTHING_TO_RELEASE;
   const claimed = await claimReservationRow(txDb, user, row);
   if (!claimed) return NOTHING_TO_RELEASE;
@@ -242,7 +257,8 @@ async function giveBackReservation(
   return given;
 }
 
-// Waits for a confirm still holding the row; false means that confirm (or another release) won.
+// Waits for a confirm still holding the row; false means that confirm, a settle or another release
+// won (Postgres re-checks settled_at after the lock wait).
 async function claimReservationRow(
   txDb: TenantDb,
   user: SessionUser,
@@ -251,7 +267,7 @@ async function claimReservationRow(
   const claimed = await txDb.updateMany(
     capReservationsTable,
     { expiresAt: row.expiresAt },
-    { id: row.id, tenantId: user.tenantId },
+    { id: row.id, tenantId: user.tenantId, settledAt: null },
   );
   return claimed.length > 0;
 }
@@ -291,8 +307,61 @@ function bookCalendarDelta(
   );
 }
 
-// Replaces the reserved amount by the actual one in a single transaction. When the row is already
-// gone (swept or released), the reserved amount was given back, so the full actual amount is booked.
+async function settleInTransaction(
+  txDb: TenantDb,
+  user: SessionUser,
+  id: string,
+  options: SettleCalendarCapOptions,
+): Promise<WriteResult> {
+  const ownRow = { id, tenantId: user.tenantId };
+  const open = await txDb.fetchOne<CapReservationRow>(capReservationsTable, {
+    ...ownRow,
+    settledAt: null,
+  });
+  if (open && (await claimReservationRow(txDb, user, open))) {
+    const booked = await bookCalendarDelta(txDb, user, options, options.actualAmount - open.amount);
+    if (!booked.isSuccess) return booked;
+    const now = Temporal.Now.instant();
+    await txDb.updateMany(
+      capReservationsTable,
+      { settledAt: now, expiresAt: now.add({ minutes: CAP_SETTLED_TOMBSTONE_TTL_MINUTES }) },
+      ownRow,
+    );
+    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;
+  }
+  // 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.
+  const now = Temporal.Now.instant();
+  await txDb.insertOne(capReservationsTable, {
+    ...ownRow,
+    capName: options.capName,
+    kind: "calendar",
+    periodStartIso: options.periodStartIso,
+    amount: options.actualAmount,
+    expiresAt: now.add({ minutes: CAP_SETTLED_TOMBSTONE_TTL_MINUTES }),
+    createdAt: now,
+    settledAt: now,
+  });
+  return bookCalendarDelta(txDb, user, options, options.actualAmount);
+}
+
+// The failed tombstone insert aborts the whole attempt, so nothing was booked; the repeat sees the
+// winner's tombstone.
+async function retryOnceOnTombstoneRace(attempt: () => Promise<WriteResult>): Promise<WriteResult> {
+  try {
+    return await attempt();
+  } catch (error) {
+    if (!isUniqueViolation(error)) throw error;
+    return attempt();
+  }
+}
+
+// Replaces the reserved amount by the actual one in a single transaction and keeps the row as a
+// settled tombstone, so a repeated settle (retry, lost ack) books nothing twice.
 export async function settleCalendarCapReservation(
   ctx: CapCounterContext,
   id: string,
@@ -306,41 +375,33 @@ export async function settleCalendarCapReservation(
   }
   const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
   const settled = await retryCounterWriteOnVersionConflict(() =>
-    runInOwnTransaction(writeDb, async (txDb) => {
-      const row = await txDb.fetchOne<CapReservationRow>(capReservationsTable, {
-        id,
-        tenantId: user.tenantId,
-      });
-      const claimed = row ? await claimReservationRow(txDb, user, row) : false;
-      if (!row || !claimed) {
-        return bookCalendarDelta(txDb, user, options, options.actualAmount);
-      }
-      const booked = await bookCalendarDelta(
-        txDb,
-        user,
-        options,
-        options.actualAmount - row.amount,
-      );
-      if (!booked.isSuccess) return booked;
-      await txDb.deleteMany(capReservationsTable, { id, tenantId: user.tenantId });
-      return booked;
-    }),
+    retryOnceOnTombstoneRace(() =>
+      runInOwnTransaction(writeDb, (txDb) => settleInTransaction(txDb, user, id, options)),
+    ),
   );
   if (!settled.isSuccess) throw reraiseAsKumikoError(settled.error);
 }
 
 // A failed release leaves its row behind; giving it back once the TTL passed bounds how long that
-// capacity stays counted.
+// capacity stays counted. Expired settled tombstones are only deleted: their amount stays booked.
 export async function releaseExpiredCapReservations(
   ctx: CapCounterContext,
   capName: string,
   outsideTransaction = true,
 ): Promise<void> {
   const { user, writeDb } = resolveCapCounterScope(ctx, outsideTransaction);
-  const expired = await writeDb.selectMany<Pick<CapReservationRow, "id">>(capReservationsTable, {
+  const expiredWhere = {
     tenantId: user.tenantId,
     capName,
     expiresAt: { lt: Temporal.Now.instant() },
+  };
+  await writeDb.deleteMany(capReservationsTable, {
+    ...expiredWhere,
+    settledAt: { ne: null },
+  });
+  const expired = await writeDb.selectMany<Pick<CapReservationRow, "id">>(capReservationsTable, {
+    ...expiredWhere,
+    settledAt: null,
   });
   for (const { id } of expired) {
     try {

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

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.366.0",
+    "type": "fix",
+    "title": "cap-counter calendar settle is idempotent",
+    "detail": "Settling a calendar cap reservation now keeps the row as a tombstone (new column store_cap_reservations.settled_at, retained for 24 hours) instead of deleting it. A repeated settle with the same reservation id is a no-op, and confirm, give-back and expiry sweep ignore settled rows. The sweep deletes expired tombstones.",
+    "migration": "Apps with cap-counter generate a migration for the new column store_cap_reservations.settled_at (kumiko migrate generate)."
+  },
   {
     "version": "0.365.0",
     "type": "breaking",

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

@@ -28,6 +28,9 @@ export const ROLLING_RELEASED_EVENT_QN = "cap-counter:event:rolling-released" as
 // reservation for the same cap, which bounds the over-count a failed release can leave behind.
 export const CAP_RESERVATION_TTL_MINUTES = 60;
 
+// A settled reservation stays as a tombstone this long so a retried or lost-ack settle stays a no-op.
+export const CAP_SETTLED_TOMBSTONE_TTL_MINUTES = 24 * 60;
+
 // Qualified write handler names (QN format: scope:type:name).
 export const CapCounterHandlers = {
   increment: "cap-counter:write:increment",

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

@@ -1,7 +1,7 @@
 // cap-counter — Counter-Storage + Increment-API + Soft-Warn-State.
 //
 // **Was diese Feature liefert:**
-//   1. r.entity("cap-counter") — Counter-Rows pro (tenant, capName,
+//   1. r.entity({ name: "cap-counter" }) — Counter-Rows pro (tenant, capName,
 //      period) für Calendar-Period-Caps (Mails/Monat, Egress/Monat).
 //   2. increment-Handler — atomic counter increment via deterministic
 //      aggregate-id (try-create / executor-update). Race-frei via
@@ -77,7 +77,7 @@ export const capCounterFeature = defineFeature(CAP_COUNTER_FEATURE, (r) => {
     category: "operations",
     recommended: false,
   });
-  r.entity("cap-counter", capCounterEntity);
+  r.entity({ name: "cap-counter", ...capCounterEntity });
   r.storeTable(capReservationsTableMeta, {
     reason: "coordination.cap_reservation_ledger",
   });

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

@@ -14,8 +14,9 @@ const CAP_RESERVATIONS_TENANT_CAP_EXPIRES_INDEX =
 
 // One row per capacity that was booked before a handler transaction and is not settled yet. The
 // handler transaction deletes it on its own commit (confirm); a release or the TTL sweep deletes it
-// together with the counter decrement. Unmanaged: the rows are a coordination aid, not state with
-// an event history.
+// together with the counter decrement. A settle keeps the row as a tombstone (settled_at set) until
+// its shortened TTL passes, so a repeated settle or a late release finds it and does nothing.
+// Unmanaged: the rows are a coordination aid, not state with an event history.
 export const capReservationsTable = pgTable(
   "store_cap_reservations",
   {
@@ -28,6 +29,7 @@ export const capReservationsTable = pgTable(
     amount: integer("amount").notNull(),
     expiresAt: instant("expires_at").notNull(),
     createdAt: instant("created_at").notNull(),
+    settledAt: instant("settled_at"),
   },
   (t) => [index(CAP_RESERVATIONS_TENANT_CAP_EXPIRES_INDEX).on(t.tenantId, t.capName, t.expiresAt)],
 );
@@ -49,5 +51,6 @@ export const capReservationsTableMeta: EntityTableMeta = defineUnmanagedTable({
     { name: "amount", pgType: "integer", notNull: true },
     { name: "expires_at", pgType: "timestamptz", notNull: true },
     { name: "created_at", pgType: "timestamptz", notNull: true },
+    { name: "settled_at", pgType: "timestamptz", notNull: false },
   ],
 });

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

@@ -70,9 +70,9 @@ export function createCapOverviewFeature(opts: CreateCapOverviewOptions): Featur
       recommended: false,
     });
     r.systemScope();
-    r.requires("tenant");
-    r.requires("tier-engine");
-    r.requires("billing-foundation");
+    r.requires({ features: ["tenant"] });
+    r.requires({ features: ["tier-engine"] });
+    r.requires({ features: ["billing-foundation"] });
 
     r.queryHandler(createTenantCapsListQuery(opts.caps, listCaps));
     r.queryHandler(createCapsUsageQuery(opts.caps, usageRoles));

package/packages/bundled-features/src/channel-discord/feature.ts

@@ -24,8 +24,8 @@ export function createChannelDiscordFeature(
       category: "notifications",
       recommended: false,
     });
-    r.requires("delivery");
-    r.requires("secrets");
+    r.requires({ features: ["delivery"] });
+    r.requires({ features: ["secrets"] });
 
     const webhookTarget = resolveChatWebhookTarget(
       {

package/packages/bundled-features/src/channel-email/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.367.0",
+    "type": "improvement",
+    "title": "Email channel can send through the tenant's own mail provider",
+    "detail": "EmailChannelOptions gets tenantTransport, a resolver called per send with the delivery channel context. mail-foundation exports tenantMailTransport for it: a tenant with a provider configured sends through its own transport, a broken provider fails the send, a tenant without a provider uses the app transport. The transport is built per send and never cached, and the tenant comes from the server-side delivery context only. ChannelContext now carries the tenant's config accessor as config. Without tenantTransport nothing changes."
+  },
   {
     "version": "0.365.0",
     "type": "fix",