@nylorun/runtime 0.15.1-beta → 0.16.0-beta

package/dist/sandbox/records.d.ts

@@ -0,0 +1,29 @@
+import type { WorkspaceRecord } from "@nylorun/core/harness-api";
+import type { SessionStore } from "../store/types.js";
+export type SandboxState = WorkspaceRecord["state"];
+/** A workspace's compute record. */
+export type SandboxRecord = WorkspaceRecord;
+/** The SandboxManager's records port. */
+export interface SandboxRecords {
+    get(key: string): Promise<SandboxRecord | undefined>;
+    put(record: SandboxRecord): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(): Promise<SandboxRecord[]>;
+    count(): Promise<number>;
+}
+/** The workspace key prefix of the Tenant `scope`. */
+export declare function workspacePrefix(scope: string): string;
+/** The key of session `sessionId`'s own workspace. */
+export declare function sessionWorkspaceKey(scope: string, sessionId: string): string;
+/**
+ * The key of sandbox resource `sandboxId`'s workspace: apart from every session key (16 hex
+ * characters after the prefix). The virtual backend keeps it in `<sandboxes>/<key>/workspace`.
+ */
+export declare function sandboxWorkspaceKey(scope: string, sandboxId: string): string;
+/** The records in the Tenant's `sandboxes` table. */
+export declare function storeSandboxRecords(store: SessionStore): SandboxRecords;
+/**
+ * The records in one JSON file, rewritten whole (to a temporary file, then renamed) after each
+ * change. Writes are serialized; a file that cannot be read starts empty.
+ */
+export declare function fileSandboxRecords(path: string): SandboxRecords;

package/dist/sandbox/records.js

@@ -0,0 +1,79 @@
+/**
+ * Where the SandboxManager keeps its workspaces' compute records (`SandboxRecords`). In core's
+ * process the records are the Tenant's `sandboxes` table (`storeSandboxRecords`). A harness
+ * process reaches no store (F6.2): it keeps them in a file on its volume
+ * (`fileSandboxRecords`), and core keeps its table in step from the harness's `sandbox.state`
+ * claims and `workspace.sweep` answers.
+ *
+ * A workspace's key is `<prefix><16 hex>` for a session's own workspace and
+ * `<prefix>sbx-<16 hex>` for a sandbox resource's, where the prefix names the Tenant: core and
+ * a harness compute the same keys from the Tenant id.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+/** The workspace key prefix of the Tenant `scope`. */
+export function workspacePrefix(scope) {
+    return `nylorun-${scope}-`;
+}
+/** The key of session `sessionId`'s own workspace. */
+export function sessionWorkspaceKey(scope, sessionId) {
+    return workspacePrefix(scope) + createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
+}
+/**
+ * The key of sandbox resource `sandboxId`'s workspace: apart from every session key (16 hex
+ * characters after the prefix). The virtual backend keeps it in `<sandboxes>/<key>/workspace`.
+ */
+export function sandboxWorkspaceKey(scope, sandboxId) {
+    return `${workspacePrefix(scope)}sbx-${createHash("sha256").update(sandboxId).digest("hex").slice(0, 16)}`;
+}
+/** The records in the Tenant's `sandboxes` table. */
+export function storeSandboxRecords(store) {
+    return {
+        get: (key) => store.tx((t) => t.get("sandboxes", key)),
+        put: (record) => store.tx((t) => t.put("sandboxes", record.key, record)),
+        delete: (key) => store.tx((t) => t.delete("sandboxes", key)),
+        list: () => store.tx((t) => t.listSandboxes()),
+        count: async () => (await store.tx((t) => t.counts())).sandboxes,
+    };
+}
+/**
+ * The records in one JSON file, rewritten whole (to a temporary file, then renamed) after each
+ * change. Writes are serialized; a file that cannot be read starts empty.
+ */
+export function fileSandboxRecords(path) {
+    const records = new Map();
+    try {
+        const stored = JSON.parse(readFileSync(path, "utf8"));
+        for (const record of stored.records ?? [])
+            records.set(record.key, record);
+    }
+    catch {
+        /* no file yet, or unreadable: start empty */
+    }
+    let writing = Promise.resolve();
+    const save = () => {
+        const body = JSON.stringify({ records: [...records.values()] });
+        // A failed write does not stop the next one, which writes everything again.
+        writing = writing.catch(() => undefined).then(() => {
+            mkdirSync(dirname(path), { recursive: true });
+            const temporary = `${path}.${process.pid}.tmp`;
+            writeFileSync(temporary, body, { mode: 0o600 });
+            renameSync(temporary, path);
+        });
+        return writing;
+    };
+    return {
+        get: async (key) => records.get(key),
+        async put(record) {
+            records.set(record.key, record);
+            await save();
+        },
+        async delete(key) {
+            if (records.delete(key))
+                await save();
+        },
+        list: async () => [...records.values()],
+        count: async () => records.size,
+    };
+}

