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

package/host/prisma/migrations/20240101000008_add_worker_nodes/migration.sql

@@ -0,0 +1,90 @@
+-- =============================================================================
+-- Worker Nodes (issue #267, epic #254)
+-- =============================================================================
+-- Adds `worker_nodes` and `node_credentials`, and wires the FK on
+-- `jobs.claimed_by_node_id` that was deliberately left unconstrained by
+-- 20260906120000_add_jobs (see that migration's own header comment, and the
+-- block comment above the `Job` model and the `WorkerNode` model in
+-- prisma/schema.prisma for the full reasoning behind every choice below —
+-- this file intentionally does not restate it at length).
+-- =============================================================================
+
+-- CreateEnum
+CREATE TYPE "NodeStatus" AS ENUM ('online', 'draining', 'offline', 'disabled');
+
+-- CreateTable
+CREATE TABLE "worker_nodes" (
+    "id" UUID NOT NULL,
+    "name" TEXT NOT NULL,
+    "hostname" TEXT NOT NULL,
+    "platform" TEXT NOT NULL,
+    "cli_version" TEXT NOT NULL,
+    "eligible_types" TEXT[],
+    "concurrency" INTEGER NOT NULL,
+    "status" "NodeStatus" NOT NULL DEFAULT 'offline',
+    "capabilities" JSONB,
+    "registered_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "last_heartbeat_at" TIMESTAMPTZ,
+    "created_by_id" UUID NOT NULL,
+
+    CONSTRAINT "worker_nodes_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "node_credentials" (
+    "id" UUID NOT NULL,
+    "user_id" UUID NOT NULL,
+    "name" TEXT NOT NULL,
+    "token_hash" TEXT NOT NULL,
+    "token_prefix" TEXT NOT NULL,
+    "expires_at" TIMESTAMPTZ,
+    "last_used_at" TIMESTAMPTZ,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "revoked_at" TIMESTAMPTZ,
+
+    CONSTRAINT "node_credentials_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+-- The register-or-reattach anchor (#268's own words: "existing exactly this
+-- way") — see the block comment above the `WorkerNode` model.
+CREATE UNIQUE INDEX "worker_nodes_created_by_id_name_key" ON "worker_nodes"("created_by_id", "name");
+
+-- CreateIndex
+-- "Every online/draining/offline/disabled node" — the fleet page's primary
+-- filter, and what #270's lifecycle cron scans.
+CREATE INDEX "worker_nodes_status_idx" ON "worker_nodes"("status");
+
+-- CreateIndex
+-- "This user's own nodes" — backs `GET /nodes` and `assertOwnership` (#268).
+CREATE INDEX "worker_nodes_created_by_id_idx" ON "worker_nodes"("created_by_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "node_credentials_token_hash_key" ON "node_credentials"("token_hash");
+
+-- CreateIndex
+-- "This user's own credentials" — backs `GET /api/node-credentials`, the
+-- same query shape as `personal_access_tokens_user_id_idx`.
+CREATE INDEX "node_credentials_user_id_idx" ON "node_credentials"("user_id");
+
+-- AddForeignKey
+-- onDelete: Cascade — a WorkerNode is a live registration with no standalone
+-- value once its owner is gone (its NodeCredential rows are already gone via
+-- their own Cascade below, so an orphaned node could never authenticate
+-- again). See the block comment above `WorkerNode.createdBy` in
+-- prisma/schema.prisma for the full reasoning, including why this is NOT the
+-- SetNull audit-trail pattern used elsewhere in this schema (AuditEvent,
+-- Credential, NotificationDelivery).
+ALTER TABLE "worker_nodes" ADD CONSTRAINT "worker_nodes_created_by_id_fkey" FOREIGN KEY ("created_by_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+-- onDelete: Cascade — mirrors `personal_access_tokens_user_id_fkey` exactly
+-- (per issue #267): a node credential is a live authentication artifact with
+-- no standalone value once its owning account is deleted.
+ALTER TABLE "node_credentials" ADD CONSTRAINT "node_credentials_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+-- The FK deferred by 20260906120000_add_jobs. onDelete: SetNull — deleting a
+-- WorkerNode must release the jobs it was holding, never delete job history.
+-- See the "claimedByNodeId" block comment above the `Job` model.
+ALTER TABLE "jobs" ADD CONSTRAINT "jobs_claimed_by_node_id_fkey" FOREIGN KEY ("claimed_by_node_id") REFERENCES "worker_nodes"("id") ON DELETE SET NULL ON UPDATE CASCADE;

package/host/prisma/migrations/20240101000009_add_database_backup_runs/migration.sql

@@ -0,0 +1,104 @@
+-- CreateEnum
+CREATE TYPE "DatabaseBackupStatus" AS ENUM ('pending', 'running', 'completed', 'failed', 'stale');
+
+-- CreateEnum
+CREATE TYPE "DatabaseBackupTrigger" AS ENUM ('manual', 'scheduled', 'pre_restore');
+
+-- CreateTable
+CREATE TABLE "database_backup_runs" (
+    "id" UUID NOT NULL,
+    "status" "DatabaseBackupStatus" NOT NULL DEFAULT 'pending',
+    "trigger" "DatabaseBackupTrigger" NOT NULL,
+    "started_at" TIMESTAMPTZ,
+    "finished_at" TIMESTAMPTZ,
+    "last_heartbeat_at" TIMESTAMPTZ,
+    "bytes_written" BIGINT NOT NULL DEFAULT 0,
+    "size_bytes" BIGINT NOT NULL DEFAULT 0,
+    "storage_provider" TEXT NOT NULL,
+    "storage_key" TEXT NOT NULL,
+    "bucket" TEXT NOT NULL,
+    "format" TEXT NOT NULL,
+    "checksum_sha256" TEXT,
+    "db_version" TEXT,
+    "app_version" TEXT,
+    "migration_name" TEXT,
+    "verified_at" TIMESTAMPTZ,
+    "last_error" TEXT,
+    "created_by_id" UUID,
+    "restore_status" TEXT,
+    "restore_error" TEXT,
+    "restored_at" TIMESTAMPTZ,
+    "restored_by_id" UUID,
+    "restore_scratch_db" TEXT,
+    "restore_old_db" TEXT,
+    "swapped_at" TIMESTAMPTZ,
+    "pre_restore_backup_id" UUID,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL,
+
+    CONSTRAINT "database_backup_runs_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "database_backup_runs_created_at_idx" ON "database_backup_runs"("created_at" DESC);
+
+-- CreateIndex
+CREATE INDEX "database_backup_runs_started_at_idx" ON "database_backup_runs"("started_at" DESC);
+
+-- CreateIndex
+CREATE INDEX "database_backup_runs_status_idx" ON "database_backup_runs"("status");
+
+-- CreateIndex
+CREATE INDEX "database_backup_runs_status_created_at_idx" ON "database_backup_runs"("status", "created_at" DESC);
+
+-- AddForeignKey
+ALTER TABLE "database_backup_runs" ADD CONSTRAINT "database_backup_runs_created_by_id_fkey" FOREIGN KEY ("created_by_id") REFERENCES "users"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "database_backup_runs" ADD CONSTRAINT "database_backup_runs_restored_by_id_fkey" FOREIGN KEY ("restored_by_id") REFERENCES "users"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "database_backup_runs" ADD CONSTRAINT "database_backup_runs_pre_restore_backup_id_fkey" FOREIGN KEY ("pre_restore_backup_id") REFERENCES "database_backup_runs"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- =============================================================================
+-- HAND-WRITTEN INDEX — INTENTIONAL SCHEMA DRIFT (issue #281, epic #254)
+-- =============================================================================
+-- The index below is NOT emitted by `prisma migrate dev`/`diff` and never will
+-- be: it needs a partial-index `WHERE` clause, which the Prisma schema language
+-- has no syntax for. It is written here by hand, and the block comment above
+-- the `DatabaseBackupRun` model in prisma/schema.prisma records the same fact
+-- for anyone reading the schema without this file open.
+--
+-- ⚠ `prisma migrate dev` WILL WANT TO DROP IT on the next diff, exactly as it
+-- would for the three partial indexes in 20260906120000_add_jobs. Do not
+-- "reconcile" this migration by accepting that drop, and do not expect
+-- `prisma migrate diff` against a live database to come back clean. This drift
+-- is deliberate and permanent for as long as Prisma's DSL lacks partial
+-- indexes. If a future `migrate dev` run emits a `DROP INDEX
+-- "database_backup_runs_active_uniq_idx"`, delete that line from the generated
+-- migration before committing it.
+-- =============================================================================
+
+-- THE single-active-run guard. It is what makes "at most one backup at a time"
+-- true ACROSS REPLICAS, rather than true only within one process: a scheduled
+-- tick on one container and an administrator's click on another cannot both
+-- insert, so two `pg_dump` processes can never stream into the derived storage
+-- key at once. `DatabaseBackupRunnerService.startBackup` inserts optimistically
+-- and turns the loser's P2002 into a typed
+-- `DatabaseBackupAlreadyRunningError` carrying the winner's id; there is
+-- deliberately no `findFirst` pre-check anywhere in that path, because
+-- check-then-act is racy exactly when this constraint matters.
+--
+-- No cast is needed on the literals: Postgres coerces an unadorned string
+-- literal to the column's enum type in an `IN` list, the same way
+-- "jobs_active_dedup_uniq_idx" does for "JobStatus".
+--
+-- ⚠ WHAT THIS ADMITS, PRECISELY: a UNIQUE index on ("status") filtered to two
+-- values permits at most one 'pending' row AND at most one 'running' row. The
+-- runner only ever inserts 'running', so today the ceiling is exactly one
+-- active run; 'pending' is covered so that a future path which does insert one
+-- is still arbitrated here rather than in application code. A future design
+-- that genuinely needs both states populated at once must TIGHTEN this index
+-- (to a constant expression) — never relax the guard into a service.
+CREATE UNIQUE INDEX "database_backup_runs_active_uniq_idx"
+  ON "database_backup_runs" ("status") WHERE "status" IN ('pending','running');

package/host/prisma/migrations/20240101000010_add_notification_broadcasts/migration.sql

@@ -0,0 +1,57 @@
+-- =============================================================================
+-- Notification Broadcasts (issue #320, epic #319)
+-- =============================================================================
+-- Adds `notification_broadcasts`. See the block comment above the
+-- `NotificationBroadcast` model in prisma/schema.prisma for the full
+-- reasoning behind every choice below (why a table at all rather than
+-- `Job.payload`, why `channels` is a plain string array, why `status` carries
+-- a currently-unreachable `draft` member, why `cursor_user_id` pairs with
+-- `audience_cutoff` to freeze and replay the fan-out's audience, why
+-- `created_by_id` is SetNull, and the rejected per-recipient join table) —
+-- this file intentionally does not restate it at length.
+-- =============================================================================
+
+-- CreateEnum
+CREATE TYPE "NotificationBroadcastStatus" AS ENUM ('draft', 'scheduled', 'sending', 'sent', 'canceled', 'failed');
+
+-- CreateTable
+CREATE TABLE "notification_broadcasts" (
+    "id" UUID NOT NULL,
+    "title" TEXT NOT NULL,
+    "body" TEXT NOT NULL,
+    "link" TEXT,
+    "cta_label" TEXT,
+    "event_key" TEXT NOT NULL,
+    "channels" TEXT[],
+    "status" "NotificationBroadcastStatus" NOT NULL DEFAULT 'scheduled',
+    "scheduled_for" TIMESTAMPTZ,
+    "started_at" TIMESTAMPTZ,
+    "finished_at" TIMESTAMPTZ,
+    "canceled_at" TIMESTAMPTZ,
+    "audience_cutoff" TIMESTAMPTZ,
+    "cursor_user_id" UUID,
+    "recipients_targeted" INTEGER,
+    "recipients_dispatched" INTEGER NOT NULL DEFAULT 0,
+    "last_error" TEXT,
+    "created_by_id" UUID,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL,
+
+    CONSTRAINT "notification_broadcasts_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+-- "What is pending" — the scheduler's own query.
+CREATE INDEX "notification_broadcasts_status_scheduled_for_idx" ON "notification_broadcasts"("status", "scheduled_for");
+
+-- CreateIndex
+-- The admin list page's default order, "most recently composed first".
+CREATE INDEX "notification_broadcasts_created_at_idx" ON "notification_broadcasts"("created_at" DESC);
+
+-- AddForeignKey
+-- onDelete: SetNull — same audit-trail reasoning as
+-- `audit_events_actor_user_id_fkey`: deleting the admin who composed a
+-- broadcast must not delete the record of what they announced. Takes a
+-- brief lock on `users` while the constraint is validated, as any new FK to
+-- that table does.
+ALTER TABLE "notification_broadcasts" ADD CONSTRAINT "notification_broadcasts_created_by_id_fkey" FOREIGN KEY ("created_by_id") REFERENCES "users"("id") ON DELETE SET NULL ON UPDATE CASCADE;

package/host/prisma/migrations/20240101000011_add_backup_run_job_link/migration.sql

@@ -0,0 +1,87 @@
+-- =============================================================================
+-- Backup Run <-> Job link, and tightening the single-active-run guard
+-- (issue #351, epic #345)
+-- =============================================================================
+-- Two independent changes land together because the second is only safe once
+-- the first is possible to reason about (see the second block below for why
+-- they must not be split across two migrations).
+--
+-- 1. `database_backup_runs.job_id`: the FK from a backup run back to the
+--    queue job that drove it, once the dump becomes a job (`db.backup.run`).
+--    Nullable, no default, no backfill — see the block comment above
+--    `DatabaseBackupRun` in prisma/schema.prisma ("jobId") for the full
+--    reasoning behind `@unique` / nullable / `SetNull`, which this migration
+--    intentionally does not restate.
+--
+-- 2. Tightening `database_backup_runs_active_uniq_idx` from a UNIQUE index on
+--    the `status` COLUMN to a UNIQUE index on the CONSTANT EXPRESSION `(true)`
+--    — both filtered to `status IN ('pending','running')`. See the block
+--    comment above `DatabaseBackupRun` in prisma/schema.prisma
+--    ("THE SINGLE-ACTIVE-RUN GUARD...") for the full story; the short version:
+--    the old, column-keyed index admits one `pending` row AND one `running`
+--    row AT THE SAME TIME (two active runs), which was harmless only because
+--    nothing ever wrote `pending`. #351's service half makes
+--    `POST /api/admin/db-backup/runs` enqueue the job and insert the run row
+--    as `pending` before any worker claims it, so `pending` rows become real.
+--    Keying on `(true)` instead makes every active row — whichever status it
+--    holds — collide on the same key, so at most one can exist across both
+--    statuses combined.
+-- =============================================================================
+
+-- AlterTable
+ALTER TABLE "database_backup_runs" ADD COLUMN "job_id" UUID;
+
+-- CreateIndex
+CREATE UNIQUE INDEX "database_backup_runs_job_id_key" ON "database_backup_runs"("job_id");
+
+-- AddForeignKey
+-- onDelete: SetNull, NOT Cascade — `job.history.purge` deletes `jobs` rows on
+-- a retention schedule independent of the archive's own retention. Cascade
+-- would let a routine job-history purge delete the record of a still-restorable
+-- backup. See the block comment above `DatabaseBackupRun.jobId` in
+-- prisma/schema.prisma.
+ALTER TABLE "database_backup_runs" ADD CONSTRAINT "database_backup_runs_job_id_fkey" FOREIGN KEY ("job_id") REFERENCES "jobs"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- =============================================================================
+-- HAND-WRITTEN INDEX CHANGE — INTENTIONAL SCHEMA DRIFT (issue #351, epic #345)
+-- =============================================================================
+-- `database_backup_runs_active_uniq_idx` is NOT emitted by `prisma migrate
+-- dev`/`diff` and never will be: Prisma's schema language has no syntax for a
+-- partial index OR an expression index, so both the original (partial, on
+-- `status`) and this tightened form (partial, on the expression `(true)`) are
+-- written here by hand — exactly the drift `20260907120000_add_database_backup
+-- _runs/migration.sql` already carries, now one step further. The block
+-- comment above the `DatabaseBackupRun` model in prisma/schema.prisma records
+-- the same fact for anyone reading the schema without this file open.
+--
+-- ⚠ `prisma migrate dev` WILL WANT TO DROP THIS INDEX on the next diff, the
+-- same as its predecessor. Do not "reconcile" this migration by accepting
+-- that drop, and do not expect `prisma migrate diff` against a live database
+-- to come back clean. This drift is deliberate and permanent for as long as
+-- Prisma's DSL lacks expression indexes.
+-- =============================================================================
+
+-- The ORIGINAL guard admitted at most one 'pending' row AND at most one
+-- 'running' row AT THE SAME TIME — two active runs, not one — because the
+-- index was keyed on the `status` column itself: a 'pending' row and a
+-- 'running' row have different key values, so both could satisfy the same
+-- unique index simultaneously. That was harmless only because nothing ever
+-- wrote 'pending'. #351 makes the dump a queue job, and the run row is now
+-- created 'pending' before any worker has claimed it, so 'pending' rows are
+-- no longer hypothetical.
+DROP INDEX "database_backup_runs_active_uniq_idx";
+
+-- THE tightened single-active-run guard. Keying on the constant expression
+-- `(true)` — rather than on `status` — makes every row matching the WHERE
+-- predicate (any 'pending' or 'running' row) index to the exact same key, so
+-- Postgres now enforces "at most one active row, full stop" across BOTH
+-- statuses combined, not "at most one of each". A 'completed', 'failed' or
+-- 'stale' row does not match the predicate at all and is never constrained by
+-- this index, so any number of them may coexist.
+--
+-- `DatabaseBackupRunnerService.startBackup` still inserts optimistically and
+-- turns the loser's P2002 into a typed `DatabaseBackupAlreadyRunningError`
+-- carrying the winner's id; there is deliberately no `findFirst` pre-check,
+-- because check-then-act is racy exactly when this constraint matters.
+CREATE UNIQUE INDEX "database_backup_runs_active_uniq_idx"
+  ON "database_backup_runs" ((true)) WHERE "status" IN ('pending','running');

package/host/prisma/migrations/20240101000012_add_job_node_secrets/migration.sql

@@ -0,0 +1,61 @@
+-- =============================================================================
+-- Per-job secret broker: the handle ledger (issue #349, epic #345)
+-- =============================================================================
+-- One table, and the interesting thing about it is a column that is NOT here.
+--
+-- A worker node holds no credentials by design (docs/specs/worker-nodes.md §8).
+-- Epic #345 needs it to run work that genuinely requires one, so the server
+-- mints a credential per job, hands it over exactly once, and destroys it when
+-- the job settles. `job_node_secrets` records THAT A GRANT EXISTED — which node,
+-- of what kind, from when until when, revoked or not — so "did a node ever hold
+-- a credential to this database, and when" is answerable.
+--
+-- ⚠ THERE IS NO COLUMN CAPABLE OF HOLDING SECRET MATERIAL, AND ADDING ONE IS
+-- THE ONE CHANGE THIS TABLE MUST NEVER RECEIVE. Not `password`, not
+-- `encrypted_material`, not "just a base64 blob for debugging". `handle` is an
+-- identifier for the grant (a role name) and is what `JobSecretBroker.revoke`
+-- takes; the material is serialised into one HTTP response and dropped.
+-- Reusing SECRETS_ENCRYPTION_KEY here was considered and rejected: a credential
+-- that can be re-read is a credential that can be stolen twice, and nothing
+-- needs to re-read this one. Storing it — even encrypted — would put a live
+-- database password into this table, into every pg_dump of it, and into every
+-- copy of that dump. See the block comment above `JobNodeSecret` in
+-- prisma/schema.prisma for the full argument.
+--
+-- NO FOREIGN KEYS, deliberately. `job_id` and `node_id` are plain UUIDs. A
+-- `jobs` row is 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
+-- erase the audit record this table exists to keep; a grant must also stay
+-- revocable after its job row is gone, which is why the sweeper resolves a
+-- broker by `kind` rather than by the job's `type`.
+-- =============================================================================
+
+-- CreateTable
+CREATE TABLE "job_node_secrets" (
+    "id" UUID NOT NULL,
+    "job_id" UUID NOT NULL,
+    "node_id" UUID NOT NULL,
+    "kind" TEXT NOT NULL,
+    -- The grant's identifier. NEVER the password — see the header.
+    "handle" TEXT NOT NULL,
+    "issued_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "expires_at" TIMESTAMPTZ NOT NULL,
+    "revoked_at" TIMESTAMPTZ,
+
+    CONSTRAINT "job_node_secrets_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+-- ONE CREDENTIAL PER JOB, EVER. A node asks for its secret more than once as a
+-- matter of course (a restarted process still holding the lease, a lost
+-- response, a retry), and every one of those calls must extend the SAME grant.
+-- The revocation paths know exactly one handle per (job, kind); a sibling grant
+-- would be one nothing ever destroys. This index makes the second row
+-- unrepresentable rather than leaving it to the service to remember.
+CREATE UNIQUE INDEX "job_node_secrets_job_id_kind_key" ON "job_node_secrets"("job_id", "kind");
+
+-- CreateIndex
+-- The sweeper's scan: 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.
+CREATE INDEX "job_node_secrets_expires_at_idx" ON "job_node_secrets"("expires_at");

package/host/prisma/migrations/20240101000013_add_backup_run_pg_dump_version/migration.sql

@@ -0,0 +1,26 @@
+-- =============================================================================
+-- `database_backup_runs.pg_dump_version` (issue #352, epic #345)
+-- =============================================================================
+-- The fourth member of this table's audit block: WHICH `pg_dump` wrote the
+-- archive.
+--
+-- It was worth nothing while the dump could only run in the API process — the
+-- client is whatever `apps/api/Dockerfile` installed, the same for every run,
+-- and the node-credential preflight already reports it. #352 makes the dump
+-- claimable by a worker node, and on that path the binary lives on a machine
+-- this deployment may not own and cannot inspect after the fact. Without this
+-- column, nothing anywhere records which client produced the file, and
+-- "`pg_restore` cannot read an archive written by a NEWER `pg_dump`" becomes a
+-- fact an operator discovers during a restore rather than one they can check
+-- before starting it (see docs/runbooks/postgres-client-version.md).
+--
+-- Nullable, no default, NO BACKFILL. Every existing row was written by a
+-- client nobody recorded, and inventing this deployment's CURRENT client
+-- version for them would be a lie that reads exactly like evidence. NULL means
+-- "not recorded", which is the truth for every run taken before this migration
+-- and for any run whose `pg_dump --version` could not be read — the same
+-- "warn and proceed" rule the other three audit columns already follow.
+-- =============================================================================
+
+-- AlterTable
+ALTER TABLE "database_backup_runs" ADD COLUMN "pg_dump_version" TEXT;

package/host/prisma/migrations/20240101000014_add_job_claim_token/migration.sql

@@ -0,0 +1,92 @@
+-- =============================================================================
+-- jobs.claim_token — per-claim identity, closing the two-replica lease hole
+-- (issue #361)
+-- =============================================================================
+-- `heldLeaseWhere` (`src/jobs/job-lease.service.ts`) answers "does the caller
+-- still hold this row" as `{ id, status: 'running', leaseExpiresAt: { gt: now
+-- }, claimedByNodeId }`. That predicate identifies a CLAIMANT KIND — "a node"
+-- (a real `WorkerNode.id`) vs. "the server" (`claimedByNodeId: null`) — not a
+-- particular claim. Every API replica claims with `claimedByNodeId: null`, so
+-- two server replicas produce the exact same `heldLeaseWhere` predicate for
+-- the same job. Concretely: replica A claims a job, then stalls long enough
+-- for the lease reaper to reclaim it as abandoned; replica B claims the
+-- now-pending job and starts running it; replica A, still alive and unaware
+-- it lost the row, calls `renew` — which matches `heldLeaseWhere` (status is
+-- `running`, `claimedByNodeId` is `null`, and the lease B just set is still
+-- in the future) and happily extends B's lease. A never learns it lost the
+-- job, and now believes it owns work it does not.
+--
+-- The fix is a column that identifies ONE CLAIM, not one KIND of claimant:
+-- `claim_token`, minted fresh (`gen_random_uuid()`) by the claim statement
+-- itself and folded into `heldLeaseWhere` alongside `claimedByNodeId` (wiring
+-- lands in a later slice — this migration and its schema.prisma companion are
+-- schema-only, per the issue's stated scope). Once every renew/settle/reap
+-- statement also matches on `claim_token`, replica A's renewal after losing
+-- the row targets a token that is no longer on the row (B's claim overwrote
+-- it with a new one) and the `UPDATE` matches zero rows, exactly like a node
+-- losing a lease already does today.
+--
+-- -----------------------------------------------------------------------------
+-- Why NULLABLE, with no DEFAULT
+-- -----------------------------------------------------------------------------
+-- The invariant this codebase will maintain from here on is `claim_token IS
+-- NOT NULL` IFF the row is currently held under a claim. A `pending` job has
+-- no claimant at all, so writing it a token would assert a claim that does
+-- not exist — a lie the column has no business telling. `DEFAULT
+-- gen_random_uuid()` would do exactly that: every row, including ones freshly
+-- enqueued and never claimed, would carry a token that means nothing,
+-- indistinguishable from a real one to anybody reading the column.
+--
+-- No backfill, and none is wanted. Every row that exists at deploy time is
+-- either not currently claimed (`pending`, `succeeded`, `failed` — `NULL` is
+-- simply correct) or `running` under a claim taken by a REPLICA RUNNING THE
+-- OLD CODE, which never wrote a token and has no token to reconcile against.
+-- `NULL` is still correct there, but the reason an old replica keeps renewing
+-- successfully has nothing to do with NULL comparison semantics — it is
+-- simpler than that: an old replica is running the OLD `heldLeaseWhere`,
+-- which has no `claim_token` clause at all, so it never passes a token,
+-- remembered or otherwise, and this column is invisible to its predicate.
+-- The later slice's `heldLeaseWhere(jobId, { nodeId?, claimToken? })` treats
+-- `claimToken` the same three-valued way `nodeId` already works: a string
+-- constrains the match to that one claim, `undefined` omits the clause
+-- entirely (what the node control plane and this migration-era code both do),
+-- and `null` is passed straight through to Prisma and renders as an actual
+-- `claim_token IS NULL` check — matching only a row that carries no token.
+--
+-- That makes the rolling-deploy story a narrowing, not a full close, and only
+-- in one direction: a NEW replica's claim writes a real token, so no other
+-- NEW replica can renew it out from under the claimant — the hole
+-- is closed between new replicas from the moment this ships. An OLD
+-- replica's `renew` still ignores `claim_token` altogether, so an old
+-- replica that lost a row to the reaper can still extend a NEW replica's
+-- lease for as long as the old replica keeps ticking — the same failure mode
+-- this column exists to fix, just now confined to "one side of the pair is
+-- still running pre-#361 code" instead of "always". That window is bounded
+-- and ordinary: it closes for good once the last old replica has rolled off,
+-- the same way any predicate change behaves during a rolling deploy, and is
+-- not a reason to change this design.
+--
+-- -----------------------------------------------------------------------------
+-- Why no index
+-- -----------------------------------------------------------------------------
+-- `claim_token` is never queried on its own — every read of it is one more
+-- predicate bolted onto a single-row lookup already keyed by `jobs`'s primary
+-- key (`WHERE id = $1 AND claim_token = $2 AND ...`), the same shape
+-- `heldLeaseWhere` already has for `claimedByNodeId` and `leaseExpiresAt`,
+-- neither of which is indexed on its own either. An index earns its keep by
+-- narrowing a scan that would otherwise be large; there is no query here that
+-- scans `jobs` by `claim_token` and needs narrowing. Adding one would be pure
+-- write overhead on the hottest path this table has — every claim, every
+-- renewal, every settle — for a lookup nothing performs.
+--
+-- -----------------------------------------------------------------------------
+-- Online-safety
+-- -----------------------------------------------------------------------------
+-- `ADD COLUMN` of a NULLABLE column with NO DEFAULT is a metadata-only change
+-- on PostgreSQL 11+: no table rewrite, no full-table scan to populate a
+-- default, just a brief ACCESS EXCLUSIVE lock to update the catalog. Safe to
+-- run against a live, populated `jobs` table with no maintenance window.
+-- =============================================================================
+
+-- AlterTable
+ALTER TABLE "jobs" ADD COLUMN "claim_token" UUID;

package/host/prisma/migrations/20240101000015_add_ai_platform/migration.sql

@@ -0,0 +1,108 @@
+-- CreateTable
+CREATE TABLE "ai_models" (
+    "id" UUID NOT NULL,
+    "provider" TEXT NOT NULL,
+    "model_id" TEXT NOT NULL,
+    "display_name" TEXT,
+    "capabilities" JSONB NOT NULL,
+    "capability_source" TEXT NOT NULL DEFAULT 'unclassified',
+    "enabled" BOOLEAN NOT NULL DEFAULT false,
+    "context_window" INTEGER,
+    "max_output_tokens" INTEGER,
+    "discovered_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "last_seen_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "deprecated_at" TIMESTAMPTZ,
+    "updated_by_user_id" UUID,
+    "updated_at" TIMESTAMPTZ NOT NULL,
+
+    CONSTRAINT "ai_models_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "user_ai_keys" (
+    "id" UUID NOT NULL,
+    "user_id" UUID NOT NULL,
+    "provider" TEXT NOT NULL,
+    "secret" TEXT NOT NULL,
+    "hint" TEXT,
+    "verified_at" TIMESTAMPTZ,
+    "last_error_code" TEXT,
+    "reachable_model_ids" TEXT[] DEFAULT ARRAY[]::TEXT[],
+    "reachable_checked_at" TIMESTAMPTZ,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL,
+
+    CONSTRAINT "user_ai_keys_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "ai_runs" (
+    "id" UUID NOT NULL,
+    "user_id" UUID,
+    "job_id" UUID,
+    "status" TEXT NOT NULL DEFAULT 'pending',
+    "provider" TEXT NOT NULL,
+    "model_id" TEXT NOT NULL,
+    "request" JSONB NOT NULL,
+    "output" JSONB,
+    "error_code" TEXT,
+    "error_message" TEXT,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL,
+    "completed_at" TIMESTAMPTZ,
+
+    CONSTRAINT "ai_runs_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "ai_usage_events" (
+    "id" UUID NOT NULL,
+    "user_id" UUID,
+    "provider" TEXT NOT NULL,
+    "model_id" TEXT NOT NULL,
+    "operation" TEXT NOT NULL,
+    "key_source" TEXT NOT NULL,
+    "input_tokens" INTEGER,
+    "output_tokens" INTEGER,
+    "reasoning_tokens" INTEGER,
+    "cached_input_tokens" INTEGER,
+    "units" JSONB,
+    "latency_ms" INTEGER NOT NULL,
+    "status" TEXT NOT NULL,
+    "error_code" TEXT,
+    "provider_request_id" TEXT,
+    "job_id" UUID,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "ai_usage_events_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "ai_models_provider_enabled_idx" ON "ai_models"("provider", "enabled");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "ai_models_provider_model_id_key" ON "ai_models"("provider", "model_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "user_ai_keys_user_id_provider_key" ON "user_ai_keys"("user_id", "provider");
+
+-- CreateIndex
+CREATE INDEX "ai_runs_user_id_created_at_idx" ON "ai_runs"("user_id", "created_at");
+
+-- CreateIndex
+CREATE INDEX "ai_usage_events_user_id_created_at_idx" ON "ai_usage_events"("user_id", "created_at");
+
+-- CreateIndex
+CREATE INDEX "ai_usage_events_created_at_idx" ON "ai_usage_events"("created_at");
+
+-- AddForeignKey
+ALTER TABLE "ai_models" ADD CONSTRAINT "ai_models_updated_by_user_id_fkey" FOREIGN KEY ("updated_by_user_id") REFERENCES "users"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "user_ai_keys" ADD CONSTRAINT "user_ai_keys_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "ai_runs" ADD CONSTRAINT "ai_runs_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "ai_usage_events" ADD CONSTRAINT "ai_usage_events_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE SET NULL ON UPDATE CASCADE;