@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/jobs/job-run-logger.js

@@ -0,0 +1,305 @@
+import { deleteMany, fetchOne, insertMany, insertOne, updateMany, } from "@cosmicdrift/kumiko-framework/bun-db";
+import { configuredPiiSubjectKms, encryptPiiValueForSubject, KeyErasedError, PII_ERASED_SENTINEL, } from "@cosmicdrift/kumiko-framework/crypto";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { mapWithConcurrency } from "../shared/index.js";
+import { runCompletedSchema, runFailedSchema, runStartedSchema } from "./events.js";
+import { parseJobInstant } from "./job-instant.js";
+import { jobRunLogsTable, jobRunsTable } from "./job-run-table.js";
+import { tenantJobFailuresTable } from "./tenant-job-failure-table.js";
+// Matches PgKmsAdapter's default pool size (see tenant/handlers/*.query.ts) —
+// bounds concurrent getOrCreateDek calls so a large log batch doesn't claim
+// every connection in the pool.
+const KMS_POOL_CONCURRENCY = 4;
+// Default cap on the bullJobId → runId cache. A worker that starts jobs
+// without ever seeing complete/failed callbacks (e.g. crashes mid-run)
+// would otherwise leak entries indefinitely. 10k fits ~1 hour of
+// high-throughput jobs; past that we evict oldest. DB-lookup recovers
+// evicted entries, so correctness isn't at stake — only memory bounds.
+const DEFAULT_CACHE_MAX_ENTRIES = 10_000;
+// Entry TTL. A run that hangs longer than this is either a real stuck
+// worker (ops should alert) or a test-environment run that never fired
+// complete/failed; either way the cache entry has no value. Falls back
+// to DB-lookup if actually needed.
+const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+// Same per-subject encryption as encryptFailureError/encryptStartedPayload,
+// applied to a single value — shared so payload/message/error all go
+// through the identical erased-key fallback. A key erased right before (or
+// between) any of these callbacks must not blow up the write (status is
+// already committed by the time logs/error land): fall back to the
+// sentinel like decryptPiiValueForSubject does on the read side, instead of
+// throwing and dropping the rest of the batch — or, for onJobStart, the
+// whole run row.
+async function encryptOrSentinel(kms, subjectUserId, value, field) {
+    try {
+        return await encryptPiiValueForSubject(kms, { kind: "user", userId: subjectUserId }, value, { requestId: "jobs:job-run-logger" }, field);
+    }
+    catch (e) {
+        if (!(e instanceof KeyErasedError))
+            throw e;
+        return PII_ERASED_SENTINEL;
+    }
+}
+// Same per-subject encryption as encryptStartedPayload, applied to each
+// batched log line's `message` (#2247) before insertMany into
+// jobRunLogsTable — that table is unmanaged/direct-write, so there is no
+// event-piiFields catalog to lean on here either. "message" is the AAD
+// field name and must match the field passed to decryptStoredPii on read
+// (detail.query.ts) or decrypt fails loud. Same skip rules as the payload:
+// null subject (system/cron runs) and absent KMS (rollout mode) both stay
+// plaintext. Bounded concurrency (#2307) — unbounded Promise.all would fire
+// one getOrCreateDek per log line at once against the KMS adapter's pool.
+async function encryptLogMessages(logs, triggeredById) {
+    if (triggeredById === null)
+        return [...logs];
+    const kms = configuredPiiSubjectKms();
+    if (!kms)
+        return [...logs];
+    return mapWithConcurrency(logs, KMS_POOL_CONCURRENCY, async (log) => ({
+        ...log,
+        message: await encryptOrSentinel(kms, triggeredById, log.message, "message"),
+    }));
+}
+// Mirrors encryptFailureError for the failure-path `error` column (#2307):
+// stored alongside logs[].message under the same triggering user's DEK, so
+// a log/error pair from the same failed run decrypt together or erase
+// together. Exported so stale-run-sweep.ts's crash-recovery write (a
+// separate, per-row batch path outside onJobFailed) applies the identical
+// per-subject encryption instead of writing `error` in the clear.
+export async function encryptFailureError(error, triggeredById) {
+    if (triggeredById === null)
+        return error;
+    const kms = configuredPiiSubjectKms();
+    if (!kms)
+        return error;
+    return encryptOrSentinel(kms, triggeredById, error, "error");
+}
+// The run-started payload can carry arbitrary user data; triggeredById
+// names its owning user. No event-PII catalog involved (#2243 removed the
+// jobRun r.defineEvent registrations, so there is nothing to catalog) —
+// the subject is known statically, so we encrypt directly. A null subject
+// (system cron runs, recipient-less triggers) stays plaintext: there is no
+// user key to shred, mirroring the previous event-pii catalog's own skip
+// rule. Absent KMS adapter stays plaintext too (rollout mode, unchanged).
+// A key already erased by the time the trigger lands (#2307) must not fail
+// the whole run-start write — sentinel like the log/error paths.
+async function encryptStartedPayload(payload, triggeredById) {
+    if (payload === null || triggeredById === null)
+        return payload;
+    const kms = configuredPiiSubjectKms();
+    if (!kms)
+        return payload;
+    return encryptOrSentinel(kms, triggeredById, payload, "payload");
+}
+// fw#3079 — which row the tenant-visible failure record lives in: one per
+// (tenant, job, subject), so the next outcome of the same work replaces or
+// clears it. `subject` is null for a job that declares no subjectFields.
+// Null target = nothing to write or clear: the job did not opt in, the run
+// was tenant-less (cron resolves to SYSTEM_TENANT_ID, where no tenant-scoped
+// query could ever read the row), or the caller predates fw#3079 and passes
+// no outcome at all.
+function tenantJobFailureTarget(jobName, outcome) {
+    if (!outcome?.tenantVisible || outcome.tenantId === SYSTEM_TENANT_ID)
+        return null;
+    return { tenantId: outcome.tenantId, jobName, subject: outcome.tenantVisible.subject };
+}
+async function recordTenantJobFailure(db, jobName, outcome) {
+    const where = tenantJobFailureTarget(jobName, outcome);
+    const messageKey = outcome?.tenantVisible?.messageKey;
+    // skip: no tenant-visible target, or an attempt BullMQ may still retry — a
+    // non-final failure must not show the tenant a failure the next attempt
+    // may still resolve.
+    if (!where || !messageKey || outcome?.finalAttempt !== true)
+        return;
+    // ponytail: delete-then-insert instead of an upsert — two runs of the same
+    // key finishing at once can leave two rows, and the query returns the
+    // newest. Add a unique index + ON CONFLICT if that ever matters.
+    await deleteMany(db, tenantJobFailuresTable, where);
+    await insertOne(db, tenantJobFailuresTable, {
+        ...where,
+        messageKey,
+        failedAt: Temporal.Now.instant(),
+    });
+}
+async function clearTenantJobFailure(db, jobName, outcome) {
+    const where = tenantJobFailureTarget(jobName, outcome);
+    // skip: no tenant-visible target — nothing was ever recorded
+    if (!where)
+        return;
+    await deleteMany(db, tenantJobFailuresTable, where);
+}
+export function createJobRunLogger(opts) {
+    const { db } = opts;
+    const runIdByBullJobId = new Map();
+    function cachePut(bullJobId, runId, triggeredById) {
+        // Enforce max-size BEFORE insert. Map iteration returns insertion
+        // order, so dropping the first entry is the oldest.
+        if (runIdByBullJobId.size >= DEFAULT_CACHE_MAX_ENTRIES) {
+            const oldest = runIdByBullJobId.keys().next().value;
+            if (oldest !== undefined)
+                runIdByBullJobId.delete(oldest);
+        }
+        runIdByBullJobId.set(bullJobId, {
+            runId,
+            triggeredById,
+            expiresAt: Date.now() + DEFAULT_CACHE_TTL_MS,
+        });
+    }
+    function cacheGet(bullJobId) {
+        const entry = runIdByBullJobId.get(bullJobId);
+        if (!entry)
+            return undefined;
+        if (Date.now() >= entry.expiresAt) {
+            runIdByBullJobId.delete(bullJobId); // immediate cleanup on terminal callback
+            return undefined;
+        }
+        return entry;
+    }
+    async function resolveRun(bullJobId) {
+        const cached = cacheGet(bullJobId);
+        if (cached)
+            return { runId: cached.runId, triggeredById: cached.triggeredById };
+        const row = await fetchOne(db, jobRunsTable, { bullJobId });
+        if (!row)
+            return undefined;
+        // buildBaseColumns's signature types `id` as `string | number` because
+        // it returns both branches of the idType union. We know this table
+        // was built with idType: "uuid" (see job-run-table.ts), so narrowing
+        // via String() is safe runtime-wise. A proper framework-level fix
+        // would overload buildBaseColumns per idType — scoped out of this
+        // follow-up as its return type has four branches (with/without
+        // softDelete × serial/uuid).
+        const runId = String(row.id);
+        const triggeredById = row.triggeredById ?? null;
+        cachePut(bullJobId, runId, triggeredById);
+        return { runId, triggeredById };
+    }
+    return {
+        onJobStart: async (jobName, bullJobId, meta) => {
+            const runId = generateId();
+            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
+            // drift between feature + logger fails loudly at the source
+            // instead of silently landing on the table.
+            const payload = runStartedSchema.parse({
+                jobName,
+                bullJobId,
+                status: "running",
+                payload: meta.payload ?? null,
+                triggeredById,
+                startedAt: Temporal.Now.instant().toString(),
+                attempt: meta.attempt ?? 1,
+            });
+            const encryptedPayload = await encryptStartedPayload(payload.payload, payload.triggeredById);
+            await insertOne(db, jobRunsTable, {
+                id: runId,
+                tenantId: SYSTEM_TENANT_ID,
+                insertedById: "system",
+                jobName: payload.jobName,
+                bullJobId: payload.bullJobId,
+                status: payload.status,
+                payload: encryptedPayload,
+                attempt: payload.attempt,
+                startedAt: parseJobInstant(payload.startedAt),
+                triggeredById: payload.triggeredById,
+            });
+        },
+        onJobComplete: async (jobName, bullJobId, duration, logs, outcome) => {
+            // Before the run-row write and independent of it: a successful run
+            // clears the tenant's failure record even when the run row itself is
+            // unreachable (the state-loss return below).
+            await clearTenantJobFailure(db, jobName, outcome);
+            const resolved = await resolveRun(bullJobId);
+            // skip: state loss between start + complete (worker restart, cache
+            // evicted AND DB has no matching bull_job_id). Rare edge case; we
+            // drop the completion write rather than forging a run row from
+            // scratch — forensics still has the original BullMQ lifecycle.
+            if (!resolved)
+                return;
+            const { runId, triggeredById } = resolved;
+            const payload = runCompletedSchema.parse({
+                duration,
+                finishedAt: Temporal.Now.instant().toString(),
+                logs: logs.map((l) => ({
+                    level: l.level,
+                    message: l.message,
+                    timestamp: l.timestamp.toString(),
+                })),
+            });
+            await updateMany(db, jobRunsTable, {
+                status: "completed",
+                // Clear stale-sweep error if the run finished after being marked failed.
+                error: null,
+                // integer column — match onJobFailed's Math.round so fractional
+                // BullMQ timings don't trip Postgres integer syntax.
+                duration: Math.round(payload.duration),
+                finishedAt: parseJobInstant(payload.finishedAt),
+                modifiedAt: Temporal.Now.instant(),
+                modifiedById: "system",
+            }, { id: runId });
+            // skip: empty log batch — the worker ran silent. No child rows to
+            // insert; the status update above already recorded completion.
+            if (payload.logs.length > 0) {
+                const encryptedLogs = await encryptLogMessages(payload.logs, triggeredById);
+                await insertMany(db, jobRunLogsTable, encryptedLogs.map((log) => ({
+                    runId,
+                    level: log.level,
+                    message: log.message,
+                    timestamp: parseJobInstant(log.timestamp),
+                })));
+            }
+            runIdByBullJobId.delete(bullJobId); // immediate cleanup on terminal callback
+        },
+        onJobFailed: async (jobName, bullJobId, error, logs, outcome) => {
+            // Mirror of onJobComplete: recorded independently of the run row, so a
+            // tenant still learns their job failed if the row is unreachable.
+            await recordTenantJobFailure(db, jobName, outcome);
+            const resolved = await resolveRun(bullJobId);
+            // skip: same rare state-loss case as in onJobComplete — drop the
+            // failure write rather than forge a run row from scratch.
+            if (!resolved)
+                return;
+            const { runId, triggeredById } = resolved;
+            // Read started_at off the row so we can compute duration
+            // symmetrically to onJobComplete (which gets duration from the
+            // worker). The row already has started_at from onJobStart.
+            const row = await fetchOne(db, jobRunsTable, { id: runId });
+            const now = Temporal.Now.instant();
+            const duration = row
+                ? Math.round(Number(now.since(row.startedAt).total({ unit: "millisecond" })))
+                : 0;
+            const payload = runFailedSchema.parse({
+                duration,
+                finishedAt: now.toString(),
+                error,
+                logs: logs.map((l) => ({
+                    level: l.level,
+                    message: l.message,
+                    timestamp: l.timestamp.toString(),
+                })),
+            });
+            const encryptedError = await encryptFailureError(payload.error, triggeredById);
+            await updateMany(db, jobRunsTable, {
+                status: "failed",
+                error: encryptedError,
+                duration: payload.duration,
+                finishedAt: parseJobInstant(payload.finishedAt),
+                modifiedAt: now,
+                modifiedById: "system",
+            }, { id: runId });
+            // skip: empty log batch — mirror of onJobComplete
+            if (payload.logs.length > 0) {
+                const encryptedLogs = await encryptLogMessages(payload.logs, triggeredById);
+                await insertMany(db, jobRunLogsTable, encryptedLogs.map((log) => ({
+                    runId,
+                    level: log.level,
+                    message: log.message,
+                    timestamp: parseJobInstant(log.timestamp),
+                })));
+            }
+            runIdByBullJobId.delete(bullJobId); // immediate cleanup on terminal callback
+        },
+    };
+}

