@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.8

package/dist/kernel/contracts.d.ts

@@ -0,0 +1,139 @@
+/** Boundary primitives only. No plan, SQL interpreter or resource ownership. */
+import { ContractError } from "./contract-error.js";
+export { ContractError } from "./contract-error.js";
+import { isAdminCaller as isAdmin } from "./caller-identity.js";
+export type CredentialKind = "session" | "oauth" | "api-key" | "personal-token";
+export interface Gateway {
+    readonly tenant: string;
+}
+export interface RequestContext {
+    readonly props?: unknown;
+}
+/** Gateway mode or the one execution prop carrying forwarded authority. */
+export declare const forwarded: (ctx?: RequestContext, gateway?: Gateway) => boolean;
+/** Generated gateway metadata is loaded only after a forwarded request. */
+export interface AccessTarget {
+    readonly targetHash: string;
+    readonly opaque: boolean;
+    readonly guard?: string;
+    readonly variants?: readonly (Pick<AccessTarget, "opaque" | "guard"> & {
+        readonly id: string;
+    })[];
+}
+export interface AccessEvent {
+    readonly v: 1;
+    readonly requestId: string;
+    readonly target: string;
+    readonly targetHash: string;
+    readonly caller: {
+        readonly kind: string;
+        readonly subject: string;
+        readonly layer: "admin" | "member";
+    };
+    readonly outcome: "allow" | "deny" | "error";
+    readonly reason?: string;
+    readonly field?: string;
+    readonly dryRun: boolean;
+}
+export interface GatewayOptions {
+    readonly accessTargets?: () => Promise<Readonly<Record<string, AccessTarget>>>;
+    readonly onAccess?: (event: AccessEvent) => void | Promise<void>;
+}
+type IdentityCaller = {
+    /** Application subject key: opaque, stable, unique across issuers. Never an email. */
+    readonly subject: string;
+    readonly issuer?: string;
+    /** Verified real actor during impersonation; retained only by the original identity. */
+    readonly impersonatedBy?: string;
+    readonly role: string | null;
+    /** Informational; only the private identity brand grants the admin layer. */
+    readonly admin?: boolean;
+    readonly roles?: readonly string[];
+    readonly fields?: Readonly<Record<string, import("./user-fields.js").UserValue>>;
+    readonly scopes: readonly string[];
+    readonly credential: CredentialKind;
+    /** Opaque record id or token JTI, never the raw credential. */
+    readonly credentialId: string | null;
+    readonly clientId: string | null;
+    readonly authenticatedAs?: "snapshot" | "fresh";
+    readonly requestId?: string;
+    readonly target?: string;
+    readonly targetHash?: string;
+    readonly dryRun?: boolean;
+};
+export type Caller = {
+    readonly kind: "anonymous";
+} | (IdentityCaller & {
+    readonly kind: "user";
+}) | (IdentityCaller & {
+    readonly kind: "host";
+    readonly authenticatedAs: "snapshot" | "fresh";
+    readonly requestId: string;
+}) | {
+    readonly kind: "system";
+    readonly reason: string;
+};
+/** A selected boundary's application authorization target. */
+export type Target = {
+    kind: "view" | "procedure" | "schema";
+    name: string;
+    action?: "read" | "create" | "update" | "delete";
+};
+export type Authorize = (target: Target, caller: Caller) => boolean | Promise<boolean>;
+/** Privilege never follows a member role name. Only the original verified identity carries the admin layer. */
+export { isAdmin };
+/** Both authenticated layers pass ctx.user; the host layer still needs its original brand. */
+export declare const isUser: (caller: Caller) => boolean;
+export declare const hasAdminRole: (caller: Caller, name: string) => boolean;
+/** Only the core transport failures; other codes carry their own status, and unknown codes remain server errors. */
+export declare const statusOf: (code: string) => number;
+/** Redact native errors at the selected boundary; the bare query preserves their identity. */
+export declare function wire(error: unknown): {
+    status: number;
+    error: {
+        code: string;
+        message: string;
+        path: string;
+        [field: string]: unknown;
+    };
+};
+/** One result row. */
+export type Row = Record<string, unknown>;
+/** Static declared-column conversions, used only by selected transport boundaries. */
+export type WireColumns = ReadonlyArray<readonly [field: string, type: "json" | "bool" | "int"]>;
+export declare function wireRows(rows: readonly Row[], fields?: WireColumns): readonly Row[];
+/** What a generated SQL Procedure returns: the rows of each statement, in order. */
+export type Output = {
+    readonly results: ReadonlyArray<ReadonlyArray<Row>>;
+};
+/** Deny unless `allowed`: a user is AUTH_DENIED, anyone else UNAUTHENTICATED. */
+export declare function deny(caller: Caller, allowed: boolean, path: string): void;
+/** CONFLICT for a write the database refused: a unique-index clash, or a row statement that did not change exactly one row. */
+export declare const conflict: (path: string, unique: boolean, cause?: unknown) => ContractError;
+/** A Schema `checks` violation (Mantle's SQLite check trigger, or PostgreSQL SQLSTATE 23514) is a CONFLICT naming the check. */
+export declare const checkConflict: (path: string, error: unknown, violated?: boolean) => ContractError | undefined;
+/** One result of `unsafe`: the rows (typed by the generated function), plus the affected count. */
+export type PostgresResult = any[] & {
+    readonly count: number | null;
+};
+/**
+ * The PostgreSQL handle bare generated code calls: Bun.SQL's own shape, so Bun passes its `SQL` directly. A Bun
+ * transaction handle suits generated queries; the driver marks Store transaction handles to suppress nested `begin`. Other drivers adapt to it (see README). `begin` must run every statement of `fn` on one connection and
+ * COMMIT only after `fn` resolves.
+ */
+export interface Postgres {
+    unsafe(text: string, values: any[]): PromiseLike<PostgresResult>;
+    /** The transaction handle only needs `unsafe`: postgres.js 3.4.9 types it without `begin`. */
+    begin<T>(options: string, fn: (tx: Unsafe) => Promise<T>): PromiseLike<T>;
+}
+/** What a read or a single statement needs: a transaction handle suits it too. */
+export type Unsafe = Pick<Postgres, "unsafe">;
+/** A cookie is ambient authority; bearer credentials deliberately supplied by the app are not. */
+export declare function checkOrigin(request: Request, caller: Caller): void;
+/** A resolver's ContractError (e.g. UNAUTHENTICATED for an expired token) keeps its status; anything else is an application failure. */
+export declare function surfaceCaller<Env>(request: Request, env: Env, resolve: (request: Request, env: Env, authority: {
+    readonly readOnly: boolean;
+}) => Caller | Promise<Caller>, readOnly?: boolean): Promise<Caller>;
+/** The client sees the redacted wire form; the log gets the surface (a route or tool, never headers) and the original message, stack and cause. */
+export declare function surfaceError(error: unknown, where?: string): ReturnType<typeof wire>;
+export declare function surfaceFailure(error: unknown, challenge?: string, where?: string): Response;

