@sema-agent/sdk 11.0.1 → 11.2.0

package/openapi.yaml

@@ -62,6 +62,14 @@ openapi: 3.1.0
 #             `test/live/route-existence.test.ts` (a planned path must have NO handler in the pinned
 #             server artifact). Both exist because `POST /v1/tasks/{taskId}/asks/{askId}/decision` kept
 #             this label for two server releases after it went live.
+#   ahead   — implemented server-side, but in a version NEWER THAN THE PINNED ARTIFACT this repo's contract
+#             suite runs against (the SDK ships the verb in the same train — "the SDK is never behind the
+#             server"). DISTINCT FROM `planned`, which claims the server has NOT implemented it: an `ahead`
+#             face is real, has a named server version, and HAS a verb here calling it. Two gates police the
+#             pair so neither word can hide the other — `test/live/route-existence.test.ts` (an `ahead` path
+#             must have NO handler in the pinned artifact; the day it appears, flip this label to `live`/
+#             `gated`) and `spec-path-drift-gate` (every `ahead` path must be one the SDK actually calls —
+#             an `ahead` nobody calls is a mislabeled `planned`). It EXPIRES the same way `planned` does.
 #   gated   — implemented but off by a server deploy flag (e.g. leader, STREAM_APPROVAL_ENABLED); answers
 #             501 where the flag/deps are unmet. Says nothing about the flag's DEFAULT — that can differ
 #             per server version, so read the matching `capabilities` bit, never this label.
@@ -230,6 +238,170 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/ErrorResponse' }
 
