@ceralive/cerastream 2026.6.0-rc.1

package/README.md

@@ -0,0 +1,88 @@
+# @ceralive/cerastream (TypeScript bindings)
+
+Type-safe control-IPC **schema + client surface** for the cerastream Rust
+streaming engine. This package is the **public contract** (ADR-0002 Decision 13):
+a CI-published npm package — **not** a sibling `link:` dep — consumable by Bun with
+zero native dependencies.
+
+- JSON-RPC 2.0 envelope + `hello` handshake schemas
+- The eight v1 control methods (params + result Zod schemas + inferred types)
+- The seven server-push event payloads (discriminated union)
+- Two-tier error codes (Tier 1 RPC + Tier 2 runtime, 1:1 with CeraUI)
+- A unified engine config schema (= `start` params)
+- A `CerastreamClient` interface + `connect()` factory (Bun-native UDS transport)
+
+> **Schema + client.** The Zod schemas, types, and constants are the **frozen**
+> wire contract; `connect()` drives that contract over a Bun-native NDJSON/UDS
+> transport (no native deps). The schema shape is unchanged from the v0.1.0-stub
+> freeze — this release adds the runtime client behind it (plan Task 31).
+
+See [`API.md`](./API.md) for the full exported surface, ADR-0002
+([`../../docs/adr/ADR-0002-control-ipc.md`](../../docs/adr/ADR-0002-control-ipc.md))
+for the protocol decision, and `schema.md`
+([`../../docs/adr/schema.md`](../../docs/adr/schema.md)) for the v1 message
+inventory.
+
+## Install / develop
+
+```bash
+bun install
+bun run typecheck   # tsc --noEmit
+bun test            # schema round-trip + stub-honesty + count + skew guards
+bun run build       # emit dist/
+```
+
+## Usage (schema today, client after Task 31)
+
+The schemas are usable now — validate any control message on either side of the
+wire:
+
+```ts
+import { startParamsSchema, eventParamsSchema } from "@ceralive/cerastream";
+
+const params = startParamsSchema.parse({
+  pipeline: "h264_camlink_1080p",
+  srt: { host: "relay.example.com", port: 8890, latency_ms: 2000 },
+  bitrate: { min_bitrate: 500, max_bitrate: 6000 }, // balancer defaults to "adaptive"
+});
+
+const event = eventParamsSchema.parse(incomingNotification.params); // typed by `type`
+```
+
+Drive the engine through the control plane:
+
+```ts
+import { connect } from "@ceralive/cerastream";
+
+const client = await connect({ autoReconnect: true }); // hello handshake runs here
+console.log(client.hello.engine_version);
+
+const sub = await client.subscribeEvents({ topics: ["status", "bitrate"] }, (ev) => {
+  if (ev.type === "bitrate") console.log("bitrate", ev.current_bitrate);
+});
+
+await client.start({
+  pipeline: "h264_camlink_1080p",
+  srt: { host: "relay.example.com", port: 8890, latency_ms: 2000 },
+  bitrate: { min_bitrate: 500, max_bitrate: 6000 },
+});
+await client.setBitrate({ max_bitrate: 4500 });
+await client.switchInput({ input_id: "video0" });
+await client.stop();
+
+sub.close();
+await client.close(); // closes the connection; never respawns the engine (ADR-0005)
+```
+
+`connect()` honors `socketPath` (default: the resolved `/run/cerastream/control.sock`),
+`requestTimeoutMs`, and `autoReconnect` (capped backoff + re-handshake + re-subscribe).
+The engine is a systemd-owned service — the client connects, it never spawns it.
+
+## Versioning — SemVer on top of CalVer
+
+Two version axes, kept separate: the **wire-schema version** (`PROTOCOL_VERSION` +
+`SCHEMA_VERSION`) is pinned cross-language with the Rust engine and is additive-only
+within `cerastream-ipc/1`; the **npm package version** (`package.json`) is CalVer
+(`YYYY.MINOR.PATCH`) for the library release line, with SemVer intent applied to the
+exported TypeScript surface. Release candidates use `-rc.N` (npm `next` dist-tag).
+Full policy + the tag-driven publish pipeline: [`CHANGELOG.md`](./CHANGELOG.md).

