@nylorun/runtime 0.15.2-beta → 0.17.0-beta

package/dist/artifacts/config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A Tenant's artifact configuration, stored as Tenant setting `artifacts.config`: the largest
+ * file one upload may store and the most bytes every artifact version together may hold.
+ * Unset limits take the defaults (100 MiB and 10 GiB).
+ */
+import { type TenantArtifactsConfig } from "@nylorun/core/contracts";
+export declare const ARTIFACTS_CONFIG_SETTING = "artifacts.config";
+export interface ArtifactLimits {
+    readonly fileBytes: number;
+    readonly totalBytes: number;
+}
+interface SettingsReader {
+    getSetting(key: string): Promise<string | undefined>;
+}
+interface SettingsWriter extends SettingsReader {
+    putSetting(key: string, value: string): Promise<void>;
+}
+/** The limits in force: the Tenant's, with the defaults for what it leaves unset. */
+export declare function effectiveArtifactLimits(config: TenantArtifactsConfig): ArtifactLimits;
+export declare function readArtifactsConfig(t: SettingsReader): Promise<TenantArtifactsConfig>;
+export declare function readArtifactLimits(t: SettingsReader): Promise<ArtifactLimits>;
+export declare function writeArtifactsConfig(t: SettingsWriter, config: TenantArtifactsConfig): Promise<void>;
+export {};

package/dist/artifacts/config.js

@@ -0,0 +1,27 @@
+/**
+ * A Tenant's artifact configuration, stored as Tenant setting `artifacts.config`: the largest
+ * file one upload may store and the most bytes every artifact version together may hold.
+ * Unset limits take the defaults (100 MiB and 10 GiB).
+ */
+import { ARTIFACT_FILE_BYTES_DEFAULT, ARTIFACT_TOTAL_BYTES_DEFAULT, TenantArtifactsConfigSchema, } from "@nylorun/core/contracts";
+export const ARTIFACTS_CONFIG_SETTING = "artifacts.config";
+/** The limits in force: the Tenant's, with the defaults for what it leaves unset. */
+export function effectiveArtifactLimits(config) {
+    return {
+        fileBytes: config.limits?.fileBytes ?? ARTIFACT_FILE_BYTES_DEFAULT,
+        totalBytes: config.limits?.totalBytes ?? ARTIFACT_TOTAL_BYTES_DEFAULT,
+    };
+}
+export async function readArtifactsConfig(t) {
+    const raw = await t.getSetting(ARTIFACTS_CONFIG_SETTING);
+    if (raw === undefined)
+        return {};
+    const parsed = TenantArtifactsConfigSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : {};
+}
+export async function readArtifactLimits(t) {
+    return effectiveArtifactLimits(await readArtifactsConfig(t));
+}
+export async function writeArtifactsConfig(t, config) {
+    await t.putSetting(ARTIFACTS_CONFIG_SETTING, JSON.stringify(TenantArtifactsConfigSchema.parse(config)));
+}

package/dist/artifacts/export.d.ts

@@ -0,0 +1,8 @@
+import { type TenantContext } from "../tenant/context.js";
+/** The directory every sandbox's outputs are exported from. */
+export declare const OUTPUTS_DIR = "/workspace/outputs";
+/**
+ * Exports the outputs of turn `turnId` of session `sessionId`, if it completed and its sandbox
+ * has any. Never throws.
+ */
+export declare function exportOutputs(ctx: TenantContext, sessionId: string, turnId: string | null, signal: AbortSignal): Promise<void>;

package/dist/artifacts/export.js

@@ -0,0 +1,205 @@
+/**
+ * The turn-end export (F8.2): when an agent's turn completes, core reads `/workspace/outputs` of
+ * the session's sandbox through the `WorkspaceReader` seam and keeps it as a version of the
+ * session's folder artifact `outputs` (the first export creates it; later turns add versions,
+ * and a turn whose outputs did not change adds none).
+ *
+ * - **After the turn.** The advance calls `exportOutputs` once `settle` has committed the turn,
+ *   outside its transaction and while it still holds the session's lease, so the next turn
+ *   cannot change the workspace under it. Nothing here fails the turn: a sandbox or store
+ *   failure is logged and recorded as `artifact.export.failed`.
+ * - **Claimed.** The listing and the bytes are what the holder of the workspace supplied: the
+ *   version's source is `export` and its event says `claimed: true`.
+ * - **Bounded.** At most `EXPORT_MAX_FILES` files and `EXPORT_MAX_BYTES` bytes per export, each
+ *   file within the Tenant's per-file limit, and the new bytes within its total; past any of
+ *   them nothing is stored and `artifact.export.skipped` says why.
+ * - **Deduplicated.** Each file is stored content-addressed (`folders.ts`); a file the store
+ *   already holds is not stored again.
+ *
+ * No sandbox, a sandbox never created, or an empty or missing `/workspace/outputs` exports
+ * nothing and records nothing. The package's declared outputs are left for later: the manifest
+ * has no `outputs` field yet.
+ */
+import { posix } from "node:path";
+import { EXPORT_MAX_BYTES, EXPORT_MAX_FILES, OUTPUTS_ARTIFACT_NAME, } from "@nylorun/core/contracts";
+import { SANDBOX_WORKSPACE } from "@nylorun/core/define";
+import { isWorkflowManifest } from "../core/flow-host.js";
+import { sandboxWorkspaceOf } from "../sandbox/share.js";
+import { SandboxFileTooLargeError } from "../sandbox/types.js";
+import { sandboxLookup } from "../tenant/context.js";
+import { readArtifactLimits } from "./config.js";
+import { collectContent, commitFolderVersion, contentEpoch, contentKey, encodeManifest, FolderCommitRefused, sha256Hex, } from "./folders.js";
+import { contentTypeFor } from "./media-types.js";
+/** The directory every sandbox's outputs are exported from. */
+export const OUTPUTS_DIR = `${SANDBOX_WORKSPACE}/outputs`;
+/** Stops the export with `artifact.export.skipped`. */
+class Skip extends Error {
+    reason;
+    limit;
+    path;
+    constructor(reason, message, limit, path) {
+        super(message);
+        this.reason = reason;
+        this.limit = limit;
+        this.path = path;
+    }
+}
+/**
+ * Exports the outputs of turn `turnId` of session `sessionId`, if it completed and its sandbox
+ * has any. Never throws.
+ */
+export async function exportOutputs(ctx, sessionId, turnId, signal) {
+    try {
+        await runExport(ctx, sessionId, turnId, signal);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (signal.aborted) {
+            ctx.config.logger.info("outputs export stopped", { sessionId, message });
+            return;
+        }
+        const skip = error instanceof Skip
+            ? error
+            : error instanceof FolderCommitRefused && error.reason === "tenant_total"
+                ? new Skip("tenant_total", error.message, error.limit)
+                : undefined;
+        if (!skip)
+            ctx.config.logger.warn("outputs export failed", { sessionId, message });
+        try {
+            await ctx.store.tx(async (t) => {
+                if (skip)
+                    await t.event(sessionId, turnId, "artifact.export.skipped", {
+                        name: OUTPUTS_ARTIFACT_NAME,
+                        reason: skip.reason,
+                        message: skip.message,
+                        ...(skip.limit === undefined ? {} : { limit: skip.limit }),
+                        ...(skip.path === undefined ? {} : { path: skip.path }),
+                    });
+                else
+                    await t.event(sessionId, turnId, "artifact.export.failed", {
+                        name: OUTPUTS_ARTIFACT_NAME,
+                        message,
+                    });
+            });
+        }
+        catch {
+            /* the session is gone (reset) or the store closed */
+        }
+    }
+}
+async function runExport(ctx, sessionId, turnId, signal) {
+    const found = await ctx.store.tx(async (t) => {
+        const s = await t.get("sessions", sessionId);
+        // Only a turn that completed, and only an agent's (a flow agent's sandbox is its agents').
+        if (!s || s.status !== "completed" || s.lastTurnId !== turnId || isWorkflowManifest(s.manifest))
+            return undefined;
+        const workspace = sandboxWorkspaceOf(s, await sandboxLookup(t, s.id));
+        const prior = (await t.listArtifacts({ sessionId })).find((row) => row.kind === "folder" && row.name === OUTPUTS_ARTIFACT_NAME);
+        const latest = prior ? await t.artifactVersion(prior.id, prior.latestVersion) : undefined;
+        return {
+            session: {
+                sessionId,
+                turnId,
+                ownerId: workspace.ownerId,
+                ...(workspace.sandboxId === undefined ? {} : { sandboxId: workspace.sandboxId }),
+                manifest: s.manifest,
+            },
+            limits: await readArtifactLimits(t),
+            priorId: prior?.id,
+            latestSha: latest?.sha256,
+            epoch: await contentEpoch(t),
+        };
+    });
+    if (!found)
+        return;
+    const { session, limits } = found;
+    const listing = await ctx.workspaces.list(session, OUTPUTS_DIR, {
+        maxEntries: EXPORT_MAX_FILES,
+        signal,
+    });
+    if (!listing || listing.entries.length === 0)
+        return;
+    if (listing.truncated)
+        throw new Skip("too_many_files", `${OUTPUTS_DIR} holds more than ${EXPORT_MAX_FILES} files`, EXPORT_MAX_FILES);
+    const large = listing.entries.find((entry) => entry.size > limits.fileBytes);
+    if (large)
+        throw tooLargeFile(large.path, large.size, limits.fileBytes);
+    const maxBytes = Math.min(EXPORT_MAX_BYTES, limits.totalBytes);
+    const listed = listing.entries.reduce((sum, entry) => sum + entry.size, 0);
+    if (listed > maxBytes)
+        throw tooLarge(listed, maxBytes);
+    // The files this export stored: removed again if it commits nothing, unless another version
+    // names them by then.
+    const put = [];
+    try {
+        await storeAndCommit(ctx, found, listing.entries, maxBytes, put, signal);
+    }
+    catch (error) {
+        if (put.length > 0)
+            await ctx.store
+                .tx(async (t) => {
+                await t.lockArtifactQuota();
+                await collectContent(ctx.blobs, t, put);
+            })
+                .catch(() => undefined);
+        throw error;
+    }
+}
+async function storeAndCommit(ctx, found, listed, maxBytes, put, signal) {
+    const { session, limits } = found;
+    const { sessionId, turnId } = session;
+    const entries = [];
+    const stored = new Set();
+    let read = 0;
+    for (const entry of listed) {
+        let bytes;
+        try {
+            bytes = await ctx.workspaces.readBytes(session, posix.join(OUTPUTS_DIR, entry.path), {
+                maxBytes: limits.fileBytes,
+                signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof SandboxFileTooLargeError)
+                throw tooLargeFile(entry.path, error.size, limits.fileBytes);
+            throw error;
+        }
+        // Gone since the listing: the folder is what is there now.
+        if (bytes === undefined)
+            continue;
+        read += bytes.length;
+        if (read > maxBytes)
+            throw tooLarge(read, maxBytes);
+        const sha256 = sha256Hex(bytes);
+        const contentType = contentTypeFor(posix.basename(entry.path));
+        if (!stored.has(sha256)) {
+            stored.add(sha256);
+            const key = contentKey(sha256);
+            if (!(await ctx.blobs.head(key))) {
+                put.push(sha256);
+                await ctx.blobs.put(key, bytes, { contentType, signal });
+            }
+        }
+        entries.push({ path: entry.path, size: bytes.length, sha256, contentType });
+    }
+    // Every file vanished, or nothing changed since the last export: no new version.
+    if (entries.length === 0)
+        return;
+    if (found.latestSha !== undefined && sha256Hex(encodeManifest(entries)) === found.latestSha)
+        return;
+    await commitFolderVersion(ctx, {
+        sessionId,
+        turnId,
+        ...(found.priorId === undefined ? {} : { artifactId: found.priorId }),
+        name: OUTPUTS_ARTIFACT_NAME,
+        entries,
+        epoch: found.epoch,
+        totalBytes: limits.totalBytes,
+    });
+}
+function tooLargeFile(path, size, limit) {
+    return new Skip("file_too_large", `${OUTPUTS_DIR}/${path} is ${size} bytes; a file may hold at most ${limit}`, limit, path);
+}
+function tooLarge(bytes, limit) {
+    return new Skip("too_large", `${OUTPUTS_DIR} holds ${bytes} bytes; an export stores at most ${limit}`, limit);
+}

package/dist/artifacts/files.d.ts

@@ -0,0 +1,36 @@
+/**
+ * How model-gate reads the files a prompt names (protocol 6): a media part's reference is an
+ * artifact version (`./parts.ts`), resolved here to its bytes from the Object store. The gate
+ * holds the store credential; the loop and the transcript only ever hold the reference.
+ *
+ * It replaces `MediaStore`: images are file artifacts, and their bytes reach the provider only in
+ * the request model-gate builds.
+ */
+import type { JsonValue } from "@nylorun/core/define";
+import type { BlobStore } from "../blob/index.js";
+import type { SessionStore } from "../store/types.js";
+/** A file a prompt names, with its bytes. */
+export interface ResolvedFile {
+    readonly name: string;
+    /** The version's media type, as stored. */
+    readonly mediaType: string;
+    readonly bytes: Uint8Array;
+}
+/** Why a file cannot go to the model: the message is the outcome's, so it names no secret. */
+export declare class FileUnavailableError extends Error {
+    constructor(message: string);
+}
+/** Resolves a media part's reference to the file's bytes, or throws `FileUnavailableError`. */
+export type FileResolver = (reference: JsonValue) => Promise<ResolvedFile>;
+/**
+ * Files from the Tenant's artifacts: `store` for the version's row, `blobs` for its bytes, for
+ * the call of session `sessionId`. An artifact of another session is refused (a Tenant-wide one
+ * is not), and without a session every file is: the check is never skipped.
+ */
+export declare function artifactFiles(options: {
+    readonly store: SessionStore;
+    readonly blobs: BlobStore;
+    /** The session the call is for: the run token's, over HTTP. */
+    readonly sessionId: string | undefined;
+    readonly maxBytes?: number;
+}): FileResolver;

package/dist/artifacts/files.js

@@ -0,0 +1,45 @@
+import { MODEL_FILE_MAX_BYTES } from "./media-types.js";
+import { fileReferenceOf } from "./parts.js";
+/** Why a file cannot go to the model: the message is the outcome's, so it names no secret. */
+export class FileUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FileUnavailableError";
+    }
+}
+/**
+ * Files from the Tenant's artifacts: `store` for the version's row, `blobs` for its bytes, for
+ * the call of session `sessionId`. An artifact of another session is refused (a Tenant-wide one
+ * is not), and without a session every file is: the check is never skipped.
+ */
+export function artifactFiles(options) {
+    const maxBytes = options.maxBytes ?? MODEL_FILE_MAX_BYTES;
+    return async (value) => {
+        const reference = fileReferenceOf(value);
+        if (!reference)
+            throw new FileUnavailableError("Expected an artifact reference.");
+        const sessionId = options.sessionId;
+        if (typeof sessionId !== "string" || sessionId === "")
+            throw new FileUnavailableError("A model call reads files only for its own session.");
+        const found = await options.store.tx(async (t) => {
+            const artifact = await t.artifact(reference.artifactId);
+            if (!artifact)
+                return undefined;
+            const version = await t.artifactVersion(artifact.id, reference.version);
+            return version ? { artifact, version } : undefined;
+        });
+        if (!found ||
+            (found.artifact.sessionId !== null && found.artifact.sessionId !== sessionId))
+            throw new FileUnavailableError(`Artifact ${reference.artifactId} version ${reference.version} is not available.`);
+        const { artifact, version } = found;
+        if (artifact.kind !== "file")
+            throw new FileUnavailableError(`${artifact.name} is a folder; a model reads files only.`);
+        if (version.size > maxBytes)
+            throw new FileUnavailableError(`${artifact.name} is ${version.size} bytes; a model reads files of at most ${maxBytes} bytes.`);
+        const got = await options.blobs.get(version.blobKey);
+        if (!got)
+            throw new FileUnavailableError(`The bytes of ${artifact.name} are missing from the Object store.`);
+        const bytes = new Uint8Array(await new Response(got.body).arrayBuffer());
+        return { name: artifact.name, mediaType: version.contentType, bytes };
+    };
+}

