@nylorun/runtime 0.15.2-beta → 0.17.0-beta

package/dist/artifacts/links.js

@@ -0,0 +1,92 @@
+/**
+ * Capability links (protocol 6): a short-lived URL that opens one artifact version with no
+ * other credential, for UIs, `<img>` tags and sharing. The token in the path is an ES256 JWT
+ * (`typ: nylorun-artifact+jwt`) signed with the Tenant's current signing key by the keys
+ * service, like delivery tokens: `sub` is the artifact, `ver` the version, `aud`
+ * `nylorun-artifact`, and it lives at most `ARTIFACT_LINK_MAX_TTL_SECONDS` (`TOKEN_TTL_MAX_SECONDS`,
+ * so a key rotation never revokes a live link). A link opens nothing once its artifact
+ * is deleted. A folder's link (F8.2) opens its zip, or with a `path` claim one of its files.
+ */
+import { randomUUID } from "node:crypto";
+import { errors, jwtVerify } from "jose";
+import { ARTIFACT_LINK_DEFAULT_TTL_SECONDS, ARTIFACT_LINK_MAX_TTL_SECONDS, ARTIFACT_LINK_TOKEN_TYPE, tenantTokenIssuer, } from "@nylorun/core/contracts";
+import { isArtifactId } from "@nylorun/core/compatibility";
+import { failOpaque, HttpError } from "../tenant/http.js";
+import { CLOCK_TOLERANCE_SECONDS, tokenKeyId } from "../tenant/jwt.js";
+/** The audience of every capability link. */
+export const ARTIFACT_LINK_AUDIENCE = "nylorun-artifact";
+/** Where a capability link is served: `GET /v1/artifact-links/<token>`. */
+export const ARTIFACT_LINK_PATH = "/v1/artifact-links";
+export async function mintArtifactLink(ctx, link) {
+    const ttl = Math.max(1, Math.min(Math.floor(link.expiresIn ?? ARTIFACT_LINK_DEFAULT_TTL_SECONDS), ARTIFACT_LINK_MAX_TTL_SECONDS));
+    const iat = Math.floor(Date.now() / 1000);
+    // Signed by the keys service (F4.2): this process never holds the private key.
+    const { token } = await ctx.keys.sign({
+        typ: ARTIFACT_LINK_TOKEN_TYPE,
+        claims: {
+            iss: tenantTokenIssuer(ctx.config.tenantId),
+            aud: ARTIFACT_LINK_AUDIENCE,
+            sub: link.artifactId,
+            ver: link.version,
+            ...(link.file === undefined ? {} : { path: link.file }),
+            iat,
+            exp: iat + ttl,
+            jti: randomUUID(),
+        },
+    });
+    return {
+        path: `${ARTIFACT_LINK_PATH}/${token}`,
+        artifactId: link.artifactId,
+        version: link.version,
+        ...(link.file === undefined ? {} : { file: link.file }),
+        expiresAt: new Date((iat + ttl) * 1000).toISOString(),
+    };
+}
+/**
+ * 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 async function verifyArtifactLink(ctx, raw) {
+    const checked = tokenKeyId(raw, ARTIFACT_LINK_TOKEN_TYPE);
+    if ("refused" in checked)
+        return refused(ctx, `artifact_link_${checked.refused}`);
+    const row = await ctx.store.tx((t) => t.signingKey(checked.kid));
+    if (!row)
+        return refused(ctx, "artifact_link_key_unknown");
+    let claims;
+    try {
+        const verified = await jwtVerify(raw, await ctx.signingKeys.publicKey(row), {
+            algorithms: ["ES256"],
+            issuer: tenantTokenIssuer(ctx.config.tenantId),
+            audience: ARTIFACT_LINK_AUDIENCE,
+            typ: ARTIFACT_LINK_TOKEN_TYPE,
+            clockTolerance: CLOCK_TOLERANCE_SECONDS,
+            requiredClaims: ["sub", "aud", "iat", "exp", "jti"],
+        });
+        claims = verified.payload;
+    }
+    catch (error) {
+        if (error instanceof errors.JWTExpired)
+            expired(ctx, "artifact_link_expired");
+        return refused(ctx, "artifact_link_invalid");
+    }
+    if (row.state === "revoked")
+        expired(ctx, "artifact_link_key_revoked");
+    const { sub, ver, path, exp, iat } = claims;
+    if (!isArtifactId(sub) ||
+        typeof ver !== "number" ||
+        !Number.isInteger(ver) ||
+        ver < 1 ||
+        (path !== undefined && (typeof path !== "string" || path === "")) ||
+        exp - iat > ARTIFACT_LINK_MAX_TTL_SECONDS)
+        return refused(ctx, "artifact_link_claims");
+    return { artifactId: sub, version: ver, ...(typeof path === "string" ? { file: path } : {}) };
+}
+function refused(ctx, reason) {
+    ctx.config.logger.warn("credential rejected", { reason });
+    return failOpaque();
+}
+function expired(ctx, reason) {
+    ctx.config.logger.warn("artifact link refused", { reason });
+    throw new HttpError(401, "The link has expired", { code: "token_expired" });
+}

package/dist/artifacts/media-types.d.ts

@@ -0,0 +1,13 @@
+/** Images the model reads as images. */
+export declare const MODEL_IMAGE_TYPES: readonly string[];
+/** The largest image or text file a model call carries inline. */
+export declare const MODEL_FILE_MAX_BYTES: number;
+/** The type part of a `Content-Type` value, lowercased, without parameters. */
+export declare function essence(contentType: string): string;
+/** A declared `Content-Type` as stored, or undefined when it is not a media type. */
+export declare function normalizeContentType(value: string | undefined): string | undefined;
+/** The media type a file name implies, or `application/octet-stream`. */
+export declare function contentTypeFor(name: string): string;
+export declare function isModelImage(contentType: string): boolean;
+/** Files the model reads as text: `text/*`, JSON, XML, YAML and their `+json`/`+xml` kin. */
+export declare function isText(contentType: string): boolean;

