@sema-agent/settings-schema 11.2.0 → 11.3.0

package/dist/types.js

@@ -30,6 +30,9 @@ import { Sha256Digest } from "./sha256.js"; // the one `sha256:<hex>` digest for
 import { EXECUTION_LANES, EXECUTION_LANE_WORDS, MEMORY_ENGINE_BACKENDS, SESSION_BACKENDS, STORE_BACKENDS, retiredLaneWordRefusal } from "./execution-lanes.js"; // 7.0.0 M-R2: the lane / store vocabulary (one exported table)
 import { LANE_ENV_OWNER, isMigratableEnvKey, laneEnvSeat, laneRowOf } from "./execution-lane-index.js"; // package-private indexes derived from that table (not in the barrel)
 import { migrationSignpost, retiredFormSentence, retiredKey } from "./retired-form.js"; // 11.0.0: the ONE retired-form sentence + key tombstone (package-private)
+import { buildQuotedIssue, fixed } from "./quoted-issue.js"; // THE minting point of custom issues (package-private)
+import { AbsoluteHostPath } from "./host-path.js"; // the one host-path shape judge (a task's cwd and a project's folder / file entries)
+import { RFC3339_DATE_TIME } from "./rfc3339.js"; // the package's one RFC 3339 date-time judge (package-private)
 // COARSE, best-effort literal-secret SHAPE detector (NOT exhaustive — the real boundary is the env-NAME schema
 // on structured fields). Rejected in free-form value fields (worker `env`, model `extraBody`), URL components,
 // AND as an env-NAME value (an AWS key id is a valid env-NAME charset yet is a secret VALUE, not a NAME). Case-
@@ -56,7 +59,7 @@ export const ENV_NAME = z
     // lowercase — the charset above rejects them). The ONE secret shape that IS a valid all-caps env-NAME charset
     // is an AWS access-key id (AKIA…) — block exactly that, WITHOUT false-rejecting legit names like
     // GITHUB_PAT_TOKEN / GHU_TOKEN (which the full SECRET_LITERAL_RE would). Round-5.
-    .refine((s) => !/^AKIA[0-9A-Z]{12,}$/.test(s), "looks like an AWS access-key id, not an env-NAME — put the NAME of the env var here (the value lives in .env)");
+    .refine((s) => !/^AKIA[0-9A-Z]{12,}$/.test(s), buildQuotedIssue `looks like an AWS access-key id, not an env-NAME — put the NAME of the env var here (the value lives in .env)`);
 function scanForSecret(s) {
     // A private-key PEM header ANYWHERE in the string (the one regex the display redactor reads too). The header carries spaces, so
     // neither the start-anchored SECRET_LITERAL_RE below nor the tokenizer at the bottom can see it behind a prefix / newline. 10.0.0.
@@ -94,30 +97,11 @@ function scanForSecret(s) {
  *  fs path — so the worker dies at exec/boot, not at config edit. A NUL is never legitimate in a command / path
  *  / host / image, so reject it on every exec-bound string field (mcp stdio + the whole remoteExec contract). R20. */
 export const hasNul = (s) => s.includes("\0");
-/** 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}`), "");
-}
-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 ONE minting point of quoted
- *  sentences in this file — a template literal written straight into `message` would put a value into a sentence with no record
- *  of where it is (a source gate pins that none is left). */
-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 };
-}
+/** The params of a custom issue's sentence and their one rendering live in the package-private minting module `./quoted-issue`
+ *  (one minting point for the whole package); re-exported here unchanged. */
+export { renderQuotedSentence } from "./quoted-issue.js";
+/** The one host-path shape judge (a task's `cwd`, a project's `folder` / `file` entries) lives in its leaf module `./host-path`. */
+export { ABSOLUTE_HOST_PATH_MAX, AbsoluteHostPath, isAbsoluteHostPath } from "./host-path.js";
 /** Does `s` contain a secret-shaped token? —— **the one scanner** (11.0.0, S-1274): the write side (this detector, behind every
  *  free-text write port — NON_SECRET_URL, mcp stdio, execution coords, ssh login, worker env, extraBody, …) and the display side
  *  (`redactSecrets`) read the SAME normalized forms ({@link secretScanForms} in the package-private `./secret-scan`: the raw string,
@@ -169,49 +153,52 @@ export function urlQueryFragmentHasSecret(u) {
  *  after it is dropped with it — the engine and server refuse a model route root that carries one, so a stored one only fails
  *  later, on the worker). A query is a legitimate request parameter (`?api-version=…`) and stays. */
 const NON_SECRET_URL_FORBIDS = ["userinfo", "fragment"];
