@sema-agent/settings-schema 14.5.0 → 14.7.0

package/README.md

@@ -312,6 +312,21 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   use `task`; the widened vocabulary is visible to consumers that hold a `Record<MinTrust, …>` / exhaustive
   switch (compile error on upgrade — migrate to `trustRank`) or that validate external spec values with these
   schemas (they now accept `task` and must rank it — again `trustRank`, never a five-word table of their own).
+  **14.6.0 — comparison and the settings units.** "Which of two values is stricter" has ONE implementation,
+  `tightenVerdict(rule, existing, candidate)` → `equal` / `stricter` / `looser` / `unordered` / `unreadable` (`TIGHTEN_VERDICTS`).
+  It reads order only: each `TightenRule` has a normalized domain (`enumRank` a word of `order`; `boolStricter` a boolean, never
+  truthiness; `setUnion` / `setNarrower` a string array compared as a set; `numericLower` a finite number or `+Infinity` = no limit;
+  `none` a strict JSON value), a side outside it — or absent — is `unreadable`, and `policyDenyWins` is a RangeError (a fold law
+  between members, not an order). `TightenRule` appends `setUnion` (a superset is stricter) and `numericLower` (smaller is stricter),
+  both parameter-free: spellings such as an empty-set sentinel or a "≤ 0 means off" cap are normalized by the value's owner first.
+  A category's `tighten` answers only a `whole` unit's value; a declared member's comparator comes from its row's value class —
+  `MemberAdmission.list: true` marks a string-list member, `boolPole` a boolean one, exactly one per row — via
+  `memberTighten(category, member)` (`list` ⇒ setUnion for tighten / setNarrower for loosen; neither or both ⇒ RangeError).
+  The settings-document unit table is published here too: `SETTINGS_UNITS` (the ten units `permissions` · `permissionMode` ·
+  `additionalDirectories` · `sandbox` · `disableBypassPermissionsMode` · `disableAutoMode` · `hooks` · `env` · `model` · `outputStyle`,
+  each with its document `path`, category, addressing and reading), `unitTighten(unit, member?)` (a unit's comparator) and
+  `readSettingsUnit(unit, raw, member?)` (its raw-value reading: `"manual"` ⇒ `"default"`, `"disable"` ⇒ `true`, `false` stays
+  `false`, `"bypassPermissions"` ⇒ `launch_only`, everything outside the unit's reading — and `undefined` / `null` — ⇒ `unreadable`).
 - **Settings sources + layer admission** (`settings-sources.ts`, main barrel): `SETTINGS_SOURCES` (declaration order =
   merge order: user < project < local < flag < policy), `SETTINGS_SOURCE_CONTRACT` (each source's trust tier and whether a
   repository controls it — `projectSettings` / `localSettings` are repository-controllable and share the `project` tier, as in
@@ -341,8 +356,12 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   `VerifierConfig` / `VerifiedIdentity` / `AuthBridgeErrorCode` + pure decision fns
   (`shouldForceJwksRefresh`, `jwksWithinOfflineGrace`, `classifyTimeClaims`, `toVerifiedIdentity`).
   The normative rules R1–R10 in its header are the service verifier's implementation spec.
-  `VerifiedIdentity` carries an optional `scope` (the token's active tenant scope — see `api/scopes`) and an optional `iat`
-  (issued-at, integer seconds, verbatim — absent claim ⇒ no key; not a non-negative integer ⇒ the token is refused).
+  `VerifiedIdentity` carries an optional `scope` (the token's active tenant scope — see `api/scopes`), an optional `iat`
+  (issued-at, integer seconds, verbatim — absent claim ⇒ no key; not a non-negative integer ⇒ the token is refused) and an optional
+  `principalInc` (14.7.0: the principal's incarnation id, read from the token claim `PRINCIPAL_INC_CLAIM` = `sub_inc` — a non-empty string
+  verbatim; absent claim ⇒ no key, never a placeholder; present but not a non-empty string ⇒ the token is refused. A deleted-and-re-created
+  user keeps the name and gets a new incarnation, so `sub` alone names a slot, not a person; `PrincipalIncarnation` is the one schema every
+  incarnation field reads).
 - **web-admin credential file + connection env names** (`web-admin-credential.ts`, main barrel; S-698): the file behind
   `SEMA_WEB_ADMIN_TOKEN_FILE` is one of two KINDS — a bare line (one static token — the same kind of file as today:
   its first line, printable ASCII with no control / non-ASCII characters; user JWT vs worker pull token stays the reader's `looksLikeJwt` call) or a
@@ -363,6 +382,30 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   no default) → `env` / `file` / `absent`, the one pick-exactly-one rule for every credential: an empty string is unset, BOTH set (non-empty) throws (the refusal
   names the two keys, never a value), the file path comes back verbatim (resolving a relative one against a cwd
   is the reader's job).
+- **Sandbox git credential plane** (14.7.0; `sandbox-git.ts` + `api/credentials.ts`, main barrel only — no subpath): a sandbox's git uses the
+  MEMBER's own credential, fetched by the data plane from web-admin's credential port and used only through a proxy in that member's own pod. This
+  package carries the shapes and word tables, no IO. (1) `isSandboxGitOrigin` — a string equal to its own WHATWG origin with scheme http / https (the
+  canonical form is that one equation's consequence: lowercase host, no default port, no trailing slash, no userinfo / path / query / fragment;
+  an origin cannot express a sub-path deployment) — and the `sandboxGit` effective-config block `SandboxGitConfig`
+  (`{ origins: [{ origin, connectUrl }] }`, ≤ `SANDBOX_GIT_MAX_ORIGINS` = 16, distinct, empty list legal; an http origin is READABLE in the block — its
+  refusal is a per-origin answer word, not a block refusal). `sandboxGit` is a non-domain top-level key of the `/effective` payload: optional, no
+  default, carried verbatim by `readEffectiveWire` (`EffectiveWire.sandboxGit` is `unknown`) and judged by the consumer with `SandboxGitConfig`.
+  (2) The credential port's wire for `kind: "sandbox_git"`: `SandboxGitCredentialRequest` (claim a handle), `CredentialHandleAnswer` /
+  `CredentialResolveRequest` (kind-independent), `SandboxGitCredentialAnswer` with one `SandboxGitOriginAnswer` per origin (discriminated by
+  `state`; `secret` only on the `active` arm — other arms strip it), `SandboxGitCredentialRefusal` (`{ error, permanence, message }`). Three word tables,
+  each spelled once: `SANDBOX_GIT_ORIGIN_VERDICTS` (the 11-row per-origin judgment order; `SANDBOX_GIT_ORIGIN_STATES` / `SANDBOX_GIT_ORIGIN_REASONS`
+  and the answer arms' reason domains derive from it), `SANDBOX_GIT_REFUSALS` (10 refusal words → HTTP statuses + `permanence`;
+  `SANDBOX_GIT_REFUSAL_ERRORS` derives from it), `SANDBOX_GIT_PERMANENCE` (`terminal` / `transient`). Both sides' reading is in
+  `docs/CONSUMER-INTEGRATION.md` §12.
+- **Path-base judge and the fleet advertise address** (14.7.0; `url-shape.ts` main barrel, and `fleet.ts` main barrel + `./fleet`): a seat whose value is a
+  "base that other code appends request paths to" — the center base URLs, the address a fleet member advertises to the control plane, the web link base of
+  `webAdminSessionUrl` — has one rule: no credential, no query, no fragment; a path prefix is fine. `PATH_BASE_URL_FORBIDDEN_PARTS` is the ONE closed, frozen,
+  ordered set of the URL parts such a seat forbids (`userinfo` · `query` · `fragment`; a POLICY set, independent of the judge's vocabulary `HTTP_URL_PARTS` — which says what parts a URL has — so a new vocabulary word
+  has to be ruled on here explicitly); `pathBaseUrlFlaws(url)` is `httpUrlFlaws(url, that set)` — `[]` = acceptable, otherwise the judge's rule words, never a piece of the
+  value. `webAdminSessionUrl` reads it too. `FLEET_ADVERTISE_ADDRESS_ENV` (`"FLEET_ADVERTISE_ADDRESS"`, beside `FLEET_GENERATION_ENV` / `FLEET_SCOPE_ENV`) is the env name both the
+  writer (the orchestrator that renders the value) and the reader (the engine at boot) import. Judge the value AFTER placeholders are expanded: `http://$(POD_IP):8090` passes,
+  `http://[$(POD_IP)]:8090` does not (a bracketed host must parse as IPv6). Placeholder expansion, reachability and the absent / empty-string reading are not this package's;
+  the env name is not a reserved worker env name. Both sides' reading is in `docs/CONSUMER-INTEGRATION.md` §13.
 - **Session web link** (`web-admin-session-url.ts`, main barrel): `webAdminSessionUrl(webBaseUrl, { worker, sessionId })` — the ONE
   template for a web-admin session link, `<webBaseUrl>/chat?agent=<worker>&session=<sessionId>`: both parts required (a link with only
   the session id lands on whichever worker the page picks and may not find it), each part `encodeURIComponent`-escaped, the base a
@@ -481,7 +524,7 @@ therefore shows only `zod`. Node built-ins only (`node:crypto`, `node:fs`).
   `urlAllowPatternMatches` (⊆ CC `g9`, four upstream holes closed) / `urlDenyPatternMatches` (⊇ `g9` ∪ whole-string glob);
   divergences in `docs/CC-DIVERGENCE.md`.
 - **HTTP hook allowlists** (`http-hook-allowlists.ts`, 13.0.0): category `SAFETY_MERGE_SPEC.httpHookAllowlists`; `readHttpHookAllowlistLayer(source, settings)`,
-  `httpHookUrlVerdict(url, layers, workspace)` (every admitted layer's list must pass — layers intersect) and `httpHookEnvVarsAllowed(hookVars, layers, workspace)`;
+  `httpHookUrlVerdict(url, layers, workspace)` (every admitted layer's list must pass — layers intersect) and `httpHookEnvVarsAllowed(hookVars, layers, workspace)`, where every layer in `layers` is read by the reader's own reading (a reader-produced `read.layer`, a hand-built plain layer and a `JSON.parse`d layer from this realm with the same content get the same answer; a layer whose `source` cannot be read — missing, inherited, inconsistent or not a string — is a malformed layer that blocks everything (`rule: "malformed"`, not named in `sources`; a readable source with an unreadable list is `malformed` too and is named; `empty` means a list that really is `[]`), and a readable source word outside the closed set throws `RangeError`; lists, `hookVars` and `layers` must be plain arrays — the prototype is this realm's `Array.prototype` (an array from another realm — a `vm` context, another iframe — is refused; round-trip it through JSON first), `constructor` / `filter` / `flatMap` / `Symbol.iterator` read as this realm's built-ins, and the own keys are only indices and `length`; anything else, subclasses included, is read as malformed);
   a layer is admitted ⇔ `layerAdmission(source, workspace, "httpHookAllowlists") === "admitted"` (user / flag / managed; project / local are below the floor).
 - **MCP server list verdict** (`mcp-server-policy.ts`, 13.0.0): `mcpServerPolicyVerdict` → `McpPolicyBlock{name, list, rule, target,
   written, sources}` — judged on the expanded target, echoed only as written; the managed layer (whose `allowManagedMcpServersOnly` counts)

package/conformance/VERSION

@@ -1 +1 @@
-14.5.0
+14.7.0

package/conformance/cases/c84-sandbox-git-block-carried-verbatim/expected.json

@@ -0,0 +1,153 @@
+{
+  "domains": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "atMention": {
+          "mode": "all"
+        },
+        "models": [],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "prompts": {},
+      "rosters": {
+        "rosters": []
+      },
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-23T00:00:00.000Z"
+    }
+  },
+  "strictWrite": {
+    "outcome": "effective",
+    "effective": {},
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-23T00:00:00.000Z"
+    },
+    "why": "受理空集:本条打的是 wire 腿(提交的域文档集为空)。"
+  },
+  "wire": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "atMention": {
+          "mode": "all"
+        },
+        "models": [],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "rosters": {
+        "rosters": []
+      },
+      "sandboxGit": {
+        "origins": [
+          {
+            "connectUrl": "https://console.example.com/connect/git",
+            "origin": "https://git.example.com:9999"
+          },
+          {
+            "connectUrl": "https://console.example.com/connect/git",
+            "origin": "http://git.legacy.example:8080"
+          }
+        ]
+      },
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-23T00:00:00.000Z"
+    }
+  },
+  "localRoot": {
+    "derive": true,
+    "localVersion": 2617555914511015
+  }
+}

package/conformance/cases/c84-sandbox-git-block-carried-verbatim/input.json

@@ -0,0 +1,23 @@
+{
+  "meta": {
+    "version": 7,
+    "updatedAt": "2026-10-23T00:00:00.000Z"
+  },
+  "domains": {},
+  "wirePayload": {
+    "version": 7,
+    "updatedAt": "2026-10-23T00:00:00.000Z",
+    "sandboxGit": {
+      "origins": [
+        {
+          "origin": "https://git.example.com:9999",
+          "connectUrl": "https://console.example.com/connect/git"
+        },
+        {
+          "origin": "http://git.legacy.example:8080",
+          "connectUrl": "https://console.example.com/connect/git"
+        }
+      ]
+    }
+  }
+}

package/conformance/cases/c84-sandbox-git-block-carried-verbatim/meta.json

@@ -0,0 +1,5 @@
+{
+  "contributor": "contract",
+  "claim": "`sandboxGit` 是 /effective 载荷上的**非域**顶层键(web-admin 按部署登记册投影,不是存储域):wire 腿按 open-world 把它**逐字承运**(含块里的 http origin —— 它的拒因是逐 origin 应答里的一个词,不是块的校验拒),不出告警;其余三腿的入参里没有这个块,读出的 effective 里也不铸它(可选、无默认)。把它当域去校验、或当未知键丢掉的读腿,会让取值平面静默失去 origin 表。",
+  "firstRedOn": []
+}

package/conformance/cases/c85-sandbox-git-refused-block-still-carried/expected.json

@@ -0,0 +1,153 @@
+{
+  "domains": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "atMention": {
+          "mode": "all"
+        },
+        "models": [],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "prompts": {},
+      "rosters": {
+        "rosters": []
+      },
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-23T00:00:00.000Z"
+    }
+  },
+  "strictWrite": {
+    "outcome": "effective",
+    "effective": {},
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-23T00:00:00.000Z"
+    },
+    "why": "受理空集:本条打的是 wire 腿(提交的域文档集为空)。"
+  },
+  "wire": {
+    "outcome": "effective",
+    "effective": {
+      "collab": {
+        "templates": []
+      },
+      "entitlement": {
+        "budgetGroups": [],
+        "groupBindings": [],
+        "subjects": [],
+        "tiers": []
+      },
+      "execution": {
+        "allowedLanes": [
+          "host"
+        ],
+        "required": false
+      },
+      "governance": {},
+      "hosts": {
+        "hosts": []
+      },
+      "limits": {},
+      "mcp": {
+        "servers": []
+      },
+      "models": {
+        "atMention": {
+          "mode": "all"
+        },
+        "models": [],
+        "roles": {},
+        "tierGroups": []
+      },
+      "plugins": {
+        "plugins": []
+      },
+      "projects": {
+        "projects": {}
+      },
+      "rosters": {
+        "rosters": []
+      },
+      "sandboxGit": {
+        "origins": [
+          {
+            "connectUrl": "http://console.example.com/connect/git",
+            "origin": "https://Git.Example.com:443/"
+          },
+          {
+            "connectUrl": "https://console.example.com/connect/git",
+            "origin": "https://Git.Example.com:443/"
+          }
+        ]
+      },
+      "scenarios": {
+        "scenarios": []
+      },
+      "skills": {
+        "skills": []
+      },
+      "systems": {
+        "systems": []
+      },
+      "workers": {
+        "workers": []
+      }
+    },
+    "warnings": [],
+    "metadata": {
+      "version": 7,
+      "updatedAt": "2026-10-23T00:00:00.000Z"
+    }
+  },
+  "localRoot": {
+    "derive": true,
+    "localVersion": 2617555914511015
+  }
+}

