@sema-agent/server 7.135.0 → 7.137.0

package/dist/plugins/session-ownership.d.ts

@@ -1,11 +1,25 @@
+/**
+ * 「谁也不指的串」的描述句 —— 拒句里「给的是什么」那一格的串形(从不回显值:一个谁也不指的串可能就是一段被粘进来的凭据)。
+ * 本模块的属主拒与鉴权边界的主体拒(`security.ts` `assertPrincipalShape` 的 `principal_not_a_name`)读这同一句:判官同一只,描述也同一句。
+ */
+export declare const NOT_A_PRINCIPAL_NAME = "a string that names nobody (empty, blank, or holding a control, separator or invisible format character)";
+/**
+ * 「这个值能不能作一只会话行的属主格」—— core 7.56.0 [ref] 起只有一只判官 `principalNameOf`:主体名(有可见内容、不含控制 / 分隔 / 非连接符格式字符,
+ * 原样保存不规整)或 `null`(匿名)。空串、空白串、带不可见字符的串与一切非串都不是属主(它们谁也不指 —— 读成匿名会放行每一位主体)。
+ *
+ * 边界同判官:HTTP 请求带来的主体在鉴权边界已经过同一只 `principalNameOf`(`security.ts` `principalShapeProblem` 的 `not_a_name`,7.137.0)⇒
+ * 经过边界的请求到不了这里的拒臂;这里是纵深(嵌入方直调店、别的写者),规则只有引擎那一只,不在本仓另写。
+ */
+export declare function isSessionOwnerValue(owner: unknown): owner is string | null;
 /**
  * fork 拷贝的属主 —— core `SessionStore.fork` 契约的唯一读法:
- * 显式串 ⇒ 该串;无参 / 显式 `null` ⇒ 源会话记下的属主(`undefined` = 源会话没记,拷贝也不记)。
+ * 显式主体名 ⇒ 该名;无参 / 显式 `null` ⇒ 源会话记下的属主(`undefined` = 源会话没记,拷贝也不记)。
+ * 显式给了却不是主体名(空串 / 空白 / 带不可见字符,core 7.56.0 [ref])⇒ 响亮拒(`SessionError("storage")`,不留行)—— 与 `register` 首写同一只判官。
  */
 export declare function forkOwnerOf(requested: string | null | undefined, sourceOwner: string | null | undefined): string | null | undefined;
 /**
- * `register` 首写的 owner 守卫 —— core `SessionStore.register` 契约的唯一读法(三只店同调):首写的 owner 既不是串也不是 `null` ⇒ 响亮拒(不留行);
- * 「首写」由调用方判(已记下属主的会话上的调用照旧静默不改,不经这里)。
+ * `register` 首写的 owner 守卫 —— core `SessionStore.register` 契约的唯一读法(三只店同调):首写的 owner 既不是主体名也不是 `null` ⇒ 响亮拒(不留行);
+ * 「首写」由调用方判(已记下属主的会话上的调用照旧静默不改,不经这里)。判官 = {@link isSessionOwnerValue}(core 7.56.0 [ref] `principalNameOf`)。
  */
 export declare function assertFirstOwnerWritable(sessionId: string, owner: unknown): asserts owner is string | null;
 //# sourceMappingURL=session-ownership.d.ts.map

package/dist/plugins/session-ownership.js

@@ -1,11 +1,25 @@
-import { SessionError } from "@sema-agent/core";
+import { SessionError, principalNameOf } from "@sema-agent/core";
+export const NOT_A_PRINCIPAL_NAME = "a string that names nobody (empty, blank, or holding a control, separator or invisible format character)";
+function ownerValueFault(owner) {
+    if (typeof owner === "string")
+        return NOT_A_PRINCIPAL_NAME;
+    return owner === undefined ? "undefined" : typeof owner;
+}
+export function isSessionOwnerValue(owner) {
+    return owner === null || principalNameOf(owner) !== undefined;
+}
 export function forkOwnerOf(requested, sourceOwner) {
-    return typeof requested === "string" ? requested : sourceOwner;
+    if (requested === undefined || requested === null)
+        return sourceOwner;
+    if (principalNameOf(requested) === undefined) {
+        throw new SessionError("storage", `fork: session owner must be a principal name or null, got ${ownerValueFault(requested)} — refusing, nothing written`);
+    }
+    return requested;
 }
 export function assertFirstOwnerWritable(sessionId, owner) {
-    if (typeof owner === "string" || owner === null)
+    if (isSessionOwnerValue(owner))
         return;
-    throw new SessionError("storage", `register(${sessionId}): a first ownership write must carry a principal (string) or null (anonymous), got ${owner === undefined ? "undefined" : typeof owner} — ` +
-        "a stored value that the head read reads back as 'no row' would leave the session claimable forever and ownable never; refusing, nothing written");
+    throw new SessionError("storage", `register(${sessionId}): a first ownership write must carry a principal name or null (anonymous), got ${ownerValueFault(owner)} — ` +
+        "a value that names nobody would leave the session claimable by anyone or ownable by no one; refusing, nothing written");
 }
 //# sourceMappingURL=session-ownership.js.map

package/dist/plugins/snapshot-bucket-presence.d.ts

@@ -5,6 +5,8 @@
  * `SESSION_SNAPSHOT_BUCKET`(缺省 `session-snapshots`)是 snapshot-BLOB offload 与 SendUserFile 私有 presigned 轨 / 沙箱 staging 的桶。server 不建桶
  * (`docs/DEPLOY-PREREQS.md`「对象存储桶」),sema-up 的建桶清单又漏过它 ⇒ 起服绿,之后每一次对象写、每一拍孤儿 sweep 的列举(每分钟)都是
  * 404 NoSuchBucket —— 运维读到的是一串「失败的请求」,不是「桶没建」。