-/** The refusal sentence of one flaw at a {@link NON_SECRET_URL} seat: the judge's rule sentence, and — for the one flaw that stored data
- *  can carry from before 11.0.0 (a fragment) at a seat the one-time migration reaches — the signpost to the migration that strips
- *  it, joined the way the other signposted refusals join it (`<rule>; <signpost>`). Closed over the judge's flaw words: a new word is
- *  a compile error here. */
-function nonSecretUrlSentence(flaw, reachedByMigration) {
+/** The refusal of one flaw at a {@link NON_SECRET_URL} seat (a {@link QuotedIssue} with no operands — the sentence quotes no value): the
+ *  judge's rule sentence, and — for the one flaw that stored data can carry from before 11.0.0 (a fragment) at a seat the one-time migration
+ *  reaches — the signpost to the migration that strips it, joined the way the other signposted refusals join it (`<rule>; <signpost>`).
+ *  Closed over the judge's flaw words: a new word is a compile error here. */
+function nonSecretUrlIssue(flaw, reachedByMigration) {
     switch (flaw) {
         case "fragment":
-            return reachedByMigration ? `${httpUrlRule(flaw)}; ${migrationSignpost("SS-M7", "11.0.0")}` : httpUrlRule(flaw);
+            return reachedByMigration ? buildQuotedIssue `${fixed(httpUrlRule(flaw))}; ${fixed(migrationSignpost("SS-M7", "11.0.0"))}` : buildQuotedIssue `${fixed(httpUrlRule(flaw))}`;
         case "not-http-url":
         case "userinfo":
         case "query":
-            return httpUrlRule(flaw);
+            return buildQuotedIssue `${fixed(httpUrlRule(flaw))}`;
         default: {
             const unhandled = flaw;
-            throw new Error("nonSecretUrlSentence: unhandled flaw word", { cause: unhandled });
+            throw new Error("nonSecretUrlIssue: unhandled flaw word", { cause: unhandled });
         }
     }
 }
 /** One judge, two seat kinds — the only difference is the fragment refusal's migration signpost. `reachedByMigration` = the seat sits in a
- *  stored domain document, which the one-time migration SS-M7 rewrites (it finds its seats by this schema's identity, so "carries the
+ *  stored document the one-time migration SS-M7 rewrites (it finds its seats by this schema's identity, so "carries the
  *  signpost" and "is rewritten by SS-M7" cannot drift apart). */
 function createNonSecretUrl(reachedByMigration) {
     return z.string().superRefine((s, ctx) => {
         const flaws = httpUrlFlaws(s, NON_SECRET_URL_FORBIDS);
-        for (const flaw of flaws)
-            ctx.addIssue({ code: "custom", message: nonSecretUrlSentence(flaw, reachedByMigration), params: { flaw } });
+        for (const flaw of flaws) {
+            const refusal = nonSecretUrlIssue(flaw, reachedByMigration);
+            ctx.addIssue({ code: "custom", ...refusal, params: { ...refusal.params, flaw } }); // `flaw` = the judge's rule word, beside the sentence's params
+        }
         if (flaws.length === 0 && urlQueryFragmentHasSecret(new URL(s))) {
-            ctx.addIssue({ code: "custom", message: "must not carry a secret-shaped value in its path or query — secrets go in the *Env (env-NAME) fields" });
+            ctx.addIssue({ code: "custom", ...buildQuotedIssue `must not carry a secret-shaped value in its path or query — secrets go in the *Env (env-NAME) fields` });
         }
     });
 }
 /** A URL handed to `fetch` that carries no credential: judged by THE URL shape judge ({@link httpUrlFlaws}, `./url-shape`) — a
  *  hierarchical http(s) URL with neither userinfo nor a fragment (an empty `#` included, 11.0.0) — and with no secret-shaped value
  *  in its path or query ({@link urlQueryFragmentHasSecret}). One issue per flaw, its message the judge's rule sentence (no value
- *  echoed; a fragment's also names its migration, {@link nonSecretUrlSentence}); `params.flaw` carries the rule word.
+ *  echoed; a fragment's also names its migration, {@link nonSecretUrlIssue}); `params` carries the sentence (`template` / `operands`,
+ *  no operands) and `flaw`, the rule word.
  *
- *  This is the seat of every URL in a stored DOMAIN document (models `baseUrl`, mcp `url`, `sessionMirror.engineUrl`, workers
- *  `gitApiBaseUrl`). A URL outside the domain documents — `remote-exec.json`'s endpoints, the web-admin credential envelope's
- *  `issuer` — uses {@link NON_SECRET_URL_NO_MIGRATION}.
+ *  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}.
  *
  *  The value is kept EXACTLY as written: nothing here trims or normalizes it (zod's own `.url()` would hand back a rewritten string). */
 export const NON_SECRET_URL = createNonSecretUrl(true);
-/** {@link NON_SECRET_URL}'s judge for a seat no one-time migration reaches (not a domain document): identical rules and rule
+/** {@link NON_SECRET_URL}'s judge for a seat no one-time migration reaches (not stored data): identical rules and rule
  *  sentences, but a fragment's refusal carries no migration signpost — pointing at a migration that cannot rewrite the value would
  *  send the operator to a command that does nothing for it. */
 export const NON_SECRET_URL_NO_MIGRATION = createNonSecretUrl(false);
@@ -299,19 +286,19 @@ function vetFreeFormJson(v, field) {
         rawUnsafe = extraBodyUnsafe(v);
     }
     catch {
-        return { ok: false, ...buildQuotedIssue `${fixed(field)} could not be validated (reflective access threw)` }; // R11
+        return { ok: false, issue: buildQuotedIssue `${fixed(field)} could not be validated (reflective access threw)` }; // R11
     }
     if (rawUnsafe)
-        return { ok: false, ...buildQuotedIssue `${fixed(field)}: a key/value is a secret shape, non-JSON (Infinity/function/Map), an accessor, cyclic, or too deep` };
+        return { ok: false, issue: buildQuotedIssue `${fixed(field)}: a key/value is a secret shape, non-JSON (Infinity/function/Map), an accessor, cyclic, or too deep` };
     let clone;
     try {
         clone = JSON.parse(JSON.stringify(v)); // the ONLY serialization — its result is what we scan AND persist
     }
     catch {
-        return { ok: false, ...buildQuotedIssue `${fixed(field)} is not JSON-serializable` };
+        return { ok: false, issue: buildQuotedIssue `${fixed(field)} is not JSON-serializable` };
     }
     if (extraBodyUnsafe(clone))
-        return { ok: false, ...buildQuotedIssue `${fixed(field)}: its serialized form carries a secret` };
+        return { ok: false, issue: buildQuotedIssue `${fixed(field)}: its serialized form carries a secret` };
     return { ok: true, value: clone };
 }
 /** The transform of every **parse-transparent free-form** key (`z.unknown().optional().transform(createFreeFormTransform(field))`:
@@ -324,7 +311,7 @@ function createFreeFormTransform(field) {
             return undefined;
         const vetted = vetFreeFormJson(v, field);
         if (!vetted.ok) {
-            ctx.addIssue({ code: "custom", message: vetted.message, params: vetted.params });
+            ctx.addIssue({ code: "custom", ...vetted.issue });
             return z.NEVER;
         }
         return vetted.value;
@@ -504,12 +491,12 @@ export const ModelEntry = z.object({
             return undefined;
         const proto = typeof v === "object" && v !== null ? Object.getPrototypeOf(v) : undefined;
         if (typeof v !== "object" || v === null || Array.isArray(v) || (proto !== Object.prototype && proto !== null)) {
-            ctx.addIssue({ code: "custom", message: "extraBody must be a plain JSON object" });
+            ctx.addIssue({ code: "custom", ...buildQuotedIssue `extraBody must be a plain JSON object` });
             return z.NEVER;
         }
         const vetted = vetFreeFormJson(v, "extraBody");
         if (!vetted.ok) {
-            ctx.addIssue({ code: "custom", message: vetted.message, params: vetted.params });
+            ctx.addIssue({ code: "custom", ...vetted.issue });
             return z.NEVER;
         }
         return vetted.value;
@@ -808,7 +795,7 @@ export const SystemEntry = z.object({
             // worker that isn't provisioned yet has no Secret to label-check, so a name-level reservation is
             // the only thing closing the "squat on a future worker's credential surface" timing hole (S3 设计
             // §4.4, council DESIGN-6/13). Cost: callers can't use a secret that happens to end in -env.
-            .refine((n) => !n.endsWith("-env"), { message: 'secret names ending in "-env" are reserved for orchestrator worker-credential projections (红线1)' }),
+            .refine((n) => !n.endsWith("-env"), buildQuotedIssue `secret names ending in "-env" are reserved for orchestrator worker-credential projections (红线1)`),
         key: z.string().regex(/^[-._a-zA-Z0-9]+$/, "k8s secret data key").max(253),
     })
         .optional(),
@@ -975,13 +962,23 @@ export const LimitsConfig = z.object({
 // The governance trio an operator tunes via publish: autonomy ladder + command guardrails + approval-required
 // tools. NOT下沉 — gets its own admin tab (E5 form; E1 ships a transitional generic editor). Same `.optional()`
 // no-default discipline as the six gates: ABSENT = web-admin 不管这项(keep env / 消费者默认),present 才生效。
+/** The autonomy ladder —— the closed set as a RUNTIME VALUE (same form as `REF_CHECKED_DOMAINS`): {@link AutonomyMode} (the zod enum)
+ *  and its type are DERIVED from this table, so a consumer that needs the words at runtime (an env parser, a catalog's enum column) imports
+ *  it instead of reaching into `GovernanceConfig.shape.autonomy.unwrap().options` or writing the four words again. */
+export const AUTONOMY_MODES = ["read-only", "ask", "plan", "auto"];
+/** `governance.autonomy`'s enum, derived from {@link AUTONOMY_MODES}. */
+export const AutonomyMode = z.enum(AUTONOMY_MODES);
+/** A `commandPolicy[]` rule's decision —— the closed set as a RUNTIME VALUE; {@link CommandDecision} and its type are DERIVED from it. */
+export const COMMAND_DECISIONS = ["allow", "ask", "deny"];
+/** `commandPolicy[].decision`'s enum, derived from {@link COMMAND_DECISIONS}. */
+export const CommandDecision = z.enum(COMMAND_DECISIONS);
 export const GovernanceConfig = z.object({
     // autonomy:一个跨 knob 的安全总开关 / 放权梯度(普通用户敢用 + 专业用户放权)。
     //   read-only(只读规划,不落改)| ask(每个放权动作问)| plan(plan-review 门)| auto(放开)。
     // ⚠️ 消费侧(service)把它**展开**到 core 已有三原语(handsReadOnly / shellGate+onAsk / plan_review),
     //   经 core 的收紧-only `tightenTaskSpec` 合并。core 裁决:不在 core 加并行 autonomy 枚举(双实现陷阱),
     //   不静默覆盖调用者已设安全字段(auto 模式尤其不能静默清门控)。详见 web-admin docs/CONFIG-RESEARCH §10。
-    autonomy: z.enum(["read-only", "ask", "plan", "auto"]).optional(),
+    autonomy: AutonomyMode.optional(),
     // commandPolicy:命令级 allow/ask/deny 护栏(remoteExec 管"在哪跑",这管"能跑什么命令")。每条 = 一个
     //   **精确 argv[0] 命令名** → 决策;**DENY-WINS**(冲突 deny 赢,与 core `combinePolicies` 一致,NOT last-match-wins)。
     // ⚠️ EXACT,不是 glob(service 裁决①,2026-06-22):core 1.114.0 shipped 的 `createCoarseCommandNamePolicy`
@@ -1003,7 +1000,7 @@ export const GovernanceConfig = z.object({
             .min(1)
             .max(128)
             .regex(/^[A-Za-z0-9._+-]+$/, "exact argv[0] command NAME — letters/digits/._+- only; NO glob (*,?), path (/), spaces or shell fragments — e.g. rm, git, docker-compose"),
-        decision: z.enum(["allow", "ask", "deny"]),
+        decision: CommandDecision,
     }))
         .optional(),
     /** Tool names needing operator approval (F4). ABSENT = web-admin 不管;显式 `[]` = 一个都不需要审批。 */
@@ -1183,7 +1180,7 @@ export const EntitlementTier = z.object({
     /** 🔴 B1 违宪修复(EXPERT-REDESIGN §4-1):tokenQuota **不挂 tier** —— 只挂 defaults/subject/groupBinding。
      *  fail-loud 而非 zod 默认的静默剥除(admin 挂上去以为生效才是最糟的)。 */
     tokenQuota: z
-        .custom(() => false, { message: "tokenQuota does not mount on a tier — mount it on defaults / subjects[] / groupBindings[] (拍板:配额挂用户/组,非访问级别)" })
+        .custom(() => false, buildQuotedIssue `tokenQuota does not mount on a tier — mount it on defaults / subjects[] / groupBindings[] (拍板:配额挂用户/组,非访问级别)`)
         .optional(),
 });
 /** A time-bounded, audited per-principal override (escape hatch above the tier/role defaults). */
@@ -1205,7 +1202,7 @@ export const EntitlementOverride = z
     // by env-NAME, never inline. (Budget overrides are numbers/enums, so this never fires on the v1 use.)
     const s = typeof o.value === "string" ? o.value : o.value == null ? "" : JSON.stringify(o.value);
     if (s && containsSecretToken(s))
-        ctx.addIssue({ code: "custom", message: "override.value appears to contain a secret token — overrides are persisted + audited; reference secrets by env-NAME, never inline a value", path: ["value"] });
+        ctx.addIssue({ code: "custom", ...buildQuotedIssue `override.value appears to contain a secret token — overrides are persisted + audited; reference secrets by env-NAME, never inline a value`, path: ["value"] });
 });
 export const EntitlementSubject = z.object({
     principal: z.string().min(1),
@@ -1368,7 +1365,7 @@ export const SESSION_MIRROR_ENGINE_URL = z.string().trim().pipe(NON_SECRET_URL).
     catch {
         return true; // already passed NON_SECRET_URL; unreachable in practice
     }
-}, "non-loopback sessionMirror.engineUrl must be https — the mirror carries session content + a Bearer credential; plain http across the network is rejected at WRITE time (shell evaluateEngineRouting 同款传输闸)");
+}, buildQuotedIssue `non-loopback sessionMirror.engineUrl must be https — the mirror carries session content + a Bearer credential; plain http across the network is rejected at WRITE time (shell evaluateEngineRouting 同款传输闸)`);
 /** Org 默认会话镜像目标(WEB-SETUP-RECON 附B,产品拍板两层,0.10.1)。**收编进 execution 域**(非独立
  *  域)——142-S3 草案同款尺量:①同一治理轴(org 对「会话数据必须落到受控引擎」的 scope 级管控,与
  *  「任务必须跑在受控 lane」同族;`required` 语义与 {@link ExecutionPolicy}.required 完全同构=壳锁定、
@@ -1453,41 +1450,72 @@ export const ExecutionPolicy = z.object({
  *  flags:本常量刻意**不带** `i`,因为它是登记簿 Record 的**键**,大小写不同的同一个 UUID 会变成两条登记行
  *  (同一 project 双注册);引擎侧是识别语义(读 marker / 找回身份),放宽合理。 */
 export const PROJECT_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** The bounds of a project registration's free-form fields —— the ONE source of these numbers: the schema below reads them, and so do
