@nylorun/runtime 0.13.0-beta → 0.14.0-beta

package/dist/store/types.d.ts

@@ -9,9 +9,9 @@
  *
  * 1. **One transaction per `tx` call, READ COMMITTED or stronger.** Nothing a
  *    transaction wrote is visible to others before it commits, and nothing is
- *    kept when `fn` throws: document writes, event sequences, outbox rows,
- *    `afterCommit` callbacks and `signalWork` are all discarded, and `tx`
- *    rejects with the error `fn` threw.
+ *    kept when `fn` throws: document writes, event sequences, record rows,
+ *    and `afterCommit` callbacks are all discarded, and `tx` rejects with the
+ *    error `fn` threw.
  * 2. **Session-scoped writes lock the session row first.** `lockSession` takes
  *    a row lock (`SELECT … FOR UPDATE`) held until the transaction ends. Effect
  *    intent and outcome, Action transitions, checkpoint settlement and event
@@ -21,18 +21,17 @@
  * 3. **Per-session event sequence.** `event` allocates the session's next
  *    sequence under the session lock, starting at 0, without gaps across
  *    committed transactions. The sequence is also the S2 sequence number of the
- *    event in the session's stream (`sessions/<id>/<incarnation>`,
- *    `streams/types.ts`), and the cursor is `base64url("<sessionId>:<seq>")`
- *    (see `store/cursor.ts`).
+ *    event in the session's stream (`sessions/<id>` in the Tenant's basin
+ *    generation, `streams/basin.ts`), and the cursor is
+ *    `base64url("<sessionId>:<seq>")` (see `store/cursor.ts`).
  * 4. **No external I/O inside `fn`.** No model, tool, MCP, sandbox, Restate or
- *    S2 call, and no `fetch`, runs inside a transaction. Wakes go through
- *    `afterCommit`, executor notifications through `signalWork`, and events are
- *    delivered to commit listeners after commit (seam rule 1 and 2).
+ *    S2 call, and no `fetch`, runs inside a transaction. Wakes and deliveries go
+ *    through `afterCommit`, and events are delivered to commit listeners after
+ *    commit (seam rule 1 and 2).
  * 5. **No nested transactions.** Calling `store.tx` from inside `fn` rejects.
  *    A `Tx` must not be used after its `tx` call settles.
  * 6. **Post-commit order.** After a commit, the store first calls every commit
- *    listener once with the transaction's events (in allocation order) and its
- *    `signalWork` flag, then runs the `afterCommit` callbacks in registration
+ *    listener once with the transaction's events (in allocation order), then runs the `afterCommit` callbacks in registration
  *    order and awaits them. Listener and callback failures are reported to the
  *    store's error hook; they never reject `tx`, because the commit stands.
  *    Recovery from a lost post-commit step is the Tenant sweep's job.
@@ -46,14 +45,17 @@
  * ## Typed queries, no scans
  *
  * There is no generic table scan. Every read the Runtime needs is a typed
