biz-a-cli 2.3.80-15372 → 2.3.80-15375

package/engine/orm/apiRoute.js

@@ -19,6 +19,9 @@
  *   TOrmMethod/"orm"  -> {"data":[{...}],"success":"OK"}
  *   failure           -> {"error":"..."} , which db/ds.js's dsReq already looks for.
  */
+import { UNSAFE_SQL_CODE } from "./sqlGuard.js";
+import { INCOMPLETE_COLLECTION_CODE } from "./completeness.js";
+import { isGraphRead, assertGraphRequest, attachCollections, GRAPH_READ_KEY_REQUIRED_CODE } from "./graphRead.js";
 import { json2List, addTableNameToArray, lookupToSql, lookupTotalToSql, resolveDbIndex, buildWriteSql } from "./index.js";
 import { nextGeneratorValue } from "./dialect.js";
 import { createReaders } from "./changeInference.js";
@@ -364,9 +367,33 @@ const lookupResponse = async (param, exec, dbIndex, isTotal, tenantIds) => {
 /* `param.version` selects the persistence semantics (Doc 3 §6.1). The envelope already reached here
    whole — `parseDataSnapRequest` passes `param` through untouched — so carrying it needed no
    wire-format change, only for this function to stop discarding the key. */
+/*
+ * Doc 2 section 5.2 item 5 - a delete the database refuses because another row still REFERENCES the record
+ * (a shared relationship, e.g. a category using a template) is a caller-visible state, not a server fault:
+ * answered 409 IN_USE naming the referencing table. Only for a DELETE - an FK violation on a save means a
+ * bad reference, which is a different thing. PostgreSQL reports the referencing table as error.table.
+ */
+export const IN_USE_CODE = "IN_USE";
+const asInUse = (error, param) => {
+	if (error?.code !== "23503" || String(param?.method ?? "").toLowerCase() !== "delete") return error;
+	/* ⚠️ The transaction runner (dialect.js decorate) wraps the driver error to add the failing statement
+	   and copies only `code`, so the table survives on `cause` - or only in PostgreSQL's detail text. */
+	const original = error.cause ?? {};
+	const table =
+		error.table ??
+		original.table ??
+		/referenced from table "([^"]+)"/.exec(String(original.detail ?? error.detail ?? ""))?.[1];
+	const by = table ? ` by ${table}` : "";
+	return Object.assign(new Error(`This record cannot be deleted: it is still used${by}.`), { code: IN_USE_CODE });
+};
+
 const ormResponse = async (param, exec, execStatements, dbIndex, principal) => {
 	const tenantIds = principal?.tenantIds;
 	const readers = createReaders(exec, dbIndex, tenantIds);
+	/* Doc 2 section 5.2 item 1 - a v2 get that names collections loads the whole graph. Validated
+	   BEFORE anything is read; see graphRead.js for why the collections use `readers.readRows`. */
+	const graph = isGraphRead(param);
+	if (graph) assertGraphRequest(param.object, dbIndex);
 	const sql = await buildWriteSql({
 		method: param.method,
 		object: param.object,
@@ -381,7 +408,12 @@ const ormResponse = async (param, exec, execStatements, dbIndex, principal) => {
 		tenantIds,
 		...readers,
 	});
-	const rows = await runStatements(exec, execStatements, sql, dbIndex);
+	const rows = await runStatements(exec, execStatements, sql, dbIndex).catch((error) => {
+		throw asInUse(error, param);
+	});
+	if (graph) await attachCollections({ object: param.object, masterRows: rows, readRows: readers.readRows, dbIndex });
+	/* Shallow on purpose: the master keeps the key casing the client has always seen, and the rows
+	   inside a collection keep PostgreSQL columns - the shape the save takes straight back. */
 	const body = { data: upperCaseKeys(rows), success: "OK" };
 
 	/*
@@ -829,6 +861,9 @@ export const routeApiRequest = async (
 		/* Doc 3 §6.7 — a concurrency conflict is not a server fault, and must be distinguishable from
 		   one WITHOUT parsing a message, so an application can offer reload/retry instead of showing a
 		   generic failure. */
+		if (error?.code === IN_USE_CODE) {
+			return { status: 409, body: { error: error.message, code: IN_USE_CODE } };
+		}
 		if (error?.code === CONFLICT_CODE) {
 			return { status: 409, body: { error: error.message, code: CONFLICT_CODE } };
 		}
@@ -844,6 +879,16 @@ export const routeApiRequest = async (
 		if (error?.code === AMBIGUOUS_TENANT_CODE) {
 			return { status: 400, body: { error: error.message, code: AMBIGUOUS_TENANT_CODE } };
 		}
+		/* Request input the ORM will not put into SQL text (sqlGuard.js) - a caller error, named. */
+		if (error?.code === GRAPH_READ_KEY_REQUIRED_CODE) {
+			return { status: 400, body: { error: error.message, code: GRAPH_READ_KEY_REQUIRED_CODE } };
+		}
+		if (error?.code === INCOMPLETE_COLLECTION_CODE) {
+			return { status: 400, body: { error: error.message, code: INCOMPLETE_COLLECTION_CODE } };
+		}
+		if (error?.code === UNSAFE_SQL_CODE) {
+			return { status: 400, body: { error: error.message, code: UNSAFE_SQL_CODE } };
+		}
 		if (error?.code === SHARED_RELATIONSHIP_CODE) {
 			return { status: 400, body: { error: error.message, code: SHARED_RELATIONSHIP_CODE } };
 		}

package/engine/orm/changeInference.js

@@ -20,11 +20,34 @@
  * enforcing completeness is the APPLICATION's responsibility — the ORM cannot distinguish a partial
  * load from a legitimate delete-all-but-these, and deliberately does not try.
  */
-import { hasRealKey, scalarEntries, detailEntries, foreignKeyColumn, renderValue } from "./masterDetail.js";
+import { hasRealKey, scalarEntries, detailEntries, renderValue } from "./masterDetail.js";
 import { PRIMARY_KEY_COLUMN } from "./crudQuery.js";
 import { projectRowVersion } from "./concurrency.js";
-import { assertOwnedCollection, tenantFilter } from "./entityConfig.js";
+import { assertOwnedCollection, tenantFilter, softDeleteFilter, foreignKeyFor } from "./entityConfig.js";
 import { runTrusted } from "./tenantContext.js";
+import { assertIdentifier } from "./sqlGuard.js";
+
+/*
+ * `col [ASC|DESC], ...` checked as identifiers and rendered, always followed by `id` - rows with
+ * equal or null sort values would otherwise come back in heap order, which an UPDATE changes on
+ * PostgreSQL. tests/orm-v2-order-by.test.js.
+ */
+const renderOrderBy = (orderBy) => {
+	const terms = String(orderBy ?? "")
+		.split(",")
+		.map((term) => term.trim())
+		.filter(Boolean)
+		.map((term) => {
+			const [column, direction, ...rest] = term.split(/\s+/);
+			const dir = String(direction ?? "").toUpperCase();
+			if (rest.length > 0 || (direction !== undefined && dir !== "ASC" && dir !== "DESC")) {
+				assertIdentifier(term, "orderBy term");
+			}
+			assertIdentifier(column, "orderBy column");
+			return direction === undefined ? column : `${column} ${dir}`;
+		});
+	return ` ORDER BY ${[...terms, PRIMARY_KEY_COLUMN].join(", ")}`;
+};
 
 /*
  * The two reads the inference needs, defined ONCE and shared by both entrances (apiRoute.js and
@@ -41,16 +64,29 @@ export const createReaders = (exec, dbIndex, tenantIds) => {
 	   dangerous half of the filter, not the cosmetic one. Unfiltered, another tenant's rows are drawn
 	   into the comparison; filtered here while the write stays unfiltered, rows the caller cannot see
 	   are inferred `Deleted` and destroyed. Both halves move together or neither does. */
+	const hideDeleted = (table) => {
+		const predicate = softDeleteFilter(table, dbIndex);
+		return predicate ? ` AND ${predicate}` : "";
+	};
 	const scope = (table) => {
 		const predicate = tenantFilter(table, dbIndex, tenantIds);
 		return predicate ? ` AND ${predicate}` : "";
 	};
 	return {
-	readRows: async (table, fkColumn, parentKeyValue) =>
-		(await exec(
-			`SELECT * FROM ${table} WHERE ${fkColumn} = ${renderValue(parentKeyValue)}${scope(table)}`,
-			dbIndex,
-		)) ?? [],
+	/* ⚠️ Soft-deleted rows are EXCLUDED here, and the reason is not tidiness. Deletion is inferred from
+	   absence, and the display read already hides soft-deleted rows (Doc 3 section 6.6 rule 2), so no
+	   client ever sends them back. Included here, every one of them was "missing", therefore Deleted,
+	   therefore stamped again on EVERY save - overwriting who deleted it and when. The load and the
+	   comparison must see the same rows. tests/orm-soft-delete-resave.test.js. */
+	readRows: async (table, fkColumn, parentKeyValue, orderBy = null) => {
+		const order = renderOrderBy(orderBy);
+		return (
+			(await exec(
+				`SELECT * FROM ${table} WHERE ${fkColumn} = ${renderValue(parentKeyValue)}${scope(table)}${hideDeleted(table)}${order}`,
+				dbIndex,
+			)) ?? []
+		);
+	},
 	/* ⚠️ `xmin` is named explicitly because it is a SYSTEM column and `SELECT *` does not include it.
 	   Without it the §6.7 comparison reads `undefined` on every save and silently never conflicts —
 	   a security-blanket failure that looks exactly like the feature working. */
@@ -219,7 +255,8 @@ const planNested = async ({ parentTable, parentRow, parentPlan, readRows, dbInde
 		const collection = await planCollection({
 			table,
 			rows,
-			fkColumn: foreignKeyColumn(parentTable),
+			/* Declared first, the convention otherwise - the SAME resolver the graph read uses. */
+			fkColumn: foreignKeyFor(parentTable, table, dbIndex),
 			parentKeyValue,
 			readRows,
 		});
@@ -231,6 +268,9 @@ const planNested = async ({ parentTable, parentRow, parentPlan, readRows, dbInde
 				parentRow: rows[index],
 				parentPlan: rowPlan,
 				readRows,
+				/* ⚠️ Passed down. Dropped here, every level below the first looked up an unprimed index,
+				   so a SHARED subdetail was never refused. tests/orm-v2-foreign-key.test.js. */
+				dbIndex,
 			});
 		}
 	}

package/engine/orm/completeness.js

@@ -0,0 +1,62 @@
+/*
+ * Doc 2 section 5.5, ruling 5 (2026-09-26) - an INCOMPLETE detail collection is rejected, never read as
+ * deletions.
+ *
+ * Deletion is inferred from a row's absence (Doc 3 section 6.2), and the ORM cannot tell a partially
+ * loaded collection from "delete all but these". Doc 3 made completeness the application's
+ * responsibility; the application meets it by MARKING what it loaded partially, on the parent row:
+ *
+ *     { st_order: { id: 7, _incomplete: ["st_order_line"], st_order_line: [ ...one page... ] } }
+ *
+ * and this refuses a save that carries a marked collection. A marked collection that is ABSENT is fine
+ * - absent already means "leave alone". tests/orm-incomplete-collection.test.js.
+ */
+export const INCOMPLETE_KEY = "_incomplete";
+export const INCOMPLETE_COLLECTION_CODE = "INCOMPLETE_COLLECTION";
+
+const isIncompleteKey = (key) => String(key).toLowerCase() === INCOMPLETE_KEY;
+
+const refuse = (message) => Object.assign(new Error(message), { code: INCOMPLETE_COLLECTION_CODE });
+
+/* An unreadable mark refuses: it is not proof that the collections are complete. */
+const markedTables = (mark) => {
+	if (!Array.isArray(mark) || !mark.every((t) => typeof t === "string" && t.trim() !== "")) {
+		throw refuse(`${INCOMPLETE_KEY} must be a list of detail table names`);
+	}
+	return mark.map((t) => t.trim().toLowerCase());
+};
+
+const checkRow = (row) => {
+	const out = {};
+	let marked = [];
+	for (const [key, value] of Object.entries(row)) {
+		if (isIncompleteKey(key)) {
+			marked = markedTables(value);
+			continue;
+		}
+		out[key] = check(value);
+	}
+	for (const table of marked) {
+		const present = Object.keys(row).find((key) => key.toLowerCase() === table && Array.isArray(row[key]));
+		if (present) {
+			throw refuse(
+				`${present} was loaded incompletely and cannot be saved: its missing rows would be read as deletions. ` +
+					"Load the whole collection, or leave it out of the save.",
+			);
+		}
+	}
+	return out;
+};
+
+const check = (value) => {
+	if (Array.isArray(value)) return value.map(check);
+	if (value === null || typeof value !== "object" || value instanceof Date) return value;
+	return checkRow(value);
+};
+
+/*
+ * Throw if any row, at any depth, marks a collection it also carries; otherwise return a copy with every
+ * mark removed. ⚠️ The strip is not tidiness: masterDetail.js scalarEntries turns every non-detail key
+ * into a column, so an unstripped mark would become `INSERT INTO ... (_incomplete)`.
+ */
+export const assertCompleteCollections = (object) => check(object);

package/engine/orm/configVersion.js

@@ -0,0 +1,28 @@
+/*
+ * Doc 2 section 2 - what a template config's `version` means to the ORM.
+ *
+ * Absent means 1 (section 2.1 rule 4). 2 OR HIGHER selects the new behaviour (rule 2) - today that is
+ * change inference in place of delete-and-replace (Doc 3 section 6.1).
+ *
+ * WARNING THE CLIENT HAS A TWIN OF THIS (client/src/app/services/config-version.ts) and the two must
+ * never disagree - a screen would render as v2 and persist as v1, each side correct on its own. Both
+ * are held to shared/domain/config-version-cases.json; change the rule there, and both sides fail
+ * until both agree.
+ *
+ * WARNING THIS IS NOT metadata.version. That key is a required semver identifying the domain package
+ * ("0.1.0"), and it reads here as undeclared, not as 0.1.
+ */
+
+/* Anything that is not a finite number, or a string holding one, was never a version. */
+export const configVersion = (value) => {
+	if (typeof value === "number") return Number.isFinite(value) ? value : 1;
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		if (trimmed === "") return 1;
+		const parsed = Number(trimmed);
+		return Number.isFinite(parsed) ? parsed : 1;
+	}
+	return 1;
+};
+
+export const isConfigV2 = (value) => configVersion(value) >= 2;

package/engine/orm/crudQuery.js

@@ -5,6 +5,7 @@
  * string becomes a quoted literal, a JSON number stays bare, JSON null becomes `null`. Callers
  * quote their own values (the same contract db/ds.js already documents for filter values).
  */
+import { assertQualifiedIdentifier, assertKeyLiteral, assertSqlFragment, assertPayloadIdentifiers } from "./sqlGuard.js";
 import { buildSequenceNextValue, renderTimestamp } from "./dialect.js";
 import { buildOrderClause } from "./listQuery.js";
 import { projectRowVersion } from "./concurrency.js";
@@ -76,8 +77,9 @@ const renderValue = (value, isBoolean = false) => {
 /* `get` and `delete` interpolate the value VERBATIM — the caller quotes its own, which is the
    contract orm.pas set and db/ds.js documents (`cuti.id=-1`, unquoted). A Date has no verbatim
    form that PostgreSQL accepts, so it alone is rendered; everything else is untouched. */
+/* Verbatim by contract (a GUID arrives pre-quoted) - but only ever ONE literal. sqlGuard.js. */
 const renderKeyValue = (value) =>
-	value instanceof Date ? `'${renderTimestamp(value)}'` : `${value}`;
+	value instanceof Date ? `'${renderTimestamp(value)}'` : `${assertKeyLiteral(value, "key value")}`;
 
 const entriesOf = (row) => Object.entries(row ?? {});
 
@@ -123,13 +125,16 @@ const buildDelete = (tableName, row, dbIndex, deletedBy, tenantIds) => {
 
 /* A row whose primary key is null is unambiguously new -> a plain INSERT with the key omitted, so
    the sequence/GUID default supplies it. Otherwise an upsert on the primary key. */
-const buildUpsert = (tableName, row, dbIndex, tenantIds, tenantContext) => {
+const buildUpsert = (tableName, row, dbIndex, tenantIds, tenantContext, returningKey = false) => {
 	/* Doc 3 §11 — resolve the tenant ONCE for the whole statement: the INSERT branches stamp it and
 	   the UPDATE branch is constrained by it. Null when there is nothing to enforce, in which case
 	   every branch below emits exactly what it emitted before tenancy existed. */
 	const rawEntries = entriesOf(row);
 	const primaryKeyRaw = rawEntries.find(([column]) => column.toLowerCase() === PRIMARY_KEY_COLUMN);
-	const isNew = Boolean(primaryKeyRaw) && (primaryKeyRaw[1] === null || primaryKeyRaw[1] === undefined);
+	/* ⚠️ A row with NO key column is new too - there is nothing to upsert on. It used to fall into the
+	   upsert branch and crash on the missing key (a 500); a v2 master saved new with no collections sends
+	   exactly that. tests/orm-keyless-insert.test.js. */
+	const isNew = !primaryKeyRaw || primaryKeyRaw[1] === null || primaryKeyRaw[1] === undefined;
 	/* ⚠️ `isNew` decides whether an absent tenant is fatal. A keyed row is an UPDATE as far as this
 	   statement is concerned; the case where it turns out NOT to exist yet is caught by the async
 	   authority check in index.js, which is the only layer that can know. */
@@ -154,9 +159,11 @@ const buildUpsert = (tableName, row, dbIndex, tenantIds, tenantContext) => {
 
 	if (isNew) {
 		const insertable = entries.filter(([column]) => column.toLowerCase() !== PRIMARY_KEY_COLUMN);
+		/* v2 hands a new master its key back, as the master-detail path does - without it the client reloads
+		   the record as NEW and a second save inserts a duplicate. tests/orm-keyless-insert.test.js. */
 		return `INSERT INTO ${tableName} (${insertable.map(([c]) => c).join(", ")}) VALUES (${insertable
 			.map(([c, v]) => renderValue(v, isBool(c)))
-			.join(", ")})`;
+			.join(", ")})${returningKey ? ` RETURNING ${PRIMARY_KEY_COLUMN}` : ""}`;
 	}
 
 	/* UPDATE first, INSERT only if it matched nothing.
@@ -210,7 +217,9 @@ const buildUpsert = (tableName, row, dbIndex, tenantIds, tenantContext) => {
    keep working. TestORM.pas TestPutArray. */
 export const STATEMENT_SEPARATOR = ";eof ";
 
-export const buildCrudSql = (method, object, dbIndex, deletedBy, tenantIds, tenantContext) => {
+export const buildCrudSql = (method, object, dbIndex, deletedBy, tenantIds, tenantContext, { returningKey = false } = {}) => {
+	/* Every table and column NAME the caller supplied, before any of them reaches SQL text. */
+	assertPayloadIdentifiers(object);
 	const [tableName, payload] = Object.entries(object ?? {})[0] ?? [];
 	if (!tableName) {
 		return "";
@@ -239,7 +248,7 @@ export const buildCrudSql = (method, object, dbIndex, deletedBy, tenantIds, tena
 			.map((row) => buildUpsert(tableName, row, dbIndex, tenantIds, tenantContext))
 			.join(STATEMENT_SEPARATOR);
 	}
-	return buildUpsert(tableName, payload, dbIndex, tenantIds, tenantContext);
+	return buildUpsert(tableName, payload, dbIndex, tenantIds, tenantContext, returningKey);
 };
 
 /* orm.pas:1695-1745 (lookupToSQLCustom). Both forms honour `lookup.filter`; only the page form
@@ -251,7 +260,9 @@ const buildLookupWhere = (lookup) => {
 	if (filter === undefined || filter === null || String(filter) === "null" || String(filter) === "") {
 		return "";
 	}
-	return ` where ${filter}`;
+	/* A raw where string by contract; refused only for structure that would escape the parentheses
+	   the platform wraps it in (sqlGuard.assertSqlFragment). */
+	return ` where ${assertSqlFragment(filter, "lookup filter")}`;
 };
 
 /*
@@ -272,6 +283,7 @@ const lookupWhereWithSoftDelete = (lookup, dbIndex, tenantIds) => {
 };
 
 export const buildLookupSql = (lookup, dbIndex, tenantIds) => {
+	assertLookupShape(lookup);
 	const order = Array.isArray(lookup?.order) && lookup.order.length > 0
 		? buildOrderClause(lookup.order).replace(/^ ORDER BY /, " order by ")
 		: " order by 2";
@@ -282,7 +294,16 @@ export const buildLookupSql = (lookup, dbIndex, tenantIds) => {
 	);
 };
 
-export const buildLookupTotalSql = (lookup, dbIndex, tenantIds) =>
-	`select count(*) total from ${lookup.table}${lookupWhereWithSoftDelete(lookup, dbIndex, tenantIds)}`;
+/* key and display may be expressions (`name || ' - ' || code`); the table may not. */
+const assertLookupShape = (lookup) => {
+	assertQualifiedIdentifier(lookup?.table, "lookup table");
+	assertSqlFragment(lookup?.key, "lookup key");
+	assertSqlFragment(lookup?.display, "lookup display");
+};
+
+export const buildLookupTotalSql = (lookup, dbIndex, tenantIds) => {
+	assertLookupShape(lookup);
+	return `select count(*) total from ${lookup.table}${lookupWhereWithSoftDelete(lookup, dbIndex, tenantIds)}`;
+};
 
 export const buildGenIdSql = (sequenceName) => buildSequenceNextValue(sequenceName);

package/engine/orm/entityConfig.js

@@ -125,6 +125,111 @@ export const buildRelationshipMap = (parsedDomainConfigs = []) => {
 	return map;
 };
 
+/*
+ * The FK a one-to-many relationship DECLARES, keyed parentTable|childTable.
+ *
+ * ⚠️ Entity keys are resolved to their TABLES here. The ownership map above keys on the raw names,
+ * which works only because real configs happen to name entities after their tables.
+ */
+export const buildForeignKeyMap = (parsedDomainConfigs = []) => {
+	const map = new Map();
+	for (const parsed of parsedDomainConfigs) {
+		const entities = parsed?.model?.entities ?? {};
+		const relationships = parsed?.model?.relationships;
+		if (!relationships || typeof relationships !== "object") continue;
+		const tableOf = (name) => String(entities?.[name]?.table ?? name ?? "").trim().toLowerCase();
+		for (const relationship of Object.values(relationships)) {
+			const foreignKey = String(relationship?.foreignKey ?? "").trim();
+			const from = tableOf(relationship?.from);
+			const to = tableOf(relationship?.to);
+			if (!foreignKey || !from || !to) continue;
+			map.set(`${from}|${to}`, foreignKey);
+		}
+	}
+	return map;
+};
+
+/*
+ * The ORDER a one-to-many relationship DECLARES for its rows (`orderBy: 'sequence_no'`), keyed
+ * parentTable|childTable like the FK map and resolved to tables the same way. Doc 2 section 5: a
+ * v2 screen shows a collection in the order the graph read returns it, and nothing else orders it.
+ */
+export const buildOrderByMap = (parsedDomainConfigs = []) => {
+	const map = new Map();
+	for (const parsed of parsedDomainConfigs) {
+		const entities = parsed?.model?.entities ?? {};
+		const relationships = parsed?.model?.relationships;
+		if (!relationships || typeof relationships !== "object") continue;
+		const tableOf = (name) => String(entities?.[name]?.table ?? name ?? "").trim().toLowerCase();
+		for (const relationship of Object.values(relationships)) {
+			const orderBy = String(relationship?.orderBy ?? "").trim();
+			const from = tableOf(relationship?.from);
+			const to = tableOf(relationship?.to);
+			if (!orderBy || !from || !to) continue;
+			map.set(`${from}|${to}`, orderBy);
+		}
+	}
+	return map;
+};
+
+/* The declared order of a parent's collection, or null. Unchecked here - readRows checks it as
+   identifiers before it reaches SQL (sqlGuard.js). */
+/*
+ * Doc 2 section 5.2 item 5 - the OWNED children of each table: one-to-many relationships declared
+ * ownership: parent, keyed by parent TABLE, each child resolved to its table, in declaration order.
+ * A v2 delete cascades through exactly these (masterDetail.buildGraphDeleteSql) - never through a
+ * shared or independent relationship, whose rows only REFERENCE the parent.
+ */
+export const buildOwnedChildrenMap = (parsedDomainConfigs = []) => {
+	const map = new Map();
+	for (const parsed of parsedDomainConfigs) {
+		const entities = parsed?.model?.entities ?? {};
+		const relationships = parsed?.model?.relationships;
+		if (!relationships || typeof relationships !== "object") continue;
+		const tableOf = (name) => String(entities?.[name]?.table ?? name ?? "").trim().toLowerCase();
+		for (const relationship of Object.values(relationships)) {
+			if (String(relationship?.type ?? "").trim().toLowerCase() !== "one-to-many") continue;
+			if (String(relationship?.ownership ?? "").trim().toLowerCase() !== "parent") continue;
+			const from = tableOf(relationship?.from);
+			const to = tableOf(relationship?.to);
+			if (!from || !to) continue;
+			const children = map.get(from) ?? [];
+			if (!children.includes(to)) children.push(to);
+			map.set(from, children);
+		}
+	}
+	return map;
+};
+
+/* A table's owned children with the FK each is found by - the SAME foreignKeyFor the graph load and
+   save use, so a delete can never correlate through a column the save does not. */
+export const ownedChildrenOf = (parentTable, dbIndex) =>
+	(byDbIndex.get(Number(dbIndex))?.ownedChildren?.get(String(parentTable ?? "").trim().toLowerCase()) ?? []).map(
+		(table) => ({ table, foreignKey: foreignKeyFor(parentTable, table, dbIndex) }),
+	);
+
+export const orderByFor = (parentTable, childTable, dbIndex) =>
+	byDbIndex
+		.get(Number(dbIndex))
+		?.orderBy?.get(
+			`${String(parentTable ?? "").trim().toLowerCase()}|${String(childTable ?? "").trim().toLowerCase()}`,
+		) ?? null;
+
+/*
+ * ⚠️⚠️ THE FK A v2 GRAPH USES - load (graphRead.js) AND save (changeInference.js), through this one
+ * function so the two can never disagree. Declared first; the orm.pas `<parent>_ID` convention only
+ * when nothing is declared. It must be declared-first because the convention cannot always hold:
+ * Supertail's rel_item_add_info_options uses st_add_info_tmpl_det_id, since the conventional name is
+ * one character over Firebird 2.5's 31-character limit. v1 (Delphi parity) keeps the convention.
+ * The convention is spelled exactly as masterDetail.foreignKeyColumn spells it (fenced in the test).
+ */
+export const foreignKeyFor = (parentTable, childTable, dbIndex) =>
+	byDbIndex
+		.get(Number(dbIndex))
+		?.foreignKeys?.get(
+			`${String(parentTable ?? "").trim().toLowerCase()}|${String(childTable ?? "").trim().toLowerCase()}`,
+		) ?? `${parentTable}_ID`;
+
 /*
  * Doc 3 §11 — which tables are scoped by a tenant, and by which column.
  *
@@ -238,9 +343,12 @@ export const primeEntityConfig = async ({ dbIndex, loadDomainConfigs }) => {
 		const configs = await loadDomainConfigs();
 		const map = buildEntityMap(configs);
 		const relationships = buildRelationshipMap(configs);
+		const foreignKeys = buildForeignKeyMap(configs);
+		const orderBy = buildOrderByMap(configs);
+		const ownedChildren = buildOwnedChildrenMap(configs);
 		const tenancy = buildTenancyMap(configs);
 		const booleanColumns = buildBooleanColumnMap(configs);
-		byDbIndex.set(Number(dbIndex), { entities: map, relationships, tenancy, booleanColumns });
+		byDbIndex.set(Number(dbIndex), { entities: map, relationships, foreignKeys, orderBy, ownedChildren, tenancy, booleanColumns });
 
 		/* ⚠️ Report the COUNT, not just success. "Everything is hard" is the correct answer when no
 		   entity declares `soft`, and it is also exactly what a silently empty map returns — the two

package/engine/orm/graphRead.js

@@ -0,0 +1,94 @@
+/*
+ * Doc 2 section 5.2 item 1 - load a master WITH its details and subdetails, in one request.
+ *
+ * The request is the shape the save already takes, collections left empty to mean "include":
+ *
+ *   get, version 2, { st_customer: { id: "'{C1}'", name: "", st_customer_identity: [] } }
+ *
+ * and a subdetail is named inside the collection's first row. The master is read by the ordinary
+ * `get` (so its projection, soft-delete and tenant scoping and its section 6.7 concurrency token are
+ * exactly what they always were); only the collections are new.
+ *
+ * ⚠️⚠️ EVERY COLLECTION IS READ THROUGH THE SAVE'S OWN COMPARISON READER (changeInference
+ * createReaders.readRows) - passed in, never re-implemented. Deletion on save is inferred from
+ * absence (Doc 3 section 6.2), so if the load and the comparison ever see different rows, the next
+ * save deletes the difference silently. Sharing the reader makes them the same set by construction:
+ * tenant scope, soft delete, and anything added to that reader later.
+ *
+ * ⚠️ The FK is found the way the save finds it - entityConfig.foreignKeyFor, the declared foreignKey
+ * first and the orm.pas `<parent>_ID` convention otherwise. A load that followed a different rule
+ * from the save would be the same drift by another route.
+ */
+import { detailEntries } from "./masterDetail.js";
+import { PRIMARY_KEY_COLUMN } from "./crudQuery.js";
+import { assertOwnedCollection, foreignKeyFor, orderByFor } from "./entityConfig.js";
+import { isConfigV2 } from "./configVersion.js";
+
+export const GRAPH_READ_KEY_REQUIRED_CODE = "GRAPH_READ_KEY_REQUIRED";
+
+/* A get at version 2 that names at least one collection, and is not the Delphi `getd` (`detail` key). */
+export const isGraphRead = ({ method, version, object }) =>
+	String(method ?? "").toLowerCase() === "get" &&
+	isConfigV2(version) &&
+	object?.detail === undefined &&
+	Object.entries(object ?? {}).some(([, payload]) =>
+		(Array.isArray(payload) ? payload : [payload]).some((row) => detailEntries(row).length > 0),
+	);
+
+const keyOf = (row) => {
+	const column = Object.keys(row ?? {}).find((k) => k.toLowerCase() === PRIMARY_KEY_COLUMN);
+	return column === undefined ? undefined : row[column];
+};
+
+const templateOf = (rows) =>
+	Array.isArray(rows) && rows[0] && typeof rows[0] === "object" ? rows[0] : {};
+
+/*
+ * Refuse the WHOLE shape before anything is read. The save will not manage a shared collection
+ * (Doc 3 section 6.3); a load that handed one out would give a screen a graph it can never save.
+ */
+const assertShape = (parentTable, templateRow, dbIndex) => {
+	for (const [table, rows] of detailEntries(templateRow)) {
+		assertOwnedCollection(parentTable, table, dbIndex);
+		assertShape(table, templateOf(rows), dbIndex);
+	}
+};
+
+/*
+ * A graph read is the load of ONE record. Without a key the master read is every row, and each
+ * collection would multiply that - so it is refused by name instead of issuing N+1 reads.
+ */
+export const assertGraphRequest = (object, dbIndex) => {
+	for (const [table, payload] of Object.entries(object ?? {})) {
+		if (table === "detail") continue;
+		for (const row of Array.isArray(payload) ? payload : [payload]) {
+			const key = keyOf(row);
+			if (key === undefined || key === null || String(key).trim() === "") {
+				throw Object.assign(
+					new Error(`a graph read of ${table} needs its key - it loads one record, with its collections`),
+					{ code: GRAPH_READ_KEY_REQUIRED_CODE },
+				);
+			}
+			assertShape(table, row, dbIndex);
+		}
+	}
+};
+
+const attach = async (parentTable, dbRow, templateRow, readRows, dbIndex) => {
+	for (const [table, templateRows] of detailEntries(templateRow)) {
+		const key = keyOf(dbRow);
+		const rows =
+			key === undefined || key === null ? [] : (await readRows(table, foreignKeyFor(parentTable, table, dbIndex), key, orderByFor(parentTable, table, dbIndex))) ?? [];
+		for (const row of rows) await attach(table, row, templateOf(templateRows), readRows, dbIndex);
+		dbRow[table] = rows;
+	}
+	return dbRow;
+};
+
+/* `masterRows` are what the ordinary get returned for the master table. Mutated and returned. */
+export const attachCollections = async ({ object, masterRows, readRows, dbIndex }) => {
+	const [masterTable, payload] = Object.entries(object ?? {}).find(([key]) => key !== "detail") ?? [];
+	const template = Array.isArray(payload) ? templateOf(payload) : payload ?? {};
+	for (const row of masterRows ?? []) await attach(masterTable, row, template, readRows, dbIndex);
+	return masterRows;
+};

package/engine/orm/index.js

@@ -20,9 +20,11 @@ import {
 	buildGenIdSql,
 	PRIMARY_KEY_COLUMN,
 } from "./crudQuery.js";
-import { buildMasterDetailChangeSql, hasDetailCollection } from "./masterDetail.js";
+import { buildMasterDetailChangeSql, buildGraphDeleteSql, hasDetailCollection } from "./masterDetail.js";
 import { inferChanges } from "./changeInference.js";
+import { isConfigV2 } from "./configVersion.js";
 import { checkRowVersion } from "./concurrency.js";
+import { assertCompleteCollections } from "./completeness.js";
 import { tenantColumnFor, resolveWriteTenant, CROSS_TENANT_CODE } from "./entityConfig.js";
 
 const parseRequest = (param) => (typeof param === "string" ? JSON.parse(param) : (param ?? {}));
@@ -208,15 +210,30 @@ export const buildWriteSql = async ({
 	   "conflict" would also confirm to the caller that a row it may not see exists and has changed.
 	   This is also the only place a cross-tenant write gets a NAMED refusal: the SQL constraints
 	   downstream make such a write do nothing, which is safe but silent. */
-	const tenantContext = await assertTenantAuthority({ object, dbIndex, tenantIds, readTenant });
+	/* Doc 2 section 5.5 ruling 5 - FIRST, before anything is read: a collection marked incomplete would
+	   otherwise have its missing rows inferred as Deleted. Returns the payload with every mark stripped. */
+	const complete = assertCompleteCollections(object);
+
+	const tenantContext = await assertTenantAuthority({ object: complete, dbIndex, tenantIds, readTenant });
 
 	/* Doc 3 §6.7 — reject a save whose data has moved since it was loaded, BEFORE any SQL is built,
 	   so a conflict writes nothing. This sits above the version split on purpose: the token is an
 	   opt-in property of the payload, not of the persistence semantics, so a v1 save made from a
 	   freshly-loaded form is protected too. A payload with no token reads nothing and is unchanged. */
-	const checked = await checkRowVersion({ object, readMaster });
+	const checked = await checkRowVersion({ object: complete, readMaster });
+
+	/* ⚠️⚠️ `put` ONLY - change inference is the SAVE semantic. This used to admit every method except
+	   `delete`, so a `get` at version 2 carrying an empty collection was planned as a save: blank master
+	   fields became an UPDATE and the empty array meant every detail row was Deleted. A read that
+	   deletes. Unreachable only until a client sent `version` on a get, which Doc 2 section 5 does.
+	   tests/orm-graph-read.test.js. */
+	/* Doc 2 section 5.2 item 5 - a v2 delete cascades by CONFIG (ownership: parent, declared FKs), not by
+	   what the client names. v1 delete stays one row. tests/orm-v2-delete.test.js. */
+	if (isConfigV2(version) && String(method ?? "").toLowerCase() === "delete") {
+		return buildGraphDeleteSql(checked, dbIndex, deletedBy, tenantIds);
+	}
 
-	const wantsInference = Number(version) >= 2 && String(method ?? "").toLowerCase() !== "delete";
+	const wantsInference = isConfigV2(version) && String(method ?? "").toLowerCase() === "put";
 	if (wantsInference && hasDetailCollection(checked)) {
 		return buildMasterDetailChangeSql(
 			await inferChanges({ object: checked, readRows, readMaster, dbIndex }),
@@ -229,7 +246,7 @@ export const buildWriteSql = async ({
 	/* ⚠️ `tenantIds` reaches buildCrudSql here as well as through jsonToSql. This is the FOURTH place
 	   today that quietly dropped a parameter it never declared; the `get` path runs through here, so
 	   omitting it left reads unfiltered while every unit test that called buildCrudSql directly passed. */
-	return buildCrudSql(method, checked, dbIndex, deletedBy, tenantIds, tenantContext);
+	return buildCrudSql(method, checked, dbIndex, deletedBy, tenantIds, tenantContext, { returningKey: isConfigV2(version) });
 };
 
 /* Delphi: TOrm.lookupToSql / lookupTotalToSql (Doc 3 §5 item 1). */

package/engine/orm/listQuery.js

@@ -3,6 +3,7 @@
  * orm.pas jsonToListSQL. Produces both the page query and the record-count query, matching the
  * Delphi TListRecord (QuerySQL / recordsTotalSQL).
  */
+import { assertSqlFragment, assertSearchLiteral, normaliseFilterOperator } from "./sqlGuard.js";
 import { buildPagingClause } from "./dialect.js";
 import { isPostgresIndex } from "../domain/dialect.js";
 import { softDeleteFilter, tenantFilter, isBooleanColumn } from "./entityConfig.js";
@@ -176,9 +177,9 @@ const buildCondition = (filter, registry, dbIndex) => {
 	}
 
 	const junction = String(filter?.junction ?? "");
-	const rawColumn = String(filter?.column ?? "");
+	const rawColumn = String(assertSqlFragment(filter?.column ?? "", "filter column"));
 	const column = rawColumn === "" || isRawExpression(rawColumn) ? rawColumn : registry.resolve(rawColumn) ?? rawColumn;
-	const operator = String(filter?.operator ?? "");
+	const operator = String(normaliseFilterOperator(filter?.operator ?? ""));
 
 	const rendered = `${junction ? ` ${junction}` : ""} ${column} ${operator}`;
 
@@ -192,13 +193,13 @@ const buildCondition = (filter, registry, dbIndex) => {
 	const lowered = operator.toLowerCase().replace(/\s+/g, " ").trim();
 	if ((lowered === CONTAINING || lowered === NOT_CONTAINING) && isPostgresIndex(dbIndex)) {
 		const rendered2 = `${junction ? ` ${junction}` : ""} ${column} ${lowered === NOT_CONTAINING ? "NOT ILIKE" : "ILIKE"}`;
-		return `${rendered2} ${toContainingPattern(filter.value1)}`;
+		return `${rendered2} ${toContainingPattern(assertSearchLiteral(filter.value1, "containing value"))}`;
 	}
 
 	if (operator.toLowerCase() === "between") {
-		return `${rendered} ${filter.value1} AND ${filter.value2}`;
+		return `${rendered} ${assertSqlFragment(filter.value1, "value1")} AND ${assertSqlFragment(filter.value2, "value2")}`;
 	}
-	return `${rendered} ${coerceBooleanFilterValue(rawColumn, filter.value1, dbIndex)}`;
+	return `${rendered} ${coerceBooleanFilterValue(rawColumn, assertSqlFragment(filter.value1, "value1"), dbIndex)}`;
 };
 
 const buildWhereClause = (filters, registry, dbIndex) => {
@@ -215,7 +216,7 @@ export const buildOrderClause = (orders) => {
 	const parts = (Array.isArray(orders) ? orders : []).map((order) => {
 		const dir = String(order?.dir ?? "").toLowerCase();
 		const direction = dir === "asc" || dir === "desc" ? ` ${dir.toUpperCase()}` : "";
-		return `${order?.column ?? ""}${direction}`;
+		return `${assertSqlFragment(order?.column ?? "", "order column")}${direction}`;
 	});
 	return parts.length > 0 ? ` ORDER BY ${parts.join(", ")}` : "";
 };
@@ -265,7 +266,10 @@ export const buildListSql = (object = {}, dbIndex, tenantIds) => {
 		extra.length === 0
 			? baseWhere
 			: baseWhere
-				? `${baseWhere} AND ${extra.join(" AND ")}`
+				/* ⚠️⚠️ The caller's conditions are PARENTHESISED before the platform's predicates. Appended
+				   bare, an ordinary OR filter (`a = 1 or a = 2`) bound tighter than nothing and returned
+				   soft-deleted rows - no attacker needed. Lookup already did this. tests/orm-sql-guard. */
+				? ` WHERE (${baseWhere.replace(/^ WHERE */, "")}) AND ${extra.join(" AND ")}`
 				: ` WHERE ${extra.join(" AND ")}`;
 	const from = ` FROM ${registry.baseTable}${registry.renderJoins()}`;
 	/* orm.pas:1504 compares case-INsensitively (CompareText), and 1521-1523 sits outside the

package/engine/orm/masterDetail.js

@@ -20,6 +20,7 @@
  * discarded. The FK is always the parent's real id, threaded from the parent CTE — never a value
  * the payload asserts.
  */
+import { assertKeyLiteral } from "./sqlGuard.js";
 import { PRIMARY_KEY_COLUMN, STATEMENT_SEPARATOR } from "./crudQuery.js";
 import {
 	softDeleteFilter,
@@ -30,6 +31,7 @@ import {
 	stampTenant,
 	withTenant,
 	isBooleanColumn,
+	ownedChildrenOf,
 } from "./entityConfig.js";
 import { renderTimestamp } from "./dialect.js";
 
@@ -342,7 +344,10 @@ const collectAddedSubtree = (rowPlan, tableName, parentRef, ctx) => {
 const plainInsert = (rowPlan, tableName, parentRef, ctx) => {
 	const { columnList, values } = insertColumns(rowPlan, parentRef, tableName, ctx);
 	const valueList = [...values, ...(parentRef.fkColumn ? [parentRef.keyValue] : [])].join(", ");
-	return `INSERT INTO ${tableName} (${columnList}) VALUES (${valueList})`;
+	/* A MASTER returns its key: the caller has to be able to find the record it just created (Doc 2
+	   section 5 reloads it). A detail stays plain - nothing downstream needs its key back. */
+	const returning = parentRef.fkColumn ? "" : ` RETURNING ${PRIMARY_KEY_COLUMN}`;
+	return `INSERT INTO ${tableName} (${columnList}) VALUES (${valueList})${returning}`;
 };
 
 const hasAddedDescendants = (rowPlan) =>
@@ -416,8 +421,11 @@ const walkPlan = (rowPlan, tableName, parentRef, out) => {
 const softDeleteOrDelete = (table, where, dbIndex, deletedBy, tenantIds) => {
 	const scopeTenant = tenantFilter(table, dbIndex, tenantIds);
 	const scoped = scopeTenant ? `${where} AND ${scopeTenant}` : where;
+	/* ⚠️ A soft delete touches only LIVE rows. Without this, deleting an already-deleted row stamped it
+	   again - `deleted_at` and `deleted_by` rewritten to now and to whoever asked, on every v2 save and
+	   every repeated deletemd. Soft delete exists to keep that record; this is what keeps it. */
 	return isSoftDelete(table, dbIndex)
-		? `UPDATE ${table} SET ${buildSoftDeleteSet(deletedBy)} WHERE ${scoped}`
+		? `UPDATE ${table} SET ${buildSoftDeleteSet(deletedBy)} WHERE ${scoped} AND ${softDeleteFilter(table, dbIndex)}`
 		: `DELETE FROM ${table} WHERE ${scoped}`;
 };
 
@@ -440,6 +448,37 @@ export const buildMasterDetailChangeSql = (plan, dbIndex, deletedBy, tenantIds,
 	return [...out.deletes, ...out.updates, ...out.inserts].join(STATEMENT_SEPARATOR);
 };
 
+/*
+ * Doc 2 section 5.2 item 5 - a v2 DELETE of a master, cascading by CONFIG.
+ *
+ * Unlike deletemd, the client names nothing: the cascade is every ownership:parent relationship at any
+ * depth (entityConfig.ownedChildrenOf), through the DECLARED foreign keys. Deepest first, each table by
+ * its OWN strategy (softDeleteOrDelete - soft/hard and tenant scope, Doc 3 sections 6.6 and 11), the
+ * master last. A table already on the path is not re-entered, so an owned self-reference terminates.
+ * tests/orm-v2-delete.test.js.
+ */
+export const buildGraphDeleteSql = (object, dbIndex, deletedBy, tenantIds) => {
+	const [masterTable, masterRow] = Object.entries(object ?? {})[0] ?? [];
+	const keyEntry = Object.entries(masterRow ?? {}).find(([column]) => isPrimaryKey(column));
+	if (!masterTable || !keyEntry || !hasRealKey(masterRow)) {
+		throw new Error(`a v2 delete of ${masterTable ?? "a table"} needs the key of the record to delete`);
+	}
+	const statements = [];
+	const walk = (parentTable, correlation, path) => {
+		for (const { table, foreignKey } of ownedChildrenOf(parentTable, dbIndex)) {
+			if (path.includes(table.toLowerCase())) continue;
+			const here = `${foreignKey} ${correlation}`;
+			walk(table, `IN (SELECT ${PRIMARY_KEY_COLUMN} FROM ${table} WHERE ${here})`, [...path, table.toLowerCase()]);
+			statements.push(softDeleteOrDelete(table, here, dbIndex, deletedBy, tenantIds));
+		}
+	};
+	walk(masterTable, `= ${renderValue(keyEntry[1])}`, [String(masterTable).toLowerCase()]);
+	statements.push(
+		softDeleteOrDelete(masterTable, `${PRIMARY_KEY_COLUMN} = ${renderValue(keyEntry[1])}`, dbIndex, deletedBy, tenantIds),
+	);
+	return statements.join(STATEMENT_SEPARATOR);
+};
+
 /* deletemd — deepest detail first, each correlated to the master through its parent chain. */
 export const buildDeleteMasterDetailSql = (object, dbIndex, deletedBy, tenantIds) => {
 	const [masterTable, masterRow] = Object.entries(object ?? {})[0] ?? [];
@@ -508,7 +547,8 @@ export const buildDetailSelectSql = (object, dbIndex, tenantIds) => {
 	const columns = Object.keys(detailRow)
 		.filter((column) => column.toLowerCase() !== masterKey.toLowerCase())
 		.map((column) => `${detailTable}.${column}`);
-	const masterValue = (masterRow ?? {})[masterValueKey];
+	/* Verbatim by contract, like every get key - so exactly one literal (sqlGuard.js). */
+	const masterValue = assertKeyLiteral((masterRow ?? {})[masterValueKey], `${masterTable}.${masterValueKey}`);
 	/* Doc 3 §6.6 rule 2 — a soft-deleted detail must not reappear when its master is read. */
 	const hideDeleted = softDeleteFilter(detailTable, dbIndex);
 	/* Doc 3 §11 — and a detail belonging to another tenant must not reappear either. A detail is

package/engine/orm/sqlGuard.js

@@ -0,0 +1,172 @@
+/*
+ * What request input may reach the ORM's SQL text, and in what shape.
+ *
+ * The ported ORM keeps FINA's contract: table names, column names, key values and filter fragments
+ * arrive from the caller and are interpolated AS WRITTEN (crudQuery.renderKeyValue, listQuery
+ * buildCondition). A GUID key arrives pre-quoted; a filter value may be a subquery. That contract is
+ * kept - every function here passes a legitimate value through unchanged, byte for byte - and what it
+ * refuses is the STRUCTURE no legitimate value needs.
+ *
+ * ⚠️⚠️ WHAT THIS DEFENDS, HONESTLY. Any authenticated user can already run arbitrary SQL through the
+ * `block` endpoint - by design, relied on by the applications. So this is NOT a defence against a
+ * malicious logged-in user. It defends against DATA-BORNE injection: a value somebody else controlled
+ * (an external member, an import) flowing into a key or filter position, where whoever planted it
+ * cannot call `block`.
+ *
+ * Every refusal throws with `code: UNSAFE_SQL_CODE`, which apiRoute answers with a 400 naming the
+ * field - a caller can fix a request it can see is wrong; it cannot fix a bare 500.
+ * tests/orm-sql-guard.test.js pins every shape found in real application source.
+ */
+export const UNSAFE_SQL_CODE = "UNSAFE_SQL";
+
+const refuse = (what, value, why) =>
+	Object.assign(
+		new Error(`the ORM refuses ${what} ${JSON.stringify(String(value)).slice(0, 80)}: ${why}`),
+		{ code: UNSAFE_SQL_CODE },
+	);
+
+/* A plain SQL identifier. `$` stays legal - Firebird-era system tables are SYS$USERS, SYS$CONFIG. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+
+export const assertIdentifier = (name, what = "identifier") => {
+	const text = String(name ?? "");
+	if (!IDENTIFIER.test(text)) throw refuse(what, text, "not a plain SQL identifier");
+	return name;
+};
+
+/* `schema.table` - each part a plain identifier. The platform itself rewrites a Firebird catalog
+   lookup (RDB$RELATIONS) to information_schema.tables, so a lookup table may be qualified. */
+export const assertQualifiedIdentifier = (name, what = "identifier") => {
+	const parts = String(name ?? "").split(".");
+	if (parts.length > 2 || !parts.every((part) => IDENTIFIER.test(part))) {
+		throw refuse(what, name, "not a plain or schema-qualified SQL identifier");
+	}
+	return name;
+};
+
+/* Exactly one single-quoted SQL string, inner quotes doubled - the pre-quoted form the contract uses. */
+const ONE_QUOTED_LITERAL = /^'(?:[^']|'')*'$/;
+const NUMERIC = /^-?\d+(\.\d+)?$/;
+
+/*
+ * A `get` / `delete` / `getd` key: interpolated verbatim by contract, so it must be ONE literal.
+ * Returns the value itself - the caller renders it exactly as before.
+ */
+export const assertKeyLiteral = (value, what = "key") => {
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw refuse(what, value, "not a finite number");
+		return value;
+	}
+	if (typeof value === "boolean" || value instanceof Date) return value;
+	const text = String(value ?? "").trim();
+	if (NUMERIC.test(text) || ONE_QUOTED_LITERAL.test(text)) return value;
+	throw refuse(what, value, "a key value must be one literal - a number, or one quoted string");
+};
+
+/*
+ * A filter or order fragment. The filter language IS an expression language in production use
+ * (Trimandiri appends `1 AND NOT EXISTS (SELECT ...)` through value1; Supertail sends DATEADD(...)),
+ * so expressions pass. Refused, outside string literals only: a statement terminator, a comment, an
+ * unbalanced parenthesis, an unterminated string. None of those appears in any surveyed filter, and
+ * each is what turns a filter into something that escapes it - a second statement, a truncated tail
+ * that drops the tenant predicate, or a `)` closing the group the platform wraps conditions in.
+ */
+export const assertSqlFragment = (value, what = "fragment") => {
+	if (value === null || value === undefined || typeof value === "number" || typeof value === "boolean") {
+		return value;
+	}
+	const text = String(value);
+	let depth = 0;
+	let quoted = false;
+	for (let i = 0; i < text.length; i += 1) {
+		const ch = text[i];
+		if (quoted) {
+			if (ch === "'") {
+				if (text[i + 1] === "'") {
+					i += 1;
+					continue;
+				}
+				quoted = false;
+			}
+			continue;
+		}
+		if (ch === "'") {
+			quoted = true;
+			continue;
+		}
+		if (ch === ";") throw refuse(what, text, "a statement terminator");
+		if (ch === "-" && text[i + 1] === "-") throw refuse(what, text, "a comment");
+		if (ch === "/" && text[i + 1] === "*") throw refuse(what, text, "a comment");
+		if (ch === "(") depth += 1;
+		if (ch === ")") {
+			depth -= 1;
+			if (depth < 0) throw refuse(what, text, "a parenthesis closed that was never opened");
+		}
+	}
+	if (quoted) throw refuse(what, text, "an unterminated string");
+	if (depth !== 0) throw refuse(what, text, "an unbalanced parenthesis");
+	return value;
+};
+
+/*
+ * A `containing` search value is always a SEARCH STRING, never an expression: listQuery unwraps its
+ * quotes and escapes wildcards but not quotes, so an embedded quote closed the pattern early. One
+ * quoted literal, or plain text with no quote at all.
+ */
+export const assertSearchLiteral = (value, what = "search value") => {
+	if (value === null || value === undefined) return value;
+	const text = String(value).trim();
+	if (ONE_QUOTED_LITERAL.test(text) || !text.includes("'")) return value;
+	throw refuse(what, value, "a search value must be one quoted string");
+};
+
+/*
+ * Every operator found across biz-a-template (5,787 filters) and the client filter-list component,
+ * plus their natural complements. Compared lower-cased with whitespace collapsed, so "Not  In" and
+ * "CONTAINING" are the operators they read as.
+ */
+const OPERATORS = new Set([
+	"", "=", "<>", "!=", "<", "<=", ">", ">=",
+	"in", "not in", "like", "not like", "similar to", "not similar to",
+	"containing", "not containing", "starting", "starting with", "not starting", "not starting with",
+	"is", "is not", "is null", "is not null", "between", "not between", "exists", "not exists",
+]);
+
+export const normaliseFilterOperator = (operator) => {
+	const text = String(operator ?? "").toLowerCase().replace(/\s+/g, " ").trim();
+	if (!OPERATORS.has(text)) throw refuse("filter operator", operator, "not a recognised operator");
+	return operator;
+};
+
+/*
+ * Every table and column NAME in a crud payload: the table keys, every row's keys, nested detail
+ * collections, and the `detail` spec of a getd. Values are not this function's business.
+ */
+export const assertPayloadIdentifiers = (object) => {
+	for (const [table, payload] of Object.entries(object ?? {})) {
+		if (table === "detail") {
+			const detail = payload;
+			if (typeof detail === "string") assertIdentifier(detail, "detail table");
+			else if (detail && typeof detail === "object") {
+				/* Only when PRESENT: a missing key is buildDetailSelectSql's to name (the Delphi contract's
+				   own error, TestORMMasterDetail.pas GetDetail_DetailObject_invalid*). */
+				if ("tableName" in detail) assertIdentifier(detail.tableName, "detail table");
+				if ("masterKey" in detail) assertIdentifier(detail.masterKey, "detail master key");
+			}
+			continue;
+		}
+		assertIdentifier(table, "table");
+		assertRowIdentifiers(table, payload);
+	}
+};
+
+const assertRowIdentifiers = (table, payload) => {
+	for (const row of Array.isArray(payload) ? payload : [payload]) {
+		if (!row || typeof row !== "object") continue;
+		for (const [column, value] of Object.entries(row)) {
+			/* `*` is the contract's "every column" - ormGet sends it, and the ESB kiosk path relies on it. */
+			if (column !== "*") assertIdentifier(column, `column of ${table}`);
+			if (Array.isArray(value)) assertRowIdentifiers(column, value);
+		}
+	}
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "biz-a-cli",
-	"version": "2.3.80-15372",
+	"version": "2.3.80-15375",
 	"description": "",
 	"main": "bin/index.js",
 	"type": "module",