@nylorun/runtime 0.10.0-beta → 0.11.0-beta

package/dist/store/types.d.ts

@@ -0,0 +1,440 @@
+/**
+ * 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.
+ *
+ * ## 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.
+ * 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
+ *    writes for one session are serialized through it. Idempotency comparisons
+ *    (`canonical(...)`) run inside the same locked transaction. `event` and the
+ *    ownership methods take the lock themselves.
+ * 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`).
+ * 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).
+ * 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
+ *    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.
+ * 7. **Documents are values.** `get` and queries return fresh copies; mutating
+ *    them changes nothing until `put`.
+ * 8. **Ownership columns are store-managed.** `owner`, `epoch` and
+ *    `ownerExpiresAt` on a session are read with the session but written only
+ *    through `takeOwnership`, `renewOwnership` and `releaseOwnership`; `put`
+ *    ignores them. A session starts with no owner and epoch 0.
+ *
+ * ## Typed queries, no scans
+ *
+ * There is no generic table scan. Every read the Runtime needs is a typed
+ * method on `Tx` (`sessionsWithStatus`, `expiredClaims`, `pendingActions`,
+ * `effectsForTurn`, `linkedSessions`, `counts`, …) that an implementation can
+ * back with an index, and principals, executors, 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`).
+ */
+import type { Action, LiveEvent } 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";
+export declare const DOC_TABLES: readonly DocTable[];
+/** Session lifecycle (architecture §10.2). */
+export type SessionStatus = "idle" | "runnable" | "running" | "waiting" | "paused" | "uncertain" | "completed" | "failed" | "cancelled";
+/** Effect states (§10.3), plus the flow host's `queued` and `cancelled`. */
+export type EffectStatus = "pending" | "invoking" | "completed" | "uncertain" | "queued" | "cancelled";
+export type ActionStatus = Action["status"];
+export type ActionKind = Action["kind"];
+export type EffectKind = HostEffect["kind"];
+/**
+ * Ownership of a session by a Worker (§10.6). Read with the session; written
+ * only through the ownership methods on `Tx`.
+ */
+export interface SessionOwnership {
+    /** Worker id holding the lease, or null. */
+    owner: string | null;
+    /** Incremented by every successful `takeOwnership`. Starts at 0. */
+    epoch: number;
+    /** ISO time the owner's lease ends, or null without an owner. */
+    ownerExpiresAt: string | null;
+}
+/**
+ * The fields of a session document that the store indexes. The
+ * Runtime's own session type extends this; everything else in the body is
+ * opaque to the store.
+ */
+export interface SessionDoc {
+    id: string;
+    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`. */
+export type ActionDoc = Action;
+/** A workflow → agent session link, keyed by the linked agent session id. Indexed: `workflowSessionId`. */
+export interface LinkDoc {
+    workflowSessionId: string;
+    path: string;
+    effectId: string;
+    turnId: string;
+}
+/** A definition document. Indexed: `manifest.id`. */
+export interface DefinitionDoc {
+    manifest: {
+        id: string;
+    };
+}
+/** A sandbox record, keyed by sandbox key. */
+export interface SandboxDoc {
+    key: string;
+}
+/** A session as read from the store: its document plus the store-managed ownership fields. */
+export type StoredSession<T extends SessionDoc = SessionDoc> = T & SessionOwnership;
+/** A link row together with the agent session it names. */
+export interface LinkedSession<S extends SessionDoc = SessionDoc> {
+    agentSessionId: string;
+    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.
+     */
+    readonly incarnations: readonly (string | null)[];
+    /** True when the transaction called `signalWork()`. */
+    readonly workAvailable: boolean;
+}
+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 {
+    agentId: string;
+    tokenHash: string;
+    implementationVersion: string;
+    manifestHash?: string;
+    principalId?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PrincipalRow {
+    id: string;
+    role: "application" | (string & {});
+    tokenHash: string;
+    idempotencyKey: string | null;
+    createdAt: string;
+}
+export interface VaultRow {
+    id: string;
+    name: string;
+    ownerUserId: string;
+    /** JSON text, or null. */
+    metadataJson: string | null;
+    createdAt: string;
+    scope: "user" | "host";
+}
+/** Envelope-encrypted secret material. Always in columns, never inside a JSON body. */
+export interface SealedSecret {
+    kekId: string;
+    nonce: Uint8Array;
+    ciphertext: Uint8Array;
+    wrappedDek: Uint8Array;
+}
+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;
+}
+/** 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;
+    statuses?: readonly (EffectStatus | (string & {}))[];
+}
+export interface SessionActionFilter {
+    /** Only this turn. Absent means every turn. */
+    turnId?: string;
+    statuses?: readonly ActionStatus[];
+}
+/** Counts used by Tenant status, `summary` and `drain`. */
+export interface StoreCounts {
+    sessions: number;
+    /** Sessions `running` or `runnable`. */
+    runningSessions: number;
+    /** Actions `pending` or `claimed`. */
+    pendingActions: number;
+    /** Effects `uncertain`. */
+    uncertainEffects: number;
+    sandboxes: number;
+    definitions: number;
+}
+export type ResetScope = "sessions" | "sandboxes" | "all";
+/** Result of `takeOwnership`. */
+export type TakeOwnership = {
+    status: "owned";
+    /** The new epoch every later transaction of this advance must present. */
+    epoch: number;
+    /** True when a previous owner's lease had expired without release: run takeover (§10.5 step 2). */
+    takeover: boolean;
+    previous: SessionOwnership;
+} | {
+    status: "busy";
+    owner: string;
+    ownerExpiresAt: string;
+} | {
+    status: "missing";
+};
+/** One tenant's Session Store. */
+export interface SessionStore {
+    /** The Tenant this store serves; stamped on every event. */
+    readonly tenantId: string;
+    /**
+     * Runs `fn` in one READ COMMITTED transaction and commits when it resolves.
+     * Session-scoped writes call `lockSession` first. See the module invariants.
+     */
+    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.
+     */
+    onCommit(listener: CommitListener): () => void;
+    /** Reachability and schema check for Tenant status and `/ready`. Never throws. */
+    health(): Promise<StoreHealth>;
+    close(): Promise<void>;
+}
+export interface StoreHealth {
+    ok: boolean;
+    schemaVersion: number;
+    expectedSchemaVersion: number;
+}
+/** Options every implementation accepts. */
+export interface SessionStoreOptions {
+    tenantId: string;
+    /** Clock for event `createdAt`. Defaults to `() => new Date()`. */
+    now?: () => Date;
+    /** Receives listener and `afterCommit` failures, which never reject `tx`. */
+    onError?: (error: unknown) => void;
+}
+/** The transaction handle. Valid only inside its `tx` callback. */
+export interface Tx {
+    get<T = any>(table: DocTable, id: string): Promise<T | undefined>;
+    /** 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).
+     */
+    delete(table: DocTable, id: string): Promise<void>;
+    /**
+     * Locks the session row for the rest of the transaction and returns the
+     * session (with ownership fields), or undefined when it does not exist.
+     * 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):
+     * - 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
+     *   that starts from the parent and must touch children locks the children
+     *   first, or splits into one transaction per session;
+     * - unrelated sessions touched by one transaction are locked in ascending
+     *   id order (`lockSessions` in `store/postgres/locking.ts`), or split.
+     */
+    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.
+     */
+    event(sessionId: string, turnId: string | null, type: string, payload: unknown): Promise<LiveEvent>;
+    /** 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
+     * to `now + leaseMs`. A live lease (including this owner's own) is `busy`.
+     */
+    takeOwnership(sessionId: string, claim: {
+        owner: string;
+        now: Date;
+        leaseMs: number;
+    }): Promise<TakeOwnership>;
+    /** Extends the lease when `owner` and `epoch` still match. Returns false when ownership was lost. */
+    renewOwnership(sessionId: string, owner: string, epoch: number, until: Date): Promise<boolean>;
+    /** Clears the owner (keeping the epoch) when `owner` and `epoch` still match. */
+    releaseOwnership(sessionId: string, owner: string, epoch: number): Promise<boolean>;
+    /**
+     * Locks the session and throws `OwnershipLostError` (`ownership.lost`) when
+     * its epoch is not `epoch` or the session is gone. Every transaction of an
+     * advance calls this first; see `ownedTx` in `store/ownership.ts`.
+     */
+    assertEpoch<T extends SessionDoc = SessionDoc>(sessionId: string, epoch: number): Promise<StoredSession<T>>;
+    sessionsWithStatus<T extends SessionDoc = SessionDoc>(statuses: readonly (SessionStatus | (string & {}))[]): Promise<StoredSession<T>[]>;
+    /**
+     * Sessions `running` or `runnable` with no owner or an owner whose lease
+     * ended at or before `now`, oldest lease first. The sweep re-wakes these.
+     */
+    orphanedSessions<T extends SessionDoc = SessionDoc>(now: Date, limit: number): Promise<StoredSession<T>[]>;
+    listSessions<T extends SessionDoc = SessionDoc>(filter?: {
+        agentId?: string;
+    }): 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. */
+    pendingActions(agentId: string): Promise<ActionDoc[]>;
+    actionsForSession(sessionId: string, filter?: SessionActionFilter): Promise<ActionDoc[]>;
+    actionsWithStatus(statuses: readonly ActionStatus[], filter?: {
+        kinds?: readonly ActionKind[];
+    }): Promise<ActionDoc[]>;
+    /** `invoking` effects of one session; takeover turns them `uncertain`. */
+    invokingEffects<T extends EffectDoc = EffectDoc>(sessionId: string): Promise<T[]>;
+    effectsForSession<T extends EffectDoc = EffectDoc>(sessionId: string, filter?: SessionEffectFilter): Promise<T[]>;
+    effectsForTurn<T extends EffectDoc = EffectDoc>(sessionId: string, turnId: string, statuses?: readonly (EffectStatus | (string & {}))[]): Promise<T[]>;
+    effectsWithStatus<T extends EffectDoc = EffectDoc>(statuses: readonly (EffectStatus | (string & {}))[], filter?: {
+        kinds?: readonly EffectKind[];
+    }): Promise<T[]>;
+    /** 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[]>;
+    /**
+     * 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.
+     */
+    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>;
+    /** Rejects when the id or token hash already exists. */
+    insertPrincipal(row: PrincipalRow): Promise<void>;
+    principalByTokenHash(tokenHash: string): Promise<PrincipalRow | undefined>;
+    principalById(id: string): Promise<PrincipalRow | undefined>;
+    applicationTokenHashes(): Promise<string[]>;
+    /** Rejects on a duplicate id, or a second `host` vault. */
+    insertVault(row: VaultRow): Promise<void>;
+    getVault(id: string): Promise<VaultRow | undefined>;
+    /** User vaults of one owner, ordered by `createdAt`, then id. */
+    vaultsByOwner(ownerUserId: string): Promise<VaultRow[]>;
+    updateVaultMetadata(id: string, metadataJson: string | null): Promise<void>;
+    /** Deletes the vault and its credentials. */
+    deleteVault(id: string): Promise<void>;
+    /** Rejects on a duplicate id or an unknown vault. */
+    insertCredential(row: VaultCredentialRow): Promise<void>;
+    /** Looks a credential up by id alone (attachment checks); callers compare `vaultId`. */
+    getCredential(id: string): Promise<VaultCredentialRow | undefined>;
+    /** Credentials of one vault, ordered by `createdAt`, then id. */
+    credentialsForVault(vaultId: string, filter?: {
+        type?: VaultCredentialRow["type"];
+    }): Promise<VaultCredentialRow[]>;
+    /** Updates a credential of `vaultId`. Returns false when it does not exist. */
+    updateCredential(vaultId: string, id: string, patch: VaultCredentialPatch): Promise<boolean>;
+    /** Returns false when it does not exist. */
+    deleteCredential(vaultId: string, id: string): Promise<boolean>;
+    countCredentials(): Promise<number>;
+    insertVaultAudit(row: VaultAuditRow): Promise<void>;
+    /** Audit rows, oldest first. */
+    vaultAudit(filter?: {
+        vaultId?: string;
+        limit?: number;
+    }): Promise<VaultAuditRow[]>;
+    getVaultIdempotency(id: string): Promise<VaultIdempotencyRow | undefined>;
+    /** Rejects when the id exists. */
+    insertVaultIdempotency(row: VaultIdempotencyRow): Promise<void>;
+    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;
+     * - `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.
+     */
+    reset(scope: ResetScope): Promise<void>;
+}

