@sema-agent/sdk 4.1.0 → 4.3.0

package/registry-openapi.yaml

@@ -153,8 +153,21 @@ paths:
       - { in: path, name: domain, required: true, schema: { type: string } }
     get:
       operationId: registryScopeConfigDraftGet
-      summary: Read a scope's config DRAFT (getScopeConfigDraft).
-      responses: { '200': { description: '{value, version, …}.' } }
+      summary: Read a scope's config — DRAFT by default, or the PUBLISHED snapshot with `?source=published`.
+      # 🔴 RC-6(2026-08-02):`?source=published` 此前完全未成文,而 SDK 的 `getScopeConfigPublished`
+      # (`scope-config-feedback.ts:46`)一直在打它 —— 两个响应形不同(draft 是 `{value, version}`,
+      # published 是 `{value, published, publishedAt?}`),按 spec codegen 的人只知道 draft 那一个。
+      parameters:
+        - in: query
+          name: source
+          required: false
+          schema: { type: string, enum: [published] }
+          description: 'Omit ⇒ the DRAFT (workspace) read. `published` ⇒ the PUBLISHED snapshot — what members actually receive.'
+      responses:
+        '200':
+          description: >
+            Without `?source=`: the draft, `{value, version, …}` — `version` is the CAS baseline for the PUT.
+            With `?source=published`: `{value, published, publishedAt?, …}`.
     put:
       operationId: registryScopeConfigDraftPut
       summary: CAS-write the draft (putScopeConfigDraft; version NUMBER axis — not updatedAt).
@@ -164,10 +177,28 @@ paths:
   /api/v1/scopes/{s}/publish:
     parameters:
       - { in: path, name: s, required: true, schema: { type: string } }
+    # 🔴 RC-6(2026-08-02):此前这条路径**只有 post、只有 '200'**。两个后果,都命中同一个设计的核心:
+    #  ① 缺 `get` ⇒ 按本 spec(随 npm 包发布,package.json exports `./registry-openapi.yaml`)生成客户端的人
+    #     拿不到状态查询 verb —— 而 SDK 的 `getPublishState` 一直在打它。
+    #  ② 缺 `'202'` ⇒ 拿不到 pending 分支,他会把 202 当成一个未处理的异常状态。而 200/202 的判别**就是**
+    #     这条设计的核心(`scope-config-feedback.ts:85-86` 明写「消费方绝不许把 202 渲染成已发布」)。
+    # 现有的 registry path 门是双向零基线的、很强 —— 但它比对的是**路径集合**,method/responses 全不参与,
+    # 所以这两类问题结构上红不了。同批把那道门升到了 path × method(见 test/registry-spec-path-gate.test.ts)。
+    get:
+      operationId: registryScopePublishState
+      summary: Read the publish state (getPublishState) — is a request already pending, and how many approvals does it need?
+      responses:
+        '200':
+          description: >
+            `{published?, pending?, approvalsRequired}`. `pending` present ⇒ a request is already outstanding and a
+            new one cannot be opened. ⚠️ `approvalsRequired` gates a PROTECTION; if it is ever absent, treat that as
+            unknown and fail CLOSED — never render "no approval needed".
     post:
       operationId: registryScopePublishRequest
       summary: Request publish of the draft (requestPublish; goes through the approval gate).
-      responses: { '200': { description: 'Publish requested/pending.' } }
+      responses:
+        '200': { description: 'PUBLISHED — the draft took effect immediately (no approval gate, or already satisfied).' }
+        '202': { description: 'PENDING — the approval gate is open and the draft is NOT in effect. Approvers act via …/publish/approve. A consumer MUST NOT render this as published.' }
 
   # ── feedback ──────────────────────────────────────────────────────────────────────────────────
   /api/v1/feedback: