@sema-agent/sdk 6.12.0 → 6.14.0

package/openapi.yaml

@@ -135,6 +135,24 @@ tags:
       MF-Fleet (shell-host data contract) — the LIVE multi-row fleet view SSE (active task + workflow rows,
       transitioning over time). Owner-scoped by the credential principal (scope wire-stripped) unless fleet-wide;
       in-process bus, NOT resumable (a drop is a full restart). No fleet wiring → 501.
+  - name: rules
+    description: >
+      #154 车二 (design/179 §7) — PERSISTENT permission rules: the CC-settings import lane (prepare → redeem).
+      Two-step consent protocol: prepare only previews and mints a one-shot, principal-bound, expiring,
+      payload-bound ticket; only redeem reaches the writer. LANE = PRINCIPAL (a rule means "this person
+      themself said yes"), never operator. GATED AND OFF BY DEFAULT: the whole lane hangs on
+      PERMISSION_RULES_ENABLED (default false) plus a wired rule store — so on a stock deployment BOTH doors
+      answer 501 `capability.rule_store_required`, and so does the single-card half (the ask frame simply
+      carries no `ruleSuggestions`). Read the observed frame / an actual response, never a version number.
+      The SINGLE-CARD half of the same lane is `persistRule` on POST /v1/tool-approvals/{id}/respond.
+  - name: adoption
+    description: >
+      design/183 — identity ADOPTION (form b: pure identity rebind). A one-shot, operator-only DEPLOYMENT
+      action; nothing billed. Idempotent in the sense that re-running with the same parameters does not start a
+      second adoption and, ONCE TERMINAL, replays the SAME FROZEN `immutableReport` byte-for-byte — the receipt
+      as a whole carries no such guarantee (`current` is recomputed every read, and a `stalled` report is a
+      provisional projection). Requires a SQL backend (→ else 501). Refusals never produce a receipt — they are
+      typed 409s. ⚠️ The GET does not sweep late rows but CAN resume an in-flight arc — it is not a safe poll.
   - name: leader
     description: v2 leader pipeline (gated; E2B + git push). NOT the default door-B brain.
   - name: metrics
@@ -2530,6 +2548,67 @@ paths:
         '404': { $ref: '#/components/responses/NotFound' }
         '501': { $ref: '#/components/responses/NotImplemented' }
 
+  /v1/tasks/{taskId}/tool-results/{ref}:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - $ref: '#/components/parameters/TaskIdPath'
+      - in: path
+        name: ref
+        required: true
+        schema: { type: string }
+        description: >
+          The opaque tool-result ref the model was handed in the offload preview
+          (`<persisted-output ref="tr_…">`). Pass it VERBATIM (URL-encoded) — never re-derive it.
+    get:
+      tags: [trace]
+      operationId: traceToolResult
+      x-status: live             # server: routes/trace-usage.ts `handleToolResult` (blackboard [3321]).
+      summary: Page back an offloaded (large) tool result.
+      description: >
+        The wire mirror of the engine's `ToolResultStore.get`: when a tool returns more text than the
+        offload threshold, the conversation keeps a preview + a `ref` and the full text moves into the
+        deployment's durable tool-result store. This endpoint reads a SLICE of it back, so a workspace/
+        shell can show the full output the model paged through.
+
+        🔴 The 404 is DELIBERATELY uniform (`not_found.tool_result`, one fixed message, the ref never
+        echoed): a ref this task's log does not attest (unknown, another session's, another task's), a
+        deployment with no durable tool-result store, and an attested ref whose content was already
+        reaped are byte-identical responses. Do not branch on them — you cannot tell them apart, by
+        design (a distinguishable arm would be an existence/deployment-shape oracle). In particular this
+        face never 501s on a missing store, and a 404 never proves the output is gone.
+
+        SCOPE — read the ref on the task whose trace showed it. Ownership is the trace family's gate (a
+        principal caller sees only its own runs; a fleet credential is fleet-wide) PLUS an exact binding:
+        the ref must be one this task's own durable event log attests (it is re-derived from the log's
+        tool-call ids). The trace and this face read the same log, so "visible in the task's trace ⇒
+        readable here" holds; a ref carried over from a DIFFERENT task of the same session is a 404 —
+        ask for it under that task's id.
+      parameters:
+        - in: query
+          name: offset
+          required: false
+          schema: { type: integer, minimum: 0, maximum: 2147483646 }
+          description: >
+            Char offset to start the slice at. Absent ⇒ the store's default (0). The cap is the narrowest
+            backend's integer range (the PostgreSQL store binds `offset + 1` as int4) — above it the server
+            answers 400 rather than letting the read fail backend-dependently.
+        - in: query
+          name: limit
+          required: false
+          schema: { type: integer, minimum: 0, maximum: 262144 }
+          description: >
+            Max chars to return. Absent ⇒ the store's default. Above 262144 ⇒ 400 (the server refuses
+            rather than silently clamping, so a caller can never mistake a truncated slice for the ask).
+      responses:
+        '200':
+          description: One slice of the stored content (`totalChars` is the FULL length, not the slice's).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ToolResultSlice' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.query_invalid — offset/limit not a non-negative integer, or limit over the cap
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }          # not_found.tool_result — the uniform arm (see description)
+
   /v1/tasks/{taskId}/stream:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -2806,6 +2885,32 @@ paths:
               properties:
                 decision: { type: string, enum: [allow, allow_session, deny] }
                 updatedInput: { description: 'ctrl+g edited tool args (replaces the asked args on allow).' }
+                persistRule:
+                  type: object
+                  # 刻意**不**封闭:server 的 `parseToolApprovalResponse` 只读 `rule`,对象里多给的键它**忽略**
+                  # (与 `updatedInput` 同一条宽收姿势)。写 `additionalProperties:false` 会让照 spec 生成的
+                  # 客户端拒发一个 server 其实会受理的请求 —— 那是我们自己造的漂移,不是上游的约束。
+                  required: [rule]
+                  properties:
+                    rule: { type: string, minLength: 1, maxLength: 512, description: 'Non-empty (the server parser rejects an empty string); at most MAX_RULE_TEXT_CHARS = 512.' }
+                  description: >
+                    server #154 车二, ADDITIVE — the person ticked "don't ask again": echo back, VERBATIM, the
+                    `rule` of the chosen entry of the frame's `ruleSuggestions`. Allow-family only (on `deny`
+                    the server tolerantly ignores it, same posture as `updatedInput`).
+
+                    🔴 A CANDIDATE, NOT FREE TEXT: the server locates this string in the candidate table the
+                    engine minted and refuses if it does not match (`ruleRefusal: "rule_not_offered"`). Do not
+                    hand-build it, re-case it or append `:*` — take it from the frame.
+                    🔴 Together with `updatedInput` the persistence is refused (`rule_input_edited`): the call
+                    that takes effect is the edited one while the candidates came from the ORIGINAL command.
+                    The decision itself still stands.
+                    ⚠️ If the frame carried no `ruleSuggestions`, do not send this key — there is nothing
+                    redeemable for THIS card and the answer is necessarily `rulePersisted:false` +
+                    `rule_lane_unavailable` (the missing material short-circuits BEFORE any candidate
+                    comparison, so it is never `rule_not_offered`). Absence has THREE possible causes — no rule
+                    store wired, the engine minted no candidate for this command (compound / redirect /
+                    substitution), or the command bytes were unreadable — so do NOT diagnose the deployment's
+                    rule lane from one frame or from that refusal.
       responses:
         '200':
           description: Ack (`decision` echoed).
@@ -3855,6 +3960,376 @@ paths:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
         '501': { $ref: '#/components/responses/NotImplemented' }
 