package/dist/jobs/job-run-table.d.ts

@@ -0,0 +1,197 @@
+import { type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+export type JobRunStatus = "queued" | "running" | "completed" | "failed";
+export type JobLogLevel = "info" | "warn" | "error";
+export declare const jobRunEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
+    jobName: {
+        readonly type: "text";
+        readonly description?: string;
+        readonly maxLength?: number;
+        readonly required?: boolean;
+        readonly searchable?: boolean;
+        readonly sortable?: boolean;
+        readonly filterable?: boolean;
+        readonly encrypted?: boolean;
+        readonly sensitive?: boolean;
+        readonly readAsInstruction?: boolean;
+        readonly format?: "email" | "url" | "phone" | "password";
+        readonly default?: string;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly multiline?: boolean | {
+            readonly rows?: number;
+        };
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+        required: true;
+    };
+    bullJobId: {
+        readonly type: "text";
+        readonly description?: string;
+        readonly maxLength?: number;
+        readonly required?: boolean;
+        readonly searchable?: boolean;
+        readonly sortable?: boolean;
+        readonly filterable?: boolean;
+        readonly encrypted?: boolean;
+        readonly sensitive?: boolean;
+        readonly readAsInstruction?: boolean;
+        readonly format?: "email" | "url" | "phone" | "password";
+        readonly default?: string;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly multiline?: boolean | {
+            readonly rows?: number;
+        };
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+        required: true;
+    };
+    status: {
+        readonly type: "text";
+        readonly description?: string;
+        readonly maxLength?: number;
+        readonly required?: boolean;
+        readonly searchable?: boolean;
+        readonly sortable?: boolean;
+        readonly filterable?: boolean;
+        readonly encrypted?: boolean;
+        readonly sensitive?: boolean;
+        readonly readAsInstruction?: boolean;
+        readonly format?: "email" | "url" | "phone" | "password";
+        readonly default?: string;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly multiline?: boolean | {
+            readonly rows?: number;
+        };
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+        required: true;
+    };
+    payload: {
+        readonly type: "text";
+        readonly description?: string;
+        readonly maxLength?: number;
+        readonly required?: boolean;
+        readonly searchable?: boolean;
+        readonly sortable?: boolean;
+        readonly filterable?: boolean;
+        readonly encrypted?: boolean;
+        readonly sensitive?: boolean;
+        readonly readAsInstruction?: boolean;
+        readonly format?: "email" | "url" | "phone" | "password";
+        readonly default?: string;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly multiline?: boolean | {
+            readonly rows?: number;
+        };
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+        required: false;
+    };
+    error: {
+        readonly type: "text";
+        readonly description?: string;
+        readonly maxLength?: number;
+        readonly required?: boolean;
+        readonly searchable?: boolean;
+        readonly sortable?: boolean;
+        readonly filterable?: boolean;
+        readonly encrypted?: boolean;
+        readonly sensitive?: boolean;
+        readonly readAsInstruction?: boolean;
+        readonly format?: "email" | "url" | "phone" | "password";
+        readonly default?: string;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly multiline?: boolean | {
+            readonly rows?: number;
+        };
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+        required: false;
+    };
+    attempt: {
+        readonly type: "number";
+        readonly description?: string;
+        readonly required?: boolean;
+        readonly sortable?: boolean;
+        readonly filterable?: boolean;
+        readonly sensitive?: boolean;
+        readonly default?: number;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly min?: number;
+        readonly max?: number;
+        readonly integer?: boolean;
+        readonly unit?: string | {
+            readonly field: string;
+        };
+        readonly grouping?: boolean;
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+        required: true;
+    };
+    startedAt: {
+        readonly type: "timestamp";
+        readonly description?: string;
+        readonly required?: boolean;
+        readonly sortable?: boolean;
+        readonly filterable?: boolean;
+        readonly sensitive?: boolean;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly locatedBy?: string;
+        readonly min?: string;
+        readonly max?: string;
+        readonly locale?: string;
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+        required: true;
+    };
+    finishedAt: {
+        readonly type: "timestamp";
+        readonly description?: string;
+        readonly required?: boolean;
+        readonly sortable?: boolean;
+        readonly filterable?: boolean;
+        readonly sensitive?: boolean;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly locatedBy?: string;
+        readonly min?: string;
+        readonly max?: string;
+        readonly locale?: string;
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+        required: false;
+    };
+    duration: {
+        readonly type: "number";
+        readonly description?: string;
+        readonly required?: boolean;
+        readonly sortable?: boolean;
+        readonly filterable?: boolean;
+        readonly sensitive?: boolean;
+        readonly default?: number;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly min?: number;
+        readonly max?: number;
+        readonly integer?: boolean;
+        readonly unit?: string | {
+            readonly field: string;
+        };
+        readonly grouping?: boolean;
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+        required: false;
+    };
+    triggeredById: {
+        readonly type: "text";
+        readonly description?: string;
+        readonly maxLength?: number;
+        readonly required?: boolean;
+        readonly searchable?: boolean;
+        readonly sortable?: boolean;
+        readonly filterable?: boolean;
+        readonly encrypted?: boolean;
+        readonly sensitive?: boolean;
+        readonly readAsInstruction?: boolean;
+        readonly format?: "email" | "url" | "phone" | "password";
+        readonly default?: string;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly multiline?: boolean | {
+            readonly rows?: number;
+        };
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+        required: false;
+    };
+}, "tenant">;
+export declare const jobRunsTable: EntityTableMeta;
+export declare const jobRunsTableMeta: EntityTableMeta;
+export declare const jobRunLogsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const jobRunLogsTableMeta: EntityTableMeta;

