@nylorun/runtime 0.15.1-beta → 0.16.0-beta

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;
+}>;

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 subject and delivery tokens: `sub` is the artifact, `ver` the version, `aud`
+ * `nylorun-artifact`, and it lives at most `ARTIFACT_LINK_MAX_TTL_SECONDS` (the subject-token
+ * maximum, 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, subjectTokenIssuer, } 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: subjectTokenIssuer(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: subjectTokenIssuer(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;
+}>;