@carno.js/live 1.8.0

package/dist/resource/ResourceRegistry.d.ts

@@ -0,0 +1,32 @@
+import 'reflect-metadata';
+import type { Dependency } from '../graph/types';
+import type { LiveExecutionContext, LiveInputs, LiveResource, LiveResourceExecutor } from './types';
+export declare class LiveValidationError extends Error {
+    constructor(message: string);
+}
+export declare class ResourceRegistry {
+    private readonly resources;
+    /**
+     * Scan a controller for @Live handlers and validate them.
+     *
+     * Validation runs at registration, which is bootstrap time: the core
+     * compiles everything at startup, so a misdeclared resource fails the boot
+     * instead of failing the first subscription in production.
+     */
+    register(ControllerClass: new (...args: any[]) => any, instance: any, executor: LiveResourceExecutor): void;
+    get(id: string): LiveResource | undefined;
+    ids(): string[];
+    /** Every live route, as the HTTP layer addresses it. */
+    livePaths(): {
+        method: string;
+        path: string;
+        resourceId: string;
+    }[];
+    /** Run the handler and report what it read. */
+    compute(resource: LiveResource, inputs: LiveInputs, context?: LiveExecutionContext): Promise<{
+        data: unknown;
+        deps: Dependency[];
+    }>;
+}
+/** Same join the core router does: collapse the slashes, keep the root. */
+export declare function joinRoutePath(prefix: string, path: string): string;

package/dist/resource/ResourceRegistry.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResourceRegistry = exports.LiveValidationError = void 0;
+exports.joinRoutePath = joinRoutePath;
+require("reflect-metadata");
+const core_1 = require("@carno.js/core");
+const metadata_1 = require("../metadata");
+const dependency_context_1 = require("./dependency-context");
+/**
+ * Verbs that may carry @Live. The real criterion is idempotence, not the verb:
+ * subscribing means re-running the handler whenever the data changes, and
+ * re-running a write duplicates the side effect. GET and POST are the two the
+ * web uses for reading; a PUT that only reads is an abuse of the protocol and
+ * is not worth the API surface.
+ */
+const ALLOWED_METHODS = new Set(['get', 'post']);
+/**
+ * Parameters that would make the handler depend on a caller request rather
+ * than its declared, replayable inputs. Middleware still receives a synthetic
+ * request during every compute and may use it as a guard.
+ */
+const FORBIDDEN_PARAMS = {
+    req: '@Req()',
+    ctx: '@Ctx()',
+    header: '@Header()',
+    locals: '@Locals()'
+};
+class LiveValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LiveValidationError';
+    }
+}
+exports.LiveValidationError = LiveValidationError;
+class ResourceRegistry {
+    constructor() {
+        this.resources = new Map();
+    }
+    /**
+     * Scan a controller for @Live handlers and validate them.
+     *
+     * Validation runs at registration, which is bootstrap time: the core
+     * compiles everything at startup, so a misdeclared resource fails the boot
+     * instead of failing the first subscription in production.
+     */
+    register(ControllerClass, instance, executor) {
+        const routes = Reflect.getMetadata(core_1.ROUTES_META, ControllerClass) || [];
+        const controllerMeta = Reflect.getMetadata(core_1.CONTROLLER_META, ControllerClass) || {};
+        const prefix = controllerMeta.path ?? '';
+        for (const route of routes) {
+            const meta = Reflect.getMetadata(metadata_1.LIVE_META, ControllerClass, route.handlerName);
+            if (!meta) {
+                continue;
+            }
+            const id = `${ControllerClass.name}.${route.handlerName}`;
+            const where = `${ControllerClass.name}.${route.handlerName}()`;
+            if (!ALLOWED_METHODS.has(route.method)) {
+                throw new LiveValidationError(`${where} is decorated with @Live() on @${route.method.toUpperCase()}(). ` +
+                    `Subscribing means re-running the handler whenever the data changes, so it has ` +
+                    `to be idempotent. Only @Get() and @Post() may be live.`);
+            }
+            const params = Reflect.getMetadata(core_1.PARAMS_META, ControllerClass, route.handlerName) || [];
+            for (const type of ['req', 'ctx', 'header', 'locals']) {
+                const param = params.find(candidate => candidate.type === type);
+                const forbidden = param ? FORBIDDEN_PARAMS[param.type] : undefined;
+                if (forbidden) {
+                    throw new LiveValidationError(`${where} uses ${forbidden}, which is not a replayable live input. ` +
+                        `A live resource handler must be a pure function of its declared inputs.`);
+                }
+            }
+            if (route.method === 'get' && params.some(param => param.type === 'body')) {
+                throw new LiveValidationError(`${where} uses @Body() on @Get(). A GET subscription carries no body; ` +
+                    `declare the route as @Post() or read the value from @Query().`);
+            }
+            if (meta.key !== undefined && (typeof meta.key !== 'string' || meta.key === '')) {
+                throw new LiveValidationError(`${where} declares an empty @Live({ key }).`);
+            }
+            if (this.resources.has(id)) {
+                throw new LiveValidationError(`Live resource "${id}" is already registered.`);
+            }
+            let resource;
+            resource = {
+                id,
+                controllerClass: ControllerClass,
+                controllerName: ControllerClass.name,
+                handlerName: route.handlerName,
+                meta,
+                params,
+                invoke: (inputs, context = {}) => executor(instance, resource, inputs, context),
+                httpPath: joinRoutePath(prefix, route.path),
+                httpMethod: route.method.toUpperCase()
+            };
+            this.resources.set(id, resource);
+        }
+    }
+    get(id) {
+        return this.resources.get(id);
+    }
+    ids() {
+        return [...this.resources.keys()];
+    }
+    /** Every live route, as the HTTP layer addresses it. */
+    livePaths() {
+        return [...this.resources.values()].map(resource => ({
+            method: resource.httpMethod,
+            path: resource.httpPath,
+            resourceId: resource.id
+        }));
+    }
+    /** Run the handler and report what it read. */
+    async compute(resource, inputs, context = {}) {
+        const { result, deps } = await dependency_context_1.dependencyContext.run(collector => {
+            for (const key of resource.meta.dependsOn) {
+                collector.add({ key, columns: null });
+            }
+            return resource.invoke(inputs, context);
+        });
+        return { data: result, deps };
+    }
+}
+exports.ResourceRegistry = ResourceRegistry;
+/** Same join the core router does: collapse the slashes, keep the root. */
+function joinRoutePath(prefix, path) {
+    const joined = `${prefix}${path}`.replace(/\/{2,}/g, '/');
+    return joined.length > 1 ? joined.replace(/\/$/, '') : (joined || '/');
+}