package/dist/jobs/job-run-table.js

@@ -0,0 +1,80 @@
+import { defineUnmanagedTable, deriveEntityTableMeta, instant, table as pgTable, serial, text, } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createNumberField, createTextField, createTimestampField, } from "@cosmicdrift/kumiko-framework/engine";
+// jobRun is a system-scoped direct-write store (#2243): every job execution
+// writes straight into jobRunsTable / jobRunLogsTable from the BullMQ
+// callbacks (onJobStart / -Complete / -Failed, see job-run-logger.ts) —
+// no event-store detour. Pre-#2243 this was an events-only aggregate
+// replayed through two inline projections; that generated two permanent
+// `kumiko_events` rows per run for data that is itself already the
+// system of record (no other consumer replays or MSP-subscribes to it).
+//
+// Logs are batched onto the completed/failed callback as an array —
+// "Option B" from the original design discussion: one write per run
+// instead of one write per log line, no log duplication across status
+// transitions. job-run-logger.ts expands the batch into N rows in
+// jobRunLogsTable.
+//
+// Entity-derived table (query API + migration meta share one field
+// definition). status/$type<JobRunStatus> is not modeled in the entity
+// schema — the column type is text, with the status union enforced at the
+// app boundary (same pattern as template-resolver kind/scope).
+// `table: "store_job_runs"` (not `read_*`) because this is no longer a
+// rebuildable projection — `defineUnmanagedTable`/`deriveEntityTableMeta`
+// reject the `read_` prefix for `source: "unmanaged"` (#1208/#1220).
+export const jobRunEntity = createEntity({
+    table: "store_job_runs",
+    fields: {
+        jobName: createTextField({ required: true, personal: false, reason: "system_metadata" }),
+        bullJobId: createTextField({ required: true, personal: false, reason: "system_metadata" }),
+        status: createTextField({ required: true, personal: false, reason: "system_metadata" }),
+        // The run-started payload can carry arbitrary caller-supplied data,
+        // encrypted by job-run-logger.ts under the triggering user's DEK (see
+        // jobs-pii-kms.integration.test.ts) — same subject as `triggeredById`.
+        payload: createTextField({ personal: { of: "triggeredById" }, find: "none" }),
+        // Failure messages can echo payload content back — same subject/DEK as
+        // `payload` (job-run-logger.ts encryptFailureError).
+        error: createTextField({ personal: { of: "triggeredById" }, find: "none" }),
+        attempt: createNumberField({ required: true, default: 1, integer: true }),
+        startedAt: createTimestampField({ required: true }),
+        finishedAt: createTimestampField(),
+        duration: createNumberField({ integer: true }),
+        triggeredById: createTextField({ personal: false, reason: "pseudonymous_fk" }),
+    },
+});
+// Plain EntityTableMeta, NOT a branded EntityTable (buildEntityTable would
+// mark it executor-only): job-run is an unmanaged direct-write store, so
+// onJobStart/-Complete/-Failed need to write via ctx.db/insertOne directly
+// (same pattern as sessions/schema/user-session.ts).
+export const jobRunsTable = deriveEntityTableMeta("job-run", jobRunEntity, {
+    source: "unmanaged",
+});
+export const jobRunsTableMeta = jobRunsTable;
+// Child projection keyed by the jobRun aggregate id. Pre-ES used a serial
+// PK + integer runId; post-ES runId is still exposed but now holds the
+// uuid of the parent jobRun. Existing detail-query callers treat it as an
+// opaque identifier, so the type-switch is backward-compatible at the
+// query surface.
+export const jobRunLogsTable = pgTable("store_job_run_logs", {
+    id: serial("id").primaryKey(),
+    runId: text("run_id").notNull(),
+    level: text("level").notNull().$type(),
+    message: text("message").notNull(),
+    timestamp: instant("timestamp").notNull(),
+});
+// **Unmanaged table** — deliberately no createEntity. Reasoning:
+//   - serial PK (not uuid) — pre-ES legacy, compatible with existing rows
+//   - no tenant_id — child table of jobRun, tenant context lives on the parent
+//   - no base columns (no version/inserted_at/inserted_by_id) — append-only
+//     log, no in-place update, no audit columns needed
+// pgTable stays the source of truth for the query API; this meta mirrors it
+// for migration generation.
+export const jobRunLogsTableMeta = defineUnmanagedTable({
+    tableName: "store_job_run_logs",
+    columns: [
+        { name: "id", pgType: "serial", notNull: true, primaryKey: true },
+        { name: "run_id", pgType: "text", notNull: true },
+        { name: "level", pgType: "text", notNull: true },
+        { name: "message", pgType: "text", notNull: true },
+        { name: "timestamp", pgType: "timestamptz", notNull: true },
+    ],
+});

