@sema-agent/server 7.43.0 → 7.44.0

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

@@ -1,40 +1,3 @@
-/**
- * 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` (#192 A5 归一后两条方言同名 uq_image_bake_event_line)
- *   - `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, pgHasUnstorable } from "./pg-safe-json.js";
@@ -42,12 +5,6 @@ import { parseJsonOr as parseJson, toIso as iso } from "./sql-row-helpers.js";
 import { mysqlDriver, pgDriver, dialectJsonEncoder } from "./sql-driver.js";
 import { mapBakeRow as mapRow, BAKE_SELECT_COLS as SELECT_COLS, } from "./store-contracts.js";
 import { isDupKeyError } from "./sql-errors.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 line UNIQUE is given the explicit name uq_image_bake_event_line 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) COLLATE "C"  NOT NULL,
@@ -100,32 +57,17 @@ 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) COLLATE "C" 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 — the PREDICATE has a single owner (`sql-errors.ts`); only the ATTRIBUTION
- *  (which UNIQUE collided — `dupKeyName` below) is store-specific. A-032 P1-①: the old local form
- *  recognized only mysql2's string `code`, so an error carrying just `errno` fell through. */
 const isDupKey = isDupKeyError;
-/** 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_image_bake_event_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 ?? "");
@@ -144,21 +86,16 @@ 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, 
-    /** The builder pool a lease serializes on (one docker daemon ⇒ one pool today). */
-    poolName = "standard") {
+    constructor(db, 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,
@@ -175,12 +112,6 @@ 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();
@@ -200,35 +131,6 @@ 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();
@@ -238,12 +140,8 @@ 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);
@@ -253,7 +151,6 @@ 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 +
@@ -268,15 +165,12 @@ 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);
@@ -292,55 +186,28 @@ 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"); // 48 hex chars ≤ VARCHAR(64)
-            // (1) claim the bake row: only a still-queued row can be claimed (single-flight on the row).
+            const ingestSecret = randomBytes(24).toString("hex");
             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]);
@@ -348,24 +215,11 @@ 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) {
@@ -375,7 +229,7 @@ export class SqlImageBake {
                 catch (err) {
                     if (isDupKey(this.db.dialect, err)) {
                         await conn.rollback();
-                        return null; // a concurrent claim inserted the lease first — we lose.
+                        return null;
                     }
                     throw err;
                 }
@@ -383,22 +237,21 @@ export class SqlImageBake {
             else {
                 if (new Date(cur.expires_at).getTime() >= now.getTime()) {
                     await conn.rollback();
-                    return null; // the lease is live (unexpired) — we lose.
+                    return null;
                 }
                 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; // expired-but-LIVE build — never steal (would double-bake on one daemon).
+                    return null;
                 }
                 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; // a concurrent claim refreshed/stole the lease first — we lose.
+                    return null;
                 }
             }
-            // 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();
@@ -412,7 +265,6 @@ export class SqlImageBake {
                 await conn.rollback();
             }
             catch {
-                /* ignore */
             }
             throw err;
         }
@@ -420,31 +272,11 @@ 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; // 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.
+            return null;
         const payload = data == null ? null : dialectJsonEncoder(this.db.dialect)(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 {
@@ -455,12 +287,8 @@ 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)));
             }
         }
@@ -470,19 +298,16 @@ 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) => ({
@@ -494,32 +319,12 @@ export class SqlImageBake {
             ts: iso(r.ts),
         }));
     }
-    /**
-     * Coarse 4-value lifecycle transition (the column the SSE reader polls for terminality).
-     *
-     * @deprecated #193 车7(staleness-sweep P2-12):**test-only**——生产零调用。生产唯一写入路径是
-     * `ingestBakeLine`(routes/images.ts),它只经 `setState`(denormalize)与 `setTerminal` 驱动状态;
-     * 本方法是绕开「status 只由 state/done 驱动」不变量的唯一直接写口,**禁止新增生产调用**。留而不删
-     * 的唯一理由=三个集成测试用它铸中间态,整删随该套件下次翻新一并做。
-     */
     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) => {
@@ -531,7 +336,6 @@ export class SqlImageBake {
         });
         return affectedRows;
     }
-    /** TiDB stores the terminal facts VERBATIM (no protocol-byte class to defend against). */
     terminalParamsTidb(bakeId, t) {
         return [
             t.status,
@@ -549,10 +353,6 @@ 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)) ||
@@ -574,79 +374,41 @@ 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",
@@ -660,14 +422,12 @@ 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 {
@@ -680,7 +440,6 @@ export class SqlImageBake {
                 await conn.rollback();
             }
             catch {
-                /* ignore */
             }
             throw err;
         }
@@ -689,13 +448,11 @@ 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);