gsd-pi 2.78.1-dev.d8826a445 → 2.78.1-dev.eccf86e27

package/src/resources/extensions/gsd/db/command-queue.ts

@@ -0,0 +1,149 @@
+// gsd-2 + Worker IPC command queue (DB-backed coordination, Phase B)
+//
+// New infrastructure for dispatcher-to-worker IPC (cancel signals, pause
+// requests, etc.). NOT a replacement for any existing on-disk queue and
+// NOT related to startAutoCommandPolling() in auto.ts (which polls a
+// remote channel like Telegram, not a local file queue).
+//
+// Broadcast semantics (codex review LOW B4):
+// SQLite indexes NULLs in B-trees, so the single index
+// idx_command_queue_pending(target_worker, claimed_at) serves both:
+//   - targeted queries: WHERE target_worker = ?
+//   - broadcast queries: WHERE target_worker IS NULL
+// Workers should poll for both forms (their own ID + broadcasts) on each
+// claim cycle.
+
+import {
+  _getAdapter,
+  isDbAvailable,
+  transaction,
+} from "../gsd-db.js";
+
+export interface CommandQueueRow {
+  id: number;
+  target_worker: string | null;
+  command: string;
+  args_json: string;
+  enqueued_at: string;
+  claimed_at: string | null;
+  claimed_by: string | null;
+  completed_at: string | null;
+  result_json: string | null;
+}
+
+export interface EnqueueInput {
+  /** null = broadcast to all workers; string = target a specific worker_id */
+  targetWorker: string | null;
+  command: string;
+  args?: Record<string, unknown>;
+}
+
+/**
+ * Enqueue a command. Returns the new row id. Broadcast commands
+ * (targetWorker=null) will be claimed by exactly one worker — the IPC
+ * model is "single delivery to whoever claims first", not pub-sub.
+ */
+export function enqueueCommand(input: EnqueueInput): number {
+  if (!isDbAvailable()) {
+    throw new Error("enqueueCommand: DB unavailable");
+  }
+  const now = new Date().toISOString();
+  const db = _getAdapter()!;
+  const result = transaction(() => {
+    return db.prepare(
+      `INSERT INTO command_queue (target_worker, command, args_json, enqueued_at)
+       VALUES (:target_worker, :command, :args_json, :enqueued_at)`,
+    ).run({
+      ":target_worker": input.targetWorker,
+      ":command": input.command,
+      ":args_json": JSON.stringify(input.args ?? {}),
+      ":enqueued_at": now,
+    });
+  });
+  return Number((result as { lastInsertRowid?: number | bigint }).lastInsertRowid ?? 0);
+}
+
+/**
+ * Atomically claim the next pending command for the given worker. Returns
+ * the claimed row, or null if nothing to claim.
+ *
+ * Polls both targeted (target_worker = workerId) and broadcast
+ * (target_worker IS NULL) queues, oldest-first.
+ */
+export function claimNextCommand(workerId: string): CommandQueueRow | null {
+  if (!isDbAvailable()) return null;
+  const now = new Date().toISOString();
+  const db = _getAdapter()!;
+
+  return transaction((): CommandQueueRow | null => {
+    // Find the oldest unclaimed command targeted at this worker OR
+    // broadcast. The partial index covers both via NULL-in-B-tree.
+    const row = db.prepare(
+      `SELECT id, target_worker, command, args_json, enqueued_at,
+              claimed_at, claimed_by, completed_at, result_json
+       FROM command_queue
+       WHERE claimed_at IS NULL
+         AND completed_at IS NULL
+         AND (target_worker = :worker_id OR target_worker IS NULL)
+       ORDER BY enqueued_at ASC, id ASC
+       LIMIT 1`,
+    ).get({ ":worker_id": workerId }) as CommandQueueRow | undefined;
+
+    if (!row) return null;
+
+    // Conditional UPDATE — only succeeds if still unclaimed (guards against
+    // races between two workers polling simultaneously).
+    const result = db.prepare(
+      `UPDATE command_queue
+       SET claimed_at = :now, claimed_by = :worker_id
+       WHERE id = :id AND claimed_at IS NULL AND completed_at IS NULL`,
+    ).run({ ":now": now, ":worker_id": workerId, ":id": row.id });
+
+    const changes =
+      typeof (result as { changes?: unknown }).changes === "number"
+        ? (result as { changes: number }).changes
+        : 0;
+
+    if (changes !== 1) return null; // lost the race
+
+    return { ...row, claimed_at: now, claimed_by: workerId };
+  });
+}
+
+/**
+ * Mark a command complete with optional result payload. Idempotent — if
+ * the command is already completed, the second call is a no-op.
+ */
+export function completeCommand(
+  id: number,
+  workerId: string,
+  result?: Record<string, unknown>,
+): void {
+  if (!isDbAvailable()) return;
+  const now = new Date().toISOString();
+  const db = _getAdapter()!;
+  db.prepare(
+    `UPDATE command_queue
+     SET completed_at = :now, result_json = :result_json
+     WHERE id = :id
+       AND claimed_by = :worker_id
+       AND completed_at IS NULL`,
+  ).run({
+    ":id": id,
+    ":worker_id": workerId,
+    ":now": now,
+    ":result_json": result ? JSON.stringify(result) : null,
+  });
+}
+
+/** Diagnostic helper: read a single row by id. */
+export function getCommand(id: number): CommandQueueRow | null {
+  if (!isDbAvailable()) return null;
+  const db = _getAdapter()!;
+  const row = db.prepare(
+    `SELECT id, target_worker, command, args_json, enqueued_at,
+            claimed_at, claimed_by, completed_at, result_json
+     FROM command_queue WHERE id = :id`,
+  ).get({ ":id": id }) as CommandQueueRow | undefined;
+  return row ?? null;
+}

