@carno.js/live 1.8.0

package/dist/shared/descriptor.d.ts

@@ -0,0 +1,44 @@
+import type { LiveInputs } from './inputs';
+/**
+ * Structural twin of the descriptor @carno.js/client emits.
+ *
+ * The generated file imports nothing, on purpose, so the two definitions meet
+ * through TypeScript's structural typing. Keep the field names identical.
+ */
+export interface LiveDescriptor<R = unknown> {
+    readonly method: string;
+    readonly path: string;
+    readonly resourceId?: string;
+    readonly live?: {
+        readonly shared: 'private' | 'tenant' | 'public';
+        readonly key?: string;
+    };
+    readonly __route?: R;
+}
+/** What the route answers, as the client sees it. */
+export type LiveDataOf<R> = R extends {
+    response: infer S;
+} ? Exclude<S, undefined | void> : unknown;
+/** What the route takes, as a subscription sends it. */
+export type LiveInputsOf<R> = (R extends {
+    params: infer P;
+} ? {
+    params: P;
+} : {
+    params?: Record<string, string>;
+}) & (R extends {
+    query: infer Q;
+} ? {
+    query: Q;
+} : {
+    query?: Record<string, string | string[]>;
+}) & (R extends {
+    body: infer B;
+} ? {
+    body: B;
+} : {
+    body?: undefined;
+});
+export declare function resourceIdOf(descriptor: LiveDescriptor<any>): string;
+/** Fill the three input slots, whichever of them the caller bothered with. */
+export declare function normalizeLiveInputs(inputs?: Partial<LiveInputs>): LiveInputs;

package/dist/shared/descriptor.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resourceIdOf = resourceIdOf;
+exports.normalizeLiveInputs = normalizeLiveInputs;
+function resourceIdOf(descriptor) {
+    if (!descriptor.resourceId || !descriptor.live) {
+        throw new Error(`${descriptor.method.toUpperCase()} ${descriptor.path} is not a live resource. ` +
+            `Add @Live() to the handler and re-run the client codegen.`);
+    }
+    return descriptor.resourceId;
+}
+/** Fill the three input slots, whichever of them the caller bothered with. */
+function normalizeLiveInputs(inputs = {}) {
+    return {
+        params: inputs.params ?? {},
+        query: inputs.query ?? {},
+        body: inputs.body
+    };
+}

package/dist/shared/hash.d.ts

@@ -0,0 +1,12 @@
+/**
+ * FNV-1a widened to 64 output bits by running two lanes with different offset
+ * bases, the second one position-sensitive.
+ *
+ * `packages/orm/src/cache/cache-key-generator.ts` uses the 32-bit variant,
+ * which is right for a cache — a collision there costs one stale entry. Here a
+ * content-hash collision means "data changed but no patch was sent", and 32
+ * bits reach 50% collision odds around 65k keys while `maxInstancesPerNode`
+ * alone is 50000. This lives in one module so it can be swapped for a stronger
+ * hash without touching anything else.
+ */
+export declare function fnv1a64(input: string): string;

package/dist/shared/hash.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fnv1a64 = fnv1a64;
+const FNV_OFFSET_BASIS_A = 2166136261;
+const FNV_OFFSET_BASIS_B = 0x9e3779b9;
+const FNV_PRIME = 16777619;
+/**
+ * FNV-1a widened to 64 output bits by running two lanes with different offset
+ * bases, the second one position-sensitive.
+ *
+ * `packages/orm/src/cache/cache-key-generator.ts` uses the 32-bit variant,
+ * which is right for a cache — a collision there costs one stale entry. Here a
+ * content-hash collision means "data changed but no patch was sent", and 32
+ * bits reach 50% collision odds around 65k keys while `maxInstancesPerNode`
+ * alone is 50000. This lives in one module so it can be swapped for a stronger
+ * hash without touching anything else.
+ */
+function fnv1a64(input) {
+    let laneA = FNV_OFFSET_BASIS_A;
+    let laneB = FNV_OFFSET_BASIS_B;
+    for (let i = 0; i < input.length; i++) {
+        const code = input.charCodeAt(i);
+        laneA ^= code;
+        laneA = Math.imul(laneA, FNV_PRIME);
+        laneB ^= code + i;
+        laneB = Math.imul(laneB, FNV_PRIME);
+    }
+    return (laneA >>> 0).toString(16).padStart(8, '0') + (laneB >>> 0).toString(16).padStart(8, '0');
+}

