@xtrape/capsule-contracts-node 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +64 -21
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -8,30 +8,72 @@ identifier. `Capsule` is not a current Xtrape concept. New code should use the
8
8
  canonical `Worker*` exports; the existing `Capsule*` exports and `services` wire
9
9
  field remain available until a versioned protocol migration removes them.
10
10
 
11
+ ## Contract Authority Boundary
12
+
13
+ | Name | Role |
14
+ |---|---|
15
+ | `xtrape-contracts` | The **future language-neutral schema authority** for Xtrape contracts (not yet a separate repository). |
16
+ | `xtrape-contracts-nodejs` (this repo) | The **TypeScript / Zod runtime validation and type implementation**. |
17
+
18
+ Until a standalone `xtrape-contracts` exists, this package hosts the executable
19
+ TypeScript schemas, but it is **not** a separate conceptual authority: the
20
+ canonical model lives in [`xtrape-docs`](https://forgejo.xtrape.com/xtrape/xtrape-docs)
21
+ (`runtime-platform/02..04`, `architecture/11`). When the two disagree, the
22
+ canonical architecture docs win and this package is corrected to match.
23
+
24
+ ## Xtrape CE 0.1 Phase 0 Contracts
25
+
26
+ The CE 0.1 runtime loop (`Telegram → server-ce → demo xtrape-service → reply`)
27
+ depends on a **frozen** set of schemas, exported from this package and validated
28
+ by `tests/ce-contracts.spec.ts` (including a field/enum surface guard):
29
+
30
+ | Export | Used by |
31
+ |---|---|
32
+ | `CE_CONTRACT_VERSION` (`1`) | version negotiation across agent ↔ server-ce |
33
+ | `ServiceManifestSchema` / `ServiceManifest` | service registration descriptor |
34
+ | `ServiceInstanceSchema` / `ServiceInstance` | registered instance with resolvable address |
35
+ | `AgentHeartbeatSchema` / `AgentHeartbeat` | heartbeat / health reporting |
36
+ | `ConversationMessageSchema` / `ConversationMessage` | message routing + reply envelope |
37
+ | `ErrorModelSchema` / `ErrorModel` (+ `CeErrorCode`) | structured error responses |
38
+
39
+ ```ts
40
+ import { ServiceManifestSchema, CE_CONTRACT_VERSION } from "@xtrape/capsule-contracts-node";
41
+
42
+ const manifest = ServiceManifestSchema.parse({
43
+ contractVersion: CE_CONTRACT_VERSION,
44
+ service: { id: "demo-echo-service", name: "Demo Echo Service", version: "0.6.0" },
45
+ runtime: { language: "node", agent: "xtrape-agent-nodejs" },
46
+ capabilities: ["status.query"],
47
+ message: { supportedTypes: ["QUERY"] },
48
+ });
49
+ ```
50
+
51
+ These schemas are frozen for CE 0.1: changing a field or enum is a contract
52
+ change that must bump `CE_CONTRACT_VERSION` and update the surface guard. See the
53
+ matching examples in `xtrape-docs/docs/runtime-platform/01-phase-0-runtime-mvp.md`.
54
+
11
55
  [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
12
- [![Status: Public Review](https://img.shields.io/badge/status-Public%20Review-orange.svg)](https://xtrape-com.github.io/xtrape-capsule-site/)
13
- [![Docs](https://img.shields.io/badge/docs-xtrape--capsule--site-blue.svg)](https://xtrape-com.github.io/xtrape-capsule-site/contracts/overview)
56
+ [![Status: Release Train 0.6.0](https://img.shields.io/badge/status-0.6.0-blue.svg)](https://forgejo.xtrape.com/xtrape/xtrape-docs)
57
+ [![Docs](https://img.shields.io/badge/docs-xtrape--docs-blue.svg)](https://forgejo.xtrape.com/xtrape/xtrape-docs)
14
58
 
15
59
  `@xtrape/capsule-contracts-node` is the current published TypeScript contract
16
60
  package for Panel CE, Agent SDKs, and Worker integrations. It exports Zod
17
61
  schemas, inferred TypeScript types, enum values, ID helpers, pagination helpers,
18
62
  and protocol error helpers for the Agent/Admin/System wire contracts.
19
63
 
20
- > **Package status:** Xtrape is currently in **Public Review** before
21
- > the `v0.1.0 Public Preview` release. This package is **published to npm** under the
22
- > `public-review` dist-tag. APIs, contracts, deployment instructions, and SDK
23
- > interfaces may still change.
64
+ > **Package status:** This package follows the unified Xtrape `0.6.0` release
65
+ > train. The npm package name remains a compatibility identifier, but release
66
+ > versioning now follows the shared Xtrape train version.
24
67
 
25
68
  ## Install
26
69
 
27
- During Public Review, install the prerelease package with:
70
+ This repository tracks the `0.6.0` snapshot train. Until the `0.6.0` npm cut is
71
+ published, install the latest published compatibility package:
28
72
 
29
73
  ```bash
30
- pnpm add @xtrape/capsule-contracts-node@public-review
74
+ pnpm add @xtrape/capsule-contracts-node@^0.5.1
31
75
  ```
32
76
 
33
- The current Public Review version may change before `v0.1.0`.
34
-
35
77
  For this repository itself:
36
78
 
37
79
  ```bash
@@ -352,11 +394,11 @@ const response = paginate(items, query.page, query.pageSize, total);
352
394
 
353
395
  ## Used By
354
396
 
355
- - [`xtrape-capsule-ce`](https://github.com/xtrape-com/xtrape-capsule-ce) —
397
+ - [`xtrape-panel-ce`](https://forgejo.xtrape.com/xtrape/xtrape-panel-ce) —
356
398
  Xtrape Panel CE backend validation and protocol handling.
357
- - [`xtrape-capsule-agent-node`](https://github.com/xtrape-com/xtrape-capsule-agent-node)
399
+ - [`xtrape-agent-nodejs`](https://forgejo.xtrape.com/xtrape/xtrape-agent-nodejs)
358
400
  — Node embedded Agent SDK request/response types.
359
- - [`xtrape-capsule-demo`](https://github.com/xtrape-com/xtrape-capsule-demo)
401
+ - [`xtrape-demo`](https://forgejo.xtrape.com/xtrape/xtrape-demo)
360
402
  — End-to-end runnable Worker that imports these schemas through
361
403
  the Agent SDK.
362
404
  - Worker implementations that want local validation before reporting to
@@ -387,8 +429,8 @@ existing `0.1.x` agents continue to validate against a `0.2.x` backend.
387
429
 
388
430
  ## Schema Stability
389
431
 
390
- The package follows semver. For Public Review and Public Preview, the
391
- guarantees per schema group are:
432
+ The package follows semver. During the current pre-`1.0` release-train phase,
433
+ the guarantees per schema group are:
392
434
 
393
435
  | Group | Stability | Notes |
394
436
  | ---------------------------------------------------------------------------------------------------------------- | :---------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -406,12 +448,13 @@ Breaking changes will be called out in `CHANGELOG.md`.
406
448
 
407
449
  ## Documentation
408
450
 
409
- - Contracts overview: https://xtrape-com.github.io/xtrape-capsule-site/contracts/overview
410
- - Manifest contract: https://xtrape-com.github.io/xtrape-capsule-site/contracts/manifest
411
- - Health contract: https://xtrape-com.github.io/xtrape-capsule-site/contracts/health
412
- - Actions contract: https://xtrape-com.github.io/xtrape-capsule-site/contracts/actions
413
- - Errors: https://xtrape-com.github.io/xtrape-capsule-site/contracts/errors
414
- - Xtrape Panel CE: https://xtrape-com.github.io/xtrape-capsule-site/opstage-ce/overview
451
+ - Public docs repo: https://forgejo.xtrape.com/xtrape/xtrape-site
452
+ - Contracts overview: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/contracts/overview.md
453
+ - Manifest contract: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/contracts/manifest.md
454
+ - Health contract: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/contracts/health.md
455
+ - Actions contract: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/contracts/actions.md
456
+ - Errors: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/contracts/errors.md
457
+ - Xtrape Panel CE docs: https://forgejo.xtrape.com/xtrape/xtrape-site/src/branch/main/docs/opstage-ce/overview.md
415
458
 
416
459
  ## Contributing
417
460
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xtrape/capsule-contracts-node",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "TypeScript contracts and Zod schemas for Xtrape Agent, Worker, and Panel wire protocols.",
5
5
  "keywords": [
6
6
  "xtrape",
@@ -13,11 +13,11 @@
13
13
  ],
14
14
  "repository": {
15
15
  "type": "git",
16
- "url": "git+https://github.com/xtrape-com/xtrape-capsule-contracts-node.git"
16
+ "url": "git+https://forgejo.xtrape.com/xtrape/xtrape-contracts-nodejs.git"
17
17
  },
18
- "homepage": "https://github.com/xtrape-com/xtrape-capsule-contracts-node#readme",
18
+ "homepage": "https://forgejo.xtrape.com/xtrape/xtrape-contracts-nodejs#readme",
19
19
  "bugs": {
20
- "url": "https://github.com/xtrape-com/xtrape-capsule-contracts-node/issues"
20
+ "url": "https://forgejo.xtrape.com/xtrape/xtrape-contracts-nodejs/issues"
21
21
  },
22
22
  "type": "module",
23
23
  "main": "./dist/index.cjs",