@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

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

@@ -1,6 +1,6 @@
-// imapflow-Wiring + pure Helpers des IMAP-Providers.
-// Referenz-Impl: /Users/marc/code/doc-o-mat (HEINZ) — aber inkrementeller
-// UIDVALIDITY:lastUid-Cursor statt '1:*'-Vollscan.
+// imapflow wiring and pure helpers for IMAP providers.
+// Reference implementation: /Users/marc/code/doc-o-mat (HEINZ), but uses an
+// incremental UIDVALIDITY:lastUid cursor instead of a '1:*' full scan.
 
 import {
   BlockedHostError,
@@ -95,9 +95,9 @@ export async function createImapClient(
 
 /** Server-Fehler → typisierte Foundation-Fehlerklassen (Plan §2). */
 export function mapImapError(err: unknown, host: string): Error {
-  // imapflow-Fehler tragen die Server-Antwort in responseText, die
-  // message ist nur "Command failed" — beides in den Match einbeziehen;
-  // authenticationFailed ist das verlässliche Flag.
+  // imapflow errors carry the server response in responseText; the
+  // message is only "Command failed", so both are included in the match;
+  // authenticationFailed is the reliable flag.
   const carrier = isPlainObject(err) ? err : undefined;
   const responseText = typeof carrier?.["responseText"] === "string" ? carrier["responseText"] : "";
   const msg = `${err instanceof Error ? err.message : String(err)} ${responseText}`.trim();
@@ -129,9 +129,9 @@ export function parseImapCursor(cursor: SyncCursorPayload | null): ImapCursor |
   return { uidValidity, lastUid };
 }
 
-/** Wirft InboundCursorInvalidError bei UIDVALIDITY-Wechsel — die
- *  Foundation resettet den Cursor und macht einen Voll-Resync im
- *  Backfill-Fenster (Dedup fängt Dubletten). */
+/** Throws InboundCursorInvalidError when UIDVALIDITY changes; the
+ *  foundation resets the cursor and performs a full resync within the
+ *  backfill window (deduplication catches duplicates). */
 export function assertUidValidity(cursor: ImapCursor | null, serverUidValidity: string): void {
   if (cursor && cursor.uidValidity !== serverUidValidity) {
     throw new InboundCursorInvalidError(
@@ -148,8 +148,9 @@ function stripAngles(id: string): string {
   return id.replace(/^<|>$/g, "").trim();
 }
 
-/** References-Chain normalisieren: mailparser liefert string | string[]
- *  | undefined; fehlt References, trägt In-Reply-To den Thread-Anker. */
+/** Normalizes the References chain: mailparser returns string | string[]
+ *  | undefined; when References is missing, In-Reply-To provides the thread
+ *  anchor. */
 export function normalizeReferences(parsed: {
   references?: string | string[];
   inReplyTo?: string;
@@ -170,16 +171,16 @@ function addressList(a: AddressObject | AddressObject[] | undefined): string[] {
   return arr.map((x) => x.text).filter((t): t is string => Boolean(t));
 }
 
-/** imapflow liefert internalDate je nach Codepfad als Date ODER string.
- *  String-Form verwerfen wir bewusst (kein Date-Parsing im Feature-Code,
- *  no-date-api) — toRawInboundMessage fällt dann auf mailparsers
- *  Date-Header zurück, der immer als echtes Date kommt. */
+/** imapflow provides internalDate as either a Date or string depending on
+ *  the code path. The string form is deliberately discarded (no date parsing
+ *  in feature code, no-date-api); toRawInboundMessage then falls back to the
+ *  mailparser Date header, which is always a real Date. */
 export function coerceDate(d: Date | string | undefined): Date | undefined {
   return d instanceof Date ? d : undefined;
 }
 
-/** providerMessageId: UID ist nur innerhalb einer UIDVALIDITY eindeutig
- *  — beides zusammen ist der stabile Idempotency-Anchor. */
+/** providerMessageId: a UID is unique only within a UIDVALIDITY; together,
+ *  they form the stable idempotency anchor. */
 export function buildProviderMessageId(uidValidity: string, uid: number): string {
   return `${uidValidity}:${uid}`;
 }
@@ -204,8 +205,8 @@ export async function toRawInboundMessage(args: {
     cc: addressList(parsed.cc),
     subject: parsed.subject ?? "",
     snippet: text.slice(0, SNIPPET_MAX),
-    // Lib-Boundary-Bridge (Date von imapflow/mailparser) → Temporal;
-    // fehlt jedes Datum, ist Epoch der ehrliche Marker.
+    // Lib-boundary bridge (Date from imapflow/mailparser) → Temporal;
+    // when no date exists, Epoch is the honest marker.
     receivedAtIso: (receivedAt
       ? legacyDateToInstant(receivedAt)
       : Temporal.Instant.fromEpochMilliseconds(0)

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

@@ -1,15 +1,15 @@
 // kumiko-feature-version: 1
 //
-// inbound-provider-inmemory — scriptbarer In-Memory-Provider für die
-// inbound-mail-foundation Plugin-API. Für Tests, Demos und Sample-Apps:
-// Messages werden per `seedInboundMessage()` eingespeist statt von einem
-// echten Postfach gefetcht; `watch()` pusht geseedete Messages sofort
-// (IDLE-Simulation), `fetch()` liefert sie cursor-basiert nach
-// (Reconciliation-Pfad) — beide Pfade zusammen exercisen exakt die
-// Dedup-Garantie der Foundation.
+// inbound-provider-inmemory — scriptable in-memory provider for the
+// inbound-mail-foundation plugin API. For tests, demos, and sample apps:
+// messages are supplied via `seedInboundMessage()` instead of being fetched
+// from a real mailbox; `watch()` immediately pushes seeded messages
+// (IDLE simulation), while `fetch()` returns them by cursor
+// (reconciliation path). Together, both paths exercise the foundation's
+// deduplication guarantee exactly.
 //
-// **Pattern-Vorbild:** mail-transport-inmemory (module-level State +
-// Test-Helper-Exports). NICHT für Production.
+// **Pattern basis:** mail-transport-inmemory (module-level state +
+// test-helper exports). Not for production.
 
 import type {
   InboundFetchResult,
@@ -24,8 +24,8 @@ const FEATURE_NAME = "inbound-provider-inmemory";
 export const INMEMORY_PROVIDER_KEY = "inmemory";
 
 // =============================================================================
-// Module-level State — pro Account: Message-Log (append-only, wie ein
-// echtes Postfach), aktive Watch-Handler, One-Shot-Fehlerinjektion.
+// Module-level state — per account: an append-only message log, like a real
+// mailbox; active watch handlers and one-shot error injection.
 // =============================================================================
 
 type WatchHandlers = {
@@ -51,28 +51,28 @@ function stateFor(accountId: string): AccountState {
   return state;
 }
 
-/** Test-Helper: Message ins Postfach legen. Läuft ein watch, wird sie
- *  sofort gepusht (IDLE-Simulation); der nächste fetch liefert sie
- *  cursor-basiert ebenfalls — Dedup der Foundation macht das idempotent. */
+/** Test helper: adds a message to the mailbox. If a watch is active, it is
+ *  pushed immediately (IDLE simulation); the next fetch also returns it by
+ *  cursor — the foundation's deduplication makes this idempotent. */
 export async function seedInboundMessage(accountId: string, msg: RawInboundMessage): Promise<void> {
   const state = stateFor(accountId);
   state.log.push(msg);
   if (state.watch) await state.watch.onMessages([msg]);
 }
 
-/** Test-Helper: One-Shot-Fehler für den nächsten fetch (z.B.
- *  InboundAuthError, InboundCursorInvalidError). */
+/** Test helper: injects a one-shot error into the next fetch (e.g.
+ *  InboundAuthError or InboundCursorInvalidError). */
 export function failNextFetchWith(accountId: string, err: unknown): void {
   stateFor(accountId).nextFetchError = err;
 }
 
-/** Test-Helper: One-Shot-Fehler für das nächste verify. */
+/** Test helper: injects a one-shot error into the next verify. */
 export function failNextVerifyWith(accountId: string, err: unknown): void {
   stateFor(accountId).nextVerifyError = err;
 }
 
-/** Test-Helper: Tod der Live-Verbindung simulieren (Supervisor muss
- *  mit Backoff neu starten). */
+/** Test helper: simulates the live connection terminating (the supervisor
+ *  must restart with backoff). */
 export function emitWatchError(accountId: string, err: unknown): void {
   const state = accounts.get(accountId);
   if (state?.watch) {
@@ -82,7 +82,7 @@ export function emitWatchError(accountId: string, err: unknown): void {
   }
 }
 
-/** Test-Helper: läuft gerade ein watch für den Account? */
+/** Test helper: reports whether an account currently has an active watch. */
 export function isWatching(accountId: string): boolean {
   return accounts.get(accountId)?.watch != null;
 }
@@ -94,7 +94,7 @@ export function resetInboundInMemory(): void {
 }
 
 // =============================================================================
-// Plugin — cursor = { offset: number } über das append-only-Log.
+// Plugin — cursor = { offset: number } over the append-only log.
 // =============================================================================
 
 function offsetOf(cursor: SyncCursorPayload | null): number {

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

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "readRoles for tenant job status",
+    "detail": "`createJobsFeature({ readRoles: [\"PropertyManager\"] })` lets those app roles call `jobs:query:failures` and `jobs:query:tenant-runs` for their own tenant. They are added to the default `User`, `Editor` and admin roles, which stay. Before, a member who only holds app roles got access_denied.",
+    "migration": "Optional. Apps whose members hold only their own roles pass `createJobsFeature({ readRoles: [...] })`."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Deduplicated job add keeps the finished tenant run row",
+    "detail": "JobQueuedMeta carries the BullMQ creation time of the job. The queued hook only removes finished rows queued before that time (leftovers of a Redis reset), so re-announcing an already finished job no longer turns its row back into queued."
+  },
   {
     "version": "0.384.0",
     "type": "improvement",

package/packages/bundled-features/src/jobs/db/queries/retention.ts

@@ -1,4 +1,4 @@
-// Job-run retention (#2243): store_job_runs/store_job_run_logs are
+// Job-run retention: store_job_runs/store_job_run_logs are
 // direct-write stores now, not event-sourced projections — nothing else
 // purges them, so without this query they grow forever with the run count
 // instead of the runtime. Not the retention-cleanup executor: that executor
@@ -44,7 +44,7 @@ export async function deleteStaleJobRuns(
     { limit: RETENTION_DELETE_BATCH_SIZE },
   );
 
-  // Same window for the tenant-visible failure records (fw#3079): the run
+  // Same window for the tenant-visible failure records: the run
   // they point at is gone by now, and a job whose subject never ran again
   // would otherwise keep its record forever.
   const tenantFailuresResult = await deleteManyBatched(

package/packages/bundled-features/src/jobs/db/queries/stale-run-sweep.ts

@@ -1,5 +1,5 @@
-// Stale job-run sweep (#2246): store_job_runs is a direct-write store
-// (#2243) — status is set to "running" once at onJobStart and only ever
+// Stale job-run sweep: store_job_runs is a direct-write store
+// Status is set to "running" once at onJobStart and only ever
 // flipped to "completed"/"failed" by onJobComplete/onJobFailed. If the
 // process dies mid-run (crash, OOM, kill -9), those callbacks never fire and
 // the row is stuck on "running" forever — nothing else on the read side
@@ -48,7 +48,7 @@ export async function markStaleJobRunsFailed(
   // user subject annotation as job-run-logger.ts's onJobFailed path
   // (personal: { of: "triggeredById" } on job-run-table.ts), so it is encrypted
   // under the triggering user's DEK, or the system tenant key when
-  // triggeredById is null (whenAbsent: "tenant", fw#3654). Runs are grouped by
+  // triggeredById is null (whenAbsent: "tenant"). Runs are grouped by
   // that subject: one encrypt and one updateMany per subject instead of per run.
   const stale = await selectMany<{ id: string; triggeredById: string | null }>(db, jobRunsTable, {
     status: "running",

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

@@ -1,4 +1,4 @@
-// Payload schemas for the jobRun direct-write path (#2243). Pre-#2243 these
+// Payload schemas for the jobRun direct-write path. Previously these
 // 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

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

@@ -23,8 +23,8 @@ import {
   createStaleRunSweepJob,
   DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS,
 } from "./handlers/stale-run-sweep.job.ts";
-import { tenantFailuresQuery } from "./handlers/tenant-failures.query.ts";
-import { tenantRunsQuery } from "./handlers/tenant-runs.query.ts";
+import { createTenantFailuresQuery } from "./handlers/tenant-failures.query.ts";
+import { createTenantRunsQuery } from "./handlers/tenant-runs.query.ts";
 import { triggerWrite } from "./handlers/trigger.write.ts";
 import { jobRunLogsTableMeta, jobRunsTableMeta } from "./job-run-table.ts";
 import {
@@ -44,16 +44,26 @@ export type JobsFeatureOptions = {
   // which a tenant-visible "queued" row counts as lost and is dropped by the stale-run sweep.
   readonly retentionDays?: number;
   // How long a run can sit at status "running" before the hourly
-  // stale-run-sweep job marks it "failed" (#2246 — a process kill mid-run
+  // stale-run-sweep job marks it "failed" — a process kill mid-run
   // never fires onJobComplete/onJobFailed, so nothing else ever revisits
   // it). Must clear any legitimately long-running job (reindexEntity,
   // projectionRebuild) — set high, not tight.
   readonly staleRunTimeoutHours?: number;
+  // Additional app roles that may read their own tenant's job status and
+  // failures (jobs:query:failures, jobs:query:tenant-runs). Added to the default
+  // User/Editor/admin roles, which stay; the scope stays the caller's own tenant.
+  readonly readRoles?: readonly string[];
 };
 
 export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefinition {
   const retentionDays = options.retentionDays ?? DEFAULT_JOB_RUN_RETENTION_DAYS;
   const staleRunTimeoutHours = options.staleRunTimeoutHours ?? DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS;
+  const readRoles = options.readRoles ?? [];
+  if (readRoles.includes("anonymous")) {
+    throw new Error(
+      `createJobsFeature: readRoles must not contain "anonymous" — job status and failures are only readable by members of the tenant.`,
+    );
+  }
   return defineFeature("jobs", (r) => {
     r.describe(
       "Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution writes directly into `store_job_runs` (current status + duration) and `store_job_run_logs` (per-line log rows) from the BullMQ callbacks — no event stream in between (#2243). A daily `retention-cleanup` job deletes runs (and their logs) older than `retentionDays`; an hourly `stale-run-sweep` job marks runs stuck at status `running` past `staleRunTimeoutHours` as `failed` (#2246 — a crashed worker never fires the completion callback, so nothing else ever revisits the row). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list`, `jobs:query:details`, and `jobs:query:catalog` (manual jobs) for the operator UI. A job that declares `tenantVisibleFailure` also records its last failed attempt per tenant and subject in `store_tenant_job_failures`, which the tenant itself reads through `jobs:query:failures` — a translation key only, never the provider's message (fw#3079). A job that declares `tenantVisibleRun` also keeps its run state per tenant and subject in `store_tenant_job_runs` (queued, running, plus the latest completed or failed run, no payload, error text or logs), which the tenant reads through `jobs:query:tenant-runs` (fw#3616); the stale-run sweep fails its stuck `running` rows and drops `queued` rows older than `retentionDays`.",
@@ -67,11 +77,10 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
     r.storeTable(jobRunsTableMeta, {
       reason: "direct_write.job_runs",
       // payload/error carry personal:{of:"triggeredById"} (job-run-table.ts): encrypted under the
-      // triggering user's DEK, or the system tenant key when triggeredById is null
-      // (whenAbsent: "tenant", fw#3654).
+      // triggering user's DEK, or the system tenant key when triggeredById is null.
       // job-run-logger.ts manually encrypts both before every insert/update
       // (encryptStartedPayload/encryptFailureError) since this store bypasses
-      // the executor's automatic PII pipeline (#2243).
+      // the executor's automatic PII pipeline.
       piiEncryptedOnWrite: true,
     });
     r.storeTable(jobRunLogsTableMeta, {
@@ -91,7 +100,7 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
       projectionRebuildJob,
     );
 
-    // Retroactive search backfill (#1206/#1215) — manual + perTenant, so one
+    // Retroactive search backfill — manual + perTenant, so one
     // `jobs:write:trigger` call with { entity } fans out to every active
     // tenant (job-runner.ts perTenant dispatch applies to manual triggers
     // too, not just cron).
@@ -107,7 +116,7 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
     );
 
     // store_job_runs/store_job_run_logs are direct-write, unbounded-growth
-    // stores (#2243) — nothing else purges them.
+    // stores — nothing else purges them.
     r.job(
       "retention-cleanup",
       { trigger: { cron: "0 3 * * *" }, concurrency: "skip" },
@@ -115,7 +124,7 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
     );
 
     // Sweeps store_job_runs for rows stuck at status "running" past the
-    // timeout (#2246). Hourly matches the timeout's own granularity —
+    // timeout. Hourly matches the timeout's own granularity —
     // frequent enough to catch a stuck run soon after it crosses the
     // threshold, cheap enough that an (almost always empty) result set
     // doesn't matter.
@@ -138,8 +147,8 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
       list: r.queryHandler(listQuery),
       detail: r.queryHandler(detailQuery),
       catalog: r.queryHandler(catalogQuery),
-      failures: r.queryHandler(tenantFailuresQuery),
-      tenantRuns: r.queryHandler(tenantRunsQuery),
+      failures: r.queryHandler(createTenantFailuresQuery(readRoles)),
+      tenantRuns: r.queryHandler(createTenantRunsQuery(readRoles)),
       consumers: r.queryHandler(consumersQuery),
       consumerDetails: r.queryHandler(consumerDetailQuery),
     };

package/packages/bundled-features/src/jobs/handlers/detail.query.ts

@@ -32,12 +32,12 @@ export const detailQuery = defineQueryHandler({
 
     if (!row) return null;
 
-    // payload is stored encrypted under the triggering user's DEK (#799).
+    // payload is stored encrypted under the triggering user's DEK.
     if (typeof row["payload"] === "string") {
       row["payload"] = await decryptStoredPii(row["payload"], "payload", "job-run-detail");
     }
 
-    // error is stored encrypted under the triggering user's DEK (#2307),
+    // error is stored encrypted under the triggering user's DEK,
     // same mechanism as row.payload above.
     if (typeof row["error"] === "string") {
       row["error"] = await decryptStoredPii(row["error"], "error", "job-run-detail");
@@ -52,8 +52,8 @@ export const detailQuery = defineQueryHandler({
       },
     );
 
-    // message is stored encrypted under the triggering user's DEK (#2247),
-    // same mechanism as row.payload above. Bounded concurrency (#2307) —
+    // message is stored encrypted under the triggering user's DEK,
+    // same mechanism as row.payload above. Bounded concurrency —
     // unbounded Promise.all would fire one decrypt per log line at once
     // against the KMS adapter's pool.
     const decryptedLogs = await mapWithConcurrency(logs, KMS_POOL_CONCURRENCY, async (log) => {

package/packages/bundled-features/src/jobs/handlers/list.query.ts

@@ -109,7 +109,7 @@ export const listQuery = defineQueryHandler({
     // capped at the page size and would silently undercount the total.
     const total =
       query.payload.totalCount === true ? await countWhere(db, jobRunsTable, where) : undefined;
-    // payload/error are stored encrypted under the triggering user's DEK (#799, #2307).
+    // payload/error are stored encrypted under the triggering user's DEK.
     return {
       rows: await mapWithConcurrency(rows, KMS_POOL_CONCURRENCY, decryptRunRow),
       nextCursor: hasMore ? encodeCursor(String(offset + limit)) : null,

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

@@ -8,7 +8,7 @@ import * as z from "zod";
 
 export const projectionRebuildPayloadSchema = z.object({
   projection: z.string().min(1),
-  // Quarantine mode (#760): skip + dead-letter poison events instead of
+  // Quarantine mode: skip + dead-letter poison events instead of
   // failing the whole rebuild. Operator opt-in per run.
   skipApplyErrors: z.boolean().optional(),
 });

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

@@ -1,4 +1,4 @@
-// Manual, perTenant backfill job (#1206/#1215) — indexes existing rows for
+// Manual, perTenant backfill job — indexes existing rows for
 // an entity that only got `searchable: true` after rows already existed.
 // perTenant fan-out (job-runner.ts) also applies to a manual dispatch, not
 // just cron: one `jobs:write:trigger` call with { entity } re-runs once per

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

@@ -58,7 +58,7 @@ export const retryWrite = defineWriteHandler({
       );
     }
 
-    // payload is stored encrypted under the triggering user's DEK (#799),
+    // payload is stored encrypted under the triggering user's DEK,
     // same mechanism as detail.query.ts/list.query.ts — decrypt before
     // parsing it as JSON. A key erased since the run finished decrypts to
     // PII_ERASED_SENTINEL, which is not JSON; reject the retry rather than

package/packages/bundled-features/src/jobs/handlers/tenant-failures.query.ts

@@ -30,44 +30,49 @@ function parseSubject(stored: string | null): Record<string, unknown> | null {
   return Object.fromEntries(parsed.filter(isSubjectEntry));
 }
 
-export const tenantFailuresQuery = defineQueryHandler({
-  name: "failures",
-  description:
-    "Lists the calling tenant's own failed jobs — one record per job and subject, newest first, each carrying a translation key for the reason, never the provider's own error message; the optional subject filter matches exactly: all declared subjectFields with the same JSON types as the job payload; use it to tell a tenant that their asynchronous job failed instead of leaving the screen waiting.",
-  schema: z.object({
-    jobName: z.string().optional(),
-    subject: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
-    limit: z.number().int().min(1).max(200).optional(),
-  }),
-  // Every membership rank: a failure record carries a job name and a
-  // translation key, nothing a team member of the tenant may not see.
-  access: { roles: access.roles("User", "Editor", ...access.admin) },
-  handler: async (query, ctx) => {
-    if (!ctx.systemDb) {
-      throw new InternalError({
-        message: "jobs:query:failures requires ctx.systemDb (feature must declare r.systemScope())",
+export function createTenantFailuresQuery(readRoles: readonly string[]) {
+  return defineQueryHandler({
+    name: "failures",
+    description:
+      "Lists the calling tenant's own failed jobs — one record per job and subject, newest first, each carrying a translation key for the reason, never the provider's own error message; the optional subject filter matches exactly: all declared subjectFields with the same JSON types as the job payload; use it to tell a tenant that their asynchronous job failed instead of leaving the screen waiting.",
+    schema: z.object({
+      jobName: z.string().optional(),
+      subject: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+      limit: z.number().int().min(1).max(200).optional(),
+    }),
+    // Every membership rank: a failure record carries a job name and a
+    // translation key, nothing a team member of the tenant may not see.
+    access: {
+      roles: [...new Set([...access.roles("User", "Editor", ...access.admin), ...readRoles])],
+    },
+    handler: async (query, ctx) => {
+      if (!ctx.systemDb) {
+        throw new InternalError({
+          message:
+            "jobs:query:failures requires ctx.systemDb (feature must declare r.systemScope())",
+        });
+      }
+      // assertTenantMatch is a self-check on the caller and returns the same
+      // unfiltered system-mode db (tenant-db.ts) — the explicit tenantId below
+      // is the filter, assertRowsTenant the second net. There is no
+      // cross-tenant mode here: SystemAdmin reads runs via jobs:query:list.
+      const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+      const where: Record<string, unknown> = { tenantId: [query.user.tenantId] };
+      if (query.payload.jobName) where["jobName"] = query.payload.jobName;
+      if (query.payload.subject) where["subject"] = serializeJobSubject(query.payload.subject);
+      const rows = await selectMany<TenantJobFailureRow>(db, tenantJobFailuresTable, where, {
+        orderBy: { col: "failedAt", direction: "desc" },
+        limit: query.payload.limit ?? DEFAULT_LIMIT,
       });
-    }
-    // assertTenantMatch is a self-check on the caller and returns the same
-    // unfiltered system-mode db (tenant-db.ts) — the explicit tenantId below
-    // is the filter, assertRowsTenant the second net. There is no
-    // cross-tenant mode here: SystemAdmin reads runs via jobs:query:list.
-    const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
-    const where: Record<string, unknown> = { tenantId: [query.user.tenantId] };
-    if (query.payload.jobName) where["jobName"] = query.payload.jobName;
-    if (query.payload.subject) where["subject"] = serializeJobSubject(query.payload.subject);
-    const rows = await selectMany<TenantJobFailureRow>(db, tenantJobFailuresTable, where, {
-      orderBy: { col: "failedAt", direction: "desc" },
-      limit: query.payload.limit ?? DEFAULT_LIMIT,
-    });
-    return {
-      rows: ctx.systemDb.assertRowsTenant(rows, "tenantId").map((row) => ({
-        jobName: row.jobName,
-        subject: parseSubject(row.subject),
-        messageKey: row.messageKey,
-        failedAt: row.failedAt,
-      })),
-      nextCursor: null,
-    };
-  },
-});
+      return {
+        rows: ctx.systemDb.assertRowsTenant(rows, "tenantId").map((row) => ({
+          jobName: row.jobName,
+          subject: parseSubject(row.subject),
+          messageKey: row.messageKey,
+          failedAt: row.failedAt,
+        })),
+        nextCursor: null,
+      };
+    },
+  });
+}

package/packages/bundled-features/src/jobs/handlers/tenant-runs.query.ts

@@ -32,63 +32,67 @@ function parseSubject(stored: string | null): Record<string, unknown> | null {
   return Object.fromEntries(parsed.filter(isSubjectEntry));
 }
 
-export const tenantRunsQuery = defineQueryHandler({
-  name: "tenant-runs",
-  description:
-    "Lists the calling tenant's own job runs that opted in via tenantVisibleRun — per job and subject every queued or running run plus the latest completed or failed one, active runs first, then newest first; each row carries only status and queuedAt/startedAt/finishedAt, never payloads, error text or logs; the optional subject filter matches exactly: all declared subjectFields with the same JSON types as the job payload; use it to show whether work for a subject is waiting, running or done, and to tell a failed run from a finished one.",
-  schema: z.object({
-    jobName: z.string().optional(),
-    subject: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
-    limit: z.number().int().min(1).max(200).optional(),
-  }),
-  // Every membership rank: a run state carries a job name, a status and
-  // times, nothing a team member of the tenant may not see.
-  access: { roles: access.roles("User", "Editor", ...access.admin) },
-  handler: async (query, ctx) => {
-    if (!ctx.systemDb) {
-      throw new InternalError({
-        message:
-          "jobs:query:tenant-runs requires ctx.systemDb (feature must declare r.systemScope())",
+export function createTenantRunsQuery(readRoles: readonly string[]) {
+  return defineQueryHandler({
+    name: "tenant-runs",
+    description:
+      "Lists the calling tenant's own job runs that opted in via tenantVisibleRun — per job and subject every queued or running run plus the latest completed or failed one, active runs first, then newest first; each row carries only status and queuedAt/startedAt/finishedAt, never payloads, error text or logs; the optional subject filter matches exactly: all declared subjectFields with the same JSON types as the job payload; use it to show whether work for a subject is waiting, running or done, and to tell a failed run from a finished one.",
+    schema: z.object({
+      jobName: z.string().optional(),
+      subject: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+      limit: z.number().int().min(1).max(200).optional(),
+    }),
+    // Every membership rank: a run state carries a job name, a status and
+    // times, nothing a team member of the tenant may not see.
+    access: {
+      roles: [...new Set([...access.roles("User", "Editor", ...access.admin), ...readRoles])],
+    },
+    handler: async (query, ctx) => {
+      if (!ctx.systemDb) {
+        throw new InternalError({
+          message:
+            "jobs:query:tenant-runs requires ctx.systemDb (feature must declare r.systemScope())",
+        });
+      }
+      // assertTenantMatch returns the same unfiltered system-mode db — the
+      // explicit tenantId below is the filter, assertRowsTenant the second net.
+      const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
+      const where: Record<string, unknown> = { tenantId: [query.user.tenantId] };
+      if (query.payload.jobName) where["jobName"] = query.payload.jobName;
+      if (query.payload.subject) where["subject"] = serializeJobSubject(query.payload.subject);
+      const limit = query.payload.limit ?? DEFAULT_LIMIT;
+      const newestFirst = { col: "updatedAt", direction: "desc" } as const;
+      const activeRows = await selectMany<TenantJobRunRow>(
+        db,
+        tenantJobRunsTable,
+        { ...where, status: { in: ["queued", "running"] } },
+        { orderBy: newestFirst, limit },
+      );
+      const finishedRows = await selectMany<TenantJobRunRow>(
+        db,
+        tenantJobRunsTable,
+        { ...where, status: { in: ["completed", "failed"] } },
+        { orderBy: newestFirst, limit },
+      );
+      const seenFinishedKeys = new Set<string>();
+      const finishedNewestPerKey = finishedRows.filter((row) => {
+        const key = JSON.stringify([row.jobName, row.subject]);
+        if (seenFinishedKeys.has(key)) return false;
+        seenFinishedKeys.add(key);
+        return true;
       });
-    }
-    // assertTenantMatch returns the same unfiltered system-mode db — the
-    // explicit tenantId below is the filter, assertRowsTenant the second net.
-    const db = ctx.systemDb.assertTenantMatch(query.user.tenantId);
-    const where: Record<string, unknown> = { tenantId: [query.user.tenantId] };
-    if (query.payload.jobName) where["jobName"] = query.payload.jobName;
-    if (query.payload.subject) where["subject"] = serializeJobSubject(query.payload.subject);
-    const limit = query.payload.limit ?? DEFAULT_LIMIT;
-    const newestFirst = { col: "updatedAt", direction: "desc" } as const;
-    const activeRows = await selectMany<TenantJobRunRow>(
-      db,
-      tenantJobRunsTable,
-      { ...where, status: { in: ["queued", "running"] } },
-      { orderBy: newestFirst, limit },
-    );
-    const finishedRows = await selectMany<TenantJobRunRow>(
-      db,
-      tenantJobRunsTable,
-      { ...where, status: { in: ["completed", "failed"] } },
-      { orderBy: newestFirst, limit },
-    );
-    const seenFinishedKeys = new Set<string>();
-    const finishedNewestPerKey = finishedRows.filter((row) => {
-      const key = JSON.stringify([row.jobName, row.subject]);
-      if (seenFinishedKeys.has(key)) return false;
-      seenFinishedKeys.add(key);
-      return true;
-    });
-    const activeFirst = [...activeRows, ...finishedNewestPerKey];
-    return {
-      rows: ctx.systemDb.assertRowsTenant(activeFirst.slice(0, limit), "tenantId").map((row) => ({
-        jobName: row.jobName,
-        subject: parseSubject(row.subject),
-        status: row.status,
-        queuedAt: row.queuedAt,
-        startedAt: row.startedAt,
-        finishedAt: row.finishedAt,
-      })),
-      nextCursor: null,
-    };
-  },
-});
+      const activeFirst = [...activeRows, ...finishedNewestPerKey];
+      return {
+        rows: ctx.systemDb.assertRowsTenant(activeFirst.slice(0, limit), "tenantId").map((row) => ({
+          jobName: row.jobName,
+          subject: parseSubject(row.subject),
+          status: row.status,
+          queuedAt: row.queuedAt,
+          startedAt: row.startedAt,
+          finishedAt: row.finishedAt,
+        })),
+        nextCursor: null,
+      };
+    },
+  });
+}

package/packages/bundled-features/src/jobs/job-instant.ts

@@ -1,6 +1,6 @@
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 
-// kumiko-framework#1525: the five value-position Temporal.Instant.from
+// The five value-position Temporal.Instant.from
 // call sites in feature.ts live inside defineApply callbacks with no
 // exported seam, so this thin wrapper gives the ambient-global-independence
 // regression test something to import directly.