package/dist/sandbox/resolve.d.ts

@@ -24,6 +24,11 @@ export interface ResolveSandboxInput {
     readonly config: EffectiveSandboxConfig;
     /** The request acts for a subject (`Nylorun-Subject`) rather than as the application. */
     readonly actingForSubject: boolean;
+    /**
+     * The sandbox's kind. Default `virtual`, which runs no images and allows exact host names
+     * only; a `pod` (F7.2) takes an image and `*.suffix` hosts.
+     */
+    readonly kind?: "virtual" | "pod";
 }
 export declare const SUBJECT_INLINE_MESSAGE = "Defining a sandbox needs an application key. Use the Tenant default, or open the session from the application backend.";
 export declare function resolveSandbox(input: ResolveSandboxInput): SandboxResolution;

package/dist/sandbox/resolve.js

@@ -17,13 +17,14 @@ export function resolveSandbox(input) {
 function build(request, source, input) {
     const { limits } = input.config;
     const errors = [];
-    if (request.image !== undefined)
+    const pod = input.kind === "pod";
+    if (request.image !== undefined && !pod)
         errors.push("sandbox.image is not supported: the virtual sandbox has no images.");
     const allow = (request.network?.allow ?? []).map((host) => host.toLowerCase());
     for (const host of allow) {
         if (!withinCeiling(host, limits.network))
             errors.push(`sandbox.network.allow includes ${host}, which this Tenant does not allow.`);
-        else if (host.startsWith("*."))
+        else if (host.startsWith("*.") && !pod)
             errors.push(`sandbox.network.allow includes ${host}; the virtual sandbox allows exact host names only, such as ${host.slice(2)}.`);
     }
     const cpus = request.resources?.cpus ?? limits.defaultResources.cpus;

package/dist/sandbox/session-sandbox.js

@@ -1,11 +1,12 @@
 /**
  * Gives a session the sandbox chosen when it was opened. An agent session's pinned manifest is
  * its definition plus the `nylorun.sandbox` capability (the six built-in tools, the sandbox
- * instructions and the resolved spec), also added to each agent it uses as a tool, so the tree
- * shares one spec. The definition in the registry never changes.
+ * instructions and the resolved spec) and the `nylorun.artifacts` capability (`save_artifact`),
+ * also added to each agent it uses as a tool, so the tree shares one spec. The definition in the
+ * registry never changes.
  */
 import { AgentManifestSchema } from "@nylorun/core/contracts";
-import { hashManifest, sandboxCapabilityManifest, } from "@nylorun/core/define";
+import { artifactsCapabilityManifest, hashManifest, sandboxCapabilityManifest, } from "@nylorun/core/define";
 import { sandboxSpecOf } from "./share.js";
 function isAgentManifest(value) {
     return (typeof value === "object" &&
@@ -30,7 +31,8 @@ function addCapability(manifest, spec) {
         });
     return {
         ...manifest,
-        capabilities: [...capabilities, sandboxCapabilityManifest(spec)],
+        // With a sandbox comes `save_artifact`, so files the agent makes reach the user (F8.1).
+        capabilities: [...capabilities, sandboxCapabilityManifest(spec), artifactsCapabilityManifest()],
     };
 }
 /** The agent's manifest with the sandbox capability added, or why it cannot take one. */
@@ -43,7 +45,7 @@ export function withSandboxCapability(manifest, spec) {
         return {
             ok: false,
             message: clash
-                ? `'${manifest.id}' declares a tool named like a sandbox tool (bash, read, write, edit, grep, glob). Rename it, or open the session with sandbox: false.`
+                ? `'${manifest.id}' declares a tool named like a sandbox tool (bash, read, write, edit, grep, glob, save_artifact). Rename it, or open the session with sandbox: false.`
                 : `'${manifest.id}' cannot take this sandbox: ${[...new Set(issues)].join("; ")}`,
         };
     }

package/dist/sandbox/share.d.ts

@@ -11,6 +11,8 @@ export type SessionSandboxRef = {
     readonly manifest: AgentManifest | WorkflowManifest | Record<string, unknown>;
     /** Session whose id keys the sandbox. Absent means this session owns its own. */
     readonly sandboxOwnerId?: string | null;
+    /** The sandbox resource the session is attached to; its id keys the workspace. */
+    readonly sandboxId?: string;
     /** The sandbox chosen when the session was opened (or inherited from its owner), resolved. */
     readonly sandbox?: SandboxManifest;
 };
@@ -32,4 +34,13 @@ export declare function capabilityForSandbox(sandbox: SandboxManifest): Capabili
  * cycles fall back to the starting session.
  */
 export declare function owningSandboxSessionId(session: SessionSandboxRef, lookup: (id: string) => SessionSandboxRef | undefined): string;
+/**
+ * The workspace a session's sandbox tools run in: the owning session (one hop through
+ * `sandboxOwnerId`, whose log records the workspace's events) and, when that session is
+ * attached to a sandbox resource, the resource's id, which keys the workspace.
+ */
+export declare function sandboxWorkspaceOf(session: SessionSandboxRef, lookup: (id: string) => SessionSandboxRef | undefined): {
+    readonly ownerId: string;
+    readonly sandboxId?: string;
+};
 export declare function sessionHasSandbox(session: SessionSandboxRef, lookup: (id: string) => SessionSandboxRef | undefined): boolean;

package/dist/sandbox/share.js

@@ -81,6 +81,16 @@ export function owningSandboxSessionId(session, lookup) {
     }
     return session.id;
 }
+/**
+ * The workspace a session's sandbox tools run in: the owning session (one hop through
+ * `sandboxOwnerId`, whose log records the workspace's events) and, when that session is
+ * attached to a sandbox resource, the resource's id, which keys the workspace.
+ */
+export function sandboxWorkspaceOf(session, lookup) {
+    const ownerId = owningSandboxSessionId(session, lookup);
+    const owner = ownerId === session.id ? session : lookup(ownerId) ?? session;
+    return owner.sandboxId === undefined ? { ownerId } : { ownerId, sandboxId: owner.sandboxId };
+}
 export function sessionHasSandbox(session, lookup) {
     const ownerId = owningSandboxSessionId(session, lookup);
     const owner = ownerId === session.id ? session : lookup(ownerId) ?? session;

package/dist/sandbox/tenant-config.d.ts

@@ -3,12 +3,14 @@
  * session gets when it names none, and the limits every session's sandbox must fit. Unset
  * fields take the defaults below.
  */
-import { type SandboxInlineRequest, type TenantSandboxConfig } from "@nylorun/core/contracts";
+import { type SandboxInlineRequest, type SandboxPlacementHost, type TenantSandboxConfig } from "@nylorun/core/contracts";
 export declare const SANDBOX_CONFIG_SETTING = "sandbox.config";
 /** The most a session may ask for when the Tenant sets no maximum. */
 export declare const DEFAULT_MAX_CPUS = 4;
 export declare const DEFAULT_MAX_MEMORY_MIB = 8192;
 export declare const DEFAULT_SANDBOX_IDLE = "15m";
+/** The most sandbox resources a Tenant holds when it sets no limit. */
+export declare const DEFAULT_MAX_SANDBOXES = 100;
 export interface SandboxResourcesLimit {
     readonly cpus: number;
     readonly memoryMiB: number;
@@ -21,7 +23,20 @@ export interface EffectiveSandboxConfig {
         readonly resources: SandboxResourcesLimit;
         readonly defaultResources: SandboxResourcesLimit;
         readonly idle: string;
+        /** The most sandbox resources (`PUT /v1/sandboxes/{id}`) the Tenant may hold. */
+        readonly sandboxes: number;
+        /** Pods: the longest `lifecycle.ttl`. */
+        readonly ttl?: string;
     };
+    /** Pods (F7.2, D36). */
+    readonly lifecycle: {
+        readonly onExpiry: "retain" | "delete";
+        readonly stopGrace: string;
+    };
+    /** Where each harness may run (D38). */
+    readonly placement: Readonly<Record<string, {
+        readonly hosts: readonly SandboxPlacementHost[];
+    }>>;
 }
 interface SettingsReader {
     getSetting(key: string): Promise<string | undefined>;

package/dist/sandbox/tenant-config.js

@@ -11,6 +11,8 @@ export const SANDBOX_CONFIG_SETTING = "sandbox.config";
 export const DEFAULT_MAX_CPUS = 4;
 export const DEFAULT_MAX_MEMORY_MIB = 8192;
 export const DEFAULT_SANDBOX_IDLE = "15m";
+/** The most sandbox resources a Tenant holds when it sets no limit. */
+export const DEFAULT_MAX_SANDBOXES = 100;
 export function memoryMiB(value) {
     const bytes = parseSandboxSize(value);
     return bytes === undefined ? 0 : Math.max(128, Math.ceil(bytes / 1024 ** 2));
@@ -36,7 +38,14 @@ export function effectiveSandboxConfig(config) {
                 memoryMiB: DEFAULT_SANDBOX_MEMORY_MIB,
             }),
             idle: limits.idle ?? DEFAULT_SANDBOX_IDLE,
+            sandboxes: limits.sandboxes ?? DEFAULT_MAX_SANDBOXES,
+            ...(limits.ttl === undefined ? {} : { ttl: limits.ttl }),
         },
+        lifecycle: {
+            onExpiry: config.lifecycle?.onExpiry ?? "retain",
+            stopGrace: config.lifecycle?.stopGrace ?? "10s",
+        },
+        placement: config.placement ?? { "*": { hosts: ["harness-container", "sandbox"] } },
     };
 }
 /** The stored configuration, or `{}` when the Tenant has none. */

