@cosmicdrift/kumiko-samples 0.389.0 → 0.390.0

package/packages/bundled-features/src/jobs/job-run-logger.ts

@@ -18,7 +18,17 @@ import {
   updateMany,
   upsertOnConflict,
 } from "@cosmicdrift/kumiko-framework/db";
-import { type Registry, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  parseTenantId,
+  type Registry,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  isRowLevelSecurityViolation,
+  runInRowLevelSecurityScope,
+  tenantRowLevelSecurityScope,
+} from "@cosmicdrift/kumiko-framework/internal/row-level-security";
 import type {
   JobDroppedMeta,
   JobLogEntry,
@@ -77,6 +87,16 @@ const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 // Run rows hang on SYSTEM_TENANT_ID and a null trigger is a cron/system run;
 // job-run-table.ts declares whenAbsent: "tenant" for exactly that case, so the
 // logger must resolve the same subject the entity chain would.
+// Job callbacks run outside any request scope; the tenant tables enforce their rows per tenant, so each write
+// declares the tenant it belongs to.
+function inTenantScope<T>(tenantId: string, work: () => Promise<T>): Promise<T> {
+  const parsed = parseTenantId(tenantId);
+  if (parsed === null) {
+    throw new InternalError({ message: `job run logger got a malformed tenant id "${tenantId}"` });
+  }
+  return runInRowLevelSecurityScope(tenantRowLevelSecurityScope(parsed), work);
+}
+
 function jobRunSubject(triggeredById: string | null): SubjectId {
   return triggeredById === null
     ? { kind: "tenant", tenantId: SYSTEM_TENANT_ID }
@@ -182,7 +202,7 @@ const TENANT_RUN_CONFLICT_KEYS = ["tenantId", "jobName", "bullJobId"] as const;
 function tenantJobFailureTarget(
   jobName: string,
   outcome: JobOutcomeMeta | undefined,
-): Record<string, unknown> | null {
+): { tenantId: string; jobName: string; subject: string | null } | null {
   if (!outcome?.tenantVisible || outcome.tenantId === SYSTEM_TENANT_ID) return null;
   return { tenantId: outcome.tenantId, jobName, subject: outcome.tenantVisible.subject };
 }
@@ -202,19 +222,21 @@ async function recordTenantJobFailure(
   // partial unique indexes (subject NULL vs. set) are no ON CONFLICT target.
   // The lock makes the later of two racing final failures replace the earlier
   // one; the indexes are the backstop against any writer that skips the lock.
-  await transaction(db, async (tx) => {
-    await acquireNamespacedAdvisoryLock(
-      tx,
-      TENANT_JOB_FAILURE_LOCK_NAMESPACE,
-      JSON.stringify([where["tenantId"], where["jobName"], where["subject"]]),
-    );
-    await deleteMany(tx, tenantJobFailuresTable, where);
-    await insertOne(tx, tenantJobFailuresTable, {
-      ...where,
-      messageKey,
-      failedAt: Temporal.Now.instant(),
-    });
-  });
+  await inTenantScope(where.tenantId, () =>
+    transaction(db, async (tx) => {
+      await acquireNamespacedAdvisoryLock(
+        tx,
+        TENANT_JOB_FAILURE_LOCK_NAMESPACE,
+        JSON.stringify([where["tenantId"], where["jobName"], where["subject"]]),
+      );
+      await deleteMany(tx, tenantJobFailuresTable, where);
+      await insertOne(tx, tenantJobFailuresTable, {
+        ...where,
+        messageKey,
+        failedAt: Temporal.Now.instant(),
+      });
+    }),
+  );
 }
 
 async function clearTenantJobFailure(
@@ -225,7 +247,7 @@ async function clearTenantJobFailure(
   const where = tenantJobFailureTarget(jobName, outcome);
   // skip: no tenant-visible target — nothing was ever recorded
   if (!where) return;
-  await deleteMany(db, tenantJobFailuresTable, where);
+  await inTenantScope(where.tenantId, () => deleteMany(db, tenantJobFailuresTable, where));
 }
 
 // Tenant-visible run state. One row per BullMQ job in
@@ -260,28 +282,30 @@ async function recordTenantRunQueued(
   // skip: system-tenant run, no tenant-scoped query reads it
   if (!key) return;
   const now = Temporal.Now.instant();
-  await transaction(db, async (tx) => {
-    // A finished row under the same id is left over from before a Redis reset
-    // (ids restart at 1), not this job. Only rows queued before this BullMQ job
-    // was created qualify: a fast worker can finish before the hook runs (no
-    // queuedAt), and a deduplicated add of an already finished job re-announces
-    // it with a creation time older than its own row. Both rows must stay.
-    await deleteMany(tx, tenantJobRunsTable, {
-      tenantId: key.tenantId,
-      jobName,
-      bullJobId,
-      status: { in: ["completed", "failed"] },
-      queuedAt: { lt: Temporal.Instant.fromEpochMilliseconds(meta.jobCreatedAtMs) },
-    });
-    // DO NOTHING: a fast worker can report the start before this enqueue hook
-    // returns, and a repeated jobId (debounce, fan-out dedup) is the same job.
-    await insertOnConflictDoNothing(
-      tx,
-      tenantJobRunsTable,
-      { ...key, bullJobId, status: "queued", queuedAt: now, updatedAt: now },
-      { conflictKeys: [...TENANT_RUN_CONFLICT_KEYS] },
-    );
-  });
+  await inTenantScope(key.tenantId, () =>
+    transaction(db, async (tx) => {
+      // A finished row under the same id is left over from before a Redis reset
+      // (ids restart at 1), not this job. Only rows queued before this BullMQ job
+      // was created qualify: a fast worker can finish before the hook runs (no
+      // queuedAt), and a deduplicated add of an already finished job re-announces
+      // it with a creation time older than its own row. Both rows must stay.
+      await deleteMany(tx, tenantJobRunsTable, {
+        tenantId: key.tenantId,
+        jobName,
+        bullJobId,
+        status: { in: ["completed", "failed"] },
+        queuedAt: { lt: Temporal.Instant.fromEpochMilliseconds(meta.jobCreatedAtMs) },
+      });
+      // DO NOTHING: a fast worker can report the start before this enqueue hook
+      // returns, and a repeated jobId (debounce, fan-out dedup) is the same job.
+      await insertOnConflictDoNothing(
+        tx,
+        tenantJobRunsTable,
+        { ...key, bullJobId, status: "queued", queuedAt: now, updatedAt: now },
+        { conflictKeys: [...TENANT_RUN_CONFLICT_KEYS] },
+      );
+    }),
+  );
 }
 
 async function recordTenantRunStarted(
@@ -296,14 +320,16 @@ async function recordTenantRunStarted(
   // skip: system-tenant run, no tenant-scoped query reads it
   if (!key) return;
   const now = Temporal.Now.instant();
-  await upsertOnConflict(
-    db,
-    tenantJobRunsTable,
-    { ...key, bullJobId, status: "running", startedAt: now, updatedAt: now },
-    {
-      conflictKeys: [...TENANT_RUN_CONFLICT_KEYS],
-      update: { status: "running", startedAt: now, finishedAt: null, updatedAt: now },
-    },
+  await inTenantScope(key.tenantId, () =>
+    upsertOnConflict(
+      db,
+      tenantJobRunsTable,
+      { ...key, bullJobId, status: "running", startedAt: now, updatedAt: now },
+      {
+        conflictKeys: [...TENANT_RUN_CONFLICT_KEYS],
+        update: { status: "running", startedAt: now, finishedAt: null, updatedAt: now },
+      },
+    ),
   );
 }
 
@@ -323,11 +349,13 @@ async function recordTenantRunOutcome(
   // A failed attempt BullMQ will retry goes back to waiting: the tenant keeps
   // seeing pending work, not a failure the next attempt may still resolve.
   if (result === "failed" && !outcome.finalAttempt) {
-    await updateMany(
-      db,
-      tenantJobRunsTable,
-      { status: "queued", startedAt: null, finishedAt: null, updatedAt: now },
-      { tenantId: key.tenantId, jobName, bullJobId },
+    await inTenantScope(key.tenantId, () =>
+      updateMany(
+        db,
+        tenantJobRunsTable,
+        { status: "queued", startedAt: null, finishedAt: null, updatedAt: now },
+        { tenantId: key.tenantId, jobName, bullJobId },
+      ),
     );
     // skip: retry pending, the row stays active until the final attempt
     return;
@@ -336,30 +364,32 @@ async function recordTenantRunOutcome(
   // one it replaces. The per-key lock keeps two runs of the same subject that
   // finish together from each missing the other's uncommitted row and leaving
   // both behind.
-  await transaction(db, async (tx) => {
-    await acquireNamespacedAdvisoryLock(
-      tx,
-      TENANT_JOB_RUN_LOCK_NAMESPACE,
-      JSON.stringify([key.tenantId, key.jobName, key.subject]),
-    );
-    // Read under the lock: the run that finishes last in lock order must also carry the
-    // latest finishedAt, otherwise a stale timestamp makes it the row that gets pruned.
-    const finishedAt = Temporal.Now.instant();
-    await upsertOnConflict(
-      tx,
-      tenantJobRunsTable,
-      { ...key, bullJobId, status: result, finishedAt, updatedAt: finishedAt },
-      {
-        conflictKeys: [...TENANT_RUN_CONFLICT_KEYS],
-        update: { status: result, finishedAt, updatedAt: finishedAt },
-      },
-    );
-    await deleteMany(tx, tenantJobRunsTable, {
-      ...key,
-      status: { in: ["completed", "failed"] },
-      bullJobId: { ne: bullJobId },
-    });
-  });
+  await inTenantScope(key.tenantId, () =>
+    transaction(db, async (tx) => {
+      await acquireNamespacedAdvisoryLock(
+        tx,
+        TENANT_JOB_RUN_LOCK_NAMESPACE,
+        JSON.stringify([key.tenantId, key.jobName, key.subject]),
+      );
+      // Read under the lock: the run that finishes last in lock order must also carry the
+      // latest finishedAt, otherwise a stale timestamp makes it the row that gets pruned.
+      const finishedAt = Temporal.Now.instant();
+      await upsertOnConflict(
+        tx,
+        tenantJobRunsTable,
+        { ...key, bullJobId, status: result, finishedAt, updatedAt: finishedAt },
+        {
+          conflictKeys: [...TENANT_RUN_CONFLICT_KEYS],
+          update: { status: result, finishedAt, updatedAt: finishedAt },
+        },
+      );
+      await deleteMany(tx, tenantJobRunsTable, {
+        ...key,
+        status: { in: ["completed", "failed"] },
+        bullJobId: { ne: bullJobId },
+      });
+    }),
+  );
 }
 
 async function requeueTenantRun(
@@ -373,11 +403,13 @@ async function requeueTenantRun(
   const key = tenantRunKey(jobName, meta.tenantVisibleRun.tenantId, meta.tenantVisibleRun.subject);
   // skip: system-tenant run, no tenant-scoped query reads it
   if (!key) return;
-  await updateMany(
-    db,
-    tenantJobRunsTable,
-    { status: "queued", startedAt: null, finishedAt: null, updatedAt: Temporal.Now.instant() },
-    { tenantId: key.tenantId, jobName, bullJobId },
+  await inTenantScope(key.tenantId, () =>
+    updateMany(
+      db,
+      tenantJobRunsTable,
+      { status: "queued", startedAt: null, finishedAt: null, updatedAt: Temporal.Now.instant() },
+      { tenantId: key.tenantId, jobName, bullJobId },
+    ),
   );
 }
 
@@ -387,20 +419,22 @@ async function dropTenantRunQueued(
   bullJobId: string,
   meta: JobDroppedMeta,
 ): Promise<void> {
-  await deleteMany(db, tenantJobRunsTable, {
-    tenantId: meta.tenantId,
-    jobName,
-    bullJobId,
-    status: "queued",
-  });
+  await inTenantScope(meta.tenantId, () =>
+    deleteMany(db, tenantJobRunsTable, {
+      tenantId: meta.tenantId,
+      jobName,
+      bullJobId,
+      status: "queued",
+    }),
+  );
 }
 
 const log = createFallbackLogger("job-run-logger");
 
 // The tenant run state is an optional side write: a throw here must not
 // fail the enqueue, skip the run-row write or turn a completed run into a
-// BullMQ retry.
-async function isolateTenantRunWrite(
+// BullMQ retry. A row-level-security rejection is logged louder (a missing or wrong tenant scope), never rethrown.
+export async function isolateTenantRunWrite(
   write: () => Promise<void>,
   jobName: string,
   bullJobId: string,
@@ -408,6 +442,13 @@ async function isolateTenantRunWrite(
   try {
     await write();
   } catch (e) {
+    if (isRowLevelSecurityViolation(e)) {
+      log.error(
+        "tenant job run state write rejected by row level security: missing or wrong tenant scope",
+        { jobName, bullJobId },
+      );
+      return;
+    }
     log.error("tenant job run state write failed", {
       jobName,
       bullJobId,
@@ -417,7 +458,8 @@ async function isolateTenantRunWrite(
 }
 
 // The tenant failure record is an optional side write: a throw here must not
-// skip the run-row update or turn a completed run into a BullMQ retry.
+// skip the run-row update or turn a completed run into a BullMQ retry. A row-level-security rejection is
+// logged louder (a missing or wrong tenant scope), never rethrown.
 async function isolateTenantFailureWrite(
   write: () => Promise<void>,
   jobName: string,
@@ -426,6 +468,13 @@ async function isolateTenantFailureWrite(
   try {
     await write();
   } catch (e) {
+    if (isRowLevelSecurityViolation(e)) {
+      log.error(
+        "tenant job failure record write rejected by row level security: missing or wrong tenant scope",
+        { jobName, bullJobId },
+      );
+      return;
+    }
     log.error("tenant job failure record write failed", {
       jobName,
       bullJobId,
@@ -544,7 +593,7 @@ export function createJobRunLogger(opts: JobRunLoggerOptions): JobRunLoggerCallb
       const triggeredById = meta.triggeredById ?? null;
       cachePut(bullJobId, runId, triggeredById);
       // Parse against the registered schema so out-of-dispatcher writes
-      // get the same validation guarantee as ctx.appendEvent. A shape
+      // get the same validation guarantee as ctx.events.append. A shape
       // drift between feature + logger fails loudly at the source
       // instead of silently landing on the table.
       const payload = runStartedSchema.parse({

package/packages/bundled-features/src/legal-pages/README.md

@@ -164,7 +164,7 @@ A throw rejects the boot, so the process never reports ready.
 
 | Slug + locale | What happens when missing |
 |---|---|
-| `imprint` / `de` | **Production:** `throw new Error(...)` blocks app start. **Dev:** `ctx.log.warn(...)` |
+| `imprint` / `de` | **Production:** `throw new Error(...)` blocks app start. **Dev:** `ctx.obs.log.warn(...)` |
 | `privacy` / `de` | as above |
 
 EN versions are **not** boot-fail-relevant by default (`LEGAL_OPTIONAL_BLOCKS`).

package/packages/bundled-features/src/legal-pages/lib/boot-check.ts

@@ -6,13 +6,17 @@ import {
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { LEGAL_REQUIRED_BLOCKS, type LegalRequiredBlock } from "../web/constants.ts";
 
-// Only the fields the check reads, so HandlerContext, AppContext or a hand-built
-// object in a unit test all fit.
+// Only the fields the check reads, so a HandlerContext or a hand-built object in a unit test
+// fits.
 export type LegalPagesBootCheckCtx = {
-  readonly templateResolver?: TemplateResolverApi;
-  readonly log?: {
-    readonly info?: (msg: string) => void;
-    readonly warn?: (msg: string) => void;
+  readonly services: {
+    readonly extensions: { readonly templateResolver?: TemplateResolverApi };
+  };
+  readonly obs?: {
+    readonly log?: {
+      readonly info?: (msg: string) => void;
+      readonly warn?: (msg: string) => void;
+    };
   };
 };
 
@@ -42,7 +46,7 @@ export async function runLegalPagesBootCheck(
   }
 
   if (missing.length === 0) {
-    ctx.log?.info?.("legal-pages boot-check: alle Pflicht-Blocks vorhanden");
+    ctx.obs?.log?.info?.("legal-pages boot-check: alle Pflicht-Blocks vorhanden");
   } else {
     const message =
       `legal-pages: missing ${missing.length} required text-block(s) in SYSTEM_TENANT: ` +
@@ -52,6 +56,6 @@ export async function runLegalPagesBootCheck(
     if (process.env["NODE_ENV"] === "production") {
       throw new Error(`Boot-Validation failed: ${message}`);
     }
-    ctx.log?.warn?.(message);
+    ctx.obs?.log?.warn?.(message);
   }
 }

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

@@ -64,7 +64,7 @@ export const MAIL_TRANSPORT_EXTENSION = "mailTransport" as const;
  * **Why not the full HandlerContext?** On the worker path (transport builds
  * triggered by r.job, such as the user-data-rights forget/export cron) there
  * is no per-request `config`/`tx`/`actor`; the wrapper builds the per-tenant
- * ConfigAccessor from `ctx.configResolver`. A plugin reading `ctx.tx` or other
+ * ConfigAccessor from `ctx.services.configResolver`. A plugin reading `ctx.tx` or other
  * request-only fields would break the worker path at runtime, and that would
  * only show up with real SMTP in production. Casting
  * `ctx as unknown as HandlerContext` satisfies the compiler but fails at
@@ -82,7 +82,7 @@ export const MAIL_TRANSPORT_EXTENSION = "mailTransport" as const;
 export type MailTransportContext = {
   readonly config?: ConfigAccessor;
   readonly registry?: Registry;
-  readonly secrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext;
+  readonly secrets: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext | undefined;
   readonly auditUserId?: string | undefined;
 };
 

package/packages/bundled-features/src/mail-transport-smtp/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.390.0",
+    "type": "fix",
+    "title": "nodemailer 10.2.1 fixes the address-parser advisories",
+    "detail": "nodemailer 10.0.13 mis-parsed quoted semicolons, angle brackets and nested comments in addresses (GHSA-m943-m63m-w62w, GHSA-85x2-q946-cp5h, GHSA-8c8m-p3m8-cjg8). The dependency is now 10.2.1, and the overrides for ip-address (10.7.4) and fast-copy (4.2.0) remove the remaining audit findings."
+  },
   {
     "version": "0.389.0",
     "type": "improvement",

package/packages/bundled-features/src/mail-transport-smtp/feature.ts

@@ -231,7 +231,10 @@ async function buildSmtpTransport(
 }
 
 async function readPassword(ctx: MailTransportContext, 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, SMTP_PASSWORD);
   return requireSecretSet(branded, FEATURE_NAME, SMTP_PASSWORD.name).reveal();
 }

package/packages/bundled-features/src/managed-pages/seeding.ts

@@ -8,12 +8,12 @@ import {
   type DbConnection,
   fetchOne,
 } from "@cosmicdrift/kumiko-framework/db";
-import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
-  runEventStoreSeed,
-  type SeedIfExists,
-  TestUsers,
-} from "@cosmicdrift/kumiko-framework/seeding";
+  createSystemUser,
+  type SessionUser,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { runEventStoreSeed, type SeedIfExists } from "@cosmicdrift/kumiko-framework/seeding";
 
 import { type PageRow, pageEntity, pagesTable } from "./table.ts";
 
@@ -35,9 +35,14 @@ export type SeedPageOptions = {
 export async function seedPage(db: DbConnection, opts: SeedPageOptions): Promise<{ id: string }> {
   // The default user must have user.tenantId === opts.tenantId; otherwise the
   // event-store stream ends up in the wrong tenant bucket → version_conflict
-  // on subsequent real writes. TestUsers.systemAdmin is testTenantId(1).
-  const by = opts.by ?? { ...TestUsers.systemAdmin, tenantId: opts.tenantId };
-  const tdb = createTenantDb({ db, tenantId: opts.tenantId, mode: "system" });
+  // on subsequent real writes.
+  const by = opts.by ?? createSystemUser(opts.tenantId);
+  const tdb = createTenantDb({
+    db,
+    tenantId: opts.tenantId,
+    mode: "system",
+    reason: "seeding writes managed pages into an explicitly named tenant",
+  });
 
   const existing = await fetchOne<PageRow>(db, pagesTable, {
     tenantId: opts.tenantId,

package/packages/bundled-features/src/notes-history/handlers/add-note.write.ts

@@ -80,7 +80,7 @@ export function createAddNoteHandler(
           return decryptStoredPii(userRow.displayName, "displayName", "notes-history:add-note");
         });
       } catch (e) {
-        ctx.log?.warn("notes-history: authorName lookup failed", {
+        ctx.obs.log?.warn("notes-history: authorName lookup failed", {
           error: e,
           userId: event.user.id,
         });

package/packages/bundled-features/src/personal-access-tokens/feature.ts

@@ -136,7 +136,7 @@ export function createPersonalAccessTokensFeature(
 
     // Custom domain-event for cross-instance access-invalidation,
     // mirroring sessions' SESSION_REVOKED_EVENT_SHORT. r.defineEvent
-    // registers the schema so ctx.unsafeAppendEvent (revoke) enforces it at
+    // registers the schema so ctx.events.unsafeAppend (revoke) enforces it at
     // append time. revoke-for-user.ts appends via the low-level append()
     // instead (needs to anchor on SYSTEM_TENANT_ID) — same guarantee via a
     // different path. No projection: the payload IS the read, consumed

package/packages/bundled-features/src/personal-access-tokens/handlers/create.write.ts

@@ -68,7 +68,7 @@ export function createPatCreateHandler(opts: CreatePatOptions = {}) {
     escapeHatch: {
       grants: ["systemIdentity"],
       reason:
-        "Reads the caller's own passwordHash (privileged-only field) via ctx.queryAs(SYSTEM, " +
+        "Reads the caller's own passwordHash (privileged-only field) via ctx.dispatch.queryAs(SYSTEM, " +
         "user:findForAuth) to re-verify the current password before minting the token. Also " +
         "reads the MFA enrollment of the user being re-authenticated via the mfaVerifier callback.",
     },
@@ -79,7 +79,7 @@ export function createPatCreateHandler(opts: CreatePatOptions = {}) {
     agent: { expose: false },
     handler: async (event, ctx) => {
       const systemUser = createSystemUser(event.user.tenantId);
-      const me = (await ctx.queryAs(systemUser, UserQueries.findForAuth, {
+      const me = (await ctx.dispatch.queryAs(systemUser, UserQueries.findForAuth, {
         id: event.user.id,
       })) as { passwordHash: string | null } | null; // @cast-boundary db-runner
       if (!me?.passwordHash) return reauthFailed();

package/packages/bundled-features/src/personal-access-tokens/handlers/revoke.write.ts

@@ -39,7 +39,7 @@ export const revokePatWrite = defineWriteHandler({
       // see feature.ts). Without this, the access-invalidation consumer
       // never hears about the revoke and an already-open SSE stream
       // authenticated by this exact token survives it.
-      await ctx.unsafeAppendEvent({
+      await ctx.events.unsafeAppend({
         aggregateId: generateId(),
         aggregateType: PAT_REVOKED_AGGREGATE_TYPE,
         type: PAT_REVOKED_EVENT_QN,

package/packages/bundled-features/src/rate-limiting/handlers/status.query.ts

@@ -37,12 +37,12 @@ export const rateLimitStatus = defineQueryHandler({
     // about the wiring either.
     const denied = bucketAccessDenied(query.payload.bucket, ctx.user);
     if (denied) throw denied;
-    if (!ctx.rateLimit) {
+    if (!ctx.services.rateLimit) {
       throw new UnprocessableError(RateLimitErrors.resolverUnavailable, {
         i18nKey: "rateLimiting.errors.resolverUnavailable",
       });
     }
-    const decision = await ctx.rateLimit.peek(query.payload.bucket, {
+    const decision = await ctx.services.rateLimit.peek(query.payload.bucket, {
       limit: query.payload.limit,
       windowSeconds: query.payload.windowSeconds,
     });

package/packages/bundled-features/src/readiness/handlers/status.query.ts

@@ -36,7 +36,10 @@ export const statusQuery = defineQueryHandler({
 
     // has() is metadata-only: no decryption, no read-audit event — a
     // readiness probe must not pollute the credential-read trail.
-    const secrets = requireSecretsContext(ctx, ReadinessQueries.status);
+    const secrets = requireSecretsContext(
+      { secrets: ctx.services.secrets, user: ctx.user },
+      ReadinessQueries.status,
+    );
     const missingSecrets: ReadinessMissingSecret[] = [];
     for (const [qualifiedName, keyDef] of ctx.registry.getAllSecretKeys()) {
       if (keyDef.required !== true) continue;

package/packages/bundled-features/src/renderer-foundation/api.ts

@@ -87,12 +87,12 @@ function indexByKind(plugins: ReadonlyArray<RendererPlugin>): Map<RenderKind, Re
 // Single source of truth for handlers that require renderer-foundation.
 // The pattern mirrors requireTemplateResolver + requireTextContent.
 export function requireRendererFoundation(
-  ctx: { readonly rendererFoundation?: RendererFoundationApi } | object,
+  ctx: { readonly services: { readonly extensions: Readonly<Record<string, unknown>> } },
   callerName: string,
 ): RendererFoundationApi {
   // @cast-boundary engine-bridge — rendererFoundation kommt per extraContext
-  // from the app bootstrap.
-  const api = (ctx as { rendererFoundation?: RendererFoundationApi }).rendererFoundation;
+  // from the app bootstrap and lands in services.extensions; the framework does not know its type.
+  const api = ctx.services.extensions["rendererFoundation"] as RendererFoundationApi | undefined;
   if (!api) {
     throw new InternalError({
       message:

package/packages/bundled-features/src/secrets/announce-secret-change.ts

@@ -6,8 +6,8 @@ import {
 } from "@cosmicdrift/kumiko-framework/redis";
 
 type AnnouncingContext = {
-  readonly cacheSync?: CacheSyncBus;
-  readonly scheduleAfterCommit?: (hook: () => Promise<void>) => void;
+  readonly services: { readonly cacheSync?: CacheSyncBus };
+  readonly lifecycle: { readonly afterCommit?: (hook: () => Promise<void>) => void };
 };
 
 // Secret writes bypass config:write:*, yet provider caches (e.g. the S3 secret
@@ -18,13 +18,13 @@ export function announceSecretChange(
   tenantId: TenantId,
   key: string,
 ): void {
-  const bus = ctx.cacheSync;
+  const bus = ctx.services.cacheSync;
   // skip: no bus wired (single-process setup), nothing to announce
   if (!bus) return;
   const message: TenantConfigSyncMessage = { tenantId, key };
   const publish = async (): Promise<void> => {
     bus.publish(CACHE_SYNC_TOPICS.tenantConfig, message);
   };
-  if (ctx.scheduleAfterCommit) ctx.scheduleAfterCommit(publish);
+  if (ctx.lifecycle.afterCommit) ctx.lifecycle.afterCommit(publish);
   else bus.publish(CACHE_SYNC_TOPICS.tenantConfig, message);
 }

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

@@ -70,19 +70,19 @@ export { type StoredEnvelope, type StoredMetadata, tenantSecretsTable } from "./
 export const JOIN_REQUEST_TRANSACTION_REASON =
   "the secret write runs on the request transaction so a failing batch rolls it back together with the config writes";
 
-// AppContext carries ctx.secrets via extraContext. requireSecretsContext
+// AppContext carries ctx.services.secrets via extraContext. requireSecretsContext
 // wraps that raw context so every `.get(...)` call automatically includes
 // the current user and handler as audit metadata, preventing feature code
 // from silently bypassing read auditing.
 //
-// The context shape stays minimal: HandlerContext paths (Set/Delete handlers)
-// and FileProviderContext paths (the S3 plugin in the worker) provide the same
-// two fields, so importing the full HandlerContext is unnecessary.
-// Handler contexts carry the caller as ctx.user; provider contexts set
-// auditUserId, which takes precedence.
+// The source shape stays minimal: handler paths pass `{ secrets: ctx.services.secrets,
+// user: ctx.user }`, provider paths (the S3 plugin in the worker) pass `{ secrets, auditUserId }`.
+// `secrets` is a required key on purpose: a whole HandlerContext or JobContext does not carry
+// it flat, so handing one over is a type error instead of a silently undefined secret store.
+// Provider contexts set auditUserId, which takes precedence over the caller in `user`.
 export function requireSecretsContext(
   ctx: {
-    readonly secrets?: SecretsContext;
+    readonly secrets: SecretsContext | undefined;
     readonly auditUserId?: string | undefined;
     readonly user?: { readonly id: string };
   },
@@ -91,7 +91,7 @@ export function requireSecretsContext(
   if (!ctx.secrets) {
     throw new InternalError({
       message:
-        `[${handlerName}] ctx.secrets missing — pass ` +
+        `[${handlerName}] ctx.services.secrets missing — pass ` +
         "createSecretsContext({db, masterKeyProvider, registry}) via extraContext.secrets at boot.",
     });
   }
@@ -187,7 +187,7 @@ export function createSecretsFeature(
     // Read-audit domain-event. Registered here so ops tools + MSPs can
     // discover the type; secrets-context.get parses payloads against
     // `secretReadSchema` at write time because the low-level append() path
-    // skips ctx.appendEvent's schema-validation guard.
+    // skips ctx.events.append's schema-validation guard.
     r.defineEvent("read", secretReadSchema, { piiFields: "none" });
 
     // Per-tenant handlers (set/delete/list) run in the default tenant-scope,