@econ-v1/rpc 6.7.0 → 6.10.0

package/src/protocol.js

@@ -0,0 +1,758 @@
+// @ts-check
+
+/** @import { AppEventPayload, AppEventType, ClientError, CoreKernelEventType, DomainEvent, JsonObject, JsonValue, KernelEventPayload, QueryDiff, QueryName } from '@econ-v1/domain' */
+/** @typedef {{ readonly occurredAt: string; readonly payload: { readonly state?: string }; readonly type: "device-cleanup.changed" }} DeviceCleanupDomainEvent */
+/** @typedef {DomainEvent | DeviceCleanupDomainEvent} ProtocolDomainEvent */
+/** @typedef {CoreKernelEventType | "device-cleanup.changed"} ProtocolCoreKernelEventType */
+import { appEventInstance, appEventScope, isCoreKernelEventType, isKernelEventType, isQueryName, } from "@econ-v1/domain";
+import { deserializeClientError, isJsonObject, isSerializableClientError, serializeClientError, } from "./errors.js";
+/**
+ * @param {RpcRequest} request
+ * @returns {string}
+ */
+export function serializeRpcRequest(request) {
+    switch (request.type) {
+        case "command":
+            return stringify({ id: request.id, name: request.name, payload: request.payload, type: request.type });
+        case "query":
+            return stringify({ id: request.id, name: request.name, params: request.params, type: request.type });
+        case "live-query.subscribe":
+            return stringify({ id: request.id, name: request.name, params: request.params, subscriptionId: request.subscriptionId, type: request.type });
+        case "live-query.unsubscribe":
+        case "event.unsubscribe":
+            return stringify({ id: request.id, subscriptionId: request.subscriptionId, type: request.type });
+        case "event.subscribe":
+            return stringify({ eventType: request.eventType, id: request.id, subscriptionId: request.subscriptionId, type: request.type });
+        case "event.publish":
+            return stringify({ event: projectDomainEvent(request.event), id: request.id, type: request.type });
+        case "stage.prepare":
+            return stringify({ appName: request.appName, id: request.id, type: request.type });
+        case "stage.open-session":
+            return stringify({ appName: request.appName, id: request.id, manifestSha256: request.manifestSha256, type: request.type });
+        case "stage.query":
+            return stringify({ id: request.id, name: request.name, params: request.params, sessionId: request.sessionId, type: request.type });
+        case "stage.live-query.subscribe":
+            return stringify({ id: request.id, name: request.name, params: request.params, sessionId: request.sessionId, subscriptionId: request.subscriptionId, type: request.type });
+        case "stage.live-query.unsubscribe":
+        case "stage.event.unsubscribe":
+            return stringify({ id: request.id, sessionId: request.sessionId, subscriptionId: request.subscriptionId, type: request.type });
+        case "stage.event.subscribe":
+            return stringify({ eventType: request.eventType, id: request.id, sessionId: request.sessionId, subscriptionId: request.subscriptionId, type: request.type });
+        case "stage.event.publish":
+            return stringify({ event: projectDomainEvent(request.event), id: request.id, sessionId: request.sessionId, type: request.type });
+        case "stage.capability.invoke":
+            return stringify({ capability: request.capability, id: request.id, payload: request.payload, sessionId: request.sessionId, type: request.type });
+        case "stage.close-session":
+            return stringify({ id: request.id, sessionId: request.sessionId, type: request.type });
+    }
+}
+/**
+ * @param {string} serialized
+ * @returns {RpcRequest}
+ */
+export function deserializeRpcRequest(serialized) {
+    const value = parseRecord(serialized);
+    const type = stringField(value, "type");
+    const id = stringField(value, "id");
+    switch (type) {
+        case "command": return { id, name: versionedNameField(value, "name"), payload: jsonField(value, "payload"), type };
+        case "query": return { id, name: queryNameField(value), params: jsonField(value, "params"), type };
+        case "live-query.subscribe": return { id, name: queryNameField(value), params: jsonField(value, "params"), subscriptionId: stringField(value, "subscriptionId"), type };
+        case "live-query.unsubscribe": return { id, subscriptionId: stringField(value, "subscriptionId"), type };
+        case "event.subscribe": return { eventType: eventTypeField(value), id, subscriptionId: stringField(value, "subscriptionId"), type };
+        case "event.unsubscribe": return { id, subscriptionId: stringField(value, "subscriptionId"), type };
+        case "event.publish": return { event: domainEventField(value), id, type };
+        case "stage.prepare": return { appName: stringField(value, "appName"), id, type };
+        case "stage.open-session": return { appName: stringField(value, "appName"), id, manifestSha256: stringField(value, "manifestSha256"), type };
+        case "stage.query": return { id, name: queryNameField(value), params: jsonField(value, "params"), sessionId: stringField(value, "sessionId"), type };
+        case "stage.live-query.subscribe": return { id, name: queryNameField(value), params: jsonField(value, "params"), sessionId: stringField(value, "sessionId"), subscriptionId: stringField(value, "subscriptionId"), type };
+        case "stage.live-query.unsubscribe": return { id, sessionId: stringField(value, "sessionId"), subscriptionId: stringField(value, "subscriptionId"), type };
+        case "stage.event.subscribe": return { eventType: eventTypeField(value), id, sessionId: stringField(value, "sessionId"), subscriptionId: stringField(value, "subscriptionId"), type };
+        case "stage.event.unsubscribe": return { id, sessionId: stringField(value, "sessionId"), subscriptionId: stringField(value, "subscriptionId"), type };
+        case "stage.event.publish": return { event: domainEventField(value), id, sessionId: stringField(value, "sessionId"), type };
+        case "stage.capability.invoke": return { capability: stringField(value, "capability"), id, payload: jsonField(value, "payload"), sessionId: stringField(value, "sessionId"), type };
+        case "stage.close-session": return { id, sessionId: stringField(value, "sessionId"), type };
+        default: throw new TypeError("Unknown RPC request type");
+    }
+}
+/**
+ * @param {JsonObject} value
+ * @param {string} field
+ * @returns {string}
+ */
+function versionedNameField(value, field) {
+    const name = stringField(value, field);
+    if (!/^[-a-z0-9.]+\.v[1-9][0-9]*$/u.test(name))
+        throw new TypeError(`Expected ${field} to be versioned`);
+    return name;
+}
+/**
+ * @param {RpcResponse} response
+ * @returns {string}
+ */
+export function serializeRpcResponse(response) {
+    return response.ok
+        ? stringify({ id: response.id, ok: true, value: response.value })
+        : stringify({ error: serializeClientError(response.error), id: response.id, ok: false });
+}
+/**
+ * @param {string} serialized
+ * @returns {RpcResponse}
+ */
+export function deserializeRpcResponse(serialized) {
+    const value = parseRecord(serialized);
+    const id = stringField(value, "id");
+    if (value.ok === true)
+        return { id, ok: true, value: jsonField(value, "value") };
+    if (value.ok === false && isSerializableClientError(value.error))
+        return { error: deserializeClientError(value.error), id, ok: false };
+    throw new TypeError("Invalid RPC response");
+}
+/**
+ * @param {RpcEvent} event
+ * @returns {string}
+ */
+export function serializeRpcEvent(event) {
+    return event.type === "live-query.changed"
+        ? stringify({ diff: projectQueryDiff(event.diff), subscriptionId: event.subscriptionId, type: event.type })
+        : stringify({ event: projectDomainEvent(event.event), subscriptionId: event.subscriptionId, type: event.type });
+}
+/**
+ * @param {string} serialized
+ * @returns {RpcEvent}
+ */
+export function deserializeRpcEvent(serialized) {
+    const value = parseRecord(serialized);
+    const subscriptionId = stringField(value, "subscriptionId");
+    if (value.type === "live-query.changed")
+        return { diff: queryDiffField(value), subscriptionId, type: value.type };
+    if (value.type === "kernel.event")
+        return { event: domainEventField(value), subscriptionId, type: value.type };
+    throw new TypeError("Unknown RPC event type");
+}
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function stringify(value) {
+    return JSON.stringify(value);
+}
+/**
+ * @param {string} serialized
+ * @returns {JsonObject}
+ */
+function parseRecord(serialized) {
+    const value = JSON.parse(serialized);
+    if (!isJsonObject(value))
+        throw new TypeError("Expected an RPC object");
+    return value;
+}
+/**
+ * @param {JsonObject} value
+ * @param {string} field
+ * @returns {string}
+ */
+function stringField(value, field) {
+    const candidate = value[field];
+    if (typeof candidate !== "string")
+        throw new TypeError(`Expected ${field} to be a string`);
+    return candidate;
+}
+/**
+ * @param {JsonObject} value
+ * @param {string} field
+ * @returns {JsonValue}
+ */
+function jsonField(value, field) {
+    const candidate = value[field];
+    if (candidate === undefined)
+        throw new TypeError(`Expected ${field}`);
+    return candidate;
+}
+/**
+ * @param {JsonObject} value
+ * @returns {QueryName}
+ */
+function queryNameField(value) {
+    const name = stringField(value, "name");
+    if (!isQueryName(name))
+        throw new TypeError("Expected a versioned query name");
+    return name;
+}
+/**
+ * @param {JsonObject} value
+ * @returns {ProtocolDomainEvent["type"]}
+ */
+function eventTypeField(value) {
+    const type = stringField(value, "eventType");
+    if (!isKernelEventType(type))
+        throw new TypeError("Expected a known domain event type");
+    return /** @type {ProtocolDomainEvent["type"]} */ (type);
+}
+/**
+ * @param {JsonObject} value
+ * @returns {ProtocolDomainEvent}
+ */
+function domainEventField(value) {
+    const event = objectField(value, "event", "Expected a domain event");
+    const occurredAt = timestampField(event, "occurredAt");
+    const type = eventTypeField({ eventType: stringField(event, "type") });
+    // App events (`app.<resource>`) carry an app-defined payload, so they are decoded
+    // structurally rather than by the exhaustive core-event switch below. The switch
+    // stays exhaustive over `CoreKernelEventType`, which is what makes a new core event
+    // type a compile error here instead of a silent decode failure.
+    //
+    // The CLOSED vocabulary is tested FIRST. `AppEventType` is spelled `app.${string}`,
+    // which at the type level also matches core events that happen to start with `app.`
+    // (`app.data.changed`, `app.data.committed`) — testing the app branch first would
+    // narrow those two out of the switch below and break its exhaustiveness. The runtime
+    // guards already agree on this precedence: `isAppEventType` rejects a dotted resource,
+    // so `app.data.changed` was never an app event. This just makes the compiler agree.
+    if (type !== "device-cleanup.changed" && !isCoreKernelEventType(type)) {
+        const appType = /** @type {AppEventType} */ (type);
+        return { occurredAt, payload: appEventPayload(event, appType), type: appType };
+    }
+    const coreType = /** @type {ProtocolCoreKernelEventType} */ (type);
+    switch (coreType) {
+        case "transport.state-changed":
+            return { occurredAt, payload: transportStateChangedPayload(event), type: coreType };
+        case "stage.catalog-invalidated":
+            return { occurredAt, payload: stageCatalogInvalidatedPayload(event), type: coreType };
+        case "stage.registry-changed":
+            return { occurredAt, payload: stageRegistryChangedPayload(event), type: coreType };
+        case "query.invalidated":
+            return { occurredAt, payload: queryInvalidatedPayload(event), type: coreType };
+        case "outbox.state-changed":
+            return { occurredAt, payload: outboxStateChangedPayload(event), type: coreType };
+        case "domain.entity-changed":
+            return { occurredAt, payload: domainEntityChangedPayload(event), type: coreType };
+        case "sync.delta-applied":
+            return { occurredAt, payload: syncDeltaAppliedPayload(event), type: coreType };
+        case "client-storage.state-changed":
+            return { occurredAt, payload: clientStorageStateChangedPayload(event), type: coreType };
+        case "offline.stage-readiness-changed":
+            return { occurredAt, payload: offlineStageReadinessChangedPayload(event), type: coreType };
+        case "offline.identity-invalidated":
+            return { occurredAt, payload: offlineIdentityInvalidatedPayload(event), type: coreType };
+        case "app.data.changed":
+            return { occurredAt, payload: appDataEventPayload(event), type: coreType };
+        case "app.data.committed":
+            return { occurredAt, payload: appDataEventPayload(event), type: coreType };
+        case "onboarding.flow-changed":
+            return { occurredAt, payload: onboardingFlowChangedPayload(event), type: coreType };
+        case "device-cleanup.changed":
+            return { occurredAt, payload: deviceCleanupChangedPayload(event), type: coreType };
+        case "room.turn-stream":
+            return { occurredAt, payload: roomTurnStreamPayload(event), type: coreType };
+        case "room.job-stream":
+            return { occurredAt, payload: roomJobStreamPayload(event), type: coreType };
+    }
+}
+/**
+ * Decode an `app.<resource>` payload. The `resource` on the wire must match the
+ * resource encoded in the event type — a frame claiming `app.contest` while carrying
+ * `resource: "wallet"` is rejected rather than delivered, so a stage's declared
+ * `app.<resource>` scope cannot be widened by a malformed or hostile frame.
+ * @param {JsonObject} event
+ * @param {AppEventType} type
+ * @returns {AppEventPayload}
+ */
+function appEventPayload(event, type) {
+    const payload = objectField(event, "payload");
+    const resource = stringField(payload, "resource");
+    // The scope encoded in the type must match the payload's resource, so a frame
+    // claiming `app.contest` while carrying `resource: "wallet"` is rejected
+    // rather than delivered. The INSTANCE is compared separately: an
+    // instance-addressed type may legitimately carry the matching id.
+    if (appEventScope(type) !== `app.${resource}`) {
+        throw new TypeError("App event resource does not match its event type");
+    }
+    const instance = payload["instance"];
+    if (instance !== undefined && typeof instance !== "string") {
+        throw new TypeError("Expected instance to be a string");
+    }
+    const declaredInstance = appEventInstance(type);
+    if (declaredInstance !== undefined && instance !== undefined && instance !== declaredInstance) {
+        throw new TypeError("App event instance does not match its event type");
+    }
+    return {
+        data: objectField(payload, "data"),
+        ...(instance === undefined ? {} : { instance }),
+        resource,
+        type: stringField(payload, "type"),
+    };
+}
+/**
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"room.job-stream">}
+ */
+function roomJobStreamPayload(event) {
+    const payload = objectField(event, "payload");
+    const kind = stringField(payload, "kind");
+    if (kind !== "job" && kind !== "job_step")
+        throw new TypeError("Expected a known room job-stream kind");
+    const job = objectField(payload, "job");
+    /** @type {"open" | "done" | "aborted" | "capped"} */
+    const status = /** @type {"open" | "done" | "aborted" | "capped"} */ (stringField(job, "status"));
+    if (status !== "open" && status !== "done" && status !== "aborted" && status !== "capped")
+        throw new TypeError("Expected a known job status");
+    /** @type {"user" | "scheduled"} */
+    const origin = /** @type {"user" | "scheduled"} */ (stringField(job, "origin"));
+    if (origin !== "user" && origin !== "scheduled")
+        throw new TypeError("Expected a known job origin");
+    /** @param {JsonObject} source @param {string} field */
+    const optionalStr = (source, field) => {
+        const value = source[field];
+        if (value !== undefined && typeof value !== "string")
+            throw new TypeError(`Expected ${field} to be a string`);
+        return value;
+    };
+    /** @param {JsonObject} source @param {string} field */
+    const optionalNum = (source, field) => {
+        const value = source[field];
+        if (value !== undefined && typeof value !== "number")
+            throw new TypeError(`Expected ${field} to be a number`);
+        return value;
+    };
+    /** @param {JsonObject} source @param {string} field */
+    const numField = (source, field) => {
+        const value = source[field];
+        if (typeof value !== "number")
+            throw new TypeError(`Expected ${field} to be a number`);
+        return value;
+    };
+    const closedAt = optionalStr(job, "closedAt");
+    const openedBySeq = optionalNum(job, "openedBySeq");
+    const mappedJob = {
+        ...(closedAt === undefined ? {} : { closedAt }), jobId: stringField(job, "jobId"),
+        openedAt: stringField(job, "openedAt"), ...(openedBySeq === undefined ? {} : { openedBySeq }),
+        origin, pendingArrivals: numField(job, "pendingArrivals"), queueCount: numField(job, "queueCount"),
+        roomId: stringField(job, "roomId"), status, stepCount: numField(job, "stepCount"),
+        turnsUsed: numField(job, "turnsUsed"),
+    };
+    /** @type {KernelEventPayload<"room.job-stream">["step"]} */
+    let mappedStep;
+    if (payload.step !== undefined) {
+        const step = objectField(payload, "step");
+        const actor = objectField(step, "actor");
+        const actorKind = stringField(actor, "kind");
+        if (actorKind !== "orchestrator" && actorKind !== "specialist")
+            throw new TypeError("Expected a known step actor kind");
+        const name = optionalStr(actor, "name");
+        const slug = optionalStr(actor, "slug");
+        const outcome = optionalStr(step, "outcome");
+        const runId = optionalStr(step, "runId");
+        const seq = optionalNum(step, "seq");
+        mappedStep = {
+            actor: { kind: actorKind, ...(name === undefined ? {} : { name }), ...(slug === undefined ? {} : { slug }) },
+            detail: stringField(step, "detail"), kind: stringField(step, "kind"),
+            ...(outcome === undefined ? {} : { outcome }), ...(runId === undefined ? {} : { runId }),
+            ...(seq === undefined ? {} : { seq }), stepId: stringField(step, "stepId"), ts: stringField(step, "ts"),
+        };
+    }
+    return { job: mappedJob, kind, roomId: stringField(payload, "roomId"),
+        ...(mappedStep === undefined ? {} : { step: mappedStep }) };
+}
+/**
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"room.turn-stream">}
+ */
+function roomTurnStreamPayload(event) {
+    const payload = objectField(event, "payload");
+    const kind = stringField(payload, "kind");
+    if (kind !== "room.turn_started" && kind !== "turn.completed" && kind !== "turn.delta" &&
+        kind !== "turn.failed" && kind !== "turn.tool_delta" && kind !== "work.delta")
+        throw new TypeError("Expected a known room turn-stream kind");
+    /** @param {string} field */
+    const optional = (field) => {
+        const value = payload[field];
+        if (value !== undefined && typeof value !== "string")
+            throw new TypeError(`Expected ${field} to be a string`);
+        return value;
+    };
+    const anchorSession = stringField(payload, "anchorSession");
+    const agentName = optional("agentName");
+    const argsDelta = optional("argsDelta");
+    const runId = optional("runId");
+    const callId = optional("callId");
+    const callIndex = payload.callIndex;
+    if (callIndex !== undefined && typeof callIndex !== "number")
+        throw new TypeError("Expected callIndex to be a number");
+    const reason = optional("reason");
+    const responderName = optional("responderName");
+    const responderSlug = optional("responderSlug");
+    const text = optional("text");
+    const toolName = optional("toolName");
+    return {
+        ...(agentName === undefined ? {} : { agentName }), anchorSession,
+        ...(argsDelta === undefined ? {} : { argsDelta }), ...(callId === undefined ? {} : { callId }),
+        ...(callIndex === undefined ? {} : { callIndex }), kind, ...(reason === undefined ? {} : { reason }),
+        ...(responderName === undefined ? {} : { responderName }),
+        ...(responderSlug === undefined ? {} : { responderSlug }), roomId: stringField(payload, "roomId"),
+        ...(runId === undefined ? {} : { runId }), ...(text === undefined ? {} : { text }),
+        ...(toolName === undefined ? {} : { toolName }),
+    };
+}
+/**
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"client-storage.state-changed">}
+ */
+function clientStorageStateChangedPayload(event) {
+    const payload = objectField(event, "payload");
+    const status = stringField(payload, "status");
+    if (status !== "ready" && status !== "recovery-required" && status !== "starting") {
+        throw new TypeError("Expected a known client-storage status");
+    }
+    // `code`/`message` accompany "recovery-required" only; a wire frame that omits them for
+    // the other two states is well-formed, so they are decoded as optional rather than
+    // required-and-empty (which would erase the distinction the shell renders on).
+    const code = payload["code"];
+    const message = payload["message"];
+    if (code !== undefined && typeof code !== "string")
+        throw new TypeError("Expected code to be a string");
+    if (message !== undefined && typeof message !== "string") {
+        throw new TypeError("Expected message to be a string");
+    }
+    return {
+        ...(code === undefined ? {} : { code }),
+        ...(message === undefined ? {} : { message }),
+        status,
+    };
+}
+/**
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"offline.stage-readiness-changed">}
+ */
+function offlineStageReadinessChangedPayload(event) {
+    const payload = objectField(event, "payload");
+    const readiness = objectField(payload, "readiness");
+    const state = stringField(readiness, "state");
+    if (state !== "caching-assets" && state !== "needs-first-sync" &&
+        state !== "offline-ready" && state !== "update-available" &&
+        state !== "failed" && state !== "removing") {
+        throw new TypeError("Expected a known offline stage state");
+    }
+    const failureCode = optionalStringField(readiness, "failureCode");
+    if (failureCode !== undefined && failureCode !== "asset-fetch-failed" &&
+        failureCode !== "asset-integrity-failed" && failureCode !== "projection-seed-failed" &&
+        failureCode !== "schema-incompatible" && failureCode !== "quota-exceeded" &&
+        failureCode !== "identity-mismatch" && failureCode !== "active-resource-corrupt") {
+        throw new TypeError("Expected a known offline readiness failure code");
+    }
+    const activeManifestSha256 = optionalStringField(readiness, "activeManifestSha256");
+    const candidateManifestSha256 = optionalStringField(readiness, "candidateManifestSha256");
+    return {
+        readiness: {
+            ...(activeManifestSha256 === undefined ? {} : { activeManifestSha256 }),
+            appName: stringField(readiness, "appName"),
+            ...(candidateManifestSha256 === undefined ? {} : { candidateManifestSha256 }),
+            ...(failureCode === undefined ? {} : { failureCode }),
+            state,
+            updatedAt: timestampField(readiness, "updatedAt"),
+        },
+    };
+}
+/**
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"offline.identity-invalidated">}
+ */
+function offlineIdentityInvalidatedPayload(event) {
+    const payload = objectField(event, "payload");
+    const scope = objectField(payload, "scope");
+    return {
+        scope: {
+            deviceDid: stringField(scope, "deviceDid"),
+            homeNodeId: stringField(scope, "homeNodeId"),
+        },
+    };
+}
+/**
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"app.data.changed">}
+ */
+function appDataEventPayload(event) {
+    const payload = objectField(event, "payload");
+    return {
+        appName: stringField(payload, "appName"),
+        cursor: stringField(payload, "cursor"),
+        revision: stringField(payload, "revision"),
+        stream: stringField(payload, "stream"),
+    };
+}
+/**
+ * Decodes only `stepId`, because that is the entire payload the domain declares. Any other
+ * field a frame carries is dropped here rather than forwarded: this event crosses the wire to
+ * every subscriber, and the flow's secrets (the Wi-Fi password, the match-code digits, the
+ * invitation code) must not be able to ride along even if a future producer misbehaves.
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"onboarding.flow-changed">}
+ */
+function onboardingFlowChangedPayload(event) {
+    const payload = objectField(event, "payload");
+    return { stepId: stringField(payload, "stepId") };
+}
+/**
+ * @param {JsonObject} event
+ * @returns {{ readonly state?: string }}
+ */
+function deviceCleanupChangedPayload(event) {
+    const payload = objectField(event, "payload");
+    const state = optionalStringField(payload, "state");
+    return { ...(state === undefined ? {} : { state }) };
+}
+/**
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"stage.catalog-invalidated">}
+ */
+function stageCatalogInvalidatedPayload(event) {
+    const payload = objectField(event, "payload");
+    return { reason: stringField(payload, "reason") };
+}
+/**
+ * @param {JsonObject} value
+ * @returns {QueryDiff<JsonValue>}
+ */
+function queryDiffField(value) {
+    const record = objectField(value, "diff", "Expected a query diff");
+    return {
+        added: arrayField(record, "added"),
+        deleted: arrayField(record, "deleted"),
+        revision: numberField(record, "revision"),
+        updated: arrayField(record, "updated"),
+    };
+}
+/**
+ * @param {ProtocolDomainEvent} event
+ * @returns {object}
+ */
+function projectDomainEvent(event) {
+    return { occurredAt: event.occurredAt, payload: event.payload, type: event.type };
+}
+/**
+ * @param {QueryDiff<JsonValue>} diff
+ * @returns {object}
+ */
+function projectQueryDiff(diff) {
+    return { added: diff.added, deleted: diff.deleted, revision: diff.revision, updated: diff.updated };
+}
+/**
+ * @param {JsonObject} value
+ * @param {string} field
+ * @returns {readonly JsonValue[]}
+ */
+function arrayField(value, field) {
+    const candidate = value[field];
+    if (!Array.isArray(candidate))
+        throw new TypeError(`Expected ${field} to be an array`);
+    return candidate;
+}
+/**
+ * @param {JsonObject} value
+ * @param {string} field
+ * @returns {number}
+ */
+function numberField(value, field) {
+    const candidate = value[field];
+    if (typeof candidate !== "number" || !Number.isFinite(candidate)) {
+        throw new TypeError(`Expected ${field} to be a finite number`);
+    }
+    return candidate;
+}
+/** @param {JsonObject} value @param {string} field @returns {number} */
+function integerField(value, field) {
+    const candidate = numberField(value, field);
+    if (!Number.isInteger(candidate))
+        throw new TypeError(`Expected ${field} to be an integer`);
+    return candidate;
+}
+/** @param {JsonObject} value @param {string} field @returns {string | undefined} */
+function optionalStringField(value, field) {
+    const candidate = value[field];
+    if (candidate === undefined)
+        return undefined;
+    if (typeof candidate !== "string")
+        throw new TypeError(`Expected ${field} to be a string`);
+    return candidate;
+}
+/**
+ * @param {JsonObject} value
+ * @param {string} field
+ * @param {string} [message=`Expected ${field} to be an object`]
+ * @returns {JsonObject}
+ */
+function objectField(value, field, message = `Expected ${field} to be an object`) {
+    const candidate = value[field];
+    if (!isJsonObject(candidate))
+        throw new TypeError(message);
+    return candidate;
+}
+/**
+ * @param {JsonObject} value
+ * @param {string} field
+ * @returns {readonly string[]}
+ */
+function stringArrayField(value, field) {
+    const candidate = value[field];
+    if (!Array.isArray(candidate) || !candidate.every((item) => typeof item === "string")) {
+        throw new TypeError(`Expected ${field} to be an array of strings`);
+    }
+    return candidate;
+}
+/**
+ * @param {JsonObject} value
+ * @param {string} field
+ * @returns {string}
+ */
+function timestampField(value, field) {
+    const candidate = stringField(value, field);
+    const timestampPattern = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/u;
+    if (!timestampPattern.test(candidate) || !Number.isFinite(Date.parse(candidate))) {
+        throw new TypeError(`Expected ${field} to be an RFC 3339 timestamp`);
+    }
+    return candidate;
+}
+/**
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"transport.state-changed">}
+ */
+function transportStateChangedPayload(event) {
+    const payload = objectField(event, "payload");
+    const state = objectField(payload, "state");
+    const changedAt = timestampField(state, "changedAt");
+    const path = stringField(state, "path");
+    const status = stringField(state, "status");
+    if (status === "connected" && isConnectedTransportPath(path)) {
+        return { state: { changedAt, path, status } };
+    }
+    if (path === "offline") {
+        if (status === "connecting")
+            return { state: { attempt: integerField(state, "attempt"), changedAt, path, status } };
+        if (status === "reconnecting") {
+            return { state: { attempt: integerField(state, "attempt"), changedAt,
+                nextRetryAt: timestampField(state, "nextRetryAt"), path, status } };
+        }
+        if (status === "offline") {
+            const reason = optionalStringField(state, "reason");
+            if (reason !== undefined && !isTransportOfflineReason(reason))
+                throw new TypeError("Expected a valid transport offline reason");
+            return { state: { changedAt, path, status, ...(reason === undefined ? {} : { reason }) } };
+        }
+    }
+    throw new TypeError("Expected a valid transport state");
+}
+/**
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"stage.registry-changed">}
+ */
+function stageRegistryChangedPayload(event) {
+    const payload = objectField(event, "payload");
+    return { appNames: stringArrayField(payload, "appNames") };
+}
+/**
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"query.invalidated">}
+ */
+function queryInvalidatedPayload(event) {
+    const payload = objectField(event, "payload");
+    return { name: queryNameField(payload) };
+}
+/**
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"outbox.state-changed">}
+ */
+function outboxStateChangedPayload(event) {
+    const payload = objectField(event, "payload");
+    const intent = objectField(payload, "intent");
+    return {
+        intent: {
+            domain: stringField(intent, "domain"),
+            id: stringField(intent, "id"),
+            idempotencyKey: stringField(intent, "idempotencyKey"),
+            payload: jsonField(intent, "payload"),
+            state: outboxIntentStateField(intent),
+        },
+    };
+}
+/**
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"domain.entity-changed">}
+ */
+function domainEntityChangedPayload(event) {
+    const payload = objectField(event, "payload");
+    return {
+        action: entityActionField(payload),
+        entityId: stringField(payload, "entityId"),
+        entityType: stringField(payload, "entityType"),
+    };
+}
+/**
+ * @param {JsonObject} event
+ * @returns {KernelEventPayload<"sync.delta-applied">}
+ */
+function syncDeltaAppliedPayload(event) {
+    const payload = objectField(event, "payload");
+    return {
+        cursor: stringField(payload, "cursor"),
+        domain: stringField(payload, "domain"),
+    };
+}
+/** @param {string} value */
+function isTransportOfflineReason(value) {
+    return value === "no-network" || value === "node-unreachable" || value === "session-required";
+}
+/**
+ * @param {string} value
+ * @returns {value is "iroh-relay" | "lan-direct" | "lan-webtransport" | "wan-direct" | "webrtc-direct"}
+ */
+function isConnectedTransportPath(value) {
+    return (value === "iroh-relay" || value === "lan-direct" || value === "lan-webtransport" ||
+        value === "wan-direct" || value === "webrtc-direct");
+}
+/**
+ * @param {JsonObject} value
+ * @returns {"acknowledged" | "failed" | "pending" | "replaying"}
+ */
+function outboxIntentStateField(value) {
+    const state = stringField(value, "state");
+    if (state === "acknowledged" || state === "failed" || state === "pending" || state === "replaying") {
+        return state;
+    }
+    throw new TypeError("Expected a known outbox intent state");
+}
+/**
+ * @param {JsonObject} value
+ * @returns {"created" | "deleted" | "updated"}
+ */
+function entityActionField(value) {
+    const action = stringField(value, "action");
+    if (action === "created" || action === "deleted" || action === "updated")
+        return action;
+    throw new TypeError("Expected a known entity action");
+}
+/**
+ * @typedef {| { readonly id: string; readonly name: string; readonly payload: JsonValue; readonly type: "command" }
+ *   | { readonly id: string; readonly name: QueryName; readonly params: JsonValue; readonly type: "query" }
+ *   | { readonly id: string; readonly name: QueryName; readonly params: JsonValue; readonly subscriptionId: string; readonly type: "live-query.subscribe" }
+ *   | { readonly id: string; readonly subscriptionId: string; readonly type: "live-query.unsubscribe" }
+ *   | { readonly eventType: ProtocolDomainEvent["type"]; readonly id: string; readonly subscriptionId: string; readonly type: "event.subscribe" }
+ *   | { readonly id: string; readonly subscriptionId: string; readonly type: "event.unsubscribe" }
+ *   | { readonly event: ProtocolDomainEvent; readonly id: string; readonly type: "event.publish" }
+ *   | { readonly appName: string; readonly id: string; readonly type: "stage.prepare" }
+ *   | { readonly appName: string; readonly id: string; readonly manifestSha256: string; readonly type: "stage.open-session" }
+ *   | { readonly id: string; readonly name: QueryName; readonly params: JsonValue; readonly sessionId: string; readonly type: "stage.query" }
+ *   | { readonly id: string; readonly name: QueryName; readonly params: JsonValue; readonly sessionId: string; readonly subscriptionId: string; readonly type: "stage.live-query.subscribe" }
+ *   | { readonly id: string; readonly sessionId: string; readonly subscriptionId: string; readonly type: "stage.live-query.unsubscribe" }
+ *   | { readonly eventType: ProtocolDomainEvent["type"]; readonly id: string; readonly sessionId: string; readonly subscriptionId: string; readonly type: "stage.event.subscribe" }
+ *   | { readonly id: string; readonly sessionId: string; readonly subscriptionId: string; readonly type: "stage.event.unsubscribe" }
+ *   | { readonly event: ProtocolDomainEvent; readonly id: string; readonly sessionId: string; readonly type: "stage.event.publish" }
+ *   | { readonly capability: string; readonly id: string; readonly payload: JsonValue; readonly sessionId: string; readonly type: "stage.capability.invoke" }
+ *   | { readonly id: string; readonly sessionId: string; readonly type: "stage.close-session" }} RpcRequest
+ */
+/**
+ * @typedef {| { readonly id: string; readonly ok: true; readonly value: JsonValue }
+ *   | { readonly error: ClientError; readonly id: string; readonly ok: false }} RpcResponse
+ */
+/**
+ * @typedef {| { readonly diff: QueryDiff<JsonValue>; readonly subscriptionId: string; readonly type: "live-query.changed" }
+ *   | { readonly event: ProtocolDomainEvent; readonly subscriptionId: string; readonly type: "kernel.event" }} RpcEvent
+ */