package/dist/sandbox/types.d.ts

@@ -3,7 +3,8 @@
  * and import a substrate SDK; everything else in the Runtime talks to this interface.
  */
 import type { SandboxNetworkPreset } from "@nylorun/core/define";
-export type SandboxBackendName = "virtual";
+/** `virtual` (just-bash, in process); `local` (the pod sandbox the engine runs in, F7.2). */
+export type SandboxBackendName = "virtual" | "local";
 /** What separates a sandbox from its host: the Runtime process, or a container boundary. */
 export type SandboxIsolation = "process" | "container";
 export interface SandboxProbe {
@@ -52,11 +53,38 @@ export interface SandboxHandle {
     exec(request: ExecRequest, signal: AbortSignal): Promise<ExecResult>;
     /** Returns undefined when the file does not exist. */
     readFile(path: string): Promise<string | undefined>;
+    /**
+     * The file's bytes, or undefined when it does not exist; refuses one larger than `maxBytes`
+     * (`SandboxFileTooLargeError`). For `save_artifact`, which keeps binary files intact.
+     */
+    readBytes?(path: string, maxBytes: number): Promise<Uint8Array | undefined>;
+    /**
+     * The regular files under directory `dir`, recursively, with paths relative to it (`/`-
+     * separated) in path order; symbolic links are skipped. Undefined when `dir` is not a
+     * directory. Stops after `maxEntries + 1` files (`truncated`). For the turn-end export (F8.2).
+     */
+    listFiles?(dir: string, maxEntries: number): Promise<SandboxListing | undefined>;
     /** Parent directories must already exist. */
     writeFile(path: string, content: string): Promise<void>;
     /** Release compute; files persist. */
     stop(): Promise<void>;
 }
+/** The files `listFiles` found: paths relative to the directory listed. */
+export interface SandboxListing {
+    readonly entries: readonly {
+        readonly path: string;
+        readonly size: number;
+    }[];
+    /** More files than `maxEntries` were found; `entries` holds the first `maxEntries + 1`. */
+    readonly truncated: boolean;
+}
+/** A sandbox file read with `readBytes` is larger than the caller allows. */
+export declare class SandboxFileTooLargeError extends Error {
+    readonly path: string;
+    readonly size: number;
+    readonly maxBytes: number;
+    constructor(path: string, size: number, maxBytes: number);
+}
 export interface SandboxBackend {
     readonly name: SandboxBackendName;
     readonly isolation: SandboxIsolation;

package/dist/sandbox/types.js

@@ -1 +1,13 @@
-export {};
+/** A sandbox file read with `readBytes` is larger than the caller allows. */
+export class SandboxFileTooLargeError extends Error {
+    path;
+    size;
+    maxBytes;
+    constructor(path, size, maxBytes) {
+        super(`${path} is ${size} bytes, more than ${maxBytes}`);
+        this.path = path;
+        this.size = size;
+        this.maxBytes = maxBytes;
+        this.name = "SandboxFileTooLargeError";
+    }
+}

package/dist/store/postgres/drizzle/0004_sandbox_resources.sql

@@ -0,0 +1,20 @@
+CREATE TABLE "nylorun_streams"."sandbox_events" (
+	"sandbox_id" text COLLATE "C" NOT NULL,
+	"seq" bigint NOT NULL,
+	"type" text NOT NULL,
+	"body" json NOT NULL,
+	"committed_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "sandbox_events_pkey" PRIMARY KEY("sandbox_id","seq")
+);
+--> statement-breakpoint
+CREATE TABLE "nylorun"."sandbox_resources" (
+	"id" text COLLATE "C" PRIMARY KEY NOT NULL,
+	"kind" text NOT NULL,
+	"spec" json NOT NULL,
+	"labels" json NOT NULL,
+	"created_at" text COLLATE "C" NOT NULL,
+	"updated_at" text COLLATE "C" NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "nylorun"."sessions" ADD COLUMN "sandbox_id" text GENERATED ALWAYS AS (nylorun.doc(body)->>'sandboxId') STORED;--> statement-breakpoint
+CREATE INDEX "sessions_sandbox" ON "nylorun"."sessions" USING btree ("sandbox_id");

package/dist/store/postgres/drizzle/0005_artifacts.sql

@@ -0,0 +1,27 @@
+CREATE TABLE "nylorun"."artifact_versions" (
+	"artifact_id" text COLLATE "C" NOT NULL,
+	"version" integer NOT NULL,
+	"blob_key" text NOT NULL,
+	"size" bigint NOT NULL,
+	"sha256" text NOT NULL,
+	"content_type" text NOT NULL,
+	"source" text NOT NULL,
+	"created_at" text COLLATE "C" NOT NULL,
+	CONSTRAINT "artifact_versions_pkey" PRIMARY KEY("artifact_id","version")
+);
+--> statement-breakpoint
+CREATE TABLE "nylorun"."artifacts" (
+	"id" text COLLATE "C" PRIMARY KEY NOT NULL,
+	"kind" text NOT NULL,
+	"name" text NOT NULL,
+	"content_type" text NOT NULL,
+	"session_id" text COLLATE "C",
+	"latest_version" integer NOT NULL,
+	"labels_json" text,
+	"created_at" text COLLATE "C" NOT NULL,
+	"updated_at" text NOT NULL,
+	CONSTRAINT "artifacts_kind_check" CHECK (kind = 'file')
+);
+--> statement-breakpoint
+ALTER TABLE "nylorun"."artifact_versions" ADD CONSTRAINT "artifact_versions_artifact_id_fkey" FOREIGN KEY ("artifact_id") REFERENCES "nylorun"."artifacts"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "artifacts_session" ON "nylorun"."artifacts" USING btree ("session_id","created_at","id");

package/dist/store/postgres/drizzle/0006_folder_artifacts.sql

@@ -0,0 +1,12 @@
+CREATE TABLE "nylorun"."artifact_content" (
+	"artifact_id" text COLLATE "C" NOT NULL,
+	"version" integer NOT NULL,
+	"sha256" text COLLATE "C" NOT NULL,
+	"size" bigint NOT NULL,
+	CONSTRAINT "artifact_content_pkey" PRIMARY KEY("artifact_id","version","sha256")
+);
+--> statement-breakpoint
+ALTER TABLE "nylorun"."artifacts" DROP CONSTRAINT "artifacts_kind_check";--> statement-breakpoint
+ALTER TABLE "nylorun"."artifact_content" ADD CONSTRAINT "artifact_content_version_fkey" FOREIGN KEY ("artifact_id","version") REFERENCES "nylorun"."artifact_versions"("artifact_id","version") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "artifact_content_sha256" ON "nylorun"."artifact_content" USING btree ("sha256");--> statement-breakpoint
+ALTER TABLE "nylorun"."artifacts" ADD CONSTRAINT "artifacts_kind_check" CHECK (kind IN ('file', 'folder'));

package/dist/store/postgres/drizzle/0007_sandbox_pods.sql

@@ -0,0 +1,14 @@
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "k8s_name" text COLLATE "C";--> statement-breakpoint
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "volume_gen" integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "desired" text;--> statement-breakpoint
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "observed" text;--> statement-breakpoint
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "pod_uid" text;--> statement-breakpoint
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "host_epoch" integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "join_token_hash" text;--> statement-breakpoint
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "rev" integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "last_active_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "expires_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "started_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "reason" text;--> statement-breakpoint
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "retiring" text COLLATE "C";--> statement-breakpoint
+ALTER TABLE "nylorun"."sandbox_resources" ADD COLUMN "volume_id" text;

package/dist/store/postgres/drizzle/meta/_journal.json

@@ -29,6 +29,34 @@
       "when": 1790956444115,
       "tag": "0003_tool_crossings",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1791033032750,
+      "tag": "0004_sandbox_resources",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1791038725360,
+      "tag": "0005_artifacts",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1791040679989,
+      "tag": "0006_folder_artifacts",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1791048873567,
+      "tag": "0007_sandbox_pods",
+      "breakpoints": true
     }
   ]
 }