- * method on `Tx` (`sessionsWithStatus`, `expiredClaims`, `pendingActions`,
+ * method on `Tx` (`sessionsWithStatus`, `expiredDeliveries`, `pendingActions`,
  * `effectsForTurn`, `linkedSessions`, `counts`, …) that an implementation can
- * back with an index, and principals, executors, vaults and Tenant settings
+ * back with an index, and principals, endpoints, vaults and Tenant settings
  * have their own methods rather than raw SQL outside the store. Session history
- * is not read from the store: the relay moves events from the outbox to
- * Durable Streams, and history and SSE read them there (`tenant/streams.ts`).
+ * is not read from the store: every event is written to the record (Postgres
+ * `nylorun_streams.session_events`) in its transaction, the stream relay
+ * (`streams/relay/`) feeds Durable Streams from it, and history and SSE read
+ * them there (`tenant/session-streams.ts`).
  */
-import type { Action, LiveEvent } from "@nylorun/core/contracts";
+import type { RecordReader } from "../streams/relay/types.js";
+import type { Action, EventPayload, EventType, LiveEvent, SessionEventOf } from "@nylorun/core/contracts";
 import type { HostEffect } from "@nylorun/harness/run";
 /** Tables holding JSON documents keyed by `id`. */
 export type DocTable = "definitions" | "sessions" | "commands" | "checkpoints" | "effects" | "actions" | "sandboxes" | "links";
@@ -87,18 +89,13 @@ export interface SessionDoc {
     agentId: string;
     status: SessionStatus | (string & {});
     activeTurnId: string | null;
-    /**
-     * Names the session's event stream (`sessions/<id>/<incarnation>`, `streams/types.ts`).
-     * Set when the session is created; `event` reports it with each event (`Commit`).
-     */
-    streamIncarnation?: string;
 }
 /** The fields of an effect document the store indexes (`request.sessionId`, `request.turnId`, `request.kind`, `status`). */
 export interface EffectDoc {
     request: HostEffect;
     status: EffectStatus | (string & {});
 }
-/** Actions are stored as the wire `Action`. Indexed: `sessionId`, `turnId`, `agentId`, `status`, `kind`, `leaseExpiresAt`. */
+/** Actions are stored as the wire `Action`. Indexed: `sessionId`, `turnId`, `agentId`, `status`, `kind`, `deadlineAt`. */
 export type ActionDoc = Action;
 /** A workflow → agent session link, keyed by the linked agent session id. Indexed: `workflowSessionId`. */
 export interface LinkDoc {
@@ -125,42 +122,70 @@ export interface LinkedSession<S extends SessionDoc = SessionDoc> {
     link: LinkDoc;
     session: StoredSession<S>;
 }
-/** One committed-but-not-yet-relayed event (§12.4). Deleted once S2 has it. */
-export interface OutboxRow {
-    sessionId: string;
-    seq: number;
-    event: LiveEvent;
-}
-export interface OutboxStats {
-    /** Unrelayed events. */
-    depth: number;
-    /** ISO `createdAt` of the oldest unrelayed event, or null when the outbox is empty. */
-    oldestCreatedAt: string | null;
-}
 /** What one commit produced, delivered to commit listeners after commit. */
 export interface Commit {
     /** Events written by the transaction, in allocation order. */
     readonly events: readonly LiveEvent[];
     /**
-     * The `streamIncarnation` of each event's session when the event was allocated (under the
-     * session lock), aligned with `events`; null for a session without one. The relay appends
-     * each event to that incarnation's stream.
+     * The basin generation of each event, aligned with `events`: the stream relay appends it to
+     * `sessions/<id>` in that generation's basin.
      */
-    readonly incarnations: readonly (string | null)[];
-    /** True when the transaction called `signalWork()`. */
-    readonly workAvailable: boolean;
+    readonly generations: readonly number[];
+}
+/** A Tenant's basin generations (Durable Streams §8.1). */
+export interface BasinGenerations {
+    /** The basin session streams are written to and read from. */
+    current: number;
+    /** Earlier generations whose basins are still to be deleted. */
+    retired: number[];
 }
 export type CommitListener = (commit: Commit) => void;
-/** Executors carry a bearer secret hash, so they use typed columns with a unique token hash. */
-export interface ExecutorRow {
+/**
+ * An Action endpoint: the URL the Runtime delivers one agent's Actions to, and what recent
+ * deliveries and the last ping say about it.
+ */
+export interface EndpointRow {
     agentId: string;
-    tokenHash: string;
+    url: string;
     implementationVersion: string;
     manifestHash?: string;
+    timeoutMs: number;
+    maxConcurrent: number;
+    /** Application principal that registered it, when known. */
     principalId?: string;
+    lastDeliveryAt?: string;
+    lastSuccessAt?: string;
+    lastErrorCode?: string;
+    lastErrorMessage?: string;
+    consecutiveFailures: number;
+    /** What the endpoint reported serving on the last ping. */
+    servedImplementationVersion?: string;
+    servedManifestHash?: string;
     createdAt: string;
     updatedAt: string;
 }
+/** The registration part of an endpoint, as `putEndpoint` writes it. */
+export type EndpointRegistrationRow = Pick<EndpointRow, "agentId" | "url" | "implementationVersion" | "manifestHash" | "timeoutMs" | "maxConcurrent" | "principalId" | "updatedAt">;
+/** One observation about an endpoint (`recordEndpointHealth`). */
+export type EndpointHealthUpdate = 
+/** A delivery was answered. */
+{
+    kind: "success";
+    at: string;
+}
+/** A delivery failed: not reached, refused, or lost. */
+ | {
+    kind: "failure";
+    at: string;
+    code: string;
+    message: string;
+}
+/** A ping was answered with what the endpoint serves. */
+ | {
+    kind: "served";
+    implementationVersion: string;
+    manifestHash?: string;
+};
 export interface PrincipalRow {
     id: string;
     role: "application" | (string & {});
@@ -184,6 +209,34 @@ export interface SealedSecret {
     ciphertext: Uint8Array;
     wrappedDek: Uint8Array;
 }
+/** A Tenant signing key (subject tokens). The private key is sealed; the public JWK is not. */
+export interface SigningKeyRow extends SealedSecret {
+    id: string;
+    state: "standby" | "current" | "previous" | "revoked";
+    alg: "ES256";
+    /** JSON text of the public JWK. */
+    publicJwk: string;
+    createdAt: string;
+    activatedAt: string | null;
+    retiredAt: string | null;
+    revokedAt: string | null;
+}
+/** A publishable key (Host feature `browser-access`). Public by design. */
+export interface PublishableKeyRow {
+    id: string;
+    key: string;
+    name: string;
+    /** JSON array of allowed origins. */
+    originsJson: string;
+    createdAt: string;
+    revokedAt: string | null;
+}
+/** A subject's turn bucket (subject limits): tokens left and when they were last refilled. */
+export interface SubjectUsageRow {
+    subject: string;
+    turnTokens: number;
+    refilledAt: string;
+}
 export interface VaultCredentialRow extends SealedSecret {
     id: string;
     vaultId: string;
@@ -229,7 +282,7 @@ export interface StoreCounts {
     sessions: number;
     /** Sessions `running` or `runnable`. */
     runningSessions: number;
-    /** Actions `pending` or `claimed`. */
+    /** Actions `pending` or `delivering`. */
     pendingActions: number;
     /** Effects `uncertain`. */
     uncertainEffects: number;
@@ -263,10 +316,12 @@ export interface SessionStore {
     tx<T>(fn: (t: Tx) => Promise<T>): Promise<T>;
     /**
      * Registers a listener called once per committed transaction that wrote
-     * events or signalled work. Returns an unsubscribe function. The outbox
-     * relay (`streams/relay.ts`) subscribes here.
+     * events. Returns an unsubscribe function. A Tenant without the Host's stream
+     * relay relays its own commits from here (`tenant/streams.ts`).
      */
     onCommit(listener: CommitListener): () => void;
+    /** Reads the record back, for the stream relay's refills and reconciliation. */
+    record(): RecordReader;
     /** Reachability and schema check for Tenant status and `/ready`. Never throws. */
     health(): Promise<StoreHealth>;
     close(): Promise<void>;
@@ -279,7 +334,7 @@ export interface StoreHealth {
 /** Options every implementation accepts. */
 export interface SessionStoreOptions {
     tenantId: string;
-    /** Clock for event `createdAt`. Defaults to `() => new Date()`. */
+    /** Clock for event `time`. Defaults to `() => new Date()`. */
     now?: () => Date;
     /** Receives listener and `afterCommit` failures, which never reject `tx`. */
     onError?: (error: unknown) => void;
@@ -290,9 +345,9 @@ export interface Tx {
     /** Insert or replace. For `sessions`, ownership fields in `body` are ignored. */
     put(table: DocTable, id: string, body: unknown): Promise<void>;
     /**
-     * Deletes a document. Deleting a session also deletes its outbox rows, so a
-     * session created again with the same id starts at sequence 0 without
-     * colliding with rows the relay never took (its stream is a new incarnation).
+     * Deletes a document. Deleting a session keeps its record rows and log head
+     * (per-session record deletion is deferred, Durable Streams §15), so a session
+     * created again with the same id continues its log and stream.
      */
     delete(table: DocTable, id: string): Promise<void>;
     /**
@@ -313,14 +368,15 @@ export interface Tx {
     lockSession<T extends SessionDoc = SessionDoc>(id: string): Promise<StoredSession<T> | undefined>;
     /**
      * Allocates the session's next sequence (from 0) under the session lock,
-     * writes the event to the outbox and buffers it for commit listeners.
-     * Rejects when the session does not exist. The returned cursor is final.
+     * builds the event on the `nylorun.event/2` envelope, checks it against the
+     * event catalog (`InvalidEventError` when it does not match), writes it to
+     * the record in the Tenant's current basin generation and buffers it for
+     * commit listeners. Rejects when the session does not exist. The returned
+     * cursor is final.
      */
-    event(sessionId: string, turnId: string | null, type: string, payload: unknown): Promise<LiveEvent>;
+    event<T extends EventType>(sessionId: string, turnId: string | null, type: T, payload: EventPayload<T>): Promise<SessionEventOf<T>>;
     /** Runs `fn` after a successful commit (never on rollback). Used for wakes. */
     afterCommit(fn: () => void | Promise<void>): void;
-    /** Signals `work_available` to executors after a successful commit. */
-    signalWork(): void;
     /**
      * Locks the session and takes ownership when it has no owner or the owner's
      * lease ended at or before `now`; then increments `epoch` and sets the lease
@@ -354,10 +410,14 @@ export interface Tx {
     }): Promise<StoredSession<T>[]>;
     listDefinitions<T extends DefinitionDoc = DefinitionDoc>(): Promise<T[]>;
     listSandboxes<T extends SandboxDoc = SandboxDoc>(): Promise<T[]>;
-    /** Claimed actions whose lease ended at or before `now`, earliest lease first. */
-    expiredClaims(now: Date, limit: number): Promise<ActionDoc[]>;
-    /** `pending` actions offered to one agent's executor. */
+    /** One agent's `pending` actions, delivered when its endpoint is registered. */
     pendingActions(agentId: string): Promise<ActionDoc[]>;
+    /** How many of one agent's actions are `delivering` (Action endpoints). */
+    deliveringCount(agentId: string): Promise<number>;
+    /** `pending` actions of agents that have an Action endpoint, by id. */
+    pendingActionsWithEndpoint(limit: number): Promise<ActionDoc[]>;
+    /** `delivering` actions whose deadline is at or before `now`, earliest first. */
+    expiredDeliveries(now: Date, limit: number): Promise<ActionDoc[]>;
     actionsForSession(sessionId: string, filter?: SessionActionFilter): Promise<ActionDoc[]>;
     actionsWithStatus(statuses: readonly ActionStatus[], filter?: {
         kinds?: readonly ActionKind[];
@@ -372,27 +432,19 @@ export interface Tx {
     /** Links of one workflow session joined to their existing agent sessions, ordered by agent session id. */
     linkedSessions<S extends SessionDoc = SessionDoc>(workflowSessionId: string): Promise<LinkedSession<S>[]>;
     counts(): Promise<StoreCounts>;
-    /** Unrelayed events, ordered by session id then sequence. */
-    outbox(limit: number, filter?: {
-        sessionId?: string;
-    }): Promise<OutboxRow[]>;
+    basinGenerations(): Promise<BasinGenerations>;
+    /** Forgets a retired generation once its basin is deleted. */
+    forgetRetiredGeneration(generation: number): Promise<void>;
+    listEndpoints(): Promise<EndpointRow[]>;
+    getEndpoint(agentId: string): Promise<EndpointRow | undefined>;
     /**
-     * Deletes a session's outbox rows with `seq <= throughSeq`. Returns the number deleted.
-     * With `incarnation`, deletes only while the session exists with that `streamIncarnation`
-     * (null: none), in one statement: a relay that appended to an abandoned incarnation's
-     * stream never deletes the rows of a session created again with the same id.
+     * Inserts or updates by `agentId`, keeping `createdAt`. Health is kept, except that a new
+     * `url` starts with none.
      */
-    deleteOutbox(sessionId: string, throughSeq: number, incarnation?: string | null): Promise<number>;
-    /** How many events are unrelayed, and the `createdAt` of the oldest (Tenant status). */
-    outboxStats(): Promise<OutboxStats>;
-    listExecutors(): Promise<ExecutorRow[]>;
-    getExecutor(agentId: string): Promise<ExecutorRow | undefined>;
-    /**
-     * Inserts or updates by `agentId`, keeping `createdAt` on update. Rejects
-     * when another agent already uses `tokenHash`.
-     */
-    putExecutor(row: Omit<ExecutorRow, "createdAt">): Promise<void>;
-    deleteExecutor(agentId: string): Promise<void>;
+    putEndpoint(row: EndpointRegistrationRow): Promise<void>;
+    deleteEndpoint(agentId: string): Promise<void>;
+    /** Records one observation. Nothing happens when the endpoint does not exist. */
+    recordEndpointHealth(agentId: string, update: EndpointHealthUpdate): Promise<void>;
     /** Rejects when the id or token hash already exists. */
     insertPrincipal(row: PrincipalRow): Promise<void>;
     principalByTokenHash(tokenHash: string): Promise<PrincipalRow | undefined>;
@@ -428,15 +480,58 @@ export interface Tx {
     getVaultIdempotency(id: string): Promise<VaultIdempotencyRow | undefined>;
     /** Rejects when the id exists. */
     insertVaultIdempotency(row: VaultIdempotencyRow): Promise<void>;
+    /**
+     * Serializes signing key changes: held until the transaction ends. Take it before reading
+     * the keys a change depends on, so concurrent first uses or rotations do not collide.
+     */
+    lockSigningKeys(): Promise<void>;
+    /** Rejects on a duplicate id, or a second key in `standby`, `current` or `previous`. */
+    insertSigningKey(row: SigningKeyRow): Promise<void>;
+    signingKey(id: string): Promise<SigningKeyRow | undefined>;
+    /** Keys in the given states (all when omitted), ordered by `createdAt`, then id. */
+    signingKeys(states?: readonly SigningKeyRow["state"][]): Promise<SigningKeyRow[]>;
+    /**
+     * Moves a key from `from` to `to` and stamps the matching time (`activatedAt` for
+     * `current`, `retiredAt` for `previous`, `revokedAt` for `revoked`). Returns false when the
+     * key is not in `from`.
+     */
+    setSigningKeyState(id: string, from: SigningKeyRow["state"], to: SigningKeyRow["state"], at: string): Promise<boolean>;
+    countSigningKeys(): Promise<number>;
+    /** The subject's revocation epoch; 0 when it was never revoked. */
+    subjectEpoch(subject: string): Promise<number>;
+    /** The epochs of several subjects; subjects never revoked are absent. */
+    subjectEpochs(subjects: readonly string[]): Promise<Map<string, number>>;
+    /** Adds one to the subject's epoch and returns the new value. */
+    bumpSubjectEpoch(subject: string, at: string): Promise<number>;
+    /**
+     * The subject's turn bucket, created from `initial` when missing, locked until the
+     * transaction ends so concurrent commands of one subject serialize.
+     */
+    lockSubjectUsage(initial: SubjectUsageRow): Promise<SubjectUsageRow>;
+    putSubjectUsage(row: SubjectUsageRow): Promise<void>;
+    /** How many sessions of `ownerUserId` are in one of `statuses`. */
+    countOwnerSessions(ownerUserId: string, statuses: readonly string[]): Promise<number>;
+    /** Rejects on a duplicate id, key or name. */
+    insertPublishableKey(row: PublishableKeyRow): Promise<void>;
+    publishableKeyByKey(key: string): Promise<PublishableKeyRow | undefined>;
+    publishableKey(id: string): Promise<PublishableKeyRow | undefined>;
+    /** All keys, revoked ones included, ordered by `createdAt`, then id. */
+    publishableKeys(): Promise<PublishableKeyRow[]>;
+    /** Returns false when the key does not exist. */
+    updatePublishableKey(id: string, patch: Partial<Pick<PublishableKeyRow, "originsJson" | "revokedAt">>): Promise<boolean>;
     getSetting(key: string): Promise<string | undefined>;
     putSetting(key: string, value: string): Promise<void>;
     /**
      * Deletes Tenant state by scope, in this transaction:
-     * - `sessions`: sessions, commands, checkpoints, effects, actions, links and the outbox;
+     * - `sessions`: sessions, commands, checkpoints, effects, actions, links, subject turn
+     *   buckets and the Tenant's record rows and log heads. The Tenant moves to the next basin
+     *   generation and the current one is retired, so session ids it frees start again in an
+     *   empty basin;
      * - `sandboxes`: sandbox records;
-     * - `all`: both, plus definitions, executors and user vaults with their
-     *   credentials. The host vault, principals, settings, audit and vault
-     *   idempotency rows stay.
+     * - `all`: both, plus definitions, Action endpoints and user vaults with their
+     *   credentials. The host vault, principals, signing keys, subject epochs, publishable
+     *   keys, settings,
+     *   audit and vault idempotency rows stay.
      */
     reset(scope: ResetScope): Promise<void>;
 }

package/dist/streams/basin.d.ts

@@ -20,4 +20,21 @@
  */
 export declare const MAX_BASIN_PREFIX_LENGTH = 16;
 export declare function validateBasinPrefix(prefix: string): string;
-export declare function tenantBasinName(tenantId: string, prefix?: string): string;
+/**
+ * The basin of one generation of a Tenant (Durable Streams §8.1). A Tenant reset moves the
+ * Tenant to a new generation, so a session id it frees starts again in an empty basin.
+ * `DurableStreams` methods take this key where they take a Tenant id; generation 0 is the
+ * Tenant id itself, so existing basins keep their names.
+ */
+export declare function basinOf(tenantId: string, generation: number): string;
+/** The Tenant id and generation of a basin key from `basinOf`. */
+export declare function parseBasin(basin: string): {
+    tenantId: string;
+    generation: number;
+};
+/**
+ * The S2 basin of a Tenant, or of one of its generations (`basinOf`). Generation `g` > 0 of
+ * a canonical Tenant appends `-<g mod 1296 in base36>`, at most 48 characters with a
+ * 16-character prefix; other ids fold the generation into their hash.
+ */
+export declare function tenantBasinName(basin: string, prefix?: string): string;

package/dist/streams/basin.js

@@ -28,13 +28,42 @@ export function validateBasinPrefix(prefix) {
         throw new Error(`S2 basin prefix must be at most ${MAX_BASIN_PREFIX_LENGTH} lowercase letters, digits or hyphens, starting with a letter or digit`);
     return prefix;
 }
-export function tenantBasinName(tenantId, prefix = "") {
+/**
+ * The basin of one generation of a Tenant (Durable Streams §8.1). A Tenant reset moves the
+ * Tenant to a new generation, so a session id it frees starts again in an empty basin.
+ * `DurableStreams` methods take this key where they take a Tenant id; generation 0 is the
+ * Tenant id itself, so existing basins keep their names.
+ */
+export function basinOf(tenantId, generation) {
+    if (!Number.isInteger(generation) || generation < 0)
+        throw new Error("A basin generation is a non-negative integer");
+    return generation === 0 ? tenantId : `${tenantId}${GENERATION_SEPARATOR}${generation}`;
+}
+/** The Tenant id and generation of a basin key from `basinOf`. */
+export function parseBasin(basin) {
+    const at = basin.lastIndexOf(GENERATION_SEPARATOR);
+    const generation = at < 0 ? NaN : Number(basin.slice(at + 1));
+    return Number.isInteger(generation) && generation > 0
+        ? { tenantId: basin.slice(0, at), generation }
+        : { tenantId: basin, generation: 0 };
+}
+/** Never in a Tenant id (`TENANT_ID_PATTERN`). */
+const GENERATION_SEPARATOR = "#";
+/**
+ * The S2 basin of a Tenant, or of one of its generations (`basinOf`). Generation `g` > 0 of
+ * a canonical Tenant appends `-<g mod 1296 in base36>`, at most 48 characters with a
+ * 16-character prefix; other ids fold the generation into their hash.
+ */
+export function tenantBasinName(basin, prefix = "") {
     validateBasinPrefix(prefix);
+    const { tenantId, generation } = parseBasin(basin);
     if (!tenantId)
         throw new Error("tenantId is required");
     let name;
     if (TENANT_ID_PATTERN.test(tenantId)) {
         name = `${prefix}tn-${tenantId.slice(3)}`;
+        if (generation > 0)
+            name += `-${(generation % 1296).toString(36)}`;
     }
     else {
         const slug = tenantId
@@ -42,7 +71,10 @@ export function tenantBasinName(tenantId, prefix = "") {
             .replace(/[^a-z0-9]+/g, "-")
             .slice(0, 12)
             .replace(/^-+|-+$/g, "");
-        const hash = createHash("sha256").update(tenantId).digest("hex").slice(0, 16);
+        const hash = createHash("sha256")
+            .update(generation > 0 ? basin : tenantId)
+            .digest("hex")
+            .slice(0, 16);
         name = `${prefix}x-${slug ? `${slug}-` : ""}${hash}`;
     }
     if (!BASIN_NAME.test(name))

package/dist/streams/control.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Signals on a basin's `tenant/control` stream (Durable Streams §8). They are appended
+ * directly, never recorded: a lost signal costs latency, never correctness (the epoch fence
+ * stops a cancelled turn's effects; readers also check their sessions periodically).
+ */
+import { type DurableStreams } from "./types.js";
+/** Appends a `session.cancel` signal: the process running the session's advance aborts it. */
+export declare function signalCancel(streams: DurableStreams, basin: string, sessionId: string): Promise<void>;
+/**
+ * Appends a `sessions.reset` signal to the old generation's basin: every process with the
+ * Tenant open moves its readers to `generation` and ends the streams of deleted sessions.
+ */
+export declare function signalSessionsReset(streams: DurableStreams, basin: string, generation: number): Promise<void>;
+/**
+ * Appends a `subject.revoked` signal: every process with the Tenant open ends the subject's
+ * streams opened with a token older than `epoch`.
+ */
+export declare function signalSubjectRevoked(streams: DurableStreams, basin: string, subject: string, epoch: number): Promise<void>;

package/dist/streams/control.js

@@ -0,0 +1,29 @@
+/**
+ * Signals on a basin's `tenant/control` stream (Durable Streams §8). They are appended
+ * directly, never recorded: a lost signal costs latency, never correctness (the epoch fence
+ * stops a cancelled turn's effects; readers also check their sessions periodically).
+ */
+import { CONTROL_STREAM } from "./types.js";
+/** Appends a `session.cancel` signal: the process running the session's advance aborts it. */
+export async function signalCancel(streams, basin, sessionId) {
+    if (!sessionId)
+        throw new Error("sessionId is required");
+    const signal = { type: "session.cancel", sessionId };
+    await streams.append(basin, CONTROL_STREAM, [signal]);
+}
+/**
+ * Appends a `sessions.reset` signal to the old generation's basin: every process with the
+ * Tenant open moves its readers to `generation` and ends the streams of deleted sessions.
+ */
+export async function signalSessionsReset(streams, basin, generation) {
+    const signal = { type: "sessions.reset", generation };
+    await streams.append(basin, CONTROL_STREAM, [signal]);
+}
+/**
+ * Appends a `subject.revoked` signal: every process with the Tenant open ends the subject's
+ * streams opened with a token older than `epoch`.
+ */
+export async function signalSubjectRevoked(streams, basin, subject, epoch) {
+    const signal = { type: "subject.revoked", subject, epoch };
+    await streams.append(basin, CONTROL_STREAM, [signal]);
+}

package/dist/streams/memory.d.ts

@@ -14,7 +14,9 @@ export declare class MemoryStreams implements DurableStreams {
     read<T = unknown>(tenantId: string, stream: string, fromSeq: number, options?: ReadOptions): AsyncIterable<StreamRecord<T>>;
     tail(tenantId: string, stream: string): Promise<number>;
     ensureTenant(tenantId: string): Promise<void>;
-    deleteTenant(tenantId: string): Promise<void>;
+    deleteTenant(tenantId: string, options?: {
+        allGenerations?: boolean;
+    }): Promise<void>;
     deleteStream(tenantId: string, stream: string): Promise<void>;
     listStreams(tenantId: string, prefix: string): Promise<string[]>;
     close(): Promise<void>;

package/dist/streams/memory.js

@@ -1,3 +1,4 @@
+import { parseBasin } from "./basin.js";
 /**
  * In-memory `DurableStreams` for unit tests and a local development Host.
  * Not durable: history does not survive a restart. Keeps the seam's
@@ -71,14 +72,19 @@ export class MemoryStreams {
         if (!this.tenants.has(tenantId))
             this.tenants.set(tenantId, new Map());
     }
-    async deleteTenant(tenantId) {
-        const streams = this.tenants.get(tenantId);
-        this.tenants.delete(tenantId);
-        for (const stream of streams?.keys() ?? [])
-            this.notify(tenantId, stream);
-        for (const key of this.waiters.keys())
-            if (key.startsWith(`${tenantId}\u0000`))
-                this.notifyKey(key);
+    async deleteTenant(tenantId, options = {}) {
+        const basins = options.allGenerations
+            ? [...this.tenants.keys()].filter((key) => parseBasin(key).tenantId === tenantId)
+            : [tenantId];
+        for (const basin of basins) {
+            const streams = this.tenants.get(basin);
+            this.tenants.delete(basin);
+            for (const stream of streams?.keys() ?? [])
+                this.notify(basin, stream);
+            for (const key of this.waiters.keys())
+                if (key.startsWith(`${basin}\u0000`))
+                    this.notifyKey(key);
+        }
     }
     async deleteStream(tenantId, stream) {
         this.tenants.get(tenantId)?.delete(stream);

package/dist/streams/relay/core.d.ts

@@ -0,0 +1,35 @@
+import { type DurableStreams } from "../types.js";
+import type { ChangeSource, RecordReader } from "./types.js";
+export interface StreamRelayOptions {
+    source: ChangeSource;
+    record: RecordReader;
+    streams: DurableStreams;
+    /** Relay events: lag, errors, reconciliations. */
+    log?: (message: string, fields?: Record<string, unknown>) => void;
+    /** Records per append (S2 allows 1000). */
+    maxBatchRecords?: number;
+    /** Bytes per append (S2 allows 1 MiB). */
+    maxBatchBytes?: number;
+    /** Sessions reconciled at once. */
+    reconcileConcurrency?: number;
+}
+export interface StreamRelayStatus {
+    /** This process holds the source (the replication slot). */
+    active: boolean;
+    /** Committed transactions not yet fully in S2. */
+    pendingTxs: number;
+    /** Rows queued for S2. */
+    pendingRows: number;
+    /** The last position acknowledged to the source. */
+    confirmed: string | null;
+    reconciliations: number;
+    lastError: string | null;
+}
+export interface StreamRelay {
+    start(): void;
+    stop(): Promise<void>;
+    status(): StreamRelayStatus;
+    /** Resolves once nothing is pending (tests and shutdown). */
+    idle(): Promise<void>;
+}
+export declare function createStreamRelay(options: StreamRelayOptions): StreamRelay;