+  # ── S-481(server >= 7.93.0;core 7.26.0 `probeMcpServers`)—— 无 run 可读的逐台 MCP 状态面,两条口一套词表 ──
+  /v1/capabilities/mcp:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    get:
+      tags: [metrics]
+      operationId: mcpCapabilities
+      x-status: ahead           # server main 955fdbf0 routes/capabilities.ts `capability-mcp`(server 7.93.0,未上 npm ⇒ 钉版 7.92.2 产物里没有);SDK client.mcpCapabilities() 消费。钉版抬到 ≥7.93.0 当天改 `live`。
+      summary: Per-server MCP status for THIS deployment's own declared servers — dialed now, with no run.
+      description: >
+        What this deployment's OWN configured MCP servers answer RIGHT NOW, one row per declaration. It exists
+        because a session that never started a run had no face at all: `capabilities.mcp` is a single boolean, so a
+        shell's one-shot command had to dial and invent its own words — and then disagreed with the interactive
+        lane about the same server (a command line reporting Failed while that server's tools worked in a session).
+
+        🔴 THE ROWS ARE NOT MINTED HERE. `servers[]` is the engine's `probeMcpServers` entries through the SAME
+        projection a prepared leg pushes onto `wiring_manifest.mcp[]` — same mint point, same failure vocabulary.
+        So a row here and a row in that run are the same KIND of thing, not two things that look alike; every
+        clause of `WiringManifestMcpEntry` holds verbatim, including the deliberate ABSENCE of the engine's
+        `error` free text (the actionable cause is `errorCode`).
+
+        🔴 VISIBLE SET = THIS DEPLOYMENT'S DEFAULT SCENARIO (the same filter `resolveSpec` uses), NOT "what that
+        run would actually mount": on a deployment whose scenarios carry different MCP labels, or that decides
+        scenarios per principal, the two differ. There is no `?scenario=` on this face today — ask a run's own
+        manifest for another scenario. Per-principal authorization is decided at the MCP server by the injected
+        `principalHeader`, not filtered here.
+
+        🔴 ZERO DECLARATIONS = `200` with `servers: []` (an honest empty face — NOT a 404, NOT a 501). Probing is a
+        REAL DIAL, so the face is rate-limited per caller identity (12/60s per replica) with a 30s reuse window
+        (`ttlSec`; a cache hit does not count against the limit and returns the ORIGINAL `probedAt`). Gate on
+        `capabilities.mcpProbe` — absent means an older worker where this path does not exist (404
+        `not_found.route`), not "this deployment has no MCP".
+      responses:
+        '200':
+          description: 'The per-server readings (see `McpProbeFace`); an empty `servers` array = this deployment declared none.'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/McpProbeFace' }
+        '401':
+          description: >
+            THREE codes land here and they do NOT share one typed class, so branch on `errorCode`:
+            `auth.unauthorized` (the worker-wide service-credential gate, before this route),
+            `auth.principal_required` (the principal header is absent while `REQUIRE_PRINCIPAL` is on — same gate as
+            `GET /v1/sessions/{id}/mcp`), and `principal_unverified` (the header WAS sent and failed verification —
+            a DIFFERENT action: fix the token/signing, not the header). A consumer that only handles the `auth.*`
+            family silently misses the third.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '429': { $ref: '#/components/responses/RateLimited' }       # limit.rate_exceeded — 12/60s per identity, OR the replica-wide in-flight cap (32, ACROSS identities: one caller can be refused because of another). Retry-After and the body's `retryAfterSec` are the same value; the body's absence means no header either
+        '500':
+          description: >
+            errorCode `internal.error` — the engine refused THIS DEPLOYMENT'S declaration SET as a whole (the one
+            documented cause: two servers would mount under the same tool-namespace prefix, refused BEFORE any
+            transport is touched). 🔴 WHOEVER WROTE THE DECLARATIONS OWNS THE ERROR: on this door they are the
+            deployment's, so this machine's configuration is broken and a 5xx is the honest direction — folding it
+            into a 4xx would report an operator's mistake as the caller's. The cause is NOT echoed (it comes from
+            the declaration set itself); it is in this worker's logs. Retrying does not change it.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '503':
+          description: >
+            errorCode `state.mcp_probe_incomplete` — the WHOLE walk did not settle within this face's bound
+            (derived from the declaration count: `ceil(n / 8) x 10s + 4s`, so 1 server = 14s and 32 = 44s). 🔴 THIS
+            FACE HAS NO `degraded` ARM ON PURPOSE: a probe that cannot answer must not return a normal-looking
+            empty list, which is exactly the false answer it exists to remove. A retry MAY succeed. ⚠️ The
+            abandoned dial can outlive the request (the engine's dial does not own cancellation).
+          headers:
+            Retry-After: { schema: { type: integer }, description: 'Suggested wait; a HINT, not a promise.' }
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
+  /v1/capabilities/mcp/probe:
+    parameters:
+      - $ref: '#/components/parameters/PrincipalHeader'
+    post:
+      tags: [metrics]
+      operationId: mcpProbe
+      x-status: ahead          # server main 955fdbf0 routes/capabilities.ts `capability-mcp-probe`(server 7.93.0,未上 npm);门 = mcpInjectionHonored ⇒ 钉版抬到 ≥7.93.0 当天改 `gated`(不是 live:它有 501 腿)。SDK client.probeMcp() 消费。
+      summary: Probe the CALLER'S OWN MCP declarations (the shell's .mcp.json) — same body shape as a submission.
+      description: >
+        The caller-declared twin of `mcpCapabilities`: it dials the servers in the request body and answers with
+        the SAME body shape, so one consumer rendering reads both faces.
+
+        🔴 THE GATE IS `capabilities.mcpInjection` (the SAME predicate the task-submission leg uses): a
+        multi-tenant worker, an administratively locked `mcp` config key, or a compliance posture that denies
+        `mcp_servers` each refuse the whole call with 501 `capability.mcp_injection_required`. ⚠️ DELIBERATELY
+        UNLIKE the submission leg, which IGNORES an unhonored `mcpServers` (plus a user-facing notice) — a probe
+        asks "can I use these", so the answer must be loud.
+
+        🔴 THE BODY IS CLOSED AND A BAD ENTRY REFUSES THE WHOLE LIST. Top level accepts `mcpServers` only; entry
+        keys and both `transport` key sets are closed (the vocabulary is pinned to the engine's `McpServerSpec`
+        in both directions). An out-of-vocabulary key is 400 `request.body_shape` with `unknownKeys` naming the
+        KEY PATHS verbatim (`mcpServers[0].transport.header`); a bad value (a non-http(s) url, a `transport.kind`
+        outside the closed set, a `contentOrigin` outside its vocabulary, more than 32 declarations) is 400
+        `request.field_invalid`. ⚠️ Again unlike the submission leg, which names and DROPS a bad entry while
+        mounting its siblings: quietly removing the problem entry and returning a good-looking list is the false
+        answer this face exists to remove. A refusal may echo a url, always through the display-safe mint point
+        (no userinfo on the wire); a SUCCESS body carries no url at all (the row shape has no `url`/`headers`/`env`).
+
+        Rate limit, reuse window and the in-flight cap are shared with `mcpCapabilities` — see that operation.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              description: >
+                The declaration list to probe — the SAME shape a task submits (`TaskRequest.mcpServers`), which is
+                why the key has that name and the element is the very same schema. Closed: any other top-level key
+                is a 400 `request.body_shape`.
+              required: [mcpServers]
+              additionalProperties: false
+              properties:
+                mcpServers:
+                  type: array
+                  maxItems: 32
+                  items: { $ref: '#/components/schemas/McpServerSpec' }
+                  description: 'At most 32; index-aligned with `McpProbeFace.servers`.'
+      responses:
+        '200':
+          description: 'The per-server readings — the SAME body as `mcpCapabilities` (see `McpProbeFace`).'
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/McpProbeFace' }
+        '400': { $ref: '#/components/responses/BadRequest' }        # request.body_shape (closed-key refusal; body carries `unknownKeys` = the offending KEY PATHS) / request.field_invalid (bad value, over the 32-declaration ceiling, or the engine refused the declaration SET — two servers under one tool-namespace prefix; that cause is NOT echoed) / request.rejected (the body is not parseable JSON — the status-derived coarse code from the body READER, which runs before the closed-key door, so it is NOT `request.body_shape`)
+        '401':
+          description: >
+            Same three codes as `mcpCapabilities`, same reason to branch on `errorCode`: `auth.unauthorized`
+            (service-credential gate), `auth.principal_required` (header absent under `REQUIRE_PRINCIPAL`), and
+            `principal_unverified` (header sent, verification failed — fix the token, not the header). They do not
+            share one typed class.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '413':
+          description: >
+            errorCode `request.payload_too_large` — the request body is over this worker's cap. It comes from the
+            body READER (before this route's closed-key door), so it carries no `unknownKeys`. Shorten the
+            declaration list and resend; resending the same bytes never succeeds.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '429': { $ref: '#/components/responses/RateLimited' }       # limit.rate_exceeded — per-identity window OR the replica-wide in-flight cap; see mcpCapabilities
+        '501':
+          description: >
+            errorCode `capability.mcp_injection_required` — this deployment does not honor caller-supplied MCP
+            declarations (multi-tenant, or `mcp` is a locked config key, or the compliance posture denies
+            `mcp_servers`; the refusal names which). Read `capabilities.mcpInjection` BEFORE asking — do not
+            trial-by-501. `mcpCapabilities` (this deployment's OWN declared servers) stays available either way.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+        '503':
+          description: >
+            errorCode `state.mcp_probe_incomplete` — identical to `mcpCapabilities`'s 503 (see there).
+          headers:
+            Retry-After: { schema: { type: integer }, description: 'Suggested wait; a HINT, not a promise.' }
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+
   /v1/tasks:
     parameters:
       - $ref: '#/components/parameters/PrincipalHeader'
@@ -5371,17 +5543,20 @@ paths:
         '429': { $ref: '#/components/responses/RateLimited' }
         '503':
           description: >
-            errorCode `state.rule_write_failed` — this call CANNOT CONFIRM that the rule now stands. Store
-            jitter and a redemption leg that returned no decidable outcome are INDISTINGUISHABLE here, and both
-            available lies ("nothing was written" / "it is standing") would mislead the next step. Retry, then
-            reconcile with `GET /v1/rules`. ⚠️ NARROWED AT server 7.92.2: "the write landed and was revoked
+            errorCode `state.rule_write_failed` — the write did not complete. 🔴 WHAT TO DO NEXT IS IN THE BODY'S
+            `committed` KEY (server >= 7.93.0), and the two words say opposite things: `no` = the store answered
+            and nothing landed ⇒ resend the same body verbatim; `unknown` = it cannot be proven ⇒ reconcile with
+            `GET /v1/rules` FIRST. Do not derive it from the sentence — on servers <= 7.92.2 the two strengths are
+            byte-identical here and the one sentence says "retry, then reconcile", which is the wrong order for
+            `unknown`. Word table and per-word disposition: `RuleWriteFailedBody.committed`.
+            ⚠️ NARROWED AT server 7.92.2: "the write landed and was revoked
             concurrently before the read-back" NO LONGER ARRIVES HERE — that shape has an answer (200 +
             `stillLive: no`), and retrying it would re-erect a tightening someone just revoked. (Also `auth.service_token_required` on a deployment with no service credential
             and no explicit `ALLOW_UNAUTHED_WRITES=true` — the write-door credential precondition, shared with
-            the other rule write faces.)
+            the other rule write faces; THAT refusal carries no `committed`, so read `errorCode` first.)
           content:
             application/json:
-              schema: { $ref: '#/components/schemas/ErrorResponse' }
+              schema: { $ref: '#/components/schemas/RuleWriteFailedBody' }
         '501': { $ref: '#/components/responses/NotImplemented' }    # capability.rule_store_required
     delete:
       tags: [rules]
@@ -5409,9 +5584,11 @@ paths:
         alias). 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
+        answers `no-op` off its initial snapshot, so an approval landing between that snapshot and the response
         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.
+        set and one consumer branch reads both — and since server 7.93.0 the same VALUE RANGE as well:
+        `no-op` + `unknown` is REACHABLE (that arm now reads the same liveness read-back as `removed`, instead of
+        the server taking its own and 5xx-ing when it failed). See `RuleRevokeResult.stillLive`.
 
         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
@@ -5436,13 +5613,19 @@ paths:
         '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`.
+            errorCode `state.rule_remove_failed` — the tombstone did not land. 🔴 WHICH OF THE TWO STRENGTHS IT
+            WAS IS IN THE BODY'S `committed` KEY (server >= 7.93.0 — the SAME key, word set and mint point as
+            `rulesWrite`): `no` = the store answered and nothing landed ⇒ resend the same body verbatim;
+            `unknown` = the apply threw or the read-back did not complete ⇒ reconcile with `GET /v1/rules` FIRST
+            (a blind retry can re-erect a tightening somebody just revoked). Both are 503 rather than 500 because
+            they speak about THIS attempt, not about whether a retry can ever succeed. Word table and per-word
+            disposition: `RuleWriteFailedBody.committed`; on servers <= 7.92.2 the key is absent and the two
+            strengths are indistinguishable here. (Also `auth.service_token_required` on a deployment with no
+            service credential and no explicit `ALLOW_UNAUTHED_WRITES=true` — this verb is in the credential-gated
+            write family too; THAT refusal carries no `committed`, so read `errorCode` first.)
           content:
             application/json:
-              schema: { $ref: '#/components/schemas/ErrorResponse' }
+              schema: { $ref: '#/components/schemas/RuleWriteFailedBody' }
         '501': { $ref: '#/components/responses/NotImplemented' }    # capability.rule_store_required
 
   # ── design/183 —— 身份收编面(form b:纯身份重绑)。operator-only 的一次性部署级动作,零模型工作。 ──
@@ -8036,6 +8219,20 @@ components:
         projectContext: { type: boolean, description: "Project-context injection is wired." }
         mcp: { type: boolean, description: "MCP servers can be attached." }
         mcpInjection: { type: boolean, description: "Per-request MCP injection is accepted." }
+        mcpProbe:
+          type: boolean
+          description: >
+            server >= 7.93.0 (S-481) — the no-run per-server MCP status face is present: `GET /v1/capabilities/mcp`
+            (this deployment's OWN declared servers) and `POST /v1/capabilities/mcp/probe` (the CALLER'S
+            declarations). ALWAYS TRUE where it exists, for the same reason as `mcp`: the GET has no 501 arm
+            (zero declarations answer an honest empty face), so "says yes" iff "the route works" is structural.
+            PRESENT-IFF carries the version: ABSENT = an older worker with no such face (fall back to the
+            session replay leg `McpStatusPanel.lastLegMcp`, or show the human the real cause row).
+            🔴 TWO BITS, TWO QUESTIONS — DO NOT MERGE: whether the CALLER-declared door works is answered by
+            `mcpInjection` (the same `mcpInjectionHonored` predicate IS that route's gate; multi-tenant, a
+            locked `mcp` key, or a compliance posture denying `mcp_servers` each yield 501
+            `capability.mcp_injection_required`). So `mcpProbe: true` beside `mcpInjection: false` is the
+            NORMAL multi-tenant reading, not a contradiction.
         mcpElicitation: { type: boolean, description: "MCP elicitation round-trips are supported." }
         askUserQuestion: { type: boolean, description: "AskUserQuestion gate is available (durable when approvals are)." }
         toolApproval: { type: boolean, description: "Tool-approval gating is active." }
@@ -12412,6 +12609,74 @@ components:
             WHO ASKED. Same-present/same-absent as `settlement` (I1). CLOSED here (and only here) — see the
             enum note above.
 
