@sema-agent/server 7.50.0 → 7.52.0

package/dist/plugins/memory-run-store.d.ts

@@ -71,8 +71,9 @@ export declare class MemoryRunStore {
     setSuspended(taskId: string): Promise<void>;
     /** design/80 D-B: park NON-terminal `needs_review`, KEEP the claim. CAS on running/needs_review. */
     setNeedsReview(taskId: string): Promise<void>;
-    /** Durable F4 resume: flip suspended/needs_review → running (CAS) + reset cancel/preempt flags. */
-    markResuming(taskId: string): Promise<boolean>;
+    /** Durable F4 resume: flip suspended/needs_review → running (CAS) + reset cancel/preempt flags.
+     *  S-51(codex R1 [medium]):认领 = 接管 `instanceId`(= 当前持有副本;SQL 孪生同注)。CAS 输不改。 */
+    markResuming(taskId: string, instanceId: string): Promise<boolean>;
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     getRun(taskId: string): Promise<RunRecord | undefined>;
     /** Runs newest-first, keyset on (createdAt, taskId) DESC; optional exact-match filters (owner is exact, like the SQL). */
@@ -140,7 +141,7 @@ export declare class MemoryRunStore {
      * probe instead of a SQL JOIN (formerly a NO-OP, which was one of the five closed doors in the "suspended run
      * locks the session forever" incident). Semantics verbatim from the SQL twin: suspended ∧ updatedAt < cutoff
      * ∧ NOT probe.hasPending(session) → failed 'approval expired before decision' / error_code 'approval.expired'
-     * + release the task_active claim. The NOT-pending clause is the design/80 D-D adversarial-blocker guard
+     * + release the task_active claim. The NOT-pending clause is the design/80 D-D blocker guard
      * (SQL 孪生现在的真身:`run-store-sql.ts` 的 `reapSuspended`;`tidb-run-store.ts` 该壳文件已删(5.0.0)): a row whose checkpoint is STILL pending belongs to the checkpoint-state
      * sweeps (SLA deny-sweep / failSuspendedWithExpiredCheckpoint) — time-reaping it here would orphan a model
      * leg on a now-unlocked session. Probe absent ⇒ honest NO-OP (never kill a park without the guard).

package/dist/plugins/memory-run-store.js

@@ -133,11 +133,12 @@ export class MemoryRunStore {
             r.updatedAt = new Date();
         }
     }
-    async markResuming(taskId) {
+    async markResuming(taskId, instanceId) {
         const r = this.runs.get(taskId);
         if (!r || (r.status !== "suspended" && r.status !== "needs_review"))
             return false;
         r.status = "running";
+        r.instanceId = instanceId;
         r.cancelRequested = false;
         r.preemptRequested = false;
         r.updatedAt = new Date();

package/dist/plugins/permission-rule-store-file.d.ts

@@ -1,5 +1,5 @@
 import { FilePermissionRuleStoreProvider, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleScope, type StaleRuleApprovalRecord } from "@sema-agent/core";
-import { type RuleImportTicket, type RuleTicketDecisionClock, type RuleTicketRedeemResult } from "./permission-rule-store-sql.js";
+import { type RuleImportTicket, type RuleTicketDecisionClock, type RuleTicketPurpose, type RuleTicketReclaimResult, type RuleTicketRedeemResult, type RuleTicketSnapshot } from "./permission-rule-store-sql.js";
 import type { PermissionRuleStoreBundle } from "../rules-consent.js";
 /**
  * `RuleApprovalRecordStore` 的 File 形。
@@ -44,18 +44,28 @@ export declare class FileRuleImportTicketStore {
         ticketId: string;
         principal: string;
         approvalId: string;
+        purpose: RuleTicketPurpose;
         candidates: ReadonlyArray<{
             rule: string;
             scope: RuleScope;
         }>;
         ttlMs: number;
     }): Promise<RuleImportTicket>;
-    /** 一次性**认领**。四条否定项的判序与 SQL 形逐字相同(unknown → wrong-principal → consumed → expired),
-     *  于是两形的服务端日志归因可比;wire 面把四类折成同一个 404(零存在性 oracle)。 */
-    consume(ticketId: string, principal: string, opts?: RuleTicketDecisionClock): Promise<RuleTicketRedeemResult>;
+    /** 一次性**认领**。五条否定项的判序与 SQL 形逐字相同(unknown → wrong-principal → wrong-purpose →
+     *  consumed → expired),于是两形的服务端日志归因可比;wire 面把五类折成同一个 404(零存在性 oracle)。 */
+    consume(ticketId: string, principal: string, purpose: RuleTicketPurpose, opts?: RuleTicketDecisionClock): Promise<RuleTicketRedeemResult>;
     /** 把认领**放回去**。`mustRemainValidMs` = 放回之后至少还要能用多久 —— 撑不过就不算放回成功
-     *  (理由逐字见 SQL 侧 `release` 的头注:承诺一次必然兑现不了的重试比不承诺更坏)。 */
-    release(ticketId: string, principal: string, mustRemainValidMs?: number, opts?: RuleTicketDecisionClock): Promise<boolean>;
+     *  (理由逐字见 SQL 侧 `release` 的头注:承诺一次必然兑现不了的重试比不承诺更坏)。
+     *  `claimId` = A7 的认领围栏(R1-F1):被顶替的旧持有者动不了现持有者的认领。 */
+    release(ticketId: string, principal: string, claimId: string, mustRemainValidMs?: number, opts?: RuleTicketDecisionClock): Promise<boolean>;
+    /** #265 A7 CLAIMED → **SETTLED**。判据与 SQL 孪生逐字同源(持有**这一代**认领 ∧ 未落定;过期
+     *  **刻意不设门** —— 理由逐字见 SQL 侧 `settle` 的头注:拒绝记录一件已经发生的事只会把真相丢掉)。 */
+    settle(ticketId: string, principal: string, claimId: string, outcome: unknown): Promise<boolean>;
+    /** #265 A7 三态快照。属主门与车道门同源(别人的票 / 别条车道的票 / 不存在的票一律 `undefined`)。 */
+    peek(ticketId: string, principal: string, purpose: RuleTicketPurpose): Promise<RuleTicketSnapshot | undefined>;
+    /** #265 A7 崩溃窗恢复:抢过一次**可证陈旧**的认领(判据与 SQL 孪生逐字同源 —— 含"过期刻意不设门"
+     *  那一条:过期只挡开始一次兑付,不挡做完一次已经开始的)。抢到之后**换一代认领**。 */
+    reclaim(ticketId: string, principal: string, purpose: RuleTicketPurpose, minClaimAgeMs: number): Promise<RuleTicketReclaimResult>;
 }
 /** local 车道的三面束 + 生命周期。`dispose()` 释放 core File provider 的写锁(见 {@link createFilePermissionRuleStores})。 */
 export interface FilePermissionRuleStores extends PermissionRuleStoreBundle {

package/dist/plugins/permission-rule-store-file.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { randomUUID } from "node:crypto";
 import { readdirSync } from "node:fs";
 import { FilePermissionRuleStoreProvider, AppendLog, ensureDir, readJsonlRecords, } from "@sema-agent/core";
 import { z } from "zod";
@@ -92,11 +93,14 @@ const TicketLineSchema = z.union([
         approvalId: z.string().min(1),
         payloadHash: z.string().min(1),
         expiresAtMs: z.number().int().nonnegative().safe(),
+        purpose: z.enum(["cc-import", "local-import"]).optional(),
     })
         .strict(),
-    z.object({ op: z.literal("consume"), ticketId: z.string().min(1), atMs: z.number().int().nonnegative().safe() }).strict(),
+    z.object({ op: z.literal("consume"), ticketId: z.string().min(1), atMs: z.number().int().nonnegative().safe(), claimId: z.string().min(1).optional() }).strict(),
     z.object({ op: z.literal("release"), ticketId: z.string().min(1) }).strict(),
+    z.object({ op: z.literal("settle"), ticketId: z.string().min(1), outcome: z.unknown() }).strict(),
 ]);
+const LEGACY_TICKET_PURPOSE = "cc-import";
 class CorruptionGate {
     face;
     path;
@@ -204,16 +208,35 @@ export class FileRuleImportTicketStore {
             }
             const line = parsed.data;
             if (line.op === "mint") {
-                this.rows.set(line.ticketId, { ownerKey: line.ownerKey, approvalId: line.approvalId, payloadHash: line.payloadHash, expiresAtMs: line.expiresAtMs });
+                this.rows.set(line.ticketId, {
+                    ownerKey: line.ownerKey,
+                    approvalId: line.approvalId,
+                    payloadHash: line.payloadHash,
+                    purpose: line.purpose ?? LEGACY_TICKET_PURPOSE,
+                    expiresAtMs: line.expiresAtMs,
+                });
                 continue;
             }
             const row = this.rows.get(line.ticketId);
             if (row === undefined)
                 continue;
-            if (line.op === "consume")
-                row.consumedAtMs = line.atMs;
-            else
-                delete row.consumedAtMs;
+            switch (line.op) {
+                case "consume":
+                    row.consumedAtMs = line.atMs;
+                    row.claimId = line.claimId ?? `legacy-claim-${randomUUID()}`;
+                    break;
+                case "release":
+                    delete row.consumedAtMs;
+                    delete row.claimId;
+                    break;
+                case "settle":
+                    row.outcome = line.outcome;
+                    break;
+                default: {
+                    const unknown = line;
+                    this.gate.trip(`a replayed ticket line carries an unknown op: ${JSON.stringify(unknown)}`);
+                }
+            }
         }
         this.log = new AppendLog(path);
     }
@@ -228,37 +251,78 @@ export class FileRuleImportTicketStore {
         this.gate.assertUsable();
         const expiresAtMs = this.now() + input.ttlMs;
         const payloadHash = buildRulePayloadHash(input.candidates);
-        this.log.append({ op: "mint", ticketId: input.ticketId, ownerKey: input.principal, approvalId: input.approvalId, payloadHash, expiresAtMs }, true);
-        this.rows.set(input.ticketId, { ownerKey: input.principal, approvalId: input.approvalId, payloadHash, expiresAtMs });
+        this.log.append({ op: "mint", ticketId: input.ticketId, ownerKey: input.principal, approvalId: input.approvalId, payloadHash, purpose: input.purpose, expiresAtMs }, true);
+        this.rows.set(input.ticketId, { ownerKey: input.principal, approvalId: input.approvalId, payloadHash, purpose: input.purpose, expiresAtMs });
         return { ticketId: input.ticketId, approvalId: input.approvalId, payloadHash, expiresAtMs };
     }
-    async consume(ticketId, principal, opts) {
+    async consume(ticketId, principal, purpose, opts) {
         this.gate.assertUsable();
         const row = this.rows.get(ticketId);
         if (row === undefined)
             return { ok: false, reason: "unknown" };
         if (row.ownerKey !== principal)
             return { ok: false, reason: "wrong-principal" };
+        if (row.purpose !== purpose)
+            return { ok: false, reason: "wrong-purpose" };
         if (row.consumedAtMs !== undefined)
             return { ok: false, reason: "consumed" };
         const stampMs = this.now();
         if (row.expiresAtMs <= (opts?.decisionNowMs ?? stampMs))
             return { ok: false, reason: "expired" };
-        this.log.append({ op: "consume", ticketId, atMs: stampMs }, true);
+        const claimId = randomUUID();
+        this.log.append({ op: "consume", ticketId, atMs: stampMs, claimId }, true);
         row.consumedAtMs = stampMs;
-        return { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash };
+        row.claimId = claimId;
+        return { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash, claimId };
     }
-    async release(ticketId, principal, mustRemainValidMs = 0, opts) {
+    async release(ticketId, principal, claimId, mustRemainValidMs = 0, opts) {
         this.gate.assertUsable();
         const row = this.rows.get(ticketId);
-        if (row === undefined || row.ownerKey !== principal || row.consumedAtMs === undefined)
+        if (row === undefined || row.ownerKey !== principal || row.consumedAtMs === undefined || row.claimId !== claimId || row.outcome !== undefined)
             return false;
         if (row.expiresAtMs <= (opts?.decisionNowMs ?? this.now()) + mustRemainValidMs)
             return false;
         this.log.append({ op: "release", ticketId }, true);
         delete row.consumedAtMs;
+        delete row.claimId;
+        return true;
+    }
+    async settle(ticketId, principal, claimId, outcome) {
+        this.gate.assertUsable();
+        const row = this.rows.get(ticketId);
+        if (row === undefined || row.ownerKey !== principal || row.consumedAtMs === undefined || row.claimId !== claimId || row.outcome !== undefined)
+            return false;
+        this.log.append({ op: "settle", ticketId, outcome }, true);
+        row.outcome = outcome;
         return true;
     }
+    async peek(ticketId, principal, purpose) {
+        this.gate.assertUsable();
+        const row = this.rows.get(ticketId);
+        if (row === undefined || row.ownerKey !== principal || row.purpose !== purpose)
+            return undefined;
+        if (row.outcome !== undefined)
+            return { state: "settled", outcome: row.outcome };
+        if (row.consumedAtMs === undefined)
+            return { state: "minted" };
+        return { state: "claimed", claimAgeMs: Math.max(0, this.now() - row.consumedAtMs) };
+    }
+    async reclaim(ticketId, principal, purpose, minClaimAgeMs) {
+        this.gate.assertUsable();
+        const row = this.rows.get(ticketId);
+        if (row === undefined || row.ownerKey !== principal || row.purpose !== purpose)
+            return { ok: false };
+        if (row.consumedAtMs === undefined || row.claimId === undefined || row.outcome !== undefined)
+            return { ok: false };
+        const stampMs = this.now();
+        if (stampMs - row.consumedAtMs < minClaimAgeMs)
+            return { ok: false };
+        const claimId = randomUUID();
+        this.log.append({ op: "consume", ticketId, atMs: stampMs, claimId }, true);
+        row.consumedAtMs = stampMs;
+        row.claimId = claimId;
+        return { ok: true, approvalId: row.approvalId, payloadHash: row.payloadHash, claimId };
+    }
 }
 export function createFilePermissionRuleStores(root, opts) {
     const dir = join(root, "permission-rules");

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import { type PermissionRuleWriter, type PermissionRuleStore, type PermissionRuleStoreProvider, type RuleScope, type RuleSyncFrontier, type RuleApprovalRecord, type StaleRuleApprovalRecord, type RuleApprovalRecordStore, type RuleOwner } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { PgQueryFn } from "./pg-query.js";
@@ -13,6 +14,16 @@ import { type SqlDriver } from "./sql-driver.js";
  * 也是三份会各自漂的形状假设。
  */
 export declare function writerOfSqlRuleStore(store: PermissionRuleStore): PermissionRuleWriter | undefined;
+/**
+ * 382P1(core 7.0.0 design/382 §4.3)—— 这是 **DURABLE 二员面**的 at-rest 形:`{global, project-with-root}`,
+ * 与 core `isValidDurableScope` 逐格等价(`test/permission-rule-durable-face-pin.test.ts` 探针表钉住)。
+ * `RuleScope` 联合自 v7 起有第三员 `session`,但它**结构上**不许进持久店(家在会话 overlay,随会话死):
+ * at-rest 解码不认它 ⇒ 一条被外部写进来的 session 行整桶拒读(fail-closed),写臂另由 core 的
+ * `assertWriteDeltaScopeDurable` 在任何 DB 往返之前以典型码拒(见 `apply`)。consent 面(三员)归
+ * engine/cli 半场;本仓 wire 入口 `parseRuleScope` 只拼二员,所以审批记录的候选也用这张表(下方
+ * `RuleCandidateSchema`)——那是本仓自己的窄型收口,不是把两张表合成一张。
+ */
+export declare const DurableRuleScopeSchema: z.ZodType<RuleScope>;
 export declare const PERMISSION_RULE_TABLE = "permission_rule";
 export declare const PERMISSION_RULE_APPROVAL_TABLE = "permission_rule_approval";
 export declare const PERMISSION_RULE_TICKET_TABLE = "permission_rule_ticket";
@@ -35,7 +46,7 @@ export declare const TIDB_PERMISSION_RULE_STATEMENTS: readonly string[];
  *  本函数留给只需要这三张表的集成测试)。 */
 export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise<void>;
 /**
- * #340 升级前置断言 —— **拒启**,不是 warn(codex 对抗复审 [high],验真后修;形照 #119 的
+ * #340 升级前置断言 —— **拒启**,不是 warn(codex 交叉复审 [high],验真后修;形照 #119 的
  * `assertToolResultProvenanceSchema` 先例)。
  *
  * 病:本仓不发 `ALTER TABLE` 迁移(SCHEMA POLICY:改列就改 CREATE + 删库重建)。于是一台**没删表**就升
@@ -51,7 +62,7 @@ export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise
  * 判据用**能力探测**而不是版本号/information_schema:发一条恒空的 `WHERE 1=0` 读,列不在就报错。
  * 只判「两列在不在」,不判宽度(两列都是 TEXT 族,没有截断轴)。
  *
- * 🔴 **只有可证的缺列才给破坏性指路**(codex 对抗复审 round2/round3 [high],两轮收窄后的终形):
+ * 🔴 **只有可证的缺列才给破坏性指路**(codex 交叉复审 round2/round3 [high],两轮收窄后的终形):
  * 「探针失败」**不等于**「列不在」。超时、连接被重置、取消、资源不足、列级权限被拒、表整个不存在 ——
  * 每一种都会让这条读抛错,而把它们诊断成「去 DROP TABLE」是一条**会真的毁掉审计记录**的建议(比它要
  * 挡的缺陷更贵)。round2 的两步探(先读一列老列)也不够:两次读之间同样可以插进一次瞬时故障。
@@ -70,6 +81,29 @@ export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise
 export declare function assertPermissionRuleApprovalSchema(query: (sql: string) => Promise<{
     rows: Record<string, unknown>[];
 }>, dialect: "tidb" | "pg"): Promise<void>;
+/**
+ * #265 A7 升级前置断言 —— **拒启**(形与理由逐字照 {@link assertPermissionRuleApprovalSchema} 的配方,
+ * 那条头注写了这道门为什么必须是拒启而不是 warn:本仓不发 `ALTER TABLE`,`CREATE TABLE IF NOT EXISTS`
+ * 对存量表是空操作,而新列被**无条件**引用)。
+ *
+ * 病:一台没删表就升上来的部署,`permission_rule_ticket` 上没有 `redeemed_outcome` 列,而 A7 的三态
+ * 协议(`settle` / `peek` / `reclaim`)三条语句全都引用它。后果不是"少一个新功能":
+ *  · `POST /v1/rules/local-import/redeem` 的落定那一跳撞 unknown column ⇒ 票停在 CLAIMED 永不结算,
+ *    属主的重放只能拿到 409,一次人的确认就此卡死到票过期;
+ *  · 更坏的是它**只在兑付走完之后**才炸 —— 规则已经落进店了,而客户端拿到的是失败:一次**真实生效
+ *    的同意**被报成没发生。
+ * 所以判据放在启动期、拒启,而不是等第一位用户去踩。
+ *
+ * 判据同款:发一条恒空的 `WHERE 1=0` 读;**只有可证的缺列**才给破坏性指路(其余错误原样 rethrow ——
+ * 超时/连接重置/权限/表不在都会让这条读抛,把它们诊断成"去 DROP TABLE"是一条比缺陷更贵的建议)。
+ *
+ * 🔴 破坏性指路的代价在本表上**比审批表小得多**,文案照实说:票是分钟级 TTL 的治理瞬态(过期即死),
+ * 删表最多让**正在预览、还没按确认**的那几个人重走一次 prepare;持久规则在 `permission_rule` 里,
+ * 一行都不动。
+ */
+export declare function assertPermissionRuleTicketSchema(query: (sql: string) => Promise<{
+    rows: Record<string, unknown>[];
+}>, dialect: "tidb" | "pg"): Promise<void>;
 export declare function ensurePgPermissionRuleSchema(q: PgQueryFn): Promise<void>;
 /**
  * 一只桶的**存储键**(纯数据 ⇒ `build*`)。
@@ -137,15 +171,28 @@ export interface RuleImportTicket {
     payloadHash: string;
     expiresAtMs: number;
 }
-/** 消费结果。**四种拒绝合并成一个 `refused` 形**是刻意的:调用点把它们全部翻成同一个 404,
- *  于是「这张票不存在」「它是别人的」「它过期了」「它已经用过了」在 wire 上不可区分(禁存在性 oracle)。 */
+/**
+ * #265 A7 —— 一张票是**哪条导入车道**铸的(codex 交叉轮 R1-F2,验真后修)。
+ *
+ * 🔴 闭集且**不可变**:两条车道共用这张表,而它们的票语义刻意不同(cc-import 一次性 / local-import
+ * 可恢复三态)。票不带这一位时,两条车道的兑付口互相**可以吃对方的票** —— 那不是"多一条路",那是让
+ * 一条车道的语义在**另一条车道的代码里**被改掉。铸票时定,此后每一次读写都拿它当匹配项。
+ */
+export type RuleTicketPurpose = "cc-import" | "local-import";
+/** 消费结果。**五种拒绝合并成一个 `refused` 形**是刻意的:调用点把它们全部翻成同一个 404,
+ *  于是「这张票不存在」「它是别人的」「它是另一条车道的」「它过期了」「它已经用过了」在 wire 上
+ *  不可区分(禁存在性 oracle)。
+ *
+ *  `claimId` = 本次认领的**代次**(A7 围栏,R1-F1):`release`/`settle` 必须原样递回来,于是一个被
+ *  顶替的旧持有者动不了现持有者的认领。 */
 export type RuleTicketRedeemResult = {
     ok: true;
     approvalId: string;
     payloadHash: string;
+    claimId: string;
 } | {
     ok: false;
-    reason: "unknown" | "wrong-principal" | "expired" | "consumed";
+    reason: "unknown" | "wrong-principal" | "wrong-purpose" | "expired" | "consumed";
 };
 /**
  * [4232]③/[4235]③ —— 票的**判定钟**覆写(记账钟永远不覆写,见 `consume` 内注)。
@@ -157,6 +204,43 @@ export type RuleTicketRedeemResult = {
 export interface RuleTicketDecisionClock {
     decisionNowMs?: number;
 }
+/**
+ * #265 A7 —— 一张票的**三态快照**(MINTED → CLAIMED → SETTLED)。
+ *
+ * 🔴 判别式联合而不是"一个态字符串 + 两个可选字段":三个态各自带的东西**互不相干**,而消费方对三者
+ * 要做的事完全不同(首兑 / 判租约 / 逐字回放)。塌成一个可选包会让"已落定却读不出终局"这种矛盾态
+ * 变得可表达 —— 而那正是本协议最不能出错的地方(回放不出终局 = 要么重跑一次已经跑过的兑付,要么
+ * 对属主说一次谎)。
+ *
+ * `claimAgeMs` 由**店自己**用它的记账钟算,不交给调用方去减:认领戳(`consumed_at_ms`)是真墙钟,
+ * 而车道手里那只是单调投影 —— 两只钟不在同一个域,跨域相减出来的"年龄"没有意义(本仓 [4232]③ 的
+ * 教训:两只钟必须分家,谁的问题谁的钟答)。
+ */
+export type RuleTicketSnapshot = {
+    state: "minted";
+} | {
+    state: "claimed";
+    claimAgeMs: number;
+} | {
+    state: "settled";
+    outcome: unknown;
+};
+/**
+ * #265 A7 —— 抢认领的结果。赢家拿回**票上那两样不可变的东西**(`approval_id` / `payload_hash`),
+ * 与 {@link RuleTicketRedeemResult} 的成功臂同形:抢到认领之后要做的事与首次认领之后**一模一样**
+ * (读记录 → 载荷比对 → 走批),所以两条路必须交出同一份素材,否则恢复臂就得自己再发一条读 ——
+ * 而"认领之后还有一次可能失败的 I/O"正是本仓 round4 修掉的那个形。
+ *
+ * 拒绝臂**不分类**:没抢到只有一个处置(继续等/让客户端稍后再来),分类只会诱导调用方去猜。
+ */
+export type RuleTicketReclaimResult = {
+    ok: true;
+    approvalId: string;
+    payloadHash: string;
+    claimId: string;
+} | {
+    ok: false;
+};
 /**
  * [4232]③ 同族的 **GC 宽限**:`reapExpired` 只收「按墙钟至少已死一个完整 TTL」的票行。
  *
@@ -169,6 +253,23 @@ export interface RuleTicketDecisionClock {
  * ——这正是 core 建议的姿态(「接受 + 票廉价重铸」)。
  */
 export declare const RULE_IMPORT_TICKET_GC_GRACE_MS: number;
+/**
+ * #265 A7 —— **数据库自己的钟**(毫秒),两方言各一句(codex 交叉轮 R5-F1,验真后修)。
+ *
+ * 用处:`settled_at_ms` 的写入与清扫「已落定」那一支的截止**必须在同一个钟域**。它们此前各拿各副本的
+ * 墙钟:落定那台若比跑清扫那台慢过一个宽限(本仓 [4232]③ 记过一次真实的 11 分钟 NTP 纠正),一份**刚刚**
+ * 生出来的权威回执下一拍就被删,而"落定之后必有一个完整的回放窗"是本批新许下的承诺 —— 它不能建立在
+ * 「两台机器的钟差不多」这条没人声明过的假设上。数据库的钟是这两台副本**唯一**共享的那口钟。
+ *
+ * 🔴 射程**刻意只到这一支**:票的其余三列(`expires_at_ms` / `consumed_at_ms` / `created_at_ms`)仍在
+ * 既有的副本墙钟域里 —— 那是 cc-import 车道的**既存已登记残余**([4232]③,收口方向逐字见
+ * `rules-consent.ts` 的 anchors 头注),把它一并搬走会改动两条车道共用的认领谓词,不在本批射程。
+ * 这一句同时也是那次收口的**样板**:形已经在这里了,下一批照抄即可。
+ */
+export declare const SQL_DB_NOW_MS: {
+    readonly tidb: "CAST(UNIX_TIMESTAMP(NOW(3)) * 1000 AS SIGNED)";
+    readonly pg: "(EXTRACT(EPOCH FROM clock_timestamp()) * 1000)::bigint";
+};
 /** prepare 时刻候选集的规范摘要(载荷绑定 F1 ④ 的判据)。纯数据 ⇒ `build*`。 */
 export declare function buildRulePayloadHash(candidates: ReadonlyArray<{
     rule: string;
@@ -183,6 +284,7 @@ export declare class SqlRuleImportTicketStore {
         ticketId: string;
         principal: string;
         approvalId: string;
+        purpose: RuleTicketPurpose;
         candidates: ReadonlyArray<{
             rule: string;
             scope: RuleScope;
@@ -204,7 +306,7 @@ export declare class SqlRuleImportTicketStore {
      * expired/consumed 四类给服务端日志;wire 面把四类折成同一个 404)。预读说「可以」而 UPDATE 命中零行,
      * 只可能是我们在这两跳之间输给了一个并发认领者 —— 如实报 `consumed`,而不是把这次失败当成成功。
      */
-    consume(ticketId: string, principal: string, opts?: RuleTicketDecisionClock): Promise<RuleTicketRedeemResult>;
+    consume(ticketId: string, principal: string, purpose: RuleTicketPurpose, opts?: RuleTicketDecisionClock): Promise<RuleTicketRedeemResult>;
     /**
      * **认领的释放**(codex 交叉复审 round1 [high] 一,验真后修)。
      *
@@ -212,7 +314,7 @@ export declare class SqlRuleImportTicketStore {
      * 载荷比对、confirm+批量兑付。旧形把认领当终局 ⇒ 一次数据库抖动就让票**永久**烧掉,而调用方拿到的
      * 是与「票不存在」同形的 404:重试无门、最终状态对客户端不可判。
      *
-     * ⇒ 认领之后**只有裁定性拒绝**才留着消费位(载荷被篡改、记录不存在 —— 重试不改判);**不确定/瞬时**
+     * ⇒ 认领之后**只有裁定性拒绝**才留着消费位(载荷被改写、记录不存在 —— 重试不改判);**不确定/瞬时**
      * 的失败(store 抛错、CAS 冲突)把认领**放回去**,让属主重试。放回去不会打开双兑付的门:同一时刻
      * 只有一个持有者(认领本身仍是单条条件 UPDATE),而兑付腿(`redeemRuleBatch`)按 core 的设计是
      * **幂等**的(记录里存着每个候选已铸的 dot,重放只会重放同一个 dot)。
@@ -221,7 +323,53 @@ export declare class SqlRuleImportTicketStore {
      * 期间属主可以重新走 prepare 拿一张新票(导入是幂等的:同一条规则再兑付只是同一个 dot 的重放)。
      * 要彻底消灭它需要一条带租约到期的认领状态机,属协议改动,列为后续件。
      */
-    release(ticketId: string, principal: string, mustRemainValidMs?: number, opts?: RuleTicketDecisionClock): Promise<boolean>;
+    release(ticketId: string, principal: string, claimId: string, mustRemainValidMs?: number, opts?: RuleTicketDecisionClock): Promise<boolean>;
+    /**
+     * #265 A7 —— CLAIMED → **SETTLED**:把这一次兑付的终局写进行里。
+     *
+     * 🔴 判据全写在 `WHERE` 里(与 `consume` 同一条纪律,**禁 read-then-write**):必须**持有认领**
+     * (`consumed_at_ms IS NOT NULL`)且**尚未落定**(`redeemed_outcome IS NULL`)。两个写者同时到达时
+     * 恰一条 `affected === 1` —— 输者据此知道"别人已经答过了",去读那份终局回放,而不是把自己的那份
+     * 覆盖上去(覆盖 = 同一张票对两个客户端说了两句不同的话)。
+     *
+     * 🔴 **过期刻意不进 WHERE**(与 `consume`/`release` 相反,理由方向也相反):走已经发生了,规则可能
+     * 已经落进店里 —— 因为票在记录的这一刻恰好过期就拒绝记录它,只会把一份**已知的真相**丢掉,把
+     * 属主推回"不知道到底成没成"。过期管的是"还能不能**开始**兑付",不是"能不能**记下**已经发生的事"。
+     */
+    settle(ticketId: string, principal: string, claimId: string, outcome: unknown): Promise<boolean>;
+    /**
+     * #265 A7 —— 读一张票的三态。**principal 绑定**与四类拒同源:别人的票 / 不存在的票一律 `undefined`
+     * (调用方把它折成同一个 404,零存在性 oracle)。
+     *
+     * `claimAgeMs` 在**这里**算(店的记账钟),不交给调用方:见 {@link RuleTicketSnapshot} 的头注。
+     */
+    peek(ticketId: string, principal: string, purpose: RuleTicketPurpose): Promise<RuleTicketSnapshot | undefined>;
+    /**
+     * #265 A7 —— **崩溃窗恢复**:把一次**可证陈旧**的认领抢过来。
+     *
+     * 病:`consume` 之后、`settle` 之前硬崩,票停在 CLAIMED 且永远不会自己走完。旧形(cc-import)对这
+     * 一格没有答案 —— 票随 TTL 消失,人的确认丢掉;而 `release` 帮不上忙,它要求那个死掉的进程**还活着
+     * 去调它**。
+     *
+     * 判据同样全在 `WHERE` 里(恰一赢者):**这一代**认领仍在场 ∧ 未落定 ∧ 认领戳早于 now − minClaimAgeMs。
+     * `minClaimAgeMs` 由调用方给(车道的租约常数),而"多久算陈旧"这件事本身**只能**用记账钟判 ——
+     * 所以减法在这里做,与 {@link peek} 同源。
+     *
+     * 🔴 抢过来之后**换一代认领**(新戳 + 新 `claim_id`):租约从此刻起算,于是"抢的人自己也死了"这一形
+     * 同样有下一个恢复者;而新代次让被顶替的那一位从此 `release`/`settle` 都动不了这张票(R1-F1)。
+     * 重驱本身安全的理由在车道那侧(core 的批走是成员级幂等的)。
+     *
+     * 🔴 **过期刻意不进 WHERE**(codex 交叉轮 R1-F3,验真后改判)。第一版照 `consume` 抄了
+     * `expires_at_ms > now`,而那让"临期崩溃"这一整族**永远救不回来**:租约(分钟级)比 TTL(10 分钟)短,
+     * 持有者若在距过期不足一个租约时崩掉,认领**成熟之时票已过期** ⇒ 谁都抢不动,而车道对这一态答的是
+     * 「稍后拿同一张票再来」—— 一句必然兑现不了的承诺(本仓 `release` 的保守门正是为了不说这种话)。
+     * 更实的伤:那次崩溃可能已经把一半规则写进店了,属主却永远拿不到回执。
+     * 改判的语义是**过期只挡「开始」一次兑付,不挡「做完」一次已经开始的**:`consume` 的过期门一个字节
+     * 不动(一张从未被认领的过期票照旧是死的,外泄的票不会因此复活),而一张**已被属主认领过**的票代表
+     * 一次已经开始的兑付 —— 它的载荷仍被摘要锚定,做完它不多给任何东西。窗仍然有界:行随
+     * {@link RULE_IMPORT_TICKET_GC_GRACE_MS} 之外的保留期腿被收走,那就是成文的"回放窗 = 票行存续期"。
+     */
+    reclaim(ticketId: string, principal: string, purpose: RuleTicketPurpose, minClaimAgeMs: number): Promise<RuleTicketReclaimResult>;
     private readRow;
 }
 /**