@sema-agent/settings-schema 10.1.1 → 11.1.0

package/dist/hooks.js

@@ -29,9 +29,12 @@
  * Pure zod contract — zero runtime deps beyond zod, browser-safe, same as the rest of this package.
  */
 import { z } from "zod";
+import { INTEGER } from "./integer.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}.
 /** CC 2.1.198 full hook-event set (jP array) — 27 events. Order matches the shell's HOOK_EVENTS. */
-export const CC_198_HOOK_EVENTS = [
+const CC_198_HOOK_EVENTS = [
     "PreToolUse",
     "PostToolUse",
     "PostToolUseFailure",
@@ -71,8 +74,8 @@ export const CC_198_HOOK_EVENTS = [
  * (naming the missing words) whenever the CC anchor snapshot in `test/fixtures/cc-hook-events.json` holds an
  * event this set does not, and that snapshot is produced by `scripts/extract-cc-hook-events.mjs`, never typed.
  */
-export const POST_198_HOOK_EVENTS = ["CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded", "PreModelSwitch", "PostModelSwitch"];
-/** The full 33-event contract set = CC 198's 27 + the 6 post-198 events. */
+const POST_198_HOOK_EVENTS = ["CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded", "PreModelSwitch", "PostModelSwitch"];
+/** The full 33-event contract set = CC 198's 27 + the 6 post-198 events — the one exported closed set of hook event names. */
 export const HOOK_EVENTS = [...CC_198_HOOK_EVENTS, ...POST_198_HOOK_EVENTS];
 export const HookEventName = z.enum(HOOK_EVENTS);
 // ── ownership (owner-single) ─────────────────────────────────────────────────────────────────────
@@ -100,8 +103,8 @@ export const ENGINE_OWNED_HOOK_EVENTS = [
 export const HOOK_EVENT_OWNER = Object.fromEntries(HOOK_EVENTS.map((e) => [e, ENGINE_OWNED_HOOK_EVENTS.includes(e) ? "engine" : "shell"]));
 /**
  * Which INPUT FIELD an entry's `matcher` string is matched against, per event (`null` = matchers are
- * ignored for the event; every entry matches). Ported from the shell's getMatchingHooks switch (CC
- * semantics: exact name, `a|b` alternation, or a JS regex; empty / `*` matches everything).
+ * ignored for the event; every entry matches). Ported from the shell's getMatchingHooks switch. HOW the matcher is read
+ * against that field is {@link hookMatcherSelects} (the one reading).
  */
 export const HOOK_EVENT_MATCHER_FIELD = {
     PreToolUse: "tool_name",
@@ -201,20 +204,20 @@ export const BaseHookInput = z.object({
 export const PreToolUseHookInput = BaseHookInput.extend({
     hook_event_name: z.literal("PreToolUse"),
     tool_name: z.string(),
-    tool_input: z.unknown(),
+    tool_input: z.unknown().optional(),
     tool_use_id: z.string(),
 });
 export const PostToolUseHookInput = BaseHookInput.extend({
     hook_event_name: z.literal("PostToolUse"),
     tool_name: z.string(),
-    tool_input: z.unknown(),
-    tool_response: z.unknown(),
+    tool_input: z.unknown().optional(),
+    tool_response: z.unknown().optional(),
     tool_use_id: z.string(),
 });
 export const PostToolUseFailureHookInput = BaseHookInput.extend({
     hook_event_name: z.literal("PostToolUseFailure"),
     tool_name: z.string(),
-    tool_input: z.unknown(),
+    tool_input: z.unknown().optional(),
     tool_use_id: z.string(),
     error: z.string(),
     is_interrupt: z.boolean().optional(),
@@ -222,7 +225,7 @@ export const PostToolUseFailureHookInput = BaseHookInput.extend({
 /** One resolved tool call inside a PostToolBatch payload. */
 export const PostToolBatchToolCall = z.object({
     tool_name: z.string(),
-    tool_input: z.unknown(),
+    tool_input: z.unknown().optional(),
     tool_use_id: z.string(),
     tool_response: z.unknown().optional(),
 });
@@ -299,13 +302,13 @@ export const PostCompactHookInput = BaseHookInput.extend({
 export const PermissionRequestHookInput = BaseHookInput.extend({
     hook_event_name: z.literal("PermissionRequest"),
     tool_name: z.string(),
-    tool_input: z.unknown(),
+    tool_input: z.unknown().optional(),
     permission_suggestions: z.array(PermissionUpdate).optional(),
 });
 export const PermissionDeniedHookInput = BaseHookInput.extend({
     hook_event_name: z.literal("PermissionDenied"),
     tool_name: z.string(),
-    tool_input: z.unknown(),
+    tool_input: z.unknown().optional(),
     tool_use_id: z.string(),
     reason: z.string(),
 });
@@ -396,7 +399,7 @@ export const MessageDisplayHookInput = BaseHookInput.extend({
     /** Stable per-message UUID across flushes (not the API msg_… id). */
     message_id: z.string(),
     /** Zero-based flush index within the message. */
-    index: z.number().int(),
+    index: INTEGER,
     /** True on the message's last flush (exactly one per message). */
     final: z.boolean(),
     /** Newly completed lines since the prior flush (final flush may end mid-line / be empty). */
@@ -675,11 +678,52 @@ export const HttpHookEntry = z.object({
 export const HookEntry = z.discriminatedUnion("type", [CommandHookEntry, PromptHookEntry, AgentHookEntry, HttpHookEntry]);
 /** One matcher group: `matcher` (see HOOK_EVENT_MATCHER_FIELD) + the hooks it fires. */
 export const HookMatcherEntry = z.object({
-    /** Exact name, `a|b` alternation, or JS regex; empty/`*`/absent matches everything. */
+    /** Read by {@link hookMatcherSelects} — the one reading (name list or unanchored JS regex; empty/`*`/absent matches everything). */
     matcher: z.string().optional(),
     hooks: z.array(HookEntry),
 });
-export const HooksConfig = z.record(HookEventName, z.array(HookMatcherEntry));
+/** 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_|, -]+$/;
+/**
+ * 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.
+ *
+ * **Rule: the reading does not depend on the event.** `|`, `,` and spaces are name-list syntax under every event key, and the event is
+ * not an input. Why: `matcher` is one field of one shape ({@link HookMatcherEntry}) under every event; a reading that changed with the
+ * event key would make one string select different names once moved between events, and every reader would need the event to read
+ * a matcher at all. CC (the reference corpus `cli291.js:241202`, `xen` / `h5`) reads `,` and spaces as list syntax only for the events in its `h5`
+ * set — of the matcher-bearing events, `StopFailure` and `FileChanged` stay on `|` alone there, so a matcher under those two that
+ * contains `,` or a space is a name list here and a regex there (write `|` to mean the same thing in both).
+ *
+ *  · absent / `""` / `"*"` ⇒ selects everything;
+ *  · only name characters, `|`, `,` and spaces ⇒ a NAME LIST: split on `|` / `,`, trim each part, drop empty parts, membership
+ *    (case-sensitive; a space inside a word stays — `"Ba sh"` is one word);
+ *  · anything else ⇒ the whole matcher is a JS regex tested **unanchored** (`Edi.` selects `Edit`, `MultiEdit`, `NotebookEdit`;
+ *    write `^Edit$` to pin one name). A regex that does not compile ⇒ `"invalid"`: the caller does not run the hook and accounts
+ *    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.
+ */
+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);
+    }
+    catch {
+        return "invalid";
+    }
+    return pattern.test(name);
+}
+export const HooksConfig = z.partialRecord(HookEventName, z.array(HookMatcherEntry));
 /**
  * DESIGN POINT ③ (slot semantics — RESERVED, core to finalize): how `spec.hooks` composes with the
  * engine's own `deps.hooks` (e.g. the service's process-level toolTracer). "override" = the spec slot

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 /**
  * @sema-agent/settings-schema — the public barrel. ONE source of truth for the config contract shared by
- * the config center, the worker service, and the TOC desktop/CLI.
+ * web-admin, the worker service, and the TOC desktop/CLI.
  */
 export * from "./types.js";
 export * from "./execution-lanes.js";
+export * from "./url-shape.js";
+export * from "./default-model.js";
+export * from "./loopback.js";
 export * from "./hash.js";
 export * from "./sha256.js";
 export * from "./skills-manifest.js";
@@ -18,9 +21,12 @@ export * from "./scheduler-store.js";
 export * from "./cross-session.js";
 export * from "./hooks.js";
 export * from "./fleet.js";
-export * from "./migrate-workers.js";
-export * from "./migrate.js";
+export * from "./workers-rows.js";
 export * from "./api/auth.js";
 export * from "./api/auth-bridge.js";
 export * from "./api/scopes.js";
-export * from "./center-credential.js";
+export * from "./api/pull-token.js";
+export * from "./api/feedback.js";
+export * from "./web-admin-env.js";
+export * from "./web-admin-credential.js";
+export * from "./retired-envs.js";

package/dist/index.js

@@ -1,9 +1,12 @@
 /**
  * @sema-agent/settings-schema — the public barrel. ONE source of truth for the config contract shared by
- * the config center, the worker service, and the TOC desktop/CLI.
+ * web-admin, the worker service, and the TOC desktop/CLI.
  */
 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 "./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";
 export * from "./sha256.js";
 export * from "./skills-manifest.js";
@@ -18,13 +21,16 @@ export * from "./scheduler-store.js"; // R7 self-wake scheduler store CONTRACT (
 export * from "./cross-session.js"; // CC-parity `settings.json` cross-session keys (crossSessionInbound / dialogExpiry) — pure/browser-safe
 export * from "./hooks.js"; // CC-parity hooks contract (31-event set + owner map + per-event input/output shapes + HooksConfig) & stop attribution (stoppedBy) — pure/browser-safe
 export * from "./fleet.js"; // scheduling/fleet contract (drain protocol · instance discovery · dispatch policy · quota lease · usage report · quota reset event) — CONTROL-PLANE-SCHEDULING-DESIGN, pure/browser-safe
-export * from "./migrate-workers.js"; // 7.0.0 one-time workers-domain migration (env.REMOTE_EXEC / sessionBackend / tidb* → runtime.execution / runtime.store), pure — run it on the RAW document before parseDomain
-export * from "./migrate.js"; // 0.5→0.6 migration tools (hosts grandfathering + worker.model→catalog migration PLAN — report/draft only, E1; EXPERT-REDESIGN §2-2/§3), pure/browser-safe
+export * from "./workers-rows.js"; // 11.0.0 the workers domain's per-row verdict (readWorkersRows: a row that does not read is held, the rest read on) — permanent read semantics, pure
 export * from "./api/auth.js"; // /api/v1/auth/* wire contract (RFC 8628 device flow + rotating refresh + logout + approve) — REGISTRY-REBUILD-DESIGN §2, M1 shipped shapes frozen, pure/browser-safe
-export * from "./api/auth-bridge.js"; // 鉴权桥 contract: worker verifies registry user JWT (RS256-only, JWKS kid-miss refresh + throttle, offline grace fail-closed) → VerifiedIdentity — design §5, the service verifier's spec
-export * from "./api/scopes.js"; // multi-tenant scope contract: /api/v1/scopes* + /api/v1/auth/scope wire shapes + THE minting/switch decision functions (resolveTokenScope / canSwitchScope / effectiveScopeRole / tokenScopeOf) — registry imports these, never re-implements
-export * from "./center-credential.js"; // S-698 center-credential FILE contract: CenterCredentialEnvelope (user-session envelope, strict) + parseCenterCredentialFile (bare / envelope / unreadable — the one discrimination law) + S-742 CENTER_CREDENTIAL_ENV (the two declaration keys) + judgeCenterCredentialDeclaration (pick-exactly-one), pure/browser-safe
+export * from "./api/auth-bridge.js"; // 鉴权桥 contract: worker verifies web-admin user JWT (RS256-only, JWKS kid-miss refresh + throttle, offline grace fail-closed) → VerifiedIdentity — design §5, the service verifier's spec
+export * from "./api/scopes.js"; // multi-tenant scope contract: /api/v1/scopes* + /api/v1/auth/scope wire shapes + THE minting/switch decision functions (resolveTokenScope / canSwitchScope / effectiveScopeRole / readTokenScope) — web-admin imports these, never re-implements
+export * from "./api/pull-token.js"; // scope-bound token FORM + minting rule (one rule, token families are data: WORKER_PULL_TOKEN) + claimed-binding reader + verifier (re-mint + constant-time compare), pure-JS HMAC-SHA256, browser-safe
+export * from "./api/feedback.js"; // /bug report wire contract: FeedbackSubmitRequest (POST body) + FeedbackWire / FeedbackListResponse + the two caps, pure/browser-safe
+export * from "./web-admin-env.js"; // WEB_ADMIN_ENV — every env name an engine reads to reach web-admin (one table; a leaf module), pure/browser-safe
+export * from "./web-admin-credential.js"; // S-698 web-admin credential FILE contract: WebAdminCredentialEnvelope (user-session envelope, strict) + parseWebAdminCredentialFile (bare / envelope / unreadable — the one discrimination law) + judgeWebAdminCredentialDeclaration(env, credential) (pick-exactly-one over the credential's WEB_ADMIN_ENV pair; WEB_ADMIN_CREDENTIALS = access | assertion), pure/browser-safe
+export * from "./retired-envs.js"; // the retired-env TOMBSTONE table (renamed / replaced / removed, closed set) + retiredEnvRefusal(env) (the one refusal sentence) + buildRetiredEnvWire() — engine boot, catalog wire, shell and web-admin read this one table, pure/browser-safe
 // NOTE: the Node-fs-backed helpers (FileConfigStore + the file editor) are NOT in this barrel — they pull
 // `node:fs`/`node:path` and would break a browser/client bundle that only wants the contract (e.g.
-// sema-registry's client components import the zod types through here). Import them from the Node-only
+// web-admin's client components import the zod types through here). Import them from the Node-only
 // subpath instead: `import { FileConfigStore } from "@sema-agent/settings-schema/node"`.

package/dist/integer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The package's ONE integer rule (internal — not on any package subpath): `Number.isInteger` — a number with no fractional
+ * part, however large.
+ *
+ * The validator library's own integer check is narrower in its current major: it also refuses everything beyond
+ * ±(2^53 − 1). Every release of this package validated stored documents with the wider rule, and on a gate domain a stored
+ * value that stops reading is a whole-domain read failure, not a rejected write — so the rule stays where it always was and is
+ * written down here once, instead of being borrowed from the library and changing whenever the library does.
+ */
+import { z } from "zod";
+export declare const INTEGER: z.ZodNumber;

package/dist/integer.js

@@ -0,0 +1,11 @@
+/**
+ * The package's ONE integer rule (internal — not on any package subpath): `Number.isInteger` — a number with no fractional
+ * part, however large.
+ *
+ * The validator library's own integer check is narrower in its current major: it also refuses everything beyond
+ * ±(2^53 − 1). Every release of this package validated stored documents with the wider rule, and on a gate domain a stored
+ * value that stops reading is a whole-domain read failure, not a rejected write — so the rule stays where it always was and is
+ * 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");

package/dist/issue-path.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A zod issue's path as a {@link ConfigPath} (internal — not on any package subpath). zod types an issue path `PropertyKey[]`;
+ * this package's inputs are JSON (string keys, array indices), so a symbol segment never comes from a document — where one
+ * shows up anyway it leaves as its redacted `String()` form. The one place that converts the type, so the reports that name
+ * a field (`readWorkersRows`' `held[].field`, the one-time migrations' refusals) read it the same way.
+ */
+import { type ConfigPath } from "./config-fns.js";
+export declare function issuePath(issue: {
+    readonly path: readonly PropertyKey[];
+}): ConfigPath;

package/dist/issue-path.js

@@ -0,0 +1,10 @@
+/**
+ * A zod issue's path as a {@link ConfigPath} (internal — not on any package subpath). zod types an issue path `PropertyKey[]`;
+ * this package's inputs are JSON (string keys, array indices), so a symbol segment never comes from a document — where one
+ * shows up anyway it leaves as its redacted `String()` form. The one place that converts the type, so the reports that name
+ * a field (`readWorkersRows`' `held[].field`, the one-time migrations' refusals) read it the same way.
+ */
+import { redactSecrets } from "./config-fns.js";
+export function issuePath(issue) {
+    return issue.path.map((seg) => (typeof seg === "number" || typeof seg === "string" ? seg : redactSecrets(String(seg))));
+}

package/dist/local-load.d.ts

@@ -7,7 +7,7 @@ export declare function remoteExecPath(root: string): string;
 /** 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. */
 export declare function loadRemoteExec(root: string): Promise<RemoteExecSpec | undefined>;
-/** Validate + ATOMICALLY write `<root>/config.d/remote-exec.json` (tmp → rename; never a half file). The
+/** 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 declare function writeRemoteExec(root: string, spec: unknown): Promise<RemoteExecSpec>;
 /** Parse `<root>/.env` (KEY=VALUE, `#` comments, optional surrounding quotes) MERGED OVER process.env (the

package/dist/local-load.js

@@ -7,9 +7,10 @@
  * `<root>/config.d/remote-exec.json` (service vote), loaded/validated by loadRemoteExec — distinct from
  * the per-domain `config.d/<domain>.json` the resolver reads. getEffective never reads it (not a DomainName).
  */
-import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 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";
@@ -28,9 +29,6 @@ function parseRemoteExec(raw) {
         return r.data;
     throw sanitizeZodError(r.error);
 }
-// Monotonic suffix so two atomic writes in the SAME process+millisecond can't collide on the tmp name (which
-// would make one rename hit ENOENT / lose a write). pid+Date.now() alone isn't unique under concurrency.
-let tmpSeq = 0;
 /** 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");
@@ -62,21 +60,13 @@ export async function loadRemoteExec(root) {
     }
     return parseRemoteExec(json);
 }
-/** Validate + ATOMICALLY write `<root>/config.d/remote-exec.json` (tmp → rename; never a half file). The
+/** 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 dir = path.join(root, "config.d");
     await mkdir(dir, { recursive: true });
-    const tmp = path.join(dir, `.remote-exec.json.${process.pid}.${Date.now()}.${tmpSeq++}.tmp`);
-    try {
-        await writeFile(tmp, JSON.stringify(parsed, null, 2) + "\n", "utf8");
-        await rename(tmp, remoteExecPath(root));
-    }
-    catch (e) {
-        await unlink(tmp).catch(() => { }); // never leave a half-written tmp behind
-        throw e;
-    }
+    writeFileAtomic(remoteExecPath(root), JSON.stringify(parsed, null, 2) + "\n", "config-document");
     return parsed;
 }
 /** Resolve a `file:<path>` .env VALUE → the file's trimmed content (the file-NAME secret ref, config-research

package/dist/loopback.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 「这是本机吗」—— **两个**问题,各一只具名谓词(11.0.0)。读者按自己问的是哪一个来选,不再各写一份字面表。
+ *
+ *  · **鉴权放宽**({@link isLoopbackAuthHost},窄):要不要因为对端是本机而少要一样东西(免登录、允许明文 http 带凭据)。
+ *    窄是安全方向 —— 认少了只会多要一次凭据;认多了就是把放宽送给一台不是本机的主机。只认字面。
+ *  · **连接路由**({@link isLoopbackRouteHost},宽):这条连接会不会落在本机(要不要绕开代理直连)。宽是正确方向 ——
+ *    认少了,本机目标被送进代理,代理那头的 127.0.0.1 是代理自己。
+ *
+ * 两只都是纯函数,入参是 `URL.hostname`、socket 地址或裸主机名;不用 `node:net`(浏览器 / 客户端包可用)。
+ */
+/**
+ * 鉴权放宽问的「本机」:只认四个字面 `127.0.0.1` / `localhost` / `::1` / `[::1]`(`URL.hostname` 对 IPv6 带方括号,两写法都收),
+ * 外加 socket 地址形 `::ffff:127.0.0.1`(双栈监听上 IPv4 回环连接的 `remoteAddress`)。大小写变体、尾点、127/8 的其它地址、
+ * 全写 IPv6、未指定地址一律不算 —— 那些都要先被「规范化」才是本机,而放宽不赌规范化。
+ */
+export declare function isLoopbackAuthHost(host: string): boolean;
+/**
+ * 连接路由问的「本机」(大小写不敏感):
+ *  · `localhost`(含 FQDN 尾点 `localhost.`);
+ *  · IPv4 `127.0.0.0/8` 整段与未指定地址 `0.0.0.0`(作为目的地址它在本机就是本机);
+ *  · IPv6 `::1`(带不带方括号、全写都算)与未指定地址 `::`;
+ *  · IPv4 映射 IPv6 的回环段 `::ffff:127.x.x.x` 与 `::ffff:0.0.0.0`(WHATWG 把它们规范成 `::ffff:7f00:1` 形,按规范形判)。
+ * 刻意**不**认 `*.localhost` 子域(能否落到本机取决于系统解析器,不是地址本身的事实)、带区域 id 的 IPv6、简写 IPv4(`127.1`)。
+ * 认不出的写法一律答 `false`(按远端处置)。
+ */
+export declare function isLoopbackRouteHost(host: string): boolean;

package/dist/loopback.js

@@ -0,0 +1,54 @@
+/**
+ * 「这是本机吗」—— **两个**问题,各一只具名谓词(11.0.0)。读者按自己问的是哪一个来选,不再各写一份字面表。
+ *
+ *  · **鉴权放宽**({@link isLoopbackAuthHost},窄):要不要因为对端是本机而少要一样东西(免登录、允许明文 http 带凭据)。
+ *    窄是安全方向 —— 认少了只会多要一次凭据;认多了就是把放宽送给一台不是本机的主机。只认字面。
+ *  · **连接路由**({@link isLoopbackRouteHost},宽):这条连接会不会落在本机(要不要绕开代理直连)。宽是正确方向 ——
+ *    认少了,本机目标被送进代理,代理那头的 127.0.0.1 是代理自己。
+ *
+ * 两只都是纯函数,入参是 `URL.hostname`、socket 地址或裸主机名;不用 `node:net`(浏览器 / 客户端包可用)。
+ */
+/**
+ * 鉴权放宽问的「本机」:只认四个字面 `127.0.0.1` / `localhost` / `::1` / `[::1]`(`URL.hostname` 对 IPv6 带方括号,两写法都收),
+ * 外加 socket 地址形 `::ffff:127.0.0.1`(双栈监听上 IPv4 回环连接的 `remoteAddress`)。大小写变体、尾点、127/8 的其它地址、
+ * 全写 IPv6、未指定地址一律不算 —— 那些都要先被「规范化」才是本机,而放宽不赌规范化。
+ */
+export function isLoopbackAuthHost(host) {
+    return host === "127.0.0.1" || host === "localhost" || host === "::1" || host === "[::1]" || host === "::ffff:127.0.0.1";
+}
+/** 点分十进制 IPv4(每段 0–255、无前导零)—— 与 Node `net.isIPv4` 同一个接受集。 */
+const DOTTED_IPV4 = /^(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)$/;
+/**
+ * 连接路由问的「本机」(大小写不敏感):
+ *  · `localhost`(含 FQDN 尾点 `localhost.`);
+ *  · IPv4 `127.0.0.0/8` 整段与未指定地址 `0.0.0.0`(作为目的地址它在本机就是本机);
+ *  · IPv6 `::1`(带不带方括号、全写都算)与未指定地址 `::`;
+ *  · IPv4 映射 IPv6 的回环段 `::ffff:127.x.x.x` 与 `::ffff:0.0.0.0`(WHATWG 把它们规范成 `::ffff:7f00:1` 形,按规范形判)。
+ * 刻意**不**认 `*.localhost` 子域(能否落到本机取决于系统解析器,不是地址本身的事实)、带区域 id 的 IPv6、简写 IPv4(`127.1`)。
+ * 认不出的写法一律答 `false`(按远端处置)。
+ */
+export function isLoopbackRouteHost(host) {
+    let h = host.trim().toLowerCase();
+    if (h.startsWith("[") && h.endsWith("]"))
+        h = h.slice(1, -1);
+    h = h.replace(/\.+$/, ""); // FQDN 尾点:`localhost.` / `127.0.0.1.` 与不带点的是同一个目的地
+    if (h === "localhost")
+        return true;
+    if (DOTTED_IPV4.test(h))
+        return h.startsWith("127.") || h === "0.0.0.0";
+    if (!h.includes(":"))
+        return false;
+    // IPv6:交给 WHATWG 规范化(全写 / 前导零 / 点分映射形收成同一种压缩写法)再比;解析不动(区域 id 等)⇒ 按远端处置。
+    const bracketed = `http://[${h}]/`;
+    if (!URL.canParse(bracketed))
+        return false;
+    const canon = new URL(bracketed).hostname.slice(1, -1);
+    if (canon === "::1" || canon === "::")
+        return true;
+    const mapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(canon);
+    if (mapped === null)
+        return false;
+    const hi = parseInt(mapped[1], 16);
+    const lo = parseInt(mapped[2], 16);
+    return hi >> 8 === 127 || (hi === 0 && lo === 0);
+}

package/dist/migration-receipt.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 一次性迁移的**收据形**与两张闭集(11.0.0)—— 叶子模块(运行期零依赖;只有型导入),由 `./one-time-migrations` 再导出(不进主桶)。
+ * 单拆出来只为一件事:调度店的读口(`./scheduler-store`,轻、浏览器安全)要在告警里带收据,不该为一个型把整套域 schema 拉进来。
+ */
+import type { DomainName, RetiredDomainName } from "./types.js";
+/** 本版登记的一次性**数据**迁移 id(闭集;每个 id 在 `ONE_TIME_MIGRATIONS` 登记表里恰一行)。收据只许这些 id —— 同表登记的 wire 删码位
+ *  (`WIRE_RETIREMENT_IDS`,`./one-time-migrations`)不改任何存储形,铸不出收据,不在本集。 */
+export declare const ONE_TIME_MIGRATION_IDS: readonly ["SS-M1", "SS-M2", "SS-M3", "SS-M4", "SS-M5", "SS-M6", "SS-M7", "SS-M9"];
+export type OneTimeMigrationId = (typeof ONE_TIME_MIGRATION_IDS)[number];
+/**
+ * 一条收据说迁移**对一个坐标做了什么**(闭集,每词一义):
+ *  - `moved`            — 值搬到新位(`to`),义不变;
+ *  - `rewritten`        — 同一坐标上的值换成今天的生效读法(例:URL 剥掉从不上线的 fragment、调度行的 durable 键重铸、6.x 的 worker 行换新形);
+ *  - `dropped-shadowed` — 删掉;它从来没生效过,因为另一个位赢了(例:`governance` 已设时 `runtime` 上的治理旧键、`sealedApiKey` 在场时的 `apiKeyEnv`);
+ *  - `dropped-inert`    — 删掉;今天的读法本就不让它生效(例:超界的主机条目、引擎从不读的旧字段、空的retired 域文档);
+ *  - `refused`          — 不改:要改就得替运维猜(或旧文档今天本就读不进);原样留着,读侧照旧响亮拒,`reason` 说为什么。
+ */
+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";
+/** 文档里的段坐标(字符串段 = 对象键,数字段 = 数组下标;与告警坐标同一形)。 */
+export type MigrationPath = readonly (string | number)[];
+interface ReceiptBase {
+    readonly migration: OneTimeMigrationId;
+    readonly document: MigrationDocument;
+    readonly path: MigrationPath;
+}
+/** 一条迁移收据。只点名坐标与处置,**不带值**(值可能是粘错位置的凭据)。 */
+export type MigrationReceipt = (ReceiptBase & {
+    readonly appliedAs: "moved";
+    readonly to: {
+        readonly document: MigrationDocument;
+        readonly path: MigrationPath;
+    };
+}) | (ReceiptBase & {
+    readonly appliedAs: "rewritten" | "dropped-shadowed" | "dropped-inert";
+}) | (ReceiptBase & {
+    readonly appliedAs: "refused";
+    readonly reason: string;
+});
+export {};

package/dist/migration-receipt.js

@@ -0,0 +1,12 @@
+/** 本版登记的一次性**数据**迁移 id(闭集;每个 id 在 `ONE_TIME_MIGRATIONS` 登记表里恰一行)。收据只许这些 id —— 同表登记的 wire 删码位
+ *  (`WIRE_RETIREMENT_IDS`,`./one-time-migrations`)不改任何存储形,铸不出收据,不在本集。 */
+export const ONE_TIME_MIGRATION_IDS = ["SS-M1", "SS-M2", "SS-M3", "SS-M4", "SS-M5", "SS-M6", "SS-M7", "SS-M9"];
+/**
+ * 一条收据说迁移**对一个坐标做了什么**(闭集,每词一义):
+ *  - `moved`            — 值搬到新位(`to`),义不变;
+ *  - `rewritten`        — 同一坐标上的值换成今天的生效读法(例:URL 剥掉从不上线的 fragment、调度行的 durable 键重铸、6.x 的 worker 行换新形);
+ *  - `dropped-shadowed` — 删掉;它从来没生效过,因为另一个位赢了(例:`governance` 已设时 `runtime` 上的治理旧键、`sealedApiKey` 在场时的 `apiKeyEnv`);
+ *  - `dropped-inert`    — 删掉;今天的读法本就不让它生效(例:超界的主机条目、引擎从不读的旧字段、空的retired 域文档);
+ *  - `refused`          — 不改:要改就得替运维猜(或旧文档今天本就读不进);原样留着,读侧照旧响亮拒,`reason` 说为什么。
+ */
+export const MIGRATION_APPLIED_AS = ["moved", "rewritten", "dropped-shadowed", "dropped-inert", "refused"];

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

@@ -0,0 +1,62 @@
+import type { MigrationReceipt, OneTimeMigrationId } from "./migration-receipt.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";
+/** wire 删码位的 id(闭集;`W` = wire):没有存储形要改写、没有收据,与数据迁移同表登记只为让「什么时候删、删什么、删后谁接住」只写一处。 */
+export declare const WIRE_RETIREMENT_IDS: readonly ["SS-W1"];
+export type WireRetirementId = (typeof WIRE_RETIREMENT_IDS)[number];
+/** 一条一次性迁移的窗(登记表的一行;纯数据)。 */
+export interface OneTimeMigrationWindow {
+    /** 数据迁移 id(闭集 `ONE_TIME_MIGRATION_IDS`)或 wire 删码位 id(闭集 {@link WIRE_RETIREMENT_IDS});两集合起来每个 id 恰一行。 */
+    readonly id: OneTimeMigrationId | WireRetirementId;
+    /** 旧形在读侧的待遇(闭集,每词一义;「读写两面遇旧形一律响亮拒,拒句点名迁移 id」这条律的例外只在这一格里写):
+     *   · `refused`           — 读写两面拒,拒句点名本行 id(经 `migrationSignpost` 铸;钉:每个 `refused` 行的 id 在 `src/` 至少一处铸点,
+     *                           且非 `refused` 行零铸点);
+     *   · `rewritten-on-read` — 读时改写、不拒(SS-M3:调度店的下一个写者落盘),没有拒句可点名;
+     *   · `not-stored`        — 没有存储形(wire 删码位),谈不上拒。 */
+    readonly oldForm: "refused" | "rewritten-on-read" | "not-stored";
+    /** 引入这条迁移的版本。 */
+    readonly introducedIn: string;
+    /** 该版本在 npm 上的发布日(UTC 日历日 YYYY-MM-DD)。`null` = 未发布形,由抬 `package.json` 到 `introducedIn` 的发布准备提交回填。 */
+    readonly releasedOn: string | null;
+    /** = `releasedOn` + 30 天(UTC 日历日);与 `releasedOn` 同为 `null` 或同为日期。今天晚于它 ⇒ 到期门红。 */
+    readonly removableAfter: string | null;
+    /** 迁什么:旧形 → 新形(= 迁移前读路径上的生效读法)。 */
+    readonly rewrites: string;
+    /** 删码时删什么(到期门的红句逐字引用)。 */
+    readonly removal: string;
+    /** 删码之后,存量若还带着迁移前的形,由哪一条**既有**响亮臂接住;没有就如实写没有。 */
+    readonly afterRemoval: string;
+}
+/** 一次性迁移登记表 —— 本族各条窗的**唯一属主**。别处只写「窗见 `ONE_TIME_MIGRATIONS` 登记表」。 */
+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>>>;
+export interface StoredDocumentsMigration {
+    /** 迁移后的文档集:没改的文档是**同一引用**;被移除的(retired 域)不在;新建的(例:迁出的 `governance` / `limits`)在。 */
+    readonly docs: Readonly<Record<string, unknown>>;
+    /** 逐条收据(步序 SS-M1 → SS-M2 → SS-M5 → SS-M6 → SS-M9 → SS-M7 → SS-M4:纯改写步在前,用新 schema 终判的 SS-M4 最后;步内按坐标)。
+     *  只有 `refused` 的收据 = 什么都没改。 */
+    readonly receipts: readonly MigrationReceipt[];
+}
+/**
+ * 迁移一组存储文档(见文件头「入口」)。纯函数;没改的文档原样返回;**不抬任何版本号**(结果里没有版本 —— 那是调用方的)。
+ * 重跑恒等:第二次跑零改动,只剩第一次就 `refused` 的那几张收据(那些坐标原样留着,读侧照旧拒)。
+ */
+export declare function migrateStoredDocuments(docs: StoredDocuments, opts: {
+    readonly coverage: DocumentCoverage;
+}): StoredDocumentsMigration;
+/**
+ * 迁移一份冻结的 effective(见文件头「入口」):域键过与 {@link migrateStoredDocuments} 同一组步(coverage `"scope"` —— effective 里每个域
+ * 都物化了),其余键(`version` / `updatedAt` / wire 上的 `skills` 清单形 …)原样。键序保持;被移除的retired 域不在;effective 没改 ⇒ 同一引用。
+ * 不是对象 ⇒ 原样返回(判形是读者的事)。
+ */
+export declare function migrateEffectiveSnapshot(effective: unknown): {
+    readonly effective: unknown;
+    readonly receipts: readonly MigrationReceipt[];
+};
+/** 本包域 schema 里全部 URL 座位的坐标模式(派生;数组 / Record 位写 `*`)—— 迁移不用它,它给钉与说明看「今天派生出哪些座位」。 */
+export declare function urlSeatPatterns(): string[];