+  # ── #154 车二(design/179 §7)—— 持久权限规则的 CC settings 导入两口 ─────────────────────────────
+  # 两步同意协议:prepare 产出预览 + 一张票(**零规则落库**,但 pending 记录与票本身是 durable 的 ⇒ 不幂等),
+  # redeem 才够得着写面。lane = principal(用户导的是
+  # 他自己的规则),NOT operator。整条车道挂 PERMISSION_RULES_ENABLED,未接规则店 ⇒ 两口 501。
+  /v1/rules/cc-import/prepare:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [rules]
+      operationId: rulesCcImportPrepare
+      x-status: gated            # server routes/rules.ts;PERMISSION_RULES_ENABLED + 规则店装配,缺一 ⇒ 501 capability.rule_store_required。SDK rules.ccImportPrepare() 消费。
+      summary: Preview a CC-settings rule import and mint a one-shot redemption ticket.
+      description: >
+        Read the ALLOW buckets of 1–3 user-editable CC settings layers the caller submits, and answer with
+        what the import WOULD do plus a ticket.
+
+        🔴 NO PERMISSION RULE is persisted by this call — only POST /v1/rules/cc-import/redeem reaches the
+        writer. But the call is NOT free of durable state and NOT idempotent: every successful prepare writes
+        a PENDING approval record and mints ANOTHER valid ticket. So re-previewing in a loop accumulates
+        pending records and live tickets; preview once, show it, then redeem or drop it. (A candidate-cap
+        rejection tries to discard the record it just created, best-effort — a leftover orphan pending record
+        affects no adjudication, but it is not a promise of zero residue either.)
+
+        Only the allow bucket is read. The deny/ask buckets are the TIGHTENING direction and have their own
+        channel; importing them through a loosening lane would be the wrong door.
+
+        The ticket is principal-bound, expiring (10 min), single-use (atomically consumed) and payload-bound
+        (it pins a digest of the candidate set at mint time). It is NOT a cacheable credential and must never
+        be handed to another user.
+
+        LANE = PRINCIPAL, not operator: a rule means "this person themself said yes", so an operator has no
+        position on this path — an operator importing their OWN rules walks the same route under their own
+        principal.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              # 封闭:server 侧 zod 是 `.strict()` —— 多一个键是 400,不是静默忽略(把 `content` 拼成
+              # `contents` 的客户端应当场知道,而不是拿到一份「零候选」的预览去纳闷)。
+              additionalProperties: false
+              required: [layers]
+              properties:
+                layers:
+                  type: array
+                  minItems: 1
+                  maxItems: 3
+                  items: { $ref: '#/components/schemas/CcImportLayer' }
+      responses:
+        '200':
+          description: >
+            What the import would do, plus the redemption ticket. NO PERMISSION RULE is in the store yet — but a
+            pending approval record and this ticket are already durable (this call is not idempotent; see the
+            operation description).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/CcImportPrepareResult' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — not {layers:[{layer,path,root,content}]}, or an empty `root` (an empty prefix would silently promote a project rule to global)
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '413': { $ref: '#/components/responses/PayloadTooLarge' }   # request.payload_too_large — more than 200 candidates across all submitted layers; SHORTEN and resend (retrying the same payload cannot help)
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.rule_store_required — this deployment has no permission-rule store wired
+
+  /v1/rules/cc-import/redeem:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [rules]
+      operationId: rulesCcImportRedeem
+      x-status: gated            # server routes/rules.ts;同 prepare 的部署谓词。SDK rules.ccImportRedeem() 消费。
+      summary: Redeem a prepared import ticket — the ONE step that reaches the rule writer.
+      description: >
+        Atomically consume the ticket, confirm the pending approval record, and apply the batch. Idempotent
+        at the engine level (each candidate carries its own dot), but the TICKET is single-use — do not
+        auto-retry this call, and never replay it speculatively.
+
+        🔴 THE 404 IS UNIFORM BY DESIGN (`not_found.rule_ticket`, one fixed message): a forged ticket,
+        ANOTHER principal's ticket, an expired one and an already-consumed one are byte-identical responses.
+        Distinguishable arms would be an existence oracle (probing whether someone else's ticket exists).
+        ⚠️ It is also WIDER than those four: non-retryable record/payload failures (the approval record is gone,
+        the payload digest no longer matches, an adjudicated confirmation refusal) fold into the SAME 404. So do
+        NOT branch on the cause and do NOT read it as "the user brought the wrong ticket" — treat any 404 as
+        "this ticket is not usable here, start over".
+
+        The ONE distinguishable arm is 503 `state.rule_import_retry`: it means the claim was RELEASED and
+        the ticket is STILL USABLE — retry as-is after `retryAfterSec` (echoed in `Retry-After`). Folding
+        that into the 404 would tell a caller their confirmation is lost when it is not; the two call for
+        opposite handling.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false   # server 侧 `.strict()`
+              required: [ticket]
+              properties:
+                ticket: { type: string, minLength: 1, maxLength: 190, description: 'The ticket from rulesCcImportPrepare. Verbatim.' }
+      responses:
+        '200':
+          description: What the import ACTUALLY did (a different moment and contract from the preview).
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/CcImportRedeemResult' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — body is not {ticket}
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { $ref: '#/components/responses/NotFound' }          # not_found.rule_ticket — the UNIFORM arm (forged / another principal's / expired / already used). Never branch on the cause.
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '503':
+          description: >
+            errorCode `state.rule_import_retry` — the import could not complete right now (a transient store
+            wobble), the claim was released and THE TICKET IS STILL USABLE. Body carries `retryAfterSec`
+            and the same value rides `Retry-After`. Retry the SAME ticket. This is the only arm on this
+            endpoint a caller may distinguish from the uniform 404, and the distinction is load-bearing.
+          headers:
+            Retry-After:
+              schema: { type: integer }
+              description: Seconds to wait before retrying with the same ticket.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.rule_store_required
+
+  # ── design/203 §2(server 7.12.0)—— 持久权限规则的**撤销面**两口。与上面的导入两口共用部署谓词
+  # (PERMISSION_RULES_ENABLED + 规则店装配,缺一 ⇒ 501),但多一条 operator 越权域:`principal` 让一个
+  # 列了名的 operator 读或收回**任一租户**的规则。方向决定授权 —— 收回是 TIGHTENING(core removePersistedRule
+  # 头注逐字:a host may narrow on a user's behalf, it may not widen),而回收权限正是撤销面的本义。
+  # 🔴 路径**没有 :id 段**:一条规则的身份就是它的 (rule, scope) 内容对,服务端不铸行 id,所以删是按内容删。
+  /v1/rules:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [rules]
+      operationId: rulesList
+      x-status: gated            # server routes/rules.ts handleRuleList;同 cc-import 的部署谓词。SDK rules.list() 消费。
+      summary: List the rules that are LIVE under a principal (keyset-paged, cursor bound to the revision).
+      description: >
+        List the persisted allow rules currently live under one principal (tombstones already folded).
+        Ordering is deterministic — `(scope, rule)` lexicographic — because keyset paging's whole premise is
+        that the same data comes back in the same order every time. The order is decided by the server, NOT
+        by the store (core's `list()` promises none).
+
+        🔴 THE CURSOR IS BOUND TO `(rev, principal, scope)` AND A MISMATCH IS REFUSED, NOT RESET. A rule set
+        is read WHOLE, so there is no tearing WITHIN a page — tearing happens BETWEEN pages, when somebody
+        adds or removes a rule after page 1 and the keyset start now lands in a different set (silently
+        dropped or duplicated rows). Sending a cursor minted at another revision / principal / scope filter
+        gets a 400 (`request.query_invalid`, body carries the current `rev`); restart the listing without a
+        cursor. Silently starting over would let a client read page 2 as "continuing page 1" and hand a
+        governance surface a list that is both short and duplicated, with nobody the wiser.
+
+        `scope` FILTER: given but unreadable ⇒ 400, never "treated as unfiltered" — that would silently turn
+        "show me only this project" into a full listing the caller would accept as the project's list.
+        `limit` is CLAMPED (not refused) into 1..200, default 50 — a mistyped paging knob must not make a
+        governance page unopenable.
+
+        OPERATOR OVERRIDE: `principal` reads ANOTHER tenant's rules and is `OPERATOR_PRINCIPALS`-gated
+        (an EMPTY list means NOBODY — never inferred from the service token, which is a shared deployment
+        credential, not a person). Omitted, or equal to your own principal, is the ordinary self-read and
+        needs no operator standing.
+      parameters:
+        - name: principal
+          in: query
+          required: false
+          schema: { type: string, minLength: 1, maxLength: 190 }
+          description: >
+            OPERATOR-ONLY cross-tenant read. Absent (or equal to the caller's own principal) = read your own
+            rules. Anything else requires explicit OPERATOR_PRINCIPALS membership ⇒ otherwise 403
+            `auth.operator_only`. Rule text contains command shapes, so third-party reads are an information
+            disclosure and are deliberately not opened to non-operators.
+        - name: scope
+          in: query
+          required: false
+          schema: { type: string, minLength: 1 }
+          description: >
+            Filter to one scope, spelled `global` or `project:<root>` with a NON-EMPTY root. Unreadable ⇒ 400
+            `request.query_invalid` (never silently unfiltered). Matching is done on the CANONICAL form, so an
+            equivalent-but-differently-spelled root filters to an empty page.
+        - name: limit
+          in: query
+          required: false
+          schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
+          description: 'Page size. CLAMPED into 1..200 (non-numeric / out-of-range is clamped, not refused); default 50.'
+        - name: cursor
+          in: query
+          required: false
+          schema: { type: string }
+          description: >
+            The `nextCursor` from the previous page, VERBATIM (base64url, opaque — do not parse or mint one).
+            It is bound to the revision, the principal and the scope filter it was minted on; any mismatch is
+            a 400 `request.query_invalid` carrying the current `rev`. Restart the listing without a cursor.
+      responses:
+        '200':
+          description: One page of live rules plus the store revision the page was read at.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/RuleListResult' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.query_invalid — unreadable `scope`, unreadable `cursor`, or a cursor minted at a different (rev, principal, scope). Body carries `rev` on the revision-mismatch arm.
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }         # auth.operator_only — reading another principal's rules without explicit OPERATOR_PRINCIPALS membership (an EMPTY list means nobody)
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.rule_store_required — this deployment has no permission-rule store wired
+    delete:
+      tags: [rules]
+      operationId: rulesRevoke
+      x-status: gated            # server routes/rules.ts handleRuleRevoke;同 cc-import 的部署谓词。SDK rules.revoke() 消费。
+      summary: Revoke a persisted rule BY CONTENT — `(rule, scope)`, with no id in the path.
+      description: >
+        Revoke one persisted allow rule identified by its CONTENT pair `(rule, scope)`. There is no `:id`
+        path segment on purpose: a rule's identity IS that pair, the server mints no row id, and the engine's
+        `removePersistedRule` primitive (which this endpoint always goes through) works in observed-remove
+        form over the add dots.
+
+        🔴 IDEMPOTENT, AND DELIBERATELY NOT A 404. Revoking twice, or revoking something that was never
+        there, is `200 {status:"no-op"}` — a "did this rule ever exist?" 404 would be an existence oracle
+        (a CROSS-TENANT one under the operator override), and deletion has no business answering that
+        question. Read `status` to learn whether you removed anything.
+
+        🔴 `stillLive` IS LOAD-BEARING ON BOTH ARMS. `true` means the tombstone landed but the rule is
+        STILL live under add-wins — a fresh approval was recorded during the call. Folding that into a plain
+        200 would let a client read an INCOMPLETE revocation as complete, which is precisely what a
+        governance surface must never get wrong. The `no-op` arm carries it for the same reason: the engine
+        answers `no-op` off its initial snapshot without a read-back, so an approval landing in that window
+        leaves the rule alive while the verb says "nothing to remove". Both arms therefore ship the same key
+        set and one consumer branch reads both.
+
+        OPERATOR OVERRIDE: `principal` revokes on ANOTHER tenant's behalf, gated exactly like the read half
+        (explicit `OPERATOR_PRINCIPALS`; empty list = nobody). The direction is what makes the override
+        legitimate — revoking is TIGHTENING — but the identity test does not relax because of it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/RuleRevokeRequest' }
+      responses:
+        '200':
+          description: >
+            The revocation outcome. `removed` = a tombstone was written; `no-op` = nothing matched (idempotent
+            repeat, or it was never there). BOTH arms carry `stillLive` — read it before telling a human the
+            rule is gone.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/RuleRevokeResult' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape — body is not {rule, scope, principal?}, or `scope` is not `global`/`project:<non-empty root>`
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }         # auth.operator_only — revoking another principal's rule without explicit OPERATOR_PRINCIPALS membership
+        '429': { $ref: '#/components/responses/RateLimited' }
+        '503':
+          description: >
+            errorCode `state.rule_remove_failed` — the engine could not complete the removal right now. Core's
+            contract for this arm is "a read-back confirmed nothing was written, OR the read-back itself failed
+            and the outcome is undetermined" — both are RETRY-CAN-CHANGE-IT, which is why it is a 503 and not a
+            500. Retry, then reconcile with `GET /v1/rules`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.rule_store_required
+
+  # ── design/183 —— 身份收编面(form b:纯身份重绑)。operator-only 的一次性部署级动作,零模型工作。 ──
+  /v1/adoption:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [adoption]
+      operationId: adoptionStart
+      x-status: gated            # server routes/adoption.ts;需 SQL 后端(DB_BACKEND=mysql|pg),否则 501 capability.adoption_store_required。SDK adoption.start() 消费。
+      summary: Adopt one principal's data under another principal (identity rebind, form b).
+      description: >
+        A one-shot DEPLOYMENT action, not a business surface: operator-only, nothing billed, and honestly 501
+        on a deployment with no SQL backend (the identity axis being rebound does not exist on the local one).
+
+        IDEMPOTENT: re-running with the same parameters never starts a second adoption, and ONCE THE ARC IS
+        TERMINAL it replays the same frozen `immutableReport` byte-for-byte (written once at the final phase,
+        never recomputed). The RECEIPT AS A WHOLE carries no byte-identity guarantee — `current` is recomputed
+        on every call, so two reads may match or may differ — and before the terminal state
+        (`status: "stalled"`) the report itself is a provisional projection of the current row. Concurrent identical POSTs are
+        arbitrated by a UNIQUE on the source principal: exactly one row lands and both connections read the
+        same `adoptionId`.
+
+        🔴 A REFUSED ADOPTION NEVER PRODUCES A RECEIPT. `status` is a two-word closed set
+        (`adopted`/`stalled`) with NO `rejected` member — refusals are typed 409s. Otherwise "refused" and
+        "succeeded" would share one 200 envelope and a consumer could only guess by reading fields.
+
+        🔴 This does NOT fence off ordinary writers. "Stop the engine first" is an OPERATOR PRECONDITION, not
+        a machine guarantee: a caller still injecting the old identity keeps writing rows after the terminal
+        state, while the idempotent short-circuit keeps answering `adopted`. That is what
+        `current.residualSourceRows` makes visible — `> 0` means rows MAY still sit under the old identity OR
+        the count itself failed (the server reports 1 fail-closed when it cannot count); either way, go look.
+        It is not proof of an active writer. A POST (a write verb) also sweeps those late rows into the new
+        identity and re-reports the count; a GET does not sweep — but it DOES resume an in-flight arc (see the
+        GET description), so it is not a safe poll either.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/AdoptionRequest' }
+      responses:
+        '200':
+          description: >
+            The adoption receipt — the SAME ENVELOPE SHAPE for the first success and for every idempotent
+            re-run. There is NO byte-identity guarantee for the whole receipt (it may match or differ):
+            `current` is recomputed on every call. The one frozen part is a TERMINAL `immutableReport`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AdoptionReceipt' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape / request.field_invalid — same from/to ("nothing to adopt", refused BEFORE a row is minted so the UNIQUE slot is not burned), or a principal that does not fit every identity column and derived key this adoption must write
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }         # auth.operator_only
+        '409':
+          description: >
+            A refusal — THREE distinct errorCodes ride this status and the operator's next action differs for
+            each, so branch on `errorCode`, never on the status:
+            `adoption.source_already_bound` (this source is already bound to a DIFFERENT destination — a
+            second adoption / cross-tenant transfer, deliberately out of scope; body carries `adoptionId`,
+            `fromPrincipal`, `boundTo`);
+            `adoption.destination_conflict` (the destination already holds rows sharing a logical key with
+            the source; body lists the conflicting tables in `conflicts` — go clean those up);
+            `adoption.destination_unrepresentable` (the destination identity does not fit some key this
+            adoption would DERIVE from it, e.g. a memory `proj:` key overrunning a column width — pick a
+            SHORTER destination principal).
+            Either way both sides are byte-unchanged.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.adoption_store_required — adoption requires a SQL store backend (DB_BACKEND=mysql|pg)
+
+  /v1/adoption/{adoptionId}:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+      - { name: adoptionId, in: path, required: true, schema: { type: string }, description: 'From AdoptionReceipt.adoptionId.' }
+    get:
+      tags: [adoption]
+      operationId: adoptionGet
+      x-status: gated            # server routes/adoption.ts;同 POST 的部署谓词。SDK adoption.get() 消费。
+      summary: Read one adoption's state (and RESUME it if it is still in flight).
+      description: >
+        🔴 THIS IS NOT A SIDE-EFFECT-FREE READ. On a TERMINAL row (adopted / refused) it is a pure read. On a
+        row that is STILL IN FLIGHT — the typical case being a deployment where nothing has POSTed again since
+        a crash — it RESUMES THE ARC: the same `driveUnderLock` the boot scan uses, advancing phases, rewriting
+        rows on the identity axis, recording the config ledger and landing the terminal state. That is
+        deliberate upstream (otherwise one crash would require a human to re-POST), but a consumer must know
+        it: do NOT treat this as a safe prefetch / dashboard poll — reading an in-flight arc is pressing
+        continue on it. The ONLY difference from the POST is that the GET does NOT sweep late rows into the
+        new identity (the POST does). Repeating the call is safe (advisory lock + phase CAS + idempotent
+        identity ⇒ a replay lands where one call lands) — but "safely replayable" is not "read-only". There
+        is no verb on this wire today that guarantees zero progression.
+
+        `immutableReport` is historical fact — but only ONCE `status` is `adopted`; on a `stalled` receipt it is
+        a provisional projection of the current row and can differ between two reads (see the AdoptionReport
+        schema). `current` is recomputed every time. Do not infer one half from the other — in particular
+        `status: "adopted"` does NOT mean the configuration migration is done; that account lives in
+        `current.outstandingConfigs` / `current.residualSourceRows`, and a non-zero residual may also mean the
+        count itself failed (see that field).
+      responses:
+        '200':
+          description: The adoption receipt.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AdoptionReceipt' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.id_invalid — undecodable id (shared with sessions/attachments; no second synonym code was minted)
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '403': { $ref: '#/components/responses/Forbidden' }         # auth.operator_only
+        '404': { $ref: '#/components/responses/NotFound' }          # not_found.adoption — no such id. ⚠️ A REFUSED adoption is still a typed 409 here, not a 404: the refusal is remembered.
+        '409':
+          description: 'Same three refusal codes as adoptionStart (a refused adoption keeps answering its refusal).'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '501': { $ref: '#/components/responses/NotImplemented' }    # capability.adoption_store_required
+
   /metrics/summary:
     get:
       tags: [metrics]