+ *  the server's project routes and the admin / client forms (they import this, never copy a number). The path bound of `folder` / `file`
+ *  entries is the host-path judge's own ({@link ABSOLUTE_HOST_PATH_MAX}). */
+export const PROJECT_LIMITS = {
+    displayNameMax: 200,
+    goalMax: 2000,
+    contextItemsMax: 64,
+    noteMax: 4000,
+};
+/** A project context item's kind —— the closed set as a RUNTIME VALUE: `folder` / `file` = a host path (judged by the same
+ *  {@link isAbsoluteHostPath} as a task's `cwd`), `note` = free text. */
+export const PROJECT_CONTEXT_ITEM_KINDS = ["folder", "file", "note"];
+/** A project's icon: a token (lowercase letter first, then lowercase letters / digits / `-`, at most 64). Absent = the default icon. */
+export const PROJECT_ICON_REGEX = /^[a-z][a-z0-9-]{0,63}$/;
+/** A project's colour: `#` + six lowercase hex digits. Absent = the default colour. */
+export const PROJECT_COLOR_REGEX = /^#[0-9a-f]{6}$/;
+/** One context item of a project. */
+export const ProjectContextItem = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("folder"), value: AbsoluteHostPath }),
+    z.object({ kind: z.literal("file"), value: AbsoluteHostPath }),
+    z.object({ kind: z.literal("note"), value: z.string().max(PROJECT_LIMITS.noteMax) }),
+]);
+// 每个字段的 schema 只写一次:登记形({@link ProjectRegistration})与 PATCH 形({@link ProjectRegistrationPatch})都由它们组成。
+const ProjectDisplayName = z.string().min(1).max(PROJECT_LIMITS.displayNameMax);
+/** 归一化 git remotes(`host/path` 形态,design/142 §1.1 归一化规范)。归一化动作发生在 scaffold/调用方,本契约只验底线形状:非空、无空白、
+ *  不含 "://"(出现即证据未归一化,fail-loud)。无仓 project = 空数组合法。`.max(16)` 防登记簿被单条撑爆。 */
+const ProjectGitRemotes = z
+    .array(z
+    .string()
+    .min(1)
+    .max(512)
+    .refine((s) => !/\s/.test(s) && !s.includes("://"), buildQuotedIssue `must be a NORMALIZED remote (host/path — no scheme, no whitespace)`))
+    .max(16);
+/** 该项目会话的默认记忆 scope 词表。OPEN value domain — z.string(),不 enum(纪律:加词不得 BREAKING)。方向(S4 细化):消费方=service
+ *  memoryScope 派生(作 TaskSpec.memory.scopes 种子),形态=v2 scope 键字符串(过 core parseScopeKey 校验;known 词根:`proj` / `userproj`)。
+ *  未知串=消费者自定义;空数组=不下发默认。本域只登记不解释,零耦合。 */
+const ProjectDefaultScopes = z.array(z.string().min(1));
+const ProjectGoal = z.string().max(PROJECT_LIMITS.goalMax);
+const ProjectContextItems = z.array(ProjectContextItem).max(PROJECT_LIMITS.contextItemsMax);
+const ProjectIcon = z.string().regex(PROJECT_ICON_REGEX, "an icon is a token: a lowercase letter, then lowercase letters / digits / -, at most 64");
+const ProjectColor = z.string().regex(PROJECT_COLOR_REGEX, "a colour is # followed by six lowercase hex digits");
 export const ProjectRegistration = z.object({
-    /** 人读名(展示/管理面用;不是身份,改名自由——身份=Record 键 projectId)。 */
-    displayName: z.string().min(1).max(120),
-    /** 归一化 git remotes(`host/path` 形态,design/142 §1.1 归一化规范)。归一化动作发生在 scaffold/
-     *  调用方,本契约只验底线形状:非空、无空白、不含 "://"(出现即证据未归一化,fail-loud)。
-     *  无仓 project = 空数组合法。`.max(16)` 防登记簿被单条撑爆。 */
-    gitRemotes: z
-        .array(z
-        .string()
-        .min(1)
-        .max(512)
-        .refine((s) => !/\s/.test(s) && !s.includes("://"), "must be a NORMALIZED remote (host/path — no scheme, no whitespace)"))
-        .max(16)
-        .prefault([]),
-    /** 该项目会话的默认记忆 scope 词表。OPEN value domain — z.string(),不 enum(纪律:加词
-     *  不得 BREAKING)。方向(S4 细化):消费方=service memoryScope 派生(作 TaskSpec.
-     *  memory.scopes 种子),形态=v2 scope 键字符串(过 core parseScopeKey 校验;known 词根:`proj` /
-     *  `userproj`)。未知串=消费者自定义;空数组=不下发默认。本域只登记不解释,零耦合。 */
-    defaultScopes: z.array(z.string().min(1)).prefault([]),
-    /** 登记人 principal(审计锚;web-admin 写面自动填 caller,不信客户端提交)。 */
+    /** 人读名(展示/管理面用;不是身份,改名自由——身份=Record 键 projectId)。上界 {@link PROJECT_LIMITS}`.displayNameMax`(200;此前 120)。 */
+    displayName: ProjectDisplayName,
+    gitRemotes: ProjectGitRemotes.prefault([]),
+    defaultScopes: ProjectDefaultScopes.prefault([]),
+    /** 登记人 principal(审计锚;web-admin 写面自动填 caller,不信客户端提交)。PATCH 改不了它。 */
     registeredBy: z.string().min(1),
-    /** 登记时刻(ISO)。web-admin 写面 server 端盖章。 */
+    /** 登记时刻(ISO)。web-admin 写面 server 端盖章。PATCH 改不了它。 */
     registeredAt: z.string().min(1),
+    /** 自由备注(与 `goal` 不是一件事)。 */
     notes: z.string().optional(),
-});
-export const ProjectsConfig = z
-    .object({
-    /** 键=projectId({@link PROJECT_ID_REGEX},generic lowercase UUID——宽读);tenant 半边=web-admin
-     *  scope 轴(不进域文档,见域头注)。 */
-    projects: z.record(z.string().regex(PROJECT_ID_REGEX, "projectId must be a lowercase canonical UUID"), ProjectRegistration).prefault({}),
-})
-    .superRefine((cfg, ctx) => {
-    // 同 scope 内一条 remote 只许属于一个 project——「remote → projectId」找回阶梯(design/142
-    // §1.5 ③)与 scaffold 防重铸查询要求该映射在租户内确定;撞了=写入 fail-loud(合法双登记诉求
-    // 出现时再放开,先紧后松 additive)。
+    /** 项目目标(≤ {@link PROJECT_LIMITS}`.goalMax`)。 */
+    goal: ProjectGoal.optional(),
+    /** 项目上下文条目(≤ {@link PROJECT_LIMITS}`.contextItemsMax` 条,见 {@link ProjectContextItem})。 */
+    contextItems: ProjectContextItems.optional(),
+    /** 归档时刻(RFC 3339)。在场 = 已归档;没有硬删(会话行引用项目)。 */
+    archivedAt: RFC3339_DATE_TIME.optional(),
+    /** 图标 token({@link PROJECT_ICON_REGEX})。 */
+    icon: ProjectIcon.optional(),
+    /** 颜色({@link PROJECT_COLOR_REGEX})。 */
+    color: ProjectColor.optional(),
+});
+/** 同 scope 内一条 remote 只许属于一个 project——「remote → projectId」找回阶梯(design/142 §1.5 ③)与 scaffold 防重铸查询要求该映射在
+ *  租户内确定;撞了=写入 fail-loud(合法双登记诉求出现时再放开,先紧后松 additive)。按文档键序走:后出现的那一条被拒、句子点名先占的项目。 */
+function remoteUniquenessIssues(cfg, ctx) {
     const seen = new Map();
     for (const [pid, reg] of Object.entries(cfg.projects)) {
         for (const [i, r] of reg.gitRemotes.entries()) {
@@ -1498,7 +1526,66 @@ export const ProjectsConfig = z
             seen.set(r, pid);
         }
     }
-});
+}
+export const ProjectsConfig = z
+    .object({
+    /** 键=projectId({@link PROJECT_ID_REGEX},generic lowercase UUID——宽读);tenant 半边=web-admin
+     *  scope 轴(不进域文档,见域头注)。 */
+    projects: z.record(z.string().regex(PROJECT_ID_REGEX, "projectId must be a lowercase canonical UUID"), ProjectRegistration).prefault({}),
+})
+    .superRefine(remoteUniquenessIssues);
+/** The PATCH form of one registration: every key a PATCH may change, all optional; `registeredBy` / `registeredAt` (and any key
+ *  the registration does not have) are refused (`.strict()`). An optional key given `null` is cleared (merge-patch: `archivedAt: null`
+ *  un-archives). Each field is the registration's own schema — one bound, one shape. */
+export const ProjectRegistrationPatch = z
+    .object({
+    displayName: ProjectDisplayName.optional(),
+    gitRemotes: ProjectGitRemotes.optional(),
+    defaultScopes: ProjectDefaultScopes.optional(),
+    notes: z.string().nullable().optional(),
+    goal: ProjectGoal.nullable().optional(),
+    contextItems: ProjectContextItems.nullable().optional(),
+    archivedAt: RFC3339_DATE_TIME.nullable().optional(),
+    icon: ProjectIcon.nullable().optional(),
+    color: ProjectColor.nullable().optional(),
+})
+    .strict();
+/**
+ * Apply a PATCH to one registration and judge the whole document with **the same** {@link ProjectsConfig} (the same remote-uniqueness rule a
+ * full write meets — a PATCH has no rule of its own). The patch is judged here by {@link ProjectRegistrationPatch} first — whatever the caller
+ * did before (a request body handed over as is cannot rewrite `registeredBy` / `registeredAt` or carry an unknown key) — and only its parsed
+ * keys are merged. The patched project is judged LAST, so a remote another project already holds is refused on the patched project and the
+ * sentence names the holder, whatever the document's key order; a successful result keeps the document's key order. Every issue path is a
+ * document coordinate (`["projects", <projectId>, …]`), the patch's own included. `projectId` must be registered (the caller answers "no such
+ * project" first) —— otherwise this throws.
+ */
+export function applyProjectPatch(doc, projectId, patch) {
+    const current = Object.prototype.hasOwnProperty.call(doc.projects, projectId) ? doc.projects[projectId] : undefined;
+    if (current === undefined)
+        throw new Error(`applyProjectPatch: project "${projectId}" is not registered in this document`);
+    const parsed = ProjectRegistrationPatch.safeParse(patch);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => ({ ...i, path: ["projects", projectId, ...i.path] }));
+        return { success: false, error: new z.ZodError(issues) };
+    }
+    const next = { ...current };
+    for (const [k, v] of Object.entries(parsed.data)) {
+        if (v === undefined)
+            continue;
+        if (v === null)
+            delete next[k];
+        else
+            next[k] = v;
+    }
+    const { [projectId]: _patched, ...others } = doc.projects;
+    const judged = ProjectsConfig.safeParse({ ...doc, projects: { ...others, [projectId]: next } });
+    if (!judged.success)
+        return judged;
+    const ordered = {};
+    for (const pid of Object.keys(doc.projects))
+        ordered[pid] = judged.data.projects[pid];
+    return { ...judged, data: { ...judged.data, projects: ordered } };
+}
 // ── Domain: collab (协作模式 — multi-model collaboration templates, 0.7.0) ─────
 // Replaces the deleted `teams` domain (EXPERT-REDESIGN §8/§9, 五拍裁定 T1-T5).
 // Unified shape = slots × topology × rounds × finalizer. COMPLETELY separate from rosters (拍板): a slot
@@ -1571,7 +1658,7 @@ const CollabTemplate = z.object({
     });
     if (t.finalizer.type === "none") {
         if (t.finalizer.slot !== undefined)
-            ctx.addIssue({ code: "custom", message: `finalizer type "none" must not anchor a slot`, path: ["finalizer", "slot"] });
+            ctx.addIssue({ code: "custom", ...buildQuotedIssue `finalizer type "none" must not anchor a slot`, path: ["finalizer", "slot"] });
     }
     else if (t.finalizer.slot !== undefined && !slotIds.has(t.finalizer.slot)) {
         ctx.addIssue({ code: "custom", ...buildQuotedIssue `finalizer.slot "${t.finalizer.slot}" is not a slot id of this template`, path: ["finalizer", "slot"] });
@@ -1735,7 +1822,7 @@ const nonSecretLiteral = (minLength) => z
     .string()
     .min(minLength)
     .max(2048)
-    .refine((s) => !containsSecretToken(s), "looks like a literal secret — a credential goes in a secretRefs field as an env-NAME, never a value here");
+    .refine((s) => !containsSecretToken(s), buildQuotedIssue `looks like a literal secret — a credential goes in a secretRefs field as an env-NAME, never a value here`);
 /**
  * `runtime.execution` —— 这台 worker 的执行车道(渲染:`REMOTE_EXEC=<lane>` + `REQUIRE_EXECUTION_LANE=true` + coords / secretRefs 逐键)。
  *  - `lane`:{@link EXECUTION_LANE_WORDS} 之一。没有「无手」词。
@@ -1856,7 +1943,7 @@ const WorkerSpecObject = z.object({
         /** Target average CPU utilization %, vs resources.requests.cpu. Absent → backend default 80. */
         targetCpuPercent: INTEGER.min(10).max(95).optional(),
     })