package/dist/kernel/contracts.js

@@ -0,0 +1,92 @@
+/** Boundary primitives only. No plan, SQL interpreter or resource ownership. */
+import { ContractError } from "./contract-error.js";
+export { ContractError } from "./contract-error.js";
+import { hasRole, isAdminCaller as isAdmin } from "./caller-identity.js";
+/** Gateway mode or the one execution prop carrying forwarded authority. */
+export const forwarded = (ctx, gateway) => !!(gateway || ctx?.props && Object.hasOwn(ctx.props, "mantle"));
+/** Privilege never follows a member role name. Only the original verified identity carries the admin layer. */
+export { isAdmin };
+/** Both authenticated layers pass ctx.user; the host layer still needs its original brand. */
+export const isUser = (caller) => caller.kind === "user" || isAdmin(caller);
+export const hasAdminRole = (caller, name) => isAdmin(caller) && hasRole(caller, name);
+/** Only the core transport failures; other codes carry their own status, and unknown codes remain server errors. */
+export const statusOf = (code) => ({ __proto__: null,
+    INPUT_VALIDATION_FAILED: 400, UNAUTHENTICATED: 401, AUTH_DENIED: 403, NOT_FOUND: 404,
+    METHOD_NOT_ALLOWED: 405, CONFLICT: 409, OUTCOME_UNKNOWN: 503,
+}[code] ?? 500);
+/** Redact native errors at the selected boundary; the bare query preserves their identity. */
+export function wire(error) {
+    const status = error instanceof ContractError ? error.status ?? statusOf(error.code) : 500;
+    if (status !== 500) {
+        const { code, message, path, fields } = error;
+        return { status, error: { code, message, path, ...fields } };
+    }
+    return { status, error: { code: "INTERNAL_ERROR", message: "An internal error occurred.", path: "" } };
+}
+export function wireRows(rows, fields = []) {
+    if (!fields.length)
+        return rows;
+    return rows.map(row => {
+        const result = { ...row };
+        for (const [key, type] of fields)
+            if (Object.hasOwn(row, key) && row[key] != null) {
+                const value = row[key];
+                if (type === "json") {
+                    try {
+                        result[key] = JSON.parse(value);
+                    }
+                    catch {
+                        throw new ContractError("INVALID_STORED_JSON", "Persisted JSON could not be parsed.");
+                    }
+                }
+                else
+                    result[key] = type === "bool" ? value === true || value === 1
+                        : typeof value === "number" || Number.isSafeInteger(Number(value)) ? Number(value) : String(value);
+            }
+        return result;
+    });
+}
+/** Deny unless `allowed`: a user is AUTH_DENIED, anyone else UNAUTHENTICATED. */
+export function deny(caller, allowed, path) {
+    if (!allowed)
+        throw new ContractError("subject" in caller ? "AUTH_DENIED" : "UNAUTHENTICATED", "Authorization predicate not satisfied.", path);
+}
+/** CONFLICT for a write the database refused: a unique-index clash, or a row statement that did not change exactly one row. */
+export const conflict = (path, unique, cause) => new ContractError("CONFLICT", unique ? "A unique constraint of the Schema was violated." : "Expected one affected row.", path, { cause });
+/** A Schema `checks` violation (Mantle's SQLite check trigger, or PostgreSQL SQLSTATE 23514) is a CONFLICT naming the check. */
+export const checkConflict = (path, error, violated = /MANTLE_CHECK /.test(String(error?.message))) => {
+    if (!violated)
+        return undefined;
+    const message = String(error?.message ?? "");
+    return new ContractError("CONFLICT", `A check of the Schema failed: ${/MANTLE_CHECK [^\n'"]+/.exec(message)?.[0] ?? message}`, path, { cause: error });
+};
+/** A cookie is ambient authority; bearer credentials deliberately supplied by the app are not. */
+export function checkOrigin(request, caller) {
+    if (!("credential" in caller) || caller.credential !== "session" || ["GET", "HEAD", "OPTIONS"].includes(request.method))
+        return;
+    const site = request.headers.get("sec-fetch-site"), origin = request.headers.get("origin");
+    if ((!site && !origin) || (site && site !== "same-origin" && site !== "none") || (origin && origin !== new URL(request.url).origin))
+        throw new ContractError("AUTH_DENIED", "Cross-origin session mutation rejected.", "request:origin");
+}
+/** A resolver's ContractError (e.g. UNAUTHENTICATED for an expired token) keeps its status; anything else is an application failure. */
+export async function surfaceCaller(request, env, resolve, readOnly = false) {
+    try {
+        return await resolve(request, env, { readOnly });
+    }
+    catch (cause) {
+        if (cause instanceof ContractError)
+            throw cause;
+        throw new Error("Caller resolution failed.", { cause });
+    }
+}
+/** The client sees the redacted wire form; the log gets the surface (a route or tool, never headers) and the original message, stack and cause. */
+export function surfaceError(error, where = "surface") {
+    const result = wire(error);
+    if (result.status === 500)
+        console.error(`[mantle ${where}] unhandled failure`, error);
+    return result;
+}
+export function surfaceFailure(error, challenge, where) {
+    const result = surfaceError(error, where);
+    return Response.json({ error: result.error }, { status: result.status, headers: { "cache-control": "private, no-store", ...(challenge && [401, 403].includes(result.status) && result.error.path !== "request:origin" ? { "www-authenticate": challenge } : {}) } });
+}

