@cosmicdrift/kumiko-samples 0.388.0 → 0.390.0

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

@@ -15,6 +15,7 @@ import type {
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
   assertNotificationVariables,
+  attachOutsideTransaction,
   bridgeStub,
   createSystemUser,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -98,7 +99,7 @@ export type DeliveryServiceOptions = {
   // inline delivery (job-less setups, unit tests).
   readonly jobRunner?: NotifyJobDispatcher;
   // Credentials source for inline-delivered chat channels (webhook URL / bot
-  // token). Jobs get ctx.secrets from the job runner instead.
+  // token). Jobs get ctx.services.secrets from the job runner instead.
   readonly secrets?: SecretsContext;
   // Seals the recipient address inside queued job payloads (tenant scope). Absent means the
   // payload carries the plaintext address.
@@ -277,7 +278,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       sink: escapeHatchAuditSink,
       log: logError,
     });
-    // ctx.db/dbOutsideTransaction are tenant-filtered even for a systemScope handler:
+    // ctx.db/db.outsideTransaction are tenant-filtered even for a systemScope handler:
     // the dispatcher closes them off entirely there, so "system" mode would hand this
     // path a cross-tenant read the dispatcher never allows. Cross-tenant reach only
     // exists through the grant-carrying systemDb view below.
@@ -299,6 +300,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           db: run.db,
           tenantId,
           mode: "system",
+          reason: "delivery fan-out of a systemScope handler resolves recipients across tenants",
           grants: {
             report,
             unsafeRaw: { reason: `r.systemScope() handler "${tenantUserIdsQuery}"` },
@@ -306,13 +308,12 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
         })
       : undefined;
     // Hand-built context, not routed through the dispatcher — this needs both
