@nylorun/runtime 0.14.0-beta → 0.15.1-beta

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # Changelog
 
+## 0.15.1-beta
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin harness to the tested release.
+- Updated dependencies [4b9906f]
+- Updated dependencies
+  - @nylorun/core@0.11.0-beta
+  - @nylorun/harness@0.21.2-beta
+
+## 0.15.0-beta
+
+### Major Changes
+
+- 5ca1923: **One Tenant per installation: a database per Tenant, protocol 5.** A Runtime serves exactly one Tenant, the one its Postgres database holds. Two Tenants are two installations.
+
+  - **Breaking: fresh start.** The Tenant's state is in the fixed schema `nylorun` of its own database and its record in `nylorun_streams`, keyed by session (no `tenant_id`). A database written by an earlier Runtime (`tenant_<id>` schemas, or a record keyed by Tenant) is refused: the Host stays up but not ready, and `/v1/admin/status` names the cause `database-layout-old`. Point the Runtime at a new database (with the local stack, a new stack); the old one is never changed.
+  - **The Host creates its Tenant** on first start, in the migration transaction: `NYLORUN_TENANT_ID` (default a new id), `NYLORUN_TENANT_NAME` (default `default`), the Studio principal and the derived principals of `NYLORUN_DERIVED_PRINCIPALS` (comma-separated, default `project`), whose keys the admin key derives (`deriveTenantKey`). Later starts open the same Tenant and add derived principals configured since.
+  - **Breaking: no Tenant catalog.** `/v1/admin/tenants` and `/v1/admin/tenants/{tenantId}` are gone (404). `AdminStatus.tenants[]` is replaced by `AdminStatus.tenant` (`id`, `name`, `state: open | unavailable`, `envelope`, and `cause` when it could not be opened). `CreateTenantRequestSchema`, `AdminTenantSchema`, `AdminTenantStatusSchema`, `AdminTenantListSchema` and `QuarantineSchema` leave `@nylorun/core`; `HostTenantSchema` and `TenantCauseSchema` replace them. `@nylorun/admin`'s `listTenants`, `getTenant`, `deleteTenant` and `createTenant` are removed (see below).
+  - **Readiness instead of quarantine.** A Tenant that cannot be opened (`schema-too-new`, `kek-missing`, `migration-failed`, `envelope-invalid`, `database-layout-old`, …) fails `/ready` (check `tenant`, which replaces `discovery`) and is reported with its repair in `/v1/admin/status` and the log; every Tenant request gets the opaque 404. A failure outside it (Postgres unreachable) is retried.
+  - **Protocol 5.** `PROTOCOL_VERSION = 5`; the Host serves protocols 4 and 5 for one release. Clients no longer require `runtime-tenants`; the Host still advertises it. No request needs `Nylorun-Tenant`: a request without it reaches the Host's Tenant, and one naming another Tenant (or a malformed one), or a publishable key of another Tenant, gets the opaque 404. The OpenAPI documents drop the header parameter and the Admin Tenant routes.
+  - **Paths.** The Tenant directory is `<Host root>/tenant/` (was `tenants/<id>/`); `trash/` and the SQLite move to it are gone. The gates service serves its database's Tenant, and its `Nylorun-Tenant` header is optional (when sent, it must name that Tenant).
+  - **Breaking: `startEphemeralRuntime` needs a database; the in-memory Session Store is removed.** `StartEphemeralRuntimeOptions.database` is required: a Postgres URL, for which the Runtime opens a pool and ends it on `close()`, or a pool the caller ends. It creates its Tenant in that database through the same bootstrap as a Host, or serves the Tenant the database already holds; the data stays after `close()`, so give each test Tenant a database of its own. Durable Streams and scheduling stay in process. See `MIGRATION.md`.
+
+### Minor Changes
+
+- ee9e471: **The vault key leaves the runtime container (F4.2).** A new `keys` service, run in the gateway's process (`--service gates,keys`), is the only process that reads the vault key. Vault writes that touch a secret (creating and rotating a credential, setting and selecting the host model) and all token signing (subject tokens, delivery tokens, signing-key rotation) run there. A Runtime with `NYLORUN_KEYS_URL`, which defaults to `NYLORUN_GATES_URL`, never reads, creates or holds the key. The Tenant API answers as before, with the same statuses, codes and details.
+
+  - The vault key file moves to `<Host root>/keys/vault-kek`. A gateway that runs keys is not ready until the file is there, and it never creates one.
+  - The anonymous `GET /v1/access/jwks` reads the public keys, and asks the keys service only when the current or standby key is missing.
+  - While the keys service is down, vault writes and token minting answer `503 keys_unavailable`.
+
+- fed780d: **Hard caps on model spend.** A Tenant can cap what its model calls use, per turn, per agent per UTC day or month, or for the whole Tenant per day or month, in USD, tokens or both. Before each call the model gate checks the scope's recorded spend, plus its calls in flight, against the cap. Once a cap is reached the call fails with the new `budget_exhausted` code, which is never retried, and the turn fails with `model.budget_exhausted`. A runaway loop stops there, at most one call over its cap.
+
+  - `PUT /v1/tenant/budgets` replaces the budgets and `GET /v1/tenant/budgets` reads them. Both need the application key or `tenant:settings`.
+  - `@nylorun/core` adds `budget_exhausted` to `ModelFailureCode` and `MODEL_FAILURE_CODES`, plus `ModelBudgetSchema`, `PutModelBudgetsRequestSchema` and `ModelBudgetsSchema`. Code that switches over failure codes exhaustively needs the new case.
+  - Custom endpoints are priced at $0, so only a token limit stops them.
+  - Budgets survive a `sessions` reset. A reset of scope `all` clears them.
+
+- 744208d: **A runtime that dies or restarts mid-call no longer strands the session (P1.2).** The loop sends each model call with its effect id as the `Idempotency-Key`, and the gate runs a keyed call under its own control: if the caller disconnects, the call finishes and its outcome is kept for 30 minutes. The runtime that takes the session over re-sends the journaled call and joins it, or collects its outcome, so the turn completes with one provider call instead of becoming `uncertain`. A shutdown no longer marks the call `uncertain` either.
+
+  - A re-send with the same key and a different request answers `409 gate_conflict`.
+  - A user cancel sends `POST /nylorun/v1/model-calls/{key}/cancel`, which stops the provider request, and marks the turn's model call `uncertain`.
+  - Outcomes live in the gateway's memory: a gateway restart forgets them. A Runtime that calls models in its own process (embedding, tests) keeps the previous behaviour.
+
+- 744208d: **Model calls leave the loop through the Model Gate (P1.1).** Every vault-backed model call of the loop goes through one `ModelGate` (`runtime/src/gates/`). `--service gates` serves it over HTTP: one listener (`NYLORUN_GATES_LISTEN_HOST`, `NYLORUN_GATES_LISTEN_PORT`, default port 4100, `NYLORUN_GATES_ALLOWED_HOSTS`) answering `POST /nylorun/v1/model-calls` to callers presenting `NYLORUN_GATES_TOKEN`, with one JSON body once the call has finished. The gate reads the Tenant's host model from its vault and calls the provider with the same adapter, retries, idle watchdog, failure classification and redaction as before.
+
+  - **Breaking:** in a container, a Runtime that runs `loop` refuses to start without `NYLORUN_GATES_URL` and `NYLORUN_GATES_TOKEN`; it then never reads a model credential. Outside a container (embedding, `startEphemeralRuntime`), a loop without `NYLORUN_GATES_URL` runs the gate in its own process, as before. See `DEPLOYMENT.md`.
+  - **Breaking:** the `gateway` model kind is removed from `TenantConfig.model` and `StartEphemeralRuntimeOptions.model`. Nothing set it, and it read the Tenant's model credential inside the loop. The exported `gatewayModel` provider is unchanged.
+  - The gate needs only `NYLORUN_DATABASE_URL` and the Host's Tenant directory (`tenant/`), which it never writes: it runs no migration and opens no Tenant runtime. It refuses a Tenant whose schema is at another version, so the gateway and the runtime must run the same build. gates never shares a process with core or loop: `--service core,gates` is refused.
+  - The client speaks `node:http` with a 630 s idle timeout, so calls longer than five minutes are not cut off. It never retries; the gate does. A failure of the hop is a failure outcome: an unreachable gate, a connection lost mid-call, a timeout or a 5xx is `transient` and retryable; a refused token is `auth`, naming `NYLORUN_GATES_TOKEN`.
+  - The `host_stack_config` startup log names the gate (`modelGate`).
+
+- fed780d: **Every model call is recorded in the Tenant's usage ledger.** The model gate writes one row per call that answers: the session, turn and agent, the provider and model, the tokens (input, output, cached, cache write, reasoning) and pi-ai's price in USD. Custom endpoints count as $0. A call the gateway ran twice after a restart is recorded twice and flagged as a duplicate, since the provider billed both.
+
+  - `GET /v1/tenant/usage?scope=tenant|agent|turn&id=&period=day|month|total` totals the ledger. It needs the application key or `tenant:settings`, like the other Tenant settings.
+  - `@nylorun/core/contracts` adds `ModelUsageScopeSchema`, `ModelUsageQuerySchema` and `ModelUsageTotalsSchema`.
+  - The ledger survives a `sessions` reset. A reset of scope `all` clears it.
+  - The gateway and the runtime must run the same build, as before.
+
+- 7f4c3f1: **One history: a session's transcript is folded from its record.** The own loop's model-facing transcript is no longer stored on the session row, where up to three copies of it lived (`state`, `turnStartState` and the checkpoint). After each segment that keeps its state, the Runtime records the change as an internal `transcript.updated` event: the new entries, or a snapshot after compaction. Each segment folds the transcript back from the record, and a cancelled or failed turn's entries are undone, as before.
+
+  - **Internal events.** `transcript.updated` is in the event catalog with `visibility: "internal"`. SSE, history, AG-UI and A2A never serve it. Served events can therefore skip the seq numbers internal events hold; cursors resume as before. `TranscriptUpdatedPayloadSchema` is exported from `@nylorun/core/contracts`, and catalog entries may declare `visibility`.
+  - **No checkpoints table.** Every settle used to write a copy of the session's checkpoint to a `checkpoints` table that nothing read; it is gone. The checkpoint a session resumes from stays on the session row.
+  - **Storage.** A long session's row no longer grows with its transcript (a 10-turn, 300-step session on a 16k window: under 16 KB instead of up to 196 KB).
+
+- 7bd38d6: **`--service` names what a Runtime process runs.** The image now starts as `--service core,loop` (the default without a flag): `core` serves the Tenant and Admin APIs and runs the stream relay, and `loop` runs the agent loop and serves the Worker endpoint Restate calls. A container may run several services, which is how the local stack packs them.
+
+  - `--role api|worker|all` still works for one release as a deprecated alias of `--service core`, `loop` and `core,loop`, and logs `deprecated_flag` at startup.
+  - `--service all` is refused: name the services, e.g. `--service core,loop`.
+  - The `host_stack_config` startup log names `services` instead of `role`.
+
+- 5ca1923: **Drizzle defines the Session Store's schema, migrations and queries.** An internal storage change: the tables, columns and indexes of a Tenant database are the same as before.
+
+  - The tables are defined in `src/store/postgres/schema.ts`; drizzle-kit generates the migrations from it, and they ship in the package (`dist/store/postgres/drizzle/`). At startup the Host applies the missing ones in one transaction under an advisory lock and records them in `nylorun.__drizzle_migrations` (Drizzle's journal format). A database whose journal holds a migration this Runtime does not ship still fails readiness with `schema-too-new`. The schema version reported by `/ready` and Admin status is the number of applied migrations.
+  - Statements are prepared again (one Tenant per database makes every statement the same for the whole pool).
+  - `drizzle-orm` is a new dependency.
+
+- 7bd38d6: **The local stack runs a gateway container: model calls leave the Runtime.** `nylorun up` now runs the Runtime image twice, the combined packing: `runtime` (`--service core,loop`: the APIs and the agent loop) and `gateway` (`--service gates,keys`: the Model Gate, the Tool Gate and the keys service). Every model call, remote MCP call and Action delivery of the loop crosses the gateway, which alone reads the Tenant's credentials and the vault key. A new stack starts with the gateway.
+
+  - **Breaking for hand-written Compose files:** in a container, a Runtime that runs `loop` refuses to start without `NYLORUN_GATES_URL` and `NYLORUN_GATES_TOKEN`. Run the image a second time with `--service gates,keys` (see `DEPLOYMENT.md`). The image's default command is now `--service core,loop`.
+  - The gateway has no published port, mounts only the Host's Tenant directory (`tenant/`) and `keys/`, both read-only, and reaches model servers on this machine at `host.docker.internal`. `docker/.env` holds `NYLORUN_GATES_TOKEN`, generated once and kept across starts.
+  - `nylorun status` shows a Gateway line, `nylorun doctor` fails when the gateway is unhealthy and names `nylorun logs gateway`, and `nylorun logs gateway` is accepted.
+  - An image set with `NYLORUN_RUNTIME_IMAGE` must be this release or newer: older Runtimes don't know `--service`.
+
+- 31cfec0: **Action deliveries leave through the gateway (F4.1).** With the gates service, every delivery and endpoint ping is POSTed by the gateway (`POST /nylorun/v1/deliveries`) under the gateway's own `NYLORUN_ENDPOINT_*` policy. The delivery state machine is unchanged. A gateway that cannot be reached counts as a delivery that was not sent, so it is retried, and its failure code is `gateway.unreachable`.
+
+  - `nylorun`: the `gateway` container now sets `NYLORUN_ENDPOINT_LOOPBACK=docker-host`, so Action endpoints on this machine stay reachable.
+  - A process that runs only `core` also reads `NYLORUN_GATES_URL`, for endpoint pings.
+
+- 31cfec0: **Remote MCP servers run behind the Tool Gate (F4.1).** With the gates service (the local stack's `gateway` container), the gateway holds each session's connection to a `streamable-http` or `sse` MCP server, authorizes it from the session's attached vaults (OAuth refresh included), and runs `tools/list` and `tools/call`. The runtime names the server and never sees its credential. Stdio MCP servers still run beside the loop.
+
+  - New internal routes on the gates service: `POST /nylorun/v1/mcp/connect`, `/mcp/list`, `/mcp/close` and `/tool-calls`.
+  - The loop now passes its abort signal to every MCP call, in and out of process.
+
+- 31cfec0: **Remote MCP calls outlive the runtime that sent them, and never run twice (F4.1).** The loop sends each remote MCP call with its effect id as the `Idempotency-Key`. The gateway keeps a keyed call running after its caller goes away, and a restarted or new owner re-sends the journaled call and joins it, so the turn completes with one call to the server and nothing `uncertain`.
+
+  - The gateway records each keyed call before it reaches the server and stores the answer after. After a gateway restart, a call that was in flight answers `uncertain` and is never run again. Rows are deleted a day after they settle.
+  - A user cancel stops the call at the gateway (`POST /nylorun/v1/tool-calls/{key}/cancel`).
+
+### Patch Changes
+
+- 1a38e0e: **A late cancel signal no longer stops the next turn.** The `session.cancel` signal on `tenant/control` now names the turn it cancelled, and a Worker aborts only an advance of that turn. Before, a signal delivered after S2 came back (an append the SDK retried, or a control reader catching up) aborted whatever advance the session was running, which could be a turn started after the cancel.
+- Pin core to the tested release.
+- Pin harness to the tested release.
+- Updated dependencies [fed780d]
+- Updated dependencies [fed780d]
+- Updated dependencies [7f4c3f1]
+- Updated dependencies [5ca1923]
+- Updated dependencies [5ca1923]
+- Updated dependencies
+  - @nylorun/core@0.10.0-beta
+  - @nylorun/harness@0.21.1-beta
+
 ## 0.14.0-beta
 
 ### Major Changes

package/README.md

@@ -3,7 +3,7 @@
 The independent OSS **Runtime Host** consumes `@nylorun/harness/run` and
 `@nylorun/core/contracts`. Cloud installs published `@nylorun/harness` from npm
 and does not import this package. Client authoring and sessions belong to
-`@nylorun/agents`; Tenant lifecycle management belongs to `@nylorun/admin`.
+`@nylorun/agents`; the Host's status and derived keys belong to `@nylorun/admin`.
 Vocabulary: [src/CONTEXT.md](./src/CONTEXT.md).
 
 Requires Node 24+. Build from the repository root:
@@ -18,21 +18,39 @@ npm run build --workspace @nylorun/runtime
 ## Running the Runtime
 
 The Runtime runs as the `ghcr.io/nylorun/runtime` image, next to Postgres,
-Restate and S2: `nylorun start` runs that stack on a developer machine. The
+Restate and S2: `nylorun start` runs them, as a local Tenant, on a developer machine. The
 package is a library with no bin; its Host entry is `@nylorun/runtime/server`
 (`dist/host/main.js`), which requires `NYLORUN_DATABASE_URL`. For tests and
 ephemeral embeds, use `startEphemeralRuntime()` from `@nylorun/runtime/core`.
 See [MIGRATION.md](../MIGRATION.md).
 
-No Tenant state lives only in the Runtime process. Each Tenant's data is the
-Postgres schema `tenant_<id>` (the Session Store); Restate runs one advance of a session at a
-time and holds the Tenant's sweep timer (Durable Session Execution); every
-session's events are relayed from the schema's outbox to its own S2 stream,
-which history and SSE read (Durable Streams). An API node serves the Tenant API,
-Admin API and SSE, and a Worker runs advances; `--role api|worker|all` picks
-them, and the local stack runs one process with `all`.
-
-The container is configured by its environment, which the stack's Compose file
+A Runtime serves one **Tenant**: an installation is one Runtime with its own
+Postgres database, Restate and S2 basin, and two Tenants are two installations. No
+Tenant state lives only in the Runtime process. The Tenant's data is its Postgres
+database, in the fixed schemas `nylorun` (its state: the Session Store) and
+`nylorun_streams` (the record of its session events). Drizzle defines the tables
+(`src/store/postgres/schema.ts`) and generates the migrations, which ship in the package
+(`dist/store/postgres/drizzle/`). At startup the Host applies the missing ones in one
+transaction under an advisory lock, records them in `nylorun.__drizzle_migrations`, and
+refuses a database holding a migration it does not ship (`schema-too-new`); then, on
+first start, it creates the Tenant there: its id (`NYLORUN_TENANT_ID`, default a
+new one), its name (`NYLORUN_TENANT_NAME`, default `default`), its Studio principal and
+the derived principals (`NYLORUN_DERIVED_PRINCIPALS`, default `project`) whose keys the
+admin key derives. A database written by a Runtime that kept several Tenants in one
+database (`tenant_<id>` schemas), or by a pre-release build of one Tenant per database
+(`schema_version` tables), is refused: this release starts fresh on a new database. Restate runs one advance of a session at a time and holds the Tenant's sweep
+timer (Durable Session Execution); every session's events are relayed from the record to
+its own S2 stream, which history and SSE read (Durable Streams). One image runs every **service**,
+and `--service` picks what a process runs: `core` serves the Tenant API, Admin
+API and SSE and runs the stream relay, `loop` runs advances (the Worker), and
+`gates` is the Model Gate, the only process that reads a model credential and
+calls providers. `core` and `loop` may share a process; `gates` never joins
+them. A local Tenant packs `core,loop` into the `runtime` container and
+`gates` into the `gateway` container (the combined packing). `--role
+api|worker|all` is the deprecated name of `--service core`, `loop` and
+`core,loop`.
+
+The container is configured by its environment, which a local Tenant's Compose file
 sets: `NYLORUN_DATABASE_URL` (required), `NYLORUN_RESTATE_INGRESS_URL`,
 `NYLORUN_RESTATE_ADMIN_URL`, `NYLORUN_WORKER_URL` and
 `NYLORUN_RESTATE_IDENTITY_KEY` (Restate), `NYLORUN_S2_ENDPOINT` and
@@ -40,17 +58,23 @@ sets: `NYLORUN_DATABASE_URL` (required), `NYLORUN_RESTATE_INGRESS_URL`,
 `NYLORUN_LISTEN_PORT`, `NYLORUN_ALLOWED_HOSTS` and `NYLORUN_PUBLIC_URL`, plus
 `NYLORUN_BROWSER_ACCESS` (`on` or `off`) and the operator listener
 (`NYLORUN_ADMIN_LISTEN_PORT`, `NYLORUN_ADMIN_LISTEN_HOST`,
-`NYLORUN_ADMIN_ALLOWED_HOSTS`).
-
-With an operator listener (the stack's default: container port 4001), the Host
+`NYLORUN_ADMIN_ALLOWED_HOSTS`). A process that runs `loop` sends its model
+calls to the gate at `NYLORUN_GATES_URL` with `NYLORUN_GATES_TOKEN`; in a
+container it refuses to start without them. A `gates` process needs only
+`NYLORUN_DATABASE_URL`, `NYLORUN_GATES_TOKEN`, its listener
+(`NYLORUN_GATES_LISTEN_HOST`, `NYLORUN_GATES_LISTEN_PORT`, default 4100, and
+`NYLORUN_GATES_ALLOWED_HOSTS`) and the Host's `tenant/` directory, which it
+never writes; it serves the database's one Tenant. `NYLORUN_PACKING` (`combined` or `split`) is logged at startup.
+
+With an operator listener (a local Tenant's default: container port 4001), the Host
 serves two ports. The public one serves the Tenant API, to browsers too when
 browser access is on, and answers admin routes with the opaque `404`. The
 operator one serves the Admin API, Host shutdown and the Tenant API, never to
 browsers; keep it on loopback or a private network and never proxy it. Outside
 a container, `adminPort` in `host.json` does the same on loopback.
 
-The Host root is `NYLORUN_HOME` or `~/.nylorun` (bind-mounted at `/nylorun` in
-the stack). What stays on the Host is under `tenants/<tenantId>/`.
+The Host root is `NYLORUN_HOME` or `~/.nylorun` (for a local Tenant,
+`~/.nylorun/tenants/<name>/`, bind-mounted at `/nylorun` in its containers). What stays on the Host is under `tenant/`.
 
 ## Layout
 
@@ -58,9 +82,8 @@ the stack). What stays on the Host is under `tenants/<tenantId>/`.
 <host root>/
   host.json                 # format 1: hostId, host, port, adminPort?, runtimeVersion, …
   host-credentials.json     # adminKey (0600)
-  stack/                    # compose.yaml, .env (0600), Restate identity key
-  tenants/<tenantId>/       # vault-kek, plugin-data, logs, home, tmp, sandboxes
-  trash/                    # SQLite Tenants from before the Postgres switch
+  docker/                   # compose.yaml, .env (0600), Restate identity key
+  tenant/                   # vault-kek, plugin-data, logs, home, tmp, sandboxes
 ```
 
 ## HTTP surface
@@ -68,25 +91,25 @@ the stack). What stays on the Host is under `tenants/<tenantId>/`.
 | Route | Auth | Notes |
 | --- | --- | --- |
 | `GET /health` | none | `service: "nylorun-runtime"`, `hostId`, protocol `{min,max,features}`, pid |
-| `GET /ready` | none | Listener up, Tenants discovered, and Postgres, Restate and S2 answer (`checks`) |
+| `GET /ready` | none | Listener up, the Tenant open, and Postgres, Restate and S2 answer (`checks`) |
 | `GET /openapi.json` | none | The Tenant API's OpenAPI 3.2 document (below); refuses an `Origin` |
-| `GET /v1/admin/status` | admin key | `AdminStatusSchema`; alias `GET /v1/admin/host`. On the operator listener when there is one |
-| `/v1/admin/tenants*` | admin key | Create / list / get / delete Tenants |
+| `GET /v1/admin/status` | admin key | `AdminStatusSchema`: the Host, its protocol and its Tenant (`tenant`: id, name, `open` or `unavailable`, and the cause when it could not be opened); alias `GET /v1/admin/host`. On the operator listener when there is one |
 | `POST /v1/admin/host/shutdown` | admin key | Host-private; not in `@nylorun/admin` |
 | `GET /v1/admin/openapi.json` | admin key | The Admin API's OpenAPI 3.2 document |
-| `/v1/*` Tenant routes | application key, subject token or delivery token | Require `Nylorun-Tenant` (or `Nylorun-Key`) + `Nylorun-Protocol` |
+| `/v1/*` Tenant routes | application key, subject token or delivery token | Require `Nylorun-Protocol`; nothing names the Tenant |
 
 Every route checks `Host` first (`421 host_rejected`) and rejects non-JSON bodies
 with `415 unsupported_media_type`. An `Origin` is `403 origin_rejected` on
 `/health`, `/ready`, admin routes, and everywhere when browser access is off.
-With browser access on (feature `browser-access`: the stack's default, or
+With browser access on (feature `browser-access`: a local Tenant's default, or
 `browserAccess` in `host.json`), the Host answers preflights for browser routes
 from the route alone, and the Tenant admits an `Origin` only with a publishable
 key (`Nylorun-Key`) that lists it, adding CORS headers only then; Tenant keys
-and delivery tokens are refused from browsers before they are looked up. A
-publishable key also names the Tenant, so `Nylorun-Tenant` may be left out. Missing or unsupported protocol → `426` before
-authentication. Unknown, quarantined or rejected Tenant credentials → opaque
-`404` with identical body. A path or method no route serves is `404 Route not found`
+and delivery tokens are refused from browsers before they are looked up. Missing or
+unsupported protocol → `426` before authentication (the Host serves protocols 4 and 5).
+Protocol 5 clients name no Tenant. A protocol 4 client's `Nylorun-Tenant` naming
+another Tenant (or malformed), a publishable key of another Tenant, a Tenant that
+could not be opened and rejected credentials → opaque `404` with identical body. A path or method no route serves is `404 Route not found`
 once the caller is known.
 
 ## API reference (OpenAPI)
@@ -126,10 +149,27 @@ and `api/` import Hono.
 
 Tests and ephemeral embeds use `startEphemeralRuntime()` from
 `@nylorun/runtime/core`: private Host on port 0, temporary Host root, one Tenant,
-returns `{ url, tenantId, applicationKey, adminKey, close() }`. It is not durable:
-its Tenants live in memory and are gone after `close()`. The smoke checks'
-temporary Tenants (`scripts/lib/temporary-tenant.mjs`) do not use it; they are
-created on the Docker stack.
+returns `{ url, tenantId, applicationKey, adminKey, close() }`. Its Tenant is the
+one Tenant of the Postgres database you pass as `database` (required): a pool, which
+you end, or a URL, for which it opens a pool and ends it on `close()`. It creates the
+Tenant there on first start, as a Host does (with `tenantId`, `name` and an application
+principal for `applicationKey`), and serves the Tenant a database already holds. The
+data stays after `close()`; give each test Tenant its own database and drop it
+afterwards. Its
+streams and scheduling are in process and gone after `close()`. The smoke checks do
+not use it; they reset and seed a temporary local Tenant
+(`scripts/lib/stack-tenant.mjs`).
+
+```ts
+const runtime = await startEphemeralRuntime({
+  hostRoot, // a temporary directory
+  database: "postgres://nylorun:nylorun@127.0.0.1:55432/my_test_db",
+});
+```
+
+The package's own tests run every Session Store on Postgres: `npm test` gives each
+test file a database on the Docker test stack (`test/stack/compose.yaml`) and starts
+the stack when it is down; see [CONTRIBUTING.md](../CONTRIBUTING.md).
 
 Register Action endpoints with `PUT /v1/endpoints` using the application principal
 (`createActionHandler(...).register({ url })` in `@nylorun/agents` does this). The
@@ -147,7 +187,7 @@ delivery token authorizes only its own Action's heartbeat, result and sandbox ca
 Session observers cannot submit action results.
 
 Postgres transactions persist session checkpoints, command receipts, individual
-effects/actions, waits and the event outbox — **per Tenant schema**; history is
+effects/actions, waits and the record of session events — in the Tenant's database; history is
 read from Durable Streams (S2). An advance owns its session through a lease with
 an epoch; a Worker that takes over after a crash marks in-flight effects
 `uncertain`. Vault ciphertext needs that Tenant's own KEK.
@@ -157,22 +197,24 @@ Tenant owns each sandbox; backend names are prefixed `nylorun-<tenant-id>-`.
 
 ## Local Project workflow
 
-A project depends on `@nylorun/agents` only. `npx nylorun up` runs the local
-stack (Docker); `npx @nylorun/cli tenant create` (`nylo`) creates the
-project's Tenant and writes its Project link; the project's `npm run dev` runs
-`src/main.ts` under `tsx watch`; `npx nylorun studio` opens Studio.
+A project depends on `@nylorun/agents` only. `npx nylorun start` in the project
+runs its local Tenant (Docker), named after the project directory, and writes
+the Project link (outside a project it runs the Tenant `default`); the project's `npm run dev` runs `src/main.ts` under
+`tsx watch`; `npx nylorun studio` opens Studio on that Tenant.
 
 ## Troubleshooting
 
 | Symptom | What to do |
 | --- | --- |
 | `kek-missing` | Restore `vault-kek` in the Tenant directory |
-| `corrupt` / `migration-failed` / `envelope-invalid` / `open-failed` / `open-timeout` | Follow the `nylo tenant status` repair string |
-| `schema-too-new` | Run a Runtime at least as new as the one that migrated the schema |
+| `GET /ready` is 503 and `/v1/admin/status` names a `tenant.cause` | The Tenant could not be opened; every Tenant request is the opaque `404`. Follow the cause's `repair`, then restart the Runtime |
+| `corrupt` / `migration-failed` / `envelope-invalid` / `open-failed` / `open-timeout` | Follow the cause's `repair` string |
+| `schema-too-new` | Run a Runtime at least as new as the one that migrated the database |
+| `database-layout-old` | The database holds `tenant_<id>` schemas of an older Runtime, or the `schema_version` tables of a pre-release one: point the Runtime at a new database (locally, a new Tenant: `nylorun start --tenant <new name>`); the old one is left as it is |
 | `426 protocol_unsupported` | Upgrade clients or Host to a compatible set |
 | `421 host_rejected` / `403 origin_rejected` | In a container, list the `Host` in `NYLORUN_ALLOWED_HOSTS`. From a browser, use a subject token and a publishable key that lists the page's origin, never a Tenant key |
 | `503` for a Tenant | Postgres or Restate is unreachable; `GET /ready` names which |
-| Port in use | Change `NYLORUN_PORT` in `<Host root>/stack/.env` and run `nylorun up` |
+| Port in use | Change `NYLORUN_PORT` in `~/.nylorun/tenants/<name>/docker/.env` and run `nylorun start` |
 | Logs | `nylorun logs runtime` |
 
 Definitions have no `agent.run()`; applications use `@nylorun/agents`.

package/dist/adapters/execution/restate.js

@@ -12,8 +12,8 @@
  * - `<prefix>NylorunTenant`, key `<tenantId>`. `arm`, `sweep` and `disarm`
  *   keep one self-re-arming sweep chain per Tenant. The chain's generation is
  *   kept in the object's state, so arming is idempotent and a disarmed or
- *   replaced chain dies at its next link. The state is rebuildable: Workers
- *   re-arm every Tenant at startup (§14.8).
+ *   replaced chain dies at its next link. The state is rebuildable: a Host
+ *   re-arms its Tenant's sweep when it opens it, at every start (§14.8).
  * - `<prefix>NylorunTimer`, key `<tenantId>:<timer key>`. `set` records the
  *   latest time and sends a delayed `fire`; a `fire` for an older time is a
  *   no-op, which is how setting a key again replaces it.

package/dist/adapters/replication/pgoutput.d.ts

@@ -2,6 +2,11 @@ import type { ChangeSource } from "../../streams/relay/types.js";
 export interface PgoutputSourceOptions {
     /** A Postgres URL whose role may replicate (`REPLICATION`) and read `nylorun_streams`. */
     connectionString: string;
+    /**
+     * The Tenant the database holds. The record has no Tenant column (one Tenant per
+     * database), so every row read is this Tenant's.
+     */
+    tenantId: string;
     /** Default `nylorun_stream_relay`. */
     slot?: string;
     /** Default `nylorun_stream_relay`. */

package/dist/adapters/replication/pgoutput.js

@@ -25,6 +25,7 @@ export function createPgoutputSource(options) {
     const publication = options.publication ?? "nylorun_stream_relay";
     const schema = options.schema ?? "nylorun_streams";
     const retryMs = options.retryMs ?? 5000;
+    const { tenantId } = options;
     const log = options.log ?? (() => { });
     const pool = new pg.Pool({
         connectionString: options.connectionString,
@@ -84,7 +85,7 @@ export function createPgoutputSource(options) {
                     if (decoding &&
                         message.relation?.schema === schema &&
                         message.relation?.name === "session_events")
-                        decoding.rows.push(rowOf(message.new));
+                        decoding.rows.push(rowOf(message.new, tenantId));
                     break;
                 case "commit": {
                     const tx = { endLsn: message.commitEndLsn, rows: decoding?.rows ?? [] };
@@ -158,9 +159,9 @@ export function createPgoutputSource(options) {
     };
 }
 /** A decoded `session_events` row (`pg` parses `json`; `bigint` arrives as text). */
-function rowOf(values) {
+function rowOf(values, tenantId) {
     return {
-        tenantId: values.tenant_id,
+        tenantId,
         sessionId: values.session_id,
         seq: Number(values.seq),
         generation: Number(values.generation),