+ * `WORKSPACE_SNAPSHOT_BUCKET`(缺省 `workspaces`,k8s 工作区快照桶)同病且更隐:起服不核它 ⇒ 缺桶 / 无权限时每条 run 读 `latest` 得 404,
+ * 被读成「这个空间头一回」,从空目录起;run 末的保存虽失败,报的却是一条不点名桶的 curl 404,没有一行说「桶没建」。
  *
  * ## 形(一条规则,不加特例)
  *  · 核的是 {@link MinioBlobBackend.probeBucket}(presigned 列举 `max-keys=1`);**只有** 404 + `NoSuchBucket` 是「缺」,其余证明不了的形(连不上 / 403 / 5xx / 没有
@@ -13,24 +15,57 @@
  *  · 缺 = 配置好的店资源还没就绪,与「库连不上」同一类处境:在 `STORE_LOCK_WAIT_MS` 窗内重试({@link openWithinWait},同一只窗、同一只节拍、同一条窗尾规则 —— 编排里
  *    建桶晚于 server 起是常态),到窗时手上有缺桶的证据 ⇒ 拒启,拒句点名桶名、`MINIO_ENDPOINT` 的显示安全形(`buildDisplaySafeUrl` 的产物:userinfo 落地、
  *    query 值成记号,不带密钥)与出路;探针从头到尾没答过(每一次都挂到窗尾)⇒ 同样是「证明不了」,走上面那只兜底口、照常起服。
- *  · 只核**快照桶**(`config.snapshotBlobStore.bucket`;SendUserFile 的私桶缺省同一只);公桶 `sema-public` 是运维另配的匿名桶,不在本核之内。
+ *  · 核的桶是一张角色表({@link SNAPSHOT_BUCKET_ROLES},闭集两行)里的两只,**同一只探针、同一条规则、同一只兜底口**:
+ *    `session` = `config.snapshotBlobStore.bucket`(`SESSION_SNAPSHOT_BUCKET`;SendUserFile 的私桶缺省同一只);
+ *    `workspace` = k8s 车道的 `config.remoteExec.s3Snapshot.bucket`(`WORKSPACE_SNAPSHOT_BUCKET`,缺省 `workspaces`)—— 车道没开 / 没配对象存储 ⇒ 没有这只桶,不核。
+ *    拒句的旋钮名跟着桶走(缺的是哪只桶就只点哪只的旋钮)。公桶 `sema-public` 是运维另配的匿名桶,不在本核之内。
+ *  · 运行期的对应臂:工作区 `latest` 指针读答 404 `NoSuchBucket`(同一条「桶不在」判据 `isNoSuchBucketAnswer`)⇒ 那条 run 响亮拒绝,不再读成「空间头一回」
+ *    (`remote-env-k8s.ts` `readPointer`)—— 起服核之后桶被删 / 起服核证明不了的部署,在运行期也有一道。
  */
 import type { ServiceConfig } from "../config-types.js";
 import { type StoreOpenWaitClock } from "./store-open-wait.js";
 type SnapshotBlobStoreConfig = NonNullable<ServiceConfig["snapshotBlobStore"]>;
+/** 被核的桶的角色(闭集):`session` = 快照 blob / SendUserFile 私桶;`workspace` = k8s 工作区快照桶。 */
+export type SnapshotBucketRole = "session" | "workspace";
+/** 两只被核的桶的角色表 —— 拒句、`snapshot_bucket_wait` 披露与 {@link ensureSnapshotBuckets} 都读这一张(缺一行 = 编译错)。 */
+export declare const SNAPSHOT_BUCKET_ROLES: {
+    readonly session: {
+        readonly noun: "snapshot bucket";
+        readonly knob: "SESSION_SNAPSHOT_BUCKET";
+        readonly defaultName: "session-snapshots";
+        readonly consequence: "every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever)";
+        readonly createHint: "; this version's sema-up scripts create it — re-run them on an existing sema-up deployment";
+    };
+    readonly workspace: {
+        readonly noun: "workspace snapshot bucket";
+        readonly knob: "WORKSPACE_SNAPSHOT_BUCKET";
+        readonly defaultName: "workspaces";
+        readonly consequence: "no workspace snapshot could be saved or restored (every run would start from an empty /workspace and every run-end save would fail on a bare 404), and no line would say the bucket is missing";
+        readonly createHint: "";
+    };
+};
 /** boot 期单次探针的上界(ms):黑洞端点(丢包不拒连)不许把起服拖到对象存储 IO 的 120s;到点 ⇒ `unknown`(证明不了缺桶 ⇒ 不拒、报一次)。 */
 export declare const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10000;
 /** 缺桶的拒启句(唯一铸点)。 */
 /** @param endpoint `MINIO_ENDPOINT` 的**显示安全形**(调用方过 {@link buildDisplaySafeUrl};本函数不碰原串)。 */
-export declare function buildSnapshotBucketRefusal(bucket: string, endpoint: string, waitedMs: number): string;
+export declare function buildSnapshotBucketRefusal(bucket: string, endpoint: string, waitedMs: number, role?: SnapshotBucketRole): string;
 /** 探针到窗尾一次都没答过时,兜底口 detail 里的成因(证明不了缺桶的一形)。 */
 export declare const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
 /**
- * boot 期核一次快照桶(`boot/stores.ts`)。缺桶 ⇒ 窗内重试、到窗拒启;证明不了 ⇒ 兜底口留痕、照常起服。
+ * boot 期核一次**一只**快照桶。缺桶 ⇒ 窗内重试、到窗拒启;证明不了 ⇒ 兜底口留痕、照常起服。
  * @param waitMs `config.storeLockWaitMs`。`0` ⇒ 只核一次(缺就当场拒)。
+ * @param role 这只桶的角色({@link SNAPSHOT_BUCKET_ROLES}):决定拒句点名哪根旋钮;缺省 `session`。
  */
 export declare function ensureSnapshotBucket(store: SnapshotBlobStoreConfig, waitMs: number, logger: {
     warn(msg: string, meta?: Record<string, unknown>): void;
-}, clock?: StoreOpenWaitClock): Promise<void>;
+}, clock?: StoreOpenWaitClock, role?: SnapshotBucketRole): Promise<void>;
+/**
+ * boot 期核**这份配置要用的全部**快照桶(`boot/stores.ts`,排在打开任何店之前):角色表的每一行,配置里有这只桶才核 —— 会话快照桶 ⇐ 配了对象存储
+ * (`snapshotBlobStore`);工作区快照桶 ⇐ k8s 车道配了对象存储(`remoteExec.s3Snapshot`)。依角色表顺序逐只核,每只各有自己的 `STORE_LOCK_WAIT_MS` 窗
+ * (缺的桶才占窗;在场的桶一次探针就过),第一只缺的桶即拒启。
+ */
+export declare function ensureSnapshotBuckets(config: Pick<ServiceConfig, "snapshotBlobStore" | "remoteExec" | "storeLockWaitMs">, logger: {
+    warn(msg: string, meta?: Record<string, unknown>): void;
+}): Promise<void>;
 export {};
 //# sourceMappingURL=snapshot-bucket-presence.d.ts.map

package/dist/plugins/snapshot-bucket-presence.js

@@ -1,21 +1,39 @@
 import { buildDisplaySafeUrl } from "../trace/redact.js";
 import { MinioBlobBackend } from "./blob-backend.js";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { SESSION_SNAPSHOT_BUCKET_DEFAULT, WORKSPACE_SNAPSHOT_BUCKET_DEFAULT } from "../object-store-buckets.js";
 import { isStoreOpenWindowExpired, openWithinWait } from "./store-open-wait.js";