package/dist/artifacts/folders.d.ts

@@ -0,0 +1,60 @@
+import type { ArtifactDiff, FolderEntry, FolderManifest } from "@nylorun/core/contracts";
+import type { BlobStore } from "../blob/index.js";
+import type { ArtifactRow, ArtifactVersionRow, Tx } from "../store/types.js";
+import { type TenantContext } from "../tenant/context.js";
+/** Where a folder file's bytes are: content-addressed by their SHA-256. */
+export declare function contentKey(sha256: string): string;
+export declare function sha256Hex(bytes: Uint8Array): string;
+/** Entries in manifest order: by path, comparing UTF-16 code units. */
+export declare function sortEntries(entries: readonly FolderEntry[]): FolderEntry[];
+/** The manifest's bytes, as stored: deterministic for the same entries. */
+export declare function encodeManifest(entries: readonly FolderEntry[]): Uint8Array;
+/** A folder version's manifest, read from the Object store. */
+export declare function readManifest(blobs: BlobStore, version: ArtifactVersionRow): Promise<FolderManifest>;
+/** The entry at `path`, or the 404 of a missing file. */
+export declare function entryAt(manifest: FolderManifest, path: string): FolderEntry;
+/** What changed from `from` (absent: nothing) to `to`. */
+export declare function diffManifests(artifactId: string, from: {
+    version: number;
+    manifest: FolderManifest;
+} | undefined, to: {
+    version: number;
+    manifest: FolderManifest;
+}): ArtifactDiff;
+/** The Tenant's content epoch: moves whenever content-addressed files are deleted. */
+export declare function contentEpoch(t: Tx): Promise<number>;
+/**
+ * Deletes those of `shas` no committed folder version references any more, and moves the content
+ * epoch when it deletes any. Call it in a transaction holding the quota lock, after the rows that
+ * named them are gone: the deletes happen before the transaction commits, under the lock.
+ */
+export declare function collectContent(blobs: BlobStore, t: Tx, shas: readonly string[]): Promise<number>;
+/** The commit could not go ahead: a limit, or content removed while the export ran. */
+export declare class FolderCommitRefused extends Error {
+    readonly reason: "tenant_total" | "content_gone" | "artifact_gone";
+    readonly limit?: number | undefined;
+    constructor(message: string, reason: "tenant_total" | "content_gone" | "artifact_gone", limit?: number | undefined);
+}
+export interface FolderVersionInput {
+    readonly sessionId: string;
+    readonly turnId: string | null;
+    /** A new version of this folder of the session; otherwise a new folder named `name`. */
+    readonly artifactId?: string;
+    readonly name: string;
+    /** Every file, each one's bytes already at `contentKey(sha256)`. */
+    readonly entries: readonly FolderEntry[];
+    /** The content epoch read before the first `head` of those bytes. */
+    readonly epoch: number;
+    /** The Tenant total in force. */
+    readonly totalBytes: number;
+}
+/**
+ * Commits a folder version whose files are already stored: its manifest to the Object store,
+ * then, in one transaction under the session and quota locks, the version row, its content rows
+ * and `artifact.created` or `artifact.version.created` (`claimed: true`, source `export`).
+ * Throws `FolderCommitRefused` when the Tenant total would be passed or a file is gone.
+ */
+export declare function commitFolderVersion(ctx: TenantContext, input: FolderVersionInput): Promise<{
+    artifact: ArtifactRow;
+    version: ArtifactVersionRow;
+}>;

