@xtrape/capsule-contracts-node 0.5.0 → 0.5.1

package/README.md

@@ -8,6 +8,50 @@ 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtrape/capsule-contracts-node",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "TypeScript contracts and Zod schemas for Xtrape Agent, Worker, and Panel wire protocols.",
   "keywords": [
     "xtrape",
@@ -13,11 +13,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/xtrape-com/xtrape-capsule-contracts-node.git"
+    "url": "git+https://forgejo.xtrape.com/xtrape/xtrape-contracts-nodejs.git"
   },
-  "homepage": "https://github.com/xtrape-com/xtrape-capsule-contracts-node#readme",
+  "homepage": "https://forgejo.xtrape.com/xtrape/xtrape-contracts-nodejs#readme",
   "bugs": {
-    "url": "https://github.com/xtrape-com/xtrape-capsule-contracts-node/issues"
+    "url": "https://forgejo.xtrape.com/xtrape/xtrape-contracts-nodejs/issues"
   },
   "type": "module",
   "main": "./dist/index.cjs",