@nylorun/runtime 0.24.0-beta → 0.25.0-beta

package/dist/tenant/environments.d.ts

@@ -1,43 +1,8 @@
-/**
- * Environments (D55, D56, protocol 11): `PUT`, `GET` and `DELETE /v1/environments/{id}`, the
- * list by label, stop, reset and the lifecycle stream; sessions naming one with `environment`,
- * and the checks every turn start makes on it.
- *
- * - **No scope.** The Runtime decides nothing about who uses an Environment: the app maps its
- *   people and agents to ids. It stores the id, kind, recipe, labels and the optional owner
- *   guard; the session body names the Environment (`Session.environmentId`), and deleting a
- *   session (a sessions reset) only detaches it.
- * - **One sandbox, one vault.** Kind `virtual` (a just-bash workspace in the harness container,
- *   keyed by the Environment id and created on the first tool call), `pod` (an agent-sandbox pod
- *   on the Tenant's cluster, Host feature `sandbox-pods`, created at once) or `none` (no compute).
- *   Each has one vault (`vault/service.ts`), created and deleted with it in one transaction.
- * - **A recipe that changes.** `PUT` on an existing id compares the fields sent: `kind` and
- *   `storage` are fixed (`409`), labels replace, and any other change writes the recipe and bumps
- *   `version`. A pod runs `applied`: image and resources reach it when it is next asked to run
- *   from stopped (`wantRunning`), so nothing swaps them mid-turn; so does `harness`, which picks
- *   what the pod runs (R4.4). Network and lifecycle apply at once. A virtual or `none`
- *   Environment applies every change at once.
- * - **Access.** An application key reaches every Environment, and so does an application key
- *   acting for a subject (`Nylorun-Subject`), which needs `environments:write` to change one. A
- *   token caller reaches only the ids its grants match, and changes them only with
- *   `environments:write`; any other id is the 404 of a missing one.
- * - **The owner guard.** When `ownerUserId` is set, only that owner's sessions may name the
- *   Environment, checked when a session opens and at every turn start (`403
- *   environment_owner_mismatch`; the opaque 404 to a caller acting for a person).
- * - **Serial turns.** One turn at a time per Environment with a sandbox: a session whose
- *   Environment another session's turn holds is refused (`409 environment_busy`).
- * - **Lifecycle.** `POST .../stop` suspends a pod (the volume is kept; the next turn starts it),
- *   `POST .../reset` gives it a new pod on a new volume. A lost pod refuses turns
- *   (`environment_lost`) until a reset. `lifecycle.deleteAfter` deletes an Environment unused
- *   for that long (the Tenant sweep, `sweepUnusedEnvironments`). Deleting a pod Environment keeps
- *   its row (`desired: deleted`, invisible here) until its Sandbox is gone; its vault goes at once.
- * - **Lifecycle events** go to the Environment's own stream in the record (`Tx.environmentEvent`,
- *   `record/environment.ts`); the session's log records `environment.attached` too.
- */
-import { type EnvironmentView, type PutEnvironmentRequest } from "@nylorun/core/contracts";
-import type { Environment, Tx } from "../store/types.js";
+import { type EnvironmentRecipe, type EnvironmentView, type ForkEnvironmentRequest, type ForkEnvironmentResponse, type PutEnvironmentRequest, type PutEnvironmentSecretRequest } from "@nylorun/core/contracts";
+import type { Environment, EnvironmentEventsQuery, Tx } from "../store/types.js";
 import type { SandboxRouteDeps } from "../core/sandbox-routes.js";
 import { type AuthScope, type Session, type TenantContext } from "./context.js";
+import type { SealedSecretCopies } from "../vault/service.js";
 /** The Environment grants that limit `scope`, or undefined when it reaches every Environment. */
 export declare function environmentGrantsOf(scope: AuthScope): readonly string[] | undefined;
 /** Who the vault's audit rows name for a request: the subject, else the application. */
@@ -48,13 +13,54 @@ export declare function assertReaches(scope: AuthScope, id: string): void;
 export declare function liveEnvironment(t: Tx, id: string, options?: {
     lock?: boolean;
 }): Promise<Environment | undefined>;
