@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

package/src/queue/store.ts

@@ -0,0 +1,1006 @@
+import os from "node:os";
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { randomUUID } from "node:crypto";
+import type { JobKind, JobStage, JobStatus as ContractStatus, PipelineData } from "@vfrey/contracts";
+import * as desk from "./desk-ops.js";
+export type { DeskResult, JobEventRow, SeriesInput } from "./desk-ops.js";
+
+/**
+ * The contract's statuses plus `awaiting_review` (spec 015 D): a job whose series has review on stops there after the
+ * script, scene and pre-render checks. It holds no lease; Approve makes it `pending` again, Reject ends it `rejected`
+ * with the code `review_rejected`.
+ */
+export type JobStatus = ContractStatus | "awaiting_review";
+
+export interface JobRecord {
+  id: string;
+  accountId: string;
+  kind: JobKind;
+  stage: JobStage;
+  status: JobStatus;
+  payload: PipelineData;
+  attempt: number;
+  maxAttempts: number;
+  leaseUntil: string | null;
+  /** Names the claim that holds this job. A write from a worker whose claim was cancelled or taken over is refused. */
+  leaseToken?: string | null;
+  runAfter: string;
+  lastError: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS jobs (
+  id TEXT PRIMARY KEY,
+  account_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  stage TEXT NOT NULL,
+  status TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  attempt INTEGER NOT NULL,
+  max_attempts INTEGER NOT NULL,
+  lease_until TEXT,
+  run_after TEXT NOT NULL,
+  last_error TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS jobs_claim ON jobs (status, run_after);
+CREATE TABLE IF NOT EXISTS source_seen (
+  account_id TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  first_seen TEXT NOT NULL,
+  PRIMARY KEY (account_id, fingerprint)
+);
+CREATE TABLE IF NOT EXISTS publications (
+  id TEXT PRIMARY KEY,
+  job_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  platform TEXT NOT NULL,
+  external_id TEXT,
+  disclosure TEXT NOT NULL,
+  variation TEXT NOT NULL,
+  hook TEXT NOT NULL,
+  title TEXT NOT NULL,
+  hashtags TEXT NOT NULL,
+  script TEXT NOT NULL,
+  published_at TEXT NOT NULL,
+  audit TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS comments_handled (
+  platform TEXT NOT NULL,
+  comment_id TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  action TEXT NOT NULL,
+  tone TEXT,
+  reply_text TEXT,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (platform, comment_id)
+);
+CREATE TABLE IF NOT EXISTS metrics (
+  id TEXT PRIMARY KEY,
+  account_id TEXT NOT NULL,
+  platform TEXT NOT NULL,
+  external_id TEXT NOT NULL,
+  captured_at TEXT NOT NULL,
+  views INTEGER,
+  watch_time_sec REAL,
+  retention REAL,
+  estimated_revenue REAL,
+  revenue_status TEXT NOT NULL,
+  raw TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS rate_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  bucket TEXT NOT NULL,
+  at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS rate_bucket ON rate_events (bucket, at);
+CREATE TABLE IF NOT EXISTS account_health (
+  account_id TEXT NOT NULL,
+  platform TEXT NOT NULL,
+  token_state TEXT NOT NULL,
+  last_error TEXT,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (account_id, platform)
+);
+CREATE TABLE IF NOT EXISTS desk_accounts (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  owner_id TEXT,
+  paused INTEGER NOT NULL DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS desk_secrets (
+  owner_kind TEXT NOT NULL,
+  owner_id TEXT NOT NULL,
+  field TEXT NOT NULL,
+  ciphertext TEXT NOT NULL,
+  PRIMARY KEY (owner_kind, owner_id, field)
+);
+CREATE TABLE IF NOT EXISTS desk_series (
+  id TEXT PRIMARY KEY,
+  account_id TEXT NOT NULL,
+  niche TEXT NOT NULL,
+  language TEXT NOT NULL,
+  autopilot INTEGER NOT NULL,
+  timezone TEXT NOT NULL,
+  min_hours REAL NOT NULL,
+  max_posts INTEGER NOT NULL,
+  windows_json TEXT NOT NULL,
+  voices_json TEXT NOT NULL,
+  hashtags_json TEXT NOT NULL,
+  engage_enabled INTEGER NOT NULL,
+  allow_spicy INTEGER NOT NULL,
+  max_replies INTEGER NOT NULL,
+  min_seconds INTEGER NOT NULL,
+  upload_cap INTEGER NOT NULL,
+  style_path TEXT NOT NULL,
+  paused INTEGER NOT NULL DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS desk_platforms (
+  series_id TEXT NOT NULL,
+  platform TEXT NOT NULL,
+  enabled INTEGER NOT NULL,
+  config_json TEXT NOT NULL,
+  PRIMARY KEY (series_id, platform)
+);
+CREATE TABLE IF NOT EXISTS desk_sources (
+  id TEXT PRIMARY KEY,
+  series_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  value TEXT NOT NULL,
+  last_status TEXT
+);
+CREATE TABLE IF NOT EXISTS desk_settings (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS job_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  job_id TEXT NOT NULL,
+  at TEXT NOT NULL,
+  stage TEXT NOT NULL,
+  status TEXT NOT NULL,
+  code TEXT,
+  message TEXT,
+  duration_ms INTEGER
+);
+CREATE TABLE IF NOT EXISTS series_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  series_id TEXT NOT NULL,
+  at TEXT NOT NULL,
+  code TEXT NOT NULL,
+  message TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS desk_warnings (
+  id TEXT PRIMARY KEY,
+  account_id TEXT,
+  job_id TEXT,
+  code TEXT NOT NULL,
+  message TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  acked_at TEXT
+);
+`;
+
+export class Store {
+  readonly db: DatabaseSync;
+  /** Directory that holds the database file and `renders/`. Null for an in-memory store. */
+  readonly dataDir: string | null;
+
+  constructor(path: string) {
+    this.dataDir = path === ":memory:" ? null : dirname(resolve(path));
+    if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+    this.db = new DatabaseSync(path);
+    this.db.exec("PRAGMA busy_timeout = 5000");
+    if (path !== ":memory:") this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec(SCHEMA);
+    this.ensureColumn("desk_series", "base_json", "TEXT");
+    this.ensureColumn("desk_series", "engine", "TEXT");
+    this.ensureColumn("job_events", "attempt", "INTEGER");
+    this.ensureColumn("comments_handled", "code", "TEXT");
+    this.ensureColumn("jobs", "finished_at", "TEXT");
+    this.ensureColumn("jobs", "lease_owner", "TEXT");
+    this.ensureColumn("jobs", "lease_token", "TEXT");
+    this.ensureColumn("desk_secrets", "set_at", "TEXT");
+    // Dashboard screens (spec 015 B): what the last fetch of a source returned, and what a comment said.
+    this.ensureColumn("desk_sources", "last_fetch_at", "TEXT");
+    this.ensureColumn("desk_sources", "last_count", "INTEGER");
+    this.ensureColumn("desk_sources", "last_code", "TEXT");
+    this.ensureColumn("comments_handled", "comment_text", "TEXT");
+    this.ensureColumn("comments_handled", "dry_run", "INTEGER NOT NULL DEFAULT 0");
+    this.ensureColumn("desk_series", "publish_on", "INTEGER NOT NULL DEFAULT 1");
+    this.ensureColumn("desk_series", "review_on", "INTEGER NOT NULL DEFAULT 0");
+    const hadLive = (this.db.prepare(`PRAGMA table_info(desk_series)`).all() as Array<{ name: string }>).some((item) => item.name === "live");
+    this.ensureColumn("desk_series", "live", "INTEGER NOT NULL DEFAULT 0");
+    if (!hadLive) desk.backfillLive(this.db);
+  }
+
+  ensureColumn(table: string, column: string, ddl: string): void {
+    const columns = this.db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+    if (columns.some((item) => item.name === column)) return;
+    this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${ddl}`);
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  enqueue(input: {
+    accountId: string;
+    kind: JobKind;
+    stage?: JobStage;
+    payload?: PipelineData;
+    runAfter?: string;
+    maxAttempts?: number;
+    /** A one-off job: it neither joins nor blocks the series' own in-progress job. */
+    standalone?: boolean;
+  }): JobRecord {
+    if (input.kind === "pipeline" && !input.standalone) {
+      const existing = this.db
+        .prepare(
+          `SELECT id FROM jobs WHERE account_id = ? AND kind = 'pipeline' AND status IN ('pending','leased') LIMIT 1`,
+        )
+        .get(input.accountId) as { id: string } | undefined;
+      if (existing) return this.mustGet(existing.id);
+    }
+    const now = new Date().toISOString();
+    const id = randomUUID();
+    const payload = input.payload ?? emptyPayload();
+    this.db
+      .prepare(
+        `INSERT INTO jobs (id, account_id, kind, stage, status, payload, attempt, max_attempts, lease_until, run_after, last_error, created_at, updated_at)
+         VALUES (?, ?, ?, ?, 'pending', ?, 0, ?, NULL, ?, NULL, ?, ?)`,
+      )
+      .run(
+        id,
+        input.accountId,
+        input.kind,
+        input.stage ?? "source",
+        JSON.stringify(payload),
+        input.maxAttempts ?? 5,
+        input.runAfter ?? now,
+        now,
+        now,
+      );
+    return this.mustGet(id);
+  }
+
+  /**
+   * Takes the next due job. A `leased` job whose lease has expired belonged to a worker that died,
+   * so it is taken over and a `reclaimed` event is recorded. A job that has no attempts left is
+   * ended `dead` instead of being taken again.
+   */
+  claim(now: Date, leaseMs: number, onlyId?: string): JobRecord | null {
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const iso = now.toISOString();
+      const events: Array<{ id: string; stage: string; status: string; code: string; message: string; attempt: number }> = [];
+      let claimedId: string | null = null;
+      // A lease held by a process on this host that no longer exists is free now, not at expiry.
+      const gone = new Set<string>();
+      const held = this.db
+        .prepare(`SELECT id, lease_owner FROM jobs WHERE status = 'leased' AND lease_owner IS NOT NULL AND lease_until >= ?`)
+        .all(iso) as Array<{ id: string; lease_owner: string }>;
+      for (const item of held) {
+        const at = item.lease_owner.lastIndexOf(":");
+        const pid = Number(item.lease_owner.slice(at + 1));
+        if (item.lease_owner.slice(0, at) !== os.hostname() || !Number.isInteger(pid) || pid <= 0 || pidAlive(pid)) continue;
+        this.db.prepare(`UPDATE jobs SET lease_until = ? WHERE id = ?`).run(new Date(now.getTime() - 1000).toISOString(), item.id);
+        gone.add(item.id);
+      }
+      for (;;) {
+        const row = this.db
+          .prepare(
+            `SELECT id, status, stage, attempt, max_attempts FROM jobs
+             WHERE ((status = 'pending' AND run_after <= ?)
+                OR (status = 'leased' AND lease_until IS NOT NULL AND lease_until < ?))
+                AND (? IS NULL OR id = ?)
+             ORDER BY run_after ASC LIMIT 1`,
+          )
+          .get(iso, iso, onlyId ?? null, onlyId ?? null) as { id: string; status: string; stage: string; attempt: number; max_attempts: number } | undefined;
+        if (!row) break;
+        const reclaimed = row.status === "leased";
+        if (reclaimed && Number(row.attempt) >= Number(row.max_attempts)) {
+          const message = "lease_expired: the worker stopped and no attempts are left";
+          this.db
+            .prepare(`UPDATE jobs SET status = 'dead', lease_until = NULL, last_error = ?, updated_at = ? WHERE id = ?`)
+            .run(message, iso, row.id);
+          events.push({ id: row.id, stage: row.stage, status: "dead", code: "lease_expired", message, attempt: Number(row.attempt) });
+          continue;
+        }
+        const leaseUntil = new Date(now.getTime() + leaseMs).toISOString();
+        this.db
+          .prepare(
+            `UPDATE jobs SET status = 'leased', lease_until = ?, lease_owner = ?, lease_token = ?, attempt = attempt + 1, updated_at = ? WHERE id = ?`,
+          )
+          .run(leaseUntil, `${os.hostname()}:${process.pid}`, randomUUID(), iso, row.id);
+        if (reclaimed) {
+          events.push({
+            id: row.id,
+            stage: row.stage,
+            status: "reclaimed",
+            code: gone.has(row.id) ? "owner_gone" : "lease_expired",
+            message: gone.has(row.id)
+              ? "The process holding this job is gone. A new worker took it over now and resumes from the stored session."
+              : "The worker holding this job stopped. A new worker took it over and resumes from the stored session.",
+            attempt: Number(row.attempt) + 1,
+          });
+        }
+        claimedId = row.id;
+        break;
+      }
+      for (const event of events) {
+        desk.recordEvent(this.db, event.id, { stage: event.stage, status: event.status, code: event.code, message: event.message, durationMs: null, attempt: event.attempt });
+      }
+      this.db.exec("COMMIT");
+      return claimedId ? this.mustGet(claimedId) : null;
+    } catch (error) {
+      this.db.exec("ROLLBACK");
+      throw error;
+    }
+  }
+
+  /** Gives back every job this process holds, so an interrupted run does not leave a lease behind. */
+  releaseOwned(now: Date = new Date()): string[] {
+    const owner = `${os.hostname()}:${process.pid}`;
+    const rows = this.db.prepare(`SELECT id, stage, attempt FROM jobs WHERE status = 'leased' AND lease_owner = ?`).all(owner) as Array<{ id: string; stage: string; attempt: number }>;
+    for (const row of rows) {
+      this.db
+        .prepare(`UPDATE jobs SET status = 'pending', lease_until = NULL, lease_owner = NULL, run_after = ?, attempt = MAX(0, attempt - 1), updated_at = ? WHERE id = ?`)
+        .run(now.toISOString(), now.toISOString(), row.id);
+      this.recordTerminal(row.id, { stage: row.stage, status: "retrying", code: "shutdown", message: "Interrupted. The job resumes from this stage on the next tick.", attempt: Number(row.attempt) });
+    }
+    return rows.map((row) => row.id);
+  }
+
+  /** Extends the lease of a job this worker still holds. Returns false when the job is no longer leased. */
+  renewLease(job: JobRecord, leaseMs: number, now: Date = new Date()): boolean {
+    const leaseUntil = new Date(now.getTime() + leaseMs).toISOString();
+    const result = this.db
+      .prepare(`UPDATE jobs SET lease_until = ? WHERE id = ? AND status = 'leased' AND (? IS NULL OR lease_token = ?)`)
+      .run(leaseUntil, job.id, job.leaseToken ?? null, job.leaseToken ?? null);
+    if (Number(result.changes) === 0) return false;
+    job.leaseUntil = leaseUntil;
+    return true;
+  }
+
+  /**
+   * Puts a job back to `pending` without spending the attempt that claimed it.
+   * Used for a platform pause, a processing poll, and a shutdown.
+   */
+  releaseWithoutAttempt(job: JobRecord, runAfter: Date, note: string | null): void {
+    job.status = "pending";
+    job.leaseUntil = null;
+    job.runAfter = runAfter.toISOString();
+    job.attempt = Math.max(0, job.attempt - 1);
+    job.lastError = note;
+    this.save(job);
+  }
+
+  /**
+   * Parks the job for review: the claim is given up (no lease, no owner, no token), the attempt that claimed it is
+   * not spent, and nothing holds a worker while the person looks. A worker whose claim was lost writes nothing.
+   */
+  holdForReview(job: JobRecord): void {
+    const result = this.db
+      .prepare(
+        `UPDATE jobs SET stage = ?, status = 'awaiting_review', payload = ?, attempt = MAX(0, attempt - 1), lease_until = NULL,
+           lease_owner = NULL, lease_token = NULL, last_error = NULL, updated_at = ?
+         WHERE id = ? AND (? IS NULL OR lease_token = ?)`,
+      )
+      .run(job.stage, JSON.stringify(job.payload), new Date().toISOString(), job.id, job.leaseToken ?? null, job.leaseToken ?? null);
+    if (Number(result.changes) === 0 && job.leaseToken) throw new LeaseLost(job.id);
+    job.status = "awaiting_review";
+    job.leaseUntil = null;
+    job.attempt = Math.max(0, job.attempt - 1);
+    job.lastError = null;
+  }
+
+  save(job: JobRecord): void {
+    // A worker whose claim was cancelled or taken over must not write the job back. Its own view is stale.
+    const result = this.db
+      .prepare(
+        `UPDATE jobs SET stage = ?, status = ?, payload = ?, attempt = ?, lease_until = ?, run_after = ?, last_error = ?, updated_at = ?
+         WHERE id = ? AND (? IS NULL OR lease_token = ?)`,
+      )
+      .run(
+        job.stage,
+        job.status,
+        JSON.stringify(job.payload),
+        job.attempt,
+        job.leaseUntil,
+        job.runAfter,
+        job.lastError,
+        new Date().toISOString(),
+        job.id,
+        job.leaseToken ?? null,
+        job.leaseToken ?? null,
+      );
+    if (Number(result.changes) === 0 && job.leaseToken) throw new LeaseLost(job.id);
+  }
+
+  /** True while this record's claim is the one the database holds. */
+  holdsLease(job: JobRecord): boolean {
+    if (!job.leaseToken) return true;
+    const row = this.db.prepare(`SELECT lease_token FROM jobs WHERE id = ?`).get(job.id) as { lease_token: string | null } | undefined;
+    return row?.lease_token === job.leaseToken;
+  }
+
+  /** A worker that learned it lost its claim says it has stopped, so a retry no longer has to wait for it. */
+  releaseLeaseOwner(job: JobRecord): void {
+    this.db
+      .prepare(`UPDATE jobs SET lease_owner = NULL WHERE id = ? AND lease_owner = ? AND (lease_token IS NULL OR lease_token != ?)`)
+      .run(job.id, `${os.hostname()}:${process.pid}`, job.leaseToken ?? "");
+  }
+
+  releaseRetry(job: JobRecord, runAfter: Date, error: string): void {
+    const status: JobStatus = job.attempt >= job.maxAttempts ? "dead" : "pending";
+    job.status = status;
+    job.leaseUntil = null;
+    job.runAfter = runAfter.toISOString();
+    job.lastError = error;
+    this.save(job);
+  }
+
+  finish(job: JobRecord, status: JobStatus, error: string | null, at: Date = new Date()): void {
+    job.status = status;
+    job.leaseUntil = null;
+    job.lastError = error;
+    if (status === "succeeded") job.stage = "done";
+    this.save(job);
+    this.db.prepare(`UPDATE jobs SET finished_at = ? WHERE id = ?`).run(at.toISOString(), job.id);
+  }
+
+  seen(accountId: string, fingerprint: string): boolean {
+    const row = this.db
+      .prepare(`SELECT fingerprint FROM source_seen WHERE account_id = ? AND fingerprint = ?`)
+      .get(accountId, fingerprint);
+    return Boolean(row);
+  }
+
+  markSeen(accountId: string, fingerprint: string, at: Date): void {
+    this.db
+      .prepare(`INSERT OR IGNORE INTO source_seen (account_id, fingerprint, first_seen) VALUES (?, ?, ?)`)
+      .run(accountId, fingerprint, at.toISOString());
+  }
+
+  recentPublications(accountId: string, limit: number): Array<Record<string, unknown>> {
+    return this.db
+      .prepare(
+        `SELECT * FROM publications WHERE account_id = ? ORDER BY published_at DESC LIMIT ?`,
+      )
+      .all(accountId, limit) as Array<Record<string, unknown>>;
+  }
+
+  /** One row per video (job), newest first. A video on three platforms is one entry. */
+  recentVideos(accountId: string, limit: number, excludeJobId: string | null): Array<Record<string, unknown>> {
+    return this.db
+      .prepare(
+        `SELECT p.* FROM publications p
+         WHERE p.account_id = ? AND (? IS NULL OR p.job_id != ?)
+           AND p.id = (SELECT q.id FROM publications q WHERE q.job_id = p.job_id ORDER BY q.published_at ASC, q.id ASC LIMIT 1)
+         ORDER BY p.published_at DESC LIMIT ?`,
+      )
+      .all(accountId, excludeJobId, excludeJobId, limit) as Array<Record<string, unknown>>;
+  }
+
+  publicationExists(jobId: string, platform: string): boolean {
+    return Boolean(
+      this.db.prepare(`SELECT id FROM publications WHERE job_id = ? AND platform = ?`).get(jobId, platform),
+    );
+  }
+
+  insertPublication(row: {
+    id: string;
+    jobId: string;
+    accountId: string;
+    platform: string;
+    externalId: string | null;
+    disclosure: unknown;
+    variation: unknown;
+    hook: string;
+    title: string;
+    hashtags: string[];
+    script: string;
+    publishedAt: string;
+    audit: unknown;
+  }): void {
+    this.db
+      .prepare(
+        `INSERT INTO publications (id, job_id, account_id, platform, external_id, disclosure, variation, hook, title, hashtags, script, published_at, audit)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        row.id,
+        row.jobId,
+        row.accountId,
+        row.platform,
+        row.externalId,
+        JSON.stringify(row.disclosure),
+        JSON.stringify(row.variation),
+        row.hook,
+        row.title,
+        JSON.stringify(row.hashtags),
+        row.script,
+        row.publishedAt,
+        JSON.stringify(row.audit),
+      );
+  }
+
+  lastPublishAt(accountId: string): Date | null {
+    const row = this.db
+      .prepare(`SELECT published_at FROM publications WHERE account_id = ? ORDER BY published_at DESC LIMIT 1`)
+      .get(accountId) as { published_at: string } | undefined;
+    return row ? new Date(row.published_at) : null;
+  }
+
+  publicationTimes(accountId: string, limit = 50): Date[] {
+    const rows = this.db
+      .prepare(
+        `SELECT MIN(published_at) AS published_at FROM publications WHERE account_id = ?
+         GROUP BY job_id ORDER BY MIN(published_at) DESC LIMIT ?`,
+      )
+      .all(accountId, limit) as Array<{ published_at: string }>;
+    return rows.map((row) => new Date(row.published_at));
+  }
+
+  /** True when any platform already has this job's video. */
+  jobHasPublication(jobId: string): boolean {
+    return Boolean(this.db.prepare(`SELECT id FROM publications WHERE job_id = ? LIMIT 1`).get(jobId));
+  }
+
+  /**
+   * When each video of the series was made, newest first. A video is one pipeline job that succeeded
+   * (at its finish time) or has a publication row (at its first publication when it did not succeed).
+   * A video on three platforms is one entry; a render nobody could publish still counts. A job waiting for review
+   * counts from the moment it began waiting, so the cadence goes on and the series does not pile up waiting jobs.
+   */
+  videoTimes(accountId: string, limit = 50): Date[] {
+    const rows = this.db
+      .prepare(
+        `SELECT CASE WHEN j.status = 'succeeded' THEN COALESCE(j.finished_at, j.updated_at)
+                     WHEN j.status = 'awaiting_review' THEN j.updated_at
+                     ELSE (SELECT MIN(p.published_at) FROM publications p WHERE p.job_id = j.id) END AS at
+         FROM jobs j
+         WHERE j.account_id = ? AND j.kind = 'pipeline'
+           AND (j.status IN ('succeeded', 'awaiting_review') OR EXISTS (SELECT 1 FROM publications p WHERE p.job_id = j.id))
+         ORDER BY at DESC LIMIT ?`,
+      )
+      .all(accountId, limit) as Array<{ at: string }>;
+    return rows.map((row) => new Date(row.at));
+  }
+
+  commentHandled(platform: string, commentId: string): boolean {
+    return Boolean(
+      this.db.prepare(`SELECT comment_id FROM comments_handled WHERE platform = ? AND comment_id = ?`).get(platform, commentId),
+    );
+  }
+
+  recordComment(row: {
+    platform: string;
+    commentId: string;
+    accountId: string;
+    action: string;
+    tone: string | null;
+    replyText: string | null;
+    at: Date;
+    /** Why a comment was skipped, for example `youtube_reply_403`. */
+    code?: string | null;
+    /** The comment itself, shown on the Engage screen. */
+    commentText?: string | null;
+    /** True when the reply was drafted but not sent (the series is not live). */
+    dryRun?: boolean;
+  }): void {
+    this.db
+      .prepare(
+        `INSERT OR IGNORE INTO comments_handled (platform, comment_id, account_id, action, tone, reply_text, created_at, code, comment_text, dry_run)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(row.platform, row.commentId, row.accountId, row.action, row.tone, row.replyText, row.at.toISOString(), row.code ?? null, row.commentText ? row.commentText.slice(0, 600) : null, row.dryRun ? 1 : 0);
+  }
+
+  /** Records what the last fetch of a source returned: n candidates, or an error code. */
+  recordSourceFetch(id: string, input: { at: Date; count: number | null; code: string | null; status: string }): void {
+    this.db
+      .prepare(`UPDATE desk_sources SET last_fetch_at = ?, last_count = ?, last_code = ?, last_status = ? WHERE id = ?`)
+      .run(input.at.toISOString(), input.count, input.code, input.status, id);
+  }
+
+  repliesSince(accountId: string, sinceIso: string): number {
+    const row = this.db
+      .prepare(
+        `SELECT COUNT(*) AS n FROM comments_handled WHERE account_id = ? AND action = 'replied' AND created_at >= ?`,
+      )
+      .get(accountId, sinceIso) as { n: number };
+    return Number(row.n);
+  }
+
+  lastReplyAt(accountId: string): Date | null {
+    const row = this.db
+      .prepare(
+        `SELECT created_at FROM comments_handled WHERE account_id = ? AND action = 'replied' ORDER BY created_at DESC LIMIT 1`,
+      )
+      .get(accountId) as { created_at: string } | undefined;
+    return row ? new Date(row.created_at) : null;
+  }
+
+  recordRate(bucket: string, at: Date): void {
+    this.db.prepare(`INSERT INTO rate_events (bucket, at) VALUES (?, ?)`).run(bucket, at.toISOString());
+  }
+
+  countRate(bucket: string, sinceIso: string): number {
+    const row = this.db
+      .prepare(`SELECT COUNT(*) AS n FROM rate_events WHERE bucket = ? AND at >= ?`)
+      .get(bucket, sinceIso) as { n: number };
+    return Number(row.n);
+  }
+
+  insertMetric(row: {
+    accountId: string;
+    platform: string;
+    externalId: string;
+    capturedAt: string;
+    views: number | null;
+    watchTimeSec: number | null;
+    retention: number | null;
+    estimatedRevenue: number | null;
+    revenueStatus: string;
+    raw: unknown;
+  }): void {
+    if ((row.revenueStatus === "forbidden" || row.revenueStatus === "unavailable") && row.estimatedRevenue != null) {
+      throw new Error(`A ${row.revenueStatus} metric cannot store a revenue number.`);
+    }
+    this.db
+      .prepare(
+        `INSERT INTO metrics (id, account_id, platform, external_id, captured_at, views, watch_time_sec, retention, estimated_revenue, revenue_status, raw)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        randomUUID(),
+        row.accountId,
+        row.platform,
+        row.externalId,
+        row.capturedAt,
+        row.views,
+        row.watchTimeSec,
+        row.retention,
+        row.estimatedRevenue,
+        row.revenueStatus,
+        JSON.stringify(row.raw),
+      );
+    if (row.revenueStatus === "forbidden") {
+      desk.insertWarningOnce(this.db, {
+        accountId: row.accountId,
+        jobId: null,
+        code: "revenue_forbidden",
+        message: `Revenue for ${row.platform} ${row.externalId} is forbidden.`,
+      });
+    }
+  }
+
+  recordEvent(jobId: string, event: desk.EventInput): void {
+    desk.recordEvent(this.db, jobId, event);
+  }
+
+  recordTerminal(jobId: string, event: Omit<desk.EventInput, "durationMs">): void {
+    desk.recordTerminal(this.db, jobId, event);
+  }
+
+  eventsFor(jobId: string): desk.JobEventRow[] {
+    return desk.eventsFor(this.db, jobId);
+  }
+
+  createAccount(input: { id: string; name: string; ownerId?: string | null }): void {
+    desk.createAccount(this.db, input);
+  }
+
+  renameAccount(id: string, name: string): desk.DeskResult {
+    return desk.renameAccount(this.db, id, name);
+  }
+
+  deleteAccount(id: string): desk.DeskResult {
+    return desk.deleteAccount(this.db, id);
+  }
+
+  setSecret(input: { ownerKind: "account" | "series"; ownerId: string; field: string; plaintext: string; key: string }) {
+    return desk.setSecret(this.db, input);
+  }
+
+  clearSecret(input: { ownerKind: "account" | "series"; ownerId: string; field: string }) {
+    return desk.clearSecret(this.db, input);
+  }
+
+  secretPresence(ownerKind: "account" | "series", ownerId: string): Record<string, boolean> {
+    return desk.secretPresence(this.db, ownerKind, ownerId);
+  }
+
+  createSeries(input: desk.SeriesInput): void {
+    desk.createSeries(this.db, input);
+  }
+
+  updateSeries(id: string, patch: Partial<desk.SeriesInput>): desk.DeskResult {
+    return desk.updateSeries(this.db, id, patch);
+  }
+
+  deleteSeries(id: string): desk.DeskResult {
+    return desk.deleteSeries(this.db, id);
+  }
+
+  pauseSeries(id: string): desk.DeskResult {
+    return desk.pauseSeries(this.db, id);
+  }
+
+  resumeSeries(id: string): desk.DeskResult {
+    return desk.resumeSeries(this.db, id);
+  }
+
+  seriesPaused(accountId: string): boolean {
+    return desk.seriesPaused(this.db, accountId);
+  }
+
+  /** The publish gates of a series: live, publish, review. A series the desk does not know is dry-run with publishing on. */
+  seriesGates(seriesId: string): desk.SeriesGates {
+    return desk.seriesGates(this.db, seriesId);
+  }
+
+  setLive(seriesId: string, live: boolean, message: string): desk.DeskResult {
+    return desk.setLive(this.db, seriesId, live, message);
+  }
+
+  seriesEvents(seriesId: string, limit = 20): Array<{ id: number; at: string; code: string; message: string }> {
+    return desk.seriesEvents(this.db, seriesId, limit);
+  }
+
+  recordSeriesEvent(seriesId: string, code: string, message: string): void {
+    desk.recordSeriesEvent(this.db, seriesId, code, message);
+  }
+
+  setPlatform(input: { seriesId: string; platform: string; enabled: boolean; config?: Record<string, unknown> }): desk.DeskResult {
+    return desk.setPlatform(this.db, input);
+  }
+
+  disablePlatform(seriesId: string, platform: string): desk.DeskResult {
+    return desk.disablePlatform(this.db, seriesId, platform);
+  }
+
+  removePlatform(seriesId: string, platform: string): desk.DeskResult {
+    return desk.removePlatform(this.db, seriesId, platform);
+  }
+
+  addSource(input: { seriesId: string; kind: string; value: string }): { id: string } {
+    return desk.addSource(this.db, input);
+  }
+
+  updateSource(id: string, value: string): desk.DeskResult {
+    return desk.updateSource(this.db, id, value);
+  }
+
+  removeSource(id: string): desk.DeskResult {
+    return desk.removeSource(this.db, id);
+  }
+
+  setMode(userId: string, mode: string, llmKeyPresent: boolean): desk.DeskResult {
+    return desk.setMode(this.db, userId, mode, llmKeyPresent);
+  }
+
+  clearMode(userId: string): desk.DeskResult {
+    return desk.clearMode(this.db, userId);
+  }
+
+  readMode(userId: string): "agent" | "api" {
+    return desk.readMode(this.db, userId);
+  }
+
+  setCadence(
+    seriesId: string,
+    input: { timezone: string; minHoursBetweenPosts: number; maxPostsPerDay: number; windows: string[] },
+  ): desk.DeskResult {
+    return desk.setCadence(this.db, seriesId, input);
+  }
+
+  clearCadence(): desk.DeskResult {
+    return desk.clearCadence();
+  }
+
+  setQuota(
+    seriesId: string,
+    input: { youtubeDailyUploadCap: number; maxRepliesPerDay: number; minSecondsBetween: number },
+  ): desk.DeskResult {
+    return desk.setQuota(this.db, seriesId, input);
+  }
+
+  clearQuota(): desk.DeskResult {
+    return desk.clearQuota();
+  }
+
+  insertWarning(input: { accountId: string | null; jobId: string | null; code: string; message: string }): { id: string } {
+    return desk.insertWarning(this.db, input);
+  }
+
+  ackWarning(id: string): desk.DeskResult {
+    return desk.ackWarning(this.db, id);
+  }
+
+  deleteWarning(): desk.DeskResult {
+    return desk.deleteWarning();
+  }
+
+  deleteJob(): desk.DeskResult {
+    return desk.deleteJob();
+  }
+
+  deletePublication(): desk.DeskResult {
+    return desk.deletePublication();
+  }
+
+  deleteMetric(): desk.DeskResult {
+    return desk.deleteMetric();
+  }
+
+  deleteComment(): desk.DeskResult {
+    return desk.deleteComment();
+  }
+
+  retryJob(id: string, now = new Date()): desk.DeskResult {
+    return desk.retryJob(this.db, id, now);
+  }
+
+  /** Releases a job that waits for review. Exactly one caller wins; the next tick renders it. */
+  approveJob(id: string, now = new Date()): desk.DeskResult {
+    return desk.approveJob(this.db, id, now);
+  }
+
+  /** Ends a job that waits for review as `rejected` with the code `review_rejected`. */
+  rejectJob(id: string, reason: string | null, now = new Date()): desk.DeskResult {
+    return desk.rejectJob(this.db, id, reason, now);
+  }
+
+  /** How many jobs wait for review, overall or for one series. */
+  awaitingReviewCount(seriesId?: string): number {
+    return desk.awaitingReviewCount(this.db, seriesId);
+  }
+
+  /** The ids of a series' jobs that wait for review, oldest first. */
+  awaitingReviewJobs(seriesId: string): string[] {
+    return (this.db.prepare(`SELECT id FROM jobs WHERE account_id = ? AND status = 'awaiting_review' ORDER BY updated_at ASC, rowid ASC`).all(seriesId) as Array<{ id: string }>).map((row) => row.id);
+  }
+
+  /** The Review screen: every job waiting for review, oldest first. */
+  reviewQueue(dataDir: string | null = null) {
+    return desk.reviewQueue(this.db, dataDir);
+  }
+
+  cancelJob(id: string, now = new Date()): desk.DeskResult {
+    return desk.cancelJob(this.db, id, now);
+  }
+
+  engineDefault(): string | null {
+    return desk.readEngineDefault(this.db);
+  }
+
+  setEngineDefault(engine: string): void {
+    desk.writeEngineDefault(this.db, engine);
+  }
+
+  seriesEngine(seriesId: string): string | null {
+    return desk.readSeriesEngine(this.db, seriesId);
+  }
+
+  snapshot(userId: string): Record<string, unknown> {
+    return desk.buildSnapshot(this.db, userId, this.dataDir);
+  }
+
+  importLegacy(fromDir: string): { imported: Record<string, number>; files: number } {
+    return desk.importLegacy(this.db, this.dataDir, fromDir);
+  }
+
+  runDetail(id: string): ReturnType<typeof desk.buildRunDetail> {
+    return desk.buildRunDetail(this.db, id, this.dataDir);
+  }
+
+  latestMetrics(): Array<Record<string, unknown>> {
+    return this.db
+      .prepare(
+        `SELECT m.* FROM metrics m
+         JOIN (
+           SELECT external_id, platform, MAX(captured_at) AS captured_at
+           FROM metrics GROUP BY external_id, platform
+         ) latest
+         ON m.external_id = latest.external_id AND m.platform = latest.platform AND m.captured_at = latest.captured_at
+         ORDER BY m.views IS NULL, m.views DESC, m.watch_time_sec IS NULL, m.watch_time_sec DESC`,
+      )
+      .all() as Array<Record<string, unknown>>;
+  }
+
+  setHealth(accountId: string, platform: string, tokenState: string, lastError: string | null, at: Date): void {
+    this.db
+      .prepare(
+        `INSERT INTO account_health (account_id, platform, token_state, last_error, updated_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT (account_id, platform) DO UPDATE SET token_state = excluded.token_state, last_error = excluded.last_error, updated_at = excluded.updated_at`,
+      )
+      .run(accountId, platform, tokenState, lastError, at.toISOString());
+    if (lastError) {
+      desk.insertWarningOnce(this.db, {
+        accountId,
+        jobId: null,
+        code: `health:${platform}`,
+        message: lastError,
+      });
+    }
+  }
+
+  deskOverlay(accountId: string): desk.DeskOverlay | null {
+    return desk.deskOverlay(this.db, accountId);
+  }
+
+  warnOnce(input: { accountId: string | null; jobId: string | null; code: string; message: string }): { id: string } {
+    return desk.insertWarningOnce(this.db, input);
+  }
+
+  healthRows(): Array<Record<string, unknown>> {
+    return this.db.prepare(`SELECT * FROM account_health`).all() as Array<Record<string, unknown>>;
+  }
+
+  /** One job by id, or null. */
+  job(id: string): JobRecord | null {
+    try {
+      return this.mustGet(id);
+    } catch {
+      return null;
+    }
+  }
+
+  private mustGet(id: string): JobRecord {
+    const row = this.db.prepare(`SELECT * FROM jobs WHERE id = ?`).get(id) as Record<string, unknown> | undefined;
+    if (!row) throw new Error(`job ${id} missing`);
+    return {
+      id: String(row.id),
+      accountId: String(row.account_id),
+      kind: row.kind as JobKind,
+      stage: row.stage as JobStage,
+      status: row.status as JobStatus,
+      payload: JSON.parse(String(row.payload)) as PipelineData,
+      attempt: Number(row.attempt),
+      maxAttempts: Number(row.max_attempts),
+      leaseUntil: row.lease_until ? String(row.lease_until) : null,
+      leaseToken: row.lease_token ? String(row.lease_token) : null,
+      runAfter: String(row.run_after),
+      lastError: row.last_error ? String(row.last_error) : null,
+      createdAt: String(row.created_at),
+      updatedAt: String(row.updated_at),
+    };
+  }
+}
+
+/** The job's claim was cancelled or taken over while this worker still held it. The worker stops without writing. */
+export class LeaseLost extends Error {
+  constructor(readonly jobId: string) {
+    super(`The claim on job ${jobId} is gone.`);
+    this.name = "LeaseLost";
+  }
+}
+
+export function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+export function emptyPayload(): PipelineData {
+  return {
+    candidates: [],
+    rejectedFingerprints: [],
+    content: null,
+    platforms: {},
+    engageReplied: 0,
+    dryRunPayloads: {},
+  };
+}