@nylorun/runtime 0.15.1-beta → 0.16.0-beta

package/dist/artifacts/service.js

@@ -0,0 +1,301 @@
+/**
+ * File artifacts (blueprint D35, F8.1): an opaque id, a name, numbered immutable versions,
+ * metadata in Postgres and bytes in the Object store behind the `BlobStore` seam. Folders
+ * (F8.2) are written by the turn-end export (`./export.ts`, `./folders.ts`) and read here.
+ *
+ * - **Uploads stream.** The body goes to the store as it arrives, at a fresh random key, counted
+ *   against the per-file cap and what is left of the Tenant total (`maxBytes`): nothing is
+ *   buffered whole, and a body past either limit stores nothing (`413 limit_exceeded`).
+ * - **Postgres is the commit point.** One transaction writes the version row and, for a session's
+ *   artifact, its `artifact.created` or `artifact.version.created` event through the record
+ *   module, after re-checking the Tenant total under the quota lock. Until it commits the object
+ *   is garbage, and a failed commit deletes it.
+ * - **Access mirrors sessions.** An application principal reaches every artifact. A request acting
+ *   for a person (a subject token or subject headers) reaches only artifacts of that person's
+ *   sessions; another person's, or a Tenant-wide one, is the same 404 as a missing artifact.
+ *
+ * Lock order, the same in every write: the session, then the quota lock, then the artifact row.
+ */
+import { randomUUID } from "node:crypto";
+import { ARTIFACT_NAME_MAX } from "@nylorun/core/contracts";
+import { isArtifactId, newArtifactId } from "@nylorun/core/compatibility";
+import { BlobTooLargeError } from "../blob/index.js";
+import { lockedSession, sessionOf, } from "../tenant/context.js";
+import { fail } from "../tenant/http.js";
+import { readArtifactLimits } from "./config.js";
+import { collectContent, readManifest } from "./folders.js";
+import { contentTypeFor } from "./media-types.js";
+const notFound = () => fail(404, "Artifact not found");
+function tooLarge(message, limit) {
+    return fail(413, message, { code: "limit_exceeded", details: { limitBytes: limit } });
+}
+/** A body past `maxBytes`: past the per-file cap, or past what is left of the Tenant total. */
+function tooLargeFor(maxBytes, limits) {
+    return maxBytes === limits.fileBytes
+        ? tooLarge(`A file may hold at most ${limits.fileBytes} bytes`, limits.fileBytes)
+        : tooLarge(`The Tenant's artifacts may hold at most ${limits.totalBytes} bytes; this file does not fit`, limits.totalBytes);
+}
+export function versionView(row) {
+    return {
+        version: row.version,
+        size: row.size,
+        sha256: row.sha256,
+        contentType: row.contentType,
+        source: row.source,
+        createdAt: row.createdAt,
+    };
+}
+export function artifactView(row, versions) {
+    return {
+        artifactId: row.id,
+        kind: row.kind,
+        name: row.name,
+        contentType: row.contentType,
+        ...(row.sessionId === null ? {} : { sessionId: row.sessionId }),
+        latestVersion: row.latestVersion,
+        ...(row.labelsJson === null ? {} : { labels: JSON.parse(row.labelsJson) }),
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+        ...(versions === undefined ? {} : { versions: versions.map(versionView) }),
+    };
+}
+/** An artifact name: 1–255 characters, no path separators or control characters. */
+export function checkArtifactName(name) {
+    if (name === undefined ||
+        name.trim() === "" ||
+        name.length > ARTIFACT_NAME_MAX ||
+        /[/\\\u0000-\u001f\u007f]/u.test(name) ||
+        name === "." ||
+        name === "..")
+        return fail(400, `An artifact name is 1 to ${ARTIFACT_NAME_MAX} characters, without '/', '\\' or control characters`);
+    return name;
+}
+/**
+ * The artifact if the caller may reach it, else the 404 of a missing one. Reads its session
+ * (without locking) to check whose it is.
+ */
+export async function readableArtifact(t, id, access, options = {}) {
+    if (!isArtifactId(id))
+        return notFound();
+    const row = await t.artifact(id, options);
+    if (!row)
+        return notFound();
+    await checkReach(t, row, access);
+    return row;
+}
+async function checkReach(t, row, access) {
+    if (access === undefined)
+        return;
+    if (row.sessionId === null)
+        notFound();
+    try {
+        await sessionOf(t, row.sessionId, access);
+    }
+    catch {
+        notFound();
+    }
+}
+/** `version`, or the latest when it is undefined; a missing one is a 404. */
+export async function versionOf(t, row, version) {
+    const found = await t.artifactVersion(row.id, version ?? row.latestVersion);
+    return found ?? fail(404, "Artifact version not found");
+}
+/**
+ * Stores `body` as a new artifact, or a new version of one, within the Tenant's limits. See the
+ * module comment for how it streams and commits.
+ */
+export async function uploadArtifact(ctx, input, body, access, signal) {
+    const name = input.artifactId === undefined ? checkArtifactName(input.name) : undefined;
+    // Where it goes and how much room is left, before a byte is stored.
+    const { limits, used, sessionId, fileName } = await ctx.store.tx(async (t) => {
+        let sessionId;
+        let fileName = name;
+        if (input.artifactId !== undefined) {
+            const prior = await readableArtifact(t, input.artifactId, access);
+            if (prior.kind !== "file")
+                fail(400, `Artifact ${prior.id} is a folder; its versions come from turn-end exports`);
+            sessionId = prior.sessionId;
+            fileName = prior.name;
+        }
+        else {
+            if (input.sessionId === undefined && access !== undefined)
+                fail(400, "Acting for a person, an artifact belongs to one of their sessions: name sessionId");
+            if (input.sessionId !== undefined)
+                await sessionOf(t, input.sessionId, access);
+            sessionId = input.sessionId ?? null;
+        }
+        return { limits: await readArtifactLimits(t), used: await t.artifactBytes(), sessionId, fileName };
+    });
+    const contentType = input.contentType ?? contentTypeFor(fileName);
+    const room = limits.totalBytes - used;
+    if (room <= 0)
+        tooLarge(`The Tenant's artifacts hold ${used} of ${limits.totalBytes} bytes; delete some first`, limits.totalBytes);
+    const maxBytes = Math.min(limits.fileBytes, room);
+    if (input.declaredBytes !== undefined && input.declaredBytes > maxBytes)
+        tooLargeFor(maxBytes, limits);
+    const artifactId = input.artifactId ?? newArtifactId();
+    const key = `artifacts/${artifactId}/${randomUUID()}`;
+    let stored;
+    try {
+        stored = await ctx.blobs.put(key, body, {
+            contentType,
+            maxBytes,
+            ...(signal ? { signal } : {}),
+        });
+    }
+    catch (error) {
+        if (error instanceof BlobTooLargeError)
+            tooLargeFor(maxBytes, limits);
+        throw error;
+    }
+    const createdAt = new Date().toISOString();
+    try {
+        return await ctx.store.tx(async (t) => {
+            // The session first, then the quota, then the artifact (the module's lock order).
+            let session;
+            if (sessionId !== null)
+                session = await lockedSession(t, sessionId, access);
+            await t.lockArtifactQuota();
+            const total = await t.artifactBytes();
+            if (total + stored.size > limits.totalBytes)
+                tooLarge(`The Tenant's artifacts may hold at most ${limits.totalBytes} bytes; this file does not fit`, limits.totalBytes);
+            let row;
+            let version;
+            if (input.artifactId !== undefined) {
+                const prior = await readableArtifact(t, input.artifactId, access, { lock: true });
+                version = {
+                    artifactId: prior.id,
+                    version: prior.latestVersion + 1,
+                    blobKey: key,
+                    size: stored.size,
+                    sha256: stored.sha256,
+                    contentType,
+                    source: input.source,
+                    createdAt,
+                };
+                await t.insertArtifactVersion(version);
+                row = {
+                    ...prior,
+                    latestVersion: version.version,
+                    contentType: version.contentType,
+                    updatedAt: createdAt,
+                };
+            }
+            else {
+                row = {
+                    id: artifactId,
+                    kind: "file",
+                    name: name,
+                    contentType,
+                    sessionId,
+                    latestVersion: 1,
+                    labelsJson: input.labels === undefined || Object.keys(input.labels).length === 0
+                        ? null
+                        : JSON.stringify(input.labels),
+                    createdAt,
+                    updatedAt: createdAt,
+                };
+                version = {
+                    artifactId,
+                    version: 1,
+                    blobKey: key,
+                    size: stored.size,
+                    sha256: stored.sha256,
+                    contentType,
+                    source: input.source,
+                    createdAt,
+                };
+                await t.insertArtifact(row, version);
+            }
+            if (session)
+                await t.event(session.id, input.turnId ?? null, version.version === 1 ? "artifact.created" : "artifact.version.created", {
+                    artifactId: row.id,
+                    kind: "file",
+                    name: row.name,
+                    contentType: version.contentType,
+                    version: version.version,
+                    size: version.size,
+                    sha256: version.sha256,
+                    source: version.source,
+                    ...(input.callId === undefined ? {} : { callId: input.callId }),
+                });
+            return { artifact: artifactView(row), version: versionView(version) };
+        });
+    }
+    catch (error) {
+        // Nothing references the object: it was garbage from the start.
+        await ctx.blobs.delete(key).catch(() => undefined);
+        throw error;
+    }
+}
+/** The caller's artifacts: of one session, or of every session it reaches. */
+export async function listArtifacts(ctx, filter, access) {
+    return ctx.store.tx(async (t) => {
+        if (filter.sessionId !== undefined) {
+            await sessionOf(t, filter.sessionId, access);
+            return { artifacts: (await t.listArtifacts({ sessionId: filter.sessionId })).map((row) => artifactView(row)) };
+        }
+        const rows = await t.listArtifacts();
+        if (access === undefined)
+            return { artifacts: rows.map((row) => artifactView(row)) };
+        const owned = new Map();
+        const reachable = [];
+        for (const row of rows) {
+            if (row.sessionId === null)
+                continue;
+            let ok = owned.get(row.sessionId);
+            if (ok === undefined) {
+                ok = await sessionOf(t, row.sessionId, access).then(() => true, () => false);
+                owned.set(row.sessionId, ok);
+            }
+            if (ok)
+                reachable.push(row);
+        }
+        return { artifacts: reachable.map((row) => artifactView(row)) };
+    });
+}
+/** One artifact with every version. */
+export async function getArtifact(ctx, id, access) {
+    return ctx.store.tx(async (t) => {
+        const row = await readableArtifact(t, id, access);
+        return artifactView(row, await t.artifactVersions(row.id));
+    });
+}
+/** One version's row, for a download. */
+export async function artifactContent(ctx, id, version, access) {
+    return ctx.store.tx(async (t) => {
+        const artifact = await readableArtifact(t, id, access);
+        return { artifact, version: await versionOf(t, artifact, version) };
+    });
+}
+/** One version's row, its artifact and, for a folder, its manifest; a file is a 400. */
+export async function folderContent(ctx, id, version, access) {
+    const found = await artifactContent(ctx, id, version, access);
+    if (found.artifact.kind !== "folder")
+        fail(400, `Artifact ${found.artifact.id} is a file; download its content`);
+    return { ...found, manifest: await readManifest(ctx.blobs, found.version) };
+}
+/**
+ * Deletes the artifact and every version: its rows and, for a session's artifact, its
+ * `artifact.deleted` event in one transaction, then its bytes. A folder's content-addressed
+ * files go too, those no other version names, under the quota lock (`folders.ts`).
+ */
+export async function deleteArtifact(ctx, id, access) {
+    const keys = await ctx.store.tx(async (t) => {
+        const found = await readableArtifact(t, id, access);
+        if (found.sessionId !== null)
+            await lockedSession(t, found.sessionId, access);
+        if (found.kind === "folder")
+            await t.lockArtifactQuota();
+        const row = await readableArtifact(t, id, access, { lock: true });
+        const content = row.kind === "folder" ? await t.artifactContentShas({ artifactId: row.id }) : [];
+        const keys = await t.deleteArtifact(row.id);
+        await collectContent(ctx.blobs, t, content);
+        if (row.sessionId !== null)
+            await t.event(row.sessionId, null, "artifact.deleted", { artifactId: row.id, name: row.name });
+        return keys;
+    });
+    for (const key of keys)
+        await ctx.blobs.delete(key).catch(() => undefined);
+    return { artifactId: id, deleted: true };
+}

