@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/store/postgres/tenants.js

@@ -1,214 +0,0 @@
-import { isTenantId } from "@nylorun/core/compatibility";
-import { TenantEnvelopeSchema, } from "@nylorun/core/contracts";
-import { STUDIO_PRINCIPAL_ID } from "../../tenant/principals.js";
-import { TenantConflictError, asQuarantine, quarantine, } from "../../tenant/quarantine.js";
-import { MIGRATIONS, lockSchema, migrateSchemaInTx, readSchemaVersion, schemaExists, } from "./migrations/index.js";
-import { TENANT_SCHEMA_PREFIX, tenantIdFromSchema, tenantSchemaName } from "./names.js";
-import { createPostgresSessionStore } from "./store.js";
-/**
- * Whether Postgres rejected a statement (a SQLSTATE), rather than the connection or the
- * server failing (classes 08, 53, 57, and the driver's own connection errors). Only the
- * first says something about the Tenant's schema.
- */
-function isStatementError(error) {
-    const code = error?.code;
-    return (typeof code === "string" &&
-        /^[0-9A-Z]{5}$/.test(code) &&
-        !/^(08|53|57)/.test(code));
-}
-export function createPostgresTenantCatalog(options) {
-    const { sql } = options;
-    const now = options.now ?? (() => new Date());
-    const migrations = options.migrations ?? MIGRATIONS;
-    const latest = migrations.length;
-    async function readEnvelopeWith(q, id) {
-        const schema = tenantSchemaName(id);
-        const invalid = (message) => quarantine("envelope-invalid", message, { tenantId: id });
-        let rows;
-        try {
-            rows = await q `
-        SELECT id, name, created_at, updated_at, schema_version
-        FROM ${q(`${schema}.tenant`)}`;
-        }
-        catch (error) {
-            // A missing schema or `tenant` table is the Tenant's problem; anything else
-            // (a lost connection) is not, and is thrown as it is.
-            const code = error.code;
-            if (code !== "42P01" && code !== "3F000")
-                throw error;
-            throw invalid(`Tenant envelope could not be read: ${error.message}`);
-        }
-        if (rows.length !== 1)
-            throw invalid("Tenant envelope is missing");
-        const row = rows[0];
-        const parsed = TenantEnvelopeSchema.safeParse({
-            id: row.id,
-            name: row.name,
-            createdAt: row.created_at,
-            updatedAt: row.updated_at,
-            schemaVersion: row.schema_version,
-        });
-        if (!parsed.success)
-            throw invalid("Tenant envelope is not valid");
-        if (parsed.data.id !== id)
-            throw invalid(`Tenant envelope id ${parsed.data.id} does not match schema ${schema}`);
-        return parsed.data;
-    }
-    async function bootstrapMatchesWith(q, id, bootstrap) {
-        const schema = tenantSchemaName(id);
-        const rows = await q `
-      SELECT id, token_hash, idempotency_key FROM ${q(`${schema}.principals`)}
-      WHERE role = 'application'`;
-        const app = rows.find((row) => row.id === bootstrap.principalId);
-        if (!app ||
-            app.token_hash !== bootstrap.credentialHash ||
-            app.idempotency_key !== bootstrap.idempotencyKey)
-            return false;
-        const studio = rows.find((row) => row.id === STUDIO_PRINCIPAL_ID);
-        if (studio?.token_hash !== bootstrap.studioCredentialHash)
-            return false;
-        return (bootstrap.derivedPrincipals ?? []).every((principal) => rows.find((row) => row.id === principal.id)?.token_hash ===
-            principal.credentialHash);
-    }
-    const catalog = {
-        async listTenantIds() {
-            const schemas = await sql `
-        SELECT nspname FROM pg_namespace
-        WHERE starts_with(nspname, ${TENANT_SCHEMA_PREFIX})
-        ORDER BY nspname COLLATE "C"`;
-            return schemas.flatMap(({ nspname }) => tenantIdFromSchema(nspname) ?? []);
-        },
-        async tenantExists(id) {
-            return isTenantId(id) && schemaExists(sql, tenantSchemaName(id));
-        },
-        async listTenants() {
-            const listings = [];
-            for (const id of await catalog.listTenantIds()) {
-                try {
-                    listings.push({ id, envelope: await readEnvelopeWith(sql, id) });
-                }
-                catch (error) {
-                    listings.push({
-                        id,
-                        envelope: null,
-                        quarantine: asQuarantine(error) ??
-                            quarantine("open-failed", "Tenant schema could not be read", {
-                                tenantId: id,
-                            }).toQuarantine(),
-                    });
-                }
-            }
-            return listings;
-        },
-        readEnvelope(id) {
-            return readEnvelopeWith(sql, id);
-        },
-        async createTenant({ envelope, principals }) {
-            const input = TenantEnvelopeSchema.parse(envelope);
-            const schema = tenantSchemaName(input.id);
-            const outcome = await sql.begin(async (tx) => {
-                await lockSchema(tx, schema);
-                if (await schemaExists(tx, schema))
-                    return { created: false };
-                await migrateSchemaInTx(tx, schema, migrations);
-                const stored = { ...input, schemaVersion: latest };
-                await tx `
-          INSERT INTO ${tx(`${schema}.tenant`)} (id, name, created_at, updated_at, schema_version)
-          VALUES (${stored.id}, ${stored.name}, ${stored.createdAt}, ${stored.updatedAt}, ${stored.schemaVersion})`;
-                const createdAt = now().toISOString();
-                await tx `
-          INSERT INTO ${tx(`${schema}.principals`)} (id, role, token_hash, idempotency_key, created_at)
-          VALUES (${principals.principalId}, 'application', ${principals.credentialHash},
-                  ${principals.idempotencyKey}, ${createdAt})`;
-                if (principals.studioCredentialHash)
-                    await tx `
-            INSERT INTO ${tx(`${schema}.principals`)} (id, role, token_hash, idempotency_key, created_at)
-            VALUES (${STUDIO_PRINCIPAL_ID}, 'application', ${principals.studioCredentialHash},
-                    NULL, ${createdAt})`;
-                for (const derived of principals.derivedPrincipals ?? [])
-                    await tx `
-            INSERT INTO ${tx(`${schema}.principals`)} (id, role, token_hash, idempotency_key, created_at)
-            VALUES (${derived.id}, 'application', ${derived.credentialHash}, NULL, ${createdAt})`;
-                return { created: true, envelope: stored };
-            });
-            if (outcome.created)
-                return { status: "created", envelope: outcome.envelope };
-            if (!(await bootstrapMatchesWith(sql, input.id, principals)))
-                throw new TenantConflictError();
-            return { status: "exists", envelope: await readEnvelopeWith(sql, input.id) };
-        },
-        async bootstrapMatches(id, bootstrap) {
-            if (!(await schemaExists(sql, tenantSchemaName(id))))
-                return false;
-            return bootstrapMatchesWith(sql, id, bootstrap);
-        },
-        async openTenant(id, storeOptions = {}) {
-            if (!isTenantId(id))
-                return { status: "not-found" };
-            const schema = tenantSchemaName(id);
-            const version = await readSchemaVersion(sql, schema);
-            if (version === undefined)
-                return { status: "not-found" };
-            if (version > latest)
-                return {
-                    status: "quarantined",
-                    reason: quarantine("schema-too-new", `Tenant schema version ${version} is newer than this Runtime's ${latest}`, { tenantId: id }).toQuarantine(),
-                };
-            let migrated = { from: version, to: version };
-            if (version < latest) {
-                try {
-                    migrated = await catalog.migrateTenant(id);
-                }
-                catch (error) {
-                    if (!asQuarantine(error) && !isStatementError(error))
-                        throw error;
-                    return {
-                        status: "quarantined",
-                        reason: asQuarantine(error) ??
-                            quarantine("migration-failed", `Tenant schema migration from version ${version} failed: ${error.message}`, { tenantId: id }).toQuarantine(),
-                    };
-                }
-            }
-            let envelope;
-            try {
-                envelope = await readEnvelopeWith(sql, id);
-            }
-            catch (error) {
-                const reason = asQuarantine(error);
-                if (!reason)
-                    throw error;
-                return { status: "quarantined", reason };
-            }
-            const store = createPostgresSessionStore({
-                sql,
-                tenantId: id,
-                schema,
-                schemaVersion: latest,
-                now: storeOptions.now,
-                onError: storeOptions.onError ?? options.onError,
-            });
-            return { status: "ok", store, envelope, migrated };
-        },
-        async migrateTenant(id) {
-            const schema = tenantSchemaName(id);
-            const result = await sql.begin(async (tx) => {
-                await lockSchema(tx, schema);
-                if (!(await schemaExists(tx, schema)))
-                    throw new Error(`Tenant ${id} does not exist`);
-                return { result: await migrateSchemaInTx(tx, schema, migrations) };
-            });
-            return result.result;
-        },
-        async deleteTenant(id) {
-            const schema = tenantSchemaName(id);
-            return sql.begin(async (tx) => {
-                await lockSchema(tx, schema);
-                if (!(await schemaExists(tx, schema)))
-                    return false;
-                await tx `DROP SCHEMA ${tx(schema)} CASCADE`;
-                return true;
-            });
-        },
-    };
-    return catalog;
-}

