@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.7

package/dist/kernel/media.js

@@ -0,0 +1,216 @@
+/** 0.2 media lifecycle over native target drivers. No bytes pass through this module. */
+import { ContractError } from "./contracts.js";
+const P = "media";
+/** HTTP status of each media code: a custom MediaStorage may throw them without one. */
+const STATUS = new Map(Object.entries({
+    MEDIA_PURPOSE_REJECTED: 400, MEDIA_SVG_REJECTED: 400, MEDIA_MIME_REJECTED: 400, MEDIA_VARIANTS_INCOMPLETE: 400, MEDIA_VARIANT_SIZE_EXCEEDED: 400, MEDIA_VARIANTS_SUSPICIOUS_SIZE: 400,
+    MEDIA_ASSET_NOT_FOUND: 404, MEDIA_OBJECT_NOT_FOUND: 409, MEDIA_UPLOAD_EXPIRED: 410, SITE_NOT_CONFIGURED: 501, MEDIA_NOT_CONFIGURED: 501, PARTIAL_FAILURE: 503,
+}));
+const extra = (code) => ({ status: STATUS.get(code), ...(code === "PARTIAL_FAILURE" ? { fields: { failure: { outcome: "partial", retry: "safe", resource: "media" } } } : {}) });
+/**
+ * A media, site or partial-failure error with the HTTP status (and `failure` payload) its code has on the wire. Code
+ * outside this module raising these codes uses it: core `statusOf` maps only the core codes.
+ */
+export const mediaError = (code, message, path = P, options) => new ContractError(code, message, path, { ...options, ...extra(code) });
+const fail = (code, message, options) => mediaError(code, message, P, options);
+/** A storage error keeps the wire status its code has always had. */
+const own = (error) => { if (error instanceof ContractError && !error.status && STATUS.has(error.code))
+    Object.assign(error, extra(error.code)); return error; };
+const rejected = (results) => results.filter((r) => r.status === "rejected");
+const bad = (expected) => fail("INPUT_VALIDATION_FAILED", `expected ${expected}`);
+/** SVG is refused: object storage does not sanitize it, and an SVG can carry script. */
+const ALLOWED = new Set(["image/png", "image/jpeg", "image/webp", "image/avif", "image/gif"]);
+/** Modern formats a skipped optimization makes larger than the fallback. */
+const MODERN = new Set(["image/avif", "image/webp"]);
+const ROLES = new Set(["primary", "alternate", "fallback"]);
+const TTL_MS = 15 * 60 * 1000;
+const obj = (v) => (v !== null && typeof v === "object" && !Array.isArray(v) ? v : {});
+const MAX_TEXT = 1000;
+const MAX_FILENAME = 255;
+/** `alt` and `caption`: absent, or a string of at most 1000 characters. */
+function texts(body) {
+    const b = obj(body);
+    for (const k of ["alt", "caption"])
+        if (b[k] !== undefined && (typeof b[k] !== "string" || b[k].length > MAX_TEXT))
+            throw bad(`{ alt?: string, caption?: string }, each at most ${MAX_TEXT} characters`);
+    return { ...(typeof b["alt"] === "string" ? { alt: b["alt"] } : {}), ...(typeof b["caption"] === "string" ? { caption: b["caption"] } : {}) };
+}
+/** Exactly one variant per required slot, nothing outside them, and exactly one primary. */
+function checkVariants(policy, variants) {
+    const slots = policy.required.map(slot => slot.split(","));
+    const slotOf = new Map(slots.flatMap((mimes, i) => mimes.map((m) => [m, i])));
+    const filled = variants.map((v) => slotOf.get(v.mimeType));
+    if (filled.includes(undefined) || new Set(filled).size !== variants.length || filled.length !== slots.length || variants.filter((v) => v.role === "primary").length !== 1)
+        throw fail("MEDIA_VARIANTS_INCOMPLETE", `purpose '${policy.name}' takes one variant for each of ${JSON.stringify(policy.required)}, exactly one of them primary`);
+    for (const v of variants) {
+        if (v.mimeType === "image/svg+xml")
+            throw fail("MEDIA_SVG_REJECTED", "SVG uploads are refused: object storage does not sanitize them");
+        if (!ALLOWED.has(v.mimeType))
+            throw fail("MEDIA_MIME_REJECTED", `${v.mimeType} is not an accepted image type`);
+    }
+    for (const v of variants) {
+        const cap = policy.maxBytes[v.mimeType] ?? 0;
+        if (v.byteSize > cap)
+            throw fail("MEDIA_VARIANT_SIZE_EXCEEDED", `${v.mimeType} is ${v.byteSize} bytes; purpose '${policy.name}' allows ${cap}`);
+    }
+    const fallback = ["image/jpeg", "image/png", "image/gif"].map((m) => variants.find((v) => v.mimeType === m)).find(Boolean);
+    const heavy = fallback && variants.find((v) => MODERN.has(v.mimeType) && v.byteSize > fallback.byteSize);
+    if (heavy)
+        throw fail("MEDIA_VARIANTS_SUSPICIOUS_SIZE", `${heavy.mimeType} (${heavy.byteSize}B) is larger than ${fallback.mimeType} (${fallback.byteSize}B): optimize it before uploading`);
+}
+const COLUMNS = "id, created_at, alt, caption, variants, metadata";
+function assetOf(r) {
+    return {
+        id: String(r.id), variants: JSON.parse(String(r.variants)), createdAt: Number(r.created_at),
+        ...(r.alt === null ? {} : { alt: String(r.alt) }), ...(r.caption === null ? {} : { caption: String(r.caption) }),
+        ...(r.metadata === null ? {} : { metadata: JSON.parse(String(r.metadata)) }),
+    };
+}
+const save = (a, p) => ({
+    sql: `INSERT INTO media_assets (id, created_at, owner_id, alt, caption, variants, metadata) VALUES (${p(1)}, ${p(2)}, NULL, ${p(3)}, ${p(4)}, ${p(5)}, ${p(6)}) ON CONFLICT(id) DO NOTHING`,
+    binds: [a.id, a.createdAt, a.alt ?? null, a.caption ?? null, JSON.stringify(a.variants), a.metadata ? JSON.stringify(a.metadata) : null],
+});
+export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
+    const p = d.param;
+    const one = async (sql, binds) => (await driver.read(sql, binds))[0];
+    const byId = (id) => one(`SELECT ${COLUMNS} FROM media_assets WHERE id = ${p(1)}`, [id]);
+    const unpend = (id) => ({ sql: `DELETE FROM pending_media_uploads WHERE id = ${p(1)}`, binds: [id] });
+    const removeAll = (variants) => Promise.allSettled(variants.map((v) => storage.deleteObject({ storageKey: v.storageKey })));
+    const get = async (id) => {
+        const r = await byId(id);
+        if (!r)
+            throw fail("MEDIA_ASSET_NOT_FOUND", `no media asset '${id}'`);
+        return assetOf(r);
+    };
+    return {
+        async createUpload(request) {
+            const b = obj(request);
+            const variants = Array.isArray(b["variants"]) ? b["variants"].map(obj) : null;
+            if (typeof b["filename"] !== "string" || b["filename"].length > MAX_FILENAME || typeof b["purpose"] !== "string" || !variants?.length
+                || variants.some((v) => typeof v["mimeType"] !== "string" || !Number.isSafeInteger(v["byteSize"]) || v["byteSize"] <= 0 || !ROLES.has(v["role"])))
+                throw bad("{ filename: string of at most 255 characters, purpose: string, variants: [{ mimeType: string, byteSize: positive integer, role: 'primary'|'alternate'|'fallback' }] }");
+            const { filename, purpose } = b;
+            const described = texts(b);
+            const declared = policies;
+            const policy = declared.find((p) => p.name === purpose);
+            if (!policy)
+                throw fail("MEDIA_PURPOSE_REJECTED", `purpose '${purpose}' is not declared`);
+            const asked = variants;
+            checkVariants(policy, asked);
+            const at = now();
+            const expiresAt = at + TTL_MS;
+            // bearer-equivalent until commit: storage keys under it must not be guessable
+            const uploadGroupId = crypto.randomUUID();
+            const specs = asked.map(({ mimeType, byteSize, role }) => ({ mimeType, byteSize, role, maxBytes: policy.maxBytes[mimeType] }));
+            let capabilities;
+            try {
+                ({ capabilities } = await storage.createUpload({ uploadGroupId, purpose, filename, variants: specs, now: at, expiresAt }));
+            }
+            catch (error) {
+                throw own(error);
+            }
+            const record = {
+                purpose, filename, ...described, expiresAt, createdAt: at,
+                variants: capabilities.map((c, i) => ({ mimeType: c.mimeType, role: c.role, storageKey: c.storageKey, expectedSize: specs[i].byteSize, maxBytes: specs[i].maxBytes })),
+            };
+            await driver.write([
+                { sql: `DELETE FROM pending_media_uploads WHERE expires_at <= ${p(1)}`, binds: [at] },
+                { sql: `INSERT INTO pending_media_uploads (id, record, expires_at) VALUES (${p(1)}, ${p(2)}, ${p(3)})`, binds: [uploadGroupId, JSON.stringify(record), expiresAt] },
+            ]);
+            return { uploadGroupId, capabilities: capabilities.map(({ mimeType, role, method, uploadUrl, requiredHeaders }) => ({ mimeType, role, method, uploadUrl, ...(requiredHeaders ? { requiredHeaders } : {}) })), expiresAt };
+        },
+        async commitUpload(uploadGroupId, request) {
+            const patch = texts(request);
+            const committed = await byId(uploadGroupId);
+            if (committed)
+                return assetOf(committed);
+            const row = await one(`SELECT record FROM pending_media_uploads WHERE id = ${p(1)}`, [uploadGroupId]);
+            const record = row ? JSON.parse(String(row.record)) : null;
+            // a rejected group's objects are deleted: an upload URL takes any type and size, so what was PUT is not trusted
+            const discard = () => removeAll(record?.variants ?? []);
+            if (!record || record.expiresAt <= now()) {
+                if (record) {
+                    await discard();
+                    await driver.write([unpend(uploadGroupId)]);
+                }
+                throw fail("MEDIA_UPLOAD_EXPIRED", `upload group '${uploadGroupId}' is unknown or expired; create a new upload`);
+            }
+            let asset;
+            try {
+                asset = await storage.commitUpload({
+                    uploadGroupId, filename: record.filename, now: record.createdAt,
+                    // the declared size is the cap: a larger object than announced is refused
+                    variants: record.variants.map((v) => ({ mimeType: v.mimeType, role: v.role, storageKey: v.storageKey, maxBytes: Math.min(v.maxBytes, v.expectedSize) })),
+                    ...((patch.alt ?? record.alt) !== undefined ? { alt: patch.alt ?? record.alt } : {}),
+                    ...((patch.caption ?? record.caption) !== undefined ? { caption: patch.caption ?? record.caption } : {}),
+                });
+            }
+            catch (error) {
+                if (error instanceof ContractError && error.code === "MEDIA_OBJECT_NOT_FOUND") {
+                    const winner = await byId(uploadGroupId);
+                    if (winner)
+                        return assetOf(winner);
+                }
+                if (error instanceof ContractError && error.code.startsWith("MEDIA_"))
+                    await discard();
+                throw own(error);
+            }
+            if (asset.id !== uploadGroupId)
+                throw new ContractError("OUTCOME_UNKNOWN", "Storage returned a different asset id; reconcile this upload group.", P);
+            await driver.write([save(asset, p), unpend(uploadGroupId)]).catch(async (error) => {
+                // Cleanup requires positive native rollback evidence; an unclassified failure may have committed.
+                if (driver.definitive?.(error) === true) {
+                    const failed = rejected(await removeAll(asset.variants));
+                    if (failed.length)
+                        throw fail("PARTIAL_FAILURE", "The write rolled back, but some attempt copies could not be removed. Reconcile storage before retrying.", { cause: new AggregateError([error, ...failed.map(r => r.reason)]) });
+                    throw error;
+                }
+                throw error instanceof ContractError && error.code === "OUTCOME_UNKNOWN" ? error : new ContractError("OUTCOME_UNKNOWN", "The write outcome is unknown; reconcile this upload group before retrying.", P, { cause: error });
+            });
+            const durable = await get(uploadGroupId);
+            // ON CONFLICT may select another concurrent attempt. Only discard this attempt's unselected copies.
+            const selected = new Set(durable.variants.map(v => v.storageKey));
+            if (rejected(await removeAll(asset.variants.filter(v => !selected.has(v.storageKey)))).length)
+                throw new ContractError("OUTCOME_UNKNOWN", "The asset is committed, but unselected upload copies need storage reconciliation.", P);
+            await discard();
+            return durable;
+        },
+        async list({ limit, cursor, search }) {
+            if (search !== undefined && typeof search !== "string")
+                throw bad("search: string");
+            const n = limit ?? 50;
+            const offset = cursor === undefined ? 0 : Number(cursor);
+            if (!Number.isInteger(n) || n < 1 || n > 500 || !Number.isSafeInteger(offset) || offset < 0 || (cursor !== undefined && String(offset) !== cursor))
+                throw bad("limit 1..500 and a cursor this list returned");
+            const term = search ? d.escapeLike(search) : undefined;
+            const where = term ? `WHERE id ${d.like(true)} ${p(3)}${d.likeEscape} OR alt ${d.like(true)} ${p(3)}${d.likeEscape} OR caption ${d.like(true)} ${p(3)}${d.likeEscape}` : "";
+            const page = await driver.read(`SELECT ${COLUMNS} FROM media_assets ${where} ORDER BY created_at DESC, id DESC LIMIT ${p(1)} OFFSET ${p(2)}`, [n + 1, offset, ...(term ? [`%${term}%`] : [])]);
+            const rows = page.slice(0, n).map(assetOf);
+            return { rows, ...(page.length > n ? { nextCursor: String(offset + n) } : {}) };
+        },
+        get,
+        async update(id, request) {
+            const patch = Object.entries(texts(request));
+            if (!patch.length)
+                return get(id);
+            // only the patched columns, and only a row that still exists: a concurrent delete or edit of the other field stands
+            const [r] = (await driver.write([{ sql: `UPDATE media_assets SET ${patch.map(([k], i) => `${k} = ${p(i + 2)}`).join(", ")} WHERE id = ${p(1)} RETURNING ${COLUMNS}`, binds: [id, ...patch.map(([, v]) => v)] }]))[0];
+            if (!r)
+                throw fail("MEDIA_ASSET_NOT_FOUND", `no media asset '${id}'`);
+            return assetOf(r);
+        },
+        async delete(id) {
+            const asset = await get(id);
+            const failed = rejected(await removeAll(asset.variants));
+            if (failed.length)
+                throw fail("PARTIAL_FAILURE", "Some objects could not be removed. Retry deleting the same asset.", { cause: new AggregateError(failed.map(r => r.reason)) });
+            await driver.write([{ sql: `DELETE FROM media_assets WHERE id = ${p(1)}`, binds: [id] }]);
+            return { deleted: true, variantsRemoved: asset.variants.length };
+        },
+    };
+}
+/** The 0.2 Admin library item's convenience fields, without changing the storage DTO. */
+export function mediaItem(asset) {
+    const primary = asset.variants.find(v => v.role === "primary") ?? asset.variants[0];
+    return { id: asset.id, variants: asset.variants, primaryUrl: primary?.publicUrl ?? null, mime: primary?.mimeType ?? null, byteSize: primary?.byteSize ?? null, alt: asset.alt ?? null, caption: asset.caption ?? null, createdAt: asset.createdAt };
+}