package/dist/shared/inputs.d.ts

@@ -0,0 +1,19 @@
+/** Everything a resource compute is allowed to read from the caller. */
+export interface LiveInputs {
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    /**
+     * Body of a @Post() live resource. Absent on @Get().
+     *
+     * It is part of the instance identity, not extra baggage: two clients
+     * posting different filters must not share one computed instance.
+     */
+    body?: unknown;
+}
+/** Ambient dimensions resolved on the server; never sent by the client. */
+export interface LiveScope {
+    principal?: string | number;
+    tenant?: string | number;
+    /** Optional request headers for replaying route middleware during compute. */
+    headers?: HeadersInit;
+}

package/dist/shared/inputs.js

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

package/dist/shared/protocol.d.ts

@@ -0,0 +1,83 @@
+import type { PatchOp } from '../patch/types';
+import type { LiveInputs } from '../resource/types';
+export declare const LIVE_PROTOCOL_VERSION = 1;
+/** Headers used by the HTTP polling rung to carry the live auth contract. */
+export declare const LIVE_POLL_HEADER = "X-Carno-Live-Poll";
+export declare const LIVE_CONNECTION_HEADER = "X-Carno-Live-Connection";
+export declare const LIVE_RESOURCE_HEADER = "X-Carno-Live-Resource";
+export declare const LIVE_TOKEN_HEADER = "X-Carno-Live-Token";
+/** Sent once per connection, before any subscription. */
+export interface ClientHello {
+    t: 'hello';
+    v: number;
+    /** Opaque credential; the server's LiveScopeResolver interprets it. */
+    token?: string;
+}
+export interface ClientSub {
+    t: 'sub';
+    /** Client-chosen subscription id. The instance id never leaves the server. */
+    sid: string;
+    resource: string;
+    inputs: LiveInputs;
+    /** Content hash of what the client already has on screen, if anything. */
+    hash?: string;
+}
+export interface ClientUnsub {
+    t: 'unsub';
+    sid: string;
+}
+export interface ClientResync {
+    t: 'resync';
+    sid: string;
+    hash?: string;
+}
+export type ClientMessage = ClientHello | ClientSub | ClientUnsub | ClientResync;
+/** Full state. */
+export interface ServerSnapshot {
+    t: 'snapshot';
+    sid: string;
+    rev: number;
+    hash: string;
+    data: unknown;
+    /**
+     * The resource's `@Live({ key })`, if it declared one. The client needs it
+     * to apply keyed ops, and this is the only message that establishes state,
+     * so it is the only place it has to travel.
+     */
+    key?: string;
+}
+/** The client's hash matched what the server computed: nothing on the wire. */
+export interface ServerCurrent {
+    t: 'current';
+    sid: string;
+    rev: number;
+    hash: string;
+    /** Same reason as on `snapshot`: this also establishes state, on hydration. */
+    key?: string;
+}
+export interface ServerPatch {
+    t: 'patch';
+    sid: string;
+    from: number;
+    to: number;
+    hash: string;
+    ops: PatchOp[];
+}
+/**
+ * The server cannot vouch for this instance being current (a recompute is
+ * failing). The client keeps showing the last data and flags it, so the UI can
+ * say so.
+ */
+export interface ServerStale {
+    t: 'stale';
+    sid: string;
+    reason: string;
+}
+/** The subscription is invalid or not allowed; the client ends the instance. */
+export interface ServerError {
+    t: 'error';
+    sid: string;
+    code: string;
+    message: string;
+}
+export type ServerMessage = ServerSnapshot | ServerCurrent | ServerPatch | ServerStale | ServerError;