+export const SNAPSHOT_BUCKET_ROLES = {
+    session: {
+        noun: "snapshot bucket",
+        knob: "SESSION_SNAPSHOT_BUCKET",
+        defaultName: SESSION_SNAPSHOT_BUCKET_DEFAULT,
+        consequence: "every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever)",
+        createHint: "; this version's sema-up scripts create it — re-run them on an existing sema-up deployment",
+    },
+    workspace: {
+        noun: "workspace snapshot bucket",
+        knob: "WORKSPACE_SNAPSHOT_BUCKET",
+        defaultName: WORKSPACE_SNAPSHOT_BUCKET_DEFAULT,
+        consequence: "no workspace snapshot could be saved or restored (every run would start from an empty /workspace and every run-end save would fail on a bare 404), and no line would say the bucket is missing",
+        createHint: "",
+    },
+};
 export const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10_000;
 class SnapshotBucketMissing extends Error {
     constructor() {
         super("snapshot bucket missing");
     }
 }
-export function buildSnapshotBucketRefusal(bucket, endpoint, waitedMs) {
+export function buildSnapshotBucketRefusal(bucket, endpoint, waitedMs, role = "session") {
+    const r = SNAPSHOT_BUCKET_ROLES[role];
     const waited = waitedMs > 0 ? `after retrying for ${waitedMs}ms (STORE_LOCK_WAIT_MS)` : "on the first check (STORE_LOCK_WAIT_MS=0: no wait)";
-    return (`Object storage is configured (MINIO_ENDPOINT → ${endpoint}) but the snapshot bucket "${bucket}" (SESSION_SNAPSHOT_BUCKET; default session-snapshots) does not exist there ${waited} — refusing to boot: ` +
-        `the server never creates buckets, so every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever). ` +
-        `Next: create the bucket (mc mb <alias>/${bucket}; this version's sema-up scripts create it — re-run them on an existing sema-up deployment), or set SESSION_SNAPSHOT_BUCKET to a bucket that exists.`);
+    return (`Object storage is configured (MINIO_ENDPOINT → ${endpoint}) but the ${r.noun} "${bucket}" (${r.knob}; default ${r.defaultName}) does not exist there ${waited} — refusing to boot: ` +
+        `the server never creates buckets, so ${r.consequence}. ` +
+        `Next: create the bucket (mc mb <alias>/${bucket}${r.createHint}), or set ${r.knob} to a bucket that exists.`);
 }
 export const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
-export async function ensureSnapshotBucket(store, waitMs, logger, clock) {
+export async function ensureSnapshotBucket(store, waitMs, logger, clock, role = "session") {
     const probe = new MinioBlobBackend({ endpoint: store.endpoint, bucket: store.bucket, accessKey: store.accessKey, secretKey: store.secretKey, ...(store.region ? { region: store.region } : {}), ...(store.keyPrefix ? { keyPrefix: store.keyPrefix } : {}) });
     let verdict;
     try {
@@ -24,11 +42,11 @@ export async function ensureSnapshotBucket(store, waitMs, logger, clock) {
             if (r.state === "missing")
                 throw new SnapshotBucketMissing();
             return r;
-        }, waitMs, (w) => logger.warn("snapshot_bucket_wait", { bucket: store.bucket, endpoint: buildDisplaySafeUrl(store.endpoint), waitMs: w.waitMs, error: w.error }), clock);
+        }, waitMs, (w) => logger.warn("snapshot_bucket_wait", { role, bucket: store.bucket, endpoint: buildDisplaySafeUrl(store.endpoint), waitMs: w.waitMs, error: w.error }), clock);
     }
     catch (err) {
         if (err instanceof SnapshotBucketMissing)
-            throw new Error(buildSnapshotBucketRefusal(store.bucket, buildDisplaySafeUrl(store.endpoint), waitMs), { cause: err });
+            throw new Error(buildSnapshotBucketRefusal(store.bucket, buildDisplaySafeUrl(store.endpoint), waitMs, role), { cause: err });
         if (!isStoreOpenWindowExpired(err))
             throw err;
         verdict = { state: "unknown", detail: SNAPSHOT_BUCKET_PROBE_PENDING };
@@ -37,4 +55,14 @@ export async function ensureSnapshotBucket(store, waitMs, logger, clock) {
         recordFailOpen("server.snapshot-bucket.presence-unproven", `bucket=${store.bucket} endpoint=${buildDisplaySafeUrl(store.endpoint)} ${verdict.detail}`);
     }
 }
+export async function ensureSnapshotBuckets(config, logger) {
+    const wanted = [
+        ["session", config.snapshotBlobStore],
+        ["workspace", config.remoteExec?.provider === "k8s" ? config.remoteExec.s3Snapshot : undefined],
+    ];
+    for (const [role, store] of wanted) {
+        if (store)
+            await ensureSnapshotBucket(store, config.storeLockWaitMs, logger, undefined, role);
+    }
+}
 //# sourceMappingURL=snapshot-bucket-presence.js.map

package/dist/plugins/sql-errors.d.ts

@@ -129,11 +129,13 @@ export declare function rowTooLargeWallOf(dialect: SqlDialect, err: unknown): Ro
  * (`ErrEntryTooLarge`,事务层的语句错;真库读数:同池上 8025 写之后的读照常 —— `checkpoint-row-size-db-integration` ②③④)。
  * 断连形(`ECONNRESET` / `EPIPE` / `PROTOCOL_CONNECTION_LOST`)也不在表里:那是 mysql2 的**致命错误**,连接对象自己已经 `_removeFromPool`。
  * PostgreSQL 没有对应面:node-pg 的 `pool.query` 对任何错误都丢弃那条 client。
+ * `statementRefusal`:这一行的错说的是**这一条语句**被拒(连接坏只是后果)—— 同一句话换一条连接重试仍被拒。{@link isConnectionFaultError} 读同一张表,认其余各行为连接类故障,唯独不认带这个标记的行。
  * 新增一行 = 改表 + 在 `test/db-closed-connection-never-pooled.test.ts` 的码表里加一格。
  */
 export declare const MYSQL_CONNECTION_UNUSABLE_ERRORS: ReadonlyArray<{
     readonly errno: number;
     readonly code: string;
+    readonly statementRefusal?: true;
 }>;
 /**
  * 「抛出这个错误的那条连接还能不能回池」的单一判据:{@link MYSQL_CONNECTION_UNUSABLE_ERRORS} 里的错 ⇒ **不能** —— 持连接的一方(`sql-driver.ts` 的 `leaseOf`)
@@ -141,6 +143,64 @@ export declare const MYSQL_CONNECTION_UNUSABLE_ERRORS: ReadonlyArray<{
  * 认不出的一律不是(连接照常归还;断连形由 mysql2 自己清出池)。只管 MySQL 协议的错误形:PG 的错误没有这两个键,恒 false。
  */
 export declare function isConnectionUnusableError(err: unknown): boolean;