package/dist/store/postgres/record-writer.d.ts

@@ -1,4 +1,9 @@
-import type { RecordWriter } from "../../record/index.js";
+import type { RecordWriter, SandboxRecordWriter } from "../../record/index.js";
 import type { Transaction } from "./db.js";
+/**
+ * The sandbox stream writer of transaction `db` (`record/sandbox.ts`): the only inserts into
+ * `sandbox_events`. The caller holds the sandbox row's lock, which orders its events.
+ */
+export declare function postgresSandboxRecordWriter(db: Transaction): SandboxRecordWriter;
 /** The record writer of transaction `db`. */
 export declare function postgresRecordWriter(db: Transaction): RecordWriter;

package/dist/store/postgres/record-writer.js

@@ -4,8 +4,26 @@
  * and `session_log_heads`. They sit here, behind the driver boundary (session-store.md §3), and
  * run in the store's transaction under the caller's session row lock.
  */
-import { sql } from "drizzle-orm";
-import { sessionEvents, sessionLogHeads, tenant } from "./schema.js";
+import { eq, sql } from "drizzle-orm";
+import { sandboxEvents, sessionEvents, sessionLogHeads, tenant } from "./schema.js";
+/**
+ * The sandbox stream writer of transaction `db` (`record/sandbox.ts`): the only inserts into
+ * `sandbox_events`. The caller holds the sandbox row's lock, which orders its events.
+ */
+export function postgresSandboxRecordWriter(db) {
+    return {
+        async nextSeq(sandboxId) {
+            const [row] = await db
+                .select({ next: sql `coalesce(max(${sandboxEvents.seq}) + 1, 0)`.mapWith(Number) })
+                .from(sandboxEvents)
+                .where(eq(sandboxEvents.sandboxId, sandboxId));
+            return row?.next ?? 0;
+        },
+        async insert(row) {
+            await db.insert(sandboxEvents).values(row);
+        },
+    };
+}
 /** The record writer of transaction `db`. */
 export function postgresRecordWriter(db) {
     return {