@xtrape/capsule-contracts-node 0.4.0 → 0.5.1

package/spec/openapi/opstage-ce-v0.1.yaml

@@ -1,13 +1,13 @@
 openapi: 3.1.0
 info:
-  title: Opstage CE API
+  title: Xtrape Panel CE API
   version: 0.1.0
-  summary: CE v0.1 API contract for Opstage Capsule Service governance.
+  summary: CE v0.1 API contract for Xtrape Panel Worker governance.
   license:
     name: Apache-2.0
     identifier: Apache-2.0
   contact:
-    name: Opstage CE maintainers
+    name: Xtrape Panel CE maintainers
     url: https://github.com/xtrape/xtrape-capsule-ce
   description: |
     This contract defines the CE v0.1 Admin API, Agent API, and System API.
@@ -72,13 +72,13 @@ tags:
   - name: AdminDashboard
     description: Aggregate counters for the CE governance loop.
   - name: AdminAgents
-    description: List, inspect, and manage Agents bound to Capsule Services.
+    description: List, inspect, and manage Agents bound to Workers.
   - name: AdminRegistrationTokens
     description: Create, list, and revoke single-use registration tokens.
   - name: AdminCapsuleServices
-    description: Inspect Capsule Services and request predefined actions.
+    description: Inspect Workers and request predefined actions.
   - name: AdminCommands
-    description: Inspect Commands created via Capsule Service actions.
+    description: Inspect Commands created via Worker actions.
   - name: AdminAuditEvents
     description: Read the immutable audit trail.
   - name: Agent
@@ -510,7 +510,7 @@ paths:
   /api/admin/capsule-services:
     get:
       tags: [AdminCapsuleServices]
-      summary: List Capsule Services.
+      summary: List Workers.
       description: |
         Allowed `sort` fields: `createdAt`, `lastReportedAt`, `code`, `name`.
         Default sort: `-createdAt`. Filter `status` accepts multiple values
@@ -536,7 +536,7 @@ paths:
             pattern: '^agt_'
       responses:
         '200':
-          description: Capsule Service list.
+          description: Worker list.
           content:
             application/json:
               schema:
@@ -575,7 +575,7 @@ paths:
   /api/admin/capsule-services/{serviceId}:
     get:
       tags: [AdminCapsuleServices]
-      summary: Get Capsule Service detail.
+      summary: Get Worker detail.
       operationId: getCapsuleService
       security:
         - AdminSessionCookie: []
@@ -583,7 +583,7 @@ paths:
         - $ref: '#/components/parameters/ServiceId'
       responses:
         '200':
-          description: Capsule Service detail.
+          description: Worker detail.
           content:
             application/json:
               schema:
@@ -598,7 +598,7 @@ paths:
   /api/admin/capsule-services/{serviceId}/manifest:
     get:
       tags: [AdminCapsuleServices]
-      summary: Get Capsule Service manifest JSON.
+      summary: Get Worker manifest JSON.
       operationId: getCapsuleServiceManifest
       security:
         - AdminSessionCookie: []
@@ -754,7 +754,7 @@ paths:
       description: |
         Allowed `sort` fields: `createdAt`, `finishedAt`. Default: `-createdAt`.
         Filter `status` accepts multiple values (OR'ed). `serviceId` and
-        `agentId` filter by Capsule Service / Agent ownership.
+        `agentId` filter by Worker / Agent ownership.
       operationId: listCommands
       security:
         - AdminSessionCookie: []
@@ -1041,7 +1041,7 @@ paths:
   /api/agents/{agentId}/services/report:
     post:
       tags: [Agent]
-      summary: Report Capsule Service manifest, configs, actions, and health.
+      summary: Report Worker manifest, configs, actions, and health.
       description: |
         Idempotent upsert keyed by `(workspaceId, code)`. The Agent SHOULD
         report once at startup and again when its manifest changes, NOT on
@@ -1906,7 +1906,7 @@ components:
     CapsuleManifest:
       type: object
       description: |
-        Authoritative shape of a Capsule Service manifest reported by the Agent.
+        Authoritative shape of a Worker manifest reported by the Agent.
         Backend stores the full object as `CapsuleService.manifestJson` and validates
         the listed required fields. Unknown fields are preserved (forward-compat).
       required: [kind, code, name, version, runtime, agentMode]

package/spec/worker-compatibility-v0.4.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xtrape.dev/contracts/worker-compatibility-v0.4.json",
+  "title": "Xtrape Worker compatibility additions",
+  "version": "0.4.0-rc.0",
+  "description": "Additive Worker terminology and endpoint aliases over the existing CE wire contract. Legacy identifiers remain valid until a versioned removal.",
+  "canonicalEndpoints": {
+    "workerReport": "/api/agents/{agentId}/workers/report",
+    "workerList": "/api/admin/workers",
+    "workerDetail": "/api/admin/workers/{serviceId}",
+    "workerAction": "/api/admin/workers/{serviceId}/actions/{actionName}"
+  },
+  "legacyAliases": {
+    "/api/agents/{agentId}/services/report": "/api/agents/{agentId}/workers/report",
+    "/api/admin/capsule-services": "/api/admin/workers",
+    "/api/admin/capsule-services/{serviceId}": "/api/admin/workers/{serviceId}",
+    "/api/admin/capsule-services/{serviceId}/actions/{actionName}": "/api/admin/workers/{serviceId}/actions/{actionName}"
+  },
+  "ownership": {
+    "rule": "An Agent may update only Worker Instance records it owns. Reporting an existing Worker code owned by another Agent fails until an explicit transfer flow exists.",
+    "conflictErrorCode": "CAPSULE_SERVICE_CODE_TAKEN",
+    "note": "The error code is a persisted compatibility identifier."
+  },
+  "requestShapes": {
+    "workerReport": {
+      "type": "object",
+      "required": ["workers"],
+      "properties": {
+        "workers": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/definitions/workerRuntimeReport" }
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "definitions": {
+    "workerRuntimeReport": {
+      "type": "object",
+      "required": ["code", "name", "manifest"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1, "maxLength": 80 },
+        "name": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "manifest": { "type": "object" },
+        "health": { "type": "object" },
+        "configs": { "type": "array" },
+        "actions": { "type": "array" }
+      },
+      "additionalProperties": true
+    }
+  }
+}