-        .refine((a) => a.maxReplicas >= a.minReplicas, { message: "maxReplicas must be >= minReplicas" })
+        .refine((a) => a.maxReplicas >= a.minReplicas, buildQuotedIssue `maxReplicas must be >= minReplicas`)
         .optional(),
     /** Per-worker resource requests/limits (k8s backend). Optional → the backend's modest default
      *  (requests cpu 50m/mem 128Mi, no limits). Hash-INCLUDED → a change rolls the pods (resources are
@@ -2090,7 +2177,7 @@ export const WorkersConfig = z
         // replicas + autoscaling = two owners of the same knob (the orchestrator's SSA vs the HPA controller
         // would endlessly fight over spec.replicas) → reject at save, not at reconcile.
         if (w.replicas !== undefined && w.autoscaling) {
-            ctx.addIssue({ code: "custom", message: "replicas and autoscaling are mutually exclusive — the HPA owns the replica count when autoscaling is set", path: ["workers", i, "autoscaling"] });
+            ctx.addIssue({ code: "custom", ...buildQuotedIssue `replicas and autoscaling are mutually exclusive — the HPA owns the replica count when autoscaling is set`, path: ["workers", i, "autoscaling"] });
         }
     });
 });
@@ -2251,7 +2338,7 @@ const McpEnvRefs = z.record(ENV_NAME, ENV_NAME); // target ENV key → ENV_NAME
 const HTTP_HEADER_NAME = z
     .string()
     .regex(/^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/, "must be an HTTP header NAME")
-    .refine((s) => !containsSecretToken(s), "HTTP header name must not contain a secret literal — credentials go in the env-NAME value, never the header name");
+    .refine((s) => !containsSecretToken(s), buildQuotedIssue `HTTP header name must not contain a secret literal — credentials go in the env-NAME value, never the header name`);
 // Header NAME → ENV_NAME holding its value. Header names are tokens (RFC 7230) — not env-name-shaped.
 const McpHeaderRefs = z.record(HTTP_HEADER_NAME, ENV_NAME);
 export const McpTransport = z.discriminatedUnion("kind", [
@@ -2264,13 +2351,13 @@ export const McpTransport = z.discriminatedUnion("kind", [
         command: z
             .string()
             .min(1)
-            .refine((s) => !containsSecretToken(s), "mcp stdio command must not contain a secret literal — put credentials in envRefs (an env-NAME)")
-            .refine((s) => !hasNul(s), "mcp stdio command must not contain a NUL byte (Node cannot spawn it)"),
+            .refine((s) => !containsSecretToken(s), buildQuotedIssue `mcp stdio command must not contain a secret literal — put credentials in envRefs (an env-NAME)`)
+            .refine((s) => !hasNul(s), buildQuotedIssue `mcp stdio command must not contain a NUL byte (Node cannot spawn it)`),
         args: z
             .array(z
             .string()
-            .refine((s) => !containsSecretToken(s), "mcp stdio arg must not contain a secret literal — put credentials in envRefs (an env-NAME)")
-            .refine((s) => !hasNul(s), "mcp stdio arg must not contain a NUL byte (Node cannot spawn it)"))
+            .refine((s) => !containsSecretToken(s), buildQuotedIssue `mcp stdio arg must not contain a secret literal — put credentials in envRefs (an env-NAME)`)
+            .refine((s) => !hasNul(s), buildQuotedIssue `mcp stdio arg must not contain a NUL byte (Node cannot spawn it)`))
             .optional(),
         /** target ENV key → ENV_NAME in the service env (never a secret value). */
         envRefs: McpEnvRefs.optional(),
