@sema-agent/server 7.51.0 → 7.52.0

package/dist/rules-consent.d.ts

@@ -1,6 +1,6 @@
 import { type RuleOwner, type ImportPreview, type RedeemedBatchMember, type ImportedSettingsLayer, type PersistedAllowRule, type RemoveResult, type EditedRuleTextPrecheck, type RuleScope, type RuleOffer } from "@sema-agent/core";
 import type { PermissionRuleStoreProvider, RuleApprovalRecordStore } from "@sema-agent/core";
-import { type RuleImportTicket, type RuleTicketDecisionClock, type RuleTicketRedeemResult } from "./plugins/permission-rule-store-sql.js";
+import { type RuleImportTicket, type RuleTicketDecisionClock, type RuleTicketPurpose, type RuleTicketReclaimResult, type RuleTicketRedeemResult, type RuleTicketSnapshot } from "./plugins/permission-rule-store-sql.js";
 /**
  * 本车道**真正**依赖的三面(**结构**接口,不是 SQL 类)。
  *
@@ -22,6 +22,7 @@ export interface RuleConsentStores {
             ticketId: string;
             principal: string;
             approvalId: string;
+            purpose: RuleTicketPurpose;
             candidates: ReadonlyArray<{
                 rule: string;
                 scope: RuleScope;
@@ -29,11 +30,24 @@ export interface RuleConsentStores {
             ttlMs: number;
         }): Promise<RuleImportTicket>;
         /** 一次**认领**(不是「已完成」)。语义与「认领之后怎么办」见 {@link RuleConsentStores.tickets.release}。
+         *  `purpose` = 车道绑定(A7 R1-F2):一条车道的口只认它自己铸的票,不符与「票不存在」同形。
          *  `opts.decisionNowMs` = [4232]③ 的判定钟覆写(记账列不受影响),见 {@link RuleTicketDecisionClock}。 */
-        consume(ticketId: string, principal: string, opts?: RuleTicketDecisionClock): Promise<RuleTicketRedeemResult>;
-        /** 把认领**放回去**(认领之后遇到不确定/瞬时失败时)。`mustRemainValidMs` = 放回之后这张票至少还要
-         *  能用多久 —— 撑不过就**不算放回成功**(理由逐字见 store 侧 `release` 的头注)。 */
-        release(ticketId: string, principal: string, mustRemainValidMs?: number, opts?: RuleTicketDecisionClock): Promise<boolean>;
+        consume(ticketId: string, principal: string, purpose: RuleTicketPurpose, opts?: RuleTicketDecisionClock): Promise<RuleTicketRedeemResult>;
+        /** 把认领**放回去**(认领之后遇到不确定/瞬时失败时)。`claimId` = 本次认领的代次(A7 R1-F1 围栏:
+         *  被顶替的旧持有者动不了现持有者的认领);`mustRemainValidMs` = 放回之后这张票至少还要能用多久
+         *  —— 撑不过就**不算放回成功**(理由逐字见 store 侧 `release` 的头注)。 */
+        release(ticketId: string, principal: string, claimId: string, mustRemainValidMs?: number, opts?: RuleTicketDecisionClock): Promise<boolean>;
+        /**
+         * #265 A7 三态协议的三条口(CLAIMED → SETTLED / 三态快照 / 崩溃窗抢认领)。
+         *
+         * 🔴 **必填,不给 optional**:它们是 local-import 车道正确性的承重件 —— 一个"没有 settle 的店"上,
+         * 一次已经落地的导入会永远答不出终局(属主重放恒 409 到票过期)。把它们写成可选 = 让一台缺实现的
+         * 部署**静默**退化成那个形,而本仓对安全/权限轴的静默降级是明令禁止的。两个真实现(SQL / File)与
+         * 测试孪生各自实现同一份语义,缺一个当场编译红。
+         */
+        settle(ticketId: string, principal: string, claimId: string, outcome: unknown): Promise<boolean>;
+        peek(ticketId: string, principal: string, purpose: RuleTicketPurpose): Promise<RuleTicketSnapshot | undefined>;
+        reclaim(ticketId: string, principal: string, purpose: RuleTicketPurpose, minClaimAgeMs: number): Promise<RuleTicketReclaimResult>;
     };
 }
 /**
@@ -60,7 +74,7 @@ export interface PermissionRuleStoreBundle extends RuleConsentStores {
     reapExpired?(nowMs: number): Promise<number>;
 }
 /** 导入票的存活窗。人从「看到预览」到「按下确认」是一次交互,不是一段会话——十分钟宽到不会误伤,
- *  窄到一张泄漏的票不会常驻。运维旋钮暂不开(没有部署形要求它可调;要开时走 config.ts 的既有姿势)。 */
+ *  窄到一张外泄的票不会常驻。运维旋钮暂不开(没有部署形要求它可调;要开时走 config.ts 的既有姿势)。 */
 export declare const RULE_IMPORT_TICKET_TTL_MS: number;
 /** 可重试那一支通告给客户端的等待秒数(`state.rule_import_retry` 的 `retryAfterSec` / `Retry-After`)。
  *  短 —— 它对应的是一次瞬时 store 抖动,不是排队。**单一真源在本文件**:放回认领时要用它判「这张票
@@ -80,6 +94,177 @@ export declare const RULE_IMPORT_RETRY_AFTER_SEC = 2;
  * 「几百次 SQL」而不是「几万次」。
  */
 export declare const MAX_IMPORT_CANDIDATES = 200;
