@sema-agent/server 1.323.0 → 2.0.0

package/dist/plugins/store-backend.js

@@ -1,3 +1,11 @@
+/**
+ * Durable-store BACKEND seam (clay 2026-06-21 PG migration). One place that, given `config.dbBackend`, builds the
+ * SQL pool (TiDB/MySQL via mysql2 OR PostgreSQL via pg) and constructs the right store TWIN for every durable
+ * subsystem. main.ts wires through this instead of `new TiDB*(pool)` so `DB_BACKEND=pg` boots the whole service on
+ * PG with zero call-site churn. The twins are interchangeable behaviourally (one shared real-DB integration suite
+ * keeps them in lock-step); the unions below exist only because TS private fields make the concrete classes
+ * nominally distinct (run/approval/imageIndex/imageBake have no core interface — the rest implement one).
+ */
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { FileStorageBackend, FileSessionRepo, DEFAULT_SNAPSHOT_BOUNDS } from "@sema-agent/core";
@@ -44,8 +52,15 @@ import { TiDBRateLimiter } from "./tidb-rate-limiter.js";
 import { PgRateLimiter } from "./pg-rate-limiter.js";
 import { TiDBSessionStore } from "./tidb-session-store.js";
 import { PgSessionStore } from "./pg-session-storage.js";