-    // db and dbOutsideTransaction wired directly.
+    // db (with its outsideTransaction) wired directly.
     // @cast-boundary engine-payload — generic query-handler return for typed convention
     return (await handler.handler(
       { type: tenantUserIdsQuery, payload: { tenantId }, user: systemUser },
       {
-        db: tenantDb,
-        dbOutsideTransaction: tenantDb,
+        db: attachOutsideTransaction(tenantDb, tenantDb),
         systemDb: systemDbSourceTenantDb
           ? createSystemDbView(systemDbSourceTenantDb, undefined, report)
           : undefined,

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

@@ -62,6 +62,7 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
   const resolvedAccess = options?.access ?? access.admin;
   const attemptLogRetentionDays = resolveAttemptLogRetentionDays(options?.attemptLogRetentionDays);
   return defineFeature("delivery", (r) => {
+    r.adoptsBundledLists();
     r.describe(
       "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (the `runProdApp` and `runDevApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. An app serving its own (e.g. legacy) unsubscribe links renders the same result page with `renderUnsubscribeResultPage({ kind, locale })`. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.",
     );
@@ -205,10 +206,10 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
             const pruned = await runAttemptLogRetention(db, {
               olderThanDays: attemptLogRetentionDays,
             });
-            ctx.log.info("delivery attempt log pruned", pruned);
+            ctx.obs.log.info("delivery attempt log pruned", pruned);
           } catch (error) {
             if (!(error instanceof ConsumerLagError)) throw error;
-            ctx.log.warn("delivery attempt log retention postponed: an event consumer lags", {
+            ctx.obs.log.warn("delivery attempt log retention postponed: an event consumer lags", {
               consumer: error.laggingConsumer,
             });
           }

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

@@ -73,6 +73,11 @@ export {
 } from "./handlers/unsubscribe-address.write.ts";
 export { currentNotificationType } from "./notification-type-aliases.ts";
 export { createDeliveryNotifyFactory } from "./notify-factory.ts";
+export {
+  buildSystemChannelContext,
+  type SystemChannelContextDeps,
+  type SystemChannelContextOptions,
+} from "./system-channel-context.ts";
 export {
   deliveryAttemptsTable,
   notificationAddressOptOutEntity,

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

@@ -150,21 +150,21 @@ function entryFor(
   };
 }
 
-// Assumes ctx.redis is the handle the service claimed on; runProdApp wires the same
+// Assumes ctx.services.redis is the handle the service claimed on; runProdApp wires the same
 // instance into both.
 async function releaseIdempotencyKey(ctx: JobContext, p: RenderJobPayload): Promise<void> {
   // skip: no idempotency key was claimed for this notification
   if (!p.idempotencyKey) return;
-  if (!ctx.redis) {
-    ctx.log.warn("delivery: idempotency key not released, job context has no redis", {
+  if (!ctx.services.redis) {
+    ctx.obs.log.warn("delivery: idempotency key not released, job context has no redis", {
       notificationType: p.notificationType,
     });
     return;
   }
   try {
-    await ctx.redis.del(deliveryIdempotencyRedisKey(p.tenantId, p.idempotencyKey));
+    await ctx.services.redis.del(deliveryIdempotencyRedisKey(p.tenantId, p.idempotencyKey));
   } catch (err) {
-    ctx.log.warn(`delivery: idempotency key release failed: ${redactedMessageOf(err)}`, {
+    ctx.obs.log.warn(`delivery: idempotency key release failed: ${redactedMessageOf(err)}`, {
       notificationType: p.notificationType,
     });
   }
@@ -206,7 +206,7 @@ async function addressForAttemptLog(
     return await openRecipientAddress(
       p,
       p.tenantId as TenantId, // @cast-boundary engine-payload — job payload string is the stream tenant
-      ctx.configEncryption,
+      ctx.services.configEncryption,
     );
   } catch {
     return null;
@@ -225,7 +225,7 @@ async function failAttempt(
   err: unknown,
 ): Promise<never> {
   const message = redactedMessageOf(err);
-  ctx.log.error(`delivery.${p.channelName} ${code}: ${message}`, {
+  ctx.obs.log.error(`delivery.${p.channelName} ${code}: ${message}`, {
     notificationType: p.notificationType,
     channel: p.channelName,
   });
@@ -255,7 +255,7 @@ async function renderStep(p: RenderJobPayload, ctx: JobContext): Promise<void> {
     registry,
     undefined,
     tenantId,
-    ctx.secrets,
+    ctx.services.secrets,
     ctx.config,
     (fileTenantId) => fileContextForTenant(ctx, ctx.systemUser.tenantId, fileTenantId),
   );
@@ -270,7 +270,7 @@ async function renderStep(p: RenderJobPayload, ctx: JobContext): Promise<void> {
     return failAttempt(ctx, db, registry, p, "render_failed", err);
   }
   try {
-    const jobRunner = ctx["jobRunner"] as JobRunner; // @cast-boundary dynamic-key — dispatch lives on the concrete runner
+    const jobRunner = ctx.services.jobRunner as JobRunner; // @cast-boundary engine-bridge — dispatch lives on the concrete runner
     await jobRunner.dispatch(
       DeliveryJobs.send,
       { ...p, rendered: toSendRendered(rendered) },
@@ -298,13 +298,13 @@ async function sendStep(p: z.infer<typeof sendJobPayloadSchema>, ctx: JobContext
     registry,
     undefined,
     tenantId,
-    ctx.secrets,
+    ctx.services.secrets,
     ctx.config,
     (fileTenantId) => fileContextForTenant(ctx, ctx.systemUser.tenantId, fileTenantId),
   );
 
   try {
-    const address = await openRecipientAddress(p, tenantId, ctx.configEncryption);
+    const address = await openRecipientAddress(p, tenantId, ctx.services.configEncryption);
     const result = await channel.send(address, toMessage(p), channelCtx, p.rendered);
     await appendAttemptEvent(
       db,

package/packages/bundled-features/src/delivery/system-channel-context.ts

@@ -0,0 +1,33 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { ConfigAccessor, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { buildChannelContext } from "./channel-context.ts";
+import type { ChannelContext } from "./types.ts";
+
+export type SystemChannelContextDeps = {
+  readonly db: DbConnection;
+  readonly registry: Registry;
+  readonly filesForTenant: (tenantId: string) => FileContext | undefined;
+};
+
+export type SystemChannelContextOptions = {
+  readonly config?: ConfigAccessor;
+  readonly secrets?: SecretsContext;
+};
+
+export function buildSystemChannelContext(
+  deps: SystemChannelContextDeps,
+  options: SystemChannelContextOptions = {},
+): ChannelContext {
+  return buildChannelContext(
+    deps.db,
+    deps.registry,
+    undefined,
+    SYSTEM_TENANT_ID,
+    options.secrets,
+    options.config,
+    deps.filesForTenant,
+  );
+}

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

@@ -25,7 +25,7 @@ export type CreateDeliveryTestContextOptions = {
   readonly log?: Logger;
   readonly jobRunner?: JobRunner;
   readonly secrets?: SecretsContext;
-  // Seals queued job payload addresses and, like the boot wiring, doubles as the jobs' ctx.configEncryption.
+  // Seals queued job payload addresses and, like the boot wiring, doubles as the jobs' ctx.services.configEncryption.
   readonly addressCipher?: EnvelopeCipher;
   readonly idempotencyRedis?: Redis;
   readonly filesForTenant?: (tenantId: string) => FileContext | undefined;

package/packages/bundled-features/src/document-ingest-foundation/append-missing-extract-event.ts

@@ -0,0 +1,84 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry, SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  appendEventInTenantDb,
+  getStreamVersionInTenantDb,
+} from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  DOCUMENT_EXTRACT_AGGREGATE_TYPE,
+  documentExtractFailedPayloadSchema,
+  documentExtractReadyPayloadSchema,
+} from "./events.ts";
+
+export type ExistingDocumentExtract = {
+  readonly id: string;
+  readonly meta: { readonly error?: unknown } | null;
+};
+
+export type AppendMissingExtractEventDeps = {
+  readonly tenantDb: TenantDb;
+  readonly registry: Registry;
+  readonly actor: SessionUser;
+  readonly tenantId: string;
+};
+
+export type AppendMissingExtractEventOptions = {
+  readonly readyEventQn: string;
+  readonly failedEventQn: string;
+  readonly mapError?: (error: string) => string;
+};
+
+export type AppendMissingExtractEventResult =
+  | "appended-ready"
+  | "appended-failed"
+  | "already-terminal";
+
+// Version 1 of the stream is the extract's created event; anything beyond it is the terminal event.
+const CREATED_ONLY_STREAM_VERSION = 1;
+const UNKNOWN_EXTRACT_ERROR = "unknown extract error";
+
+// A previous delivery created the extract but died before appending its ready/failed event.
+// Without the event, consumers waiting on it hang forever.
+export async function appendMissingDocumentExtractEvent(
+  deps: AppendMissingExtractEventDeps,
+  existing: ExistingDocumentExtract,
+  fileRefId: string,
+  options: AppendMissingExtractEventOptions,
+): Promise<AppendMissingExtractEventResult> {
+  if (deps.tenantDb.tenantId !== deps.tenantId) {
+    throw new InternalError({
+      message: `document-ingest-foundation: tenantDb is bound to tenant ${deps.tenantDb.tenantId}, not ${deps.tenantId}`,
+    });
+  }
+  const version = await getStreamVersionInTenantDb(deps.tenantDb, existing.id);
+  // A missing stream means a wrong id; appending would make the terminal event the first event of a new stream.
+  if (version === 0) {
+    throw new InternalError({
+      message: `document-ingest-foundation: no document extract stream for id ${existing.id}`,
+    });
+  }
+  // skip: the terminal event was already written, nothing to catch up
+  if (version > CREATED_ONLY_STREAM_VERSION) return "already-terminal";
+  const metaError = existing.meta?.error;
+  const failed = typeof metaError === "string";
+  await appendEventInTenantDb(
+    deps.tenantDb,
+    {
+      aggregateId: existing.id,
+      aggregateType: DOCUMENT_EXTRACT_AGGREGATE_TYPE,
+      expectedVersion: version,
+      type: failed ? options.failedEventQn : options.readyEventQn,
+      payload: failed
+        ? documentExtractFailedPayloadSchema.parse({
+            documentExtractId: existing.id,
+            fileRefId,
+            error: options.mapError?.(metaError) || metaError || UNKNOWN_EXTRACT_ERROR,
+          })
+        : documentExtractReadyPayloadSchema.parse({ documentExtractId: existing.id, fileRefId }),
+      metadata: { userId: deps.actor.id },
+    },
+    { registry: deps.registry },
+  );
+  return failed ? "appended-failed" : "appended-ready";
+}

package/packages/bundled-features/src/document-ingest-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "appendMissingDocumentExtractEvent and shared ready/failed payload schemas",
+    "detail": "A provider whose job died after creating the extract calls appendMissingDocumentExtractEvent(deps, existing, fileRefId, { readyEventQn, failedEventQn, mapError }) to append the missing terminal event; it returns appended-ready, appended-failed or already-terminal. documentExtractReadyPayloadSchema and documentExtractFailedPayloadSchema are exported so providers register their own event names with the shared payload shape."
+  },
   {
     "version": "0.379.0",
     "type": "fix",

package/packages/bundled-features/src/document-ingest-foundation/events.ts

@@ -14,7 +14,7 @@ export const DOCUMENT_EXTRACT_AGGREGATE_TYPE = "document-extract";
 
 export const DOCUMENT_INGEST_REQUESTED_EVENT_SHORT = "documentIngest.requested" as const;
 
-// Qualified name — what ctx.unsafeAppendEvent's `type` actually needs
+// Qualified name — what ctx.events.unsafeAppend's `type` actually needs
 // (r.defineEvent registers under qn(toKebab(feature), "event",
 // toKebab(shortName)); appendEvent looks up the registry by QN, not the
 // short name — see MSP-apply "event not registered" error otherwise).
@@ -47,3 +47,18 @@ export const documentIngestSkippedPayloadSchema = z.object({
   reason: z.enum(["file-too-large", "unsupported-mime-type"]),
 });
 export type DocumentIngestSkippedPayload = z.infer<typeof documentIngestSkippedPayloadSchema>;
+
+// Terminal events of a document-extract stream. The QNs belong to the provider that registers
+// them; the foundation only owns the shared payload shape.
+export const documentExtractReadyPayloadSchema = z.object({
+  documentExtractId: z.string().min(1),
+  fileRefId: z.string().min(1),
+});
+export type DocumentExtractReadyPayload = z.infer<typeof documentExtractReadyPayloadSchema>;
+
+export const documentExtractFailedPayloadSchema = z.object({
+  documentExtractId: z.string().min(1),
+  fileRefId: z.string().min(1),
+  error: z.string().min(1),
+});
+export type DocumentExtractFailedPayload = z.infer<typeof documentExtractFailedPayloadSchema>;

package/packages/bundled-features/src/document-ingest-foundation/index.ts

@@ -1,6 +1,13 @@
 // Public API of the document-ingest-foundation bundled-feature.
 
 export { documentIngestAggregateId } from "./aggregate-id.ts";
+export {
+  type AppendMissingExtractEventDeps,
+  type AppendMissingExtractEventOptions,
+  type AppendMissingExtractEventResult,
+  appendMissingDocumentExtractEvent,
+  type ExistingDocumentExtract,
+} from "./append-missing-extract-event.ts";
 export {
   type DocumentExtractMeta,
   documentExtractEntity,
@@ -14,8 +21,12 @@ export {
   DOCUMENT_INGEST_REQUESTED_EVENT_SHORT,
   DOCUMENT_INGEST_SKIPPED_EVENT_QN,
   DOCUMENT_INGEST_SKIPPED_EVENT_SHORT,
+  type DocumentExtractFailedPayload,
+  type DocumentExtractReadyPayload,
   type DocumentIngestRequestedPayload,
   type DocumentIngestSkippedPayload,
+  documentExtractFailedPayloadSchema,
+  documentExtractReadyPayloadSchema,
   documentIngestRequestedPayloadSchema,
   documentIngestSkippedPayloadSchema,
 } from "./events.ts";

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

@@ -44,6 +44,7 @@ export function createFeatureTogglesFeature(
   options: FeatureTogglesOptions = {},
 ): FeatureDefinition {
   return defineFeature("feature-toggles", (r) => {
+    r.adoptsBundledLists();
     r.describe(
       'Persists per-feature enabled/disabled state in the `store_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: "shared"` syncs the snapshot across instances whenever a `toggle-set` event is appended.',
     );

package/packages/bundled-features/src/feature-toggles/handlers/registered.query.ts

@@ -43,7 +43,7 @@ export const registeredQuery = defineQueryHandler({
     // The per-tenant signature requires SYSTEM_TENANT_ID; the app resolver
     // returns the union of all tier features. The sentinel convention is
     // documented in DispatcherOptions.effectiveFeatures.
-    const effective = ctx.effectiveFeatures?.(SYSTEM_TENANT_ID);
+    const effective = ctx.services.effectiveFeatures?.(SYSTEM_TENANT_ID);
 
     const rows: Array<{
       id: string;

package/packages/bundled-features/src/feature-toggles/handlers/set.write.ts

@@ -160,7 +160,7 @@ export function createSetWriteHandler(getRuntime: (() => GlobalFeatureToggleRunt
       // its config-changed events.
       // unsafeAppendEvent: the strict appendEvent is bound to an app's own event map, which
       // bundled-features cannot see. Schema validation still runs via r.defineEvent("toggle-set", ...).
-      await ctx.unsafeAppendEvent({
+      await ctx.events.unsafeAppend({
         aggregateId: SYSTEM_TENANT_ID,
         aggregateType: FEATURE_TOGGLE_AGGREGATE_TYPE,
         type: FEATURE_TOGGLE_SET_EVENT_NAME,

package/packages/bundled-features/src/feature-toggles/toggle-sync-signal.ts

@@ -52,7 +52,7 @@ export function createRedisToggleSyncSignal(
     onMessage(listener) {
       signal.onMessage((_channel, payload) => {
         if (!isTogglePayload(payload)) {
-          // biome-ignore lint/suspicious/noConsole: ops-visible fallback — no ctx.log in a raw PubSubSignal handler.
+          // biome-ignore lint/suspicious/noConsole: ops-visible fallback — no ctx.obs.log in a raw PubSubSignal handler.
           console.error(
             `[kumiko:feature-toggles] dropping malformed cache-sync message on "${toggleSyncChannel}"`,
           );

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

@@ -53,7 +53,7 @@ export type FileDerivativesOptions = {
    *  Without this option, neither the httpRoute NOR the `publicVariant`
    *  query is registered — it is unreachable via the httpRoute path and via
    *  the generic `/api` query dispatch. Existing consumers that only need
-   *  `ctx.derivatives` are unaffected. See {@link PublicVariantResolveApexTenant}
+   *  `ctx.services.derivatives` are unaffected. See {@link PublicVariantResolveApexTenant}
    *  for the in-memory/sync contract. */
   readonly resolveApexTenant?: PublicVariantResolveApexTenant;
   /** Base path of the public variant route. Default "/media". */
@@ -104,7 +104,7 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
     FEATURE_NAME,
     (r) => {
       r.describe(
-        "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) depends on the server's `trustedProxyHops` matching the deployment's actual reverse-proxy count — at the default 0 it ignores `x-forwarded-for` entirely, so every caller shares one bucket until that's configured. `publicTenantResolution: \"fileRef\"` keeps resolveApexTenant as the host gate but reads the variant from the FileRef row's own tenant instead of the host's, so one shared platform host serves every tenant's public variants — each FileRef-tenant's own `isPublic` predicate still default-denies. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.",
+        "Declares the `derivativeRenderer` extension point. `ctx.services.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) depends on the server's `trustedProxyHops` matching the deployment's actual reverse-proxy count — at the default 0 it ignores `x-forwarded-for` entirely, so every caller shares one bucket until that's configured. `publicTenantResolution: \"fileRef\"` keeps resolveApexTenant as the host gate but reads the variant from the FileRef row's own tenant instead of the host's, so one shared platform host serves every tenant's public variants — each FileRef-tenant's own `isPublic` predicate still default-denies. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.",
       );
       r.uiHints({
         displayLabel: "File Derivatives",

package/packages/bundled-features/src/file-derivatives/handlers/public-variant-by-file-ref.query.ts

@@ -52,6 +52,10 @@ export const publicVariantByFileRefQuery = defineQueryHandler({
     const tenant = await fetchOne<TenantGateRow>(db, tenantTable, { id: row.tenantId });
     if (!tenant || !isTenantServingPublicContent(tenant)) return null;
 
-    return ctx.queryAs(createAnonymousUser(row.tenantId), PUBLIC_VARIANT_QN, query.payload);
+    return ctx.dispatch.queryAs(
+      createAnonymousUser(row.tenantId),
+      PUBLIC_VARIANT_QN,
+      query.payload,
+    );
   },
 });

package/packages/bundled-features/src/file-derivatives/handlers/public-variant.query.ts

@@ -18,7 +18,7 @@
 // consumer's `resolverTrust`/anonymousAccess setup, not the host.
 //
 // In `publicTenantResolution: "fileRef"` mode, this handler is also the
-// `ctx.queryAs(createAnonymousUser(fileRefTenantId), ...)` target of
+// `ctx.dispatch.queryAs(createAnonymousUser(fileRefTenantId), ...)` target of
 // publicVariantByFileRefQuery — tenantId there comes from the FileRef row,
 // but this handler's own isPublic gate runs exactly the same either way.
 
@@ -133,14 +133,16 @@ export const publicVariantQuery = defineQueryHandler({
     );
     if (!isPublic) return null;
 
-    // ctx.files/ctx.derivatives are optional on HandlerContext (only wired
+    // ctx.services.files/ctx.services.derivatives are optional on HandlerContext (only wired
     // when file-foundation resolved a provider) — narrow via a plain guard,
     // never `!`/`as`, and surface a real config error (not a silent deny)
     // when the feature isn't actually wired.
-    const { files, derivatives } = ctx;
+    const {
+      services: { files, derivatives },
+    } = ctx;
     if (!files || !derivatives) {
       throw new Error(
-        "file-derivatives requires ctx.files/ctx.derivatives — is file-foundation mounted?",
+        "file-derivatives requires ctx.services.files/ctx.services.derivatives — is file-foundation mounted?",
       );
     }
 
@@ -151,7 +153,7 @@ export const publicVariantQuery = defineQueryHandler({
 
     // ponytail: fully buffered (no streaming), +33% over the wire from
     // base64 — HttpRouteHandlerDeps only exposes {app, systemQuery} (no
-    // direct ctx.files access from the Hono handler itself), and the local
+    // direct ctx.services.files access from the Hono handler itself), and the local
     // dev storage provider has no getSignedUrl (a redirect design wouldn't
     // work in dev). Upgrade path: a binary-passthrough dispatcher primitive
     // would be its own, larger issue.

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

@@ -4,7 +4,7 @@
 // extension point + the per-tenant `provider` config key. Provider RESOLUTION
 // (createFileProviderForTenant) + the plugin types now live in the framework
 // (packages/framework/src/files/provider-resolver.ts) so the upload routes,
-// `ctx.files` and the GDPR jobs resolve through ONE path — uploads, export and
+// `ctx.services.files` and the GDPR jobs resolve through ONE path — uploads, export and
 // erasure hit the same store by construction. This feature re-exports the moved
 // symbols unchanged so existing imports keep working.
 //

package/packages/bundled-features/src/file-foundation/read-file-ref-content.ts

@@ -22,19 +22,21 @@ type FileRefRow = {
   readonly size: number | bigint | string;
 };
 
-// Tenant-bound on purpose: without a resolver `ctx.files` only reaches the storage of the
+// Tenant-bound on purpose: without a resolver `ctx.services.files` only reaches the storage of the
 // context's own tenant (`contextTenantId`), so a request for another tenant's files is
 // undefined instead of silently reading through the wrong tenant's storage.
 export function fileContextForTenant(
   ctx: {
-    readonly _fileProviderResolver?: FileProviderResolver | undefined;
-    readonly files?: FileContext | undefined;
+    readonly services: {
+      readonly _fileProviderResolver?: FileProviderResolver | undefined;
+      readonly files?: FileContext | undefined;
+    };
   },
   contextTenantId: string,
   tenantId: string,
 ): FileContext | undefined {
-  const resolver = ctx._fileProviderResolver;
-  if (resolver === undefined) return tenantId === contextTenantId ? ctx.files : undefined;
+  const resolver = ctx.services._fileProviderResolver;
+  if (resolver === undefined) return tenantId === contextTenantId ? ctx.services.files : undefined;
   return fileContextFromResolver(resolver, tenantId);
 }
 

package/packages/bundled-features/src/file-provider-s3/feature.ts

@@ -201,7 +201,10 @@ async function buildS3Provider(
 }
 
 async function readSecretAccessKey(ctx: FileProviderContext, tenantId: string): Promise<string> {
-  const secrets = requireSecretsContext(ctx, FEATURE_NAME);
+  const secrets = requireSecretsContext(
+    { secrets: ctx.secrets, auditUserId: ctx.auditUserId },
+    FEATURE_NAME,
+  );
   const branded = await secrets.get(tenantId, S3_SECRET_ACCESS_KEY);
   return requireSecretSet(branded, FEATURE_NAME, S3_SECRET_ACCESS_KEY.name).reveal();
 }

package/packages/bundled-features/src/files-tenant-data/handlers/sweep-orphaned-derivatives.job.ts

@@ -56,9 +56,9 @@ export async function sweepOrphanedDerivativesJob(
   db: DbConnection,
 ): Promise<void> {
   const payload = sweepOrphanedDerivativesPayloadSchema.parse(rawPayload ?? {});
-  const maybeResolver = ctx._fileProviderResolver;
+  const maybeResolver = ctx.services._fileProviderResolver;
   if (!maybeResolver) {
-    ctx.log?.warn(
+    ctx.obs.log?.warn(
       "[files-tenant-data:sweep] no _fileProviderResolver wired — nothing to sweep, skipping run",
     );
     return;
@@ -96,7 +96,7 @@ export async function sweepOrphanedDerivativesJob(
         try {
           provider = await resolver(tenantId);
         } catch (err) {
-          ctx.log?.warn?.(
+          ctx.obs.log?.warn?.(
             `[files-tenant-data:sweep] no file provider resolvable for tenant=${tenantId}, skipping: ${err instanceof Error ? err.message : String(err)}`,
           );
           continue;
@@ -105,7 +105,7 @@ export async function sweepOrphanedDerivativesJob(
         try {
           keys = await provider.list(`${tenantId}/`);
         } catch (err) {
-          ctx.log?.warn?.(
+          ctx.obs.log?.warn?.(
             `[files-tenant-data:sweep] provider.list() failed for tenant=${tenantId}, skipping: ${err instanceof Error ? err.message : String(err)}`,
           );
           continue;
@@ -140,7 +140,7 @@ export async function sweepOrphanedDerivativesJob(
       { limit: 1 },
     );
     if (owners.length > 0) return "skipped";
-    // Binaries written through ctx.files.ref(key) (and their derive()d
+    // Binaries written through ctx.services.files.ref(key) (and their derive()d
     // variants) never get a fileRef row; an original still sitting in storage
     // means the derivative is not an orphan.
     if (await candidate.provider.exists(candidate.originalKey)) return "skipped";
@@ -158,15 +158,15 @@ export async function sweepOrphanedDerivativesJob(
     migrateRow,
     maxFailures,
     deadlineAt: deadline,
-    signal: ctx.signal,
+    signal: ctx.lifecycle.signal,
     onRowError: (candidate, err) => {
-      ctx.log?.warn?.(
+      ctx.obs.log?.warn?.(
         `[files-tenant-data:sweep] failed to delete key=${candidate.key} tenant=${candidate.tenantId}: ${err instanceof Error ? err.message : String(err)}`,
       );
     },
   });
 
-  ctx.log?.info?.(
+  ctx.obs.log?.info?.(
     `[files-tenant-data:sweep] complete dryRun=${dryRun} deleted=${outcome.migrated} wouldDelete=${dryRunWouldDelete} skipped=${outcome.skipped} failed=${outcome.failed} batches=${outcome.batchesProcessed} stoppedReason=${outcome.stoppedReason}`,
   );
 }

package/packages/bundled-features/src/form-draft/feature.ts

@@ -27,7 +27,7 @@ function registerFormDraft(r: FeatureRegistrar<typeof FORM_DRAFT_FEATURE_NAME>):
   });
 
   // config is optional: the retention-days key only resolves when the
-  // config feature is mounted (ctx.configResolver present) — the cleanup
+  // config feature is mounted (ctx.services.configResolver present) — the cleanup
   // job already falls back to FORM_DRAFT_DEFAULT_RETENTION_DAYS otherwise
   // (see handlers/cleanup.job.ts). A hard r.requires({ features: ["config"] }) would break
   // every app that mounts form-draft without config, which is a breaking