package/dist/{spec/domain/service/CloudflareCron.d.ts → kernel/cron.d.ts}

@@ -1,2 +1 @@
 export declare function toCloudflareCron(cron: string): string;
-//# sourceMappingURL=CloudflareCron.d.ts.map

package/dist/{spec/domain/service/CloudflareCron.js → kernel/cron.js}

@@ -1,8 +1,4 @@
-/**
- * `toCloudflareCron` (ADR-0032 decision 5 and amendment "the service preset"): a five-field POSIX cron (weekday 0 = Sunday) as
- * Cloudflare's cron triggers spell it (weekday 1 = Sunday through 7 = Saturday). Only explicit weekday numbers move. It lives in
- * spec, outside the barrel, so the CLI can write `wrangler.jsonc` with it; `@aotter/mantle/cloudflare` is its public home.
- */
+/** SDK-owned POSIX to Cloudflare cron conversion, copied verbatim from Core's CloudflareCron so Workers don't pull Core's D1 driver; Core is retired with 0.2.0, so this copy becomes the only one. */
 const PART = /^(\*|\d+|[A-Za-z]{3})(?:-(\d+|[A-Za-z]{3}))?(?:\/(\d+))?$/;
 const MONTHS = ["JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"];
 const DAYS = ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"];
@@ -60,4 +56,3 @@ export function toCloudflareCron(cron) {
         refuse("restrict the day of month or the weekday, not both");
     return [...fields.slice(0, 4), weekday.join(",")].join(" ");
 }