package/dist/artifacts/workspace.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The `WorkspaceReader` seam (F8.2): how core reads a session's sandbox workspace at turn end, to
+ * export its outputs as a folder artifact. Two calls, a listing and one file's bytes, both the
+ * claim of whoever holds the workspace: the Runtime stores what it is given without observing it.
+ *
+ * One implementation, `sandboxWorkspaceReader`, over the workspace capability (F6.2,
+ * `harness-api/workspace.ts`): the in-process `SandboxManager`, or the harness that serves the
+ * Tenant's workspaces (`workspace.read`). F6.2 reimplements it over the Harness API's `workspace.read`, and F7.2's pod
+ * sandboxes are read through the same seam, so the export never knows which kind of sandbox it
+ * reads.
+ */
+import { type AgentManifest } from "@nylorun/core/define";
+import { type SandboxManager } from "../sandbox/manager.js";
+/** What the reader needs of a workspace: a `SandboxManager`, or the workspace capability. */
+export type WorkspaceFiles = Pick<SandboxManager, "listFiles" | "readBytes">;
+/** Whose workspace to read: the session whose turn ended, resolved to the workspace it uses. */
+export interface WorkspaceSession {
+    /** The session whose turn ended. */
+    readonly sessionId: string;
+    /** The turn that ended. */
+    readonly turnId: string | null;
+    /** The session that owns the workspace (one hop through `sandboxOwnerId`). */
+    readonly ownerId: string;
+    /** The sandbox resource the workspace belongs to, when the owner is attached to one. */
+    readonly sandboxId?: string;
+    /** The session's pinned manifest: its sandbox capability carries the sandbox's spec. */
+    readonly manifest: AgentManifest;
+}
+/** One regular file under the listed directory. */
+export interface WorkspaceEntry {
+    /** Relative to the directory listed, `/`-separated, never `.` or `..` segments. */
+    readonly path: string;
+    readonly size: number;
+}
+export interface WorkspaceListing {
+    /** The files in path order, symbolic links left out. */
+    readonly entries: readonly WorkspaceEntry[];
+    /** More than `maxEntries` files: `entries` holds `maxEntries + 1` of them. */
+    readonly truncated: boolean;
+}
+export interface WorkspaceReader {
+    /**
+     * The regular files under `dir` (absolute, e.g. `/workspace/outputs`), recursively. Undefined
+     * when the session has no sandbox, its sandbox was never created, or `dir` is not a directory.
+     */
+    list(session: WorkspaceSession, dir: string, options: {
+        readonly maxEntries: number;
+        readonly signal: AbortSignal;
+    }): Promise<WorkspaceListing | undefined>;
+    /**
+     * One file's bytes (absolute path), or undefined when it is gone. A file larger than
+     * `maxBytes` throws `SandboxFileTooLargeError`; a sandbox that fails throws.
+     */
+    readBytes(session: WorkspaceSession, path: string, options: {
+        readonly maxBytes: number;
+        readonly signal: AbortSignal;
+    }): Promise<Uint8Array | undefined>;
+}
+/** The reader over the workspaces, in each sandbox's queue of tool calls. */
+export declare function sandboxWorkspaceReader(sandbox: WorkspaceFiles): WorkspaceReader;