package/dist/kernel/paging.d.ts

@@ -0,0 +1,55 @@
+/** Keyset paging for a generated View boundary: Core printed the first and next page SQL; this binds, checks the cursor and trims. */
+import type { Caller } from "./contracts.js";
+import { type Recipe, type Values } from "./binds.js";
+/** Shared keyset wire format; a selected View binds its cursor to its operation. */
+export declare const encodeCursor: (value: unknown, id: unknown, operation?: string) => string;
+export declare function decodeCursor(cursor: string, path?: string, operation?: string): [unknown, unknown];
+/** Selected boundaries may accept a NULL key; their generated kind guard validates it before native I/O. */
+export declare function decodeNullableCursor(cursor: string, path: string, operation: string): [unknown, string];
+export declare const MAX_PAGE_SIZE = 500;
+/** Transport and native entry bounds share one check; Views retain their declared cap. */
+export declare function checkPageLimit(limit: unknown, path: string): asserts limit is number;
+/** First and next page SQL; `extra` lists, per trailing placeholder, the cursor key it binds (-1: the limit + 1). */
+export interface Pages {
+    readonly binds: readonly Recipe[];
+    readonly first: {
+        readonly sql: string;
+        readonly extra: readonly number[];
+    };
+    readonly next: {
+        readonly sql: string;
+        readonly extra: readonly number[];
+    };
+}
+/** The order column's cursor check: `int` is int8/integer, `numeric` a NUMERIC with scale, `date`/`timestamp` strings converted by the dialect. */
+export type CursorKind = "bool" | "int4" | "int" | "numeric" | "float" | "text" | "date" | "timestamp";
+export interface Paged<Database> {
+    readonly path: string;
+    /** The View's LIMIT, else 500. */
+    readonly cap: number;
+    readonly sqlite: boolean;
+    readonly cursor: readonly CursorKind[];
+    /** Complete compiler-proved order tuple; zero keys is a bounded singleton. */
+    readonly keys: number;
+    readonly values: Values;
+    /** The driver's `read`. */
+    readonly read: (db: Database, sql: string, binds: unknown[]) => PromiseLike<any[]> | any[];
+    readonly caller: Pages;
+    /** System callers' page, when the View's caller page applies row policy. */
+    readonly trusted?: Pages;
+    readonly auth?: (caller: Caller) => void;
+}
+type Options = {
+    limit?: number;
+    cursor?: string;
+};
+export declare function validCursor(kind: CursorKind, sqlite: boolean, key: unknown): boolean;
+/**
+ * A View's paged boundary: `options.limit` defaults to min(50, cap) and is capped at cap and 500. Generated modules
+ * call it from their exported function, so importing a View runs no kernel code.
+ */
+export declare function page<Database, Row>(spec: Paged<Database>, db: Database, caller: Caller, input: unknown, options?: Options): Promise<{
+    rows: Row[];
+    nextCursor?: string;
+}>;
+export {};