package/dist/store/types.js

@@ -0,0 +1,10 @@
+export const DOC_TABLES = [
+    "definitions",
+    "sessions",
+    "commands",
+    "checkpoints",
+    "effects",
+    "actions",
+    "sandboxes",
+    "links",
+];

package/dist/streams/basin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * S2 basin names for Tenants (architecture §12.4).
+ *
+ * S2 basin names are 8–48 characters of lowercase letters, digits and hyphens,
+ * and cannot begin or end with a hyphen. Tenant ids are `tn_` plus a 26
+ * character lowercase ULID, and `_` is not allowed, so:
+ *
+ * - a canonical Tenant id `tn_<ulid>` maps to `<prefix>tn-<ulid>` (29
+ *   characters plus the prefix). The ULID contains no hyphen, so the mapping is
+ *   one-to-one and readable in S2 tooling;
+ * - any other id (tests, legacy ids) maps to `<prefix>x-<slug>-<hash>`, where
+ *   `slug` is the id lowercased with every run of other characters replaced by
+ *   `-` (at most 12 characters) and `hash` is the first 16 hex digits of the
+ *   id's SHA-256. The `x-` start keeps these apart from canonical names, and the
+ *   hash keeps ids that slug alike apart.
+ *
+ * `prefix` separates deployments or test runs that share one S2 account (basin
+ * names are global in S2). It must itself be lowercase letters, digits and
+ * hyphens, start with a letter or digit, and be at most 16 characters.
+ */
+export declare const MAX_BASIN_PREFIX_LENGTH = 16;
+export declare function validateBasinPrefix(prefix: string): string;
+export declare function tenantBasinName(tenantId: string, prefix?: string): string;

