@clamator/protocol 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @clamator/protocol
+
+Pure JSON-RPC 2.0 protocol primitives plus Zod-derived envelope types for clamator. **No I/O, ever** — anything that touches a network, filesystem, or process belongs in a transport adapter.
+
+## Install
+
+```bash
+npm install @clamator/protocol
+```
+
+## When you reach for this
+
+- Authoring a Zod contract that will be fed to [`@clamator/codegen`](https://www.npmjs.com/package/@clamator/codegen).
+- Building a custom transport adapter that needs the wire-envelope schema, the `Transport` and `Dispatcher` interfaces, or the reserved JSON-RPC error codes.
+
+If you only consume generated clients and servers, you don't import this package directly — your transport package (`@clamator/over-memory`, `@clamator/over-redis`) re-exports the few symbols you need.
+
+## Defining a contract
+
+Contracts are the source of truth that both sides — and the codegen — consume:
+
+```typescript
+const arith = defineContract('arith', {
+  add: defineMethod({
+    params: z.object({ a: z.number(), b: z.number() }),
+    result: z.object({ sum: z.number() }),
+  }),
+  divide: defineMethod({
+    params: z.object({ a: z.number(), b: z.number() }),
+    result: z.object({ q: z.number() }),
+  }),
+  ping: defineNotification({ params: z.object({ tag: z.string().optional() }) }),
+});
+```
+
+(Verbatim from `ts/packages/over-memory/tests/loopback.test.ts`.)
+
+## Key exports
+
+- `defineContract`, `defineMethod`, `defineNotification` — declare a service's methods and notifications with Zod schemas for params and results.
+- `RpcError` — the error type you throw from a handler to surface a structured JSON-RPC error to the caller.
+- `ClamatorProtocolError`, `ClamatorTransportError` — distinguishable error classes for protocol-level vs. transport-level failures.
+- `Transport`, `Dispatcher` — interfaces a custom transport adapter implements.
+
+## Links
+
+- Sibling (Python): [`clamator-protocol`](https://pypi.org/project/clamator-protocol/)
+- Codegen: [`@clamator/codegen`](https://www.npmjs.com/package/@clamator/codegen)
+- Design spec: [`docs/2026-05-07-clamator-design.md`](../../../docs/2026-05-07-clamator-design.md)
+- Agent rules: [`AGENTS.md`](./AGENTS.md)

package/dist/client-core.d.ts

@@ -0,0 +1,19 @@
+import type { Transport } from './transport.js';
+export interface ClamatorClient {
+    call<P, R>(service: string, method: string, params: P): Promise<R>;
+    notify<P>(service: string, method: string, params: P): Promise<void>;
+}
+export interface RpcClientCoreOptions {
+    defaultTimeoutMs?: number;
+}
+export declare class RpcClientCore implements ClamatorClient {
+    private readonly transport;
+    private state;
+    private readonly defaultTimeoutMs;
+    constructor(transport: Transport, opts?: RpcClientCoreOptions);
+    call<P, R>(service: string, method: string, params: P): Promise<R>;
+    notify<P>(service: string, method: string, params: P): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=client-core.d.ts.map

package/dist/client-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-core.d.ts","sourceRoot":"","sources":["../src/client-core.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIhD,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACnE,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,aAAc,YAAW,cAAc;IAItC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAHtC,OAAO,CAAC,KAAK,CAA0C;IACvD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAEb,SAAS,EAAE,SAAS,EAAE,IAAI,GAAE,oBAAyB;IAI5E,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAiBlE,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAK5B"}

package/dist/client-core.js

@@ -0,0 +1,59 @@
+import { randomUUID } from 'node:crypto';
+import { SERVICE_RE, METHOD_RE, parseEnvelope, EnvelopeKind, buildRequest, buildNotification } from './envelope.js';
+import { RpcError, ClamatorProtocolError } from './error.js';
+export class RpcClientCore {
+    transport;
+    state = 'idle';
+    defaultTimeoutMs;
+    constructor(transport, opts = {}) {
+        this.transport = transport;
+        this.defaultTimeoutMs = opts.defaultTimeoutMs ?? 30_000;
+    }
+    async call(service, method, params) {
+        if (!SERVICE_RE.test(service))
+            throw new Error(`invalid service "${service}"`);
+        if (!METHOD_RE.test(method))
+            throw new Error(`invalid method "${method}"`);
+        const id = randomUUID();
+        const env = buildRequest(`${service}.${method}`, params, id);
+        const reply = await this.transport.send(env, { timeoutMs: this.defaultTimeoutMs });
+        let parsed;
+        try {
+            parsed = parseEnvelope(reply);
+        }
+        catch (e) {
+            throw new ClamatorProtocolError(`invalid response envelope: ${e.message}`);
+        }
+        if (parsed.kind === EnvelopeKind.SuccessResponse)
+            return parsed.result;
+        if (parsed.kind === EnvelopeKind.ErrorResponse) {
+            const { code, message, data } = parsed.error;
+            throw new RpcError(code, message, data);
+        }
+        throw new ClamatorProtocolError(`unexpected response kind: ${parsed.kind}`);
+    }
+    async notify(service, method, params) {
+        if (!SERVICE_RE.test(service))
+            throw new Error(`invalid service "${service}"`);
+        if (!METHOD_RE.test(method))
+            throw new Error(`invalid method "${method}"`);
+        await this.transport.notify(buildNotification(`${service}.${method}`, params));
+    }
+    async start() {
+        if (this.state === 'stopped')
+            throw new Error('client has been stopped');
+        if (this.state === 'started')
+            return;
+        await this.transport.start();
+        this.state = 'started';
+    }
+    async stop() {
+        if (this.state !== 'started') {
+            this.state = 'stopped';
+            return;
+        }
+        await this.transport.stop();
+        this.state = 'stopped';
+    }
+}
+//# sourceMappingURL=client-core.js.map

package/dist/client-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-core.js","sourceRoot":"","sources":["../src/client-core.ts"],"names":[],"mappings":"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"}

package/dist/contract.d.ts

@@ -0,0 +1,23 @@
+import type { z } from 'zod';
+export interface MethodDef<P extends z.ZodTypeAny, R extends z.ZodTypeAny> {
+    params: P;
+    result: R;
+    notification?: false;
+}
+export interface NotificationDef<P extends z.ZodTypeAny> {
+    params: P;
+    notification: true;
+}
+export type AnyMethodDef = MethodDef<z.ZodTypeAny, z.ZodTypeAny> | NotificationDef<z.ZodTypeAny>;
+export interface Contract<S extends string, M extends Record<string, AnyMethodDef>> {
+    service: S;
+    methods: M;
+}
+export declare function defineMethod<P extends z.ZodTypeAny, R extends z.ZodTypeAny>(def: MethodDef<P, R>): MethodDef<P, R>;
+export declare function defineNotification<P extends z.ZodTypeAny>(def: Omit<NotificationDef<P>, 'notification'>): NotificationDef<P>;
+export declare function defineContract<S extends string, M extends Record<string, AnyMethodDef>>(service: S, methods: M): Contract<S, M>;
+/** Inferred handler signatures from a contract's method map. */
+export type HandlersFor<M extends Record<string, AnyMethodDef>> = {
+    [K in keyof M]: M[K] extends NotificationDef<infer P> ? (params: z.infer<P>) => Promise<void> : M[K] extends MethodDef<infer P, infer R> ? (params: z.infer<P>) => Promise<z.infer<R>> : never;
+};
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,CAAC,UAAU;IACvE,MAAM,EAAE,CAAC,CAAC;IACV,MAAM,EAAE,CAAC,CAAC;IACV,YAAY,CAAC,EAAE,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU;IACrD,MAAM,EAAE,CAAC,CAAC;IACV,YAAY,EAAE,IAAI,CAAC;CACpB;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;AAEjG,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;IAChF,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,CAAC,CAAC;CACZ;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,CAAC,UAAU,EACzE,GAAG,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GACnB,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAEjB;AAED,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACvD,GAAG,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,GAC5C,eAAe,CAAC,CAAC,CAAC,CAEpB;AAED,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EACrF,OAAO,EAAE,CAAC,EACV,OAAO,EAAE,CAAC,GACT,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAgBhB;AAED,gEAAgE;AAChE,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,IAAI;KAC/D,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,eAAe,CAAC,MAAM,CAAC,CAAC,GACjD,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GACrC,CAAC,CAAC,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GACxC,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAC3C,KAAK;CACV,CAAC"}

package/dist/contract.js

@@ -0,0 +1,26 @@
+import { SERVICE_RE, METHOD_RE } from './envelope.js';
+export function defineMethod(def) {
+    return def;
+}
+export function defineNotification(def) {
+    return { ...def, notification: true };
+}
+export function defineContract(service, methods) {
+    if (!SERVICE_RE.test(service))
+        throw new Error(`invalid service name "${service}" (must match ${SERVICE_RE.source})`);
+    for (const [name, def] of Object.entries(methods)) {
+        if (!METHOD_RE.test(name))
+            throw new Error(`invalid method name "${name}" (must match ${METHOD_RE.source})`);
+        const isNotification = def.notification === true;
+        if (isNotification) {
+            if ('result' in def)
+                throw new Error(`notification "${name}" must not include result`);
+        }
+        else {
+            if (!('result' in def) || def.result === undefined)
+                throw new Error(`method "${name}" must include result schema`);
+        }
+    }
+    return { service, methods };
+}
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAoBtD,MAAM,UAAU,YAAY,CAC1B,GAAoB;IAEpB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,GAA6C;IAE7C,OAAO,EAAE,GAAG,GAAG,EAAE,YAAY,EAAE,IAAI,EAAwB,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,OAAU,EACV,OAAU;IAEV,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,yBAAyB,OAAO,iBAAiB,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;IACzF,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAClD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,iBAAiB,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QACpF,MAAM,cAAc,GAAI,GAA0C,CAAC,YAAY,KAAK,IAAI,CAAC;QACzF,IAAI,cAAc,EAAE,CAAC;YACnB,IAAI,QAAQ,IAAK,GAA0C;gBACzD,MAAM,IAAI,KAAK,CAAC,iBAAiB,IAAI,2BAA2B,CAAC,CAAC;QACtE,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,CAAC,QAAQ,IAAI,GAAG,CAAC,IAAK,GAA6C,CAAC,MAAM,KAAK,SAAS;gBAC3F,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,8BAA8B,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/dist/envelope.d.ts

@@ -0,0 +1,47 @@
+export declare const SERVICE_RE: RegExp;
+export declare const METHOD_RE: RegExp;
+export declare enum EnvelopeKind {
+    Request = "request",
+    Notification = "notification",
+    SuccessResponse = "success",
+    ErrorResponse = "error"
+}
+export type RpcId = string | number;
+export interface RequestEnvelope {
+    kind: EnvelopeKind.Request;
+    service: string;
+    method: string;
+    fullMethod: string;
+    params: unknown;
+    id: RpcId;
+    raw: Record<string, unknown>;
+}
+export interface NotificationEnvelope {
+    kind: EnvelopeKind.Notification;
+    service: string;
+    method: string;
+    fullMethod: string;
+    params: unknown;
+    raw: Record<string, unknown>;
+}
+export interface SuccessResponseEnvelope {
+    kind: EnvelopeKind.SuccessResponse;
+    id: RpcId;
+    result: unknown;
+}
+export interface ErrorResponseEnvelope {
+    kind: EnvelopeKind.ErrorResponse;
+    id: RpcId | null;
+    error: {
+        code: number;
+        message: string;
+        data: unknown;
+    };
+}
+export type Envelope = RequestEnvelope | NotificationEnvelope | SuccessResponseEnvelope | ErrorResponseEnvelope;
+export declare function parseEnvelope(value: unknown): Envelope;
+export declare function buildSuccessResponse(id: RpcId, result: unknown): Record<string, unknown>;
+export declare function buildErrorResponse(id: RpcId | null, code: number, message: string, data?: unknown): Record<string, unknown>;
+export declare function buildRequest(fullMethod: string, params: unknown, id: RpcId): Record<string, unknown>;
+export declare function buildNotification(fullMethod: string, params: unknown): Record<string, unknown>;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU,QAAsB,CAAC;AAC9C,eAAO,MAAM,SAAS,QAAyB,CAAC;AAGhD,oBAAY,YAAY;IACvB,OAAO,YAAY;IACnB,YAAY,iBAAiB;IAC7B,eAAe,YAAY;IAC3B,aAAa,UAAU;CACvB;AAED,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;AAEpC,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,EAAE,EAAE,KAAK,CAAC;IACV,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,YAAY,CAAC,YAAY,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACvC,IAAI,EAAE,YAAY,CAAC,eAAe,CAAC;IACnC,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,YAAY,CAAC,aAAa,CAAC;IACjC,EAAE,EAAE,KAAK,GAAG,IAAI,CAAC;IACjB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;CACxD;AAED,MAAM,MAAM,QAAQ,GACjB,eAAe,GACf,oBAAoB,GACpB,uBAAuB,GACvB,qBAAqB,CAAC;AASzB,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CA4DtD;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAExF;AAED,wBAAgB,kBAAkB,CACjC,EAAE,EAAE,KAAK,GAAG,IAAI,EAChB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,OAAc,GACjD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzB;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEpG;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9F"}

package/dist/envelope.js

@@ -0,0 +1,91 @@
+export const SERVICE_RE = /^[a-z][a-z0-9-]*$/;
+export const METHOD_RE = /^[a-z][a-zA-Z0-9-]*$/;
+// Plain string enum (NOT `const enum` — incompatible with `isolatedModules: true`).
+export var EnvelopeKind;
+(function (EnvelopeKind) {
+    EnvelopeKind["Request"] = "request";
+    EnvelopeKind["Notification"] = "notification";
+    EnvelopeKind["SuccessResponse"] = "success";
+    EnvelopeKind["ErrorResponse"] = "error";
+})(EnvelopeKind || (EnvelopeKind = {}));
+class InvalidRequest extends Error {
+    code = -32600;
+    constructor(msg) {
+        super(`-32600 Invalid Request: ${msg}`);
+    }
+}
+export function parseEnvelope(value) {
+    if (Array.isArray(value))
+        throw new InvalidRequest('batch requests not supported');
+    if (typeof value !== 'object' || value === null)
+        throw new InvalidRequest('not an object');
+    const obj = value;
+    if (obj.jsonrpc !== '2.0')
+        throw new InvalidRequest('jsonrpc must equal "2.0"');
+    const hasMethod = typeof obj.method === 'string';
+    const hasResult = 'result' in obj;
+    const hasError = 'error' in obj;
+    const hasId = 'id' in obj && obj.id !== null && obj.id !== undefined;
+    if (hasMethod) {
+        const fullMethod = obj.method;
+        const dot = fullMethod.indexOf('.');
+        if (dot <= 0 || dot === fullMethod.length - 1)
+            throw new InvalidRequest('method must be "<service>.<method>"');
+        const service = fullMethod.slice(0, dot);
+        const method = fullMethod.slice(dot + 1);
+        if (!SERVICE_RE.test(service))
+            throw new InvalidRequest('invalid service segment');
+        if (!METHOD_RE.test(method))
+            throw new InvalidRequest('invalid method segment');
+        if (hasId) {
+            const id = obj.id;
+            if (typeof id !== 'string' && typeof id !== 'number')
+                throw new InvalidRequest('id must be string or number');
+            return {
+                kind: EnvelopeKind.Request,
+                service, method, fullMethod,
+                params: obj.params ?? {},
+                id, raw: obj,
+            };
+        }
+        return {
+            kind: EnvelopeKind.Notification,
+            service, method, fullMethod,
+            params: obj.params ?? {},
+            raw: obj,
+        };
+    }
+    if (hasResult && !hasError) {
+        if (!hasId)
+            throw new InvalidRequest('response must have id');
+        return {
+            kind: EnvelopeKind.SuccessResponse,
+            id: obj.id,
+            result: obj.result,
+        };
+    }
+    if (hasError && !hasResult) {
+        const err = obj.error;
+        if (!err || typeof err.code !== 'number' || typeof err.message !== 'string')
+            throw new InvalidRequest('error must have numeric code + string message');
+        return {
+            kind: EnvelopeKind.ErrorResponse,
+            id: (hasId ? obj.id : null),
+            error: { code: err.code, message: err.message, data: err.data ?? null },
+        };
+    }
+    throw new InvalidRequest('envelope must be request, notification, or response');
+}
+export function buildSuccessResponse(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+export function buildErrorResponse(id, code, message, data = null) {
+    return { jsonrpc: '2.0', id, error: { code, message, data } };
+}
+export function buildRequest(fullMethod, params, id) {
+    return { jsonrpc: '2.0', method: fullMethod, params, id };
+}
+export function buildNotification(fullMethod, params) {
+    return { jsonrpc: '2.0', method: fullMethod, params };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,UAAU,GAAG,mBAAmB,CAAC;AAC9C,MAAM,CAAC,MAAM,SAAS,GAAG,sBAAsB,CAAC;AAEhD,oFAAoF;AACpF,MAAM,CAAN,IAAY,YAKX;AALD,WAAY,YAAY;IACvB,mCAAmB,CAAA;IACnB,6CAA6B,CAAA;IAC7B,2CAA2B,CAAA;IAC3B,uCAAuB,CAAA;AACxB,CAAC,EALW,YAAY,KAAZ,YAAY,QAKvB;AAyCD,MAAM,cAAe,SAAQ,KAAK;IACxB,IAAI,GAAG,CAAC,KAAK,CAAC;IACvB,YAAY,GAAW;QACtB,KAAK,CAAC,2BAA2B,GAAG,EAAE,CAAC,CAAC;IACzC,CAAC;CACD;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC3C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,cAAc,CAAC,8BAA8B,CAAC,CAAC;IACnF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,MAAM,IAAI,cAAc,CAAC,eAAe,CAAC,CAAC;IAC3F,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,IAAI,GAAG,CAAC,OAAO,KAAK,KAAK;QAAE,MAAM,IAAI,cAAc,CAAC,0BAA0B,CAAC,CAAC;IAEhF,MAAM,SAAS,GAAG,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC;IACjD,MAAM,SAAS,GAAG,QAAQ,IAAI,GAAG,CAAC;IAClC,MAAM,QAAQ,GAAG,OAAO,IAAI,GAAG,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,IAAI,GAAG,IAAI,GAAG,CAAC,EAAE,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,KAAK,SAAS,CAAC;IAErE,IAAI,SAAS,EAAE,CAAC;QACf,MAAM,UAAU,GAAG,GAAG,CAAC,MAAgB,CAAC;QACxC,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,KAAK,UAAU,CAAC,MAAM,GAAG,CAAC;YAC5C,MAAM,IAAI,cAAc,CAAC,qCAAqC,CAAC,CAAC;QACjE,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACzC,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,MAAM,IAAI,cAAc,CAAC,yBAAyB,CAAC,CAAC;QACnF,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,MAAM,IAAI,cAAc,CAAC,wBAAwB,CAAC,CAAC;QAChF,IAAI,KAAK,EAAE,CAAC;YACX,MAAM,EAAE,GAAG,GAAG,CAAC,EAAW,CAAC;YAC3B,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,OAAO,EAAE,KAAK,QAAQ;gBACnD,MAAM,IAAI,cAAc,CAAC,6BAA6B,CAAC,CAAC;YACzD,OAAO;gBACN,IAAI,EAAE,YAAY,CAAC,OAAO;gBAC1B,OAAO,EAAE,MAAM,EAAE,UAAU;gBAC3B,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE;gBACxB,EAAE,EAAE,GAAG,EAAE,GAAG;aACZ,CAAC;QACH,CAAC;QACD,OAAO;YACN,IAAI,EAAE,YAAY,CAAC,YAAY;YAC/B,OAAO,EAAE,MAAM,EAAE,UAAU;YAC3B,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE;YACxB,GAAG,EAAE,GAAG;SACR,CAAC;IACH,CAAC;IAED,IAAI,SAAS,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,cAAc,CAAC,uBAAuB,CAAC,CAAC;QAC9D,OAAO;YACN,IAAI,EAAE,YAAY,CAAC,eAAe;YAClC,EAAE,EAAE,GAAG,CAAC,EAAW;YACnB,MAAM,EAAE,GAAG,CAAC,MAAM;SAClB,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,IAAI,CAAC,SAAS,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,GAAG,CAAC,KAA4C,CAAC;QAC7D,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;YAC1E,MAAM,IAAI,cAAc,CAAC,+CAA+C,CAAC,CAAC;QAC3E,OAAO;YACN,IAAI,EAAE,YAAY,CAAC,aAAa;YAChC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAE,GAAG,CAAC,EAAY,CAAC,CAAC,CAAC,IAAI,CAAC;YACtC,KAAK,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,IAAI,EAAE;SACvE,CAAC;IACH,CAAC;IAED,MAAM,IAAI,cAAc,CAAC,qDAAqD,CAAC,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,EAAS,EAAE,MAAe;IAC9D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,kBAAkB,CACjC,EAAgB,EAChB,IAAY,EAAE,OAAe,EAAE,OAAgB,IAAI;IAEnD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,MAAe,EAAE,EAAS;IAC1E,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,UAAkB,EAAE,MAAe;IACpE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AACvD,CAAC"}

package/dist/error.d.ts

@@ -0,0 +1,14 @@
+export declare class RpcError extends Error {
+    readonly code: number;
+    readonly data: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+export declare class ClamatorProtocolError extends Error {
+    constructor(message: string);
+}
+export declare class ClamatorTransportError extends Error {
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare function exceptionToErrorData(err: unknown): Record<string, unknown>;
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBACX,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,OAAc;CAMhE;AAED,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBACZ,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,OAAc;CAKnD;AAID,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgB1E"}

package/dist/error.js

@@ -0,0 +1,47 @@
+export class RpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data = null) {
+        super(message);
+        this.name = 'RpcError';
+        this.code = code;
+        this.data = data;
+    }
+}
+export class ClamatorProtocolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ClamatorProtocolError';
+    }
+}
+export class ClamatorTransportError extends Error {
+    cause;
+    constructor(message, cause = null) {
+        super(message);
+        this.name = 'ClamatorTransportError';
+        this.cause = cause;
+    }
+}
+const SERIALIZABLE_TYPES = new Set(['string', 'number', 'boolean']);
+export function exceptionToErrorData(err) {
+    const out = {};
+    if (err instanceof Error) {
+        out.name = err.name;
+        out.message = err.message;
+        for (const key of Object.getOwnPropertyNames(err)) {
+            if (key === 'stack' || key === 'message' || key === 'name')
+                continue;
+            const v = err[key];
+            if (v === null || SERIALIZABLE_TYPES.has(typeof v))
+                out[key] = v;
+            else if (Array.isArray(v) && v.every(x => x === null || SERIALIZABLE_TYPES.has(typeof x)))
+                out[key] = v;
+        }
+    }
+    else {
+        out.name = typeof err;
+        out.message = String(err);
+    }
+    return out;
+}
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,CAAS;IACb,IAAI,CAAU;IACvB,YAAY,IAAY,EAAE,OAAe,EAAE,OAAgB,IAAI;QAC7D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACtC,KAAK,CAAU;IACxB,YAAY,OAAe,EAAE,QAAiB,IAAI;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;AAEpE,MAAM,UAAU,oBAAoB,CAAC,GAAY;IAC/C,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACpB,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;QAC1B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;YAClD,IAAI,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,MAAM;gBAAE,SAAS;YACrE,MAAM,CAAC,GAAI,GAA0C,CAAC,GAAG,CAAC,CAAC;YAC3D,IAAI,CAAC,KAAK,IAAI,IAAI,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;iBAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1G,CAAC;IACH,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,IAAI,GAAG,OAAO,GAAG,CAAC;QACtB,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { defineContract, defineMethod, defineNotification, type Contract, type MethodDef, type NotificationDef, type AnyMethodDef, type HandlersFor, } from './contract.js';
+export { parseEnvelope, buildRequest, buildNotification, buildSuccessResponse, buildErrorResponse, EnvelopeKind, SERVICE_RE, METHOD_RE, type Envelope, type RequestEnvelope, type NotificationEnvelope, type SuccessResponseEnvelope, type ErrorResponseEnvelope, type RpcId, } from './envelope.js';
+export { RpcError, ClamatorProtocolError, ClamatorTransportError, exceptionToErrorData, } from './error.js';
+export type { Transport, Dispatcher, SendOptions } from './transport.js';
+export { RpcServerCore, type ServerStopOptions } from './server-core.js';
+export { RpcClientCore, type ClamatorClient, type RpcClientCoreOptions } from './client-core.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EAAE,YAAY,EAAE,kBAAkB,EAChD,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,GACzF,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,aAAa,EAAE,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,kBAAkB,EACxF,YAAY,EAAE,UAAU,EAAE,SAAS,EACnC,KAAK,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,oBAAoB,EAC9D,KAAK,uBAAuB,EAAE,KAAK,qBAAqB,EAAE,KAAK,KAAK,GACrE,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,QAAQ,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,oBAAoB,GAC9E,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { defineContract, defineMethod, defineNotification, } from './contract.js';
+export { parseEnvelope, buildRequest, buildNotification, buildSuccessResponse, buildErrorResponse, EnvelopeKind, SERVICE_RE, METHOD_RE, } from './envelope.js';
+export { RpcError, ClamatorProtocolError, ClamatorTransportError, exceptionToErrorData, } from './error.js';
+export { RpcServerCore } from './server-core.js';
+export { RpcClientCore } from './client-core.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EAAE,YAAY,EAAE,kBAAkB,GAEjD,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,aAAa,EAAE,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,kBAAkB,EACxF,YAAY,EAAE,UAAU,EAAE,SAAS,GAGpC,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,QAAQ,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,oBAAoB,GAC9E,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,aAAa,EAA0B,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAkD,MAAM,kBAAkB,CAAC"}

package/dist/server-core.d.ts

@@ -0,0 +1,17 @@
+import type { Contract, AnyMethodDef, HandlersFor } from './contract.js';
+import type { Transport } from './transport.js';
+export interface ServerStopOptions {
+    graceMs?: number;
+}
+export declare class RpcServerCore {
+    private readonly transport;
+    private services;
+    private state;
+    private inflight;
+    constructor(transport: Transport);
+    registerService<M extends Record<string, AnyMethodDef>>(contract: Contract<string, M>, handlers: HandlersFor<M>): void;
+    private dispatcher;
+    start(): Promise<void>;
+    stop(opts?: ServerStopOptions): Promise<void>;
+}
+//# sourceMappingURL=server-core.d.ts.map

package/dist/server-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-core.d.ts","sourceRoot":"","sources":["../src/server-core.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,gBAAgB,CAAC;AAS5D,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,aAAa;IAKZ,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJtC,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,KAAK,CAA0C;IACvD,OAAO,CAAC,QAAQ,CAA+B;gBAElB,SAAS,EAAE,SAAS;IAEjD,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EACpD,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,EAC7B,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,GACvB,IAAI;IASP,OAAO,CAAC,UAAU;IAgDZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtB,IAAI,CAAC,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;CAaxD"}

package/dist/server-core.js

@@ -0,0 +1,104 @@
+import { EnvelopeKind, buildSuccessResponse, buildErrorResponse } from './envelope.js';
+import { RpcError, exceptionToErrorData } from './error.js';
+export class RpcServerCore {
+    transport;
+    services = new Map();
+    state = 'idle';
+    inflight = new Set();
+    constructor(transport) {
+        this.transport = transport;
+    }
+    registerService(contract, handlers) {
+        if (this.services.has(contract.service))
+            throw new Error(`service "${contract.service}" already registered on this server`);
+        this.services.set(contract.service, {
+            contract,
+            handlers: handlers,
+        });
+    }
+    dispatcher(serviceName) {
+        return async (env) => {
+            const entry = this.services.get(serviceName);
+            if (!entry) {
+                if (env.kind === EnvelopeKind.Notification)
+                    return null;
+                const id = env.kind === EnvelopeKind.Request ? env.id : null;
+                return buildErrorResponse(id, -32601, 'Method not found');
+            }
+            if (env.kind !== EnvelopeKind.Request && env.kind !== EnvelopeKind.Notification)
+                return null;
+            const methodDef = entry.contract.methods[env.method];
+            const id = env.kind === EnvelopeKind.Request ? env.id : null;
+            if (!methodDef) {
+                return env.kind === EnvelopeKind.Notification ? null : buildErrorResponse(id, -32601, 'Method not found');
+            }
+            let parsed;
+            try {
+                parsed = methodDef.params.parse(env.params);
+            }
+            catch (e) {
+                if (env.kind === EnvelopeKind.Notification)
+                    return null;
+                return buildErrorResponse(id, -32602, 'Invalid params', exceptionToErrorData(e));
+            }
+            const handler = entry.handlers[env.method];
+            if (!handler)
+                return env.kind === EnvelopeKind.Notification ? null : buildErrorResponse(id, -32601, 'Method not found');
+            const work = handler(parsed);
+            this.inflight.add(work);
+            let result;
+            try {
+                result = await work;
+            }
+            catch (e) {
+                this.inflight.delete(work);
+                if (env.kind === EnvelopeKind.Notification)
+                    return null;
+                if (e instanceof RpcError)
+                    return buildErrorResponse(id, e.code, e.message, e.data);
+                return buildErrorResponse(id, -32603, 'Internal error', exceptionToErrorData(e));
+            }
+            this.inflight.delete(work);
+            if (env.kind === EnvelopeKind.Notification)
+                return null;
+            const isNotificationDef = 'notification' in methodDef && methodDef.notification === true;
+            if (isNotificationDef)
+                return null;
+            try {
+                const validated = methodDef.result.parse(result);
+                return buildSuccessResponse(id, validated);
+            }
+            catch (e) {
+                return buildErrorResponse(id, -32603, 'Result validation failed', exceptionToErrorData(e));
+            }
+        };
+    }
+    async start() {
+        if (this.state === 'started')
+            return;
+        if (this.state === 'stopped')
+            throw new Error('server has been stopped');
+        for (const name of this.services.keys()) {
+            await this.transport.registerService(name, this.dispatcher(name));
+        }
+        await this.transport.start();
+        this.state = 'started';
+    }
+    async stop(opts = {}) {
+        if (this.state !== 'started') {
+            this.state = 'stopped';
+            return;
+        }
+        const grace = opts.graceMs ?? 5000;
+        const deadline = Date.now() + grace;
+        while (this.inflight.size > 0 && Date.now() < deadline) {
+            await Promise.race([
+                Promise.allSettled([...this.inflight]),
+                new Promise(r => setTimeout(r, 50)),
+            ]);
+        }
+        await this.transport.stop();
+        this.state = 'stopped';
+    }
+}
+//# sourceMappingURL=server-core.js.map

package/dist/server-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-core.js","sourceRoot":"","sources":["../src/server-core.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -0,0 +1,19 @@
+import type { Envelope } from './envelope.js';
+/** Adapter-side dispatch fn: returns Response envelope for requests, null for notifications. */
+export type Dispatcher = (env: Envelope) => Promise<Record<string, unknown> | null>;
+export interface SendOptions {
+    timeoutMs: number;
+}
+export interface Transport {
+    /** Register a handler for inbound traffic on a given service name. */
+    registerService(name: string, dispatch: Dispatcher): Promise<void>;
+    /** Send a request envelope; resolve with the response envelope. */
+    send(env: Record<string, unknown>, opts: SendOptions): Promise<Record<string, unknown>>;
+    /** Send a fire-and-forget notification envelope. */
+    notify(env: Record<string, unknown>): Promise<void>;
+    /** Spin up loops; idempotent. */
+    start(): Promise<void>;
+    /** Drain in-flight + close; idempotent. */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,gGAAgG;AAChG,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;AAEpF,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,mEAAmE;IACnE,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxF,oDAAoD;IACpD,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,iCAAiC;IACjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,2CAA2C;IAC3C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB"}

package/dist/transport.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@clamator/protocol",
+  "version": "0.1.0",
+  "description": "Polyglot RPC protocol layer (pre-1.0; API may break in minor versions).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}