package/src/resources/extensions/gsd/db/milestone-leases.ts

@@ -0,0 +1,274 @@
+// gsd-2 + Milestone leases with fencing tokens (DB-backed coordination, Phase B)
+//
+// One worker at a time may hold a lease on a given milestone. Leases carry a
+// monotonic fencing token that increments on every successful takeover, so
+// stale workers can be cheaply detected and rejected at write time
+// (unit_dispatches.milestone_lease_token).
+//
+// Codex review BLOCKING B1: claim semantics must atomically handle two
+// distinct cases inside one transaction:
+//   1. First claim (no row exists)         → INSERT with fencing_token=1
+//   2. Takeover (row exists, expired/released) → UPDATE w/ fencing_token+1
+// `INSERT OR ABORT` alone is wrong because the row already exists for any
+// takeover and a plain INSERT cannot succeed.
+
+import { randomUUID } from "node:crypto";
+
+import {
+  _getAdapter,
+  isDbAvailable,
+  transaction,
+  insertAuditEvent,
+} from "../gsd-db.js";
+
+const LEASE_TTL_SECONDS = 60;
+
+export type LeaseStatus = "held" | "released" | "expired";
+
+export interface MilestoneLeaseRow {
+  milestone_id: string;
+  worker_id: string;
+  fencing_token: number;
+  acquired_at: string;
+  expires_at: string;
+  status: LeaseStatus;
+}
+
+export type ClaimResult =
+  | { ok: true; token: number; expiresAt: string }
+  | { ok: false; error: "held_by"; byWorker: string; expiresAt: string };
+
+function isDuplicateLeaseInsertError(err: unknown): boolean {
+  const code =
+    err && typeof err === "object" && "code" in err
+      ? String((err as { code?: unknown }).code ?? "")
+      : "";
+  const msg = err instanceof Error ? err.message : String(err);
+  if (/\bFOREIGN KEY\b/i.test(msg)) {
+    return false;
+  }
+
+  if (code === "SQLITE_CONSTRAINT" || code === "SQLITE_CONSTRAINT_PRIMARYKEY" || code === "SQLITE_CONSTRAINT_UNIQUE") {
+    return true;
+  }
+
+  return /\bUNIQUE\b|\bPRIMARY KEY\b|\bconstraint failed\b/i.test(msg);
+}
+
+function ttlExpiry(now: Date): string {
+  return new Date(now.getTime() + LEASE_TTL_SECONDS * 1000).toISOString();
+}
+
+/**
+ * Acquire (or take over an expired) milestone lease for the given worker.
+ *
+ * Atomicity: the entire claim runs inside a single transaction so the
+ * INSERT-vs-UPDATE branch decision can never tear under concurrent claims.
+ * Fencing token is computed by SQL (`fencing_token + 1`), never supplied
+ * by the client. Initial value is 1.
+ *
+ * datetime('now') uses local wall-clock time, so this remains single-host
+ * SQLite WAL coordination only. Cross-host coordination would need a real
+ * coordinator; out of scope for Phase B.
+ */
+export function claimMilestoneLease(
+  workerId: string,
+  milestoneId: string,
+): ClaimResult {
+  if (!isDbAvailable()) {
+    throw new Error("claimMilestoneLease: DB unavailable");
+  }
+  const now = new Date();
+  const nowIso = now.toISOString();
+  const expiresIso = ttlExpiry(now);
+
+  return transaction((): ClaimResult => {
+    const db = _getAdapter()!;
+
+    // Step 1: try a fresh INSERT. If it fails because the row already
+    // exists, fall through to the takeover branch below.
+    let inserted = false;
+    try {
+      db.prepare(
+        `INSERT INTO milestone_leases (
+          milestone_id, worker_id, fencing_token,
+          acquired_at, expires_at, status
+        ) VALUES (
+          :milestone_id, :worker_id, 1,
+          :acquired_at, :expires_at, 'held'
+        )`,
+      ).run({
+        ":milestone_id": milestoneId,
+        ":worker_id": workerId,
+        ":acquired_at": nowIso,
+        ":expires_at": expiresIso,
+      });
+      inserted = true;
+    } catch (err) {
+      // SQLite raises a constraint error on duplicate PK — catch and fall
+      // through to UPDATE. Any other error is a bug; rethrow.
+      if (!isDuplicateLeaseInsertError(err)) throw err;
+    }
+
+    if (inserted) {
+      insertAuditEvent({
+        eventId: randomUUID(),
+        traceId: workerId,
+        category: "orchestration",
+        type: "lease-acquired",
+        ts: nowIso,
+        payload: { workerId, milestoneId, token: 1, mode: "fresh" },
+      });
+      return { ok: true, token: 1, expiresAt: expiresIso };
+    }
+
+    // Step 2: takeover. Conditional UPDATE — only succeeds if the existing
+    // lease is expired or explicitly released. Fencing token is incremented
+    // by SQL (`fencing_token + 1`) so the new holder's token monotonically
+    // exceeds the prior holder's. db.changes() === 1 confirms the takeover
+    // actually happened (vs. losing the race to another worker).
+    const updateResult = db.prepare(
+      `UPDATE milestone_leases
+       SET worker_id = :worker_id,
+           fencing_token = fencing_token + 1,
+           acquired_at = :acquired_at,
+           expires_at = :expires_at,
+           status = 'held'
+       WHERE milestone_id = :milestone_id
+         AND (status IN ('expired','released')
+              OR datetime(expires_at) < datetime('now'))`,
+    ).run({
+      ":milestone_id": milestoneId,
+      ":worker_id": workerId,
+      ":acquired_at": nowIso,
+      ":expires_at": expiresIso,
+    });
+
+    const changes =
+      typeof (updateResult as { changes?: unknown }).changes === "number"
+        ? (updateResult as { changes: number }).changes
+        : 0;
+
+    if (changes === 1) {
+      // Read back to obtain the new token value.
+      const row = db.prepare(
+        `SELECT worker_id, fencing_token, expires_at FROM milestone_leases WHERE milestone_id = :milestone_id`,
+      ).get({ ":milestone_id": milestoneId }) as Pick<MilestoneLeaseRow, "worker_id" | "fencing_token" | "expires_at"> | undefined;
+      const token = row?.fencing_token ?? 1;
+      insertAuditEvent({
+        eventId: randomUUID(),
+        traceId: workerId,
+        category: "orchestration",
+        type: "lease-acquired",
+        ts: nowIso,
+        payload: { workerId, milestoneId, token, mode: "takeover" },
+      });
+      return { ok: true, token, expiresAt: expiresIso };
+    }
+
+    // Lease still held by someone else — read current holder for the error.
+    const holder = db.prepare(
+      `SELECT worker_id, expires_at FROM milestone_leases WHERE milestone_id = :milestone_id`,
+    ).get({ ":milestone_id": milestoneId }) as { worker_id: string; expires_at: string } | undefined;
+
+    return {
+      ok: false,
+      error: "held_by",
+      byWorker: holder?.worker_id ?? "unknown",
+      expiresAt: holder?.expires_at ?? "",
+    };
+  });
+}
+
+/**
+ * Refresh the lease's expires_at when the worker heartbeats. Idempotent —
+ * silently no-ops if the lease was already taken over or released.
+ */
+export function refreshMilestoneLease(
+  workerId: string,
+  milestoneId: string,
+  fencingToken: number,
+): boolean {
+  if (!isDbAvailable()) return false;
+  const now = new Date();
+  const expiresIso = ttlExpiry(now);
+  const db = _getAdapter()!;
+  const result = db.prepare(
+    `UPDATE milestone_leases
+     SET expires_at = :expires_at
+     WHERE milestone_id = :milestone_id
+       AND worker_id = :worker_id
+       AND fencing_token = :token
+       AND status = 'held'`,
+  ).run({
+    ":expires_at": expiresIso,
+    ":milestone_id": milestoneId,
+    ":worker_id": workerId,
+    ":token": fencingToken,
+  });
+  const changes =
+    typeof (result as { changes?: unknown }).changes === "number"
+      ? (result as { changes: number }).changes
+      : 0;
+  return changes === 1;
+}
+
+/**
+ * Voluntarily release the lease (e.g. clean shutdown). Future claims may
+ * proceed without waiting for TTL expiry.
+ */
+export function releaseMilestoneLease(
+  workerId: string,
+  milestoneId: string,
+  fencingToken: number,
+): boolean {
+  if (!isDbAvailable()) return false;
+  const db = _getAdapter()!;
+  return transaction(() => {
+    const result = db.prepare(
+      `UPDATE milestone_leases
+       SET status = 'released'
+       WHERE milestone_id = :milestone_id
+         AND worker_id = :worker_id
+         AND fencing_token = :token
+         AND status = 'held'`,
+    ).run({
+      ":milestone_id": milestoneId,
+      ":worker_id": workerId,
+      ":token": fencingToken,
+    });
+    const changes =
+      typeof (result as { changes?: unknown }).changes === "number"
+        ? (result as { changes: number }).changes
+        : 0;
+    if (changes === 1) {
+      insertAuditEvent({
+        eventId: randomUUID(),
+        traceId: workerId,
+        category: "orchestration",
+        type: "lease-released",
+        ts: new Date().toISOString(),
+        payload: { workerId, milestoneId, token: fencingToken },
+      });
+    }
+    return changes === 1;
+  });
+}
+
+/**
+ * Read current lease row for diagnostics. Returns null if no row exists.
+ */
+export function getMilestoneLease(milestoneId: string): MilestoneLeaseRow | null {
+  if (!isDbAvailable()) return null;
+  const db = _getAdapter()!;
+  const row = db.prepare(
+    `SELECT milestone_id, worker_id, fencing_token, acquired_at, expires_at, status
+     FROM milestone_leases WHERE milestone_id = :milestone_id`,
+  ).get({ ":milestone_id": milestoneId }) as MilestoneLeaseRow | undefined;
+  return row ?? null;
+}
+
+/** TTL exported so callers (e.g. tests / janitors) can compute expirations. */
+export function milestoneLeaseTtlSeconds(): number {
+  return LEASE_TTL_SECONDS;
+}