-//# sourceMappingURL=CloudflareCron.js.map

package/dist/kernel/dialect/common.d.ts

@@ -0,0 +1,39 @@
+/** What SQLite and PostgreSQL spell identically, defined once; each dialect module re-exports it. */
+/** A (possibly schema-qualified) name, quoted. */
+export declare const ident: (name: string) => string;
+/** A literal piece of text for a LIKE pattern: `\`, `%` and `_` match themselves. Pair with `likeEscape`. */
+export declare const escapeLike: (value: string) => string;
+export declare const likeEscape = " ESCAPE '\\'";
+/**
+ * How one engine spells SQL and stores values, exactly what the Store needs: each dialect module exports it as `dialect` (and its
+ * members by name, so a bundle that uses a few carries only those). A generated bundle imports one dialect; nothing branches on it.
+ */
+export interface Dialect {
+    readonly userRefs?: import('../binds.js').Values['userRefs'];
+    readonly user?: import('../binds.js').Values['user'];
+    readonly anyOf?: (column: string, placeholder: string, type: 'string' | 'number') => string;
+    readonly scopeInsert?: (scopes: readonly {
+        readonly column: string;
+        readonly field: string;
+        readonly type: 'string' | 'number';
+    }[], caller: import('../contracts.js').Caller, set: object) => object;
+    /** The `n`th (1-based) numbered placeholder. */
+    param(n: number): string;
+    ident(name: string): string;
+    escapeLike(value: string): string;
+    likeEscape: string;
+    /** The LIKE keyword; PostgreSQL's is case-sensitive unless `insensitive`. */
+    like(insensitive: boolean): string;
+    /** Search declared text fields; the caller separately permits an exact id match. */
+    search(table: string, fields: readonly string[], alias: string, query: string): string;
+    /** A declared date-time / date in its wire form (ISO UTC with six digits, `YYYY-MM-DD`): text parts interleaved with the operand. */
+    wireTimestamp<T>(v: T): (string | T)[];
+    wireDate<T>(v: T): (string | T)[];
+    /** Bind values: `now()` and a TTL cutoff from epoch milliseconds, declared ISO inputs, and the typed Store inputs. */
+    now(ms: number): unknown;
+    cutoff(ms: number, seconds: number): unknown;
+    timestamp(v: string | Date): unknown;
+    date(v: string): unknown;
+    /** A placeholder compared with, or written to, a column of this type, so every driver sends the value verbatim (postgres.js would turn text bound to timestamptz or date into a JavaScript Date and lose microseconds). */
+    cast(placeholder: string, type: string): string;
+}

package/dist/kernel/dialect/common.js

@@ -0,0 +1,6 @@
+/** What SQLite and PostgreSQL spell identically, defined once; each dialect module re-exports it. */
+/** A (possibly schema-qualified) name, quoted. */
+export const ident = (name) => name.split(".").map(part => `"${part.replaceAll('"', '""')}"`).join(".");
+/** A literal piece of text for a LIKE pattern: `\`, `%` and `_` match themselves. Pair with `likeEscape`. */
+export const escapeLike = (value) => value.replace(/[\\%_]/g, "\\$&");
+export const likeEscape = " ESCAPE '\\'";

package/dist/kernel/dialect/postgres.d.ts