package/dist/resource/dependency-context.d.ts

@@ -0,0 +1,25 @@
+import type { Dependency } from '../graph/types';
+export declare class DependencyCollector {
+    private readonly deps;
+    add(dep: Dependency): void;
+    addAll(deps: Dependency[]): void;
+    drain(): Dependency[];
+}
+/**
+ * Collects the reads performed during one resource compute.
+ *
+ * Same AsyncLocalStorage shape as identityMapContext, tenantContext and
+ * transactionContext in @carno.js/orm — concurrent computes each get their own
+ * collector without threading a parameter through user code.
+ */
+declare class DependencyContext {
+    private readonly storage;
+    run<T>(fn: (collector: DependencyCollector) => Promise<T> | T): Promise<{
+        result: T;
+        deps: Dependency[];
+    }>;
+    current(): DependencyCollector | undefined;
+    isActive(): boolean;
+}
+export declare const dependencyContext: DependencyContext;
+export {};

package/dist/resource/dependency-context.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dependencyContext = exports.DependencyCollector = void 0;
+const async_hooks_1 = require("async_hooks");
+class DependencyCollector {
+    constructor() {
+        this.deps = [];
+    }
+    add(dep) {
+        this.deps.push(dep);
+    }
+    addAll(deps) {
+        for (const dep of deps) {
+            this.deps.push(dep);
+        }
+    }
+    drain() {
+        return this.deps.slice();
+    }
+}
+exports.DependencyCollector = DependencyCollector;
+/**
+ * Collects the reads performed during one resource compute.
+ *
+ * Same AsyncLocalStorage shape as identityMapContext, tenantContext and
+ * transactionContext in @carno.js/orm — concurrent computes each get their own
+ * collector without threading a parameter through user code.
+ */
+class DependencyContext {
+    constructor() {
+        this.storage = new async_hooks_1.AsyncLocalStorage();
+    }
+    async run(fn) {
+        const collector = new DependencyCollector();
+        const result = await this.storage.run(collector, async () => fn(collector));
+        return { result, deps: collector.drain() };
+    }
+    current() {
+        return this.storage.getStore();
+    }
+    isActive() {
+        return this.storage.getStore() !== undefined;
+    }
+}
+exports.dependencyContext = new DependencyContext();