package/src/resources/extensions/gsd/db/runtime-kv.ts

@@ -0,0 +1,127 @@
+// gsd-2 + Non-correctness-critical key-value storage (Phase C — file-state migration)
+//
+// STRICT INVARIANT (re-stated from gsd-db.ts createRuntimeKvTableV25):
+// runtime_kv is for SOFT state only. UI cursors, dashboard caches,
+// last-seen-version markers, resume cursors, and similar values that
+// can be lost without breaking auto-mode correctness.
+//
+// Anything that drives the auto-loop's control flow MUST get typed
+// columns in unit_dispatches / workers / milestone_leases — never a
+// bag of JSON in runtime_kv. The reviewer's smell test: if losing the
+// row would cause the loop to reorder, double-execute, or stuck-loop,
+// it does NOT belong here.
+//
+// Single-host invariant: SQLite WAL coordination, local disk only.
+// See db/auto-workers.ts for the same constraint applied to coordination.
+
+import {
+  _getAdapter,
+  isDbAvailable,
+  transaction,
+} from "../gsd-db.js";
+
+export type RuntimeKvScope = "global" | "worker" | "milestone";
+
+export interface RuntimeKvRow {
+  scope: RuntimeKvScope;
+  scope_id: string;
+  key: string;
+  value_json: string;
+  updated_at: string;
+}
+
+/**
+ * Set or update a runtime_kv row. The value is JSON-stringified before
+ * storage. Best-effort — silently no-ops when the DB is unavailable.
+ */
+export function setRuntimeKv(
+  scope: RuntimeKvScope,
+  scopeId: string,
+  key: string,
+  value: unknown,
+): void {
+  if (!isDbAvailable()) return;
+  const now = new Date().toISOString();
+  const db = _getAdapter()!;
+  let valueJson: string;
+  try {
+    valueJson = JSON.stringify(value);
+  } catch {
+    valueJson = JSON.stringify(String(value));
+  }
+  if (valueJson === undefined) {
+    valueJson = JSON.stringify(null);
+  }
+  transaction(() => {
+    db.prepare(
+      `INSERT INTO runtime_kv (scope, scope_id, key, value_json, updated_at)
+       VALUES (:scope, :scope_id, :key, :value_json, :updated_at)
+       ON CONFLICT (scope, scope_id, key) DO UPDATE SET
+         value_json = excluded.value_json,
+         updated_at = excluded.updated_at`,
+    ).run({
+      ":scope": scope,
+      ":scope_id": scopeId,
+      ":key": key,
+      ":value_json": valueJson,
+      ":updated_at": now,
+    });
+  });
+}
+
+/**
+ * Read a runtime_kv value, parsed from JSON. Returns null if the row
+ * doesn't exist or the DB is unavailable.
+ */
+export function getRuntimeKv<T = unknown>(
+  scope: RuntimeKvScope,
+  scopeId: string,
+  key: string,
+): T | null {
+  if (!isDbAvailable()) return null;
+  const db = _getAdapter()!;
+  const row = db.prepare(
+    `SELECT value_json FROM runtime_kv
+     WHERE scope = :scope AND scope_id = :scope_id AND key = :key`,
+  ).get({ ":scope": scope, ":scope_id": scopeId, ":key": key }) as { value_json: string } | undefined;
+  if (!row) return null;
+  try {
+    return JSON.parse(row.value_json) as T;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Delete a runtime_kv row. Idempotent — silently no-ops when the row
+ * doesn't exist or the DB is unavailable.
+ */
+export function deleteRuntimeKv(
+  scope: RuntimeKvScope,
+  scopeId: string,
+  key: string,
+): void {
+  if (!isDbAvailable()) return;
+  const db = _getAdapter()!;
+  db.prepare(
+    `DELETE FROM runtime_kv WHERE scope = :scope AND scope_id = :scope_id AND key = :key`,
+  ).run({ ":scope": scope, ":scope_id": scopeId, ":key": key });
+}
+
+/**
+ * List all rows within a (scope, scopeId) bucket. Useful for diagnostics
+ * and bulk migrations.
+ */
+export function listRuntimeKv(
+  scope: RuntimeKvScope,
+  scopeId: string,
+): readonly RuntimeKvRow[] {
+  if (!isDbAvailable()) return [];
+  const db = _getAdapter()!;
+  return db.prepare(
+    `SELECT scope, scope_id, key, value_json, updated_at
+     FROM runtime_kv
+     WHERE scope = :scope AND scope_id = :scope_id
+     ORDER BY key`,
+  ).all({ ":scope": scope, ":scope_id": scopeId }) as unknown as RuntimeKvRow[];
+}