@aotter/mantle 0.2.0 → 0.2.1-alpha.2

package/dist/kernel/contracts.js

@@ -46,6 +46,15 @@ export function deny(caller, allowed, 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 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))

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

@@ -1,4 +1,4 @@
-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";
@@ -30,8 +30,8 @@ export async function procedure(db, steps, path) {
         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,4 +1,4 @@
-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;
@@ -8,14 +8,17 @@ export async function procedure(db, steps, path) {
         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, schemaCheckFailed } 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"];
@@ -15,18 +15,23 @@ export function definitive(error) {
     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);
 }
+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 });
 }
 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;
@@ -75,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/mcp-apps.d.ts

@@ -40,7 +40,7 @@ export interface McpAppResource {
     readonly domain?: string;
     /** Tool names whose results this resource renders. */
     readonly renders?: readonly string[];
-    /** Views only this App may call (`visibility: ["app"]`); a client without MCP Apps does not see them. A Procedure cannot be hidden from the model. */
+    /** Views only this App may call (`visibility: ["app"]`); a client without MCP Apps does not see them. To hide a Procedure, give its tool `meta: { ui: { visibility: ["app"] } }`. */
     readonly appOnly?: readonly string[];
 }
 export interface McpApps {
@@ -51,7 +51,7 @@ export type McpAppsSource = McpApps | ((context: Pick<McpAppRender, "env" | "req
 /** Flatten contributors; `mcp(...)` reads static resources getters once at construction. */
 export declare const resourcesOf: (apps: McpApps | readonly McpApps[]) => McpApps;
 /** Static contributors are checked at construction; resolved factories are checked per request. A request-bound tool table defers tool-link checks until its first request. */
-export declare function linkApps(apps: McpApps | readonly McpApps[], tools?: ReadonlySet<string>, views?: ReadonlySet<string>): {
+export declare function linkApps(apps: McpApps | readonly McpApps[], tools?: ReadonlyMap<string, Readonly<Record<string, any>> | undefined>, views?: ReadonlySet<string>): {
     resources: McpAppResource[];
     renders: Map<string, string>;
     appOnly: Set<string>;
@@ -60,6 +60,7 @@ export declare function linkApps(apps: McpApps | readonly McpApps[], tools?: Rea
 export declare function linkSurface(apps: McpApps | readonly McpApps[], selected: readonly {
     name: string;
     page?: unknown;
+    meta?: Readonly<Record<string, unknown>>;
 }[], previous?: {
     key: string;
     links: ReturnType<typeof linkApps>;

package/dist/kernel/mcp-apps.js

@@ -27,9 +27,14 @@ export function linkApps(apps, tools, views) {
             appOnly.add(tool);
         }
     }
+    for (const [tool, uri] of renders) {
+        const meta = tools?.get(tool) ?? {}, ui = meta.ui ?? {};
+        if ([ui.resourceUri, meta["ui/resourceUri"], meta["openai/outputTemplate"]].some(value => value && value !== uri) || appOnly.has(tool) && ui.visibility && `${ui.visibility}` !== "app")
+            refuse(`Tool '${tool}' meta contradicts its MCP App links.`);
+    }
     return { resources, renders, appOnly };
 }
 export function linkSurface(apps, selected, previous) {
-    const key = JSON.stringify(selected.map(tool => [tool.name, !!tool.page]).sort(([a], [b]) => a.localeCompare(b)));
-    return previous?.key === key ? previous : { key, links: linkApps(apps, new Set(selected.map(tool => tool.name)), new Set(selected.filter(tool => tool.page).map(tool => tool.name))) };
+    const key = JSON.stringify(selected.map(tool => [tool.name, !!tool.page, tool.meta]).sort(([a], [b]) => a.localeCompare(b)));
+    return previous?.key === key ? previous : { key, links: linkApps(apps, new Map(selected.map(tool => [tool.name, tool.meta])), new Set(selected.filter(tool => tool.page).map(tool => tool.name))) };
 }

package/dist/kernel/mcp-handler.js

@@ -20,9 +20,12 @@ function observe(listener, event) {
 }
 const paging = (schema) => ({ ...schema, properties: { ...schema.properties, limit: { type: "integer", minimum: 1, maximum: 500 }, cursor: { type: "string" } } });
 const MCP_PAGE_BUDGET = 60_000;
+const MCP_INPUT_ELEMENTS = 10_000;
 const union = (scopes, extra) => [...new Set([...scopes, ...extra])].join(" ");
 export function handler(tools, options, apps = {}, reads = []) {
     const allowed = options.allowedOrigins ?? [];
+    if (options.toolsPageSize !== undefined && !(Number.isInteger(options.toolsPageSize) && options.toolsPageSize > 0))
+        throw new TypeError("mcp: toolsPageSize must be a positive integer.");
     return draining(async (request, env, ctx) => {
         const access = options.gateway ? (await import("./host-access.js")).accessRequest(ctx, options) : undefined;
         let resolved;
@@ -207,21 +210,29 @@ export function handler(tools, options, apps = {}, reads = []) {
             const serverInfo = { name: "aotter.mantle", ...options.serverInfo, version: options.serverInfo?.version ?? version };
             const handler = createMcpHandler(() => {
                 const schema = (value) => fromJsonSchema(value, { getValidator() { return (input) => ({ valid: true, data: input, errorMessage: undefined }); } });
-                const server = new McpServer(serverInfo, options.instructions ? { instructions: options.instructions } : {});
+                const server = new McpServer(serverInfo, { maxToolInputElements: MCP_INPUT_ELEMENTS, ...(options.instructions ? { instructions: options.instructions } : {}) });
                 server.server.registerCapabilities({ tools: { listChanged: false } });
                 if (host)
                     server.server.onclose = () => access?.finish(isRecord(parsedBody) && parsedBody.method === "initialize" ? undefined : new ContractError("INPUT_VALIDATION_FAILED", "MCP request refused.", "mcp", { status: 400 }));
-                const appMeta = links ? registerApps(server, links, parsedBody, new Set(selected.map(tool => tool.name)), { env, request }) : undefined;
+                const enabled = clientUiSupport(parsedBody) !== "unsupported";
+                const appMeta = links ? registerApps(server, links, enabled, new Set(selected.map(tool => tool.name)), { env, request }) : undefined;
                 const registered = new Set(), set = server.server.setRequestHandler.bind(server.server);
+                const size = options.toolsPageSize;
                 server.server.setRequestHandler = ((method, handler) => set(method, method === "tools/call" && typeof handler === "function" ? (request, context) => {
                     if (!registered.has(request.params.name))
                         throw new ProtocolError(ProtocolErrorCode.InvalidParams, `No tool named ${JSON.stringify(request.params.name)} exists in the current catalogue (catalogue version ${serverInfo.version}).`);
                     return handler(request, context);
+                } : method === "tools/list" && size && typeof handler === "function" ? async (request, context) => {
+                    const { tools } = await handler(request, context), cursor = request.params?.cursor, start = cursor === undefined ? 0 : Number(cursor.split(":")[1]);
+                    if (cursor !== undefined && !(start > 0 && start % size === 0 && start < tools.length && cursor === `${version}:${start}`))
+                        throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unknown tools/list cursor; list again from the first page (catalogue version ${serverInfo.version}).`);
+                    return { tools: tools.slice(start, start + size), ...(start + size < tools.length ? { nextCursor: `${version}:${start + size}` } : {}) };
                 } : handler));
                 for (const tool of selected) {
-                    const meta = appMeta?.(tool.name);
-                    if (meta === false)
+                    const linked = appMeta?.(tool.name), own = tool.meta, visibility = own?.ui?.visibility;
+                    if (linked === false || !enabled && Array.isArray(visibility) && !visibility.includes("model"))
                         continue;
+                    const meta = linked && own ? { ...linked, ...own, ui: { ...linked.ui, ...own.ui } } : linked ?? own;
                     registered.add(tool.name);
                     const about = (contract) => { const text = [tool.version && `tool version ${tool.version}`, contract && `input schema ${JSON.stringify(tool.page ? paging(tool.inputSchema) : tool.inputSchema)}`].filter(Boolean).join("; "); return text ? [{ type: "text", text }] : []; };
                     server.registerTool(tool.name, { ...(meta ? { _meta: meta } : {}), ...(tool.title ? { title: text(tool.title, locale) } : {}), description: text(tool.description, locale) ?? text(tool.title, locale) ?? tool.name, inputSchema: schema(tool.page ? paging(tool.inputSchema) : tool.inputSchema), ...(tool.outputSchema ? { outputSchema: schema(tool.outputSchema) } : {}), ...(tool.annotations ? { annotations: tool.annotations } : {}) }, async (raw) => {
@@ -235,8 +246,11 @@ export function handler(tools, options, apps = {}, reads = []) {
                                 tool.check?.(caller);
                             if (tool.run && (!host || !tool.readOnly))
                                 checkOrigin(request, caller);
-                            let db;
-                            const run = (input) => callTool(tool, input, () => db ??= options.db(env), caller, options.handlers, access?.dryRun ? () => ({ dryRun: true, event: access.finish() }) : undefined);
+                            let db, resultMeta;
+                            const run = async (input) => {
+                                const out = await callTool(tool, input, () => db ??= options.db(env), caller, options.handlers, access?.dryRun ? () => ({ dryRun: true, event: access.finish() }) : undefined);
+                                return isRecord(out) && Symbol.for("net.aotter.mantle/result") in out ? (resultMeta = out._meta, out.data) : out;
+                            };
                             let data = await run(raw);
                             for (let tries = 0; tool.page && isRecord(data) && Array.isArray(data.rows); tries++) {
                                 const rows = data.rows, total = JSON.stringify(data).length;
@@ -260,7 +274,7 @@ export function handler(tools, options, apps = {}, reads = []) {
                             if (host)
                                 access?.finish();
                             const text = JSON.stringify(data), notice = tool.page && text.length > MCP_PAGE_BUDGET;
-                            return { ...(meta ? { _meta: { "net.aotter.mantle/tool": tool.name } } : {}), content: [{ type: "text", text }, ...about(false), ...(notice ? [{ type: "text", text: `This page is larger than the ${MCP_PAGE_BUDGET}-character page size budget (a single row over it, or a View without an order, is returned whole), so a host may truncate it. Continue with nextCursor, if any.` }] : [])], ...(data && typeof data === "object" && !Array.isArray(data) ? { structuredContent: data } : {}) };
+                            return { ...(meta || resultMeta ? { _meta: { ...resultMeta, "net.aotter.mantle/tool": tool.name } } : {}), content: [{ type: "text", text }, ...about(false), ...(notice ? [{ type: "text", text: `This page is larger than the ${MCP_PAGE_BUDGET}-character page size budget (a single row over it, or a View without an order, is returned whole), so a host may truncate it. Continue with nextCursor, if any.` }] : [])], ...(data && typeof data === "object" && !Array.isArray(data) ? { structuredContent: data } : {}) };
                         }
                         catch (error) {
                             if (host)
@@ -321,8 +335,7 @@ function appMeta(r, csp = r.csp) {
     const ui = { ...(csp ? { csp } : {}), ...(r.permissions ? { permissions: r.permissions } : {}), ...(r.domain !== undefined ? { domain: r.domain } : {}), ...(r.prefersBorder !== undefined ? { prefersBorder: r.prefersBorder } : {}) };
     return Object.keys(ui).length > 0 ? { ui } : undefined;
 }
-function registerApps(server, links, message, tools, request) {
-    const enabled = clientUiSupport(message) !== "unsupported";
+function registerApps(server, links, enabled, tools, request) {
     if (enabled)
         for (const resource of links.resources) {
             const meta = appMeta(resource);

package/dist/kernel/mcp.d.ts

@@ -37,6 +37,8 @@ export interface Options<Env, Database> extends GatewayOptions {
     allowedOrigins?: readonly string[];
     onObservation?: (event: McpObservation) => void | Promise<void>;
     onRefusal?: (event: CallerRefusal) => void | Promise<void>;
+    /** Tools per `tools/list` page: the result carries `nextCursor` while more remain. Unset, one page lists every tool. */
+    toolsPageSize?: number;
 }
 export interface CallerRefusal {
     readonly at: number;
@@ -98,7 +100,23 @@ export interface Tool<Database, Handlers = never> {
     readonly path?: string;
     readonly page?: (db: Database, caller: Caller, input: never, paging: Paging) => Promise<unknown>;
     readonly run?: (db: Database, caller: Caller, input: never, handlers: Handlers) => Promise<unknown>;
+    /**
+     * Merged into this tool's `_meta` in `tools/list` (top level shallow, `ui` one level deep) with what its App links produce;
+     * a contradicting value fails at `mcp(...)`. `ui.visibility: ["app"]` hides the tool from clients without MCP Apps.
+     * It is a listing hint and grants or removes no execution authority.
+     */
+    readonly meta?: Readonly<Record<string, unknown>>;
 }
+/** What `withResultMeta` returns: `data` is the tool result as usual, `_meta` goes only to the `tools/call` result `_meta`. */
+export interface ResultWithMeta<T> {
+    readonly data: T;
+    readonly _meta: Readonly<Record<string, unknown>>;
+}
+/**
+ * Returned from a tool's `run`: MCP sends `data` exactly as an unwrapped return, and `meta` only in the result `_meta`
+ * (beside `net.aotter.mantle/tool`, which it cannot replace). `callTool` returns the wrapper itself; drop `_meta` before forwarding to a model.
+ */
+export declare const withResultMeta: <T>(data: T, meta: Readonly<Record<string, unknown>>) => ResultWithMeta<T>;
 /** Request-bound tool tables keep native environment bindings outside the cached App catalogue. */
 export type Tools<Env, Database, Handlers = never> = readonly Tool<Database, Handlers>[] | ((request: Request, env: Env) => readonly Tool<Database, Handlers>[] | Promise<readonly Tool<Database, Handlers>[]>);
 /** The selected MCP routes; all request work loads only when an MCP request arrives. */

package/dist/kernel/mcp.js

@@ -1,6 +1,7 @@
 import { linkApps, linkSurface, resourcesOf } from "./mcp-apps.js";
 export const callTool = async (...args) => (await import("./mcp-call.js")).callTool(...args);
 export const callToolLazy = async (...args) => (await import("./mcp-call.js")).callToolLazy(...args);
+export const withResultMeta = (data, meta) => ({ [Symbol.for("net.aotter.mantle/result")]: true, data, _meta: meta });
 export function mcp(tools, options, reads = []) {
     let serve;
     const linked = {};

package/dist/kernel/rest-router.js

@@ -2,6 +2,7 @@ import { forwarded, ContractError } from "./contracts.js";
 import { checkOrigin, surfaceCaller } from "./surface-failure.js";
 import { decode, invalid } from "./surface.js";
 import { draining } from "./drain.js";
+import { canonicalPath } from "./route-pattern.js";
 const isApi = (path) => path === "/api" || path.startsWith("/api/");
 const fail = message => invalid(message, "rest");
 export function router(routes, options, send) {
@@ -14,11 +15,8 @@ export function router(routes, options, send) {
             if (isForwarded)
                 caller = (await import("./host-caller.js")).gatewayCaller(ctx, options.gateway, options.fields);
             const original = new URL(request.url).pathname;
-            let path;
-            try {
-                path = original.split("/").map(segment => encodeURIComponent(decodeURIComponent(segment))).join("/");
-            }
-            catch {
+            const path = canonicalPath(original);
+            if (path === undefined) {
                 if (!isApi(original))
                     return undefined;
                 fail("Malformed request path.");

package/dist/kernel/rest.d.ts

@@ -1,6 +1,8 @@
 /** REST request handling for a generated route table: matching, body and parameter decoding, dispatch and errors. */
 import type { Caller, Target, Authorize, Gateway, RequestContext, GatewayOptions } from "./contracts.js";
 import { type Conversions } from "./surface.js";
+/** The routers' path grammar, for Admin's router: its mount, route patterns and the canonical request path. */
+export { ADMIN_API_BASE, canonicalPath, routeSource } from "./route-pattern.js";
 type Paging = {
     limit?: number;
     cursor?: string;
@@ -55,4 +57,3 @@ export declare function rest<Env, Database, Handlers = never>(routes: readonly R
 export declare function nativeRest<Env, Database, Handlers = never>(routes: readonly Route<Database, Handlers, Env>[], options: Options<Env, Database> & {
     handlers?: Handlers;
 }): (request: Request, env: Env, ctx?: RequestContext) => Promise<Response | undefined>;
-export {};

package/dist/kernel/rest.js

@@ -1,5 +1,6 @@
 import { ContractError } from "./contract-error.js";
 import { invalid } from "./surface.js";
+export { ADMIN_API_BASE, canonicalPath, routeSource } from "./route-pattern.js";
 const headers = { "cache-control": "private, no-store" };
 const fail = message => invalid(message, "rest");
 export async function body(request, limit = 1_000_000) {

package/dist/kernel/route-pattern.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one path grammar of the generated REST router, the Admin router and describe's `matchTarget`: a route template's
+ * pattern, the request path it is tested against and REST precedence. Pure; no database, application or other module.
+ */
+/** Where Admin serves its API. Admin route templates and `admin:` describe ids are relative to it. */
+export declare const ADMIN_API_BASE = "/admin/api";
+/**
+ * An http Trigger path as a describe template: `{name}` becomes `:name`. The compiler refuses other braces and
+ * `:`-prefixed segments in these paths, so `routePath` inverts it exactly.
+ */
+export declare const pathTemplate: (path: string) => string;
+/** A describe template as the route path the routers compile: `:name` segments become `{name}`. */
+export declare const routePath: (template: string) => string;
+/**
+ * A template's anchored pattern source and capture keys. A `{name}` segment captures one segment; with `suffix`,
+ * `{name*}` captures the rest of the path. Other segments, `:name` included, match literally in encoded form. One
+ * trailing slash is optional.
+ */
+export declare function routeSource(template: string, base?: string, suffix?: boolean): {
+    source: string;
+    keys: string[];
+};
+/** The path the routers test: each segment decoded and re-encoded, so equivalent escapes match alike. Malformed escapes are undefined. */
+export declare function canonicalPath(pathname: string): string | undefined;
+/** REST precedence over route paths: fewer parameters, then a literal before a parameter from the left, then the path. */
+export declare function routeOrder(a: string, b: string): number;

package/dist/kernel/route-pattern.js

@@ -0,0 +1,34 @@
+export const ADMIN_API_BASE = "/admin/api";
+export const pathTemplate = (path) => path.replace(/\{([^}]+)\}/g, ":$1");
+export const routePath = (template) => template.split("/").map(segment => segment.startsWith(":") ? `{${segment.slice(1)}}` : segment).join("/");
+export function routeSource(template, base = "", suffix = false) {
+    const keys = [];
+    const path = template.split("/").map(segment => {
+        const rest = suffix ? /^\{([a-zA-Z]\w*)\*\}$/.exec(segment) : null, one = /^\{([^}]+)\}$/.exec(segment);
+        if (rest || one) {
+            keys.push((rest ?? one)[1]);
+            return rest ? "(.*)" : "([^/]+)";
+        }
+        return encodeURIComponent(segment).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }).join("/");
+    return { source: `^${base}${path}/?$`, keys };
+}
+export function canonicalPath(pathname) {
+    try {
+        return pathname.split("/").map(segment => encodeURIComponent(decodeURIComponent(segment))).join("/");
+    }
+    catch {
+        return undefined;
+    }
+}
+const isParameter = (segment) => /^\{[^}]+\}$/.test(segment);
+export function routeOrder(a, b) {
+    const x = a.split("/"), y = b.split("/");
+    const count = (segments) => segments.filter(isParameter).length;
+    if (count(x) !== count(y))
+        return count(x) - count(y);
+    for (let i = 0; i < Math.min(x.length, y.length); i++)
+        if (isParameter(x[i]) !== isParameter(y[i]))
+            return isParameter(x[i]) ? 1 : -1;
+    return a < b ? -1 : a > b ? 1 : 0;
+}

package/dist/kernel/store.d.ts

@@ -30,6 +30,13 @@ export interface Rules {
     /** Core's new entry id as the dialect prints it (an SQL expression). */
     readonly newId: string;
 }
+/** A Schema lock (#1822): while `sql` (Core's `when`, printed for the dialect) holds for the existing row, a caller's write on `on` is refused. */
+export interface Lock {
+    readonly name: string;
+    readonly on: readonly ("update" | "delete")[];
+    readonly sql: string;
+    readonly message: string;
+}
 /** What a Schema adds to the rules. The table is the collection's name. */
 export interface Fact {
     readonly u?: readonly Extract<Term, readonly [string, 'in', ...unknown[]]>[];
@@ -39,6 +46,8 @@ export interface Fact {
     readonly ttl?: readonly [column: string, seconds: number];
     /** Opt-in publishing lifecycle. */
     readonly pub?: 1;
+    /** The columns `publish` requires non-null, each to its declared field: an update of a published row cannot clear one (#1822). */
+    readonly req?: Readonly<Record<string, string>>;
     /** Declared date-time and date columns (`created_at` and `updated_at` are always date-times). */
     readonly ts?: readonly string[];
     readonly d?: readonly string[];
@@ -52,6 +61,8 @@ export interface Fact {
         readonly same: readonly (readonly [parent: string, child: string])[];
         readonly terms: readonly Term[];
     }[];
+    /** Schema locks; a trusted caller is not bound by them. */
+    readonly lock?: readonly Lock[];
     /** Generated parent policy and inherited read-only columns; no authored schema is interpreted. */
     readonly parent?: {
         readonly on: string;
@@ -66,6 +77,8 @@ export interface Fact {
     };
 }
 export declare const SCOPE = "$scope", TTL = "$ttl";
+/** The probe's answer for an update that would leave a published row unpublishable; no lock name has a dot. */
+export declare const REQUIRED = "publishing.required";
 /** A Schema's rules: the shared ones with its scope and TTL put in, and a term dropped where it has none. The generator proves this equals Core's for every Schema. */
 export declare function expand(r: Rules, f: Fact): {
     caller: Term[];
@@ -148,6 +161,7 @@ export interface TransactionOptions {
 }
 export interface Store<T extends Record<string, Table>> {
     collection<K extends keyof T & string>(name: K): Collection<T[K]>;
+    /** Atomic unused Writes from this Store. Inside a transaction, joins it; any rejection makes the outer transaction rollback-only, even if caught. */
     batch<const W extends readonly Write<unknown>[]>(writes: W): Promise<{
         -readonly [K in keyof W]: Awaited<W[K]>;
     }>;
@@ -158,7 +172,7 @@ type BoundOperations<O> = {
         [N in keyof O[K]]: O[K][N] extends (db: any, caller: Caller, input: infer I, ...args: any[]) => infer R ? (input: I) => R : never;
     };
 };
-type Tx<T extends Record<string, Table>, O> = Pick<Store<T>, "collection"> & BoundOperations<O>;
+type Tx<T extends Record<string, Table>, O> = Store<T> & BoundOperations<O>;
 type Interactive<T extends Record<string, Table>, O> = {
     transaction<R>(fn: (tx: Tx<T, O>) => Promise<R>, options?: TransactionOptions): Promise<R>;
 };

package/dist/kernel/store.js

@@ -6,6 +6,7 @@ import { condition } from "./where.js";
 import { decodeCursor, encodeCursor } from "./paging.js";
 export { decodeCursor, encodeCursor };
 export const SCOPE = "$scope", TTL = "$ttl";
+export const REQUIRED = "publishing.required";
 const SYSTEM = ["id", "version", "created_at", "updated_at", "author_id", "status", "published_at", "_rid"];
 export function expand(r, f) {
     const all = (l) => l.flatMap(([c, ...t]) => (c = c === SCOPE ? f.s : c === TTL ? f.ttl?.[0] : c === "status" && !f.pub ? "" : c) ? [[c, ...t.map(v => v.k === "cutoff" ? { ...v, seconds: f.ttl[1] } : v)]] : []);
@@ -67,8 +68,8 @@ export function createStore(d, drv, rules, facts, operations) {
         p.policy.set(trusted, preparedPolicy);
         return preparedPolicy;
     };
-    return ((db, caller, options) => make(db, caller, false, options));
-    function make(db, caller, inTransaction = false, options) {
+    return ((db, caller, options) => make(db, caller, undefined, options));
+    function make(db, caller, transaction, options) {
         const pending = new WeakMap();
         const write = (build, project, path) => {
             const state = { build: () => { checkFresh(caller, false, path); return build(); }, project };
@@ -94,7 +95,8 @@ export function createStore(d, drv, rules, facts, operations) {
                             return fn && (cache[name] = (input) => fn(db, caller, input, options && { ...options, store }));
                         } })];
             })),
-            ...(!inTransaction && { batch: async (writes) => {
+            batch: async (writes) => {
+                try {
                     const states = writes.map(w => pending.get(w));
                     if (new Set(writes).size !== writes.length || states.some(s => !s || s.claimed))
                         throw new Error("Batch needs unused Writes from this Store.");
@@ -102,14 +104,26 @@ export function createStore(d, drv, rules, facts, operations) {
                         s.claimed = true;
                     const rows = writes.length ? await drv.procedure(db, states.map(s => s.build()), "store/batch") : [];
                     return states.map((s, i) => s.project(rows[i]));
-                } }),
+                }
+                catch (error) {
+                    if (transaction)
+                        transaction.failure ??= { error };
+                    throw error;
+                }
+            },
             ...(drv.transaction && { transaction: async (fn, txOptions) => {
-                    if (inTransaction)
+                    if (transaction)
                         throw new Error("Nested transactions are not supported.");
-                    return drv.transaction(db, tx => fn(make(tx, caller, true, options), tx), txOptions);
+                    const state = {};
+                    return drv.transaction(db, async (tx) => {
+                        const result = await fn(make(tx, caller, state, options), tx);
+                        if (state.failure)
+                            throw state.failure.error;
+                        return result;
+                    }, txOptions);
                 } }),
         };
-        if (inTransaction)
+        if (transaction)
             transactionStores.add(store);
         return store;
     }
@@ -132,11 +146,18 @@ export function createStore(d, drv, rules, facts, operations) {
             return out;
         };
         const rows = (sql, values) => drv.read(db, scoped(sql, caller), values);
-        const clean = (list) => { for (const r of list) {
-            delete r._rid;
-            if (f.s)
-                delete r[f.s];
-        } return list; };
+        const clean = (list) => {
+            for (const r of list) {
+                delete r._rid;
+                if (f.s)
+                    delete r[f.s];
+                const v = Number(r.version);
+                if (!Number.isSafeInteger(v))
+                    throw new ContractError("SQL_TYPE", `version ${r.version} is beyond Number.MAX_SAFE_INTEGER.`, p.name);
+                r.version = v;
+            }
+            return list;
+        };
         const select = () => pol.select ??= `SELECT r.*, ${wires(p, "r.")}${pol.projection ? ", " + pol.projection : ""}${pol.from}`;
         const where = (conds) => { const all = pol.sql ? [pol.sql, ...conds] : conds; return all.length ? ` WHERE ${all.join(" AND ")}` : ""; };
         const base = () => evaluate(d, pol.recipes, caller);
@@ -189,10 +210,22 @@ export function createStore(d, drv, rules, facts, operations) {
                 return [d.ident(name), mark];
             });
             const refs = (child) => trusted ? [] : (f.ref ?? []).flatMap(r => { const v = marks.get(r.column); return v ? [`EXISTS (SELECT 1 FROM ${d.ident(r.table)} _mantle_ref WHERE ${[`_mantle_ref.${d.ident(r.field)} = ${v}`, ...r.same.map(([parent, column]) => `_mantle_ref.${d.ident(parent)} = ${child(column) ?? "NULL"}`), ...r.terms.map(t => renderTerm(d, t, "_mantle_ref.", recipe))].join(" AND ")})`] : []; });
-            const guard = (id, also = []) => ` WHERE ${[`${ID} = ${push(id)}`, ...[...pol.terms, x.lock].map(t => renderTerm(d, t, t[1] === "parent" ? d.ident(p.name) + "." : "", recipe)), ...also].join(" AND ")}`;
-            const step = (sql) => ({ sql: scoped(sql, caller), binds: values, row: true });
+            const guard = (id, also = [], versioned = true) => ` WHERE ${[`${ID} = ${push(id)}`, ...[...pol.terms, ...versioned ? [x.lock] : []].map(t => renderTerm(d, t, t[1] === "parent" ? d.ident(p.name) + "." : "", recipe)), ...also].join(" AND ")}`;
+            const step = (sql, lock) => ({ sql: scoped(sql, caller), binds: values, row: true, ...(lock ? { lock } : {}) });
             return { given, marks, recipe, refs, guard, step, into, returning: () => ` RETURNING *, ${p.returning ??= wires(p, "")}` };
         };
+        const cleared = (set) => {
+            const req = f.req ?? {};
+            return [...new Set(Object.entries(set).flatMap(([name, v]) => v === null && Object.hasOwn(req, name.toLowerCase()) ? [req[name.toLowerCase()]] : []))];
+        };
+        const locked = (id, verb, fields = []) => {
+            const locks = trusted ? [] : (f.lock ?? []).filter(l => l.on.includes(verb)), required = fields.length ? `${d.ident("status")} <> 'published'` : undefined;
+            if (!locks.length && !required)
+                return { terms: [] };
+            const w = writer(), where = w.guard(id, [], false), cases = [...locks.map(l => `WHEN (${l.sql}) IS NOT FALSE THEN '${l.name}'`), ...required ? [`WHEN NOT (${required}) THEN '${REQUIRED}'`] : []];
+            const { sql, binds } = w.step(`SELECT CASE ${cases.join(" ")} END AS ${d.ident("lock")} FROM ${w.into}${where}`);
+            return { terms: [...locks.map(l => `NOT (${l.sql})`), ...required ? [required] : []], lock: { sql, binds, schema: p.name, verb, locks: Object.fromEntries(locks.map(l => [l.name, l.message])), ...required ? { required: `This entry is published: publish requires ${fields.join(", ")}, so an update cannot clear ${fields.length > 1 ? "them" : "it"}.` } : {} } };
+        };
         return {
             async findById(id) {
                 const values = base();
@@ -229,14 +262,14 @@ export function createStore(d, drv, rules, facts, operations) {
                     const w = writer(lock), assigns = w.given(set).map(([name, mark]) => `${name} = ${mark}`);
                     for (const [column, v] of x.sets)
                         assigns.push(`${d.ident(column)} = ${v === "bump" ? `${d.ident(column)} + 1` : w.recipe(v)}`);
-                    const refs = w.refs(column => `${w.into}.${d.ident(column)}`);
-                    return w.step(`UPDATE ${w.into} SET ${assigns.join(", ")}${w.guard(id, refs)}${w.returning()}`);
+                    const refs = w.refs(column => `${w.into}.${d.ident(column)}`), held = locked(id, "update", cleared(set));
+                    return w.step(`UPDATE ${w.into} SET ${assigns.join(", ")}${w.guard(id, [...refs, ...held.terms])}${w.returning()}`, held.lock);
                 }, rows => clean(rows)[0], `${p.name}/update`);
             },
             delete(id, { lock }) {
                 return write(() => {
-                    const w = writer(lock);
-                    return w.step(`DELETE FROM ${w.into}${w.guard(id)}`);
+                    const w = writer(lock), held = locked(id, "delete");
+                    return w.step(`DELETE FROM ${w.into}${w.guard(id, held.terms)}`, held.lock);
                 }, () => undefined, `${p.name}/delete`);
             },
         };

package/dist/usecase/adminBindings.js

@@ -93,9 +93,9 @@ export function emitAdminBindings(input, refuse) {
         const defaults = Object.fromEntries(Object.entries(checks(s, true).properties ?? {}).flatMap(([key, p]) => p.default !== undefined ? [[key, p.default]] : []));
         const primary = isPrimaryCollection(s, Object.values(plan.schemas));
         const schemaCode = `{
-      name:${q(s.name)},primary:${primary},descriptor:allCollections[${q(s.name)}],publishing:${!!s.publishing},readOnly:${s.schema.readOnly === true || declared.some(f => s.fields[f] === "geo")},fields:names${n},defaults:${q(defaults)},
+      name:${q(s.name)},primary:${primary},descriptor:allCollections[${q(s.name)}],publishing:${!!s.publishing},${s.liveEdits ? "liveEdits:true," : ""}readOnly:${s.schema.readOnly === true || declared.some(f => s.fields[f] === "geo")},fields:names${n},defaults:${q(defaults)},
       binding:${entrySpec},
-      query:query${n},validate:(data,full)=>{const checked=Object.fromEntries(Object.entries(data).filter(([key,v])=>v!==null||${q(s.schema.required ?? [])}.includes(key)));(full?full${n}:partial${n})(checked);${sqlite ? "" : "nativeText(data);"}${yearZero}return data;},
+      query:query${n},validate:(data,full)=>{const checked=Object.fromEntries(Object.entries(data).filter(([key,v])=>v!==null||${s.publishing ? "full&&" : ""}${q(s.schema.required ?? [])}.includes(key)));(full?full${n}:partial${n})(checked);${sqlite ? "" : "nativeText(data);"}${yearZero}return data;},
       values:values${n},row:${named},
       ${sqlite ? "" : "native:nativeText,"}
       ${s.publishing ? `transition:async(db,caller,verb,id,expectedVersion)=>{const run=await ({publish:()=>import("./procedures/${encodeURIComponent(s.name + ".publish")}.js"),unpublish:()=>import("./procedures/${encodeURIComponent(s.name + ".unpublish")}.js"),archive:()=>import("./procedures/${encodeURIComponent(s.name + ".archive")}.js")})[verb]();const version=wireRows([{version:expectedVersion}],[["version","int"]])[0]!.version;return run.default(db,caller,{id,expectedVersion:version} as Parameters<typeof run.default>[2]);},` : ""}