@springbrand/agent-runtime 0.1.0

package/src/db/schema.ts

@@ -0,0 +1,164 @@
+import type { SqlTaggedTemplate } from "agents/chat";
+
+// Repository 和各持久化记录的统一定义见 ./index.ts。
+// 创建当前 Runtime 需要但尚不存在的 SQLite 表。
+// AgentRuntimeKernel 构造时通过 RuntimeDatabase.initializeSchema 调用，重复启动依赖 IF NOT EXISTS 保留现有表。
+// pi_approvals 有一次显式的 risk → 四档升级；步骤均可重入，中断后下次初始化会继续。
+export function initializeSchema(sql: SqlTaggedTemplate): void {
+  sql`CREATE TABLE IF NOT EXISTS pi_message_ui (
+    message_id TEXT PRIMARY KEY,
+    body TEXT NOT NULL
+  )`;
+  sql`CREATE TABLE IF NOT EXISTS pi_submissions (
+    submission_id TEXT PRIMARY KEY,
+    request_id TEXT NOT NULL UNIQUE,
+    idempotency_key TEXT UNIQUE,
+    status TEXT NOT NULL,
+    accepted INTEGER NOT NULL,
+    error TEXT,
+    created_at INTEGER NOT NULL,
+    completed_at INTEGER,
+    assembly_revision TEXT NOT NULL,
+    assembly_descriptor TEXT NOT NULL,
+    assistant_message_id TEXT NOT NULL,
+    abort_reason TEXT
+  )`;
+  const submissionColumns = new Set(
+    sql<{ name: string }>`PRAGMA table_info(pi_submissions)`
+      .map((column) => column.name),
+  );
+  if (!submissionColumns.has("queued_input_json")) {
+    sql`ALTER TABLE pi_submissions ADD COLUMN queued_input_json TEXT`;
+  }
+  if (!submissionColumns.has("queued_ui_message_json")) {
+    sql`ALTER TABLE pi_submissions ADD COLUMN queued_ui_message_json TEXT`;
+  }
+  if (!submissionColumns.has("user_message_id")) {
+    sql`ALTER TABLE pi_submissions ADD COLUMN user_message_id TEXT`;
+  }
+  if (!submissionColumns.has("regenerate_message_id")) {
+    sql`ALTER TABLE pi_submissions ADD COLUMN regenerate_message_id TEXT`;
+  }
+  sql`CREATE UNIQUE INDEX IF NOT EXISTS pi_submissions_one_running
+      ON pi_submissions(status)
+      WHERE status = 'running'`;
+  sql`CREATE TABLE IF NOT EXISTS pi_pending_steers (
+    steer_id TEXT PRIMARY KEY,
+    submission_id TEXT NOT NULL,
+    message_id TEXT NOT NULL UNIQUE,
+    canonical_json TEXT NOT NULL,
+    ui_message_json TEXT,
+    created_at INTEGER NOT NULL
+  )`;
+  sql`CREATE TABLE IF NOT EXISTS pi_tool_settlements (
+    submission_id TEXT NOT NULL,
+    tool_call_id TEXT NOT NULL,
+    tool_name TEXT NOT NULL,
+    args TEXT NOT NULL,
+    result TEXT NOT NULL,
+    is_error INTEGER NOT NULL,
+    created_at INTEGER NOT NULL,
+    PRIMARY KEY (submission_id, tool_call_id)
+  )`;
+  sql`CREATE TABLE IF NOT EXISTS pi_turn_event_outbox (
+    event_id TEXT PRIMARY KEY,
+    body TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    delivered_at INTEGER
+  )`;
+  sql`CREATE TABLE IF NOT EXISTS pi_approvals (
+    execution_id TEXT PRIMARY KEY,
+    submission_id TEXT NOT NULL,
+    request_id TEXT NOT NULL,
+    source TEXT NOT NULL,
+    tool_call_id TEXT NOT NULL,
+    tool_name TEXT NOT NULL,
+    summary TEXT NOT NULL,
+    execution_level TEXT NOT NULL,
+    required_level TEXT NOT NULL,
+    input_json TEXT NOT NULL,
+    status TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    decided_at INTEGER,
+    reason TEXT,
+    UNIQUE (submission_id, tool_call_id)
+  )`;
+  const approvalColumns = () =>
+    new Set(
+      sql<{ name: string }>`PRAGMA table_info(pi_approvals)`
+        .map((column) => column.name),
+    );
+  let columns = approvalColumns();
+  if (!columns.has("execution_level")) {
+    // 旧 Session 没有持久化当时的授权档位，safe 失败关闭；只影响旧 pending 回执展示，不会静默放行。
+    sql`ALTER TABLE pi_approvals
+        ADD COLUMN execution_level TEXT NOT NULL DEFAULT 'safe'`;
+    columns = approvalColumns();
+  }
+  if (!columns.has("required_level")) {
+    sql`ALTER TABLE pi_approvals
+        ADD COLUMN required_level TEXT NOT NULL DEFAULT 'safe'`;
+    columns = approvalColumns();
+  }
+  if (columns.has("risk")) {
+    sql`UPDATE pi_approvals
+        SET required_level = CASE risk
+          WHEN 'low' THEN 'low'
+          WHEN 'medium' THEN 'medium'
+          WHEN 'high' THEN 'high'
+          ELSE 'safe'
+        END`;
+    sql`ALTER TABLE pi_approvals DROP COLUMN risk`;
+  }
+  sql`CREATE TABLE IF NOT EXISTS pi_recovery_milestones (
+    submission_id TEXT NOT NULL,
+    seq INTEGER NOT NULL,
+    milestone_key TEXT NOT NULL,
+    body TEXT NOT NULL,
+    PRIMARY KEY (submission_id, seq),
+    UNIQUE (submission_id, milestone_key)
+  )`;
+  sql`UPDATE pi_recovery_milestones
+      SET body = json_remove(
+        json_set(
+          body,
+          '$.approval.executionLevel', 'safe',
+          '$.approval.requiredExecutionLevel',
+          COALESCE(json_extract(body, '$.approval.risk'), 'safe')
+        ),
+        '$.approval.risk'
+      )
+      WHERE json_valid(body)
+        AND json_extract(body, '$.version') = 1
+        AND json_extract(body, '$.type') = 'approval'
+        AND json_type(body, '$.turnId') = 'text'
+        AND json_type(body, '$.assemblyRevision') = 'text'
+        AND json_type(body, '$.approval') = 'object'
+        AND json_type(body, '$.approval.executionId') = 'text'
+        AND json_type(body, '$.approval.requestId') = 'text'
+        AND json_extract(body, '$.approval.source') IN (
+          'action', 'codemode', 'temporary-agent'
+        )
+        AND json_type(body, '$.approval.toolCallId') = 'text'
+        AND json_type(body, '$.approval.toolName') = 'text'
+        AND json_type(body, '$.approval.summary') = 'text'
+        AND json_type(body, '$.approval.inputJson') = 'text'
+        AND json_type(body, '$.approval.createdAt') IN ('integer', 'real')
+        AND json_extract(body, '$.approval.status') IN (
+          'pending', 'approved', 'rejected'
+        )
+        AND (
+          json_type(body, '$.approval.risk') IS NULL
+          OR json_type(body, '$.approval.risk') = 'null'
+          OR json_extract(body, '$.approval.risk') IN (
+            'low', 'medium', 'high'
+          )
+        )
+        AND json_type(body, '$.approval.executionLevel') IS NULL
+        AND json_type(body, '$.approval.requiredExecutionLevel') IS NULL`;
+  sql`CREATE TABLE IF NOT EXISTS pi_extension_context (
+    label TEXT PRIMARY KEY,
+    content TEXT NOT NULL,
+    updated_at INTEGER NOT NULL
+  )`;
+}

