@nylorun/runtime 0.22.0-beta → 0.24.0-beta

package/dist/store/types.d.ts

@@ -10,8 +10,8 @@
  * 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, record rows,
- *    and `afterCommit` callbacks are all discarded, and `tx` rejects with the
- *    error `fn` threw.
+ *    and outbox requests 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, checkpoint settlement and event
@@ -25,18 +25,22 @@
  *    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. A wake is written in the
- *    transaction (`Tx.wake`, the wake outbox) and delivered after commit, and events
- *    are delivered to commit listeners after commit (seam rule 1 and 2).
+ *    S2 call, and no `fetch`, runs inside a transaction. What a transaction asks of
+ *    Durable Session Execution (a wake, a pod sandbox's reconcile or timer) is written
+ *    to the outbox in the transaction (`Tx.wake`, `Tx.signalSandbox`) and delivered
+ *    after commit; what it tells the other processes goes on the control bus
+ *    (`Tx.signal`); 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), 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: a wake's
- *    delivery is a callback too, and its outbox row is what the sweep delivers
- *    again (`Tx.wake`).
+ *    listener once with the transaction's events (in allocation order), then hands
+ *    the transaction's outbox requests to the delivery (`deliverTo`), in the order
+ *    they were written, without the caller waiting. Listener and delivery failures
+ *    are reported to the store's error hook; they never reject `tx`, because the
+ *    commit stands. A request whose delivery fails, or that a crash cuts off, stays
+ *    in the outbox, which the Tenant sweep delivers again. Nothing else runs after
+ *    commit: a step that is not written down is lost to a crash.
  * 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
@@ -58,9 +62,8 @@
  */
 import type { KeyRole } from "@nylorun/core/compatibility";
 import type { RecordReader } from "../streams/relay/types.js";
-import type { Wake } from "../execution/types.js";
-import type { EventPayload, EventType, LiveEvent, SandboxEvent, SandboxEventPayload, SandboxEventType, SandboxKind, SandboxPodDesired, SandboxPodObserved, SessionEventOf } from "@nylorun/core/contracts";
-import type { SandboxManifest } from "@nylorun/core/define";
+import type { SandboxSignal, Wake } from "../execution/types.js";
+import type { EventPayload, EventType, EventWriter, LiveEvent, EnvironmentEvent, EnvironmentEventPayload, EnvironmentEventType, EnvironmentKind, EnvironmentRecipe, PodDesired, PodObserved, SessionEventOf } from "@nylorun/core/contracts";
 import type { HostEffect } from "@nylorun/harness/run";
 import type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, PrincipalRow, ToolCrossingRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow } from "./postgres/schema.js";
 /** Tables holding JSON documents keyed by `id`. */