package/dist/artifacts/media-types.js

@@ -0,0 +1,80 @@
+/**
+ * Media types of file artifacts: what an upload may declare, what a name's extension implies,
+ * and how the model reads a file (an image as an image, text as text, anything else refused).
+ */
+import { DEFAULT_CONTENT_TYPE } from "../blob/index.js";
+const MEDIA_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]{0,126}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,126}$/;
+const BY_EXTENSION = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    pdf: "application/pdf",
+    txt: "text/plain",
+    md: "text/markdown",
+    csv: "text/csv",
+    html: "text/html",
+    htm: "text/html",
+    css: "text/css",
+    js: "text/javascript",
+    mjs: "text/javascript",
+    ts: "text/x-typescript",
+    py: "text/x-python",
+    sh: "text/x-sh",
+    json: "application/json",
+    xml: "application/xml",
+    yaml: "application/yaml",
+    yml: "application/yaml",
+    zip: "application/zip",
+    tar: "application/x-tar",
+    gz: "application/gzip",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    mp4: "video/mp4",
+};
+/** Images the model reads as images. */
+export const MODEL_IMAGE_TYPES = Object.freeze([
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "image/gif",
+]);
+/** The largest image or text file a model call carries inline. */
+export const MODEL_FILE_MAX_BYTES = 8 * 1024 * 1024;
+/** The type part of a `Content-Type` value, lowercased, without parameters. */
+export function essence(contentType) {
+    return contentType.split(";")[0].trim().toLowerCase();
+}
+/** A declared `Content-Type` as stored, or undefined when it is not a media type. */
+export function normalizeContentType(value) {
+    if (value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === "" || trimmed.length > 255)
+        return undefined;
+    return MEDIA_TYPE.test(essence(trimmed)) ? trimmed : undefined;
+}
+/** The media type a file name implies, or `application/octet-stream`. */
+export function contentTypeFor(name) {
+    const dot = name.lastIndexOf(".");
+    if (dot < 0)
+        return DEFAULT_CONTENT_TYPE;
+    return BY_EXTENSION[name.slice(dot + 1).toLowerCase()] ?? DEFAULT_CONTENT_TYPE;
+}
+export function isModelImage(contentType) {
+    return MODEL_IMAGE_TYPES.includes(essence(contentType));
+}
+/** Files the model reads as text: `text/*`, JSON, XML, YAML and their `+json`/`+xml` kin. */
+export function isText(contentType) {
+    const type = essence(contentType);
+    return (type.startsWith("text/") ||
+        type === "application/json" ||
+        type === "application/xml" ||
+        type === "application/yaml" ||
+        type === "application/x-yaml" ||
+        type === "application/javascript" ||
+        type.endsWith("+json") ||
+        type.endsWith("+xml"));
+}

