@synapse-sdk/core 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @synapse-sdk/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of the Synapse SDK for JavaScript. Documentation: the repository.

package/dist/clock.d.ts

@@ -0,0 +1,105 @@
+import type { TimeOffsets, TimeRequest, TimeResponse } from "./types.ts";
+/** Probes sent back to back at connect; the lowest-RTT one is the first estimate. */
+export declare const CLOCK_BURST = 7;
+/** One probe every 2 s after the burst. */
+export declare const CLOCK_INTERVAL_US = 2000000;
+/** The sliding window the candidate (lowest RTT) is picked from. */
+export declare const CLOCK_WINDOW = 15;
+/** Largest change to the estimate per probe after the burst, microseconds. */
+export declare const CLOCK_MAX_SLEW_US = 500;
+/** The four timestamps of one probe (Cristian / SNTP): `t1` local send, `t2` remote receive, `t3` remote send, `t4` local receive. */
+export interface Probe {
+    t1: number;
+    t2: number;
+    t3: number;
+    t4: number;
+}
+/** Local clock minus remote clock: `((t1 − t2) + (t4 − t3)) / 2` (integer division toward zero, as Rust's i64 `/`). Off by at most `probeRttUs / 2` on an uneven path. */
+export declare function probeOffsetUs(p: Probe): number;
+/** Network round trip `(t4 − t1) − (t3 − t2)`: the remote's own processing time is excluded. */
+export declare function probeRttUs(p: Probe): number;
+/** One answered probe as the window keeps it. */
+export interface ClockSample {
+    /** Local minus remote, from this probe alone. */
+    offsetUs: number;
+    rttUs: number;
+    /** Local clock when the answer arrived (`t4`). */
+    at: number;
+}
+/** What a node reports about its clock (SDK §4.4 `clock()`); the camelCase spelling of Rust's `ClockInfo`. */
+export interface ClockInfo {
+    /** This node's time-domain id. */
+    dom: string;
+    /** The broker's time-domain id (from the hello). */
+    brokerDom: string;
+    /** `dom − brokerDom`, microseconds; 0 until the first sample and when `sameDom`. */
+    offsetUs: number;
+    /** Error bound on `offsetUs`; 0 when `sameDom`. */
+    epsUs: number;
+    /** Round trip of the sample the estimate rests on. */
+    rttUs: number;
+    /** `offsetUs` now minus the offset at the end of the connect burst: the drift tracked so far. */
+    driftUs: number;
+    /** Probes answered on this session. */
+    samples: number;
+    /** `dom === brokerDom`: the broker's clock is ours, nothing to estimate. */
+    sameDom: boolean;
+    /** Local clock when the estimate last changed (`undefined` before the first sample). */
+    updatedAt: number | undefined;
+}
+/** Whether `offsetUs`/`epsUs` mean anything yet: same domain, or at least one sample. */
+export declare function hasEstimate(c: ClockInfo): boolean;
+/**
+ * The estimator for one session. Drive it with `nextProbeAt()`, `request()` and `response()`;
+ * read `info()` (a new object on every change, so it can sit in a cell).
+ */
+export declare class ClockSync {
+    #private;
+    /** A fresh estimator for a session whose hello named `brokerDom`. When it equals `dom` the estimator is done at once: 0 ± 0, `nextProbeAt()` undefined. */
+    constructor(dom: string, brokerDom: string, nowUs: number);
+    info(): ClockInfo;
+    get sameDom(): boolean;
+    /** The window's samples, oldest first. */
+    samples(): readonly ClockSample[];
+    /**
+     * When the next probe is due in the local clock: `undefined` when there is nothing to probe (same
+     * domain), the time of the previous probe (i.e. right away) while the burst is not spent, then
+     * `CLOCK_INTERVAL_US` after the previous probe. A probe that got no answer still counts as sent,
+     * so a dead link is probed at the interval, not hammered.
+     */
+    nextProbeAt(): number | undefined;
+    /** Builds the next `synapse/time` request with `t1 = nowUs` and the current estimate, if any. Marks the probe sent; the answer goes to `response()`. */
+    request(nowUs: number): TimeRequest;
+    /** The probe got no answer (timeout, session lost): forget it; the schedule goes on. */
+    probeLost(): void;
+    /**
+     * Records the answer to the outstanding probe, read at local time `t4`, and updates the estimate.
+     * Returns the sample, or `undefined` when the answer is not to the outstanding probe (`t1`
+     * differs: late or duplicate) or the broker turned out to share our domain (then the estimator
+     * switches to the same-domain shortcut).
+     */
+    response(resp: TimeResponse, t4: number): ClockSample | undefined;
+}
+/** A publisher's stamp converted into our clock, with the error bound to fold into any freshness judgment. */
+export interface LocalTime {
+    localUs: number;
+    epsUs: number;
+}
+/**
+ * Converts `tUs`, stamped by a publisher in time domain `dom`, into the clock of the node `me`
+ * describes (SDK §4.4, the three judgment modes):
+ * - same domain (`dom === me.dom`): exact, `epsUs` 0;
+ * - different domain with a known offset: through the broker's clock,
+ *   `local = tUs − offset(dom) + offset(me)`, `eps = eps(dom) + eps(me)`; the broker's own domain
+ *   has offset 0 and eps 0, the publisher's comes from the `runtime/time` table, ours from `me`;
+ * - no entry for `dom` (or no estimate of our own yet): `undefined`, no judgment: never drop on age.
+ */
+export declare function toLocalUs(me: ClockInfo, table: TimeOffsets, tUs: number, dom: string): LocalTime | undefined;
+/** How old a frame is on our clock (`nowUs − local`), with the conversion's error bound; `undefined` when no judgment is possible. */
+export interface Age {
+    ageUs: number;
+    epsUs: number;
+}
+export declare function ageOf(me: ClockInfo, table: TimeOffsets, tUs: number, dom: string, nowUs: number): Age | undefined;
+/** The erring-stale rule (SDK §4.4): a frame that *might* be older than `thresholdUs` counts as stale; an unknown age is never judged. */
+export declare function isStale(age: Age | undefined, thresholdUs: number): boolean;

