@cosmicdrift/kumiko-samples 0.351.0 → 0.353.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.351.0",
+  "version": "0.353.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.351.0",
+  "version": "0.353.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>",
@@ -164,7 +164,7 @@
     "nodemailer": "^10.0.13",
     "qrcode": "^1.5.4",
     "react": "^19.2.6",
-    "sharp": "^0.35.4",
+    "sharp": "^0.35.5",
     "stripe": "^22.6.2",
     "tailwind-merge": "^3.6.0",
     "temporal-polyfill": "^0.3.2",

package/packages/bundled-features/src/agent-tools/agent-manifest.ts

@@ -19,6 +19,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { translationValueOtherText } from "@cosmicdrift/kumiko-framework/ui-types";
 import * as z from "zod";
+import { recordManifestDenyQns } from "./manifest-deny-qns.js";
 import type {
   AgentManifest,
   AgentManifestEntity,
@@ -334,6 +335,16 @@ function detailIdParam(screen: ScreenDefinition): string {
   return screen.type === "projectionDetail" ? (screen.idParam ?? "id") : "id";
 }
 
+function screenTitles(
+  translations: TranslationKeys,
+  screenId: string,
+  shortId: string,
+): AgentManifestScreen["titles"] {
+  return entryAsLabels(
+    translations[`${screenId}.title`] ?? translations[`screen:${shortId}.title`] ?? {},
+  );
+}
+
 function buildScreens(
   screens: ReadonlyMap<string, ScreenDefinition>,
   navs: ReadonlyMap<string, NavDefinition>,
@@ -372,7 +383,7 @@ function buildScreens(
     result.push({
       id: screen.id,
       type: screen.type,
-      titles: labelsForSuffix(translations, `screen:${shortId}.title`),
+      titles: screenTitles(translations, screen.id, shortId),
       // `screen.description` may be a raw i18n key (`registry.getAllTranslations()`
       // double-prefixes it, see build-app-schema.ts:77-81) — match on suffix like
       // `labelsForSuffix` does for entity/field labels, else fall back to the
@@ -444,7 +455,7 @@ export function buildAgentManifest(
   );
   const workspaces = buildWorkspaces(workspaceMap, translations, roles);
 
-  return {
+  const manifest: AgentManifest = {
     builtForRoles: [...roles],
     features: sortedByKey(features, (f) => f.name),
     entities: sortedByKey(entities, (e) => e.name),
@@ -457,4 +468,6 @@ export function buildAgentManifest(
       ...(options.currency && { currency: options.currency }),
     },
   };
+  recordManifestDenyQns(manifest, new Set(options.denyQns ?? []));
+  return manifest;
 }

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

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.353.0",
+    "type": "fix",
+    "title": "buildToolCatalog throws when the manifest was built with denyQns the catalog options lack",
+    "migration": "Pass the same denyQns list to buildAgentManifest and buildToolCatalog."
+  },
+  {
+    "version": "0.353.0",
+    "type": "fix",
+    "title": "Agent manifest screen titles resolve per feature instead of by mount order",
+    "detail": "Agent manifest screen titles no longer depend on feature mount order\nTwo features with a screen of the same short id used to get the title of whichever feature was mounted first. The manifest now looks up the screen's own feature-prefixed title key first and falls back to the unprefixed key."
+  },
   {
     "version": "0.338.0",
     "type": "improvement",

package/packages/bundled-features/src/agent-tools/manifest-deny-qns.ts

@@ -0,0 +1,25 @@
+import type { AgentManifest } from "./types.js";
+
+// The deny list is deliberately not a manifest field (the manifest is prompt
+// payload), so the catalog builder learns it through this side channel to
+// detect a manifest cut that the catalog would silently not mirror.
+const denyQnsByManifest = new WeakMap<AgentManifest, ReadonlySet<string>>();
+
+export function recordManifestDenyQns(manifest: AgentManifest, denyQns: ReadonlySet<string>): void {
+  denyQnsByManifest.set(manifest, denyQns);
+}
+
+export function assertCatalogMirrorsManifestDenyQns(
+  manifest: AgentManifest,
+  catalogDenyQns: ReadonlySet<string>,
+): void {
+  const manifestDenyQns = denyQnsByManifest.get(manifest);
+  // skip: manifest has no registered deny list, nothing to mirror
+  if (!manifestDenyQns) return;
+  const missing = [...manifestDenyQns].filter((qn) => !catalogDenyQns.has(qn));
+  if (missing.length > 0) {
+    throw new Error(
+      `agent denyQns passed to buildAgentManifest but not to buildToolCatalog: ${missing.join(", ")} — the catalog would still expose their entity CRUD tools`,
+    );
+  }
+}

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

@@ -6,6 +6,7 @@ import type {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { hasAccess, normalizeAccessEntry } from "@cosmicdrift/kumiko-framework/engine";
 import { FILTER_OPS, isRecord } from "./filter-ops.js";
+import { assertCatalogMirrorsManifestDenyQns } from "./manifest-deny-qns.js";
 import type {
   AgentManifest,
   AgentManifestEntity,
@@ -628,7 +629,8 @@ function addClientTools(manifest: AgentManifest, mode: AgentToolMode, sink: Cata
  *  to drop an entity CRUD tool, which no `agent.expose` on the manifest side can reach. It is
  *  NOT read off the manifest on purpose — the manifest is prompt payload, and a list of the
  *  handlers the model may not call has no business travelling to the provider. Pass the same
- *  list to `buildAgentManifest` so the manifest stops describing what the catalog withholds. */
+ *  list to `buildAgentManifest` so the manifest stops describing what the catalog withholds;
+ *  a manifest built with `denyQns` that the catalog lacks throws. */
 export function buildToolCatalog(
   registry: RegistrySearchView,
   manifest: AgentManifest,
@@ -639,6 +641,7 @@ export function buildToolCatalog(
   const locale = manifest.tenantSettings.locale;
   const entityByName = new Map(manifest.entities.map((entity) => [entity.name, entity]));
   const denyQns = new Set(options.denyQns ?? []);
+  assertCatalogMirrorsManifestDenyQns(manifest, denyQns);
 
   addRegistrySearchTools(registry, roleFilter, denyQns, sink);
   const { detailQnByEntity, listQnByEntity, entityListDetailQns } = collectEntityHandlerQns(

package/packages/bundled-features/src/audit/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.353.0",
+    "type": "fix",
+    "title": "Audit list paging no longer repeats rows with ascending sort",
+    "detail": "Audit list pages forward without repeats when sorted ascending\n`audit:query:list` with `sortDirection: \"asc\"` returned the same rows again on the next page because the cursor always meant \"older than\". The cursor now follows the sort direction, and ties are broken by event id. Sorting by `type` returns a single page without `nextCursor`, since an event id cannot resume a type-ordered listing."
+  },
   {
     "version": "0.346.0",
     "type": "improvement",

package/packages/bundled-features/src/audit/handlers/list.query.ts

@@ -52,6 +52,7 @@ function buildAuditWhere(
     cursor?: string;
     before?: string;
   },
+  direction: "asc" | "desc",
 ): WhereObject {
   const where: WhereObject = { tenantId };
   if (p.aggregateType) where["aggregateType"] = p.aggregateType;
@@ -62,7 +63,9 @@ function buildAuditWhere(
   const range = buildDateRange(p.from, p.to);
   if (range) where["createdAt"] = range;
   const cursor = p.cursor ?? p.before;
-  if (cursor) where["id"] = { lt: BigInt(cursor) };
+  // The cursor is an event id, so it only walks pages in id order: ascending
+  // pages continue past it, descending pages stop before it.
+  if (cursor) where["id"] = direction === "asc" ? { gt: BigInt(cursor) } : { lt: BigInt(cursor) };
   return where;
 }
 
@@ -94,10 +97,15 @@ export const listQuery = defineQueryHandler({
   handler: async (query, ctx) => {
     const p = query.payload;
     const scopeFilter = resolveAuditScopeFilter(query.user, p.scope);
-    const where = buildAuditWhere(scopeFilter.tenantId, {
-      ...p,
-      aggregateType: scopeFilter.aggregateType ?? p.aggregateType,
-    });
+    const direction = p.sortDirection ?? "desc";
+    const where = buildAuditWhere(
+      scopeFilter.tenantId,
+      {
+        ...p,
+        aggregateType: scopeFilter.aggregateType ?? p.aggregateType,
+      },
+      direction,
+    );
 
     const rows = await selectMany<{
       id: bigint;
@@ -110,10 +118,11 @@ export const listQuery = defineQueryHandler({
       createdAt: unknown;
       createdBy: string;
     }>(ctx.db, eventsTable, where, {
-      orderBy: {
-        col: query.payload.sort === "type" ? "type" : "createdAt",
-        direction: query.payload.sortDirection ?? "desc",
-      },
+      // `id` as tie-breaker keeps the order total, so pages never overlap.
+      orderBy: [
+        { col: p.sort === "type" ? "type" : "createdAt", direction },
+        { col: "id", direction },
+      ],
       limit: p.limit,
     });
 
@@ -129,7 +138,8 @@ export const listQuery = defineQueryHandler({
       createdBy: r.createdBy,
     }));
     const last = serialised[serialised.length - 1];
-    const nextId = serialised.length === p.limit && last ? last.id : null;
+    // An id cursor cannot resume a type-ordered listing, so that sort is one page.
+    const nextId = serialised.length === p.limit && last && p.sort !== "type" ? last.id : null;
     return {
       rows: serialised,
       nextCursor: nextId,

package/packages/bundled-features/src/auth-email-password/handlers/signup-confirm.write.ts

@@ -196,9 +196,8 @@ export function createSignupConfirmHandler(opts: SignupConfirmOptions = {}) {
               displayName,
               tenantId,
               tenantKey,
-              // Tenant-Display-Name als Default = Email. User wechselt das im
-              // Settings-Screen. Konzept "Tenant" leakt nicht in die Signup-UI.
-              tenantName: email,
+              // Generated slug as default name: no personal data (the email) in the tenant name.
+              tenantName: tenantKey,
             },
             // #1463: seedTenant's postSave hooks (tier-engine's auto-default-
             // tier, an app's auto-default-compliance) must fire on self-signup

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

@@ -58,7 +58,7 @@ export const mfaEnableScreen: SecretMintScreenDefinition = {
   confirm: {
     handler: AuthMfaHandlers.enableConfirm,
     fields: {
-      code: { type: "text", required: true, maxLength: 6 },
+      code: { type: "text", required: true, minLength: 6, maxLength: 6 },
     },
     layout: { sections: [{ fields: ["code"] }] },
     carry: ["setupToken"],
@@ -69,7 +69,7 @@ export const mfaEnableScreen: SecretMintScreenDefinition = {
 
 // Either a 6-digit TOTP code or a 9-char recovery code proves possession —
 // same bounds as the disable/regenerate-recovery handler schemas.
-const possessionCodeField = { type: "text", required: true, maxLength: 9 } as const;
+const possessionCodeField = { type: "text", required: true, minLength: 6, maxLength: 9 } as const;
 
 export const mfaDisableScreen: ActionFormScreenDefinition = {
   id: MFA_DISABLE_SCREEN_ID,

package/packages/bundled-features/src/billing-foundation/billing-info-query.ts

@@ -45,10 +45,9 @@ export type BillingInfo<TTier extends string> = {
 export type BillingInfoQueryDeps<TTier extends string> = {
   readonly roles: readonly string[];
   readonly resolveTier: (db: TenantDb, tenantId: TenantId) => Promise<TTier>;
-  // ctx is the same HandlerContext the returned handler receives — app
-  // implementations read app-specific extraContext fields off it (e.g.
-  // publicstatus/show-pony's getBillingPrices(ctx) reads `billingPrices`),
-  // so they type their own ctx param as `unknown` and cast internally.
+  // ctx is the same HandlerContext the returned handler receives — apps read
+  // their extraContext fields (e.g. `billingPrices`) off it and validate them
+  // at that boundary.
   readonly getBillingPrices: (
     ctx: HandlerContext,
   ) => Readonly<Partial<Record<string, string>>> | null;

package/packages/bundled-features/src/billing-foundation/checkout-core.ts

@@ -274,6 +274,13 @@ export type OpenCheckoutOptions = {
   readonly baseUrl?: string;
   readonly catalog?: BillingPlanCatalog;
   readonly now: () => Temporal.Instant;
+  /** The caller already ran `assertBillingEnabled` under its own handler name
+   *  (before a costly provider lookup), so the gate is not repeated here. */
+  readonly billingEnabledChecked?: boolean;
+  /** The caller already ran `assertNoActiveSubscription` and passes its result
+   *  (null = tenant has none); mode:"subscription" skips the second read and
+   *  the providerCustomerId check reuses it. */
+  readonly checkedSubscription?: Awaited<ReturnType<typeof getSubscriptionForTenant>>;
 };
 
 export type OpenCheckoutInput = {
@@ -358,7 +365,9 @@ export async function assertCheckoutAllowed(
   // Checked before the redirect-origin hardening for every mode — a
   // disabled provider must reject a mode:"payment" checkout just as much
   // as a mode:"subscription" one.
-  await assertBillingEnabled(ctx, plugin, "create-checkout-session");
+  if (options.billingEnabledChecked !== true) {
+    await assertBillingEnabled(ctx, plugin, "create-checkout-session");
+  }
   assertRedirectOrigins([input.successUrl, input.cancelUrl], options.baseUrl);
 
   const mode = input.mode ?? "subscription";
@@ -368,7 +377,10 @@ export async function assertCheckoutAllowed(
 
   if (mode === "subscription") {
     assertSubscriptionPriceAllowed(plugin, options.catalog, input);
-    ownSubscription = await assertNoActiveSubscription(ctx, options.now());
+    ownSubscription =
+      options.checkedSubscription !== undefined
+        ? options.checkedSubscription
+        : await assertNoActiveSubscription(ctx, options.now());
   } else {
     assertOneOffPriceAllowed(plugin, input);
   }

package/packages/bundled-features/src/billing-foundation/handlers/start-plan-checkout.write.ts

@@ -74,7 +74,13 @@ export function createStartPlanCheckoutHandler(
       const baseUrl = options.baseUrl ?? "";
       const result = await openCheckout(
         ctx,
-        { baseUrl: options.baseUrl, catalog, now: options.now },
+        {
+          baseUrl: options.baseUrl,
+          catalog,
+          now: options.now,
+          billingEnabledChecked: true,
+          checkedSubscription: existing,
+        },
         {
           providerName,
           priceId: resolved.priceId,

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

@@ -4,14 +4,19 @@ import { runInOwnTransaction, type TenantDb } from "@cosmicdrift/kumiko-framewor
 import {
   createEntityExecutor,
   type HandlerContext,
+  type SessionUser,
   type TenantId,
   type WriteResult,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { eventsTable, VersionConflictError } from "@cosmicdrift/kumiko-framework/event-store";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id.js";
-import { CAP_COUNTER_ROLLING_AGGREGATE_TYPE, ROLLING_INCREMENTED_EVENT_QN } from "./constants.js";
+import {
+  CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
+  ROLLING_INCREMENTED_EVENT_QN,
+  ROLLING_RELEASED_EVENT_QN,
+} from "./constants.js";
 import { capCounterEntity } from "./entity.js";
 
 const { table, executor } = createEntityExecutor("cap-counter", capCounterEntity);
@@ -39,7 +44,7 @@ function sleepMs(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-async function retryCounterWriteOnVersionConflict(
+export async function retryCounterWriteOnVersionConflict(
   writeAttempt: () => Promise<WriteResult>,
 ): Promise<WriteResult> {
   let result: WriteResult = await writeAttempt();
@@ -54,6 +59,20 @@ async function retryCounterWriteOnVersionConflict(
   return result;
 }
 
+// Event-store appends signal a lost race by throwing; the whole attempt (read, guard, append) is repeated.
+export async function retryOnStreamVersionConflict<T>(attempt: () => Promise<T>): Promise<T> {
+  for (let tries = 1; ; tries++) {
+    try {
+      return await attempt();
+    } catch (error) {
+      if (!(error instanceof VersionConflictError) || tries >= MAX_COUNTER_WRITE_ATTEMPTS) {
+        throw error;
+      }
+      await sleepMs(Math.random() * tries * BACKOFF_JITTER_MS_PER_ATTEMPT);
+    }
+  }
+}
+
 export type BookCapUsageOptions = {
   readonly capName: string;
   readonly periodStartIso: string;
@@ -63,7 +82,7 @@ export type BookCapUsageOptions = {
   readonly guardCurrentValue?: (currentValue: number) => void;
 };
 
-function requireOutsideTransactionDb(ctx: HandlerContext): TenantDb {
+export function requireOutsideTransactionDb(ctx: HandlerContext): TenantDb {
   if (!ctx.dbOutsideTransaction) {
     throw new Error(
       "cap-counter.bookCapUsage: outsideTransaction requested but ctx.dbOutsideTransaction is undefined",
@@ -87,64 +106,70 @@ export async function releaseCapUsage(
   return applyCapDelta(ctx, options, "subtract");
 }
 
-async function applyCapDelta(
-  ctx: HandlerContext,
+// One attempt against an already-open db handle; a lost race comes back as a version_conflict failure the caller retries.
+export async function applyCapDeltaOn(
+  db: TenantDb,
+  user: SessionUser,
   options: BookCapUsageOptions,
   direction: "add" | "subtract",
 ): Promise<WriteResult> {
   const parsed = capBookingSchema.parse(options);
-  const aggregateId = capCounterAggregateId(
-    ctx.user.tenantId,
-    parsed.capName,
-    parsed.periodStartIso,
-  );
-
-  async function attemptWrite(db: TenantDb): Promise<WriteResult> {
-    const existing = await db.selectMany(table, { id: aggregateId }, { limit: 1 });
-    if (existing.length === 0) {
-      options.guardCurrentValue?.(0);
-      if (direction === "subtract") return { isSuccess: true, data: {} };
-      return executor.create(
-        {
-          id: aggregateId,
-          capName: parsed.capName,
-          value: parsed.amount,
-          periodStart: Temporal.Instant.from(parsed.periodStartIso),
-          lastSoftWarnedAt: null,
-        },
-        ctx.user,
-        db,
-      );
-    }
+  const aggregateId = capCounterAggregateId(user.tenantId, parsed.capName, parsed.periodStartIso);
 
-    const currentRow = existing[0];
-    if (!currentRow) {
-      throw new Error("cap-counter.bookCapUsage: row vanished between length-check and read");
-    }
-    const currentValue = currentRow["value"] as number; // @cast-boundary db-row
-    const currentVersion = currentRow["version"] as number; // @cast-boundary db-row
-    options.guardCurrentValue?.(currentValue);
-    return executor.update(
+  const existing = await db.selectMany(table, { id: aggregateId }, { limit: 1 });
+  if (existing.length === 0) {
+    options.guardCurrentValue?.(0);
+    if (direction === "subtract") return { isSuccess: true, data: {} };
+    return executor.create(
       {
         id: aggregateId,
-        version: currentVersion,
-        changes: {
-          value:
-            direction === "add"
-              ? currentValue + parsed.amount
-              : Math.max(0, currentValue - parsed.amount),
-        },
+        capName: parsed.capName,
+        value: parsed.amount,
+        periodStart: Temporal.Instant.from(parsed.periodStartIso),
+        lastSoftWarnedAt: null,
       },
-      ctx.user,
+      user,
       db,
     );
   }
 
+  const currentRow = existing[0];
+  if (!currentRow) {
+    throw new Error("cap-counter.bookCapUsage: row vanished between length-check and read");
+  }
+  const currentValue = currentRow["value"] as number; // @cast-boundary db-row
+  const currentVersion = currentRow["version"] as number; // @cast-boundary db-row
+  options.guardCurrentValue?.(currentValue);
+  return executor.update(
+    {
+      id: aggregateId,
+      version: currentVersion,
+      changes: {
+        value:
+          direction === "add"
+            ? currentValue + parsed.amount
+            : Math.max(0, currentValue - parsed.amount),
+      },
+    },
+    user,
+    db,
+  );
+}
+
+async function applyCapDelta(
+  ctx: HandlerContext,
+  options: BookCapUsageOptions,
+  direction: "add" | "subtract",
+): Promise<WriteResult> {
   if (options.outsideTransaction) {
     const outsideDb = requireOutsideTransactionDb(ctx);
-    return retryCounterWriteOnVersionConflict(() => runInOwnTransaction(outsideDb, attemptWrite));
+    return retryCounterWriteOnVersionConflict(() =>
+      runInOwnTransaction(outsideDb, (txDb) => applyCapDeltaOn(txDb, ctx.user, options, direction)),
+    );
   }
-  return retryCounterWriteOnVersionConflict(() => attemptWrite(ctx.db));
+  return retryCounterWriteOnVersionConflict(() =>
+    applyCapDeltaOn(ctx.db, ctx.user, options, direction),
+  );
 }
 
 export type MarkCapSoftWarnedOptions = {
@@ -205,12 +230,11 @@ export type ReadRollingCapUsageOptions = {
   readonly windowDays: number;
 };
 
-// Sums usage without throwing — for callers that only need the raw number
-// (e.g. a CapSpec.usage callback), not the enforce-and-throw path.
-export async function readRollingCapUsage(
+async function sumRollingEventAmounts(
   db: TenantDb,
   tenantId: TenantId,
   options: ReadRollingCapUsageOptions,
+  type: string,
 ): Promise<number> {
   const aggregateId = rollingCapAggregateId(tenantId, options.capName);
   const cutoff = Temporal.Now.instant().subtract({ hours: options.windowDays * 24 });
@@ -219,20 +243,37 @@ export async function readRollingCapUsage(
     tenantId,
     aggregateType: CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
     aggregateId,
-    type: ROLLING_INCREMENTED_EVENT_QN,
+    type,
     createdAt: { gte: cutoff },
   });
 
-  let value = 0;
+  let total = 0;
   for (const row of rows) {
     // @cast-boundary engine-payload — events.payload is jsonb (typed as
     // unknown by drizzle's $type<Record<string,unknown>>); narrowing the
     // shape here mirrors enforceRollingCap's own read-side contract.
     const payload = row["payload"] as { amount?: number };
     if (typeof payload.amount === "number") {
-      value += payload.amount;
+      total += payload.amount;
     }
   }
+  return total;
+}
 
-  return value;
+// Sums usage without throwing — for callers that only need the raw number
+// (e.g. a CapSpec.usage callback), not the enforce-and-throw path.
+// Incremented minus released amounts inside the window; a release whose increment already left the window cannot push it below 0.
+export async function readRollingCapUsage(
+  db: TenantDb,
+  tenantId: TenantId,
+  options: ReadRollingCapUsageOptions,
+): Promise<number> {
+  const incremented = await sumRollingEventAmounts(
+    db,
+    tenantId,
+    options,
+    ROLLING_INCREMENTED_EVENT_QN,
+  );
+  const released = await sumRollingEventAmounts(db, tenantId, options, ROLLING_RELEASED_EVENT_QN);
+  return Math.max(0, incremented - released);
 }