package/dist/streams/relay.d.ts

@@ -1,37 +0,0 @@
-import type { SessionStore } from "../store/types.js";
-import { type DurableStreams } from "./types.js";
-/** A session's outbox starts past the end of its stream: events are missing from the stream. */
-export declare class StreamGapError extends Error {
-    constructor(sessionId: string, first: number, tail: number);
-}
-export interface RelayOptions {
-    store: SessionStore;
-    streams: DurableStreams;
-    /** The Tenant whose basin receives the events; must match `store.tenantId`. */
-    tenantId: string;
-    /** Receives append and delete failures. The rows they concern stay in the outbox. */
-    onError?: (error: unknown) => void;
-}
-export interface Relay {
-    /**
-     * Appends leftover outbox rows (at most `limit`, default 1000) per session in
-     * sequence order: the Tenant sweep's recovery after a crash or an S2 outage.
-     * Resolves with the number of rows now in S2 and removed from the outbox.
-     * Per-session failures go to `onError`; those rows stay.
-     */
-    drain(limit?: number): Promise<number>;
-    /** Resolves when every relay started so far has settled. */
-    idle(): Promise<void>;
-    /** Stops listening to commits and waits for in-flight relays. */
-    close(): Promise<void>;
-}
-export declare function createRelay(options: RelayOptions): Relay;
-/** Appends a `work_available` signal to `tenant/work`. Not relayed through the outbox. */
-export declare function signalWork(streams: DurableStreams, tenantId: string): Promise<void>;
-/** Appends a `session.cancel` signal to `tenant/control`. Not relayed through the outbox. */
-export declare function signalCancel(streams: DurableStreams, tenantId: string, sessionId: string): Promise<void>;
-/**
- * Appends a `sessions.reset` signal to `tenant/control`: every process with the Tenant open
- * checks its session feeds against the Session Store.
- */
-export declare function signalSessionsReset(streams: DurableStreams, tenantId: string): Promise<void>;

