@cosmicdrift/kumiko-bundled-features 0.388.0 → 0.390.0

package/dist/document-ingest-foundation/append-missing-extract-event.js

@@ -0,0 +1,42 @@
+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.js";
+// 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, existing, fileRefId, options) {
+    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/dist/document-ingest-foundation/events.d.ts

@@ -26,3 +26,14 @@ export declare const documentIngestSkippedPayloadSchema: z.ZodObject<{
     }>;
 }, z.core.$strip>;
 export type DocumentIngestSkippedPayload = z.infer<typeof documentIngestSkippedPayloadSchema>;
+export declare const documentExtractReadyPayloadSchema: z.ZodObject<{
+    documentExtractId: z.ZodString;
+    fileRefId: z.ZodString;
+}, z.core.$strip>;
+export type DocumentExtractReadyPayload = z.infer<typeof documentExtractReadyPayloadSchema>;
+export declare const documentExtractFailedPayloadSchema: z.ZodObject<{
+    documentExtractId: z.ZodString;
+    fileRefId: z.ZodString;
+    error: z.ZodString;
+}, z.core.$strip>;
+export type DocumentExtractFailedPayload = z.infer<typeof documentExtractFailedPayloadSchema>;

package/dist/document-ingest-foundation/events.js

@@ -10,7 +10,7 @@ export const DOCUMENT_INGEST_AGGREGATE_TYPE = "document-ingest";
 // "documentExtract", so the projection replays this stream through an extension.
 export const DOCUMENT_EXTRACT_AGGREGATE_TYPE = "document-extract";
 export const DOCUMENT_INGEST_REQUESTED_EVENT_SHORT = "documentIngest.requested";
-// 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).
@@ -35,3 +35,14 @@ export const documentIngestSkippedPayloadSchema = z.object({
     size: z.number().int().min(0),
     reason: z.enum(["file-too-large", "unsupported-mime-type"]),
 });
+// 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 const documentExtractFailedPayloadSchema = z.object({
+    documentExtractId: z.string().min(1),
+    fileRefId: z.string().min(1),
+    error: z.string().min(1),
+});

package/dist/document-ingest-foundation/index.d.ts

@@ -1,6 +1,7 @@
 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, documentExtractsTable, type IngestPage, } from "./entity.ts";
