@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/dist/kernel/binds.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Core's bind recipes (`BindSpec` in the policy rewriter), evaluated for one call. Generated Views, generated
+ * Procedures and the Store all bind through this one function. Input recipes carry the authored field name; `version` reads the Store's lock from `input`.
+ */
+import { type Caller } from "./contracts.js";
+import type { Dialect } from "./dialect/common.js";
+export type Recipe = {
+    readonly k: "user";
+    readonly field: string;
+    readonly type: "string" | "number";
+    readonly multiple: boolean;
+    readonly scope?: true;
+} | {
+    readonly k: "uid" | "admin" | "now" | "version";
+} | {
+    readonly k: "cutoff";
+    readonly seconds: number;
+} | {
+    readonly k: "const";
+    readonly value: unknown;
+}
+/** A field-scoped Schema's scope column on an SQL INSERT: the Store's insert rule (autofill one value, refuse a value outside the caller's set). */
+ | {
+    readonly k: "scoped";
+    readonly column: string;
+    readonly field: string;
+    readonly type: "string" | "number";
+    readonly name?: string;
+    readonly value?: string | number;
+} | {
+    readonly k: "input";
+    readonly name: string; /** Only a date-time, a date or JSON is converted, so only those carry a type. */
+    readonly type?: "timestamptz" | "date" | "json";
+};
+/** One printed statement and how to bind it. `row`: it must affect exactly one row. */
+export interface Step {
+    readonly sql: string;
+    readonly binds: readonly Recipe[];
+    readonly row?: boolean;
+}
+export type Bound = {
+    readonly sql: string;
+    readonly binds: unknown[];
+    readonly row?: boolean;
+};
+/** The dialect functions the recipes in use call; generated code passes only those. */
+export type Values = Partial<Pick<Dialect, "now" | "cutoff" | "timestamp" | "date">> & {
+    readonly scopeInsert?: Dialect['scopeInsert'];
+    readonly userRefs?: (recipe: Recipe, caller: Caller, input?: Readonly<Record<string, unknown>>) => unknown;
+    /** Present only in apps with user fields: keeps, per caller, one printed form of each Schema scope term. */
+    readonly scopedAll?: <T>(value: T, caller: Caller) => T;
+};
+/**
+ * A declared date-time or date as the engine stores it, and a JSON value as its text (a string, such as a boundary's
+ * already converted value, is bound as it is); any other value (and `null`) is bound as it is.
+ */
+export declare const encode: (d: Values, type: string | undefined, v: unknown) => unknown;
+export declare function binds(d: Values, recipes: readonly Recipe[], caller: Caller, input?: Readonly<Record<string, unknown>>, ms?: number): unknown[];
+/** Every step's binds, evaluated for a Procedure. */
+export declare function bound(d: Values, steps: readonly Step[], caller: Caller, input?: Readonly<Record<string, unknown>>): Bound[];

package/dist/kernel/binds.js

@@ -0,0 +1,49 @@
+/**
+ * Core's bind recipes (`BindSpec` in the policy rewriter), evaluated for one call. Generated Views, generated
+ * Procedures and the Store all bind through this one function. Input recipes carry the authored field name; `version` reads the Store's lock from `input`.
+ */
+import { deny, isAdmin } from "./contracts.js";
+/**
+ * A declared date-time or date as the engine stores it, and a JSON value as its text (a string, such as a boundary's
+ * already converted value, is bound as it is); any other value (and `null`) is bound as it is.
+ */
+export const encode = (d, type, v) => type === "timestamptz" ? (v == null ? null : d.timestamp(v)) : type === "date" ? (v == null ? null : d.date(v))
+    : type === "json" && v != null && typeof v !== "string" ? JSON.stringify(v) : v;
+export function binds(d, recipes, caller, input, ms = 0) {
+    const out = [];
+    for (const r of recipes) {
+        switch (r.k) {
+            case "uid":
+                if (caller.kind === "host")
+                    deny(caller, isAdmin(caller), "");
+                out.push("subject" in caller ? caller.subject : caller.kind === "system" ? `system:${caller.reason}` : null);
+                break;
+            case "admin":
+                out.push(isAdmin(caller) ? 1 : 0);
+                break;
+            case "now":
+                out.push(d.now(ms ||= Date.now()));
+                break;
+            case "cutoff":
+                out.push(d.cutoff(ms ||= Date.now(), r.seconds));
+                break;
+            case "const":
+                out.push(r.value);
+                break;
+            case "version":
+                out.push(input.version);
+                break;
+            case "input":
+                out.push(encode(d, r.type, input[r.name]));
+                break;
+            // Only apps whose plan uses caller values import the version-checked capability; it refuses an unknown recipe, and without it this throws before SQL.
+            default: out.push(d.userRefs(r, caller, input));
+        }
+    }
+    return out;
+}
+/** Every step's binds, evaluated for a Procedure. */
+export function bound(d, steps, caller, input) {
+    const ms = Date.now(); // one clock for the whole Procedure
+    return steps.map(s => ({ sql: s.sql, binds: binds(d, s.binds, caller, input, ms), row: s.row }));
+}