@@ -0,0 +1,16 @@
+/** PostgreSQL: `$n` placeholders, time as timestamptz (ISO text keeps every microsecond). */
+import { isoTimestamptz } from "../scalars.js";
+import { escapeLike, ident, likeEscape, type Dialect } from "./common.js";
+export { ident, escapeLike, likeEscape };
+export declare const param: (n: number) => string;
+export declare const anyOf: (column: string, placeholder: string, type: "string" | "number") => string;
+export declare const like: (insensitive: boolean) => string;
+export declare const wireTimestamp: <T>(v: T) => (string | T)[];
+export declare const wireDate: <T>(v: T) => (string | T)[];
+export declare const now: (ms: number) => Date;
+export declare const cutoff: (ms: number, seconds: number) => Date;
+export declare const timestamp: typeof isoTimestamptz;
+export declare const date: (v: string) => string;
+export declare const cast: (placeholder: string, type: string) => string;
+export declare const search: (_table: string, fields: readonly string[], alias: string, query: string) => string;
+export declare const dialect: Dialect;

package/dist/kernel/dialect/postgres.js

@@ -0,0 +1,18 @@
+/** PostgreSQL: `$n` placeholders, time as timestamptz (ISO text keeps every microsecond). */
+import { isoDate, isoTimestamptz } from "../scalars.js";
+import { searchLike } from "../search.js";
+import { escapeLike, ident, likeEscape } from "./common.js";
+export { ident, escapeLike, likeEscape };
+export const param = (n) => `$${n}`;
+export const anyOf = (column, placeholder, type) => `${column} = ANY(CAST(CAST(${placeholder} AS text) AS ${type === 'number' ? 'float8' : 'text'}[]))`;
+export const like = (insensitive) => insensitive ? "ILIKE" : "LIKE";
+export const wireTimestamp = (v) => ["to_char((", v, ") AT TIME ZONE 'UTC', 'YYYY-MM-DD\"T\"HH24:MI:SS.US\"Z\"')"];
+export const wireDate = (v) => ["to_char(", v, ", 'YYYY-MM-DD')"];
+export const now = (ms) => new Date(ms);
+export const cutoff = (ms, seconds) => new Date(ms - seconds * 1000);
+export const timestamp = isoTimestamptz;
+export const date = isoDate;
+export const cast = (placeholder, type) => type === "timestamptz" || type === "date" ? `CAST(CAST(${placeholder} AS text) AS ${type})` : type === "json" ? `CAST(CAST(${placeholder} AS text) AS jsonb)` : placeholder;
+// ponytail: preserve Core's ILIKE scan; add pg_trgm only when measured search latency needs it.
+export const search = (_table, fields, alias, query) => searchLike(fields.map(field => `${alias}.${ident(field)}`), query, "ILIKE");
+export const dialect = { param, ident, escapeLike, likeEscape, like, search, wireTimestamp, wireDate, now, cutoff, timestamp, date, cast, anyOf };

package/dist/kernel/dialect/sqlite.d.ts

@@ -0,0 +1,20 @@
+/** SQLite and Cloudflare D1: `?n` placeholders, time as microseconds and dates as days since the epoch. */
+import { encodeDate, encodeTimestamptz } from "../scalars.js";
+import { escapeLike, ident, likeEscape, type Dialect } from "./common.js";
+export { ident, escapeLike, likeEscape };
+export declare const param: (n: number) => string;
+export declare const anyOf: (column: string, placeholder: string) => string;
+export declare const like: () => string;
+/** A write that broke a UNIQUE index or the id's UNIQUE (bun:sqlite and D1 word it the same). */
+export declare const unique: (error: unknown) => boolean;
+/** Positive rollback evidence only. Plain/network/I/O errors are deliberately uncertain. */
+export declare function definitive(error: unknown): boolean;
+export declare const wireTimestamp: <T>(v: T) => (string | T)[];
+export declare const wireDate: <T>(v: T) => (string | T)[];
+export declare const now: (ms: number) => number;
+export declare const cutoff: (ms: number, seconds: number) => number;
+export declare const timestamp: typeof encodeTimestamptz;
+export declare const date: typeof encodeDate;
+export declare const cast: (placeholder: string) => string;
+export declare function search(table: string, fields: readonly string[], alias: string, query: string): string;
+export declare const dialect: Dialect;

package/dist/kernel/dialect/sqlite.js