package/dist/streams/basin.js

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+import { TENANT_ID_PATTERN } from "@nylorun/core/compatibility";
+/**
+ * S2 basin names for Tenants (architecture §12.4).
+ *
+ * S2 basin names are 8–48 characters of lowercase letters, digits and hyphens,
+ * and cannot begin or end with a hyphen. Tenant ids are `tn_` plus a 26
+ * character lowercase ULID, and `_` is not allowed, so:
+ *
+ * - a canonical Tenant id `tn_<ulid>` maps to `<prefix>tn-<ulid>` (29
+ *   characters plus the prefix). The ULID contains no hyphen, so the mapping is
+ *   one-to-one and readable in S2 tooling;
+ * - any other id (tests, legacy ids) maps to `<prefix>x-<slug>-<hash>`, where
+ *   `slug` is the id lowercased with every run of other characters replaced by
+ *   `-` (at most 12 characters) and `hash` is the first 16 hex digits of the
+ *   id's SHA-256. The `x-` start keeps these apart from canonical names, and the
+ *   hash keeps ids that slug alike apart.
+ *
+ * `prefix` separates deployments or test runs that share one S2 account (basin
+ * names are global in S2). It must itself be lowercase letters, digits and
+ * hyphens, start with a letter or digit, and be at most 16 characters.
+ */
+export const MAX_BASIN_PREFIX_LENGTH = 16;
+const BASIN_NAME = /^[a-z0-9][a-z0-9-]{6,46}[a-z0-9]$/;
+const BASIN_PREFIX = /^(?:[a-z0-9][a-z0-9-]*)?$/;
+export function validateBasinPrefix(prefix) {
+    if (prefix.length > MAX_BASIN_PREFIX_LENGTH || !BASIN_PREFIX.test(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 = "") {
+    validateBasinPrefix(prefix);
+    if (!tenantId)
+        throw new Error("tenantId is required");
+    let name;
+    if (TENANT_ID_PATTERN.test(tenantId)) {
+        name = `${prefix}tn-${tenantId.slice(3)}`;
+    }
+    else {
+        const slug = tenantId
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .slice(0, 12)
+            .replace(/^-+|-+$/g, "");
+        const hash = createHash("sha256").update(tenantId).digest("hex").slice(0, 16);
+        name = `${prefix}x-${slug ? `${slug}-` : ""}${hash}`;
+    }
+    if (!BASIN_NAME.test(name))
+        throw new Error(`Invalid S2 basin name ${name}`);
+    return name;
+}

package/dist/streams/memory.d.ts

@@ -0,0 +1,25 @@
+import type { AppendOptions, AppendResult, DurableStreams, ReadOptions, StreamRecord } from "./types.js";
+/**
+ * In-memory `DurableStreams` for unit tests and a local development Host.
+ * Not durable: history does not survive a restart. Keeps the seam's
+ * sequence, conditional-append and resume semantics.
+ */
+export declare class MemoryStreams implements DurableStreams {
+    /** tenantId → stream → records. */
+    private readonly tenants;
+    /** `tenantId\0stream` → wake-ups for readers waiting at the tail. */
+    private readonly waiters;
+    private closed;
+    append(tenantId: string, stream: string, records: readonly unknown[], options?: AppendOptions): Promise<AppendResult>;
+    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>;
+    deleteStream(tenantId: string, stream: string): Promise<void>;
+    listStreams(tenantId: string, prefix: string): Promise<string[]>;
+    close(): Promise<void>;
+    private log;
+    private waitForAppend;
+    private notify;
+    private notifyKey;
+}

package/dist/streams/memory.js

@@ -0,0 +1,124 @@
+/**
+ * In-memory `DurableStreams` for unit tests and a local development Host.
+ * Not durable: history does not survive a restart. Keeps the seam's
+ * sequence, conditional-append and resume semantics.
+ */
+export class MemoryStreams {
+    /** tenantId → stream → records. */
+    tenants = new Map();
+    /** `tenantId\0stream` → wake-ups for readers waiting at the tail. */
+    waiters = new Map();
+    closed = false;
+    async append(tenantId, stream, records, options = {}) {
+        if (this.closed)
+            throw new Error("DurableStreams is closed");
+        const streams = this.tenants.get(tenantId);
+        if (!streams)
+            throw new Error(`Tenant ${tenantId} has no stream basin`);
+        if (records.length === 0)
+            throw new Error("append needs at least one record");
+        const bodies = records.map((record) => {
+            const body = JSON.stringify(record);
+            if (body === undefined)
+                throw new Error("Stream records must be JSON");
+            return body;
+        });
+        let log = streams.get(stream);
+        const tail = log?.length ?? 0;
+        if (options.matchSeq !== undefined && options.matchSeq !== tail)
+            return { status: "seq_mismatch", tail };
+        if (!log)
+            streams.set(stream, (log = []));
+        const timestamp = Date.now();
+        for (const body of bodies)
+            log.push({ seq: log.length, timestamp, body });
+        this.notify(tenantId, stream);
+        return { status: "ok", start: tail, end: log.length };
+    }
+    read(tenantId, stream, fromSeq, options = {}) {
+        if (!Number.isInteger(fromSeq) || fromSeq < 0)
+            throw new Error("fromSeq must be a non-negative integer");
+        const follow = options.follow ?? true;
+        const signal = options.signal;
+        const self = this;
+        return {
+            async *[Symbol.asyncIterator]() {
+                let next = fromSeq;
+                const end = follow ? Infinity : self.log(tenantId, stream)?.length ?? 0;
+                while (!signal?.aborted && !self.closed) {
+                    const log = self.log(tenantId, stream);
+                    while (log && next < log.length && next < end) {
+                        const record = log[next++];
+                        yield {
+                            seq: record.seq,
+                            timestamp: record.timestamp,
+                            body: JSON.parse(record.body),
+                        };
+                        if (signal?.aborted)
+                            return;
+                    }
+                    if (next >= end || !self.tenants.has(tenantId))
+                        return;
+                    await self.waitForAppend(tenantId, stream, signal);
+                }
+            },
+        };
+    }
+    async tail(tenantId, stream) {
+        return this.log(tenantId, stream)?.length ?? 0;
+    }
+    async ensureTenant(tenantId) {
+        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 deleteStream(tenantId, stream) {
+        this.tenants.get(tenantId)?.delete(stream);
+        this.notify(tenantId, stream);
+    }
+    async listStreams(tenantId, prefix) {
+        return [...(this.tenants.get(tenantId)?.keys() ?? [])]
+            .filter((stream) => stream.startsWith(prefix))
+            .sort();
+    }
+    async close() {
+        this.closed = true;
+        for (const key of [...this.waiters.keys()])
+            this.notifyKey(key);
+    }
+    log(tenantId, stream) {
+        return this.tenants.get(tenantId)?.get(stream);
+    }
+    waitForAppend(tenantId, stream, signal) {
+        const key = `${tenantId}\u0000${stream}`;
+        return new Promise((resolve) => {
+            let set = this.waiters.get(key);
+            if (!set)
+                this.waiters.set(key, (set = new Set()));
+            const done = () => {
+                set.delete(done);
+                if (set.size === 0 && this.waiters.get(key) === set)
+                    this.waiters.delete(key);
+                signal?.removeEventListener("abort", done);
+                resolve();
+            };
+            set.add(done);
+            signal?.addEventListener("abort", done, { once: true });
+        });
+    }
+    notify(tenantId, stream) {
+        this.notifyKey(`${tenantId}\u0000${stream}`);
+    }
+    notifyKey(key) {
+        for (const wake of [...(this.waiters.get(key) ?? [])])
+            wake();
+    }
+}