package/dist/kernel/caller-identity.d.ts

@@ -0,0 +1,24 @@
+import type { Caller } from "./contracts.js";
+import type { UserValue } from "./user-fields.js";
+type Identity = {
+    readonly roles: readonly string[];
+    readonly fields: Readonly<Record<string, UserValue>>;
+    readonly admin: boolean;
+    readonly impersonatedBy?: string;
+    readonly host?: true;
+};
+export declare const identities: WeakMap<Caller, Identity>;
+export declare const isHostCaller: (caller: Caller) => boolean;
+export declare const rolesOf: (caller: Caller) => readonly string[];
+export declare const fieldsOf: (caller: Caller) => Readonly<Record<string, UserValue>>;
+export declare const valueFor: (caller: Caller, field: string) => UserValue | undefined;
+export declare const hasRole: (caller: Caller, role: string) => boolean;
+export declare const isAdminCaller: (caller: Caller) => caller is Extract<Caller, {
+    kind: "user" | "host";
+}> & {
+    readonly admin: true;
+};
+export declare function modeOf(caller: Caller): "caller" | "trusted";
+/** Only branded host identities may carry freshness authority. */
+export declare function checkFresh(caller: Caller, readOnly: boolean, target?: string): void;
+export {};

package/dist/kernel/caller-identity.js

@@ -0,0 +1,22 @@
+import { ContractError } from "./contract-error.js";
+export const identities = /* @__PURE__ */ new WeakMap();
+export const isHostCaller = (caller) => identities.get(caller)?.host === true;
+export const rolesOf = (caller) => identities.get(caller)?.roles ?? [];
+// Unbranded callers get a fresh empty map; mutating it cannot grant authority.
+export const fieldsOf = (caller) => identities.get(caller)?.fields ?? {};
+export const valueFor = (caller, field) => identities.get(caller)?.fields[field];
+export const hasRole = (caller, role) => rolesOf(caller).includes(role);
+export const isAdminCaller = (caller) => !!identities.get(caller)?.admin;
+export function modeOf(caller) {
+    const kind = caller.kind;
+    if (kind === 'system')
+        return 'trusted';
+    if (kind === 'user' || kind === 'anonymous' || kind === 'host' && isHostCaller(caller))
+        return 'caller';
+    throw new ContractError('AUTH_DENIED', 'Unknown caller');
+}
+/** Only branded host identities may carry freshness authority. */
+export function checkFresh(caller, readOnly, target) {
+    if (!readOnly && isHostCaller(caller) && "authenticatedAs" in caller && caller.authenticatedAs === "snapshot")
+        throw new ContractError("STALE_CALLER", "Snapshot callers cannot write.", target, { status: 403 });
+}

package/dist/kernel/contract-error.d.ts

@@ -0,0 +1,12 @@
+export declare class ContractError extends Error {
+    readonly code: string;
+    readonly path: string;
+    /** HTTP status for codes outside the core set `statusOf` maps. */
+    readonly status?: number;
+    /** Extra wire fields, after `code`, `message` and `path`. */
+    readonly fields?: Record<string, unknown>;
+    constructor(code: string, message: string, path?: string, options?: ErrorOptions & {
+        status?: number;
+        fields?: Record<string, unknown>;
+    });
+}

package/dist/kernel/contract-error.js

@@ -0,0 +1,14 @@
+export class ContractError extends Error {
+    code;
+    path;
+    constructor(code, message, path = "", options) {
+        super(message, options);
+        this.code = code;
+        this.path = path;
+        this.name = "ContractError";
+        if (options?.status)
+            this.status = options.status;
+        if (options?.fields)
+            this.fields = options.fields;
+    }
+}

package/dist/kernel/contracts.d.ts