package/dist/kernel/paging.js

@@ -0,0 +1,95 @@
+import { modeOf } from "./caller-identity.js";
+import { binds } from "./binds.js";
+import { invalid } from "./surface.js";
+/** Shared keyset wire format; a selected View binds its cursor to its operation. */
+export const encodeCursor = (value, id, operation) => encodeURIComponent(JSON.stringify(operation === undefined ? [value, id] : [value, id, operation]));
+export function decodeCursor(cursor, path = "", operation) {
+    try {
+        const c = JSON.parse(decodeURIComponent(cursor));
+        if (Array.isArray(c) && c.length === (operation === undefined ? 2 : 3) && (operation === undefined || typeof c[1] === "string" && (typeof c[0] === "string" || typeof c[0] === "boolean" || typeof c[0] === "number" && Number.isFinite(c[0])) && c[2] === operation))
+            return [c[0], c[1]];
+    }
+    catch { }
+    invalid("Malformed or foreign cursor.", path);
+}
+/** Selected boundaries may accept a NULL key; their generated kind guard validates it before native I/O. */
+export function decodeNullableCursor(cursor, path, operation) {
+    try {
+        const c = JSON.parse(decodeURIComponent(cursor));
+        if (Array.isArray(c) && c.length === 3 && typeof c[1] === "string" && c[2] === operation)
+            return [c[0], c[1]];
+    }
+    catch { }
+    invalid("Malformed or foreign cursor.", path);
+}
+export const MAX_PAGE_SIZE = 500;
+/** Transport and native entry bounds share one check; Views retain their declared cap. */
+export function checkPageLimit(limit, path) {
+    if (!Number.isSafeInteger(limit) || Number(limit) < 1 || Number(limit) > MAX_PAGE_SIZE)
+        invalid("limit is 1 to 500.", path);
+}
+export function validCursor(kind, sqlite, key) {
+    switch (kind) {
+        case "bool": return sqlite ? key === 0 || key === 1 : typeof key === "boolean";
+        case "int4":
+        case "int": {
+            const [min, max] = kind === "int4" ? [-2147483648n, 2147483647n] : [-9223372036854775808n, 9223372036854775807n];
+            return Number.isSafeInteger(key) && (kind !== "int4" || key >= -2147483648 && key <= 2147483647) || typeof key === "string" && key.length <= 20 && /^(?:0|-?[1-9]\d*)$/.test(key) && BigInt(key) >= min && BigInt(key) <= max;
+        }
+        case "numeric": return sqlite ? Number.isSafeInteger(key) : typeof key === "string" && /^-?\d+(?:\.\d+)?$/.test(key) && Number.isFinite(Number(key));
+        case "float": return typeof key === "number" && Number.isFinite(key);
+        default: return typeof key === "string";
+    }
+}
+/**
+ * A View's paged boundary: `options.limit` defaults to min(50, cap) and is capped at cap and 500. Generated modules
+ * call it from their exported function, so importing a View runs no kernel code.
+ */
+export async function page(spec, db, caller, input, options = {}) {
+    const { path, cap } = spec;
+    spec.auth?.(caller);
+    const requested = options.limit ?? Math.min(50, cap);
+    if (!Number.isInteger(requested) || requested < 1)
+        invalid("limit must be a positive integer.", path + "/limit");
+    const limit = Math.min(requested, cap, MAX_PAGE_SIZE);
+    const m = (modeOf(caller) === "trusted" ? spec.trusted : undefined) ?? spec.caller;
+    const values = binds(spec.values, m.binds, caller, input);
+    let keys;
+    if (options.cursor !== undefined) {
+        try {
+            const encoded = JSON.parse(decodeURIComponent(options.cursor));
+            if (!spec.keys || !Array.isArray(encoded) || encoded.length !== Math.max(2, spec.keys) + 1 || encoded.at(-1) !== path)
+                throw 0;
+            if (spec.keys === 1 && encoded[0] !== encoded[1])
+                throw 0;
+            // Preserve the existing [id,id,operation] single-key and [value,id,operation] two-key formats.
+            keys = spec.keys === 1 ? [encoded[1]] : encoded.slice(0, -1);
+            for (const [i, kind] of spec.cursor.entries()) {
+                if (!validCursor(kind, spec.sqlite, keys[i]))
+                    throw 0;
+                if (kind === "date" || kind === "timestamp")
+                    keys[i] = spec.values[kind](keys[i]);
+            }
+        }
+        catch {
+            invalid("Malformed, foreign or wrongly typed cursor.", path + "/cursor");
+        }
+    }
+    const sql = keys ? m.next : m.first;
+    const rows = await spec.read(db, sql.sql, [...values, ...sql.extra.map(i => i < 0 ? limit + 1 : keys[i])]);
+    const last = rows[limit - 1];
+    if (!spec.keys && rows.length > limit)
+        invalid("This unordered View exceeds one page; add a supported ORDER BY.", path);
+    const next = last && Array.from({ length: spec.keys }, (_, i) => {
+        const key = last[`_k${i}`];
+        return typeof key === "bigint" && (spec.cursor[i] === "int" || spec.cursor[i] === "int4")
+            ? Number.isSafeInteger(Number(key)) ? Number(key) : String(key) : key;
+    });
+    const nextCursor = rows.length > limit && next ? encodeURIComponent(JSON.stringify([...next, ...(spec.keys === 1 ? next : []), path])) : undefined;
+    if (rows.length > limit)
+        rows.length = limit;
+    for (const row of rows)
+        for (let i = 0; i < spec.keys; i++)
+            delete row[`_k${i}`];
+    return { rows: rows, ...(nextCursor === undefined ? {} : { nextCursor }) };
+}

