@sema-agent/server 7.147.0 → 7.149.0

package/dist/observability/principal-context.d.ts

@@ -6,12 +6,19 @@
  * call still reads the originating principal. Absent store = unattributed (dev / no principal).
  */
 import { AsyncLocalStorage } from "node:async_hooks";
-export declare const principalContext: AsyncLocalStorage<string>;
-/** 这次执行的记账身份钉表;不在任何 {@link withPrincipal} 作用域里 ⇒ `undefined`(记账按此刻身份)。 */
+import { type Person, type Subject } from "../owner-brands.js";
+/**
+ * 场景子命名空间:ALS 带**主体**(分区键),不带人 —— 读者有两种:记账三写口(成本 / 用量批报 / 租约)读人({@link currentPerson} = `personOf(主体)`),
+ * leader 子任务的 spec 读分区(`leader/wire.ts` 经引擎交界一处铸身份格)。只带人会让 leader 子任务丢分区;只带主体、人现解码,两种读者各取一格。
+ */
+export declare const principalContext: AsyncLocalStorage<Subject>;
+/** 这次执行的记账身份钉表;不在任何 {@link withSubject} 作用域里 ⇒ `undefined`(记账按此刻身份)。 */
 export declare function currentExecutionPins(): Map<object, string> | undefined;
-/** Run `fn` with `principal` as the ambient context (principal-wise a no-op wrapper when principal is undefined — the outer
- *  principal, if any, stays). [ref]: also opens the execution's accounting-pin scope when none is open yet (nested calls share it). */
-export declare function withPrincipal<T>(principal: string | undefined, fn: () => T): T;
-/** The principal attributed to the current async execution, if any. */
-export declare function currentPrincipal(): string | undefined;
+/** Run `fn` with `subject` as the ambient context (a no-op wrapper when the subject is undefined — the outer
+ *  subject, if any, stays). [ref]: also opens the execution's accounting-pin scope when none is open yet (nested calls share it). */
+export declare function withSubject<T>(subject: Subject | undefined, fn: () => T): T;
+/** The subject (partition key) the current async execution runs in, if any. */
+export declare function currentSubject(): Subject | undefined;
+/** The person the current async execution is attributed to (cost / usage / lease accounting) = the person behind {@link currentSubject}. */
+export declare function currentPerson(): Person | undefined;
 //# sourceMappingURL=principal-context.d.ts.map

package/dist/observability/principal-context.js

@@ -1,14 +1,19 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { personOf } from "../owner-brands.js";
 export const principalContext = new AsyncLocalStorage();
 const executionPins = new AsyncLocalStorage();
 export function currentExecutionPins() {
     return executionPins.getStore();
 }
