@aotter/mantle 0.2.0-alpha.1 → 0.2.0-alpha.11

package/dist/infrastructure/wrangler.js

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { applyEdits, modify, parse } from "jsonc-parser";
+const requiredFlags = ["nodejs_compat", "global_fetch_strictly_public"];
+function compatibilityDate(dir) {
+    try {
+        let from = join(dir, "package.json");
+        for (const name of ["wrangler", "miniflare", "workerd"])
+            from = createRequire(from).resolve(`${name}/package.json`);
+        const [, y, m, d] = /^\d+\.(\d{4})(\d{2})(\d{2})\./.exec(JSON.parse(readFileSync(from, "utf8")).version) ?? [];
+        if (y)
+            return `${y}-${m}-${d}`;
+    }
+    catch { }
+    return "2026-09-28";
+}
+export function configureWrangler(configPath, entry, outdir, generated, check = false, assets, publicFetchRequired = false) {
+    const configDir = dirname(resolve(configPath));
+    const local = (path) => relative(configDir, resolve(path)).replaceAll("\\", "/") || ".";
+    const output = local(outdir);
+    const quote = (arg) => /^[\w./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`;
+    const worker = `${output}/worker`;
+    const assetsFlag = assets !== undefined && resolve(assets) !== resolve(outdir, "client") ? ` --assets ${quote(assets)}` : "";
+    const keys = {
+        main: `${worker}/${basename(entry).replace(/\.[^.]+$/, "")}.js`, no_bundle: true,
+        find_additional_modules: true, base_dir: worker,
+        rules: [{ type: "ESModule", globs: ["**/*.js"], fallthrough: true }],
+        build: { command: `mantle bundle ${quote(entry)} ${quote(outdir)}${assetsFlag}`, watch_dir: [local(dirname(entry)), local(generated)] },
+    };
+    if (configPath.endsWith(".toml")) {
+        if (check)
+            throw new Error("--check requires a JSON or JSONC Wrangler config; TOML generation only prints manual edits.");
+        console.log(`Leave ${configPath} unchanged. Add these Wrangler TOML keys (include nodejs_compat and global_fetch_strictly_public in every compatibility_flags override):\n` +
+            `main = ${JSON.stringify(keys.main)}\nno_bundle = true\nfind_additional_modules = true\nbase_dir = ${JSON.stringify(worker)}\ncompatibility_flags = ${JSON.stringify(requiredFlags)}\n\n` +
+            (assets === undefined ? "" : `[assets]\ndirectory = ${JSON.stringify(local(assets))}\nbinding = "ASSETS"\nrun_worker_first = true\nhtml_handling = "none"\n\n`) +
+            `[[rules]]\ntype = "ESModule"\nglobs = ["**/*.js"]\nfallthrough = true\n\n[build]\ncommand = ${JSON.stringify(keys.build.command)}\nwatch_dir = ${JSON.stringify(keys.build.watch_dir)}`);
+        return false;
+    }
+    const exists = existsSync(configPath);
+    const original = exists ? readFileSync(configPath, "utf8") : JSON.stringify({ name: "your-worker-name", compatibility_date: compatibilityDate(configDir) }, null, 2) + "\n";
+    let text = original;
+    const errors = [];
+    const config = parse(text, errors, { allowTrailingComma: true });
+    if (errors.length || !config || typeof config !== "object" || Array.isArray(config))
+        throw new Error(`${configPath} must be a valid JSONC object.`);
+    const indent = text.match(/\n([ \t]+)"/)?.[1] ?? "  ";
+    const formattingOptions = { insertSpaces: !indent.includes("\t"), tabSize: indent.length, eol: text.includes("\r\n") ? "\r\n" : "\n" };
+    const { rules: [rule], build: buildKeys, ...top } = keys;
+    const edit = (path, value) => {
+        if (!isDeepStrictEqual(path.reduce((v, k) => v?.[k], config), value))
+            text = applyEdits(text, modify(text, path, value, { formattingOptions }));
+    };
+    const ensureFlags = (path, flags) => {
+        if (flags !== undefined && (!Array.isArray(flags) || !flags.every(flag => typeof flag === "string")))
+            throw new Error(`${configPath}: ${path.join(".")} must be an array of strings.`);
+        const privateFetch = Array.isArray(flags) && flags.includes("global_fetch_private_origin");
+        if (privateFetch && (publicFetchRequired || flags.includes("global_fetch_strictly_public")))
+            throw new Error(`${configPath}: ${path.join(".")} includes global_fetch_private_origin, which conflicts with public OAuth/CIMD fetch routing. Remove it and use global_fetch_strictly_public.`);
+        const required = privateFetch ? ["nodejs_compat"] : requiredFlags;
+        if (flags === undefined)
+            edit(path, required);
+        else
+            for (const flag of required)
+                if (!flags.includes(flag))
+                    edit([...path, -1], flag);
+    };
+    ensureFlags(["compatibility_flags"], config.compatibility_flags);
+    for (const [name, environment] of Object.entries(config.env ?? {})) {
+        if (environment?.compatibility_flags !== undefined)
+            ensureFlags(["env", name, "compatibility_flags"], environment.compatibility_flags);
+    }
+    for (const [key, value] of Object.entries(top))
+        edit([key], value);
+    for (const [key, value] of Object.entries(buildKeys))
+        edit(["build", key], value);
+    if (assets !== undefined) {
+        const wireAssets = (path, current) => {
+            edit([...path, "directory"], local(assets));
+            const ownsDefaults = current === undefined || current?.binding === undefined;
+            if (ownsDefaults && current?.binding === undefined)
+                edit([...path, "binding"], "ASSETS");
+            if (ownsDefaults && current?.run_worker_first === undefined)
+                edit([...path, "run_worker_first"], true);
+            if (current?.html_handling === undefined && (current?.run_worker_first === true || (ownsDefaults && current?.run_worker_first === undefined)))
+                edit([...path, "html_handling"], "none");
+        };
+        wireAssets(["assets"], config.assets);
+        for (const [name, environment] of Object.entries(config.env ?? {})) {
+            if (environment?.assets !== undefined)
+                wireAssets(["env", name, "assets"], environment.assets);
+        }
+    }
+    if (!(config.rules ?? []).some((r) => isDeepStrictEqual(r, rule)))
+        edit(config.rules === undefined ? ["rules"] : ["rules", -1], config.rules === undefined ? [rule] : rule);
+    const changed = !exists || text !== original;
+    if (changed && !check)
+        writeFileSync(configPath, text);
+    if (!exists && !check)
+        console.log(`Created ${configPath}. Set name and compatibility_date for your Worker, and add your D1/Hyperdrive bindings and other application settings.`);
+    return changed;
+}

package/dist/kernel/authorization.d.ts

@@ -0,0 +1,4 @@
+import { type Authorize, type Target, type Caller } from "./contracts.js";
+/** Rejections deny; synchronous application failures remain internal errors. */
+export declare function authorized(authorize: Authorize, target: Target, caller: Caller): Promise<boolean>;
+export declare function authorizeTarget(authorize: Authorize, target: Target, caller: Caller): Promise<void>;

package/dist/kernel/authorization.js

@@ -0,0 +1,15 @@
+import { ContractError } from "./contracts.js";
+export async function authorized(authorize, target, caller) {
+    let result;
+    try {
+        result = authorize(target, caller);
+    }
+    catch (cause) {
+        throw new Error("Authorization failed.", { cause });
+    }
+    return await Promise.resolve(result).catch(() => false) === true;
+}
+export async function authorizeTarget(authorize, target, caller) {
+    if (!await authorized(authorize, target, caller))
+        throw new ContractError("AUTH_DENIED", "Target is not authorized.", target.kind + "/" + target.name);
+}

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,39 @@
+import { deny, isAdmin } from "./contracts.js";
+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;
+            default: out.push(d.userRefs(r, caller, input));
+        }
+    }
+    return out;
+}
+export function bound(d, steps, caller, input) {
+    const ms = Date.now();
+    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,21 @@
+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 {};

package/dist/kernel/caller-identity.js

@@ -0,0 +1,7 @@
+export const identities = /* @__PURE__ */ new WeakMap();
+export const isHostCaller = (caller) => identities.get(caller)?.host === true;
+export const rolesOf = (caller) => identities.get(caller)?.roles ?? [];
+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;

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

@@ -0,0 +1,4 @@
+import type { Caller } from "./contracts.js";
+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;

package/dist/kernel/caller-mode.js

@@ -0,0 +1,14 @@
+import { ContractError } from "./contract-error.js";
+import { isHostCaller } from "./caller-identity.js";
+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');
+}
+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,135 @@
+/** 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">;
+export { checkOrigin, surfaceCaller, surfaceError, surfaceFailure } from "./surface-failure.js";

package/dist/kernel/contracts.js

@@ -0,0 +1,56 @@
+import { ContractError } from "./contract-error.js";
+export { ContractError } from "./contract-error.js";
+import { hasRole, isAdminCaller as isAdmin } from "./caller-identity.js";
+export const forwarded = (ctx, gateway) => !!(gateway || ctx?.props && Object.hasOwn(ctx.props, "mantle"));
+export { isAdmin };
+export const isUser = (caller) => caller.kind === "user" || isAdmin(caller);
+export const hasAdminRole = (caller, name) => isAdmin(caller) && hasRole(caller, name);
+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);
+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;
+    });
+}
+export function deny(caller, allowed, path) {
+    if (!allowed)
+        throw new ContractError("subject" in caller ? "AUTH_DENIED" : "UNAUTHENTICATED", "Authorization predicate not satisfied.", path);
+}
+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.";
+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" } });
+export const checkConflict = (path, error) => {
+    const message = error?.message ?? "", marker = /MANTLE_CHECK ([^:\n]+): (.+)/.exec(message);
+    if (!/MANTLE_CHECK /.test(message))
+        return undefined;
+    return schemaCheckFailed(path, error, marker?.[1], marker?.[2]?.replace(/: SQLITE_CONSTRAINT.*$/, ""));
+};
+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 } });
+export { checkOrigin, surfaceCaller, surfaceError, surfaceFailure } from "./surface-failure.js";

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,12 +1,6 @@
-/**
- * `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.
- */
 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) => {
@@ -18,7 +12,6 @@ export function toCloudflareCron(cron) {
     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"))
@@ -55,9 +48,7 @@ export function toCloudflareCron(cron) {
         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(" ");
 }
-//# sourceMappingURL=CloudflareCron.js.map

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,3 @@
+export const ident = (name) => name.split(".").map(part => `"${part.replaceAll('"', '""')}"`).join(".");
+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,16 @@
+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;
+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;