package/src/db/settlement.repo.ts

@@ -0,0 +1,104 @@
+import type { SqlTaggedTemplate } from "agents/chat";
+
+// Settlement 的统一定义见 ./index.ts。
+export interface StoredToolSettlement {
+  toolCallId: string;
+  submissionId: string;
+  toolName: string;
+  args: string;
+  result: string;
+  isError: boolean;
+  createdAt: number;
+}
+
+export interface NewToolSettlement {
+  toolCallId: string;
+  submissionId: string;
+  toolName: string;
+  args: string;
+  result: string;
+  isError: boolean;
+  createdAt: number;
+}
+
+type SettlementRow = {
+  tool_call_id: string;
+  submission_id: string;
+  tool_name: string;
+  args: string;
+  result: string;
+  is_error: number;
+  created_at: number;
+};
+
+// 把 SQLite 行转成 Runtime 使用的工具结果对象。
+// find 查到记录后调用，上层因而只看 camelCase 字段和 boolean。
+// SQLite 用 0/1 存 is_error，转换必须留在此边界；增加列时要同步核对类型、SELECT 和映射。
+function mapRow(row: SettlementRow): StoredToolSettlement {
+  return {
+    toolCallId: row.tool_call_id,
+    submissionId: row.submission_id,
+    toolName: row.tool_name,
+    args: row.args,
+    result: row.result,
+    isError: row.is_error === 1,
+    createdAt: row.created_at,
+  };
+}
+
+export class ToolSettlementRepository {
+  // 保存当前 Agent SQLite 的查询入口。
+  // RuntimeDatabase 构造时调用，工具执行和恢复流程随后共享这个 Repository。
+  // Settlement 要与所属 Submission 同库持久化，否则重放时无法一致查重。
+  constructor(private readonly sql: SqlTaggedTemplate) {}
+
+  // 按 Submission 和工具调用 ID 读取已落盘的最终结果。
+  // settleTool 写入前和 readToolSettlement 恢复时调用，没有记录时返回 null。
+  // 两列共同定位表的复合主键，不能只按 toolCallId 查询而把其他 Submission 的结果当成当前结果。
+  find(
+    submissionId: string,
+    toolCallId: string,
+  ): StoredToolSettlement | null {
+    const row = this.sql<SettlementRow>`
+      SELECT tool_call_id, submission_id, tool_name, args, result,
+             is_error, created_at
+      FROM pi_tool_settlements
+      WHERE submission_id = ${submissionId}
+        AND tool_call_id = ${toolCallId}
+    `[0];
+    return row ? mapRow(row) : null;
+  }
+
+  // 持久化一条尚未存在的工具最终结果。
+  // settleTool 在事务中确认 find 返回 null 后调用，冲突的重复结果由上层拒绝。
+  // 复合主键会让未经查重的重复写入直接失败，不能用 INSERT OR REPLACE 掩盖不一致的工具结果。
+  insert(s: NewToolSettlement): void {
+    this.sql`
+      INSERT INTO pi_tool_settlements (
+        tool_call_id, submission_id, tool_name, args, result,
+        is_error, created_at
+      ) VALUES (
+        ${s.toolCallId},
+        ${s.submissionId},
+        ${s.toolName},
+        ${s.args},
+        ${s.result},
+        ${s.isError ? 1 : 0},
+        ${s.createdAt}
+      )
+    `;
+  }
+
+  // 统计某次 Submission 已落盘的工具结果数。
+  // Runtime 生成恢复快照时调用，没有记录时应得到 0。
+  // 这里以数据库为真相源，不能改成内存计数，否则 Durable Object 重启后会丢失进度。
+  countForSubmission(submissionId: string): number {
+    return (
+      this.sql<{ count: number }>`
+        SELECT COUNT(*) AS count
+        FROM pi_tool_settlements
+        WHERE submission_id = ${submissionId}
+      `[0]?.count ?? 0
+    );
+  }
+}