+/**
+ * **连接类故障**的识别表(闭集;逐行登记「为什么」)—— 「到库的那条连接坏了 / 库此刻不接」:与这一条语句的内容无关、什么都不改稍后再试可能成。
+ * 读者(整仓一只判官 `plugins/store-fault.ts` 的 `storeFaultClassOf`,三处同读):审批队列读口、文件历史店的折点(`permanence: "transient"`)、会话同步拉取口(`503` + `permanence: "transient"`)。
+ *
+ * 识别集 = 三张表的并集,**没有第四处**:
+ *  · 本表(下):套接字层与协议层的断连 / 拒连 / 连接数满 / 库的关停与只读切换,按 `code` 登记(MySQL 协议的数字 errno 在场的并登 —— 同本文件其余谓词的姿势:`errno` 与 `code` 是同一件事的两种写法);
+ *  · {@link MYSQL_CONNECTION_UNUSABLE_ERRORS}(「这条连接不许再回池」的 MySQL 协议错):整表读入,**唯独不认带 `statementRefusal` 的行**(1153:拒的是这一条语句,不是连接);
+ *  · {@link CONNECTION_FAULT_DRIVER_SENTENCES}:驱动自己抛的**无 `code` 的裸 `Error`**(node-pg 的断连在这一形),按整句相等认。
+ *
+ * **不在识别集里**(认不出一律不是 —— 错判成连接类的代价是调用方被劝「再试」去撞一个注定失败的语句):
+ *  · 语句级的错:唯一键冲突、CHECK 被拒、缺列、语法错、行 / 包超墙(1153 / 8025 / `54000`);缺表与权限拒也不是连接类 —— 它们是**部署错配类**(判官的另一个词,识别表 {@link DEPLOYMENT_FAULT_ERRORS},与本表互斥);
+ *  · 死锁(引擎的仲裁产物,重试的前提在调用方的整事务重来,见 {@link isDeadlockError})与锁等待 / 语句超时(延迟信号,重试只把长等待乘上次数);
+ *  · 认证类拒连(MySQL 1045、PG `28xxx`、`08004`:凭据 / 白名单要人去改)与协议违例(PG `08P01`、mysql2 `PROTOCOL_ERROR`:我方的码病);
+ *  · TiDB 自己的忙 / 区域不可用(9001 / 9005 一族)—— 候真库逐码读数再登,今天不在表里(登记在案的未收项);
+ *  · 池已被我方关闭(`Pool is closed.` / `Cannot use a pool after calling end on the pool`):那是本进程在收摊,不是库的事。
+ * 只看被抛出的**这一只**对象(不沿 `cause` 链往下找):店层把驱动错包进自己的类时,包它的那一层要不要继承连接类,归那一层的契约说,不在这里猜。
+ */
+export declare const CONNECTION_FAULT_ERRORS: ReadonlyArray<{
+    readonly code: string;
+    readonly errno?: number;
+    readonly why: string;
+}>;
+/**
+ * 驱动**自己抛的、不带 `code` 的裸 `Error`** 的整句 —— 连接类故障的第三种归因键。node-pg 的断连 / 池连接超时就是这一形(`new Error('Connection terminated unexpectedly')`,
+ * 没有任何结构化字段可读),mysql2 的「连接已关闭」同形。**整句相等**才认(不是 `includes`):一句夹着用户路径 / 数据的散文伪造不出驱动句;且只认 `code` 缺席的 `Error`。
+ * 每一行的 `source` 是它在驱动源码里的出处文件,`test/store-fault-judge.test.ts` 读已装驱动的源码核句子仍在(驱动升级改了句子 ⇒ 红,而不是判官悄悄静音)。
+ */
+export declare const CONNECTION_FAULT_DRIVER_SENTENCES: ReadonlyArray<{
+    readonly sentence: string;
+    readonly source: string;
+    readonly why: string;
+}>;
+/**
+ * 「这个错误**是**连接类故障吗」—— {@link CONNECTION_FAULT_ERRORS} 的唯一判据(识别集与排除项见该表头注)。纯谓词、不抛;认不出的一律不是。
+ * 归因键三种:`code`(字符串)、`errno`(数字)、无 `code` 的驱动裸 `Error` 的整句 —— 只读被抛出的这一只对象身上的结构化字段 / 整句,**不读散文里的在册词**。
+ */
+export declare function isConnectionFaultError(err: unknown): boolean;
+/**
+ * **部署错配类故障**的识别表(闭集;逐行登记「为什么」)—— 到库的连接是好的、语句也是对的,是这套库的形与本部署的要求不符:**重试注定失败**,修表 / 授权之前什么都不会变
+ * (与连接类互为反面:那一类是「什么都不改稍后再试可能成」)。读者:整仓一只判官 `plugins/store-fault.ts` 的 `storeFaultClassOf` 的 `deployment` 一词 ——
+ * 文件历史店的折点与会话同步拉取口(`503 state.file_history_unreadable`)据它判 `permanence: "terminal"`;审批队列读口并入「此刻读不出」的 503;各读者各自表态,**不在自己那里写码**。
+ *
+ * 识别集 = 本表一张,按归因键登记:`code`(字符串)与 MySQL 协议的数字 `errno`(两键是同一件事的两种写法,代理 / 序列化往返可能只留一个;同本文件其余谓词的姿势)。
+ * **与连接类互斥**:本表的任何一码都不在 {@link CONNECTION_FAULT_ERRORS} / {@link MYSQL_CONNECTION_UNUSABLE_ERRORS} 的识别集里,反之亦然(`test/store-fault-judge.test.ts` 钉两个方向)—— 同一只错只落一个词。
+ *
+ * **不在表里**(认不出一律不是;本批只收缺表与权限拒两形,其余是登记在案的未收项,不是「已裁定不判」):缺列(1054 / `42703`:升级前置断言 `assert*Schema` 族有自己的判据与出路)、
+ * 认证类拒连(MySQL 1045、PG `28xxx`:凭据 / 白名单)、库级与列级的权限拒(MySQL 1044 / 1143)、TiDB 自己的忙 / 区域不可用一族(同连接类表的登记)。
+ */
+export declare const DEPLOYMENT_FAULT_ERRORS: ReadonlyArray<{
+    readonly code: string;
+    readonly errno?: number;
+    readonly why: string;
+}>;
+/**
+ * 「这个错误**是**部署错配类故障吗」—— {@link DEPLOYMENT_FAULT_ERRORS} 的唯一判据(识别集与排除项见该表头注)。纯谓词、不抛;认不出的一律不是。
+ * 只读被抛出的**这一只**对象身上的结构化字段(`code` 字符串 / `errno` 数字),不沿 `cause` 链找、不读散文里的在册词。
+ */
+export declare function isDeploymentFaultError(err: unknown): boolean;
 /**
  * 检查点店的两笔写(续跑输入 `putCtx` / 停驻行 `put`)被引擎以「一行装不下」拒 ⇒ **这一只**带码错误(码 `store.row_too_large`),不以裸驱动错上抛
  * (其余店写今天仍是各自的驱动错 —— 未收,登记在案)。

package/dist/plugins/sql-errors.js

@@ -64,7 +64,7 @@ export function rowTooLargeWallOf(dialect, err) {
 export const MYSQL_CONNECTION_UNUSABLE_ERRORS = [
     { errno: 1053, code: "ER_SERVER_SHUTDOWN" },
     { errno: 1152, code: "ER_ABORTING_CONNECTION" },
-    { errno: 1153, code: "ER_NET_PACKET_TOO_LARGE" },
+    { errno: 1153, code: "ER_NET_PACKET_TOO_LARGE", statementRefusal: true },
     { errno: 1158, code: "ER_NET_READ_ERROR" },
     { errno: 1159, code: "ER_NET_READ_INTERRUPTED" },
     { errno: 1160, code: "ER_NET_ERROR_ON_WRITE" },
@@ -82,6 +82,69 @@ export function isConnectionUnusableError(err) {
     const code = keyOf(err, "code");
     return (typeof errno === "number" && UNUSABLE_ERRNOS.has(errno)) || (typeof code === "string" && UNUSABLE_CODES.has(code));
 }
+export const CONNECTION_FAULT_ERRORS = [
+    { code: "ECONNRESET", why: "对端重置了连接(库重启 / 代理断流 / 空闲连接被回收)" },
+    { code: "ECONNREFUSED", why: "库此刻不接连接(进程没起 / 端口没开 / 滚动重启中)" },
+    { code: "ECONNABORTED", why: "连接在建立或使用中被本机协议栈中止" },
+    { code: "EPIPE", why: "写一条对端已经关掉的连接" },
+    { code: "ETIMEDOUT", why: "连接 / 套接字超时(mysql2 的 `connectTimeout` 同答此码)" },
+    { code: "EHOSTUNREACH", why: "到库的主机不可达(路由 / 节点切换)" },
+    { code: "ENETUNREACH", why: "到库的网络不可达" },
+    { code: "EAI_AGAIN", why: "DNS 临时失败(「稍后再试」是它自己的定义)" },
+    { code: "PROTOCOL_CONNECTION_LOST", why: "mysql2:服务端关了连接(`Connection lost: The server closed the connection.`,带 `fatal: true`)" },
+    { code: "ER_CON_COUNT_ERROR", errno: 1040, why: "连接数满(`Too many connections`)—— 别人放连接之后就好" },
+    { code: "08000", why: "PG connection_exception" },
+    { code: "08001", why: "PG sqlclient_unable_to_establish_sqlconnection" },
+    { code: "08003", why: "PG connection_does_not_exist" },
+    { code: "08006", why: "PG connection_failure" },
+    { code: "57P01", why: "PG admin_shutdown(库被管理员关停 / 重启)" },
+    { code: "57P02", why: "PG crash_shutdown" },
+    { code: "57P03", why: "PG cannot_connect_now(启动 / 恢复中)" },
+    { code: "53300", why: "PG too_many_connections" },
+    { code: "25006", why: "PG read_only_sql_transaction(故障切换后落在只读节点)" },
+];
+export const CONNECTION_FAULT_DRIVER_SENTENCES = [
+    { sentence: "Connection terminated unexpectedly", source: "pg/lib/client.js", why: "node-pg:连接在使用中被对端关掉" },
+    { sentence: "Client has encountered a connection error and is not queryable", source: "pg/lib/client.js", why: "node-pg:这条 client 的连接已出错,后续语句直接拒" },
+    { sentence: "Connection terminated due to connection timeout", source: "pg-pool/index.js", why: "node-pg 池:建连超过 `connectionTimeoutMillis`" },
+    { sentence: "timeout exceeded when trying to connect", source: "pg-pool/index.js", why: "node-pg 池:排队等连接超过 `connectionTimeoutMillis`" },
+    { sentence: "Can't add new command when connection is in closed state", source: "mysql2/lib/base/connection.js", why: "mysql2:往一条已被对端关掉的连接上发语句(带 `fatal: true`、无 `code`)" },
+];
+const CONNECTION_FAULT_CODES = new Set([
+    ...CONNECTION_FAULT_ERRORS.map((r) => r.code),
+    ...MYSQL_CONNECTION_UNUSABLE_ERRORS.filter((r) => r.statementRefusal !== true).map((r) => r.code),
+]);
+const CONNECTION_FAULT_ERRNOS = new Set([
+    ...CONNECTION_FAULT_ERRORS.flatMap((r) => (r.errno === undefined ? [] : [r.errno])),
+    ...MYSQL_CONNECTION_UNUSABLE_ERRORS.filter((r) => r.statementRefusal !== true).map((r) => r.errno),
+]);
+const CONNECTION_FAULT_SENTENCES = new Set(CONNECTION_FAULT_DRIVER_SENTENCES.map((r) => r.sentence));
+export function isConnectionFaultError(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const code = keyOf(err, "code");
+    const errno = keyOf(err, "errno");
+    if (typeof code === "string" && CONNECTION_FAULT_CODES.has(code))
+        return true;
+    if (typeof errno === "number" && CONNECTION_FAULT_ERRNOS.has(errno))
+        return true;
+    return err instanceof Error && code === undefined && CONNECTION_FAULT_SENTENCES.has(err.message);
+}
+export const DEPLOYMENT_FAULT_ERRORS = [
+    { code: "42P01", why: "PG undefined_table(缺表:库没按本版的表结构建好 / 迁移没跑 —— 重试不会让表长出来)" },
+    { code: "42501", why: "PG insufficient_privilege(权限拒:库账号缺这张表 / 这类语句的授权 —— 授权之前重试注定失败)" },
+    { code: "ER_NO_SUCH_TABLE", errno: 1146, why: "MySQL 协议(MySQL / MariaDB / TiDB)缺表:同 PG `42P01`" },
+    { code: "ER_TABLEACCESS_DENIED_ERROR", errno: 1142, why: "MySQL 协议表级权限拒:库账号对这张表缺这类语句的授权,同 PG `42501`" },
+];
+const DEPLOYMENT_FAULT_CODES = new Set(DEPLOYMENT_FAULT_ERRORS.map((r) => r.code));
+const DEPLOYMENT_FAULT_ERRNOS = new Set(DEPLOYMENT_FAULT_ERRORS.flatMap((r) => (r.errno === undefined ? [] : [r.errno])));
+export function isDeploymentFaultError(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    const code = keyOf(err, "code");
+    const errno = keyOf(err, "errno");
+    return (typeof code === "string" && DEPLOYMENT_FAULT_CODES.has(code)) || (typeof errno === "number" && DEPLOYMENT_FAULT_ERRNOS.has(errno));
+}
 export class StoreRowTooLargeError extends Error {
     row;
     wall;

package/dist/plugins/store-contracts.d.ts

@@ -19,6 +19,7 @@
  *    code should import from this file.
  */
 import type { PeerSessionTempo, TaskResult, TaskStatus } from "@sema-agent/core";