@@ -69,7 +72,9 @@ 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 EffectStatus = "pending" | "invoking"
+/** A tool call the Tool Gate held for a person's approval (R5 step 2): nothing was sent. */
+ | "held" | "completed" | "uncertain" | "queued" | "cancelled";
 export type EffectKind = HostEffect["kind"];
 /**
  * Ownership of a session by a Worker (§10.6). Read with the session; written
@@ -122,28 +127,51 @@ export interface DefinitionDoc {
 export interface SandboxDoc {
     key: string;
 }
-/** A sandbox resource (`sandbox_resources`): what `PUT /v1/sandboxes/{id}` created. */
-export interface SandboxResource {
+/** An Environment (`environments`, D55): what `PUT /v1/environments/{id}` created. */
+export interface Environment {
     id: string;
-    kind: SandboxKind;
-    /** The spec resolved against the Tenant's limits when the sandbox was created. */
-    spec: SandboxManifest;
+    kind: EnvironmentKind;
     labels: Record<string, string>;
+    /** What the app asked for, resolved against the Tenant's limits. */
+    recipe: EnvironmentRecipe;
+    /** The recipe the current pod or workspace runs (copied from `recipe` at the next wake). */
+    applied: EnvironmentRecipe;
+    version: number;
+    appliedVersion: number;
+    /** The owner guard: only this owner's sessions may name it. */
+    ownerUserId?: string;
+    /** ISO time it was last used (`lifecycle.deleteAfter` counts from it). */
+    lastUsedAt: string;
     createdAt: string;
     updatedAt: string;
-    /** Kind `pod`: the pod's lifecycle (F7.2). Absent for a virtual sandbox. */
+    /** Kind `pod`: the pod's lifecycle (F7.2). Absent otherwise. */
     pod?: SandboxPodState;
+    /** The disk lease while a snapshot, restore or seed copies the disk (R2d step 3). */
+    diskOp?: DiskOperation;
+    /** The disk version the next volume starts from (R2d step 3). */
+    diskSeed?: {
+        artifactId: string;
+        version: number;
+    };
+}
+/** A disk lease (R2d step 3): what holds the disk, since when, and until when unless renewed. */
+export interface DiskOperation {
+    kind: "snapshot" | "restore" | "seed";
+    version?: number;
+    /** ISO times. */
+    startedAt: string;
+    until: string;
 }
 /**
- * A pod sandbox's lifecycle columns (`sandbox_resources`, F7.2, D34): what the Runtime wants
+ * A pod Environment's lifecycle columns (`environments`, F7.2, D34): what the Runtime wants
  * (`desired`), what it last saw (`observed`), and the fences of its incarnations.
  */
 export interface SandboxPodState {
     /** The agent-sandbox Sandbox's name (`podName`), of generation `volumeGen`. */
     k8sName: string;
     volumeGen: number;
-    desired: SandboxPodDesired;
-    observed: SandboxPodObserved;
+    desired: PodDesired;
+    observed: PodObserved;
     /** The UID of the pod that last joined. */
     podUid?: string;
     /** Bumped by every join, relaunch, loss and reset; host and egress tokens carry it. */
@@ -154,7 +182,6 @@ export interface SandboxPodState {
     rev: number;
     /** ISO times. */
     lastActiveAt?: string;
-    expiresAt?: string;
     startedAt?: string;
     reason?: string;
     /** An earlier incarnation's Sandbox still to delete (after a reset or a loss). */
@@ -229,7 +256,7 @@ export interface StoreCounts {
     sandboxes: number;
     definitions: number;
 }
-export type ResetScope = "sessions" | "sandboxes" | "all";
+export type ResetScope = "sessions" | "environments" | "all";
 /** Result of `takeOwnership`. */
 export type TakeOwnership = {
     status: "owned";
@@ -272,6 +299,14 @@ export interface SessionStore {
      * throw; what it throws goes to `onError`, as do listener failures.
      */
     followSignals(onSignal: (signal: ControlSignal) => void, options?: FollowSignalsOptions): Promise<SignalFollower>;
+    /**
+     * Sets where committed outbox requests go (`Tx.wake`, `Tx.signalSandbox`): after each
+     * commit the store hands them to `deliver` without waiting for it, so a slow execution
+     * never holds up the caller. Without one, they wait in the outbox for the Tenant sweep.
+     */
+    deliverTo(deliver: OutboxDelivery | undefined): void;
+    /** Resolves once every delivery started so far has settled (`close` waits for them too). */
+    delivered(): Promise<void>;
     close(): Promise<void>;
 }
 /** A wake as the outbox delivers it: its `dedupeKey` is the request's idempotency key. */
@@ -279,18 +314,38 @@ export type OutboxWake = Wake & {
     dedupeKey: string;
 };
 /**
- * Hands an outbox request to Durable Session Execution (`Tx.wake`). Resolving means the
- * execution accepted it; `false` means it was not delivered and stays in the outbox, as a
- * rejection does, without an error.
+ * What a committed transaction asked of Durable Session Execution, as the outbox delivers it:
+ * a wake (`Tx.wake`), or a pod sandbox's reconcile or timer (`Tx.signalSandbox`; a reconcile
+ * carries its idempotency key, `signal:<row id>`).
  */
-export type WakeDelivery = (sessionId: string, wake: OutboxWake) => boolean | void | Promise<boolean | void>;
-/** A wake outbox request not yet delivered (`Tx.pendingWakes`). */
-export interface PendingWake {
-    id: string;
+export type OutboxRequest = {
+    kind: "wake";
     sessionId: string;
     wake: OutboxWake;
+} | {
+    kind: "sandbox";
+    sandboxId: string;
+    signal: SandboxSignal;
+};
+/**
+ * Hands an outbox request to Durable Session Execution (`SessionStore.deliverTo`). Resolving
+ * means the execution accepted it; `false` means it was not delivered and stays in the
+ * outbox, due at the sweep's next pass, as after a rejection, which also goes to the store's
+ * error hook.
+ */
+export type OutboxDelivery = (request: OutboxRequest) => boolean | void | Promise<boolean | void>;
+/** An outbox row: which table (`kind`) and its id. */
+export type OutboxRef = {
+    kind: OutboxRequest["kind"];
+    id: string;
+};
+/** An outbox request not yet delivered (`Tx.pendingOutbox`). */
+export interface PendingRequest extends OutboxRef {
+    request: OutboxRequest;
     /** ISO time it was written. */
     createdAt: string;
+    /** The sweep's failed deliveries of it so far (`failOutbox`). */
+    attempts: number;
 }
 /**
  * A signal on the control bus (D21, D48): one process tells the others with the Tenant open.
@@ -307,6 +362,15 @@ export type ControlSignal = {
     /** The Tenant's sessions were reset and it moved to basin generation `generation`. */
     type: "sessions.reset";
     generation: number;
+} | {
+    /**
+     * Pod sandbox `sandboxId`'s host epoch moved to `epoch` (a join, a stop, a reset, a
+     * deletion, a loss): every process closes its connections hosting it at an older epoch
+     * (`HarnessApiServer.revokeHost`).
+     */
+    type: "host.revoked";
+    sandboxId: string;
+    epoch: number;
 };
 export interface FollowSignalsOptions {
     /** How often recent signals are read back. Default 5 s. */
@@ -327,7 +391,7 @@ export interface SessionStoreOptions {
     tenantId: string;
     /** Clock for event `time`. Defaults to `() => new Date()`. */
     now?: () => Date;
-    /** Receives listener and `afterCommit` failures, which never reject `tx`. */
+    /** Receives listener and outbox delivery failures, which never reject `tx`. */
     onError?: (error: unknown) => void;
 }
 /** The transaction handle. Valid only inside its `tx` callback. */
@@ -365,29 +429,46 @@ export interface Tx {
      * commit listeners. Rejects when the session does not exist. The returned
      * cursor is final.
      */
-    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): a sandbox signal or a host
-     * revocation. Nothing writes it down, so a crash after commit loses it. A wake goes
-     * through `wake`, which does.
-     */
-    afterCommit(fn: () => void | Promise<void>): void;
+    event<T extends EventType>(sessionId: string, turnId: string | null, type: T, payload: EventPayload<T>, 
+    /** Who wrote it (R4.9): absent, core, observed. */
+    writer?: EventWriter): Promise<SessionEventOf<T>>;
     /**
      * Asks for an advance of `sessionId` once this transaction commits. The request is a row
      * of the wake outbox written in this transaction, so it commits, or rolls back, with what
-     * caused it: a commit never loses its wake. After commit, in `afterCommit` order, the
-     * store calls `deliver` (`DurableExecution.wake`, through the Tenant) and deletes the row
-     * once it resolves to anything but `false`. A request `deliver` declines (`false`) or
-     * rejects, or one a crash cut off, stays in the outbox until the Tenant sweep delivers it
-     * (`pendingWakes`, `deleteWakes`). `deliver` gets the request's idempotency key as
-     * `dedupeKey`: the wake's own, or `wake:<row id>` without one, so a request delivered
-     * twice still causes one advance.
-     */
-    wake(sessionId: string, wake: Wake, deliver: WakeDelivery): Promise<void>;
-    /** Outbox requests written before `before`, oldest first. */
-    pendingWakes(before: Date, limit: number): Promise<PendingWake[]>;
+     * caused it: a commit never loses its wake. After commit the store hands it to the
+     * delivery (`SessionStore.deliverTo`, `DurableExecution.wake` through the Tenant) without
+     * waiting, and deletes the row once that resolves to anything but `false`. A request the
+     * delivery declines or rejects is due at the sweep's next pass; one a crash cut off, or
+     * still being sent, is due once it is older than the sweep's grace (`pendingOutbox`). The
+     * delivery gets the request's idempotency key as `dedupeKey`: the wake's own, or
+     * `wake:<row id>` without one, so a request delivered twice still causes one advance.
+     */
+    wake(sessionId: string, wake: Wake): Promise<void>;
+    /**
+     * Asks for a pod sandbox's reconcile, or sets one of its timers, once this transaction
+     * commits (`DurableExecution.sandbox`): a row of the sandbox signal outbox, delivered as a
+     * wake's is. A reconcile is delivered with the key `signal:<row id>`, so one delivered
+     * twice runs once.
+     */
+    signalSandbox(sandboxId: string, signal: SandboxSignal): Promise<void>;
+    /**
+     * Outbox requests that are due, by the database's clock: written more than `graceMs` ago,
+     * or whose delivery failed and whose retry time has come (`failOutbox`), and not parked.
+     * Oldest first, a retried one by its retry time, so a request that keeps failing never
+     * holds the head of the queue.
+     */
+    pendingOutbox(graceMs: number, limit: number): Promise<PendingRequest[]>;
     /** Deletes delivered outbox requests. */
-    deleteWakes(ids: readonly string[]): Promise<void>;
+    deleteOutbox(rows: readonly OutboxRef[]): Promise<void>;
+    /**
+     * Records a failed delivery of outbox request `row`: one more attempt, due again `retryInMs`
+     * from now (the database's clock). With `park` it is never due again: it stays in the
+     * outbox, with when it was parked, for an operator to send again or delete.
+     */
+    failOutbox(row: OutboxRef, retry: {
+        retryInMs: number;
+        park: boolean;
+    }): Promise<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
@@ -416,9 +497,10 @@ export interface Tx {
     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.
+     * ended at or before `now`, by id, the first `limit` after `after` (a page:
+     * pass the last id of the previous one). The sweep re-wakes these.
      */
-    orphanedSessions<T extends SessionDoc = SessionDoc>(now: Date, limit: number): Promise<StoredSession<T>[]>;
+    orphanedSessions<T extends SessionDoc = SessionDoc>(now: Date, limit: number, after?: string): Promise<StoredSession<T>[]>;
     /** Sessions, optionally of one agent and one owner (`ownerUserId`), by id. */
     listSessions<T extends SessionDoc = SessionDoc>(filter?: {
         agentId?: string;
@@ -426,37 +508,54 @@ export interface Tx {
     }): Promise<StoredSession<T>[]>;
     listDefinitions<T extends DefinitionDoc = DefinitionDoc>(): Promise<T[]>;
     listSandboxes<T extends SandboxDoc = SandboxDoc>(): Promise<T[]>;
-    /** The sandbox resource `id`; with `lock`, its row is locked until the transaction ends. */
-    sandboxResource(id: string, options?: {
+    /** Environment `id`; with `lock`, its row is locked until the transaction ends. */
+    environment(id: string, options?: {
         lock?: boolean;
-    }): Promise<SandboxResource | undefined>;
-    /**
-     * Creates the sandbox resource unless one with its id exists, while the Tenant holds fewer
-     * than `limit`: `exists` and `limit` write nothing. Serialized with every other create.
-     */
-    createSandboxResource(row: SandboxResource, limit: number): Promise<"created" | "exists" | "limit">;
-    updateSandboxLabels(id: string, labels: Record<string, string>, updatedAt: string): Promise<void>;
-    /** Replaces a sandbox's spec (a pod's new `lifecycle.ttl`; the caller holds the row's lock). */
-    updateSandboxSpec(id: string, spec: SandboxManifest, updatedAt: string): Promise<void>;
-    /** Changes a pod sandbox's lifecycle columns (the caller holds the row's lock). */
-    updateSandboxPod(id: string, patch: SandboxPodPatch, updatedAt: string): Promise<void>;
-    deleteSandboxResource(id: string): Promise<void>;
-    /** Sandbox resources by id, those with every label in `labels` when it is given. */
-    listSandboxResources(filter?: {
+    }): Promise<Environment | undefined>;
+    /**
+     * Creates the Environment unless one with its id exists, while the Tenant holds fewer than
+     * `limit`: `exists` and `limit` write nothing. Serialized with every other create.
+     */
+    createEnvironment(row: Environment, limit: number): Promise<"created" | "exists" | "limit">;
+    /**
+     * Changes an Environment's columns other than its pod's (the caller holds the row's lock):
+     * labels, recipe and version, the applied recipe and its version, the owner guard (`null`
+     * clears it), and when it was last used.
+     */
+    updateEnvironment(id: string, patch: {
         labels?: Record<string, string>;
-    }): Promise<SandboxResource[]>;
-    /** Sessions attached to sandbox resource `sandboxId` (`Session.sandboxId`), by id. */
-    sessionsOnSandbox<T extends SessionDoc = SessionDoc>(sandboxId: string): Promise<StoredSession<T>[]>;
+        recipe?: EnvironmentRecipe;
+        version?: number;
+        applied?: EnvironmentRecipe;
+        appliedVersion?: number;
+        ownerUserId?: string | null;
+        lastUsedAt?: string;
+        diskOp?: DiskOperation | null;
+        diskSeed?: {
+            artifactId: string;
+            version: number;
+        } | null;
+    }, updatedAt: string): Promise<void>;
+    /** Changes a pod Environment's lifecycle columns (the caller holds the row's lock). */
+    updateEnvironmentPod(id: string, patch: SandboxPodPatch, updatedAt: string): Promise<void>;
+    /** Deletes the Environment; its vault and credentials go with it (foreign key). */
+    deleteEnvironment(id: string): Promise<void>;
+    /** Environments by id, those with every label in `labels` when it is given. */
+    listEnvironments(filter?: {
+        labels?: Record<string, string>;
+    }): Promise<Environment[]>;
+    /** Sessions that name Environment `environmentId` (`Session.environmentId`), by id. */
+    sessionsOnEnvironment<T extends SessionDoc = SessionDoc>(environmentId: string): Promise<StoredSession<T>[]>;
     /**
-     * Appends an event to the sandbox's lifecycle stream through the record module. The caller
-     * holds the sandbox row's lock (or created the row in this transaction).
+     * Appends an event to the Environment's lifecycle stream through the record module. The
+     * caller holds the Environment row's lock (or created the row in this transaction).
      */
-    sandboxEvent<T extends SandboxEventType>(sandboxId: string, type: T, payload: SandboxEventPayload<T>): Promise<SandboxEvent>;
-    /** The sandbox's lifecycle stream, from `fromSeq` on, at most `limit` events. */
-    sandboxEvents(sandboxId: string, options?: {
+    environmentEvent<T extends EnvironmentEventType>(environmentId: string, type: T, payload: EnvironmentEventPayload<T>): Promise<EnvironmentEvent>;
+    /** The Environment's lifecycle stream, from `fromSeq` on, at most `limit` events. */
+    environmentEvents(environmentId: string, options?: {
         fromSeq?: number;
         limit?: number;
-    }): Promise<SandboxEvent[]>;
+    }): Promise<EnvironmentEvent[]>;
     /** `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[]>;
@@ -492,20 +591,20 @@ export interface Tx {
     putPrincipal(id: string, tokenHash: string, createdAt: string, role?: KeyRole): Promise<PrincipalRow>;
     /** Deletes principal `id`; false when there was none. */
     deletePrincipal(id: string): Promise<boolean>;
-    /** Rejects on a duplicate id, or a second `host` vault. */
+    /** Rejects on a duplicate id, or a second vault for one Environment. */
     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[]>;
-    /** Installation vaults (any session may attach them), ordered by `createdAt`, then id. */
-    installationVaults(): Promise<VaultRow[]>;
+    /** The vault of Environment `environmentId` (D56). */
+    vaultOfEnvironment(environmentId: string): Promise<VaultRow | undefined>;
     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`. */
+    /** Looks a credential up by id alone; callers compare `vaultId`. */
     getCredential(id: string): Promise<VaultCredentialRow | undefined>;
+    /** The credential named `name` in vault `vaultId` (names are unique per vault). */
+    credentialByName(vaultId: string, name: string): Promise<VaultCredentialRow | undefined>;
     /** Credentials of one vault, ordered by `createdAt`, then id. */
     credentialsForVault(vaultId: string, filter?: {
         type?: VaultCredentialRow["type"];
@@ -543,6 +642,11 @@ export interface Tx {
     countSigningKeys(): Promise<number>;
     /** Appends a row, setting `duplicate` when one with the same `effectKey` exists; returns it. */
     recordModelUsage(row: ModelUsageWrite): Promise<ModelUsageRow>;
+    /**
+     * The first row the gate recorded for the model call `effectKey` (R7.1), never a `duplicate`;
+     * undefined when no gate metered it.
+     */
+    modelUsageOf(effectKey: string): Promise<ModelUsageRow | undefined>;
     modelUsageTotals(query: ModelUsageQuery): Promise<ModelUsageTotals>;
     /** Every budget, ordered by scope, then scope id. */
     listModelBudgets(): Promise<ModelBudgetRow[]>;
@@ -551,6 +655,11 @@ export interface Tx {
     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>;
+    /**
+     * Starts a lost call's row again (R5.3): `startedAt` moves on, on a row with no answer and
+     * `hash`. False when the row is gone, settled, or another request's.
+     */
+    restartToolCrossing(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. */
@@ -559,6 +668,10 @@ export interface Tx {
     artifact(id: string, options?: {
         lock?: boolean;
     }): Promise<ArtifactRow | undefined>;
+    /** The folder artifact that holds Environment `environmentId`'s disk versions (R2d step 3). */
+    diskArtifact(environmentId: string, options?: {
+        lock?: boolean;
+    }): Promise<ArtifactRow | undefined>;
     /** Artifacts by creation time, then id: those of one session when `sessionId` is given. */
     listArtifacts(filter?: {
         sessionId?: string;
@@ -575,6 +688,11 @@ export interface Tx {
     artifactVersions(artifactId: string): Promise<ArtifactVersionRow[]>;
     /** Deletes the artifact and its versions; returns the versions' blob keys (empty when none). */
     deleteArtifact(id: string): Promise<string[]>;
+    /**
+     * Deletes one version of a locked artifact (its content rows go with it) and returns its blob
+     * key; the latest version becomes the newest one left. The artifact itself stays, even empty.
+     */
+    deleteArtifactVersion(artifactId: string, version: number): Promise<string | undefined>;
     /**
      * Serializes the Tenant's artifact writes: held until the transaction ends. Take it before
      * reading the total a new version must fit under.
@@ -620,9 +738,9 @@ export interface Tx {
      *   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, sandbox resources and their lifecycle streams;
+     * - `environments`: sandbox records, Environments with their vaults, and their lifecycle
+     *   streams;
      * - `all`: both, plus definitions (and which definition files they use),
-     *   user vaults with their credentials,
      *   the model usage ledger, the model budgets and Tenant-wide artifacts. The host vault, principals, signing keys,
      *   settings, audit and vault idempotency rows stay.
      */

package/dist/streams/relay/core.js

@@ -22,6 +22,7 @@
  *
  * The relay never writes the record and never deletes from S2.
  */
+import { sleep } from "../../retry.js";
 import { basinOf } from "../basin.js";
 import { sessionStream } from "../types.js";
 const RETRY_MIN_MS = 50;
@@ -351,16 +352,3 @@ export function createStreamRelay(options) {
     };
 }
 const messageOf = (error) => (error instanceof Error ? error.message : String(error));
-function sleep(ms, signal) {
-    return new Promise((resolve) => {
-        if (signal.aborted)
-            return resolve();
-        const done = () => {
-            clearTimeout(timer);
-            signal.removeEventListener("abort", done);
-            resolve();
-        };
-        const timer = setTimeout(done, ms);
-        signal.addEventListener("abort", done, { once: true });
-    });
-}

package/dist/tenant/advance.d.ts

@@ -1,6 +1,6 @@
 import type { AdvanceResult } from "../execution/types.js";
 import type { Tx } from "../store/types.js";
-import type { Session, TenantContext } from "./context.js";
+import { type Session, type TenantContext } from "./context.js";
 /**
  * Advance session `id` if it has a runnable checkpoint (`WorkerHandlers.advance`). Returns
  * `busy` when another advance holds a live lease, `done` otherwise.
@@ -9,12 +9,13 @@ export declare function advance(ctx: TenantContext, id: string, signal: AbortSig
 /**
  * Takeover (§10.5 step 2, §11.4), inside the transaction that took ownership: the dead
  * owner's `invoking` effects become `uncertain` and are never invoked again, except model
- * calls when the gate recovers them (P1.2) and remote MCP and HTTP tool calls when the Tool
- * Gate does (F4.1 G3): those stay `invoking`, and the replay re-sends them. When one belongs
- * to the active turn, the session becomes `uncertain` too, with an `effect.uncertain` event.
- * Mutates and writes `s`. Returns the effect ids it marked.
+ * calls when the gate recovers them (P1.2) and every tool call (R5.3): those stay `invoking`,
+ * and the replay decides. It re-sends a model call, and an MCP or HTTP tool call with the same
+ * key; a sandbox or core-served tool call fails to the model as `tool.interrupted`
+ * (`harness-api/tool-journal.ts`). When an effect marked `uncertain` belongs to the active
+ * turn, the session becomes `uncertain` too, with an `effect.uncertain` event. Mutates and
+ * writes `s`. Returns the effect ids it marked.
  */
 export declare function takeOver(t: Tx, s: Session, options?: {
     recoversModelCalls?: boolean;
-    recoversToolCalls?: boolean;
 }): Promise<string[]>;