@cosmicdrift/kumiko-framework 0.374.0 → 0.378.0

package/dist/db/money.d.ts

@@ -1,5 +1,6 @@
+import { toMinorUnits } from "../engine/minor-units.ts";
 import type { EntityDefinition } from "../engine/types/index.ts";
-export declare function toMinorUnits(amount: number): number;
+export { toMinorUnits };
 export declare function moneyPayloadToMinorUnits(raw: unknown): number | undefined;
 export declare function flattenMoney(payload: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;
 /** Shape of a single rehydrated money field — {amount major, currency,

package/dist/db/money.js

@@ -10,7 +10,7 @@
 //                round-tripping the float amount through /100·*100.
 //                `amountMinor` stays as a @deprecated alias of the same
 //                value until #1976/4 and #1976/5 migrate their remaining
-//                consumers (renderer-web/primitives/index.tsx,
+//                consumers (renderer/web/primitives/index.tsx,
 //                renderer/components/render-field.tsx) off the old name.
 //
 // table-builder.ts's moneyAmount column has always documented BIGINT as
@@ -30,15 +30,10 @@
 // Anders als locatedTimestamp behalten wir den Field-Namen `<name>` als
 // amount-Spalte (Legacy DB-Convention für Money — `SUM(buying_price)` bleibt
 // idiomatisch). `<name>Currency` ist die zusätzliche Spalte.
+import { MINOR_UNIT_SCALE, toMinorUnits } from "../engine/minor-units.js";
 import { DEFAULT_CURRENCIES } from "../engine/types/index.js";
 const FRAMEWORK_DEFAULT_CURRENCY = DEFAULT_CURRENCIES[0]; // "EUR"
-// 2 decimal places (cents) — covers every currently-supported currency
-// (EUR/USD/GBP/...). No ISO-4217 minor-unit table yet (JPY=0, BHD=3) —
-// upgrade path once a currency needing a different scale actually lands.
-const MINOR_UNIT_SCALE = 100;
-export function toMinorUnits(amount) {
-    return Math.round(amount * MINOR_UNIT_SCALE);
-}
+export { toMinorUnits };
 function toMajorUnits(amountScaled) {
     return amountScaled / MINOR_UNIT_SCALE;
 }

package/dist/db/query.js

@@ -44,7 +44,7 @@ function snakeToCamel(key) {
 // the only collision-safe path.
 export { asEntityTableMeta, requireEntityTableMeta };
 export function hasBegin(client) {
-    // Bun.SQL tx/savepoint handles keep a begin() that throws; only savepoint() tells them apart from a pool.
+    // Tx/savepoint handles can keep a begin() that throws; only savepoint() tells them apart from a pool.
     return typeof client.begin === "function" && typeof client.savepoint !== "function";
 }
 function isRawClient(value) {
@@ -77,7 +77,7 @@ export function asRawClient(db) {
 export function runnerCanBeginTransaction(db) {
     return hasBegin(asRawClient(db));
 }
-// postgres.js / Bun.SQL reject the WHOLE begin() when any statement inside
+// postgres.js rejects the WHOLE begin() when any statement inside
 // it errored — even if the JS error was caught (the driver tracks per-block
 // query failures). Error confinement therefore must go through the driver's
 // own savepoint(), not manual SAVEPOINT statements. The callback receives
@@ -85,7 +85,7 @@ export function runnerCanBeginTransaction(db) {
 export async function runInSavepoint(tx, fn) {
     const raw = asRawClient(tx);
     if (typeof raw.savepoint !== "function") {
-        throw new Error("runInSavepoint: transaction handle has no savepoint() — pass the driver tx (postgres.js TransactionSql / Bun.SQL).");
+        throw new Error("runInSavepoint: transaction handle has no savepoint() — pass the driver tx (postgres.js TransactionSql).");
     }
     return raw.savepoint(fn);
 }
@@ -180,7 +180,7 @@ function isWhereOperator(v) {
 export function extractTableInfo(table) {
     const meta = asEntityTableMeta(table);
     if (!meta) {
-        throw new Error("bun-db.extractTableInfo: table is not a kumiko EntityTableMeta — " +
+        throw new Error("extractTableInfo: table is not a kumiko EntityTableMeta — " +
             "build it via buildEntityTable / deriveEntityTableMeta / table().");
     }
     const colByField = new Map();
@@ -282,7 +282,7 @@ function isTemporalPlainDateTimeLike(v) {
         "toPlainDate" in v &&
         typeof v.toPlainDate === "function");
 }
-// Verified empirically against Bun.SQL (kumiko-framework#1924): a `date`
+// Verified empirically (kumiko-framework#1924): a `date`
 // column comes back as a native JS Date, but ALWAYS anchored at UTC
 // midnight regardless of process TZ — epochMilliseconds is stable across
 // zones, only the local wall-clock read of that Date would drift the day
@@ -296,7 +296,7 @@ function isTemporalPlainDateTimeLike(v) {
 // the day, so say so once per column instead of returning the wrong day quietly.
 const warnedNonMidnightDateColumns = new Set();
 const MS_PER_DAY = 86_400_000;
-const dateColumnDriftLog = createFallbackLogger("bun-db");
+const dateColumnDriftLog = createFallbackLogger("postgres-js");
 function warnIfNotDateColumn(epochMs, column) {
     // skip: midnight value is a correct date column, and an already-warned column is deduped
     if (epochMs % MS_PER_DAY === 0 || warnedNonMidnightDateColumns.has(column))
@@ -384,7 +384,7 @@ function coerceDriverRow(row, info) {
         }
         else if ((pgType === "integer" || pgType === "int4" || pgType === "smallint" || pgType === "int2") &&
             (typeof value === "bigint" || typeof value === "string")) {
-            // Bun.SQL / some drivers return int4 as bigint or numeric string.
+            // Drivers may return int4 as bigint or numeric string.
             // Drizzle coerced to number for numberField columns — match that.
             const n = Number(value);
             if (!Number.isNaN(n))
@@ -469,8 +469,8 @@ const INTEGER_PG_TYPES = new Set([
     "serial",
     "bigserial",
 ]);
-// postgres.js truncates timestamptz params to ms via Date; Bun.SQL sends µs and Postgres
-// rounds into timestamptz(3). Truncating here keeps both drivers storing the same instant.
+// Postgres rounds sub-millisecond params into timestamptz(3); truncating to ms here keeps the
+// stored instant identical across drivers and equal to what postgres.js sends via Date.
 export function instantToTimestamptzParam(instant) {
     return Temporal.Instant.fromEpochMilliseconds(instant.epochMilliseconds).toString();
 }
@@ -478,7 +478,7 @@ function prepareDriverNeutralScalar(value, pgType) {
     if ((pgType === "timestamptz" || pgType === "timestamptz(3)") && isTemporalInstant(value)) {
         return { kind: "param", sql: "", bound: instantToTimestamptzParam(value) };
     }
-    // Bun.SQL binds JS numbers typed, so Postgres would round 3.5 into an integer column; postgres.js sends text and rejects it.
+    // postgres.js sends text, so Postgres rejects 3.5 for an integer column instead of rounding it.
     if (typeof value === "number" && pgType !== undefined && INTEGER_PG_TYPES.has(pgType)) {
         return { kind: "param", sql: "", bound: String(value) };
     }
@@ -489,7 +489,7 @@ function prepareValue(value, pgType) {
         return { kind: "literal", literal: value.text };
     }
     // A PII-encrypted jsonb field is a JSON string scalar; a raw string bound to
-    // ::jsonb would be parsed as JSON text (or double-encoded under Bun.SQL).
+    // ::jsonb would be parsed as JSON text (or double-encoded).
     if (pgType === "jsonb" && isPiiCiphertext(value)) {
         return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
     }
@@ -732,7 +732,7 @@ function isPooledClient(raw) {
         typeof propertyOf(raw, "savepoint") !== "function" &&
         typeof propertyOf(raw, "release") !== "function");
 }
-const closedConnectionLog = createFallbackLogger("bun-db");
+const closedConnectionLog = createFallbackLogger("postgres-js");
 // The driver rejects in-flight queries with this AbortError (no code) when the
 // pool closes under them, so isClosedConnectionError can't see it.
 const DRIVER_CLOSED_ABORT_MESSAGE = "The connection was closed.";
@@ -805,7 +805,7 @@ function logClosedConnection(raw, err, attempts, context) {
     });
 }
 // Write and other non-retried paths: log when a closed-connection error leaves
-// bun-db, rethrow unchanged.
+// the db layer, rethrow unchanged.
 async function unsafeLoggingClosedConnection(db, sqlText, params, context) {
     const raw = asRawClient(db);
     try {
@@ -821,7 +821,7 @@ function poolMaxOf(raw) {
     const max = propertyOf(propertyOf(raw, "options"), "max");
     return typeof max === "number" && Number.isInteger(max) && max > 0 ? max : DEFAULT_POOL_MAX;
 }
-// Exported so raw-SQL query modules outside bun-db (e.g. bundled-features'
+// Exported so raw-SQL query modules outside the db layer (e.g. bundled-features'
 // db/queries/*.ts) can opt into the same closed-connection retry instead of
 // calling asRawClient(db).unsafe(...) directly and losing it.
 // READS ONLY — retry re-executes the statement; never pass INSERT/UPDATE/DELETE.

package/dist/db/replay-migration-sql.d.ts

@@ -1,6 +1,7 @@
 import type { Snapshot } from "./migrate-generator.ts";
 export type ReplayedTable = {
     readonly columns: ReadonlySet<string>;
+    readonly columnsUnknown?: boolean;
 };
 export type ReplayedSchema = ReadonlyMap<string, ReplayedTable>;
 export declare function replayMigrationsDir(migrationsDir: string): ReplayedSchema;

package/dist/db/replay-migration-sql.js

@@ -67,18 +67,106 @@ function parseColumnNames(body) {
 // Clauses that can appear inside an ALTER TABLE body which do NOT change the
 // table/column shape this replay tracks (presence only, not types/
 // constraints/RLS/ownership) — recognized explicitly so they don't fall
-// through to the fail-loud check as "unparsed". Deliberately does NOT
-// include RENAME TO / RENAME COLUMN: those DO change identity in a way this
-// replay can't track, so they must keep failing loud.
+// through to the fail-loud check as "unparsed". RENAME TO / RENAME COLUMN
+// are not listed here: they change identity and are applied explicitly.
 const SHAPE_NEUTRAL_ALTER_CLAUSE_RE = new RegExp([
     `ALTER COLUMN\\s+${IDENT}\\s+TYPE\\b`, // #1085 int/bigint-catchup fixes
     `ALTER COLUMN\\s+${IDENT}\\s+(SET|DROP)\\s+NOT NULL\\b`,
     `ALTER COLUMN\\s+${IDENT}\\s+(SET DEFAULT\\b|DROP DEFAULT\\b)`,
     `(ADD|DROP)\\s+CONSTRAINT\\s+${IDENT}`,
+    `RENAME\\s+CONSTRAINT\\s+${IDENT}\\s+TO\\s+${IDENT}`,
     `\\b(ENABLE|DISABLE|(NO\\s+)?FORCE)\\s+ROW LEVEL SECURITY\\b`,
     `^OWNER TO\\b`,
 ].join("|"), "gi");
+function lastIdentifierSegment(expression) {
+    const match = expression.trim().match(new RegExp(`(?:^|\\.)${IDENT}$`));
+    return match?.[1];
+}
+// Column names of a `SELECT <list> FROM <table>` as CREATE TABLE AS materializes them: the
+// alias, else the last segment of a plain column reference. `*` copies the single FROM table
+// when the replay knows it; anything else makes the column set unknown.
+function selectListColumns(schema, query) {
+    const columns = new Set();
+    let columnsUnknown = false;
+    const select = query.match(/^\s*SELECT\s+(?:DISTINCT\s+)?([\s\S]*)$/i);
+    if (!select?.[1])
+        return { columns, columnsUnknown: true };
+    let list = select[1];
+    const fromAt = topLevelKeywordIndex(list, "FROM");
+    const fromClause = fromAt === -1 ? "" : list.slice(fromAt + 4);
+    if (fromAt !== -1)
+        list = list.slice(0, fromAt);
+    for (const item of splitTopLevel(list)) {
+        const trimmed = item.trim();
+        if (/(^|\.)\*$/.test(trimmed)) {
+            const source = fromClause.match(new RegExp(`^\\s*${IDENT}\\s*(?:;|$)`))?.[1];
+            const sourceTable = source === undefined ? undefined : schema.get(source);
+            if (sourceTable && !sourceTable.columnsUnknown) {
+                for (const column of sourceTable.columns)
+                    columns.add(column);
+            }
+            else {
+                columnsUnknown = true;
+            }
+            continue;
+        }
+        const alias = trimmed.match(new RegExp(`\\bAS\\s+${IDENT}\\s*$`, "i"))?.[1];
+        const name = alias ?? lastIdentifierSegment(trimmed);
+        if (name === undefined)
+            columnsUnknown = true;
+        else
+            columns.add(name);
+    }
+    return { columns, columnsUnknown };
+}
+function topLevelKeywordIndex(text, keyword) {
+    let depth = 0;
+    const keywordRe = new RegExp(`^${keyword}\\b`, "i");
+    for (let i = 0; i < text.length; i++) {
+        const ch = text.charAt(i);
+        if (ch === "(")
+            depth++;
+        else if (ch === ")")
+            depth--;
+        else if (depth === 0 && /\s/.test(text.charAt(i - 1) || " ") && keywordRe.test(text.slice(i))) {
+            return i;
+        }
+    }
+    return -1;
+}
+// A DO block's conditions can't be evaluated here; its table DDL is applied as written, since
+// guarded blocks (IF NOT EXISTS ... THEN ALTER TABLE ...) express the intended end state.
+function doBlockTableStatements(statement, file) {
+    const body = statement.match(/^DO\s+(?:LANGUAGE\s+\w+\s+)?(\$(?:[A-Za-z_]\w*)?\$)([\s\S]*)\1/i)?.[2];
+    if (body === undefined) {
+        throw new Error(`${file}: DO block without a recognizable dollar-quoted body — refusing to guess its table DDL`);
+    }
+    return body
+        .split(";")
+        .map((chunk) => chunk.match(/\b(?:CREATE|ALTER|DROP)\s+TABLE\b[\s\S]*$/i)?.[0])
+        .filter((ddl) => ddl !== undefined)
+        .map((ddl) => `${ddl.trim()};`);
+}
 function applyStatement(schema, statement, context) {
+    if (/^DO\b/i.test(statement)) {
+        for (const nested of doBlockTableStatements(statement, context.file))
+            applyStatement(schema, nested, context);
+        // skip: DO block fully handled above
+        return;
+    }
+    const createAs = statement.match(new RegExp(`^CREATE\\s+(?:UNLOGGED\\s+)?TABLE\\s+(IF NOT EXISTS\\s+)?${IDENT}\\s*(?:\\(([^)]*)\\)\\s*)?AS\\b([\\s\\S]*)$`, "i"));
+    if (createAs?.[2] !== undefined && createAs[4] !== undefined) {
+        if (!(createAs[1] !== undefined && schema.has(createAs[2]))) {
+            const explicitColumns = createAs[3] === undefined ? undefined : parseColumnNames(createAs[3]);
+            const selected = selectListColumns(schema, createAs[4]);
+            schema.set(createAs[2], {
+                columns: explicitColumns ?? selected.columns,
+                ...(explicitColumns === undefined && selected.columnsUnknown && { columnsUnknown: true }),
+            });
+        }
+        // skip: CREATE TABLE AS fully handled above
+        return;
+    }
     const create = statement.match(new RegExp(`^CREATE TABLE\\s+(IF NOT EXISTS\\s+)?${IDENT}\\s*\\(([\\s\\S]*)\\);?\\s*$`, "i"));
     if (create?.[2] !== undefined && create[3] !== undefined) {
         const hasIfNotExists = create[1] !== undefined;
@@ -113,6 +201,23 @@ function applyStatement(schema, statement, context) {
     const alterTableName = alterTable?.[1];
     const alterBody = alterTable?.[2];
     if (alterTableName !== undefined && alterBody !== undefined) {
+        const renameTable = alterBody.match(new RegExp(`^RENAME\\s+TO\\s+${IDENT}\\s*;?$`, "i"));
+        if (renameTable?.[1] !== undefined) {
+            const renamed = schema.get(alterTableName) ?? { columns: new Set() };
+            schema.delete(alterTableName);
+            schema.set(renameTable[1], renamed);
+            // skip: ALTER TABLE RENAME TO fully handled above
+            return;
+        }
+        const renameColumn = alterBody.match(new RegExp(`^RENAME\\s+(?:COLUMN\\s+)?${IDENT}\\s+TO\\s+${IDENT}\\s*;?$`, "i"));
+        if (renameColumn?.[1] !== undefined && renameColumn[2] !== undefined) {
+            const renamedIn = schema.get(alterTableName) ?? { columns: new Set() };
+            schema.set(alterTableName, renamedIn);
+            renamedIn.columns.delete(renameColumn[1]);
+            renamedIn.columns.add(renameColumn[2]);
+            // skip: ALTER TABLE RENAME COLUMN fully handled above
+            return;
+        }
         const table = schema.get(alterTableName) ?? { columns: new Set() };
         schema.set(alterTableName, table);
         const clauseRe = new RegExp(`(ADD|DROP)\\s+COLUMN\\s+(?:IF (?:NOT )?EXISTS\\s+)?${IDENT}`, "gi");
@@ -133,8 +238,8 @@ function applyStatement(schema, statement, context) {
         if (alterBody.match(SHAPE_NEUTRAL_ALTER_CLAUSE_RE))
             matchedAClause = true;
         // An ALTER TABLE that matched the outer "ALTER TABLE <name> <body>" shape
-        // but whose body contains no recognized clause (e.g. RENAME TO/RENAME
-        // COLUMN, which DO change identity) would otherwise silently no-op here
+        // but whose body contains no recognized clause (e.g. SET SCHEMA)
+        // would otherwise silently no-op here
         // — fall through to the fail-loud check below instead of returning, so
         // it's reported rather than vanishing.
         // skip: at least one recognized clause matched — this ALTER TABLE is
@@ -146,19 +251,16 @@ function applyStatement(schema, statement, context) {
     // shape this replay tracks — but a statement that clearly INTENDED to
     // touch a table's shape (starts with CREATE/ALTER/DROP TABLE) and matched
     // none of the recognized patterns above must fail loud, not vanish
-    // silently. Concretely this is RENAME TO / RENAME COLUMN (identity change
-    // this replay can't track) or genuinely unparsed hand-written DDL — either
-    // way a misleading missing-table/column-drift report is worse than
+    // silently. Concretely this is genuinely unparsed hand-written DDL — a misleading missing-table/column-drift report is worse than
     // pointing at the actual unparsed statement.
     if (/^(CREATE|ALTER|DROP)\s+TABLE\b/i.test(statement)) {
         const prefix = statement.slice(0, 200).replace(/\s+/g, " ").trim();
         throw new Error(`replayMigrationsDir: unparsed table-DDL statement in ${context.file} — ` +
             `starts with CREATE/ALTER/DROP TABLE but matched none of the replay's ` +
             `recognized patterns (CREATE TABLE, DROP TABLE, ALTER TABLE ADD/DROP ` +
-            `COLUMN, ALTER COLUMN ... TYPE, SET/DROP NOT NULL, SET/DROP DEFAULT, ` +
+            `COLUMN, RENAME TO/COLUMN, CREATE TABLE AS, DO blocks, ALTER COLUMN ... TYPE, SET/DROP NOT NULL, SET/DROP DEFAULT, ` +
             `ADD/DROP CONSTRAINT, ENABLE/DISABLE/[NO] FORCE ROW LEVEL SECURITY, OWNER TO — ` +
-            `optionally-quoted identifiers). Likely RENAME TO/RENAME COLUMN (real ` +
-            `identity change, not trackable here) or genuinely unparsed hand-written ` +
+            `optionally-quoted identifiers). Likely genuinely unparsed hand-written ` +
             `DDL. Statement: ${prefix}${statement.length > 200 ? "…" : ""}`);
     }
 }
@@ -194,6 +296,8 @@ export function diffReplayAgainstSnapshot(replayed, snapshot) {
             });
             continue;
         }
+        if (table.columnsUnknown)
+            continue;
         const expected = new Set(meta.columns.map((c) => c.name));
         const missing = [...expected].filter((c) => !table.columns.has(c));
         const extra = [...table.columns].filter((c) => !expected.has(c));

package/dist/db/tenant-db.d.ts

@@ -36,6 +36,13 @@ export declare function acknowledgeConventionCrossTenant(tenantDb: TenantDb, rea
     readonly deferReport?: boolean;
 }): TenantDb;
 export declare function reportConventionCrossTenantUse(acknowledged: TenantDb, target?: EscapeHatchTarget): void;
+export type OutsideTransactionContext = {
+    readonly dbOutsideTransaction: TenantDb | undefined;
+};
+export declare function hasOutsideTransactionDb(ctx: OutsideTransactionContext): ctx is OutsideTransactionContext & {
+    readonly dbOutsideTransaction: TenantDb;
+};
+export declare function requireOutsideTransactionDb(ctx: OutsideTransactionContext): TenantDb;
 export declare function runInOwnTransaction<T>(tenantDb: TenantDb, fn: (txDb: TenantDb) => Promise<T>): Promise<T>;
 export type CreateTenantDbOptions = {
     readonly db: DbRunner;

package/dist/db/tenant-db.js

@@ -5,6 +5,7 @@ import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
 import { emitDbQuery, fallbackEscapeHatchReporter, registerStandardMetrics, } from "../observability/index.js";
 import { bindProjectionRegistry, projectionRegistryOf } from "./projection-registry-binding.js";
+import { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
 import { hasFieldProperty, tableNameOf } from "./table-introspection.js";
 import { bindTenantDbRunner, denyTenantDbWrites, tenantDbRunner, tenantDbWritesDeniedError, } from "./tenant-db-runner.js";
 export { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
@@ -103,7 +104,7 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
     // AccessDeniedError) because this is a dispatch wiring fault, not a
     // tenant-access denial — mirrors the "no database connection configured"
     // case in dispatch-shared.ts's appendDomainEvent.
-    function requireOutsideTransactionDb() {
+    function requireSystemOutsideTransactionDb() {
         if (!dbOutsideTransaction) {
             throw new InternalError({
                 message: "systemScope() outsideTransaction check failed: no outside-transaction database " +
@@ -173,13 +174,13 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
                         message: `systemScope() outsideTransaction tenant self-check failed: expected "${db.tenantId}", got "${tenantId}"`,
                     });
                 }
-                return requireOutsideTransactionDb();
+                return requireSystemOutsideTransactionDb();
             },
             acknowledgeCrossTenant(reason) {
                 if (reason.trim().length === 0) {
                     throw new Error("acknowledgeCrossTenant requires a non-empty reason");
                 }
-                const result = requireOutsideTransactionDb();
+                const result = requireSystemOutsideTransactionDb();
                 report("acknowledge-cross-tenant", reason);
                 return result;
             },
@@ -301,12 +302,24 @@ export function reportConventionCrossTenantUse(acknowledged, target) {
     reporter(target);
 }
 const ownTransactionRebinders = new WeakMap();
+export function hasOutsideTransactionDb(ctx) {
+    return ctx.dbOutsideTransaction !== undefined;
+}
+export function requireOutsideTransactionDb(ctx) {
+    if (!hasOutsideTransactionDb(ctx)) {
+        throw new InternalError({
+            message: "ctx.dbOutsideTransaction is not available in this dispatch phase (member-resolution, before-transaction denial) or metering tenant mode.",
+        });
+    }
+    return ctx.dbOutsideTransaction;
+}
 export async function runInOwnTransaction(tenantDb, fn) {
     const rebind = ownTransactionRebinders.get(tenantDb);
     if (!rebind) {
         throw new InternalError({
-            message: "runInOwnTransaction received a TenantDb not built by createTenantDb — " +
-                "no transaction rebinder bound.",
+            message: "runInOwnTransaction received a TenantDb without a transaction rebinder: either it was not " +
+                "built by createTenantDb, or it is the fail-closed ctx.db/ctx.dbOutsideTransaction of an " +
+                "r.systemScope() handler (use ctx.systemDb.outsideTransaction there).",
         });
     }
     return rebind(fn);
@@ -543,6 +556,9 @@ function buildTenantDb(options) {
             const filter = readWhere(table, where);
             return withDbSpan("select", table, async () => bunCountWhere(db, table, filter));
         },
+        advisoryXactLock(namespace, key) {
+            return acquireNamespacedAdvisoryLock(db, namespace, `${tenantId}:${key}`);
+        },
         aggregate(table, spec, where) {
             const filter = readWhere(table, where);
             return withDbSpan("select", table, async () => bunAggregateWhere(db, table, spec, filter));

package/dist/engine/boot-validator/entity-handler.js

@@ -642,6 +642,9 @@ function validateEmbeddedDerivedCells(fieldName, entityName, field) {
         if (!(derivedName in field.schema)) {
             throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" that is not a sub-field in its schema. Add the sub-field to the schema or remove the derived cell.`);
         }
+        if (derivedDef.op === "percent" && derivedDef.from.length !== 2) {
+            throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" with op "percent", which needs exactly two sources (base, rate).`);
+        }
         for (const sourceName of derivedDef.from) {
             if (!(sourceName in field.schema)) {
                 throw new Error(`Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" reading unknown sub-field "${sourceName}". Read only sub-fields that exist in the schema.`);

package/dist/engine/boot-validator/form-derivations.d.ts

@@ -0,0 +1,4 @@
+import type { FeatureDefinition } from "../types/feature.ts";
+import type { ActionFormScreenDefinition } from "../types/screen.ts";
+export declare function validateFormDerivations(featureName: string, screenId: string, screen: ActionFormScreenDefinition): void;
+export declare function validateFormDerivationsEnforced(featureName: string, screenId: string, screen: ActionFormScreenDefinition, featureMap: ReadonlyMap<string, FeatureDefinition>): void;

package/dist/engine/boot-validator/form-derivations.js

@@ -0,0 +1,82 @@
+import { orderFormDerivations } from "../form-derivations.js";
+import { parseQn } from "../qualified-name.js";
+import { formDerivationsOfSchema } from "../with-form-derivations.js";
+const NUMERIC_FORM_FIELD_TYPES = ["money", "number", "decimal"];
+const NUMERIC_SUB_FIELD_TYPES = ["money", "number", "decimal"];
+function validateFromList({ prefix, screen, target }, derivation) {
+    if (derivation.op === "percent" && derivation.from.length !== 2) {
+        throw new Error(`${prefix}.${target}: "percent" needs exactly two sources (base, rate).`);
+    }
+    for (const source of derivation.from) {
+        if (!(source in screen.fields)) {
+            throw new Error(`${prefix}.${target}: unknown source field "${source}". Name a field of this screen.`);
+        }
+    }
+}
+function validateListSum(check, derivation) {
+    const { prefix, screen, target } = check;
+    const listField = screen.fields[derivation.list];
+    if (listField === undefined) {
+        throw new Error(`${prefix}.${target}: unknown list field "${derivation.list}".`);
+    }
+    if (listField.type !== "embedded" || listField.multiple !== true) {
+        throw new Error(`${prefix}.${target}: "${derivation.list}" must be an embedded list field (multiple: true).`);
+    }
+    const cellType = listField.schema[derivation.cell]?.type;
+    if (cellType === undefined || !NUMERIC_SUB_FIELD_TYPES.includes(cellType)) {
+        throw new Error(`${prefix}.${target}: "${derivation.cell}" must be a money, number or decimal sub-field of "${derivation.list}".`);
+    }
+    const { whenEmpty } = derivation;
+    // skip: whenEmpty is optional
+    if (whenEmpty === undefined)
+        return;
+    // Type forbids a nested listSum; JS/cast callers can still pass one.
+    if (!("from" in whenEmpty)) {
+        throw new Error(`${prefix}.${target}: whenEmpty must not be a listSum.`);
+    }
+    validateFromList(check, whenEmpty);
+}
+// actionForm `derive`: every name must resolve, targets must be numeric, a
+// listSum must point at a numeric cell of an embedded list, no cycles.
+export function validateFormDerivations(featureName, screenId, screen) {
+    const derive = screen.derive;
+    // skip: the screen derives nothing
+    if (derive === undefined)
+        return;
+    const prefix = `[Feature ${featureName}] Screen "${screenId}" (actionForm) derive`;
+    for (const [target, derivation] of Object.entries(derive)) {
+        const targetField = screen.fields[target];
+        if (targetField === undefined) {
+            throw new Error(`${prefix}: key "${target}" is not a field of this screen.`);
+        }
+        if (!NUMERIC_FORM_FIELD_TYPES.includes(targetField.type)) {
+            throw new Error(`${prefix}.${target}: a derived field must be money, number or decimal, not "${targetField.type}".`);
+        }
+        const check = { prefix, screen, target };
+        if (derivation.op === "listSum")
+            validateListSum(check, derivation);
+        else
+            validateFromList(check, derivation);
+    }
+    try {
+        orderFormDerivations(derive);
+    }
+    catch (error) {
+        throw new Error(`${prefix}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+// Secure by default: a derive the handler schema doesn't recompute would let a
+// client send its own totals, so the handler must wrap with this very screen.
+export function validateFormDerivationsEnforced(featureName, screenId, screen, featureMap) {
+    // skip: the screen derives nothing
+    if (screen.derive === undefined)
+        return;
+    const { scope, name } = parseQn(screen.handler);
+    const schema = featureMap.get(scope)?.writeHandlers[name]?.schema;
+    // skip: wrapped with this screen
+    if (formDerivationsOfSchema(schema) === screen.derive)
+        return;
+    throw new Error(`[Feature ${featureName}] Screen "${screenId}" (actionForm) declares derive, but handler ` +
+        `"${screen.handler}" does not recompute it on the server. Wrap the handler schema: ` +
+        `withFormDerivations(schema, screen) with this screen object.`);
+}

package/dist/engine/boot-validator/screens.js

@@ -18,6 +18,7 @@ import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops.js"
 import { explicitListScreenId, isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../screen-helpers.js";
 import { metricField } from "../types/index.js";
 import { LIST_ROW_META_COLUMN_NAMES } from "./entity-list-screens.js";
+import { validateFormDerivations, validateFormDerivationsEnforced } from "./form-derivations.js";
 import { isSelectOptionTone } from "./select-option-tone.js";
 function isRowClickAction(action) {
     return (action.kind === "navigate" || action.kind === "drawer") && action.rowClick === true;
@@ -319,7 +320,7 @@ function validateWizardLayout(featureName, screenId, screenType, layout, feature
 // typed IconKey, a closed union — but that only protects call sites this
 // repo's own `tsc --build` actually covers (samples and external consumers
 // aren't in that project graph). The renderer's actionIconFor
-// (renderer-web/src/primitives/index.tsx) already falls back to "no icon"
+// (renderer/src/web/primitives/index.tsx) already falls back to "no icon"
 // for an unregistered key instead of crashing — this check makes the same
 // gap fail loudly at boot instead of silently at render.
 function isRegisteredIcon(icon) {
@@ -909,6 +910,12 @@ function validateInlineFormNavTargets(feature, screenId, screen, kind, lookups)
     if (screen.redirect !== undefined) {
         validateRedirectTarget(feature, screenId, kind, screen.redirect, lookups);
     }
+    if (screen.type === "actionForm" &&
+        screen.successFacts !== undefined &&
+        screen.redirect !== undefined) {
+        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (actionForm) sets both redirect and successFacts — ` +
+            `redirect leaves the screen, successFacts are shown on it. Use one of them.`);
+    }
     if (screen.type === "actionForm" && screen.successLinks !== undefined) {
         if (screen.redirect !== undefined) {
             throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (actionForm) sets both redirect and successLinks — ` +
@@ -939,6 +946,10 @@ function validateInlineFormScreen(feature, screenId, screen, kind, allWriteHandl
     const fieldNames = validateFormFieldsMap(feature.name, screenId, kind, screen.fields, allowEmptyMintForm);
     validateFormLayoutSections(feature.name, screenId, kind, screen.layout, fieldNames, screen.fields, allowEmptyMintForm && fieldNames.size === 0);
     validateWizardLayout(feature.name, screenId, kind, screen.layout, featureMap);
+    if (screen.type === "actionForm") {
+        validateFormDerivations(feature.name, screenId, screen);
+        validateFormDerivationsEnforced(feature.name, screenId, screen, featureMap);
+    }
     validateInlineFormNavTargets(feature, screenId, screen, kind, lookups);
 }
 // SecretMintConfirmStep (fw#2838): an optional proof-of-receipt form rendered
@@ -1281,17 +1292,25 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     else if (action.kind === "clientAction") {
                         validateClientActionName(feature.name, screenId, "projectionList", "rowAction", action);
                     }
+                    else if (!allWriteHandlerQns.has(action.handler)) {
+                        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionList) rowAction "${action.id}" ` +
+                            `handler "${action.handler}" is not a registered write-handler. Check the QN spelling ` +
+                            `(expected "<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
+                    }
                 }
                 validateAtMostOneRowClick(feature.name, screenId, "projectionList", screen.rowActions);
             }
-            // Only drawer-kind and navigate actions that set tab are validated
-            // here — plain navigate (no tab) and writeHandler toolbarActions on
-            // projectionList have no boot check yet (pre-existing gap).
+            // Plain navigate toolbarActions (no tab) have no boot check yet.
             if (screen.toolbarActions !== undefined) {
                 for (const action of screen.toolbarActions) {
                     if (action.kind === "drawer") {
                         validateDrawerTargetAction(feature.name, screenId, "projectionList", "toolbarAction", action, feature.screens);
                     }
+                    else if (action.kind === "writeHandler" && !allWriteHandlerQns.has(action.handler)) {
+                        throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (projectionList) toolbarAction "${action.id}" ` +
+                            `handler "${action.handler}" is not a registered write-handler. Check the QN spelling ` +
+                            `(expected "<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
+                    }
                     if (action.kind === "navigate" && action.tab !== undefined) {
                         resolveRowActionNavigateTarget(feature.name, screenId, "projectionList", "toolbarAction", action, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens);
                     }