package/dist/resource/instance-id.d.ts

@@ -0,0 +1,17 @@
+import type { LiveShared } from '../metadata';
+import type { LiveInputs, LiveScope } from '../shared/inputs';
+export declare class MissingScopeError extends Error {
+    readonly dimension: 'tenant' | 'principal';
+    constructor(dimension: 'tenant' | 'principal');
+}
+export declare class InputTooLargeError extends Error {
+    readonly size: number;
+    readonly limit: number;
+    constructor(size: number, limit: number);
+}
+/** The scope half of the instance identity, embedded literally and encoded. */
+export declare function scopeKeyOf(shared: LiveShared, scope: LiveScope): string;
+/** Canonical form of inputs, guarded by the size ceiling. */
+export declare function canonicalInputs(inputs: LiveInputs, maxInputBytes: number): string;
+/** Same resource, scope and inputs means one compute, one diff and N sends. */
+export declare function instanceIdOf(resourceId: string, scopeKey: string, canonicalInputsValue: string): string;

package/dist/resource/instance-id.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InputTooLargeError = exports.MissingScopeError = void 0;
+exports.scopeKeyOf = scopeKeyOf;
+exports.canonicalInputs = canonicalInputs;
+exports.instanceIdOf = instanceIdOf;
+const canonical_1 = require("../shared/canonical");
+const hash_1 = require("../shared/hash");
+class MissingScopeError extends Error {
+    constructor(dimension) {
+        super(`Live resource requires a ${dimension} in scope but none was resolved. ` +
+            'Register a LiveScopeResolver, or declare the resource as @Live({ shared: \'public\' }).');
+        this.dimension = dimension;
+        this.name = 'MissingScopeError';
+    }
+}
+exports.MissingScopeError = MissingScopeError;
+class InputTooLargeError extends Error {
+    constructor(size, limit) {
+        super(`Live subscription inputs are ${size} bytes, over the ${limit} byte limit.`);
+        this.size = size;
+        this.limit = limit;
+        this.name = 'InputTooLargeError';
+    }
+}
+exports.InputTooLargeError = InputTooLargeError;
+/** The scope half of the instance identity, embedded literally and encoded. */
+function scopeKeyOf(shared, scope) {
+    if (shared === 'public') {
+        return 'pub';
+    }
+    if (shared === 'tenant') {
+        if (scope.tenant === undefined || scope.tenant === null || scope.tenant === '') {
+            throw new MissingScopeError('tenant');
+        }
+        return `t:${encodeURIComponent(String(scope.tenant))}`;
+    }
+    if (scope.principal === undefined || scope.principal === null || scope.principal === '') {
+        throw new MissingScopeError('principal');
+    }
+    return `p:${encodeURIComponent(String(scope.principal))}`;
+}
+/** Canonical form of inputs, guarded by the size ceiling. */
+function canonicalInputs(inputs, maxInputBytes) {
+    const encoded = (0, canonical_1.canonical)({
+        params: inputs.params ?? {},
+        query: inputs.query ?? {},
+        // `canonical` renders undefined and null identically, so a GET (no
+        // body) and a POST with an empty body land on the same string.
+        body: inputs.body ?? null
+    });
+    const size = Buffer.byteLength(encoded, 'utf8');
+    if (size > maxInputBytes) {
+        throw new InputTooLargeError(size, maxInputBytes);
+    }
+    return encoded;
+}
+/** Same resource, scope and inputs means one compute, one diff and N sends. */
+function instanceIdOf(resourceId, scopeKey, canonicalInputsValue) {
+    return `${resourceId}|${scopeKey}|${(0, hash_1.fnv1a64)(canonicalInputsValue)}`;
+}

package/dist/resource/prefetch.d.ts