@@ -4479,6 +4954,35 @@ components:
           items: { $ref: '#/components/schemas/TaskAgentDefinition' }
           description: Per-task sub-agent definitions (roster additions scoped to this task only).
         interactiveTools: { type: boolean, description: Mount interactive (prompting) tools. }
+        oneShot:
+          type: boolean
+          description: >
+            core >=5.23.0 `TaskSpec.oneShot`, server >=7.12.0 — declare that THIS SUBMISSION is one-shot: no
+            later turn exists in which an asynchronous background notification could land. The archetype is a
+            headless `sema -p` whose process exits when the turn ends.
+
+            🔴 IT GRANTS NOTHING AND GUARANTEES NOTHING — core consumes it as GUIDANCE ONLY. What changes is
+            the wording the engine gives the MODEL for `RunWorkflow` / delegation receipts: "end your turn, you
+            will be notified" (correct only when a next turn exists) becomes "block-wait via
+            `TaskOutput({block:true})`". Omitting it on a headless call is a known way to LOSE background
+            results — that is why the key exists — but sending it is **best-effort**, not a completion
+            contract: the model may ignore the instruction or run out of budget, and some legs have no poll
+            path at all. If your caller REQUIRES the results, keep your own wait/reconcile step; do not treat
+            `oneShot: true` as one. There is no tenancy gate because there is no capability to gate.
+
+            🔴 PROBE `capabilities.oneShot` BEFORE SENDING IT: the task body is an OPEN set (the server does
+            not refuse unknown keys), so a worker that does not yet consume this field accepts `oneShot: true`,
+            answers 200, and still tells the model to end its turn and await a notification the process will
+            never receive — no 400, no warning. The capability bit (server >=7.12.0) is what distinguishes the
+            two; ABSENT means the key is being ignored. Note the bit being PRESENT does not retire the
+            caller-side wait step: it proves the key is consumed, not that the results arrive.
+
+            PER-REQUEST on purpose: "does this submission expect to be continued" is a property of the
+            SUBMISSION, not of the connection it arrived on. Sibling of `interactiveTools` (the same `-p`
+            posture) and passed through identically — a boolean rides, ABSENT ⇒ the key is omitted and core's
+            default (interactive) applies. Anything that is neither absent nor a boolean is a fail-loud 400
+            `request.field_invalid` ("oneShot must be a boolean"), NOT a silent coercion. Rides the persisted
+            body onto resume legs.
         retainBackgroundProcesses: { type: boolean, description: Keep background processes alive past the turn. }
         forwardSubagentEvents:
           type: boolean
@@ -4927,8 +5431,12 @@ components:
       type: object
       description: >
         Trace turn (true shape, service-pinned). role currently only "assistant" (user/system/tool reserved —
-        the user/objective opening turn is NOT projected today). blocks is an OPEN set; tool-result.output
-        is currently ALWAYS absent (session-storage join not wired — known gap).
+        the user/objective opening turn is NOT projected today). blocks is an OPEN set. tool-result.output IS
+        present (server trace/project.ts projects it; the old "ALWAYS absent" note was stale — [3315] finding) —
+        but note it carries the STORED form: outputs over the engine's offload threshold are persisted in
+        bounded form (head/tail preview + `<persisted-output ref>` marker), so `output` here can be the
+        truncated form, disclosed via `truncated`/`totalChars`. Full retrieval of an offloaded output awaits
+        the tool-results read face ([3316] server half, planned).
       required: [seq, ts, role, blocks]
       additionalProperties: true
       properties:
