@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/image-bake-store-sql.js

@@ -1,9 +1,52 @@
+/**
+ * Sandbox-image-pool BAKE store — SINGLE-FILE DUAL-DIALECT (design/158 A12 定型半场; the 4th collapse
+ * after background-agent / mailbox / task-list / roster). ONE implementation, TWO dialects; the
+ * historical `TiDBImageBake` / `PgImageBake` class names survive as thin ctor subclasses so every
+ * consumer (store-backend.ts, pg-pool.ts, the unit + real-DB suites) is untouched.
+ *
+ * A bake is the async, resumable, auto-registering execution of `build.sh` on the privileged build-host
+ * bake-runner. image-api (this, the unprivileged controller) owns the durable job row + the per-bake event
+ * log + the single-flight build lease; the runner CLAIMS a queued bake, runs build.sh, and POSTs each
+ * build.sh JSON line back to the ingest endpoint, which appends to the event log the SSE reader serves
+ * (run-trace mechanics verbatim: `(bakeId,seq)` PK, ++seq, getEvents(after), maxSeq, retainedFrom→416,
+ * heartbeat-not-persisted).
+ *
+ * This is a DEDICATED table set — NOT a reuse of task_run/task_event (FK-coupled to task_active + the run
+ * reaper + the /v1/runs list; co-mingling bakes — no session, no spend, no checkpoint — would leak non-task
+ * rows into reapStale/listRuns, a category error). The shape mirrors TiDBRunStore: durable idempotency via a
+ * unique-key CAS (like createRun), a conditional-UPDATE single-flight claim (like requestCancel), and a
+ * reaper twin.
+ *
+ * The split that makes the SSE reader correct (P2.3 MUST-FIX): the COARSE 4-value `status`
+ * (queued|running|done|failed) is what the reader polls for terminality; build.sh's 8-value `state`
+ * (PENDING→…→COMPLETE|FAILED|CANCELLED) is denormalized for the UI progress bar ONLY and never drives stream
+ * termination (a non-terminal PUSHING/VERIFYING state must NOT truncate the stream before `done`).
+ *
+ * ── Dialect deltas, kept EXPLICIT (never hidden behind an abstraction) ────────────────────────────────
+ *   - `?` placeholders vs `$n`                        - `CAST(? AS JSON)` vs `$n::jsonb` (argv equality)
+ *   - `INSERT IGNORE` vs `ON CONFLICT DO NOTHING`     - affectedRows vs rowCount (via SqlDriver)
+ *   - dup-key `ER_DUP_ENTRY` vs SQLSTATE `23505`      - which UNIQUE collided: mysql2 `sqlMessage` text
+ *                                                       vs pg `err.constraint` (uq_line naming differs)
+ *   - `BEGIN PESSIMISTIC` (TiDB current read) vs `BEGIN` (PG READ COMMITTED under the sentinel lock)
+ *   - the ADMISSION statement itself differs (see createBakeIfIdle) — both are correct under the
+ *     sentinel lock, and both are preserved verbatim because the real-DB suites are the oracle
+ *   - PG-ONLY protocol-byte defenses: `pgSafeJsonStringify` on event payloads, and the setTerminal
+ *     identity-fold (`invalidIdentity`) + `pgSanitizeText` on error/errorCode/tag. TiDB stores verbatim.
+ *   - schema ownership: the TiDB DDL lives in tidb-pool.ts SCHEMA_STATEMENTS; the PG DDL is exported
+ *     from HERE (PG_IMAGE_BAKE_SCHEMA + ensurePgImageBakeSchema) for pg-pool.ts + the integration test.
+ */
 import { uuidv7 } from "@sema-agent/core";
 import { randomBytes } from "node:crypto";
 import { pgSanitizeText, pgSafeJsonStringify, pgHasUnstorable } from "./pg-safe-json.js";
 import { parseJsonOr as parseJson, toIso as iso } from "./sql-row-helpers.js";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { mapBakeRow as mapRow, BAKE_SELECT_COLS as SELECT_COLS, } from "./store-contracts.js";
+/** PG translation of the image_bake / image_bake_event / image_bake_lease DDL in tidb-pool.ts SCHEMA_STATEMENTS
+ *  (JSON→JSONB, TINYINT→SMALLINT, DATETIME(3)→TIMESTAMPTZ(3), inline UNIQUE/KEY→named CONSTRAINT + CREATE INDEX).
+ *  TINYINT(1) 归一(clay 批 2026-07-26):布尔列的 PG 映射统一 SMALLINT 0/1(此前本家族用 BOOLEAN)——
+ *  两方言驱动读回同为 number ⇒ 不再存在「忘了配的适配器」这个病族;写入参与 SQL 字面量一律 0/1,
+ *  读侧 `!!`/`Boolean()` 保持,store 出口 JS 类型逐字节不变(真双库套件的严格值断言为证)。
+ *  The uq_line UNIQUE is given an explicit name so a 23505 can be attributed to it via err.constraint. */
 export const PG_IMAGE_BAKE_SCHEMA = [
     `CREATE TABLE IF NOT EXISTS image_bake (
      bake_id          VARCHAR(64)  NOT NULL,
@@ -56,20 +99,33 @@ export const PG_IMAGE_BAKE_SCHEMA = [
      expires_at  TIMESTAMPTZ(3) NOT NULL,
      PRIMARY KEY (pool)
    )`,
+    // Admission sentinel: ONE always-present row per builder pool, `SELECT … FOR UPDATE`-locked to SERIALIZE the
+    // createBakeIfIdle busy-check+insert (so the M4 single-flight admission is genuinely atomic, not a snapshot
+    // NOT EXISTS that two concurrent READ COMMITTED txns both pass — see createBakeIfIdle). Dialect-uniform with
+    // the TiDB twin so a future divergence FAILS LOUD in the shared real-DB suite.
     `CREATE TABLE IF NOT EXISTS image_bake_admit (
      pool VARCHAR(32) NOT NULL,
      PRIMARY KEY (pool)
    )`,
 ];