package/dist/artifacts/workspace.js

@@ -0,0 +1,57 @@
+/**
+ * The `WorkspaceReader` seam (F8.2): how core reads a session's sandbox workspace at turn end, to
+ * export its outputs as a folder artifact. Two calls, a listing and one file's bytes, both the
+ * claim of whoever holds the workspace: the Runtime stores what it is given without observing it.
+ *
+ * One implementation, `sandboxWorkspaceReader`, over the workspace capability (F6.2,
+ * `harness-api/workspace.ts`): the in-process `SandboxManager`, or the harness that serves the
+ * Tenant's workspaces (`workspace.read`). F6.2 reimplements it over the Harness API's `workspace.read`, and F7.2's pod
+ * sandboxes are read through the same seam, so the export never knows which kind of sandbox it
+ * reads.
+ */
+import { SANDBOX_CAPABILITY_ID, } from "@nylorun/core/define";
+import { sandboxCapabilityOf } from "../sandbox/manager.js";
+import { SandboxFileTooLargeError } from "../sandbox/types.js";
+/** The reader over the workspaces, in each sandbox's queue of tool calls. */
+export function sandboxWorkspaceReader(sandbox) {
+    const target = (session) => {
+        const capability = sandboxCapabilityOf(session.manifest, SANDBOX_CAPABILITY_ID, "read");
+        if (!capability)
+            return undefined;
+        return {
+            capability,
+            ref: {
+                id: session.ownerId,
+                activeTurnId: session.turnId,
+                manifest: session.manifest,
+                ...(session.sandboxId === undefined ? {} : { sandboxId: session.sandboxId }),
+            },
+        };
+    };
+    return {
+        async list(session, dir, options) {
+            const found = target(session);
+            if (!found)
+                return undefined;
+            const listed = await sandbox.listFiles(found.ref, found.capability, dir, options.maxEntries, options.signal);
+            if (listed.kind === "missing")
+                return undefined;
+            if (listed.kind === "failed")
+                throw new Error(listed.message);
+            return listed.listing;
+        },
+        async readBytes(session, path, options) {
+            const found = target(session);
+            if (!found)
+                return undefined;
+            const read = await sandbox.readBytes(found.ref, found.capability, path, options.maxBytes, options.signal);
+            if (read.kind === "read")
+                return read.bytes;
+            if (read.kind === "missing")
+                return undefined;
+            if (read.code === "artifact.too_large")
+                throw new SandboxFileTooLargeError(path, options.maxBytes + 1, options.maxBytes);
+            throw new Error(read.message);
+        },
+    };
+}