@@ -4949,6 +5457,20 @@ components:
               input: { description: tool-call — redacted args. }
               callId: { type: string }
               isError: { type: boolean }
+              # 🔴 core >=5.18.1 (#187) —— 与 `Event_tool_end.settledBy` **同一个值**:server 的共享挑键器
+              # `toolResultFieldsOf`(src/trace/project.ts)同时喂 turns 面与 trace SSE 面,而写侧
+              # `toolEndEventData` 喂 durable 账本 —— 三面一个真源,所以这里的词表与那边逐字相同。
+              settledBy:
+                type: string
+                enum: [human, timeout, aborted]
+                description: >
+                  tool-result — HOW this call was settled when it went through an approval: `human` = somebody
+                  actually answered; `timeout` = the approval window elapsed; `aborted` = abort / unclonable
+                  arguments / out-of-contract. Present ONLY on the settled call.
+                  ABSENCE CARRIES NO SEMANTICS (an older worker, or a posture arm that deliberately leaves it
+                  unset — the two are indistinguishable), so absent is neither "human" nor "no approval
+                  happened". The read leg re-validates the closed set independently of the write leg, because a
+                  ledger row can come from any engine generation.
         tokens:
           type: object
           properties:
@@ -4968,6 +5490,9 @@ components:
       # 于是「server 少发 retainedFrom」这种断页判据丢失对本门不可见。
       additionalProperties: false
       required: [turns, retainedFrom]
+      # ⚠️ 路别差异契约([3315]② 定谳,core [3316] 判设计事实非缺陷):trace 记账只在 /v1/runs 路;
+      # sync `POST /v1/tasks` 完成后的 turns 读面对该 run 恒 `turns: []`(retainedFrom: 0)。这是契约,
+      # 不是待修缺口——sync 路要 trace 请改走 /v1/runs。哪天 sync 路开始填 turns = 行为变更需过本表。
       properties:
         turns:
           type: array
@@ -5048,6 +5573,21 @@ components:
           type: array
           items: { $ref: '#/components/schemas/Artifact' }
 
+    ToolResultSlice:
+      type: object
+      description: >
+        One slice of an offloaded tool result (`GET /v1/tasks/{taskId}/tool-results/{ref}`) — the wire
+        form of the engine's `ToolResultSlice`. `offset` echoes where this slice starts (so successive
+        reads concatenate deterministically) and `totalChars` is the length of the FULL stored content,
+        independent of the slice — a client pages until `offset + content.length === totalChars`.
+      # 封闭:铸造点 routes/trace-usage.ts `handleToolResult` 只发这三键(core ToolResultSlice 原形)。
+      additionalProperties: false
+      required: [content, offset, totalChars]
+      properties:
+        content: { type: string, description: 'The slice text.' }
+        offset: { type: integer, description: 'Char offset this slice starts at.' }
+        totalChars: { type: integer, description: 'Total chars of the FULL stored content (not this slice).' }
+
     LeaderReceipt:
       type: object
       description: >
@@ -5186,6 +5726,76 @@ components:
             legacy verbs in 1.0.0; the live face is `client.memory.exportScope` / `.sync`
             (`GET /v1/memory/export`, `POST /v1/memory/sync/{scope}`), which this flag does NOT gate.
             Kept on the wire so an older shell that still reads it honestly hides the dead affordances.