+import type { RunIdentity } from "../identity-source.js";
 /**
  * **File 店族的 boot 期拒启基类**([ref];把 `RunStoreStrictHydrateError` 的那条论证升成一条族规)。
  *
@@ -212,8 +213,13 @@ export interface RunRecord {
      *  (MCP façade / portal). null when the caller didn't supply one. */
     jobId: string | null;
     /** Which SYSTEM's credential submitted the run (oa/cc-mcp/portal…), derived at the auth gate — never
-     *  self-declared. null = legacy single-token deployment (authenticated, no system identity). */
+     *  self-declared. null = legacy single-token deployment (authenticated, no system identity).
+     *  **归因用,不是认证来源**:任何凭据判都不读它(认证来源 = {@link RunRecord.identity});系统名是运维写的任意串,`"sso"` 也只是归因值。 */
     source: string | null;
+    /** 🔴 **run 行身份元组**(三列 `identity_source` / `identity_scope` / `identity_principal_inc`):受理时在凭据门上铸、建行时写入、之后只读 ——
+     *  续跑认领 / 挂起 / 终局 / 重启都不改它,没有按当前状态重算的读者。`null` = 这一行没有「属主在受理时验过的凭据」的记录(三列之前的行 /
+     *  无鉴权写面的受理 / 别人替属主按下的那一跑),一律不合格。律与形的唯一属主 = `identity-source.ts`。不上 wire(run 读面是显式投影,不带它)。 */
+    identity: RunIdentity | null;
     /** The replica currently HOLDING this run — written at createRun and TAKEN OVER by markResuming ([ref]: a
      *  cross-replica resume moves the seat, so a reader comparing it with its own instanceId is asking "is the
      *  live leg here NOW", not "who minted the row"). Lets a preempt/cancel/steer handler tell "this run is on
@@ -263,6 +269,9 @@ export interface RunIdemBinding {
 export interface NewRunMeta {
     jobId?: string | null;
     source?: string | null;
+    /** 这一行的身份元组(`RunRecord.identity` 的写口)。缺席 = `null`(没有记录;不合格)。`src/http/**` 的每个建行点都显式写它(机器门
+     *  `test/run-identity-tuple.test.ts`),取值只经凭据门铸下的那一份(`principal-gate.ts` 的 `runIdentityOf`)。 */
+    identity?: RunIdentity | null;
     objectivePreview?: string | null;
     idem?: RunIdemBinding | null;
 }