@@ -2374,18 +2461,18 @@ export const McpConfig = z
 export const PLUGIN_ORIGIN = z
     .string()
     .min(1)
-    .refine((s) => !containsSecretToken(s), "plugin source must not contain a secret literal — private remotes authenticate via the consuming machine's git credentials, never an inline token")
-    .refine((s) => !hasNul(s), "plugin source must not contain a NUL byte")
+    .refine((s) => !containsSecretToken(s), buildQuotedIssue `plugin source must not contain a secret literal — private remotes authenticate via the consuming machine's git credentials, never an inline token`)
+    .refine((s) => !hasNul(s), buildQuotedIssue `plugin source must not contain a NUL byte`)
     .superRefine((s, ctx) => {
     // The shape is THE URL judge's ({@link httpUrlFlaws}); this seat adds two rules of its own: https only, and spelled in full
     // (`https://…` as written — git reads the raw string, and WHATWG's repair of `https:host/x` into `https://host/x` is not git's).
     const flaws = httpUrlFlaws(s, ["userinfo"]);
     if (flaws.includes("not-http-url") || new URL(s).protocol !== "https:" || s.slice(0, 8).toLowerCase() !== "https://") {
-        ctx.addIssue({ code: "custom", message: "plugin source must be an https:// URL (contract: https-only; ssh/scp/git/file/plain-http and owner/repo shorthand are not accepted — domestic mirrors ride an https mirror domain via PLUGINS_ALLOW_HOSTS)" });
+        ctx.addIssue({ code: "custom", ...buildQuotedIssue `plugin source must be an https:// URL (contract: https-only; ssh/scp/git/file/plain-http and owner/repo shorthand are not accepted — domestic mirrors ride an https mirror domain via PLUGINS_ALLOW_HOSTS)` });
         return;
     }
     if (flaws.includes("userinfo") || urlQueryFragmentHasSecret(new URL(s))) {
-        ctx.addIssue({ code: "custom", message: "an https plugin source must not embed credentials (userinfo) or a secret-bearing query/fragment" });
+        ctx.addIssue({ code: "custom", ...buildQuotedIssue `an https plugin source must not embed credentials (userinfo) or a secret-bearing query/fragment` });
     }
 });
 /** A full 40-hex git commit SHA — the ONLY pin form the supply-side treats as 钉死 (a branch/tag `version`
@@ -2434,7 +2521,9 @@ export const PluginsConfig = z
 // 消费投影在 server(声明数组逐字喂 core typed stableBlocks 钩子),schema 恒在本仓(零第二份)。
 /** 提示声明的槽位闭集(core `PromptTextDeclaration.slot` 同形):identity = 角色卡、scenario = 场景说明、behavior = 行为守则。
  *  declaration 轴与 catalog 轴({@link PromptArtifactSection})共用这一只。 */