package/conformance/cases/c85-sandbox-git-refused-block-still-carried/input.json

@@ -0,0 +1,23 @@
+{
+  "meta": {
+    "version": 7,
+    "updatedAt": "2026-10-23T00:00:00.000Z"
+  },
+  "domains": {},
+  "wirePayload": {
+    "version": 7,
+    "updatedAt": "2026-10-23T00:00:00.000Z",
+    "sandboxGit": {
+      "origins": [
+        {
+          "origin": "https://Git.Example.com:443/",
+          "connectUrl": "http://console.example.com/connect/git"
+        },
+        {
+          "origin": "https://Git.Example.com:443/",
+          "connectUrl": "https://console.example.com/connect/git"
+        }
+      ]
+    }
+  }
+}

package/conformance/cases/c85-sandbox-git-refused-block-still-carried/meta.json

@@ -0,0 +1,5 @@
+{
+  "contributor": "contract",
+  "claim": "块不合格(非规范形 origin、http 的 connectUrl、重复 origin)时 wire 腿**照样逐字承运**、不出告警:读腿不替消费方判 `sandboxGit`,判它的唯一座位是 `SandboxGitConfig`(消费方在用之前跑)。读腿若『好心』校验并丢弃坏块,消费方分不清『没有投影』与『投影坏了』。",
+  "firstRedOn": []
+}