@@ -0,0 +1,34 @@
+import { ContractError } from "../contracts.js";
+/** SQLite and Cloudflare D1: `?n` placeholders, time as microseconds and dates as days since the epoch. */
+import { encodeDate, encodeTimestamptz } from "../scalars.js";
+import { searchLike } from "../search.js";
+import { escapeLike, ident, likeEscape } from "./common.js";
+export { ident, escapeLike, likeEscape };
+export const param = (n) => `?${n}`;
+export const anyOf = (column, placeholder) => `${column} IN (SELECT value FROM json_each(${placeholder}))`;
+export const like = () => "LIKE"; // SQLite's LIKE already ignores ASCII case
+/** A write that broke a UNIQUE index or the id's UNIQUE (bun:sqlite and D1 word it the same). */
+export const unique = (error) => /UNIQUE constraint failed/.test(String(error?.message));
+/** Positive rollback evidence only. Plain/network/I/O errors are deliberately uncertain. */
+export function definitive(error) {
+    if (error instanceof ContractError)
+        return error.code === "CONFLICT";
+    const e = error;
+    // Bun before 1.4 omits `code` on statement errors; its SQLiteError still carries the native errno.
+    const native = typeof e?.code === "string" ? e.code.startsWith("SQLITE_") : e?.name === "SQLiteError";
+    return native && typeof e.errno === "number" && [1, 19, 20, 25].includes(e.errno & 255);
+}
+// floor, not SQLite's truncating `/` and `%`: a time before 1970 is a negative number of microseconds
+export const wireTimestamp = (v) => ["strftime('%Y-%m-%dT%H:%M:%S', ((", v, ") - ((", v, ") % 1000000 + 1000000) % 1000000) / 1000000, 'unixepoch') || '.' || substr('00000' || (((", v, ") % 1000000 + 1000000) % 1000000), -6) || 'Z'"];
+export const wireDate = (v) => ["date((", v, ") * 86400, 'unixepoch')"];
+export const now = (ms) => ms * 1000;
+export const cutoff = (ms, seconds) => ms * 1000 - seconds * 1_000_000;
+export const timestamp = encodeTimestamptz;
+export const date = encodeDate;
+export const cast = (placeholder) => placeholder;
+export function search(table, fields, alias, query) {
+    const fts = ident(`_mantle_fts_${table}`);
+    const phrase = `'"' || replace(${query}, '"', '""') || '"'`;
+    return `CASE WHEN length(${query}) >= 3 THEN ${alias}._rid IN (SELECT rowid FROM ${fts} WHERE ${fts} = ${phrase}) ELSE (${searchLike(fields.map(field => `${alias}.${ident(field)}`), query, "LIKE")}) END`;
+}
+export const dialect = { param, ident, escapeLike, likeEscape, like, search, wireTimestamp, wireDate, now, cutoff, timestamp, date, cast, anyOf };

package/dist/kernel/drain.d.ts

@@ -0,0 +1,5 @@
+/** Request-time only: no Worker startup path imports this. */
+/** A request handler that drains the body once it has answered or thrown. `undefined` and `null` mean the request is not this
+ *  handler's, so the next handler can still read it. A handler that answers and reads the request later (in `waitUntil`) must
+ *  read or lock the body before answering. */
+export declare const draining: <A extends [Request, ...any[]], R>(handle: (...args: A) => Promise<R>) => (...args: A) => Promise<R>;

package/dist/kernel/drain.js