-export function withPrincipal(principal, fn) {
-    const run = () => (principal ? principalContext.run(principal, fn) : fn());
+export function withSubject(subject, fn) {
+    const run = () => (subject ? principalContext.run(subject, fn) : fn());
     return executionPins.getStore() !== undefined ? run() : executionPins.run(new Map(), run);
 }
-export function currentPrincipal() {
+export function currentSubject() {
     return principalContext.getStore();
 }
+export function currentPerson() {
+    const subject = principalContext.getStore();
+    return subject === undefined ? undefined : personOf(subject);
+}
 //# sourceMappingURL=principal-context.js.map

package/dist/observability/run-terminal.d.ts

@@ -86,7 +86,6 @@ export declare function notifyRunTerminal(rec: RunTerminalRecord): void;
  *  不抛**:脱敏失败 ⇒ 落固定占位 `«redacted:oversized»`(绝不落原文,也绝不阻断终态翻转),并走既有 fail-open 遥测 tag。
  *  🔴 [ref] 之后这条 throw 臂**照留**(结构性兜底,不依赖「脱敏器今天抛不抛」):它守的是「终态翻转不被一次脱敏异常拦下」,
  *  而脱敏器是一张会长新臂的表 —— 计数 `server.run-terminal.redact-threw` 恒零是证据,不归零就是新形,运维按 detail 回溯。 */
-export declare const OVERSIZED_REDACTION_PLACEHOLDER = "\u00ABredacted:oversized\u00BB";
 /** [ref] 窄范围重扫 [medium]:`redactSecrets` 对 PEM 起始栅栏密集的多 MB 文案**不抛但慢**(实测 1MB 1.4s / 8MB 7.9s 同步阻塞
  *  事件循环),而终态座每次写要扫两遍(appendEvent + setTerminal 入口)、每次读再扫一遍。超过本上限的自由文本**整段**换占位
  *  (fail-closed:不截断——截断会把密钥切成半截,[ref] 的病;不扫——O(1)),取证面丢的是「>256KB 的错误文案」这一档。 */
@@ -263,6 +262,13 @@ export declare function redactTerminalResult<T extends object | null | undefined
  * 本函数是**写入口**(结果第一次落盘 ⇒ 折码运维线索 `at=exit`);读面读存量行用 {@link sealStoredRunRowResult}(读座必填)。
  */
 export declare function sealRunRowResult(result: PersistedTaskResult | null): PersistedTaskResult | null;
+/**
+ * run 行 `error_code` 列的**写律**(三只 run 店、写 `result` 的三个写口 —— `setTerminal` / `setSuspended` / `setNeedsReview` —— 同一只):
+ * 列 = 落在行上的那份结果(已过 {@link sealRunRowResult})的对外码(core 的唯一派生 `outwardPlane`);没有结果 ⇒ `null`。
+ * 列是 run 的 `errorCode` 的**唯一读法**(读面、A2A、审批对账、fleet 都读它),所以停驻行的 `review.pending` 也落在列上。
+ * 其余迁移(续跑认领 / 收割 / 接管)把 `result` 写空的同时写自己的码或空,不经本函数。
+ */
+export declare function runRowErrorCodeOf(sealed: PersistedTaskResult | null): string | null;
 /**
  * {@link sealRunRowResult} 的**读入口**(`GET /v1/runs/:id` 的非终态臂读停驻行):同一套封口 + 同一只汇点,只差折码运维线索的观看点 ——
  * 读座必填({@link StoredResultReadSeat}),再观看走 fail-open 纪律(见 `terminal.ts` 的 `sealStoredResult`)。

package/dist/observability/run-terminal.js

@@ -3,8 +3,9 @@ import { redactSecrets } from "../trace/redact.js";
 import { isProviderEchoShape } from "@sema-agent/core";
 import { isModelTextLedgerEventType, isParkLedgerEventType } from "../trace/ledger-events.js";
 import { isUnsuccessfulRunStatus } from "../plugins/store-contracts.js";
-import { mapPauseSeats, PAUSE_SEATS, sealResultForExit, sealStoredResult } from "../terminal.js";
+import { mapPauseSeats, outwardPlane, PAUSE_SEATS, sealResultForExit, sealStoredResult } from "../terminal.js";
 import { errorText } from "./err-text.js";
+import { OVERSIZED_REDACTION_PLACEHOLDER } from "../trace/exit-seat.js";
 import { recordFailOpen } from "./fail-open.js";
 import { toolEndMediaAsDescriptors } from "../trace/tool-output-media.js";
 const MESSAGE_CAP = 1024;
@@ -53,7 +54,6 @@ export function notifyRunTerminal(rec) {
         ...(rec.elapsedMs !== undefined ? { elapsedMs: rec.elapsedMs } : {}),
     });
 }
-export const OVERSIZED_REDACTION_PLACEHOLDER = "«redacted:oversized»";
 export const REDACT_INPUT_CAP = 65_536;
 export const REDACT_OUTPUT_MAX_BYTES = 65_000;
 const OUTPUT_TRUNCATED_MARK = "…[truncated: exceeds store column]";
@@ -175,6 +175,7 @@ export const RESULT_TEXT_LEAVES = {
     "cancelContext.lastEventKind": "verbatim",
     "cancelContext.lastBrainStatus.phase": "verbatim",
     "cancelContext.lastBrainStatus.errClass": "verbatim",
+    "readDenyFloor.message": "verbatim",
 };
 const DROP_LEAF = Symbol("drop-leaf");
 function textLeafAct(treatment) {
@@ -436,6 +437,9 @@ function redactLegacyPlaneLeaves(result) {
 export function sealRunRowResult(result) {
     return result === null ? null : redactTerminalResult(sealResultForExit(result));
 }
+export function runRowErrorCodeOf(sealed) {
+    return sealed === null ? null : (outwardPlane(sealed.terminal).errorCode ?? null);
+}
 export function sealStoredRunRowResult(result, seat) {
     return result === null ? null : redactTerminalResult(sealStoredResult(result, seat));
 }

package/dist/observability/secret-env-scrub.d.ts

@@ -90,7 +90,7 @@ export declare const SECRET_ENV_SCRUB_SITES: {
     };
     readonly "server.hooks.spawn-env": {
         readonly told: "log";
-        readonly note: "settings hooks 的命令腿(请求带来的命令跑在宿主上)的 env —— 严格名单(`PATH` / `HOME` / 终端 / locale 等十二名)经引擎的 `hostChildEnv` 组合:名单外一律不交,本服务自有凭据任何情况都不交;请求的有效环境层(`settings.env`)作授予叠在上面;请求给工具 shell 的继承词对它不作用";
+        readonly note: "settings hooks 的命令腿(请求带来的命令跑在宿主上)的 env —— 严格名单(`PATH` / `HOME` / 终端 / locale 等十二名)∪ 部署方 `HOOK_ENV_ALLOW` 点名放回的变量,经引擎的 `hostChildEnv` 组合:其余一律不交,本服务自有凭据(名与值副本)任何情况都不交;请求的有效环境层(`settings.env`)作授予叠在上面;请求给工具 shell 的继承词对它不作用";
         readonly remedy: null;
     };
     readonly "server.project-memory.git-subprocess": {

package/dist/observability/secret-env-scrub.js

@@ -20,7 +20,7 @@ export const SECRET_ENV_SCRUB_SITES = {
     },
     "server.hooks.spawn-env": {
         told: "log",
-        note: "settings hooks 的命令腿(请求带来的命令跑在宿主上)的 env —— 严格名单(`PATH` / `HOME` / 终端 / locale 等十二名)经引擎的 `hostChildEnv` 组合:名单外一律不交,本服务自有凭据任何情况都不交;请求的有效环境层(`settings.env`)作授予叠在上面;请求给工具 shell 的继承词对它不作用",
+        note: "settings hooks 的命令腿(请求带来的命令跑在宿主上)的 env —— 严格名单(`PATH` / `HOME` / 终端 / locale 等十二名)∪ 部署方 `HOOK_ENV_ALLOW` 点名放回的变量,经引擎的 `hostChildEnv` 组合:其余一律不交,本服务自有凭据(名与值副本)任何情况都不交;请求的有效环境层(`settings.env`)作授予叠在上面;请求给工具 shell 的继承词对它不作用",
         remedy: null,
     },
     "server.project-memory.git-subprocess": {

package/dist/orchestration/hardened-vm-runner.d.ts

@@ -98,6 +98,7 @@ export declare function isScriptRealmRejection(promise: unknown): boolean;
  * message channel for a rejection nobody awaited does not exist anyway.
  */
 export declare function describeRejectionReason(reason: unknown): string;
+export declare function installScriptRejectionReport(report: (summary: string) => void): void;
 export declare function installScriptRealmRejectionGuard(): void;
 /**
  * The membrane handed to a surface's `buildGlobals` callback to construct the CONTEXT-LOCAL bindings the

package/dist/orchestration/hardened-vm-runner.js

@@ -55,17 +55,23 @@ export function describeRejectionReason(reason) {
     return `<unknown typeof ${typeof reason}>`;
 }
 let rejectionGuardInstalled = false;
+let scriptRejectionReport;
+export function installScriptRejectionReport(report) {
+    scriptRejectionReport = report;
+}
 export function installScriptRealmRejectionGuard() {
     if (rejectionGuardInstalled)
         return;
     rejectionGuardInstalled = true;
     process.on("unhandledRejection", (reason, promise) => {
         if (isScriptRealmRejection(promise)) {
-            const summary = describeRejectionReason(reason);
-            try {
-                console.warn(`hardened-vm: un-awaited script rejection contained: ${summary}`);
-            }
-            catch {
+            const report = scriptRejectionReport;
+            if (report !== undefined) {
+                try {
+                    report(describeRejectionReason(reason));
+                }
+                catch {
+                }
             }
             return;
         }

package/dist/orchestration/hardened-vm-worker-runner.d.ts

@@ -1,18 +1,4 @@
 import { type WorkflowScriptRunner } from "@sema-agent/core";
 import { type HardenedVmLimits } from "./hardened-vm-runner.js";
-/**
- * Worker-isolated S8 hard runner ([ref] v2). Runs the hardened-vm membrane inside a `worker_thread`, adding
- * RESOURCE isolation on top of the in-process {@link import("./hardened-vm-runner.js").createHardenedVmRunner}'s
- * BOUNDARY isolation:
- *   - HEAP cap (`resourceLimits.maxOldGenerationSizeMb`): a runaway-allocation script OOMs the WORKER (an `error`
- *     event), never the shared main process — closes the in-process resource-exhaustion gap.
- *   - `terminate()` on wall-clock timeout / abort: kills a MICROTASK-starvation loop (`while(true){await null}`)
- *     the in-process wall-clock race cannot pre-empt (it starves its own event loop).
- *   - credential isolation: the worker gets only the script + args; `agent`/`log` IPC to the main thread (which
- *     holds the real Runner/DB/keys); a (validated-impossible) boundary crossing lands in a credential-free isolate.
- *
- * `safeForUntrustedScripts: true` — the membrane it runs is the conformance-validated + robustness-tested one. Use
- * this (over the in-process runner) for genuinely-untrusted multi-tenant scripts where resource isolation matters.
- */
 export declare function createWorkerHardenedVmRunner(limits?: HardenedVmLimits): WorkflowScriptRunner;
 //# sourceMappingURL=hardened-vm-worker-runner.d.ts.map

package/dist/orchestration/hardened-vm-worker-runner.js

@@ -1,10 +1,12 @@
 import { Worker } from "node:worker_threads";
 import { WorkflowScriptError } from "@sema-agent/core";
 import { scopedPhaseGate, workflowTotalTimeoutMsDefault } from "./hardened-vm-runner.js";
+import { createLogger } from "../observability/logger.js";
 const DEFAULTS = { totalTimeoutMs: workflowTotalTimeoutMsDefault(), syncTimeoutMs: 5_000, maxAgents: 1000, concurrency: 12, maxHeapMb: 128 };
 const IS_TS = import.meta.url.endsWith(".ts");
 const WORKER_URL = new URL(IS_TS ? "./hardened-vm-worker.ts" : "./hardened-vm-worker.js", import.meta.url);
 const WORKER_EXEC_ARGV = IS_TS ? ["--import", "tsx/esm"] : undefined;
+const containedLog = createLogger();
 export function createWorkerHardenedVmRunner(limits = {}) {
     const cfg = { ...DEFAULTS, ...limits };
     return {
@@ -60,6 +62,9 @@ export function createWorkerHardenedVmRunner(limits = {}) {
                     else if (msg.type === "log") {
                         primitives.log(String(msg.msg));
                     }
+                    else if (msg.type === "scriptRejectionContained") {
+                        containedLog.warn("unhandled_rejection_script_realm_contained", { reason: String(msg.reason) });
+                    }
                     else if (msg.type === "done") {
                         finish(() => resolve({ result: msg.result, meta: (msg.meta ?? { name: "workflow", description: "" }) }));
                     }

package/dist/orchestration/hardened-vm-worker.js

@@ -1,7 +1,7 @@
 import { parentPort, workerData } from "node:worker_threads";
 import { splitWorkflowMeta } from "@sema-agent/core";
 const ext = import.meta.url.endsWith(".ts") ? "ts" : "js";
-const { runInHardenedVm, orchestrationGlobals } = (await import(`./hardened-vm-runner.${ext}`));
+const { runInHardenedVm, orchestrationGlobals, installScriptRejectionReport } = (await import(`./hardened-vm-runner.${ext}`));
 const port = parentPort;
 if (!port)
     throw new Error("hardened-vm-worker must run inside a worker_thread");
@@ -26,6 +26,7 @@ port.on("message", (msg) => {
         p.rej(e);
     }
 });
+installScriptRejectionReport((summary) => port.postMessage({ type: "scriptRejectionContained", reason: summary }));
 const ipcCall = (type, extra) => new Promise((res, rej) => {
     const id = nextId++;
     pending.set(id, { res, rej });

package/dist/orchestration/workflow-completion-inbox.d.ts

@@ -217,8 +217,8 @@ export declare const INBOX_SUMMARY_WITHHELD = "[payload over budget: summary wit
 /**
  * 一次 workflow 完成 → 入箱条目(`workflow_complete` 家族;启动期投递闭包的**唯一**构造点)。`summary` 在 core 的 notifier seam 上已脱敏 + 限长,这里原样入箱;
  * `completionId`(引擎铸,`WorkflowCompletionPayload` 上在场 iff 引擎给了)逐字落进 `payload` 列 —— 同一次完成的补投帧与 live 帧同一个相关 id,本服务零自铸。
- * `diagnostics`(引擎铸的诊断教学文本,在场 iff 引擎给了)是自由文本:**这里**过出口座(`inbox-diagnostics-text` 行 —— 与 live `task_notification.diagnostics` 同一个脱敏 scope,
- * 加一条界)再落 `payload` 列,drain 逐字带出;店里不放未洗的字节。
+ * `diagnostics`(引擎铸的诊断教学文本,在场 iff 引擎给了)是自由文本:**这里**过出口座(`completion-diagnostics-text` 行 —— 与 live `task_notification.diagnostics` **同一行**:同一份脱敏、同一份界、
+ * 读者是人的档在行上声明)再落 `payload` 列,drain 逐字带出;店里不放未洗的字节。引擎 notifier seam 递来的已是抹过的文本,座再读一遍是恒等(档的不动点)—— 补投帧与 live 帧的一致不靠上游记得抹。
  */
 export declare function buildWorkflowCompleteInboxEntry(route: {
     sessionId: string;
@@ -240,7 +240,7 @@ export declare function buildWorkflowCompleteInboxEntry(route: {
  * deterministic `WorkflowStatus` poll is the floor); at-least-once — the shell dedups by runId (two legs racing
  * the same session may double-emit; same contract).
  *
- * 🔒 Tenancy (defence-in-depth over the authorizer's sessionId→owner gate): only entries whose stamped
+ * 🔒 Tenancy (defence-in-depth over the authorizer's sessionId→owner gate; the face `inbox.drain` in `owner-faces.ts`): only entries whose stamped
  * `owner` matches `callerPrincipal` are EMITTED — a session deleted-then-reclaimed by a different tenant
  * (which rotates the sessionId→owner binding) can't surface the prior owner's completions. `owner: null`
  * (single-user turnkey) has no tenancy boundary → always emitted. A non-matching entry is a DELIBERATE drop —

package/dist/orchestration/workflow-completion-inbox.js

@@ -10,6 +10,7 @@ import { injectionTierOrAbsent } from "../trace/injection-tier.js";
 import { semaProvenanceFields } from "../trace/sema-provenance.js";
 import { resupplyFields, sessionBoxCarrierFields, terminalFrameFacetFields } from "../trace/task-notification-facets.js";
 import { ensureDir, taskNotificationDedupKey } from "@sema-agent/core";
+import { keyAdmits, ownerCellOf, recoveredSubject } from "../owner-faces.js";
 export const MAX_PENDING_PER_SESSION = 100;
 export const COMPACT_EVERY = 512;
 export const PURGE_FENCE_MS = 10 * 60 * 1000;
@@ -316,7 +317,7 @@ export function buildWorkflowCompleteInboxEntry(route, p, enqueuedAt) {
         runId: p.runId,
         status: p.status,
         enqueuedAt,
-        ...encodeWorkflowCompleteExtras(p.summary, { completionId: p.completionId, diagnostics: p.diagnostics ? seatText("inbox-diagnostics-text", p.diagnostics) : undefined }, { sessionId: route.sessionId, key: p.runId }),
+        ...encodeWorkflowCompleteExtras(p.summary, { completionId: p.completionId, diagnostics: p.diagnostics ? seatText("completion-diagnostics-text", p.diagnostics) : undefined }, { sessionId: route.sessionId, key: p.runId }),
     };
 }
 export async function emitPendingWorkflowCompletions(inbox, sessionId, callerPrincipal, emit, diag) {
@@ -338,7 +339,7 @@ export async function emitPendingWorkflowCompletions(inbox, sessionId, callerPri
     }
     for (const e of entries) {
         try {
-            if (e.owner !== null && e.owner !== callerPrincipal) {
+            if (!keyAdmits("inbox.drain", { subject: recoveredSubject(callerPrincipal), operator: false }, ownerCellOf(e.owner))) {
                 await inbox.ack(sessionId, e.runId);
                 dlog("workflow_complete_dropped_owner_mismatch", { route: diag?.route, sessionId, runId: e.runId });
                 continue;

package/dist/org-delivery-gate.d.ts

@@ -15,7 +15,9 @@
  *    + 可选 `urgent` 与显示名;不写 `fromSession / fromMode / hopChain`)。本仓不另铸任何记录形。
  *  · **限流是配额店的两个原子动作,各管一件事**:`admitAttempt` 记发件人的每一次尝试(碰目录之前;界住刷目录的速率),
  *    `take` 在同一把锁下判并记 (from→to) 对偶界与收件人聚合界(投递额度)。SQL 两方言各是一个事务,见
- *    `plugins/org-delivery-quota-store.ts` 头注;File / Memory = 单进程。
+ *    `plugins/org-delivery-quota-store.ts` 头注;File / Memory = 单进程。两个动作的拒都带店算的重试秒数,门原样放进 `rate_limited` 的答案里。
+ *  · **答案是 core 闭集的答案加一个本服务的成员**:core 的 `OrgDeliveryOutcome` 对 `rate_limited` 只有码与句;本服务的 wire 另带 `retryAfterSec`,
+ *    所以门交出的是 {@link ServerOrgDeliveryOutcome} —— 对 core 的类型结构上是子型(多一个成员,别的词不变),`rate_limited` 一只词多一个必填成员。
  *  · **收件人的 scope 就是收件人主体串本身**:本服务的引擎 scope = `spec.principal`(`resolve-spec.ts` 落
  *    `auth.principal`;同一事实的推导见 `peer-directory.ts` 的「scope 轴」段)。门不另造编解码。
  *
@@ -24,15 +26,17 @@
  *     收件人串交给组织目录去查,而目录的每主体状态按属主裁定不淘汰、它的量级只在「查的都是验过的主体」时有界(`org-memory-admission.ts`
  *     的 `PrincipalState` 注);这一界让「一个成员拿任意串去刷目录」的速率与总量随时间线性有界(设计稿收件人查询面第四条:查询限流)。
  *     与收件人无关 ⇒ 它的 `rate_limited` 不泄露收件人存不存在。
- *  1. **成员判**(纯读):不同 org / 查无此人 / 目录不可用 / 收件人串过不了主体形判 / 收件人当不了收件箱的身份键(良构 Unicode ∧ 无控制字符 ∧
- *     UTF-8 字节不超过键列宽 —— 两方言收件箱写面与读面同读的唯一判官 `mailbox-store-sql.ts` 的 `mailboxKeyProblem`)⇒ 同一句 `not_member`,逐字节同 ——
- *     门永远不是一只存在性探针(core 契约原句),也不说「是长度」。收件人那一判必须在配额之前:第 5 步的追加按同一只判官拒,拒在扣了投递额度之后就是「吃了额度没投到」。
+ *  1. **成员判**(纯读):不同 org / 查无此人 / 目录不可用 / 收件人串过不了主体形判 ⇒ 同一句 `not_member`,逐字节同 ——
+ *     门永远不是一只存在性探针(core 契约原句),也不说「是长度」。主体形判(名字 ∧ 良构 Unicode ∧ 无控制字符 ∧ ≤ `PRINCIPAL_MAX_BYTES` UTF-8 字节)**蕴含**收件箱键判官
+ *     (`mailbox-store-sql.ts` 的 `mailboxKeyProblem`:非空 ∧ 良构 ∧ 无 C0 / DEL ∧ ≤ 同一只常量字节;收件人 scope 就是这只键)⇒ 收件人过了这一判,第 5 步的追加不会再按键判拒,
+ *     「吃了额度没投到」只剩追加失败这一种 —— 门里不另问键判官(零双判;蕴含性质钉在 `test/principal-one-byte-ruler.test.ts`)。收件人那一判必须在配额之前。
  *  2. **铸信**(纯函数):放在任何有副作用的步骤之前。发件人的 scope 拼不进信封的发件人位(引擎按百分号编码后 1..190 字节判,抛闭集码
  *     `cross_session.invalid_from_scope`,`CrossSessionCodecError` 由引擎包根导出)⇒ 同一句 `not_member`、一个配额名额都没吃 —— 发件人这一侧的判官只有引擎这一只,
  *     本仓不另抄宽度公式。部署没声明收件箱消费方(`no_consumer`)或别的铸信失败 ⇒ 门抛(core:「the gate maps that to its own failure」),HTTP 面答 500,同样没吃额度。
  *  3. **收件箱上界**(`peekCount` 读):满 ⇒ `inbox_full`,在吃配额之前判,满箱不烧发件人的额度。与引擎同主体车道的
  *     `maxQueuedPeerMessages` 同一形(入口处读一次占用);两封并发信最多越界并发数那么多,上界由配额再界一次。
- *  4. **配额**(原子判并记):任一界满 ⇒ `rate_limited`,与第 0 步同一句(不让发件人从拒句里分辨出「收件人这一小时收了多少」)。
+ *  4. **配额**(原子判并记):任一界满 ⇒ `rate_limited`,与第 0 步同一句(不让发件人从拒句里分辨出「收件人这个窗里收了多少」);
+ *     同一个 `retryAfterSec` 口径 —— 配额店答的、到店钟当前窗结束的整秒数(第 0 步与第 4 步读同一口钟、同一道算式,数里也分辨不出是哪一界)。
  *  5. **追加**:`append(收件人 scope, PRINCIPAL_INBOX_HANDLE, 记录)`。店的预删除态拒码(`mailbox.recipient_tombstoned`)
  *     原样转成 `recipient_tombstoned`(core 对这只词的定义:「the store's own pre-delete code, relayed」);其余错误抛。
  * 被拒的投递在任何地方都不追加任何东西(core 契约原句);投递额度(第 4 步)在之后只有追加失败这一种「吃了额度没投到」—— 方向是收紧;
@@ -43,13 +47,14 @@
  * 跨 scope 写径:受理口(`POST /v1/principal-inbox/messages`)只调门,本仓源码里拼得出 `principal.inbox` 这只箱址的只有本文件
  * (`test/org-delivery-gate-single-path.test.ts` 按源码钉)。
  */
-import { type MailboxStore, type OrgDeliveryGate, type OrgDeliveryRefusalCode, type PrincipalInboxConsumer } from "@sema-agent/core";
+import { type CrossPrincipalBody, type MailboxStore, type OrgAuthenticatedSender, type OrgDeliveryGate, type OrgDeliveryOutcome, type OrgDeliveryRefusalCode, type PrincipalInboxConsumer } from "@sema-agent/core";
 import type { OrgMemoryDirectory } from "./org-memory-admission.js";
 import type { OrgDeliveryQuotaPolicy, OrgDeliveryQuotaStore } from "./plugins/org-delivery-quota-store.js";
 /**
  * 跨主体配额(**唯一**的数字源;店只按它数)。默认显著紧于同主体车道(引擎 `PEER_LANE_DEFAULTS`:每发件人突发 30、
- * 每秒回填 0.5):同一对主体每小时 10 封,一位收件人每小时合计 30 封 —— org 里一个吵闹的主体淹不了别人的箱;
- * 一个发件人每小时 60 次尝试(成没成都算)—— 拿收件人串去问组织目录的速率有界(头注「次序」第 0 步)。
+ * 每秒回填 0.5):同一对主体每个挂钟整点桶 10 封,一位收件人每个挂钟整点桶合计 30 封 —— org 里一个吵闹的主体淹不了别人的箱;
+ * 一个发件人每个挂钟整点桶 60 次尝试(成没成都算)—— 拿收件人串去问组织目录的速率有界(头注「次序」第 0 步)。
+ * 「桶」= 店钟对齐的固定窗(窗宽一小时,`floor(店钟 / windowMs)` 一处公式,`plugins/org-delivery-quota-store.ts` 头注),不是滑动的「过去 60 分钟」。
  */
 export declare const ORG_DELIVERY_QUOTA: OrgDeliveryQuotaPolicy;
 /** 收件箱上界(在箱、未被消费方确认的信封数)。与引擎同主体车道的箱上界缺省(`maxQueuedPeerMessages`)同值。 */
@@ -57,9 +62,30 @@ export declare const PRINCIPAL_INBOX_BOUND = 50;
 /**
  * 四只拒绝词各自的那**一句**(wire 上的 `error` 就是它,`routes/principal-inbox.ts` 原样中继、不手抄)。
  * 键集 = core 闭集:core 加词 ⇒ 这张表编译红。
- * `not_member` 一句同时服务「不同 org / 查无此人 / 目录答不上来 / 收件人串不成形 / 收件人当不了收件箱的键 / 发件人主体拼不进信封的发件人位」—— 改它要保持各臂同字节。
+ * `not_member` 一句同时服务「不同 org / 查无此人 / 目录答不上来 / 收件人串不成形 / 发件人主体拼不进信封的发件人位」—— 改它要保持各臂同字节。
  */
 export declare const ORG_DELIVERY_REFUSAL_MESSAGES: Readonly<Record<OrgDeliveryRefusalCode, string>>;
+/**
+ * 本服务的投递答案 = core 的 {@link OrgDeliveryOutcome} 加上额度拒的重试指引:`rate_limited` 一只词必带 `retryAfterSec`(配额店算的、到店钟当前窗结束的整秒数,
+ * ≥ 1),另三只词的答案与 core 的形逐字相同。对 core 的 `OrgDeliveryGate` 契约结构上是子型,所以这只门照样能交给任何读 core 契约的人。
+ * 数只在配额店算一次;HTTP 面把它投影成体里的 `retryAfterSec` 与同值 `Retry-After` 头(`routes/principal-inbox.ts`,不再算)。
+ */
+export type ServerOrgDeliveryOutcome = Extract<OrgDeliveryOutcome, {
+    ok: true;
+}> | {
+    readonly ok: false;
+    readonly code: Exclude<OrgDeliveryRefusalCode, "org_delivery.rate_limited">;
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly code: "org_delivery.rate_limited";
+    readonly message: string;
+    readonly retryAfterSec: number;
+};
+/** {@link createOrgDeliveryGate} 交出的门:core 契约的子型,答案是 {@link ServerOrgDeliveryOutcome}。装配点、`ServiceDeps.orgDeliveryGate` 与受理口读这一只型。 */
+export interface ServerOrgDeliveryGate extends OrgDeliveryGate {
+    deliverCrossPrincipal(authedFrom: OrgAuthenticatedSender, toPrincipal: string, body: CrossPrincipalBody): Promise<ServerOrgDeliveryOutcome>;
+}
 export interface OrgDeliveryGateDeps {
     /** org 成员目录 —— **必须**与记忆准入 seam / memory-policy / 共享记忆读面同一个实例(头注)。 */
     readonly directory: OrgMemoryDirectory;
@@ -77,7 +103,7 @@ export interface OrgDeliveryGateDeps {
 /**
  * 活对象(闭包持有目录 / 两只店 / 消费方)⇒ `create*`(CLAUDE.md 工厂命名律)。
  */
-export declare function createOrgDeliveryGate(deps: OrgDeliveryGateDeps): OrgDeliveryGate;
+export declare function createOrgDeliveryGate(deps: OrgDeliveryGateDeps): ServerOrgDeliveryGate;
 /**
  * 箱址的读侧映射也归门(单一属主:箱址常量只在本文件出现,`test/org-delivery-gate-single-path.test.ts` ①):
  * 被扣的跨会话信在收信会话的哪条车道上 ⇄ core 队列键的 `box`。消费方 = `src/peer-inbound-face.ts`。

package/dist/org-delivery-gate.js

@@ -1,6 +1,7 @@
 import { CrossSessionCodecError, MAILBOX_TOMBSTONED_RECIPIENT_CODE, PRINCIPAL_INBOX_HANDLE, peerSessionBoxHandle, mintCrossPrincipalRecord, uuidv7, } from "@sema-agent/core";
-import { principalShapeProblem } from "./security.js";
-import { mailboxKeyProblem } from "./stores-sql/mailbox-store-sql.js";
+import { principalShapeProblem } from "./principal-shape.js";
+import { personOf } from "./owner-brands.js";
+import { recoveredSubject } from "./owner-faces.js";
 export const ORG_DELIVERY_QUOTA = Object.freeze({ windowMs: 3_600_000, attemptsPerSender: 60, perPair: 10, perRecipient: 30 });
 export const PRINCIPAL_INBOX_BOUND = 50;
 export const ORG_DELIVERY_REFUSAL_MESSAGES = Object.freeze({
@@ -10,6 +11,7 @@ export const ORG_DELIVERY_REFUSAL_MESSAGES = Object.freeze({
     "org_delivery.recipient_tombstoned": "the recipient is being deleted — nothing was delivered",
 });
 const refuse = (code) => ({ ok: false, code, message: ORG_DELIVERY_REFUSAL_MESSAGES[code] });
+const refuseRateLimited = (retryAfterSec) => ({ ok: false, code: "org_delivery.rate_limited", message: ORG_DELIVERY_REFUSAL_MESSAGES["org_delivery.rate_limited"], retryAfterSec });
 async function shareAnOrg(directory, a, b) {
     const [la, lb] = await Promise.all([directory.lookup(a), directory.lookup(b)]);
     if (la.kind !== "granted" || lb.kind !== "granted")
@@ -17,15 +19,16 @@ async function shareAnOrg(directory, a, b) {
     return Object.keys(la.scopes).some((org) => Object.hasOwn(lb.scopes, org));
 }
 const principalShaped = (s) => principalShapeProblem(s) === undefined;
-const fitsInboxKey = (recipient) => mailboxKeyProblem("scope", recipient) === undefined;
 export function createOrgDeliveryGate(deps) {
     const nowMs = deps.nowMs ?? Date.now;
     const mintReceiptId = deps.mintReceiptId ?? uuidv7;
     return {
         async deliverCrossPrincipal(authedFrom, toPrincipal, body) {
-            if (!(await deps.quota.admitAttempt(authedFrom.scope, ORG_DELIVERY_QUOTA)))
-                return refuse("org_delivery.rate_limited");
-            if (!principalShaped(toPrincipal) || !fitsInboxKey(toPrincipal) || !(await shareAnOrg(deps.directory, authedFrom.scope, toPrincipal))) {
+            const senderPerson = personOf(recoveredSubject(authedFrom.scope));
+            const attempt = await deps.quota.admitAttempt(senderPerson, ORG_DELIVERY_QUOTA);
+            if (!attempt.granted)
+                return refuseRateLimited(attempt.retryAfterSec);
+            if (!principalShaped(toPrincipal) || !(await shareAnOrg(deps.directory, senderPerson, toPrincipal))) {
                 return refuse("org_delivery.not_member");
             }
             const toScope = toPrincipal;
@@ -41,8 +44,9 @@ export function createOrgDeliveryGate(deps) {
             }
             if ((await deps.mailbox.peekCount(toScope, PRINCIPAL_INBOX_HANDLE)) >= PRINCIPAL_INBOX_BOUND)
                 return refuse("org_delivery.inbox_full");
-            if (!(await deps.quota.take(authedFrom.scope, toScope, ORG_DELIVERY_QUOTA)))
-                return refuse("org_delivery.rate_limited");
+            const taken = await deps.quota.take(senderPerson, toScope, ORG_DELIVERY_QUOTA);
+            if (!taken.granted)
+                return refuseRateLimited(taken.retryAfterSec);
             let seq;
             try {
                 seq = await deps.mailbox.append(toScope, PRINCIPAL_INBOX_HANDLE, record);

package/dist/outbound-dispatcher.d.ts

@@ -125,7 +125,7 @@ export declare function buildOutboundProxyPosture(env?: NodeJS.ProcessEnv): Outb
  * (按远端处置 = 交给代理那一半,与修前方向一致)。认哪几形(与 sema-cli 1.0.136 `isLoopbackHost` 同集):
  *  · `localhost`(含 FQDN 尾点 `localhost.`);刻意**不**认 `*.localhost` 子域(能否落到本机取决于系统解析器,不是地址本身的事实);
  *  · IPv4 `127.0.0.0/8` 整段(WHATWG URL 先把 `127.1` / `0x7f.1` 这类写法规范成点分四段);
- *  · IPv6 `::1`、IPv4 映射段 `::ffff:127.x.x.x`(URL 规范成 `::ffff:7fxx:xxxx` 形);
+ *  · IPv6 `::1`、IPv4 映射段 `::ffff:127.x.x.x`(URL 规范成 `::ffff:7fxx:xxxx` 形,经 `canonicalAddress` 折回点分 IPv4 再判);
  *  · 未指定地址 `0.0.0.0` / `::`(及映射形):作为目的地址它在本机就是「本机」,送进代理只会让代理去连它自己。
  */
 export declare function isLoopbackOrigin(origin: string | URL | undefined): boolean;

package/dist/outbound-dispatcher.js

@@ -1,6 +1,7 @@
 import { Agent, Client, Dispatcher, EnvHttpProxyAgent, getGlobalDispatcher, Pool, setGlobalDispatcher } from "undici";
 import { PROXY_TUNNEL_REFUSED } from "@sema-agent/core";
 import { isIP } from "node:net";
+import { canonicalAddress } from "./net-address.js";
 import diagnosticsChannel from "node:diagnostics_channel";
 import { buildDisplaySafeUrl, DISPLAY_SAFE_URL_TOKEN, redactSecrets } from "./trace/redact.js";
 import { recordFailOpen } from "./observability/fail-open.js";
@@ -41,19 +42,12 @@ export function isLoopbackOrigin(origin) {
     host = host.replace(/\.+$/, "");
     if (host === "localhost")
         return true;
-    const family = isIP(host);
-    if (family === 4)
-        return host.startsWith("127.") || host === "0.0.0.0";
-    if (family !== 6)
+    const address = canonicalAddress(host);
+    if (address === undefined)
         return false;
-    if (host === "::1" || host === "::")
-        return true;
-    const mapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
-    if (mapped === null)
-        return false;
-    const hi = Number.parseInt(mapped[1], 16);
-    const lo = Number.parseInt(mapped[2], 16);
-    return hi >> 8 === 127 || (hi === 0 && lo === 0);
+    if (isIP(address) === 4)
+        return address.startsWith("127.") || address === "0.0.0.0";
+    return address === "::1" || address === "::";
 }
 class OutboundDispatcher extends Dispatcher {
     direct;

package/dist/owner-brands.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 🔴 **身份的三根轴与行上的属主**(属主律 + 场景子命名空间的类型事实;叶子:零 import)。
+ *
+ * ## 律(四句)
+ *  1. **轴在汇点上,不在串里。** {@link Person} = 外部验过的那个人(谁付钱 / 谁有权 / 谁被治理:成本、租约、用量窗、运维名册、中心场景裁定、持久规则、组织成员);
+ *     {@link Scenario} = 请求自报的场景(人之内的自选收窄,不是权限主张);{@link Subject} = 分区键(行属主 / 存储键 / 列表过滤 / 检查点 scope / 记忆 scope / 幂等身份)。
+ *     读身份的每只汇点形参带品牌:人面收 `Person`,分区面收 `Subject`(行上读出的是它的持久形 {@link DurableOwnerKey})—— 收错 = 编译红。
+ *  2. **两只铸点、一只解码器。** 外部管线 {@link subjectOf}(没带场景 ⇒ 主体与人**逐字节相同**;带了 ⇒ `_scn:<场景>:<人>`);内部恢复管线 {@link partsOf}
+ *     (行属主 / 检查点 scope / 引擎回传的 scope 恢复成 `{ subject, person, scenario? }`,存量串**一律先过它**)。保留前缀 / 在册 / 宽度三判只在外部管线
+ *     (`security.ts` 的形判与宽度判、`http/principal-gate.ts` 的请求身份判决);恢复的不是外部输入,不判。
+ *  3. **载体只带一格。** 调用方 / 幂等身份 / 列表视域 / 执行上下文只带 `Subject`;人只经 {@link personOf} 从它读 —— 不存在「人与主体不一致」的态。
+ *  4. **存储零改形。** 主体按字节落进既有的属主 / scope 列;没带场景的请求写下的行与今天逐字节同。
+ *
+ * ## 铸点闭集(普查门 ⑤ 逐文件钉)
+ *  · `Person` —— `security.ts` 的 `verifiedPerson`(验请求身份的那一只)、`principal-jwt.ts` 的 `verifyDirectDoorProof`(直连门上这一次决定的证明推出的人)、
+ *    本文件的 {@link partsOf}(恢复管线);
+ *  · `Scenario` —— 本文件的 {@link scenarioNamed}(文法是它的唯一入口)与 {@link partsOf};
+ *  · `Subject` —— 本文件的 {@link subjectOf} 与 {@link partsOf};
+ *  · `DurableOwnerKey` —— `owner-faces.ts` 的 `ownerKeyOf`(属主列读数)、`security.ts` 的 `decodeCheckpointScope`(停驻行 scope 列)与 `http/owner-access.ts` 判行处的
+ *    {@link mintOwnedRow}(门放过的那一行:同一个行对象原样交出,只在型上带品牌)。
+ * 四只品牌两两不可赋、裸 `string` 都不可赋;「调用方 vs 行属主」只经 `owner-faces.ts` 的 `sameParty`(有主行)/ `sameKey`(存储键)两座桥 —— 桥的调用方一侧是 `Subject`。
+ * 本文件是 src 里这四只品牌**唯一**出现断言的地方。
+ */
+declare const personBrand: unique symbol;
+declare const scenarioBrand: unique symbol;
+declare const subjectBrand: unique symbol;
+declare const durableOwnerKeyBrand: unique symbol;
+export type Person = string & {
+    readonly [personBrand]: true;
+};
+export type Scenario = string & {
+    readonly [scenarioBrand]: true;
+};
+export type Subject = string & {
+    readonly [subjectBrand]: true;
+};
+export type DurableOwnerKey = string & {
+    readonly [durableOwnerKeyBrand]: true;
+};
+/** 场景名文法(唯一一份):内建场景表与中心声明的场景、请求的场景头同读。不含冒号 ⇒ 主体里前缀后的第一个冒号唯一切分(编码单射、可解)。 */
+export declare const SCENARIO_NAME_RE: RegExp;
+/** 带场景的主体的保留前缀。身份边界拒以它开头的人(`security.ts` 的保留前缀表登记它),否则一个人可以自称别人的分区。 */
+export declare const SCENARIO_SUBJECT_PREFIX = "_scn:";
+/** {@link Person} 的铸造口(只在铸点闭集里调,见上)。 */
+export declare function mintPerson(verified: string): Person;
+/** {@link DurableOwnerKey} 的铸造口(只在铸点闭集里调,见上)。 */
+export declare function mintDurableOwnerKey(persisted: string): DurableOwnerKey;
+/** {@link Scenario} 的唯一入口:合文法 ⇒ 场景;不合 ⇒ `undefined`(调用方按自己的面答拒;不合文法的名字不可能在册)。 */
+export declare function scenarioNamed(raw: string): Scenario | undefined;
+/** 外部管线的主体铸点:没带场景 ⇒ 与人逐字节相同;带了 ⇒ `_scn:<场景>:<人>`。 */
+export declare function subjectOf(person: Person, scenario?: Scenario): Subject;
+/** 一只主体的三格(恢复管线的产物)。 */
+export interface SubjectParts {
+    readonly subject: Subject;
+    readonly person: Person;
+    readonly scenario: Scenario | undefined;
+}
+/** 一只以保留前缀开头、却拆不出「合文法的场景 + 非空的人」的串 —— 存量里不该有(起服的切换检查拒启它的来源),出现即是数据坏,不猜。 */
+export declare class MalformedSubjectError extends Error {
+    readonly code = "owner.malformed_subject";
+    constructor();
+}
+/**
+ * 🔴 **内部恢复管线的唯一解码器**:行属主 / 检查点 scope / 引擎回传的 scope 恢复成三格。不以保留前缀开头 ⇒ 无场景(主体 = 人,逐字节);
+ * 以它开头 ⇒ 前缀后第一个冒号切成场景与人 —— 场景不合文法或人段为空 ⇒ 抛 {@link MalformedSubjectError}(响亮,不把坏形读成人)。
+ * 不判保留前缀 / 在册 / 宽度:恢复的不是外部输入。
+ */
+export declare function partsOf(key: Subject | DurableOwnerKey): SubjectParts;
+/** 一只主体(或它的持久形)背后的人 —— 人面汇点从分区键读人的唯一读法(= {@link partsOf} 的 `person` 格)。 */
+export declare function personOf(key: Subject | DurableOwnerKey): Person;
+/**
+ * 门放过的那一行的铸造口(只在属主存取器判行处调):**行对象原样交回** —— 运行期是同一个对象、属主是同一串,只在型上把属主那一格带 {@link DurableOwnerKey}。
+ * 不展开、不拷贝:行上可能有惰性读的格(头读的叶子 `leafId` 在会话内容读不出时是一只抛故障的读取器 —— 只判归属的口不读内容),展开一次就把内容读了。
+ */
+export declare function mintOwnedRow<R extends {
+    readonly owner: string | null;
+}>(row: R): R & {
+    readonly owner: DurableOwnerKey | null;
+};
+export {};
+//# sourceMappingURL=owner-brands.d.ts.map

package/dist/owner-brands.js

@@ -0,0 +1,42 @@
+export const SCENARIO_NAME_RE = /^[a-z][a-z0-9-]{1,31}$/;
+export const SCENARIO_SUBJECT_PREFIX = "_scn:";
+export function mintPerson(verified) {
+    return verified;
+}
+export function mintDurableOwnerKey(persisted) {
+    return persisted;
+}
+export function scenarioNamed(raw) {
+    return SCENARIO_NAME_RE.test(raw) ? raw : undefined;
+}
+export function subjectOf(person, scenario) {
+    return (scenario === undefined ? person : `${SCENARIO_SUBJECT_PREFIX}${scenario}:${person}`);
+}
+export class MalformedSubjectError extends Error {
+    code = "owner.malformed_subject";
+    constructor() {
+        super(`a stored owner key starts with the reserved scenario prefix "${SCENARIO_SUBJECT_PREFIX}" but does not split into a scenario name and a person`);
+        this.name = "MalformedSubjectError";
+    }
+}
+export function partsOf(key) {
+    const raw = key;
+    if (!raw.startsWith(SCENARIO_SUBJECT_PREFIX))
+        return { subject: raw, person: raw, scenario: undefined };
+    const rest = raw.slice(SCENARIO_SUBJECT_PREFIX.length);
+    const cut = rest.indexOf(":");
+    if (cut < 0)
+        throw new MalformedSubjectError();
+    const scenario = scenarioNamed(rest.slice(0, cut));
+    const person = rest.slice(cut + 1);
+    if (scenario === undefined || person.length === 0)
+        throw new MalformedSubjectError();
+    return { subject: raw, person: person, scenario };
+}
+export function personOf(key) {
+    return partsOf(key).person;
+}
+export function mintOwnedRow(row) {
+    return row;
+}
+//# sourceMappingURL=owner-brands.js.map