package/dist/streams/relay.js

@@ -1,254 +0,0 @@
-/**
- * The outbox relay (architecture §12.4, "Writing: outbox and relay").
- *
- * The Session Store writes every event to its outbox in the same transaction
- * as the state change. After the commit the relay appends the events to the
- * stream of their session's incarnation (`sessions/<id>/<incarnation>`) with
- * `matchSeq` set to each batch's first sequence, and deletes the rows S2 has:
- *
- * - **The right incarnation.** A committed event comes with the incarnation
- *   its session had when the event was allocated (`Commit.incarnations`).
- *   Leftover rows (`drain`, and a commit that finds earlier rows still
- *   waiting) are read with the session's incarnation in one transaction that
- *   locks the session; deleting a session deletes its outbox rows in the same
- *   transaction, so those rows belong to the incarnation read. Either way a
- *   session deleted and created again with the same id never gets the old
- *   incarnation's events, or the reverse.
- * - **ok**: the rows are deleted through the last appended sequence, only
- *   while the session still has the incarnation appended to (one statement,
- *   `deleteOutbox` with `incarnation`).
- * - **`seq_mismatch` with the tail past the batch start**: an earlier attempt
- *   (this process or another) already appended those events. The rows below
- *   the tail are deleted, and whatever is left of the batch is appended from
- *   the tail.
- * - **`seq_mismatch` with the tail before the batch start**: earlier events of
- *   the session are still in the outbox (an earlier append failed), and the
- *   session's outbox is relayed in sequence order, which includes this batch.
- *   If the outbox's first row is past the tail, events are missing from the
- *   stream: the rows stay and the error goes to `onError`.
- * - **append throws** (S2 unreachable, basin missing): the rows stay in the
- *   outbox and the error goes to `onError`. The next commit of the session, or
- *   the Tenant sweep's `drain`, appends them in order.
- *
- * Conditional appends make this exactly-once and in order per session however
- * many processes relay the same rows. Within one process the relay also runs
- * one relay at a time per session.
- *
- * `work_available`, `session.cancel` and `sessions.reset` are signals, not
- * canonical events: they skip the outbox (`signalWork`, `signalCancel`,
- * `signalSessionsReset`). A commit that called `t.signalWork()` is signalled
- * by the relay after its events.
- */
-import { decodeCursor } from "../store/cursor.js";
-import { CONTROL_STREAM, WORK_AVAILABLE, WORK_STREAM, streamOfSession, } from "./types.js";
-/** A session's outbox starts past the end of its stream: events are missing from the stream. */
-export class StreamGapError extends Error {
-    constructor(sessionId, first, tail) {
-        super(`Outbox of session ${sessionId} starts at ${first}, past the end of its stream at ${tail}; events before it are missing`);
-        this.name = "StreamGapError";
-    }
-}
-/** At most this many records per append (S2 allows 1000). */
-const MAX_BATCH_RECORDS = 500;
-/** At most this many bytes of JSON per append (S2 allows 1 MiB metered). */
-const MAX_BATCH_BYTES = 768 * 1024;
-/** Outbox rows read per page while relaying one session. */
-const DRAIN_PAGE = 1000;
-export function createRelay(options) {
-    const { store, streams, tenantId } = options;
-    if (store.tenantId !== tenantId)
-        throw new Error(`Relay tenant ${tenantId} does not match store tenant ${store.tenantId}`);
-    const onError = options.onError ?? (() => { });
-    /** sessionId → tail of that session's relay chain. */
-    const chains = new Map();
-    const pending = new Set();
-    let closed = false;
-    /** Runs `task` after every earlier task of the same session. */
-    function serialize(sessionId, task) {
-        const previous = chains.get(sessionId) ?? Promise.resolve();
-        const run = previous.then(task, task);
-        const settled = run.then(() => undefined, () => undefined);
-        chains.set(sessionId, settled);
-        pending.add(settled);
-        void settled.then(() => {
-            pending.delete(settled);
-            if (chains.get(sessionId) === settled)
-                chains.delete(sessionId);
-        });
-        return run;
-    }
-    /**
-     * Appends `rows` (one session, ascending, contiguous) to the stream of `incarnation`
-     * with `matchSeq`, and deletes what S2 has while the session still has that incarnation.
-     * Throws a `StreamGapError` when the stream's tail is before the first row still to append.
-     */
-    async function appendRows(sessionId, incarnation, rows) {
-        const stream = streamOfSession({
-            id: sessionId,
-            ...(incarnation === null ? {} : { streamIncarnation: incarnation }),
-        });
-        const deleteThrough = (seq) => store.tx((t) => t.deleteOutbox(sessionId, seq, incarnation));
-        let rest = rows;
-        while (rest.length > 0) {
-            const batch = takeBatch(rest);
-            const first = batch[0].seq;
-            const last = batch[batch.length - 1].seq;
-            const result = await streams.append(tenantId, stream, batch.map((row) => row.event), { matchSeq: first });
-            if (result.status === "ok") {
-                await deleteThrough(last);
-                rest = rest.slice(batch.length);
-            }
-            else if (result.tail > first) {
-                // Already appended by an earlier attempt: S2 has everything below the tail.
-                await deleteThrough(result.tail - 1);
-                rest = rest.filter((row) => row.seq >= result.tail);
-            }
-            else {
-                throw new StreamGapError(sessionId, first, result.tail);
-            }
-        }
-    }
-    /**
-     * Appends the session's outbox rows in sequence order, at most `limit`, reading them with
-     * the session's incarnation under its lock. Resolves with the number relayed.
-     */
-    async function relaySession(sessionId, limit = Infinity) {
-        let relayed = 0;
-        while (relayed < limit) {
-            const page = Math.min(DRAIN_PAGE, limit - relayed);
-            const read = await store.tx(async (t) => {
-                const session = await t.lockSession(sessionId);
-                // A deleted session took its outbox rows with it.
-                if (!session)
-                    return undefined;
-                return {
-                    incarnation: session.streamIncarnation ?? null,
-                    rows: await t.outbox(page, { sessionId }),
-                };
-            });
-            if (!read || read.rows.length === 0)
-                return relayed;
-            const run = contiguous(read.rows);
-            await appendRows(sessionId, read.incarnation, run);
-            relayed += run.length;
-            // A gap inside the outbox: the next page starts at it and reports it.
-            if (read.rows.length < page && run.length === read.rows.length)
-                return relayed;
-        }
-        return relayed;
-    }
-    /**
-     * Appends one commit's rows of a session to the stream of the incarnation they were
-     * written under. When earlier rows are still in the outbox, relays the whole outbox.
-     */
-    async function relayCommitted(sessionId, incarnation, rows) {
-        try {
-            await appendRows(sessionId, incarnation, contiguous(rows));
-        }
-        catch (error) {
-            if (!(error instanceof StreamGapError))
-                throw error;
-            await relaySession(sessionId);
-        }
-    }
-    function onCommit(commit) {
-        if (closed)
-            return;
-        /** `sessionId\0incarnation` → the commit's rows of that incarnation. */
-        const groups = new Map();
-        commit.events.forEach((event, i) => {
-            let seq;
-            try {
-                seq = decodeCursor(event.sessionId, event.cursor);
-            }
-            catch {
-                onError(new Error(`Event ${event.eventId} has an invalid cursor; left for the sweep`));
-                return;
-            }
-            const incarnation = commit.incarnations[i] ?? null;
-            const key = `${event.sessionId}\u0000${incarnation ?? ""}`;
-            let group = groups.get(key);
-            if (!group)
-                groups.set(key, (group = { sessionId: event.sessionId, incarnation, rows: [] }));
-            group.rows.push({ sessionId: event.sessionId, seq, event });
-        });
-        const relays = [...groups.values()].map(({ sessionId, incarnation, rows }) => {
-            rows.sort((a, b) => a.seq - b.seq);
-            return serialize(sessionId, () => relayCommitted(sessionId, incarnation, rows)).catch(onError);
-        });
-        if (commit.workAvailable) {
-            const signalled = Promise.all(relays)
-                .then(() => signalWork(streams, tenantId))
-                .catch(onError);
-            pending.add(signalled);
-            void signalled.then(() => pending.delete(signalled));
-        }
-    }
-    const unsubscribe = store.onCommit(onCommit);
-    async function idle() {
-        while (pending.size > 0)
-            await Promise.all([...pending]);
-    }
-    return {
-        async drain(limit = 1000) {
-            const rows = await store.tx((t) => t.outbox(limit));
-            const bySession = new Map();
-            for (const row of rows)
-                bySession.set(row.sessionId, (bySession.get(row.sessionId) ?? 0) + 1);
-            const counts = await Promise.all([...bySession].map(([sessionId, count]) => 
-            // Rows may have been relayed since they were read; the conditional
-            // appends skip those.
-            serialize(sessionId, () => relaySession(sessionId, count)).catch((error) => {
-                onError(error);
-                return 0;
-            })));
-            return counts.reduce((sum, n) => sum + n, 0);
-        },
-        idle,
-        async close() {
-            closed = true;
-            unsubscribe();
-            await idle();
-        },
-    };
-}
-/** Appends a `work_available` signal to `tenant/work`. Not relayed through the outbox. */
-export async function signalWork(streams, tenantId) {
-    await streams.append(tenantId, WORK_STREAM, [WORK_AVAILABLE]);
-}
-/** Appends a `session.cancel` signal to `tenant/control`. Not relayed through the outbox. */
-export async function signalCancel(streams, tenantId, sessionId) {
-    if (!sessionId)
-        throw new Error("sessionId is required");
-    const signal = { type: "session.cancel", sessionId };
-    await streams.append(tenantId, CONTROL_STREAM, [signal]);
-}
-/**
- * Appends a `sessions.reset` signal to `tenant/control`: every process with the Tenant open
- * checks its session feeds against the Session Store.
- */
-export async function signalSessionsReset(streams, tenantId) {
-    const signal = { type: "sessions.reset" };
-    await streams.append(tenantId, CONTROL_STREAM, [signal]);
-}
-// ---------------------------------------------------------------------------
-/** The leading run of `rows` (ascending) without a sequence gap. */
-function contiguous(rows) {
-    let n = 1;
-    while (n < rows.length && rows[n].seq === rows[n - 1].seq + 1)
-        n += 1;
-    return rows.slice(0, n);
-}
-/** The leading rows that fit one append. Always at least one row. */
-function takeBatch(rows) {
-    let bytes = 0;
-    let n = 0;
-    while (n < rows.length && n < MAX_BATCH_RECORDS) {
-        const size = JSON.stringify(rows[n].event).length + 8;
-        if (n > 0 && bytes + size > MAX_BATCH_BYTES)
-            break;
-        bytes += size;
-        n += 1;
-    }
-    return rows.slice(0, n);
-}

