@sema-agent/settings-schema 14.3.0 → 14.5.0

package/dist/fs-failure.js

@@ -12,7 +12,12 @@
  * 认得的 errno 给那一步对应的出路,别的 errno(磁盘满、I/O 错 …)给 Node 自己的句子 —— 照样响亮,只是不替它猜出路。两条与落点无关的律:
  *  · errno 只打一遍 —— 句首括号里一次,Node 句子自带的 `<errno>: ` 前缀去掉;
  *  · `ENAMETOOLONG`(路径某一节或整条超限)既不是目录的错也不是文件的错 ⇒ 一句 `path too long: <被操作系统拒的路径> (ENAMETOOLONG)`,不点名目录、不给权限类出路。
- * 目录落点(`dir-create-temp` / `remove`)的 `EPERM` / `EROFS` 出路句尾加「目录可能是只读 / 不可变(chflags / chattr)」—— 改权限位修不好的那两种。
+ * 三个落点(`dir-create-temp` / `remove` / `rename`)的权限类出路走**同一条顺序**(`rename` 的「可写」是已证明的事实,见下)({@link permissionWayOut}):同一个 `EPERM` 既可能是目录模式不让写,也可能是不可变标志
+ * (macOS `chflags uchg` / Linux `chattr +i`)—— 铸点是纯函数,分不清,但调用方在 Node 一侧能读目录模式,把「模式对本进程可写」这个事实经落点的 `directoryWritable` 递进来:
+ * `EPERM` ∧ 可写 ⇒ chmod 已经没用,首选出路 = 清标志(`chflags nouchg` / `chattr -i`);否则(模式不可写,或调用方没读过模式 —— 注入的替身 I/O 抛的错,包看不到它背后)⇒ 先 chmod,
+ * 句尾提示「只读 / 不可变」的可能。`EROFS` 的出路不变(只读文件系统清不掉),`EACCES` 是纯权限位,不吃这条规则。
+ * `rename` 落点的「可写」不是读出来的而是已证明的(走到 rename 时临时文件刚在同一目录建成):`EPERM` 恒为清标志先行,`EACCES` 保留 14.4.0 的文件向原句("make the file replaceable — clear an immutable flag"),
+ * 两者句尾都是粘滞目录一句,都不说「make the directory writable」。
  *
  * 原子写器抛 {@link FsFailure}(句子在 `message`,`code` 照抄底层 errno,原错误在 `cause`);它在写器内部已经按更细的落点铸过句子,
  * 命令行 / 迁移用 {@link fsFailureMessage} 取句 —— 已经是 {@link FsFailure} 的原样用,否则按它所在的口铸。
@@ -21,11 +26,22 @@
 const DIRECTORY_NOT_WRITABLE = new Set(["EACCES", "EPERM", "EROFS", "ENOENT"]);
 /** `remove` 里「目录不让删目录项」的 errno(同一个因:目录不可写)。目录不在 / 文件已不在(ENOENT)不是这个因,给 Node 自己的句子。 */
 const DIRECTORY_ENTRY_NOT_REMOVABLE = new Set(["EACCES", "EPERM", "EROFS"]);
-/** `rename` 里「目录收新文件、却换不掉这一份」的 errno:不可变标志、粘滞目录里别人的文件。出路 = 让文件可被替换。 */
+/** `rename` 里「目录收新文件、却换不掉这一份」的 errno:不可变标志、粘滞目录里别人的文件。出路 = 文件向(见 {@link renameWayOut}),句尾加粘滞目录一句。 */
 const FILE_NOT_REPLACEABLE = new Set(["EACCES", "EPERM"]);