package/src/db/steer.repo.ts

@@ -0,0 +1,73 @@
+import type { SqlTaggedTemplate } from "agents/chat";
+
+export interface PendingSteer {
+  steerId: string;
+  submissionId: string;
+  messageId: string;
+  canonicalJson: string;
+  uiMessageJson: string | null;
+  createdAt: number;
+}
+
+type PendingSteerRow = {
+  steer_id: string;
+  submission_id: string;
+  message_id: string;
+  canonical_json: string;
+  ui_message_json: string | null;
+  created_at: number;
+};
+
+function mapRow(row: PendingSteerRow): PendingSteer {
+  return {
+    steerId: row.steer_id,
+    submissionId: row.submission_id,
+    messageId: row.message_id,
+    canonicalJson: row.canonical_json,
+    uiMessageJson: row.ui_message_json,
+    createdAt: row.created_at,
+  };
+}
+
+export class SteerRepository {
+  constructor(private readonly sql: SqlTaggedTemplate) {}
+
+  insert(steer: PendingSteer): void {
+    this.sql`
+      INSERT INTO pi_pending_steers (
+        steer_id, submission_id, message_id, canonical_json,
+        ui_message_json, created_at
+      ) VALUES (
+        ${steer.steerId}, ${steer.submissionId}, ${steer.messageId},
+        ${steer.canonicalJson}, ${steer.uiMessageJson}, ${steer.createdAt}
+      )
+    `;
+  }
+
+  listForSubmission(submissionId: string): PendingSteer[] {
+    return this.sql<PendingSteerRow>`
+      SELECT steer_id, submission_id, message_id, canonical_json,
+             ui_message_json, created_at
+      FROM pi_pending_steers
+      WHERE submission_id = ${submissionId}
+      ORDER BY created_at ASC, rowid ASC
+    `.map(mapRow);
+  }
+
+  findByMessageId(messageId: string): PendingSteer | null {
+    const row = this.sql<PendingSteerRow>`
+      SELECT steer_id, submission_id, message_id, canonical_json,
+             ui_message_json, created_at
+      FROM pi_pending_steers
+      WHERE message_id = ${messageId}
+    `[0];
+    return row ? mapRow(row) : null;
+  }
+
+  deleteByMessageId(messageId: string): void {
+    this.sql`
+      DELETE FROM pi_pending_steers
+      WHERE message_id = ${messageId}
+    `;
+  }
+}