@@ -0,0 +1,35 @@
+/** Request-time only: no Worker startup path imports this. */
+/** Read and discard what is left of a request body, at most 1 MiB and 1 s. A response sent over an unread POST body makes local
+ *  `wrangler dev` break the connection, and the next request fails with "Network connection lost". */
+async function drain(request) {
+    let reader;
+    const timer = setTimeout(() => reader?.cancel().catch(() => { }), 1000);
+    try {
+        reader = request.body?.getReader(); // a body the app consumed is done; one it still holds is locked and throws
+        for (let read = 0, chunk; reader && !(chunk = await reader.read()).done;)
+            if ((read += chunk.value.byteLength) > 1024 * 1024) {
+                await reader.cancel();
+                return;
+            }
+    }
+    catch { /* the client went away */ }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** A request handler that drains the body once it has answered or thrown. `undefined` and `null` mean the request is not this
+ *  handler's, so the next handler can still read it. A handler that answers and reads the request later (in `waitUntil`) must
+ *  read or lock the body before answering. */
+export const draining = (handle) => async (...args) => {
+    let response;
+    try {
+        response = await handle(...args);
+    }
+    catch (error) {
+        await drain(args[0]);
+        throw error;
+    }
+    if (response != null)
+        await drain(args[0]);
+    return response;
+};

package/dist/kernel/driver/bun-sqlite.d.ts

@@ -0,0 +1,19 @@
+/** `bun:sqlite`: sync queries; interactive transactions queue all work on the same Database. */
+import type { Bound } from "../binds.js";
+import { type Row } from "../contracts.js";
+export { definitive } from "../dialect/sqlite.js";
+export interface Handle {
+    query(sql: string): {
+        readonly columnNames: readonly string[];
+        all(...values: any[]): any[];
+        run(...values: any[]): {
+            readonly changes: number | bigint;
+        };
+    };
+    exec(sql: string): unknown;
+    transaction(fn: (db: any) => any): (db: any) => any;
+}
+export declare const read: (db: Handle, sql: string, binds: unknown[]) => any[] | Promise<any[]>;
+/** One statement is atomic on its own; several run in a transaction, and a row statement that does not change exactly one row rolls it back. A unique-index clash is CONFLICT. */
+export declare function procedure(db: Handle, steps: readonly Bound[], path: string): Promise<Row[][]>;
+export declare function transaction<T>(db: Handle, fn: (tx: Handle) => Promise<T>): Promise<T>;

package/dist/kernel/driver/bun-sqlite.js

@@ -0,0 +1,77 @@
+import { checkConflict, conflict, ContractError } from "../contracts.js";
+import { unique } from "../dialect/sqlite.js";
+export { definitive } from "../dialect/sqlite.js";
+import { context, guard } from "./transaction-context.js";
+const transactions = new WeakSet();
+const queues = new WeakMap();
+/** Only queued transactions make otherwise synchronous statements wait; a rejection cannot poison the queue. */
+function enqueue(db, fn) {
+    const result = (queues.get(db) ?? Promise.resolve()).then(fn);
+    const tail = result.then(() => { }, () => { });
+    queues.set(db, tail);
+    void tail.then(() => { if (queues.get(db) === tail)
+        queues.delete(db); });
+    return result;
+}
+const available = (db, fn) => { guard(db); return queues.has(db) ? enqueue(db, fn) : fn(); };
+export const read = (db, sql, binds) => available(db, () => db.query(sql).all(...binds));
+/** One statement is atomic on its own; several run in a transaction, and a row statement that does not change exactly one row rolls it back. A unique-index clash is CONFLICT. */
+export async function procedure(db, steps, path) {
+    const execute = (handle) => steps.map(s => {
+        const statement = handle.query(s.sql);
+        // a statement with columns (SELECT, RETURNING) gives rows, and their number is its affected count
+        let rows = [], changes;
+        try {
+            rows = statement.columnNames.length ? statement.all(...s.binds) : [];
+            if (statement.columnNames.length)
+                changes = rows.length;
+            else {
+                statement.run(...s.binds);
+                // Bun's run().changes includes FTS maintenance writes; SQLite changes() counts the authored statement only.
+                changes = s.row ? Number(handle.query("SELECT changes() AS n").all()[0].n) : 0;
+            }
+        }
+        catch (error) {
+            throw unique(error) ? conflict(path, true, error) : checkConflict(path, error) ?? error;
+        }
+        if (s.row && changes !== 1)
+            throw conflict(path, false);
+        return rows;
+    });
+    return available(db, () => transactions.has(db) || steps.length === 1 ? execute(db) : db.transaction(execute)(db));
+}
+export async function transaction(db, fn) {
+    guard(db);
+    if (transactions.has(db))
+        throw new Error("Nested transactions are not supported.");
+    return enqueue(db, async () => {
+        db.exec("BEGIN IMMEDIATE");
+        let active = true;
+        const tx = { query: sql => {
+                if (!active)
+                    throw new Error("Transaction has ended.");
+                return db.query(sql);
+            }, exec: db.exec.bind(db), transaction: db.transaction.bind(db) };
+        transactions.add(tx);
+        const state = { outer: db, handle: tx };
+        try {
+            const result = await context.run(state, () => fn(tx));
+            db.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch (rollback) {
+                throw new ContractError("OUTCOME_UNKNOWN", "Rollback failed; reconcile before retrying.", "store/transaction", { cause: new AggregateError([error, rollback]) });
+            }
+            throw error;
+        }
+        finally {
+            active = false;
+            state.outer = undefined;
+            state.handle = undefined;
+        }
+    });
+}

package/dist/kernel/driver/d1.d.ts

@@ -0,0 +1,24 @@
+/** Cloudflare D1: no interactive transactions, so a Procedure is one `batch` whose row checks go through `_mantle_assert`. */
+import type { Bound } from "../binds.js";
+import { type Row } from "../contracts.js";
+export { definitive } from "../dialect/sqlite.js";
+interface Statement {
+    bind(...values: any[]): Statement;
+    all(): Promise<{
+        results: any[];
+        meta: {
+            changes: number;
+        };
+    }>;
+}
+export interface Reader {
+    prepare(sql: string): Statement;
+}
+export interface Handle extends Reader {
+    batch(statements: any[]): Promise<{
+        results: any[];
+    }[]>;
+}
+export declare const read: (db: Reader, sql: string, binds: unknown[]) => Promise<any[]>;
+/** The assert table's trigger aborts the whole batch with `CONFLICT op=<k>` when statement k did not change exactly one row. */
+export declare function procedure(db: Handle, steps: readonly Bound[], path: string): Promise<Row[][]>;

package/dist/kernel/driver/d1.js

@@ -0,0 +1,22 @@
+import { checkConflict, conflict } from "../contracts.js";
+import { unique } from "../dialect/sqlite.js";
+export { definitive } from "../dialect/sqlite.js";
+export const read = async (db, sql, binds) => (await db.prepare(sql).bind(...binds).all()).results;
+/** The assert table's trigger aborts the whole batch with `CONFLICT op=<k>` when statement k did not change exactly one row. */
+export async function procedure(db, steps, path) {
+    const batch = [], at = [];
+    steps.forEach((s, i) => {
+        at.push(batch.length);
+        batch.push(db.prepare(s.sql).bind(...s.binds));
+        if (s.row)
+            batch.push(db.prepare(`INSERT INTO _mantle_assert (op,ok) SELECT ${i}, changes() = 1`));
+    });
+    let out;
+    try {
+        out = await db.batch(batch);
+    }
+    catch (error) {
+        throw unique(error) ? conflict(path, true, error) : /CONFLICT op=\d/.test(String(error?.message)) ? conflict(path, false, error) : checkConflict(path, error) ?? error;
+    }
+    return at.map(i => out[i].results);
+}

package/dist/kernel/driver/postgres.d.ts

@@ -0,0 +1,25 @@
+/** Bun.SQL's PostgreSQL shape (`Postgres`); postgres.js satisfies it as it is. */
+import type { Bound } from "../binds.js";
+import type { TransactionOptions } from "../store.js";
+import { type Postgres, type PostgresResult, type Row, type Unsafe } from "../contracts.js";
+export declare const read: (db: Unsafe, sql: string, binds: unknown[]) => PromiseLike<PostgresResult>;
+export declare function run(db: Unsafe, sql: string, binds: unknown[]): Promise<{
+    rows: any[];
+    changes: number;
+}>;
+/** A structured server ErrorResponse proves rollback; missing evidence is uncertain. */
+export declare function definitive(error: unknown): boolean;
+/**
+ * The error to throw when a PostgreSQL write fails where it may already have committed (autocommit, or COMMIT).
+ * A server ErrorResponse (SQLSTATE + severity) outside connection/resource classes rolled back; anything else, such as a
+ * lost socket, is OUTCOME_UNKNOWN.
+ */
+export declare function postgresOutcome(error: unknown, path: string): unknown;
+/**
+ * One statement is atomic on its own (a row statement touches at most one row, so a failed count check changes nothing)
+ * and runs in autocommit. Several run in `begin(serializable)`: a failure before the callback returns was rolled back;
+ * only a failed COMMIT can leave the outcome unknown.
+ */
+export declare function procedure(db: Postgres, steps: readonly Bound[], path: string): Promise<Row[][]>;
+/** Shared BEGIN/COMMIT outcome handling for Procedures and interactive Store transactions. */
+export declare function transaction<T>(db: Postgres, fn: (tx: Postgres) => Promise<T>, options?: TransactionOptions, path?: string): Promise<T>;