package/dist/tenant/envelope.d.ts

@@ -1,7 +0,0 @@
-import { type TenantEnvelope } from "@nylorun/core/contracts";
-export declare function parseEnvelope(raw: unknown, expectedId?: string): TenantEnvelope;
-export declare function envelopeNow(input: {
-    id: string;
-    name: string;
-    schemaVersion: number;
-}, now?: Date): TenantEnvelope;

package/dist/tenant/envelope.js

@@ -1,22 +0,0 @@
-import { TenantEnvelopeSchema, } from "@nylorun/core/contracts";
-import { quarantine } from "./quarantine.js";
-export function parseEnvelope(raw, expectedId) {
-    const parsed = TenantEnvelopeSchema.safeParse(raw);
-    if (!parsed.success) {
-        throw quarantine("envelope-invalid", "the Tenant envelope is missing or invalid", expectedId ? { tenantId: expectedId } : {});
-    }
-    if (expectedId !== undefined && parsed.data.id !== expectedId) {
-        throw quarantine("envelope-invalid", `the Tenant envelope id ${parsed.data.id} does not match ${expectedId}`, { tenantId: expectedId });
-    }
-    return parsed.data;
-}
-export function envelopeNow(input, now = new Date()) {
-    const iso = now.toISOString();
-    return {
-        id: input.id,
-        name: input.name,
-        createdAt: iso,
-        updatedAt: iso,
-        schemaVersion: input.schemaVersion,
-    };
-}

