@cosmicdrift/kumiko-samples 0.404.0 → 0.405.0

package/packages/bundled-features/src/auth-mfa/mfa-challenge-token.ts

@@ -1,23 +1,21 @@
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
-import { createHmacTokenCodec, type HmacTokenVerifyResult } from "./hmac-token-codec.ts";
+import {
+  createHmacTokenCodec,
+  type HmacTokenVerifyResult,
+  isUserTenantPayload,
+} from "./hmac-token-codec.ts";
 
 export type MfaChallengePayload = {
   readonly userId: string;
   readonly tenantId: TenantId;
 };
 
-function isPayload(value: unknown): value is MfaChallengePayload {
-  if (!isPlainObject(value)) return false;
-  return typeof value["userId"] === "string" && typeof value["tenantId"] === "string";
-}
-
 // Domain-separated from mfa-preauth-setup (see hmac-token-codec). Single-use is
 // enforced by the consumer via burnToken (purpose "mfa-challenge"); this codec
 // only signs and verifies. Brute-forcing the code behind a valid token is
 // limited separately in mfa-verify-attempts.ts.
-const codec = createHmacTokenCodec("mfa-challenge", isPayload);
+const codec = createHmacTokenCodec("mfa-challenge", isUserTenantPayload);
 
 export function signMfaChallengeToken(
   payload: MfaChallengePayload,

package/packages/bundled-features/src/auth-mfa/mfa-preauth-setup-token.ts

@@ -1,22 +1,20 @@
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
-import { createHmacTokenCodec, type HmacTokenVerifyResult } from "./hmac-token-codec.ts";
+import {
+  createHmacTokenCodec,
+  type HmacTokenVerifyResult,
+  isUserTenantPayload,
+} from "./hmac-token-codec.ts";
 
 export type MfaPreauthSetupPayload = {
   readonly userId: string;
   readonly tenantId: TenantId;
 };
 
-function isPayload(value: unknown): value is MfaPreauthSetupPayload {
-  if (!isPlainObject(value)) return false;
-  return typeof value["userId"] === "string" && typeof value["tenantId"] === "string";
-}
-
 // Domain "mfa-preauth-setup" must never equal the challenge domain: a setup
 // token has to fail verification as a challenge token and vice versa. The
 // challenge token secret is reused deliberately; the domain carries the separation.
-const codec = createHmacTokenCodec("mfa-preauth-setup", isPayload);
+const codec = createHmacTokenCodec("mfa-preauth-setup", isUserTenantPayload);
 
 export function signMfaPreauthSetupToken(
   payload: MfaPreauthSetupPayload,

package/packages/bundled-features/src/auth-mfa/mfa-setup-token.ts

@@ -6,12 +6,10 @@
 // the same response — the token exists to avoid a second round-trip to
 // regenerate it, not to hide it.
 //
-// Format: <base64url(JSON body)>.<hmac-base64url>. Distinct from
-// signed-token.ts (userId-only payload) because setup needs to carry
-// generated secret material, not just re-derive it from a lookup.
-import { createHmac, timingSafeEqual } from "node:crypto";
+// Wire format and signing live in hmac-token-codec.ts.
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { createHmacTokenCodec, type HmacTokenVerifyResult } from "./hmac-token-codec.ts";
 
 export type MfaSetupPayload = {
   readonly userId: string;
@@ -24,73 +22,34 @@ export type MfaSetupPayload = {
   readonly tenantId?: string;
 };
 
-type EncodedBody = MfaSetupPayload & { readonly expiresAtMs: number };
-
-function sign(input: string, secret: string): string {
-  return createHmac("sha256", secret).update(input).digest("base64url");
+function isMfaSetupPayload(value: unknown): value is MfaSetupPayload {
+  if (!isPlainObject(value)) return false;
+  return (
+    typeof value["userId"] === "string" &&
+    typeof value["totpSecretBase32"] === "string" &&
+    Array.isArray(value["recoveryCodeHashes"]) &&
+    value["recoveryCodeHashes"].every((h) => typeof h === "string") &&
+    (value["tenantId"] === undefined || typeof value["tenantId"] === "string")
+  );
 }
 
+const codec = createHmacTokenCodec("mfa-setup", isMfaSetupPayload);
+
 export function signMfaSetupToken(
   payload: MfaSetupPayload,
   ttlMinutes: number,
   secret: string,
   now: Temporal.Instant = Temporal.Now.instant(),
 ): { token: string; expiresAt: Temporal.Instant } {
-  const expiresAt = now.add({ minutes: ttlMinutes });
-  const body: EncodedBody = { ...payload, expiresAtMs: expiresAt.epochMilliseconds };
-  const bodyB64 = Buffer.from(JSON.stringify(body)).toString("base64url");
-  const signature = sign(`mfa-setup:${bodyB64}`, secret);
-  return { token: `${bodyB64}.${signature}`, expiresAt };
+  return codec.sign(payload, ttlMinutes, secret, now);
 }
 
-export type VerifyMfaSetupResult =
-  | { readonly ok: true; readonly payload: MfaSetupPayload; readonly expiresAtMs: number }
-  | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
-
-function isEncodedBody(value: unknown): value is EncodedBody {
-  if (!isPlainObject(value)) return false;
-  return (
-    typeof value["userId"] === "string" &&
-    typeof value["totpSecretBase32"] === "string" &&
-    Array.isArray(value["recoveryCodeHashes"]) &&
-    value["recoveryCodeHashes"].every((h) => typeof h === "string") &&
-    typeof value["expiresAtMs"] === "number" &&
-    (value["tenantId"] === undefined || typeof value["tenantId"] === "string")
-  );
-}
+export type VerifyMfaSetupResult = HmacTokenVerifyResult<MfaSetupPayload>;
 
 export function verifyMfaSetupToken(
   token: string,
   secret: string,
   now: Temporal.Instant = Temporal.Now.instant(),
 ): VerifyMfaSetupResult {
-  const parts = token.split(".");
-  if (parts.length !== 2) return { ok: false, reason: "malformed" };
-  const [bodyB64, providedSig] = parts;
-  if (!bodyB64 || !providedSig) return { ok: false, reason: "malformed" };
-
-  const expected = sign(`mfa-setup:${bodyB64}`, secret);
-  const expectedBuf = Buffer.from(expected, "base64url");
-  const providedBuf = Buffer.from(providedSig, "base64url");
-  // Length check before timingSafeEqual — a length mismatch throws inside
-  // timingSafeEqual, and that throw is itself a timing signal.
-  if (expectedBuf.length !== providedBuf.length) return { ok: false, reason: "bad_signature" };
-  if (!timingSafeEqual(expectedBuf, providedBuf)) return { ok: false, reason: "bad_signature" };
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(Buffer.from(bodyB64, "base64url").toString("utf8"));
-  } catch {
-    return { ok: false, reason: "malformed" };
-  }
-  if (!isEncodedBody(parsed)) return { ok: false, reason: "malformed" };
-
-  if (
-    Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(parsed.expiresAtMs)) > 0
-  ) {
-    return { ok: false, reason: "expired" };
-  }
-
-  const { expiresAtMs, ...payload } = parsed;
-  return { ok: true, payload, expiresAtMs };
+  return codec.verify(token, secret, now);
 }

package/packages/bundled-features/src/billing-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "Provider helpers shared through billing-foundation",
+    "detail": "billing-foundation exports validateOneOffPriceIds, parseStoredSecret, createTtlPriceCache and hasSeenProviderEvent. subscription-stripe and subscription-paddle use them instead of their own copies, with the same error texts as before. The subscription projection reuses one apply body for created/updated and one for canceled/invoice-paid; the exported apply names stay."
+  },
   {
     "version": "0.399.0",
     "type": "improvement",

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

@@ -3,7 +3,7 @@
 // The anonymous handler only routes to the declaration's tenant; the system
 // handler checks the token and does the work.
 
-import { createHash, timingSafeEqual } from "node:crypto";
+import { hashOpaqueTokenSync, opaqueTokenHashMatches } from "@cosmicdrift/kumiko-framework/crypto";
 import {
   access,
   createSystemUser,
@@ -45,17 +45,7 @@ export function createRevocationToken(): { readonly token: string; readonly toke
   const token = Buffer.from(crypto.getRandomValues(new Uint8Array(TOKEN_BYTES))).toString(
     "base64url",
   );
-  return { token, tokenHash: hashRevocationToken(token) };
-}
-
-function hashRevocationToken(token: string): string {
-  return createHash("sha256").update(token).digest("hex");
-}
-
-function tokenMatchesHash(token: string, expectedHash: string): boolean {
-  const actual = Buffer.from(hashRevocationToken(token));
-  const expected = Buffer.from(expectedHash);
-  return actual.length === expected.length && timingSafeEqual(actual, expected);
+  return { token, tokenHash: hashOpaqueTokenSync(token) };
 }
 
 export function revocationUrl(args: {
@@ -154,7 +144,7 @@ export function createRecordContractTerminationRevocationHandler(
         .find((candidate) => candidate?.requestId === payload.requestId);
       if (
         declared?.revocationTokenHash === undefined ||
-        !tokenMatchesHash(payload.token, declared.revocationTokenHash)
+        !opaqueTokenHashMatches(payload.token, declared.revocationTokenHash)
       ) {
         return outcome("invalid");
       }

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

@@ -200,11 +200,7 @@ export function createBillingFoundationFeature<TTier extends string = string>(
       });
 
       // Plugin extension point. Provider plugins register here.
-      r.extendsRegistrar(SUBSCRIPTION_PROVIDER_EXTENSION, {
-        onRegister: () => {
-          // No side-effects at register-time.
-        },
-      });
+      r.extendsRegistrar(SUBSCRIPTION_PROVIDER_EXTENSION, {});
 
       // Custom write handlers:
       //   - process-event: programmatic entry point called by the webhook

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

@@ -33,6 +33,7 @@ import {
   type SubscriptionEventPayload,
 } from "../events.ts";
 import { getSubscriptionForTenant, type SubscriptionView } from "../get-subscription-for-tenant.ts";
+import { hasSeenProviderEvent } from "../provider-event-seen.ts";
 import {
   BILLING_SUBSCRIPTION_LOCK_NAMESPACE,
   isSubscriptionBlockingCheckout,
@@ -176,14 +177,7 @@ export async function appendSubscriptionEvent(
   //    idempotency anchor (like cap-counter).
   // ---------------------------------------------------------------
   const existingEvents = await ctx.events.load(aggId);
-  const alreadySeen = existingEvents.some((e) => {
-    const headers = e.metadata.headers ?? {};
-    return (
-      headers["providerEventId"] === payload.providerEventId &&
-      headers["providerName"] === payload.providerName
-    );
-  });
-  if (alreadySeen) {
+  if (hasSeenProviderEvent(existingEvents, payload)) {
     return { duplicate: true, subscriptionAggregateId: aggId };
   }
 

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

@@ -24,6 +24,7 @@ import {
   type PaymentEventHeaders,
   type PaymentEventPayload,
 } from "../events.ts";
+import { hasSeenProviderEvent } from "../provider-event-seen.ts";
 
 export const processPaymentEventSchema = z.object({
   providerEventId: z.string().min(1).max(200),
@@ -57,14 +58,7 @@ export const processPaymentEventHandler: WriteHandlerDef = {
     //    optimize via a per-tenant providerEventId-index if that bites).
     // ---------------------------------------------------------------
     const existingEvents = await ctx.events.load(aggId);
-    const alreadySeen = existingEvents.some((e) => {
-      const headers = e.metadata.headers ?? {};
-      return (
-        headers["providerEventId"] === payload.providerEventId &&
-        headers["providerName"] === payload.providerName
-      );
-    });
-    if (alreadySeen) {
+    if (hasSeenProviderEvent(existingEvents, payload)) {
       return {
         isSuccess: true as const,
         data: { duplicate: true as const, paymentAggregateId: aggId },

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

@@ -46,6 +46,14 @@ export {
 export { createBillingFoundationFeature } from "./feature.ts";
 export { getSubscriptionForTenant, type SubscriptionView } from "./get-subscription-for-tenant.ts";
 export { paymentsProjectionTable, subscriptionsProjectionTable } from "./projection.ts";
+export { hasSeenProviderEvent } from "./provider-event-seen.ts";
+export {
+  createTtlPriceCache,
+  parseStoredSecret,
+  type TtlPriceCache,
+  type TtlPriceCacheOptions,
+  validateOneOffPriceIds,
+} from "./provider-shared.ts";
 export { billingPlansPanel, createBillingPlansScreen } from "./screens.ts";
 export {
   createSubscriptionTierSync,

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

@@ -130,43 +130,12 @@ async function upsert(
 // materialize the row correctly.
 // =============================================================================
 
-/** subscription-created → UPSERT with all fields. PK = aggregateId =
- *  subscriptionAggregateId(tenantId), with one row per tenant. UPSERT allows
- *  the Disney+-change pattern (a second provider sends create for the same
- *  tenant) to overwrite the existing row instead of causing a PK conflict. */
-export const applySubscriptionCreated = defineApply<SubscriptionEventPayload>(async (event, tx) => {
-  const full = fullSetFromPayload(event.payload);
-  await upsert(tx, event, { ...full, ...cancelAtSetFromPayload(event.payload) }, event.payload);
-});
-
-/** subscription-updated → UPSERT with all fields. */
-export const applySubscriptionUpdated = defineApply<SubscriptionEventPayload>(async (event, tx) => {
+const applyFullSubscriptionState = defineApply<SubscriptionEventPayload>(async (event, tx) => {
   const full = fullSetFromPayload(event.payload);
   await upsert(tx, event, { ...full, ...cancelAtSetFromPayload(event.payload) }, event.payload);
 });
 
-/** subscription-canceled → status/tier/currentPeriodEnd patchen. */
-export const applySubscriptionCanceled = defineApply<SubscriptionEventPayload>(
-  async (event, tx) => {
-    const p = event.payload;
-    await upsert(
-      tx,
-      event,
-      {
-        status: p.status,
-        tier: p.tier,
-        currentPeriodEnd: p.currentPeriodEndIso,
-        ...cancelAtSetFromPayload(p),
-      },
-      p,
-    );
-  },
-);
-
-/** invoice-paid → state update (status, tier, currentPeriodEnd).
- *  The invoice history itself lives in the event store, so it remains
- *  replayable. */
-export const applyInvoicePaid = defineApply<SubscriptionEventPayload>(async (event, tx) => {
+const applyStatusTierPeriodPatch = defineApply<SubscriptionEventPayload>(async (event, tx) => {
   const p = event.payload;
   await upsert(
     tx,
@@ -181,6 +150,23 @@ export const applyInvoicePaid = defineApply<SubscriptionEventPayload>(async (eve
   );
 });
 
+/** subscription-created → UPSERT with all fields. PK = aggregateId =
+ *  subscriptionAggregateId(tenantId), with one row per tenant. UPSERT allows
+ *  the Disney+-change pattern (a second provider sends create for the same
+ *  tenant) to overwrite the existing row instead of causing a PK conflict. */
+export const applySubscriptionCreated = applyFullSubscriptionState;
+
+/** subscription-updated → UPSERT with all fields. */
+export const applySubscriptionUpdated = applyFullSubscriptionState;
+
+/** subscription-canceled → status/tier/currentPeriodEnd patchen. */
+export const applySubscriptionCanceled = applyStatusTierPeriodPatch;
+
+/** invoice-paid → state update (status, tier, currentPeriodEnd).
+ *  The invoice history itself lives in the event store, so it remains
+ *  replayable. */
+export const applyInvoicePaid = applyStatusTierPeriodPatch;
+
 /** invoice-payment-failed → status (typically past_due) + tier. The tier
  *  engine reads the row and decides whether to downgrade. currentPeriodEnd is
  *  intentionally unchanged: the period has not "ended"; payment simply

package/packages/bundled-features/src/billing-foundation/provider-event-seen.ts

@@ -0,0 +1,14 @@
+import type { StoredEvent } from "@cosmicdrift/kumiko-framework/event-store";
+
+export function hasSeenProviderEvent(
+  existingEvents: readonly Pick<StoredEvent, "metadata">[],
+  providerEvent: { readonly providerEventId: string; readonly providerName: string },
+): boolean {
+  return existingEvents.some((e) => {
+    const headers = e.metadata.headers ?? {};
+    return (
+      headers["providerEventId"] === providerEvent.providerEventId &&
+      headers["providerName"] === providerEvent.providerName
+    );
+  });
+}

package/packages/bundled-features/src/billing-foundation/provider-shared.ts

@@ -0,0 +1,61 @@
+import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
+
+export function validateOneOffPriceIds(providerLabel: string, priceIds: readonly string[]): void {
+  const seen = new Set<string>();
+  for (const priceId of priceIds) {
+    if (priceId.length === 0) {
+      throw new Error(`${providerLabel}: oneOffPriceIds must not contain an empty string`);
+    }
+    if (seen.has(priceId)) {
+      throw new Error(`${providerLabel}: duplicate oneOffPriceIds entry "${priceId}"`);
+    }
+    seen.add(priceId);
+  }
+}
+
+// backing:"secrets" values are stored JSON-serialized, so the store read has to
+// be parsed back; the env fallback is a plain string and stays raw. The error
+// must not carry the input: the JSON parser's own message would repeat the
+// credential into logs and, for webhooks, into the 401 body.
+export function parseStoredSecret(
+  providerLabel: string,
+  raw: string | undefined,
+): string | undefined {
+  if (raw === undefined || raw.length === 0) return undefined;
+  const parsed = parseJsonSafe<unknown>(raw, undefined);
+  if (parsed === undefined) {
+    throw new Error(`${providerLabel} credential (backing:secrets) is not valid JSON`);
+  }
+  return typeof parsed === "string" && parsed.length > 0 ? parsed : undefined;
+}
+
+export type TtlPriceCache<TPrice> = {
+  readonly get: (priceId: string) => TPrice | undefined;
+  readonly set: (priceId: string, price: TPrice) => void;
+};
+
+export type TtlPriceCacheOptions = {
+  readonly ttlMs?: number;
+  readonly now: () => number;
+};
+
+export function createTtlPriceCache<TPrice>({
+  ttlMs = 600_000,
+  now,
+}: TtlPriceCacheOptions): TtlPriceCache<TPrice> {
+  const store = new Map<string, { readonly price: TPrice; readonly expiresAt: number }>();
+  return {
+    get: (priceId) => {
+      const entry = store.get(priceId);
+      if (!entry) return undefined;
+      if (entry.expiresAt <= now()) {
+        store.delete(priceId);
+        return undefined;
+      }
+      return entry.price;
+    },
+    set: (priceId, price) => {
+      store.set(priceId, { price, expiresAt: now() + ttlMs });
+    },
+  };
+}

package/packages/bundled-features/src/billing-foundation/tenant-destroy-hook.ts

@@ -1,6 +1,10 @@
 import { declareEscapeHatch, type TenantDataHookCtx } from "@cosmicdrift/kumiko-framework/engine";
 import { archiveStream } from "@cosmicdrift/kumiko-framework/event-store";
 import { resolveProfileForTenant } from "../compliance-profiles/index.ts";
+import {
+  TENANT_DESTROY_ARCHIVE_REASON,
+  TENANT_DESTROY_ARCHIVED_BY,
+} from "../tenant-lifecycle/index.ts";
 import { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id.ts";
 import { PAYMENT_AGGREGATE_TYPE, SUBSCRIPTION_AGGREGATE_TYPE } from "./events.ts";
 import { paymentsProjectionMeta, subscriptionsProjectionMeta } from "./projection.ts";
@@ -42,8 +46,8 @@ export async function subscriptionTenantDestroyHook(ctx: TenantDataHookCtx): Pro
     tenantId: ctx.tenantId,
     aggregateId,
     aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
-    archivedBy: "tenant-lifecycle:destroy",
-    reason: "tenant_destroy",
+    archivedBy: TENANT_DESTROY_ARCHIVED_BY,
+    reason: TENANT_DESTROY_ARCHIVE_REASON,
   });
 }
 
@@ -74,7 +78,7 @@ export async function paymentTenantDestroyHook(ctx: TenantDataHookCtx): Promise<
     tenantId: ctx.tenantId,
     aggregateId,
     aggregateType: PAYMENT_AGGREGATE_TYPE,
-    archivedBy: "tenant-lifecycle:destroy",
-    reason: "tenant_destroy",
+    archivedBy: TENANT_DESTROY_ARCHIVED_BY,
+    reason: TENANT_DESTROY_ARCHIVE_REASON,
   });
 }

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

@@ -25,7 +25,7 @@ export function createChannelEmailFeature(options: EmailChannelOptions) {
     r.envSchema(smtpEnvSchema);
 
     r.translations({ keys: { "delivery.channel.email": { en: "Email" } } });
-    r.extendsRegistrar(EMAIL_APP_TRANSPORT_EXTENSION, { onRegister: () => {} });
+    r.extendsRegistrar(EMAIL_APP_TRANSPORT_EXTENSION, {});
     r.useExtension(EMAIL_APP_TRANSPORT_EXTENSION, EMAIL_APP_TRANSPORT_USAGE, {
       transport: appTransport,
     });

package/packages/bundled-features/src/config/handlers/reencrypt.job.ts

@@ -28,7 +28,6 @@ import {
   createSystemDbView,
   createTenantDb,
   type DbConnection,
-  type TenantDb,
   type UncheckedSystemDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import {
@@ -43,6 +42,7 @@ import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 import {
   type ChunkedMigrationStopReason,
   classifyStoredEnvelope,
+  createTenantDbCache,
   runChunkedMigration,
 } from "../../shared/index.ts";
 import { configValueEntity, configValuesTable } from "../table.ts";
@@ -121,20 +121,14 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
     });
   }
 
-  const tdbCache = new Map<TenantId, TenantDb>();
-  function tdbFor(tenantId: TenantId): TenantDb {
-    let existing = tdbCache.get(tenantId);
-    if (!existing) {
-      existing = createTenantDb({
-        db,
-        tenantId,
-        mode: "system",
-        reason: "KEK rotation job re-encrypts config values of every tenant",
-      });
-      tdbCache.set(tenantId, existing);
-    }
-    return existing;
-  }
+  const tdbFor = createTenantDbCache((tenantId) =>
+    createTenantDb({
+      db,
+      tenantId,
+      mode: "system",
+      reason: "KEK rotation job re-encrypts config values of every tenant",
+    }),
+  );
 
   const sdbCache = new Map<TenantId, UncheckedSystemDb>();
   function sdbFor(tenantId: TenantId): UncheckedSystemDb {

package/packages/bundled-features/src/delivery/delivery-service.ts

@@ -33,7 +33,7 @@ import type { EnvelopeCipher, SecretsContext } from "@cosmicdrift/kumiko-framewo
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import type { Redis } from "ioredis";
 import { fileContextFromResolver } from "../file-foundation/index.ts";
-import { redactErrorText } from "../shared/index.ts";
+import { collectExtensionOptions, redactErrorText } from "../shared/index.ts";
 import { hashUnsubscribeAddress } from "./address-opt-out.ts";
 import { appendAttemptEvent, logAttempt } from "./attempt-log.ts";
 import { buildChannelContext } from "./channel-context.ts";
@@ -120,15 +120,7 @@ export type DeliveryServiceOptions = {
 
 // Build channel list from registry extension usages
 export function collectChannels(registry: Registry): DeliveryChannel[] {
-  const usages = registry.getExtensionUsages(DELIVERY_CHANNEL_EXTENSION);
-  return usages.map((usage) => {
-    if (!isDeliveryChannelPlugin(usage.options)) {
-      throw new Error(
-        `${DELIVERY_CHANNEL_EXTENSION} registration for "${usage.entityName}" has invalid options`,
-      );
-    }
-    return { name: usage.entityName, ...usage.options };
-  });
+  return collectExtensionOptions(registry, DELIVERY_CHANNEL_EXTENSION, isDeliveryChannelPlugin);
 }
 
 export function createDeliveryService(options: DeliveryServiceOptions): DeliveryService {

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

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "0.404.1",
+    "type": "fix",
+    "title": "Documents recipe has a README and gen-sample-index rejects a primarySample without one",
+    "detail": "feature-reference linked to /en/samples/recipes-documents/, a page the docs site never generated because the recipe had no README.md. The README is added, and gen-sample-index aborts with the feature, the sample and the fix when a primarySample from sample-index.overrides.json has no README.md."
+  }
+]

package/packages/bundled-features/src/file-derivatives/feature.ts

@@ -120,27 +120,15 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
       // time variant() runs.
       r.requires({ features: ["files"] });
 
-      r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, {
-        onRegister: () => {
-          // No side-effects at register-time — resolution (exact MIME match,
-          // then `<type>/*` wildcard) happens at request-time in
-          // resolveRenderer, mirrors file-foundation's fileProvider point.
-        },
-      });
-      r.extendsRegistrar(EXT_DERIVATIVE_PUBLIC_PREDICATE, {
-        onRegister: () => {
-          // No side-effects at register-time — resolution happens at
-          // request-time in publicVariantQuery, keyed by the FileRef's
-          // entityType.
-        },
-      });
-      r.extendsRegistrar(EXT_DERIVATIVE_OVERLAY_RESOLVER, {
-        onRegister: () => {
-          // No side-effects at register-time — resolution happens in
-          // variant(), keyed by the FileRef's entityType, before the spec
-          // hash is computed.
-        },
-      });
+      // Resolution (exact MIME match, then `<type>/*` wildcard) happens at request-time in
+      // resolveRenderer, mirrors file-foundation's fileProvider point.
+      r.extendsRegistrar(EXT_DERIVATIVE_RENDERER, {});
+      // Resolution happens at request-time in publicVariantQuery, keyed by the FileRef's
+      // entityType.
+      r.extendsRegistrar(EXT_DERIVATIVE_PUBLIC_PREDICATE, {});
+      // Resolution happens in variant(), keyed by the FileRef's entityType, before the spec
+      // hash is computed.
+      r.extendsRegistrar(EXT_DERIVATIVE_OVERLAY_RESOLVER, {});
 
       // Registered ONLY when resolveApexTenant is supplied — r.queryHandler
       // registers publicVariantQuery into the feature's dispatch table as a

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

@@ -54,12 +54,8 @@ export function createFileFoundationFeature() {
       });
       r.requires({ features: ["config"] });
 
-      r.extendsRegistrar(EXT_FILE_PROVIDER, {
-        onRegister: () => {
-          // No side-effects at register-time — registry stores the usage,
-          // factory looks it up at request-time.
-        },
-      });
+      // Registry stores the usage, factory looks it up at request-time.
+      r.extendsRegistrar(EXT_FILE_PROVIDER, {});
 
       const providerConfigKey = r.config(
         "provider",

package/packages/bundled-features/src/files-tenant-data/hooks.ts

@@ -62,6 +62,7 @@ import {
   storageKeyStemPrefix,
   tenantStoragePrefixes,
 } from "@cosmicdrift/kumiko-framework/files";
+import { chunk } from "@cosmicdrift/kumiko-framework/utils";
 import { type ChunkedMigrationResult, runChunkedMigration } from "../shared/index.ts";
 
 const crud = createEventStoreExecutor(fileRefsTable, fileRefEntity, { entityName: "fileRef" });
@@ -73,12 +74,6 @@ const SURVIVOR_CHECK_BATCH_SIZE = 500;
 
 const DESTROY_CHUNK_SIZE = 500;
 
-function chunk<T>(items: readonly T[], size: number): T[][] {
-  const chunks: T[][] = [];
-  for (let i = 0; i < items.length; i += size) chunks.push(items.slice(i, i + size));
-  return chunks;
-}
-
 function isUnderOwnPrefix(storageKey: string, prefixes: readonly string[]): boolean {
   return prefixes.some((prefix) => storageKey.startsWith(prefix));
 }