package/dist/api/auth-bridge.d.ts

@@ -54,10 +54,14 @@
  *     signature checks). (Decision function: `jwksWithinOfflineGrace`.)
  *
  *  R9 OUTPUT. Success → `VerifiedIdentity { principal: sub, role: token.role, grantId: token.jti,
- *     scope: token.scope, iat: token.iat }` (`scope` = the multi-tenant active scope claim, `api/scopes`; read it with
+ *     scope: token.scope, iat: token.iat, principalInc: token.sub_inc }` (`scope` = the multi-tenant active scope claim, `api/scopes`; read it with
  *     `readTokenScope` — an absent claim is refused, not read as "global"; `iat` = issued-at, integer seconds, carried
  *     verbatim — a reader that learns a principal was deleted at T cuts off its tokens issued before T; absent claim ⇒ no
- *     `iat` key; present but not a non-negative integer ⇒ the token is `malformed`).
+ *     `iat` key; present but not a non-negative integer ⇒ the token is `malformed`; `principalInc` = the incarnation claim
+ *     {@link PRINCIPAL_INC_CLAIM} carried verbatim — the same name deleted and re-created is ANOTHER person, and this is what
+ *     tells the two apart; absent claim ⇒ no `principalInc` key — never a placeholder: what a reader does with a token that names
+ *     no incarnation is that reader's decision, not a refusal here; present but not a non-empty string ⇒ the token is `malformed`,
+ *     the same law as `sub`).
  *     `role` is web-admin RBAC role claim (string, informational for the worker's own authz mapping);
  *     `grantId` is the jti when web-admin stamps one (absent today — optional forever). Failure → one
  *     of AUTH_BRIDGE_ERROR_CODES; the HTTP surface answers 401 with a GENERIC message (no error detail
@@ -87,6 +91,14 @@ export declare const DEFAULT_OFFLINE_GRACE_SEC: number;
  *  split one identity into two. Anyone validating or minting a principal (a token `sub`, a membership row, an outbound
  *  principal header) checks against THIS value. */
 export declare const PRINCIPAL_MAX_LENGTH = 190;
+/** R9 — the token claim that carries the principal's INCARNATION: a deleted-and-re-created user keeps the name (`sub`) and gets a new
+ *  incarnation, so `sub` alone names a slot, not a person. One spelling for whoever mints the claim and whoever reads it
+ *  ({@link toVerifiedIdentity} reads it by this constant), the way `SCOPE_CLAIM` (`api/scopes`) is spelled once for the scope claim. */
+export declare const PRINCIPAL_INC_CLAIM = "sub_inc";
+/** One incarnation id: a non-empty string, opaque (never trimmed, folded or parsed). The token claim, {@link VerifiedIdentity.principalInc},
+ *  and every wire field that names an incarnation (the credential port's request and answer) are THIS schema — one rule, read by object. */
+export declare const PrincipalIncarnation: z.ZodString;
+export type PrincipalIncarnation = z.infer<typeof PrincipalIncarnation>;
 /** One RSA public JWK as web-admin publishes it (public members ONLY — a `d`/`p`/`q` here is a web-admin
  *  bug, but the verifier MUST still never use/echo private members). */
 export declare const WebAdminJwk: z.ZodObject<{
@@ -140,6 +152,7 @@ export declare const VerifiedIdentity: z.ZodObject<{
     grantId: z.ZodOptional<z.ZodString>;
     scope: z.ZodOptional<z.ZodString>;
     iat: z.ZodOptional<z.ZodNumber>;
+    principalInc: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type VerifiedIdentity = z.infer<typeof VerifiedIdentity>;
 /** The verifier's total result — exactly one of ok/error. */
@@ -195,6 +208,7 @@ export declare function toVerifiedIdentity(payload: {
     aud?: unknown;
     scope?: unknown;
     iat?: unknown;
+    sub_inc?: unknown;
 }, cfg?: Pick<VerifierConfig, "audience">): AuthBridgeResult;
 /** Cheap pre-filter: does this bearer LOOK like a JWT (three non-empty dot-separated segments)? Use it to
  *  route between the existing static-token branch and this verifier — NOT as any kind of validation. */

package/dist/api/auth-bridge.js

@@ -54,10 +54,14 @@
  *     signature checks). (Decision function: `jwksWithinOfflineGrace`.)
  *
  *  R9 OUTPUT. Success → `VerifiedIdentity { principal: sub, role: token.role, grantId: token.jti,
- *     scope: token.scope, iat: token.iat }` (`scope` = the multi-tenant active scope claim, `api/scopes`; read it with
+ *     scope: token.scope, iat: token.iat, principalInc: token.sub_inc }` (`scope` = the multi-tenant active scope claim, `api/scopes`; read it with
  *     `readTokenScope` — an absent claim is refused, not read as "global"; `iat` = issued-at, integer seconds, carried
  *     verbatim — a reader that learns a principal was deleted at T cuts off its tokens issued before T; absent claim ⇒ no
- *     `iat` key; present but not a non-negative integer ⇒ the token is `malformed`).
+ *     `iat` key; present but not a non-negative integer ⇒ the token is `malformed`; `principalInc` = the incarnation claim
+ *     {@link PRINCIPAL_INC_CLAIM} carried verbatim — the same name deleted and re-created is ANOTHER person, and this is what
+ *     tells the two apart; absent claim ⇒ no `principalInc` key — never a placeholder: what a reader does with a token that names
+ *     no incarnation is that reader's decision, not a refusal here; present but not a non-empty string ⇒ the token is `malformed`,
+ *     the same law as `sub`).
  *     `role` is web-admin RBAC role claim (string, informational for the worker's own authz mapping);
  *     `grantId` is the jti when web-admin stamps one (absent today — optional forever). Failure → one
  *     of AUTH_BRIDGE_ERROR_CODES; the HTTP surface answers 401 with a GENERIC message (no error detail
@@ -72,6 +76,8 @@
  */
 import { z } from "zod";
 import { INTEGER } from "../integer.js";
+import { inspect, orWhenUninspectable, ownJsonOrThrow, ownOrThrow } from "../own-key-read.js";
+import { isJsonArray } from "../plain-json-object.js";
 // ── constants ────────────────────────────────────────────────────────────────────────────────────────────
 /** The web-admin JWKS endpoint, relative to the web-admin origin (shipped; public by design, RFC 7517 §5). */
 export const WEB_ADMIN_JWKS_PATH = "/api/auth/sso/jwks";
@@ -88,6 +94,13 @@ export const DEFAULT_OFFLINE_GRACE_SEC = 24 * 60 * 60;
  *  split one identity into two. Anyone validating or minting a principal (a token `sub`, a membership row, an outbound
  *  principal header) checks against THIS value. */
 export const PRINCIPAL_MAX_LENGTH = 190;
+/** R9 — the token claim that carries the principal's INCARNATION: a deleted-and-re-created user keeps the name (`sub`) and gets a new
+ *  incarnation, so `sub` alone names a slot, not a person. One spelling for whoever mints the claim and whoever reads it
+ *  ({@link toVerifiedIdentity} reads it by this constant), the way `SCOPE_CLAIM` (`api/scopes`) is spelled once for the scope claim. */
+export const PRINCIPAL_INC_CLAIM = "sub_inc";
+/** One incarnation id: a non-empty string, opaque (never trimmed, folded or parsed). The token claim, {@link VerifiedIdentity.principalInc},
+ *  and every wire field that names an incarnation (the credential port's request and answer) are THIS schema — one rule, read by object. */
+export const PrincipalIncarnation = z.string().min(1);
 // ── JWKS wire shape (what GET /api/auth/sso/jwks returns) ────────────────────────────────────────────────
 /** One RSA public JWK as web-admin publishes it (public members ONLY — a `d`/`p`/`q` here is a web-admin
  *  bug, but the verifier MUST still never use/echo private members). */
@@ -159,6 +172,11 @@ export const VerifiedIdentity = z.object({
      *  a claim that is not a non-negative integer makes the token `malformed` (R9), and one issued later than now + the clock
      *  skew is `expired` (R5, the same tolerance as `exp` / `nbf`). */
     iat: INTEGER.nonnegative().optional(),
+    /** = token {@link PRINCIPAL_INC_CLAIM} (`sub_inc`) when present, verbatim — the principal's incarnation id ({@link PrincipalIncarnation}).
+     *  Absent claim ⇒ the key is absent (never minted; never `0`, `""` or any placeholder): a reader that needs an incarnation and finds none
+     *  answers "incarnation unrecorded" itself — that is not a refusal of the token. A claim that is not a non-empty string makes the token
+     *  `malformed` (R9): a broken issuer is not read as an old one. */
+    principalInc: PrincipalIncarnation.optional(),
 });
 /**
  * R3 — should a token bearing `kid` trigger a forced JWKS refetch?
@@ -203,29 +221,46 @@ export function classifyTimeClaims(claims, nowSec, clockSkewSec) {
  * library has verified signature (R1/R2/R3), issuer (R4) and time (R5).
  */
 export function toVerifiedIdentity(payload, cfg) {
-    if (typeof payload.sub !== "string" || payload.sub.length === 0)
-        return { ok: false, error: "malformed" };
-    // The iat rule is the output field's own schema (one rule, not a second hand-written check).
-    const iatRead = VerifiedIdentity.shape.iat.safeParse(payload.iat);
-    if (!iatRead.success)
-        return { ok: false, error: "malformed" };
-    const iat = iatRead.data;
-    if (cfg?.audience) {
-        const aud = payload.aud;
-        const match = typeof aud === "string" ? aud === cfg.audience : Array.isArray(aud) && aud.includes(cfg.audience);
-        if (!match)
+    // Every claim is read from the payload's OWN keys (identity reads only what the token carries: a polluted `Object.prototype.role` is not a role the token was minted with,
+    // and a token with no `aud` is not given one); a claim that cannot be read ⇒ the token is malformed (fail-closed), never an engine error.
+    return orWhenUninspectable(() => {
+        const sub = ownOrThrow(payload, "sub"); // 只问「是不是非空串」:读一次值,不深拷
+        if (typeof sub !== "string" || sub.length === 0)
             return { ok: false, error: "malformed" };
-    }
-    return {
-        ok: true,
-        identity: {
-            principal: payload.sub,
-            role: typeof payload.role === "string" && payload.role.length > 0 ? payload.role : undefined,
-            grantId: typeof payload.jti === "string" && payload.jti.length > 0 ? payload.jti : undefined,
-            scope: typeof payload.scope === "string" && payload.scope.length > 0 ? payload.scope : undefined,
-            ...(iat !== undefined ? { iat } : {}),
-        },
-    };
+        // The iat and incarnation rules are the output fields' own schemas (one rule each, not a second hand-written check).
+        // Each schema call runs under `inspect`: the validator reads a snapshot THIS package took, and a throw there (a length check coercing an object value to a primitive) is not the caller's
+        // object being unreadable — but it is still no identity: the claim is malformed, and no engine error escapes the judge.
+        const iatRead = inspect(() => VerifiedIdentity.shape.iat.safeParse(ownJsonOrThrow(payload, "iat")));
+        if (!iatRead.ok || !iatRead.value.success)
+            return { ok: false, error: "malformed" };
+        const iat = iatRead.value.data;
+        const incRead = inspect(() => VerifiedIdentity.shape.principalInc.safeParse(ownJsonOrThrow(payload, PRINCIPAL_INC_CLAIM)));
+        if (!incRead.ok || !incRead.value.success)
+            return { ok: false, error: "malformed" };
+        const principalInc = incRead.value.data;
+        if (cfg?.audience) {
+            const aud = ownJsonOrThrow(payload, "aud");
+            const match = typeof aud === "string" ? aud === cfg.audience : isJsonArray(aud) && aud.includes(cfg.audience);
+            if (!match)
+                return { ok: false, error: "malformed" };
+        }
+        // role / jti / scope 只问「是不是非空串」(别的值读成缺省):读一次值,不深拷 —— 深拷会让「值是个带 Date 的对象」把整枚令牌拖成 malformed(v14.6.0 只做 typeof 判)。
+        // 要深拷的只有交给会反射它的代码的值:`aud`(数组上 `includes`)与 `iat` / `sub_inc`(交给校验器)
+        const role = ownOrThrow(payload, "role");
+        const jti = ownOrThrow(payload, "jti");
+        const scope = ownOrThrow(payload, "scope");
+        return {
+            ok: true,
+            identity: {
+                principal: sub,
+                role: typeof role === "string" && role.length > 0 ? role : undefined,
+                grantId: typeof jti === "string" && jti.length > 0 ? jti : undefined,
+                scope: typeof scope === "string" && scope.length > 0 ? scope : undefined,
+                ...(iat !== undefined ? { iat } : {}),
+                ...(principalInc !== undefined ? { principalInc } : {}),
+            },
+        };
+    }, () => ({ ok: false, error: "malformed" }));
 }
 /** Cheap pre-filter: does this bearer LOOK like a JWT (three non-empty dot-separated segments)? Use it to
  *  route between the existing static-token branch and this verifier — NOT as any kind of validation. */