package/dist/artifacts/parts.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Message `parts` (protocol 6): what a user message's text and file parts become for the
+ * engine. A file part names an artifact the caller may read, of this session or Tenant-wide;
+ * its version is pinned when the message is accepted (the latest when the part names none).
+ * The engine gets an opaque media part whose `reference` is `{ artifactId, version }`: model-gate
+ * resolves it to bytes (`./files.ts`), and the transcript and the record never hold them.
+ */
+import type { MessagePart } from "@nylorun/core/contracts";
+import type { JsonObject, JsonValue } from "@nylorun/core/define";
+import type { Tx } from "../store/types.js";
+import { type ArtifactAccess } from "./service.js";
+/** A user-message content part, as the engine's `MessageInput.content` takes it. */
+export type EnginePart = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "media";
+    readonly mediaType: string;
+    readonly reference: JsonObject;
+};
+/** The reference a media part carries: the artifact version, by id. */
+export interface FileReference {
+    readonly artifactId: string;
+    readonly version: number;
+}
+export declare function fileReferenceOf(value: JsonValue | undefined): FileReference | undefined;
+/**
+ * The parts with each file pinned to a version: for the engine (`engine`) and for a workflow's
+ * JSON input (`pinned`). Reads in the caller's transaction.
+ */
+export declare function resolveMessageParts(t: Tx, parts: readonly MessagePart[], sessionId: string, access: ArtifactAccess): Promise<{
+    engine: EnginePart[];
+    pinned: MessagePart[];
+}>;

package/dist/artifacts/parts.js

@@ -0,0 +1,38 @@
+import { fail } from "../tenant/http.js";
+import { readableArtifact, versionOf } from "./service.js";
+export function fileReferenceOf(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const { artifactId, version } = value;
+    if (typeof artifactId !== "string" || typeof version !== "number" || !Number.isInteger(version))
+        return undefined;
+    return { artifactId, version };
+}
+/**
+ * The parts with each file pinned to a version: for the engine (`engine`) and for a workflow's
+ * JSON input (`pinned`). Reads in the caller's transaction.
+ */
+export async function resolveMessageParts(t, parts, sessionId, access) {
+    const engine = [];
+    const pinned = [];
+    for (const part of parts) {
+        if (part.type === "text") {
+            engine.push({ type: "text", text: part.text });
+            pinned.push(part);
+            continue;
+        }
+        const artifact = await readableArtifact(t, part.artifactId, access);
+        if (artifact.sessionId !== null && artifact.sessionId !== sessionId)
+            fail(400, `Artifact ${artifact.id} belongs to another session`);
+        if (artifact.kind !== "file")
+            fail(400, `Artifact ${artifact.id} is a folder; a file part names a file artifact`);
+        const version = await versionOf(t, artifact, part.version);
+        engine.push({
+            type: "media",
+            mediaType: version.contentType,
+            reference: { artifactId: artifact.id, version: version.version, name: artifact.name },
+        });
+        pinned.push({ type: "file", artifactId: artifact.id, version: version.version });
+    }
+    return { engine, pinned };
+}