+    McpProbeFace:
+      type: object
+      description: >
+        The body of the no-run per-server MCP status face — BYTE-FOR-BYTE THE SAME for `mcpCapabilities` (GET) and
+        `mcpProbe` (POST), so one consumer rendering reads both (S-481, server >= 7.93.0).
+
+        🔴 THE ROWS ARE NOT MINTED BY THIS FACE: `servers[]` is `WiringManifestMcpEntry` — the engine's
+        `probeMcpServers` entries through the SAME projection a prepared leg pushes onto `wiring_manifest.mcp[]`.
+        🔴 `servers[]` IS INDEX-ALIGNED with the declaration list (same order, same length; engine contract
+        `mcp.probe.index_aligned`): a failed, timed-out or never-dialed server STILL HOLDS ITS POSITION. Pair it
+        with your own declaration list BY INDEX, never by `name` — names are not guaranteed unique.
+        🔴 NO `degraded` ARM, DELIBERATELY (unlike `McpStatusPanel.degraded`): a probe that cannot answer returns a
+        LOUD 503 `state.mcp_probe_incomplete`, never a normal-looking empty list. ⚠️ `servers: []` is a different
+        thing entirely — an honest empty face (this deployment declared nothing).
+      required: [probedAt, ttlSec, servers]
+      additionalProperties: false
+      properties:
+        probedAt:
+          type: string
+          description: 'WHEN this reading is from (ISO). 🔴 A cache hit returns the ORIGINAL instant — a reused answer pretending to be fresh is a false fact.'
+        ttlSec:
+          type: integer
+          description: 'How long this reading may be reused (seconds; 30s per identity + declaration set server-side). A hit inside the window does NOT count against the rate limit.'
+        servers:
+          type: array
+          items: { $ref: '#/components/schemas/WiringManifestMcpEntry' }
+          description: 'One row per declaration, SAME ROW SHAPE as the wiring manifest, index-aligned (see this schema''s description).'
+
+    McpLivenessState:
+      type: string
+      enum: [reachable, unreachable, unknown]
+      description: >
+        The engine's CLOSED three-word answer to ONE question, "can this client complete an exchange with this
+        server" (core `MCP_LIVENESS_STATES`; the vocabulary's single owner is the engine, mirrored here the same way
+        `McpDelivered` is): `reachable` = an exchange COMPLETED (handshake + list, a successful re-dial, or the
+        server itself answered — an MCP-level rejection IS an answer, so it proves reach even though the call
+        failed); `unreachable` = an exchange was attempted and LOST at the transport or the clock (refused, reset,
+        closed, unspawnable, timed out); `unknown` = an exchange was attempted and what came back DOES NOT ANSWER
+        the question (a status some gateway wrote, a non-MCP payload, a thrown value with no structure this table
+        reads).
+        🔴 ABSENCE OF THE WHOLE `liveness` RECORD is a FOURTH reading and is NOT one of these words — see
+        `WiringManifestMcpEntry.liveness`. Do not fold an absent record into `unknown`.
+
+    McpServerLiveness:
+      type: object
+      description: >
+        ONE liveness OBSERVATION about one MCP server (core 7.24.3 #874 `McpServerLiveness`). It says what the
+        engine last LEARNED and WHEN — never what is true now, and NEVER a poll: the engine makes no probe of its
+        own, so every record is a by-product of work the leg already did (the dial, a re-dial, a transport close).
+        🔴 `state` + `observedAt` ARE BOTH LOAD-BEARING — together they are one sentence (what was seen, and when);
+        the server's projection drops the WHOLE record when either half fails its shape check, so a record that
+        arrives has both.
+        🔴 `errorCode` RIDES `unreachable` ONLY: on `unknown` it is deliberately absent, because the whole point of
+        that word is that the failure did NOT decide reachability — carrying a failure class there invites a
+        consumer to key a reconnect action off evidence that says nothing about reach.
+      required: [state, observedAt]
+      additionalProperties: false
+      properties:
+        state:
+          allOf: [{ $ref: '#/components/schemas/McpLivenessState' }]
+          description: 'WHAT the engine last learned (the closed three-word table — see `McpLivenessState`).'
+        observedAt: { type: integer, description: 'When that observation happened (epoch ms).' }
+        errorCode:
+          type: string
+          description: >
+            The failure class that decided `unreachable` (the engine's `McpFailureKind` word — deliberately NOT
+            enumerated here; the vocabulary's owner is the engine). Absent on the other two words.
+
     McpDelivered:
       type: string
       description: >
@@ -14777,6 +15042,47 @@ components:
         can never be accepted. The retry fetches the FINAL ROUTING INFO (poll until the 410 hands over the gate
         coordinates). Carries NO gate coordinates — they are not written until the batch binds.
 
+    RuleWriteFailedBody:
+      allOf:
+        - $ref: '#/components/schemas/ErrorResponse'
+        - type: object
+          properties:
+            committed:
+              type: string
+              enum: [no, unknown]
+              description: >-
+                DID THIS WRITE LAND? The engine's closed word pair, passed through VERBATIM (the server neither
+                enumerates, folds, nor translates it), and THE TWO WORDS HAVE OPPOSITE DISPOSITIONS:
+                `no` = the store answered and NOTHING landed (no write face / the shape test refused this target /
+                the read before the write failed / preflight refused / an epoch seal / every compare-and-set lost)
+                ⇒ RESEND THE SAME BODY VERBATIM — no second dot can be minted and no just-revoked tightening can
+                be re-erected, so you do NOT need to reconcile first.
+                `unknown` = it cannot be proven — the apply THREW (the engine may have committed and then lost its
+                acknowledgement), or the read-back that would have settled it could not be taken ⇒ 🔴 RECONCILE
+                WITH `GET /v1/rules` FIRST, then decide whether to resend. A blind retry can mint a second dot and
+                re-erect a tightening somebody just revoked.
+                ⚠️ A READ-BACK FAILURE DOES NOT FLIP THE WORD, it only fails to improve it (engine 7.26.0's own
+                declaration): whatever the apply earned stands — a throw stays `unknown`, an ANSWERED
+                compare-and-set stays `no`, "because an unreadable store cannot un-answer what the store already
+                said". So `no` is never a guess about an unreadable store.
+                🔴 BRANCH ON THIS KEY, NEVER REGEX THE MESSAGE: the two English sentences change with
+                readability edits, this word does not. Both words are 503 (they say whether THIS write landed,
+                not whether a retry can ever succeed).
+                🔴 ABSENT ON SERVERS <= 7.92.2 (added at server 7.93.0 / core 7.26.0): on that generation the two
+                strengths were BYTE-IDENTICAL on the wire and the single sentence said "retry, then reconcile" —
+                which is the wrong order for `unknown`. The SDK forges no default for an absent key: read it
+                through `APIError.extra` and treat absence as "this server cannot tell you".
+      description: >
+        The 503 body of `rulesWrite` and `rulesRevoke` — ONE shape for both verbs, because `committed` is one key
+        off one closed word set minted in ONE place server-side (`sendRuleWriteFailure`), and a consumer branches
+        on it identically for either verb.
+        🔴 `committed` IS CONDITIONAL ON `errorCode`, hence NOT `required`: the same 503 slot also carries
+        `auth.service_token_required` (both verbs sit in the credential-gated write family — a deployment with no
+        service credential and no explicit `ALLOW_UNAUTHED_WRITES=true` never reaches the rule lane), and that
+        refusal has no `committed` key. Read `errorCode` first.
+        ⚠️ `committed` answers "did THIS write land"; `stillLive` (on the 200 bodies) answers "is the rule
+        standing NOW". Two different questions, two different keys, neither derives the other.
+
     ApprovalFrameEnvelope:
       type: object
       description: >
@@ -16237,6 +16543,18 @@ components:
             core >= 7.6.0 (S6-B) — the status the endpoint answered with; rides ONLY with
             `errorCode === "http_status"` (401/403 = re-authorize, 5xx = that end is down). ABSENT rather
             than 0.
+        liveness:
+          allOf: [{ $ref: '#/components/schemas/McpServerLiveness' }]
+          description: >
+            core >= 7.24.3 (#874), server >= 7.91.2 — the engine's LAST OBSERVATION of reachability.
+            🔴 SEPARATE FROM `status`: `status` is the verdict at dial time (the engine freezes it), this is what
+            the connection layer last LEARNED — so `failed` beside `reachable` on one row is a REAL row (the server
+            answered the handshake and answered with a protocol error = alive and misconfigured).
+            🔴 ABSENCE IS NOT `unknown`: absent = NO USABLE OBSERVATION EXISTS (the leg never reached this server,
+            the declaration was never dialed, an older mint, or the record failed its shape check), while `unknown`
+            is the engine's STRONGER claim (it looked and the answer does not decide reach). Do not infer "was it
+            dialed" from absence. Declared here as of sdk 11.2.0 — the key had been on the wire since server 7.91.2
+            while this row schema stayed closed, so a strict consumer was rejecting a LEGITIMATE response.
 
     ServerWiringGates:
       type: object
@@ -17372,9 +17690,19 @@ components:
         current state with `GET /v1/rules` instead.
 
 
-        `unknown` — DOES NOT OCCUR ON THIS DOOR (a read-back that cannot be taken is a 5xx: a write whose
-        outcome cannot be told does not answer 200). That is why each arm narrows the shared three-word table
-        to its own single word with an `enum`; the table itself is NOT forked.
+        `unknown` — REACHABLE SINCE server 7.93.0: the write LANDED (the engine confirmed the add and handed
+        back a real `rev`) and THE READ-BACK THAT WOULD ANSWER LIVENESS COULD NOT BE TAKEN (the store did not
+        answer). `rule` is ABSENT. 🔴 SAME DISPOSITION AS `no` — DO NOT RETRY (a resend only answers `no-op`);
+        reconcile with `GET /v1/rules`. Up to 7.92.2 this shape answered 500 `internal.error`, byte-identical
+        to the one a PRE-write store failure produced — two opposite dispositions under one answer, which is
+        exactly what these keys exist to separate. ⚠️ A store failure BEFORE the write is a different answer:
+        503 `state.rule_write_failed` with `committed: "no"` (provably nothing landed ⇒ resending the same body
+        is safe). Same store outage, opposite handling, decided by WHICH SIDE of the write it happened on.
+
+
+        ⇒ THE TWO ROWLESS WORDS SHARE ONE ARM (`RuleWriteResult_rowless`): identical key set, identical
+        disposition; the WORD is what distinguishes "observed gone" from "nobody looked". The shared
+        three-word table is narrowed per arm with an `enum` and is NEVER forked.
 
 
         🔴 READ `stillLive` FIRST, THEN `rule`. The `rule` KEY LIVES ONLY ON THE `yes` ARM — it is not "present
@@ -17389,22 +17717,28 @@ components:
         passed through verbatim). A shell that must span both generations reads an ABSENT `stillLive` AS `yes`
         itself — that is its own judgement about its own deployment, not something this door said.
       oneOf:
-        - $ref: '#/components/schemas/RuleWriteResult_yes'
-        - $ref: '#/components/schemas/RuleWriteResult_no'
+        - $ref: '#/components/schemas/RuleWriteResult_live'
+        - $ref: '#/components/schemas/RuleWriteResult_rowless'
       # 🔴 两支是**命名 schema**,不是内联形(codex 对抗复审 [medium],验真后修):OAS 3.1 的
       # discriminator 明文**不考虑内联 schema**,而 mapping 指回父联合就等于「选不出臂」——
       # 照它生成/解码的消费方拿不到分支,而普通 oneOf 校验照样绿,坏形因此不可见。
+      # 🔴 **两支按「有没有活行可端」命名**(sdk 11.2.0 改名,codegen 面的名字变了、wire 逐字节不变):
+      # `unknown` 自 server 7.93.0 起可达且与 `no` 同支,一个叫 `_no` 的臂承载两个词就是「名字与它所含的
+      # 一半相反」——本仓明令禁止的那一形(server 侧 `indeterminate`→`failed` 改名同一条理由)。
+      # mapping 必须给**每个**词一个键:少一个词,照 spec 解码的消费端对那个词选不出臂。
       discriminator:
         propertyName: stillLive
         mapping:
-          "yes": '#/components/schemas/RuleWriteResult_yes'
-          "no": '#/components/schemas/RuleWriteResult_no'
+          "yes": '#/components/schemas/RuleWriteResult_live'
+          "no": '#/components/schemas/RuleWriteResult_rowless'
+          "unknown": '#/components/schemas/RuleWriteResult_rowless'
 
-    RuleWriteResult_yes:
+    RuleWriteResult_live:
       description: >
         The LIVE-ROW arm of `rulesWrite`'s 200 (the ordinary outcome): the read-back saw the rule alive, so
         there is a row to hand over. THE ONLY ARM THAT CARRIES `rule`. Never returned on its own — read it
-        through `RuleWriteResult`.
+        through `RuleWriteResult`. (Named `RuleWriteResult_yes` up to SDK 11.1.0 — renamed when its sibling
+        started carrying two words; the wire is byte-identical, only codegen names change.)
       type: object
       additionalProperties: false
       required: [status, rev, stillLive, rule]
@@ -17423,7 +17757,7 @@ components:
         stillLive:
           allOf: [{ $ref: '#/components/schemas/RemovalLiveness' }]
           enum: ["yes"]
-          description: 'The read-back SAW IT ALIVE — the ordinary outcome, and the only arm that carries `rule`. Same key, same word table as `rulesRevoke`; this door''s value range is narrower (`unknown` is unreachable here), never a second table.'
+          description: 'The read-back SAW IT ALIVE — the ordinary outcome, and the only arm that carries `rule`. Same key, same word table as `rulesRevoke`; since server 7.93.0 the same VALUE RANGE as well (all three words are reachable on this door too), and never a second table.'
         rule:
           allOf: [{ $ref: '#/components/schemas/PersistedRule' }]
           description: >
@@ -17439,12 +17773,16 @@ components:
             a human answered a card, `starter` = a deployment preset, `imported-cc` = a real import) — this
             call wrote nothing, so it rewrites nothing either.
 