-export const PromptSlot = z.enum(["identity", "scenario", "behavior"]);
+export const PROMPT_SLOTS = ["identity", "scenario", "behavior"];
+/** The slot enum, DERIVED from {@link PROMPT_SLOTS} (the runtime member table —— same form as `REF_CHECKED_DOMAINS`). */
+export const PromptSlot = z.enum(PROMPT_SLOTS);
 /** core `PromptTextDeclaration` 的契约层同形(core prompts/default.d.ts 逐字:id/slot 闭集/text)。
  *  slot ↔ 三卡:identity=角色卡、scenario=场景说明、behavior=行为守则([1051]①)。 */
 export const PromptTextDeclaration = z.object({
@@ -2465,11 +2554,11 @@ export const PromptBinding = z.object({
     notes: z.string().optional(),
 }).superRefine((b, ctx) => {
     if (b.level === "worker" && !b.worker)
-        ctx.addIssue({ code: "custom", message: "level=worker requires `worker`" });
+        ctx.addIssue({ code: "custom", ...buildQuotedIssue `level=worker requires \`worker\`` });
     if (b.level === "scenario" && !b.scenario)
-        ctx.addIssue({ code: "custom", message: "level=scenario requires `scenario`" });
+        ctx.addIssue({ code: "custom", ...buildQuotedIssue `level=scenario requires \`scenario\`` });
     if (b.level === "global" && (b.worker || b.scenario))
-        ctx.addIssue({ code: "custom", message: "level=global must not carry a selector" });
+        ctx.addIssue({ code: "custom", ...buildQuotedIssue `level=global must not carry a selector` });
 });
 // ═══ prompts 域 catalog 轴(0.10.20;[ref]a/[1242]/[1248] 过轮定稿;core design/148 S1 seam)═══
 // 形 = core 1.336+ 的 `PublishedPromptArtifactEnvelope`(sema-core src/prompt-assembly/artifact.ts,
@@ -2565,7 +2654,7 @@ export const EffectivePromptsWire = z
     declarations: EffectivePrompts.optional(),
     catalog: PublishedPromptArtifactEnvelope.optional(),
 })