package/dist/jobs/tenant-job-failure-table.d.ts

@@ -0,0 +1,3 @@
+import { type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+export declare const tenantJobFailuresTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const tenantJobFailuresTableMeta: EntityTableMeta;

package/dist/jobs/tenant-job-failure-table.js

@@ -0,0 +1,29 @@
+import { asEntityTableMeta } from "@cosmicdrift/kumiko-framework/bun-db";
+import { instant, table as pgTable, serial, sql, text, uuid, } from "@cosmicdrift/kumiko-framework/db";
+// The tenant's own view of a failed job (fw#3079). Direct-write store like
+// store_job_runs: job-run-logger.ts writes it from the BullMQ callbacks,
+// outside any dispatcher transaction.
+//
+// Deliberately holds no error text. `message_key` is a translation key
+// (the thrown KumikoError's i18nKey or the one declared at the job), so a
+// provider message can never reach the tenant through this table — it stays
+// on store_job_runs.error and in store_job_run_logs, both SystemAdmin-only.
+//
+// One row per (tenant, job, subject): a later final-attempt failure replaces
+// it, a later successful run of the same key deletes it. `subject` is the
+// canonical JSON of the job's declared subjectFields, or NULL for a job that
+// declares none — stored in clear, so a job must not declare a PII field
+// as its subject.
+export const tenantJobFailuresTable = pgTable("store_tenant_job_failures", {
+    id: serial("id").primaryKey(),
+    tenantId: uuid("tenant_id").notNull(),
+    jobName: text("job_name").notNull(),
+    subject: text("subject"),
+    messageKey: text("message_key").notNull(),
+    failedAt: instant("failed_at").default(sql `now()`).notNull(),
+});
+const derivedTenantJobFailuresTableMeta = asEntityTableMeta(tenantJobFailuresTable);
+if (!derivedTenantJobFailuresTableMeta) {
+    throw new Error("tenantJobFailuresTable: table carries no EntityTableMeta — built via table()?");
+}
+export const tenantJobFailuresTableMeta = derivedTenantJobFailuresTableMeta;

package/dist/jobs/web/client-plugin.d.ts

@@ -0,0 +1,6 @@
+import { type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+export type JobsClientOptions = {
+    readonly translations?: TranslationsByLocale;
+};
+export declare function jobsClient(options?: JobsClientOptions): ClientFeatureDefinition;

package/dist/jobs/web/client-plugin.js

@@ -0,0 +1,10 @@
+// @runtime client
+import { mergeTranslations } from "@cosmicdrift/kumiko-renderer";
+import { JOBS_FEATURE } from "../constants.js";
+import { defaultTranslations } from "./i18n.js";
+export function jobsClient(options) {
+    return {
+        name: JOBS_FEATURE,
+        translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
+    };
+}

package/dist/jobs/web/i18n.d.ts

@@ -0,0 +1,2 @@
+import { type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+export declare const defaultTranslations: TranslationsByLocale;

package/dist/jobs/web/i18n.js

@@ -0,0 +1,4 @@
+// @runtime client
+import { translationsByLocaleFromKeys, } from "@cosmicdrift/kumiko-renderer";
+import { JOBS_I18N } from "../i18n.js";
+export const defaultTranslations = translationsByLocaleFromKeys(JOBS_I18N);

package/dist/jobs/web/index.d.ts

@@ -0,0 +1 @@
+export { type JobsClientOptions, jobsClient } from "./client-plugin.js";

package/dist/jobs/web/index.js

@@ -0,0 +1,2 @@
+// @runtime client
+export { jobsClient } from "./client-plugin.js";