package/dist/artifacts/service.d.ts

@@ -0,0 +1,74 @@
+import type { ArtifactSource, ArtifactVersionView, ArtifactView, FolderManifest } from "@nylorun/core/contracts";
+import { type BlobBody } from "../blob/index.js";
+import type { ArtifactRow, ArtifactVersionRow, Tx } from "../store/types.js";
+import { type SessionAccess, type TenantContext } from "../tenant/context.js";
+/** What the caller may reach: undefined for the whole Tenant (an application principal). */
+export type ArtifactAccess = SessionAccess | undefined;
+export interface UploadInput {
+    /** A new version of this artifact; otherwise a new artifact. */
+    readonly artifactId?: string;
+    /** The new artifact's name; for a new version, it stays the artifact's. */
+    readonly name?: string;
+    /** The declared media type; default: what the name's extension implies. */
+    readonly contentType?: string;
+    /** The session a new artifact belongs to. Required when acting for a person. */
+    readonly sessionId?: string;
+    readonly labels?: Readonly<Record<string, string>>;
+    /** The body's declared length (`Content-Length`): one past the limits is refused unread. */
+    readonly declaredBytes?: number;
+    readonly source: ArtifactSource;
+    /** The turn that saved it (`save_artifact`), for the event. */
+    readonly turnId?: string | null;
+    /** The tool call that saved it, for the event. */
+    readonly callId?: string;
+}
+export interface Uploaded {
+    readonly artifact: ArtifactView;
+    readonly version: ArtifactVersionView;
+}
+export declare function versionView(row: ArtifactVersionRow): ArtifactVersionView;
+export declare function artifactView(row: ArtifactRow, versions?: ArtifactVersionRow[]): ArtifactView;
+/** An artifact name: 1–255 characters, no path separators or control characters. */
+export declare function checkArtifactName(name: string | undefined): string;
+/**
+ * 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 declare function readableArtifact(t: Tx, id: string, access: ArtifactAccess, options?: {
+    lock?: boolean;
+}): Promise<ArtifactRow>;
+/** `version`, or the latest when it is undefined; a missing one is a 404. */
+export declare function versionOf(t: Tx, row: ArtifactRow, version: number | undefined): Promise<ArtifactVersionRow>;
+/**
+ * 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 declare function uploadArtifact(ctx: TenantContext, input: UploadInput, body: BlobBody, access: ArtifactAccess, signal?: AbortSignal): Promise<Uploaded>;
+/** The caller's artifacts: of one session, or of every session it reaches. */
+export declare function listArtifacts(ctx: TenantContext, filter: {
+    sessionId?: string;
+}, access: ArtifactAccess): Promise<{
+    artifacts: ArtifactView[];
+}>;
+/** One artifact with every version. */
+export declare function getArtifact(ctx: TenantContext, id: string, access: ArtifactAccess): Promise<ArtifactView>;
+/** One version's row, for a download. */
+export declare function artifactContent(ctx: TenantContext, id: string, version: number | undefined, access: ArtifactAccess): Promise<{
+    artifact: ArtifactRow;
+    version: ArtifactVersionRow;
+}>;
+/** One version's row, its artifact and, for a folder, its manifest; a file is a 400. */
+export declare function folderContent(ctx: TenantContext, id: string, version: number | undefined, access: ArtifactAccess): Promise<{
+    artifact: ArtifactRow;
+    version: ArtifactVersionRow;
+    manifest: FolderManifest;
+}>;
+/**
+ * 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 declare function deleteArtifact(ctx: TenantContext, id: string, access: ArtifactAccess): Promise<{
+    artifactId: string;
+    deleted: true;
+}>;

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 trusted issuer's 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 };
+}