-    RuleWriteResult_no:
+    RuleWriteResult_rowless:
       description: >
-        The ROW-IS-GONE arm of `rulesWrite`'s 200: the write LANDED (`rev` is real) and a concurrent revoke
-        reached the row before the read-back. `rule` is ABSENT here BY CONSTRUCTION, and 🔴 RETRYING would
-        re-erect a tightening someone just revoked. Never returned on its own — read it through
-        `RuleWriteResult`.
+        The NO-LIVE-ROW arm of `rulesWrite`'s 200 — TWO WORDS, ONE KEY SET, ONE DISPOSITION (named
+        `RuleWriteResult_no` up to SDK 11.1.0; renamed at 11.2.0 when `unknown` became reachable, because an arm
+        called `_no` that also carries `unknown` is a name that contradicts half of what it holds).
+        The write LANDED (`rev` is real) and either a concurrent revoke reached the row before the read-back
+        (`no`), or the read-back itself could not be taken (`unknown`, server >= 7.93.0). `rule` is ABSENT here
+        BY CONSTRUCTION, and 🔴 RETRYING IS WRONG FOR BOTH WORDS (it re-erects a tightening someone just
+        revoked, or simply answers `no-op`) — reconcile with `GET /v1/rules`. Never returned on its own — read
+        it through `RuleWriteResult`.
       type: object
       additionalProperties: false
       required: [status, rev, stillLive]