+/** Build the snapshot-BLOB object-store backend from config, or undefined to fall back to the SqlBlobBackend default.
+ *  When `config.snapshotBlobStore` (MINIO_* env) is set, the E19/2c file-snapshot stores route ONLY the blob BYTES to
+ *  MinIO; the MANIFEST stays in SQL (the transcript hot read never touches MinIO). The MinioBlobBackend is given the
+ *  SAME pool+dialect so it keeps the bytes-NULL `snapshot_blob` INDEX in SQL (the orphan/grace reference-tracking +
+ *  presence checks read it — see blob-backend.ts). Shared by the tidb + pg backends. */
 function snapshotBlobBackend(config, dialect, pool) {
     const s = config.snapshotBlobStore;
+    // (a): no MinIO ⇒ construct the SQL default EXPLICITLY so the per-blob cap (env override or the tidb
+    // packet-wall default) rides along — the stores' internal `?? new SqlBlobBackend(...)` fallback would lose it.
     if (!s)
         return new SqlBlobBackend(dialect, pool, config.snapshotBlobSqlMaxBytes);
     return new MinioBlobBackend({
@@ -58,6 +73,11 @@ function snapshotBlobBackend(config, dialect, pool) {
         ...(s.presignTtlSec ? { presignTtlSec: s.presignTtlSec } : {}),
     }, { dialect, pool });
 }
+/** (c)(clay 拍 a+c,2026-07-27)云形快照 blob 姿势门——boot 时调用(main.ts),纯函数可单测。
+ *  SQL 后端(mysql|pg)把 blob 字节落 `snapshot_blob` 单行的形已被两役实证撞 mysql-协议包墙
+ *  (D-1 附件 → 对象存储裁定;snapshot_blob >31MiB 同墙):大字节归对象存储。云形缺 MinIO ⇒
+ *  fail-loud(启动了才是假安全);`SNAPSHOT_BLOB_ALLOW_SQL_BYTES=true` = 显式接受 SQL 店 +
+ *  per-blob 帽(单机/测试台形)。local 后端不经此门(file/in-memory 快照店,无 SQL 包墙)。 */
 export function assertCloudSnapshotBlobPosture(kind, config) {
     if (kind === "local" || config.snapshotBlobStore || config.snapshotBlobAllowSql)
         return;
@@ -67,6 +87,10 @@ export function assertCloudSnapshotBlobPosture(kind, config) {
         "same ruling as the D-1 attachment store). Single-box/test rigs may explicitly opt out with " +
         "SNAPSHOT_BLOB_ALLOW_SQL_BYTES=true (a per-blob cap then applies; oversized blobs are rejected 413).");
 }
+/** REWIND_SNAPSHOT_MAX_MB overrides ONLY the byte cap of core's DEFAULT_SNAPSHOT_BOUNDS (raise for
+ *  big monorepos, lower for tight DBs). File-count / ignoreDirs stay core defaults — the knob answers the one
+ *  field the 20G-workspace case needed; more knobs when a case shows up. Exported for tests
+ *  (fractional-MB rounding + partial-merge semantics need a regression lock). */
 export function snapshotBoundsFromConfig(config) {
     const mb = config.rewindSnapshotMaxMb;
     return mb !== undefined ? { ...DEFAULT_SNAPSHOT_BOUNDS, maxBytes: Math.round(mb * 1024 * 1024) } : DEFAULT_SNAPSHOT_BOUNDS;
@@ -88,10 +112,10 @@ class TiDBBackend {
     sessionPolicy() { return new TiDBSessionPolicyStore(this.pool); }
     fileSnapshot() { return new TiDBFileSnapshotStore(this.pool, snapshotBlobBackend(this.config, "tidb", this.pool), snapshotBoundsFromConfig(this.config)); }
     workflowJournal() { return new TiDBWorkflowJournalStore(this.pool); }
-    outcomeSink() { return new TiDBOutcomeLedger(this.pool); }
-    workflowRun() { return new TiDBWorkflowRunStore(this.pool); }
-    completionInbox(onWarn) { return new TiDBWorkflowCompletionInbox(this.pool, onWarn); }
-    notifyJournal() { return new TiDBWorkflowNotifyJournalStore(this.pool); }
+    outcomeSink() { return new TiDBOutcomeLedger(this.pool); } // design/73 §1→§7 bridge (recordCore)
+    workflowRun() { return new TiDBWorkflowRunStore(this.pool); } // P1: cross-replica workflow record
+    completionInbox(onWarn) { return new TiDBWorkflowCompletionInbox(this.pool, onWarn); } // P1: cross-replica push half
+    notifyJournal() { return new TiDBWorkflowNotifyJournalStore(this.pool); } // 1.108: cross-replica at-least-once notify
     checkpoint(logger) { return new TiDBCheckpointStore(this.pool, logger); }
     approval() { return new TiDBApprovalStore(this.pool); }
     toolResult() { return new TiDBToolResultStore(this.pool); }
@@ -103,7 +127,7 @@ class TiDBBackend {
     session() { return new TiDBSessionStore(this.pool); }
     mysqlPool() { return this.pool; }
     pgPool() { return undefined; }
-    async dbNowMs() { const [rows] = await this.pool.query("SELECT ROUND(UNIX_TIMESTAMP(NOW(3))*1000) AS ms"); return Number(rows[0]?.ms); }
+    async dbNowMs() { const [rows] = await this.pool.query("SELECT ROUND(UNIX_TIMESTAMP(NOW(3))*1000) AS ms"); return Number(rows[0]?.ms); } // S10
 }
 class PgBackend {
     pool;
@@ -122,10 +146,10 @@ class PgBackend {
     sessionPolicy() { return new PgSessionPolicyStore(this.pool); }
     fileSnapshot() { return new PgFileSnapshotStore(this.pool, snapshotBlobBackend(this.config, "pg", this.pool), snapshotBoundsFromConfig(this.config)); }
     workflowJournal() { return new PgWorkflowJournalStore(this.pool); }
-    outcomeSink() { return new PgOutcomeLedger(this.pool); }
-    workflowRun() { return new PgWorkflowRunStore(this.pool); }
-    completionInbox(onWarn) { return new PgWorkflowCompletionInbox(this.pool, onWarn); }
-    notifyJournal() { return new PgWorkflowNotifyJournalStore(this.pool); }
+    outcomeSink() { return new PgOutcomeLedger(this.pool); } // design/73 §1→§7 bridge (recordCore)
+    workflowRun() { return new PgWorkflowRunStore(this.pool); } // P1: cross-replica workflow record
+    completionInbox(onWarn) { return new PgWorkflowCompletionInbox(this.pool, onWarn); } // P1: cross-replica push half
+    notifyJournal() { return new PgWorkflowNotifyJournalStore(this.pool); } // 1.108: cross-replica at-least-once notify
     checkpoint(logger) { return new PgCheckpointStore(this.pool, logger); }
     approval() { return new PgApprovalStore(this.pool); }
     toolResult() { return new PgToolResultStore(this.pool); }
@@ -137,8 +161,30 @@ class PgBackend {
     session() { return new PgSessionStore(this.pool); }
     mysqlPool() { return undefined; }
     pgPool() { return this.pool; }
-    async dbNowMs() { const res = await this.pool.query("SELECT ROUND(EXTRACT(EPOCH FROM now())*1000) AS ms"); return Number(res.rows[0]?.ms); }
+    async dbNowMs() { const res = await this.pool.query("SELECT ROUND(EXTRACT(EPOCH FROM now())*1000) AS ms"); return Number(res.rows[0]?.ms); } // S10
 }
+/**
+ * LOCAL backend (clay 2026-06-25 seamless local↔cloud; P0.5 variant-2 + variant-1 file-backed 2026-06-26): a DB-less StoreBackend
+ * so a locally-run HTTP service serves the SAME contract a cloud worker does (runs + trace + sessions + resume;
+ * long-term memory rides the design/138 memory ENGINE, not this backend). Sessions / per-session policy / file snapshots are
+ * FILE-BACKED via core's `FileStorageBackend` over `root`, so a session SURVIVES a process restart and the resume
+ * picker (GET /v1/sessions → LocalSessionStore.listSessions) is restart-visible — the 2c "first local, then sync"
+ * hard prerequisite.
+ *
+ * The session store stays the §0.5 owner-aware {@link LocalSessionStore} wrapper, but over a fresh `FileSessionRepo`
+ * (NOT `fileBackend.sessionStore`, which is core's bare `TtlSessionStore` lacking the §0.5 owner/list/fork/delete
+ * ops); policy/snapshot delegate to the fileBackend's own file stores. The fileBackend takes a coarse boot
+ * `flock` on `root/LOCK` (single-instance per data dir) — `close()` MUST `dispose()` it so a graceful restart can
+ * re-acquire (a stale lock from a dead PID is pruned by core, but graceful restart relies on the release).
+ *
+ * P0.5 variant-1 (clay 2026-06-26): `run()`/`resumeAnchor()` are now FILE-backed too (FileRunStore /
+ * FileResumeAnchorStore over core 1.138.0's crash-safe fs primitives — atomicWriteFile/writeThenLink/AppendLog), so the
+ * runs ledger + trace event log + E18 anchors SURVIVE a process restart, completing variant-2's promised follow-on. The
+ * picker still lists from the session abstraction (variant-2), but a restart now also re-reads run history + resume
+ * anchors. Owner identity is still process-local (single-user acceptable; durable owners = P1). The cloud-only stores
+ * (checkpoint/approval/toolResult/imageIndex/imageBake/breaker/costQuota/rateLimiter) are OMITTED → the consumers'
+ * `backend?.X?.()` gates degrade them exactly like a no-DB env.
+ */
 class LocalBackend {
     kind = "local";
     fileBackend;
@@ -147,17 +193,29 @@ class LocalBackend {
     resumeAnchorStore;
     approvalExemptionStore;
     sendFileLedgerStore;
+    // SVC-2: FILE-backed durable journal (was core's InMemory — a TOC restart silently resolved
+    // resumeFromRunId to an empty journal → full live re-run). Now restart-durable on one box; crash-safe JSONL,
+    // scope-guarded, oversize skip-journal — byte-matched degrade with the SQL twins. Singleton: fds live here.
     workflowJournalStore;
+    /** design/73 §1 — owner-only JSONL outcome-fact sink (stateless append; no fd held). */
     outcomeSinkInst;
     constructor(root, config) {
+        // The fileBackend ctor mkdirs `root` + takes the boot flock — a SECOND instance over the same dir FAILS FAST.
+        // Re-throw with a clear operator message (the raw core error is "another instance owns this data dir").
         try {
-            this.fileBackend = new FileStorageBackend({ root, ...(config.rewindSnapshotMaxMb !== undefined ? { snapshotBounds: { maxBytes: Math.round(config.rewindSnapshotMaxMb * 1024 * 1024) } } : {}) });
+            this.fileBackend = new FileStorageBackend({ root, ...(config.rewindSnapshotMaxMb !== undefined ? { snapshotBounds: { maxBytes: Math.round(config.rewindSnapshotMaxMb * 1024 * 1024) } } : {}) }); // REWIND_SNAPSHOT_MAX_MB
         }
         catch (e) {
             throw new Error(`DB_BACKEND=local cannot open data dir ${root}: ${e instanceof Error ? e.message : String(e)} ` +
                 "(another HTTP service / run-local instance may own it; stop it first or set LOCAL_DATA_ROOT to a free dir)");
         }
+        // §0.5 owner-aware wrapper over a fresh FileSessionRepo on the SAME root (NOT fileBackend.sessionStore — that's
+        // the bare TtlSessionStore without the §0.5 owner/list/fork/delete ops). Both touch root/sessions/*.jsonl.
+        // Pass `root` as the lastActivity sidecar dir so the /resume picker's newest-first order survives a restart (TOC #10):
+        // without it the in-memory recency map starts empty on boot and every session degrades to createdAt ordering.
         this.sessionStore = new LocalSessionStore(new FileSessionRepo(this.fileBackend.root), this.fileBackend.root);
+        // P0.5 variant-1: file-backed runs ledger + E18 anchors over the SAME canonical root (under root/runs + root/
+        // resume-anchors). Hydrate the in-memory index from disk on construction → restart-visible.
         this.runStore = new FileRunStore(this.fileBackend.root);
         this.resumeAnchorStore = new FileResumeAnchorStore(this.fileBackend.root);
         this.approvalExemptionStore = new FileApprovalExemptionStore(this.fileBackend.root);
@@ -165,21 +223,23 @@ class LocalBackend {
         this.workflowJournalStore = new FileWorkflowJournalStore(this.fileBackend.root);
         this.outcomeSinkInst = new FileOutcomeSink(this.fileBackend.root);
     }
-    async ensureSchema() { }
+    async ensureSchema() { } // FileStorageBackend ctor already created root + the boot lock → always "reachable"
     async close() {
-        await this.sessionStore.dispose();
-        this.runStore.dispose();
-        this.resumeAnchorStore.dispose();
-        this.approvalExemptionStore.dispose();
-        this.sendFileLedgerStore.dispose();
-        this.workflowJournalStore.dispose();
-        this.checkpointStoreInst?.close();
-        await this.fileBackend.dispose();
+        await this.sessionStore.dispose(); // AWAIT the final lastActivity flush (bug C) BEFORE releasing the dir lock below
+        this.runStore.dispose(); // release the per-run event-log fds so a graceful restart can re-open the data dir
+        this.resumeAnchorStore.dispose(); // release the per-session anchor-log fds
+        this.approvalExemptionStore.dispose(); // release the per-session exemption-log fds
+        this.sendFileLedgerStore.dispose(); // release the sendfile-ledger append fd (lazy — may never have opened)
+        this.workflowJournalStore.dispose(); // release the per-run journal-ledger fds
+        this.checkpointStoreInst?.close(); // release the checkpoint ledger fd (lazy, may never have been built)
+        await this.fileBackend.dispose(); // MUST release root/LOCK so a graceful restart can re-acquire the data dir
     }
     run() { return this.runStore; }
-    resumeAnchor() { return this.resumeAnchorStore; }
-    approvalExemption() { return this.approvalExemptionStore; }
-    sendFileLedger() { return this.sendFileLedgerStore; }
+    resumeAnchor() { return this.resumeAnchorStore; } // singleton — state lives in the instance (mirrors run()/session())
+    approvalExemption() { return this.approvalExemptionStore; } // singleton — same posture
+    sendFileLedger() { return this.sendFileLedgerStore; } // singleton — append fd lives in the instance
+    /** Durable HITL / plan-review parking on the LOCAL lane. Lazy singleton (the inner core store holds
+     *  an append fd). taskId join ← FileRunStore; E21 owner guard ← LocalSessionStore.ownerOf (same root). */
     checkpoint() {
         if (!this.checkpointStoreInst) {
             const cs = new LocalCheckpointStore(this.fileBackend.root, {
@@ -187,6 +247,14 @@ class LocalBackend {
                 ownerOf: (sessionId) => this.sessionStore.ownerOf(sessionId),
             });
             this.checkpointStoreInst = cs;
+            // [868] the reverse join: FileRunStore's suspended-run reapers cannot JOIN the checkpoint plane (separate
+            // store), so they take the two EXISTS predicates as an injected probe — wired HERE because this is the one
+            // place both stores exist over the same root. Without it the reapers stay honest NO-OPs, and an abandoned
+            // durable HITL park (approval never answered) held its task_active claim forever (session locked; the
+            // [868] incident). NB the probe only tells the reaper what the SQL twins read via JOIN — the reaper's
+            // D-D NOT-pending guard still decides; and the APPROVAL_TIMEOUT_SEC=0 default still keeps the time-based
+            // leg OFF (durable HITL waits for a human indefinitely BY DESIGN; the checkpoint-expiry leg + the cancel
+            // verb are the recovery handles).
             this.runStore.setCheckpointProbe({
                 hasPending: async (sessionId) => (await cs.findPendingTokenBySession(sessionId)) !== null,
                 hasExpired: (sessionId) => cs.hasExpiredBySession(sessionId),
@@ -195,21 +263,28 @@ class LocalBackend {
         return this.checkpointStoreInst;
     }
     checkpointStoreInst;
-    sessionPolicy() { return this.fileBackend.sessionPolicyStore; }
-    fileSnapshot() { return this.fileBackend.fileSnapshotStore; }
-    workflowJournal() { return this.workflowJournalStore; }
-    outcomeSink() { return this.outcomeSinkInst; }
+    sessionPolicy() { return this.fileBackend.sessionPolicyStore; } // E6 — file-backed (survives restart)
+    fileSnapshot() { return this.fileBackend.fileSnapshotStore; } // E19 — file-backed content-addressed blobs (survive restart)
+    workflowJournal() { return this.workflowJournalStore; } // SVC-2 — FILE-backed (restart-durable on one box, see field doc)
+    outcomeSink() { return this.outcomeSinkInst; } // design/73 §1 — owner-only JSONL fact ledger
     session() { return this.sessionStore; }
+    // core 1.219 (dogfood finding "ReadToolResult(ref) 恒空"): the TOC lane now has a DURABLE tool-result
+    // store — core's FileToolResultStore under the same data root (one file per ref, write-once, restart-durable).
+    // In-process cross-task deref was already fixed core-side (1.219 Runner-shared fallback); this adds the
+    // cross-RESTART half. No reapOlderThan/deleteBySession (optional extras) — single-user text previews, CC posture.
     toolResult() { return this.fileBackend.toolResultStore; }
     mysqlPool() { return undefined; }
     pgPool() { return undefined; }
 }
+/** Build the durable-store backend for `config.dbBackend`. Does NOT connect (the pool connects lazily; the
+ *  reachability probe is the caller's first `ensureSchema`). Returns undefined when no DB is configured. */
 export function createStoreBackend(config) {
     if (config.dbBackend === "local")
         return new LocalBackend(config.localDataRoot ?? join(homedir(), ".ai-agent"), config);
     if (config.dbBackend === "pg") {
         if (!config.pg)
             return undefined;
+        // pgPoolOptions also arms the DB_QUERY_TIMEOUT_MS pool-wide per-query ceiling (S9 deeper fix) when set.
         const pool = createPgPool(pgPoolOptions(config.pg, config.dbQueryTimeoutMs));
         return new PgBackend(pool, config);
     }
@@ -217,17 +292,35 @@ export function createStoreBackend(config) {
         return undefined;
     return new TiDBBackend(createTidbPool(config), config);
 }
+/** boot 期打开 store 后端的**统一入口**:构造 + ensureSchema 同罩一层降级臂。
+ *
+ *  为什么必须把 `createStoreBackend()` 也罩进来(2026-07-28 修):clay 1.292 拍的口径是「裸 boot
+ *  **默认推导**的 local 在只读文件系统/mkdir 失败时不得拒启」,但原先 try 只罩 `ensureSchema()`——
+ *  而 LocalBackend 的 `ensureSchema` 是**空实现**,真正会抛的 mkdir + 数据根 BootLock 在构造函数里、
+ *  落在 try 之外。于是那条降级臂对 local 形从来没生效过,注释宣称的行为与代码真做的事撕裂。
+ *
+ *  降级条件不变(两形同一姿势):`sessionBackend=auto`(配置的 DB 不可达,S5 原形)或**默认推导**的
+ *  local(`dbBackend=local && !dbBackendExplicit`)。**显式** DB_BACKEND=local / tidb 仍 fail-loud——
+ *  operator 要了 durable,静默丢=丢数据。 */
 export async function openStoreBackendWithFallback(config, logger) {
+    // 判据按后端分岔(2026-07-28 同批修):原先写的是 `sessionBackend === "auto" || (local && !explicit)`,
+    // 而 `auto` 是 SESSION_BACKEND 的**默认值** ⇒ 显式 `DB_BACKEND=local` 的部署照样落进第一条臂被静默降级,
+    // 「显式仍 fail-loud」这句话同样从未生效。local 形只看 DB_BACKEND 是不是显式;SQL 形维持 S5 原义
+    // (auto=尽力而为可降级,显式 tidb/pg=fail-loud,静默丢持久化会丢 run)。
     const mayFallback = config.dbBackend === "local" ? !config.dbBackendExplicit : config.sessionBackend === "auto";
     let backend;
     try {
         backend = createStoreBackend(config);
+        // connects + creates schema (also the reachability probe).
         if (backend)
             await backend.ensureSchema();
     }
     catch (err) {
         if (!mayFallback)
             throw err;
+        // S5 (SILENT-FALLBACK P0-b): one boot warn was the ONLY trace of "this replica is not persisting".
+        // The caller renders the gauge + /health twin flag so a degraded replica is distinguishable from
+        // an in-memory-by-choice one.
         logger.warn("store_db_unreachable_fallback_memory", {
             backend: backend?.kind ?? config.dbBackend,
             error: err instanceof Error ? err.message : String(err),

package/dist/plugins/store-contracts.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Backend-NEUTRAL store contracts (design/158 A3 沉底).
+ *
+ * The record/event/summary shapes (and the pure row-mapping helpers) shared by ALL store backends —
+ * TiDB/MySQL, PostgreSQL, file, memory — plus their non-store consumers (http wire, trace, images,
+ * capabilities). They used to live inside the TiDB adapters, which made every other backend (and the
+ * HTTP layer) import a TiDB module just to name a type; this file is the neutral home.
+ *
+ * Rules for this file:
+ *  - ZERO dialect dependencies (no mysql2, no pg) — types + pure functions only. The only imports
+ *    allowed are core contract types and the neutral sql-row-helpers leaf.
+ *  - Adapters import their contracts from HERE; no adapter imports its twin (store-backend.ts, the
+ *    composition root, is the one place that names every concrete adapter).
+ *  - The TiDB adapters re-export these names for back-compat (the historical import surface), but new
+ *    code should import from this file.
+ */
 import type { TaskResult, TaskStatus } from "@sema-agent/core";
 export interface RunRecord {
     taskId: string;
@@ -6,23 +22,42 @@ export interface RunRecord {
     status: "running" | TaskStatus;
     result: TaskResult | null;
     error: string | null;
+    /** Structured failure code (1.36/1.37) denormalized from the result for SQL queryability. */
     errorCode: string | null;
+    /** Work-view correlation id (optional): groups the runs of one logical task across both client doors
+     *  (MCP façade / portal). null when the caller didn't supply one. */
     jobId: string | null;
+    /** Which SYSTEM's credential submitted the run (oa/cc-mcp/portal…), derived at the auth gate — never
+     *  self-declared. null = legacy single-token deployment (authenticated, no system identity). */
     source: string | null;
+    /** The replica that OWNS this run (the instanceId that created it). Lets a preempt/cancel handler tell
+     *  "this run is on MY replica" (consult the in-process inflight/preemptable map authoritatively) from "owned
+     *  elsewhere" (fall back to the durable cross-replica flag). null for pre-column rows. */
     instanceId: string | null;
+    /** First ~120 chars of the objective (secret-redacted at write) — the list's "what is this task" glance.
+     *  null for rows predating the column. */
     objectivePreview: string | null;
     createdAt: string;
     updatedAt: string;
 }
+/** One row of the GET /v1/sessions list (CC /resume picker): a DISTINCT session (sessionId) aggregated from its
+ *  task_run rows — newest-first by last activity. The preview/status are the LATEST run's ("continue where I left
+ *  off"); the counts/timestamps span the whole session. Owner included so a fleet-wide (ops) listing is attributable. */
 export interface SessionSummary {
     sessionId: string;
     owner: string | null;
+    /** The most recent run's create time (the keyset sort key) and the session's first run's create time. */
     lastActivityAt: string;
     firstActivityAt: string;
     runCount: number;
+    /** The LATEST run's objective preview + status — what the session was last doing. */
     objectivePreview: string | null;
     lastStatus: string;
+    /** K-5c (shell §K): the LATEST run's task_id — the anchor the shell uses to re-attach the live event tail in ONE
+     *  hop (`GET /v1/runs/:lastRunId/events`) when resuming a picked session, instead of a second lookup. */
     lastRunId: string | null;
+    /** The auto-generated session title (cheap-model one-liner, write-once). null = not (yet)
+     *  titled OR the lister face has no session_meta (the legacy task_run aggregate / memory twins — honest degrade). */
     title: string | null;
 }
 export interface RunEvent {
@@ -31,8 +66,11 @@ export interface RunEvent {
     data: unknown;
     ts: string;
 }
+/** Coarse 4-value lifecycle the SSE reader polls for terminality (run-store parity). */
 export type BakeStatus = "queued" | "running" | "done" | "failed";
+/** build.sh's 8-value ordered state — UI progress bar only, NEVER stream terminality (P2.3). */
 export type BakeState = "PENDING" | "BUILDING" | "PUSHING" | "VERIFYING" | "REGISTERING" | "COMPLETE" | "FAILED" | "CANCELLED";
+/** Structured terminal codes the center band-composer UI keys on (P2.14): null on success / uncategorized. */
 export type BakeErrorCode = "band-conflict" | "duplicate" | "disk" | "timeout" | "cancelled" | null;
 export interface BakeRecord {
     bakeId: string;
@@ -65,12 +103,15 @@ export interface BakeRecord {
 }
 export interface BakeEvent {
     seq: number;
+    /** Runner-supplied per-line ordinal (ingest dedupe key); null for image-api-synthesized frames. */
     lineOrd: number | null;
     kind: string;
+    /** 'raw' for opt-in build.log tail rows (evicted first); null for structured frames. */
     level: string | null;
     data: unknown;
     ts: string;
 }
+/** The validated/normalized inputs a `POST /v1/images/bakes` produces (operator free-text never reaches here). */
 export interface CreateBakeInput {
     profile: string;
     bands: string[] | null;
@@ -78,10 +119,12 @@ export interface CreateBakeInput {
     push: boolean;
     dryRun: boolean;
     logs: boolean;
+    /** The VETTED, normalized build.sh argv the runner runs (and ONLY this). */
     argv: string[];
     idemKey: string | null;
     requestedBy: string | null;
 }
+/** The terminal fields the auto-register / done path writes (P2.10). */
 export interface BakeTerminal {
     status: "done" | "failed";
     state: BakeState;
@@ -95,6 +138,8 @@ export interface BakeTerminal {
     manifestSha?: string | null;
     tag?: string | null;
 }
+/** Raw SELECT row shape shared by BOTH SQL twins (design/158 S8 归位, A3 沉底 —
+ *  node-pg reads BIGINT-ish `exit_code` back as a string, hence `number | string | null`). */
 export interface BakeRow {
     bake_id: string;
     profile: string;
@@ -124,13 +169,18 @@ export interface BakeRow {
     created_at: Date | string;
     updated_at: Date | string;
 }
+/** SELECT row → {@link BakeRecord} — shared by BOTH SQL twins (design/158 S8 归位, A3 沉底). */
 export declare function mapBakeRow(r: BakeRow): BakeRecord;
+/** Column list mapBakeRow expects — shared by BOTH SQL twins (design/158 S8 归位, A3 沉底). */
 export declare const BAKE_SELECT_COLS: string;
+/** Nested-build security posture (the operator console shows rootless vs privileged-dind). */
 export type ImageNestedBuildMode = "none" | "docker-cli-only" | "rootless-buildkit" | "privileged-dind";
 export interface ImageCapabilities {
     browser?: boolean;
     db?: boolean;
+    /** Whether the image can build container images at all (bool — back-compat). */
     nestedBuild?: boolean;
+    /** HOW it nests (the security posture). Additive over `nestedBuild`; absent ⇒ treat as `nestedBuild`. */
     nestedBuildMode?: ImageNestedBuildMode;
 }
 export interface ImagePodContract {
@@ -165,19 +215,30 @@ export interface ImageIndexEntry {
     createdAt: string;
     updatedAt: string;
 }
+/** The fields an upsert supplies (id/createdAt/updatedAt are derived/managed). id is ALWAYS the deterministic
+ *  idFor(repo,digest) — there is no explicit-id seam, so id-conflict ⟺ (repo,digest)-conflict in BOTH stores
+ *  (PG's `ON CONFLICT (id)` and MySQL's `ON DUPLICATE KEY` are provably equivalent; no false-parity surface). */
 export type ImageIndexUpsert = Omit<ImageIndexEntry, "id" | "createdAt" | "updatedAt">;
+/** Who is asking — drives visibility scoping. */
 export interface ImageViewer {
+    /** Operators see every row regardless of visibility/tenant. */
     operator?: boolean;
+    /** A tenant principal additionally sees its own `tenant` rows. */
     tenantId?: string | null;
 }
 export interface ImageListFilter extends ImageViewer {
     profile?: string;
     status?: ImageStatus;
+    /** Require a capability to be true (e.g. "browser"). */
     capability?: keyof ImageCapabilities;
+    /** Only the newest published digest per profile. */
     latestOnly?: boolean;
     limit?: number;
+    /** Opaque keyset cursor from a prior page's `nextCursor`. */
     cursor?: string;
 }
+/** Raw SELECT row shape shared by BOTH SQL twins (design/158 S8 归位, A3 沉底 —
+ *  node-pg reads BIGINT `size_bytes` back as a string, hence `number | string | null`). */
 export interface ImageRow {
     id: string;
     profile: string;
@@ -201,5 +262,6 @@ export interface ImageRow {
     created_at: Date | string;
     updated_at: Date | string;
 }
+/** SELECT row → {@link ImageIndexEntry} — shared by BOTH SQL twins (design/158 S8 归位, A3 沉底). */
 export declare function mapImageRow(r: ImageRow): ImageIndexEntry;
 //# sourceMappingURL=store-contracts.d.ts.map

package/dist/plugins/store-contracts.js

@@ -1,4 +1,5 @@
 import { parseJsonOr, toIso as iso, normalizeIsoOrNull as isoOrNull } from "./sql-row-helpers.js";
+/** SELECT row → {@link BakeRecord} — shared by BOTH SQL twins (design/158 S8 归位, A3 沉底). */
 export function mapBakeRow(r) {
     return {
         bakeId: r.bake_id,
@@ -30,9 +31,11 @@ export function mapBakeRow(r) {
         updatedAt: iso(r.updated_at),
     };
 }
+/** Column list mapBakeRow expects — shared by BOTH SQL twins (design/158 S8 归位, A3 沉底). */
 export const BAKE_SELECT_COLS = "bake_id, profile, bands, base_ref, push, dry_run, logs, argv, status, state, digest, repo, ref, index_id, " +
     "exit_code, error, error_code, manifest_sha, tag, idem_key, ingest_secret, runner_id, lease_until, " +
     "cancel_requested, requested_by, created_at, updated_at";
+/** SELECT row → {@link ImageIndexEntry} — shared by BOTH SQL twins (design/158 S8 归位, A3 沉底). */
 export function mapImageRow(r) {
     return {
         id: r.id,

package/dist/plugins/task-attachment-store.d.ts

@@ -1,8 +1,35 @@
+/**
+ * TaskAttachmentStore —— D-1 通用文件上传的**独立附件 store**(clay 拍 2026-07-27:不复用 fileSnapshot
+ * 的 content-addressed blob 面,新建)。TiDB/PG 双方言 + local 文件店(local-task-attachment-store.ts)。
+ *
+ * 为什么独立而不是骑 SqlBlobBackend/snapshot_blob:那套的引用追踪=「manifest 里没有的即 orphan」,
+ * 附件不在任何 snapshot_manifest ⇒ 会被 sweepOrphanBlobs 在 1h grace 后误收。生命周期也不同:
+ * snapshot blob 跟 session 的工作树;**附件跟 task/session 的绑定**(上传先行、提交时绑定、E21 随会话
+ * 级联删、未绑定的按 TTL 收割)。
+ *
+ * 语义要点:
+ *  - `owner` = auth principal ?? "default"(单库 tenant 轴;无 principal 部署全 default = 单用户语义)。
+ *    读/删门在 SQL WHERE 完成(filter-before-reduce,roster 语义条 1 同姿)——他人行连结果集都不进。
+ *  - **字节本体在对象存储(clay 裁 2026-07-27:云形态对象存储必配,「现在就接」)**:SQL 只存 meta
+ *    (索引/owner 门/生命周期),bytes 走 {@link AttachmentBytesStore}(生产=既有 MinioBlobBackend,
+ *    读侧内建 sha 校验)。对象键=**sha256**(同内容天然去重;跨 owner 共享对象 ⇒ 对象删除必须过
+ *    零引用检查)+ **附件专属 keyPrefix**(与快照 blob 命名空间隔离——同 sha 不同生命周期,混用会互删)。
+ *    删除次序:meta 先(E21 purge 永不被 MinIO 网络抖动卡死,blob-backend 异步删裁定同旨),对象删
+ *    =零引用检查后 best-effort(失败只 log:无 meta 的对象经 API 不可达;彻底清收敛作 follow-up 记账)。
+ *    ⚠️ 曾试过字节进 DB:真库连撞 max_allowed_packet(文本协议 2× 膨胀)与 TiDB 单 entry 6 MiB 限
+ *    (txn-entry-size-limit)两道墙——分块版虽真库 5/5 跑通,被本裁定取代,教训留此。
+ *  - 隔离键排序规则:TiDB 表级 utf8mb4_bin / PG owner 列 COLLATE "C"(bga F2 同姿,'=' 字节等价)。
+ *    owner 值恒为 server 端从凭据推导(非用户输入),PAD SPACE 近撞面不可达,VARBINARY 键列不必要。
+ *  - 布尔列:无(遵 1.287.0 归一约定,若未来加,PG 用 SMALLINT 0/1)。
+ *  - 绑定:`bind` 把行钉到 sessionId(重复绑定=改绑,同 owner 内 last-wins;同 session 多 task 共享
+ *    自然成立——listBySession 是物化输入)。未绑定行 = 上传后从未被任何 task 引用 ⇒ reapUnbound(TTL)。
+ */
 import type { Pool } from "mysql2/promise";
 import type { PgQueryFn } from "./pg-query.js";
 export interface TaskAttachmentRecord {
     id: string;
     owner: string;
+    /** 消毒后的 basename(http 面用 core sanitizePathComponent 处理;store 只存不再消毒)。 */
     name: string;
     mime: string;
     sha256: string;
@@ -15,16 +42,25 @@ export interface TaskAttachmentStore {
     put(rec: TaskAttachmentRecord & {
         content: Uint8Array;
     }): Promise<void>;
+    /** meta(不带 bytes);owner 不匹配/不存在 → null(无 oracle)。 */
     get(owner: string, id: string): Promise<TaskAttachmentRecord | null>;
     getContent(owner: string, id: string): Promise<Uint8Array | null>;
+    /** 把 ids 钉到 sessionId(owner 门在 WHERE);返回真绑到的行数——调用方以 count===ids.length 判全成。 */
     bind(owner: string, ids: string[], sessionId: string, boundAtMs: number): Promise<number>;
+    /** 物化输入(env 建立时)——按 session 单键查(绑定时已 owner 验过;session uuid 不可枚举)。 */
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
     delete(owner: string, id: string): Promise<boolean>;
+    /** E21 会话删除级联(session_id 单键,路由已证会话所有权——resume-anchor 同理由)。 */
     deleteBySession(sessionId: string): Promise<number>;
+    /** TTL 收割:未绑定且 created_at_ms < olderThanMs 的行。返回删除数。 */
     reapUnbound(olderThanMs: number): Promise<number>;
+    /** D-1 孤儿**对象**彻底 GC(clay 拍 2026-07-28):列举对象存储 × meta 行对账,零行且过 grace 的对象删。
+     *  可选——local 店(meta+bytes 同盘同步删)无此孤儿类。 */
     sweepOrphanObjects?(graceMs: number, nowMs?: number): Promise<number>;
 }
 export declare const TASK_ATTACHMENT_TABLE = "task_attachment";
+/** 字节面 seam —— MinioBlobBackend 的结构子集(hash 键控;读侧 sha 校验在实现内)。`listObjects` 可选
+ *  (D-1 孤儿对象 GC 的列举面;测试桩/无列举后端缺席=sweep 诚实 0,不装作扫过)。 */
 export interface AttachmentBytesStore {
     putBlob(hash: string, bytes: Uint8Array): Promise<void>;
     getBlob(hash: string): Promise<Uint8Array | undefined>;
@@ -33,11 +69,19 @@ export interface AttachmentBytesStore {
         hash: string;
         lastModifiedMs: number;
     }>;
+    /** 删前复查面(复审 B-F1):返回对象当前 LastModified(缺席=已不在)。缺此面 ⇒ sweep 保守**不删**
+     *  (宁可留孤儿也不冒误删风险)——见 sweepOrphanObjects 的竞态注。 */
     headObject?(hash: string): Promise<{
         lastModifiedMs: number;
     } | undefined>;
 }
+/** 物化相对路径(确定性,notice 与真实写盘共用一份推导——两处各算一遍会漂):按 listBySession 序
+ *  (created_at_ms, id)分配 `attachments/<name>`;同名撞车时后者前缀 id 头 8 位。名字在上传时已
+ *  消毒为安全 basename([A-Za-z0-9._-]),拼接后仍是安全相对路径。 */
 export declare function materializedRelPaths(atts: TaskAttachmentRecord[]): Map<string, string>;
+/** 半场②(提交时绑定 + objective 告知)的可测核。fresh 腿硬验证(未知/他人 id → throw(mapTo400));
+ *  resume 腿降级(warn+跳过——4xx 会砖存量 task;记录不可变 ⇒ 在场行的 notice 字节恒稳)。
+ *  notice 路径从**绑定后的全 session 集**推导(与物化共用 materializedRelPaths),只罗列本次引用的文件。 */
 export declare function bindAttachmentsForTask(opts: {
     store: TaskAttachmentStore;
     owner: string;
@@ -49,6 +93,8 @@ export declare function bindAttachmentsForTask(opts: {
 }): Promise<{
     notice: string | undefined;
 }>;
+/** 半场③(env 建立时物化)的可测核。**fail-loud**:objective 已宣告文件在场,静默缺文件=模型按幻影
+ *  文件行动,比 env 建立失败更糟 ⇒ 任一写失败即 throw。幂等:重建沙箱/resume 重写同路径同字节。 */
 export declare function materializeAttachmentsInto(env: {
     createDir(path: string, options?: {
         recursive?: boolean;
@@ -71,6 +117,7 @@ export declare function materializeAttachmentsInto(env: {
 }, store: TaskAttachmentStore, sessionId: string): Promise<number>;
 export declare function ensureTiDBTaskAttachmentSchema(pool: Pool): Promise<void>;
 export declare function ensurePgTaskAttachmentSchema(q: PgQueryFn): Promise<void>;
+/** bytes → 4 MiB 块序列(共享切块器,两方言 + 完整性校验共用)。 */
 export declare class TiDBTaskAttachmentStore implements TaskAttachmentStore {
     private readonly pool;
     private readonly bytes;
@@ -80,14 +127,24 @@ export declare class TiDBTaskAttachmentStore implements TaskAttachmentStore {
     }): Promise<void>;
     get(owner: string, id: string): Promise<TaskAttachmentRecord | null>;
     getContent(owner: string, id: string): Promise<Uint8Array | null>;
+    /** 零引用对象删除(best-effort):meta 已删后,sha 仍被其他行引用则对象保留(跨行去重共享)。
+     *  失败只吞不抛——E21 purge 不被对象存储抖动卡死(blob-backend 异步删裁定同旨);无 meta 的对象
+     *  经 API 不可达,彻底清收敛记 follow-up。 */
     private deleteBytesIfUnreferenced;
     bind(owner: string, ids: string[], sessionId: string, boundAtMs: number): Promise<number>;
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
     delete(owner: string, id: string): Promise<boolean>;
     deleteBySession(sessionId: string): Promise<number>;
     reapUnbound(olderThanMs: number): Promise<number>;
+    /** D-1 孤儿对象彻底 GC(clay 拍 2026-07-28):对象存储列举 × meta 行对账。判据保守三层:
+     *  ①只删**真列举到**且 ②零 meta 行引用 且 ③LastModified 过 grace 的对象(上传先行窗口:对象先落、
+     *  meta 行后写——grace 护住 put 竞态,宁漏勿误删,下轮再收);列举失败=整轮 throw(调用方 catch,
+     *  「列不出来」绝不当「没有孤儿」)。 */
     sweepOrphanObjects(graceMs: number, nowMs?: number): Promise<number>;
+    /** sweep 的引用对账半场:批内 sha 中仍有 meta 行的子集(单 IN 查询;DISTINCT 免重复行膨胀)。 */
     private referencedShas;
+    /** 删前复查(复审 B-F1):只保留「HEAD 仍在 且 LastModified 仍过 grace」的 hash。无 headObject
+     *  面 ⇒ 返回空集(保守不删);HEAD 抛错 ⇒ 该对象本轮跳过(下轮再收)。 */
     private filterStillOrphan;
 }
 export declare class PgTaskAttachmentStore implements TaskAttachmentStore {
@@ -105,8 +162,11 @@ export declare class PgTaskAttachmentStore implements TaskAttachmentStore {
     delete(owner: string, id: string): Promise<boolean>;
     deleteBySession(sessionId: string): Promise<number>;
     reapUnbound(olderThanMs: number): Promise<number>;
+    /** D-1 孤儿对象彻底 GC —— twin of the TiDB store(判据三层同注:真列举/零引用/过 grace)。 */
     sweepOrphanObjects(graceMs: number, nowMs?: number): Promise<number>;
     private referencedShas;
+    /** 删前复查(复审 B-F1):只保留「HEAD 仍在 且 LastModified 仍过 grace」的 hash。无 headObject
+     *  面 ⇒ 返回空集(保守不删);HEAD 抛错 ⇒ 该对象本轮跳过(下轮再收)。 */
     private filterStillOrphan;
 }
 //# sourceMappingURL=task-attachment-store.d.ts.map