@sema-agent/sdk 6.11.0 → 6.13.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,242 @@ 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/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]
@@ -4927,8 +5268,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:
@@ -4968,6 +5313,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 +5396,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 +5549,25 @@ 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 (/v1/rules/cc-import/* plus the respond persistRule redemption arm)
+            is available. Server predicate = PERMISSION_RULES_ENABLED=true AND the rule store is wired
+            (default OFF => false; the revocation face is a prerequisite for enabling).
+        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." }
@@ -6025,6 +6407,8 @@ components:
         status: { type: string, description: 'the TaskResult''s terminal status (open vocabulary; core enum verbatim).' }
         error: { type: string, description: 'first line of errorMessage, clipped to 300 chars (redacted). Present only when the result carried an errorMessage.' }
         result: { type: string, description: 'the result text, clipped to 2000 chars (redacted). Present only when the result carried one.' }
+        resultTruncated: { type: boolean, description: 'server >=7.9.0 (A-002.6): present (true) only when `result` was clipped at 2000 chars — the disclosure twin of the >64KiB whole-row truncated arm; absent = the result field is complete.' }
+        resultChars: { type: integer, description: 'server >=7.9.0 (A-002.6): the ORIGINAL result length in characters; present only alongside resultTruncated.' }
         tokens: { type: integer, description: 'present only when the result carried stats.' }
         turns: { type: integer, description: 'present only when the result carried stats.' }
 
@@ -8148,6 +8532,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]
@@ -8267,11 +8689,80 @@ 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.
+      enum:
+        - no-candidates
+        - unknown-candidate
+        - confirm-refused
+        - redeem-refused
+        - rule_lane_unavailable
+        - rule_input_edited
+        - rule_not_offered
+        - rule_store_error
+
     ApprovalRiskAxes:
       type: object
       description: >
@@ -9585,7 +10076,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:
@@ -9604,6 +10098,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
@@ -9828,3 +10340,358 @@ 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/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' }