@godspeedai/cognate-proto 0.1.0 → 0.1.2

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 +81 -18
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,20 +1,83 @@
1
1
  # @godspeedai/cognate-proto
2
2
 
3
- Generated TypeScript bindings for the canonical `proto/` sources (spec §21). Generated code
4
- (`src/gen/**`) is committed and never edited by hand; `src/index.ts` re-exports `RuntimeService`,
5
- every message and enum.
6
-
7
- Regenerate with `bun scripts/generate.ts [outDir]` (default `src/gen`). It runs `buf generate`
8
- against `buf.gen.yaml`, using the pinned local `protoc-gen-es` binary from `node_modules/.bin`,
9
- `target=ts`, reading `../../proto` (the canonical sources) via `buf.yaml`. Generation is
10
- deterministic: two runs into separate directories are byte-identical to each other and to the
11
- committed `src/gen`.
12
-
13
- ## Supported mode matrix
14
-
15
- | Concern | Support |
16
- | --- | --- |
17
- | Message/enum codegen | Full (all `proto/cognate/v1/*.proto`) |
18
- | `RuntimeService` methods | Unary + server-streaming only (DEBT-004); no client/bidi streaming methods exist in the schema |
19
- | Wire formats | JSON and binary (protobuf-es `Message` supports both; format choice is a transport concern) |
20
- | Codegen determinism | Verified by `test/codegen.test.ts` (two fresh generations + committed output, byte-for-byte) |
3
+ Generated TypeScript bindings for Cognate's canonical protobuf schemas (the `cognate.v1` package), produced with [buf](https://buf.build) and [protobuf-es](https://protobuf-es.buf.build).
4
+
5
+ **When to use this package:** you need the typed `RuntimeService` service descriptor and the generated message and enum classes for Cognate's wire format — for a custom transport, a gateway in another stack, or message-level tooling. Applications that simply call a Cognate runtime should use [`@godspeedai/cognate-client`](https://www.npmjs.com/package/@godspeedai/cognate-client) or the protocol adapters instead; they build on these bindings and handle the wire details for you.
6
+
7
+ ## Installation
8
+
9
+ ```sh
10
+ bun add @godspeedai/cognate-proto
11
+ ```
12
+
13
+ Requires [Bun](https://bun.sh) >= 1.4.0. The package depends on `@bufbuild/protobuf`; calling a runtime over HTTP additionally needs a Connect transport (`@connectrpc/connect`, plus `@connectrpc/connect-web` or the convenience exports of [`@godspeedai/cognate-protocol-connect-bun`](https://www.npmjs.com/package/@godspeedai/cognate-protocol-connect-bun)).
14
+
15
+ ## What it exports
16
+
17
+ The entry point re-exports everything generated from the canonical `cognate/v1` schemas:
18
+
19
+ - the `RuntimeService` service descriptor (run start/get/cancel/list, event streaming, continuations, capability invocation, artifacts, projections, shared state, remote capability offers);
20
+ - message types and their schemas — `Event`/`EventSchema`, `Run`, `Continuation`, `StateUpdate`, `RemoteCapabilityOffer`, `SemanticRef`, and the rest of the family;
21
+ - the enums `RunStatus`, `ContinuationStatus`, `ContinuationAction`, and `ResolveOutcome`.
22
+
23
+ ## Quick start
24
+
25
+ Messages are ordinary protobuf-es values — create them from JSON, then serialize to canonical JSON or binary protobuf:
26
+
27
+ ```ts
28
+ import { fromJson, toJson } from "@bufbuild/protobuf";
29
+ import { EventSchema } from "@godspeedai/cognate-proto";
30
+
31
+ const event = fromJson(EventSchema, {
32
+ eventId: "e-1",
33
+ streamId: "s-1",
34
+ streamSequence: "1", // uint64 fields are strings in canonical JSON
35
+ position: "1",
36
+ eventType: "run.started",
37
+ schemaVersion: 1,
38
+ occurredAt: new Date().toISOString(),
39
+ recordedAt: new Date().toISOString(),
40
+ tenant: "tenant-a",
41
+ correlationId: "c-1",
42
+ scopeId: "workspace-1",
43
+ });
44
+
45
+ const json = toJson(EventSchema, event); // canonical JSON
46
+ const bytes = event.toBinary(); // binary protobuf
47
+ ```
48
+
49
+ To call a served runtime with a typed client, hand the service descriptor to a Connect transport:
50
+
51
+ ```ts
52
+ import { createClient } from "@connectrpc/connect";
53
+ import { connectTransport } from "@godspeedai/cognate-protocol-connect-bun";
54
+ import { RuntimeService } from "@godspeedai/cognate-proto";
55
+
56
+ const client = createClient(RuntimeService, connectTransport("http://127.0.0.1:3000"));
57
+ const run = await client.getRun({ runId: "<run id>" });
58
+ ```
59
+
60
+ Prefer [`@godspeedai/cognate-protocol-connect`](https://www.npmjs.com/package/@godspeedai/cognate-protocol-connect)'s `createRemoteRuntimeService` when you call the runtime yourself: the generated client does not coerce plain JSON for `google.protobuf.Value` fields (such as the run `input`), and that adapter performs the conversion and maps error codes in both directions.
61
+
62
+ ## Regeneration
63
+
64
+ The generated files (`src/gen/**`) are committed and never edited by hand. Regeneration happens in the Cognate repository, not downstream: running `bun run generate` in this package executes `buf generate` with a pinned `protoc-gen-es` plugin against the canonical `proto/` sources. Consumers of the published package never run codegen — they import the committed output like any other module.
65
+
66
+ Generation is deterministic: two runs into separate directories are byte-identical to each other and to the committed output, and the package's own test suite keeps that true.
67
+
68
+ ## Limitations
69
+
70
+ - The generated `RuntimeService` declares unary and server-streaming methods only; the schema has no client-streaming or bidirectional methods.
71
+ - protobuf-es can serialize every message as JSON or binary; choosing a wire format is a transport decision, not something this package configures.
72
+ - Message and field shapes change only through a new release of this package, since there is no downstream codegen path.
73
+
74
+ ## Related packages
75
+
76
+ - [`@godspeedai/cognate-protocol-connect`](https://www.npmjs.com/package/@godspeedai/cognate-protocol-connect) — transport-neutral server routes and a remote `RuntimeService` built on these bindings.
77
+ - [`@godspeedai/cognate-protocol-connect-bun`](https://www.npmjs.com/package/@godspeedai/cognate-protocol-connect-bun) — serves the service on `Bun.serve` and provides the fetch transport.
78
+ - [`@godspeedai/cognate-client`](https://www.npmjs.com/package/@godspeedai/cognate-client) — the high-level client most applications should use instead.
79
+ - [`@godspeedai/cognate`](https://www.npmjs.com/package/@godspeedai/cognate) — the SDK umbrella.
80
+
81
+ ## License
82
+
83
+ Apache-2.0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@godspeedai/cognate-proto",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Generated TypeScript bindings for the canonical proto/ sources. Generated files are never edited by hand (spec §21).",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",