@sema-agent/settings-schema 14.6.0 → 14.7.0

package/dist/safety-merge-spec.js

@@ -66,8 +66,8 @@
  */
 import { z } from "zod";
 import { MAX_HASH_DEPTH, stableStringify } from "./hash.js";
-import { captureStringArray, dataDescriptor } from "./definition-copy.js";
-import { isJsonArray, isPlainJsonObject } from "./plain-json-object.js";
+import { captureStringArray, dataDescriptor, isAccessorDescriptor, isolatedObject } from "./own-key-read.js";
+import { jsonShapeOf } from "./plain-json-object.js";
 /** How values from different layers/principals combine for a category. */
 export const MergeShape = z.enum(["denyFirst", "replace", "runAll", "overrideByName", "concat"]);
 /** The trust-tier VOCABULARY as a RUNTIME VALUE — the ONE source of the ladder's words, in the same form as
@@ -183,10 +183,11 @@ function orderVerdict(diff) {
     return diff > 0 ? "stricter" : diff < 0 ? "looser" : "equal";
 }
 /** A string list as a set (order and duplicates do not count); `undefined` when the value is not an array of strings
- *  — a sparse array, an accessor that throws, a proxy that cannot be read (revoked, a trap that throws) is not one: all through the package's one string-array
- *  reading ({@link captureStringArray}), so the comparator never throws on them and never splits a string. */
+ *  — a sparse array, an accessor or non-enumerable element (the verdict is about the caller's own value: an accessor is not a stored value, it may answer
+ *  differently on the next read — the `none` rule's domain says the same; no getter is called), a proxy that cannot be read (revoked, a trap that throws) is not one:
+ *  all through the package's one string-array reading, strict ({@link captureStringArray}), so the comparator never throws on them and never splits a string. */
 function stringSetOf(v) {
-    const list = captureStringArray(v);
+    const list = captureStringArray(v, "strict");
     return list === undefined ? undefined : new Set(list);
 }
 /** `superset ⇒ stricter` for setUnion, the mirror for setNarrower. */
@@ -213,45 +214,57 @@ const NOT_STRICT_JSON = { ok: false };
 function strictJsonCopy(v, depth = 0) {
     if (depth > MAX_HASH_DEPTH)
         return NOT_STRICT_JSON;
-    if (v === null || typeof v === "string" || typeof v === "boolean")
-        return { ok: true, value: v };
-    if (typeof v === "number")
-        return Number.isFinite(v) ? { ok: true, value: v } : NOT_STRICT_JSON;
-    if (typeof v !== "object")
-        return NOT_STRICT_JSON; // undefined / function / symbol / bigint
-    if (isJsonArray(v)) {
-        const length = v.length;
-        if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0)
-            return NOT_STRICT_JSON;
-        const out = [];
-        for (let i = 0; i < length; i++) {
-            const member = strictJsonStored(Object.getOwnPropertyDescriptor(v, i), depth);
-            if (!member.ok)
+    const shape = jsonShapeOf(v); // the shape is asked ONCE, of the seat (total): no `typeof` split, no second prototype read
+    switch (shape) {
+        case "null":
+            return { ok: true, value: v };
+        case "primitive":
+            if (typeof v === "string" || typeof v === "boolean")
+                return { ok: true, value: v };
+            return typeof v === "number" && Number.isFinite(v) ? { ok: true, value: v } : NOT_STRICT_JSON; // undefined / symbol / bigint / NaN / ±Infinity
+        case "array": {
+            const array = v;
+            const length = array.length;
+            if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0)
                 return NOT_STRICT_JSON;
-            Object.defineProperty(out, i, dataDescriptor(member.value));
+            const out = [];
+            for (let i = 0; i < length; i++) {
+                const member = strictJsonStored(Object.getOwnPropertyDescriptor(array, i), depth);
+                if (!member.ok)
+                    return NOT_STRICT_JSON;
+                Object.defineProperty(out, i, dataDescriptor(member.value));
+            }
+            return { ok: true, value: out };
         }
-        return { ok: true, value: out };
-    }
-    if (!isPlainJsonObject(v))
-        return NOT_STRICT_JSON; // Date / Map / class instance
-    const out = Object.create(null);
-    for (const key of Reflect.ownKeys(v)) {
-        if (typeof key === "symbol")
-            continue; // never serialized
-        const desc = Object.getOwnPropertyDescriptor(v, key);
-        if (desc !== undefined && desc.enumerable !== true)
-            continue; // never serialized (what `Object.keys` leaves out)
-        const member = strictJsonStored(desc, depth);
-        if (!member.ok)
+        case "plain": {
+            const record = v;
+            const out = isolatedObject();
+            for (const key of Reflect.ownKeys(record)) {
+                if (typeof key === "symbol")
+                    continue; // never serialized
+                const desc = Object.getOwnPropertyDescriptor(record, key);
+                if (desc !== undefined && desc.enumerable !== true)
+                    continue; // never serialized (what `Object.keys` leaves out)
+                const member = strictJsonStored(desc, depth);
+                if (!member.ok)
+                    return NOT_STRICT_JSON;
+                Object.defineProperty(out, key, dataDescriptor(member.value));
+            }
+            return { ok: true, value: out };
+        }
+        case "non_plain_object": // function / Date / Map / class instance
+        case "uninspectable": // a proxy that cannot be inspected: outside the domain
             return NOT_STRICT_JSON;
-        Object.defineProperty(out, key, dataDescriptor(member.value));
+        default: {
+            const unhandled = shape;
+            throw new Error(`strictJsonCopy: unhandled shape ${String(unhandled)}`);
+        }
     }
-    return { ok: true, value: out };
 }
 /** One member, judged by the descriptor read ONCE: a stored value (a hole has no descriptor; an accessor has no `value`) that is itself strict JSON. */
 function strictJsonStored(desc, depth) {
-    if (desc === undefined || !Object.hasOwn(desc, "value"))
-        return NOT_STRICT_JSON; // 描述符本身也只读自有键:`Object.prototype.value` 被污染时访问器描述符不会「有 value」
+    if (desc === undefined || isAccessorDescriptor(desc))
+        return NOT_STRICT_JSON; // 访问器不是存着的值(描述符的字段只认自有的,见内核)
     return strictJsonCopy(desc.value, depth + 1);
 }
 /** `none`: compares the DESCRIPTOR VIEW, read once ({@link strictJsonCopy}), and serializes only the copies — member values never go through `[[Get]]`. The ONE guard around the

package/dist/sandbox-git.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 沙箱 git 平面的 **origin 形** 与 **有效配置块 `sandboxGit`**(14.7.0)。纯、浏览器安全。
+ *
+ * ## 律(一条)
+ * **一个 origin 就是它自己的 WHATWG origin**:串等于 `new URL(串).origin`,且 scheme ∈ {http, https}。规范形 ——
+ * 小写 host、去缺省端口(https 的 443、http 的 80)、无尾斜杠、无 userinfo / 路径 / 查询 / 片段 —— 不是一张手写规则表,而是这一个等式的推论:
+ * 凡 WHATWG 会改写的串(大写、缺省端口、IPv4 简写、百分号编码的 host、串内制表符、前后空白、反斜杠……)都不等于自己的 origin,所以都不是规范形。
+ * 判官只有 {@link isSandboxGitOrigin} 一只;请求体的 `origins`、应答行的 `origin`、有效配置块的 `origin` 全读它(经 {@link SandboxGitOrigin})。
+ * 「这个串是不是 http(s) URL」归包内唯一的 URL 形判官 `httpUrlFlaws`(`./url-shape`),本模块只加「等于自己的 origin」这一格。
+ * origin 不表达子路径部署(`https://host/gitea` 不是 origin)—— 规范化器不存在:把带路径的串静默削成 origin 会把凭据送到运维没写的地方。
+ *
+ * ## 有效配置块 `sandboxGit`
+ * `/effective` 载荷上的**非域顶层键**(web-admin 按部署登记册投影,不是存储域):可选、无默认 —— 缺席 = 这个部署没有投影这一块。
+ * `readEffectiveWire` 对它走 open-world 逐字承运(从不校验、从不丢,`EffectiveWire.sandboxGit` 是 `unknown`);**判它的座位只有 {@link SandboxGitConfig}**,由消费方在用之前判。
+ *
+ *  · `origins[i].origin` —— 本部署代理哪些 origin(规范形,见上);≤ {@link SANDBOX_GIT_MAX_ORIGINS} 项、两两不同。
+ *  · `origins[i].connectUrl` —— 控制台「连接 Gitea(git)」页的绝对 https URL(非秘密:{@link SandboxGitConnectUrl})。
+ *
+ * 🔴 **块里 http origin 可读**:它为什么送不出凭据(传输不加密)是逐 origin 应答里的一个词(`insecure_transport`,`./api/credentials` 的判定序表第 1 行)
+ * 与能力读数里的一个词,不是块的校验拒。块若因一个 http origin 整块不可读,同块里的 https origin 一并失效,「逐 origin 说拒因」就无从谈起;
+ * http origin 只配路由、永不取值,是消费方的事。
+ *
+ * 解析剥未知键(与 `SessionMirrorPolicy` 同律:加字段恒为加性)。
+ */
+import { z } from "zod";
+/** 一次最多代理的 origin 数(请求体、应答、有效配置块同一个上界)。 */
+export declare const SANDBOX_GIT_MAX_ORIGINS = 16;
+/**
+ * 判:`raw` 是不是规范形的 http(s) origin。合格 ⇔ 它是层级式 http(s) URL 且**逐字等于**自己的 WHATWG origin。
+ * 纯函数、不抛;非串由 {@link SandboxGitOrigin} 的 zod 形先拒。
+ */
+export declare function isSandboxGitOrigin(raw: string): boolean;
+/** 一个规范形的 origin(`scheme://host[:port]`,scheme ∈ {http, https})。判官 {@link isSandboxGitOrigin};拒句是定句,不回显值。 */
+export declare const SandboxGitOrigin: z.ZodString;
+export type SandboxGitOrigin = z.infer<typeof SandboxGitOrigin>;
+/**
+ * 一张 origin 表:每项是规范形、两两不同、至多 {@link SANDBOX_GIT_MAX_ORIGINS} 项。**空表合法**(有效配置块可以没有 origin);要求至少一项的座位(申领请求)自己 `.min(1)`。
+ * 重复的那一项被点名(坐标 = 第二次出现的下标)。
+ */
+export declare const SandboxGitOriginList: z.ZodArray<z.ZodString>;
+export type SandboxGitOriginList = z.infer<typeof SandboxGitOriginList>;
+/**
+ * 控制台「连接 Gitea(git)」页的绝对 URL:**https**,且是 {@link NON_SECRET_URL_NO_MIGRATION} 那一类(层级式 URL、无 userinfo、无片段、路径与查询里没有秘密形的值)。
+ * 它是 wire 输入,不是存量文档里的值,所以走「无迁移指路」那一只。
+ */
+export declare const SandboxGitConnectUrl: z.ZodString;
+export type SandboxGitConnectUrl = z.infer<typeof SandboxGitConnectUrl>;
+/** 有效配置块里的一个 origin 条目。 */
+export declare const SandboxGitOriginEntry: z.ZodObject<{
+    origin: z.ZodString;
+    connectUrl: z.ZodString;
+}, z.core.$strip>;
+export type SandboxGitOriginEntry = z.infer<typeof SandboxGitOriginEntry>;
+/**
+ * 有效配置块 `sandboxGit`(`/effective` 载荷的非域顶层键,可选、无默认)。判它的**唯一座位**:消费方在用之前对 `wire.sandboxGit` 跑 `safeParse`。
+ * `origins` ≤ {@link SANDBOX_GIT_MAX_ORIGINS} 项,按 `origin` 两两不同(重复的那一项的 `origin` 字段被点名);空表合法。
+ */
+export declare const SandboxGitConfig: z.ZodObject<{
+    origins: z.ZodArray<z.ZodObject<{
+        origin: z.ZodString;
+        connectUrl: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SandboxGitConfig = z.infer<typeof SandboxGitConfig>;

package/dist/sandbox-git.js

@@ -0,0 +1,89 @@
+/**
+ * 沙箱 git 平面的 **origin 形** 与 **有效配置块 `sandboxGit`**(14.7.0)。纯、浏览器安全。
+ *
+ * ## 律(一条)
+ * **一个 origin 就是它自己的 WHATWG origin**:串等于 `new URL(串).origin`,且 scheme ∈ {http, https}。规范形 ——
+ * 小写 host、去缺省端口(https 的 443、http 的 80)、无尾斜杠、无 userinfo / 路径 / 查询 / 片段 —— 不是一张手写规则表,而是这一个等式的推论:
+ * 凡 WHATWG 会改写的串(大写、缺省端口、IPv4 简写、百分号编码的 host、串内制表符、前后空白、反斜杠……)都不等于自己的 origin,所以都不是规范形。
+ * 判官只有 {@link isSandboxGitOrigin} 一只;请求体的 `origins`、应答行的 `origin`、有效配置块的 `origin` 全读它(经 {@link SandboxGitOrigin})。
+ * 「这个串是不是 http(s) URL」归包内唯一的 URL 形判官 `httpUrlFlaws`(`./url-shape`),本模块只加「等于自己的 origin」这一格。
+ * origin 不表达子路径部署(`https://host/gitea` 不是 origin)—— 规范化器不存在:把带路径的串静默削成 origin 会把凭据送到运维没写的地方。
+ *
+ * ## 有效配置块 `sandboxGit`
+ * `/effective` 载荷上的**非域顶层键**(web-admin 按部署登记册投影,不是存储域):可选、无默认 —— 缺席 = 这个部署没有投影这一块。
+ * `readEffectiveWire` 对它走 open-world 逐字承运(从不校验、从不丢,`EffectiveWire.sandboxGit` 是 `unknown`);**判它的座位只有 {@link SandboxGitConfig}**,由消费方在用之前判。
+ *
+ *  · `origins[i].origin` —— 本部署代理哪些 origin(规范形,见上);≤ {@link SANDBOX_GIT_MAX_ORIGINS} 项、两两不同。
+ *  · `origins[i].connectUrl` —— 控制台「连接 Gitea(git)」页的绝对 https URL(非秘密:{@link SandboxGitConnectUrl})。
+ *
+ * 🔴 **块里 http origin 可读**:它为什么送不出凭据(传输不加密)是逐 origin 应答里的一个词(`insecure_transport`,`./api/credentials` 的判定序表第 1 行)
+ * 与能力读数里的一个词,不是块的校验拒。块若因一个 http origin 整块不可读,同块里的 https origin 一并失效,「逐 origin 说拒因」就无从谈起;
+ * http origin 只配路由、永不取值,是消费方的事。
+ *
+ * 解析剥未知键(与 `SessionMirrorPolicy` 同律:加字段恒为加性)。
+ */
+import { z } from "zod";
+import { buildQuotedIssue } from "./quoted-issue.js";
+import { NON_SECRET_URL_NO_MIGRATION } from "./types.js";
+import { httpUrlFlaws } from "./url-shape.js";
+/** 一次最多代理的 origin 数(请求体、应答、有效配置块同一个上界)。 */
+export const SANDBOX_GIT_MAX_ORIGINS = 16;
+/**
+ * 判:`raw` 是不是规范形的 http(s) origin。合格 ⇔ 它是层级式 http(s) URL 且**逐字等于**自己的 WHATWG origin。
+ * 纯函数、不抛;非串由 {@link SandboxGitOrigin} 的 zod 形先拒。
+ */
+export function isSandboxGitOrigin(raw) {
+    if (httpUrlFlaws(raw, []).length > 0)
+        return false;
+    return new URL(raw).origin === raw;
+}
+/** 一个规范形的 origin(`scheme://host[:port]`,scheme ∈ {http, https})。判官 {@link isSandboxGitOrigin};拒句是定句,不回显值。 */
+export const SandboxGitOrigin = z
+    .string()
+    .refine(isSandboxGitOrigin, buildQuotedIssue `must be a canonical http(s) origin — scheme://host[:port] equal to its own WHATWG origin: lowercase host, no default port, no userinfo, path, query, fragment or trailing slash`);
+/** 给定下标的 origin 在它之前已经出现过 ⇒ 下标。重复判在**规范形**之上(两个都是规范形的串,相等即同一个 origin)。 */
+function repeatedAt(origins) {
+    const seen = new Set();
+    const repeats = [];
+    origins.forEach((o, i) => {
+        if (seen.has(o))
+            repeats.push(i);
+        seen.add(o);
+    });
+    return repeats;
+}
+/**
+ * 一张 origin 表:每项是规范形、两两不同、至多 {@link SANDBOX_GIT_MAX_ORIGINS} 项。**空表合法**(有效配置块可以没有 origin);要求至少一项的座位(申领请求)自己 `.min(1)`。
+ * 重复的那一项被点名(坐标 = 第二次出现的下标)。
+ */
+export const SandboxGitOriginList = z
+    .array(SandboxGitOrigin)
+    .max(SANDBOX_GIT_MAX_ORIGINS)
+    .superRefine((origins, ctx) => {
+    for (const i of repeatedAt(origins))
+        ctx.addIssue({ code: "custom", ...buildQuotedIssue `duplicate origin`, path: [i] });
+});
+/**
+ * 控制台「连接 Gitea(git)」页的绝对 URL:**https**,且是 {@link NON_SECRET_URL_NO_MIGRATION} 那一类(层级式 URL、无 userinfo、无片段、路径与查询里没有秘密形的值)。
+ * 它是 wire 输入,不是存量文档里的值,所以走「无迁移指路」那一只。
+ */
+export const SandboxGitConnectUrl = NON_SECRET_URL_NO_MIGRATION.refine((u) => URL.canParse(u) && new URL(u).protocol === "https:", buildQuotedIssue `must be an https URL — the connect page is opened by a person and carries their session`);
+/** 有效配置块里的一个 origin 条目。 */
+export const SandboxGitOriginEntry = z.object({
+    /** 本部署代理的 origin(规范形)。http 在这里可读(见模块头注)。 */
+    origin: SandboxGitOrigin,
+    /** 该 origin 的「连接」页,绝对 https URL。 */
+    connectUrl: SandboxGitConnectUrl,
+});
+/**
+ * 有效配置块 `sandboxGit`(`/effective` 载荷的非域顶层键,可选、无默认)。判它的**唯一座位**:消费方在用之前对 `wire.sandboxGit` 跑 `safeParse`。
+ * `origins` ≤ {@link SANDBOX_GIT_MAX_ORIGINS} 项,按 `origin` 两两不同(重复的那一项的 `origin` 字段被点名);空表合法。
+ */
+export const SandboxGitConfig = z
+    .object({
+    origins: z.array(SandboxGitOriginEntry).max(SANDBOX_GIT_MAX_ORIGINS),
+})
+    .superRefine((block, ctx) => {
+    for (const i of repeatedAt(block.origins.map((e) => e.origin)))
+        ctx.addIssue({ code: "custom", ...buildQuotedIssue `duplicate origin`, path: ["origins", i, "origin"] });
+});

package/dist/scheduler-store.js

@@ -1,22 +1,30 @@
-import { isPlainJsonObject } from './plain-json-object.js';
+import { ownDeclaredValueOf } from './own-key-read.js';
+import { isJsonArray, isPlainJsonObject } from './plain-json-object.js';
 import { isSessionLifetime } from './scheduler-lifetime.js';
 import { migrateSchedulerRecords } from './scheduler-store-migration.js';
 /** Structural validation of one record (required fields + a well-formed `when`). Unknown fields are allowed. */
 export function isSchedulerRecord(v) {
     if (!isPlainJsonObject(v))
         return false;
-    const r = v;
-    if (typeof r.id !== 'string' || typeof r.scope !== 'string' || typeof r.prompt !== 'string' || typeof r.createdMs !== 'number')
+    // a type guard, so every field is read STRICTLY from the record's own keys (own, enumerable, data — the kernel's `ownDeclaredValueOf`): an inherited field is absent
+    // (a polluted `Object.prototype.prompt` is not a prompt the record carries); an accessor / hidden field, or one that cannot be read ⇒ not a record — no getter is called,
+    // so what the caller reads from the record next is what was judged
+    const field = (o, key) => {
+        const read = ownDeclaredValueOf(o, key);
+        return read.ok ? read.value : undefined;
+    };
+    if (typeof field(v, 'id') !== 'string' || typeof field(v, 'scope') !== 'string' || typeof field(v, 'prompt') !== 'string' || typeof field(v, 'createdMs') !== 'number')
         return false;
-    const w = r.when;
+    const w = field(v, 'when');
     if (!isPlainJsonObject(w))
         return false;
-    if (w.kind === 'cron')
-        return typeof w.expr === 'string';
-    if (w.kind === 'at')
-        return typeof w.atMs === 'number';
-    if (w.kind === 'delay')
-        return typeof w.delaySec === 'number';
+    const kind = field(w, 'kind');
+    if (kind === 'cron')
+        return typeof field(w, 'expr') === 'string';
+    if (kind === 'at')
+        return typeof field(w, 'atMs') === 'number';
+    if (kind === 'delay')
+        return typeof field(w, 'delaySec') === 'number';
     return false;
 }
 /** 一条会话链上的记录过期多久算「永驻孤儿」:`lifetime: "session"` ∧ `sessionId` 在场 ∧ `nextRunMs` 已过去这么久 ⇒ 读口丢弃并告警(7 天)。 */
@@ -38,7 +46,7 @@ export function parseSchedulerStore(text, opts) {
     catch {
         return { records: [], warnings: [{ kind: 'unreadable-file', why: 'not-json' }] };
     }
-    if (!Array.isArray(parsed))
+    if (!isJsonArray(parsed))
         return { records: [], warnings: [{ kind: 'unreadable-file', why: 'not-an-array' }] };
     const warnings = [];
     const kept = [];

package/dist/settings-units.js

@@ -42,6 +42,7 @@
  * the engine's env catalog, whose one implementation is the server's.
  */
 import { classifyHooksConfig } from "./hooks-config.js";
+import { captureJson, captureStringArray, ownEntriesOf } from "./own-key-read.js";
 import { isPlainJsonObject } from "./plain-json-object.js";
 import { SAFETY_MERGE_SPEC, resolveMemberTighten, tightenVerdict } from "./safety-merge-spec.js";
 /** The settings-document units (see the file header). `path` is the unit's place in a settings document. */
@@ -98,20 +99,17 @@ const UNREADABLE = { ok: false, reason: "unreadable" };
 const LAUNCH_ONLY = { ok: false, reason: "launch_only" };
 /** `stringList`: an array whose every element is a non-empty string (a hole reads as `undefined`, so a sparse array is not one). */
 function isNonEmptyStringList(v) {
-    if (!Array.isArray(v))
-        return false;
-    for (let i = 0; i < v.length; i++) {
-        const x = v[i];
-        if (typeof x !== "string" || x.length === 0)
-            return false;
-    }
-    return true;
+    const list = captureStringArray(v, "strict"); // the package's one string-array reading, strict: the value is handed back as is, so an accessor / hidden index ⇒ not a list (no getter is called)
+    return list !== undefined && list.every((x) => x.length > 0);
 }
-/** `envMap`: a plain object (prototype `Object.prototype` or `null`), non-empty keys, string values. */
+/** `envMap`: a plain object (prototype `Object.prototype` or `null`), non-empty keys, string values. The value is handed back AS IS, so its members are read strictly —
+ *  the package's one whole-container read, strict (`ownEntriesOf`: one `ownKeys`, each own string key's descriptor asked once — symbol keys never; never `[[Get]]`, never a
+ *  proxy's `get` trap): an accessor member or a non-enumerable member ⇒ not an env map (no getter is called — what the caller reads next is what was judged); unreadable ⇒ not one. */
 function isEnvMap(v) {
     if (!isPlainJsonObject(v))
         return false;
-    return Object.keys(v).every((k) => k.length > 0 && typeof v[k] === "string");
+    const members = ownEntriesOf(v);
+    return members.ok && members.value.every(([k, x]) => k.length > 0 && typeof x === "string");
 }
 /** What a declared member's value class adds on top of its comparator's domain — read through the comparator
  *  {@link resolveMemberTighten} derived from the row, so the seat is interpreted in one place: `list` ⇒ setUnion / setNarrower,
@@ -144,8 +142,12 @@ function shapedReading(unit, row, rule, raw) {
         case "killSwitch":
             // CC spells ON "disable"; the boolean itself is the member comparator's domain
             return { ok: true, value: raw === "disable" ? true : raw };
-        case "hooks":
-            return classifyHooksConfig({ hooks: raw }).outcome === "loaded" ? { ok: true, value: raw } : UNREADABLE;
+        case "hooks": {
+            // the value is handed back AS IS, so it is read strictly (as every unit is): the whole tree is snapshotted by the kernel's strict whole-container read first —
+            // an accessor anywhere or a non-enumerable member ⇒ not readable (no getter is called) — and the classifier judges the snapshot, not the caller's object
+            const snapshot = captureJson(raw);
+            return snapshot.ok && classifyHooksConfig({ hooks: snapshot.value }).outcome === "loaded" ? { ok: true, value: raw } : UNREADABLE;
+        }
         case "envMap":
             return isEnvMap(raw) ? { ok: true, value: raw } : UNREADABLE;
         case "nonEmptyString":

package/dist/types.d.ts

@@ -1830,11 +1830,11 @@ export interface SkillsManifest {
  *  legal hash scheme. */
 export declare const SkillsManifestSchema: z.ZodObject<{
     skills: z.ZodPrefault<z.ZodArray<z.ZodObject<{
+        description: z.ZodDefault<z.ZodString>;
         name: z.ZodString;
         enabled: z.ZodDefault<z.ZodBoolean>;
         notes: z.ZodOptional<z.ZodString>;
         rosters: z.ZodPrefault<z.ZodArray<z.ZodString>>;
-        description: z.ZodDefault<z.ZodString>;
         scenarios: z.ZodPrefault<z.ZodArray<z.ZodString>>;
         allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -3219,10 +3219,14 @@ export type EffectiveKey = z.infer<typeof EffectiveKey>;
  *  `prompts` is the second wire divergence: on the wire it is {@link EffectivePromptsWire} (`{schemaVersion: 2, artifact}` — the one
  *  artifact {@link promptArtifactFor} selected for the pulling worker, stamped with its publish provenance), carried verbatim by the
  *  read leg and judged by the consumer (that shape, then the engine's verify) — optional (absent = nothing published, or the publish
- *  gate is closed), never the storage shape. */
+ *  gate is closed), never the storage shape.
+ *  `sandboxGit` (14.7.0) is the third wire-only key and the third carried verbatim: the sandbox git plane's origin block — web-admin projects it from the
+ *  deployment's registry, it is NOT a stored domain, so `buildEffective` never produces it and `readEffectiveWire` neither validates nor drops it. Optional with
+ *  no default (absent = the deployment projects no such block); the ONE seat that judges it is `SandboxGitConfig` (`./sandbox-git`), run by the consumer before use. */
 export type EffectiveWire = Omit<EffectiveConfig, "skills" | "prompts"> & {
     skills: SkillsManifest;
     prompts?: unknown;
+    sandboxGit?: unknown;
 };
 /** Reserved audit "domain" for RBAC/user-management events (not a config domain → no snapshot, not
  *  rollback-able). Lets user changes share the one audit stream the Audit page already renders. */

package/dist/types.js

@@ -22,6 +22,7 @@ import { MAX_EXTRA_BODY_DEPTH } from "./hash.js"; // reconcile the extraBody dep
 import { DispatchPolicy, FLEET_GENERATION_ENV, FLEET_SCOPE_ENV } from "./fleet.js"; // WorkerSpec.fleet.dispatch (scheduling framework D3)
 import { isLoopbackAuthHost } from "./loopback.js";
 import { isJsonArray, isPlainJsonObject } from "./plain-json-object.js"; // THE "is this a JSON object" predicate + the total array test
+import { appendOwn, guardedSafeParse, isAccessorDescriptor } from "./own-key-read.js"; // the one spelling of "is this descriptor an accessor" (its own fields only) + the one guarded zod verdict
 import { httpUrlFlaws, httpUrlRule } from "./url-shape.js"; // 11.0.0: THE URL shape judge // 11.0.0: the one narrow「本机」predicate (auth relaxation)
 import { secretScanForms } from "./secret-scan.js"; // package-private normalization — the one set of forms both scanners read (not in the barrel)
 import { WEB_ADMIN_ENV } from "./web-admin-env.js"; // the three connection keys the config renderer writes are reserved worker env
@@ -255,9 +256,9 @@ export function extraBodyUnsafe(v) {
                 for (const [k, desc] of Object.entries(Object.getOwnPropertyDescriptors(cur))) {
                     if (k === "length")
                         continue; // the array's own `length` data prop — not an element
-                    if (!Object.hasOwn(desc, "value"))
+                    if (isAccessorDescriptor(desc))
                         return true; // accessor element — do NOT invoke
-                    stack.push([desc.value, depth + 1]);
+                    appendOwn(stack, [desc.value, depth + 1]); // 定义语义压栈:`push` 会被继承的数字键 setter 吞掉,遍历一层都不下、秘密静默漏判
                 }
                 continue;
             }
@@ -265,11 +266,11 @@ export function extraBodyUnsafe(v) {
                 return true; // Map/Set/Date/class/toJSON-bearing → not plain
             // descriptor walk: never read a value via [] (would invoke a getter); reject accessors outright.
             for (const [k, desc] of Object.entries(Object.getOwnPropertyDescriptors(cur))) {
-                if (!Object.hasOwn(desc, "value"))
+                if (isAccessorDescriptor(desc))
                     return true; // accessor (get/set) — do NOT invoke
                 if (containsSecretToken(k))
                     return true; // secret-shaped KEY (tokenized). R8
-                stack.push([desc.value, depth + 1]);
+                appendOwn(stack, [desc.value, depth + 1]); // 定义语义压栈:`push` 会被继承的数字键 setter 吞掉,遍历一层都不下、秘密静默漏判
             }
         }
         return false;
@@ -605,7 +606,7 @@ const RoleMap = z.partialRecord(ModelRole, RoleTarget, {
     // 枚举键的 record 在运行期以 `unrecognized_keys`(带 `keys`)报未知键,zod 的型面只列了 invalid_type / invalid_key —— 按运行期形读(钉:role-words-12.0.0)。
     error: (iss) => {
         const raw = iss;
-        return raw.code === "unrecognized_keys" && Array.isArray(raw.keys) ? retiredRoleWordsRefusal(raw.keys) : undefined;
+        return raw.code === "unrecognized_keys" && isJsonArray(raw.keys) ? retiredRoleWordsRefusal(raw.keys) : undefined;
     },
 });
 /** {@link AtMention} 的模式闭集:`all` = 每个启用的模型都可 `@`;`none` = 一个都不许;`only` = 只许 `models` 里点名的那几个。 */
@@ -1607,7 +1608,11 @@ export function applyProjectPatch(doc, projectId, patch) {
     const current = Object.prototype.hasOwnProperty.call(doc.projects, projectId) ? doc.projects[projectId] : undefined;
     if (current === undefined)
         throw new Error(`applyProjectPatch: project "${projectId}" is not registered in this document`);
-    const parsed = ProjectRegistrationPatch.safeParse(patch);
+    // the patch is the caller's value: the parse and the first read of its error sit in one guard (another realm's odd value, a getter / trap that throws) ⇒ a rejection, never a throw
+    const patchRead = guardedSafeParse(() => ProjectRegistrationPatch.safeParse(patch));
+    if (!patchRead.ok)
+        return { success: false, error: new z.ZodError([{ code: "custom", ...buildQuotedIssue `the patch could not be read during validation`, path: ["projects", projectId], input: undefined }]) };
+    const parsed = patchRead.value;
     if (!parsed.success) {
         const issues = parsed.error.issues.map((i) => ({ ...i, path: ["projects", projectId, ...i.path] }));
         return { success: false, error: new z.ZodError(issues) };

package/dist/url-shape.d.ts

@@ -41,6 +41,22 @@ export declare function isHierarchicalUrl(raw: string): boolean;
  * 层级式非 http(s) ⇒ `not-http-url` 之后照判部件。返回类型按 `forbid` 收窄:座位没禁的部件不会出现在答案里。
  */
 export declare function httpUrlFlaws<P extends HttpUrlPart>(raw: string, forbid: readonly P[]): ReadonlyArray<"not-http-url" | P>;
+/**
+ * **「后面要拼路径的基址」座位禁用的部件**(闭集、冻结、判序)—— 14.7.0 起的唯一一张。一个值若是别人要往它后面拼路径的基址
+ * (中心基址三席、本实例对中心公告的地址、会话网页链接的基址……):`userinfo` 把凭据放进一个会被记日志、转述、拼路径的值;`query` / `fragment`
+ * 挂在基址上,一拼路径就落到错的位置(`http://x?a=1` + `/v1/…` = `http://x?a=1/v1/…`)。**路径前缀不禁** —— 要拼的路径接在前缀后面。
+ * 这是**策略集,独立于判官词表**({@link HTTP_URL_PARTS} 说的是 URL 有哪些成分,本集说的是这种座位禁哪些):今天两者碰巧同三词,但本集不由词表派生 ——
+ * 词表加词时此处要显式裁(加进来还是明确不加),不会静默多禁一件。冻结:判官读的就是消费方手里的这一只。
+ * 按座位的本质命名,不按某个消费键名:谁的座位是「后面要拼路径的基址」,谁读它,不各自抄词。
+ */
+export declare const PATH_BASE_URL_FORBIDDEN_PARTS: readonly ["userinfo", "query", "fragment"];
+/**
+ * 「后面要拼路径的基址」座位的判:`[]` = 合格,否则按判序交回规则词 —— 就是 {@link httpUrlFlaws} 配 {@link PATH_BASE_URL_FORBIDDEN_PARTS},
+ * 不另写判法;规则词的句子取 {@link httpUrlRule}。答案只有词,不含值的任何片段。判**占位展开之后**的值:`http://$(POD_IP):8090` 过
+ * (占位在主机位),`http://[$(POD_IP)]:8090` 拒(方括号里必须是 IPv6 字面量),展开后的 `http://[fd00::1]:8090` 过。
+ * 缺席 / 空串由调用方在判之前处理(对 `""` 本函数答 `not-http-url`)。
+ */
+export declare function pathBaseUrlFlaws(url: string): ReadonlyArray<HttpUrlFlaw>;
 /** 以 `http://` / `https://` 起头(大小写不敏感)—— 一道**语法前缀**守卫,不是形判官:不解析、不看 host / 部件,所以 `https://` 这样的裸 scheme 它也收(见头注「第二个答案」)。
  *  唯一读者是请求面 MCP 传输读器(`readRequestMcpTransport`);S-2106 收口时它退成那个读器座位的「照字面写全」规则,与形判官合取。 */
 export declare function startsWithHttpScheme(raw: string): boolean;

package/dist/url-shape.js

@@ -57,6 +57,24 @@ export function httpUrlFlaws(raw, forbid) {
     const shape = u.protocol === "http:" || u.protocol === "https:" ? [] : ["not-http-url"];
     return [...shape, ...HTTP_URL_PARTS.filter((p) => forbid.includes(p) && present[p])];
 }
+/**
+ * **「后面要拼路径的基址」座位禁用的部件**(闭集、冻结、判序)—— 14.7.0 起的唯一一张。一个值若是别人要往它后面拼路径的基址
+ * (中心基址三席、本实例对中心公告的地址、会话网页链接的基址……):`userinfo` 把凭据放进一个会被记日志、转述、拼路径的值;`query` / `fragment`
+ * 挂在基址上,一拼路径就落到错的位置(`http://x?a=1` + `/v1/…` = `http://x?a=1/v1/…`)。**路径前缀不禁** —— 要拼的路径接在前缀后面。
+ * 这是**策略集,独立于判官词表**({@link HTTP_URL_PARTS} 说的是 URL 有哪些成分,本集说的是这种座位禁哪些):今天两者碰巧同三词,但本集不由词表派生 ——
+ * 词表加词时此处要显式裁(加进来还是明确不加),不会静默多禁一件。冻结:判官读的就是消费方手里的这一只。
+ * 按座位的本质命名,不按某个消费键名:谁的座位是「后面要拼路径的基址」,谁读它,不各自抄词。
+ */
+export const PATH_BASE_URL_FORBIDDEN_PARTS = Object.freeze(["userinfo", "query", "fragment"]);
+/**
+ * 「后面要拼路径的基址」座位的判:`[]` = 合格,否则按判序交回规则词 —— 就是 {@link httpUrlFlaws} 配 {@link PATH_BASE_URL_FORBIDDEN_PARTS},
+ * 不另写判法;规则词的句子取 {@link httpUrlRule}。答案只有词,不含值的任何片段。判**占位展开之后**的值:`http://$(POD_IP):8090` 过
+ * (占位在主机位),`http://[$(POD_IP)]:8090` 拒(方括号里必须是 IPv6 字面量),展开后的 `http://[fd00::1]:8090` 过。
+ * 缺席 / 空串由调用方在判之前处理(对 `""` 本函数答 `not-http-url`)。
+ */
+export function pathBaseUrlFlaws(url) {
+    return httpUrlFlaws(url, PATH_BASE_URL_FORBIDDEN_PARTS);
+}
 /** 以 `http://` / `https://` 起头(大小写不敏感)—— 一道**语法前缀**守卫,不是形判官:不解析、不看 host / 部件,所以 `https://` 这样的裸 scheme 它也收(见头注「第二个答案」)。
  *  唯一读者是请求面 MCP 传输读器(`readRequestMcpTransport`);S-2106 收口时它退成那个读器座位的「照字面写全」规则,与形判官合取。 */
 export function startsWithHttpScheme(raw) {

package/dist/web-admin-credential.js

@@ -25,6 +25,7 @@ import { NON_SECRET_URL_NO_MIGRATION } from "./types.js";
 import { buildQuotedIssue } from "./quoted-issue.js";
 import { RFC3339_DATE_TIME } from "./rfc3339.js"; // the package's one RFC 3339 date-time judge (a project registration's `archivedAt` reads the same one)
 import { WEB_ADMIN_ENV } from "./web-admin-env.js";
+import { guardedSafeParse } from "./own-key-read.js"; // the one guarded zod verdict (parse + building its error in one guard)
 /** 信封 `kind` 的闭集今只有一员(`SEALED_BOX_ALG` 同式的字面常量:schema 的字面与读方的比较都引它)。 */
 export const WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND = "user-session";
 /** 一枚**令牌串**的形 —— 裸行 bearer、信封里的 `accessToken` / `refreshToken` 共用这**一条**律:可打印 ASCII
@@ -99,8 +100,10 @@ export function parseWebAdminCredentialFile(text) {
             // JSON.parse 的报错会引用出错位置附近的原文 —— 不转述它。
             return { kind: "unreadable", reason: "envelope is not valid JSON" };
         }
-        const parsed = WebAdminCredentialEnvelope.safeParse(json);
-        return parsed.success ? { kind: "envelope", envelope: parsed.data } : { kind: "unreadable", reason: envelopeRejection(parsed.error) };
+        const parsed = guardedSafeParse(() => WebAdminCredentialEnvelope.safeParse(json)); // 拼拒句时抛(被污染的运行时)⇒ 读不出,不抛出去
+        if (!parsed.ok)
+            return { kind: "unreadable", reason: "envelope could not be read during validation" };
+        return parsed.value.success ? { kind: "envelope", envelope: parsed.value.data } : { kind: "unreadable", reason: envelopeRejection(parsed.value.error) };
     }
     const firstLine = trimmed.split(/[\r\n]/, 1)[0].trim(); // 行尾 = 第一个 CR 或 LF(CRLF / LF / 孤 CR 同判)
     if (!TOKEN_CHARS.test(firstLine))

package/dist/web-admin-session-url.js

@@ -11,7 +11,7 @@
  * 会话不在那一台上就落空。所以模板函数拒绝铸只带一位的链接;解析却**宽读**(旧链接、手输的链接可能缺 `agent`),缺的那一位就是缺席。
  * 链接没有 scope 位(跨空间深链不在这一形里);日后加 scope 时作可选第三位、同一函数,不另开函数。
  */
-import { httpUrlFlaws, httpUrlRule } from "./url-shape.js";
+import { httpUrlRule, pathBaseUrlFlaws } from "./url-shape.js";
 /** 链接的路径与两个参数名 —— 本文件私有,唯一一处。 */
 const SESSION_LINK_PATH = "/chat";
 const WORKER_PARAM = "agent";
@@ -29,7 +29,7 @@ function requiredPart(label, value) {
 export function webAdminSessionUrl(webBaseUrl, target) {
     if (typeof webBaseUrl !== "string")
         throw new TypeError("webAdminSessionUrl: webBaseUrl must be a string (an absolute http(s) URL)");
-    const flaws = httpUrlFlaws(webBaseUrl, ["userinfo", "query", "fragment"]);
+    const flaws = pathBaseUrlFlaws(webBaseUrl); // 「后面要拼路径的基址」座位的唯一判官(禁 userinfo / query / fragment,路径前缀放行)
     if (flaws.length > 0)
         throw new TypeError(`webAdminSessionUrl: webBaseUrl ${httpUrlRule(flaws[0])}`);
     const worker = requiredPart("worker", target?.worker);

package/dist/worker-row-verdict.d.ts

@@ -9,6 +9,17 @@
 import { type ConfigPath } from "./config-fns.js";
 /** 判的是哪一形的行(闭集):`stored` = 店里存着的那一行;`migrated` = 一次性迁移改写出来、还没写回的那一行。 */
 export type WorkerRowForm = "stored" | "migrated";
+/**
+ * zod 的 `invalid_type` 句子(`Invalid input: expected <类型>, received <类型>`)—— 与 zod 自己的话**逐字同**(对每种 JSON 值;`test/migration-row-verdict-14.7.0` 逐值对着 zod 的原句核,升级 zod 改措辞即红),
+ * 区别只有一处:zod 对「原型不是 Object.prototype 的对象」读 `input.constructor.name` 当类型名 —— 原型不是 `Object.prototype` 的(隔离原型)行快照上,用户写的**自有 `constructor` 键**就成了类型名:
+ * 整次调用抛(`constructor.name` 是个对象)、用户文本进拒因(`received hello world`)、句子变样。这里不读 constructor。别的 issue 不管(返回 `undefined` ⇒ 沿用 zod 的 / 包自己写的句子)。
+ * 只给本文件的终判调用(`safeParse` 的 `error` 参数);它在 schema 自带的句子之后、zod 内置句子之前生效。
+ */
+export declare function safeIssueMessage(issue: {
+    readonly code: string;
+    readonly expected?: unknown;
+    readonly input?: unknown;
+}): string | undefined;
 /** 一行的终判:读得进 ⇒ `undefined`;读不进 ⇒ 第一条 issue 的路径(相对该行)+ 拒句(见文件头)。 */
 export declare function workerRowVerdict(row: Readonly<Record<string, unknown>>, form: WorkerRowForm): {
     readonly field: ConfigPath;