-    .refine((w) => w.declarations !== undefined || w.catalog !== undefined, { message: "at least one axis (declarations|catalog) required" });
+    .refine((w) => w.declarations !== undefined || w.catalog !== undefined, buildQuotedIssue `at least one axis (declarations|catalog) required`);
 export const DOMAIN_SCHEMAS = {
     models: ModelsConfig,
     rosters: RostersConfig,

package/dist/web-admin-credential.d.ts

@@ -32,8 +32,8 @@ export declare const WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND: "user-session";
  *    文件**取当前值,不用内存旧值(另一个写者可能刚轮换过)。
  *  · `expiresAt` —— 访问令牌到期时刻(RFC 3339)。
  *  · `issuer` —— 签发它的 web-admin 的**基础 URL**(与读方连 web-admin 的根 URL 同形,可带路径前缀):续签只向同源的 web-admin 发,
- *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
- *    query / fragment 里不许夹带凭据)—— 本包不另写一份更窄的 URL 律。
+ *    同不同源由读方比。URL 形判据是包内 URL 判官的「非存量座位」那一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
+ *    query / fragment 里不许夹带凭据;issuer 是 wire 输入、不是存量,一次性迁移不碰它,fragment 拒句因此不指路)—— 本包不另写一份更窄的 URL 律。
  */
 export declare const WebAdminCredentialEnvelope: z.ZodObject<{
     kind: z.ZodLiteral<"user-session">;

package/dist/web-admin-credential.js

@@ -22,16 +22,11 @@
 import { z } from "zod";
 import { looksLikeJwt } from "./api/auth-bridge.js";
 import { NON_SECRET_URL_NO_MIGRATION } from "./types.js";
+import { buildQuotedIssue } from "./quoted-issue.js";
+import { RFC3339_DATE_TIME } from "./rfc3339.js"; // the package's one RFC 3339 date-time judge (a project registration's `archivedAt` reads the same one)
 import { WEB_ADMIN_ENV } from "./web-admin-env.js";
 /** 信封 `kind` 的闭集今只有一员(`SEALED_BOX_ALG` 同式的字面常量:schema 的字面与读方的比较都引它)。 */
 export const WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND = "user-session";
-/** 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` 取时刻,这是那组形里它处处读得准的子集。 */
-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");
 /** 一枚**令牌串**的形 —— 裸行 bearer、信封里的 `accessToken` / `refreshToken` 共用这**一条**律:可打印 ASCII
  *  (0x20–0x7E),首尾是可见字符(0x21–0x7E)、中间可有空格(共享令牌可以是一句口令 —— 验修轮 N2:今天走得通的
  *  这种令牌不许被本律拒掉)。控制字符、制表、非 ASCII、不可见字符一律不是令牌:判别器把它判 `unreadable`,而不是
@@ -50,13 +45,13 @@ const TokenString = z.string().regex(TOKEN_CHARS, "must be a token: printable AS
  *    文件**取当前值,不用内存旧值(另一个写者可能刚轮换过)。
  *  · `expiresAt` —— 访问令牌到期时刻(RFC 3339)。
  *  · `issuer` —— 签发它的 web-admin 的**基础 URL**(与读方连 web-admin 的根 URL 同形,可带路径前缀):续签只向同源的 web-admin 发,
- *    同不同源由读方比。URL 形判据与 `remoteExec` 的端点同一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
- *    query / fragment 里不许夹带凭据)—— 本包不另写一份更窄的 URL 律。
+ *    同不同源由读方比。URL 形判据是包内 URL 判官的「非存量座位」那一只 {@link NON_SECRET_URL_NO_MIGRATION}(http(s)、有 host、userinfo 与
+ *    query / fragment 里不许夹带凭据;issuer 是 wire 输入、不是存量,一次性迁移不碰它,fragment 拒句因此不指路)—— 本包不另写一份更窄的 URL 律。
  */
 export const WebAdminCredentialEnvelope = z
     .object({
     kind: z.literal(WEB_ADMIN_CREDENTIAL_ENVELOPE_KIND),
-    accessToken: TokenString.refine(looksLikeJwt, "must be a JWT (three dot-separated segments) — a worker pull token never goes into an envelope"),
+    accessToken: TokenString.refine(looksLikeJwt, buildQuotedIssue `must be a JWT (three dot-separated segments) — a worker pull token never goes into an envelope`),
     refreshToken: TokenString,
     expiresAt: RFC3339_DATE_TIME,
     issuer: NON_SECRET_URL_NO_MIGRATION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/settings-schema",
-  "version": "11.2.0",
+  "version": "11.3.0",
   "description": "Sema settings schema — pure config contract (zod domains + effective-config + roster resolution + ref-integrity + remoteExec) shared by sema-web-admin, sema-server, and the TOC desktop/CLI. One source of truth. (Renamed at 1.0.0 from @sema-agent/registry-core — name and docs only, no behavior change; note the range moves 0.19.0 -> 1.0.0, so a dependency must become ^1.0.0. The old names @sema-agent/registry-core <=0.19.0 and @sema-ai/registry-core remain published, frozen, for migration.)",
   "type": "module",
   "license": "BUSL-1.1",