@cosmicdrift/kumiko-samples 0.389.0 → 0.390.0

package/packages/bundled-features/src/form-draft/handlers/cleanup.job.ts

@@ -77,7 +77,12 @@ async function releaseRowFileRefs(
     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) {
@@ -137,7 +142,12 @@ export async function deleteStaleDraftsBatch(
   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) {
@@ -171,8 +181,8 @@ export async function cleanupDraftsJob(
   ctx: JobContext,
   db: DbConnection,
 ): Promise<void> {
-  const resolved = ctx.configResolver
-    ? await ctx.configResolver.get(
+  const resolved = ctx.services.configResolver
+    ? await ctx.services.configResolver.get(
         FORM_DRAFT_RETENTION_DAYS_CONFIG_KEY,
         formDraftRetentionDaysConfig,
         SYSTEM_TENANT_ID,
@@ -184,26 +194,26 @@ export async function cleanupDraftsJob(
   // 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?.(
+  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<string>();
   while (true) {
-    if (ctx.signal?.aborted) break;
+    if (ctx.lifecycle.signal?.aborted) break;
     const batch = await selectStaleDraftsBatch(db, retentionDays, DEFAULT_BATCH_SIZE, [
       ...deferred,
     ]);
     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.
@@ -213,11 +223,11 @@ export async function cleanupDraftsJob(
       batch,
       db,
       retentionDays,
-      ctx.log,
+      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
@@ -229,5 +239,5 @@ export async function cleanupDraftsJob(
     )
       break;
   }
-  ctx.log?.info?.(`[form-draft:cleanup] deleted=${deleted} retentionDays=${retentionDays}`);
+  ctx.obs.log?.info?.(`[form-draft:cleanup] deleted=${deleted} retentionDays=${retentionDays}`);
 }

package/packages/bundled-features/src/form-draft/handlers/discard.write.ts

@@ -56,7 +56,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
@@ -87,8 +87,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 (): Promise<void> => {
         await releaseDraftFileRefs(
           keys,

package/packages/bundled-features/src/form-draft/handlers/get.query.ts

@@ -27,7 +27,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?.(
+      ctx.obs.log?.warn?.(
         `[form-draft:get] stored blob for draftKey=${query.payload.draftKey} failed schema or decryption, treating as absent`,
       );
       return { draft: null };

package/packages/bundled-features/src/foundation-shared/config-helpers.ts

@@ -77,7 +77,7 @@ export function requireNonEmpty(
 }
 
 /**
- * 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/packages/bundled-features/src/inbound-mail-foundation/events.ts

@@ -29,7 +29,7 @@ export const INBOUND_MESSAGE_AGGREGATE_TYPE = "inbound-message" as const;
 export const MAIL_THREAD_AGGREGATE_TYPE = "mail-thread" as const;
 
 // 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" as const;
 export const MAIL_ACCOUNT_UPDATED_EVENT_SHORT = "mail-account-updated" as const;
 export const MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT = "mail-account-disconnected" as const;

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

@@ -254,7 +254,7 @@ export function createInboundMailFoundationFeature() {
           const deleteBodyObject = async (bodyRef: string): Promise<void> => {
             if (!providerPromise) {
               providerPromise = createFileProviderForTenant(
-                { config: ctx.config, registry: ctx.registry },
+                { config: ctx.config, registry: ctx.registry, secrets: ctx.services.secrets },
                 tenantId,
               );
             }

package/packages/bundled-features/src/inbound-mail-foundation/handlers/account-state.ts

@@ -13,10 +13,10 @@ import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import type { MailAccountEventPayload } from "../events.ts";
 
 export async function loadCurrentMailAccountPayload(
-  ctx: Pick<HandlerContext, "loadAggregate">,
+  ctx: { readonly events: Pick<HandlerContext["events"], "load"> },
   accountId: string,
 ): Promise<MailAccountEventPayload | undefined> {
-  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 as MailAccountEventPayload | undefined;

package/packages/bundled-features/src/inbound-mail-foundation/handlers/connect-account.write.ts

@@ -104,7 +104,7 @@ export const connectAccountHandler: WriteHandlerDef = {
       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/packages/bundled-features/src/inbound-mail-foundation/handlers/disconnect-account.write.ts

@@ -56,7 +56,7 @@ export const disconnectAccountHandler: WriteHandlerDef = {
       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,

package/packages/bundled-features/src/inbound-mail-foundation/handlers/ingest-message.write.ts

@@ -10,7 +10,7 @@
 //      both the event log AND projection contain ciphertext.
 //   4. inbound-message-received append (inline projection writes
 //      read_inbound_messages in the same TX). Savepoint-scoped
-//      (ctx.tryAppendEvent) — a losing concurrent ingest for the same
+//      (ctx.events.tryAppend) — a losing concurrent ingest for the same
 //      messageAggId returns { duplicate: true } instead of failing the TX.
 //   5. Thread rollup: mail-thread-updated append with a recalculated
 //      snapshot (count+1, max(lastMessageAt)) — the apply is a
@@ -140,7 +140,7 @@ export const ingestMessageHandler: WriteHandlerDef = {
         data: { duplicate: true as const, inboundMessageAggregateId: messageAggId },
       };
     }
-    const existingEvents = await ctx.loadAggregate(messageAggId);
+    const existingEvents = await ctx.events.load(messageAggId);
     if (existingEvents.length > 0) {
       // Stream existiert, Anchor fehlte → Anchor nachziehen, dann raus.
       await ctx.db.insertOne(seenMessageTable, {
@@ -211,7 +211,7 @@ export const ingestMessageHandler: WriteHandlerDef = {
       providerName: payload.providerName,
       providerCursor: payload.providerCursor,
     };
-    const messageAppend = await ctx.tryAppendEvent({
+    const messageAppend = await ctx.events.tryAppend({
       aggregateId: messageAggId,
       aggregateType: INBOUND_MESSAGE_AGGREGATE_TYPE,
       type: INBOUND_MESSAGE_RECEIVED_EVENT_QN,
@@ -222,8 +222,8 @@ export const ingestMessageHandler: WriteHandlerDef = {
       // Lost the race against a concurrent ingest for the same messageAggId
       // (Watch-Push vs. Poll-Reconciliation overlap). The winner already
       // writes thread-rollup + seen-anchor for this message — steps 5+6
-      // skip here. tryAppendEvent's savepoint keeps this TX usable despite
-      // the caught VersionConflictError (see ctx.tryAppendEvent doc).
+      // skip here. events.tryAppend's savepoint keeps this TX usable despite
+      // the caught VersionConflictError (see ctx.events.tryAppend doc).
       return {
         isSuccess: true as const,
         data: { duplicate: true as const, inboundMessageAggregateId: messageAggId },
@@ -232,7 +232,7 @@ export const ingestMessageHandler: WriteHandlerDef = {
 
     // ---------------------------------------------------------------
     // 5. Thread-Rollup. New snapshot (live COUNT + max(lastMessageAt)) via
-    //    ctx.tryAppendEvent in a bounded retry loop — the apply stays a
+    //    ctx.events.tryAppend in a bounded retry loop — the apply stays a
     //    dumb, replay-idempotent UPSERT. lastMessageAtIso is not PII (a
     //    timestamp), so it stays plaintext-comparable; subject is
     //    encrypted once up front (constant across retries, doesn't
@@ -244,9 +244,9 @@ export const ingestMessageHandler: WriteHandlerDef = {
     //    same thread arriving at once) converge on the true count.
     //    acquireNamespacedAdvisoryLock below serializes this whole
     //    countWhere+append section per threadAggId — transaction-scoped,
-    //    so it survives tryAppendEvent's inner SAVEPOINT and releases at
+    //    so it survives events.tryAppend's inner SAVEPOINT and releases at
     //    the enclosing TX's commit/rollback. Without it, a concurrent
-    //    commit landing between countWhere and tryAppendEvent's own fresh
+    //    commit landing between countWhere and events.tryAppend's own fresh
     //    version-read makes the append succeed with a stale count instead
     //    of a VersionConflictError, so the retry loop below never sees it
     //    as a conflict to retry (the original gap). Unlike step 4, a
@@ -280,7 +280,7 @@ export const ingestMessageHandler: WriteHandlerDef = {
 
     let threadAppendOk = false;
     for (let attempt = 1; attempt <= THREAD_ROLLUP_MAX_ATTEMPTS && !threadAppendOk; attempt++) {
-      const threadEvents = await ctx.loadAggregate(threadAggId);
+      const threadEvents = await ctx.events.load(threadAggId);
       const lastThreadEvent = threadEvents[threadEvents.length - 1];
       // @cast-boundary engine-payload — eigene events, shape via defineEvent
       const previousThread = lastThreadEvent?.payload as MailThreadEventPayload | undefined;
@@ -298,7 +298,7 @@ export const ingestMessageHandler: WriteHandlerDef = {
         lastMessageAtIso: newLastAt,
         messageCount,
       };
-      const threadAppend = await ctx.tryAppendEvent({
+      const threadAppend = await ctx.events.tryAppend({
         aggregateId: threadAggId,
         aggregateType: MAIL_THREAD_AGGREGATE_TYPE,
         type: MAIL_THREAD_UPDATED_EVENT_QN,

package/packages/bundled-features/src/inbound-mail-foundation/handlers/update-account.write.ts

@@ -79,7 +79,7 @@ export const updateAccountHandler: WriteHandlerDef = {
       providerName: current.provider,
       reason: auditReasonFor(event.user, payload.reason),
     };
-    await ctx.unsafeAppendEvent({
+    await ctx.events.unsafeAppend({
       aggregateId: payload.accountId,
       aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
       type: MAIL_ACCOUNT_UPDATED_EVENT_QN,

package/packages/bundled-features/src/inbound-mail-foundation/projection.ts

@@ -3,7 +3,7 @@
 //   inbound-message  → read_inbound_messages  (INSERT-ignore, append-only)
 //   mail-thread      → read_mail_threads      (UPSERT, rollup)
 //
-// Apply runs in the same transaction as ctx.unsafeAppendEvent, providing
+// Apply runs in the same transaction as ctx.events.unsafeAppend, providing
 // read-your-own-write without waiting for a dispatcher tick (as in
 // billing-foundation).
 //

package/packages/bundled-features/src/inbound-mail-foundation/watch-supervisor.ts

@@ -7,7 +7,7 @@
 //
 // **Documented deviation:** the poll was originally intended as an `r.job`
 // cron trigger. JobContext previously had no dispatcher (see
-// run-export-jobs.ts), but now has one (`ctx.write`/`ctx.queryAs`,
+// run-export-jobs.ts), but now has one (`ctx.dispatch.write`/`ctx.dispatch.queryAs`,
 // job-runner.ts). Converting the poll to a cron job is a separate migration
 // because it changes the concurrency model, so this dispatcher contract
 // remains in place. The app owner wires the supervisor in bin/server.ts:

package/packages/bundled-features/src/inbound-provider-imap/feature.ts

@@ -64,7 +64,10 @@ async function readCredentialDocument(
   ctx: InboundMailContext,
   account: MailAccountRecord,
 ): Promise<ImapCredentialDocument> {
-  const secrets = requireSecretsContext(ctx, FEATURE_NAME);
+  const secrets = requireSecretsContext(
+    { secrets: ctx.secrets, auditUserId: ctx.auditUserId },
+    FEATURE_NAME,
+  );
   const secret = await secrets.get(account.tenantId, inboundCredentialSecretKey(account.id));
   if (!secret) {
     throw new InboundAuthError(

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.390.0",
+    "type": "fix",
+    "title": "Tenant job run rows are written in the tenant's scope",
+    "detail": "With row level security on, the queued, started and finished rows of tenant-visible job runs were rejected by Postgres when the job was dispatched outside a request scope, and the logger only logged the error. The logger now scopes its tenant writes to the job's tenant and logs a rejected write as a missing row-level-security scope instead of a generic write failure."
+  },
   {
     "version": "0.388.0",
     "type": "improvement",

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

@@ -2,7 +2,7 @@
 // backed jobRun's event-store payloads (r.defineEvent + inline projections);
 // now job-run-logger.ts parses against them before writing straight into
 // jobRunsTable/jobRunLogsTable, so an out-of-dispatcher write still gets the
-// same validation guarantee ctx.appendEvent used to give it.
+// same validation guarantee ctx.events.append used to give it.
 
 import * as z from "zod";
 

package/packages/bundled-features/src/jobs/handlers/consumer.write.ts

@@ -65,10 +65,13 @@ function defineConsumerWrite(name: string, description: string, transition: Cons
             ? rejected(JobErrors.consumerUnknown, "jobs.errors.consumerUnknown")
             : rejected(JobErrors.consumerWrongStatus, "jobs.errors.consumerWrongStatus");
         }
-        ctx.log?.error(`jobs:write:${name} failed: ${e instanceof Error ? e.message : String(e)}`, {
-          consumer: event.payload.name,
-          instanceId: event.payload.instanceId,
-        });
+        ctx.obs.log?.error(
+          `jobs:write:${name} failed: ${e instanceof Error ? e.message : String(e)}`,
+          {
+            consumer: event.payload.name,
+            instanceId: event.payload.instanceId,
+          },
+        );
         return rejected(JobErrors.consumerTransitionFailed, "jobs.errors.consumerTransitionFailed");
       }
     },

package/packages/bundled-features/src/jobs/handlers/projection-rebuild.job.ts

@@ -36,7 +36,7 @@ export const projectionRebuildJob: JobHandlerFn = async (rawPayload, ctx): Promi
     registry: ctx.registry,
     ...(skipApplyErrors === true && { errorPolicy: { skipApplyErrors: true } }),
   });
-  ctx.log?.info?.(
+  ctx.obs.log?.info?.(
     `[jobs:projection-rebuild] rebuilt ${projection}: ${result.eventsProcessed} events` +
       `${result.eventsSkipped > 0 ? ` (${result.eventsSkipped} quarantined)` : ""} in ${result.durationMs}ms`,
   );

package/packages/bundled-features/src/jobs/handlers/reindex-entity.job.ts

@@ -20,16 +20,16 @@ export const reindexEntityJob: JobHandlerFn = async (rawPayload, ctx): Promise<v
       message: "[jobs:reindex-entity] ctx.registry missing — job context requires the registry.",
     });
   }
-  if (!ctx.searchAdapter) {
+  if (!ctx.services.searchAdapter) {
     throw new InternalError({
       message:
-        "[jobs:reindex-entity] ctx.searchAdapter missing — mount a search adapter to run this job.",
+        "[jobs:reindex-entity] ctx.services.searchAdapter missing — mount a search adapter to run this job.",
     });
   }
   // perTenant fan-out — the job-runner enqueues one child run per active
   // tenant with ctx.systemUser scoped to it; a run without one (e.g.
   // misconfigured manual dispatch outside the fan-out) has nothing scoped
-  // to reindex. ctx._tenantId is never populated per-dispatch (only
+  // to reindex. ctx.user.tenantId is never populated per-dispatch (only
   // ctx.systemUser is), so it is not a valid fallback here.
   const tenantId = ctx.systemUser?.tenantId;
   if (tenantId === undefined) {
@@ -48,8 +48,14 @@ export const reindexEntityJob: JobHandlerFn = async (rawPayload, ctx): Promise<v
   const db = ctx.systemDb.unsafeRaw(
     "reindexEntity filters WHERE tenant_id = $1 itself with this job's tenantId",
   );
-  const result = await reindexEntity(db, ctx.registry, ctx.searchAdapter, entity, tenantId);
-  ctx.log?.info?.(
+  const result = await reindexEntity(
+    db,
+    ctx.registry,
+    ctx.services.searchAdapter,
+    entity,
+    tenantId,
+  );
+  ctx.obs.log?.info?.(
     `[jobs:reindex-entity] tenant=${tenantId} reindexed ${entity}: ${result.indexedRows}/${result.scannedRows} rows indexed` +
       `${result.failures.length > 0 ? ` (${result.failures.length} failed)` : ""}`,
   );

package/packages/bundled-features/src/jobs/handlers/retention-cleanup.job.ts

@@ -18,6 +18,6 @@ export function createRetentionCleanupJob(retentionDays: number): JobHandlerFn {
       "store_job_runs retention purges finished runs of every tenant",
     ) as DbConnection; // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
     const result = await deleteStaleJobRuns(db, retentionDays);
-    ctx.log?.info?.(`[jobs:retention-cleanup] complete: ${JSON.stringify(result)}`);
+    ctx.obs.log?.info?.(`[jobs:retention-cleanup] complete: ${JSON.stringify(result)}`);
   };
 }

package/packages/bundled-features/src/jobs/handlers/retry.write.ts

@@ -37,7 +37,7 @@ export const retryWrite = defineWriteHandler({
     }
     const db = ctx.systemDb.acknowledgeCrossTenant("cross-tenant job monitoring");
     // @cast-boundary engine-payload — JobRunner attached by app-boot via ctx-extension
-    const jobRunner = ctx["jobRunner"] as JobRunner;
+    const jobRunner = ctx.services.jobRunner as JobRunner;
 
     const run = await fetchOne<JobRunRow>(db, jobRunsTable, { id: event.payload.runId });
 

package/packages/bundled-features/src/jobs/handlers/stale-run-sweep.job.ts

@@ -28,6 +28,6 @@ export function createStaleRunSweepJob(
       "stale-run sweep marks stuck runs of every tenant as failed",
     ) as DbConnection; // @cast-boundary db-operator — DbRunner narrows to DbConnection, jobs never run inside a DbTx
     const result = await markStaleJobRunsFailed(db, timeoutHours, queuedRetentionDays);
-    ctx.log?.info?.(`[jobs:stale-run-sweep] complete: ${JSON.stringify(result)}`);
+    ctx.obs.log?.info?.(`[jobs:stale-run-sweep] complete: ${JSON.stringify(result)}`);
   };
 }

package/packages/bundled-features/src/jobs/handlers/trigger.write.ts

@@ -28,8 +28,8 @@ export const triggerWrite = defineWriteHandler({
   access: { roles: ["SystemAdmin"] },
   handler: async (event, ctx) => {
     const registry = ctx.registry;
-    // `jobRunner` is a dynamic context extension — not a core HandlerContext field.
-    const jobRunner = ctx["jobRunner"] as JobRunner; // @cast-boundary dynamic-key
+    // `services.jobRunner` is typed as the handleEvent-only JobRunnerRef; dispatch lives on the concrete runner.
+    const jobRunner = ctx.services.jobRunner as JobRunner; // @cast-boundary engine-bridge
 
     const jobDef = registry.getJob(event.payload.jobName);
     if (!jobDef) {