@sema-agent/settings-schema 11.2.0 → 11.3.0

package/dist/hooks.js

@@ -30,6 +30,7 @@
  */
 import { z } from "zod";
 import { INTEGER } from "./integer.js";
+import { buildQuotedIssue } from "./quoted-issue.js";
 // ── event set ──────────────────────────────────────────────────────────────────────────────────────────
 // The two halves below are where each word came from (CC 2.1.198's own table, then the later additions) — provenance for the
 // reader of this file, not a contract: they are module-private, and the ONE exported closed set is {@link HOOK_EVENTS}.
@@ -623,7 +624,7 @@ export const HOOK_INJECTED_ENV = [
 /** Default per-hook timeout when an entry does not set one (seconds; CC default). */
 export const DEFAULT_HOOK_TIMEOUT_SECONDS = 60;
 /** A non-empty string with no NUL byte (spawn()/JSON-safe). */
-const hookStr = z.string().min(1).refine((s) => !s.includes("\0"), "must not contain a NUL byte");
+const hookStr = z.string().min(1).refine((s) => !s.includes("\0"), buildQuotedIssue `must not contain a NUL byte`);
 /**
  * `if` condition — permission-rule syntax (e.g. "Bash(git *)") evaluated against tool_name/tool_input
  * BEFORE spawning the hook (only meaningful on tool events). Shell superset field, CC-compatible.
@@ -684,6 +685,25 @@ export const HookMatcherEntry = z.object({
 });
 /** The characters a matcher may consist of to be read as a NAME LIST rather than a regex. */
 const HOOK_MATCHER_NAME_LIST = /^[a-zA-Z0-9_|, -]+$/;
+function readHookMatcher(matcher) {
+    if (matcher === undefined || matcher === "" || matcher === "*")
+        return { form: "all" };
+    if (HOOK_MATCHER_NAME_LIST.test(matcher)) {
+        return {
+            form: "names",
+            names: matcher
+                .split(/[|,]/)
+                .map((part) => part.trim())
+                .filter((part) => part !== ""),
+        };
+    }
+    try {
+        return { form: "regex", pattern: new RegExp(matcher) };
+    }
+    catch {
+        return { form: "invalid" };
+    }
+}
 /**
  * Does `matcher` select `name`? —— **the one reading** of a hooks matcher (11.0.0). The shell and the server both ask this
  * function; neither keeps a copy.
@@ -703,25 +723,50 @@ const HOOK_MATCHER_NAME_LIST = /^[a-zA-Z0-9_|, -]+$/;
  *    for the bad matcher itself.
  * Before 11.0.0 the server anchored the regex form (`^(?:…)$`) while the shell did not, so one regex matcher selected different
  * tools in the two places. A deployment whose regex matchers relied on that anchoring selects MORE tools now — add `^…$`.
- * Pure: no budget / timeout — a caller evaluating untrusted regex matchers under a deadline does so around this call.
+ * Pure: no budget / timeout — a caller evaluating untrusted regex matchers under a deadline does so around this call
+ * ({@link hookMatcherForm} tells it beforehand which matchers run a regex at all).
  */
 export function hookMatcherSelects(matcher, name) {
-    if (matcher === undefined || matcher === "" || matcher === "*")
-        return true;
-    if (HOOK_MATCHER_NAME_LIST.test(matcher)) {
-        return matcher
-            .split(/[|,]/)
-            .map((part) => part.trim())
-            .some((part) => part !== "" && part === name);
-    }
-    let pattern;
-    try {
-        pattern = new RegExp(matcher);
+    const r = readHookMatcher(matcher);
+    switch (r.form) {
+        case "all":
+            return true;
+        case "names":
+            return r.names.includes(name);
+        case "regex":
+            return r.pattern.test(name);
+        case "invalid":
+            return "invalid";
+        default: {
+            const unhandled = r;
+            throw new Error(`hookMatcherSelects: unhandled matcher reading ${JSON.stringify(unhandled)}`);
+        }
     }
-    catch {
-        return "invalid";
+}
+/**
+ * Which form `matcher` takes under the one reading —— the same parse step as {@link hookMatcherSelects}, so for every
+ * matcher `hookMatcherForm(m) === "invalid"` ⇔ `hookMatcherSelects(m, name) === "invalid"` (for any `name`):
+ *  · `"literal"` —— no regex is compiled or run: absent / `""` / `"*"` (selects everything) and the NAME-LIST form (only name
+ *    characters, `|`, `,` and spaces — membership after splitting);
+ *  · `"regex"`   —— anything else that compiles as a JS regex (tested unanchored);
+ *  · `"invalid"` —— a regex that does not compile (the caller does not run the hook).
+ * For a caller that must route matchers before evaluating them (run the literal ones inline, give the regex ones a deadline).
+ */
+export function hookMatcherForm(matcher) {
+    const r = readHookMatcher(matcher);
+    switch (r.form) {
+        case "all":
+        case "names":
+            return "literal";
+        case "regex":
+            return "regex";
+        case "invalid":
+            return "invalid";
+        default: {
+            const unhandled = r;
+            throw new Error(`hookMatcherForm: unhandled matcher reading ${JSON.stringify(unhandled)}`);
+        }
     }
-    return pattern.test(name);
 }
 export const HooksConfig = z.partialRecord(HookEventName, z.array(HookMatcherEntry));
 /**

package/dist/host-path.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 叶子模块(纯、浏览器安全):**一只**「主机绝对路径」形判 —— 任务请求的 `cwd`(服务器受理时判)与项目登记里 `folder` / `file`
+ * 条目的值读同一只,不各写一份。只判形,不判存在(不碰文件系统)。
+ */
+import { z } from "zod";
+/** 一条主机绝对路径的长度上界(字符数)。 */
+export declare const ABSOLUTE_HOST_PATH_MAX = 4096;
+/**
+ * `p` 是不是一条形上合法的**主机绝对路径**:字符串、非空、≤ {@link ABSOLUTE_HOST_PATH_MAX}、不含 NUL、以 `/` 开头(posix 绝对)、没有 `..` 段
+ * (`/` 与 `\` 都算分隔符 —— `path.isAbsolute` 是语法判,`/a/../../etc` 也「绝对」,而读方 `path.resolve` 会把它解到别处;拒掉它,读到的就是写下的那一条)。
+ *
+ * posix 口径是有意的:读这些路径的主机车道今天跑 posix 树,而这一律在 posix 宿主上与 Node 的 `path.isAbsolute` 逐字同判(`C:\x`、`\\host\share`
+ * 在 posix 上不绝对)。哪天主机车道要接 win 树,换的是这一只(按树的家族判),读方跟着同一只走。
+ */
+export declare function isAbsoluteHostPath(p: unknown): p is string;
+/** {@link isAbsoluteHostPath} 的 zod 座位(一条 issue,定句)。 */
+export declare const AbsoluteHostPath: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;

package/dist/host-path.js

@@ -0,0 +1,22 @@
+/**
+ * 叶子模块(纯、浏览器安全):**一只**「主机绝对路径」形判 —— 任务请求的 `cwd`(服务器受理时判)与项目登记里 `folder` / `file`
+ * 条目的值读同一只,不各写一份。只判形,不判存在(不碰文件系统)。
+ */
+import { z } from "zod";
+import { buildQuotedIssue, fixed } from "./quoted-issue.js";
+/** 一条主机绝对路径的长度上界(字符数)。 */
+export const ABSOLUTE_HOST_PATH_MAX = 4096;
+/**
+ * `p` 是不是一条形上合法的**主机绝对路径**:字符串、非空、≤ {@link ABSOLUTE_HOST_PATH_MAX}、不含 NUL、以 `/` 开头(posix 绝对)、没有 `..` 段
+ * (`/` 与 `\` 都算分隔符 —— `path.isAbsolute` 是语法判,`/a/../../etc` 也「绝对」,而读方 `path.resolve` 会把它解到别处;拒掉它,读到的就是写下的那一条)。
+ *
+ * posix 口径是有意的:读这些路径的主机车道今天跑 posix 树,而这一律在 posix 宿主上与 Node 的 `path.isAbsolute` 逐字同判(`C:\x`、`\\host\share`
+ * 在 posix 上不绝对)。哪天主机车道要接 win 树,换的是这一只(按树的家族判),读方跟着同一只走。
+ */
+export function isAbsoluteHostPath(p) {
+    return typeof p === "string" && p.length > 0 && p.length <= ABSOLUTE_HOST_PATH_MAX && !p.includes("\0") && p.startsWith("/") && !p.split(/[/\\]/).includes("..");
+}
+/** {@link isAbsoluteHostPath} 的 zod 座位(一条 issue,定句)。 */
+export const AbsoluteHostPath = z
+    .string()
+    .refine(isAbsoluteHostPath, buildQuotedIssue `must be an absolute host path: starts with "/", no ".." segment, no NUL, at most ${fixed(String(ABSOLUTE_HOST_PATH_MAX))} characters`);

package/dist/integer.js

@@ -8,4 +8,5 @@
  * written down here once, instead of being borrowed from the library and changing whenever the library does.
  */
 import { z } from "zod";
-export const INTEGER = z.number().refine((n) => Number.isInteger(n), "Expected integer, received float");
+import { buildQuotedIssue } from "./quoted-issue.js";
+export const INTEGER = z.number().refine((n) => Number.isInteger(n), buildQuotedIssue `Expected integer, received float`);

package/dist/local-load.d.ts

@@ -1,6 +1,6 @@
 import { type RequiredEnvName } from "./file-edit.js";
 import { type EffectiveReadWarning } from "./config-fns.js";
-import { RemoteExecSpec } from "./remote-exec.js";
+import { type RemoteExecSpec } from "./remote-exec.js";
 import type { EffectiveConfig } from "./types.js";
 /** The remoteExec file path under a config root (under config.d/, beside the per-domain files). */
 export declare function remoteExecPath(root: string): string;

package/dist/local-load.js

@@ -13,25 +13,12 @@ import path from "node:path";
 import { writeFileAtomic } from "./atomic-write.js";
 import { FileConfigStore } from "./file-store.js";
 import { listRequiredEnvNames } from "./file-edit.js";
-import { sanitizeZodError } from "./config-fns.js";
-import { RemoteExecSpec } from "./remote-exec.js";
-/** Parse a RemoteExecSpec with a SANITIZED error (zod echoes the offending value — never let a pasted secret
- *  ride the thrown error). A hostile getter/Proxy trap → a fixed message. R14. */
-function parseRemoteExec(raw) {
-    let r;
-    try {
-        r = RemoteExecSpec.safeParse(raw);
-    }
-    catch {
-        throw new Error("invalid remoteExec (a value could not be read during validation)");
-    }
-    if (r.success)
-        return r.data;
-    throw sanitizeZodError(r.error);
-}
+import {} from "./config-fns.js";
+import { configDDocumentText, judgeRemoteExecText, parseRemoteExecDocument } from "./config-d-file.js";
+import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 /** The remoteExec file path under a config root (under config.d/, beside the per-domain files). */
 export function remoteExecPath(root) {
-    return path.join(root, "config.d", "remote-exec.json");
+    return path.join(root, "config.d", `${REMOTE_EXEC_DOCUMENT}.json`);
 }
 /** Read `<root>/config.d/remote-exec.json` → a VALIDATED RemoteExecSpec, or undefined if the file is absent
  *  (→ the engine defaults to `host` under CONFIG_PROVIDER=local). Throws (zod) on a present-but-invalid file. */
@@ -45,28 +32,19 @@ export async function loadRemoteExec(root) {
             return undefined;
         throw e;
     }
-    const trimmed = text.trim();
     // A present-but-empty file is a corruption/half-write, NOT "use the default" — FAIL CLOSED (an empty file
     // silently falling back to the host lane would be an isolation DOWNGRADE if the user meant local-docker).
-    // To get the host default, the file must be ABSENT, not empty.
-    if (!trimmed)
-        throw new Error(`${remoteExecPath(root)} is empty/corrupt — delete it for the host default, or write a valid remoteExec spec`);
-    let json;
-    try {
-        json = JSON.parse(trimmed); // sanitized: don't let a SyntaxError echo the raw (possibly secret-bearing) file text
-    }
-    catch {
-        throw new Error(`${remoteExecPath(root)} — invalid JSON (delete it for the host default, or write a valid remoteExec spec)`);
-    }
-    return parseRemoteExec(json);
+    // To get the host default, the file must be ABSENT, not empty. The text judge and the sanitized value judge are the ones the
+    // directory migration reads this file with (`./config-d-file`).
+    return parseRemoteExecDocument(judgeRemoteExecText(remoteExecPath(root), text));
 }
 /** Validate + ATOMICALLY write `<root>/config.d/remote-exec.json` (the package's one atomic writer, `./atomic-write`; never a half file). The
  *  client's `config` editor writes the exec backend through this; the engine reads it via loadRemoteExec. */
 export async function writeRemoteExec(root, spec) {
-    const parsed = parseRemoteExec(spec);
+    const parsed = parseRemoteExecDocument(spec);
     const dir = path.join(root, "config.d");
     await mkdir(dir, { recursive: true });
-    writeFileAtomic(remoteExecPath(root), JSON.stringify(parsed, null, 2) + "\n", "config-document");
+    writeFileAtomic(remoteExecPath(root), configDDocumentText(parsed), "config-document");
     return parsed;
 }
 /** Resolve a `file:<path>` .env VALUE → the file's trimmed content (the file-NAME secret ref, config-research

package/dist/migration-receipt.d.ts

@@ -2,6 +2,7 @@
  * 一次性迁移的**收据形**与两张闭集(11.0.0)—— 叶子模块(运行期零依赖;只有型导入),由 `./one-time-migrations` 再导出(不进主桶)。
  * 单拆出来只为一件事:调度店的读口(`./scheduler-store`,轻、浏览器安全)要在告警里带收据,不该为一个型把整套域 schema 拉进来。
  */
+import type { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 import type { DomainName, RetiredDomainName } from "./types.js";
 /** 本版登记的一次性**数据**迁移 id(闭集;每个 id 在 `ONE_TIME_MIGRATIONS` 登记表里恰一行)。收据只许这些 id —— 同表登记的 wire 删码位
  *  (`WIRE_RETIREMENT_IDS`,`./one-time-migrations`)不改任何存储形,铸不出收据,不在本集。 */
@@ -17,8 +18,8 @@ export type OneTimeMigrationId = (typeof ONE_TIME_MIGRATION_IDS)[number];
  */
 export declare const MIGRATION_APPLIED_AS: readonly ["moved", "rewritten", "dropped-shadowed", "dropped-inert", "refused"];
 export type MigrationAppliedAs = (typeof MIGRATION_APPLIED_AS)[number];
-/** 收据指向的那份文档:配置域名、retired 域名(`runtime`),或调度店(`scheduler-store`)。 */
-export type MigrationDocument = DomainName | RetiredDomainName | "scheduler-store";
+/** 收据指向的那份文档:配置域名、retired 域名(`runtime`)、`config.d/remote-exec.json`(`remote-exec`),或调度店(`scheduler-store`)。 */
+export type MigrationDocument = DomainName | RetiredDomainName | typeof REMOTE_EXEC_DOCUMENT | "scheduler-store";
 /** 文档里的段坐标(字符串段 = 对象键,数字段 = 数组下标;与告警坐标同一形)。 */
 export type MigrationPath = readonly (string | number)[];
 interface ReceiptBase {

package/dist/node.d.ts

@@ -10,5 +10,5 @@ export * from "./bundle.js";
 export * from "./local-load.js";
 export * from "./scheduler-store-node.js";
 export * from "./prompts-digest.js";
-export { migrateConfigDirectory, type ConfigDirectoryIo, type ConfigDirectoryMigration, type ConfigDirectoryRefusal, type MigrateConfigDirectoryOptions } from "./config-dir-migration.js";
+export { migrateConfigDirectory, type ConfigDirectoryDocument, type ConfigDirectoryIo, type ConfigDirectoryMigration, type ConfigDirectoryRefusal, type MigrateConfigDirectoryOptions } from "./config-dir-migration.js";
 export { nodeConfigDirectoryIo } from "./config-dir-io.js";

package/dist/one-time-migrations.d.ts

@@ -1,4 +1,5 @@
 import type { MigrationReceipt, OneTimeMigrationId } from "./migration-receipt.js";
+import { REMOTE_EXEC_DOCUMENT } from "./remote-exec.js";
 import { type DomainName, type RetiredDomainName } from "./types.js";
 export { MIGRATION_APPLIED_AS, ONE_TIME_MIGRATION_IDS, type MigrationAppliedAs, type MigrationDocument, type MigrationPath, type MigrationReceipt, type OneTimeMigrationId } from "./migration-receipt.js";
 export { migrateSchedulerRecords } from "./scheduler-store-migration.js";
@@ -33,8 +34,8 @@ export declare const ONE_TIME_MIGRATIONS: readonly OneTimeMigrationWindow[];
 /** 一组存储文档是不是**一个 scope 的全集**:`"scope"` = 缺席的域就是从未设过;`"partial"` = 缺席的域只是没给(principal 层、回滚史的
  *  单域行、任意子集)。只有 SS-M1 读它。 */
 export type DocumentCoverage = "scope" | "partial";
-/** 一组存储文档(域名 / retired 域名 → 文档)。别的键原样带过、不动。 */
-export type StoredDocuments = Readonly<Partial<Record<DomainName | RetiredDomainName, unknown>>>;
+/** 一组存储文档(域名 / retired 域名 / `remote-exec` → 文档)。别的键原样带过、不动。 */
+export type StoredDocuments = Readonly<Partial<Record<DomainName | RetiredDomainName | typeof REMOTE_EXEC_DOCUMENT, unknown>>>;
 export interface StoredDocumentsMigration {
     /** 迁移后的文档集:没改的文档是**同一引用**;被移除的(retired 域)不在;新建的(例:迁出的 `governance` / `limits`)在。 */
     readonly docs: Readonly<Record<string, unknown>>;
@@ -58,5 +59,6 @@ export declare function migrateEffectiveSnapshot(effective: unknown): {
     readonly effective: unknown;
     readonly receipts: readonly MigrationReceipt[];
 };
-/** 本包域 schema 里全部 URL 座位的坐标模式(派生;数组 / Record 位写 `*`)—— 迁移不用它,它给钉与说明看「今天派生出哪些座位」。 */
+/** SS-M7 走查的全部 URL 座位的坐标模式(派生;数组 / Record 位写 `*`;域文档以域名起头,`remote-exec.json` 以 `remote-exec` 起头)—— 迁移不用它,
+ *  它给钉与说明看「今天派生出哪些座位」。 */
 export declare function urlSeatPatterns(): string[];

package/dist/one-time-migrations.js

@@ -12,8 +12,8 @@
  * 同一串字节换意思的改动一律**换表示**(SS-M6 因此是「`atModelAllowlist` → `atMention`」换字段,而不是翻 `[]` 的义)。
  *
  * ## 入口(纯函数:不读环境、不读墙钟、不改入参、**不抬任何版本号**)
- *  · {@link migrateStoredDocuments} —— 一组**存储文档**(域名 → 文档)。一个 scope 的全部草稿、一个 principal 层(个人 models / mcp /
- *    skills / plugins)、回滚史里的一条单域行,各调一次;`coverage` 说这组文档是不是一个 scope 的全集(只有 SS-M1 要知道:缺席的
+ *  · {@link migrateStoredDocuments} —— 一组**存储文档**(域名 → 文档;还有本机的 `remote-exec` —— `config.d/remote-exec.json`,
+ *    只有 SS-M7 的座位走查读它)。一个 scope 的全部草稿、一个 principal 层(个人 models / mcp / skills / plugins)、回滚史里的一条单域行,各调一次;`coverage` 说这组文档是不是一个 scope 的全集(只有 SS-M1 要知道:缺席的
  *    `governance` 是「从未设过」还是「没给」)。缺的域 = 不动。
  *  · {@link migrateEffectiveSnapshot} —— 一份**冻结的 effective**(发布快照、回滚历史里的整份快照、引擎的 last-known-good 文件)。改写规则
  *    与草稿同(零语义变 ⇒ 不越过发布审批:改的是表示,不是已批准的内容);不从草稿重建;`version` / `updatedAt` 与其余信封键原样。
@@ -34,6 +34,7 @@ import { LANE_ENV_OWNER, STORE_ENV_KEYS, isLaneEnvKey } from "./execution-lane-i
 import { EXECUTION_LANE_WORDS, MEMORY_ENGINE_BACKENDS, STORE_BACKENDS } from "./execution-lanes.js";
 import { INTEGER } from "./integer.js";
 import { RUNTIME_LIFT_TARGETS } from "./runtime-lift-targets.js";
+import { REMOTE_EXEC_DOCUMENT, RemoteExecSpec } from "./remote-exec.js";
 import { DOMAIN_SCHEMAS, HOSTS_ARRAY_MAX, HOST_NAME_MAX, NON_SECRET_URL, isDomainName, isRetiredDomainName } from "./types.js";
 import { workerRowVerdict } from "./worker-row-verdict.js";
 import { unwrapSchema } from "./zod-unwrap.js";
@@ -128,7 +129,8 @@ export const ONE_TIME_MIGRATIONS = [
         removableAfter: "2026-11-09",
         rewrites: "every NON_SECRET_URL seat in a domain document (derived from the domain schemas, not listed by hand — today models.models[].baseUrl, " +
             "mcp.servers[].transport.url, execution.sessionMirror.engineUrl, workers.workers[].coords.gitApiBaseUrl): `#` and everything after it are removed " +
-            "(a fragment never goes on the wire)",
+            "(a fragment never goes on the wire); the same walk covers config.d/remote-exec.json, derived from its schema the same way " +
+            "(today the k8s apiUrl and s3Snapshot.endpoint) — the command-line migrate reads and rewrites it as one more document",
         removal: "the next major after the window: delete the SS-M7 step and its schema walk; the NON_SECRET_URL fragment rule loses its SS-M7 clause",
         afterRemoval: "the NON_SECRET_URL shape judge, which refuses a fragment (`#` included) on read and write",
     },
@@ -694,6 +696,14 @@ function stepModelsDefault(out, receipts) {
     out.models = { ...without(doc, "default"), roles: { ...roles, default: { model: name } } };
 }
 // ── SS-M7:URL fragment ────────────────────────────────────────────────────────────────────────────────
+/** SS-M7 走查的文档 → 它的 schema(座位从 schema 派生的那一只来源):配置域按 `DOMAIN_SCHEMAS`,`remote-exec` 按 `RemoteExecSpec`;别的文档没有 URL 座位。 */
+function urlSeatSchemaOf(document) {
+    if (isDomainName(document))
+        return DOMAIN_SCHEMAS[document];
+    if (document === REMOTE_EXEC_DOCUMENT)
+        return RemoteExecSpec;
+    return undefined;
+}
 /** 这只(已展开的)schema 是不是一个 `NON_SECRET_URL` 座位:就是它,或是「先归一、再交给它」的管道(`z.string().trim().pipe(NON_SECRET_URL)`)。 */
 function isUrlSeat(s) {
     return s === NON_SECRET_URL || (s instanceof z.ZodPipe && unwrapSchema(s.out) === NON_SECRET_URL);
@@ -775,7 +785,8 @@ function stripFragments(schema, value, path, onStrip, depth = 0) {
     }
     return value;
 }
-/** 本包域 schema 里全部 URL 座位的坐标模式(派生;数组 / Record 位写 `*`)—— 迁移不用它,它给钉与说明看「今天派生出哪些座位」。 */
+/** SS-M7 走查的全部 URL 座位的坐标模式(派生;数组 / Record 位写 `*`;域文档以域名起头,`remote-exec.json` 以 `remote-exec` 起头)—— 迁移不用它,
+ *  它给钉与说明看「今天派生出哪些座位」。 */
 export function urlSeatPatterns() {
     const out = [];
     const walk = (schema, path, depth) => {
@@ -813,16 +824,18 @@ export function urlSeatPatterns() {
     };
     for (const [d, schema] of Object.entries(DOMAIN_SCHEMAS))
         walk(schema, [d], 0);
+    walk(RemoteExecSpec, [REMOTE_EXEC_DOCUMENT], 0);
     return out;
 }
 function stepUrlFragments(out, receipts) {
     for (const d of Object.keys(out)) {
-        if (!isDomainName(d))
+        const schema = urlSeatSchemaOf(d);
+        if (schema === undefined)
             continue;
         const doc = out[d];
         if (doc === undefined)
             continue;
-        const next = stripFragments(DOMAIN_SCHEMAS[d], doc, [], (path) => receipts.push(receipt("SS-M7", d, path, "rewritten")));
+        const next = stripFragments(schema, doc, [], (path) => receipts.push(receipt("SS-M7", d, path, "rewritten")));
         if (next !== doc)
             out[d] = next;
     }

package/dist/quoted-issue.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 包内私有叶子模块(运行期零依赖,浏览器安全):**custom issue 的唯一铸点**(全包一只;11.0.0 时它住在 `./types` 里、只管那一个文件)。
+ *
+ * 律(一条):本包 schema 自己铸的每一条 custom issue —— `ctx.addIssue({ code: "custom", … })`、`.refine(判据, …)`、引用完整性的 `RefIssue`
+ * —— 都带 {@link QuotedIssueParams}(句子的固定词 `template` 与值 `operands`,值位是洞),`message` 恒是 {@link renderQuotedSentence} 从它渲出的,
+ * 铸点不手写第二遍。读者因此对 custom issue 只有一种读法:读结构化的句子(日志边界逐值打指纹、诊断面把值换成洞),不在「带 params 的读 params、
+ * 不带的退回 message」之间分流。没有值的定句一样走这里(`operands` 为空)。源码门在测试 custom-issue-params(扫 `src/` 全部铸点)。
+ *
+ * 不在本律里的(如实):zod 内建码的 issue —— `.max(n, 句)` / `.regex(re, 句)` 的 `too_big` / `invalid_format`、墓碑字段 `z.never` 的 `invalid_type`、
+ * 联合的错误映射 —— 它们的码不是 `custom`,`params` 不是 zod 给它们的槽位;它们的句子是定句(不插配置里的值),读者读 `message`。
+ */
+/** The params of a custom issue whose sentence QUOTES values (S-1075, 11.0.0) —— plain data: the sentence's fixed parts and the
+ *  values between them, in order, so `message` is exactly {@link renderQuotedSentence} of them. A reader that has to treat the
+ *  user-written parts of a sentence differently from its fixed words (a log boundary fingerprinting each value, the sanitizer
+ *  bounding each value's length) reads them HERE instead of guessing where a value starts in the sentence. Every custom issue this
+ *  package raises carries them (the fixed sentences too — those carry no operands). */
+export interface QuotedIssueParams {
+    readonly template: readonly string[];
+    readonly operands: readonly (string | number)[];
+}
+/** The one rendering of a quoted sentence: `template[0] + show(operands[0]) + template[1] + … + template[n]`. `show` defaults to
+ *  the value as written (that is how `message` is minted); a sanitizer / log boundary passes its own. */
+export declare function renderQuotedSentence(p: QuotedIssueParams, show?: (operand: string | number) => string): string;
+/** A custom issue's quoted sentence and its params (what {@link buildQuotedIssue} mints; spread into `ctx.addIssue`, or passed as a
+ *  `.refine` second argument). */
+export type QuotedIssue = {
+    readonly message: string;
+    readonly params: QuotedIssueParams;
+};
+/** Fixed sentence text spliced into a quoted sentence (a migration signpost, a closed vocabulary listed as the way out, a field
+ *  name): it joins the template, it is NOT an operand —— operands are the values the config holds, the only parts a log boundary
+ *  fingerprints and the sanitizer bounds (S-815). */
+export interface FixedText {
+    readonly fixedText: string;
+}
+export declare const fixed: (text: string) => FixedText;
+/** Mint a custom issue's `message` + `params` from a tagged template (`buildQuotedIssue\`duplicate model "${name}"\``): every
+ *  interpolation is an operand unless wrapped in {@link fixed} (then it is template text). THE minting point of custom issues in this
+ *  package — a sentence written straight into `message` would put a value into a sentence with no record of where it is, and give
+ *  readers a second way to read an issue. */
+export declare function buildQuotedIssue(strings: TemplateStringsArray, ...parts: (string | number | FixedText)[]): QuotedIssue;

package/dist/quoted-issue.js

@@ -0,0 +1,35 @@
+/**
+ * 包内私有叶子模块(运行期零依赖,浏览器安全):**custom issue 的唯一铸点**(全包一只;11.0.0 时它住在 `./types` 里、只管那一个文件)。
+ *
+ * 律(一条):本包 schema 自己铸的每一条 custom issue —— `ctx.addIssue({ code: "custom", … })`、`.refine(判据, …)`、引用完整性的 `RefIssue`
+ * —— 都带 {@link QuotedIssueParams}(句子的固定词 `template` 与值 `operands`,值位是洞),`message` 恒是 {@link renderQuotedSentence} 从它渲出的,
+ * 铸点不手写第二遍。读者因此对 custom issue 只有一种读法:读结构化的句子(日志边界逐值打指纹、诊断面把值换成洞),不在「带 params 的读 params、
+ * 不带的退回 message」之间分流。没有值的定句一样走这里(`operands` 为空)。源码门在测试 custom-issue-params(扫 `src/` 全部铸点)。
+ *
+ * 不在本律里的(如实):zod 内建码的 issue —— `.max(n, 句)` / `.regex(re, 句)` 的 `too_big` / `invalid_format`、墓碑字段 `z.never` 的 `invalid_type`、
+ * 联合的错误映射 —— 它们的码不是 `custom`,`params` 不是 zod 给它们的槽位;它们的句子是定句(不插配置里的值),读者读 `message`。
+ */
+/** The one rendering of a quoted sentence: `template[0] + show(operands[0]) + template[1] + … + template[n]`. `show` defaults to
+ *  the value as written (that is how `message` is minted); a sanitizer / log boundary passes its own. */
+export function renderQuotedSentence(p, show = String) {
+    return p.template.reduce((out, part, i) => (i === 0 ? part : `${out}${show(p.operands[i - 1])}${part}`), "");
+}
+export const fixed = (text) => ({ fixedText: text });
+/** Mint a custom issue's `message` + `params` from a tagged template (`buildQuotedIssue\`duplicate model "${name}"\``): every
+ *  interpolation is an operand unless wrapped in {@link fixed} (then it is template text). THE minting point of custom issues in this
+ *  package — a sentence written straight into `message` would put a value into a sentence with no record of where it is, and give
+ *  readers a second way to read an issue. */
+export function buildQuotedIssue(strings, ...parts) {
+    const template = [strings[0]];
+    const operands = [];
+    parts.forEach((part, i) => {
+        if (typeof part === "object")
+            template[template.length - 1] += part.fixedText + strings[i + 1];
+        else {
+            operands.push(part);
+            template.push(strings[i + 1]);
+        }
+    });
+    const params = { template, operands };
+    return { message: renderQuotedSentence(params), params };
+}

package/dist/remote-exec.d.ts

@@ -27,6 +27,9 @@
  * ONLY; the service owns the adapter implementations.
  */
 import { z } from "zod";
+/** The name of this contract's document in a `config.d` directory (`config.d/remote-exec.json`) —— the one spelling: the local reader /
+ *  writer, the directory migration and the command line name the document by it. It is not a config domain (not in `DOMAIN_SCHEMAS`). */
+export declare const REMOTE_EXEC_DOCUMENT: "remote-exec";
 export declare const RemoteExecSpec: z.ZodDiscriminatedUnion<[z.ZodObject<{
     provider: z.ZodLiteral<"host">;
     workdir: z.ZodOptional<z.ZodString>;

package/dist/remote-exec.js

@@ -28,11 +28,15 @@
  */
 import { z } from "zod";
 import { INTEGER } from "./integer.js";
-import { ENV_NAME, K8S_QUANTITY, NON_SECRET_URL_NO_MIGRATION, TCP_PORT, containsSecretToken, hasNul } from "./types.js";
+import { buildQuotedIssue } from "./quoted-issue.js";
+import { ENV_NAME, K8S_QUANTITY, NON_SECRET_URL, TCP_PORT, containsSecretToken, hasNul } from "./types.js";
 import { retiredLaneWordRefusal } from "./execution-lanes.js";
+/** The name of this contract's document in a `config.d` directory (`config.d/remote-exec.json`) —— the one spelling: the local reader /
+ *  writer, the directory migration and the command line name the document by it. It is not a config domain (not in `DOMAIN_SCHEMAS`). */
+export const REMOTE_EXEC_DOCUMENT = "remote-exec";
 /** A non-empty exec-bound string (an image / path / shell / arg the adapter feeds to spawn()/fs). Rejects a NUL
  *  byte uniformly — a NUL validates here but makes Node throw at spawn/boot (fail-OPEN → runtime crash). R20. */
-const execStr = z.string().min(1).refine((s) => !hasNul(s), "must not contain a NUL byte");
+const execStr = z.string().min(1).refine((s) => !hasNul(s), buildQuotedIssue `must not contain a NUL byte`);
 /** Container knobs of the `local-docker` lane. `network` defaults to `none` at the adapter (the safe posture for
  *  untrusted code — see the dual-mode design note). */
 const DOCKER_FIELDS = {
@@ -83,8 +87,9 @@ export const RemoteExecSpec = z.discriminatedUnion("provider", [
         provider: z.literal("k8s"),
         /** Sandbox container image (service: K8S_SANDBOX_IMAGE). Required so a run is reproducible. */
         image: execStr,
-        /** Kube API URL (service: K8S_API_URL); absent → in-cluster service account. NO embedded credentials. */
-        apiUrl: NON_SECRET_URL_NO_MIGRATION.optional(),
+        /** Kube API URL (service: K8S_API_URL); absent → in-cluster service account. NO embedded credentials. A stored fragment is rewritten
+         *  by the one-time migration SS-M7 (this file is one of its documents), so the refusal names it. */
+        apiUrl: NON_SECRET_URL.optional(),
         /** env-NAME holding the kube bearer token (service: K8S_TOKEN). NEVER the token. */
         tokenEnv: ENV_NAME.optional(),
         /** env-NAME holding the base64 CA cert (service: K8S_CA_CERT_B64). NEVER the cert bytes. */
@@ -102,7 +107,7 @@ export const RemoteExecSpec = z.discriminatedUnion("provider", [
          *  "all three of endpoint/access/secret required" gate). */
         s3Snapshot: z
             .object({
-            endpoint: NON_SECRET_URL_NO_MIGRATION, // S3/MinIO endpoint — creds go in accessKeyEnv/secretKeyEnv, never the URL
+            endpoint: NON_SECRET_URL, // S3/MinIO endpoint — creds go in accessKeyEnv/secretKeyEnv, never the URL (a stored fragment: SS-M7, like apiUrl)
             bucket: execStr.optional(),
             accessKeyEnv: ENV_NAME,
             secretKeyEnv: ENV_NAME,
@@ -117,9 +122,9 @@ export const RemoteExecSpec = z.discriminatedUnion("provider", [
         provider: z.literal("ssh"),
         // host + username are persisted to config.d/remote-exec.json — scan for a secret-shaped literal (a secret must go
         // in privateKeyEnv, not the login). R14.
-        host: execStr.refine((s) => !containsSecretToken(s), "no secret literal in ssh host — credentials go in privateKeyEnv"),
+        host: execStr.refine((s) => !containsSecretToken(s), buildQuotedIssue `no secret literal in ssh host — credentials go in privateKeyEnv`),
         port: TCP_PORT.optional(),
-        username: execStr.refine((s) => !containsSecretToken(s), "no secret literal in ssh username — credentials go in privateKeyEnv"),
+        username: execStr.refine((s) => !containsSecretToken(s), buildQuotedIssue `no secret literal in ssh username — credentials go in privateKeyEnv`),
         /** env-NAME holding the SSH private key (service: SSH_PRIVATE_KEY). NEVER the key value. */
         privateKeyEnv: ENV_NAME,
         mountPath: execStr.optional(),

package/dist/rfc3339.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 包内私有叶子模块:**一只** RFC 3339 时刻判(从 `./web-admin-credential` 搬出 —— 凭证信封的 `expiresAt` 与项目登记的 `archivedAt` 读同一只,
+ * 不各写一份)。
+ */
+import { z } from "zod";
+/** RFC 3339 `date-time` 的**剖面**:zod 的 `z.iso.datetime({offset:true})` 管日历有效性(月日范围、闰年、时分秒范围),
+ *  这里的正则自己判另三处 —— 秒必备、数字偏移必须是 `±hh:mm`、偏移的时 00–23 / 分 00–59(`10:00Z`、`+0800` 与 `+99:99`
+ *  都不是 RFC 3339,后者 `Date.parse` 读成 NaN)。这三处的判据在本正则,不随 zod 哪一版收不收而变。大写 `T` / `Z`、不收闰秒 `:60`:读方普遍用
+ *  `Date.parse` 取时刻,这是那组形里它处处读得准的子集。 */
+export declare const RFC3339_DATE_TIME: z.ZodISODateTime;

package/dist/rfc3339.js

@@ -0,0 +1,12 @@
+/**
+ * 包内私有叶子模块:**一只** RFC 3339 时刻判(从 `./web-admin-credential` 搬出 —— 凭证信封的 `expiresAt` 与项目登记的 `archivedAt` 读同一只,
+ * 不各写一份)。
+ */
+import { z } from "zod";
+/** RFC 3339 `date-time` 的**剖面**:zod 的 `z.iso.datetime({offset:true})` 管日历有效性(月日范围、闰年、时分秒范围),
+ *  这里的正则自己判另三处 —— 秒必备、数字偏移必须是 `±hh:mm`、偏移的时 00–23 / 分 00–59(`10:00Z`、`+0800` 与 `+99:99`
+ *  都不是 RFC 3339,后者 `Date.parse` 读成 NaN)。这三处的判据在本正则,不随 zod 哪一版收不收而变。大写 `T` / `Z`、不收闰秒 `:60`:读方普遍用
+ *  `Date.parse` 取时刻,这是那组形里它处处读得准的子集。 */
+export const RFC3339_DATE_TIME = z.iso
+    .datetime({ offset: true })
+    .regex(/T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/, "must be an RFC 3339 date-time: seconds and a Z / ±hh:mm offset (hh 00-23, mm 00-59) are required");