@@ -17459,12 +17797,18 @@ components:
         rev: { type: integer, description: 'The rule bucket''s OCC revision after the call. REAL on this arm — the write landed; only the row''s liveness went the other way.' }
         stillLive:
           allOf: [{ $ref: '#/components/schemas/RemovalLiveness' }]
-          enum: ["no"]
-          description: >
-            The read-back OBSERVED IT GONE: a legitimate concurrent revoke (yours, or an operator''s) landed
-            between the engine minting the dot and this leg reading the row back. 🔴 NOT an `indeterminate`
-            and NOT a 503: retrying here re-erects a tightening someone just revoked. `rule` is ABSENT on
-            this arm by construction.
+          enum: ["no", unknown]
+          description: >
+            WHICH KIND OF "no live row" this is. `no` = the read-back OBSERVED IT GONE: a legitimate concurrent
+            revoke (yours, or an operator''s) landed between the engine minting the dot and this leg reading the
+            row back. `unknown` = THE READ-BACK ITSELF COULD NOT BE TAKEN (the store did not answer; reachable
+            since server 7.93.0, a 500 before that) — nobody observed the liveness, which is a WEAKER statement
+            than `no` and must not be rendered as "gone".
+            🔴 NEITHER IS an `indeterminate` and NEITHER IS a 503: the engine answered "it wrote" and handed
+            back a real `rev` on both. Retrying is wrong for both (re-erecting a just-revoked tightening, or
+            simply getting `no-op`) — reconcile with `GET /v1/rules`. `rule` is ABSENT on this arm by
+            construction. ⚠️ Do not confuse `unknown` here with 503 `committed: "no"`: that is the SAME store
+            failing BEFORE the write, where nothing landed and resending is safe.
 
     RuleRevokeRequest:
       type: object
