@sema-agent/sdk 11.1.0 → 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'
@@ -8047,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." }
@@ -12423,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: >
@@ -16289,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
@@ -17424,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
@@ -17441,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]
@@ -17475,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: >
@@ -17491,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]
@@ -17511,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/sdk",
-  "version": "11.1.0",
+  "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",