@@ -0,0 +1,20 @@
+import type { LiveExecutionContext, LiveInputs } from './types';
+import type { ResourceRegistry } from './ResourceRegistry';
+/** What a server-rendered page hands the client so the first paint is full. */
+export interface LivePayload {
+    resourceId: string;
+    inputs: LiveInputs;
+    data: unknown;
+    hash: string;
+}
+/**
+ * Compute a live resource once, for the first paint.
+ *
+ * Deliberately not a subscription: nothing is registered in the dependency
+ * graph and no instance is created. Every rendered page would otherwise leave
+ * behind an instance being recomputed forever, including the ones nobody ever
+ * subscribes to -- the worst possible cost for the most common case. The
+ * instance is born when a client subscribes, and the hash returned here is
+ * what makes that subscription carry no data.
+ */
+export declare function prefetchLive(resources: ResourceRegistry, resourceId: string, inputs?: Partial<LiveInputs>, context?: LiveExecutionContext): Promise<LivePayload>;

package/dist/resource/prefetch.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prefetchLive = prefetchLive;
+const canonical_1 = require("../shared/canonical");
+const descriptor_1 = require("../shared/descriptor");
+const hash_1 = require("../shared/hash");
+/**
+ * Compute a live resource once, for the first paint.
+ *
+ * Deliberately not a subscription: nothing is registered in the dependency
+ * graph and no instance is created. Every rendered page would otherwise leave
+ * behind an instance being recomputed forever, including the ones nobody ever
+ * subscribes to -- the worst possible cost for the most common case. The
+ * instance is born when a client subscribes, and the hash returned here is
+ * what makes that subscription carry no data.
+ */
+async function prefetchLive(resources, resourceId, inputs = {}, context = {}) {
+    const resource = resources.get(resourceId);
+    if (!resource) {
+        throw new Error(`[carno:live] cannot prefetch "${resourceId}": no live resource by that name. ` +
+            `Is its controller listed in LivePlugin.create({ controllers })?`);
+    }
+    const normalized = (0, descriptor_1.normalizeLiveInputs)(inputs);
+    const { data } = await resources.compute(resource, normalized, context);
+    return {
+        resourceId,
+        inputs: normalized,
+        data,
+        hash: (0, hash_1.fnv1a64)((0, canonical_1.canonical)(data))
+    };
+}

package/dist/resource/route-executor.d.ts

@@ -0,0 +1,13 @@
+import { type Carno } from '@carno.js/core';
+import type { LiveResourceExecutor } from './types';
+export declare class LiveRouteExecutionError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+export declare function isLiveAuthorizationFailure(error: unknown): boolean;
+/**
+ * Adapt the core's compiled HTTP route to a Live resource compute.  The
+ * adapter is created once at startup; only the synthetic request and response
+ * decoding happen per compute.
+ */
+export declare function createLiveRouteExecutor(carno: Carno): LiveResourceExecutor;

package/dist/resource/route-executor.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveRouteExecutionError = void 0;
+exports.isLiveAuthorizationFailure = isLiveAuthorizationFailure;
+exports.createLiveRouteExecutor = createLiveRouteExecutor;
+const core_1 = require("@carno.js/core");
+class LiveRouteExecutionError extends Error {
+    constructor(statusCode, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'LiveRouteExecutionError';
+    }
+}
+exports.LiveRouteExecutionError = LiveRouteExecutionError;
+function isLiveAuthorizationFailure(error) {
+    return error instanceof LiveRouteExecutionError &&
+        (error.statusCode === 401 || error.statusCode === 403);
+}
+/**
+ * Adapt the core's compiled HTTP route to a Live resource compute.  The
+ * adapter is created once at startup; only the synthetic request and response
+ * decoding happen per compute.
+ */
+function createLiveRouteExecutor(carno) {
+    return async (_controllerInstance, resource, inputs, context) => {
+        const request = createRequest(resource, inputs, context);
+        let response;
+        try {
+            response = await carno.executeCompiledRoute(resource.controllerClass, resource.handlerName, request, inputs.params);
+        }
+        catch (error) {
+            if (error instanceof core_1.HttpException || error instanceof core_1.ValidationException) {
+                response = error.toResponse();
+            }
+            else {
+                throw error;
+            }
+        }
+        if (response.status < 200 || response.status >= 300) {
+            const detail = await response.text().catch(() => '');
+            throw new LiveRouteExecutionError(response.status, detail || `Live route returned HTTP ${response.status}.`);
+        }
+        return decodeResponse(response);
+    };
+}
+function createRequest(resource, inputs, context) {
+    const path = interpolatePath(resource.httpPath, inputs.params, resource.id);
+    const url = new URL(`http://carno.live${path}`);
+    for (const [key, value] of Object.entries(inputs.query)) {
+        for (const item of Array.isArray(value) ? value : [value]) {
+            url.searchParams.append(key, item);
+        }
+    }
+    const headers = new Headers(context.scope?.headers);
+    if (context.headers) {
+        new Headers(context.headers).forEach((value, key) => headers.set(key, value));
+    }
+    const hasBody = resource.httpMethod === 'POST' && inputs.body !== undefined;
+    if (hasBody && !headers.has('content-type')) {
+        headers.set('content-type', 'application/json');
+    }
+    return new Request(url, {
+        method: resource.httpMethod,
+        headers,
+        body: hasBody ? JSON.stringify(inputs.body) : undefined
+    });
+}
+function interpolatePath(path, params, resourceId) {
+    return path.replace(/:([A-Za-z0-9_]+)/g, (_segment, key) => {
+        const value = params[key];
+        if (value === undefined) {
+            throw new LiveRouteExecutionError(400, `Live resource "${resourceId}" is missing route parameter "${key}".`);
+        }
+        return encodeURIComponent(value);
+    });
+}
+async function decodeResponse(response) {
+    if (response.status === 204) {
+        return undefined;
+    }
+    const contentType = response.headers.get('content-type')?.toLowerCase() ?? '';
+    if (contentType.includes('json')) {
+        return response.json();
+    }
+    return response.text();
+}