package/dist/artifacts/folders.js

@@ -0,0 +1,209 @@
+/**
+ * Folder artifacts (blueprint D35, F8.2). A folder version is a **manifest**: JSON
+ * `{ format, entries: [{ path, size, sha256, contentType }] }`, sorted by path, stored in the
+ * Object store under the version's `blobKey` like a file's bytes. Each file's bytes are stored
+ * once, content-addressed, at `blobs/sha256/<hex>`: a file that did not change between versions,
+ * or that two folders share, is stored and counted once.
+ *
+ * Which content-addressed files are in use is indexed in Postgres (`artifact_content`, a row per
+ * folder version and distinct hash), so deleting a folder removes only the files nothing else
+ * names, and the Tenant total counts each file once.
+ *
+ * **Collecting content safely.** A writer skips the `put` of a file the store already has
+ * (`head`), outside any lock, and a delete could remove that file before the writer commits. So:
+ * content is deleted only while holding the quota lock, and every such delete moves the Tenant's
+ * content epoch (setting `artifacts.content_epoch`) in the same transaction. A writer reads the
+ * epoch before its first `head`; at commit, under the quota lock, a file some committed version
+ * references is present (the invariant the lock keeps), and when the epoch moved it checks the
+ * others again and refuses to commit a version naming a file that is gone.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { FOLDER_CONTENT_TYPE, FOLDER_MANIFEST_FORMAT, FolderManifestSchema, } from "@nylorun/core/contracts";
+import { newArtifactId } from "@nylorun/core/compatibility";
+import { lockedSession } from "../tenant/context.js";
+import { fail } from "../tenant/http.js";
+const CONTENT_EPOCH_SETTING = "artifacts.content_epoch";
+/** Where a folder file's bytes are: content-addressed by their SHA-256. */
+export function contentKey(sha256) {
+    return `blobs/sha256/${sha256}`;
+}
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Entries in manifest order: by path, comparing UTF-16 code units. */
+export function sortEntries(entries) {
+    return [...entries].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+/** The manifest's bytes, as stored: deterministic for the same entries. */
+export function encodeManifest(entries) {
+    const manifest = {
+        format: FOLDER_MANIFEST_FORMAT,
+        entries: sortEntries(entries).map(({ path, size, sha256, contentType }) => ({
+            path,
+            size,
+            sha256,
+            contentType,
+        })),
+    };
+    return new TextEncoder().encode(JSON.stringify(manifest));
+}
+/** A folder version's manifest, read from the Object store. */
+export async function readManifest(blobs, version) {
+    const got = await blobs.get(version.blobKey);
+    if (!got)
+        return fail(404, "Artifact bytes not found");
+    const parsed = FolderManifestSchema.safeParse(JSON.parse(await new Response(got.body).text()));
+    if (!parsed.success)
+        throw new Error(`The manifest of ${version.artifactId} v${version.version} is malformed`);
+    return parsed.data;
+}
+/** The entry at `path`, or the 404 of a missing file. */
+export function entryAt(manifest, path) {
+    return (manifest.entries.find((entry) => entry.path === path) ??
+        fail(404, `No file ${path} in this folder version`));
+}
+/** What changed from `from` (absent: nothing) to `to`. */
+export function diffManifests(artifactId, from, to) {
+    const before = new Map((from?.manifest.entries ?? []).map((entry) => [entry.path, entry]));
+    const after = new Map(to.manifest.entries.map((entry) => [entry.path, entry]));
+    const added = [];
+    const changed = [];
+    for (const entry of to.manifest.entries) {
+        const prior = before.get(entry.path);
+        if (!prior)
+            added.push(entry);
+        else if (prior.sha256 !== entry.sha256 || prior.contentType !== entry.contentType)
+            changed.push({ path: entry.path, from: prior, to: entry });
+    }
+    const removed = (from?.manifest.entries ?? []).filter((entry) => !after.has(entry.path));
+    return {
+        artifactId,
+        ...(from === undefined ? {} : { from: from.version }),
+        to: to.version,
+        added,
+        removed,
+        changed,
+    };
+}
+/** The Tenant's content epoch: moves whenever content-addressed files are deleted. */
+export async function contentEpoch(t) {
+    const raw = await t.getSetting(CONTENT_EPOCH_SETTING);
+    return raw === undefined ? 0 : Number(raw);
+}
+/**
+ * Deletes those of `shas` no committed folder version references any more, and moves the content
+ * epoch when it deletes any. Call it in a transaction holding the quota lock, after the rows that
+ * named them are gone: the deletes happen before the transaction commits, under the lock.
+ */
+export async function collectContent(blobs, t, shas) {
+    if (shas.length === 0)
+        return 0;
+    const referenced = await t.referencedArtifactContent(shas);
+    const orphans = shas.filter((sha) => !referenced.has(sha));
+    if (orphans.length === 0)
+        return 0;
+    await t.putSetting(CONTENT_EPOCH_SETTING, String((await contentEpoch(t)) + 1));
+    for (const sha of orphans)
+        await blobs.delete(contentKey(sha));
+    return orphans.length;
+}
+/** The commit could not go ahead: a limit, or content removed while the export ran. */
+export class FolderCommitRefused extends Error {
+    reason;
+    limit;
+    constructor(message, reason, limit) {
+        super(message);
+        this.reason = reason;
+        this.limit = limit;
+        this.name = "FolderCommitRefused";
+    }
+}
+/**
+ * Commits a folder version whose files are already stored: its manifest to the Object store,
+ * then, in one transaction under the session and quota locks, the version row, its content rows
+ * and `artifact.created` or `artifact.version.created` (`claimed: true`, source `export`).
+ * Throws `FolderCommitRefused` when the Tenant total would be passed or a file is gone.
+ */
+export async function commitFolderVersion(ctx, input) {
+    const entries = sortEntries(input.entries);
+    const manifest = encodeManifest(entries);
+    const sha256 = sha256Hex(manifest);
+    const files = new Map();
+    for (const entry of entries)
+        files.set(entry.sha256, entry.size);
+    const size = entries.reduce((sum, entry) => sum + entry.size, 0);
+    const artifactId = input.artifactId ?? newArtifactId();
+    const key = `artifacts/${artifactId}/${randomUUID()}`;
+    await ctx.blobs.put(key, manifest, { contentType: FOLDER_CONTENT_TYPE });
+    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).
+            await lockedSession(t, input.sessionId);
+            await t.lockArtifactQuota();
+            const shas = [...files.keys()];
+            const referenced = await t.referencedArtifactContent(shas);
+            const fresh = shas.filter((sha) => !referenced.has(sha));
+            if ((await contentEpoch(t)) !== input.epoch)
+                for (const sha of fresh)
+                    if (!(await ctx.blobs.head(contentKey(sha))))
+                        throw new FolderCommitRefused("A file's bytes were removed while the export ran", "content_gone");
+            const added = fresh.reduce((sum, sha) => sum + files.get(sha), 0);
+            const total = await t.artifactBytes();
+            if (total + added > input.totalBytes)
+                throw new FolderCommitRefused(`The Tenant's artifacts may hold at most ${input.totalBytes} bytes; these outputs add ${added} to ${total}`, "tenant_total", input.totalBytes);
+            let row;
+            const version = {
+                artifactId,
+                version: 1,
+                blobKey: key,
+                size,
+                sha256,
+                contentType: FOLDER_CONTENT_TYPE,
+                source: "export",
+                createdAt,
+            };
+            if (input.artifactId !== undefined) {
+                const prior = await t.artifact(input.artifactId, { lock: true });
+                if (!prior || prior.kind !== "folder" || prior.sessionId !== input.sessionId)
+                    throw new FolderCommitRefused("The folder was deleted while the export ran", "artifact_gone");
+                version.version = prior.latestVersion + 1;
+                await t.insertArtifactVersion(version);
+                row = { ...prior, latestVersion: version.version, contentType: FOLDER_CONTENT_TYPE, updatedAt: createdAt };
+            }
+            else {
+                row = {
+                    id: artifactId,
+                    kind: "folder",
+                    name: input.name,
+                    contentType: FOLDER_CONTENT_TYPE,
+                    sessionId: input.sessionId,
+                    latestVersion: 1,
+                    labelsJson: null,
+                    createdAt,
+                    updatedAt: createdAt,
+                };
+                await t.insertArtifact(row, version);
+            }
+            await t.insertArtifactContent(artifactId, version.version, shas.map((sha) => ({ sha256: sha, size: files.get(sha) })));
+            await t.event(input.sessionId, input.turnId, version.version === 1 ? "artifact.created" : "artifact.version.created", {
+                artifactId,
+                kind: "folder",
+                name: row.name,
+                contentType: FOLDER_CONTENT_TYPE,
+                version: version.version,
+                size,
+                sha256,
+                source: "export",
+                fileCount: entries.length,
+                claimed: true,
+            });
+            return { artifact: row, version };
+        });
+    }
+    catch (error) {
+        // Nothing references the manifest: it was garbage from the start.
+        await ctx.blobs.delete(key).catch(() => undefined);
+        throw error;
+    }
+}

package/dist/artifacts/links.d.ts

@@ -0,0 +1,28 @@
+import type { TenantContext } from "../tenant/context.js";
+/** The audience of every capability link. */
+export declare const ARTIFACT_LINK_AUDIENCE = "nylorun-artifact";
+/** Where a capability link is served: `GET /v1/artifact-links/<token>`. */
+export declare const ARTIFACT_LINK_PATH = "/v1/artifact-links";
+export interface MintedArtifactLink {
+    path: string;
+    artifactId: string;
+    version: number;
+    /** The folder's file the link opens. */
+    file?: string;
+    expiresAt: string;
+}
+export declare function mintArtifactLink(ctx: TenantContext, link: {
+    artifactId: string;
+    version: number;
+    expiresIn?: number;
+    file?: string;
+}): Promise<MintedArtifactLink>;
+/**
+ * The artifact version a capability link opens. An expired link, or one whose key was revoked,
+ * is `401 token_expired`; anything else that does not verify is the opaque 404.
+ */
+export declare function verifyArtifactLink(ctx: TenantContext, raw: string): Promise<{
+    artifactId: string;
+    version: number;
+    file?: string;
+}>;