@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/store/types.d.ts

@@ -2,16 +2,16 @@
  * The Session Store seam (architecture §12.2).
  *
  * The Session Store records what happened. It is async, transactional and
- * tenant-scoped: one `SessionStore` per Tenant. Postgres is the supported
- * implementation; `store/memory.ts` is the in-memory fake for unit tests.
+ * tenant-scoped: one `SessionStore` per Tenant. Postgres is the
+ * implementation (`store/postgres/store.ts`); tests run on it too.
  *
  * ## Invariants every implementation keeps
  *
  * 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 `record/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,17 +45,21 @@
  * ## 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";
+import type { ModelBudgetRow, ModelUsageRow, PrincipalRow, ToolCrossingRow, PublishableKeyRow, SigningKeyRow, SubjectUsageRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow } from "./postgres/schema.js";
 /** Tables holding JSON documents keyed by `id`. */
-export type DocTable = "definitions" | "sessions" | "commands" | "checkpoints" | "effects" | "actions" | "sandboxes" | "links";
+export type DocTable = "definitions" | "sessions" | "commands" | "effects" | "actions" | "sandboxes" | "links";
 export declare const DOC_TABLES: readonly DocTable[];
 /** Session lifecycle (architecture §10.2). */
 export type SessionStatus = "idle" | "runnable" | "running" | "waiting" | "paused" | "uncertain" | "completed" | "failed" | "cancelled";
@@ -87,18 +90,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,95 +123,93 @@ 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;
 }
-export interface PrincipalRow {
-    id: string;
-    role: "application" | (string & {});
-    tokenHash: string;
-    idempotencyKey: string | null;
-    createdAt: 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;
 }
-export interface VaultRow {
-    id: string;
-    name: string;
-    ownerUserId: string;
-    /** JSON text, or null. */
-    metadataJson: string | null;
-    createdAt: string;
-    scope: "user" | "host";
+/** A delivery failed: not reached, refused, or lost. */
+ | {
+    kind: "failure";
+    at: string;
+    code: string;
+    message: string;
 }
-/** Envelope-encrypted secret material. Always in columns, never inside a JSON body. */
-export interface SealedSecret {
-    kekId: string;
-    nonce: Uint8Array;
-    ciphertext: Uint8Array;
-    wrappedDek: Uint8Array;
+/** A ping was answered with what the endpoint serves. */
+ | {
+    kind: "served";
+    implementationVersion: string;
+    manifestHash?: string;
+};
+/**
+ * The rows of the typed tables, inferred from the tables Drizzle defines
+ * (`store/postgres/schema.ts`): a principal, a vault and its credentials (secrets sealed in
+ * `bytea` columns, never inside a JSON body), the vault's audit and idempotency records, the
+ * Tenant's signing keys, a subject's turn bucket, a publishable key, a model call in the usage
+ * ledger and a model budget.
+ */
+export type { ModelBudgetRow, ModelUsageRow, ToolCrossingRow, PrincipalRow, PublishableKeyRow, SigningKeyRow, SubjectUsageRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow, };
+/** Which rows of the usage ledger a total covers. */
+export interface ModelUsageQuery {
+    scope: "tenant" | "agent" | "turn";
+    /** The agent or turn id; ignored for `tenant`. */
+    id?: string;
+    /** Only rows created at or after this ISO time. */
+    since?: string;
 }
-export interface VaultCredentialRow extends SealedSecret {
-    id: string;
-    vaultId: string;
-    name: string;
-    type: "bearer" | "oauth" | "model";
-    /** JSON text of the non-secret binding (url, or provider and model). */
-    bindingJson: string;
-    expiresAt: string | null;
-    createdAt: string;
-    rotatedAt: string | null;
+export interface ModelUsageTotals {
+    calls: number;
+    tokens: number;
+    costUsd: number;
 }
 /** Fields `updateCredential` may change. */
 export type VaultCredentialPatch = Partial<Omit<VaultCredentialRow, "id" | "vaultId" | "createdAt">>;
-export interface VaultAuditRow {
-    id: string;
-    at: string;
-    actor: string;
-    action: string;
-    vaultId: string | null;
-    credentialId: string | null;
-    sessionId: string | null;
-    target: string | null;
-    outcome: string;
-}
-export interface VaultIdempotencyRow {
-    id: string;
-    bodyHash: string;
-    /** JSON text of the original response. */
-    response: string;
-}
 export interface SessionEffectFilter {
     /** Only this turn. Absent means every turn. */
     turnId?: string;
@@ -229,7 +225,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 +259,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 +277,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 +288,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>;
     /**
@@ -301,7 +299,7 @@ export interface Tx {
      * Locking twice in one transaction is a no-op.
      *
      * Lock order, so concurrent transactions cannot deadlock (Postgres takes row
-     * locks in statement order; the in-memory fake serializes whole transactions):
+     * locks in statement order):
      * - a linked agent (child) session is locked before its workflow (parent)
      *   session, never after it. `t.event` on a session takes its lock, so an
      *   event on a child after the parent is locked breaks the rule too. Work
@@ -313,14 +311,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 +353,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 +375,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 +423,71 @@ 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>;
+    /** Appends a row, setting `duplicate` when one with the same `effectKey` exists; returns it. */
+    recordModelUsage(row: Omit<ModelUsageRow, "duplicate">): Promise<ModelUsageRow>;
+    modelUsageTotals(query: ModelUsageQuery): Promise<ModelUsageTotals>;
+    /** Every budget, ordered by scope, then scope id. */
+    listModelBudgets(): Promise<ModelBudgetRow[]>;
+    /** Replaces every budget with `rows`. */
+    putModelBudgets(rows: readonly ModelBudgetRow[]): Promise<void>;
+    toolCrossing(key: string): Promise<ToolCrossingRow | undefined>;
+    /** Inserts the running call's row; false when a row with `key` already exists. */
+    startToolCrossing(row: Pick<ToolCrossingRow, "key" | "hash" | "startedAt">): Promise<boolean>;
+    /** Records the call's answer. */
+    settleToolCrossing(key: string, answer: unknown, settledAt: string): Promise<void>;
+    /** Deletes rows that settled before `before`; returns how many. */
+    pruneToolCrossings(before: string): Promise<number>;
     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, 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, user vaults with their credentials,
+     *   the model usage ledger and the model budgets. The host vault, principals, signing keys, subject epochs,
+     *   publishable keys, settings, audit and vault idempotency rows stay.
      */
     reset(scope: ResetScope): Promise<void>;
 }

package/dist/store/types.js

@@ -2,7 +2,6 @@ export const DOC_TABLES = [
     "definitions",
     "sessions",
     "commands",
-    "checkpoints",
     "effects",
     "actions",
     "sandboxes",

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, turnId?: 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,33 @@
+/**
+ * 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, turnId) {
+    if (!sessionId)
+        throw new Error("sessionId is required");
+    const signal = {
+        type: "session.cancel",
+        sessionId,
+        ...(turnId ? { turnId } : {}),
+    };
+    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>;