package/dist/kernel/publishing.d.ts

@@ -0,0 +1,4 @@
+/** A generated publishing transition, admin or system only; `write` claims translation state, released on CONFLICT. */
+import { type Caller, type Output, type Row } from "./contracts.js";
+import { type Bound, type Step, type Values } from "./binds.js";
+export declare function transition<DB>(db: DB, caller: Caller, input: Readonly<Record<string, unknown>>, path: string, steps: readonly Step[], failure: string, d: Values, execute: (db: DB, steps: readonly Bound[], path: string) => Promise<Row[][]>, write?: () => () => void): Promise<Output>;

package/dist/kernel/publishing.js

@@ -0,0 +1,16 @@
+/** A generated publishing transition, admin or system only; `write` claims translation state, released on CONFLICT. */
+import { isAdmin, deny } from "./contracts.js";
+import { checkFresh } from "./caller-identity.js";
+import { bound } from "./binds.js";
+export async function transition(db, caller, input, path, steps, failure, d, execute, write) {
+    checkFresh(caller, false, path);
+    deny(caller, caller.kind === "system" || isAdmin(caller), path);
+    const release = write?.();
+    return { results: await execute(db, bound(d, steps, caller, input), path).catch(error => {
+            if (release && error?.code === "CONFLICT")
+                release();
+            if (error?.code === "CONFLICT" && error.message === "Expected one affected row.")
+                error.message = failure;
+            throw error;
+        }) };
+}