package/dist/resource/types.d.ts

@@ -0,0 +1,26 @@
+import type { ParamMetadata } from '@carno.js/core';
+import type { LiveMeta } from '../metadata';
+export type { LiveInputs, LiveScope } from '../shared/inputs';
+import type { LiveInputs, LiveScope } from '../shared/inputs';
+export interface LiveExecutionContext {
+    /** Scope resolved for a subscription, including optional middleware headers. */
+    scope?: LiveScope;
+    /** Explicit headers, useful when prefetching from an authenticated SSR request. */
+    headers?: HeadersInit;
+}
+export interface LiveResourceExecutor {
+    (controllerInstance: any, resource: LiveResource, inputs: LiveInputs, context: LiveExecutionContext): Promise<unknown>;
+}
+export interface LiveResource {
+    /** `${controllerName}.${handlerName}` */
+    id: string;
+    controllerClass: new (...args: any[]) => any;
+    controllerName: string;
+    handlerName: string;
+    meta: LiveMeta;
+    params: ParamMetadata[];
+    invoke(inputs: LiveInputs, context?: LiveExecutionContext): Promise<unknown>;
+    /** Full HTTP path, controller prefix included. Used by the ETag layer. */
+    httpPath: string;
+    httpMethod: string;
+}

package/dist/resource/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime.d.ts

@@ -0,0 +1,41 @@
+import type { LiveEngine } from './LiveEngine';
+import type { SocketTransport } from './transport/SocketTransport';
+import type { LiveScopeResolver } from './transport/scope-resolver';
+import type { LiveScope } from './shared/inputs';
+import type { ResourceRegistry } from './resource/ResourceRegistry';
+export interface LiveRuntime {
+    engine: LiveEngine;
+    transport: SocketTransport;
+    resolver: LiveScopeResolver;
+    scopes: Map<string, LiveScope>;
+    /** Connections that have completed their single allowed hello. */
+    handshakes: Set<string>;
+    /** Needed by prefetch(), which computes without subscribing. */
+    resources: ResourceRegistry;
+    /**
+     * Everything the plugin opened and nothing else knows about: the dedicated
+     * LISTEN connections of the Postgres emitter and of the distributed bus,
+     * plus the engine's timers.
+     */
+    dispose?: (() => Promise<void> | void)[];
+}
+/**
+ * Process-wide holder, same shape as `Orm.getInstance()`.
+ *
+ * The gateway is instantiated by the core container, which has no factory
+ * providers, so constructor-injecting a hand-built engine would need a
+ * registration dance that exists only to satisfy the container.
+ */
+export declare function setLiveRuntime(runtime: LiveRuntime): void;
+export declare function getLiveRuntime(): LiveRuntime;
+/**
+ * Close whatever the plugin opened, then forget the runtime.
+ *
+ * Dropping the reference alone is not enough: a LISTEN connection is a socket
+ * held open by nothing the container can see, so a process that builds and
+ * tears down several Carno instances — a test suite, most obviously — runs the
+ * database out of client slots.
+ */
+export declare function closeLiveRuntime(): Promise<void>;
+/** Synchronous form. Prefer `closeLiveRuntime()` when you can await. */
+export declare function resetLiveRuntime(): void;