-/** 目录落点(`dir-create-temp` / `remove`)的出路。`EPERM`(目录带不可变标志:macOS `chflags uchg`、Linux `chattr +i`)与 `EROFS`(只读文件系统)靠改权限位修不好,
- *  出路句尾提示这一种可能;`EACCES` / `ENOENT` 是纯权限位 / 目录不在,出路就是让目录可写。 */
-const directoryWayOut = (code) => (code === "EPERM" || code === "EROFS" ? "make the directory writable; directory may be read-only or immutable (chflags / chattr)" : "make the directory writable");
+/** `rename` 落点上「目录对本进程可写」的事实:走到 rename 时临时文件刚在**同一目录**建成,这是已证明的,不是读出来的 —— 写器不对 rename 落点读模式位(一个来源)。 */
+const RENAME_DIRECTORY_WRITABLE = true;
+/** 权限类出路的**唯一一条顺序**(三个落点共用;`rename` 以「可写」为已证明的事实代入):`EPERM` ∧ 目录模式对本进程可写 ⇒ 真因只能是不可变标志(或粘滞位),chmod 无效 ⇒ 首选出路 = 清标志,点名清谁(`flagSubject`)与两个平台的命令;
+ *  其余 ⇒ 先让目录可写,`EPERM` / `EROFS`(靠改权限位修不好的两种)的句尾提示「只读 / 不可变」;`EACCES` / `ENOENT` 是纯权限位 / 目录不在,出路就是让目录可写。 */
+const permissionWayOut = (code, directoryWritable, flagSubject) => code === "EPERM" && directoryWritable === true
+    ? `clear the immutable flag on ${flagSubject} (macOS: chflags nouchg; Linux: chattr -i) — the directory's permission bits already admit this process, so chmod will not help`
+    : code === "EPERM" || code === "EROFS"
+        ? "make the directory writable; directory may be read-only or immutable (chflags / chattr)"
+        : "make the directory writable";
+/** `rename` 落点的出路(文件向):`EPERM` 走 {@link permissionWayOut} 的顺序(目录可写已证明 ⇒ 清标志先行);`EACCES` 是 14.4.0 的原句逐字 ——
+ *  无论哪个 errno,都不说「make the directory writable」(与已证明的事实自相矛盾)。 */
+const renameWayOut = (code) => code === "EPERM" ? permissionWayOut(code, RENAME_DIRECTORY_WRITABLE, "the file or its directory") : "make the file replaceable — clear an immutable flag";
+/** `rename` 句尾的粘滞目录一句(与权限类出路并列的另一个因:粘滞目录里别人的文件只有属主能换)。 */
+const STICKY_DIRECTORY_NOTE = "in a sticky directory only the file's owner may replace it";
 const errnoOf = (e) => {
     const code = e?.code;
     return typeof code === "string" ? code : undefined;
@@ -49,13 +65,13 @@ export function fsFailureSentence(site, cause) {
     const tag = code === undefined ? "" : ` (${code})`;
     switch (site.landing) {
         case "dir-create-temp":
-            return `cannot write into directory ${parentDirectory(site.path)}${tag}: ${code !== undefined && DIRECTORY_NOT_WRITABLE.has(code) ? directoryWayOut(code) : nodeSentenceOf(cause, code)}`;
+            return `cannot write into directory ${parentDirectory(site.path)}${tag}: ${code !== undefined && DIRECTORY_NOT_WRITABLE.has(code) ? permissionWayOut(code, site.directoryWritable, "the directory") : nodeSentenceOf(cause, code)}`;
         case "rename":
             return code !== undefined && FILE_NOT_REPLACEABLE.has(code)
-                ? `cannot replace ${site.path}${tag}: make the file replaceable — clear an immutable flag; in a sticky directory only the file's owner may replace it`
+                ? `cannot replace ${site.path}${tag}: ${renameWayOut(code)}; ${STICKY_DIRECTORY_NOTE}`
                 : `cannot replace ${site.path}${tag}: ${nodeSentenceOf(cause, code)}`;
         case "remove":
-            return `cannot remove ${site.path} from directory ${parentDirectory(site.path)}${tag}: ${code !== undefined && DIRECTORY_ENTRY_NOT_REMOVABLE.has(code) ? directoryWayOut(code) : nodeSentenceOf(cause, code)}`;
+            return `cannot remove ${site.path} from directory ${parentDirectory(site.path)}${tag}: ${code !== undefined && DIRECTORY_ENTRY_NOT_REMOVABLE.has(code) ? permissionWayOut(code, site.directoryWritable, "the file or its directory") : nodeSentenceOf(cause, code)}`;
         case "read":
             return `cannot read ${site.of === "directory" ? "directory " : ""}${site.path}${tag}: ${nodeSentenceOf(cause, code)}`;
         case "write":

package/dist/index.d.ts

@@ -5,6 +5,7 @@
 export * from "./types.js";
 export * from "./execution-lanes.js";
 export * from "./url-shape.js";
+export * from "./url-credential.js";
 export * from "./default-model.js";
 export * from "./loopback.js";
 export * from "./hash.js";

package/dist/index.js

@@ -5,6 +5,7 @@
 export * from "./types.js";
 export * from "./execution-lanes.js"; // 7.0.0 M-R2: the ONE lane / store vocabulary (EXECUTION_LANE_WORDS / EXECUTION_LANES / STORE_BACKENDS / SESSION_BACKENDS / MEMORY_ENGINE_BACKENDS) — pure data, browser-safe
 export * from "./url-shape.js"; // 11.0.0: THE URL shape judge (httpUrlFlaws / httpUrlRule / isHierarchicalUrl), pure/browser-safe
+export * from "./url-credential.js"; // 14.5.0: THE "does this URL carry a credential" judge (findUrlCredential / findUrlUserinfo / URL_CREDENTIAL_REASONS / CREDENTIAL_PARAM_NAMES …), pure/browser-safe
 export * from "./default-model.js"; // 11.0.0: THE catalog-default resolver (roles.default → active tier ladder → fallback), pure/browser-safe
 export * from "./loopback.js"; // 11.0.0: the two「本机」predicates (auth relaxation — narrow / connection routing — wide), pure/browser-safe
 export * from "./hash.js";

package/dist/node.d.ts

@@ -9,5 +9,6 @@ export * from "./file-edit.js";
 export * from "./bundle.js";
 export * from "./local-load.js";
 export * from "./scheduler-store-node.js";
-export { migrateConfigDirectory, type ConfigDirectoryDocument, type ConfigDirectoryIo, type ConfigDirectoryMigration, type ConfigDirectoryRefusal, type MigrateConfigDirectoryOptions } from "./config-dir-migration.js";
+export { migrateConfigDirectory, migrateConfigDocuments, // 14.5.0:同一段「迁 → 整域终判」的同步口(入参是已有的存量文档,无 io)—— 目录形调的就是它的内核
+type ConfigDirectoryDocument, type ConfigDirectoryIo, type ConfigDirectoryMigration, type ConfigDirectoryRefusal, type ConfigDocumentsMigration, type MigrateConfigDirectoryOptions, type MigrateConfigDocumentsOptions, } from "./config-dir-migration.js";
 export { nodeConfigDirectoryIo } from "./config-dir-io.js";

package/dist/node.js

@@ -10,5 +10,6 @@ export * from "./bundle.js";
 export * from "./local-load.js";
 export * from "./scheduler-store-node.js"; // R7 self-wake scheduler store — fs binding of the ./scheduler-store contract
 // 目录形的一次性迁移(读目录 → 迁 → 整域终判 → 原子写 → 删 retired 域文件)—— 语义只此一处,命令行是它的渲染器、引擎起服调同一只。显式列名:该模块的包内私有件(出门形/拼路径)不外泄。
-export { migrateConfigDirectory } from "./config-dir-migration.js";
+export { migrateConfigDirectory, migrateConfigDocuments, // 14.5.0:同一段「迁 → 整域终判」的同步口(入参是已有的存量文档,无 io)—— 目录形调的就是它的内核
+ } from "./config-dir-migration.js";
 export { nodeConfigDirectoryIo } from "./config-dir-io.js"; // 上面那只函数的真 I/O 绑定:node:fs + 本包唯一的原子写器(config-document 模式规则)

package/dist/one-time-migrations.js

@@ -33,6 +33,7 @@ import { outgoingPath, redactSecrets } from "./config-fns.js";
 import { LANE_ENV_OWNER, STORE_ENV_KEYS, isLaneEnvKey } from "./execution-lane-index.js";
 import { EXECUTION_LANE_WORDS, MEMORY_ENGINE_BACKENDS, STORE_BACKENDS } from "./execution-lanes.js";
 import { INTEGER } from "./integer.js";
+import { isPlainJsonObject } from "./plain-json-object.js";
 import { RUNTIME_LIFT_TARGETS } from "./runtime-lift-targets.js";
 import { RETIRED_ROLE_WORDS } from "./retired-role-words.js";
 import { REMOTE_EXEC_DOCUMENT, RemoteExecSpec } from "./remote-exec.js";
@@ -197,7 +198,7 @@ export const ONE_TIME_MIGRATIONS = [
  * 重跑恒等:第二次跑零改动,只剩第一次就 `refused` 的那几张收据(那些坐标原样留着,读侧照旧拒)。
  */
 export function migrateStoredDocuments(docs, opts) {
-    if (!isPlainObject(docs))
+    if (!isPlainJsonObject(docs))
         throw new TypeError("migrateStoredDocuments: `docs` must be a { domain: document } object");
     switch (opts.coverage) {
         case "scope":
@@ -229,7 +230,7 @@ export function migrateStoredDocuments(docs, opts) {
  * 不是对象 ⇒ 原样返回(判形是读者的事)。
  */
 export function migrateEffectiveSnapshot(effective) {
-    if (!isPlainObject(effective))
+    if (!isPlainJsonObject(effective))
         return { effective, receipts: [] };
     const docs = {};
     for (const [k, v] of Object.entries(effective))
@@ -251,13 +252,7 @@ export function migrateEffectiveSnapshot(effective) {
             next[k] = v;
     return { effective: next, receipts: m.receipts };
 }
-function isPlainObject(v) {
-    if (v === null || typeof v !== "object" || Array.isArray(v))
-        return false;
-    const proto = Object.getPrototypeOf(v);
-    return proto === Object.prototype || proto === null;
-}
-const has = (o, k) => isPlainObject(o) && Object.prototype.hasOwnProperty.call(o, k);
+const has = (o, k) => isPlainJsonObject(o) && Object.prototype.hasOwnProperty.call(o, k);
 const without = (o, k) => {
     const { [k]: _gone, ...rest } = o;
     return rest;
@@ -291,12 +286,12 @@ function stepRuntimeDomain(out, coverage, receipts) {
     if (raw === undefined)
         return;
     const refuse = (reason) => void receipts.push(refused("SS-M1", "runtime", [], reason));
-    if (isPlainObject(raw) && Object.keys(raw).length === 0) {
+    if (isPlainJsonObject(raw) && Object.keys(raw).length === 0) {
         delete out.runtime;
         receipts.push(receipt("SS-M1", "runtime", [], "dropped-inert"));
         return;
     }
-    if (!isPlainObject(raw))
+    if (!isPlainJsonObject(raw))
         return refuse("the stored runtime document is not a JSON object — the scope does not read today either; fix it by hand");
     if (coverage === "partial" && !RUNTIME_LIFT_TARGETS.every((target) => has(out, target))) {
         return refuse("a runtime document migrates only together with its scope's governance and limits documents (coverage \"scope\") — on its own there is no telling whether governance was ever set");
@@ -305,7 +300,7 @@ function stepRuntimeDomain(out, coverage, receipts) {
     if (!parsed.success)
         return refuse("the stored runtime document does not read under the 10.x runtime schema — the scope does not read today either; fix it by hand");
     const limitsRaw = out.limits;
-    if (limitsRaw !== undefined && !isPlainObject(limitsRaw))
+    if (limitsRaw !== undefined && !isPlainJsonObject(limitsRaw))
         return refuse("the scope's limits document is not a JSON object — the scope does not read today either; fix limits first");
     const trio = GOVERNANCE_TRIO.filter((k) => has(raw, k) && raw[k] !== undefined);
     if (trio.length > 0) {
@@ -323,7 +318,7 @@ function stepRuntimeDomain(out, coverage, receipts) {
     const limitKeys = LIMIT_KEYS.filter((k) => parsed.data[k] !== undefined);
     if (limitKeys.length > 0) {
         // 迁移前的读法(消费方):`limits` 有这一键 ⇒ limits 赢;没有 ⇒ 读 runtime 上的值。
-        const limits = isPlainObject(limitsRaw) ? { ...limitsRaw } : {};
+        const limits = isPlainJsonObject(limitsRaw) ? { ...limitsRaw } : {};
         let added = false;
         for (const k of limitKeys) {
             if (Object.prototype.hasOwnProperty.call(limits, k))
@@ -346,13 +341,13 @@ function stepRuntimeDomain(out, coverage, receipts) {
 // ── SS-M2:hosts 超界 ───────────────────────────────────────────────────────────────────────────────────
 function stepHostsBounds(out, receipts) {
     const doc = out.hosts;
-    if (!isPlainObject(doc) || !Array.isArray(doc.hosts))
+    if (!isPlainJsonObject(doc) || !Array.isArray(doc.hosts))
         return;
     const rows = doc.hosts;
     let kept = [];
     const dropped = [];
     rows.forEach((row, index) => {
-        const name = isPlainObject(row) ? row.name : undefined;
+        const name = isPlainJsonObject(row) ? row.name : undefined;
         if (typeof name === "string" && name.length > HOST_NAME_MAX)
             dropped.push(index);
         else
@@ -402,8 +397,8 @@ const UNCHANGED = { kind: "unchanged" };
 function migrateWorkerRow(raw) {
     const refuse = (field, reason) => ({ kind: "refused", field, reason });
     const enabled = raw.enabled !== false;
-    const laneKeysOf = (rec) => (isPlainObject(rec) ? Object.keys(rec).filter(isLaneEnvKey) : []);
-    const storeKeysOf = (rec) => (isPlainObject(rec) ? STORE_ENV_KEYS.filter((k) => Object.hasOwn(rec, k)) : []);
+    const laneKeysOf = (rec) => (isPlainJsonObject(rec) ? Object.keys(rec).filter(isLaneEnvKey) : []);
+    const storeKeysOf = (rec) => (isPlainJsonObject(rec) ? STORE_ENV_KEYS.filter((k) => Object.hasOwn(rec, k)) : []);
     const envLaneKeys = laneKeysOf(raw.env);
     const secretLaneKeys = laneKeysOf(raw.secretEnv);
     const envStoreKeys = storeKeysOf(raw.env);
@@ -432,12 +427,12 @@ function migrateWorkerRow(raw) {
     const needLane = !hasExecution && (enabled || laneTouched);
     const needStore = !hasStore && (enabled || storeTouched);
     const w = structuredClone(raw);
-    const runtime = isPlainObject(w.runtime) ? w.runtime : {};
+    const runtime = isPlainJsonObject(w.runtime) ? w.runtime : {};
     w.runtime = runtime;
-    const env = isPlainObject(w.env) ? w.env : {};
-    const secretEnv = isPlainObject(w.secretEnv) ? w.secretEnv : {};
-    const coords = isPlainObject(w.coords) ? w.coords : {};
-    const secretRefs = isPlainObject(w.secretRefs) ? w.secretRefs : {};
+    const env = isPlainJsonObject(w.env) ? w.env : {};
+    const secretEnv = isPlainJsonObject(w.secretEnv) ? w.secretEnv : {};
+    const coords = isPlainJsonObject(w.coords) ? w.coords : {};
+    const secretRefs = isPlainJsonObject(w.secretRefs) ? w.secretRefs : {};
     const dropped = [];
     const drop = (container, slot, key) => {
         delete container[key];
@@ -601,9 +596,9 @@ function migrateWorkerRow(raw) {
         }
     }
     // 被搬空的 env / secretEnv 整键去掉(它们是可选字段;留一个 `{}` 只是噪声)
-    if (isPlainObject(w.env) && Object.keys(env).length === 0 && isPlainObject(raw.env) && Object.keys(raw.env).length > 0)
+    if (isPlainJsonObject(w.env) && Object.keys(env).length === 0 && isPlainJsonObject(raw.env) && Object.keys(raw.env).length > 0)
         delete w.env;
-    if (isPlainObject(w.secretEnv) && Object.keys(secretEnv).length === 0 && isPlainObject(raw.secretEnv) && Object.keys(raw.secretEnv).length > 0)
+    if (isPlainJsonObject(w.secretEnv) && Object.keys(secretEnv).length === 0 && isPlainJsonObject(raw.secretEnv) && Object.keys(raw.secretEnv).length > 0)
         delete w.secretEnv;
     // 改写后的行仍读不进 7.x 形 ⇒ 不写回半成品:拒,原文留盘(读口 `readWorkersRows` 扣下它)。判据与拒句是读口那一只(`workerRowVerdict`)。
     const verdict = workerRowVerdict(w, "migrated");
@@ -613,12 +608,12 @@ function migrateWorkerRow(raw) {
 }
 function stepWorkers6x(out, receipts) {
     const doc = out.workers;
-    if (!isPlainObject(doc) || !Array.isArray(doc.workers))
+    if (!isPlainJsonObject(doc) || !Array.isArray(doc.workers))
         return;
     const rows = doc.workers;
     let next;
     rows.forEach((row, index) => {
-        if (!isPlainObject(row) || typeof row.name !== "string")
+        if (!isPlainJsonObject(row) || typeof row.name !== "string")
             return; // 认不出名字:整域读侧判
         const r = migrateWorkerRow(row);
         switch (r.kind) {
@@ -646,7 +641,7 @@ function stepWorkers6x(out, receipts) {
 // ── SS-M5:模型钥匙二选一 ──────────────────────────────────────────────────────────────────────────────
 function stepModelKeyOneOf(out, receipts) {
     const doc = out.models;
-    if (!isPlainObject(doc) || !Array.isArray(doc.models))
+    if (!isPlainJsonObject(doc) || !Array.isArray(doc.models))
         return;
     const rows = doc.models;
     let next;
@@ -682,17 +677,17 @@ function rewriteAtMention(holder, document, at, receipts) {
     return { ...without(holder, "atModelAllowlist"), atMention };
 }
 function stepAtMention(out, receipts) {
-    if (isPlainObject(out.models)) {
+    if (isPlainJsonObject(out.models)) {
         const next = rewriteAtMention(out.models, "models", [], receipts);
         if (next !== undefined)
             out.models = next;
     }
     const rosters = out.rosters;
-    if (isPlainObject(rosters) && Array.isArray(rosters.rosters)) {
+    if (isPlainJsonObject(rosters) && Array.isArray(rosters.rosters)) {
         const rows = rosters.rosters;
         let next;
         rows.forEach((row, index) => {
-            if (!isPlainObject(row))
+            if (!isPlainJsonObject(row))
                 return;
             const r = rewriteAtMention(row, "rosters", ["rosters", index], receipts);
             if (r === undefined)
@@ -707,7 +702,7 @@ function stepAtMention(out, receipts) {
 // ── SS-M8:退役的角色词 ────────────────────────────────────────────────────────────────────────────────
 /** 一个 `roles` 图上的退役角色词键删掉(值不论 —— 没有角色读它);逐键一张 `dropped-inert` 收据。返回改后的图或 `undefined`(没改 / 不是对象:判形是读者的事)。 */
 function withoutRetiredRoles(roles, document, at, receipts) {
-    if (!isPlainObject(roles))
+    if (!isPlainJsonObject(roles))
         return undefined;
     const present = RETIRED_ROLE_WORDS.filter((w) => Object.prototype.hasOwnProperty.call(roles, w));
     if (present.length === 0)
@@ -721,17 +716,17 @@ function withoutRetiredRoles(roles, document, at, receipts) {
 }
 function stepRetiredRoleWords(out, receipts) {
     const models = out.models;
-    if (isPlainObject(models)) {
+    if (isPlainJsonObject(models)) {
         const roles = withoutRetiredRoles(models.roles, "models", [], receipts);
         if (roles !== undefined)
             out.models = { ...models, roles };
     }
     const rosters = out.rosters;
-    if (isPlainObject(rosters) && Array.isArray(rosters.rosters)) {
+    if (isPlainJsonObject(rosters) && Array.isArray(rosters.rosters)) {
         const rows = rosters.rosters;
         let next;
         rows.forEach((row, index) => {
-            if (!isPlainObject(row))
+            if (!isPlainJsonObject(row))
                 return;
             const roles = withoutRetiredRoles(row.roles, "rosters", ["rosters", index], receipts);
             if (roles === undefined)
@@ -749,16 +744,16 @@ function stepRetiredRoleWords(out, receipts) {
  *  消失);异名 ⇒ 原 `roles.default` 作「被压过」删掉、`default` 搬入。`default` 不是非空串 ⇒ 拒(今天它让整个 models 域读不进,不替运维猜)。 */
 function stepModelsDefault(out, receipts) {
     const doc = out.models;
-    if (!isPlainObject(doc) || !Object.prototype.hasOwnProperty.call(doc, "default"))
+    if (!isPlainJsonObject(doc) || !Object.prototype.hasOwnProperty.call(doc, "default"))
         return;
     const name = doc.default;
     if (typeof name !== "string" || name === "") {
         receipts.push(refused("SS-M9", "models", ["default"], "models.default is not a catalog name — it does not read today either; fix it by hand"));
         return;
     }
-    const roles = isPlainObject(doc.roles) ? doc.roles : {};
+    const roles = isPlainJsonObject(doc.roles) ? doc.roles : {};
     const prior = roles.default;
-    if (prior !== undefined && !(isPlainObject(prior) && prior.model === name))
+    if (prior !== undefined && !(isPlainJsonObject(prior) && prior.model === name))
         receipts.push(receipt("SS-M9", "models", ["roles", "default"], "dropped-shadowed"));
     receipts.push(moved("SS-M9", "models", ["default"], { document: "models", path: ["roles", "default"] }));
     out.models = { ...without(doc, "default"), roles: { ...roles, default: { model: name } } };
@@ -769,7 +764,7 @@ function stepModelsDefault(out, receipts) {
  *  overlay,catalog 的 digest 是引擎铸的,替运维机械转就是第二个编译器 / 第二个铸点。`prompts` 不是对象 ⇒ 不动(判形是读者的事)。 */
 function stepPromptsAxes(out, receipts) {
     const doc = out.prompts;
-    if (!isPlainObject(doc))
+    if (!isPlainJsonObject(doc))
         return;
     let next = doc;
     if (has(doc, "bindings") && doc.bindings !== undefined) {
@@ -820,7 +815,7 @@ function stripFragments(schema, value, path, onStrip, depth = 0) {
         return value.slice(0, hash);
     }
     if (s instanceof z.ZodDiscriminatedUnion) {
-        if (!isPlainObject(value))
+        if (!isPlainJsonObject(value))
             return value;
         const disc = s._zod.def.discriminator;
         for (const option of s.options) {
@@ -842,7 +837,7 @@ function stripFragments(schema, value, path, onStrip, depth = 0) {
         return value;
     }
     if (s instanceof z.ZodObject) {
-        if (!isPlainObject(value))
+        if (!isPlainJsonObject(value))
             return value;
         let next;
         for (const [k, fieldSchema] of Object.entries(s.shape)) {
@@ -866,7 +861,7 @@ function stripFragments(schema, value, path, onStrip, depth = 0) {
         return next ?? value;
     }
     if (s instanceof z.ZodRecord) {
-        if (!isPlainObject(value))
+        if (!isPlainJsonObject(value))
             return value;
         let next;
         for (const [k, el] of Object.entries(value)) {

package/dist/plain-json-object.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表):**「纯 JSON 对象」的谓词(三处读域 / 迁移 / config.d 的同一只;`hooks-config.ts` 的 `hookIsRecord`、`types.ts` 内联一份、`conformance/` 两只更弱的 `isPlainObject` 是既有副本,另票收)** —— 不是 `null`、不是数组、原型是 `Object.prototype` 或 `null`(JSON 解析出来的对象恒如此;
+ * `Date` / `Map` / 类实例 / 建在别的对象原型上的记录都不是)。读域文档的键集对比(`./config-fns`)、一次性迁移的文档形判(`./one-time-migrations`)、
+ * `config.d` 文档「是不是 JSON 对象」的判(`./config-d-file`)读它,不各写一份。零 import。
+ */
+export declare function isPlainJsonObject(v: unknown): v is Record<string, unknown>;

package/dist/plain-json-object.js

@@ -0,0 +1,11 @@
+/**
+ * 包内私有(不进主桶、不进 exports 表):**「纯 JSON 对象」的谓词(三处读域 / 迁移 / config.d 的同一只;`hooks-config.ts` 的 `hookIsRecord`、`types.ts` 内联一份、`conformance/` 两只更弱的 `isPlainObject` 是既有副本,另票收)** —— 不是 `null`、不是数组、原型是 `Object.prototype` 或 `null`(JSON 解析出来的对象恒如此;
+ * `Date` / `Map` / 类实例 / 建在别的对象原型上的记录都不是)。读域文档的键集对比(`./config-fns`)、一次性迁移的文档形判(`./one-time-migrations`)、
+ * `config.d` 文档「是不是 JSON 对象」的判(`./config-d-file`)读它,不各写一份。零 import。
+ */
+export function isPlainJsonObject(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}

package/dist/types.d.ts

@@ -57,6 +57,10 @@ export declare function urlQueryFragmentHasSecret(u: URL): boolean;
  *  echoed; a fragment's also names its migration, {@link nonSecretUrlIssue}); `params` carries the sentence (`template` / `operands`,
  *  no operands) and `flaw`, the rule word.
  *
+ *  Scope of the secret test: it judges the VALUE's shape (a value that looks like a secret, whatever the parameter is called) — the sibling
+ *  name-shaped judge `findUrlCredential` (`./url-credential`) asks the other question (a parameter whose NAME is on the credential-name table,
+ *  whatever the value looks like). Neither contains the other: `?key=abc` passes here and is a hit there; `?x=sk-live-…` is the reverse.
+ *
  *  This is the seat of every URL in a STORED document the one-time migration rewrites: the domain documents (models `baseUrl`, mcp `url`,
  *  `sessionMirror.engineUrl`, workers `gitApiBaseUrl`) and `config.d/remote-exec.json` (k8s `apiUrl`, `s3Snapshot.endpoint`). A URL
  *  that is not stored data — the web-admin credential envelope's `issuer`, a wire input — uses {@link NON_SECRET_URL_NO_MIGRATION}.
@@ -1793,6 +1797,8 @@ export declare const SkillSpec: z.ZodObject<{
     rosters: z.ZodPrefault<z.ZodArray<z.ZodString>>;
     content: z.ZodDefault<z.ZodString>;
     enabled: z.ZodDefault<z.ZodBoolean>;
+    allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     notes: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type SkillSpec = z.infer<typeof SkillSpec>;
@@ -1804,6 +1810,8 @@ export declare const SkillsConfig: z.ZodObject<{
         rosters: z.ZodPrefault<z.ZodArray<z.ZodString>>;
         content: z.ZodDefault<z.ZodString>;
         enabled: z.ZodDefault<z.ZodBoolean>;
+        allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         notes: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
@@ -1828,6 +1836,8 @@ export declare const SkillsManifestSchema: z.ZodObject<{
         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>>;
         contentHash: z.ZodString;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
@@ -2480,6 +2490,8 @@ export declare const DOMAIN_SCHEMAS: {
             rosters: z.ZodPrefault<z.ZodArray<z.ZodString>>;
             content: z.ZodDefault<z.ZodString>;
             enabled: z.ZodDefault<z.ZodBoolean>;
+            allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
             notes: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
     }, z.core.$strip>;

package/dist/types.js

@@ -193,6 +193,10 @@ function createNonSecretUrl(reachedByMigration) {
  *  echoed; a fragment's also names its migration, {@link nonSecretUrlIssue}); `params` carries the sentence (`template` / `operands`,
  *  no operands) and `flaw`, the rule word.
  *
+ *  Scope of the secret test: it judges the VALUE's shape (a value that looks like a secret, whatever the parameter is called) — the sibling
+ *  name-shaped judge `findUrlCredential` (`./url-credential`) asks the other question (a parameter whose NAME is on the credential-name table,
+ *  whatever the value looks like). Neither contains the other: `?key=abc` passes here and is a hit there; `?x=sk-live-…` is the reverse.
+ *
  *  This is the seat of every URL in a STORED document the one-time migration rewrites: the domain documents (models `baseUrl`, mcp `url`,
  *  `sessionMirror.engineUrl`, workers `gitApiBaseUrl`) and `config.d/remote-exec.json` (k8s `apiUrl`, `s3Snapshot.endpoint`). A URL
  *  that is not stored data — the web-admin credential envelope's `issuer`, a wire input — uses {@link NON_SECRET_URL_NO_MIGRATION}.
@@ -2338,6 +2342,21 @@ export const SkillSpec = z.object({
     /** The markdown body injected into the model context on invoke (progressive disclosure). Stored in full here; shipped as a hash in /effective. */
     content: z.string().default(""),
     enabled: z.boolean().default(true),
+    /** Tool allow list the skill declares — carried entry by entry as the author wrote it (same name and element shape as the
+     *  engine's local `.sema/skills` manifest `SkillSpec.allowedTools`). ABSENT = the key is not there (no list is carried);
+     *  PRESENT = the whole array, `[]` included, goes to the consumer's judge — two carried shapes, and what each reads as is the
+     *  judge's call (the engine's local skills directory reads an empty list as "not declared"). This contract only CARRIES: no
+     *  de-duplication, no sorting, no spelling check, no roster intersection — what an entry means (a tool, a namespace, a rule,
+     *  a path) is read in ONE place, the consumer's grant judge; the element shape judged here is "a non-empty string" and nothing
+     *  more. A malformed shape (not an array / a non-string or empty entry) is refused with a path naming the field
+     *  (`skills[i].allowedTools`) and, when the fault is an element, the element (`skills[i].allowedTools[j]`). Read leg: the list is an ordinary nested collection and follows the one salvage law that
+     *  `scenarios` / `rosters` / `mcp.servers[].allowTools` follow (a bad element is dropped with an `entry-dropped` warning whose
+     *  path reaches the element; a list with no good element makes the skill unreadable and the skill is dropped; when no skill of the domain survives, the domain falls back to its default with `domain-defaulted`). Travels on
+     *  `/effective` with the rest of the manifest ({@link SkillsManifestSchema} derives from this schema). */
+    allowedTools: z.array(z.string().min(1)).optional(),
+    /** Tool deny list the skill declares — same carrying and reading rules as {@link SkillSpec.allowedTools} (absent = no list
+     *  carried, present = the whole array goes to the consumer's judge, `[]` included; never de-duplicated, sorted or judged here). */
+    disallowedTools: z.array(z.string().min(1)).optional(),
     notes: z.string().optional(),
 });
 export const SkillsConfig = z

package/dist/url-credential.d.ts

@@ -0,0 +1,41 @@
+/** 拒因词(闭集;判序 = 本数组序;词只在这一处写 —— {@link UrlCredentialReason} 与 {@link UrlCredential} 的成员都从它派生)。 */
+export declare const URL_CREDENTIAL_REASONS: readonly ["url_userinfo", "url_credential_param"];
+export type UrlCredentialReason = (typeof URL_CREDENTIAL_REASONS)[number];
+/**
+ * 凭据参数名表(闭集,23 词,全部是小写 ASCII `[a-z][a-z0-9_-]*`)。query / fragment 里名字整名(ASCII 大小写不敏感)在这张表上的参数就是凭据。
+ * 加一个词 = 表里加一格(minor);判官与 {@link isCredentialParamName} 现算,不手抄第二份。
+ */
+export declare const CREDENTIAL_PARAM_NAMES: readonly ["api_key", "apikey", "api-key", "key", "token", "access_token", "refresh_token", "id_token", "auth", "authorization", "proxy-authorization", "password", "passwd", "pwd", "secret", "client_secret", "private_key", "signature", "sig", "x-amz-signature", "x-amz-security-token", "x-amz-credential", "sas"];
+export type CredentialParamName = (typeof CREDENTIAL_PARAM_NAMES)[number];
+/**
+ * 「这个**已解码**的参数名是不是凭据名」。入参是收方读到的那一形(`URLSearchParams` 解过一次码的名字):整名在 {@link CREDENTIAL_PARAM_NAMES} 里(ASCII 大小写不敏感)才算。
+ */
+export declare function isCredentialParamName(decodedName: string): boolean;
+/** 每个拒因词带的细节(键集必须覆盖 {@link URL_CREDENTIAL_REASONS} 的每个词:数组里加一个词而这里没跟 ⇒ 下面的映射型编译红,{@link urlCredentialRule} 的穷举 switch 也红)。 */
+interface UrlCredentialDetail {
+    readonly url_userinfo: unknown;
+    readonly url_credential_param: {
+        readonly at: "query" | "fragment";
+        readonly name: CredentialParamName;
+    };
+}
+/** 一处命中:`url_userinfo`,或 `url_credential_param` + 它在哪一段、表里的哪个词(小写;不是调用方的原字节)。成员从 {@link URL_CREDENTIAL_REASONS} 派生。 */
+export type UrlCredential = {
+    readonly [R in UrlCredentialReason]: {
+        readonly reason: R;
+    } & UrlCredentialDetail[R];
+}[UrlCredentialReason];
+/**
+ * 判:这个值作为 URL 读出来(WHATWG),带不带 **userinfo**(判官的第一问,也是 {@link findUrlCredential} 的第一步)。只问这一件的座位 —— 运行时本就拒带 userinfo 的 URL、
+ * 而凭据名参数不由它拒的载体 —— 问这一只,不在座位里另写一份 userinfo 谓词。纯函数。
+ */
+export declare function findUrlUserinfo(raw: string): Extract<UrlCredential, {
+    readonly reason: "url_userinfo";
+}> | undefined;
+/**
+ * 判:这个值作为 URL 读出来(WHATWG),带不带凭据。首个命中(userinfo → query → fragment);没有(含不透明 / 解析不了的值)⇒ `undefined`。纯函数。
+ */
+export declare function findUrlCredential(raw: string): UrlCredential | undefined;
+/** 一处命中的规则句(穷举;新拒因词不补 = 编译红)。只说规则与表词,不含值。 */
+export declare function urlCredentialRule(c: UrlCredential): string;
+export {};

package/dist/url-credential.js

@@ -0,0 +1,95 @@
+/**
+ * **「这个 URL 的 userinfo 或 query / fragment 里,有没有名字在凭据名表上的参数」的名形判官**(14.5.0;lift 自 server `src/url-credential.ts`,规则、拒因词闭集与规则句逐字搬)。纯函数,零 import(除同包的 `./url-shape`),浏览器安全。
+ *
+ * ## 与 `NON_SECRET_URL`(`./types`)的关系:两个问题,互补,不是一个包含另一个
+ * 本判官按**名**判 —— 参数叫什么(名字整名在 {@link CREDENTIAL_PARAM_NAMES} 上就是凭据,不论值长什么样);`NON_SECRET_URL` 的 `urlQueryFragmentHasSecret` 按**值形**判密钥 —— 值长得像密钥
+ * (不论参数叫什么)。所以 `?key=abc` 本判官命中而 `NON_SECRET_URL` 放行(值不像密钥),`?x=sk-live-…` 反之;userinfo 两边都判。存量域文档位(`mcp` 的 `transport.url` 等)读 `NON_SECRET_URL`,
+ * 请求面等座位读本判官。把两个问题合成一只定义是另一件事,这里不做。
+ *
+ * ## 规则(一条):URL 里的凭据 = 日志脱敏器已经在用的那一个定义
+ * 一个 URL 里凭据住三个位置:
+ *  · **userinfo**(`scheme://<这一段>@host`,只有用户名也算)—— 判由本包的 URL 形判官 {@link httpUrlFlaws}(`["userinfo"]`),本模块不留第二份谓词;
+ *  · **query 参数**、**fragment 参数**(同一段文法)里名字整名在 {@link CREDENTIAL_PARAM_NAMES} 上的那一个 —— 名字按收方的读法读:WHATWG `URLSearchParams` 解一次码,
+ *    ASCII 大小写不敏感(不做 Unicode 折叠),整名在表里才算(`db_password` / `tokens` / `keyword` 是另一个名字)。
+ * 答首个命中(判序 = 上面的序),拒因闭集两词 {@link URL_CREDENTIAL_REASONS};**值从不进答案**,参数名只回显表里的那个词(小写)。
+ * 不透明形 / 解析不了的值没有可读的部件 ⇒ 答「没有」—— 这一形收不收是**座位**自己的律,不在本判官里。
+ *
+ * ## 判官只判「有没有」;座位决定怎么用
+ * 本模块不决定哪个载体拒、哪个载体放:同一个键在不同载体上的律可以不同(例:新提交的请求面拒,续跑重放存量体的腿不拒 —— 拒会砖死升级前停驻的任务;
+ * 部署 env 与续跑重放只因 userinfo 拒,凭据名参数只在新提交门拒)。所以判官**不**接进任何一份读已落盘 / 重放字节的 schema 或读器 —— 那会把载体律焊死成
+ * 读器律;座位在自己的新提交门调 {@link findUrlCredential} / {@link findUrlUserinfo},拒句 / 拒体的形(HTTP 码、字段坐标、出路句)是座位自己的铸点。
+ *
+ * ## 名表的来源
+ * {@link CREDENTIAL_PARAM_NAMES} 是 server 日志脱敏器名表(锚强度表的键)的 23 词。脱敏器另有一列「自由文本里这个词的锚强度」,那一列是脱敏器的事,不在这里;
+ * 词表本身在这里成为契约面 —— 脱敏器与本判官读同一张词表(同一个定义)靠消费方把它的表键钉在本导出上(例:`Record<CredentialParamName, …>` 的穷尽映射 ⇒ 加 / 删词不同步即编译红)。
+ */
+import { httpUrlFlaws, httpUrlRule, isHierarchicalUrl } from "./url-shape.js";
+/** 拒因词(闭集;判序 = 本数组序;词只在这一处写 —— {@link UrlCredentialReason} 与 {@link UrlCredential} 的成员都从它派生)。 */
+export const URL_CREDENTIAL_REASONS = Object.freeze(["url_userinfo", "url_credential_param"]);
+/**
+ * 凭据参数名表(闭集,23 词,全部是小写 ASCII `[a-z][a-z0-9_-]*`)。query / fragment 里名字整名(ASCII 大小写不敏感)在这张表上的参数就是凭据。
+ * 加一个词 = 表里加一格(minor);判官与 {@link isCredentialParamName} 现算,不手抄第二份。
+ */
+export const CREDENTIAL_PARAM_NAMES = Object.freeze([
+    "api_key", "apikey", "api-key", "key",
+    "token", "access_token", "refresh_token", "id_token",
+    "auth", "authorization", "proxy-authorization",
+    "password", "passwd", "pwd",
+    "secret", "client_secret", "private_key",
+    "signature", "sig",
+    "x-amz-signature", "x-amz-security-token", "x-amz-credential",
+    "sas",
+]);
+/** 名表的查找形(`Set`,不拿普通对象当查表:`constructor` / `__proto__` 会读到原型链上的东西)。 */
+const CREDENTIAL_PARAM_NAME_SET = new Set(CREDENTIAL_PARAM_NAMES);
+/** ASCII 大小写折叠(只折 `A-Z`,不做 Unicode 折叠:`ＴＯＫＥＮ` 不是 `token`)。 */
+const asciiLower = (s) => s.replace(/[A-Z]/g, (c) => c.toLowerCase());
+/**
+ * 「这个**已解码**的参数名是不是凭据名」。入参是收方读到的那一形(`URLSearchParams` 解过一次码的名字):整名在 {@link CREDENTIAL_PARAM_NAMES} 里(ASCII 大小写不敏感)才算。
+ */
+export function isCredentialParamName(decodedName) {
+    return CREDENTIAL_PARAM_NAME_SET.has(asciiLower(decodedName));
+}
+/** 一段参数串(`?` / `#` 之后)里第一个凭据名参数的表词(小写);没有 ⇒ `undefined`。 */
+function credentialParamIn(params) {
+    for (const name of new URLSearchParams(params).keys()) {
+        const word = asciiLower(name);
+        if (CREDENTIAL_PARAM_NAME_SET.has(word))
+            return word;
+    }
+    return undefined;
+}
+/**
+ * 判:这个值作为 URL 读出来(WHATWG),带不带 **userinfo**(判官的第一问,也是 {@link findUrlCredential} 的第一步)。只问这一件的座位 —— 运行时本就拒带 userinfo 的 URL、
+ * 而凭据名参数不由它拒的载体 —— 问这一只,不在座位里另写一份 userinfo 谓词。纯函数。
+ */
+export function findUrlUserinfo(raw) {
+    return isHierarchicalUrl(raw) && httpUrlFlaws(raw, ["userinfo"]).includes("userinfo") ? { reason: "url_userinfo" } : undefined;
+}
+/**
+ * 判:这个值作为 URL 读出来(WHATWG),带不带凭据。首个命中(userinfo → query → fragment);没有(含不透明 / 解析不了的值)⇒ `undefined`。纯函数。
+ */
+export function findUrlCredential(raw) {
+    if (!isHierarchicalUrl(raw))
+        return undefined;
+    const userinfo = findUrlUserinfo(raw);
+    if (userinfo !== undefined)
+        return userinfo;
+    const u = new URL(raw);
+    const inQuery = credentialParamIn(u.search);
+    if (inQuery !== undefined)
+        return { reason: "url_credential_param", at: "query", name: inQuery };
+    const inFragment = credentialParamIn(u.hash.slice(1));
+    if (inFragment !== undefined)
+        return { reason: "url_credential_param", at: "fragment", name: inFragment };
+    return undefined;
+}
+/** 一处命中的规则句(穷举;新拒因词不补 = 编译红)。只说规则与表词,不含值。 */
+export function urlCredentialRule(c) {
+    switch (c.reason) {
+        case "url_userinfo":
+            return httpUrlRule("userinfo"); // 与形判官诸座同一句(不写第二句)
+        case "url_credential_param":
+            return `must not carry a credential parameter (the ${c.at} names "${c.name}", a name the service's log redactor treats as a credential)`;
+    }
+}