package/src/db/submission.repo.ts

@@ -0,0 +1,323 @@
+import type { SqlTaggedTemplate } from "agents/chat";
+
+// Submission 的统一定义见 ./index.ts。
+// #region 状态与行类型
+export type SubmissionStatus =
+  | "pending"
+  | "running"
+  | "completed"
+  | "aborted"
+  | "skipped"
+  | "error";
+
+const TERMINAL_SUBMISSION_STATUSES: ReadonlySet<SubmissionStatus> = new Set([
+  "completed",
+  "aborted",
+  "skipped",
+  "error",
+]);
+
+// 判断 Submission 是否已经结束。
+// Runtime、SubmissionLifecycle 和 ApprovalLifecycle 在决定是否继续执行、等待或接受审批时调用。
+// 终态集合收口在一处防止各生命周期的判断漂移；增加状态时必须先确认它是否真的不可再继续。
+export function isTerminalSubmissionStatus(
+  status: SubmissionStatus,
+): boolean {
+  return TERMINAL_SUBMISSION_STATUSES.has(status);
+}
+
+export interface StoredSubmission {
+  submissionId: string;
+  requestId: string;
+  idempotencyKey: string | null;
+  status: SubmissionStatus;
+  accepted: boolean;
+  error: string | null;
+  createdAt: number;
+  completedAt: number | null;
+  assemblyRevision: string;
+  assemblyDescriptor: string;
+  assistantMessageId: string;
+  abortReason: string | null;
+  queuedInputJson: string | null;
+  queuedUiMessageJson: string | null;
+  userMessageId: string | null;
+  regenerateMessageId: string | null;
+}
+
+export interface NewSubmission {
+  submissionId: string;
+  requestId: string;
+  idempotencyKey: string | null;
+  createdAt: number;
+  assemblyRevision: string;
+  assemblyDescriptor: string;
+  assistantMessageId: string;
+  queuedInputJson?: string | null;
+  queuedUiMessageJson?: string | null;
+  userMessageId?: string | null;
+  regenerateMessageId?: string | null;
+}
+
+type SubmissionRow = {
+  submission_id: string;
+  request_id: string;
+  idempotency_key: string | null;
+  status: string;
+  accepted: number;
+  error: string | null;
+  created_at: number;
+  completed_at: number | null;
+  assembly_revision: string;
+  assembly_descriptor: string;
+  assistant_message_id: string;
+  abort_reason: string | null;
+  queued_input_json: string | null;
+  queued_ui_message_json: string | null;
+  user_message_id: string | null;
+  regenerate_message_id: string | null;
+};
+
+// #endregion
+// #region 行映射
+// 把 SQLite 的 Submission 行转成 Runtime 对象。
+// find 查到记录后调用，所有其他查询方法通过 find 共用这个映射。
+// SQLite 用 0/1 存 accepted，状态则由表内字符串转成联合类型；新增列时必须同步核对类型、SELECT 和映射。
+function mapRow(row: SubmissionRow): StoredSubmission {
+  return {
+    submissionId: row.submission_id,
+    requestId: row.request_id,
+    idempotencyKey: row.idempotency_key,
+    status: row.status as SubmissionStatus,
+    accepted: row.accepted === 1,
+    error: row.error,
+    createdAt: row.created_at,
+    completedAt: row.completed_at,
+    assemblyRevision: row.assembly_revision,
+    assemblyDescriptor: row.assembly_descriptor,
+    assistantMessageId: row.assistant_message_id,
+    abortReason: row.abort_reason,
+    queuedInputJson: row.queued_input_json,
+    queuedUiMessageJson: row.queued_ui_message_json,
+    userMessageId: row.user_message_id,
+    regenerateMessageId: row.regenerate_message_id,
+  };
+}
+
+// #endregion
+// #region Repository
+export class SubmissionRepository {
+  // 保存当前 Agent SQLite 的查询入口。
+  // RuntimeDatabase 构造时调用，SubmissionLifecycle 和 Runtime 随后共享这个 Repository。
+  // Submission 的准入、执行和恢复必须看同一 Agent 存储，不能混入其他 Durable Object 的 sql。
+  constructor(private readonly sql: SqlTaggedTemplate) {}
+
+  // 按 submissionId 读取一条完整 Submission，不存在时返回 null。
+  // Runtime 和 SubmissionLifecycle 在准入、执行、取消、结束与恢复时调用，调用方必须处理 null。
+  // 所有列在这里一次投影并统一映射，不能让不同调用方各自拼出不完整的 Submission。
+  find(id: string): StoredSubmission | null {
+    const row = this.sql<SubmissionRow>`
+      SELECT submission_id, request_id, idempotency_key, status, accepted,
+             error, created_at, completed_at, assembly_revision,
+             assembly_descriptor, assistant_message_id, abort_reason,
+             queued_input_json, queued_ui_message_json, user_message_id,
+             regenerate_message_id
+      FROM pi_submissions
+      WHERE submission_id = ${id}
+    `[0];
+    return row ? mapRow(row) : null;
+  }
+
+  // 先按对外 requestId 找到 Submission，再返回完整记录。
+  // SubmissionLifecycle 用它合并重复请求和按请求停止任务，Runtime 也用它处理客户端事件。
+  // request_id 有 UNIQUE 约束，先取主键再复用 find 可以保持唯一映射路径。
+  findByRequestId(requestId: string): StoredSubmission | null {
+    const id = this.sql<{ submission_id: string }>`
+      SELECT submission_id FROM pi_submissions
+      WHERE request_id = ${requestId}
+    `[0]?.submission_id;
+    return id ? this.find(id) : null;
+  }
+
+  // 先按幂等键找到 Submission，再返回完整记录。
+  // SubmissionLifecycle 在准入前和等待稳定时调用，重试应复用已有 Submission 而不是重复执行。
+  // idempotency_key 有 UNIQUE 约束作为最终防线，不能把它降级为普通非唯一字段。
+  findByIdempotencyKey(key: string): StoredSubmission | null {
+    const id = this.sql<{ submission_id: string }>`
+      SELECT submission_id FROM pi_submissions
+      WHERE idempotency_key = ${key}
+    `[0]?.submission_id;
+    return id ? this.find(id) : null;
+  }
+
+  // 计算当前还在排队或运行的 Submission 数量。
+  // SubmissionLifecycle 在准入新 Turn、查询忙碌状态和等待稳定时调用。
+  // 持久化计数能跨 Durable Object 重启保留真实状态，不能换成只反映当前进程的内存标志。
+  countUnfinished(): number {
+    return (
+      this.sql<{ count: number }>`
+        SELECT COUNT(*) AS count FROM pi_submissions
+        WHERE status IN ('pending', 'running')
+      `[0]?.count ?? 0
+    );
+  }
+
+  countPending(): number {
+    return (
+      this.sql<{ count: number }>`
+        SELECT COUNT(*) AS count FROM pi_submissions
+        WHERE status = 'pending'
+      `[0]?.count ?? 0
+    );
+  }
+
+  findRunning(): StoredSubmission | null {
+    const id = this.sql<{ submission_id: string }>`
+      SELECT submission_id FROM pi_submissions
+      WHERE status = 'running'
+      LIMIT 1
+    `[0]?.submission_id;
+    return id ? this.find(id) : null;
+  }
+
+  findNextPending(): StoredSubmission | null {
+    const id = this.sql<{ submission_id: string }>`
+      SELECT submission_id FROM pi_submissions
+      WHERE status = 'pending'
+      ORDER BY created_at ASC, rowid ASC
+      LIMIT 1
+    `[0]?.submission_id;
+    return id ? this.find(id) : null;
+  }
+
+  listPending(): StoredSubmission[] {
+    return this.sql<{ submission_id: string }>`
+      SELECT submission_id FROM pi_submissions
+      WHERE status = 'pending'
+      ORDER BY created_at ASC, rowid ASC
+    `.flatMap((row) => {
+      const submission = this.find(row.submission_id);
+      return submission ? [submission] : [];
+    });
+  }
+
+  // 用固定的初始状态写入一条新 Submission。
+  // Runtime 在 SubmissionLifecycle 的准入事务中调用，调用方只提供本次请求确定的数据。
+  // pending 和 accepted=1 是准入契约，不能交给任意调用方选择而绕过生命周期。
+  insert(s: NewSubmission): void {
+    this.sql`
+      INSERT INTO pi_submissions (
+        submission_id, request_id, idempotency_key, status, accepted,
+        created_at, assembly_revision, assembly_descriptor,
+        assistant_message_id, queued_input_json, queued_ui_message_json,
+        user_message_id, regenerate_message_id
+      ) VALUES (
+        ${s.submissionId},
+        ${s.requestId},
+        ${s.idempotencyKey ?? null},
+        'pending',
+        1,
+        ${s.createdAt},
+        ${s.assemblyRevision},
+        ${s.assemblyDescriptor},
+        ${s.assistantMessageId},
+        ${s.queuedInputJson ?? null},
+        ${s.queuedUiMessageJson ?? null},
+        ${s.userMessageId ?? null},
+        ${s.regenerateMessageId ?? null}
+      )
+    `;
+  }
+
+  pinAssembly(id: string, revision: string, descriptor: string): boolean {
+    const updated = this.sql<{ submission_id: string }>`
+      UPDATE pi_submissions
+      SET assembly_revision = ${revision},
+          assembly_descriptor = ${descriptor}
+      WHERE submission_id = ${id}
+        AND assembly_revision = ''
+        AND assembly_descriptor = ''
+        AND status IN ('pending', 'running')
+      RETURNING submission_id
+    `;
+    return updated.length === 1;
+  }
+
+  // 只在当前状态属于 from 时把 Submission 切换到 to，否则返回 false。
+  // SubmissionLifecycle 开始 Turn 时调用，调用方用返回值识别过期或重复的状态切换。
+  // Cloudflare SQLite 查询是同步的，两条语句之间不会让其他事件交错；UPDATE 再次带旧状态条件，不能去掉这层幂等保护。
+  transition(
+    id: string,
+    to: SubmissionStatus,
+    from: readonly SubmissionStatus[],
+  ): boolean {
+    if (from.length === 0) return false;
+    const row = this.sql<{ status: string }>`
+      SELECT status FROM pi_submissions WHERE submission_id = ${id}
+    `[0];
+    if (!row || !(from as readonly string[]).includes(row.status)) {
+      return false;
+    }
+    this.sql`
+      UPDATE pi_submissions
+      SET status = ${to}
+      WHERE submission_id = ${id}
+        AND status = ${row.status}
+    `;
+    return true;
+  }
+
+  clearQueuedPayload(id: string): void {
+    this.sql`
+      UPDATE pi_submissions
+      SET queued_input_json = NULL,
+          queued_ui_message_json = NULL,
+          regenerate_message_id = NULL
+      WHERE submission_id = ${id}
+    `;
+  }
+
+  // 把尚未结束的 Submission 写成终态，并记录错误与完成时间。
+  // Runtime 提交 Turn 的最终结果时调用，completedAt 主要供可重现的调用或测试传入。
+  // WHERE 排除所有终态来保留第一次结果；待确认：参数类型仍允许 pending/running，调用方当前只传终态。
+  updateTerminal(
+    id: string,
+    status: SubmissionStatus,
+    error?: string,
+    completedAt?: number,
+  ): void {
+    const ts = completedAt ?? Date.now();
+    this.sql`
+      UPDATE pi_submissions
+      SET status = ${status},
+          error = ${error ?? null},
+          completed_at = ${ts}
+      WHERE submission_id = ${id}
+        AND status NOT IN ('completed', 'aborted', 'skipped', 'error')
+    `;
+  }
+
+  // 给活跃 Submission 记录取消或停止原因。
+  // SubmissionLifecycle.cancel 在同一事务内写入终止意图前调用，执行中的 Turn 随后读取它。
+  // 只更新 pending/running 防止迟到的取消覆盖已结束记录，不能去掉状态条件。
+  updateAbortReason(id: string, reason: string): void {
+    this.sql`
+      UPDATE pi_submissions
+      SET abort_reason = ${reason}
+      WHERE submission_id = ${id}
+        AND status IN ('pending', 'running')
+    `;
+  }
+
+  // 返回所有标准会话消息到 Submission 的关联映射。
+  // Transcript.storedMessages 读取 Pi Session 分支时调用，它用 Map 为每条消息补回 submissionId。
+  // 关联表由 Pi Session 存储拥有，本方法只读不写；不能在 RuntimeDatabase.clearAll 中单独删它而破坏 Transcript 的所有权。
+  listMessageSubmissionLinks(): Map<string, string> {
+    const rows = this.sql<{
+      message_id: string;
+      submission_id: string;
+    }>`SELECT message_id, submission_id FROM pi_session_message_submission`;
+    return new Map(rows.map((r) => [r.message_id, r.submission_id] as [string, string]));
+  }
+}
+// #endregion