-export { DOCUMENT_EXTRACT_AGGREGATE_TYPE, DOCUMENT_INGEST_AGGREGATE_TYPE, DOCUMENT_INGEST_REQUESTED_EVENT_QN, DOCUMENT_INGEST_REQUESTED_EVENT_SHORT, DOCUMENT_INGEST_SKIPPED_EVENT_QN, DOCUMENT_INGEST_SKIPPED_EVENT_SHORT, type DocumentIngestRequestedPayload, type DocumentIngestSkippedPayload, documentIngestRequestedPayloadSchema, documentIngestSkippedPayloadSchema, } from "./events.ts";
+export { DOCUMENT_EXTRACT_AGGREGATE_TYPE, DOCUMENT_INGEST_AGGREGATE_TYPE, DOCUMENT_INGEST_REQUESTED_EVENT_QN, 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";
 export { createDocumentIngestFoundationFeature } from "./feature.ts";
 export { readIngestPages, writeIngestPages } from "./pages.ts";
 export { type DocumentIngestProviderOptions, documentIngestProviderOptionsSchema, documentIngestProviderTrigger, EXT_DOCUMENT_INGEST_PROVIDER, listIngestibleMimeTypes, type ResolvedDocumentIngestProvider, resolveDocumentIngestProviders, } from "./providers.ts";

package/dist/document-ingest-foundation/index.js

@@ -1,7 +1,8 @@
 // Public API of the document-ingest-foundation bundled-feature.
 export { documentIngestAggregateId } from "./aggregate-id.js";
+export { appendMissingDocumentExtractEvent, } from "./append-missing-extract-event.js";
 export { documentExtractEntity, documentExtractsTable, } from "./entity.js";
-export { DOCUMENT_EXTRACT_AGGREGATE_TYPE, DOCUMENT_INGEST_AGGREGATE_TYPE, DOCUMENT_INGEST_REQUESTED_EVENT_QN, DOCUMENT_INGEST_REQUESTED_EVENT_SHORT, DOCUMENT_INGEST_SKIPPED_EVENT_QN, DOCUMENT_INGEST_SKIPPED_EVENT_SHORT, documentIngestRequestedPayloadSchema, documentIngestSkippedPayloadSchema, } from "./events.js";
+export { DOCUMENT_EXTRACT_AGGREGATE_TYPE, DOCUMENT_INGEST_AGGREGATE_TYPE, DOCUMENT_INGEST_REQUESTED_EVENT_QN, DOCUMENT_INGEST_REQUESTED_EVENT_SHORT, DOCUMENT_INGEST_SKIPPED_EVENT_QN, DOCUMENT_INGEST_SKIPPED_EVENT_SHORT, documentExtractFailedPayloadSchema, documentExtractReadyPayloadSchema, documentIngestRequestedPayloadSchema, documentIngestSkippedPayloadSchema, } from "./events.js";
 export { createDocumentIngestFoundationFeature } from "./feature.js";
 export { readIngestPages, writeIngestPages } from "./pages.js";
 export { documentIngestProviderOptionsSchema, documentIngestProviderTrigger, EXT_DOCUMENT_INGEST_PROVIDER, listIngestibleMimeTypes, resolveDocumentIngestProviders, } from "./providers.js";

package/dist/feature-toggles/feature.js

@@ -8,6 +8,7 @@ import { FEATURE_TOGGLES_I18N } from "./i18n.js";
 import { FEATURE_TOGGLE_SET_EVENT_NAME, FeatureToggleHandlers, FeatureToggleQueries, TOGGLE_ADMIN_SCREEN_ID, } from "./web/constants.js";
 export function createFeatureTogglesFeature(options = {}) {
     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.');
         r.uiHints({
             displayLabel: "Feature Toggles · Operator Switches",

package/dist/feature-toggles/handlers/registered.query.js

@@ -35,7 +35,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 = [];
         for (const feature of ctx.registry.features.values()) {
             const toggleable = feature.toggleableDefault !== undefined;

package/dist/feature-toggles/handlers/set.write.js

@@ -111,7 +111,7 @@ export function createSetWriteHandler(getRuntime) {
             // 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/dist/feature-toggles/toggle-sync-signal.js

@@ -28,7 +28,7 @@ export function createRedisToggleSyncSignal(redisUrl, clientOptions, channelPref
         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}"`);
                     // skip: malformed message already logged above, nothing to apply
                     return;

package/dist/file-derivatives/feature.d.ts

@@ -10,7 +10,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". */

package/dist/file-derivatives/feature.js

@@ -45,7 +45,7 @@ export function createFileDerivativesFeature(opts = {}) {
         throw new Error("createFileDerivativesFeature: publicTenantResolution requires resolveApexTenant — it only changes which tenant a variant is read from, resolveApexTenant still gates the host.");
     }
     return defineFeature(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.");
+        r.describe("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",
             category: "storage",

package/dist/file-derivatives/handlers/public-variant-by-file-ref.query.js

@@ -30,6 +30,6 @@ export const publicVariantByFileRefQuery = defineQueryHandler({
         const tenant = await fetchOne(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/dist/file-derivatives/handlers/public-variant.query.js

@@ -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.
 import { computeRevisionEtag } from "@cosmicdrift/kumiko-framework/api";
@@ -87,13 +87,13 @@ export const publicVariantQuery = defineQueryHandler({
         }, ctx);
         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?");
+            throw new Error("file-derivatives requires ctx.services.files/ctx.services.derivatives — is file-foundation mounted?");
         }
         const spec = resolveFieldVariant(ctx.registry, entityType, fieldName, query.payload.variant);
         if (!spec)
@@ -102,7 +102,7 @@ export const publicVariantQuery = defineQueryHandler({
         const bytes = await files.refFromFileRef(result).read();
         // 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/dist/file-foundation/feature.js

@@ -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/dist/file-foundation/read-file-ref-content.d.ts

@@ -7,8 +7,10 @@ export type FileRefContent = {
     readonly size: number;
 };
 export declare 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;
 export declare function fileContextFromResolver(resolver: FileProviderResolver, tenantId: string): FileContext;
 export declare class FileRefTooLargeError extends Error {

package/dist/file-foundation/read-file-ref-content.js

@@ -1,13 +1,13 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { isUuid } from "@cosmicdrift/kumiko-framework/engine";
 import { createTenantFileContext, fileRefsTable, } from "@cosmicdrift/kumiko-framework/files";
-// 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, contextTenantId, tenantId) {
-    const resolver = ctx._fileProviderResolver;
+    const resolver = ctx.services._fileProviderResolver;
     if (resolver === undefined)
-        return tenantId === contextTenantId ? ctx.files : undefined;
+        return tenantId === contextTenantId ? ctx.services.files : undefined;
     return fileContextFromResolver(resolver, tenantId);
 }
 export function fileContextFromResolver(resolver, tenantId) {

package/dist/file-provider-s3/feature.js

@@ -127,7 +127,7 @@ async function buildS3Provider(ctx, tenantId) {
     });
 }
 async function readSecretAccessKey(ctx, tenantId) {
-    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/dist/files-tenant-data/handlers/sweep-orphaned-derivatives.job.js

@@ -34,9 +34,9 @@ export const sweepOrphanedDerivativesPayloadSchema = z.object({
 });
 export async function sweepOrphanedDerivativesJob(rawPayload, ctx, db) {
     const payload = sweepOrphanedDerivativesPayloadSchema.parse(rawPayload ?? {});
-    const maybeResolver = ctx._fileProviderResolver;
+    const maybeResolver = ctx.services._fileProviderResolver;
     if (!maybeResolver) {
-        ctx.log?.warn("[files-tenant-data:sweep] no _fileProviderResolver wired — nothing to sweep, skipping run");
+        ctx.obs.log?.warn("[files-tenant-data:sweep] no _fileProviderResolver wired — nothing to sweep, skipping run");
         return;
     }
     const resolver = maybeResolver;
@@ -65,7 +65,7 @@ export async function sweepOrphanedDerivativesJob(rawPayload, ctx, db) {
                     provider = await resolver(tenantId);
                 }
                 catch (err) {
-                    ctx.log?.warn?.(`[files-tenant-data:sweep] no file provider resolvable for tenant=${tenantId}, skipping: ${err instanceof Error ? err.message : String(err)}`);
+                    ctx.obs.log?.warn?.(`[files-tenant-data:sweep] no file provider resolvable for tenant=${tenantId}, skipping: ${err instanceof Error ? err.message : String(err)}`);
                     continue;
                 }
                 let keys;
@@ -73,7 +73,7 @@ export async function sweepOrphanedDerivativesJob(rawPayload, ctx, db) {
                     keys = await provider.list(`${tenantId}/`);
                 }
                 catch (err) {
-                    ctx.log?.warn?.(`[files-tenant-data:sweep] provider.list() failed for tenant=${tenantId}, skipping: ${err instanceof Error ? err.message : String(err)}`);
+                    ctx.obs.log?.warn?.(`[files-tenant-data:sweep] provider.list() failed for tenant=${tenantId}, skipping: ${err instanceof Error ? err.message : String(err)}`);
                     continue;
                 }
                 for (const key of keys) {
@@ -99,7 +99,7 @@ export async function sweepOrphanedDerivativesJob(rawPayload, ctx, db) {
         const owners = await selectMany(db, fileRefsTable, { tenantId: candidate.tenantId, storageKey: candidate.originalKey }, { 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))
@@ -117,10 +117,10 @@ export async function sweepOrphanedDerivativesJob(rawPayload, ctx, db) {
         migrateRow,
         maxFailures,
         deadlineAt: deadline,
-        signal: ctx.signal,
+        signal: ctx.lifecycle.signal,
         onRowError: (candidate, err) => {
-            ctx.log?.warn?.(`[files-tenant-data:sweep] failed to delete key=${candidate.key} tenant=${candidate.tenantId}: ${err instanceof Error ? err.message : String(err)}`);
+            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?.(`[files-tenant-data:sweep] complete dryRun=${dryRun} deleted=${outcome.migrated} wouldDelete=${dryRunWouldDelete} skipped=${outcome.skipped} failed=${outcome.failed} batches=${outcome.batchesProcessed} stoppedReason=${outcome.stoppedReason}`);
+    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/dist/form-draft/feature.js

@@ -20,7 +20,7 @@ function registerFormDraft(r) {
         recommended: false,
     });
     // 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

package/dist/form-draft/handlers/cleanup.job.js

@@ -37,7 +37,12 @@ async function releaseRowFileRefs(row, db, fileProviderResolver, log) {
     const isCreateMode = row.draftKey.includes(":new:");
     const ownedRefs = await filterOwnedFileRefs(db, row.tenantId, row.ownerId, keys, row.insertedAt, isCreateMode);
     const systemUser = createSystemUser(row.tenantId);
-    const tenantDb = createTenantDb({ db, tenantId: row.tenantId, mode: "system" });
+    const tenantDb = createTenantDb({
+        db,
+        tenantId: row.tenantId,
+        mode: "system",
+        reason: "stale-draft cleanup job removes drafts of each tenant, outside any request scope",
+    });
     for (const ref of ownedRefs) {
         const forgetResult = await fileRefExecutor.forget({ id: ref.id }, systemUser, tenantDb);
         if (!forgetResult.isSuccess) {
@@ -79,7 +84,12 @@ export async function deleteStaleDraftsBatch(batch, db, retentionDays, log) {
     const byId = new Map(batch.map((row) => [row.id, row]));
     for (const [tenantId, ids] of groupStaleDraftIdsByTenant(batch)) {
         const systemUser = createSystemUser(tenantId);
-        const tenantDb = createTenantDb({ db, tenantId, mode: "system" });
+        const tenantDb = createTenantDb({
+            db,
+            tenantId,
+            mode: "system",
+            reason: "stale-draft cleanup job removes drafts of each tenant, outside any request scope",
+        });
         for (const id of ids) {
             // skip: an unreadable blob hides its FileRefs; deleting now would orphan them, so the next run retries.
             if (byId.get(id)?.draftUnreadable) {
@@ -106,22 +116,22 @@ export async function deleteStaleDraftsBatch(batch, db, retentionDays, log) {
     return { deletedRows, skippedCount, deferredIds };
 }
 export async function cleanupDraftsJob(_payload, ctx, db) {
-    const resolved = ctx.configResolver
-        ? await ctx.configResolver.get(FORM_DRAFT_RETENTION_DAYS_CONFIG_KEY, formDraftRetentionDaysConfig, SYSTEM_TENANT_ID, SYSTEM_USER_ID, db)
+    const resolved = ctx.services.configResolver
+        ? await ctx.services.configResolver.get(FORM_DRAFT_RETENTION_DAYS_CONFIG_KEY, formDraftRetentionDaysConfig, SYSTEM_TENANT_ID, SYSTEM_USER_ID, db)
         : undefined;
     const isValidRetention = typeof resolved === "number" && resolved >= 1;
     // configResolver missing is the legitimate no-config case (r.optionalRequires,
     // see feature.ts) — nothing to warn about there. A resolver that IS wired but
     // returns something unusable means an admin set an invalid value.
-    if (ctx.configResolver && !isValidRetention) {
-        ctx.log?.warn?.(`[form-draft:cleanup] configResolver returned invalid retention-days value=${String(resolved)} — falling back to default=${FORM_DRAFT_DEFAULT_RETENTION_DAYS}`);
+    if (ctx.services.configResolver && !isValidRetention) {
+        ctx.obs.log?.warn?.(`[form-draft:cleanup] configResolver returned invalid retention-days value=${String(resolved)} — falling back to default=${FORM_DRAFT_DEFAULT_RETENTION_DAYS}`);
     }
     const retentionDays = isValidRetention ? resolved : FORM_DRAFT_DEFAULT_RETENTION_DAYS;
-    const fileProviderResolver = ctx._fileProviderResolver;
+    const fileProviderResolver = ctx.services._fileProviderResolver;
     let deleted = 0;
     const deferred = new Set();
     while (true) {
-        if (ctx.signal?.aborted)
+        if (ctx.lifecycle.signal?.aborted)
             break;
         const batch = await selectStaleDraftsBatch(db, retentionDays, DEFAULT_BATCH_SIZE, [
             ...deferred,
@@ -129,17 +139,17 @@ export async function cleanupDraftsJob(_payload, ctx, db) {
         if (batch.length === 0)
             break;
         // Rows span arbitrary tenants (this job sweeps the whole table under
-        // SYSTEM_TENANT_ID, not per-tenant) — ctx.files is resolved for a single
+        // SYSTEM_TENANT_ID, not per-tenant) — ctx.services.files is resolved for a single
         // tenant per job run and would be wrong here, so each row resolves its
         // own tenant's provider via _fileProviderResolver instead. Skipped
         // entirely for rows with no FileRefs in the blob, the common case.
         // Delete first (with staleness re-check), then release binaries from rows
         // that actually disappeared — never release a draft the user just saved.
-        const { deletedRows, skippedCount, deferredIds } = await deleteStaleDraftsBatch(batch, db, retentionDays, ctx.log);
+        const { deletedRows, skippedCount, deferredIds } = await deleteStaleDraftsBatch(batch, db, retentionDays, ctx.obs.log);
         for (const id of deferredIds)
             deferred.add(id);
         for (const row of deletedRows) {
-            await releaseRowFileRefs(row, db, fileProviderResolver, ctx.log);
+            await releaseRowFileRefs(row, db, fileProviderResolver, ctx.obs.log);
         }
         deleted += deletedRows.length;
         // A skipped row is no longer stale, so the next select drops it — a fully
@@ -149,5 +159,5 @@ export async function cleanupDraftsJob(_payload, ctx, db) {
             batch.length < DEFAULT_BATCH_SIZE)
             break;
     }
-    ctx.log?.info?.(`[form-draft:cleanup] deleted=${deleted} retentionDays=${retentionDays}`);
+    ctx.obs.log?.info?.(`[form-draft:cleanup] deleted=${deleted} retentionDays=${retentionDays}`);
 }

package/dist/form-draft/handlers/discard.write.js

@@ -47,7 +47,7 @@ export const discardDraftWrite = defineWriteHandler({
         // releaseFiles: a successful-submit discard must NOT release — the
         // domain entity the submit just wrote carries the same storageKeys
         // forward (see schemas.ts comment on discardDraftPayloadSchema).
-        const files = ctx.files;
+        const files = ctx.services.files;
         if (files && event.payload.releaseFiles === true) {
             const candidateKeys = collectDraftFileRefKeys(existing.draft);
             // Only storageKeys with a real file_refs row owned by THIS caller are
@@ -72,8 +72,8 @@ export const discardDraftWrite = defineWriteHandler({
             // Binary delete only after commit — in-tx delete would orphan pointers
             // if the surrounding write transaction rolls back after this handler.
             const keys = ownedRefs.map((ref) => ref.storageKey);
-            const log = ctx.log;
-            const schedule = ctx.scheduleAfterCommit;
+            const log = ctx.obs.log;
+            const schedule = ctx.lifecycle.afterCommit;
             const release = async () => {
                 await releaseDraftFileRefs(keys, async (key) => {
                     await files.refFromFileRef({ storageKey: key }).delete();

package/dist/form-draft/handlers/get.query.js

@@ -18,7 +18,7 @@ export const getDraftQuery = defineQueryHandler({
         if (!row.draft) {
             // Schema evolution or a corrupt/erased row: surface it to operators
             // instead of silently making the user's draft vanish.
-            ctx.log?.warn?.(`[form-draft:get] stored blob for draftKey=${query.payload.draftKey} failed schema or decryption, treating as absent`);
+            ctx.obs.log?.warn?.(`[form-draft:get] stored blob for draftKey=${query.payload.draftKey} failed schema or decryption, treating as absent`);
             return { draft: null };
         }
         return { draft: row.draft };

package/dist/foundation-shared/config-helpers.d.ts

@@ -34,7 +34,7 @@ export declare function requireDefined<T>(value: T | undefined, featureName: str
  */
 export declare function requireNonEmpty(value: string | undefined, featureName: string, label: string, uiHint?: string): string;
 /**
- * Narrow a `ctx.secrets.get()` result → set secret. The secrets-counterpart
+ * Narrow a `ctx.services.secrets.get()` result → set secret. The secrets-counterpart
  * to requireNonEmpty: a missing secret is a tenant-configuration gap, not a
  * crash — same 422 contract, so clients route to the settings screen.
  *

package/dist/foundation-shared/config-helpers.js

@@ -68,7 +68,7 @@ export function requireNonEmpty(value, featureName, label, uiHint = "Set via ten
     return trimmed;
 }
 /**
- * Narrow a `ctx.secrets.get()` result → set secret. The secrets-counterpart
+ * Narrow a `ctx.services.secrets.get()` result → set secret. The secrets-counterpart
  * to requireNonEmpty: a missing secret is a tenant-configuration gap, not a
  * crash — same 422 contract, so clients route to the settings screen.
  *

package/dist/host-routing/validate-options.js

@@ -11,6 +11,9 @@ function validateRedirects(options) {
         if (!REDIRECT_PATH_PATTERN.test(rule.from)) {
             throw new Error(`host-routing: redirect from must be a path like "/old", got "${rule.from}"`);
         }
+        if (rule.from === "/api" || rule.from.startsWith("/api/")) {
+            throw new Error(`host-routing: redirect from must not be an /api path, it would never fire, got "${rule.from}"`);
+        }
         if (!REDIRECT_TARGET_PATTERN.test(rule.to)) {
             throw new Error(`host-routing: redirect to must be a same-origin path or an https URL without query, got "${rule.to}"`);
         }

package/dist/inbound-mail-foundation/events.js

@@ -26,7 +26,7 @@ export const MAIL_ACCOUNT_AGGREGATE_TYPE = "mail-account";
 export const INBOUND_MESSAGE_AGGREGATE_TYPE = "inbound-message";
 export const MAIL_THREAD_AGGREGATE_TYPE = "mail-thread";
 // Event-name constants — short forms (for r.defineEvent) and qualified
-// FQNs (for ctx.unsafeAppendEvent and projection-apply keys).
+// FQNs (for ctx.events.unsafeAppend and projection-apply keys).
 export const MAIL_ACCOUNT_CONNECTED_EVENT_SHORT = "mail-account-connected";
 export const MAIL_ACCOUNT_UPDATED_EVENT_SHORT = "mail-account-updated";
 export const MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT = "mail-account-disconnected";

package/dist/inbound-mail-foundation/feature.js

@@ -58,6 +58,7 @@ import { mailAccountEditScreen, mailAccountListScreen } from "./screens.js";
 import { INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON, inboundMessageTenantDestroyHook, mailAccountTenantDestroyHook, mailThreadTenantDestroyHook, } from "./tenant-destroy-hook.js";
 export function createInboundMailFoundationFeature() {
     return defineFeature(INBOUND_MAIL_FOUNDATION_FEATURE, (r) => {
+        r.adoptsBundledLists();
         r.describe("Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push). The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.");
         r.uiHints({
             displayLabel: "Inbound Mail · Foundation",
@@ -192,7 +193,7 @@ export function createInboundMailFoundationFeature() {
                 let providerPromise = null;
                 const deleteBodyObject = async (bodyRef) => {
                     if (!providerPromise) {
-                        providerPromise = createFileProviderForTenant({ config: ctx.config, registry: ctx.registry }, tenantId);
+                        providerPromise = createFileProviderForTenant({ config: ctx.config, registry: ctx.registry, secrets: ctx.services.secrets }, tenantId);
                     }
                     const provider = await providerPromise;
                     await provider.delete(bodyRef);

package/dist/inbound-mail-foundation/handlers/account-state.d.ts

@@ -1,3 +1,5 @@
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import type { MailAccountEventPayload } from "../events.ts";
-export declare function loadCurrentMailAccountPayload(ctx: Pick<HandlerContext, "loadAggregate">, accountId: string): Promise<MailAccountEventPayload | undefined>;
+export declare function loadCurrentMailAccountPayload(ctx: {
+    readonly events: Pick<HandlerContext["events"], "load">;
+}, accountId: string): Promise<MailAccountEventPayload | undefined>;

package/dist/inbound-mail-foundation/handlers/account-state.js

@@ -9,7 +9,7 @@
 // and is copied byte-for-byte — NEVER re-encrypt it (that would require KMS
 // decryption when unavailable or produce double encryption).
 export async function loadCurrentMailAccountPayload(ctx, accountId) {
-    const events = await ctx.loadAggregate(accountId);
+    const events = await ctx.events.load(accountId);
     const last = events[events.length - 1];
     // @cast-boundary engine-payload — eigene events, shape via defineEvent
     return last?.payload;

package/dist/inbound-mail-foundation/handlers/connect-account.write.js

@@ -79,7 +79,7 @@ export const connectAccountHandler = {
             providerName: payload.provider,
             reason: "connect_flow",
         };
-        await ctx.unsafeAppendEvent({
+        await ctx.events.unsafeAppend({
             aggregateId: accountId,
             aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
             type: MAIL_ACCOUNT_CONNECTED_EVENT_QN,

package/dist/inbound-mail-foundation/handlers/disconnect-account.write.js

@@ -43,7 +43,7 @@ export const disconnectAccountHandler = {
             providerName: current.provider,
             reason: payload.reason,
         };
-        await ctx.unsafeAppendEvent({
+        await ctx.events.unsafeAppend({
             aggregateId: payload.accountId,
             aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
             type: MAIL_ACCOUNT_DISCONNECTED_EVENT_QN,