package/dist/clock.js

@@ -0,0 +1,136 @@
+/** Probes sent back to back at connect; the lowest-RTT one is the first estimate. */
+export const CLOCK_BURST = 7;
+/** One probe every 2 s after the burst. */
+export const CLOCK_INTERVAL_US = 2_000_000;
+/** The sliding window the candidate (lowest RTT) is picked from. */
+export const CLOCK_WINDOW = 15;
+/** Largest change to the estimate per probe after the burst, microseconds. */
+export const CLOCK_MAX_SLEW_US = 500;
+const U32_MAX = 0xffff_ffff;
+/** Local clock minus remote clock: `((t1 − t2) + (t4 − t3)) / 2` (integer division toward zero, as Rust's i64 `/`). Off by at most `probeRttUs / 2` on an uneven path. */
+export function probeOffsetUs(p) { return Math.trunc((p.t1 - p.t2 + (p.t4 - p.t3)) / 2); }
+/** Network round trip `(t4 − t1) − (t3 − t2)`: the remote's own processing time is excluded. */
+export function probeRttUs(p) { return p.t4 - p.t1 - (p.t3 - p.t2); }
+function freshClockInfo(dom, brokerDom, updatedAt) {
+    const sameDom = dom === brokerDom;
+    return { dom, brokerDom, offsetUs: 0, epsUs: 0, rttUs: 0, driftUs: 0, samples: 0, sameDom, updatedAt: sameDom ? updatedAt : undefined };
+}
+/** Whether `offsetUs`/`epsUs` mean anything yet: same domain, or at least one sample. */
+export function hasEstimate(c) { return c.sameDom || c.samples > 0; }
+/**
+ * The estimator for one session. Drive it with `nextProbeAt()`, `request()` and `response()`;
+ * read `info()` (a new object on every change, so it can sit in a cell).
+ */
+export class ClockSync {
+    #info;
+    #window = [];
+    #estimate;
+    #sent = 0;
+    #outstanding;
+    #lastProbeAt;
+    #startedAt;
+    /** A fresh estimator for a session whose hello named `brokerDom`. When it equals `dom` the estimator is done at once: 0 ± 0, `nextProbeAt()` undefined. */
+    constructor(dom, brokerDom, nowUs) {
+        this.#info = freshClockInfo(dom, brokerDom, nowUs);
+        this.#startedAt = nowUs;
+    }
+    info() { return this.#info; }
+    get sameDom() { return this.#info.sameDom; }
+    /** The window's samples, oldest first. */
+    samples() { return this.#window; }
+    /**
+     * When the next probe is due in the local clock: `undefined` when there is nothing to probe (same
+     * domain), the time of the previous probe (i.e. right away) while the burst is not spent, then
+     * `CLOCK_INTERVAL_US` after the previous probe. A probe that got no answer still counts as sent,
+     * so a dead link is probed at the interval, not hammered.
+     */
+    nextProbeAt() {
+        if (this.#info.sameDom)
+            return undefined;
+        if (this.#lastProbeAt === undefined)
+            return this.#startedAt;
+        return this.#sent < CLOCK_BURST ? this.#lastProbeAt : this.#lastProbeAt + CLOCK_INTERVAL_US;
+    }
+    /** Builds the next `synapse/time` request with `t1 = nowUs` and the current estimate, if any. Marks the probe sent; the answer goes to `response()`. */
+    request(nowUs) {
+        this.#sent++;
+        this.#lastProbeAt = nowUs;
+        this.#outstanding = nowUs;
+        const req = { t1: nowUs, dom: this.#info.dom };
+        if (this.#estimate && !this.#info.sameDom) {
+            req.offset_us = this.#estimate.offsetUs;
+            req.rtt_us = this.#info.rttUs;
+            req.eps_us = this.#info.epsUs;
+        }
+        return req;
+    }
+    /** The probe got no answer (timeout, session lost): forget it; the schedule goes on. */
+    probeLost() { this.#outstanding = undefined; }
+    /**
+     * Records the answer to the outstanding probe, read at local time `t4`, and updates the estimate.
+     * Returns the sample, or `undefined` when the answer is not to the outstanding probe (`t1`
+     * differs: late or duplicate) or the broker turned out to share our domain (then the estimator
+     * switches to the same-domain shortcut).
+     */
+    response(resp, t4) {
+        if (this.#outstanding !== resp.t1)
+            return undefined;
+        this.#outstanding = undefined;
+        if (resp.dom === this.#info.dom) {
+            this.#info = freshClockInfo(this.#info.dom, resp.dom, t4);
+            this.#estimate = undefined;
+            this.#window.length = 0;
+            return undefined;
+        }
+        const probe = { t1: resp.t1, t2: resp.t2, t3: resp.t3, t4 };
+        const sample = { offsetUs: probeOffsetUs(probe), rttUs: Math.min(Math.max(probeRttUs(probe), 0), U32_MAX), at: t4 };
+        this.#window.push(sample);
+        while (this.#window.length > CLOCK_WINDOW)
+            this.#window.shift();
+        // The candidate: lowest RTT in the window, the newest on a tie (it carries the least drift).
+        let candidate = this.#window[0];
+        for (const s of this.#window)
+            if (s.rttUs <= candidate.rttUs)
+                candidate = s;
+        const inBurst = this.#sent <= CLOCK_BURST;
+        const prev = this.#estimate;
+        // No estimate yet, or still in the burst: the lowest-RTT sample *is* the estimate; afterwards slew toward it.
+        const offsetUs = !prev || inBurst ? candidate.offsetUs : prev.offsetUs + Math.min(Math.max(candidate.offsetUs - prev.offsetUs, -CLOCK_MAX_SLEW_US), CLOCK_MAX_SLEW_US);
+        const initialUs = prev && !inBurst ? prev.initialUs : offsetUs;
+        this.#estimate = { offsetUs, initialUs };
+        const residual = Math.min(Math.abs(candidate.offsetUs - offsetUs), U32_MAX);
+        const i = this.#info;
+        this.#info = { ...i, offsetUs, rttUs: candidate.rttUs, epsUs: Math.min(Math.trunc(candidate.rttUs / 2) + residual, U32_MAX), driftUs: offsetUs - initialUs, samples: i.samples + 1, updatedAt: t4 };
+        return sample;
+    }
+}
+/**
+ * Converts `tUs`, stamped by a publisher in time domain `dom`, into the clock of the node `me`
+ * describes (SDK §4.4, the three judgment modes):
+ * - same domain (`dom === me.dom`): exact, `epsUs` 0;
+ * - different domain with a known offset: through the broker's clock,
+ *   `local = tUs − offset(dom) + offset(me)`, `eps = eps(dom) + eps(me)`; the broker's own domain
+ *   has offset 0 and eps 0, the publisher's comes from the `runtime/time` table, ours from `me`;
+ * - no entry for `dom` (or no estimate of our own yet): `undefined`, no judgment: never drop on age.
+ */
+export function toLocalUs(me, table, tUs, dom) {
+    if (dom === me.dom)
+        return { localUs: tUs, epsUs: 0 };
+    if (!hasEstimate(me))
+        return undefined;
+    let offPub = 0, epsPub = 0;
+    if (dom !== me.brokerDom) {
+        const e = table[dom];
+        if (!e)
+            return undefined;
+        offPub = e.offset_us;
+        epsPub = e.eps_us;
+    }
+    return { localUs: tUs - offPub + me.offsetUs, epsUs: Math.min(epsPub + me.epsUs, U32_MAX) };
+}
+export function ageOf(me, table, tUs, dom, nowUs) {
+    const l = toLocalUs(me, table, tUs, dom);
+    return l && { ageUs: nowUs - l.localUs, epsUs: l.epsUs };
+}
+/** The erring-stale rule (SDK §4.4): a frame that *might* be older than `thresholdUs` counts as stale; an unknown age is never judged. */
+export function isStale(age, thresholdUs) { return age !== undefined && age.ageUs + age.epsUs > thresholdUs; }

package/dist/contracts.d.ts

@@ -0,0 +1,127 @@
+import { type JsonSchema } from "./schema.ts";
+import type { StandardSchemaV1 } from "./standard.ts";
+import { type Card, type Delivery, type FecParams, type Role, type TrackDesc, type TimeDomain } from "./types.ts";
+export type ToJsonSchema = (schema: StandardSchemaV1, io: "input" | "output") => JsonSchema;
+/** Registers a fallback converter for validators without `~standard.jsonSchema` (e.g. valibot via `@valibot/to-json-schema`). */
+export declare function setJsonSchemaConverter(fn: ToJsonSchema | undefined): void;
+/** JSON Schema 2020-12 for a Standard Schema. Uses `~standard.jsonSchema` when the library ships it, else the converter. `$schema` is dropped so hashes do not depend on the dialect URL. */
+export declare function jsonSchemaOf(schema: StandardSchemaV1, io: "input" | "output", toJsonSchema?: ToJsonSchema): JsonSchema;
+/** The MIME type of a msgpack body, the default `contentType`. */
+export declare const MSGPACK = "application/msgpack";
+/** The MIME type of a body the SDK does not touch (a `raw` topic). */
+export declare const OCTET_STREAM = "application/octet-stream";
+export interface TopicDef<S extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined> {
+    /** Slash path (`imu`, `cam/front`). */
+    name: string;
+    /** The body's schema; its JSON Schema rides in the descriptor and the value type is inferred from it. */
+    schema?: S;
+    /** How frames travel (WP §6): `datagram` (the default: one datagram per message, newest wins) or `stream` (ordered, nothing dropped). */
+    delivery?: Delivery;
+    /** MIME type of the body; default `application/msgpack`. A topic with another type is `raw`: bodies are bytes. */
+    contentType?: string;
+    /** `datagram` only: FEC coding of each message into symbols (WP §6.3), for bodies larger than a datagram (video). `symbolSize` 0 = sized from the session's datagram budget. */
+    fec?: TopicFec | true;
+    /** Describes a raw body's layout for other readers (e.g. a video stream's codec and dimensions). */
+    layout?: Record<string, unknown>;
+    toJsonSchema?: ToJsonSchema;
+}
+export interface TopicFec {
+    symbolSize?: number;
+    repairPct?: number;
+    deadlineMs?: number;
+}
+export interface TopicContract<TIn = unknown, TOut = TIn> {
+    readonly kind: "topic";
+    readonly name: string;
+    readonly schema: StandardSchemaV1<TIn, TOut> | undefined;
+    readonly delivery: Delivery;
+    readonly contentType: string;
+    /** `true` when the body is not msgpack: published and delivered as bytes. */
+    readonly raw: boolean;
+    /** FEC parameters (wire shape); `symbol_size` 0 = sized from the session. Only on `datagram` topics. */
+    readonly fec: FecParams | undefined;
+    readonly layout: Record<string, unknown> | undefined;
+    /** JSON Schema of the wire body (input side: defaulted fields optional), or undefined for schemaless/raw topics. */
+    readonly jsonSchema: JsonSchema | undefined;
+    /** sha256 of the canonical JSON Schema; rides in the descriptor. */
+    readonly schemaHash: string | undefined;
+    /** Builds the WP §7.2 descriptor for a publisher in time domain `dom`. */
+    desc(dom: TimeDomain): TrackDesc;
+    /** Phantom types for inference; never set at runtime. */
+    readonly "~types"?: {
+        input: TIn;
+        output: TOut;
+    };
+}
+export type TopicInput<T> = T extends TopicContract<infer I, unknown> ? I : unknown;
+export type TopicOutput<T> = T extends TopicContract<unknown, infer O> ? O : unknown;
+export declare function defineTopic<S extends StandardSchemaV1>(def: TopicDef<S> & {
+    schema: S;
+}): TopicContract<StandardSchemaV1.InferInput<S>, StandardSchemaV1.InferOutput<S>>;
+export declare function defineTopic(def: TopicDef<undefined> & {
+    contentType: string;
+}): TopicContract<Uint8Array, Uint8Array>;
+export declare function defineTopic<T = unknown>(def: TopicDef<undefined>): TopicContract<T, T>;
+/** A topic argument: a contract or a bare name (the string escape hatch: msgpack, `datagram`, no schema). */
+export type TopicRef<TIn = unknown, TOut = TIn> = TopicContract<TIn, TOut> | string;
+export declare function topicName(ref: TopicRef): string;
+/** Resolves the string escape hatch to an ad-hoc contract. */
+export declare function resolveTopic<TIn, TOut>(ref: TopicRef<TIn, TOut>): TopicContract<TIn, TOut>;
+export interface ServiceDef<I extends StandardSchemaV1 | undefined, U extends StandardSchemaV1 | undefined, O extends StandardSchemaV1 | undefined> {
+    /** Slash path like a topic (`arm/getPose`); filled in by `defineApi` when omitted. */
+    name?: string;
+    input?: I;
+    /** The progress updates a long call sends (`ctx.update`); the card says `streaming` when present. */
+    update?: U;
+    output?: O;
+    /** Minimum caller role enforced by the broker (card `min_role`); default `agent`. */
+    minRole?: Role;
+    description?: string;
+    /** Whether a caller may cancel (card `cancelable`); default true. */
+    cancelable?: boolean;
+    toJsonSchema?: ToJsonSchema;
+}
+export interface ServiceContract<TArgs = unknown, TInput = TArgs, TUpdate = unknown, TResult = unknown> {
+    readonly kind: "service";
+    /** Service name, a slash path (`arm/getPose`); empty until `defineApi` names it. */
+    name: string;
+    readonly input: StandardSchemaV1<TArgs, TInput> | undefined;
+    readonly update: StandardSchemaV1<unknown, TUpdate> | undefined;
+    readonly output: StandardSchemaV1<unknown, TResult> | undefined;
+    readonly minRole: Role;
+    readonly description: string | undefined;
+    readonly cancelable: boolean;
+    readonly jsonSchemas: {
+        input?: JsonSchema;
+        update?: JsonSchema;
+        output?: JsonSchema;
+    };
+    /** Hash over `{input, update, output}` (what a caller compares a listed card against). */
+    readonly schemaHash: string;
+    /** Builds the WP §8.5 card. */
+    card(): Card;
+    readonly "~types"?: {
+        args: TArgs;
+        input: TInput;
+        update: TUpdate;
+        result: TResult;
+    };
+}
+export type ServiceArgs<S> = S extends ServiceContract<infer A, unknown, unknown, unknown> ? A : unknown;
+export type ServiceInput<S> = S extends ServiceContract<unknown, infer I, unknown, unknown> ? I : unknown;
+export type ServiceUpdate<S> = S extends ServiceContract<unknown, unknown, infer U, unknown> ? U : unknown;
+export type ServiceResult<S> = S extends ServiceContract<unknown, unknown, unknown, infer R> ? R : unknown;
+type InOr<S, D> = S extends StandardSchemaV1 ? StandardSchemaV1.InferInput<S> : D;
+type OutOr<S, D> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : D;
+export declare function defineService<I extends StandardSchemaV1 | undefined = undefined, U extends StandardSchemaV1 | undefined = undefined, O extends StandardSchemaV1 | undefined = undefined>(def: ServiceDef<I, U, O>): ServiceContract<InOr<I, unknown>, OutOr<I, unknown>, OutOr<U, unknown>, OutOr<O, unknown>>;
+/** A service argument: a contract or a bare name (the string escape hatch: untyped args and result). */
+export type ServiceRef<TArgs = unknown, TInput = TArgs, TUpdate = unknown, TResult = unknown> = ServiceContract<TArgs, TInput, TUpdate, TResult> | string;
+export declare function serviceName(ref: ServiceRef): string;
+/** Nested tree of service contracts; `defineApi` names each leaf by its slash path (`arm/getPose`, like topics). */
+export type ApiTree = {
+    readonly [k: string]: ServiceContract<any, any, any, any> | ApiTree;
+};
+export declare function defineApi<T extends ApiTree>(tree: T, prefix?: string): T;
+export declare function isServiceContract(v: unknown): v is ServiceContract<any, any, any, any>;
+export declare function isTopicContract(v: unknown): v is TopicContract<any, any>;
+export {};

package/dist/contracts.js

@@ -0,0 +1,148 @@
+// Contracts (SDK §3): `defineTopic`, `defineService`, `defineApi` on Standard Schema V1.
+// A contract is a plain object; `import type` of one pulls no runtime code. A contract gives one
+// declaration to both sides of a topic or a service: the publisher's/provider's descriptor or card
+// (the JSON Schema the broker serves) and the subscriber's/caller's static types.
+import { cardSchemaHash, schemaHash } from "./schema.js";
+import { FEC_DEFAULTS } from "./types.js";
+let globalToJsonSchema;
+/** Registers a fallback converter for validators without `~standard.jsonSchema` (e.g. valibot via `@valibot/to-json-schema`). */
+export function setJsonSchemaConverter(fn) { globalToJsonSchema = fn; }
+/** JSON Schema 2020-12 for a Standard Schema. Uses `~standard.jsonSchema` when the library ships it, else the converter. `$schema` is dropped so hashes do not depend on the dialect URL. */
+export function jsonSchemaOf(schema, io, toJsonSchema) {
+    const conv = schema["~standard"].jsonSchema;
+    let js;
+    if (conv)
+        js = conv[io]({ target: "draft-2020-12" });
+    else if (toJsonSchema ?? globalToJsonSchema)
+        js = (toJsonSchema ?? globalToJsonSchema)(schema, io);
+    else
+        throw new Error(`schema from ${schema["~standard"].vendor} has no ~standard.jsonSchema; pass toJsonSchema or call setJsonSchemaConverter()`);
+    if ("$schema" in js) {
+        const { $schema: _drop, ...rest } = js;
+        return rest;
+    }
+    return js;
+}
+function memo(f) { const m = { done: false }; return () => { if (!m.done) {
+    m.v = f();
+    m.done = true;
+} return m.v; }; }
+// ------------------------------------------------------------------------------------- topics
+/** The MIME type of a msgpack body, the default `contentType`. */
+export const MSGPACK = "application/msgpack";
+/** The MIME type of a body the SDK does not touch (a `raw` topic). */
+export const OCTET_STREAM = "application/octet-stream";
+export function defineTopic(def) {
+    const contentType = def.contentType ?? MSGPACK;
+    const raw = contentType !== MSGPACK;
+    const schema = def.schema;
+    if (schema && raw)
+        throw new Error(`topic ${def.name}: a ${contentType} topic cannot carry a schema`);
+    const delivery = def.delivery ?? "datagram";
+    if (def.fec && delivery !== "datagram")
+        throw new Error(`topic ${def.name}: fec is a datagram setting (WP §6)`);
+    const f = def.fec === true ? {} : def.fec;
+    const fec = f ? { symbol_size: f.symbolSize ?? 0, repair_pct: f.repairPct ?? FEC_DEFAULTS.repair_pct, deadline_ms: f.deadlineMs ?? FEC_DEFAULTS.deadline_ms } : undefined;
+    if (fec && fec.symbol_size !== 0 && (fec.symbol_size < 8 || fec.symbol_size % 8 !== 0))
+        throw new Error(`topic ${def.name}: fec symbolSize must be a multiple of 8`);
+    const js = memo(() => (schema ? jsonSchemaOf(schema, "input", def.toJsonSchema) : undefined));
+    const hash = memo(() => { const s = js(); return s ? schemaHash(s) : undefined; });
+    const c = {
+        kind: "topic",
+        name: def.name,
+        schema,
+        delivery,
+        contentType,
+        raw,
+        fec,
+        layout: def.layout,
+        get jsonSchema() { return js(); },
+        get schemaHash() { return hash(); },
+        desc(dom) {
+            const d = { delivery: this.delivery, content_type: this.contentType, dom };
+            const s = js();
+            if (s) {
+                d.schema = s;
+                d.schema_hash = hash();
+            }
+            if (this.layout)
+                d.layout = this.layout;
+            if (this.fec)
+                d.fec = { ...this.fec };
+            return d;
+        },
+    };
+    return c;
+}
+export function topicName(ref) { return typeof ref === "string" ? ref : ref.name; }
+/** Resolves the string escape hatch to an ad-hoc contract. */
+export function resolveTopic(ref) {
+    if (typeof ref !== "string")
+        return ref;
+    return defineTopic({ name: ref });
+}
+export function defineService(def) {
+    const js = memo(() => {
+        const out = {};
+        if (def.input)
+            out.input = jsonSchemaOf(def.input, "input", def.toJsonSchema);
+        if (def.update)
+            out.update = jsonSchemaOf(def.update, "output", def.toJsonSchema);
+        if (def.output)
+            out.output = jsonSchemaOf(def.output, "output", def.toJsonSchema);
+        return out;
+    });
+    const hash = memo(() => { const s = js(); return cardSchemaHash(s.input, s.update, s.output); });
+    const c = {
+        kind: "service",
+        name: def.name ?? "",
+        input: def.input,
+        update: def.update,
+        output: def.output,
+        minRole: def.minRole ?? "agent",
+        description: def.description,
+        cancelable: def.cancelable ?? true,
+        get jsonSchemas() { return js(); },
+        get schemaHash() { return hash(); },
+        card() {
+            if (!this.name)
+                throw new Error("service contract has no name; give it one or place it in defineApi()");
+            const s = js();
+            const card = { name: this.name, streaming: !!def.update, cancelable: this.cancelable, min_role: this.minRole };
+            if (this.description !== undefined)
+                card.description = this.description;
+            if (s.input)
+                card.input_schema = s.input;
+            if (s.output)
+                card.output_schema = s.output;
+            if (s.update)
+                card.update_schema = s.update;
+            return card;
+        },
+    };
+    return c;
+}
+export function serviceName(ref) {
+    const n = typeof ref === "string" ? ref : ref.name;
+    if (!n)
+        throw new Error("service contract has no name; give it one or place it in defineApi()");
+    return n;
+}
+export function defineApi(tree, prefix = "") {
+    for (const [k, v] of Object.entries(tree)) {
+        const path = prefix ? `${prefix}/${k}` : k;
+        if (isServiceContract(v)) {
+            if (!v.name)
+                v.name = path;
+        }
+        else
+            defineApi(v, path);
+    }
+    return tree;
+}
+export function isServiceContract(v) {
+    return !!v && typeof v === "object" && v.kind === "service";
+}
+export function isTopicContract(v) {
+    return !!v && typeof v === "object" && v.kind === "topic";
+}