package/dist/tenant/live.d.ts

@@ -1,92 +0,0 @@
-/**
- * Live delivery over Durable Streams (architecture §12.4, "Reading"): session history
- * (`GET /v1/sessions/:id/items`), session SSE (`GET /v1/sessions/:id/events`) and executor
- * work streams (`GET /v1/executors/connect`).
- *
- * - **Streams.** A session's events are in the stream of its current incarnation
- *   (`streamOfSession`, `sessions/<id>/<incarnation>`), resolved from the session on every
- *   request; cursors carry only the session id and sequence.
- * - **History** reads the session's stream from the cursor up to the tail seen when the read
- *   starts. The `agent` filter runs here, and the response cursor is the last record read. If
- *   the streams fail, history answers `503`.
- * - **SSE** shares one stream read per observed session in this process (a `SessionFeed`)
- *   among that session's observers. Each observer keeps the next sequence it needs and skips
- *   what it already has, so a client resuming from `Last-Event-ID` sees no gap and no
- *   duplicate. An observer behind the feed restarts the shared read from its own position.
- *   A feed follows one incarnation: it ends once its session is gone or has a new
- *   incarnation (a reset, possibly on another node), checked when a client joins, when its
- *   read fails, on a `sessions.reset` signal, and periodically (`checkFeeds`).
- * - **Executor streams** receive `work_available` from the `tenant/work` reader that
- *   `tenant/streams.ts` runs (one per Tenant per process); discovery stays `GET /v1/actions`.
- *
- * Business code never writes here: events reach streams only through the relay, after commit.
- */
-import type { IncomingMessage, ServerResponse } from "node:http";
-import type { LiveEvent } from "@nylorun/core/contracts";
-import type { TenantContext } from "./context.js";
-import type { StreamsWiring } from "./streams.js";
-/** One SSE client of a session: the next sequence it needs. */
-interface Observer {
-    readonly response: ServerResponse;
-    next: number;
-}
-/** The shared stream read of one observed session. */
-interface SessionFeed {
-    readonly sessionId: string;
-    /** The stream of the session's incarnation when the feed started. */
-    readonly stream: string;
-    /** The sequence the shared read yields next. Every observer's `next` is at or past it. */
-    next: number;
-    readonly observers: Set<Observer>;
-    /** Aborts the current read; replaced when the read restarts from an earlier sequence. */
-    read: AbortController;
-}
-export interface LiveHub {
-    /** Set once by `wireStreams`. */
-    wiring: StreamsWiring | undefined;
-    /** Session id → its shared read and observers. */
-    readonly feeds: Map<string, SessionFeed>;
-    readonly executorStreams: Map<string, Set<ServerResponse>>;
-}
-export declare function createLiveHub(): LiveHub;
-export declare function send(response: ServerResponse, data: string): void;
-/** Start an SSE response with keepalives; `onClose` runs once the client goes away. */
-export declare function openSse(request: IncomingMessage, response: ServerResponse, onClose: () => void): void;
-/** The resume cursor: `?cursor=` wins over `Last-Event-ID`. */
-export declare function requestCursor(request: IncomingMessage, url: URL): string | undefined;
-/**
- * `GET /v1/sessions/:id/items`: the session stream after the cursor, up to its tail when the
- * read starts. The cursor returned is the last record read (the request's cursor when none
- * was), whatever the `agent` filter kept.
- */
-export declare function readHistory(ctx: TenantContext, sessionId: string, cursor: string | undefined, agent: string | undefined): Promise<{
-    items: LiveEvent[];
-    cursor: string | null;
-}>;
-/**
- * `GET /v1/sessions/:id/events`: joins the session's shared read at the client's cursor and
- * follows it until the client leaves, the session is reset or deleted, or the Tenant closes.
- */
-export declare function streamSessionEvents(ctx: TenantContext, request: IncomingMessage, response: ServerResponse, sessionId: string, cursor: string | undefined): Promise<void>;
-/**
- * Ends every feed in this process whose session is gone or has a new incarnation. Run on a
- * `sessions.reset` signal and periodically, so feeds on nodes other than the one that reset
- * the Tenant end too.
- */
-export declare function checkFeeds(ctx: TenantContext): Promise<void>;
-/** `GET /v1/executors/connect`: an executor's work stream, primed with one `work_available`. */
-export declare function streamExecutorWork(hub: LiveHub, request: IncomingMessage, response: ServerResponse, tokenHash: string): void;
-/** Called by the `tenant/work` reader for each signal: wake every connected executor. */
-export declare function announceWork(hub: LiveHub): void;
-export declare function executorConnected(hub: LiveHub, tokenHash: string): boolean;
-export declare function connectedExecutorCount(hub: LiveHub): number;
-/** End the streams a token owns (rotation or deregistration). */
-export declare function endExecutorStreams(hub: LiveHub, tokenHash: string): void;
-/** Reset or close: end every session observer and stop every shared read. */
-export declare function clearObservers(hub: LiveHub): void;
-/** Reset: end and forget every executor stream. */
-export declare function clearExecutorStreams(hub: LiveHub): void;
-/** Close: end every executor stream, then every session observer. */
-export declare function endAllStreams(hub: LiveHub): void;
-export declare function sleep(ms: number, signal: AbortSignal): Promise<void>;
-export {};