@sema-agent/server 7.9.0 → 7.11.0

package/dist/main.js

@@ -16,7 +16,7 @@ import { webSearchConfigFromEnv, createWebSearchBackend, setWebSearchBadPayloadO
 import { createAuthorizer, encodeCheckpointScope } from "./security.js";
 import { assertGateIntentServiceable, hasOperatorGateIntent } from "./approval.js";
 import { loadSkills } from "./capabilities/skills.js";
-import { GiteaClient } from "./capabilities/repo-tools.js";
+import { createRepoClient } from "./capabilities/repo-tools.js";
 import { buildScenarios, builtinScenarioDetails } from "./capabilities/scenarios.js";
 import { createHandsLaneRegistry, pickHandsRunner, withoutExecutionEnv } from "./capabilities/hands-lane.js";
 import { createLogger } from "./observability/logger.js";
@@ -43,13 +43,16 @@ import { createResolveSpec } from "./boot/resolve-spec.js";
 import { createParkedReviveInheritedGate } from "./boot/parked-revive-gate.js";
 import { startReapers } from "./boot/reapers.js";
 import { openStores } from "./boot/stores.js";
+import { runAdoptionBootScan } from "./boot/adoption.js";
 import { createBudgetAndTracing } from "./boot/budget-tracing.js";
+import { createRuleConsentLane } from "./rules-consent.js";
 import { createExecutionEnv } from "./boot/execution-env.js";
 import { createWorkflowOrchestration } from "./boot/workflow-orchestration.js";
 import { createLiveCoordinators } from "./boot/coordinators.js";
 import { createRuntimeCaps } from "./boot/runtime-caps.js";
-import { createRunnerDeps, createSharedRunnerDeps } from "./boot/runner-deps.js";
+import { createRunnerDeps, createRunnerDepsOnAsk, createSharedRunnerDeps } from "./boot/runner-deps.js";
 import { createOrgMemoryAdmissionWiring } from "./boot/org-memory.js";
+import { createSharedMemoryScopeAuthorizer } from "./shared-memory-scope-authorizer.js";
 import { createSessionFaces } from "./boot/session-faces.js";
 import { createLeaderFace } from "./boot/leader.js";
 import { assertStaticWiringConsistent } from "./http/routes/diagnostics.js";
@@ -168,9 +171,23 @@ async function main() {
     // design/158 A10:持久层装配搬到 src/boot/stores.ts(逐字)。⚠️ 该段就地归一 `config.sessionBackend`
     // 且承载三条 fail-loud 拒启断言 —— 位置即契约,理由见该文件头注。
     const { backend, storeBackendDegraded, memoryEngine, memorySyncCursors, rosterStore, backgroundAgentStore, taskAttachmentStore, mailboxStore, memoryExportBackend, memorySyncRunner, sessionStore, breakerState, usageWindowStore, } = await openStores({ config, logger, metrics, localRoot });
+    // design/183 I6(server 同族):**每副本 boot 必查**收编日志的在飞行 —— 续跑或响亮留痕,禁静默跳过。
+    // 位置:store 开完之后(要 backend)、任何路由装配之前(半迁移状态绝不带进服务期)。判据与「为什么
+    // 是续跑而不是拒启」见 boot/adoption.ts 顶注。
+    const adoptionBoot = await runAdoptionBootScan({ backend, logger });
+    if (adoptionBoot.scanned > 0 || adoptionBoot.error !== undefined) {
+        logger.info("adoption_boot_scan", { ...adoptionBoot });
+    }
     // design/158 A10:计费/追踪/预算装配搬到 src/boot/budget-tracing.ts(逐字;tracer 与 side-query 同 sink 实例的
     // 「同段构造」契约见该文件头注)。
     const { brain, pricing, counterDegradeHook, costQuota, modelUsageTracker, promptManifestTracker, fleetUsage, fleetLease, tracer, sideQueryAccounting, toolResultStore, sessionPolicyStore, fileSnapshotStore, } = createBudgetAndTracing({ config, logger, metrics, backend, breakerState });
+    // #154 车二:持久化权限规则店(core 5.18.0 design/179 + 5.22.0 design/182)。三面一束 —— 规则桶
+    // provider 上 `RunnerDeps.permissionRuleStore`(引擎据它铸 ruleSuggestions + 把 manifest 的
+    // `permissionRules.storeWired` 报成真),审批记录 + 导入票喂同意车道(HTTP 两口的属主)。
+    // 缺席(local 车道 / 无 backend)⇒ 诚实缺席:storeWired:false、帧上零候选、两口 501。
+    // 🔴 总开关在最前(codex round7 [high] 一):关 ⇒ 整条车道根本不装配(店/车道/帧键/两口一起消失)。
+    const permissionRuleStores = config.permissionRulesEnabled && backend ? backend.permissionRule() : undefined;
+    const ruleConsent = permissionRuleStores ? createRuleConsentLane(permissionRuleStores) : undefined;
     // design/158 A10:执行环境装配搬到 src/boot/execution-env.ts(逐字)。
     // ⚠️ 工厂装饰顺序=行为(scratchpad → worktree → SendUserFile 登记 → 附件物化最外层),见该文件头注。
     const { perTaskImage, sessionEnvSelection, perSessionCwd, setSessionCwd, setSessionShellEnv, executionEnvFactory, worktreeReap, sendUserFileTaskEnvs, lspManager, } = createExecutionEnv({ config, logger, metrics, taskAttachmentStore });
@@ -189,11 +206,25 @@ async function main() {
     const { sqlWorkflowRunStore, workflowNotifyJournal, workflowCompletionInbox, deliverWorkflowCompletion, workflowNotifyGate, fleetBus, workflowRunStore, workflowJournalStore, outcomeSink, workflowRecoverOpts, workflowAgentRegistry, subagentSteerRegistry, } = createWorkflowOrchestration({ config, logger, metrics, localRoot, backend, getRunStore: () => runStore });
     // design/158 A10:活体协调器 + SendUserFile 工具面搬到 src/boot/coordinators.ts(逐字;durableEnabled 的
     // 「必须早于 runnerDeps 求值」次序契约见该文件头注)。
-    const { elicitation, question, toolApproval, durableEnabled, streamApprovalGate, sendUserFileEmitter, sendFileLedger, sendUserFileToolSpec } = createLiveCoordinators({ config, logger, backend, sendUserFileTaskEnvs });
+    const { elicitation, question, toolApproval, durableEnabled, streamApprovalGate, sendUserFileEmitter, sendFileLedger, sendUserFileToolSpec } = createLiveCoordinators({ config, logger, backend, sendUserFileTaskEnvs, ruleConsent });
     // design/158 A10:per-principal caps 段搬到 src/boot/runtime-caps.ts(逐字)。
     const { principalCaps, centerRuntimeCapsResolver, runtimeCapsResolver } = createRuntimeCaps({ config, logger });
     // design/170 件A(#148 件3③):org 记忆准入装配(目录源三态选择+C12 能力探测,坏配置在此拒启动)。
     const orgMemoryAdmission = createOrgMemoryAdmissionWiring({ config, logger, metrics });
+    // design/177 —— org 共享记忆库(memory_list/memory_read + `/v1/shared-memory/*` 只读面)。
+    // 🔴 铸它的合取式是**唯一**的挂载条件,模型面与 HTTP 面共用:
+    //   ① SQL 供给面在场(`backend.sharedMemoryStore` —— local 车道诚实缺席,理由在 store-backend.ts);
+    //   ② org 折叠面在场(目录源)—— 没有成员性判据的共享读面只能全放或全拒,两个都比"这个面不存在"差。
+    // deployment-origin scope 只在**无租户边界**的部署里授予:多租户下一条部署级声明会同时授予每一个
+    // principal,那是跨租户读而不是配置便利(org-memory.ts 的 N2 同判)。择净在这一行,授权模块只忠实使用。
+    const sharedMemoryStore = orgMemoryAdmission.directory !== undefined
+        ? backend?.sharedMemoryStore?.(createSharedMemoryScopeAuthorizer({
+            directory: orgMemoryAdmission.directory,
+            deploymentScopes: config.requirePrincipal === true ? [] : orgMemoryAdmission.deploymentMemoryScopes,
+        }))
+        : undefined;
+    if (sharedMemoryStore)
+        logger.info("shared_memory_stores_enabled", { backend: backend?.kind });
     // 🔴 codex 复审(#196 finding-2b):`toolResultStore` 在**无 backend** 形下是 undefined,而 core 的
     // Runner 构造函数会在缺席时**每只各自私建**一份 `RunnerSharedToolResultStore`(runtask.js
     // `if (!this.deps.toolResultStore)`)。本部署有多只 Runner(主 / subRunner / hookAgent / #196 的两只无手
@@ -209,8 +240,10 @@ async function main() {
         config, logger, metrics, localRoot, promptSource: configCenter.promptSource, rosterStore, backgroundAgentStore, mailboxStore, usageWindowStore, brain,
         pricing, tracer, outcomeSink, elicitation, question, toolApproval, sessionStore, memoryEngine,
         memorySyncRunner, toolResultStore: runnerOffloadStore, sessionPolicyStore, runtimeCapsResolver, fileSnapshotStore,
+        permissionRuleStore: permissionRuleStores?.provider,
         executionEnvFactory, lspManager, fleetBus, deploymentHooks, workflowRunStore, workflowJournalStore,
         workflowAgentRegistry, workflowNotifyGate, workflowCompletionInbox, deliverWorkflowCompletion, orgMemoryAdmission,
+        sharedMemoryStores: sharedMemoryStore ? sharedMemoryStore : undefined,
         getRunStore: () => runStore,
     });
     const runner = new Runner(runnerDeps);
@@ -380,6 +413,7 @@ async function main() {
             sessionPolicyStore,
             usageWindowStore,
             orgMemoryAdmission,
+            sharedMemoryStores: sharedMemoryStore ? sharedMemoryStore : undefined, // design/177:与主 runner 同实例
         }),
         // ── 以下为 subRunner 差异键(不在共享基座;逐个有因)──────────────────────────────────────
         sessionStore: subRunnerSessions, // 子代转录=私有短 TTL fork 路由店,生命周期异于宿主 durable 店
@@ -570,7 +604,7 @@ async function main() {
     // 解析搬到 boot/config-center.ts(逐字)。⚠️ 位置即契约:loadSkills 之后、buildScenarios 之前 ——
     // LKG 落盘点必须晚于 skill 正文装载(F7/codex R26),plugins 让位判据要求 plugins 晚于 center 直发 skills。
     skills = await configCenter.applyCenterCapabilities(skills);
-    const repoClient = config.gitApiBaseUrl ? new GiteaClient(config.gitApiBaseUrl, config.gitApiToken) : undefined;
+    const repoClient = config.gitApiBaseUrl ? createRepoClient(config.gitApiKind, config.gitApiBaseUrl, config.gitApiToken) : undefined;
     // CC-parity: deployment-injected WebSearch backend (the leg core leaves open). Absent WEB_SEARCH_PROVIDER →
     // undefined → the default scenario doesn't assemble the WebSearch tool. The API key stays in the backend closure.
     const webSearchCfg = webSearchConfigFromEnv();
@@ -679,8 +713,14 @@ async function main() {
     // 「部署 ⊇ 操作员」两层完整链(design/181 件二收编;实现与全部理由在 boot/parked-revive-gate.ts,
     // 提出去的唯一理由是 main.ts 顶层 `void main()` 让那条腿的运行期语义在原地一格都钉不住)。
     // 构造条件逐字保持:裸 Agent 工具在场 ∧ 部署真开了 durable 审批。
+    // `approverSeat`:与 `RunnerDeps.onAsk` **同一个具名工厂**(单一属主,禁在此处手搓等价闭包)。core
+    // 5.22.0 起链条目的 `durableMandate` 位进了摘要,而该位的判据正是这只席位在不在场——两处若不同源,
+    // 赎回腿算出的摘要与 park 记的对不上,跨副本赎回整条腿被 pre-CAS 拒(见 parked-revive-gate.ts
+    // `mandatePostureOf`)。此处新铸的转发闭包与 runnerDeps 那只行为逐字相同(都只转 `toolApproval.ask`),
+    // 摘要只看在场性;仅 core 的 hook 席位去重按函数身份判,那一侧的身份未命中是**多筛一次**(core 自述
+    // 的保守方向),不是漏筛。
     const parkedReviveInheritedGate = parkedReviveTool && config.durableApproval
-        ? createParkedReviveInheritedGate({ config, question, approvalExemptionStore, logger, localRoot })
+        ? createParkedReviveInheritedGate({ config, question, approvalExemptionStore, logger, localRoot, approverSeat: createRunnerDepsOnAsk(toolApproval) })
         : undefined;
     // 场景详情:内建 details 必须在 overlay 合并【前】构建(探针要打纯内建工厂,不是被 center 顶掉的);
     // center details 随 overlay 同判定源盖同名——source 语义与 selectScenario 实际取用永一致(约定①)。
@@ -782,11 +822,17 @@ async function main() {
         approvalExemptionStore: approvalExemptionStore ? approvalExemptionStore : undefined, // decide remember="session" + list/revoke
         checkpointStore,
         sessionPolicyStore: sessionPolicyStore ? sessionPolicyStore : undefined, // E6 operator session-rule store (PUT/GET /v1/sessions/:id/policy)
+        ruleConsent, // #154 车二:CC settings 导入两口的属主(缺席 ⇒ 两口 501)
         // E19 cap: core's gate-split (1.134.0) REMOVED the isRemoteExecutionEnv skip — core now snapshots each
         // completed turn + restores on resumeAt for ANY ExecutionEnv when fileSnapshotStore is wired (captureManifest/
         // applyManifest run over any env's FileSystem ops; a 30s timeout bounds a slow remote walk). So rewind works for
         // host/e2b/k8s/ssh/adb/local-docker AND the in-process worker → advertise `rewindFiles` whenever the store is wired.
         fileSnapshotStore: fileSnapshotStore ? fileSnapshotStore : undefined,
+        // [3321] tool-results 读面(GET /v1/tasks/:id/tool-results/:ref)的数据源。传的是 **durable** 的那一只
+        // (`toolResultStore`,present ⇔ 有 store backend),**不是** Runner 侧的内存兜底 `runnerOffloadStore`:
+        // 无 backend 部署里那只是进程内的、跨副本读不到的,把它接上读面只会让调用方读到「有时有有时无」。
+        // undefined ⇒ 路由 404 同形(理由见 ServiceStoreDeps.toolResultStore 的头注)。
+        toolResultStore,
         taskAttachmentStore: taskAttachmentStore ? taskAttachmentStore : undefined, // D-1 上传/取回/删除三动词面
         // design/153 件3d(/decide parked 赎回腿):durable bg 行店 + boot 裸 Agent 工具,与 RunnerDeps/
         // scenarioDeps 同实例(claim/expire/consumeParkedFlip 作用于同一行)。任一缺席=分支不存在。
@@ -855,6 +901,9 @@ async function main() {
         // (`createOrgMemoryAdmissionWiring` 的产物),两面因此共享 TTL 缓存/退避窗/gen 高水位 —— 一个进程
         // 对「谁属于 org:acme」只有一个答案。缺席(无 center 且无 env 表)⇒ 策略面 `org:` 键仍 operator-only。
         orgMemoryDirectory: orgMemoryAdmission.directory,
+        // design/177:HTTP 只读面与模型面共用**同一个** provider 实例 —— 两面看到的库集合按定义一致,
+        // 不可能出现「壳能读到模型读不到的库」。缺席 ⇒ `/v1/shared-memory/*` 整域不挂载(见 server.ts 域头)。
+        sharedMemoryStore: sharedMemoryStore ? sharedMemoryStore : undefined,
         // sessionMirror 观测面(server 非执法端,论证在 ServiceDeps.sessionMirrorRuling):
         // 与 executionRuling 同车同缓存(零额外 center RTT);无 center/dry-run ⇒ 不接线,观测面暗、零行为差。
         sessionMirrorRuling: principalCaps

package/dist/observability/fail-open.d.ts

@@ -41,6 +41,14 @@ export declare const FAIL_OPEN_TAGS: {
         readonly cls: "F";
         readonly note: "`/v1/fleet/stream` 连接时快照的**近期终态行窗**(#189:引擎重启后 boot 判死的 workflow 行,pull 自 durable store)读失败或超预算(2s)⇒ 本次快照少这几行历史。放行的最坏后果=面板首屏看不到刚结束的 workflow(与本修之前的行为等同,不是新损失);真源不受影响(`GET /v1/workflows` 照常)。方向刻意 fail-open:一次慢查询不该把整条 SSE 的握手拖住——少几行是难看,连不上流是坏掉。";
     };
+    readonly "server.rules.rejected-prepare-row-left": {
+        readonly cls: "F";
+        readonly note: "被拒的 CC 导入 prepare(候选超帽)未能收掉 core 已落盘的那条 pending 审批记录。放行的最坏后果 = 共享库里留一条**永远没人要的** pending 行(零权限影响:没有票就兑不动它,而且它连确认都没过)。不留痕就没人知道清理面在漏,故记 F 类;真解是给 permission_rule_approval / permission_rule_ticket 加保留期清扫腿(已列后续件)。";
+    };
+    readonly "server.rules.ticket-claim-release-failed": {
+        readonly cls: "F";
+        readonly note: "CC 规则导入票的**认领回滚**失败(认领之后的某一步没成 ⇒ 本该把认领放回去,而这次放回本身也抛了)。放行的最坏后果 = 这张票留在已认领态、属主这一轮不能重试 —— 恰好等于加认领回滚**之前**的行为,不是新损失;票随 TTL 自然消失,属主重走一次 prepare 即可拿新票(导入按 core 的设计幂等:同一条规则再兑付只是同一个 dot 的重放)。方向上没有任何权限被放宽(规则**没有**落地才走到这条臂),故 F 类;必须留痕,否则「票为什么突然不能用了」在遥测里没有任何痕迹。";
+    };
     readonly "server.fleet.subscriber-callback-threw": {
         readonly cls: "F";
         readonly note: "fleet bus 某订阅回调抛错 ⇒ 该回调本帧作废,其余订阅方与发布方不受影响。隔离是承重的:扇出同步,修前异常会传回发布方 put/update 投影点,core 持久化 catch{} 且不推进 storeRev ⇒ durable 行冻在 running 而 notify 已 ack(#183 复审 R3 HIGH)。丢的只是一个消费方的一帧渲染,故 F 类;但必须留痕——静默吞掉等于订阅方病灶永不显形。";

package/dist/observability/fail-open.js

@@ -64,6 +64,14 @@ export const FAIL_OPEN_TAGS = {
         cls: "F",
         note: "`/v1/fleet/stream` 连接时快照的**近期终态行窗**(#189:引擎重启后 boot 判死的 workflow 行,pull 自 durable store)读失败或超预算(2s)⇒ 本次快照少这几行历史。放行的最坏后果=面板首屏看不到刚结束的 workflow(与本修之前的行为等同,不是新损失);真源不受影响(`GET /v1/workflows` 照常)。方向刻意 fail-open:一次慢查询不该把整条 SSE 的握手拖住——少几行是难看,连不上流是坏掉。",
     },
+    "server.rules.rejected-prepare-row-left": {
+        cls: "F",
+        note: "被拒的 CC 导入 prepare(候选超帽)未能收掉 core 已落盘的那条 pending 审批记录。放行的最坏后果 = 共享库里留一条**永远没人要的** pending 行(零权限影响:没有票就兑不动它,而且它连确认都没过)。不留痕就没人知道清理面在漏,故记 F 类;真解是给 permission_rule_approval / permission_rule_ticket 加保留期清扫腿(已列后续件)。",
+    },
+    "server.rules.ticket-claim-release-failed": {
+        cls: "F",
+        note: "CC 规则导入票的**认领回滚**失败(认领之后的某一步没成 ⇒ 本该把认领放回去,而这次放回本身也抛了)。放行的最坏后果 = 这张票留在已认领态、属主这一轮不能重试 —— 恰好等于加认领回滚**之前**的行为,不是新损失;票随 TTL 自然消失,属主重走一次 prepare 即可拿新票(导入按 core 的设计幂等:同一条规则再兑付只是同一个 dot 的重放)。方向上没有任何权限被放宽(规则**没有**落地才走到这条臂),故 F 类;必须留痕,否则「票为什么突然不能用了」在遥测里没有任何痕迹。",
+    },
     "server.fleet.subscriber-callback-threw": {
         cls: "F",
         note: "fleet bus 某订阅回调抛错 ⇒ 该回调本帧作废,其余订阅方与发布方不受影响。隔离是承重的:扇出同步,修前异常会传回发布方 put/update 投影点,core 持久化 catch{} 且不推进 storeRev ⇒ durable 行冻在 running 而 notify 已 ack(#183 复审 R3 HIGH)。丢的只是一个消费方的一帧渲染,故 F 类;但必须留痕——静默吞掉等于订阅方病灶永不显形。",

package/dist/plugins/adoption-log-sql.d.ts

@@ -0,0 +1,191 @@
+/**
+ * design/183 I2(form b 位)—— **SQL 收编日志**:phase 真源与被迁的行**同库**。
+ *
+ * 🔴 为什么 phase 必须住 SQL 而不是一个 sidecar 文件(183 r3 按 codex r2-F2):发起收编的那个 pod 在两条
+ * 腿之间被摧毁时,进程本地的标记会与已经半迁移的 SQL 状态**分家** —— 接棒副本读不到「迁到哪了」。
+ * 标记与行同事务 ⇒ 崩溃后接棒副本按日志续跑,分家形不存在。
+ *
+ * ── 幂等身份 = DB 约束,不是「查了再插」(小票 v2/F2)────────────────────────────────────────────
+ * `from_principal` 上有 **UNIQUE**(183 D7「拒二次收编」的 DB 强形)。发起走 **insert-or-fetch 原子形**:
+ * 一条 `INSERT … ON CONFLICT DO NOTHING` / `INSERT IGNORE`,再按 `from_principal` 读回行。
+ * **禁 SELECT-then-INSERT** —— 那两句之间的窗正是两个并发同参 POST 各插一行(或各读到空)的地方,
+ * 而 UNIQUE 让「谁插进去了」由数据库仲裁,`affected` 就是判别式。
+ * 同 from 异 to ⇒ 读回的行 `to_principal` 不等 ⇒ typed conflict(调用方看到的是 409,不是「成功」)。
+ *
+ * ── 列的口径 ────────────────────────────────────────────────────────────────────────────────────
+ *  · `legs` / `configs` / `report` 是 **TEXT 不是 JSON 列**:`report` 是 `immutableReport` 的落库形,
+ *    契约是「逐字节恒同」;JSON 列会按引擎自己的规范形重排键序,而 TEXT 是「存什么读什么」。
+ *    (workflow_run.run / workflow_journal.result 同款先例,理由同源:String()→JSON.parse 的字节面。)
+ *  · 时间列一律 `_ms BIGINT`(schema-naming 门 ② 咬 `_at BIGINT`)。
+ *  · `phase` 是**单调**推进的阶段号,不是乐观锁计数 —— 但它的推进走的就是 CAS(`WHERE phase = :expect`),
+ *    所以它同时是那把锁。命名不叫 `rev`,因为它不守卫「行内容有没有变」,而守卫「弧走到哪了」。
+ */
+import type { Pool as MySqlPool } from "mysql2/promise";
+import type { Pool as PgPool } from "pg";
+import { type SqlDriver, type SqlExec, type SqlTxConn } from "./sql-driver.js";
+import type { AdoptionRejectCode } from "../adoption/wire.js";
+export declare const ADOPTION_LOG_TABLE = "adoption_log";
+/** 弧的阶段(183 §3.2 根级状态机的 form b 投影)。**单调**,只增不减。 */
+export declare const ADOPTION_PHASE: {
+    /** ② 意图已落库(行在,尚未动任何数据行)。 */
+    readonly INTENT: 2;
+    /** ③ 身份轴重绑腿全部完成(与腿的 UPDATE **同一个事务**)。 */
+    readonly REBOUND: 3;
+    /** ④ 解析切换 / 配置清单产出。form b 的 server 半场:配置账已物化进 `configs`。 */
+    readonly CONFIGS: 4;
+    /** ⑤ 承运腿。**form b 恒零承运**(数据本来就在 SQL)—— 阶段位仍显式推进,好让 form a 上车时挂得上。 */
+    readonly CARRIED: 5;
+    /** ⑥ 永久终态。 */
+    readonly TERMINAL: 6;
+};
+export type AdoptionState = "in_flight" | "adopted" | "rejected";
+export interface AdoptionRow {
+    adoptionId: string;
+    fromPrincipal: string;
+    toPrincipal: string;
+    phase: number;
+    state: AdoptionState;
+    /** `AdoptionLeg[]` 的 JSON 文本(phase 3 与腿同事务落库,此后不改)。 */
+    legsJson: string;
+    /** `AdoptionConfigEntry[]` 的 JSON 文本(phase 4 落库;见证位后续可更新)。 */
+    configsJson: string;
+    /** `AdoptionReport` 的 JSON 文本;`null` = 尚未终态。**落库后逐字节不变**(183 I4)。 */
+    reportJson: string | null;
+    rejectCode: string | null;
+    rejectDetail: string | null;
+    createdAtMs: number;
+    updatedAtMs: number;
+}
+export interface NewAdoptionRow {
+    adoptionId: string;
+    fromPrincipal: string;
+    toPrincipal: string;
+    nowMs: number;
+}
+/** `INSERT … ON CONFLICT DO NOTHING` 之后按 `from_principal` 读回的结果。`inserted` 只有真插进去的那一
+ *  路为 true —— 并发同参 POST 里恰有一条为 true,其余全 false 且拿到**同一行**。 */
+export interface EnsureAdoptionResult {
+    row: AdoptionRow;
+    inserted: boolean;
+}
+/**
+ * 收编日志的**消费面接口**。真实现只有 {@link SqlAdoptionLogStore} 一个(双方言);抽出接口是为了让
+ * 协议层(`adoption/runner.ts`)只依赖行为而不依赖那个带 `protected db` 的类 —— 后者是**名义类型**,
+ * 测试想给一个结构等价的假店都做不到,于是「弧的状态机」与「SQL 文本」这两件事只能一起测,
+ * 两个变量同时动的实验没有判别力。
+ */
+export interface AdoptionLogStore {
+    /** 池级只读执行面(**不在弧锁下**的读用它:锁外的现势查询、boot 扫描的名单)。 */
+    readonly reader: SqlExec;
+    ensureAdoption(row: NewAdoptionRow): Promise<EnsureAdoptionResult>;
+    /**
+     * 🔴 每个弧内方法都收一个 `exec`(codex R3-F2):弧锁**占着一条池连接**,如果弧内的读/事务再去池里
+     * 要第二条,`connectionLimit=1` 的部署会当场死锁(而 boot 的在飞扫描跑在 listen 之前 ⇒ 副本起不来)。
+     * 收编弧因此**全程单连接**:锁、preflight 读、腿的事务、phase CAS,全在 `withLock` 交出来的那一条上。
+     */
+    getById(adoptionId: string, exec?: SqlExec): Promise<AdoptionRow | null>;
+    getByFrom(fromPrincipal: string, exec?: SqlExec): Promise<AdoptionRow | null>;
+    listInFlight(exec?: SqlExec): Promise<AdoptionRow[]>;
+    /** 在**给定连接**上跑腿 + phase CAS(不自己 connect —— 见 getById 的注)。 */
+    rebindOn<L>(conn: SqlTxConn, adoptionId: string, expectPhase: number, nextPhase: number, nowMs: number, work: (exec: SqlExec) => Promise<L[]>, encodeLegs: (legs: L[]) => string): Promise<{
+        ok: true;
+        legs: L[];
+    } | {
+        ok: false;
+        reason: "phase_moved";
+    }>;
+    /** 终态后的迟到行清扫,同样在给定连接上。 */
+    sweepOn<T>(conn: SqlTxConn, work: (exec: SqlExec) => Promise<T>): Promise<T>;
+    advancePhase(adoptionId: string, expectPhase: number, nextPhase: number, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    putConfigs(adoptionId: string, expectPhase: number, nextPhase: number, configsJson: string, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    finalizeAdopted(adoptionId: string, expectPhase: number, reportJson: string, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    finalizeRejected(adoptionId: string, code: AdoptionRejectCode, detail: string, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    /** 取弧锁并把**那一条连接**交给回调(整条弧都跑在它上面)。`undefined` = 没取到锁。 */
+    withLock<T>(name: string, fn: (conn: SqlTxConn) => Promise<T>, attempts?: number, sleepMs?: number): Promise<T | undefined>;
+}
+/** MySQL 协议方言的建表语句(展开进 tidb-pool 的中央 `SCHEMA_STATEMENTS`,与 approval-ask 同姿势:
+ *  跟着中央 ensureSchema 在 named-lock 的那条 conn 上建,不绕开 DDL 串行化)。 */
+export declare const TIDB_ADOPTION_LOG_STATEMENTS: readonly string[];
+/** PostgreSQL 孪生(由 `ensurePgSchema` 在 advisory lock 的那条 client 上调用)。 */
+export declare function ensurePgAdoptionLogSchema(q: (text: string, params?: unknown[]) => Promise<unknown>): Promise<void>;
+/**
+ * 弧锁的名字。**定长**(前缀 14 + 32 位十六进制 = 46 字符)。
+ *
+ * 🔴 为什么必须 hash 而不是把 principal 直接拼进去(codex R3-F3,亲核属实):TiDB/MySQL 的 `GET_LOCK`
+ * 锁名上限是 **64 字符**,而请求面收的 principal 到 190 —— 超过 50 字符的源身份会让取锁**在弧动起来
+ * 之前**就失败,而那时意图行已经落库,于是每一次重发、每一次副本 boot 续跑都确定性地再撞一次同一堵墙。
+ * (PG 那条腿本来就走 hash 出来的 int4 对象键,这里只是把 MySQL 腿补齐到同一姿势。)
+ */
+export declare function adoptionLockName(fromPrincipal: string): string;
+/**
+ * 收编日志店(单文件双方言,SqlDriver 形——checkpoint-store / approval-ask-store 同款)。
+ *
+ * 每条语句的两方言文本**并排写在调用点**(A12 判据:方言差异必须显式,不许用占位符编号循环拼)。
+ */
+export declare class SqlAdoptionLogStore implements AdoptionLogStore {
+    protected readonly db: SqlDriver;
+    constructor(db: SqlDriver);
+    private q;
+    /** 池级只读执行面(phase 0 的 preflight 扫描用——它**零写**,不需要也不该占一条事务连接)。
+     *  写路径一律走 {@link rebindTransaction};把驱动整个暴露出去会让调用方能绕开 phase CAS。 */
+    get reader(): SqlExec;
+    /**
+     * 发起腿的 **insert-or-fetch 原子形**。返回读回的行(可能是别人插的)+ 是否本次插入。
+     * 调用方据 `row.toPrincipal !== toPrincipal` 判「同 from 异 to」⇒ typed 409。
+     */
+    ensureAdoption(row: NewAdoptionRow): Promise<EnsureAdoptionResult>;
+    getById(adoptionId: string, exec?: SqlExec): Promise<AdoptionRow | null>;
+    getByFrom(fromPrincipal: string, exec?: SqlExec): Promise<AdoptionRow | null>;
+    /** I6 server 同族:每副本 boot 必查的在飞名单(**响亮**,不静默跳过)。 */
+    listInFlight(exec?: SqlExec): Promise<AdoptionRow[]>;
+    /**
+     * 迁移事务:腿的全部 UPDATE **与** phase CAS 落在**同一个事务**里。
+     *
+     * 🔴 为什么必须同事务(而不是「先迁完再推 phase」):两句分开就留下一个窗 —— 腿提交了、phase 没推,
+     * 崩溃后接棒副本重跑腿(幂等,零行变化)却把**首次的行数读数**丢了,回执里的 `legs` 会变成一串 0。
+     * 同事务之后这个窗根本不存在:要么「行迁了且 phase=3 且 legs 读数在」,要么什么都没发生。
+     * 任何异常(含唯一键违例 = 跨轴组合冲突)⇒ ROLLBACK ⇒ **源/目的地两侧字节零变更**。
+     */
+    rebindOn<L>(conn: SqlTxConn, adoptionId: string, expectPhase: number, nextPhase: number, nowMs: number, work: (exec: SqlExec) => Promise<L[]>, encodeLegs: (legs: L[]) => string): Promise<{
+        ok: true;
+        legs: L[];
+    } | {
+        ok: false;
+        reason: "phase_moved";
+    }>;
+    /**
+     * 终态**之后**的迟到行清扫事务(无 phase 变更 —— phase 已经是终态,而终态是永久的)。
+     *
+     * 🔴 它不是「再收编一次」:腿本身幂等,清扫只是把收编**结束后**又落到旧身份下的行(配置未随迁的
+     * 部署会持续制造它们)一并搬过去,并让 `current.residualSourceRows` 有个能归零的动作。
+     * `immutableReport` 一个字节都不动(史实与现势分家,183 §6)。
+     */
+    sweepOn<T>(conn: SqlTxConn, work: (exec: SqlExec) => Promise<T>): Promise<T>;
+    /** 单调 CAS 推进(无数据写的阶段;`false` = 别人已经推过了/相位不符 ⇒ 调用方重读行)。 */
+    advancePhase(adoptionId: string, expectPhase: number, nextPhase: number, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    /** phase 4:配置账物化(与 phase 推进同一条语句,免得账落了相位没推)。 */
+    putConfigs(adoptionId: string, expectPhase: number, nextPhase: number, configsJson: string, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    /**
+     * ⑥ 终态:`report` 一次写入,`state='adopted'`。
+     * 🔴 `AND report IS NULL` 是 I4(永久终态 + 不可变史实)的**数据库强形**:即使调用序漂了,快照也
+     * 不可能被第二次写盖掉 —— 「逐字节恒同」于是不依赖调用方自觉。
+     */
+    finalizeAdopted(adoptionId: string, expectPhase: number, reportJson: string, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    /** 目的地冲突 ⇒ rejected 终态(源/目的地两侧字节零变更;phase 停在 INTENT)。 */
+    finalizeRejected(adoptionId: string, code: AdoptionRejectCode, detail: string, nowMs: number, exec?: SqlExec): Promise<boolean>;
+    /**
+     * 收编弧的 advisory 锁(183 I1 的 form b 形:「与任何活写互斥」在 SQL 侧 = 一次只有一个副本在推这条弧)。
+     *
+     * **非阻塞取 + 有界轮询**(tidb-pool 的 `acquireEnsureSchemaLock` 同款判据:阻塞式 GET_LOCK 会把并发
+     * 调用方全部park 在 TiDB 的悲观锁行上,既耗它的重试预算又饿死应用自己的 FOR UPDATE 路)。取不到 ⇒
+     * 返回 `undefined`,调用方按「在飞」应答 —— **不假装成功,也不无限等**。
+     */
+    withLock<T>(name: string, fn: (conn: SqlTxConn) => Promise<T>, attempts?: number, sleepMs?: number): Promise<T | undefined>;
+}
+export declare class TiDBAdoptionLogStore extends SqlAdoptionLogStore {
+    constructor(pool: MySqlPool);
+}
+export declare class PgAdoptionLogStore extends SqlAdoptionLogStore {
+    constructor(pool: PgPool);
+}
+//# sourceMappingURL=adoption-log-sql.d.ts.map