@aotter/mantle 0.2.0-alpha.9 → 0.2.1-alpha.1

package/dist/infrastructure/wrangler.js

@@ -4,7 +4,6 @@ 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"];
-/** Newest date the project's installed workerd supports, as create-cloudflare picks it; a fixed date before Wrangler is installed. */
 function compatibilityDate(dir) {
     try {
         let from = join(dir, "package.json");
@@ -17,7 +16,6 @@ function compatibilityDate(dir) {
     catch { }
     return "2026-09-28";
 }
-/** `assets`: with `--admin`, the static assets directory `mantle bundle` builds Admin into (`<assets>/admin`). */
 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("\\", "/") || ".";
@@ -49,13 +47,11 @@ export function configureWrangler(configPath, entry, outdir, generated, check =
         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" };
-    // Merge, never replace: the user's own module rules and build options survive.
     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 }));
     };
-    // Public routing is the default; an explicit private origin remains app-owned without OAuth/CIMD.
     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.`);
@@ -71,7 +67,6 @@ export function configureWrangler(configPath, entry, outdir, generated, check =
                     edit([...path, -1], flag);
     };
     ensureFlags(["compatibility_flags"], config.compatibility_flags);
-    // Wrangler environment arrays replace the top-level flags rather than inheriting them.
     for (const [name, environment] of Object.entries(config.env ?? {})) {
         if (environment?.compatibility_flags !== undefined)
             ensureFlags(["env", name, "compatibility_flags"], environment.compatibility_flags);
@@ -88,7 +83,6 @@ export function configureWrangler(configPath, entry, outdir, generated, check =
                 edit([...path, "binding"], "ASSETS");
             if (ownsDefaults && current?.run_worker_first === undefined)
                 edit([...path, "run_worker_first"], true);
-            // The shell fetches index.html itself; asset canonicalization would redirect it back to /admin/ forever.
             if (current?.html_handling === undefined && (current?.run_worker_first === true || (ownsDefaults && current?.run_worker_first === undefined)))
                 edit([...path, "html_handling"], "none");
         };

package/dist/kernel/authorization.js

@@ -1,5 +1,4 @@
 import { ContractError } from "./contracts.js";
-/** Rejections deny; synchronous application failures remain internal errors. */
 export async function authorized(authorize, target, caller) {
     let result;
     try {

package/dist/kernel/binds.d.ts

@@ -18,30 +18,57 @@ export type Recipe = {
 } | {
     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 or a date is converted, so only those carry a type. */
-    readonly type?: "timestamptz" | "date";
+    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. */
+/**
+ * How a row write a Schema lock guards tells, when it changed no row, a lock from the row conflict (#1822): `sql` re-reads that
+ * row as its caller sees it (version and locks aside) and outputs `lock`, the name of a lock that holds, or NULL. `locks` maps
+ * each lock on this verb to its message.
+ */
+export interface LockProbe<B = readonly Recipe[]> {
+    readonly sql: string;
+    readonly binds: B;
+    readonly schema: string;
+    readonly verb: "update" | "delete";
+    readonly locks: Readonly<Record<string, string>>; /** The probe can also answer `publishing.required` (a Store update of a published row): this message. */
+    readonly required?: string;
+}
+/** One printed statement and how to bind it. `row`: it must affect exactly one row; `"some"`: at least one (a step with `onNoRows: conflict`). `lock`: only on a row op. */
 export interface Step {
     readonly sql: string;
     readonly binds: readonly Recipe[];
-    readonly row?: boolean;
+    readonly row?: boolean | "some";
+    readonly lock?: LockProbe;
 }
 export type Bound = {
     readonly sql: string;
     readonly binds: unknown[];
-    readonly row?: boolean;
+    readonly row?: boolean | "some";
+    readonly lock?: LockProbe<unknown[]>;
 };
 /** 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) => unknown;
+    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; any other value (and `null`) is bound as it is. */
+/**
+ * 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. */

package/dist/kernel/binds.js

@@ -1,10 +1,6 @@
-/**
- * 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; 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)) : v;
+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) {
@@ -32,14 +28,12 @@ export function binds(d, recipes, caller, input, ms = 0) {
             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));
+            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 }));
+    const ms = Date.now();
+    return steps.map(s => ({ sql: s.sql, binds: binds(d, s.binds, caller, input, ms), row: s.row, ...(s.lock ? { lock: { ...s.lock, binds: binds(d, s.lock.binds, caller, input, ms) } } : {}) }));
 }

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

@@ -18,7 +18,4 @@ export declare const isAdminCaller: (caller: Caller) => caller is Extract<Caller
 }> & {
     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

@@ -1,22 +1,7 @@
-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/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/contracts.d.ts

@@ -108,10 +108,21 @@ export type Output = {
 };
 /** 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. */
+/** 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 guarded row write that changed no row (#1822): CONFLICT `kind: "lock"` when its probe found the row visible and held by a lock, else the row conflict, which reveals nothing. */
+export declare const lockConflict: (path: string, probe: {
+    readonly schema: string;
+    readonly verb: string;
+    readonly locks: Readonly<Record<string, string>>;
+    readonly required?: string;
+}, rows: readonly Row[]) => 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;
@@ -128,12 +139,4 @@ export interface Postgres {
 }
 /** 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;
+export { checkOrigin, surfaceCaller, surfaceError, surfaceFailure } from "./surface-failure.js";

package/dist/kernel/contracts.js

@@ -1,20 +1,14 @@
-/** 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) {
@@ -46,47 +40,26 @@ export function wireRows(rows, fields = []) {
         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 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 lockConflict = (path, probe, rows) => {
+    const lock = rows[0]?.lock;
+    if (lock === "publishing.required" && probe.required)
+        return new ContractError("INPUT_VALIDATION_FAILED", probe.required, path);
+    if (typeof lock !== "string" || !Object.hasOwn(probe.locks, lock))
+        return conflict(path, false);
+    const message = probe.locks[lock];
+    return new ContractError("CONFLICT", message, path, { fields: { kind: "lock", schema: probe.schema, verb: probe.verb, lock, message } });
+};
 export const checkConflict = (path, error) => {
     const message = error?.message ?? "", marker = /MANTLE_CHECK ([^:\n]+): (.+)/.exec(message);
     if (!/MANTLE_CHECK /.test(message))
         return undefined;
-    return new ContractError("CONFLICT", `A check of the Schema failed: ${marker?.[0] ?? message}`, path, { cause: error, fields: { kind: "check", schema: marker?.[1], check: marker?.[2]?.replace(/: SQLITE_CONSTRAINT.*$/, "") } });
+    return schemaCheckFailed(path, error, marker?.[1], marker?.[2]?.replace(/: SQLITE_CONSTRAINT.*$/, ""));
 };
-/** 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 } : {}) } });
-}
+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/kernel/cron.js

@@ -1,8 +1,6 @@
-/** 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) => {
@@ -14,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"))
@@ -51,7 +48,6 @@ 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(" ");

package/dist/kernel/dialect/common.js

@@ -1,6 +1,3 @@
-/** 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.js

@@ -1,4 +1,3 @@
-/** 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";
@@ -13,6 +12,5 @@ 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.js

@@ -1,24 +1,19 @@
 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 like = () => "LIKE";
 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;

package/dist/kernel/drain.js

@@ -1,25 +1,19 @@
-/** 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
+        reader = request.body?.getReader();
         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 */ }
+    catch {  }
     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 {

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

@@ -1,10 +1,9 @@
-import { checkConflict, conflict, ContractError } from "../contracts.js";
+import { checkConflict, conflict, ContractError, lockConflict } 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(() => { }, () => { });
@@ -15,11 +14,9 @@ function enqueue(db, fn) {
 }
 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) : [];
@@ -27,15 +24,14 @@ export async function procedure(db, steps, path) {
                 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);
+        if (s.row && (changes < 1 || changes > 1 && s.row !== "some"))
+            throw s.row === true && s.lock ? lockConflict(path, s.lock, handle.query(s.lock.sql).all(...s.lock.binds)) : conflict(path, false);
         return rows;
     });
     return available(db, () => transactions.has(db) || steps.length === 1 ? execute(db) : db.transaction(execute)(db));

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

@@ -20,5 +20,5 @@ export interface Handle extends Reader {
     }[]>;
 }
 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. */
+/** The assert table's trigger aborts the whole batch with `CONFLICT op=<k>` when statement k did not change exactly one row (at least one for `row: "some"`). */
 export declare function procedure(db: Handle, steps: readonly Bound[], path: string): Promise<Row[][]>;

package/dist/kernel/driver/d1.js

@@ -1,22 +1,24 @@
-import { checkConflict, conflict } from "../contracts.js";
+import { checkConflict, conflict, lockConflict } 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`));
+            batch.push(db.prepare(`INSERT INTO _mantle_assert (op,ok) SELECT ${i}, changes() ${s.row === "some" ? "> 0" : "= 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;
+        const op = /CONFLICT op=(\d+)/.exec(String(error?.message)), step = op ? steps[Number(op[1])] : undefined, probe = step?.row === true ? step.lock : undefined;
+        if (probe)
+            throw lockConflict(path, probe, await read(db, probe.sql, probe.binds));
+        throw unique(error) ? conflict(path, true, error) : op ? conflict(path, false, error) : checkConflict(path, error) ?? error;
     }
     return at.map(i => out[i].results);
 }

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

@@ -16,7 +16,8 @@ export declare function definitive(error: unknown): boolean;
  */
 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)
+ * One statement is atomic on its own (a row statement touches at most one row, and a `"some"` one fails only when it wrote
+ * none, 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.
  */

package/dist/kernel/driver/postgres.js

@@ -1,4 +1,4 @@
-import { conflict, ContractError } from "../contracts.js";
+import { conflict, ContractError, lockConflict, schemaCheckFailed } from "../contracts.js";
 import { context, guard } from "./transaction-context.js";
 const transactions = new WeakSet();
 const ISOLATION = ["serializable", "repeatable read", "read committed", "read uncommitted"];
@@ -7,38 +7,31 @@ export async function run(db, sql, binds) {
     const rows = await read(db, sql, binds);
     return { rows, changes: Number(rows.count ?? 0) };
 }
-/** SQLSTATE of a server error: `errno` on Bun.SQL, `code` on postgres.js. */
 const sqlstate = (error) => { const e = error; return typeof e?.errno === "string" ? e.errno : e?.code; };
-const check = (path, e) => new ContractError("CONFLICT", `A check of the Schema failed: ${e.message}`, path, { cause: e, fields: { kind: "check", schema: e.table ?? e.table_name, check: e.constraint ?? e.constraint_name } });
-/** A structured server ErrorResponse proves rollback; missing evidence is uncertain. */
+const check = (path, e) => schemaCheckFailed(path, e, e.table ?? e.table_name, e.constraint ?? e.constraint_name);
 export function definitive(error) {
     if (error instanceof ContractError)
         return error.code === "CONFLICT";
     const state = sqlstate(error);
     return typeof state === "string" && /^[0-9A-Z]{5}$/.test(state) && typeof error?.severity === "string" && !/^(08|28|53|57|58|XX)/.test(state);
 }
-/**
- * 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.
- */
+function serialization(error, path) {
+    const state = sqlstate(error);
+    if ((state === "40001" || state === "40P01") && definitive(error))
+        return new ContractError("CONFLICT", "A concurrent transaction prevented this write. Read again before deciding whether to retry.", path, { cause: error, fields: { kind: "serialization" } });
+}
 export function postgresOutcome(error, path) {
     if (definitive(error))
-        return error;
+        return serialization(error, path) ?? error;
     return new ContractError("OUTCOME_UNKNOWN", "The write outcome is unknown; reconcile before retrying.", path, { cause: error });
 }
-/**
- * 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 async function procedure(db, steps, path) {
     const execute = async (handle) => {
         const results = [];
         for (const s of steps) {
-            const { rows, changes } = await run(handle, s.sql, s.binds).catch(error => { throw sqlstate(error) === "23505" ? conflict(path, true, error) : sqlstate(error) === "23514" ? check(path, error) : error; });
-            if (s.row && changes !== 1)
-                throw conflict(path, false);
+            const { rows, changes } = await run(handle, s.sql, s.binds).catch(error => { throw sqlstate(error) === "23505" ? conflict(path, true, error) : sqlstate(error) === "23514" ? check(path, error) : serialization(error, path) ?? error; });
+            if (s.row && (changes < 1 || changes > 1 && s.row !== "some"))
+                throw s.row === true && s.lock ? lockConflict(path, s.lock, (await run(handle, s.lock.sql, s.lock.binds)).rows) : conflict(path, false);
             results.push(rows);
         }
         return results;
@@ -55,18 +48,15 @@ export async function procedure(db, steps, path) {
     }
     return transaction(db, execute, undefined, path);
 }
-/** Shared BEGIN/COMMIT outcome handling for Procedures and interactive Store transactions. */
 export async function transaction(db, fn, options = {}, path = "store/transaction") {
     guard(db);
     if (transactions.has(db))
         throw new Error("Nested transactions are not supported.");
-    // a transaction handle the app opened (postgres.js types it without `begin`) only suits reads and single statements
     if (typeof db.begin !== "function")
         throw new Error("This PostgreSQL handle is a transaction the app opened and cannot begin another: open the transaction with store(pool, caller).transaction and call Procedures through its tx.");
     let committing = false;
     const state = { outer: db };
     try {
-        // printed into BEGIN, so only PostgreSQL's own four levels: a handler may pass request input here
         const level = options.isolation ?? "serializable";
         if (!ISOLATION.includes(level))
             throw new ContractError("INPUT_VALIDATION_FAILED", `isolation '${level}' is not a PostgreSQL isolation level`, path);
@@ -90,7 +80,7 @@ export async function transaction(db, fn, options = {}, path = "store/transactio
         });
     }
     catch (error) {
-        throw error instanceof ContractError || !committing ? error : postgresOutcome(error, path);
+        throw serialization(error, path) ?? (error instanceof ContractError || !committing ? error : postgresOutcome(error, path));
     }
     finally {
         state.outer = undefined;

package/dist/kernel/driver/transaction-context.js

@@ -5,7 +5,6 @@ export function guard(db) {
     if (context.getStore()?.outer === db)
         throw new ContractError("INPUT_VALIDATION_FAILED", "Inside store.transaction use tx, not the outer store or handle.", "store/transaction");
 }
-/** One atomic write cannot publish a translation and change its parent's status. */
 export function translationWrite(db, schema, parent) {
     const state = context.getStore();
     if (!state || state.handle !== db)