@xtrape/capsule-contracts-node 0.4.0 → 0.5.1

package/NOTICE

@@ -1,4 +1,4 @@
-Opstage CE
-Copyright 2026 Xtrape Capsule contributors
+Xtrape Contracts for Node.js
+Copyright 2026 Xtrape contributors
 
-This product includes software developed by the Xtrape Capsule contributors.
+This product includes software developed by the Xtrape contributors.

package/README.md

@@ -1,18 +1,67 @@
-# @xtrape/capsule-contracts-node
+# Xtrape Contracts for Node.js
 
-> TypeScript contracts and Zod schemas for Xtrape Capsule and Opstage wire
+> TypeScript contracts and Zod schemas for Xtrape Agent, Worker, and Panel wire
 > protocols.
 
+The npm name `@xtrape/capsule-contracts-node` is a legacy compatibility
+identifier. `Capsule` is not a current Xtrape concept. New code should use the
+canonical `Worker*` exports; the existing `Capsule*` exports and `services` wire
+field remain available until a versioned protocol migration removes them.
+
+## Contract Authority Boundary
+
+| Name | Role |
+|---|---|
+| `xtrape-contracts` | The **future language-neutral schema authority** for Xtrape contracts (not yet a separate repository). |
+| `xtrape-contracts-nodejs` (this repo) | The **TypeScript / Zod runtime validation and type implementation**. |
+
+Until a standalone `xtrape-contracts` exists, this package hosts the executable
+TypeScript schemas, but it is **not** a separate conceptual authority: the
+canonical model lives in [`xtrape-docs`](https://forgejo.xtrape.com/xtrape/xtrape-docs)
+(`runtime-platform/02..04`, `architecture/11`). When the two disagree, the
+canonical architecture docs win and this package is corrected to match.
+
+## Xtrape CE 0.1 Phase 0 Contracts
+
+The CE 0.1 runtime loop (`Telegram → server-ce → demo xtrape-service → reply`)
+depends on a **frozen** set of schemas, exported from this package and validated
+by `tests/ce-contracts.spec.ts` (including a field/enum surface guard):
+
+| Export | Used by |
+|---|---|
+| `CE_CONTRACT_VERSION` (`1`) | version negotiation across agent ↔ server-ce |
+| `ServiceManifestSchema` / `ServiceManifest` | service registration descriptor |
+| `ServiceInstanceSchema` / `ServiceInstance` | registered instance with resolvable address |
+| `AgentHeartbeatSchema` / `AgentHeartbeat` | heartbeat / health reporting |
+| `ConversationMessageSchema` / `ConversationMessage` | message routing + reply envelope |
+| `ErrorModelSchema` / `ErrorModel` (+ `CeErrorCode`) | structured error responses |
+
+```ts
+import { ServiceManifestSchema, CE_CONTRACT_VERSION } from "@xtrape/capsule-contracts-node";
+
+const manifest = ServiceManifestSchema.parse({
+  contractVersion: CE_CONTRACT_VERSION,
+  service: { id: "demo-echo-service", name: "Demo Echo Service", version: "0.1.0" },
+  runtime: { language: "node", agent: "xtrape-agent-node" },
+  capabilities: ["status.query"],
+  message: { supportedTypes: ["QUERY"] },
+});
+```
+
+These schemas are frozen for CE 0.1: changing a field or enum is a contract
+change that must bump `CE_CONTRACT_VERSION` and update the surface guard. See the
+matching examples in `xtrape-docs/docs/runtime-platform/01-phase-0-runtime-mvp.md`.
+
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
 [![Status: Public Review](https://img.shields.io/badge/status-Public%20Review-orange.svg)](https://xtrape-com.github.io/xtrape-capsule-site/)
 [![Docs](https://img.shields.io/badge/docs-xtrape--capsule--site-blue.svg)](https://xtrape-com.github.io/xtrape-capsule-site/contracts/overview)
 
-`@xtrape/capsule-contracts-node` is the shared TypeScript contract package for
-Opstage CE, Agent SDKs, and Capsule Service integrations. It exports Zod
+`@xtrape/capsule-contracts-node` is the current published TypeScript contract
+package for Panel CE, Agent SDKs, and Worker integrations. It exports Zod
 schemas, inferred TypeScript types, enum values, ID helpers, pagination helpers,
 and protocol error helpers for the Agent/Admin/System wire contracts.
 
-> **Package status:** Xtrape Capsule is currently in **Public Review** before
+> **Package status:** Xtrape is currently in **Public Review** before
 > the `v0.1.0 Public Preview` release. This package is **published to npm** under the
 > `public-review` dist-tag. APIs, contracts, deployment instructions, and SDK
 > interfaces may still change.
@@ -39,15 +88,28 @@ pnpm build
 The package currently exports:
 
 - Zod itself as `z` for consumers that want one compatible Zod instance.
-- Status enum arrays and types: `AgentStatus`, `CapsuleServiceStatus`,
+- Status enum arrays and types: `AgentStatus`, `WorkerStatus` (plus the legacy
+  `CapsuleServiceStatus` alias),
   `HealthStatus`, `CommandStatus`, `DangerLevel`, `AuditActorType`,
   `AuditResult`, `TokenStatus`, `AgentMode`.
 - Admin schemas: users, sessions, registration token requests/responses.
 - Agent schemas: registration, heartbeat, service report, command result.
-- Capsule Service schemas: manifest, health, config, action, service detail.
+- Worker schemas: Worker Manifest, Worker Runtime Report, Worker Instance,
+  health, config, Action, and Worker Instance detail. Legacy
+  Capsule-named aliases remain available for wire compatibility.
 - Command schemas: create command, command detail, command result.
 - Audit and dashboard schemas.
 - System health/version schemas.
+
+The additive v0.4 Worker endpoint aliases and their legacy mappings are recorded
+in `spec/worker-compatibility-v0.4.json`. The older CE v0.1 OpenAPI file remains
+the historical baseline rather than being silently rewritten into a different
+protocol version.
+
+> **Known contract drift:** the historical structured sources still disagree on
+> some Command and effective-status enum values. The `WorkerStatus` export is an
+> alias of the currently shipped binding; it does not claim that the unresolved
+> enum migration documented in `xtrape-docs` has been completed.
 - Helpers: `parseSort`, `paginate`, `HttpError`, `ListQueryBase`.
 
 ## Validate Agent Registration
@@ -69,12 +131,12 @@ import { registerAgentRequestSchema } from "@xtrape/capsule-contracts-node";
 const request = registerAgentRequestSchema.parse(input);
 ```
 
-## v0.3 OpHub and Metadata
+## v0.3 External-Agent Compatibility and Metadata
 
-v0.3 adds the experimental `ophub` Agent mode. `sidecar` and `base-image`
-remain OpHub deployment forms, but the wire contract should use
-`mode: "ophub"` for an OpHub that represents one or more local Capsule
-Services.
+v0.3 adds the legacy `ophub` Agent-mode wire value for the historical Go
+external-Agent runtime. It represents one or more local Workers. It is not the
+canonical Gateway role: Gateway routes Agent/control-plane traffic while
+preserving Agent protocol semantics.
 
 ```ts
 import { RegisterAgentRequestSchema, ServiceReportRequestSchema } from "@xtrape/capsule-contracts-node";
@@ -83,7 +145,7 @@ RegisterAgentRequestSchema.parse({
   registrationToken: "opstage_reg_...",
   agent: {
     code: "ophub-a",
-    name: "OpHub A",
+    name: "External Agent A",
     mode: "ophub",
     runtime: "go",
   },
@@ -112,7 +174,7 @@ ServiceReportRequestSchema.parse({
 ```
 
 Capability metadata is implemented as declarative service metadata. Event
-metadata is intentionally a foundation for future Capsule Bus work; `designOnly`
+metadata is intentionally a foundation for future legacy event routing work; `designOnly`
 events must not be treated as a working event bus.
 
 ## Validate Service Report
@@ -169,7 +231,7 @@ Services:
 - `DOWN`
 - `UNKNOWN`
 
-Opstage may derive an operator-facing `effectiveStatus` such as:
+Xtrape Panel may derive an operator-facing `effectiveStatus` such as:
 
 - `HEALTHY`
 - `UNHEALTHY`
@@ -218,7 +280,7 @@ const prepare = ActionPrepareResultSchema.parse({
 });
 ```
 
-When reported back to Opstage for an `ACTION_PREPARE` command, this shape is
+When reported back to Xtrape Panel for an `ACTION_PREPARE` command, this shape is
 placed under `ReportCommandResultRequest.data`. Command result reporting still
 uses `ReportCommandResultRequestSchema`:
 
@@ -285,6 +347,7 @@ Currently exported codes include:
 - `FORBIDDEN`
 - `NOT_FOUND`
 - `CONFLICT`
+- `CAPSULE_SERVICE_CODE_TAKEN` (persisted compatibility identifier for a Worker ownership conflict)
 - `CSRF_INVALID`
 - `ACTION_REQUIRES_CONFIRMATION`
 - `COMMAND_EXPIRED`
@@ -334,21 +397,21 @@ const response = paginate(items, query.page, query.pageSize, total);
 ## Used By
 
 - [`xtrape-capsule-ce`](https://github.com/xtrape-com/xtrape-capsule-ce) —
-  Opstage CE backend validation and protocol handling.
+  Xtrape Panel CE backend validation and protocol handling.
 - [`xtrape-capsule-agent-node`](https://github.com/xtrape-com/xtrape-capsule-agent-node)
   — Node embedded Agent SDK request/response types.
 - [`xtrape-capsule-demo`](https://github.com/xtrape-com/xtrape-capsule-demo)
-  — End-to-end runnable Capsule Service that imports these schemas through
+  — End-to-end runnable Worker that imports these schemas through
   the Agent SDK.
-- Capsule Service implementations that want local validation before reporting to
-  Opstage.
+- Worker implementations that want local validation before reporting to
+  Xtrape Panel.
 
 ## Compatibility
 
 | Package                                | Compatible with                          |
 | -------------------------------------- | ---------------------------------------- |
-| `@xtrape/capsule-contracts-node@0.2.x` | Opstage CE `0.2.x` and Agent SDK `0.2.x` |
-| `@xtrape/capsule-contracts-node@0.1.x` | Opstage CE `0.1.x` and Agent SDK `0.1.x` |
+| `@xtrape/capsule-contracts-node@0.2.x` | Xtrape Panel CE `0.2.x` and Agent SDK `0.2.x` |
+| `@xtrape/capsule-contracts-node@0.1.x` | Xtrape Panel CE `0.1.x` and Agent SDK `0.1.x` |
 
 Pin matching minor versions across CE, Agent SDK, and Contracts. The wire
 protocol may still evolve before `v1.0`.
@@ -375,7 +438,7 @@ guarantees per schema group are:
 | ---------------------------------------------------------------------------------------------------------------- | :---------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Status enums (`AgentStatus`, `CapsuleServiceStatus`, `HealthStatus`, `CommandStatus`, `DangerLevel`, `TokenStatus`) |   Stable    | New values may be added in minor versions; existing values will not be removed before `v1.0`.                                                                        |
 | Agent ↔ Backend wire schemas (`RegisterAgentRequest`, `AgentHeartbeat*`, `ServiceReport*`, `ReportCommandResult*`) |  Evolving  | Field shape is stable; additive optional fields may land in minor versions. Required fields will not be added before `v1.0` without a deprecation cycle.             |
-| Capsule Service shapes (`CapsuleManifest`, `ReportedService`, `HealthReportInput`, `ConfigItemInput`, `ActionDefinitionInput`) |  Evolving  | Same policy as wire schemas.                                                                                                                                          |
+| Worker shapes (`WorkerManifest`, `WorkerRuntimeReport`, `WorkerInstance`, `HealthReportInput`, `ConfigItemInput`, `ActionDefinitionInput`) |  Evolving  | Legacy aliases retain the existing physical wire shapes. |
 | Persisted shapes (`Agent`, `CapsuleService`, `ConfigItem`, `ActionDefinition`, `Command*`, `AuditEvent`, `User`)  |  Evolving  | Track CE storage; safe to consume read-only.                                                                                                                          |
 | `ActionPrepareResultSchema`                                                                                      | Provisional | Added in `0.1.0-public-review.0`. Field shape may still tighten before `v1.0`.                                                                                       |
 | `Command.type` enum                                                                                              |  Evolving  | Currently `ACTION_PREPARE` / `ACTION_EXECUTE`. New types may be added.                                                                                                |
@@ -392,7 +455,7 @@ Breaking changes will be called out in `CHANGELOG.md`.
 - Health contract: https://xtrape-com.github.io/xtrape-capsule-site/contracts/health
 - Actions contract: https://xtrape-com.github.io/xtrape-capsule-site/contracts/actions
 - Errors: https://xtrape-com.github.io/xtrape-capsule-site/contracts/errors
-- Opstage CE: https://xtrape-com.github.io/xtrape-capsule-site/opstage-ce/overview
+- Xtrape Panel CE: https://xtrape-com.github.io/xtrape-capsule-site/opstage-ce/overview
 
 ## Contributing
 
@@ -402,12 +465,12 @@ contract validation safety guidance.
 
 ## License
 
-Apache-2.0. "Xtrape", "Xtrape Capsule", and "Opstage" are trademarks of their
+Apache-2.0. "Xtrape" and "Opstage" are trademarks of their
 respective owners; the open-source license does not grant trademark rights.
 
-## v0.4 Capsule Bus Experimental
+## v0.4 legacy event routing Experimental
 
-`v0.4` adds an experimental Capsule Bus contract surface for CE's built-in SQLite-backed in-process event-to-command router. It is intentionally small, single-node, and disabled by default; it is **not** a standalone Bus Server, external broker (NATS / RabbitMQ / Redis Streams / Kafka), workflow DSL, or service mesh. No fan-out (`maxCommandsPerEvent`) in v0.4 — one matched route produces at most one `ACTION_EXECUTE` command.
+`v0.4` adds an experimental legacy event routing contract surface for CE's built-in SQLite-backed in-process event-to-command router. It is intentionally small, single-node, and disabled by default; it is **not** a standalone Bus Server, external broker (NATS / RabbitMQ / Redis Streams / Kafka), workflow DSL, or service mesh. No fan-out (`maxCommandsPerEvent`) in v0.4 — one matched route produces at most one `ACTION_EXECUTE` command.
 
 Key exports: