@sema-agent/server 7.134.0 → 7.135.0

package/dist/plugins/one-time-migrations.js

@@ -1,5 +1,6 @@
-import { PAUSE_REGISTRY, SESSION_RULES_GRAMMAR, compileSessionRuleBucket, isGateKind, readSessionRulesShape, unreadableDenyEntries } from "@sema-agent/core";
-import { ASK_USER_QUESTION_TOOL_NAME } from "../approval-content-kind.js";
+import { SESSION_RULES_GRAMMAR, compileSessionRuleBucket, isGateKind, readSessionRulesShape, unreadableDenyEntries } from "@sema-agent/core";
+import { APPROVAL_GATE_KINDS, ASK_USER_QUESTION_TOOL_NAME, isApprovalGateKind } from "../approval-content-kind.js";
+import { APPROVAL_CARD_COLUMN_MAX_BYTES, buildCheckpointIndexCells } from "./checkpoint-index-columns.js";
 import { dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { SCHEMA_STATEMENTS, acquireEnsureSchemaLock, releaseEnsureSchemaLock } from "./tidb-pool.js";
 import { PG_SCHEMA_STATEMENTS, acquirePgEnsureSchemaLock, releasePgEnsureSchemaLock } from "./pg-pool.js";
@@ -18,7 +19,6 @@ import { MAILBOX_KEYED_TABLES, mailboxKeyDeleteSql, storedMailboxKeyless } from
 const RETIRED_SESSION_RULE_BUCKETS = ["commandAllow", "commandDeny"];
 export function buildMigrationReceipts() {
     return {
-        auditDetailJsonNullRows: 0,
         sessionIncarnationsBackfilled: 0,
         holderDeathCodeRowsBackfilled: 0,
         allowRuleShadowRowsMigrated: 0,
@@ -43,6 +43,9 @@ export function buildMigrationReceipts() {
         workflowJournalForeignScopeRowsRemoved: 0,
         retiredBreakerTablesDropped: 0,
         mailboxRejectedKeyRowsRemoved: 0,
+        parkedApprovalCardsBackfilled: 0,
+        parkedApprovalCardRowsUnreadable: [],
+        parkedApprovalCardRowsTooLong: [],
     };
 }
 function completedReport(r) {
@@ -53,8 +56,7 @@ function completedReport(r) {
     return { ...r, sessionIncarnationColumn, workflowParkIndexKey, sessionRuleColumn, workflowJournalScopeColumn };
 }
 function changedAnything(r) {
-    return (r.auditDetailJsonNullRows > 0 ||
-        r.sessionIncarnationColumn === "added" ||
+    return (r.sessionIncarnationColumn === "added" ||
         r.sessionIncarnationsBackfilled > 0 ||
         r.holderDeathCodeRowsBackfilled > 0 ||
         r.allowRuleShadowRowsMigrated > 0 ||
@@ -81,7 +83,10 @@ function changedAnything(r) {
         r.workflowJournalOwnersBackfilled > 0 ||
         r.workflowJournalForeignScopeRowsRemoved > 0 ||
         r.retiredBreakerTablesDropped > 0 ||
-        r.mailboxRejectedKeyRowsRemoved > 0);
+        r.mailboxRejectedKeyRowsRemoved > 0 ||
+        r.parkedApprovalCardsBackfilled > 0 ||
+        r.parkedApprovalCardRowsUnreadable.length > 0 ||
+        r.parkedApprovalCardRowsTooLong.length > 0);
 }
 function readingsSnapshot(r) {
     return {
@@ -91,6 +96,8 @@ function readingsSnapshot(r) {
         sessionRuleRowsWithRetiredBuckets: [...r.sessionRuleRowsWithRetiredBuckets],
         sessionRuleRowsWithOldGrammarEntries: [...r.sessionRuleRowsWithOldGrammarEntries],
         sessionRuleRowsWithUnreadableDeny: [...r.sessionRuleRowsWithUnreadableDeny],
+        parkedApprovalCardRowsUnreadable: [...r.parkedApprovalCardRowsUnreadable],
+        parkedApprovalCardRowsTooLong: [...r.parkedApprovalCardRowsTooLong],
     };
 }
 function receiptSentence(r) {
@@ -115,17 +122,6 @@ export class OneTimeMigrationInterruptedError extends Error {
     }
 }
 export const ONE_TIME_MIGRATIONS = [
-    {
-        id: "M4",
-        introducedIn: "7.93.5",
-        releasedOn: "2026-09-21",
-        removableAfter: "2026-10-21",
-        removal: "删 migrateOn 的 M4 步(`device_audit` 在场探针 + `UPDATE … SET detail = NULL`)与 `AUDIT_TABLE` / `AUDIT_DETAIL_COLUMN`;" +
-            "报告、日志行与 `NO_SQL_MIGRATIONS` 的 `auditDetailJsonNullRows`;它若是表里最后一条,按头注「窗」一节整个文件一起删",
-        afterRemoval: "`device-store-sql.ts` `listAudit` 的读形拒(S-550:一行读不出形 ⇒ 整页拒,刻意不逐行隔离):含一行 JSON 文本 `null` 的那一页" +
-            "读不出来,拒句点名行 id —— 响亮,但那一页会一直读不出来,直到运维手工把那些行的 `detail` 置成 SQL NULL",
-        reportKeys: ["auditDetailJsonNullRows"],
-    },
     {
         id: "M5",
         introducedIn: "7.104.0",
@@ -134,7 +130,7 @@ export const ONE_TIME_MIGRATIONS = [
         removal: "删 migrateOn 的 M5 步(`session_meta` 在场探针、`incarnation` 列在场探针 + `ADD COLUMN`、空化身回填循环)与 `backfillSessionIncarnations`;" +
             "报告、日志行与 `NO_SQL_MIGRATIONS` 的 `sessionIncarnationColumn` / `sessionIncarnationsBackfilled`;**列本身留在中央 DDL 里**(它不是迁移的一部分)",
         afterRemoval: "① 列不在的存量库:起服列册探针 `schema-consistency.ts`(S-547)的缺列臂拒启 `config.schema_mismatch`,拒句里的 `ALTER TABLE … ADD COLUMN` " +
-            "由同一份 DDL 生成(响亮);② 列在但行上仍是空化身(跳过了带 M5 的版本直接升):会话店读口 `sessionFaceOf` 对那一行响亮拒 " +
+            "由同一份 DDL 生成(响亮);② 列在但行上仍是空化身(跳过了带 M5 的版本直接升):会话店头读投成活住客(`sessionFaceOfHead`)时对那一行响亮拒 " +
             "`session.incarnation_missing`(parked 决定腿因此拒、记忆座退回按 id 绑定并 warn)—— 运维手工给那些行填一只随机令牌即可",
         reportKeys: ["sessionIncarnationColumn", "sessionIncarnationsBackfilled"],
     },
@@ -202,7 +198,7 @@ export const ONE_TIME_MIGRATIONS = [
             "`http/routes/sessions.ts` 409 `conflict.session_ownerless` 句里「Ways out: on the local backend, during the upgrade window …」那半句(连同冻结表 " +
             "`test/api-error-text-freeze.test.ts` 那一行、契约码目录 `docs/ASSISTANT-WIRE-CONTRACT.md` 那一行);本文件的 `migrationWindowOpen`(若再无别的读者)",
         afterRemoval: "没有响亮臂(删码本身零行为变化:窗关那一刻起认领臂已经不生效):属主从没被记下的存量会话(边档那一格只有化身 —— 跳过了带本条的版本直接升," +
-            "或窗内从没被带 principal 提交过)照旧答无主(`ownerOf` = null):它的会话规则这条路由读不了也改不了(409 `conflict.session_ownerless`)," +
+            "或窗内从没被带 principal 提交过)照旧答无主(`headOf(id)?.owner` = null):它的会话规则这条路由读不了也改不了(409 `conflict.session_ownerless`)," +
             "已存的规则对写下它们的 principal 的 run 照旧生效;出路 = 删会话(`DELETE /v1/sessions/:id`,规则随之删)",
         reportKeys: [],
     },
@@ -360,7 +356,7 @@ export const ONE_TIME_MIGRATIONS = [
         releasedOn: "2026-10-18",
         removableAfter: "2026-11-17",
         removal: "删 migrateOn 的 M21 步(`repairParkedRows`:pending 候选分页扫描、门型回填、续不了的置 expired、问答卡词的整只文档读 + CAS 回写)与 `parkedRowRepairOf` / `ParkedRowRepair` / " +
-            "`M21_GATE` / `M21_PENDING_ACTION` / `PARKED_ROW_REPAIR_PAGE` / `QUESTION_CARD` / `PARKED_APPROVAL_GATE_KINDS` / `readM21Subtree` / `readM21Document` / `m21Subtree`;" +
+            "`M21_GATE` / `M21_PENDING_ACTION` / `PARKED_ROW_REPAIR_PAGE` / `QUESTION_CARD` / `readM21Subtree` / `readM21Document` / `m21Subtree`;" +
             "报告、日志行与 `NO_SQL_MIGRATIONS` 的 `parkedQuestionCardsWritten` / `parkedQuestionRowsLeftAsWritten` / `parkedRowGateKindsBackfilled` / `parkedRowsUnresumableExpired`;" +
             "`test/one-time-migrations.test.ts` 的 M21 组与 `test/one-time-migrations-db-integration.test.ts` 的 M21 格",
         afterRemoval: "① 门上没有卡词的存量问答行(跳过了带本条的版本直接升的库、把 `APPROVAL_TERMINAL_BACKSTOP_MS` 调长的部署、local 车道 —— 那一车道本条从来够不着):没有新的臂,回到本条之前的读法 —— " +
@@ -462,12 +458,23 @@ export const ONE_TIME_MIGRATIONS = [
             "行字节不动 —— 出路 = 作为新任务重提(仍停驻的先取消),或升级时先过一次带本条的版本",
         reportKeys: [],
     },
+    {
+        id: "M29",
+        introducedIn: "7.135.0",
+        releasedOn: "2026-10-22",
+        removableAfter: "2026-11-21",
+        removal: "删 migrateOn 的 M29 步(`backfillParkedApprovalCards`:列在场探针、pending 候选分页扫描、整只文档读 + 同一只派生 + CAS 写列)与 `PARKED_CARD_BACKFILL_PAGE` / `readM29Document` / `m29CardOf`;" +
+            "报告、日志行(含逐行的 `parked_approval_card_row_unreadable` / `parked_approval_card_row_too_long`)与 `NO_SQL_MIGRATIONS` 的 `parkedApprovalCardsBackfilled` / `parkedApprovalCardRowsUnreadable` / `parkedApprovalCardRowsTooLong`;`test/one-time-migrations.test.ts` 的 M29 组与 " +
+            "`test/checkpoint-index-columns-db-integration.test.ts` 的 M29 格。**不随本条删**:`approval_card` 列、写口的派生、到期 facet 的生成谓词(常设)",
+        afterRemoval: "没有新的臂(如实):跳过了带本条的版本直接升的库,升级前停驻、升级后仍挂着的行卡列是 NULL —— 生成谓词读门型的 facet(审批门 ⇒ SLA 拒扫腿),问答行到期被拒扫" +
+            "(引擎对问答拒收 `sla_timeout`,拒扫腿每拍一条失败,由 `terminal_at_ms` 兜底收割);运维队列行不带卡词。出路 = 升级前答完 / 拒掉停驻的问答,或升级时先过一次带本条的版本",
+        reportKeys: ["parkedApprovalCardsBackfilled", "parkedApprovalCardRowsUnreadable", "parkedApprovalCardRowsTooLong"],
+    },
 ];
 export function migrationWindowOpen(window, today) {
     return window.removableAfter === null || today <= window.removableAfter;
 }
 export const NO_SQL_MIGRATIONS = {
-    auditDetailJsonNullRows: 0,
     sessionIncarnationColumn: "lazy-on-read",
     sessionIncarnationsBackfilled: 0,
     allowRuleShadowRowsMigrated: 0,
@@ -495,9 +502,10 @@ export const NO_SQL_MIGRATIONS = {
     workflowJournalForeignScopeRowsRemoved: 0,
     retiredBreakerTablesDropped: 0,
     mailboxRejectedKeyRowsRemoved: 0,
+    parkedApprovalCardsBackfilled: 0,
+    parkedApprovalCardRowsUnreadable: [],
+    parkedApprovalCardRowsTooLong: [],
 };
-const AUDIT_TABLE = "device_audit";
-const AUDIT_DETAIL_COLUMN = "detail";
 function mysqlDb(conn) {
     return {
         async rows(sql, params) {
@@ -584,9 +592,6 @@ async function migrateOn(db, dialect) {
     return completedReport(receipts);
 }
 async function migrateStepsOn(db, dialect, receipts) {
-    if (await tableExists(db, dialect, AUDIT_TABLE)) {
-        receipts.auditDetailJsonNullRows += await db.exec(`UPDATE ${AUDIT_TABLE} SET ${AUDIT_DETAIL_COLUMN} = NULL ` + `WHERE ${AUDIT_DETAIL_COLUMN} IS NOT NULL AND ${jsonColumnTextExpr(dialect, AUDIT_DETAIL_COLUMN)} = 'null'`);
-    }
     await migrateSessionIncarnations(db, dialect, receipts);
     receipts.holderDeathCodeRowsBackfilled += await db.exec(dialect === "tidb"
         ? "UPDATE task_run SET error_code = ? WHERE status = 'failed' AND error_code IS NULL AND error = ?"
@@ -599,9 +604,10 @@ async function migrateStepsOn(db, dialect, receipts) {
     await reshapeWorkflowParkIndex(db, dialect, receipts);
     await migrateSessionRuleGrammar(db, dialect, receipts);
     await repairParkedRows(db, dialect, receipts);
+    await backfillParkedApprovalCards(db, dialect, receipts);
     if (await tableExists(db, dialect, "session_meta"))
         await inheritPlacedSessionOwners(db, dialect, receipts);
-    if (await tableExists(db, dialect, PERMISSION_RULE_TABLE))
+    if ((await tableExists(db, dialect, PERMISSION_RULE_TABLE)) && (await columnExists(db, dialect, PERMISSION_RULE_TABLE, "grammar")))
         await purgeUndurableScopeRows(db, dialect, receipts);
     await moveWorkflowJournalScope(db, dialect, receipts);
     if (await tableExists(db, dialect, RETIRED_BREAKER_TABLE))
@@ -1010,7 +1016,6 @@ const M21_GATE = { key: "gate", as: "m21_gate" };
 const M21_PENDING_ACTION = { key: "pendingAction", as: "m21_pending_action" };
 const PARKED_ROW_REPAIR_PAGE = 200;
 const QUESTION_CARD = "question";
-const PARKED_APPROVAL_GATE_KINDS = Object.keys(PAUSE_REGISTRY).filter((k) => PAUSE_REGISTRY[k].pending === "tool_approval");
 const readM21Subtree = createObjectColumnReader();
 const readM21Document = createObjectColumnReader();
 export function parkedRowRepairOf(gateKindCell, gate, pendingAction) {
@@ -1020,7 +1025,7 @@ export function parkedRowRepairOf(gateKindCell, gate, pendingAction) {
     const kind = columnKind ?? documentKind;
     const pa = pendingAction !== null && typeof pendingAction === "object" && !Array.isArray(pendingAction) ? pendingAction : undefined;
     const questionCard = kind !== undefined &&
-        PARKED_APPROVAL_GATE_KINDS.includes(kind) &&
+        isApprovalGateKind(kind) &&
         gateObj !== undefined &&
         !Object.hasOwn(gateObj, "approvalCard") &&
         pa?.kind === "tool_approval" &&
@@ -1040,7 +1045,7 @@ function m21Subtree(cell, where) {
 }
 export async function repairParkedRows(db, dialect, receipts) {
     const ph = (n) => (dialect === "tidb" ? "?" : `$${n}`);
-    const kinds = PARKED_APPROVAL_GATE_KINDS;
+    const kinds = APPROVAL_GATE_KINDS;
     const kindSlots = kinds.map((_, i) => ph(i + 1)).join(", ");
     const scan = `SELECT token, session_id, gate_kind, ${jsonColumnText(dialect, "checkpoint", M21_GATE)}, ${jsonColumnText(dialect, "checkpoint", M21_PENDING_ACTION)} FROM checkpoint ` +
         `WHERE status = 'pending' AND (gate_kind IS NULL OR (gate_kind IN (${kindSlots}) AND tool_name = ${ph(kinds.length + 1)})) AND token > ${ph(kinds.length + 2)} ` +
@@ -1090,6 +1095,58 @@ export async function repairParkedRows(db, dialect, receipts) {
             return;
     }
 }
+const PARKED_CARD_BACKFILL_PAGE = 200;
+const readM29Document = createObjectColumnReader();
+export async function backfillParkedApprovalCards(db, dialect, receipts) {
+    if (!(await columnExists(db, dialect, "checkpoint", "approval_card")))
+        return;
+    const ph = (n) => (dialect === "tidb" ? "?" : `$${n}`);
+    const kinds = APPROVAL_GATE_KINDS;
+    const scan = `SELECT token FROM checkpoint WHERE status = 'pending' AND approval_card IS NULL AND gate_kind IN (${kinds.map((_, i) => ph(i + 1)).join(", ")}) ` +
+        `AND token > ${ph(kinds.length + 1)} ORDER BY token LIMIT ${PARKED_CARD_BACKFILL_PAGE}`;
+    let after = "";
+    for (;;) {
+        const page = await db.rows(scan, [...kinds, after]);
+        for (const r of page) {
+            const token = String(r.token);
+            after = token;
+            const [full] = await db.rows(`SELECT session_id, ${jsonColumnText(dialect, "checkpoint")} FROM checkpoint WHERE token = ${ph(1)} AND status = 'pending'`, [token]);
+            if (full === undefined)
+                continue;
+            const reading = m29CardOf(full.checkpoint);
+            if (reading.kind === "unreadable") {
+                receipts.parkedApprovalCardRowsUnreadable.push({ sessionId: String(full.session_id) });
+                continue;
+            }
+            if (reading.card === null)
+                continue;
+            const bytes = Buffer.byteLength(reading.card, "utf8");
+            if (bytes > APPROVAL_CARD_COLUMN_MAX_BYTES[dialect]) {
+                receipts.parkedApprovalCardRowsTooLong.push({ sessionId: String(full.session_id), bytes });
+                continue;
+            }
+            receipts.parkedApprovalCardsBackfilled += await db.exec(`UPDATE checkpoint SET approval_card = ${ph(1)} WHERE token = ${ph(2)} AND status = 'pending' AND approval_card IS NULL`, [reading.card, token]);
+        }
+        if (page.length < PARKED_CARD_BACKFILL_PAGE)
+            return;
+    }
+}
+function m29CardOf(cell) {
+    let doc;
+    try {
+        doc = decodeJsonColumn(cell, readM29Document, "checkpoint.checkpoint (M29 approval-card backfill)");
+    }
+    catch (e) {
+        if (!isJsonColumnBodyProblem(e))
+            throw e;
+        return { kind: "unreadable" };
+    }
+    const gate = doc.gate;
+    const pendingAction = doc.pendingAction;
+    if (typeof gate !== "object" || gate === null || typeof pendingAction !== "object" || pendingAction === null)
+        return { kind: "unreadable" };
+    return { kind: "card", card: buildCheckpointIndexCells(doc).approval_card };
+}
 const PLACED_OWNER_SCAN_PAGE = 500;
 function placedOwnerScanSql(dialect) {
     return ("SELECT c.session_id, c.incarnation, r.session_id AS root_row, r.owner AS root_owner, r.incarnation AS root_incarnation, r.placement_kind AS root_kind, " +
@@ -1210,7 +1267,6 @@ async function backfillSessionIncarnations(db, dialect, receipts) {
 }
 function readingFields(r) {
     return {
-        auditDetailJsonNullRows: r.auditDetailJsonNullRows,
         ...(r.sessionIncarnationColumn !== undefined ? { sessionIncarnationColumn: r.sessionIncarnationColumn } : {}),
         sessionIncarnationsBackfilled: r.sessionIncarnationsBackfilled,
         holderDeathCodeRowsBackfilled: r.holderDeathCodeRowsBackfilled,
@@ -1239,6 +1295,9 @@ function readingFields(r) {
         workflowJournalForeignScopeRowsRemoved: r.workflowJournalForeignScopeRowsRemoved,
         retiredBreakerTablesDropped: r.retiredBreakerTablesDropped,
         mailboxRejectedKeyRowsRemoved: r.mailboxRejectedKeyRowsRemoved,
+        parkedApprovalCardsBackfilled: r.parkedApprovalCardsBackfilled,
+        parkedApprovalCardRowsUnreadable: r.parkedApprovalCardRowsUnreadable.length,
+        parkedApprovalCardRowsTooLong: r.parkedApprovalCardRowsTooLong.length,
     };
 }
 export function logOneTimeMigrations(log, backend, report) {
@@ -1246,8 +1305,7 @@ export function logOneTimeMigrations(log, backend, report) {
         backend,
         ...readingFields(report),
         removableAfter: Object.fromEntries(ONE_TIME_MIGRATIONS.map((w) => [w.id, w.removableAfter])),
-        note: "one-time persisted-data migrations (M4: audit details written as the JSON " +
-            "text `null` by an earlier version folded to a SQL NULL, so \"no detail\" has exactly one on-disk spelling; M5: the " +
+        note: "one-time persisted-data migrations (M5: the " +
             "session incarnation column added and every session row without one minted its own token; M6: run rows failed by a " +
             "holder-death verdict written by an earlier version with only the sentence got the machine-readable code run.stalled / " +
             "run.orphaned; M7 writes nothing — it is the window of the refusal that keeps a suspended task whose stored allow list was written " +
@@ -1282,7 +1340,10 @@ export function logOneTimeMigrations(log, backend, report) {
             "the breakers live in the new table breaker_state, which this step never touches; only the count is logged, never a key; M27: rows of the three " +
             "mailbox tables (mailbox / mailbox_message / mailbox_tombstone) whose key — scope or handle — the mailbox key judge refuses (control characters, " +
             "malformed Unicode, wider than 190 UTF-8 bytes, empty scope) removed, a whole box at a time: no entry point reaches such a key any more, so neither " +
-            "delivery, reading nor session deletion would ever have touched them again; only the count is logged, never a key). Each step " +
+            "delivery, reading nor session deletion would ever have touched them again; only the count is logged, never a key; M29: suspended rows " +
+            "parked before the checkpoint column approval_card existed and still pending get that column — the approval card word on their gate, " +
+            "derived by the same function the write path uses (the engine's checkpointIndexFacts); a row whose document cannot be read as a checkpoint " +
+            "is left NULL and counted, named by a parked_approval_card_row_unreadable line, and so is a row whose card word is longer than the column can hold, named by a parked_approval_card_row_too_long line). Each step " +
             "runs on every boot until its window closes (the release that introduced it + 30 days; the per-step date is in " +
             "removableAfter, null while that release is not published yet) and is deleted in the first minor after that — start a " +
             "version that still carries a step at least once before upgrading past its deletion.",
@@ -1290,6 +1351,26 @@ export function logOneTimeMigrations(log, backend, report) {
     logReceiptRows(log, backend, report);
 }
 function logReceiptRows(log, backend, r) {
+    for (const row of r.parkedApprovalCardRowsUnreadable) {
+        log.warn("parked_approval_card_row_unreadable", {
+            backend,
+            sessionId: row.sessionId,
+            note: "a suspended approval row's checkpoint document cannot be read as a checkpoint the engine can resume (the body is not a JSON object, or the gate / pending-action member is missing), so its approval card " +
+                "could not be derived. The row was not backfilled and not touched: the checkpoint.approval_card column stays NULL and the document is exactly as it was. Such a row cannot be resumed either; " +
+                "find it by its session id and repair or remove the checkpoint document, or delete the session. The row is named on every boot until then",
+        });
+    }
+    for (const row of r.parkedApprovalCardRowsTooLong) {
+        log.warn("parked_approval_card_row_too_long", {
+            backend,
+            sessionId: row.sessionId,
+            bytes: row.bytes,
+            note: "a suspended approval row's gate carries an approval card word longer than the checkpoint.approval_card column can hold (the MySQL-protocol column is TEXT: 65,535 UTF-8 bytes). " +
+                "The engine mints short card words only, so this row was edited by hand or written by something other than the engine. It was not backfilled and not truncated: the " +
+                "column stays NULL and the read paths read the row as carrying no card (its document is untouched). Find the row by its session id and shorten " +
+                "or remove the approvalCard member of its gate in the checkpoint document (the next boot then backfills it), or delete the session. The row is named on every boot until then",
+        });
+    }
     if (r.workflowJournalForeignScopeRowsRemoved > 0) {
         log.warn("workflow_journal_foreign_scope_rows_removed", {
             backend,

package/dist/plugins/outcome-ledger-sql.d.ts

@@ -89,7 +89,7 @@ export declare function coreOutcomeToLedgerRow(o: CoreTaskOutcome): TaskOutcome;
  * drop-and-recreate, and NO new `ALTER TABLE` seams are added here; fold into the CREATE instead.
  */
 export declare const PG_OUTCOME_LEDGER_SCHEMA: string[];
-/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgOutcomeLedgerSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+/** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgOutcomeLedgerSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const OUTCOME_LEDGER_INDEXES: readonly IndexSpec[];
 /** Idempotent self-contained PG schema apply (for the integration test; central aggregation via pg-pool.ts). */
 export declare function ensurePgOutcomeLedgerSchema(pool: PgPool | PoolClient): Promise<void>;

package/dist/plugins/park-commit-watch.d.ts

@@ -1,5 +1,5 @@
 /**
- * 🔴 **S-929 F1(7.108.0 [ref] 合并复审 codex 腿 A ①,[high] 回归修)—— park 提交的唯一观察点。**
+ * 🔴 **[ref] F1(7.108.0 [ref] 合并复审 codex 腿 A ①,[high] 回归修)—— park 提交的唯一观察点。**
  *
  * core 的 durable park 就是对本仓 checkpoint 店的一次 `put`(SQL 孪生 / 本地文件店都是本仓的 `CheckpointStore` 实现,
  * 一只实例、四个消费点 —— 见 `boot/stage-06-runners.ts` 的构造注)。审批协调器交出 park 路由(ask 回调返回 `"unavailable"`)
@@ -19,7 +19,7 @@
  * **已提交**的 park 报成失败;一只不收尾的订阅者会把 core 的停驻挂住(订阅者自己给自己的工作上墙钟上限)。
  * 两个订阅者,各管一件「这只停车行提交了」之后的事:
  *  · 审批协调器 —— 有序关停下写候着的审计 settle 行(sink 自吞失败并按 [ref] 留痕,同 tag 扩射程,见协调器);
- *  · 对账收敛器 —— S-1280:这次调用的 `PARKING` 行在这一拍收口成 `PARKED`(判据 1 那一只判官的即时调用,`approval-reconciler.ts`
+ *  · 对账收敛器 —— [ref]:这次调用的 `PARKING` 行在这一拍收口成 `PARKED`(判据 1 那一只判官的即时调用,`approval-reconciler.ts`
  *    `bindCommittedPark`;它自带墙钟预算、失败只留痕,周期扫兜底)。`put` 等它(至多到它的预算)⇒ 健康时 core 的停驻返回之时行已收口;
  *    预算到点它就交还 `put`、不再发新的店调用,已发出的那一次经 {@link ParkCommitWatch.track} 留在在飞里 ⇒ 收尾链的 `quiesce`
  *    在 `backend.close()` 之前等到它落定。
@@ -46,7 +46,7 @@ export interface ParkCommitWatch {
     onParkCommitted(listener: ParkCommittedListener): void;
     /**
      * 把订阅者在 `put` 交还之后**仍可能在跑**的那段工作记进在飞:`quiesce` 等它落定(成功或失败都算落定),返回同一个 promise。
-     * 用途(S-1280):订阅者给自己的工作上了墙钟预算,到点就把 `put` 交还 core —— 而此刻已经发出的那次店调用还没回来;不记进来,
+     * 用途([ref]):订阅者给自己的工作上了墙钟预算,到点就把 `put` 交还 core —— 而此刻已经发出的那次店调用还没回来;不记进来,
      * 收尾链会读到「静默」并在它底下关池。
      */
     track<T>(work: Promise<T>): Promise<T>;

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

@@ -12,9 +12,9 @@ import { type RuleCandidate } from "@sema-agent/core";
 export declare class FileRuleApprovalRecordStore implements RuleApprovalRecordStore {
     private readonly rows;
     private readonly log;
-    /** 本面的损坏闸(S-582 起由重放属主交回;置位后每个方法第一行响亮拒)。 */
+    /** 本面的损坏闸([ref] 起由重放属主交回;置位后每个方法第一行响亮拒)。 */
     private readonly gate;
-    /** @param warn 腐读披露座(S-582;缺席 ⇒ 属主退回 `console.warn`)。 */
+    /** @param warn 腐读披露座([ref];缺席 ⇒ 属主退回 `console.warn`)。 */
     constructor(dir: string, warn?: Logger["warn"]);
     /** 取证/自证用:本面是否因内部损坏而 fail-closed。 */
     get corrupt(): boolean;
@@ -42,11 +42,11 @@ export declare class FileRuleApprovalRecordStore implements RuleApprovalRecordSt
 export declare class FileRuleImportTicketStore {
     private readonly rows;
     private readonly log;
-    /** 本面的损坏闸(S-582 起由重放属主交回)。 */
+    /** 本面的损坏闸([ref] 起由重放属主交回)。 */
     private readonly gate;
     /** 单调钟(判定用)。与 {@link now}(墙钟,记账用)是两只不同的钟,别混。 */
     private readonly monotonic;
-    /** @param warn 腐读披露座(S-582;缺席 ⇒ 属主退回 `console.warn`)。 */
+    /** @param warn 腐读披露座([ref];缺席 ⇒ 属主退回 `console.warn`)。 */
     constructor(dir: string, now?: () => number, warn?: Logger["warn"], monotonic?: () => number);
     private readonly now;
     /** 取证/自证用:本面是否因内部损坏而 fail-closed。 */
@@ -105,7 +105,7 @@ export interface FilePermissionRuleStores extends PermissionRuleStoreBundle {
  * `onError` 接的是 core 规则文件的**披露面**(读不出来 / 校验和不符 / 撞上符号链接时它答零规则并
  * 说出来)。接住它打一条 warn 是**必须**的:那条路径上「零规则」与「真的没有规则」在读面上同形,
  * 不留痕就变成一次静默的 fail-closed(用户会突然被反复询问,却没有任何线索)。
- * `warn`(S-582)接的是本仓审批记录 / 导入票两份日志的**腐读座**(逐行披露 + 计数;缺席 ⇒ `console.warn`)。
+ * `warn`([ref])接的是本仓审批记录 / 导入票两份日志的**腐读座**(逐行披露 + 计数;缺席 ⇒ `console.warn`)。
  */
 export declare function createFilePermissionRuleStores(root: string, opts?: {
     onError?: (message: string) => void;

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

@@ -4,28 +4,19 @@ import { readdirSync } from "node:fs";
 import { performance } from "node:perf_hooks";
 import { FileDurableRulePartitionProvider, AppendLog, ensureDir, } from "@sema-agent/core";
 import { z } from "zod";
-import { DurableRuleScopeSchema, buildRulePayloadHash } from "./permission-rule-store-sql.js";
+import { DurableRuleScopeSchema, RuleOffer2Schema, buildRulePayloadHash, recordOwnerOf, refusedOwnerSentence } from "./permission-rule-store-sql.js";
 import { replayJsonlGuarded } from "../observability/corrupt-read-seat.js";
-import { EDITED_RULE_BREADTH_WARNING_CODES, RULE_APPROVAL_KINDS, RULE_APPROVAL_RECORD_SCHEMA, RULE_APPROVAL_STATES, RULE_BEHAVIORS, RULE_OWNER_KINDS, UNCOVERED_SEGMENT_REASONS } from "@sema-agent/core";
+import { EDITED_RULE_BREADTH_WARNING_CODES, RULE_APPROVAL_KINDS, RULE_APPROVAL_RECORD_SCHEMA, RULE_APPROVAL_STATES, RULE_BEHAVIORS, readRuleOwner } from "@sema-agent/core";
 const RuleDotSchema = z.object({ actor: z.string().min(1), counter: z.number().int().nonnegative().safe() }).strict();
 const RuleCandidateSchema = z.object({ behavior: z.enum(RULE_BEHAVIORS), rule: z.string(), scope: DurableRuleScopeSchema }).strict();
-const RuleOffer2Schema = z.union([
-    z.object({ kind: z.literal("single"), candidate: z.number().int().nonnegative().safe() }).strict(),
-    z
-        .object({
-        kind: z.literal("batch"),
-        candidates: z.array(z.number().int().nonnegative().safe()),
-        segments: z.array(z.string()).optional(),
-        uncoveredSegments: z.number().int().nonnegative().safe().optional(),
-        uncoveredDetail: z.array(z.object({ segment: z.string(), reason: z.enum(UNCOVERED_SEGMENT_REASONS) }).strict()).optional(),
-    })
-        .strict(),
-]);
-const OWNER_SHAPE_BY_KIND = {
-    principal: z.object({ kind: z.literal("principal"), principal: z.string() }).strict(),
-    "local-owner": z.object({ kind: z.literal("local-owner") }).strict(),
-};
-const RuleOwnerSchema = z.union([OWNER_SHAPE_BY_KIND.principal, OWNER_SHAPE_BY_KIND["local-owner"]]);
+const RuleOwnerSchema = z.unknown().transform((raw, ctx) => {
+    const owner = readRuleOwner(raw);
+    if (owner === undefined) {
+        ctx.addIssue({ code: "custom", message: "not a rule owner (the engine's readRuleOwner reads none: a plain record whose kind is a member and, for a principal, whose name is not empty or whitespace-only)" });
+        return z.NEVER;
+    }
+    return owner;
+});
 const ApprovalRecordSchema = z
     .object({
     id: z.string().min(1),
@@ -163,6 +154,8 @@ export class FileRuleApprovalRecordStore {
     }
     async create(record) {
         this.gate.assertUsable();
+        if (recordOwnerOf(record) === undefined)
+            throw new Error(refusedOwnerSentence(record.id));
         if (this.rows.has(record.id))
             throw new Error(`rule approval record ${record.id} already exists`);
         this.log.append({ op: "put", record }, true);

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

@@ -31,6 +31,23 @@ export declare function writerOfSqlRuleStore(store: DurableRulePartition): Permi
  * (下方 `RuleCandidateSchema`;File 店的审批记录读同一只)。
  */
 export declare const DurableRuleScopeSchema: z.ZodType<RuleScope>;
+export declare const RuleOffer2Schema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"single">;
+    candidate: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"batch">;
+    candidates: z.ZodArray<z.ZodNumber>;
+    segments: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    uncoveredSegments: z.ZodOptional<z.ZodNumber>;
+    uncoveredDetail: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        segment: z.ZodString;
+        reason: z.ZodEnum<{
+            redirection: "redirection";
+            no_rule_form: "no_rule_form";
+            cap_overflow: "cap_overflow";
+        }>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>]>;
 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";
@@ -112,7 +129,7 @@ export declare function assertPermissionRuleApprovalSchema(query: (sql: string)
 export declare function assertPermissionRuleTicketSchema(query: (sql: string) => Promise<{
     rows: Record<string, unknown>[];
 }>, dialect: "tidb" | "pg"): Promise<void>;
-/** S-287:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgPermissionRuleSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
+/** [ref]:本 store 的索引**声明**(两方言共用一份)。PG 侧由下面的 `ensurePgPermissionRuleSchema` 应用,MySQL 侧由 `tidb-pool.ts` 的中央 `ensureSchema` 应用(那里内联 `KEY` 已在 `CREATE TABLE` 里 ⇒ 新建库探到即零 DDL,存量库缺谁补谁)。加索引以外的 schema 变更仍归运维,见 `plugins/ensure-index.ts` 头注。 */
 export declare const PERMISSION_RULE_INDEXES: readonly IndexSpec[];
 export declare function ensurePgPermissionRuleSchema(q: PgQueryFn): Promise<void>;
 /**
@@ -124,9 +141,14 @@ export declare function ensurePgPermissionRuleSchema(q: PgQueryFn): Promise<void
  * 种别前缀让两族键不可能相撞(`principal:` vs `local-owner`)。
  */
 export declare function buildRuleOwnerKey(owner: RuleOwner): string;
-/** 内容三列 + 观测向量的完整性指纹(core `ruleStoreChecksum` 同精神;**不含** rev/counter —— 那两样
+/** 内容三列 + 观测向量 + **文法戳**(非 NULL 时)的完整性指纹(core `ruleStoreChecksum` 同精神;**不含** rev/counter —— 那两样
  *  是元数据轴,`nextDot` 只动 counter 就不该迫使重算内容指纹)。
  *
+ *  🔴 戳在指纹里(`grammar` 在场 ⇒ 进规范体;缺席 ⇒ 键不在,字节与 7.134.0 的算法逐字节相同 —— 存量无戳行的指纹一个字节不变,
+ *  升级不重写任何存量桶)。为什么要进:7.134.x / 引擎 7.54.x 的副本不读戳,若戳在指纹外,它们会把本版新文法写下的 deny 读成「无形」、
+ *  什么也不拒就放行;戳进指纹后,它们对带戳桶按旧算法重算比不上、**整桶拒(响亮)**。代价与推论:戳列与指纹必须**同一条语句**写
+ *  (建行的 INSERT、整桶回写的 UPDATE),所以取 dot 的计数 UPDATE 不碰戳 —— 它不读桶体、没法重算指纹。
+ *
  *  导出(纯数据 ⇒ `build*`)是为了让**取证测试**能造一条「指纹自洽但语义矛盾」的行 —— 那正是
  *  codex round1 [high] 二的形:一条只靠指纹是拦不住的坏行,必须由语义筛拦。 */
 export declare function buildRuleBucketChecksum(body: {
@@ -134,6 +156,8 @@ export declare function buildRuleBucketChecksum(body: {
     tombstones: readonly unknown[];
     quarantined: readonly unknown[];
     observedVector?: RuleSyncFrontier;
+    /** 这只桶的行写在哪一版规则文法里(`SESSION_RULES_GRAMMAR` 的数);缺席 = 存量无戳行(列 NULL)。 */
+    grammar?: number;
 }): string;
 /**
  * SQL 双方言的 {@link DurableRulePartitionProvider} —— [ref] 里的 **durable 分区后端**
@@ -151,6 +175,16 @@ export declare class SqlDurableRulePartitionProvider implements DurableRuleParti
     forPrincipal(principal: string | undefined): DurableRulePartition;
     forLocalOwner(): DurableRulePartition;
 }
+/**
+ * 一条审批记录的属主 —— 记录自带的 `owner`,缺席时是 v1 记录的 `principal`;读法只有引擎的 `readRuleOwner`(两只店的写口与 SQL 店读口同用):
+ * 读不出 ⇒ `undefined`(闭集外的种类、缺 / 纯空白的主体名)。写口据此「只写读得回来的属主」—— 否则落下的行会在读口 / 重放时才被拒(SQL 一行读不出,File 日志重放整面 fail-closed)。
+ */
+export declare function recordOwnerOf(record: {
+    readonly owner?: unknown;
+    readonly principal?: unknown;
+}): RuleOwner | undefined;
+/** 写口拒句(两只店同一句):属主引擎读不出,记录不落。 */
+export declare function refusedOwnerSentence(recordId: string): string;
 /**
  * durable 审批记录。CAS **按 rev**,不按 state —— core 的原话:批记录的第二个候选会 redeemed→redeemed,
  * 只比 state 的两次并发重试会**都**认为自己看到了预期状态,各铸一个 dot、各写一次,后者静默覆盖前者的
@@ -439,7 +473,7 @@ export interface UnreadableRuleBucket {
 }
 /**
  * M11 写进的读数账 —— 三格与一次性迁移段那一只收据账(`one-time-migrations.ts` 的 `MigrationReceipts`)上的同名三格**同名同形**,迁移段把它的账直接递进来
- * (S-1594:一次起服一只收据账,M11 不另起第二套):删掉的行在那只桶的回写**提交的那一刻**追加,之后任何一步失败,拒因随账带走它们。
+ * ([ref]:一次起服一只收据账,M11 不另起第二套):删掉的行在那只桶的回写**提交的那一刻**追加,之后任何一步失败,拒因随账带走它们。
  */
 export interface UndurableScopePurgeReadings {
     /** 删掉的行(一行一条读数;每只桶的回写提交之后才追加)。 */
@@ -468,7 +502,7 @@ export interface UndurableScopePurgeDb {
  * 本店也不实现同步(见 `apply` 的 sync-join 臂)。
  * 幂等:第二跑零命中零写(读不出的桶每一跑照报,直到有人处置)。
  * 读数写进调用方递进来的账(`into`,{@link UndurableScopePurgeReadings}):删掉的行在那只桶的回写提交之后追加 ⇒ 本函数半途抛出时,已删的行已经在账上;
- * 错误**原样**上抛(不加工、不自铸拒因句 —— 收据由迁移段那一只收据账随拒因带走,S-1594)。
+ * 错误**原样**上抛(不加工、不自铸拒因句 —— 收据由迁移段那一只收据账随拒因带走,[ref])。
  */
 export declare function purgeUndurableScopeRows(db: UndurableScopePurgeDb, dialect: "tidb" | "pg", into: UndurableScopePurgeReadings, now?: () => number): Promise<void>;
 /** 三个 SQL 面的一次性装配束(one driver, three faces)。`durable` = [ref] 的 durable 分区后端;