package/dist/runtime.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setLiveRuntime = setLiveRuntime;
+exports.getLiveRuntime = getLiveRuntime;
+exports.closeLiveRuntime = closeLiveRuntime;
+exports.resetLiveRuntime = resetLiveRuntime;
+let current = null;
+/**
+ * Process-wide holder, same shape as `Orm.getInstance()`.
+ *
+ * The gateway is instantiated by the core container, which has no factory
+ * providers, so constructor-injecting a hand-built engine would need a
+ * registration dance that exists only to satisfy the container.
+ */
+function setLiveRuntime(runtime) {
+    current = runtime;
+}
+function getLiveRuntime() {
+    if (!current) {
+        throw new Error('[carno:live] LivePlugin.create() has not run yet.');
+    }
+    return current;
+}
+/**
+ * Close whatever the plugin opened, then forget the runtime.
+ *
+ * Dropping the reference alone is not enough: a LISTEN connection is a socket
+ * held open by nothing the container can see, so a process that builds and
+ * tears down several Carno instances — a test suite, most obviously — runs the
+ * database out of client slots.
+ */
+async function closeLiveRuntime() {
+    const runtime = current;
+    current = null;
+    for (const close of runtime?.dispose ?? []) {
+        try {
+            await close();
+        }
+        catch (error) {
+            console.error('[carno:live] failed to close a live connection', error);
+        }
+    }
+}
+/** Synchronous form. Prefer `closeLiveRuntime()` when you can await. */
+function resetLiveRuntime() {
+    void closeLiveRuntime();
+}

package/dist/shared/canonical.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Deterministic JSON canonicalization, shared verbatim by client and server.
+ *
+ * Both sides MUST produce byte-identical output for the same logical value:
+ * the instance id and the content hash are derived from it, so a divergence
+ * silently breaks subscription dedupe and the hydration handshake instead of
+ * failing loudly.
+ */
+export declare class NonSerializableInputError extends Error {
+    readonly path: string;
+    readonly received: string;
+    constructor(path: string, received: string);
+}
+export declare function canonical(value: unknown, path?: string): string;

package/dist/shared/canonical.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NonSerializableInputError = void 0;
+exports.canonical = canonical;
+/**
+ * Deterministic JSON canonicalization, shared verbatim by client and server.
+ *
+ * Both sides MUST produce byte-identical output for the same logical value:
+ * the instance id and the content hash are derived from it, so a divergence
+ * silently breaks subscription dedupe and the hydration handshake instead of
+ * failing loudly.
+ */
+class NonSerializableInputError extends Error {
+    constructor(path, received) {
+        super(`Live input at "${path}" is not serializable (received ${received}).`);
+        this.path = path;
+        this.received = received;
+        this.name = 'NonSerializableInputError';
+    }
+}
+exports.NonSerializableInputError = NonSerializableInputError;
+function canonical(value, path = '$') {
+    if (value === null || value === undefined) {
+        return 'null';
+    }
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'number':
+            if (!Number.isFinite(value)) {
+                throw new NonSerializableInputError(path, String(value));
+            }
+            // -0 and 0 are the same input as far as a query is concerned.
+            return Object.is(value, -0) ? '0' : String(value);
+        case 'string':
+            return JSON.stringify(value);
+        case 'bigint':
+        case 'function':
+        case 'symbol':
+            throw new NonSerializableInputError(path, typeof value);
+    }
+    if (Array.isArray(value)) {
+        const items = value.map((item, index) => canonical(item, `${path}[${index}]`));
+        return `[${items.join(',')}]`;
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+        // Date, Map, Set, class instances: no agreed wire form, so refuse
+        // rather than guess one the client would canonicalize differently.
+        const name = value.constructor?.name ?? 'object';
+        throw new NonSerializableInputError(path, name);
+    }
+    const entries = Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    const body = entries
+        .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item, `${path}.${key}`)}`)
+        .join(',');
+    return `{${body}}`;
+}