package/dist/{cloudflare/r2Media.d.ts → kernel/r2-media.d.ts}

@@ -1,4 +1,4 @@
-import type { MediaStorage } from "../core/site.js";
+import type { MediaStorage } from "./site-types.js";
 interface R2Head {
     readonly size: number;
     readonly httpMetadata?: {
@@ -6,7 +6,7 @@ interface R2Head {
     };
     readonly customMetadata?: Record<string, string>;
 }
-interface R2Bucket {
+export interface R2Bucket {
     head(key: string): Promise<R2Head | null>;
     get(key: string): Promise<(R2Head & {
         readonly body: ReadableStream;
@@ -17,10 +17,10 @@ interface R2Bucket {
         };
         customMetadata: Record<string, string>;
     }): Promise<unknown>;
-    delete(key: string): Promise<void>;
+    delete(key: string | string[]): Promise<void>;
 }
 /** `aws4fetch`'s `AwsClient` has this shape. */
-interface S3Signer {
+export interface S3Signer {
     sign(url: string, init: {
         method: "PUT";
         aws: {
@@ -40,4 +40,3 @@ export interface R2MediaStorageOptions {
 }
 export declare function r2MediaStorage({ bucket, signer, endpoint, publicBase }: R2MediaStorageOptions): MediaStorage;
 export {};
-//# sourceMappingURL=r2Media.d.ts.map

package/dist/kernel/r2-media.js

@@ -0,0 +1,78 @@
+/** Native R2 binding plus an app-owned SigV4 signer. No SDK dependency. */
+import { ContractError } from "./contracts.js";
+import { mediaError } from "./media.js";
+const EXT = { "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp", "image/avif": "avif", "image/gif": "gif" };
+const UPLOADS = "uploads/";
+const fail = (code, message, options) => mediaError(code, message, "media/r2", options);
+const ext = (mimeType) => EXT[mimeType] ?? "bin";
+const cancel = (o) => o?.body.cancel().catch(() => undefined);
+export function r2MediaStorage({ bucket, signer, endpoint, publicBase }) {
+    if (!publicBase)
+        throw fail("MEDIA_NOT_CONFIGURED", "R2 media storage needs publicBase, the bucket's public URL");
+    const base = publicBase.replace(/\/+$/, "");
+    const s3 = endpoint.replace(/\/+$/, "");
+    return {
+        async createUpload({ uploadGroupId, purpose, variants, now, expiresAt }) {
+            const ttl = Math.max(60, Math.floor((expiresAt - now) / 1000));
+            return {
+                capabilities: await Promise.all(variants.map(async (v) => {
+                    // server-made keys, one directory per asset so its variants list together
+                    const storageKey = `${UPLOADS}${purpose}/${uploadGroupId}/${v.role}.${ext(v.mimeType)}`;
+                    const target = new URL(`${s3}/${storageKey}`);
+                    target.searchParams.set("X-Amz-Expires", String(ttl));
+                    const { url } = await signer.sign(target.href, { method: "PUT", aws: { signQuery: true, service: "s3" } });
+                    return { mimeType: v.mimeType, role: v.role, method: "PUT", uploadUrl: url, storageKey, requiredHeaders: { "Content-Type": v.mimeType } };
+                })),
+            };
+        },
+        async commitUpload({ uploadGroupId, filename, variants, alt, caption, now }) {
+            // every variant is checked before any is published, so a rejected group publishes nothing
+            const heads = await Promise.all(variants.map(spec => bucket.head(spec.storageKey)));
+            for (const [i, spec] of variants.entries()) {
+                const o = heads[i];
+                if (!o)
+                    throw fail("MEDIA_OBJECT_NOT_FOUND", `variant ${spec.role} of '${uploadGroupId}' was not uploaded`);
+                const mime = o.httpMetadata?.contentType ?? "application/octet-stream";
+                if (mime !== spec.mimeType)
+                    throw fail("MEDIA_MIME_REJECTED", `the stored ${spec.role} is ${mime}, not ${spec.mimeType}`);
+                if (o.size > spec.maxBytes)
+                    throw fail("MEDIA_VARIANT_SIZE_EXCEEDED", `the stored ${spec.role} is ${o.size} bytes, more than ${spec.maxBytes}`);
+            }
+            // Each attempt owns its public copies: a concurrent loser cannot overwrite or clean up a committed winner.
+            const attempt = crypto.randomUUID();
+            const out = [];
+            try {
+                for (const [i, spec] of variants.entries()) {
+                    const key = `committed/${uploadGroupId}/${attempt}/${spec.role}.${ext(spec.mimeType)}`;
+                    const o = await bucket.get(spec.storageKey);
+                    // an upload URL may PUT again between the check and the copy: the copy must be what was checked
+                    if (!o || o.size !== heads[i].size || o.httpMetadata?.contentType !== spec.mimeType) {
+                        await cancel(o);
+                        throw fail("MEDIA_OBJECT_NOT_FOUND", `variant ${spec.role} of '${uploadGroupId}' changed during commit`);
+                    }
+                    // Remember a possibly published key before awaiting put: a failed response may still have stored it.
+                    out.push({ mimeType: spec.mimeType, publicUrl: `${base}/${key}`, storageKey: key, byteSize: o.size, role: spec.role });
+                    try {
+                        await bucket.put(key, o.body, {
+                            httpMetadata: { contentType: spec.mimeType },
+                            customMetadata: { ...o.customMetadata, committedAt: String(now), role: spec.role, uploadGroupId, filename, ...(alt ? { alt } : {}), ...(caption ? { caption } : {}) },
+                        });
+                    }
+                    catch (error) {
+                        await cancel(o);
+                        throw error;
+                    }
+                }
+                // The use case removes upload keys only after its SQL transaction is durable.
+            }
+            catch (error) {
+                const cleanup = await Promise.allSettled(out.map(v => bucket.delete(v.storageKey)));
+                if (cleanup.some(r => r.status === "rejected"))
+                    throw fail("PARTIAL_FAILURE", "Some copied variants could not be removed. Retry the same upload group.", { cause: error });
+                throw error instanceof ContractError ? error : new ContractError("OUTCOME_UNKNOWN", "Object copy failed; retry the same upload group after reconciliation.", "media/r2", { cause: error });
+            }
+            return { id: uploadGroupId, variants: out, createdAt: now, metadata: { filename }, ...(alt !== undefined ? { alt } : {}), ...(caption !== undefined ? { caption } : {}) };
+        },
+        deleteObject: ({ storageKey }) => bucket.delete(storageKey),
+    };
+}

package/dist/kernel/rest-dispatch.js

@@ -0,0 +1,38 @@
+/** View/Procedure dispatch loads only on a matched REST request, after caller resolution. */
+import { authorizeTarget } from "./authorization.js";
+import { convert, invalid } from "./surface.js";
+import { body } from "./rest.js";
+const fail = message => invalid(message, "rest");
+function number(raw) { const value = Number(raw); if (!raw.trim() || !Number.isFinite(value))
+    fail("Expected a number."); return value; }
+function boolean(raw) { if (raw !== "true" && raw !== "false")
+    fail("Expected true or false."); return raw === "true"; }
+export async function dispatch(route, request, getDb, caller, params, options, access) {
+    route.check?.(caller);
+    if (options.authorize && route.target) {
+        await authorizeTarget(options.authorize, route.target, caller);
+    }
+    let data;
+    if (route.page) {
+        const { input: raw, ...paging } = route.query(new URL(request.url).searchParams);
+        const input = { ...raw };
+        convert(input, route.convert);
+        if (access?.dryRun)
+            return access.response();
+        data = await route.page(getDb(), caller, input, paging);
+    }
+    else {
+        const raw = await body(request);
+        for (const key in params)
+            raw[key] = route.params?.[key] === "number" ? number(params[key]) : route.params?.[key] === "boolean" ? boolean(params[key]) : params[key];
+        const input = route.validate(raw);
+        convert(input, route.convert);
+        if (access?.dryRun)
+            return access.response();
+        data = await route.run(getDb(), caller, input, options.handlers);
+    }
+    const headers = { "cache-control": "private, no-store" };
+    const response = request.method === "HEAD" ? new Response(null, { headers }) : Response.json(data, { headers });
+    access?.finish();
+    return response;
+}

package/dist/kernel/rest-router.js

@@ -0,0 +1,63 @@
+/** Route matching and caller enforcement load on the first request. */
+import { forwarded, ContractError, checkOrigin, surfaceCaller } from "./contracts.js";
+import { decode, invalid } from "./surface.js";
+const isApi = (path) => path === "/api" || path.startsWith("/api/");
+const fail = message => invalid(message, "rest");
+/** Shared matching/auth/error envelope; selected dispatch is supplied by the surface. */
+export function router(routes, options, send) {
+    return async (request, env, ctx) => {
+        let caller;
+        const isForwarded = forwarded(ctx, options.gateway);
+        const access = options.gateway ? (await import("./host-access.js")).accessRequest(ctx, options) : undefined;
+        try {
+            await access?.select(`rest:${request.method} ${new URL(request.url).pathname}`);
+            if (isForwarded)
+                caller = (await import("./host-caller.js")).gatewayCaller(ctx, options.gateway, options.fields);
+            const original = new URL(request.url).pathname;
+            let path;
+            try {
+                path = original.split("/").map(segment => encodeURIComponent(decodeURIComponent(segment))).join("/");
+            }
+            catch {
+                if (!isApi(original))
+                    return undefined;
+                fail("Malformed request path.");
+            }
+            const allowed = new Set();
+            for (const route of routes) {
+                const match = route.pattern.exec(path);
+                if (!match)
+                    continue;
+                allowed.add(route.method);
+                const read = !!route.page && !route.run && !route.handle;
+                if (route.method !== request.method && !(request.method === "HEAD" && route.method === "GET" && read))
+                    continue;
+                const params = decode(route.keys ?? [], match, "Malformed path parameter.", "rest");
+                const id = route.id ?? `rest:${route.method} ${decodeURIComponent(path).replace(/\/$/, "")}`;
+                await access?.select(id);
+                caller ??= await surfaceCaller(request, env, options.caller ?? (() => ({ kind: "anonymous" })), read && ["GET", "HEAD"].includes(request.method));
+                await access?.select(id, caller);
+                await access?.check(read || route.readOnly === true);
+                if (!options.gateway || !read && !route.readOnly)
+                    checkOrigin(request, caller);
+                const response = await send(route, request, env, caller, params, access);
+                await access?.finishResponse(response);
+                return response;
+            }
+            if (allowed.size) {
+                const error = new ContractError("METHOD_NOT_ALLOWED", "Method is not allowed for this route.", "rest");
+                access?.finish(error);
+                const response = (await import("./host-caller.js")).hostFailure(error, caller, "rest");
+                response.headers.set("allow", [...allowed].join(", "));
+                return response;
+            }
+            if (isApi(path))
+                throw new ContractError("NOT_FOUND", "No such route.", "rest");
+            return undefined;
+        }
+        catch (error) {
+            access?.finish(error);
+            return (await import("./host-caller.js")).hostFailure(error, caller, `rest ${request.method} ${new URL(request.url).pathname}`);
+        }
+    };
+}