package/dist/artifacts/zip.d.ts

@@ -0,0 +1,10 @@
+export interface ZipEntry {
+    /** The path in the archive, `/`-separated. */
+    readonly name: string;
+    /** The file's bytes, opened only when the writer reaches it. */
+    readonly open: () => Promise<AsyncIterable<Uint8Array>>;
+}
+/** Why a folder cannot be zipped without ZIP64, or undefined when it can. */
+export declare function zipTooLarge(files: number, bytes: number): string | undefined;
+/** The archive's bytes, as the writer produces them. */
+export declare function zipStream(entries: readonly ZipEntry[], modified?: Date): AsyncGenerator<Uint8Array>;

package/dist/artifacts/zip.js

@@ -0,0 +1,126 @@
+/**
+ * A streaming zip writer (PKWARE APPNOTE 6.3), enough for a folder artifact's download: each
+ * file deflated as it streams, its CRC-32 and sizes in a data descriptor after it (general
+ * purpose bit 3) and again in the central directory, names in UTF-8 (bit 11). Nothing is
+ * buffered beyond one chunk. No ZIP64: a folder this serves stays under 4 GiB and 65,535 files
+ * (the export's limits), and `zipTooLarge` says when one would not.
+ */
+import { constants, crc32, createDeflateRaw } from "node:zlib";
+const LOCAL = 0x04034b50;
+const DESCRIPTOR = 0x08074b50;
+const CENTRAL = 0x02014b50;
+const END = 0x06054b50;
+const FLAGS = 0x0808; // bit 3: sizes in a data descriptor; bit 11: UTF-8 names
+const DEFLATE = 8;
+const VERSION = 20;
+/** Made by Unix (3), so the external attributes below are a Unix mode. */
+const MADE_BY_UNIX = (3 << 8) | VERSION;
+/** A regular file, `rw-r--r--`, in the high 16 bits. */
+const REGULAR_FILE = (0o100644 << 16) >>> 0;
+const MAX_32 = 0xffffffff;
+/** Why a folder cannot be zipped without ZIP64, or undefined when it can. */
+export function zipTooLarge(files, bytes) {
+    if (files > 0xffff)
+        return `A zip holds at most 65535 files; this folder has ${files}`;
+    // Deflate adds at most 5 bytes per 16 KiB block; keep well clear of 4 GiB.
+    if (bytes > 3.5 * 1024 * 1024 * 1024)
+        return `A zip holds at most 3.5 GiB; this folder has ${bytes} bytes`;
+    return undefined;
+}
+/** MS-DOS date and time, as zip headers store them (local time is not known: UTC). */
+function dosDateTime(date) {
+    const year = Math.max(1980, date.getUTCFullYear());
+    return {
+        time: (date.getUTCHours() << 11) | (date.getUTCMinutes() << 5) | (date.getUTCSeconds() >> 1),
+        date: ((year - 1980) << 9) | ((date.getUTCMonth() + 1) << 5) | date.getUTCDate(),
+    };
+}
+/** The archive's bytes, as the writer produces them. */
+export async function* zipStream(entries, modified = new Date()) {
+    const stamp = dosDateTime(modified);
+    const central = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const name = Buffer.from(entry.name, "utf8");
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(LOCAL, 0);
+        local.writeUInt16LE(VERSION, 4);
+        local.writeUInt16LE(FLAGS, 6);
+        local.writeUInt16LE(DEFLATE, 8);
+        local.writeUInt16LE(stamp.time, 10);
+        local.writeUInt16LE(stamp.date, 12);
+        // CRC and sizes (14–25) are zero: they follow in the data descriptor.
+        local.writeUInt16LE(name.length, 26);
+        local.writeUInt16LE(0, 28);
+        const headerAt = offset;
+        yield local;
+        yield name;
+        offset += local.length + name.length;
+        let crc = 0;
+        let size = 0;
+        let compressed = 0;
+        const deflate = createDeflateRaw({ level: constants.Z_DEFAULT_COMPRESSION });
+        const source = await entry.open();
+        const feed = (async () => {
+            try {
+                for await (const chunk of source) {
+                    // The reader went away (a cancelled download): stop reading the file.
+                    if (deflate.destroyed)
+                        break;
+                    crc = crc32(chunk, crc);
+                    size += chunk.length;
+                    if (!deflate.write(chunk))
+                        await new Promise((resolve) => {
+                            deflate.once("drain", resolve);
+                            deflate.once("close", resolve);
+                        });
+                }
+                if (!deflate.destroyed)
+                    deflate.end();
+            }
+            catch (error) {
+                deflate.destroy(error);
+            }
+        })();
+        for await (const chunk of deflate) {
+            compressed += chunk.length;
+            yield chunk;
+        }
+        await feed;
+        offset += compressed;
+        if (offset > MAX_32 || size > MAX_32)
+            throw new Error("The folder is too large to zip without ZIP64");
+        const descriptor = Buffer.alloc(16);
+        descriptor.writeUInt32LE(DESCRIPTOR, 0);
+        descriptor.writeUInt32LE(crc >>> 0, 4);
+        descriptor.writeUInt32LE(compressed, 8);
+        descriptor.writeUInt32LE(size, 12);
+        yield descriptor;
+        offset += descriptor.length;
+        const record = Buffer.alloc(46);
+        record.writeUInt32LE(CENTRAL, 0);
+        record.writeUInt16LE(MADE_BY_UNIX, 4);
+        record.writeUInt16LE(VERSION, 6);
+        record.writeUInt16LE(FLAGS, 8);
+        record.writeUInt16LE(DEFLATE, 10);
+        record.writeUInt16LE(stamp.time, 12);
+        record.writeUInt16LE(stamp.date, 14);
+        record.writeUInt32LE(crc >>> 0, 16);
+        record.writeUInt32LE(compressed, 20);
+        record.writeUInt32LE(size, 24);
+        record.writeUInt16LE(name.length, 28);
+        // Extra, comment, disk and internal attributes (30–37) stay zero.
+        record.writeUInt32LE(REGULAR_FILE, 38);
+        record.writeUInt32LE(headerAt, 42);
+        central.push(record, name);
+    }
+    const directory = Buffer.concat(central);
+    yield directory;
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(END, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(directory.length, 12);
+    end.writeUInt32LE(offset, 16);
+    yield end;
+}

package/dist/blob/fs.d.ts

@@ -0,0 +1,13 @@
+import { type BlobStore } from "./types.js";
+export interface FsBlobStoreOptions {
+    /** Absolute directory the store owns; created on the first write. */
+    root: string;
+}
+/**
+ * The `fs` adapter: objects as files under `root`, for embedding (`startEphemeralRuntime`, a
+ * Host without an Object store) and tests. `objects/<key>` holds the bytes, `meta/<key>.json`
+ * the content type; a write goes to `tmp/` first and is renamed into place, so a reader sees
+ * the old object or the new one, never part of one. A key cannot also be the directory of
+ * another key (`a` and `a/b`); the Runtime's keys never are.
+ */
+export declare function createFsBlobStore(options: FsBlobStoreOptions): BlobStore;