+/** 一批 local-import 的行数上限。**与 cc-import 同值同拒形**(413):帽住的是同一条东西 ——
+ *  `redeemRuleBatch` 那条**逐成员**「读店 + CAS 写」的串行循环(见 {@link MAX_IMPORT_CANDIDATES} 的
+ *  头注,理由一个字不变)。两处用同一个数不是巧合,是同一条论证的两个入口,所以直接派生而不是另挑一个。 */
+export declare const MAX_LOCAL_IMPORT_ROWS = 200;
+/**
+ * 一批 rows 的**总字节**上限(D5「防巨包」)。
+ *
+ * 为什么行数帽不够:行数管住的是**下游工作量**(那条串行循环的长度),管不住**单次请求的体积** ——
+ * 200 行 × (512 字规则 + 1088 字 scope + 512 字命令 + 一串出处回声)在纯算术上能到兆字节级,而这条口
+ * 是**已鉴权即可打**的写面。256 KiB 宽到装得下任何真实的规则店(一份人手养出来的规则集是几十条到几百
+ * 条一行的短串),窄到一次请求不能拿它当上传通道。超帽与行数超帽**同拒形**(413):对客户端来说处置
+ * 相同(把这批拆小再来),分成两个码只会让它多一条分支。
+ */
+export declare const MAX_LOCAL_IMPORT_BYTES: number;
+/**
+ * **认领租约**:一次认领持续超过这么久还没落定,就当持有它的那个进程**已经死了**(A7 崩溃窗恢复臂)。
+ *
+ * 三问答(CLAUDE.md 行为面条款):
+ *  · **谁要**:无状态多副本部署。`consume`(认领)与 `settle`(落定)之间隔着整条兑付走;副本在这中
+ *    间被杀/被驱逐/OOM 是常规运维事件,不是异常。没有这条租约,那张票就停在 CLAIMED 直到 TTL 到期
+ *    ——**人的确认凭空丢掉**,而客户端拿到的是一个永远重试不出结果的 409。
+ *  · **谁受伤**:一次**还活着**但走得特别慢的兑付,可能在租约到期后被第二条腿抢过去重驱 ⇒ 同一批被
+ *    两个走者同时走。这不是猜测出来的安全边界:core 的批走契约**逐字**写着「resuming a partial walk
+ *    IS re-walking … two concurrent walkers converge on one dot set, zero double mints」——重叠的代价
+ *    是多跑一遍同样的重放,不是重复落规则。
+ *  · **拿什么补**:取值远宽于一次真实的走(最坏 {@link MAX_LOCAL_IMPORT_ROWS} 次店往返),又远窄于
+ *    票的 TTL({@link RULE_IMPORT_TICKET_TTL_MS} = 10 分钟)—— 于是"崩了的票在它自己这一生里就能被
+ *    救回来",而不是等下一次 prepare。运维旋钮暂不开(没有部署形要求它可调)。
+ */
+export declare const LOCAL_IMPORT_CLAIM_LEASE_MS = 60000;
+/** 一条规则的 wire 身份键(规则文本 + {@link serializeRuleScope} 的判别式串)。两个面(预览 / 兑付回执)
+ *  用**同一把键**,客户端拿它把两张表 join 起来。 */
+export interface LocalImportRuleKey {
+    rule: string;
+    scope: string;
+}
+/**
+ * prepare 面的**成员级拒因**(闭集,机读)。
+ *
+ * 🔴 闭集而不是自由文本:客户端要按拒因分流(「这条是你本机的数据坏了」vs「这条规则本身不合法」是
+ * 两句不同的话),而自由文本只能被展示、不能被分支。`detail` 才是给人看的那一半。
+ */
+export type LocalImportRefusalCode = 
+/** scope 串读不出形(既不是 `global` 也不是 `project:<非空 root>`)。 */
+"scope_unreadable"
+/** scope 的 project root 里有 bidi 控制符([4537]② Trojan Source 族):人看到的射程与机器判据用的
+ *  射程不是同一串 —— 一条规则的**作用范围**因此可以被伪装。 */
+ | "scope_bidi_controls"
+/** scope 的 project root 里有 **C0/DEL 控制字节**(codex 交叉轮 R9,验真后补)。与 bidi 分家成两个词:
+ *  bidi 说的是"你看到的射程是假的",这个说的是"这串根本不是一条路径"。挡它有三条各自独立成立的理由:
+ *  ①**跨后端行为分岔** —— PG 的协议编码器直接拒 NUL(整条 prepare 变 500),而 TiDB/File 收得下同一行;
+ *  ②它把本层比较键的分隔符假设(见 {@link LOCAL_IMPORT_KEY_SEP} 的注:"路径里不可能出现它")变成假的
+ *  —— 去重与对账的键就此可被撞;③治理面的分页游标按 (scope, rule) 的串序做 keyset,控制字节会让那个
+ *  序不再是人以为的那个。 */
+ | "scope_control_chars"
+/** 规则文本过不了引擎的共享校验器,或它**不容纳它自称的那条命令**(覆盖门)。 */
+ | "rule_rejected"
+/** 文本门**答不了**这一行(引擎对调用方 bug 是抛,不是拒:命令缺席/非串)——那是行本身坏了,
+ *  不是"你写的规则被拒了",故单独成词。 */
+ | "rule_uncheckable"
+/** 行**自相矛盾**:规则文本解析出来的 tool/match/command 与行上自称的对不上。一行 File 店行的这三
+ *  格本该是从 `rule` 派生的事实,对不上 = 这一行是拼出来的,不是店里出来的。 */
+ | "row_inconsistent"
+/** 同一个 (rule, scope) 在这一批里出现了两次。引擎会静默去重 —— 静默去重会让"我交了 20 条,只回了
+ *  19 条"变成一次无解的差异,所以在这里如实说出来。 */
+ | "duplicate_row"
+/** 过了本层全部判据,却没能成为引擎的候选(= 本仓与 core 的判据分了家)。**响亮**而不是静默丢:
+ *  它意味着两侧的规则语法判据漂了,那是要人去看的事。 */
+ | "not_importable";
+/** 兑付面的**成员级终态**(闭集,机读;`detail` 是给人看的那一半)。
+ *
+ *  🔴 **`refused` 在本版的兑付面结构上到不了,这是如实登记而不是遗漏**:走到兑付这一步的成员,已经
+ *  在 prepare 过了全部内容判据 —— 于是 core 交回的 `refused` 行只剩店侧成因(读不出店 / 写面抛 / OCC
+ *  用尽),而那些**都是"不知道落没落"**,不是"这条规则不行"。core 的 `RedeemedBatchMember` 拒绝臂
+ *  只带一个**自由文本** `reason`,把它按串去猜「这是裁定还是瞬时」正是本仓明令禁止的自造判读,
+ *  所以一律落到 `indeterminate`(安全方向)。词留在表里是因为**两个面共用同一张词表**(预览面发的
+ *  正是它),而不是留一个死枝:客户端一套分支读得通两张表。收窄需要 core 给拒绝臂一个**带类型的**
+ *  瞬时/裁定判别位 —— 已作为上游请托登记(server 不在下游造第二份判据,[2862])。 */
+export type LocalImportMemberOutcome = 
+/** 这一次真的写进店里了。 */
+"persisted"
+/** 等价规则**已经在店**(引擎的 `deduped`)—— 同意早就生效,这次什么都不用做。 */
+ | "no-op"
+/** 这条被拒了(预览面的词;兑付面见上方登记)。 */
+ | "refused"
+/** **不知道落没落**:店在这一条上出了状况。如实编,禁猜(猜"成了"会谎报一次没发生的授权,猜"没成"
+ *  会让人以为可以重来一次,而重来会撞上一条其实已经存在的规则)。 */
+ | "indeterminate";
+/** `indeterminate` 的成因(闭集)。 */
+export type LocalImportIndeterminateCode = 
+/** 引擎在这一条上答了 refused,而拒因只有自由文本 ⇒ 落不了裁定,如实说"不知道"。 */
+"store_refused"
+/** 兑付走本身没走完(本层抛出/中断)⇒ 这一条连走都没走到。 */
+ | "walk_failed";
+/** prepare 面的一行。判别式联合:被收下的行**没有**拒因字段可读,被拒的行**必然**带拒因 ——
+ *  「admitted 却带 reason」这种矛盾态在类型上不可表达。 */
+export type LocalImportPreviewMember = {
+    key: LocalImportRuleKey;
+    admitted: true;
+} | {
+    key: LocalImportRuleKey;
+    admitted: false;
+    reason: LocalImportRefusalCode;
+    detail: string;
+};
+/** 兑付回执的一行。 */
+export interface LocalImportOutcomeMember {
+    key: LocalImportRuleKey;
+    outcome: LocalImportMemberOutcome;
+    reason?: LocalImportIndeterminateCode;
+    detail?: string;
+}
+/** 兑付回执整只 = **写进票行 `redeemed_outcome` 的逐字体**(回放同源:回放答的就是它)。 */
+export interface LocalImportOutcome {
+    members: readonly LocalImportOutcomeMember[];
+    /** 这只桶在兑付结束时的 OCC 版本(与 cc-import 的 `result.rev` 同义)。 */
+    rev: number;
+}
+/** A7 prepare 的产物。第二臂(`ticket` 整键缺席)= **零可导入行** —— 与 cc-import 的「预览无票」臂
+ *  同形同理由(没有可确认的对象,也就没有票;键缺席即答案,不编一个 null)。 */
+export type LocalImportPrepared = {
+    ok: true;
+    preview: {
+        members: readonly LocalImportPreviewMember[];
+    };
+    ticket: string;
+    expiresAtMs: number;
+} | {
+    ok: true;
+    preview: {
+        members: readonly LocalImportPreviewMember[];
+    };
+    ticket?: undefined;
+    expiresAtMs?: undefined;
+} | {
+    ok: false;
+    reason: "too-many-rows";
+    rows: number;
+} | {
+    ok: false;
+    reason: "batch-too-large";
+    bytes: number;
+};
+/** A7 redeem 的结果。 */
+export type LocalImportRedeemed = 
+/** `replayed` = 这份终局不是本次走出来的,是从票行里逐字读回来的(⑥ 丢响应重试那条路)。 */
+{
+    ok: true;
+    outcome: LocalImportOutcome;
+    replayed: boolean;
+}
+/** 四类票拒(不存在 / 别人的 / 过期 / 已用过而无从回放)—— wire 面同形 404。 */
+ | {
+    ok: false;
+    reason: "ticket-unusable";
+    detail: string;
+}
+/** 裁定性拒绝(记录不存在 / 形太旧 / 载荷被改写)。`retryable` 与 cc-import 同义。 */
+ | {
+    ok: false;
+    reason: "record-unusable" | "payload-mismatch";
+    detail: string;
+    retryable?: true;
+}
+/** 另一条腿**正持着**这张票在走,而它在有界等待窗里没走完 ⇒ 稍后再来(409)。**不驱不猜**:
+ *  抢一个还活着的持有者是拿"两个走者"去换"少等两秒",方向不对。 */
+ | {
+    ok: false;
+    reason: "in-flight";
+    detail: string;
+};
 /** 一次导入 prepare 的产物(HTTP 200 体的素材),或**超帽**的拒绝(见 {@link MAX_IMPORT_CANDIDATES})。
  *  5.58(design/375):零 importable 候选 ⇒ core **不铸** `approvalId`(「absence says so」)⇒ 无票可铸,
  *  第三臂把 preview(全 skipped 的理由就在里面)原样交给人看——不是错误,是「没有什么可确认」。 */