package/dist/plugins/store-fault.d.ts

@@ -0,0 +1,4 @@
+export type StoreFaultClass = "corrupt" | "connection" | "deployment" | "unclassified";
+/** 判官本体。纯函数、不抛;只看被抛出的这一只对象(不沿 `cause` 链找)。两张识别表互斥,判序不影响结果(`test/store-fault-judge.test.ts` 钉互斥)。 */
+export declare function storeFaultClassOf(err: unknown): StoreFaultClass;
+//# sourceMappingURL=store-fault.d.ts.map

package/dist/plugins/store-fault.js

@@ -0,0 +1,10 @@
+import { isConnectionFaultError, isDeploymentFaultError } from "./sql-errors.js";
+import { StoreCorruptError } from "./sql-json-column.js";
+export function storeFaultClassOf(err) {
+    if (err instanceof StoreCorruptError)
+        return "corrupt";
+    if (isConnectionFaultError(err))
+        return "connection";
+    return isDeploymentFaultError(err) ? "deployment" : "unclassified";
+}
+//# sourceMappingURL=store-fault.js.map

package/dist/plugins/tidb-pool.js

@@ -7,6 +7,7 @@ import { TIDB_ADOPTION_LOG_STATEMENTS } from "./adoption-log-sql.js";
 import { TIDB_PERMISSION_RULE_STATEMENTS } from "./permission-rule-store-sql.js";
 import { TIDB_RETENTION_STATEMENTS } from "./retention-store-sql.js";
 import { SESSION_META_INCARNATION_COLUMN } from "../session-incarnation.js";
+import { RUN_IDENTITY_COLUMNS } from "../identity-source.js";
 import { SESSION_RULES_COLUMN } from "./session-rules-column.js";
 import { SESSION_TITLE_MAX_CHARS } from "../session-row.js";
 import { PRINCIPAL_MAX_UTF8_BYTES } from "../security.js";