package/dist/client.d.ts

@@ -0,0 +1,58 @@
+import { type HelloResult } from "./envelope.js";
+import { type EventParams } from "./events.js";
+import { type ListDevicesParams, type ListDevicesResult, type PreviewSessionParams, type PreviewSessionResult, type ReloadConfigParams, type ReloadConfigResult, type SetBitrateParams, type SetBitrateResult, type StartParams, type StartResult, type StopParams, type StopResult, type SubscribeEventsParams, type SubscribeEventsResult, type SwitchInputParams, type SwitchInputResult } from "./messages.js";
+/** Options for {@link connect}. All optional — `connect({})` is valid. */
+export interface ConnectOptions {
+    /** Control socket path override. Defaults to the resolved /run/cerastream/control.sock. */
+    socketPath?: string;
+    /** Client name/version reported in the mandatory `hello` handshake. */
+    client?: string;
+    /** Per-request timeout (ms). Defaults to 10000. */
+    requestTimeoutMs?: number;
+    /** Auto-reconnect with capped backoff + re-subscribe on a dropped socket (ADR-0002 §6). */
+    autoReconnect?: boolean;
+    /** Initial reconnect backoff (ms). Defaults to 200. */
+    reconnectInitialDelayMs?: number;
+    /** Maximum reconnect backoff (ms). Defaults to 5000. */
+    reconnectMaxDelayMs?: number;
+}
+/** Handler invoked for each server-pushed `event` after `subscribeEvents`. */
+export type EventHandler = (event: EventParams) => void;
+/** Subscription handle returned by {@link CerastreamClient.subscribeEvents}. */
+export interface Subscription {
+    /** The topics actually subscribed to. */
+    readonly result: SubscribeEventsResult;
+    /** Stop receiving events for this subscription. Idempotent. */
+    close(): void;
+}
+/**
+ * Bidirectional JSON-RPC 2.0 control client for cerastream. One method per v1
+ * request plus the handshake. Server-push events arrive via `subscribeEvents`.
+ */
+export interface CerastreamClient {
+    /** Negotiated handshake result (protocol + schema/engine versions). */
+    readonly hello: HelloResult;
+    /** Start the streaming pipeline (encode → bond → SRT). */
+    start(params: StartParams): Promise<StartResult>;
+    /** Stop the streaming pipeline. Idempotent. Stops the pipeline, NOT the OS process. */
+    stop(params?: StopParams): Promise<StopResult>;
+    /** Hot-reload engine config (replaces SIGHUP). Returns the applied config. */
+    reloadConfig(params: ReloadConfigParams): Promise<ReloadConfigResult>;
+    /** Hot-adjust max bitrate while streaming. Returns the post-clamp applied value. */
+    setBitrate(params: SetBitrateParams): Promise<SetBitrateResult>;
+    /** Switch the active capture source (manual) or hand selection to failover (auto). */
+    switchInput(params: SwitchInputParams): Promise<SwitchInputResult>;
+    /** Enumerate capture devices (GstDeviceMonitor, de-duped by device path). */
+    listDevices(params?: ListDevicesParams): Promise<ListDevicesResult>;
+    /** Subscribe to the live event stream; `handler` fires for each pushed event. */
+    subscribeEvents(params: SubscribeEventsParams, handler: EventHandler): Promise<Subscription>;
+    /** Control a local preview session (WebCodecs binary tier / WebRTC signaling). */
+    previewSession(params: PreviewSessionParams): Promise<PreviewSessionResult>;
+    /** Close the control connection. Never respawns the engine (ADR-0005). */
+    close(): Promise<void>;
+}
+/**
+ * Connect to the cerastream control socket, run the mandatory `hello`
+ * handshake, and return a {@link CerastreamClient}.
+ */
+export declare function connect(options?: ConnectOptions): Promise<CerastreamClient>;

package/dist/client.js

