@marinoscar/kvox-eval 0.0.0-bootstrap → 0.1.0-next.0

package/host/prisma/schema/platform.jobs.prisma

@@ -0,0 +1,824 @@
+// GENERATED by platform db compose — do not edit
+// source: package:jobs.prisma
+
+// =============================================================================
+// Jobs (issue #255, epic #254)
+// =============================================================================
+//
+// A generic background-job queue table: one row per unit of work a worker
+// node claims, runs, and reports the outcome of. This issue adds only the
+// schema — the enqueue path, the claim query, and the node plane that
+// actually pulls jobs off this table all arrive in later issues of #254
+// (the claim query's `RETURNING` aliases land in #260, the `WorkerNode` model
+// that `claimedByNodeId` will finally point at lands with the node plane).
+// What is here is deliberately complete on its own: every column and index a
+// worker needs to claim, execute, retry, and rate-limit a job, so nothing
+// downstream requires a follow-up migration to `jobs` itself.
+//
+// -----------------------------------------------------------------------------
+// subjectType / subjectId — plain nullable TEXT, not typed or FK'd columns
+// -----------------------------------------------------------------------------
+// REJECTED: a column per subject shape (`mediaItemId`, `circleId`, ...). This
+// table is generic across every handler `type` this app will ever register,
+// present and future. A typed column per subject means every new job kind
+// that targets a new kind of thing is a migration to this table, which is
+// exactly the coupling a job queue must not have to its callers — the whole
+// point of `type` being a free-form handler key is that new handlers cost
+// zero schema changes. `subjectType` (a short discriminator string the
+// handler itself defines, e.g. `'media_item'`) plus `subjectId` (that
+// subject's id, stored as text specifically so it is not assumed to be a
+// UUID — some future subject might key by something else) covers every shape
+// with two columns, forever.
+//
+// REJECTED: payload-only, with no subject columns at all (dig the subject id
+// out of the JSONB `payload` when you need it). This is what `[subjectType,
+// subjectId]` below exists to make wrong: "cancel every pending job for this
+// media item" and "is there already an active job for this exact subject"
+// (the dedup index just below) are both real, known queries (not
+// speculative), and neither is expressible as an index over JSONB without a
+// GIN index and a much more awkward query. Two plain columns, indexed
+// normally, are simpler and cheaper than making Postgres reach into JSON for
+// a value that is known and named at enqueue time regardless.
+//
+// Both nullable, and BOTH null together is the documented spelling of "this
+// is a global/system job" (a nightly sweep, a cache warm) that is not about
+// any one row elsewhere in the database — there is no sentinel subjectType
+// like `'system'` to keep in sync with anything.
+//
+// -----------------------------------------------------------------------------
+// dedupKey / the active-dedup unique index — enforced by a hand-written
+// partial index, NOT `findFirst` then `create` in the enqueue service
+// -----------------------------------------------------------------------------
+// REJECTED: "check whether an active job with this key already exists, and
+// only insert if not" as application logic. That is a check-then-act race:
+// two concurrent enqueue calls can both see "no active duplicate" and both
+// insert, which is precisely the failure a dedup key exists to prevent, and
+// under real concurrent load (a webhook retried while the first delivery is
+// still being handled, two nodes reacting to the same event) it is not a
+// rare edge case. Only the database can make "is there already an active job
+// with this key" atomic with the insert that would violate it, which is what
+// `jobs_active_dedup_uniq_idx` below is for: a partial UNIQUE index on
+// `dedup_key` filtered to `status IN ('pending','running')`. The enqueue path
+// (arriving with #260) inserts optimistically and treats the resulting
+// unique-violation as "a duplicate is already in flight", not as an error —
+// no pre-check query, no race window.
+//
+// The partial filter is exactly what makes the key reusable: once a job
+// reaches `succeeded` (or `failed`) it drops out of the index's predicate, so
+// the same `dedup_key` is free again for a new active job — retrying or
+// re-triggering the same logical work later is not permanently blocked by
+// its own history. `dedup_key IS NOT NULL` in the predicate is what lets
+// jobs that opt out of dedup (most ad-hoc jobs) insert freely with a NULL key
+// — Postgres does not consider NULLs equal for uniqueness, but the explicit
+// clause documents that this is relied upon, not incidental.
+//
+// The key's actual format (`type:subjectType:subjectId`) is defined ONCE, in
+// `buildDedupKey()` (`src/jobs/job-keys.ts`), which this comment and the
+// migration's raw SQL both point back to rather than restating it — see that
+// file for why the format is what it is.
+//
+// -----------------------------------------------------------------------------
+// priority — ASCENDING is more urgent
+// -----------------------------------------------------------------------------
+// Chosen so `ORDER BY priority ASC, created_at ASC` is both "most urgent
+// first" and "oldest first within a priority", the same direction Postgres
+// already walks a plain ascending b-tree index in — no `DESC` index variant
+// needed for the hot claim-query ordering that `[status, priority,
+// createdAt]` and `[status, scheduledFor, priority, createdAt]` below exist
+// to serve. `0` is the default (normal) priority; more urgent work is a
+// smaller (including negative) number, not a larger one.
+//
+// -----------------------------------------------------------------------------
+// attempts vs rateLimitedAt/rateLimitHits — two counters for two different
+// reasons a job didn't finish, deliberately not merged into one
+// -----------------------------------------------------------------------------
+// `attempts` is charged AT CLAIM TIME (incremented when a worker takes the
+// job, not when it fails) and is what a max-retry policy reads. Being rate
+// limited by a downstream provider is not the job's fault and is not a
+// retry in that sense — charging it against `attempts` would make a job that
+// is simply waiting its turn look like a job that keeps failing, and could
+// exhaust its retry budget for a reason that has nothing to do with the
+// job's own correctness. `rateLimitedAt` / `rateLimitHits` track that
+// separately: `scheduledFor` is pushed out to defer the job, `rateLimitHits`
+// records how often this has happened (for observability/alerting on a
+// provider that is persistently saturated), and neither touches `attempts`.
+//
+// -----------------------------------------------------------------------------
+// providerKey / modelVersion — audit of WHAT ran the job, not inputs to it
+// -----------------------------------------------------------------------------
+// Both nullable and both write-once-at-completion-time metadata: which
+// downstream provider handled this job and which model/version it ran
+// against, for after-the-fact questions ("did the incident affect jobs that
+// ran on provider X" / "which jobs ran before the model version bump").
+// Neither is read back by the claim query — they exist for audit, not for
+// scheduling.
+//
+// -----------------------------------------------------------------------------
+// claimedByNodeId — a real relation as of issue #267, epic #254
+// -----------------------------------------------------------------------------
+// This column existed unconstrained (`String? @db.Uuid`) from #255 onward, so
+// the claim query and its indexes ([status, leaseExpiresAt],
+// [claimedByNodeId]) could be built against their final shape before the
+// `WorkerNode` table it references existed. #267 adds that table and wires
+// the FK on top of this already-populated column: `onDelete: SetNull`, so a
+// node's disappearance (deregistered, pruned, or manually deleted by an
+// admin) frees the jobs it was holding — via `leaseExpiresAt` already having
+// them look abandoned to the reaper — rather than deleting job history. See
+// the block comment above the `WorkerNode` model for the corresponding
+// `onDelete` decision on `WorkerNode.createdBy`, which is a different
+// question (what happens to the NODE when its owning USER is deleted, not
+// what happens to a JOB when its claiming NODE is deleted).
+//
+// -----------------------------------------------------------------------------
+// claimToken — per-claim identity, closing the two-replica lease hole
+// (issue #361)
+// -----------------------------------------------------------------------------
+// `claimedByNodeId` distinguishes a node's claim from the server's, but every
+// API replica claims with `claimedByNodeId: null` — so two different server
+// replicas produce an IDENTICAL `heldLeaseWhere` predicate for the same job,
+// and one replica's renewal cannot be told apart from another's. `claimToken`
+// is minted fresh per claim (not per process, not per batch — see the field
+// comment below for why that distinction matters) and is the extra predicate
+// that makes a specific claim, not just a specific kind of claimant,
+// checkable. Nullable with no default, same as `claimedByNodeId` and
+// `leaseExpiresAt`: `NULL` iff not currently claimed, no backfill, no index —
+// see the migration header (`20260908120000_add_job_claim_token`) for the
+// full argument, which this comment does not restate.
+//
+// -----------------------------------------------------------------------------
+// sumDurationMs on JobStatsRollup — Float (double precision), NOT BigInt
+// -----------------------------------------------------------------------------
+// REJECTED: BigInt. Prisma maps a BigInt column to the JS `bigint` primitive,
+// which `JSON.stringify` refuses outright ("Do not know how to serialize a
+// BigInt") — the not-yet-built insights endpoint that reads this rollup would
+// crash on its very first response, not degrade gracefully. A running sum of
+// per-job durations in milliseconds, even at very high job volume, never
+// approaches the ~2^53 safe-integer boundary where `Float` would start
+// losing precision that matters for an aggregate (an average duration off by
+// fractions of a millisecond at that scale is not a real-world concern);
+// BigInt's exactness buys nothing here and costs a runtime crash.
+//
+// -----------------------------------------------------------------------------
+// Prisma-expressible indexes vs the three below written directly in the
+// migration (INTENTIONAL SCHEMA DRIFT — see migration.sql in
+// 20260906120000_add_jobs)
+// -----------------------------------------------------------------------------
+// Everything Prisma's index DSL can express is declared with `@@index` below.
+// Three more indexes exist ONLY in `migration.sql` because the Prisma schema
+// language has no syntax for a partial index (a `WHERE` clause on the index
+// itself) — `@@index` always builds a full index over every row:
+//
+//   - "jobs_active_dedup_uniq_idx": the partial UNIQUE index described above
+//     that actually enforces the active-dedup constraint (`dedup_key` where
+//     `status IN ('pending','running') AND dedup_key IS NOT NULL`).
+//   - "jobs_attempts_gt1_idx": a partial index on `attempts` where
+//     `attempts > 1`, sized to the small minority of jobs that have ever
+//     been retried, for "show me flaky jobs" without indexing the (large)
+//     majority that succeeded on the first attempt.
+//   - "jobs_succeeded_duration_idx": a partial index on
+//     `(finished_at, started_at, type)` where `status = 'succeeded' AND
+//     started_at IS NOT NULL AND finished_at IS NOT NULL`, for computing
+//     per-type duration stats (what feeds `JobStatsRollup`) without scanning
+//     jobs that were never actually timed.
+//
+// Because `prisma migrate dev`/`diff` cannot regenerate these from the
+// schema file, they will show up as "drift" if anyone ever diffs this schema
+// against the live database with a tool that expects `@@index` to be the
+// full story. That drift is intentional and this comment (plus the ones in
+// the migration itself) is the record of why — do not "fix" it by dropping
+// these three indexes, and do not try to force them into `@@index` syntax
+// that does not exist.
+// @extensible — back-relations only, added with "extend model Job { ... }" in a fragment
+model Job {
+  id String @id @default(uuid()) @db.Uuid
+
+  // The handler key a worker dispatches on (e.g. `'email.send'`,
+  // `'export.csv'`). A small, code-owned, growing set — deliberately a plain
+  // string and not a Prisma enum, for the same reason `NotificationDelivery
+  // .channel` and `.eventKey` are plain strings: new handlers must cost zero
+  // migrations, and a row must be able to outlive the handler that produced
+  // it (a removed/renamed handler's historical jobs stay queryable).
+  type String
+
+  // See the block comment above for why these are plain nullable TEXT rather
+  // than typed/FK'd columns, and why both null together means a
+  // global/system job.
+  subjectType String? @map("subject_type")
+  subjectId   String? @map("subject_id")
+
+  // See the block comment above ("dedupKey / the active-dedup unique index")
+  // for the full mechanism. Built by `buildDedupKey()`
+  // (`src/jobs/job-keys.ts`); nullable because most jobs opt out of dedup
+  // entirely.
+  dedupKey String? @map("dedup_key")
+
+  status JobStatus @default(pending)
+
+  // Why the job was queued: a plain string (an open vocabulary), not a Prisma
+  // enum, for the reason `Job.type` is one. The built-ins are `upload`, `rerun`
+  // and `backfill`; an app adds its own through `registerJobReason`
+  // (`@marinoscar/platform-api/jobs`) at zero migrations. The set a row may
+  // carry is bounded by the contract's `jobReasonSchema` pattern at the API
+  // edge, not by a CHECK constraint, so a row outlives the reason that wrote it.
+  reason String
+
+  // Ascending = more urgent. See the block comment above.
+  priority Int @default(0)
+
+  // Audit of what actually ran this job — see the block comment above.
+  // Written once, at completion; never read by the claim query.
+  providerKey  String? @map("provider_key")
+  modelVersion String? @map("model_version")
+
+  // Handler-defined input, opaque to this table.
+  payload Json? @db.JsonB
+
+  // Charged AT CLAIM TIME (see the block comment above for why this is kept
+  // separate from rateLimitHits).
+  attempts Int @default(0)
+
+  lastError String? @map("last_error")
+
+  createdAt  DateTime  @default(now()) @map("created_at") @db.Timestamptz
+  startedAt  DateTime? @map("started_at") @db.Timestamptz
+  finishedAt DateTime? @map("finished_at") @db.Timestamptz
+
+  // NULL means eligible now. A non-null value in the future is what makes a
+  // job invisible to the claim query until then (deferred rate-limit retries,
+  // deliberately scheduled work).
+  scheduledFor DateTime? @map("scheduled_for") @db.Timestamptz
+
+  // Deferral bookkeeping, deliberately separate from `attempts` — see the
+  // block comment above.
+  rateLimitedAt DateTime? @map("rate_limited_at") @db.Timestamptz
+  rateLimitHits Int       @default(0) @map("rate_limit_hits")
+
+  // Node claiming. See the block comment above ("claimedByNodeId") for why
+  // this relation arrived a migration after the column did, and why
+  // `onDelete: SetNull` is correct here specifically.
+  claimedByNodeId String?     @map("claimed_by_node_id") @db.Uuid
+  claimedByNode   WorkerNode? @relation("NodeClaimedJobs", fields: [claimedByNodeId], references: [id], onDelete: SetNull)
+  leaseExpiresAt  DateTime?   @map("lease_expires_at") @db.Timestamptz
+  // 'server' | 'node' — which side actually executed the job. A plain
+  // string, not an enum, for the same "small closed set, but code-owned and
+  // not this table's own state machine" reasoning as
+  // NotificationDelivery.channel above.
+  executor        String?
+
+  // The identity of ONE CLAIM, not one KIND of claimant (issue #361). Minted
+  // fresh by the claim statement itself (`gen_random_uuid()` in
+  // `job-claim.service.ts`) every time a job is claimed, so "do I still hold
+  // this row" is answerable without reference to who is asking —
+  // `claimedByNodeId` distinguishes a node's claim from the server's, but
+  // every server replica claims with `claimedByNodeId: null`, which makes
+  // two different replicas holding the SAME job at different times
+  // indistinguishable from each other. A token minted per row closes that:
+  // it must be minted PER CLAIM, not once per claiming process or per batch,
+  // because a process-level token has the identical defect one level up — it
+  // cannot tell one process apart from itself across two separate claims of
+  // the same job (claim, lose it to the reaper, claim it again).
+  //
+  // Non-null exactly while the row is claimed — the same "non-null iff held"
+  // invariant `claimedByNodeId`/`leaseExpiresAt` already carry. The claim
+  // writes it alongside them; every un-claim path (settle, the lease reaper,
+  // a retry reset) clears it in the same statement that clears them, never
+  // on its own.
+  //
+  // Deliberately NOT exposed by the admin API — `JOB_LIST_SELECT`
+  // (`job-admin.service.ts`) omits it. It is internal ownership machinery
+  // with no operator-facing meaning; an admin reading the job list cares
+  // which node holds a job, not which of that node's (or the server's)
+  // claims it currently is.
+  claimToken String? @map("claim_token") @db.Uuid
+
+  // The W3C `traceparent` of the span that was active when this job was
+  // ENQUEUED (issue #607), or NULL when nothing was being traced (OTel off, a
+  // cron tick with no active span, a row written before this column existed).
+  // Written once, by `JobsService` at insert time (`job-trace-context.ts`
+  // validates the format and bounds it at 256 characters); never updated.
+  // The server worker starts the job's span as a CHILD of it, and the node
+  // claim hands it to the node, so queued work stays connected to the request
+  // that queued it. Plain nullable TEXT: it is an opaque correlation handle,
+  // never a key, never indexed, never read by the claim query's WHERE.
+  traceContext String? @map("trace_context")
+
+  // The organization the work belongs to (issue #734), or NULL for a
+  // deployment-wide (system) job: housekeeping, fleet sweeps, backups. Written
+  // once at enqueue (`EnqueueJobInput.orgId`, else the app's ambient scope);
+  // never updated. `SetNull`: deleting an organization keeps its job history
+  // (offboarding cancels the org's pending jobs explicitly first, #743).
+  //
+  // ⚠ NO ROW-LEVEL SECURITY ON `jobs`, deliberately. The claim is ONE
+  // cross-organization statement (`FOR UPDATE SKIP LOCKED` over the whole
+  // queue, `job-claim.service.ts`), and a per-org policy would need the bypass
+  // connection for every claim, renewal and settle. Isolation is enforced at
+  // the API: the admin routes are system routes (`jobs:read` / `jobs:write`).
+  // A handler that touches an org table runs under `JobScope.run(job, fn)`.
+  //
+  // ⚠ NOT PART OF THE DEDUP KEY. `jobs_active_dedup_uniq_idx` is unchanged; an
+  // org-scoped job with no natural subject uses `subjectType: 'organization',
+  // subjectId: orgId`, so two organizations never collide.
+  orgId String?       @map("org_id") @db.Uuid
+  org   Organization? @relation(fields: [orgId], references: [id], onDelete: SetNull)
+
+  // See the block comment above ("Prisma-expressible indexes...") for why
+  // these eight are declared here and three more exist only in
+  // migration.sql.
+  //
+  // The hot claim-query orderings:
+
+  // composed from package:db-backup.prisma
+  // The `database_backup_runs` row this job produced, when `type` is
+  // `'db.backup.run'` (epic #345, issue #351). See `DatabaseBackupRun.jobId`
+  // for the full reasoning behind `@unique`/nullable/`SetNull` — this is
+  // just the required other half of that one-to-one relation.
+  backupRun DatabaseBackupRun?
+
+  // composed from app:kvox.ask.prisma
+  // Back-relations onto the platform's Job (an `extend model` block holds back-relation fields only).
+  // The `ask_messages` assistant turn this job is producing (or produced),
+  // when `type` is `'ask.respond'` (epic #348, issues #376/#378). Same
+  // one-to-one shape as `noteGeneration` above, for the same reason:
+  // `AskMessage.jobId` is `@unique`/nullable/`SetNull` because a saved
+  // conversation outlives `job.history.purge`'s schedule for this row.
+  askMessage AskMessage?
+
+  // composed from app:kvox.graph.prisma
+  // Back-relations onto the platform's Job (an `extend model` block holds back-relation fields only).
+  // The `kg_proposals` row this job is extracting (or extracted) into, when
+  // `type` is `'kg.extract'` (epic #344, issue #351). Same one-to-one shape
+  // as `transcriptNameCheck`/`noteGeneration`/`noteExport`/`transcriptExport`/
+  // `backupRun` above, for the same reason: `KgProposal.jobId` is
+  // `@unique`/nullable/`SetNull` because a proposal's own review lifetime is
+  // independent of `job.history.purge`'s schedule for this row.
+  kgProposal KgProposal?
+
+  // The `kg_exports` row this job rendered, when `type` is `'kg.export'`
+  // (issue #386). The `noteExport` shape exactly: `KgExport.jobId` is
+  // `@unique`/nullable/`SetNull` because an export's own 7-day retention is
+  // independent of `job.history.purge`'s schedule for this row.
+  kgExport   KgExport?
+
+  // composed from app:kvox.notes.prisma
+  // Back-relations onto the platform's Job (an `extend model` block holds back-relation fields only).
+  // The `note_exports` row this job rendered, when `type` is `'note.export'`
+  // (issue #48, epic #45). Identical one-to-one shape as `transcriptExport`
+  // immediately above, for the identical reason: `NoteExport.jobId` is
+  // `@unique`/nullable/`SetNull` because export rows have their own 7-day
+  // retention (`notes.housekeeping`), independent of `job.history.purge`'s
+  // schedule for this row.
+  noteExport     NoteExport?
+
+  // The `note_generations` row this job is producing (or produced), when
+  // `type` is `'note.generate'` (issue #48, epic #45). Same one-to-one
+  // shape as `noteExport`/`transcriptExport`/`backupRun` above, for the
+  // same reason: `NoteGeneration.jobId` is `@unique`/nullable/`SetNull`
+  // because a generation's own lifetime (read by the SSE stream and the
+  // note detail page) is independent of `job.history.purge`'s schedule for
+  // this row.
+  noteGeneration NoteGeneration?
+
+  // composed from app:kvox.transcripts.prisma
+  // Back-relations onto the platform's Job (an `extend model` block holds back-relation fields only).
+  // The `transcript_exports` row this job rendered, when `type` is
+  // `'transcript.export'` (issue #24, epic #19). Same one-to-one shape as
+  // `backupRun` immediately above, for the same reason: `TranscriptExport
+  // .jobId` is `@unique`/nullable/`SetNull` because export rows have their
+  // own 7-day retention (`transcripts.housekeeping`), independent of
+  // `job.history.purge`'s schedule for this row.
+  transcriptExport    TranscriptExport?
+
+  // The `transcript_name_checks` row this job ran, when `type` is
+  // `'transcript.name_check'` (issue #328, epic #326). Same one-to-one shape as
+  // `transcriptExport`/`noteExport`/`noteGeneration` above, for the same
+  // reason: `TranscriptNameCheck.jobId` is `@unique`/nullable/`SetNull`
+  // because a run's own lifetime (read by the review UI long after job
+  // history is purged) is independent of `job.history.purge`'s schedule for
+  // this row.
+  transcriptNameCheck TranscriptNameCheck?
+
+  @@index([status, priority, createdAt])
+  @@index([status, scheduledFor, priority, createdAt])
+  // "Every job for this subject" / "is there already a job for this exact
+  // subject":
+  @@index([subjectType, subjectId])
+  // "How is this handler doing" (per-type status breakdown):
+  @@index([type, status])
+  // Lease expiry sweep (finding jobs whose claiming node went away):
+  @@index([status, leaseExpiresAt])
+  // "What is this node holding right now" — also backs the FK added by #267:
+  @@index([claimedByNodeId])
+  // Recency listings (admin job list, "what just happened"):
+  @@index([createdAt(sort: Desc)])
+  // Covering index: the two unconditional admin groupBy counts
+  // (`groupBy({ by: ['status'] })`-shaped queries) are answered entirely from
+  // this index — status, type and id are all it needs to project — so
+  // Postgres never has to visit the heap for them (index-only scan).
+  @@index([status, type, id])
+  // "This organization's jobs by status" (the admin list's `orgId` filter,
+  // offboarding's pending-job cancel; #734). Built CONCURRENTLY in a migration
+  // of its own (`0031_add_jobs_org_id_status_index`): `jobs` is a big table.
+  @@index([orgId, status])
+  @@map("jobs")
+}
+
+enum JobStatus {
+  pending
+  running
+  succeeded
+  failed
+}
+
+// =============================================================================
+// Job Stats Rollup (issue #255, epic #254)
+// =============================================================================
+//
+// One row per `type` (Job.type), maintained incrementally as jobs finish
+// rather than computed by aggregating the full `jobs` table on every read —
+// `jobs` is expected to grow without bound (or be pruned independently of
+// this rollup's needs), so a per-type COUNT/AVG over it is not something the
+// not-yet-built insights endpoint should be doing on every request.
+//
+// `sumDurationMs` is `Float`, deliberately not `BigInt` — see the block
+// comment above the `Job` model ("sumDurationMs on JobStatsRollup") for why
+// BigInt would crash `JSON.stringify` at the exact place this rollup is
+// meant to be read from. Average duration for a type is
+// `sumDurationMs / durationSamples`, computed by the reader; this table
+// stores the two accumulators, not the derived average, so re-deriving after
+// a correction never requires touching historical precision.
+model JobStatsRollup {
+  type String @id
+
+  succeededCount Int @default(0) @map("succeeded_count")
+  failedCount    Int @default(0) @map("failed_count")
+
+  // See the block comment above for why Float, not BigInt.
+  sumDurationMs   Float @default(0) @map("sum_duration_ms")
+  durationSamples Int   @default(0) @map("duration_samples")
+
+  updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  @@map("job_stats_rollup")
+}
+
+// =============================================================================
+// Worker Nodes (issue #267, epic #254)
+// =============================================================================
+//
+// This issue adds only the schema half of the node plane: `WorkerNode`
+// itself, `NodeCredential` (the `nod_` bearer credential a node authenticates
+// with), and the `Job.claimedByNode` relation deferred by #255 (see the
+// block comment above the `Job` model, "claimedByNodeId"). The service that
+// mints/validates `NodeCredential` tokens, the `/api/node-credentials`
+// endpoints, and the `Bearer nod_` branch in `jwt-auth.guard.ts` all arrive
+// in the same issue's backend half; the register/heartbeat/claim control
+// plane that actually populates and mutates `WorkerNode` rows is #268. What
+// is here is deliberately complete on its own for that later work: every
+// column and index the control plane needs already exists, so #268 requires
+// no follow-up migration to either table.
+//
+// -----------------------------------------------------------------------------
+// Why a `NodeCredential` distinct from `PersonalAccessToken`, not a reused PAT
+// -----------------------------------------------------------------------------
+// A worker node runs unattended for months on a machine its operator may not
+// tightly control. A leaked PAT carries its owning user's FULL authority —
+// admin routes included, if the owner is an admin. A node only ever needs to
+// talk to `/api/nodes/*` (enforced by a route allowlist in the guard, not by
+// this schema), so its credential is a distinct token family precisely so a
+// leak's blast radius is confined to that allowlist even for an admin owner.
+// `NodeCredential` mirrors `PersonalAccessToken`'s shape — same hash/prefix
+// pattern, same show-once-in-full contract — MINUS the duration bookkeeping;
+// see the block comment on `NodeCredential.expiresAt` below for why that one
+// column is deliberately not carried over.
+model WorkerNode {
+  id String @id @default(uuid()) @db.Uuid
+
+  name String
+
+  // Self-reported identity, refreshed on every successful register/reattach
+  // and heartbeat (#268) — none of these three are queried on individually,
+  // they exist for the fleet page and for operators diagnosing "which
+  // process is this row". Not part of any uniqueness: a node can rename its
+  // hostname or upgrade its CLI without becoming a different node, because
+  // identity is `(createdById, name)`, not any of these.
+  hostname   String
+  platform   String
+  cliVersion String @map("cli_version")
+
+  // The handler `type` keys (see `Job.type`'s own comment for why that column
+  // is a plain string, not an enum) this node is willing to claim. #268's
+  // claim endpoint INTERSECTS a request's requested types with this list — a
+  // node can only ever narrow what it claims, never broaden it beyond what it
+  // last declared itself capable of running.
+  eligibleTypes String[] @map("eligible_types")
+
+  // The node's own claimed concurrency ceiling, read LIVE by #268's claim
+  // endpoint (not cached at claim time) so a runtime `appctl node
+  // set-concurrency` takes effect on the very next claim without a
+  // re-register.
+  concurrency Int
+
+  // Operator/administrative state, NOT liveness — a node can be `online` and
+  // still be silently dead; that question is answered by comparing
+  // `lastHeartbeatAt` against the heartbeat interval, elsewhere (#270's fleet
+  // cron), not by this column. `disabled` is the operator-driven kill switch
+  // (refuse this node's claims regardless of what it reports); `draining` is
+  // "finish what you're holding, claim nothing new" — both are decisions a
+  // human or #270's lifecycle cron makes, not facts the node reports about
+  // itself.
+  status NodeStatus @default(offline)
+
+  // The node's last self-reported capability summary (CPU/RAM, GPU
+  // presence, disk headroom, ... — the exact shape is #268/#276's to define,
+  // not this schema's) from register or heartbeat. JSONB, not typed columns,
+  // for the same reason `Job.payload` is JSONB: this is opaque, evolving,
+  // node-supplied data that no query here needs to filter or index on —
+  // it exists for the fleet page to display, not for this table to reason
+  // about. Nullable: a node that has never heartbeated has reported nothing
+  // yet.
+  capabilities Json? @db.JsonB
+
+  // When this row was first created (register), vs. `lastHeartbeatAt` below
+  // which moves on every liveness ping. Distinct on purpose: "how long has
+  // this node existed" and "is it still alive" are different questions, and
+  // collapsing them into one timestamp would lose the first once the second
+  // starts moving.
+  registeredAt DateTime @default(now()) @map("registered_at") @db.Timestamptz
+
+  // NULL until the first heartbeat. #270's liveness/prune cron reads this to
+  // decide a node has gone dark; #268's lease reaper reads `Job
+  // .leaseExpiresAt` for the same question about an individual claim — the
+  // two are deliberately independent so a node with no jobs currently
+  // claimed still shows up as stale when it stops heartbeating.
+  lastHeartbeatAt DateTime? @map("last_heartbeat_at") @db.Timestamptz
+
+  // The node's last self-reported vitals snapshot (load, memory, disk, ...)
+  // carried on the heartbeat (#604). Opaque JSONB like `capabilities`: it is
+  // displayed, never filtered or indexed. `lastVitalsAt` is when the API
+  // stored it, so a stale snapshot is distinguishable from a fresh one.
+  // Both NULL until a heartbeat carries vitals.
+  lastVitals   Json?     @map("last_vitals") @db.JsonB
+  lastVitalsAt DateTime? @map("last_vitals_at") @db.Timestamptz
+
+  // The user who registered this node — see the long comment below for why
+  // this is required (not nullable) and `onDelete: Cascade`.
+  createdById String @map("created_by_id") @db.Uuid
+
+  // Relations
+  //
+  // -----------------------------------------------------------------------------
+  // createdBy — onDelete: Cascade, and `createdById` stays required
+  // -----------------------------------------------------------------------------
+  // This is NOT the audit-trail pattern this schema uses elsewhere
+  // (`AuditEvent.actorUserId`, `Credential.updatedByUser`,
+  // `NotificationDelivery.user` — all `SetNull`, all deliberately preserving a
+  // history record after its actor is gone). A `WorkerNode` is closer to
+  // `PushSubscription`: a LIVE registration with no standalone value once its
+  // owner is gone, not a record of a past event. Concretely:
+  //
+  //   1. `NodeCredential.user` is `onDelete: Cascade` (mirroring
+  //      `PersonalAccessToken`, per this table's own design above) — so
+  //      deleting the owning user ALREADY destroys every credential that
+  //      could ever authenticate as this node. A `WorkerNode` row surviving
+  //      its owner would be permanently unauthenticatable inventory: no
+  //      token can ever heartbeat, claim, or deregister it again.
+  //   2. `assertOwnership` (#268) is `node.createdById === callerId` with no
+  //      concept of "unowned" — a `SetNull`'d, ownerless node could not be
+  //      managed (deregistered, disabled, viewed via `GET /nodes`) by
+  //      anyone, ever, through the API this issue's sibling adds. It would
+  //      sit as a permanently orphaned row no admin surface reaches.
+  //   3. `@@unique([createdById, name])` below is #268's register-or-reattach
+  //      anchor. Keeping `createdById` NOT NULL keeps that constraint doing
+  //      real work: two different (deleted-owner) nodes could otherwise both
+  //      carry `createdById: null` with the same `name` and NOT collide
+  //      (Postgres does not treat two NULLs as equal for uniqueness) — a
+  //      silent hole in the exact invariant #268 depends on "existing
+  //      exactly this way" for.
+  //
+  // Cascade does not touch job HISTORY: `Job.claimedByNode` is its own
+  // separate `onDelete: SetNull` (see the block comment above the `Job`
+  // model), so a cascaded `WorkerNode` deletion still only nulls out
+  // `claimedByNodeId` on whatever it was holding — it never deletes a `Job`
+  // row. Losing the fleet-inventory row (hostname, platform, capabilities
+  // history) when its owner's account is gone is an acceptable, even
+  // correct, cleanup; losing job history is not, and nothing here does that.
+  createdBy User @relation("UserWorkerNodes", fields: [createdById], references: [id], onDelete: Cascade)
+
+  // The jobs this node currently holds or has ever held. See `Job
+  // .claimedByNode`'s own comment for the `onDelete: SetNull` that keeps
+  // this list from ever forcing a `Job` deletion.
+  claimedJobs Job[] @relation("NodeClaimedJobs")
+
+  // THE register-or-reattach anchor (#268's own words: "existing exactly
+  // this way"). A node identifies itself to `/nodes/register` by
+  // `(callerId, name)`; this is what lets that endpoint find-or-create
+  // instead of always inserting, so a restarted container reattaches to its
+  // existing row (refreshing hostname/platform/cliVersion/eligibleTypes/
+  // concurrency and flipping back to `online`) rather than leaking a new
+  // node row on every restart. `name` is caller-chosen precisely so one
+  // user can register many distinctly-named nodes while each individual
+  // name stays idempotent for them.
+  @@unique([createdById, name])
+  // "Every online/draining/offline/disabled node" — the fleet page's own
+  // primary filter, and what #270's lifecycle cron scans to find nodes to
+  // act on.
+  @@index([status])
+  // "This user's own nodes" — backs `GET /nodes` (#268: "the caller's own
+  // nodes") and the ownership check inside `assertOwnership`, in addition to
+  // already being the left half of the composite unique index above.
+  @@index([createdById])
+  @@map("worker_nodes")
+}
+
+enum NodeStatus {
+  online
+  draining
+  offline
+  disabled
+}
+
+// -----------------------------------------------------------------------------
+// NodeCredential — mirrors PersonalAccessToken minus the duration bookkeeping
+// -----------------------------------------------------------------------------
+// Same token lifecycle as `PersonalAccessToken` (`pat.service.ts` is the
+// documented model for `NodeCredentialService`): a `nod_`-prefixed token is
+// minted, hashed with sha256 into `tokenHash`, a short `tokenPrefix` is kept
+// for display, and the raw value is shown exactly once. `validateToken`
+// rejects an unknown hash, a `revokedAt`, an expired `expiresAt`, or an
+// inactive owning user, then stamps `lastUsedAt` fire-and-forget — all of
+// that is `NodeCredentialService`'s job (#267's backend half), not this
+// schema's; this model exists to make those checks possible.
+//
+// -----------------------------------------------------------------------------
+// expiresAt — nullable here, REQUIRED on PersonalAccessToken. This is the one
+// deliberate divergence from the PAT shape, and it is worth writing out why.
+// -----------------------------------------------------------------------------
+// A PAT is typically minted for a person's own convenience (the CLI, a
+// script they wrote) and a forced expiry is a reasonable default nudge
+// toward rotation — a human is around to notice it expired and mint a new
+// one. A `NodeCredential` authenticates a worker node that is expected to
+// run UNATTENDED FOR MONTHS: a spare box, a container in someone else's
+// cluster, a machine nobody is watching a dashboard for. If that credential
+// had a mandatory expiry the way a PAT does, the failure mode is an entire
+// fleet going dark at 3am because a timer nobody scheduled fired — the
+// worker can't heartbeat, can't claim, can't report results, and the first
+// anyone learns of it is jobs silently piling up unclaimed. That is a WORSE
+// failure than a long-lived credential, because the credential's blast
+// radius is already confined to `/api/nodes/*` by the guard's route
+// allowlist (issue #267) even if it leaks — the thing a mandatory expiry on
+// a PAT protects against (a leaked token with the owner's full authority)
+// simply does not apply here to the same degree. So `expiresAt` is nullable
+// and NULL is a real, supported, expected value meaning "never expires,
+// authenticate indefinitely until revoked" — not "not yet set". Revocation
+// (`revokedAt`) is the actual control for a node credential, and it is
+// immediate: an operator who needs to cut a node off does so by revoking,
+// not by waiting for a clock. An operator who DOES want an expiring node
+// credential can still set one; the column supports it, it is just not
+// forced.
+model NodeCredential {
+  id String @id @default(uuid()) @db.Uuid
+
+  userId String @map("user_id") @db.Uuid
+
+  // Operator-chosen label ("prod-worker-1", "gpu-box-3"), shown alongside
+  // `tokenPrefix` in list views — same role as `PersonalAccessToken.name`.
+  name String
+
+  // sha256 hash of the full `nod_...` token; the only form of the token this
+  // table ever stores. Never the plaintext — see `NodeCredentialService
+  // .validateToken`'s own documentation for the lookup this backs.
+  tokenHash String @unique @map("token_hash")
+
+  // Short, non-secret display fragment (e.g. the first several characters
+  // after `nod_`) so an operator can tell two credentials apart in a list
+  // without either one's full value ever being shown again after creation.
+  tokenPrefix String @map("token_prefix")
+
+  // See the block comment above for why this is nullable, unlike
+  // `PersonalAccessToken.expiresAt` which is required. NULL = never expires.
+  expiresAt DateTime? @map("expires_at") @db.Timestamptz
+
+  // Stamped fire-and-forget by `validateToken` on each successful
+  // authentication — the operator-facing answer to "is this node actually
+  // still using this credential, or is it dead and safe to revoke".
+  lastUsedAt DateTime? @map("last_used_at") @db.Timestamptz
+
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
+
+  // NULL means active. Set once, never cleared — revocation is a one-way
+  // door, matching `PersonalAccessToken.revokedAt` and `RefreshToken
+  // .revokedAt` elsewhere in this schema. Revocation is immediate: the
+  // block comment above explains why this, not a clock, is the real control
+  // for a node credential.
+  revokedAt DateTime? @map("revoked_at") @db.Timestamptz
+
+  // Relations
+  //
+  // onDelete: Cascade, matching `PersonalAccessToken.user` exactly (per
+  // issue #267's own instruction) and for the identical reason: a node
+  // credential is a live, personal authentication artifact with no
+  // standalone value once its owning account is gone — there is no one left
+  // to authorize a node acting on this user's behalf, and no audit value in
+  // keeping hashed token material around for an account that no longer
+  // exists. See `WorkerNode.createdBy`'s own comment above for how this
+  // Cascade is part of the same reasoning that made `WorkerNode.createdBy`
+  // Cascade too: the two tables are designed to disappear together.
+  user User @relation("UserNodeCredentials", fields: [userId], references: [id], onDelete: Cascade)
+
+  // "This user's own credentials" — backs `GET /api/node-credentials`
+  // (#267's list endpoint), matching `PersonalAccessToken`'s own
+  // `@@index([userId])` for the identical query shape.
+  @@index([userId])
+  @@map("node_credentials")
+}
+
+// =============================================================================
+// Job Node Secrets (issue #349, epic #345)
+// =============================================================================
+//
+// THE AUDIT RECORD OF A CREDENTIAL A WORKER NODE ONCE HELD — and, precisely,
+// NOT the credential. A node has no database access and no storage credentials
+// by design (`docs/specs/worker-nodes.md` §8); epic #345 needs it to run work
+// that genuinely requires one (a `pg_dump` needs a connection), so the server
+// mints one per job, hands it over once, and destroys it on settlement. This
+// table exists so that "which node held a credential to this deployment's
+// database, of what kind, from when until when, and was it revoked" is a
+// question with an answer.
+//
+// -----------------------------------------------------------------------------
+// ⚠ THERE IS NO COLUMN HERE CAPABLE OF HOLDING SECRET MATERIAL, AND THERE MUST
+// NEVER BE — NOT PLAINTEXT, NOT ENCRYPTED
+// -----------------------------------------------------------------------------
+//
+// `handle` is an IDENTIFIER for the grant — a role name, a token id — and it is
+// what `JobSecretBroker.revoke(handle)` takes. It is never the password. The
+// material itself is serialised into exactly one HTTP response
+// (`POST /api/nodes/:id/jobs/:jobId/secret`) and then dropped; nothing in this
+// process, this database, or any backup of it retains a copy.
+//
+// REJECTED: an `encryptedMaterial` column, reusing `SECRETS_ENCRYPTION_KEY` the
+// way the `credentials` table does. A credential that can be re-read is a
+// credential that can be STOLEN TWICE, and nothing needs to re-read this one:
+// the node received it once, and revocation is by handle rather than by
+// presenting the secret back. `credentials` stores material because an SMTP
+// password must be replayed on every send; a job credential must not be
+// replayed at all. Storing it — even encrypted — would buy nothing and would
+// put a live database password into this table, into every `pg_dump` of it,
+// and into every copy of that dump, protected by a key that lives in the same
+// deployment. That is the owner's rule for epic #345 expressed in schema rather
+// than in a convention somebody can forget.
+//
+// -----------------------------------------------------------------------------
+// `@@unique([jobId, kind])` — ONE CREDENTIAL PER JOB, EVER
+// -----------------------------------------------------------------------------
+//
+// A node asks for its secret more than once as a matter of course: a process
+// restarted while holding the lease, a response lost on the way back, a retry
+// of the same job. Every one of those calls must land on the SAME grant,
+// extended — never on a second one, because the revocation paths know exactly
+// one handle per (job, kind) and a sibling grant would be one nothing ever
+// destroys. The unique index makes the second row unrepresentable; the broker's
+// own `issue` idempotence (see `job-secret-broker.ts`) is the other half.
+//
+// `@@index([expiresAt])` backs the sweeper, which scans unrevoked grants whose
+// own clock has lapsed. See `NodeSecretBrokerService.sweep` for why the sweeper
+// is NOT redundant with the settle-event revoker: three real cases emit no
+// event at all.
+//
+// NO RELATIONS, DELIBERATELY. `jobId` and `nodeId` are plain UUID columns with
+// no foreign key either way, for two reasons. `jobs` rows are deleted on a
+// retention schedule (`job.history.purge`) that has nothing to do with a
+// grant's lifetime, and a cascade from that purge would silently erase the
+// audit record of a credential — which is the one thing this table is for. And
+// a grant must stay revocable by handle after its job row is gone, which is
+// why the sweeper resolves a broker by `kind` rather than by the job's `type`.
+model JobNodeSecret {
+  id String @id @default(uuid()) @db.Uuid
+
+  jobId  String @map("job_id") @db.Uuid
+  nodeId String @map("node_id") @db.Uuid
+
+  // Which broker minted this — `JobSecretBroker.kind`, e.g.
+  // `'postgres.readonly'`. Also how the revocation paths find their way back
+  // to the broker that can destroy the grant. A plain string, not an enum, for
+  // the same reason `Job.type` is: a fork's broker must cost zero migrations.
+  kind String
+
+  // The grant's identifier. ⚠ THE ROLE NAME. NEVER THE PASSWORD. See the block
+  // comment above.
+  handle String
+
+  issuedAt  DateTime  @default(now()) @map("issued_at") @db.Timestamptz
+  // The credential's own backstop, bounded by the job's lease (never a second
+  // clock of its own — see `JobSecretBroker.issue`). It is what makes a grant
+  // worthless if BOTH revocation paths somehow miss it.
+  expiresAt DateTime  @map("expires_at") @db.Timestamptz
+  // NULL means the grant is still live as far as this server knows. Set by
+  // whichever revocation path got there first; both tolerate the other having
+  // won.
+  revokedAt DateTime? @map("revoked_at") @db.Timestamptz
+
+  @@unique([jobId, kind])
+  @@index([expiresAt])
+  @@map("job_node_secrets")
+}