@@ -17522,9 +17866,14 @@ components:
             to prevent. 🔴 `unknown` is NOT "the revoke failed" — that is the 503 `state.rule_remove_failed` arm
             (no tombstone written: retry, then reconcile). On `unknown` the tombstone IS written: do NOT retry
             (a retry answers `no-op`, which reads as "nothing to remove" and only confuses); verify with
-            `GET /v1/rules` instead. It rides the `no-op` arm too (the server does that read-back itself and only ever
-            answers `yes` / `no` there — `no-op` + `unknown` is NOT a reachable pair, by construction, not by
-            luck). Migration: `true` → `yes`, `false` → `no`, anything else → `unknown`.
+            `GET /v1/rules` instead. It rides the `no-op` arm too, and 🔴 `no-op` + `unknown` IS A REACHABLE PAIR
+            SINCE server 7.93.0: that arm now reads the SAME liveness read-back as `removed` (engine 7.26.0 gives
+            `RemoveResult`'s `no-op` arm the word itself — one read, one bucket, one identity predicate), so the
+            two arms are BYTE-FOR-BYTE identical in key set, word table and consumer disposition. Up to 7.92.2 the
+            server took that read-back itself and 5xx'd when it failed, so the same fact ("the read that answers
+            liveness did not complete") had two fates across the two arms. A client whose `no-op` switch only has
+            `yes` / `no` (which the 7.92.x contract did promise) must add the third word — it no longer arrives as
+            a 5xx. Migration: `true` → `yes`, `false` → `no`, anything else → `unknown`.
             🔴 APPLICABILITY FLOOR: this schema describes server >= 7.92.0. A server <= 7.91.2 still sends a
             boolean here, so validating such a response against this spec goes RED — that is EXPECTED, not a
             defect (the SDK deliberately carries no union / dual-read); a shell that must span both generations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "11.0.1",
+  "version": "11.2.0",
   "description": "Typed, zero-runtime-dependency SDK for the Sema agent fleet usage plane. The shared substrate for all doors (CC/Codex MCP façade + web). Server-side only — tokens never enter the browser.",
   "type": "module",
   "license": "BUSL-1.1",