@@ -0,0 +1,274 @@
+import { CONTROL_SOCKET_PATH, PROTOCOL_VERSION } from "./constants.js";
+import { helloResultSchema, rpcErrorSchema, rpcResponseSchema, } from "./envelope.js";
+import { CerastreamConnectionError, CerastreamRpcError, CerastreamTimeoutError, } from "./errors.js";
+import { eventParamsSchema } from "./events.js";
+import { controlSocketPath } from "./paths.js";
+import { requestSchemas, } from "./messages.js";
+import { LineSocket } from "./transport.js";
+const DEFAULTS = {
+    requestTimeoutMs: 10_000,
+    reconnectInitialDelayMs: 200,
+    reconnectMaxDelayMs: 5_000,
+};
+class ClientImpl {
+    hello;
+    socket;
+    nextId = 1;
+    pending = new Map();
+    subscriptions = new Set();
+    intentionalClose = false;
+    reconnecting = false;
+    socketPath;
+    clientName;
+    requestTimeoutMs;
+    autoReconnect;
+    reconnectInitialDelayMs;
+    reconnectMaxDelayMs;
+    constructor(options) {
+        this.socketPath =
+            options.socketPath ?? safeControlSocketPath();
+        this.clientName = options.client ?? "@ceralive/cerastream";
+        this.requestTimeoutMs =
+            options.requestTimeoutMs ?? DEFAULTS.requestTimeoutMs;
+        this.autoReconnect = options.autoReconnect ?? false;
+        this.reconnectInitialDelayMs =
+            options.reconnectInitialDelayMs ?? DEFAULTS.reconnectInitialDelayMs;
+        this.reconnectMaxDelayMs =
+            options.reconnectMaxDelayMs ?? DEFAULTS.reconnectMaxDelayMs;
+    }
+    async init() {
+        await this.openSocket();
+        this.hello = await this.handshake();
+    }
+    async openSocket() {
+        const socket = new LineSocket(this.socketPath);
+        try {
+            await socket.open({
+                onLine: (line) => this.onLine(line),
+                onClose: (err) => this.onClose(err),
+            });
+        }
+        catch (err) {
+            throw new CerastreamConnectionError(`failed to connect to cerastream control socket at ${this.socketPath}`, err);
+        }
+        this.socket = socket;
+    }
+    async handshake() {
+        const raw = await this.rawRequest("hello", {
+            protocol: PROTOCOL_VERSION,
+            client: this.clientName,
+        });
+        return helloResultSchema.parse(raw);
+    }
+    start(params) {
+        return this.call("start", params);
+    }
+    stop(params) {
+        return this.call("stop", params);
+    }
+    reloadConfig(params) {
+        return this.call("reload-config", params);
+    }
+    setBitrate(params) {
+        return this.call("set-bitrate", params);
+    }
+    switchInput(params) {
+        return this.call("switch-input", params);
+    }
+    listDevices(params) {
+        return this.call("list-devices", params);
+    }
+    previewSession(params) {
+        return this.call("preview-session", params);
+    }
+    async subscribeEvents(params, handler) {
+        const result = await this.call("subscribe-events", params);
+        const sub = {
+            result,
+            handler,
+            topics: result.subscribed,
+            close: () => {
+                this.subscriptions.delete(sub);
+            },
+        };
+        this.subscriptions.add(sub);
+        return sub;
+    }
+    async close() {
+        this.intentionalClose = true;
+        for (const sub of this.subscriptions)
+            sub.close();
+        const conn = new CerastreamConnectionError("client closed");
+        this.rejectAllPending(conn);
+        this.socket?.close();
+        this.socket = undefined;
+    }
+    // Typed request: validate params, send, validate the result against the
+    // frozen Zod contract (TS → engine and engine → TS over the same schema).
+    async call(method, params) {
+        const pair = requestSchemas[method];
+        const parsedParams = pair.params.parse(params);
+        const raw = await this.rawRequest(method, parsedParams);
+        return pair.result.parse(raw);
+    }
+    rawRequest(method, params) {
+        const socket = this.socket;
+        if (!socket) {
+            return Promise.reject(new CerastreamConnectionError("control connection is not open"));
+        }
+        const id = this.nextId++;
+        const envelope = {
+            jsonrpc: "2.0",
+            id,
+            method,
+        };
+        if (params !== undefined)
+            envelope.params = params;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new CerastreamTimeoutError(method, this.requestTimeoutMs));
+            }, this.requestTimeoutMs);
+            this.pending.set(id, { method, resolve, reject, timer });
+            try {
+                socket.send(JSON.stringify(envelope));
+            }
+            catch (err) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(new CerastreamConnectionError("failed to write request", err));
+            }
+        });
+    }
+    onLine(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return; // a non-JSON line is not addressable to any request; drop it.
+        }
+        if (!isObject(msg))
+            return;
+        if (msg.method === "event") {
+            this.dispatchEvent(msg.params);
+            return;
+        }
+        if (!("id" in msg))
+            return;
+        const id = msg.id;
+        if ("error" in msg) {
+            this.settleError(msg);
+            return;
+        }
+        if ("result" in msg && id != null) {
+            const pending = this.pending.get(id);
+            if (!pending)
+                return;
+            this.pending.delete(id);
+            clearTimeout(pending.timer);
+            const parsed = rpcResponseSchema.safeParse(msg);
+            if (parsed.success)
+                pending.resolve(parsed.data.result);
+            else
+                pending.resolve(msg.result);
+        }
+    }
+    settleError(msg) {
+        const parsed = rpcErrorSchema.safeParse(msg);
+        if (!parsed.success)
+            return;
+        const { id, error } = parsed.data;
+        const rpcErr = new CerastreamRpcError(error.code, error.message, error.data?.code, id);
+        if (id == null)
+            return; // parse error with null id — no request to settle.
+        const pending = this.pending.get(id);
+        if (!pending)
+            return;
+        this.pending.delete(id);
+        clearTimeout(pending.timer);
+        pending.reject(rpcErr);
+    }
+    dispatchEvent(params) {
+        const parsed = eventParamsSchema.safeParse(params);
+        if (!parsed.success)
+            return;
+        const event = parsed.data;
+        for (const sub of this.subscriptions) {
+            if (sub.topics.includes(event.type))
+                sub.handler(event);
+        }
+    }
+    onClose(err) {
+        this.socket = undefined;
+        if (this.intentionalClose)
+            return;
+        const conn = new CerastreamConnectionError("control connection lost", err);
+        this.rejectAllPending(conn);
+        if (this.autoReconnect)
+            void this.reconnectLoop();
+    }
+    rejectAllPending(err) {
+        for (const [, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.reject(err);
+        }
+        this.pending.clear();
+    }
+    async reconnectLoop() {
+        if (this.reconnecting)
+            return;
+        this.reconnecting = true;
+        let delay = this.reconnectInitialDelayMs;
+        while (!this.intentionalClose) {
+            await sleep(delay);
+            if (this.intentionalClose)
+                break;
+            try {
+                await this.openSocket();
+                this.hello = await this.handshake();
+                await this.resubscribe();
+                this.reconnecting = false;
+                return;
+            }
+            catch {
+                this.socket?.close();
+                this.socket = undefined;
+                delay = Math.min(delay * 2, this.reconnectMaxDelayMs);
+            }
+        }
+        this.reconnecting = false;
+    }
+    async resubscribe() {
+        const topics = new Set();
+        for (const sub of this.subscriptions)
+            for (const t of sub.topics)
+                topics.add(t);
+        if (topics.size === 0)
+            return;
+        await this.rawRequest("subscribe-events", { topics: [...topics] });
+    }
+}
+function safeControlSocketPath() {
+    try {
+        return controlSocketPath();
+    }
+    catch {
+        return CONTROL_SOCKET_PATH;
+    }
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Connect to the cerastream control socket, run the mandatory `hello`
+ * handshake, and return a {@link CerastreamClient}.
+ */
+export async function connect(options) {
+    const client = new ClientImpl(options ?? {});
+    await client.init();
+    return client;
+}

package/dist/config.d.ts

@@ -0,0 +1,16 @@
+import { type CerastreamConfig, type PartialCerastreamConfig } from "./types.js";
+/** Default on-device config path (systemd `StateDirectory=cerastream`). */
+export declare const DEFAULT_CONFIG_PATH = "/var/lib/cerastream/config.json";
+/** Validate and pretty-print a config to its canonical JSON form. */
+export declare function serializeCerastreamConfig(config: PartialCerastreamConfig): string;
+/** Validate `config` and write it to disk as canonical JSON. Returns the path. */
+export declare function writeCerastreamConfig(config: PartialCerastreamConfig, path?: string): string;
+/** Read + validate a config from disk. Throws on a missing file or bad shape. */
+export declare function readCerastreamConfig(path?: string): CerastreamConfig;
+/**
+ * Coerce a loose/legacy config object into a valid {@link CerastreamConfig},
+ * filling defaults for any omitted bitrate/SRT/balancer field before validation.
+ * Use it to migrate a stored profile to the current schema; it throws if the
+ * required `pipeline` + `srt.host`/`srt.port` cannot be recovered.
+ */
+export declare function migrateCerastreamConfig(input: unknown): CerastreamConfig;

package/dist/config.js

@@ -0,0 +1,54 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { DEFAULT_BALANCER, DEFAULT_MAX_BITRATE, DEFAULT_MIN_BITRATE, DEFAULT_SRT_LATENCY, } from "./constants.js";
+import { cerastreamConfigSchema, } from "./types.js";
+// Persisted-config helpers. The unified engine config IS the `start` params
+// (types.cerastreamConfigSchema), so a config written here is exactly what
+// `client.start()` accepts — wire shape and stored profile cannot drift.
+/** Default on-device config path (systemd `StateDirectory=cerastream`). */
+export const DEFAULT_CONFIG_PATH = "/var/lib/cerastream/config.json";
+/** Validate and pretty-print a config to its canonical JSON form. */
+export function serializeCerastreamConfig(config) {
+    const parsed = cerastreamConfigSchema.parse(config);
+    return `${JSON.stringify(parsed, null, 2)}\n`;
+}
+/** Validate `config` and write it to disk as canonical JSON. Returns the path. */
+export function writeCerastreamConfig(config, path = DEFAULT_CONFIG_PATH) {
+    writeFileSync(path, serializeCerastreamConfig(config));
+    return path;
+}
+/** Read + validate a config from disk. Throws on a missing file or bad shape. */
+export function readCerastreamConfig(path = DEFAULT_CONFIG_PATH) {
+    return cerastreamConfigSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+/**
+ * Coerce a loose/legacy config object into a valid {@link CerastreamConfig},
+ * filling defaults for any omitted bitrate/SRT/balancer field before validation.
+ * Use it to migrate a stored profile to the current schema; it throws if the
+ * required `pipeline` + `srt.host`/`srt.port` cannot be recovered.
+ */
+export function migrateCerastreamConfig(input) {
+    if (typeof input !== "object" || input === null) {
+        throw new TypeError("migrateCerastreamConfig: expected a config object");
+    }
+    const raw = input;
+    const srt = asRecord(raw.srt);
+    const bitrate = asRecord(raw.bitrate);
+    const candidate = {
+        ...raw,
+        srt: {
+            ...srt,
+            latency_ms: srt.latency_ms ?? DEFAULT_SRT_LATENCY,
+        },
+        bitrate: {
+            min_bitrate: bitrate.min_bitrate ?? DEFAULT_MIN_BITRATE,
+            max_bitrate: bitrate.max_bitrate ?? DEFAULT_MAX_BITRATE,
+            balancer: bitrate.balancer ?? DEFAULT_BALANCER,
+        },
+    };
+    return cerastreamConfigSchema.parse(candidate);
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null
+        ? value
+        : {};
+}

package/dist/constants.d.ts

@@ -0,0 +1,31 @@
+/** JSON-RPC handshake protocol major. Bumped only on a breaking schema change. */
+export declare const PROTOCOL_VERSION: "cerastream-ipc/1";
+/**
+ * Wire-schema contract version, pinned cross-language with the Rust engine
+ * (`crates/cerastream-ipc/src/constants.rs`) and the conformance fixtures. It
+ * versions the JSON message shapes — NOT the npm release line, which is the CalVer
+ * in `package.json` (see CHANGELOG "Versioning"). The schema shape is frozen and
+ * additive-only within protocol major `cerastream-ipc/1` (ADR-0002 §4); this value
+ * only moves when the wire schema itself does, in lockstep across both languages.
+ */
+export declare const SCHEMA_VERSION: "0.1.0-stub";
+/** Runtime dir holding both control + preview sockets. systemd `RuntimeDirectory=cerastream`. */
+export declare const DEFAULT_IPC_DIR: "/run/cerastream";
+/** Env override for the IPC dir (tests/dev). Defaults to {@link DEFAULT_IPC_DIR}. */
+export declare const IPC_DIR_ENV: "CERASTREAM_IPC_DIR";
+/** Control-plane socket basename (JSON-RPC 2.0 / NDJSON). */
+export declare const CONTROL_SOCKET_NAME: "control.sock";
+/** Preview socket basename (length-prefixed binary frames). */
+export declare const PREVIEW_SOCKET_NAME: "preview.sock";
+/** Default control-plane socket path. */
+export declare const CONTROL_SOCKET_PATH: "/run/cerastream/control.sock";
+/** Default binary preview socket path. */
+export declare const PREVIEW_SOCKET_PATH: "/run/cerastream/preview.sock";
+/** Per-line framing cap (ADR-0002 §1): an oversized line is a fatal protocol error. */
+export declare const MAX_LINE_BYTES: number;
+/** Engine binary name (systemd-owned; CeraUI never spawns it — ADR-0005). */
+export declare const CERASTREAM_BIN: "cerastream";
+export declare const DEFAULT_MIN_BITRATE = 300;
+export declare const DEFAULT_MAX_BITRATE = 6000;
+export declare const DEFAULT_SRT_LATENCY = 2000;
+export declare const DEFAULT_BALANCER: "adaptive";

package/dist/constants.js

@@ -0,0 +1,35 @@
+// Protocol, socket, and version constants for the cerastream control IPC.
+// These are CONTRACT values (ADR-0002 / schema.md), not implementation logic —
+// they are the stable wire/runtime literals every consumer derives from.
+/** JSON-RPC handshake protocol major. Bumped only on a breaking schema change. */
+export const PROTOCOL_VERSION = "cerastream-ipc/1";
+/**
+ * Wire-schema contract version, pinned cross-language with the Rust engine
+ * (`crates/cerastream-ipc/src/constants.rs`) and the conformance fixtures. It
+ * versions the JSON message shapes — NOT the npm release line, which is the CalVer
+ * in `package.json` (see CHANGELOG "Versioning"). The schema shape is frozen and
+ * additive-only within protocol major `cerastream-ipc/1` (ADR-0002 §4); this value
+ * only moves when the wire schema itself does, in lockstep across both languages.
+ */
+export const SCHEMA_VERSION = "0.1.0-stub";
+/** Runtime dir holding both control + preview sockets. systemd `RuntimeDirectory=cerastream`. */
+export const DEFAULT_IPC_DIR = "/run/cerastream";
+/** Env override for the IPC dir (tests/dev). Defaults to {@link DEFAULT_IPC_DIR}. */
+export const IPC_DIR_ENV = "CERASTREAM_IPC_DIR";
+/** Control-plane socket basename (JSON-RPC 2.0 / NDJSON). */
+export const CONTROL_SOCKET_NAME = "control.sock";
+/** Preview socket basename (length-prefixed binary frames). */
+export const PREVIEW_SOCKET_NAME = "preview.sock";
+/** Default control-plane socket path. */
+export const CONTROL_SOCKET_PATH = "/run/cerastream/control.sock";
+/** Default binary preview socket path. */
+export const PREVIEW_SOCKET_PATH = "/run/cerastream/preview.sock";
+/** Per-line framing cap (ADR-0002 §1): an oversized line is a fatal protocol error. */
+export const MAX_LINE_BYTES = 1024 * 1024; // 1 MiB
+/** Engine binary name (systemd-owned; CeraUI never spawns it — ADR-0005). */
+export const CERASTREAM_BIN = "cerastream";
+// ---- config defaults (mirror ceracoder, the engine being replaced) ----
+export const DEFAULT_MIN_BITRATE = 300; // kbps
+export const DEFAULT_MAX_BITRATE = 6000; // kbps
+export const DEFAULT_SRT_LATENCY = 2000; // ms
+export const DEFAULT_BALANCER = "adaptive";

package/dist/envelope.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+export declare const jsonrpcVersion: z.ZodLiteral<"2.0">;
+export declare const requestId: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+export type RequestId = z.infer<typeof requestId>;
+export declare const rpcRequestSchema: z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+    method: z.ZodString;
+    params: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type RpcRequest = z.infer<typeof rpcRequestSchema>;
+export declare const rpcResponseSchema: z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+    result: z.ZodUnknown;
+}, z.core.$strip>;
+export type RpcResponse = z.infer<typeof rpcResponseSchema>;
+export declare const rpcErrorSchema: z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    id: z.ZodNullable<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    error: z.ZodObject<{
+        code: z.ZodNumber;
+        message: z.ZodString;
+        data: z.ZodOptional<z.ZodObject<{
+            code: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type RpcError = z.infer<typeof rpcErrorSchema>;
+export declare const rpcEventSchema: z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    method: z.ZodLiteral<"event">;
+    params: z.ZodObject<{
+        type: z.ZodString;
+        seq: z.ZodNumber;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+export type RpcEvent = z.infer<typeof rpcEventSchema>;
+export declare const helloParamsSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"cerastream-ipc/1">;
+    client: z.ZodString;
+}, z.core.$strip>;
+export type HelloParams = z.infer<typeof helloParamsSchema>;
+export declare const helloResultSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"cerastream-ipc/1">;
+    schema_version: z.ZodString;
+    engine_version: z.ZodString;
+}, z.core.$strip>;
+export type HelloResult = z.infer<typeof helloResultSchema>;

package/dist/envelope.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { PROTOCOL_VERSION } from "./constants.js";
+// JSON-RPC 2.0 envelope, newline-delimited over the control UDS (ADR-0002 §2,
+// schema.md "Envelope"). The JSON shape on the wire is the contract — not any
+// Rust serde type.
+export const jsonrpcVersion = z.literal("2.0");
+export const requestId = z.union([z.number().int(), z.string()]);
+// ---- request: client → server ----
+export const rpcRequestSchema = z.object({
+    jsonrpc: jsonrpcVersion,
+    id: requestId,
+    method: z.string(),
+    params: z.unknown().optional(),
+});
+// ---- success response: server → client ----
+export const rpcResponseSchema = z.object({
+    jsonrpc: jsonrpcVersion,
+    id: requestId,
+    result: z.unknown(),
+});
+// ---- error response: server → client ----
+export const rpcErrorSchema = z.object({
+    jsonrpc: jsonrpcVersion,
+    id: requestId.nullable(),
+    error: z.object({
+        code: z.number().int(), // JSON-RPC numeric (see errors.ts RPC_ERROR_NUMERIC)
+        message: z.string(),
+        // stable string code under data.code (errors.ts rpcErrorCodeSchema)
+        data: z.object({ code: z.string() }).passthrough().optional(),
+    }),
+});
+// ---- event: server → client, no id ----
+export const rpcEventSchema = z.object({
+    jsonrpc: jsonrpcVersion,
+    method: z.literal("event"),
+    params: z
+        .object({
+        type: z.string(), // event type (see events.ts)
+        seq: z.number().int().nonnegative(), // per-type monotonic counter
+    })
+        .passthrough(),
+});
+// ---- handshake: hello (mandatory first call, ADR-0002 §4) ----
+export const helloParamsSchema = z.object({
+    protocol: z.literal(PROTOCOL_VERSION),
+    client: z.string(), // e.g. "ceraui-backend/2026.6.0"
+});
+export const helloResultSchema = z.object({
+    protocol: z.literal(PROTOCOL_VERSION),
+    schema_version: z.string(), // @ceralive/cerastream semver
+    engine_version: z.string(), // cerastream CalVer build
+});