+/**
+ * Why input files cannot be used: each that is not a version of a Tenant-wide artifact (a
+ * session's artifacts go with the session). Pins nothing else: the version is the one named.
+ */
+export declare function fileErrors(t: Tx, files: EnvironmentRecipe["files"]): Promise<string[]>;
 /**
  * `PUT /v1/environments/{id}`: creates the Environment and its vault (within the Tenant's limit
- * on their number), or finds the one with this id, so "get or create" is one call. On an
- * existing one, `kind` and `storage` must match, labels replace, the owner guard is set or
- * cleared, and a recipe change bumps `version`. Every `PUT` counts as the Environment's use.
+ * on their number) from an environment manifest's version or from the inline fields, or finds
+ * the one with this id, so "get or create" is one call. An existing one never changes what it
+ * runs (D63): its labels and owner guard may change, fields that match are accepted, and any
+ * other difference is `409 environment_immutable`. Every `PUT` counts as the Environment's use.
+ */
+export declare function putEnvironment(ctx: TenantContext, id: string, body: PutEnvironmentRequest, scope: AuthScope, options?: {
+    fork?: Fork;
+}): Promise<EnvironmentView>;
+/**
+ * The secret write `raw` asks of Environment `id` (D64). When what it runs declares secret
+ * slots, the name must be one (`409 secret_not_in_manifest`), and the body is `{ value }` (or
+ * `{ headers }` for a `headers` slot) with the binding from the slot; a full typed body is
+ * accepted only when its binding is the slot's. Without slots, today's typed body.
+ */
+export declare function secretRequestFor(ctx: TenantContext, id: string, name: string, raw: unknown): Promise<PutEnvironmentSecretRequest>;
+/** What a create does for a fork (`POST .../fork`); `copied` is filled in by the create. */
+interface Fork {
+    source: string;
+    setup: boolean;
+    /**
+     * The source's secrets sealed by keys for the new vault `vaultId` (F4.2), before the create's
+     * transaction, which inserts them; absent with `secrets: none`.
+     */
+    sealed?: {
+        vaultId: string;
+        copies: SealedSecretCopies;
+    };
+    copied?: {
+        copied: string[];
+        dropped: string[];
+    };
+}
+/**
+ * `POST /v1/environments/{id}/fork` (Q15): how an Environment gets a new manifest version. A new
+ * Environment `body.id` is made from the manifest version (default the source's manifest at its
+ * latest), its disk started from a version of the source's (`latest` takes a snapshot first,
+ * refused during a turn), and its secrets copied inside the Runtime. A fork onto other setup
+ * runs that setup on the copied disk before its first turn (Q17). The source keeps what it runs,
+ * its disk and its sessions. With `dryRun`, the plan only.
  */
-export declare function putEnvironment(ctx: TenantContext, id: string, body: PutEnvironmentRequest, scope: AuthScope): Promise<EnvironmentView>;
+export declare function forkEnvironment(ctx: TenantContext, sourceId: string, body: ForkEnvironmentRequest, scope: AuthScope): Promise<ForkEnvironmentResponse>;
 /** `GET /v1/environments/{id}`. */
 export declare function getEnvironment(ctx: TenantContext, id: string, scope: AuthScope): Promise<EnvironmentView>;
 /** `GET /v1/environments?label=k=v`: every Environment with all the labels, that the caller reaches. */
@@ -113,7 +119,7 @@ export declare function newVolume(ctx: TenantContext, t: Tx, environment: Enviro
 /** How long a pending seed holds the disk before another process may take it over. */
 export declare const SEED_LEASE_MS: number;
 /** `GET /v1/environments/{id}/events`: the Environment's lifecycle stream. */
-export declare function environmentEventsOf(ctx: TenantContext, id: string, scope: AuthScope, fromSeq: number | undefined): Promise<{
+export declare function environmentEventsOf(ctx: TenantContext, id: string, scope: AuthScope, query?: EnvironmentEventsQuery): Promise<{
     events: {
         schema: "nylorun.environment-event/1";
         eventId: string;
@@ -121,7 +127,7 @@ export declare function environmentEventsOf(ctx: TenantContext, id: string, scop
         environmentId: string;
         seq: number;
         time: string;
-        type: "environment.attached" | "environment.created" | "environment.deleted" | "environment.detached" | "environment.egress" | "environment.failed" | "environment.lost" | "environment.relaunched" | "environment.reset" | "environment.running" | "environment.suspended";
+        type: "environment.attached" | "environment.created" | "environment.deleted" | "environment.detached" | "environment.egress" | "environment.failed" | "environment.forked" | "environment.lost" | "environment.relaunched" | "environment.reset" | "environment.running" | "environment.suspended";
         payload: Record<string, unknown>;
     }[];
 }>;
@@ -140,9 +146,9 @@ export declare function recordAttachment(t: Tx, sessionId: string, environmentId
 /**
  * Checks a turn start on a session that names an Environment, in the command's transaction
  * after the session row lock: the Environment still exists, a token caller's grants reach it,
- * its owner guard admits the session's owner, and, with a sandbox, no other session's turn
- * holds it. Holds the Environment row's lock until the transaction ends, so two turn starts on
- * one Environment are decided one after the other.
+ * its owner guard admits the session's owner, and no disk copy holds it. Other sessions' turns
+ * do not stop it (D66). Holds the Environment row's lock until the transaction ends, so a turn
+ * start and disk work on one Environment are decided one after the other.
  *
  * A pod Environment must also be usable: not lost (`environment_lost`), on a Runtime with
  * sandbox pods (`environment_unavailable`). A stopped or failed pod is asked to run again, with
@@ -165,3 +171,4 @@ export declare function touchEnvironment(ctx: TenantContext, id: string): Promis
 export declare function rearmPodTimers(ctx: TenantContext): Promise<void>;
 /** Session lookups for the sandbox route handlers (`core/sandbox-routes.ts`). */
 export declare function sandboxRouteDeps(ctx: TenantContext): SandboxRouteDeps;
+export {};