+        adoption:
+          type: boolean
+          description: >
+            design/183 form b adoption face (POST /v1/adoption + GET /v1/adoption/:id, operator lane) is
+            wired. Same predicate as the routes' 501 (the SQL backend's adoptionLog factory is present;
+            the local backend deliberately omits it). Probe before use, no trial-by-501.
+        permissionRules:
+          type: boolean
+          description: >
+            The permission-rule lane is available: /v1/rules/cc-import/* , the respond persistRule redemption
+            arm, and (from server 7.12.0) the GET/DELETE /v1/rules revocation face. Server predicate =
+            PERMISSION_RULES_ENABLED AND a wired rule store — the SAME predicate behind every one of those
+            endpoints' 501s, so "says yes" means all of the ones this server has actually work.
+            🔴 THE KNOB'S DEFAULT READS IN TWO SEGMENTS: default OFF (opt-in) on server <= 7.11.0, default ON
+            (opt-out) from 7.12.0, where the revocation face — the prerequisite that kept it opt-in — landed.
+            So "the operator said nothing" means OPPOSITE things across that boundary; only an explicit
+            `false` disables it. Read THIS BIT; never infer the lane's state from a knob default or a
+            version number.
+        permissionRulesRevoke:
+          type: boolean
+          description: >
+            server >=7.12.0 — the rule REVOCATION face (GET + DELETE /v1/rules) is ROUTED on this worker.
+            Same deps predicate as `permissionRules`; what carries the extra information is this key's mere
+            PRESENCE. 🔴 That is the whole point of it being a second bit rather than a tightening of the
+            first: on a <=7.11.0 worker `permissionRules` already answers true while these two routes 404, so
+            that bit cannot distinguish "the lane is off" from "this build predates the face", and its
+            published wording ("all four endpoints work") is already untrue there — you can add a bit, you
+            cannot retroactively change one. ABSENT => an older worker: expect 404 `not_found.route` from
+            `rules.list` / `rules.revoke` and hide the governance affordance. PRESENT => the routes exist
+            (whether they then answer depends on `permissionRules`, as always).
+        modeShellGateTranslation:
+          type: boolean
+          description: >
+            design/201 §3 (server >=7.12.0) — this binary CONTAINS the `permissionMode` -> `spec.shellGate`
+            translation table (bypassPermissions => off; auto/default/acceptEdits/plan => classify; no stated
+            mode => the key is not written). HARD-CODED true and landed in the SAME COMMIT as the table, so
+            "says yes <=> the translation is really there" is structural, not deps-derived — no missing
+            dependency can make it false.
+            🔴 THE PROBE MUST BE THIS BIT ON THE SERVER YOU ARE TALKING TO, NEVER YOUR OWN SHELL VERSION. A
+            shell drops its unconditional `MANUAL_MODE_SHELL_GATE` env injection on the strength of this bit;
+            keyed off the shell's own version instead, the three real deployments — new shell against an old
+            server, a replica rolled back to an older binary, a mixed-version fleet — each open a window where
+            the shell has stopped injecting and the server cannot yet translate. Absent/false ⇒ keep injecting.
+        oneShot:
+          type: boolean
+          description: >
+            server >=7.12.0 — this worker actually CONSUMES `TaskRequest.oneShot` (projects it into `TaskSpec`
+            when it is a boolean, omits the key when absent, and 400s a non-boolean). Hard-coded true: the
+            consumption depends on no optional facility. 🔴 PROBE IT BEFORE RELYING ON THE FIELD: the task
+            request body is an OPEN set, so a worker that does not consume the key still accepts it and
+            answers 200 — a headless caller would declare itself one-shot, never receive core's block-wait
+            guidance, and lose its background results with nothing on the wire to reveal it. ABSENT => the key
+            is being ignored; keep your own wait/reconcile step. (That step remains good practice even when
+            the bit is present: the field is guidance to the model, not a completion contract.)
+        outcomeLedger:
+          type: boolean
+          description: >
+            server >=7.12.0 — the `GET /v1/outcomes` mechanical-signal read aggregate (design/73 §7.2) is
+            available. Predicate mirrors the route's refusal arms exactly: a QUERYABLE ledger is wired (a
+            file-only sink writes JSONL and has no query face ⇒ 501), AND on a multi-tenant deployment the
+            operator list is non-empty (single-user has no such gate — the only user IS the operator).
+            Added because this face previously had a 501 but NO capability bit, leaving consumers to
+            trial-by-501 — the exact pattern this capability surface exists to remove.
+        sharedMemory:
+          type: boolean
+          description: >
+            design/177 org shared-memory read face (`GET /v1/shared-memory/*`) is mounted. Server-side the
+            predicate is the SAME conjunction that mounts the route domain (SQL store present AND the
+            principal→org membership fold present), so true ⟺ the face actually works — a deployment with
+            the store but no membership authority deliberately reports false (and does not mount the routes).
         workflows: { type: boolean, description: "ENGINE-CAN: this worker's engine can orchestrate S8 self-orchestration workflows (server: `workflowsCapable ?? Boolean(workflowRunStore)`). The MOUNTING of the durable /v1/workflows read routes is the separate `workflowsList` bit below; the two coincide in today's wiring but are declared as orthogonal axes." }
         workflowsList: { type: boolean, description: "`GET /v1/workflows` list face (separate from the per-run reads)." }
         resumeAt: { type: boolean, description: "E18 resume-at-message anchors are resolvable." }
@@ -7752,8 +8362,35 @@ components:
             redeem it. The engine ALWAYS emits the section, so `false` is a REAL reading ("no rule lane on this
             worker"), NOT "this engine is too old". The section is optional HERE only because this spec's support
             floor is server 3.0.0, which predates it; absent = the worker never sent it.
+
+            🔴 `syncWired` / `orgGoverned` (core >=5.23.0 design/182 §9/§7, server >=7.12.0) sit in THIS
+            section — the engine deliberately did not put them in the operator-only `governance` section, and
+            the server projects all three bits on both faces. THEY WERE THE REASON THIS SECTION HAD TO BE
+            REDECLARED: this arm is `additionalProperties: false`, so a strict consumer validating a real
+            frame against the 6.13.0 spec did not "miss two fields" — the WHOLE SECTION failed validation and
+            the diagnostics surface went unreadable. Same failure family as `errorCode` on `Event_tool_end`.
           properties:
             storeWired: { type: boolean }
+            syncWired:
+              type: boolean
+              description: >
+                core >=5.23.0 (design/182 §9) — this worker merges persisted rules into the SAME consent trust
+                domain as its cross-device / transport / server-side peers. Read with `storeWired` to answer
+                "how far does this 'don't ask again' actually travel?": the same click means something wider
+                here than on a worker that keeps its rules local.
+                🔴 PRESENT-AND-FALSE IS A REAL READING — "this engine has the concept, this deployment has not
+                wired it" — NOT "too old to know". Absent (the whole key missing) is the only "did not send it"
+                signal. On server 7.12.0 this is honestly `false` everywhere: the seam exists in core, the
+                server has not wired a supplier yet.
+            orgGoverned:
+              type: boolean
+              description: >
+                core >=5.23.0 (design/182 §7) — an ORGANIZATION governance layer is armed over this rule lane.
+                Load-bearing consequence: that layer is FAIL-CLOSED, so when the org snapshot cannot be read,
+                EVERY allow is escalated into a real human approval rather than quietly honored. A shell that
+                renders "don't ask again" without reading this bit is advertising an outcome it cannot promise.
+                🔴 Same three-way reading as `syncWired`: present-and-false = concept known, not armed here;
+                absent = the worker never sent the key. Honestly `false` on server 7.12.0.
         governance:
           type: object
           additionalProperties: false
@@ -8150,6 +8787,44 @@ components:
             governance shell gate sits at the "classify" tier, a shell ask may come from the classifier or from
             another gate; the server leaves the key absent rather than guessing). Never render absence as
             "this gate can be bypassed by a posture".
+        ruleSuggestions:
+          type: array
+          minItems: 1   # 空数组不可能出现:server 的合取项②要求 `req.ruleSuggestions` **非空**,否则整键省略(缺席 = 本卡无此选项)
+          # 刻意**不**声明 maxItems:server 的 `.max(4)` 是**卡** schema(`ApprovalCardSchema`)上的约束,这条
+          # live 帧腿没有它。在这里抄一个上界 = 声明一条 server 并不执行的约束(照 spec 生成的严格客户端会
+          # 拒收一条合法帧)。数量上界的真源是引擎:core 5.22.0 的 `suggestRulesForCommand` **至多铸一条,且恒
+          # `match: "exact"`**(不写死上界是给将来的 miner 留位,不是暗示今天会有更多)。
+          items: { $ref: '#/components/schemas/RuleSuggestion' }
+          description: >
+            server #154 车二 (core 5.18.0, design/179), ADDITIVE, "tool_approval" only: the rule candidates
+            the ENGINE minted for this ask. Render them as the "don't ask again" options and echo the chosen
+            one back as `persistRule.rule` on POST /v1/tool-approvals/{id}/respond.
+
+            🔴 PRESENCE IS THE PROMISE: the key is present ONLY on a deployment that actually has a
+            permission-rule store wired (the same object behind the engine's `permissionRules.storeWired`
+            manifest bit). A deployment without one OMITS it rather than offering an option with nowhere to
+            redeem — an unredeemable "don't ask again" is a wire lie, worse than absence.
+
+            🔴 THE CONVERSE DOES NOT HOLD: absence means "THIS CARD has no redeemable candidate", and three
+            causes produce it — no rule store wired, the engine minted no candidate for this command (compound /
+            redirect / substitution), or the command bytes were unreadable. One frame cannot tell them apart, so
+            never diagnose the deployment's rule lane from a single absence, and never synthesize a candidate.
+
+            📏 HOW MANY, TODAY: core 5.22.0's miner (`suggestRulesForCommand`) emits AT MOST ONE candidate and
+            always `match: "exact"` — no shipped producer mints the broader prefix option. `prefix` stays in the
+            closed vocabulary because the wire validator accepts it and a later miner may emit it; render what
+            arrives, but do NOT build a UI that assumes a narrow/broad PAIR is on offer.
+
+            🔴 The values are the engine's VERBATIM (closed `match` vocabulary + engine-minted text); the
+            server neither re-mints nor re-orders them. A hand-built rule string is refused at redemption
+            (`ruleRefusal: "rule_not_offered"`) — by construction, so a click on a harmless command cannot be
+            turned into a rule for something else.
+
+            ⚠️ REDEMPTION SCOPE: the key also rides the durable card replay, but its only redemption channel is
+            the LIVE respond leg keyed by this frame's `approvalId` — an in-process map on ONE replica. Same
+            replica ⇒ redeemable; after a restart / on another replica that `approvalId` 404s and the person
+            must use the durable decide leg, which carries NO rule field in v1 (its body is strict — an extra
+            `persistRule` is a loud 400, not a silent drop).
         fromSubagent:
           type: boolean
           enum: [true]
@@ -8269,11 +8944,91 @@ components:
             posture. Semantics, the ABSENT != false clause and the discrimination boundary are stated verbatim on
             ToolApprovalFrame.governanceForced. It sits at the card's top level rather than inside `risk` because
             `risk` describes the ENGINE's judgement of the call, while this key says WHO imposed the gate.
+        ruleSuggestions:
+          type: array
+          minItems: 1   # 同帧腿:空数组不可能出现(素材同源),缺席才是「本卡无此选项」
+          maxItems: 4   # 卡形上**真有**这条上界(server `ApprovalCardSchema` 的 `.max(4)`);live 帧腿没有,故只写在这里
+          items: { $ref: '#/components/schemas/RuleSuggestion' }
+          description: >
+            ADDITIVE (#154 车二 / core 5.18.0 design/179): the rule candidates the ENGINE minted for this ask —
+            the card's "don't ask again" options; echo the chosen one back as `persistRule.rule`. Semantics,
+            the PRESENCE-IS-THE-PROMISE clause (present only where a rule store is wired) and the redemption
+            scope are stated verbatim on ToolApprovalFrame.ruleSuggestions — the live frame, the stored
+            `card_json` and the replayed frame carry the SAME material.
         fromSubagent: { type: boolean, enum: [true], description: 'Present ⇔ the ask comes from a DELEGATED child — the explicit discriminator (a worker cannot forge it).' }
         sourceTaskId: { type: string, description: 'The child''s core session id — row-join value + fallback discriminator.' }
         sourceAgentName: { type: string, description: 'The child agent''s display name, redacted. UNTRUSTED.' }
         delegation: { $ref: '#/components/schemas/ApprovalCardDelegation' }
 
+    RuleSuggestion:
+      type: object
+      description: >
+        One ENGINE-minted rule candidate (#154 车二 / core 5.18.0 `RuleSuggestion`) — what a single click on
+        "don't ask again" would persist.
+
+        🔴 THE TEXT COMES FROM THE ENGINE, NOT THE SHELL: the server derives it from the adjudicated command's
+        own bytes; a client may only echo one of these back verbatim (`persistRule.rule`). Reporting text that
+        is not among the candidates is refused (`ruleRefusal: "rule_not_offered"`) rather than guessed at, so
+        "click on a harmless command, get a rule for something else" is not spellable on this path.
+      # 封闭:core `RuleSuggestion` 恰三键(rule/match/command),server 逐字透传不重铸。
+      additionalProperties: false
+      required: [rule, match, command]
+      properties:
+        rule: { type: string, maxLength: 512, description: 'The canonical rule text to echo back on redemption (server MAX_RULE_TEXT_CHARS = 512).' }
+        match:
+          type: string
+          enum: [exact, prefix]
+          description: '`exact` = this one command only (`Bash(git status)`); `prefix` = word-boundary prefix (`Bash(git status:*)`). Closed vocabulary — an unknown value is not a candidate this contract describes; do not render it as redeemable.'
+        command: { type: string, maxLength: 512, description: 'The command pattern inside the rule, for a shell that would rather not re-parse `rule`.' }
+
+    RuleRefusalReason:
+      type: string
+      description: >
+        Why a "don't ask again" did NOT get persisted (#154 车二; the server's `RuleRefusalReason`, verbatim).
+        A CLOSED set so a shell can branch instead of matching prose. The two naming styles are NOT a typo:
+        the four hyphenated members are derived from the consent lane's own refusal reasons, the four
+        underscored ones are minted by the server's gates.
+
+        🔴 A refusal NEVER flips the decision. The person's "allow this once" has already taken effect and
+        reached the engine; turning the whole respond into a 4xx would make a real allow vanish. The honest
+        shape is always 200 + `rulePersisted: false` + this reason.
+
+        `no-candidates` — the engine could mint no candidate for this command (compound/redirect/substitution).
+        `unknown-candidate` — the echoed text does not locate in the record's candidate table.
+        `confirm-refused` / `redeem-refused` — the consent protocol's confirm/redeem step was refused
+        (record state, a lost CAS, or the store refusing the write).
+        `rule_lane_unavailable` — FOUR causes share this one value (the server's three conjuncts): no rule store
+        wired, OR the engine minted no candidate for this command, OR the command bytes were unreadable, OR this
+        ask has no verified owner. 🔴 Two of those are per-CARD limits, so this reason is NOT evidence about the
+        deployment — never disable the rule feature globally on the strength of it.
+        `rule_input_edited` — the respond ALSO carried `updatedInput` (ctrl+g edit): the call that takes effect
+        is the edited one while the candidates were minted from the ORIGINAL command, so persisting would arm a
+        standing allow for the original (a real privilege widening). v1 refuses the persistence; the decision
+        itself still stands.
+        `rule_not_offered` — the echoed text is not among THIS ask's candidates (a stale card, or someone
+        trying to mint a rule of their own).
+        `rule_store_error` — the rule store wobbled. The adjudication is unaffected.
+        `rule_governance_forced` (server >=7.12.0, #204) — the gate on THIS ask came from the deployment's
+        operator governance layer, so the ask never entered the rule lane at all.
+        🔴 SPLIT FROM `rule_lane_unavailable` ON PURPOSE: that one is "one of four conjuncts failed" (no rule
+        store, no candidate, unreadable command bytes, no verified owner — two of which are per-CARD limits),
+        this one is "the lane is perfectly healthy, only THIS ask is operator-governed". Folding them would
+        erase a real distinction on the card.
+        ⚠️ NEITHER IS A DEPLOYMENT-LEVEL VERDICT. Every member of this enum describes ONE ask's outcome; the
+        note on `rule_lane_unavailable` above already says never to disable the feature globally on it, and
+        the same holds here. The one correct source for "does this worker serve rules at all" is
+        `capabilities.permissionRules`. Keep offering "don't ask again" on the next ask; just not on this one.
+      enum:
+        - no-candidates
+        - unknown-candidate
+        - confirm-refused
+        - redeem-refused
+        - rule_lane_unavailable
+        - rule_input_edited
+        - rule_not_offered
+        - rule_store_error
+        - rule_governance_forced
+
     ApprovalRiskAxes:
       type: object
       description: >
@@ -9587,7 +10342,10 @@ components:
         shape, `decision` echoed). Owner-gated with a 404 and NO existence oracle: non-owner and
         unknown/settled/expired/wrong-replica ids are indistinguishable.
       # 封闭(census 批2 第三段,2026-07-30):铸造点 `tool-approval.ts` 三恒在键 + 两条件键
-      # (rememberApplied/updatedInputForwarded 的条件展开就在同一行字面量里),键集恰是这 5 个。
+      # (rememberApplied/updatedInputForwarded 的条件展开就在同一行字面量里)。
+      # #154 车二(2026-08-10):`persistRuleAfterDecision` 的 `withFlag()` 在同一个体上再盖两个条件键
+      # (rulePersisted 恒在、ruleRefusal 仅失败时)—— 键集从 5 升 7,**封闭性不动**(additive 不许把
+      # census 闭合的口悄悄捅开)。
       required: [approvalId, delivery, decision]
       additionalProperties: false
       properties:
@@ -9606,6 +10364,24 @@ components:
             server 1.241 ([1458]): present (true) when an allow-family decision carried `updatedInput` and
             the server forwarded the edited args to the engine — forwarded, not necessarily applied
             (consumption depends on the core OnAsk object arm). Omitted on deny / no edit / older servers.
+        rulePersisted:
+          type: boolean
+          description: >
+            server #154 车二, ADDITIVE: whether the `persistRule` this respond carried actually landed in the
+            rule store.
+
+            🔴 A FAILED PERSISTENCE NEVER FLIPS THE DECISION — the person's "allow this once" already took
+            effect and reached the engine, so the honest shape is 200 + `rulePersisted: false` + `ruleRefusal`,
+            NOT a 4xx. Render it as "allowed, but 'don't ask again' was not saved" — never as a failed approval.
+            Omitted when the respond carried no `persistRule`, and on older servers; ABSENT is not `false`.
+        ruleRefusal:
+          allOf: [{ $ref: '#/components/schemas/RuleRefusalReason' }]
+          description: >
+            server #154 车二, ADDITIVE: the MACHINE-READABLE reason when `rulePersisted` is false (closed
+            vocabulary). Always absent when `rulePersisted` is true. Branch on it to separate "try again on the
+            next ask" (`rule_input_edited`) from "there was nothing redeemable on this card"
+            (`rule_lane_unavailable`). 🔴 `rule_lane_unavailable` covers four causes, two of them per-card — do
+            NOT read it as "this deployment has no rule lane" (see the RuleRefusalReason schema).
 
     UsageMetric:
       type: string
@@ -9830,3 +10606,490 @@ components:
         path: { type: string, description: 'The relPath — pass VERBATIM as ?path= on the file sub-route.' }
         hash: { type: string, description: 'Content address (sha256) — enables cross-snapshot change highlighting ([1894]②).' }
         size: { type: integer, description: 'Present only when the store has a sizes face (SQL backends).' }
+
+    # ═══════════════════════════════════════════════════════════════════════════════════════════════
+    # #154 车二(design/179 §7)—— 持久权限规则的 CC settings 导入面。形按 server 真码 + core 原形亲读
+    # (`src/http/routes/rules.ts` / `src/rules-consent.ts`;preview/result 两形是 core `ImportPreview` /
+    # `ImportResult` 的原样透传)。
+    # ═══════════════════════════════════════════════════════════════════════════════════════════════
+
+    CcImportSettingsLayer:
+      type: string
+      enum: [userSettings, projectSettings, localSettings]
+      description: >
+        The three user-editable CC settings layers this version reads (core `ImportedSettingsLayer`). The two
+        layers it does NOT read are named in `CcImportPreview.uncovered` rather than being silently absent.
+
+    RuleScope:
+      description: >
+        Where a persisted rule applies (core `RuleScope`). `project.root` is the directory prefix that decides
+        which cwds the rule is live under.
+      oneOf:
+        - type: object
+          additionalProperties: false
+          required: [kind]
+          properties:
+            kind: { type: string, enum: [global] }
+        - type: object
+          additionalProperties: false
+          required: [kind, root]
+          properties:
+            kind: { type: string, enum: [project] }
+            root: { type: string, minLength: 1, description: 'The canonical directory this rule is scoped to. NEVER empty — an empty prefix contains EVERY cwd, which would silently promote a project rule to a global one.' }
+
+    RuleCandidate:
+      type: object
+      description: 'One candidate rule: the canonical text plus the scope it would land in (core `RuleCandidate`).'
+      additionalProperties: false
+      required: [rule, scope]
+      properties:
+        rule: { type: string, maxLength: 512 }
+        scope: { $ref: '#/components/schemas/RuleScope' }
+
+    CcImportSkippedRule:
+      type: object
+      description: >
+        One entry that did NOT become a candidate.
+
+        🔴 `reason` IS HUMAN-READABLE PROSE, NOT A MACHINE CODE. Upstream produces exactly three shapes:
+        a grammar/validation refusal is `"<RuleRejectCode>: <message>"` (code-PREFIXED prose, e.g.
+        `"invalid.bare_interpreter_prefix: …"` — never the bare code); a layer whose JSON does not parse is
+        `"settings file is not valid JSON (<error text>)"`; a non-string allow entry is
+        `"settings entry is not a string"`. If you must classify, key on the prefix BEFORE the first `:` and
+        handle the two unprefixed shapes — do not equality-match the whole string and do not expect a bare code.
+
+        ⚠️ `rule` is not always a rule text either: on the unparseable-JSON arm it carries THAT LAYER'S PATH
+        (no entry was parsed, so there is no rule to name). Do not assume a `Bash(...)` shape when rendering.
+      additionalProperties: false
+      required: [rule, reason]
+      properties:
+        rule: { type: string }
+        reason: { type: string }
+
+    CcImportLayerReport:
+      type: object
+      description: >
+        Per-layer read report inside a preview.
+
+        ⚠️ ON THIS HTTP ROUTE `found` IS ALWAYS TRUE. Upstream only writes false when its injected file reader
+        returns undefined or throws, and the server adapter hands back the request's own REQUIRED `content`
+        field — so it can never be absent. Empty text, `{}`, and a file with no allow bucket all still report
+        `found: true` (they simply yield no candidates). Do NOT use `found` as "did this layer contribute
+        rules" — read `candidates` for that. The field is kept because it is part of core's preview shape
+        (it only discriminates for a host whose reader touches a real filesystem).
+      additionalProperties: false
+      required: [path, layer, found]
+      properties:
+        path: { type: string }
+        layer: { $ref: '#/components/schemas/CcImportSettingsLayer' }
+        found: { type: boolean }
+
+    CcImportLayer:
+      type: object
+      description: >
+        One settings layer submitted to rulesCcImportPrepare. The CONTENT is submitted by the caller because a
+        cloud deployment has no access to the user's filesystem — that is the deployment shape, not a bypass:
+        what is read is still only the allow bucket.
+
+        🔴 `root` MUST be non-empty (an empty prefix contains every cwd — see RuleScope). Its TRUTHFULNESS is
+        deliberately NOT validated: the server has no such tree to check against, and pretending to validate
+        would be a lie. It is the user's own label for "which cwds should this rule be live under".
+      # 封闭:server 侧 zod 是 `.strict()`(把 `content` 拼成 `contents` 的客户端应当场 400,而不是拿到
+      # 一份「零候选」的预览去纳闷)。
+      additionalProperties: false
+      required: [layer, path, root, content]
+      properties:
+        layer: { $ref: '#/components/schemas/CcImportSettingsLayer' }
+        path: { type: string, minLength: 1, maxLength: 1024 }
+        root: { type: string, minLength: 1, maxLength: 1024 }
+        content: { type: string, maxLength: 16384, description: 'The layer file''s raw JSON text (16 KiB cap — a settings file is hand-written, not a dataset; the cap keeps this from becoming an upload channel).' }
+
+    CcImportPreview:
+      type: object
+      description: >
+        What the import WOULD do, shown before anyone confirms (core `ImportPreview`).
+
+        `uncovered` is a TWO-KEY RECORD, not a list: the two layers this version does not read are named in the
+        TYPE, so an empty list, a missing member or a duplicate is not expressible. A preview that reported only
+        the layers it read would be claiming a completeness it does not have.
+      additionalProperties: false
+      required: [candidates, skipped, layers, uncovered]
+      properties:
+        candidates:
+          type: array
+          items: { $ref: '#/components/schemas/RuleCandidate' }
+          description: 'What would be persisted, in redemption order.'
+        skipped:
+          type: array
+          items: { $ref: '#/components/schemas/CcImportSkippedRule' }
+          description: 'Entries that did not become candidates. `reason` is PROSE, not a code — see the schema.'
+        layers:
+          type: array
+          items: { $ref: '#/components/schemas/CcImportLayerReport' }
+        uncovered:
+          type: object
+          additionalProperties: false
+          required: [flagSettings, policySettings]
+          properties:
+            flagSettings: { type: string, enum: [not-imported-v1] }
+            policySettings: { type: string, enum: [not-imported-v1] }
+
+    CcImportPrepareResult:
+      type: object
+      description: >
+        The 200 body of rulesCcImportPrepare. NO RULE is in the store yet — the writer is only reached by
+        rulesCcImportRedeem. (A pending approval record and this ticket ARE durable already; see the endpoint
+        description — prepare is not idempotent.)
+      additionalProperties: false
+      required: [preview, ticket, expiresAtMs]
+      properties:
+        preview: { $ref: '#/components/schemas/CcImportPreview' }
+        ticket:
+          type: string
+          description: >
+            The redemption ticket: principal-bound, expiring, atomically single-use, and payload-bound (it pins
+            a digest of the candidate set at mint time, so tampering with the record and redeeming an old ticket
+            fails an equality rather than relying on "only we can write the record"). NOT a cacheable credential;
+            never hand it to another user.
+        expiresAtMs: { type: integer, description: 'Absolute server-clock expiry (the window is 10 minutes — one interaction, not a session).' }
+
+    CcImportResult:
+      type: object
+      description: >
+        What the import ACTUALLY did (core `ImportResult`) — a different moment and a different contract from
+        the preview, because dedup, concurrency and redemption-time validation can each move an entry between
+        the two.
+
+        ⚠️ `skippedAtRedeem` is empty on every success arm of THIS lane: the server treats a non-empty one as
+        INDETERMINATE, releases the claim and answers 503 `state.rule_import_retry` instead of returning a 200
+        that quietly means "half of it did not land". The field stays on the shape because it is core's.
+      additionalProperties: false
+      required: [persisted, deduped, skippedAtRedeem, rev]
+      properties:
+        persisted:
+          type: array
+          items: { $ref: '#/components/schemas/RuleCandidate' }
+        deduped:
+          type: array
+          items: { $ref: '#/components/schemas/RuleCandidate' }
+          description: 'Already in the store — not a failure.'
+        skippedAtRedeem:
+          type: array
+          items: { $ref: '#/components/schemas/CcImportSkippedRule' }
+        rev: { type: integer, description: 'The rule store''s monotonic revision after the batch.' }
+
+    CcImportRedeemResult:
+      type: object
+      description: 'The 200 body of rulesCcImportRedeem.'
+      additionalProperties: false
+      required: [result]
+      properties:
+        result: { $ref: '#/components/schemas/CcImportResult' }
+
+    # ── design/203 §2 撤销面(server 7.12.0)—— 列举行 + 两口的 200 体 ────────────────────────────────
+    # 行形逐字段照 server `src/rules-consent.ts` 的 `PersistedRuleWireRow`(它自己逐字段照 core 的
+    # `PersistedAllowRule`,只把 `scope` 换成判别式串)。
+
+    RuleDot:
+      type: object
+      description: >
+        The immutable causal identity of ONE add — a replica identity plus a monotonic counter (core
+        `RuleDot`). Compared by IDENTITY, never by causal order: single dots minted on different replicas
+        have no order to compare. Treat it as an opaque pair; it is not a timestamp and not a sort key.
+      additionalProperties: false
+      required: [actor, counter]
+      properties:
+        actor: { type: string, description: 'The replica identity that minted this add.' }
+        counter: { type: integer, description: 'That replica''s monotonic counter at mint time. Monotonic PER ACTOR only — never comparable across actors.' }
+
+    RuleAddOrigin:
+      type: string
+      description: >
+        Where ONE add came from (core `RuleAddOrigin`). Stored PER ADD and never folded across dots — a
+        folded provenance could not follow a dot that is later deleted on its own.
+        `user` = minted from an approval card ("don't ask again"); `imported-cc` = redeemed through the
+        CC-settings import lane; `starter` = a deployment-seeded rule.
+        Closed vocabulary on the wire; read it with a default arm anyway (the owner is the engine).
+      enum: [user, imported-cc, starter]
+
+    RuleAdd:
+      type: object
+      description: >
+        ONE add of one logical rule, carrying its own dot and its own provenance (core `RuleAdd`). A rule is
+        LIVE iff at least one of its adds survives the tombstones, which is why this is a SET and not a
+        scalar: the same `(rule, scope)` can be approved several times, from different origins, at different
+        moments. Folding it to a single "addedAt" would make "did I import this or click it?" unanswerable on
+        a governance surface — which is the one place it matters.
+      additionalProperties: false
+      required: [dot, origin, createdAt]
+      properties:
+        dot: { $ref: '#/components/schemas/RuleDot' }
+        origin: { $ref: '#/components/schemas/RuleAddOrigin' }
+        createdAt: { type: string, description: 'When this ADD was recorded (engine-stamped ISO-8601). It dates the add, NOT the rule — a rule with several adds has several of these.' }
+
+    PersistedRule:
+      type: object
+      description: >
+        One LIVE persisted allow rule as `GET /v1/rules` puts it on the wire (server `PersistedRuleWireRow`).
+        Tombstones are already folded — every row here is live at `RuleListResult.rev`.
+        🔴 `scope` is the DISCRIMINANT STRING (`global` / `project:<root>`), NOT the `RuleScope` object the
+        import lane speaks: this is the exact byte sequence the revoke body wants back, so echo it VERBATIM
+        rather than re-serializing a parsed form (an equivalent-but-differently-spelled root matches nothing).
+        The rule lane is ALLOW-only; deny/ask rules are the tightening direction and never appear here.
+      additionalProperties: false
+      required: [rule, scope, tool, match, command, adds]
+      properties:
+        rule: { type: string, description: 'Canonical rule text — `Bash(git status)` (exact) or `Bash(git status:*)` (prefix). Pass back VERBATIM to revoke.' }
+        scope: { type: string, description: 'Scope discriminant string: `global`, or `project:<root>` with a NON-EMPTY root. Pass back VERBATIM to revoke.' }
+        tool: { type: string, enum: [Bash], description: 'The one tool the v1 rule lane speaks for. The field exists so a later version can widen without a shape change — read it, do not assume it.' }
+        match:
+          type: string
+          enum: [exact, prefix]
+          description: '`exact` = this one command only; `prefix` = word-boundary prefix. (core reserves a `wildcard` form for v2 that no current version produces.)'
+        command: { type: string, description: 'What the matcher actually compares against, parsed out of `rule` at mint time and stored so no consumer re-parses. Trust this + `match`, not your own parse of `rule`.' }
+        adds:
+          type: array
+          description: 'Every LIVE add of this rule (see RuleAdd — a real set, deliberately not folded).'
+          items: { $ref: '#/components/schemas/RuleAdd' }
+
+    RuleListResult:
+      type: object
+      description: >
+        The 200 body of `rulesList` — one keyset page plus the revision it was read at.
+        `nextCursor` ABSENT = this was the last page (there is no empty-string sentinel). `rev` is the rule
+        bucket's OCC revision; the cursor is bound to it, so a page fetched with a stale cursor is REFUSED
+        rather than silently restarted.
+      additionalProperties: false
+      required: [rules, rev]
+      properties:
+        rules:
+          type: array
+          description: 'Live rules, ordered `(scope, rule)` lexicographic — a server-decided deterministic order, since keyset paging depends on it.'
+          items: { $ref: '#/components/schemas/PersistedRule' }
+        rev: { type: integer, description: 'The rule bucket''s OCC revision at read time. Bucket-LOCAL: two tenants each holding one rule both read `rev: 1`, so it is not a global clock and not comparable across principals.' }
+        nextCursor: { type: string, description: 'Opaque base64url cursor for the next page. ABSENT ⇒ no further pages. Pass back VERBATIM; do not parse or mint one.' }
+
+    RuleRevokeRequest:
+      type: object
+      description: >
+        The `DELETE /v1/rules` body. A rule is addressed BY CONTENT — there is no id anywhere in this face.
+        Echo `rule` and `scope` VERBATIM from the listing: both are compared as opaque bytes, so an
+        equivalent-but-differently-spelled scope root simply matches nothing (and answers a cheerful `no-op`).
+      # 封闭:server 侧 zod 是 `.strict()` —— 把 `scope` 拼成 `scopes` 的客户端应当场知道,而不是
+      # 拿到一个「删掉了 global 那条」的意外结果。
+      additionalProperties: false
+      required: [rule, scope]
+      properties:
+        rule: { type: string, minLength: 1, maxLength: 1024, description: 'The canonical rule text, VERBATIM as `RuleListResult.rules[].rule` gave it.' }
+        scope: { type: string, minLength: 1, maxLength: 1088, description: 'The scope discriminant string — `global` or `project:<root>` with a NON-EMPTY root (an empty root would match every cwd). VERBATIM as the listing gave it.' }
+        principal: { type: string, minLength: 1, maxLength: 190, description: 'OPERATOR-ONLY cross-tenant revoke. Absent (or your own principal) = revoke your own rule.' }
+
+    RuleRevokeResult:
+      type: object
+      description: >
+        The 200 body of `rulesRevoke`. `removed` = a tombstone was written; `no-op` = nothing matched (an
+        idempotent repeat, or it was never there — deliberately NOT a 404, which would be an existence
+        oracle). BOTH arms carry `stillLive`, and the key set is identical on purpose so one consumer branch
+        reads both.
+      additionalProperties: false
+      required: [status, rev, stillLive]
+      properties:
+        status:
+          type: string
+          enum: [removed, "no-op"]
+          description: 'Whether this call wrote a tombstone. `no-op` says nothing about whether the rule EVER existed — do not render it as "not found".'
+        rev: { type: integer, description: 'The rule bucket''s OCC revision after the operation.' }
+        stillLive:
+          type: boolean
+          description: >
+            🔴 `true` = the rule is STILL LIVE despite this call — under add-wins, an approval recorded during
+            the operation keeps it alive. NEVER tell a human "the rule is gone" without reading this. It rides
+            the `no-op` arm too, because the engine answers `no-op` off its initial snapshot with no read-back,
+            so a concurrent approval leaves the rule alive while the verb reports nothing to remove.
+
+            🔴 THE TWO TRUTH VALUES ARE NOT EQUALLY STRONG, AND THE ASYMMETRY IS IN THE ENGINE, NOT HERE.
+            `true` is positive evidence: something was observed alive. `false` is only "no evidence it
+            survived" — on the `removed` arm the engine performs the confirming read-back inside a `catch`
+            that swallows a failure and reports `false` (core `removePersistedRule`), so a degraded store
+            yields a byte-identical `{status:"removed", stillLive:false}` to a genuinely verified removal.
+            The `no-op` arm does NOT share that hole: the server does that read-back itself and lets a failure
+            surface as a 500 rather than invent an answer. So: act on `true`; when it MATTERS that a rule is
+            really gone (an operator revoking a standing allow), confirm with `GET /v1/rules` instead of
+            treating `false` as proof. Registered upstream — an indeterminate outcome should be its own state
+            rather than folding into `false`.
+
+    # ═══════════════════════════════════════════════════════════════════════════════════════════════
+    # design/183 —— 身份收编(form b:纯身份重绑)。形逐字段照 server `src/adoption/wire.ts` 的 zod
+    # (那份 schema 自陈是「跨仓 wire 契约,下游按字段名逐字钉围栏」)。
+    # ═══════════════════════════════════════════════════════════════════════════════════════════════
+
+    AdoptionRequest:
+      type: object
+      description: 'The POST /v1/adoption body.'
+      additionalProperties: false   # server 侧 `.strict()`:多余键是调用方错误,当场 400(不静默吞)
+      required: [fromPrincipal, toPrincipal]
+      properties:
+        fromPrincipal: { type: string, minLength: 1, maxLength: 190, description: 'The old identity being adopted. Already bound to a DIFFERENT destination ⇒ 409 adoption.source_already_bound (a second adoption / cross-tenant transfer is deliberately out of scope).' }
+        toPrincipal: { type: string, minLength: 1, maxLength: 190, description: 'The EXISTING identity to adopt into (this form mints no credentials). Equal to fromPrincipal ⇒ 400 — that is a mistaken request, not a no-op success, and minting a row would permanently burn that source''s UNIQUE slot.' }
+
+    AdoptionSource:
+      type: object
+      description: 'Where the adoption came from. Form b has exactly one shape — a named principal.'
+      additionalProperties: false
+      required: [kind, principal]
+      properties:
+        kind: { type: string, enum: [principal] }
+        principal: { type: string, minLength: 1 }
+
+    AdoptionLegAction:
+      type: string
+      enum: [bucket-rebind, row-rewrite, carried, none, reset]
+      description: 'The per-store migration verb (closed set; form b only ever emits the first two plus `none`).'
+
+    AdoptionLeg:
+      type: object
+      description: 'One migration leg''s receipt.'
+      additionalProperties: false
+      required: [store, action]
+      properties:
+        store: { type: string, minLength: 1, description: 'Stable leg id = `<table>#<identity column>` (the server schema''s real names — reconcile against it).' }
+        action: { $ref: '#/components/schemas/AdoptionLegAction' }
+        rows:
+          type: integer
+          minimum: 0
+          description: >
+            Rows this leg changed when it RAN. 🔴 NOT a per-request delta and NOT a late-sweep delta: legs are
+            only ever exposed inside `immutableReport`, so on a terminal arc every re-run replays the FROZEN
+            first-run counts (a non-zero value here says nothing about what the current request did). On a
+            `stalled` receipt it is the current row's reading, which can still move.
+        quarantined: { type: integer, minimum: 0 }
+
+    AdoptionConfigEntry:
+      type: object
+      description: >
+        One affected DEPLOYMENT configuration. 🔴 `migrated` is always false on the server half: these live in
+        OTHER deployment units (BFF / cli / env / core declarations) that the adoption cannot reach — and a
+        configuration one cannot change must not be reported as changed. The list being present, plus
+        `migrated:false`, plus an unsettled account, is together the evidence for "configuration does not
+        migrate, stated honestly".
+      additionalProperties: false
+      required: [deployment, key, requiredValue, migrated, ack, witnessedAtMs]
+      properties:
+        deployment: { type: string, minLength: 1 }
+        key: { type: string, minLength: 1 }
+        requiredValue: { type: string }
+        migrated: { type: boolean }
+        ack: { type: boolean, description: 'An operator acknowledgement — RECORD ONLY, it does not settle the account (a hand-written boolean can settle an account into a false green).' }
+        witnessedAtMs:
+          type: [integer, "null"]
+          description: 'When a consumer''s runtime typed receipt actually read `requiredValue` back. 🔴 `null` = not witnessed = NOT settled.'
+
+    AdoptionNotMigratedFace:
+      type: string
+      enum: [usage-window, cost-quota, rate-limit, approval-exemption-grantor, approval-ask-decision-actor, image-bake-requested-by]
+      description: >
+        FROZEN machine-readable vocabulary of the faces the server deliberately does not migrate. Renaming or
+        removing a member is a wire break; adding one is a new behaviour face. Consumers assert POSITIVELY on
+        these so that "not migrated by design" and "forgotten" stay distinguishable in a black box.
+
+    AdoptionNotMigrated:
+      type: object
+      description: 'One positive "by design, not migrated" declaration.'
+      additionalProperties: false
+      required: [face, ruling, reason]
+      properties:
+        face: { $ref: '#/components/schemas/AdoptionNotMigratedFace' }
+        ruling: { type: string, enum: [D1, D2], description: 'design/183 §12 ruling id — D1 = quota windows restart and recount; D2 = a historical field is never rewritten.' }
+        reason: { type: string, minLength: 1 }
+
+    AdoptionReport:
+      type: object
+      description: >
+        The adoption report.
+
+        🔴 "IMMUTABLE" HOLDS ONLY ONCE `status` IS `adopted`. The frozen row is written once at the final phase
+        and replayed byte-for-byte thereafter, never recomputed — that byte-identity IS the idempotency
+        criterion. But a `stalled` receipt has no such row yet, so the server PROJECTS a same-shaped report
+        from the CURRENT row (`atMs` = the row's updated-at, configs/legs = the current columns). That
+        projection is provisional: the next read can differ in every field. Do NOT persist a `stalled`
+        report as audit evidence — take the frozen one after `status === "adopted"`. The two share one shape
+        by upstream ruling (there is only one envelope); the discriminator is `status`, not the field name.
+      additionalProperties: false
+      required: [adoptionId, form, from, toPrincipal, atMs, affectedDeploymentConfigs, legs, notMigratedByDesign]
+      properties:
+        adoptionId: { type: string, minLength: 1 }
+        form: { type: string, enum: [b], description: 'This version only does form b (pure identity rebind). Present explicitly so a later form-a receipt is distinguishable without inferring from an absent key.' }
+        from: { $ref: '#/components/schemas/AdoptionSource' }
+        toPrincipal: { type: string, minLength: 1 }
+        atMs: { type: integer, minimum: 0 }
+        affectedDeploymentConfigs:
+          type: array
+          items: { $ref: '#/components/schemas/AdoptionConfigEntry' }
+        legs:
+          type: array
+          items: { $ref: '#/components/schemas/AdoptionLeg' }
+        notMigratedByDesign:
+          type: array
+          items: { $ref: '#/components/schemas/AdoptionNotMigrated' }
+
+    AdoptionCurrent:
+      type: object
+      description: 'Recomputed on every read (the counterpart to AdoptionReport''s frozen history — do not infer one from the other).'
+      additionalProperties: false
+      required: [outstandingConfigs, quarantined, residualSourceRows]
+      properties:
+        outstandingConfigs:
+          type: array
+          items: { type: string }
+          description: 'Config entries whose `witnessedAtMs` is null, as `<deployment>:<key>`. Empty = the account is settled.'
+        quarantined: { type: integer, minimum: 0, description: 'Always 0 for form b (zero carriage ⇒ no rejected rows). The field is present so the envelope does not change shape when form a arrives.' }
+        residualSourceRows:
+          type: integer
+          minimum: 0
+          description: >
+            Rows STILL under the old identity, recomputed on every read. AGGREGATION: counted PER TABLE with
+            the table's identity axes unioned, so a row carrying the old identity on two or three axes counts
+            ONCE; the per-table counts are then summed. It is deliberately NOT a sum over legs — reconciling
+            this number against per-leg `rows` will not add up.
+
+            🔴 Load-bearing: adoption does NOT fence ordinary writers ("stop the engine first" is an operator
+            precondition, not a machine guarantee), so a caller still injecting the old identity keeps writing
+            rows after the terminal state while the idempotent short-circuit keeps answering `adopted`. So `> 0`
+            means "rows may still sit under the old identity, OR the count could not be taken" — either way, GO
+            LOOK. It is NOT proof that the deployment is actively writing. A POST also sweeps those late rows in
+            and re-reports this; a GET does not sweep (though it does resume an in-flight arc — see the GET
+            description).
+
+            ⚠️ `1` IS AMBIGUOUS. When the count itself fails (query error / parse failure) the server reports
+            `1` fail-closed rather than `0`, because `0` is the literal assertion "everything is clean" and it
+            has not earned the right to say that. So `1` may mean "one residual row" OR "could not measure";
+            the wire cannot tell them apart (the server log carries `adoption_residual_count_failed`). Use it
+            as intended — `> 0` ⇒ GO LOOK — but never feed `=== 1` to a report as the exact number of rows.
+
+    AdoptionReceipt:
+      type: object
+      description: >
+        The ONE adoption receipt envelope — the same SHAPE for the first success and for every idempotent
+        re-run. No second receipt shape exists anywhere.
+
+        ⚠️ Same shape carries NO byte-identity guarantee: `current` is recomputed on every call (residual
+        count, config ledger) so two reads may match or may differ, and before the terminal state
+        `immutableReport` is itself a provisional projection. The one thing guaranteed frozen is a TERMINAL
+        `immutableReport`.
+
+        🔴 `adoptionId` is at the TOP LEVEL (the server sends `{adoptionId, ...receipt}`), carrying the same
+        value as `immutableReport.adoptionId`.
+        🔴 `status` is a TWO-WORD closed set. `rejected` is deliberately NOT a member: a refused adoption never
+        produces a receipt, it answers a typed 409 — otherwise "refused" and "succeeded" would share one 200
+        envelope and a consumer could only guess by reading fields.
+        🔴 `status` is ALSO the precondition for reading `immutableReport`: it is frozen only once `adopted`;
+        on `stalled` it is a provisional projection of the current row (see AdoptionReport).
+      additionalProperties: false
+      required: [adoptionId, status, immutableReport, current]
+      properties:
+        adoptionId: { type: string, minLength: 1 }
+        status: { type: string, enum: [adopted, stalled], description: '`adopted` = the terminal state is in place (and only then is `immutableReport` frozen); `stalled` = in flight (the lock is held by another replica, or a crashed run has not been resumed yet). Not a failure.' }
+        immutableReport:
+          allOf: [{ $ref: '#/components/schemas/AdoptionReport' }]
+          description: 'Frozen ONLY when `status` is `adopted`; on `stalled` it is a provisional projection of the current row — do not persist it as audit evidence.'
+        current: { $ref: '#/components/schemas/AdoptionCurrent' }