@@ -108,7 +293,7 @@ export type RuleImportRedeemed = {
     };
 }
 /** `retryable` = 这次失败**没有裁定任何事**(store 抛错 / CAS 冲突),认领已放回,属主原样重试即可。
- *  它与裁定性拒绝(载荷被篡改、记录不存在)分家是承重的:把两者塌成一格,一次数据库抖动就会被
+ *  它与裁定性拒绝(载荷被改写、记录不存在)分家是承重的:把两者塌成一格,一次数据库抖动就会被
  *  客户端读成「这张票永远不能用了」。⚠️ **wire 面仍然折成同一个 404**(零存在性 oracle 不因此松动);
  *  这一位只进服务端日志与本层的重试判据。 */
  | {
@@ -116,6 +301,19 @@ export type RuleImportRedeemed = {
     reason: "ticket-unusable" | "record-unusable" | "payload-mismatch";
     detail: string;
     retryable?: true;
+}
+/** #265 独立复审 件2(codex 轮二、轮三改形):首跳 `consume` 抛错后**结局歧义**的那一支 —— 认领
+ *  可能已提交而代次丢了,可能根本没提交,甚至可能**还在途、稍后才提交**(轮三 R3-F2:一次事后
+ *  peek 读到 MINTED 证明不了在途的写不会迟到落地,同一场店故障也常让 peek 一起挂)。终局宣布不了
+ *  (可能把活票说死),「票还能用」承诺不了(可能撒谎),断言「在途」也不行(那是冒充知道)——
+ *  唯一诚实的形是**独立的歧义响应**(503 `state.rule_ticket_unreadable`):只说「现在答不了,稍后
+ *  拿同一张票来读个诚实答案;届时若报 not found 就重新 prepare」。`retryable?: never`:这一臂
+ *  永远不许携重试承诺(它存在的全部意义就是不承诺),声明出来只为联合型上的读点可编译。 */
+ | {
+    ok: false;
+    reason: "state-unreadable";
+    detail: string;
+    retryable?: never;
 };
 export declare function precheckCardRuleText(text: string, command: string): EditedRuleTextPrecheck | undefined;
 export type CardRuleRedemption = 
@@ -206,7 +404,18 @@ export type CardRulePersisted = {
      * 各自有自己的词,不到这里)与「预检过了但记录级仍拒」的残余竞态。到这个词时那句老话仍然成立
      * ——卡已消费、同一把 approvalId 再回决是 404。
      */
-     | "edit-rejected";
+     | "edit-rejected"
+    /**
+     * core 7.0.0(#490② BREAKING B2,design/382 §4.4):silent-global 死——`prepareCardApproval`
+     * 在**既无显式 scope 又无 cwd**时响亮拒(`config.missing_scope`),不再默落 global。本仓的
+     * scope 素材=铸卡时 `ruleScopeRootFor` 咨询一次的落点(行列 `rule_scope_root`);resolver 答不出
+     * root 的车道(host lane 未注册 launch dir)在 v7 下就是这一形。**刻意不在兑付时刻补一个
+     * `process.cwd()`**:core 契约明写 cwd=被裁决调用的工作目录、never inferred from the process——
+     * server 进程的 cwd 不是那个坐标,编一个等于把规则锚到错误的射程上(比修前的 global 更糟)。
+     * 出路=部署接 `ruleScopeRootFor`(host lane 注册 launch dir),或调用方在回决体带显式 scope。
+     * 裁决本身照常生效(与全族同律:规则没存上不改判这次放行)。
+     */
+     | "scope-unresolved";
     detail: string;
     /** #345:core 的**共享校验器**refusal code(`RuleRejectCode`,开集透传)。覆盖门拒时**缺席** ——
      *  这条在场规则与 core `confirmRuleApproval` 的 `edit_rejected` detail 逐字同源(同一个函数体)。
@@ -252,9 +461,15 @@ export declare function serializeRuleScope(scope: RuleScope): string;
  * 的尺,撤侧自动跟。
  */
 export declare const MAX_RULE_SCOPE_CHARS: number;
+/** durable 面的**二员**窄型(core 7.0.0 design/382 §4.3:consent 面三员、durable 面二员分治)。
+ *  wire 判别式串只拼得出这两员(session 刻意无 wire 拼法——它的家在引擎的会话 overlay,不在持久店),
+ *  所以 parse 产物与本仓筛选行都钉在这个窄型上:`.root` 访问零猜测,session 员漏进来是编译错不是运行病。 */
+export type DurableRuleScope = Exclude<RuleScope, {
+    kind: "session";
+}>;
 /** {@link serializeRuleScope} 的逆。读不出形 ⇒ `undefined`(调用方 400,绝不猜一个 global 出来 ——
  *  猜 global 会把一次「删项目内规则」的请求变成一次删不掉任何东西的 no-op,或者更糟)。 */
-export declare function parseRuleScope(text: string): RuleScope | undefined;
+export declare function parseRuleScope(text: string): DurableRuleScope | undefined;
 /** 一条规则在 wire 上的行 = 一个逻辑 (rule, scope) 对(design/203 v2 §6 F5)。
  *  `adds` **如实上 wire**、不折叠成单值:同一条规则可以被批准过多次(不同 dot、不同来源、不同时刻),
  *  折成「一个 addedAt」会让「这条规则是我导入的还是我点过卡的」在治理面上不可分。 */
@@ -306,6 +521,10 @@ export interface RuleConsentLane {
     prepareImport(principal: string, layers: readonly RuleImportLayerInput[]): Promise<RuleImportPrepared>;
     /** 导入道:原子消费票 → confirm → redeemRuleBatch。 */
     redeemImport(principal: string, ticket: string): Promise<RuleImportRedeemed>;
+    /** #265 A7 直通道:逐行校验 → 预览 + pending 记录 + 票(零可导入行 ⇒ 无票)。 */
+    prepareLocalImport(principal: string, rows: readonly PersistedRuleWireRow[]): Promise<LocalImportPrepared>;
+    /** #265 A7 直通道:三态兑付(首兑 / 逐字回放 / 崩溃窗重驱),终局落进票行。 */
+    redeemLocalImport(principal: string, ticket: string): Promise<LocalImportRedeemed>;
     /**
      * 撤销面读半场:列出一只桶名下**活着**的规则(墓碑已折算)。
      *
@@ -339,5 +558,8 @@ export declare function createRuleConsentLane(stores: RuleConsentStores, opts?:
     newTicketId?: () => string;
     /** [4232]③ 的单调钟 seam。缺省 `performance.now()` —— 本仓既定单调域。 */
     monotonic?: () => number;
+    /** A7 有界等待的睡眠 seam(缺省真定时器)。等待窗与轮询步长都是**实现常数**,不是旋钮 ——
+     *  开成 opts 只是为了让"输者到底等没等"这件事可被确定性地钉住。 */
+    sleep?: (ms: number) => Promise<void>;
 }): RuleConsentLane;
 //# sourceMappingURL=rules-consent.d.ts.map