package/dist/shared/protocol.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIVE_TOKEN_HEADER = exports.LIVE_RESOURCE_HEADER = exports.LIVE_CONNECTION_HEADER = exports.LIVE_POLL_HEADER = exports.LIVE_PROTOCOL_VERSION = void 0;
+exports.LIVE_PROTOCOL_VERSION = 1;
+/** Headers used by the HTTP polling rung to carry the live auth contract. */
+exports.LIVE_POLL_HEADER = 'X-Carno-Live-Poll';
+exports.LIVE_CONNECTION_HEADER = 'X-Carno-Live-Connection';
+exports.LIVE_RESOURCE_HEADER = 'X-Carno-Live-Resource';
+exports.LIVE_TOKEN_HEADER = 'X-Carno-Live-Token';

package/dist/transport/FanTransport.d.ts

@@ -0,0 +1,18 @@
+import type { LiveTransport } from '../LiveEngine';
+import type { ServerMessage } from '../shared/protocol';
+export interface OwnedTransport extends LiveTransport {
+    /** Whether this transport is the one holding that connection. */
+    owns(connectionId: string): boolean;
+}
+/**
+ * One engine, several pipes.
+ *
+ * The engine addresses connections by an opaque id and never asks how they are
+ * reached, which is exactly what makes SSE a transport rather than a second
+ * engine. This routes each send to whichever transport claims the id.
+ */
+export declare class FanTransport implements LiveTransport {
+    private readonly children;
+    add(child: OwnedTransport): void;
+    send(connectionId: string, message: ServerMessage): number;
+}

package/dist/transport/FanTransport.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FanTransport = void 0;
+/**
+ * One engine, several pipes.
+ *
+ * The engine addresses connections by an opaque id and never asks how they are
+ * reached, which is exactly what makes SSE a transport rather than a second
+ * engine. This routes each send to whichever transport claims the id.
+ */
+class FanTransport {
+    constructor() {
+        this.children = [];
+    }
+    add(child) {
+        this.children.push(child);
+    }
+    send(connectionId, message) {
+        for (const child of this.children) {
+            if (child.owns(connectionId)) {
+                return child.send(connectionId, message);
+            }
+        }
+        // Nobody holds it any more. Zero is "dropped", which the engine already
+        // handles; throwing here would take a whole fan-out down with it.
+        return 0;
+    }
+}
+exports.FanTransport = FanTransport;

package/dist/transport/LiveGateway.d.ts

@@ -0,0 +1,16 @@
+import { CarnoSocket } from '@carno.js/websocket';
+export declare const LIVE_GATEWAY_PATH = "/live";
+export declare class LiveGateway {
+    onOpen(socket: CarnoSocket): void;
+    onMessage(socket: CarnoSocket, raw: string | ArrayBuffer | Uint8Array): void;
+    onClose(socket: CarnoSocket): void;
+}
+/**
+ * Tear down a connection from any pipe.
+ *
+ * WebSocket and SSE must leave the engine, the inbound queue and the scope
+ * map in the same state: an in-flight `hello` cannot subscribe after the
+ * client has gone, and a cancelled stream cannot leak a principal.
+ */
+export declare function dropLiveConnection(connectionId: string): void;
+export declare function handleMessage(connectionId: string, raw: string): Promise<void>;

package/dist/transport/LiveGateway.js