@@ -86,7 +87,7 @@ export const SCHEMA_STATEMENTS = [
      placed_at                   DATETIME(3)  NULL,
      -- S-790 / S-506(design/330 §2):会话化身 —— 同一个会话 id 上**这一位住客**的不透明令牌。铸点只在新建行(register /
      -- 无 id 创建 / fork / 导入新行),删除随行消失,同 id 重登记铸新的;'' = 没铸过,读口响亮拒。列定义的唯一属主 =
-     -- src/session-incarnation.ts 的 SESSION_META_INCARNATION_COLUMN(存量库由一次性迁移 M5 用同一串补列 + 回填)。
+     -- src/session-incarnation.ts 的 SESSION_META_INCARNATION_COLUMN(存量库缺这一列 ⇒ 起服列册对账拒启,拒句里的 ALTER 由本建表语句生成)。
      -- 不上 wire、不进模型上下文、日志只打前 8 位。
      ${SESSION_META_INCARNATION_COLUMN.tidb},
      PRIMARY KEY (session_id),
@@ -155,6 +156,12 @@ export const SCHEMA_STATEMENTS = [
      -- source (credential-derived system identity, clay 2026-06-12): which door submitted the run
      -- (oa / cc-mcp / portal).
      source      VARCHAR(64)  NULL,
+     -- identity_source / identity_scope / identity_principal_inc: the run's identity tuple, minted ONCE at the credential gate when the
+     -- run is accepted and never rewritten (no UPDATE touches them). NULL = no record of a credential the owner presented at acceptance
+     -- (rows from before these columns, unauthenticated-write acceptance, a run someone else accepted on the owner's behalf) ⇒ not
+     -- qualified. Column definitions' single owner = src/identity-source.ts RUN_IDENTITY_COLUMNS (the boot column probe derives its
+     -- ALTER suggestion from this statement). \`source\` above is attribution only, never an authentication source.
+     ${RUN_IDENTITY_COLUMNS.tidb},
      -- objective_preview: the list's "what is this task" glance — redacted + truncated at write.
      objective_preview VARCHAR(160) NULL,
      -- cancel_requested: durable cross-replica CANCEL flag. The running instance's heartbeat tick honors it

package/dist/plugins/tidb-session-store.js

@@ -11,7 +11,7 @@ import { CLAIM_OWNERLESS_PLACED_SQL, claimOwnerlessParams, createPlacedSessionRo
 import { createLogger } from "../observability/logger.js";
 import { placementCapabilityOf, LIST_PLACED_BATCH, PLACEMENT_SELECT_COLUMNS, placedRowFromRow, placementFromRow, placementInsertValues, SQL_SESSION_PLACEMENTS, } from "./session-placement.js";
 import { classifySyncRelationshipByIds, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, STAGING_ID_MARKER, STAGING_GC_GRACE_MS, } from "../session-sync-kernel.js";
-import { assertFirstOwnerWritable, forkOwnerOf } from "./session-ownership.js";
+import { assertFirstOwnerWritable, forkOwnerOf, isSessionOwnerValue } from "./session-ownership.js";
 import { forkCopyOf, forkPointOf } from "./session-fork.js";
 export class TiDBSessionStore {
     pool;
@@ -58,7 +58,7 @@ export class TiDBSessionStore {
         return { session: new StoredSession(storage), sessionId };
     }
     async register(sessionId, owner) {
-        if (typeof owner !== "string" && owner !== null) {
+        if (!isSessionOwnerValue(owner)) {
             if ((await this.headOf(sessionId)) !== undefined)
                 return;
             assertFirstOwnerWritable(sessionId, owner);

package/dist/plugins/web-search.d.ts

@@ -54,7 +54,7 @@
  *    验证搜索配对不对。挂哪儿(boot 期一次性 warn / `/health` 子字段 / 显式端点)未定 ——
  *    注意 boot 期探活会给每次启动加一次出网,多租/离线部署要能关。
  */
-import { type UrlCredentialFacts } from "../url-credential.js";
+import { type UrlCredentialFacts } from "../url-credential-refusal.js";
 /**
  * Search providers this backend speaks —— **词表的唯一属主**(运行期与类型同一份)。
  * Absent `WEB_SEARCH_PROVIDER` ⇒ no backend ⇒ WebSearch is not assembled.

package/dist/plugins/web-search.js

@@ -1,8 +1,8 @@
 import { validateHeaderValue } from "node:http";
 import { createSearxngSearchBackend } from "@sema-agent/core";
-import { isHierarchicalUrl } from "@sema-agent/settings-schema";
+import { findUrlCredential, findUrlUserinfo, isHierarchicalUrl } from "@sema-agent/settings-schema";
 import { redactSecrets } from "../trace/redact.js";
-import { buildRequestUrlCredentialRefusal, findUrlCredential, findUrlUserinfo, urlCredentialFacts } from "../url-credential.js";
+import { buildRequestUrlCredentialRefusal, urlCredentialFacts } from "../url-credential-refusal.js";
 export const WEB_SEARCH_PROVIDERS = ["brave", "tavily", "searxng"];
 function isWebSearchProvider(word) {
     return WEB_SEARCH_PROVIDERS.includes(word);

package/dist/request-declaration-refusal.d.ts

@@ -0,0 +1,94 @@
+/**
+ * **请求体里「声明列表」(`mcpServers` · `a2aPeers`)这一类受理座的拒绝骨架** —— 列表级 / 条目级 / 键值级的拒形、拒句尾、撞帽机读位,在这里铸一处。
+ *
+ * ## 为什么在这里
+ * 两张列表是同一个问题的两个实例:调用方随请求带一份「我要挂这些外部服务」的声明,受理口要回答「这份声明能不能原样用」。答案的**形**一样 ——
+ *  ① **列表**:在场却不是数组 / 超过挂载上限 / 某一条不是对象 ⇒ `400 request.field_invalid`(整份拒而不是挂前 N 条 / 摘掉读不出的那条:一份被悄悄截短的声明,在发送方那里读起来是「生效了」);
+ *     超上限用撞帽的唯一铸点({@link limitRefusal}),拒体带机读位一组键(`field` · `reason:"over_cap"` · `count` · `cap`);
+ *  ② **键名**:条目层的词表外键 ⇒ `400 request.body_shape` + `unknownKeys`(句子由各座自己写 —— 受理键表与嵌套层是座位自己的事);
+ *  ③ **键值**:每个受理键一只判官 ⇒ `400 request.field_invalid`,句子 `<坐标>.<键路径> (<subject> "<名>") is not a usable declaration — <判官原因句>. …`,不回显值;
+ *     判官答「URL 带凭据」时拒体另带机读位 `field` / `reason`({@link urlCredentialFacts})。
+ * 第一处坏形即答:先列表、后条目;条目里先键名、后键值。各座只写**自己的**两件事:受理键表 + 键值判官表(以及它自己的词表外键句)。拒形、句尾、撞帽句不在座位文件里手拼 ——
+ * 两份手拼的拒形迟早分岔(`a2aPeers` 上线时就是缺了这一整套,坏形换回 200 + 运维 warn,调用方以为声明生效了)。
+ *
+ * ## 射程
+ * 纯值域、与租户车道无关;只在 fresh 提交腿上问(`boot/resolve-spec.ts` 的 `opts.leg`):重放存量 body 的腿走宽容读器,一个 4xx 打在 resume 上会永久砖死一条 parked 任务。
+ */
+import { type UrlCredential } from "@sema-agent/settings-schema";
+import { type LimitFacts } from "./limit-refusal.js";
+import { type UrlCredentialFacts } from "./url-credential-refusal.js";
+/** 一座声明列表的名字与上限、以及拒句里要用的称呼(座位的常量,铸点只读)。 */
+export interface DeclarationSeat {
+    /** 请求体里这张列表的键,也是机读坐标的根(`mcpServers` | `a2aPeers`)。 */
+    readonly list: string;
+    /** 挂载上限(条数;超过 ⇒ 撞帽拒)。 */
+    readonly cap: number;
+    /** 一条声明所声明的东西(拒句里的单数名词:`server` | `peer`)。 */
+    readonly subject: string;
+    /** 「一条声明」的整称(`an MCP server declaration`)。 */
+    readonly declaration: string;
+    /** 「多条声明」的整称(`MCP server declarations`)。 */
+    readonly declarations: string;
+}
+/** 一次拒绝:码 + 句 + 词表外的键名表(只在闭集那一形上在场)+ 机读位(撞帽 / URL 带凭据两形上在场)。受理口(同步 400)与探测口(`POST …/probe`)原样转述同一份。 */
+export interface DeclarationRefusal {
+    readonly errorCode: "request.body_shape" | "request.field_invalid";
+    readonly message: string;
+    /** 词表外的键,全路径形(已清洗 + 截长 + 排序 + 封顶)。 */
+    readonly unknownKeys?: readonly string[];
+    /** 撞帽:`field` · `reason:"over_cap"` · `count` · `cap`;URL 带凭据:`field` · `reason`(判官的拒因词)。 */
+    readonly facts?: UrlCredentialFacts | LimitFacts;
+}
+/** 一处键值坏形:键路径(相对条目)+ 判官的原因句;答「URL 带凭据」时另带判官的答案(⇒ 拒体带机读位)。 */
+export interface DeclarationKeyIssue {
+    readonly path: string;
+    readonly reason: string;
+    readonly credential?: UrlCredential;
+}
+/** 受理键 → 判官。`at` 是这一条的体内坐标(`a2aPeers[2]`),座位需要写绝对坐标的出路句时用。缺席(`undefined`)恒合法 = 真「没声明」;在场的 `null` 不是缺席。 */
+export type DeclarationKeyJudge<E extends Record<string, unknown> = Record<string, unknown>> = (entry: E, at: string) => DeclarationKeyIssue | undefined;
+/** 读不出名字的条目用的占位(非空:一条连名字都读不出的条目仍然要被说出来)。 */
+export declare const MALFORMED_NAME = "<malformed>";
+/** 条目的**申报名**(拿不到名字时的占位)—— 拒句、丢弃点、通告同读一只。 */
+export declare function declaredName(e: unknown): string;
+/** `name` 键的判官(两座同读:申报名线长界与首尾空白的唯一判官在契约包 {@link isUsableWireName})。 */
+export declare function declarationNameIssue(entry: Record<string, unknown>): DeclarationKeyIssue | undefined;
+/** 列表级拒句的收尾句:说清「为什么整份被拒、而不是只按读得出的那部分办」与出路(空列表 = 什么都不声明)。 */
+export declare const LIST_REFUSAL_TAIL: string;
+/** 列表级的一处坏形 → 拒(码恒 `request.field_invalid`)。`head` 只说位置与形的**种类**,不回显值。 */
+export declare function declarationListRefusal(head: string): DeclarationRefusal;
+/**
+ * 一处键值坏形**怎么被说出来**:体内坐标(`<条目坐标>.<键路径>`)+ 判官的原因句(只剥控制与双向字符,不回显值)。受理口的拒句与读器的丢弃因(请求腿运维 warn 的 `field` / `reason`)读**这一只** ——
+ * 原因只来自判官表,组句只在这里(两边各写一份,迟早分岔)。
+ */
+export declare function declarationIssueFacts(at: string, issue: DeclarationKeyIssue): {
+    readonly field: string;
+    readonly reason: string;
+};
+/**
+ * 列表条数撞帽**怎么被说出来**:坐标 = 列表键(`a2aPeers`)+ 撞帽铸点({@link limitRefusal})的头一句(`<列表> has N entries — at most M are accepted`)。受理口的撞帽拒句以同一句开头(接拒句尾),
+ * 读器的丢弃因读这一只 —— 与 {@link declarationIssueFacts} 同族:`reason` 只有一种内容 = 句子;机读词(`over_cap`)留在拒体的 `facts`,不进日志的 `reason`。
+ */
+export declare function declarationOverCapFacts(seat: DeclarationSeat, count: number): {
+    readonly field: string;
+    readonly reason: string;
+};
+/**
+ * 一条条目不是对象(`null` / 原始值 / 数组)的头一句:`<条目坐标> is <值的种类>, not <整称> (an object)`;是对象 ⇒ `undefined`。列表级拒({@link requestDeclarationRefusal})与读器的丢弃因读同一只,
+ * 「什么算对象」只在这里判。
+ */
+export declare function declarationEntryNotObject(seat: DeclarationSeat, entry: unknown, at: string): string | undefined;
+/** 一处键值坏形 → 拒。**所有键同一个形**;条目名过唯一的回显清洗,读不出名字的条目用占位,坐标与原因句由 {@link declarationIssueFacts} 铸。 */
+export declare function declarationFieldRefusal(seat: DeclarationSeat, entry: Record<string, unknown>, at: string, issue: DeclarationKeyIssue): DeclarationRefusal;
+/** 一条条目的键值判官表按受理键序问一遍,第一处坏形即返回。 */
+export declare function judgeDeclarationKeys<K extends string, E extends Record<string, unknown>>(seat: DeclarationSeat, entry: E, at: string, keys: readonly K[], judges: {
+    readonly [P in K]: DeclarationKeyJudge<E>;
+}): DeclarationRefusal | undefined;
+/**
+ * 一张声明列表「能不能原样用」的回答者骨架:列表级(缺席 / `null` ⇒ 没声明;不是数组 / 超上限 / 条目不是对象)在这里,条目级交座位的 `judgeEntry`(词表外的键 → 键值)。
+ * `undefined` = 能原样用(或没声明;各门自己定缺席的意思)。
+ */
+export declare function requestDeclarationRefusal(seat: DeclarationSeat, list: unknown, judgeEntry: (entry: Record<string, unknown>, at: string) => DeclarationRefusal | undefined): DeclarationRefusal | undefined;
+/** 受理口的转述:有答案 ⇒ 同步 400(码 / 句 / `unknownKeys` / 机读位原样);没有 ⇒ 什么也不做。 */
+export declare function throwDeclarationRefusal(refusal: DeclarationRefusal | undefined): void;
+//# sourceMappingURL=request-declaration-refusal.d.ts.map