+/** Idempotent self-contained PG schema apply (for the integration test; central aggregation is done separately). */
 export async function ensurePgImageBakeSchema(pool, poolName = "standard") {
     for (const stmt of PG_IMAGE_BAKE_SCHEMA)
         await pool.query(stmt);
+    // Seed the always-present admission sentinel (idempotent) so createBakeIfIdle can FOR UPDATE-lock it.
     await pool.query("INSERT INTO image_bake_admit (pool) VALUES ($1) ON CONFLICT (pool) DO NOTHING", [poolName]);
 }
+/** Dup-key detection — mysql2 names it `ER_DUP_ENTRY`, PG raises SQLSTATE 23505. */
 function isDupKey(dialect, err) {
     const code = err?.code;
     return Boolean(err) && code === (dialect === "tidb" ? "ER_DUP_ENTRY" : "23505");
 }
+/** Which UNIQUE key did the dup collide on? The ATTRIBUTION CHANNEL differs by engine: mysql2 names the key in
+ *  `sqlMessage` ("Duplicate entry '…' for key 'image_bake_event.uq_line'" vs "…'image_bake_event.PRIMARY'");
+ *  PG names the violated constraint in `err.constraint` (the PK is auto-named `image_bake_event_pkey`, the line
+ *  UNIQUE is explicitly named `uq_image_bake_event_line` so it is attributable at all).
+ *  M2: a line-unique dup is a BENIGN at-least-once re-send (already stored → no-op); a `PRIMARY` (bake_id,seq)
+ *  dup is a same-seq RACE the caller must RETRY (a fresh maxSeq+1), never swallow. */
 function dupKeyName(dialect, err) {
     if (dialect === "tidb") {
         const msg = String(err?.sqlMessage ?? err?.message ?? "");
@@ -88,16 +144,21 @@ function dupKeyName(dialect, err) {
 }
 const INSERT_BAKE_COLS = "INSERT INTO image_bake (bake_id, profile, bands, base_ref, push, dry_run, logs, argv, status, " +
     "idem_key, cancel_requested, requested_by, created_at, updated_at) ";
+/** Dual-dialect BAKE store. See the file header for the dialect-delta ledger. */
 export class SqlImageBake {
     db;
     poolName;
-    constructor(db, poolName = "standard") {
+    constructor(db, 
+    /** The builder pool a lease serializes on (one docker daemon ⇒ one pool today). */
+    poolName = "standard") {
         this.db = db;
         this.poolName = poolName;
     }
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
+    /** The 12 bound values shared by both admission INSERTs (column order === INSERT_BAKE_COLS). */
     insertParams(bakeId, input, now) {
         return [
             bakeId,
@@ -114,6 +175,12 @@ export class SqlImageBake {
             now,
         ];
     }
+    /**
+     * Create a bake, queued. Durable submit-idempotency mirrors createRun's CAS: `idem_key` is UNIQUE, so a
+     * re-submit with the same key races to INSERT and the loser catches the dup-key, then re-reads + returns the
+     * EXISTING row (the live bake) instead of a second job. A null `idemKey` always inserts (no dedupe requested).
+     * Returns `{ created, bake }` so the handler can answer 202 either way (idempotent dup ⇒ created:false).
+     */
     async createBake(input) {
         const bakeId = uuidv7();
         const now = new Date();
@@ -133,6 +200,35 @@ export class SqlImageBake {
             throw new Error("createBake: row vanished after insert");
         return { created: true, bake };
     }
+    /**
+     * M4 (§P2.1/§P2.7 — the 409-busy MUST): create a queued bake ATOMICALLY only when no other non-dryRun bake is
+     * in flight, so two concurrent keyless POSTs can NEVER both queue (the check-then-act in the submit handler —
+     * findActiveAny() then createBake() as two awaited round-trips — interleaves: both see null-busy, both insert).
+     * `uq_idem` only dedupes non-null idem_keys (a keyless submit is NULL = distinct), and the build lease is taken
+     * at CLAIM not submit, so neither backstops this — the admission itself must be serialized.
+     *
+     * A bare conditional INSERT (`INSERT … SELECT … WHERE NOT EXISTS(...)`) is NOT sufficient ON ITS OWN: under
+     * TiDB's default REPEATABLE READ (and PG's READ COMMITTED) two concurrent autocommit conditional inserts each
+     * evaluate NOT EXISTS against a snapshot that excludes the other's still-uncommitted row (PG takes no
+     * predicate/gap lock), so BOTH can pass and double-admit. The only backstop today is the build lease taken at
+     * CLAIM, so a double-admit degrades the 409-busy/202-attach contract rather than double-building — but the
+     * contract is the point.
+     *
+     * Fix: serialize the busy-check+insert on the per-pool admission sentinel (`image_bake_admit`) with
+     * `SELECT … FOR UPDATE` inside one transaction. The second admitter blocks on the sentinel row lock until the
+     * first commits, then sees the committed in-flight bake and inserts 0 → `created:false`, and the caller
+     * re-reads the active bake (findActiveByArgv for an idempotent attach, else findActiveAny) for the
+     * 202-attach / 409 body. A dryRun bypasses this path entirely (never takes the lease — parallel-safe) and uses
+     * plain createBake.
+     *
+     * 🔴 DIALECT DIVERGENCE (deliberate, both preserved verbatim — the real-DB suites are the oracle):
+     *   - TiDB: `BEGIN PESSIMISTIC` + a separate `SELECT 1 … FOR UPDATE` busy-check, then a plain INSERT. The
+     *     pessimistic txn is REQUIRED: TiDB's snapshot (REPEATABLE READ) txn would evaluate a NOT EXISTS against
+     *     the txn-start snapshot and miss a rival's just-committed row EVEN under the sentinel lock.
+     *   - PG: plain `BEGIN` + one `INSERT … SELECT … WHERE NOT EXISTS(...)`. READ COMMITTED takes a FRESH
+     *     statement snapshot, so the NOT EXISTS run after the sentinel lock is granted already sees the committed
+     *     rival — the conditional insert is atomic enough once serialized.
+     */
     async createBakeIfIdle(input) {
         const bakeId = uuidv7();
         const now = new Date();
@@ -142,8 +238,12 @@ export class SqlImageBake {
         try {
             if (this.db.dialect === "tidb") {
                 await conn.beginPessimistic();
+                // Lock the always-present per-pool admission sentinel so concurrent admissions serialize (defensive INSERT
+                // IGNORE first in case ensureSchema seeded a different poolName).
                 await conn.query("INSERT IGNORE INTO image_bake_admit (pool) VALUES (?)", [this.poolName]);
                 await conn.query("SELECT pool FROM image_bake_admit WHERE pool = ? FOR UPDATE", [this.poolName]);
+                // Busy-check as a CURRENT read (FOR UPDATE) — under the sentinel lock this is a single serialized admitter,
+                // so it sees the prior admitter's committed in-flight bake (no stale-snapshot phantom).
                 const busy = await conn.query("SELECT 1 FROM image_bake WHERE status IN ('queued','running') AND dry_run = 0 LIMIT 1 FOR UPDATE");
                 if (busy.rows.length === 0) {
                     await conn.query(INSERT_BAKE_COLS + "VALUES (?,?,?,?,?,?,?,?,'queued',?,0,?,?,?)", params);
@@ -153,6 +253,7 @@ export class SqlImageBake {
             }
             else {
                 await conn.begin();
+                // Defensive upsert first in case ensureSchema seeded a different poolName; ON CONFLICT keeps it idempotent.
                 await conn.query("INSERT INTO image_bake_admit (pool) VALUES ($1) ON CONFLICT (pool) DO NOTHING", [this.poolName]);
                 await conn.query("SELECT pool FROM image_bake_admit WHERE pool = $1 FOR UPDATE", [this.poolName]);
                 const res = await conn.query(INSERT_BAKE_COLS +
@@ -167,12 +268,15 @@ export class SqlImageBake {
                 await conn.rollback();
             }
             catch {
+                /* ignore */
             }
             throw err;
         }
         finally {
             conn.release();
         }
+        // 0 rows inserted ⇒ a non-dryRun bake is already in flight (the busy-check/NOT EXISTS matched under the
+        // sentinel lock) → busy.
         if (!inserted)
             return { created: false, bake: null };
         const bake = await this.getBake(bakeId);
@@ -188,28 +292,55 @@ export class SqlImageBake {
         const { rows } = await this.db.query(this.q(`SELECT ${SELECT_COLS} FROM image_bake WHERE idem_key = ? LIMIT 1`, `SELECT ${SELECT_COLS} FROM image_bake WHERE idem_key = $1 LIMIT 1`), [idemKey]);
         return rows[0] ? mapRow(rows[0]) : null;
     }
+    /**
+     * Find an in-flight (queued/running) bake with the identical normalized argv — so a re-submit WITHOUT an
+     * idempotency key still returns the live bake rather than starting a duplicate build (P2.1 "an in-flight
+     * identical-input bake returns the EXISTING row"). argv is the canonical normalized vector, so a JSON
+     * equality is the dedupe key. Newest first (the live one).
+     */
     async findActiveByArgv(argv) {
         const { rows } = await this.db.query(this.q(`SELECT ${SELECT_COLS} FROM image_bake WHERE status IN ('queued','running') AND argv = CAST(? AS JSON) ` +
             "ORDER BY created_at DESC LIMIT 1", `SELECT ${SELECT_COLS} FROM image_bake WHERE status IN ('queued','running') AND argv = $1::jsonb ` +
             "ORDER BY created_at DESC LIMIT 1"), [JSON.stringify(argv)]);
         return rows[0] ? mapRow(rows[0]) : null;
     }
+    /**
+     * The OLDEST in-flight (queued/running) NON-dry-run bake — the single-flight at-submit guard (P2.7). Concurrency
+     * is 1 (one docker daemon), so a new submit while ANY non-dry-run bake is in flight is `409 busy` UNLESS it is
+     * the identical-argv one (then the caller attaches to it, idempotent). dryRun bakes never take the lease, so they
+     * are excluded here. Oldest first = the one that holds/will-hold the lease (the build the UI should attach to).
+     */
     async findActiveAny() {
         const { rows } = await this.db.query(`SELECT ${SELECT_COLS} FROM image_bake WHERE status IN ('queued','running') AND dry_run = 0 ` +
             "ORDER BY created_at ASC LIMIT 1", []);
         return rows[0] ? mapRow(rows[0]) : null;
     }
+    /**
+     * The OLDEST queued bake id — the runner's long-poll claim target (P2.12). dryRun bakes never take the lease, so
+     * they are still discoverable here (the runner resolves them with no docker), but ordering oldest-first gives a
+     * stable FIFO. Returns null when the queue is empty. The actual claim is a CAS (`claimBake`), so two runners
+     * racing this both see the id but only one wins the conditional UPDATE — no double-build.
+     */
     async findNextQueuedId() {
         const { rows } = await this.db.query("SELECT bake_id FROM image_bake WHERE status = 'queued' ORDER BY created_at ASC LIMIT 1", []);
         return rows[0] ? String(rows[0].bake_id) : null;
     }
+    /**
+     * Single-flight CLAIM (P2.7) — the runner leases the next queued bake. Two CASes in one transaction:
+     *   1. flip the bake row `queued → running` (conditional UPDATE `WHERE status='queued'`, 1 row affected wins);
+     *   2. take the single-row `image_bake_lease` for the pool (INSERT, or steal an EXPIRED lease via CAS).
+     * Only the runner that wins BOTH gets the bake; a loser (someone else already claimed, or the lease is held by
+     * a live build) gets null. Mints + stores the per-bake `ingest_secret` (so a stale/rogue runner can't inject
+     * frames into another bake) and the initial `lease_until`. Returns the claimed row (with the secret) or null.
+     */
     async claimBake(bakeId, runnerId, leaseMs) {
         const conn = await this.db.connect();
         try {
             await conn.begin();
             const now = new Date();
             const leaseUntil = new Date(now.getTime() + leaseMs);
-            const ingestSecret = randomBytes(24).toString("hex");
+            const ingestSecret = randomBytes(24).toString("hex"); // 48 hex chars ≤ VARCHAR(64)
+            // (1) claim the bake row: only a still-queued row can be claimed (single-flight on the row).
             const bakeRes = await conn.query(this.q("UPDATE image_bake SET status='running', state='PENDING', runner_id=?, ingest_secret=?, " +
                 "lease_until=?, updated_at=? WHERE bake_id=? AND status='queued'", "UPDATE image_bake SET status='running', state='PENDING', runner_id=$1, ingest_secret=$2, " +
                 "lease_until=$3, updated_at=$4 WHERE bake_id=$5 AND status='queued'"), [runnerId, ingestSecret, leaseUntil, now, bakeId]);
@@ -217,11 +348,24 @@ export class SqlImageBake {
                 await conn.rollback();
                 return null;
             }
+            // L1 (§P2.7): a dryRun is RESOLVE-ONLY (no docker) and MUST be parallel-safe — it NEVER takes the build lease.
+            // Claim the row alone (the row CAS above already single-flights it) and skip the pool-lease INSERT/steal CAS,
+            // so a dryRun can be claimed/resolved while a real build holds the lease (matching P2.1/P2.7/P2.14). The lease
+            // release in setTerminal/reapStaleBakes is a harmless no-op for a row that never took the lease. (Read dry_run
+            // on the same row we just claimed.)
             const dry = await conn.query(this.q("SELECT dry_run FROM image_bake WHERE bake_id=?", "SELECT dry_run FROM image_bake WHERE bake_id=$1"), [bakeId]);
             if (Boolean(dry.rows[0]?.dry_run)) {
                 await conn.commit();
                 return (await this.getBake(bakeId)) ?? null;
             }
+            // (2) take the pool lease (single-flight on the build host). 🔴 TiDB rejects a correlated sub-query that
+            // references the INSERT target inside ON DUPLICATE KEY UPDATE ("Can't find column …" — caught by the live
+            // bake, NOT the fake-pool unit test which never executes the SQL). So steal at APP-LEVEL: read the current
+            // lease, then INSERT (no holder) or a CAS-UPDATE (holder's lease EXPIRED **and** its bake no longer running).
+            // 🔴 H4(a): an `expires_at < now` lease whose holder is still `running` is an expired-but-LIVE build (a
+            // heartbeat gap inside the reap window) — stealing it would run TWO builds on one docker daemon, so the steal
+            // is gated on the holder being non-running (steal-window == reap-window; a vanished holder is also stealable).
+            // The CAS on (pool,bake_id,expires_at) makes the steal atomic against a concurrent refresh.
             const leaseSel = await conn.query(this.q("SELECT bake_id, expires_at FROM image_bake_lease WHERE pool=?", "SELECT bake_id, expires_at FROM image_bake_lease WHERE pool=$1"), [this.poolName]);
             const cur = leaseSel.rows[0];
             if (!cur) {
@@ -231,7 +375,7 @@ export class SqlImageBake {
                 catch (err) {
                     if (isDupKey(this.db.dialect, err)) {
                         await conn.rollback();
-                        return null;
+                        return null; // a concurrent claim inserted the lease first — we lose.
                     }
                     throw err;
                 }
@@ -239,21 +383,22 @@ export class SqlImageBake {
             else {
                 if (new Date(cur.expires_at).getTime() >= now.getTime()) {
                     await conn.rollback();
-                    return null;
+                    return null; // the lease is live (unexpired) — we lose.
                 }
                 const holderId = String(cur.bake_id ?? "");
                 const holder = await conn.query(this.q("SELECT status FROM image_bake WHERE bake_id=?", "SELECT status FROM image_bake WHERE bake_id=$1"), [holderId]);
                 const holderStatus = String(holder.rows[0]?.status ?? "");
                 if (holderStatus === "queued" || holderStatus === "running") {
                     await conn.rollback();
-                    return null;
+                    return null; // expired-but-LIVE build — never steal (would double-bake on one daemon).
                 }
                 const stealRes = await conn.query(this.q("UPDATE image_bake_lease SET bake_id=?, acquired_at=?, expires_at=? WHERE pool=? AND bake_id=? AND expires_at=?", "UPDATE image_bake_lease SET bake_id=$1, acquired_at=$2, expires_at=$3 WHERE pool=$4 AND bake_id=$5 AND expires_at=$6"), [bakeId, now, leaseUntil, this.poolName, holderId, cur.expires_at]);
                 if (stealRes.affected === 0) {
                     await conn.rollback();
-                    return null;
+                    return null; // a concurrent claim refreshed/stole the lease first — we lose.
                 }
             }
+            // Double-check the lease row actually points at US (defends a same-instant race) before committing the claim.
             const check = await conn.query(this.q("SELECT bake_id FROM image_bake_lease WHERE pool=?", "SELECT bake_id FROM image_bake_lease WHERE pool=$1"), [this.poolName]);
             if (String(check.rows[0]?.bake_id ?? "") !== bakeId) {
                 await conn.rollback();
@@ -267,6 +412,7 @@ export class SqlImageBake {
                 await conn.rollback();
             }
             catch {
+                /* ignore */
             }
             throw err;
         }
@@ -274,11 +420,31 @@ export class SqlImageBake {
             conn.release();
         }
     }
+    /**
+     * Append one event. image-api is the SOLE ++seq writer: `seq = maxSeq(bakeId)+1`. The `(bakeId,line_ord)`
+     * UNIQUE is the at-least-once ingest dedupe (P2.10) — a runner re-sending a line it already acked races to
+     * INSERT and the loser is a NO-OP (the frame is already stored at its seq). Returns the seq written, or null
+     * when the line was a duplicate (already stored). A null `lineOrd` (image-api-synthesized frame:
+     * register/done/heartbeat-derived) never collides on the line-unique (NULLs are distinct in a UNIQUE index).
+     *
+     * seq allocation + the INSERT are NOT one atomic statement, so two concurrent appends could pick the same
+     * seq+1; the (bakeId,seq) PK then rejects the loser with a dup-key. M2: that PK collision is DISTINGUISHED from
+     * a benign line re-send (by the dup-key attribution channel) and RETRIED in a bounded loop with a fresh
+     * maxSeq+1 — never silently swallowed (which would drop a frame, incl. the terminal `done`, at a clean HTTP
+     * 200). A line dup is the at-least-once re-send no-op (returns null). The runner also serializes its per-bake
+     * pump (runner.ts), so the same-seq race is the rare burst case, not the norm.
+     */
     async appendEvent(bakeId, kind, data, opts = {}) {
         const lineOrd = opts.lineOrd ?? null;
         if (lineOrd !== null && (await this.lineOrdExists(bakeId, lineOrd)))
-            return null;
+            return null; // fast dedupe pre-check
+        // PG-only: codex R14 — a `done` frame carrying a NUL in its error text would raise 22P05 and be LOST FOREVER
+        // (the terminal flip already cleared the ingest secret, so it cannot be retried). TiDB stores JSON verbatim.
         const payload = data == null ? null : this.db.dialect === "tidb" ? JSON.stringify(data) : pgSafeJsonStringify(data);
+        // The PK race is a thundering-herd: K concurrent writers all read the same maxSeq, ONE wins the (bake_id,seq)
+        // INSERT, the rest re-read and retry — so the unluckiest writer can lose up to ~K races in a row. A small fixed
+        // cap (6) under-serves a realistic ingest burst and would THROW a frame that is merely contended, not lost.
+        // Use a generous cap plus jittered backoff so the herd disperses instead of lock-stepping onto the same seq.
         for (let attempt = 0; attempt < 50; attempt += 1) {
             const seq = (await this.maxSeq(bakeId)) + 1;
             try {
@@ -289,8 +455,12 @@ export class SqlImageBake {
                 if (!isDupKey(this.db.dialect, err))
                     throw err;
                 const which = dupKeyName(this.db.dialect, err);
+                // the line-unique lost the race (the line was concurrently stored at its own seq) → a benign at-least-once
+                // duplicate, NOT an error and NOT a frame loss. A null lineOrd CANNOT collide on the line-unique.
                 if (which === "uq_line" && lineOrd !== null)
                     return null;
+                // PRIMARY/(bake_id,seq) → a real same-seq race; re-read maxSeq and retry (do NOT swallow — that would
+                // silently drop this frame). `other` (an unnamed dup driver) is treated conservatively as retryable.
                 await new Promise((r) => setTimeout(r, Math.floor(Math.random() * 5)));
             }
         }
@@ -300,16 +470,19 @@ export class SqlImageBake {
         const { rows } = await this.db.query(this.q("SELECT 1 FROM image_bake_event WHERE bake_id = ? AND line_ord = ? LIMIT 1", "SELECT 1 FROM image_bake_event WHERE bake_id = $1 AND line_ord = $2 LIMIT 1"), [bakeId, lineOrd]);
         return rows.length > 0;
     }
+    /** Highest event seq for a bake (0 if none) — the ++seq allocator + the resume cursor head. */
     async maxSeq(bakeId) {
         const { rows } = await this.db.query(this.q("SELECT MAX(seq) AS m FROM image_bake_event WHERE bake_id = ?", "SELECT MAX(seq) AS m FROM image_bake_event WHERE bake_id = $1"), [bakeId]);
         const m = rows[0]?.m;
         return m == null ? 0 : Number(m);
     }
+    /** Earliest retained event seq (0 if none) → the SSE 416 boundary (a resume below this was evicted, P2.9). */
     async retainedFrom(bakeId) {
         const { rows } = await this.db.query(this.q("SELECT MIN(seq) AS m FROM image_bake_event WHERE bake_id = ?", "SELECT MIN(seq) AS m FROM image_bake_event WHERE bake_id = $1"), [bakeId]);
         const m = rows[0]?.m;
         return m == null ? 0 : Number(m);
     }
+    /** Events with seq strictly greater than `afterSeq` (0 for the whole stream), ascending. */
     async getEvents(bakeId, afterSeq) {
         const { rows } = await this.db.query(this.q("SELECT seq, line_ord, kind, level, data, ts FROM image_bake_event WHERE bake_id = ? AND seq > ? ORDER BY seq ASC", "SELECT seq, line_ord, kind, level, data, ts FROM image_bake_event WHERE bake_id = $1 AND seq > $2 ORDER BY seq ASC"), [bakeId, afterSeq]);
         return rows.map((r) => ({
@@ -321,12 +494,25 @@ export class SqlImageBake {
             ts: iso(r.ts),
         }));
     }
+    /** Coarse 4-value lifecycle transition (the column the SSE reader polls for terminality). */
     async setStatus(bakeId, status) {
         await this.db.query(this.q("UPDATE image_bake SET status = ?, updated_at = ? WHERE bake_id = ?", "UPDATE image_bake SET status = $1, updated_at = $2 WHERE bake_id = $3"), [status, new Date(), bakeId]);
     }
+    /** Denormalize build.sh's 8-value `state` for the UI progress bar (NEVER drives terminality, P2.3). */
     async setState(bakeId, state) {
         await this.db.query(this.q("UPDATE image_bake SET state = ?, updated_at = ? WHERE bake_id = ?", "UPDATE image_bake SET state = $1, updated_at = $2 WHERE bake_id = $3"), [state, new Date(), bakeId]);
     }
+    /**
+     * Terminal write (P2.10 step 4): flip the coarse `status` + persist all the terminal facts (digest/repo/ref/
+     * indexId/exitCode/error/errorCode/state/manifestSha/tag) the `done` frame and the poll row carry, AND release
+     * the pool lease in one transaction (a separate-statement release that failed would wedge the build host).
+     * Idempotent terminal write: only flips a NON-terminal row (`WHERE status IN ('queued','running')`) so a
+     * re-delivered terminal can't clobber the first outcome. Returns the UPDATE's affected count — 1 = THIS call won
+     * the queued/running→terminal transition; 0 = a terminal already exists (M3: the caller then SKIPS appending a
+     * contradictory second terminal `done` event, so at most one terminal `done` per bake matches the coarse row).
+     * 🔴 H3: null `ingest_secret` on the terminal flip so a terminal row can NEVER re-authenticate an ingest
+     * (a lagging/duplicate runner that still holds the secret can't inject frames into a settled bake).
+     */
     async setTerminal(bakeId, t) {
         let affectedRows = 0;
         await this.tx(async (conn) => {
@@ -338,6 +524,7 @@ export class SqlImageBake {
         });
         return affectedRows;
     }
+    /** TiDB stores the terminal facts VERBATIM (no protocol-byte class to defend against). */
     terminalParamsTidb(bakeId, t) {
         return [
             t.status,
@@ -355,6 +542,10 @@ export class SqlImageBake {
             bakeId,
         ];
     }
+    /** PG-ONLY protocol-byte handling. R20/R21:身份位(digest/manifestSha/repo/ref)带不可存字节=帧无效——
+     *  **单一谓词**统管状态折叠与全部身份绑位(R21:只查两位会放 dirty repo/ref 的假 COMPLETE 过——终态单赢,
+     *  假成功不可逆)。事务必须提交(lease 释放/secret 清理=单飞池活性底线)。codex R13/R17-H2:NUL 错误文案
+     *  或脏 tag 若让终态事务回滚,lease 保持 = bake 永占单飞池,故文本位走 sanitize 而非拒绝。 */
     terminalParamsPg(bakeId, t) {
         const invalidIdentity = (t.digest != null && pgHasUnstorable(t.digest)) ||
             (t.manifestSha != null && pgHasUnstorable(t.manifestSha)) ||
@@ -376,41 +567,79 @@ export class SqlImageBake {
             bakeId,
         ];
     }
+    /** Set the index_id once auto-register succeeds (P2.10 — kept distinct from the terminal flip so the `done`
+     *  frame can carry indexId even when the terminal write retries). codex R24:non-terminal 门——并发 done
+     *  竞态下(本请求悬在 registerBuilding 时另一 done 已赢 setTerminal)绝不把 indexId 挂回终态行(R23 折叠
+     *  的 FAILED/null 身份行会被复写成「null 身份却带 index 绑定」的矛盾形)。返回是否真绑定。 */
     async setIndexId(bakeId, indexId) {
         const res = await this.db.query(this.q("UPDATE image_bake SET index_id = ?, updated_at = ? WHERE bake_id = ? AND status IN ('queued','running')", "UPDATE image_bake SET index_id = $1, updated_at = $2 WHERE bake_id = $3 AND status IN ('queued','running')"), [indexId, new Date(), bakeId]);
         return res.affected >= 1;
     }
+    /** Heartbeat the lease forward (P2.7): the runner pushes `lease_until` (+ the lease row's `expires_at`) while
+     *  its build child runs, so the reaper doesn't steal a LIVE build's lease. CAS on the runner owning the row +
+     *  the bake still running. Returns whether it refreshed (false ⇒ lease lost/stolen — the runner should abort). */
     async heartbeatLease(bakeId, runnerId, leaseMs) {
         const now = new Date();
         const leaseUntil = new Date(now.getTime() + leaseMs);
         const res = await this.db.query(this.q("UPDATE image_bake SET lease_until = ?, updated_at = ? WHERE bake_id = ? AND runner_id = ? AND status = 'running'", "UPDATE image_bake SET lease_until = $1, updated_at = $2 WHERE bake_id = $3 AND runner_id = $4 AND status = 'running'"), [leaseUntil, now, bakeId, runnerId]);
         if (res.affected < 1)
             return false;
+        // L1: a dryRun never took the pool lease (claimBake skips it) — so it has NO `image_bake_lease` row to refresh.
+        // The bake-row refresh above is its only heartbeat; skip the pool-lease CAS so a healthy dryRun isn't aborted
+        // by an (always-zero) pool-lease no-op.
         const dry = await this.db.query(this.q("SELECT dry_run FROM image_bake WHERE bake_id = ?", "SELECT dry_run FROM image_bake WHERE bake_id = $1"), [bakeId]);
         if (Boolean(dry.rows[0]?.dry_run))
             return true;
+        // 🔴 H4(b): the pool-lease refresh is a REAL CAS — `WHERE pool=? AND bake_id=?` only matches while WE still
+        // own the lease row. If it was stolen to another bake, 0 rows affected → return false so the displaced runner
+        // sees leaseValid:false and aborts + kills its child (runner.ts). Without this guard the no-op UPDATE was
+        // silently treated as success and a displaced runner kept building (two builds, one daemon).
         const leaseRes = await this.db.query(this.q("UPDATE image_bake_lease SET expires_at = ? WHERE pool = ? AND bake_id = ?", "UPDATE image_bake_lease SET expires_at = $1 WHERE pool = $2 AND bake_id = $3"), [leaseUntil, this.poolName, bakeId]);
         return leaseRes.affected >= 1;
     }
+    /** Request cooperative cancel (P2.11) — durable + cross-replica; the runner's heartbeat tick polls it and kills
+     *  the build.sh process group. Only flags a non-terminal row (terminal → 0 affected = no-op). Returns whether a
+     *  live bake was flagged (false ⇒ already terminal → the caller answers a no-op 202). */
     async requestCancel(bakeId) {
         const res = await this.db.query(this.q("UPDATE image_bake SET cancel_requested = 1, updated_at = ? WHERE bake_id = ? AND status IN ('queued','running')", "UPDATE image_bake SET cancel_requested = 1, updated_at = $1 WHERE bake_id = $2 AND status IN ('queued','running')"), [new Date(), bakeId]);
         return res.affected > 0;
     }
+    /** Whether a cancel was requested (polled by the runner). */
     async isCancelRequested(bakeId) {
         const { rows } = await this.db.query(this.q("SELECT cancel_requested FROM image_bake WHERE bake_id = ?", "SELECT cancel_requested FROM image_bake WHERE bake_id = $1"), [bakeId]);
         return Boolean(rows[0]?.cancel_requested);
     }
+    /**
+     * Reaper twin of TiDBRunStore.reapStale (P2.7/§P2.6): fail any `running` bake whose lease is STALE (a crashed
+     * runner stopped heartbeating), append a synthetic terminal `done{failed}` so SSE readers SETTLE (never hang),
+     * and force-release the pool lease. `olderThanMs` must exceed >2 lease-heartbeat intervals (≈3× the heartbeat)
+     * so a healthy slow build is not wrongly reaped. Returns the count reaped.
+     *
+     * M3: flip the row terminal FIRST (the CAS on `status='running'`), and append the synthetic `done{failed}` ONLY
+     * when the flip WON (1 row affected). A victim that recovered + COMPLETEd between the SELECT and the flip
+     * no-ops the CAS, so we leak NO contradictory `done{failed}` into its settled SSE log. A reader that polled the
+     * still-running row in the tiny pre-flip gap simply re-polls (streamSseLog re-fetches) and settles on the
+     * eventual terminal — the winner's `done` — rather than a spurious one.
+     */
     async reapStaleBakes(olderThanMs) {
         const cutoff = new Date(Date.now() - olderThanMs);
         const victims = await this.db.query(this.q("SELECT bake_id FROM image_bake WHERE status = 'running' AND " + "(lease_until IS NULL OR lease_until < ?) AND updated_at < ?", "SELECT bake_id FROM image_bake WHERE status = 'running' AND " + "(lease_until IS NULL OR lease_until < $1) AND updated_at < $2"), [cutoff, cutoff]);
         let reaped = 0;
         for (const v of victims.rows) {
             const bakeId = String(v.bake_id);
+            // CAS the flip on still-running (a runner that recovered between the SELECT and here keeps its row).
+            // 🔴 H3: also null `ingest_secret` so the reaped (terminal) row can never re-authenticate an ingest — a
+            // lost-but-lagging runner that still holds the secret cannot inject frames into the dead bake's stream.
+            // codex R25: also null `index_id` atomically — a victim whose ingest died AFTER setIndexId bound but
+            // BEFORE setTerminal would otherwise keep a stale binding that contradicts the synthetic done below
+            // (indexId:null); the orphan `building` index row is lifecycle-tolerated (never published/selectable).
             const res = await this.db.query(this.q("UPDATE image_bake SET status='failed', state='FAILED', error='bake-runner lost (lease expired)', " +
                 "ingest_secret=NULL, index_id=NULL, updated_at=? WHERE bake_id=? AND status='running'", "UPDATE image_bake SET status='failed', state='FAILED', error='bake-runner lost (lease expired)', " +
                 "ingest_secret=NULL, index_id=NULL, updated_at=$1 WHERE bake_id=$2 AND status='running'"), [new Date(), bakeId]);
             if (res.affected === 1) {
                 reaped += 1;
+                // M3: we WON the flip — only now append the synthetic terminal so a reader settles on a `done` that matches
+                // the coarse row. A recovered+COMPLETEd victim never reaches here (the CAS no-op'd), so no contradiction.
                 try {
                     await this.appendEvent(bakeId, "done", {
                         status: "FAILED",
@@ -424,12 +653,14 @@ export class SqlImageBake {
                     });
                 }
                 catch {
+                    /* best-effort — the row is already terminal; a reader sees status!=running and re-fetches. */
                 }
                 await this.db.query(this.q("DELETE FROM image_bake_lease WHERE pool = ? AND bake_id = ?", "DELETE FROM image_bake_lease WHERE pool = $1 AND bake_id = $2"), [this.poolName, bakeId]);
             }
         }
         return reaped;
     }
+    /** Run statements atomically; rolls back on failure (mirrors TiDBRunStore.tx). */
     async tx(fn) {
         const conn = await this.db.connect();
         try {
@@ -442,6 +673,7 @@ export class SqlImageBake {
                 await conn.rollback();
             }
             catch {
+                /* ignore */
             }
             throw err;
         }
@@ -450,11 +682,13 @@ export class SqlImageBake {
         }
     }
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class TiDBImageBake extends SqlImageBake {
     constructor(pool, poolName = "standard") {
         super(mysqlDriver(pool), poolName);
     }
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export class PgImageBake extends SqlImageBake {
     constructor(pool, poolName = "standard") {
         super(pgDriver(pool), poolName);

package/dist/plugins/image-index-sql.d.ts

@@ -4,29 +4,75 @@ import { type ImageStatus, type ImageIndexEntry, type ImageIndexUpsert, type Ima
 import { type SqlDriver } from "./sql-driver.js";
 export type { ImageNestedBuildMode, ImageCapabilities, ImagePodContract, ImageStatus, ImageVisibility, ImageIndexEntry, ImageIndexUpsert, ImageViewer, ImageListFilter, ImageRow, } from "./store-contracts.js";
 export { mapImageRow as mapRow } from "./store-contracts.js";
+/** PG translation of the `sandbox_image_index` DDL in tidb-pool.ts (JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3),
+ *  TINYINT(1)→SMALLINT(布尔列 PG 映射归一,clay 批 2026-07-26 —— 两方言读回同为 number,写入 0/1,
+ *  读侧 `!!` 保持,出口 JS 类型不变), inline UNIQUE KEY/KEY → separate CREATE UNIQUE INDEX / CREATE INDEX). */
 export declare const PG_IMAGE_INDEX_SCHEMA: string[];
+/** Idempotent self-contained schema apply (for the integration test; central aggregation is done separately). */
 export declare function ensureSchema(pool: PgPool | PoolClient): Promise<void>;
+/** Dual-dialect INDEX store. See the file header for the dialect-delta ledger. */
 export declare class SqlImageIndex {
     protected readonly db: SqlDriver;
     constructor(db: SqlDriver);
+    /** Pick the dialect's SQL text. Both statements stay written out at the call site ON PURPOSE. */
     private q;
+    /** Stable index id = sha256(repo@digest) — identity is the digest, not the mutable tag. */
     static idFor(repo: string, digest: string): string;
+    /** Register or update an index row (idempotent on repo+digest). Returns the row id. */
     upsert(e: ImageIndexUpsert): Promise<string>;
+    /**
+     * STATUS-MONOTONIC register (IMAGE-API-DESIGN.md §P2.10 MUST-FIX) — the auto-register path the bake runner uses.
+     *
+     * `upsert` does an UNCONDITIONAL upsert: a re-ingested `done` (at-least-once from the runner) or a P2 bake of
+     * a digest P3 already PROMOTED would flip a live `published` row back to `building`, and `latestPublished`
+     * (`WHERE status='published'`) then DE-PUBLISHES a live, in-use image → sandbox-create 404s. This guarded path
+     * NEVER downgrades a `published` row: on a fresh row it inserts (`status:'building'` by default); on an
+     * existing row it updates the manifest projection + bumps `updated_at` but writes `status` only when the row
+     * isn't already `published` — a late/duplicate `done` for an already-promoted digest is a no-op on the
+     * lifecycle, never a regression. Returns the row id.
+     *
+     * Distinct from the unconditional `upsert` (kept for the seed + the operator `/v1/images/register` path); this
+     * is the bake auto-register's ONLY write into the index. Default status is `building` (P2 registers
+     * node-local/quarantine `building` artifacts; P3's verify gate is what flips `building → published`).
+     *
+     * The `IF(...published...)` (TiDB) / `CASE WHEN...published...` (PG) guards are the monotonic de-publish
+     * defense: once a row is `published` and live, a re-register must NOT downgrade `status` NOR flip the
+     * columns `latestPublished` filters on. wq64gmm5e: guarding only `status` left `visibility`/`tenant_id`
+     * (and `signed`) overwritable, so a re-register with visibility=private/tenant or a different tenant_id
+     * silently dropped a live row out of every viewer's `latestPublished` — an effective de-publish. ALL FOUR
+     * (status/visibility/tenant_id/signed) are gated identically in BOTH dialects; non-published rows still
+     * take the freshest projection.
+     */
     registerBuilding(e: ImageIndexUpsert): Promise<string>;
     getById(id: string): Promise<ImageIndexEntry | null>;
+    /** By immutable digest — what a running sandbox was built from. */
     getByDigest(digest: string): Promise<ImageIndexEntry | null>;
+    /** The newest PUBLISHED, viewer-visible digest for a profile — the `select` resolution.
+     *  🔴 genuinely-divergent shape (not just SQL text): TiDB's `visibilityClauseTidb` needs no placeholder
+     *  index (anonymous `?`); PG's `visibilityClausePg` threads a running `$n` index the caller continues
+     *  from. Also the null-safe ORDER BY trick differs ((build_date IS NULL) vs NULLS LAST) — same semantics. */
     latestPublished(profile: string, viewer: ImageViewer): Promise<ImageIndexEntry | null>;
+    /**
+     * Paginated, viewer-scoped catalog query (the UI's list). Keyset cursor on (created_at, id) desc.
+     * 🔴 genuinely-divergent shape: the PG arm threads an explicit `$n` index through every optional predicate
+     * (node-pg has no anonymous placeholder); the TiDB arm just appends `?` in call order. Kept as two full
+     * branches rather than a shared placeholder-numbering helper (sql-driver.ts STEP 3/4) — a reviewer sees each
+     * dialect's real query shape, not a generated abstraction over it.
+     */
     list(filter: ImageListFilter): Promise<{
         entries: ImageIndexEntry[];
         nextCursor: string | null;
     }>;
+    /** Lifecycle transition (atomic-publish: building→published, or →failed/deprecated). */
     setStatus(id: string, status: ImageStatus, opts?: {
         supersedes?: string | null;
     }): Promise<void>;
 }
+/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export declare class TiDBImageIndex extends SqlImageIndex {
     constructor(pool: MySqlPool);
 }
+/** PostgreSQL binding — historical class name + ctor shape preserved. */
 export declare class PgImageIndex extends SqlImageIndex {
     constructor(pool: PgPool);
 }