@@ -0,0 +1,126 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveGateway = exports.LIVE_GATEWAY_PATH = void 0;
+exports.dropLiveConnection = dropLiveConnection;
+exports.handleMessage = handleMessage;
+const websocket_1 = require("@carno.js/websocket");
+const runtime_1 = require("../runtime");
+exports.LIVE_GATEWAY_PATH = '/live';
+/** Per-connection tail so `hello` finishes before a back-to-back `sub`. */
+const inbound = new Map();
+let LiveGateway = class LiveGateway {
+    onOpen(socket) {
+        const runtime = (0, runtime_1.getLiveRuntime)();
+        runtime.transport.add(socket);
+        runtime.handshakes.delete(socket.id);
+        // Until a `hello` arrives, the connection is its own principal: safe,
+        // shares nothing.
+        runtime.scopes.set(socket.id, { principal: socket.id });
+    }
+    onMessage(socket, raw) {
+        if (typeof raw !== 'string') {
+            return;
+        }
+        void handleMessage(socket.id, raw).catch(() => { });
+    }
+    onClose(socket) {
+        dropLiveConnection(socket.id);
+        (0, runtime_1.getLiveRuntime)().transport.remove(socket.id);
+    }
+};
+exports.LiveGateway = LiveGateway;
+__decorate([
+    (0, websocket_1.OnOpen)(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [websocket_1.CarnoSocket]),
+    __metadata("design:returntype", void 0)
+], LiveGateway.prototype, "onOpen", null);
+__decorate([
+    (0, websocket_1.OnMessage)(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [websocket_1.CarnoSocket, Object]),
+    __metadata("design:returntype", void 0)
+], LiveGateway.prototype, "onMessage", null);
+__decorate([
+    (0, websocket_1.OnClose)(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [websocket_1.CarnoSocket]),
+    __metadata("design:returntype", void 0)
+], LiveGateway.prototype, "onClose", null);
+exports.LiveGateway = LiveGateway = __decorate([
+    (0, websocket_1.Gateway)(exports.LIVE_GATEWAY_PATH)
+], LiveGateway);
+/**
+ * Tear down a connection from any pipe.
+ *
+ * WebSocket and SSE must leave the engine, the inbound queue and the scope
+ * map in the same state: an in-flight `hello` cannot subscribe after the
+ * client has gone, and a cancelled stream cannot leak a principal.
+ */
+function dropLiveConnection(connectionId) {
+    inbound.delete(connectionId);
+    const runtime = (0, runtime_1.getLiveRuntime)();
+    runtime.engine.dropConnection(connectionId);
+    runtime.scopes.delete(connectionId);
+    runtime.handshakes.delete(connectionId);
+}
+function handleMessage(connectionId, raw) {
+    const previous = inbound.get(connectionId) ?? Promise.resolve();
+    const next = previous.then(() => dispatch(connectionId, raw), () => dispatch(connectionId, raw));
+    inbound.set(connectionId, next);
+    return next;
+}
+async function dispatch(connectionId, raw) {
+    if (!inbound.has(connectionId)) {
+        return;
+    }
+    const runtime = (0, runtime_1.getLiveRuntime)();
+    let message;
+    try {
+        message = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    if (!message || typeof message.t !== 'string') {
+        return;
+    }
+    switch (message.t) {
+        case 'hello': {
+            if (runtime.handshakes.has(connectionId)) {
+                return;
+            }
+            const scope = await runtime.resolver.resolve({ connectionId, token: message.token });
+            if (!inbound.has(connectionId)) {
+                return;
+            }
+            runtime.scopes.set(connectionId, scope);
+            runtime.handshakes.add(connectionId);
+            return;
+        }
+        case 'sub': {
+            const scope = runtime.scopes.get(connectionId) ?? { principal: connectionId };
+            await runtime.engine.subscribe(connectionId, message.sid, message.resource, {
+                params: message.inputs?.params ?? {},
+                query: message.inputs?.query ?? {},
+                body: message.inputs?.body
+            }, scope, message.hash);
+            return;
+        }
+        case 'unsub':
+            runtime.engine.unsubscribe(connectionId, message.sid);
+            return;
+        case 'resync':
+            await runtime.engine.resync(connectionId, message.sid, message.hash);
+            return;
+    }
+}

package/dist/transport/SocketTransport.d.ts

@@ -0,0 +1,18 @@
+import type { CarnoSocket } from '@carno.js/websocket';
+import type { ServerMessage } from '../shared/protocol';
+import type { OwnedTransport } from './FanTransport';
+/**
+ * Sends protocol messages over the raw socket.
+ *
+ * We use `socket.send()` rather than `socket.emit()` because emit wraps the
+ * payload in `{ event, data }` for the gateway's own event protocol, and this
+ * is a different protocol.
+ */
+export declare class SocketTransport implements OwnedTransport {
+    private readonly sockets;
+    add(socket: CarnoSocket): void;
+    remove(connectionId: string): void;
+    owns(connectionId: string): boolean;
+    /** <= 0 means back-pressured or dropped; the engine counts those. */
+    send(connectionId: string, message: ServerMessage): number;
+}

package/dist/transport/SocketTransport.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketTransport = void 0;
+/**
+ * Sends protocol messages over the raw socket.
+ *
+ * We use `socket.send()` rather than `socket.emit()` because emit wraps the
+ * payload in `{ event, data }` for the gateway's own event protocol, and this
+ * is a different protocol.
+ */
+class SocketTransport {
+    constructor() {
+        this.sockets = new Map();
+    }
+    add(socket) {
+        this.sockets.set(socket.id, socket);
+    }
+    remove(connectionId) {
+        this.sockets.delete(connectionId);
+    }
+    owns(connectionId) {
+        return this.sockets.has(connectionId);
+    }
+    /** <= 0 means back-pressured or dropped; the engine counts those. */
+    send(connectionId, message) {
+        const socket = this.sockets.get(connectionId);
+        if (!socket) {
+            return 0;
+        }
+        try {
+            return socket.send(JSON.stringify(message));
+        }
+        catch {
+            // The socket closed between fan-out and send. Treat as dropped;
+            // the close handler will clean it up.
+            return 0;
+        }
+    }
+}
+exports.SocketTransport = SocketTransport;

package/dist/transport/SseTransport.d.ts

@@ -0,0 +1,30 @@
+import type { ServerMessage } from '../shared/protocol';
+import type { OwnedTransport } from './FanTransport';
+export interface SseTransportOptions {
+    /** 0 disables the heartbeat. Only tests want that. */
+    heartbeatMs: number;
+    maxConnections: number;
+    /** Called when the client goes away, so the engine can drop the connection. */
+    onDisconnect?: (connectionId: string) => void;
+}
+/**
+ * The downstream half of the SSE transport.
+ *
+ * Upstream is `POST /live/control`, which speaks the same protocol into the
+ * same handler the WebSocket gateway uses -- see `sse-routes.ts`. This half
+ * only writes frames, so the engine cannot tell it apart from a socket.
+ */
+export declare class SseTransport implements OwnedTransport {
+    private readonly options;
+    private readonly streams;
+    private heartbeat;
+    constructor(options: SseTransportOptions);
+    open(connectionId: string): ReadableStream<Uint8Array>;
+    owns(connectionId: string): boolean;
+    send(connectionId: string, message: ServerMessage): number;
+    close(connectionId: string): void;
+    count(): number;
+    stop(): void;
+    private ensureHeartbeat;
+    private write;
+}

package/dist/transport/SseTransport.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SseTransport = void 0;
+const ENCODER = new TextEncoder();
+const NativeReadableStream = ReadableStream;
+/**
+ * The downstream half of the SSE transport.
+ *
+ * Upstream is `POST /live/control`, which speaks the same protocol into the
+ * same handler the WebSocket gateway uses -- see `sse-routes.ts`. This half
+ * only writes frames, so the engine cannot tell it apart from a socket.
+ */
+class SseTransport {
+    constructor(options) {
+        this.options = options;
+        this.streams = new Map();
+        this.heartbeat = null;
+    }
+    open(connectionId) {
+        if (this.streams.size >= this.options.maxConnections) {
+            throw new Error(`[carno:live] the SSE transport is at capacity (${this.options.maxConnections}).`);
+        }
+        return new NativeReadableStream({
+            start: controller => {
+                this.streams.set(connectionId, controller);
+                // The client cannot learn its own connection id any other way,
+                // and it needs it to address the control endpoint.
+                this.write(controller, `data: ${JSON.stringify({ t: 'ready', cid: connectionId })}\n\n`);
+                this.ensureHeartbeat();
+            },
+            cancel: () => {
+                this.streams.delete(connectionId);
+                this.options.onDisconnect?.(connectionId);
+            }
+        });
+    }
+    owns(connectionId) {
+        return this.streams.has(connectionId);
+    }
+    send(connectionId, message) {
+        const controller = this.streams.get(connectionId);
+        if (!controller) {
+            return 0;
+        }
+        return this.write(controller, `data: ${JSON.stringify(message)}\n\n`);
+    }
+    close(connectionId) {
+        const controller = this.streams.get(connectionId);
+        this.streams.delete(connectionId);
+        try {
+            controller?.close();
+        }
+        catch {
+            // Already closed from the other end.
+        }
+    }
+    count() {
+        return this.streams.size;
+    }
+    stop() {
+        if (this.heartbeat) {
+            clearInterval(this.heartbeat);
+            this.heartbeat = null;
+        }
+        for (const connectionId of [...this.streams.keys()]) {
+            this.close(connectionId);
+        }
+    }
+    ensureHeartbeat() {
+        if (this.heartbeat || this.options.heartbeatMs <= 0) {
+            return;
+        }
+        // A comment frame. EventSource ignores it; an idle-timeout proxy does
+        // not, which is the whole point.
+        this.heartbeat = setInterval(() => {
+            for (const controller of this.streams.values()) {
+                this.write(controller, ': ping\n\n');
+            }
+        }, this.options.heartbeatMs);
+        this.heartbeat.unref?.();
+    }
+    write(controller, frame) {
+        try {
+            controller.enqueue(ENCODER.encode(frame));
+            return 1;
+        }
+        catch {
+            return 0;
+        }
+    }
+}
+exports.SseTransport = SseTransport;

package/dist/transport/scope-resolver.d.ts

@@ -0,0 +1,20 @@
+import type { LiveScope } from '../shared/inputs';
+export interface LiveHandshake {
+    connectionId: string;
+    /** Opaque credential from the client's `hello`. */
+    token?: string;
+}
+export interface LiveScopeResolver {
+    resolve(handshake: LiveHandshake): LiveScope | Promise<LiveScope>;
+}
+/**
+ * Default resolver: every connection is its own principal.
+ *
+ * Safe by construction — nothing is ever shared between connections, so no
+ * application can leak one user's data to another by forgetting to configure
+ * this. Applications that want `shared: 'tenant'` or a real user identity
+ * replace it.
+ */
+export declare class ConnectionScopeResolver implements LiveScopeResolver {
+    resolve(handshake: LiveHandshake): LiveScope;
+}

package/dist/transport/scope-resolver.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectionScopeResolver = void 0;
+/**
+ * Default resolver: every connection is its own principal.
+ *
+ * Safe by construction — nothing is ever shared between connections, so no
+ * application can leak one user's data to another by forgetting to configure
+ * this. Applications that want `shared: 'tenant'` or a real user identity
+ * replace it.
+ */
+class ConnectionScopeResolver {
+    resolve(handshake) {
+        return { principal: handshake.connectionId };
+    }
+}
+exports.ConnectionScopeResolver = ConnectionScopeResolver;

package/dist/transport/sse-routes.d.ts

@@ -0,0 +1,24 @@
+import type { SseTransport } from './SseTransport';
+export interface SseRouteOptions {
+    transport: SseTransport;
+    streamPath: string;
+    controlPath: string;
+}
+/**
+ * The two halves of the SSE transport, as HTTP.
+ *
+ * `GET streamPath` opens the downstream and names the connection; every
+ * client message goes up through `POST controlPath` and into the same
+ * `handleMessage` the WebSocket gateway uses. There is no second protocol
+ * here, and there must never be one.
+ *
+ * Handlers registered through `Carno.route()` receive a Bun `Request`, not a
+ * `Context` -- the docstring on that method says otherwise, the runtime does
+ * not.
+ */
+export declare function createSseRoutes(options: SseRouteOptions): {
+    streamPath: string;
+    controlPath: string;
+    stream: (request: Request) => Response;
+    control: (request: Request) => Promise<Response>;
+};