@@ -0,0 +1,143 @@
+/** 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;
+/** A row statement that changed no row cannot tell why without leaking whether the row exists, so it says how to recover. */
+export declare const ROW_CONFLICT = "No row matched this change: it does not exist or is not visible to you, it changed since it was read, or its state no longer allows this change. Read it again before deciding whether to retry.";
+/** CONFLICT for a write the database refused: a unique-index clash (`fields.kind` "unique"), or a row statement that did not change exactly one row ("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) => ContractError | undefined;
+/** One message on every target, built from the parsed fields; the driver's own text stays in `cause`. */
+export declare const schemaCheckFailed: (path: string, cause: unknown, schema: string | undefined, check: string | undefined) => ContractError;
+/** 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,97 @@
+/** 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);
+}
+/** A row statement that changed no row cannot tell why without leaking whether the row exists, so it says how to recover. */
+export const ROW_CONFLICT = "No row matched this change: it does not exist or is not visible to you, it changed since it was read, or its state no longer allows this change. Read it again before deciding whether to retry.";
+/** CONFLICT for a write the database refused: a unique-index clash (`fields.kind` "unique"), or a row statement that did not change exactly one row ("row"). */
+export const conflict = (path, unique, cause) => new ContractError("CONFLICT", unique ? "A unique constraint of the Schema was violated." : ROW_CONFLICT, path, { cause, fields: { kind: unique ? "unique" : "row" } });
+/** A Schema `checks` violation (Mantle's SQLite check trigger, or PostgreSQL SQLSTATE 23514) is a CONFLICT naming the check. */
+export const checkConflict = (path, error) => {
+    const message = error?.message ?? "", marker = /MANTLE_CHECK ([^:\n]+): (.+)/.exec(message);
+    if (!/MANTLE_CHECK /.test(message))
+        return undefined;
+    // D1 appends its own `: SQLITE_CONSTRAINT (extended: …)`; it stays in `cause`, not in what a client reads.
+    return schemaCheckFailed(path, error, marker?.[1], marker?.[2]?.replace(/: SQLITE_CONSTRAINT.*$/, ""));
+};
+/** One message on every target, built from the parsed fields; the driver's own text stays in `cause`. */
+export const schemaCheckFailed = (path, cause, schema, check) => new ContractError("CONFLICT", schema && check ? `A check of the Schema failed: ${schema}: ${check}` : "A check of the Schema failed.", path, { cause, fields: { kind: "check", schema, check } });
+/** 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/kernel/cron.d.ts

@@ -0,0 +1 @@
+export declare function toCloudflareCron(cron: string): string;

package/dist/kernel/cron.js

@@ -0,0 +1,58 @@
+/** 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"];
+/** label, lowest, highest, names (by value from `lowest`) */
+const FIELDS = [["minute", 0, 59, null], ["hour", 0, 23, null], ["day of month", 1, 31, null], ["month", 1, 12, MONTHS], ["weekday", 0, 6, DAYS]];
+export function toCloudflareCron(cron) {
+    const refuse = (why) => {
+        throw new Error(`Cannot map the cron '${cron}' to Cloudflare: ${why}`);
+    };
+    const fields = cron.trim().split(/\s+/);
+    if (fields.length !== 5)
+        refuse("a cron has five fields (minute hour day-of-month month weekday)");
+    const weekday = [];
+    fields.forEach((field, i) => {
+        const [label, min, max, names] = FIELDS[i];
+        // a value as a number: a name counts as its number, and a number must be written plainly (`01` and `1` are one value)
+        const value = (token) => {
+            if (/^\d+$/.test(token)) {
+                if (token.length > 1 && token.startsWith("0"))
+                    refuse(`'${token}' has a leading zero`);
+                if (i === 4 && Number(token) > 6)
+                    refuse(`weekday ${token} is not POSIX (0-6, 0 = Sunday)`);
+                if (Number(token) < min || Number(token) > max)
+                    refuse(`${label} ${token} is outside ${min}-${max}`);
+                return Number(token);
+            }
+            const at = names?.indexOf(token.toUpperCase()) ?? -1;
+            if (at < 0)
+                refuse(`'${token}' is not a valid ${label}`);
+            return at + min;
+        };
+        const day = (token) => (i === 4 && token !== undefined && /^\d+$/.test(token) ? String(Number(token) + 1) : token);
+        const out = field.split(",").map((p) => {
+            const [, start, end, step] = PART.exec(p) ?? refuse(`'${p}' is not a number, name, *, range or step`);
+            if (start === "*") {
+                if (end)
+                    refuse(`'${p}' is not a range`);
+            }
+            else {
+                const a = value(start);
+                if (end && value(end) < a)
+                    refuse(`'${p}' is a range that runs backwards`);
+                if (step !== undefined && !end && !/^\d+$/.test(start))
+                    refuse(`'${p}' is a name with a step`);
+            }
+            if (step !== undefined && (/^0\d/.test(step) || Number(step) < 1))
+                refuse(`'${p}' has a step of '${step}'`);
+            return `${day(start)}${end ? `-${day(end)}` : ""}${step ? `/${step}` : ""}`;
+        });
+        if (i === 4)
+            weekday.push(...out);
+    });
+    // POSIX runs on either day when both are restricted; Cloudflare does not document that rule, so only one may be
+    if (fields[2] !== "*" && fields[4] !== "*")
+        refuse("restrict the day of month or the weekday, not both");
+    return [...fields.slice(0, 4), weekday.join(",")].join(" ");
+}

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

@@ -0,0 +1,38 @@
+/** 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 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>;