@sema-agent/server 7.147.0 → 7.148.0

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]";
@@ -436,6 +436,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/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

@@ -24,9 +24,10 @@
  *     收件人串交给组织目录去查,而目录的每主体状态按属主裁定不淘汰、它的量级只在「查的都是验过的主体」时有界(`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,同样没吃额度。
@@ -57,7 +58,7 @@ 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>>;
 export interface OrgDeliveryGateDeps {

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({
@@ -17,15 +18,15 @@ 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)))
+            const senderPerson = personOf(recoveredSubject(authedFrom.scope));
+            if (!(await deps.quota.admitAttempt(senderPerson, ORG_DELIVERY_QUOTA)))
                 return refuse("org_delivery.rate_limited");
-            if (!principalShaped(toPrincipal) || !fitsInboxKey(toPrincipal) || !(await shareAnOrg(deps.directory, authedFrom.scope, toPrincipal))) {
+            if (!principalShaped(toPrincipal) || !(await shareAnOrg(deps.directory, senderPerson, toPrincipal))) {
                 return refuse("org_delivery.not_member");
             }
             const toScope = toPrincipal;
@@ -41,7 +42,7 @@ 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)))
+            if (!(await deps.quota.take(senderPerson, toScope, ORG_DELIVERY_QUOTA)))
                 return refuse("org_delivery.rate_limited");
             let seq;
             try {

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