biz-a-cli 2.3.80-15407 → 2.3.80-15410

package/bin/hubEvent.js

@@ -1116,7 +1116,8 @@ export const clientListener = (socket, argv, via = "?") => {
 							status: routed.status,
 							statusText: routed.status === 200 ? "OK" : "Error",
 							headers: {
-								"content-type": "application/json",
+								/* An image read answers bytes with its own type (apiRoute.js `img`). */
+								"content-type": routed.contentType ?? "application/json",
 								...cliAddressHeaders(),
 							},
 							body: routed.body,

package/engine/cc/drift.js

@@ -202,10 +202,26 @@ export const unbuilt = (map, functionId, { linked, gapped }) =>
 
 /* --- drift -------------------------------------------------------------------------------------------- */
 
+/* { functionId: { domains } }: each function some link reaches, with the DOMAIN configs it was built into. */
+const builtFunctions = (elements, links) => {
+	const out = {};
+	for (const link of links ?? []) {
+		const element = elements[link.mapElementId];
+		const fn = element ? (element.type === "FUNCTION" ? element.id : element.functionId) : null;
+		if (!fn) continue;
+		const domains = (out[fn] ??= { domains: [] }).domains;
+		if (link.configKind === "DOMAIN" && !domains.includes(link.configName)) domains.push(link.configName);
+	}
+	for (const f of Object.values(out)) f.domains.sort();
+	return out;
+};
+
 /*
  * links: trace links with their baselines (elementSnapshot / targetSnapshot; null = made before baselines).
  * configs: { "KIND:name": content | null } — the OPEN draft, else what is published.
- * Returns the FLAGGED elements, and the links to baseline now (made before baselines, target present).
+ * Returns the FLAGGED elements, the links to baseline now (made before baselines, target present), and the
+ * functions that have config — with the domains their links point to (CC generates a function absent from it, and
+ * refines those domains for one in it).
  */
 export const computeDrift = ({ map, links, gaps = [], configs = {} }) => {
 	const elements = map?.elements ?? {};
@@ -249,7 +265,7 @@ export const computeDrift = ({ map, links, gaps = [], configs = {} }) => {
 		for (const id of unbuilt(map, fn, { linked, gapped })) flag(id).pendingBuild ??= { why: "notBuilt", changes: [] };
 	}
 
-	return { elements: out, baseline };
+	return { elements: out, baseline, functions: builtFunctions(elements, links) };
 };
 
 /* Exported for the tests of what counts. */

package/engine/cc/mapStore.js

@@ -13,7 +13,8 @@
  *   links    {configKind, configName}  the map elements a config implements (the studios' back-links)
  *   unlink   {linkId}                  a person removes one link
  *   drift    {}                        Doc 1 §7.4 (4b): the elements whose config was changed by hand ("drifted")
- *                                      or that changed since built / are not built yet ("pending build")
+ *                                      or that changed since built / are not built yet ("pending build"), and
+ *                                      the functions that have config, with their domains
  *   markInSync {elementId}             a person who fixed both sides re-baselines the element's links
  *   printData {version?}               Doc 1 §4.8 (4c): a SAVED map version with every gap and link, to print
  *
@@ -143,10 +144,10 @@ const actions = {
 			const key = `${link.configKind}:${link.configName}`;
 			if (!(key in configs)) configs[key] = (await readConfig(link.configKind, link.configName)).content ?? null;
 		}
-		const { elements, baseline } = computeDrift({ map: latest.map, links, gaps: await gapRepo.all(), configs });
+		const { elements, baseline, functions } = computeDrift({ map: latest.map, links, gaps: await gapRepo.all(), configs });
 		/* Links made before baselines existed take what is there now as in sync — once. */
 		if (baseline.length) await traceRepo.baseline(baseline);
-		return done({ version: latest.version, elements });
+		return done({ version: latest.version, elements, functions });
 	},
 
 	/* Ruling 2026-10-03: the implementor fixed both sides by hand — the element's links take both as they are now.

package/engine/orm/apiRoute.js

@@ -48,6 +48,16 @@ import { buildValidUserIdSql, verifyCredential, buildPasswordUpgradeSql, buildUs
 import { resolveUserTenancy, capSessionExpiry } from "./tenantResolution.js";
 import { describeTenants } from "./tenantApi.js";
 import { translateExecuteBlock } from "./executeBlock.js";
+import { isUserApiDataset, saveUserApiDataset } from "./userApiDataset.js";
+import {
+	readUpdateImgRequest,
+	buildImgColumnTypeSql,
+	isTextColumnType,
+	buildPgUpdateImg,
+	parseImgGetPath,
+	buildPgGetImg,
+	getContentType,
+} from "./imgQuery.js";
 import zlib from "node:zlib";
 
 /* /fina/rest/<Class>/%22<endpoint>%22 — the path the client builds. */
@@ -165,6 +175,36 @@ export const parseGenIdRequest = (path) => {
 	return { generator, dbIndex: Number.isFinite(dbIndex) ? dbIndex : null };
 };
 
+/*
+ * ⚠️⚠️ `img` — the BLOB write and read, which no other parser here can see.
+ *
+ * The client builds both paths UNQUOTED (`getUrlApi(config, 'img', false)`), so `DATASNAP_PATH`
+ * never matches them:
+ *
+ *   write  POST /fina/rest/TOrmMethod/img            body = {dbIndex, tableName, imgCol, keyCol,
+ *                                                            keyValue, img: <base64>} — the bare
+ *                                                            object, no `_parameters`
+ *   read   GET  /fina/rest/TOrmMethod/img/<db>/<table>/<keyCol>/<imgCol>/<'key'>[/<formatCol>]
+ *
+ * Unrecognised, both fell through to FINA. Returns { write: true, dbIndex, request } for a write,
+ * { write: false, dbIndex, ...read } for a read, or null.
+ */
+const IMG_WRITE_PATH = /\/fina\/rest\/\w+\/img\/?(?:[?#]|$)/i;
+
+export const parseImgRequest = (path, body) => {
+	const read = parseImgGetPath(path);
+	if (read) return { write: false, ...read };
+	if (!IMG_WRITE_PATH.test(String(path ?? ""))) return null;
+	try {
+		const request = readEnvelope(body);
+		if (!request || typeof request !== "object") return null;
+		const dbIndex = Number(request.dbIndex);
+		return { write: true, dbIndex: Number.isFinite(dbIndex) ? dbIndex : null, request };
+	} catch {
+		return null; // a body we cannot read is not ours; it goes to FINA untouched
+	}
+};
+
 export const parseDataSnapRequest = (path, body) => {
 	const match = DATASNAP_PATH.exec(String(path ?? ""));
 	if (!match) return null;
@@ -532,6 +572,118 @@ const requestBaseTable = (parsed) => {
 	return String(Object.keys(param.object ?? {})[0] ?? "");
 };
 
+/* The write. Answered `{success: "OK"}` — FINA's own success shape, which data.service.ts
+   handleError accepts. */
+export const IMG_ROW_NOT_FOUND_CODE = "NOT_FOUND";
+const imgWriteResponse = async (request, dbIndex, exec) => {
+	/* Every name is checked BEFORE anything runs, the column-type probe included. */
+	const fields = readUpdateImgRequest(request);
+	const [column] = (await exec(buildImgColumnTypeSql(fields), dbIndex)) ?? [];
+	const updated =
+		(await exec(buildPgUpdateImg(fields, { textColumn: isTextColumnType(column?.data_type) }), dbIndex)) ?? [];
+	/* ⚠️ FINA answers OK here too. That silence is how an item image stayed NULL with nothing shown. */
+	if (updated.length === 0) {
+		return {
+			status: 404,
+			body: {
+				error: `img: no ${fields.tableName} row has ${fields.keyCol} = ${fields.key}, so the image was not stored`,
+				code: IMG_ROW_NOT_FOUND_CODE,
+			},
+		};
+	}
+	return { status: 200, body: { success: "OK" } };
+};
+
+/* The read. ⚠️ The body is a BUFFER, not JSON: both entrances check for one and send the bytes
+   with `contentType` (finaEndpoint.js, bin/hubEvent.js). FINA's answers are kept — `image/jpeg`
+   unless a format column names the type, and an EMPTY 200 for a missing row or a NULL blob. */
+const imgReadResponse = async (read, dbIndex, exec) => {
+	const [row] = (await exec(buildPgGetImg(read), dbIndex)) ?? [];
+	/* Positional, as FINA reads Fields[0] / Fields[1]: the row's key casing is the driver's business. */
+	const [image, format] = Object.values(row ?? {});
+	const bytes =
+		image === null || image === undefined
+			? Buffer.alloc(0)
+			: Buffer.isBuffer(image)
+				? image
+				: Buffer.from(String(image), "utf8"); // a text column
+	return {
+		status: 200,
+		body: bytes,
+		contentType: read.formatCol && row ? getContentType(format) : "image/jpeg",
+	};
+};
+
+/*
+ * How a failure inside the router is answered. Shared by the ORM endpoints and `img`, so a refusal
+ * means the same thing whichever of them raised it.
+ */
+const failureResponse = (error, dbIndex) => {
+	/* 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 } };
+	}
+	/* Doc 3 §6.3 — the caller asked the ORM to manage a collection its parent does not own. A
+	   caller error, and distinguishable without parsing a message so an application can point at
+	   the screen sending it. */
+	/* Doc 3 §11 write side. 403 vs 400 says WHICH kind of problem it is: naming somebody else's
+	   tenant is an authorization failure, naming none is an under-specified request the caller can
+	   fix by sending the column. */
+	if (error?.code === CROSS_TENANT_CODE) {
+		return { status: 403, body: { error: error.message, code: CROSS_TENANT_CODE } };
+	}
+	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 } };
+	}
+	/* Doc 3 §11 layer 2 — an engine-level refusal from a raw-SQL path, translated into the same
+	   vocabulary the ORM path uses. Without this it reaches the browser as a bare 500. */
+	const engineRefusal = describeRlsFailure(error);
+	if (engineRefusal) {
+		return {
+			status: engineRefusal.status,
+			body: { error: engineRefusal.message, code: engineRefusal.code },
+		};
+	}
+	/* Found live 2026-10-07: a refused save reached the user as SQL. A refusal the user can act on is named by the
+	   field's label; anything else keeps its message, never the statement — that goes to the hub log only. */
+	const refusal = describeDatabaseRefusal(error, { labelOf: (table, column) => labelFor(table, column, dbIndex) });
+	if (refusal) {
+		logger.info(`[orm] ${refusal.code}: ${error?.message ?? error}`);
+		return { status: refusal.status, body: { error: refusal.message, code: refusal.code } };
+	}
+	logger.error(`[orm] ${error?.message ?? error}`);
+	return { status: 500, body: { error: withoutStatement(error?.message ?? String(error)) } };
+};
+
+/* Doc 3 §11 — a verified caller may only name its OWN PostgreSQL tenant. */
+const tenantMismatch = (path, principal, requestedDbIndex) => {
+	logger.error(
+		`[apiRequest] refused ${path}: principal is for db ${principal.dbIndex} but the request asked for db ${requestedDbIndex}`,
+	);
+	return {
+		status: 403,
+		body: { error: "request names a different tenant than the principal", code: "TENANT_MISMATCH" },
+	};
+};
+
 export const routeApiRequest = async (
 	{ path, body },
 	/* `principal` is the VERIFIED caller (Doc 3 §11's precondition), or null while the boundary runs
@@ -759,6 +911,29 @@ export const routeApiRequest = async (
 		}
 	}
 
+	/*
+	 * ⚠️⚠️ `img` — the BLOB write and read (parseImgRequest says why nothing else sees them).
+	 *
+	 * Forwarded, a PostgreSQL tenant's image went to a FINA holding a DIFFERENT database: the write
+	 * answered OK and stored nothing, the read answered an empty image. A Firebird index really does
+	 * keep its images in FINA, so it is still declined — forwarded byte for byte.
+	 */
+	const imgRequest = parseImgRequest(path, body);
+	if (imgRequest) {
+		const imgDbIndex = imgRequest.dbIndex;
+		if (imgDbIndex === null || !isPostgresIndex(imgDbIndex)) return null;
+		if (principal && imgDbIndex !== Number(principal.dbIndex)) {
+			return tenantMismatch(path, principal, imgDbIndex);
+		}
+		try {
+			return imgRequest.write
+				? await imgWriteResponse(imgRequest.request, imgDbIndex, exec)
+				: await imgReadResponse(imgRequest, imgDbIndex, exec);
+		} catch (error) {
+			return failureResponse(error, imgDbIndex);
+		}
+	}
+
 	const parsed = parseDataSnapRequest(path, body);
 	if (!parsed) return null;
 
@@ -846,13 +1021,7 @@ export const routeApiRequest = async (
 	 */
 	if (principal && requestedDbIndex !== null && isPostgresIndex(requestedDbIndex)) {
 		if (Number(requestedDbIndex) !== Number(principal.dbIndex)) {
-			logger.error(
-				`[apiRequest] refused ${path}: principal is for db ${principal.dbIndex} but the request asked for db ${requestedDbIndex}`,
-			);
-			return {
-				status: 403,
-				body: { error: "request names a different tenant than the principal", code: "TENANT_MISMATCH" },
-			};
+			return tenantMismatch(path, principal, requestedDbIndex);
 		}
 	}
 
@@ -934,61 +1103,18 @@ export const routeApiRequest = async (
 			const rows = await execTransaction(statements, dbIndex);
 			return { status: 200, body: { data: upperCaseKeys(rows), success: "OK" } };
 		}
-		/* Anything else — genId, setApp, ExecuteSQL, TMfgMethod — is not part of the ORM surface.
-		   Returning null forwards it to FINA, which is honest: those still need it. */
+		/* The admin Users screen saves through FINA's TUserApiDataset. On PostgreSQL the users are
+		   SYS$USERS, so it is answered here (userApiDataset.js); forwarded, it could only meet a FINA
+		   that is not running. Every OTHER json2fina module is a FINA accounting transaction with no
+		   PostgreSQL counterpart, so it still forwards. */
+		if (parsed.endpoint === "json2fina") {
+			if (!isUserApiDataset(parsed.param)) return null;
+			return await saveUserApiDataset(parsed.param, { exec, dbIndex, principal });
+		}
+		/* Anything else — setApp, the other json2fina modules, TMfgMethod — is not part of the ORM
+		   surface. Returning null forwards it to FINA, which is honest: those still need it. */
 		return null;
 	} catch (error) {
-		/* 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 } };
-		}
-		/* Doc 3 §6.3 — the caller asked the ORM to manage a collection its parent does not own. A
-		   caller error, and distinguishable without parsing a message so an application can point at
-		   the screen sending it. */
-		/* Doc 3 §11 write side. 403 vs 400 says WHICH kind of problem it is: naming somebody else's
-		   tenant is an authorization failure, naming none is an under-specified request the caller can
-		   fix by sending the column. */
-		if (error?.code === CROSS_TENANT_CODE) {
-			return { status: 403, body: { error: error.message, code: CROSS_TENANT_CODE } };
-		}
-		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 } };
-		}
-		/* Doc 3 §11 layer 2 — an engine-level refusal from a raw-SQL path, translated into the same
-		   vocabulary the ORM path uses. Without this it reaches the browser as a bare 500. */
-		const engineRefusal = describeRlsFailure(error);
-		if (engineRefusal) {
-			return {
-				status: engineRefusal.status,
-				body: { error: engineRefusal.message, code: engineRefusal.code },
-			};
-		}
-		/* Found live 2026-10-07: a refused save reached the user as SQL. A refusal the user can act on is named by the
-		   field's label; anything else keeps its message, never the statement — that goes to the hub log only. */
-		const refusal = describeDatabaseRefusal(error, { labelOf: (table, column) => labelFor(table, column, dbIndex) });
-		if (refusal) {
-			logger.info(`[orm] ${refusal.code}: ${error?.message ?? error}`);
-			return { status: refusal.status, body: { error: refusal.message, code: refusal.code } };
-		}
-		logger.error(`[orm] ${error?.message ?? error}`);
-		return { status: 500, body: { error: withoutStatement(error?.message ?? String(error)) } };
+		return failureResponse(error, dbIndex);
 	}
 };

package/engine/orm/finaEndpoint.js

@@ -232,6 +232,12 @@ export const createFinaRouter = (deps) => {
 			res.set("Access-Control-Expose-Headers", "biza-cli-address, biza-hub-address");
 		}
 
+		/* ⚠️ An image read answers BYTES (apiRoute.js `img`), and this is the route `<img src>` takes.
+		   `res.json` would send `{"type":"Buffer","data":[…]}` — a 200 the browser cannot draw. */
+		if (Buffer.isBuffer(result.body)) {
+			res.status(result.status).type(result.contentType ?? "application/octet-stream").send(result.body);
+			return;
+		}
 		res.status(result.status).json(result.body);
 	});
 	return router;

package/engine/orm/imgQuery.js

@@ -5,6 +5,7 @@
  * together; the update binds `:logo` / `:format` / `:key` parameters, which the execution layer
  * supplies. Values arrive pre-quoted from the caller, matching the rest of this ORM.
  */
+import { assertIdentifier, assertQualifiedIdentifier, assertKeyLiteral } from "./sqlGuard.js";
 
 const CONTENT_TYPES = {
 	jpg: "image/jpeg",
@@ -66,6 +67,97 @@ export const buildUpdateImg = (request = {}) => {
 	};
 };
 
+/*
+ * ⚠️⚠️ THE SAME ENDPOINT ON POSTGRESQL — and why the builders above cannot simply be run.
+ *
+ * `buildUpdateImg` emits Delphi's `:logo` / `:key` placeholders, which node-pg does not understand,
+ * and `buildGetImgSql` interpolates the key into the statement. Neither was ever wired to a route:
+ * the client builds both paths UNQUOTED (`getUrlApi(config, 'img', false)`), so apiRoute never
+ * recognised them and they fell through to FINA. On a PostgreSQL tenant that FINA holds a different
+ * database, and it answered `success: "OK"` for an UPDATE that matched nothing — Supertail's item
+ * image kept a NULL CONTENT and nobody was told (studioa, 2026-10-09).
+ *
+ * These build `{text, values}` for node-pg instead. Names are checked as plain identifiers; the key
+ * is BOUND, never interpolated, so a key value cannot become SQL. The FINA builders above stay as
+ * they are — tests/orm-parity.test.js pins them to orm.pas.
+ */
+const TEXT_COLUMN_TYPES = new Set(["text", "character varying", "character"]);
+
+/* The write request, checked in orm.pas's order and with its messages, plus the identifier guard. */
+export const readUpdateImgRequest = (request = {}) => {
+	const tableName = assertQualifiedIdentifier(requireField(request, "tableName"), "img table");
+	const imgCol = assertIdentifier(requireField(request, "imgCol"), "img column");
+	const keyCol = assertIdentifier(requireField(request, "keyCol"), "img key column");
+	const img = requireField(request, "img");
+	const key = requireField(request, "keyValue");
+	requireField(request, "dbIndex");
+	const useFormat = request.formatValue !== undefined && request.formatValue !== null;
+	return {
+		tableName,
+		imgCol,
+		keyCol,
+		img: String(img),
+		key: String(key),
+		formatCol: useFormat ? assertIdentifier(requireField(request, "formatCol"), "img format column") : "",
+		format: useFormat ? String(request.formatValue).toUpperCase() : "",
+	};
+};
+
+/* Whether the target column is text rather than bytea. Firebird has one BLOB type for both, so the
+   request cannot say; binding a Buffer to a text column would store the literal `\x…` escape. */
+export const buildImgColumnTypeSql = ({ tableName, imgCol }) => ({
+	text:
+		"SELECT data_type FROM information_schema.columns " +
+		"WHERE table_schema = current_schema() AND table_name = lower($1) AND column_name = lower($2)",
+	values: [String(tableName), String(imgCol)],
+});
+
+export const isTextColumnType = (dataType) => TEXT_COLUMN_TYPES.has(String(dataType ?? "").toLowerCase());
+
+/* ⚠️ RETURNING the key: FINA cannot tell an UPDATE that hit nothing from one that worked, and that
+   blindness is the bug this exists to fix. The caller refuses an empty result. */
+export const buildPgUpdateImg = ({ tableName, imgCol, keyCol, img, key, formatCol, format }, { textColumn = false } = {}) => {
+	const bytes = Buffer.from(img, "base64");
+	const values = [textColumn ? bytes.toString("utf8") : bytes, key];
+	let assignments = `${imgCol} = $1`;
+	if (formatCol) {
+		assignments += `, ${formatCol} = $3`;
+		values.push(format);
+	}
+	return { text: `UPDATE ${tableName} SET ${assignments} WHERE ${keyCol} = $2 RETURNING ${keyCol}`, values };
+};
+
+/* GET /fina/rest/<Class>/img/<dbIndex>/<table>/<keyCol>/<imgCol>/<value>[/<formatCol>] — FINA's
+   `TOrmMethod.img(dbIndex, table, key, img, value, imgFormat)`, one segment per argument. */
+const IMG_GET_PATH = /\/fina\/rest\/\w+\/img\/(\d+)\/([^/?#]+)\/([^/?#]+)\/([^/?#]+)\/([^/?#]+)(?:\/([^/?#]+))?\/?(?:[?#]|$)/i;
+
+/* Never throws: a path it cannot read is not a read it serves. */
+export const parseImgGetPath = (path) => {
+	const match = IMG_GET_PATH.exec(String(path ?? ""));
+	if (!match) return null;
+	try {
+		const [table, keyCol, imgCol, value, formatCol] = match.slice(2).map((part) =>
+			part === undefined ? "" : decodeURIComponent(part),
+		);
+		return { dbIndex: Number(match[1]), table, keyCol, imgCol, value, formatCol };
+	} catch {
+		return null;
+	}
+};
+
+/* The key arrives pre-quoted for FINA's interpolation (`'{GUID}'`, img-formly.component.ts). It must
+   be ONE literal; its quotes are then taken off and the value bound. */
+export const buildPgGetImg = ({ table, keyCol, imgCol, formatCol = "", value }) => {
+	assertQualifiedIdentifier(table, "img table");
+	assertIdentifier(keyCol, "img key column");
+	assertIdentifier(imgCol, "img column");
+	if (formatCol) assertIdentifier(formatCol, "img format column");
+	const literal = String(assertKeyLiteral(value, "img key")).trim();
+	const key = literal.startsWith("'") ? literal.slice(1, -1).replace(/''/g, "'") : literal;
+	const columns = formatCol ? `${imgCol}, ${formatCol}` : imgCol;
+	return { text: `SELECT ${columns} FROM ${table} WHERE ${keyCol} = $1`, values: [key] };
+};
+
 /*
  * Result post-processing: the driver returns rows keyed by bare column name, but callers address
  * them by the FULL requested key (`tn.a`), which is what disambiguates two joined columns that

package/engine/orm/userApiDataset.js

@@ -0,0 +1,153 @@
+/*
+ * FINA's `TUserApiDataset`, served for a PostgreSQL index — the admin Users screen.
+ *
+ * User List → Add → Save (client/src/app/admin/userForm.component.ts modifyUser) and the list's
+ * Delete (usersList.component.ts) post TFinaMethod/"json2fina" with this data module. apiRoute did
+ * not route json2fina, so it went to FINA — which a PostgreSQL tenant does not run, and Add User
+ * failed as `502 ECONNREFUSED 127.0.0.1:212`. Users there live in SYS$USERS, beside the tenant data.
+ *
+ * The Delphi trail, so the behaviour is FINA's and not a guess:
+ *   FINAMethod.pas:459   needAuthenticate — TUserApiDataset is the one module that demands `password`
+ *   FINAMethod.pas:734   that password is the CALLER's (`userId`) own -> 'Incorrect password'
+ *   FINAMethod.pas:499   isAppend — an `id` of '' or -1 inserts; `delete = 1` deletes; else edits
+ *   FINAMethod.pas:538   AssignField — a master key with no matching column is ignored
+ *   FINAMethod.pas:839   {"id": <key>} on success, {"error": <message>} on failure, HTTP 200 both
+ *   UserApiDataset.pas   USERNAME upper-cased; `plainpassword` hashed into USERPASSWORD
+ *
+ * ⚠️ ONE DELIBERATE DIFFERENCE: FINA skips the confirmation when `password` is '' (FINAMethod.pas:734
+ * tests `password <> Str_Empty`). Here an empty password is simply an incorrect one — the screen
+ * always asks for it, and a write to the user table must not be one empty field away from unguarded.
+ *
+ * Passwords are hashed with finaAuth.js's scrypt, the scheme the PostgreSQL login verifies, so a user
+ * created here can sign in straight away. The envelope carries plain-text passwords: nothing in this
+ * module logs or echoes it.
+ */
+import { hashPassword, verifyCredential } from "./finaAuth.js";
+import { buildInsertUserSql } from "./userAdmin.js";
+import { withoutStatement } from "./saveErrors.js";
+import { logger } from "../../logger.js";
+
+export const USER_API_DATASET = "TUserApiDataset";
+
+export const isUserApiDataset = (param) => String(param?.dataModule ?? "") === USER_API_DATASET;
+
+const quote = (value) => String(value ?? "").replace(/'/g, "''");
+const upper = (value) => String(value ?? "").toUpperCase();
+const has = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+const isBlank = (value) => String(value ?? "").trim() === "";
+
+/* Delphi's FieldByName is case-insensitive; the client happens to send lower case. */
+const lowerKeys = (object) =>
+	Object.fromEntries(Object.entries(object ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
+
+/* The columns verifyCredential reads — the same ones the login selects. */
+export const buildFindUserByIdSql = (userId) =>
+	`SELECT USERID, USERNAME, USERPASSWORD, USERLEVEL FROM SYS$USERS WHERE USERID = ${Number(userId)}`;
+
+/* Only the keys the master carries are written. ⚠️ USERPASSWORD only for a non-empty plainpassword:
+   the edit form omits it when the password is unchanged, and writing it anyway would hash ''. */
+export const buildUpdateUserSql = (userId, master = {}) => {
+	const fields = lowerKeys(master);
+	const sets = [];
+	if (has(fields, "username")) sets.push(`USERNAME = '${quote(upper(fields.username))}'`);
+	if (has(fields, "fullname")) {
+		sets.push(`FULLNAME = ${fields.fullname === null ? "NULL" : `'${quote(fields.fullname)}'`}`);
+	}
+	if (has(fields, "userlevel") && !isBlank(fields.userlevel) && Number.isInteger(Number(fields.userlevel))) {
+		sets.push(`USERLEVEL = ${Number(fields.userlevel)}`);
+	}
+	if (!isBlank(fields.plainpassword)) {
+		sets.push(`USERPASSWORD = '${quote(hashPassword(fields.plainpassword))}'`);
+	}
+	if (sets.length === 0) return null;
+	return `UPDATE SYS$USERS SET ${sets.join(", ")} WHERE USERID = ${Number(userId)} RETURNING USERID`;
+};
+
+/* SYS$SESSION, SYS$USER_TENANT and SYS$USER_PREFERENCES cascade from SYS$USERS. */
+export const buildDeleteUserSql = (userId) =>
+	`DELETE FROM SYS$USERS WHERE USERID = ${Number(userId)} RETURNING USERID`;
+
+const answer = (entry) => ({ status: 200, body: { result: [entry] } });
+const refuse = (error) => answer({ error });
+const keyOf = (rows) => rows?.[0]?.userid ?? rows?.[0]?.USERID;
+
+/* FINAMethod.pas isAppend: '' or -1. A JSON null reads as '' in Delphi, so it appends too. */
+const isAppend = (id) => id === undefined || id === null || String(id).trim() === "" || Number(id) === -1;
+
+/* dialect.js decorate keeps the driver error on `cause` and copies `code` — read both. */
+const describeFailure = (error, master) => {
+	const code = String(error?.code ?? error?.cause?.code ?? "");
+	if (code === "23505") return `User name '${upper(master.username)}' is already used.`;
+	return withoutStatement(error?.message ?? String(error));
+};
+
+/*
+ * The caller whose password confirms the change.
+ *
+ * ⚠️ A verified principal WINS over the body's `userId`, and a body naming someone else is refused
+ * rather than quietly overridden: it is either a stale tab or a forged request, and neither should
+ * reach the user table. With no principal (observe mode) the body is all there is — FINA's own rule.
+ */
+const confirmingUserOf = (param, principal) => {
+	const claimed = param.userId ?? param.userid;
+	if (principal?.userId !== undefined && principal?.userId !== null) {
+		if (claimed !== undefined && claimed !== null && Number(claimed) !== Number(principal.userId)) {
+			return { error: "The request names a different user than the one signed in." };
+		}
+		return { userId: Number(principal.userId) };
+	}
+	return { userId: Number(claimed) };
+};
+
+/* Returns a DataSnap response — always, and never throws: the caller is a socket handler. */
+export const saveUserApiDataset = async (param, { exec, dbIndex, principal = null }) => {
+	const master = lowerKeys(param?.data?.master);
+	const isDelete = String(param?.delete ?? "") === "1";
+	const inserting = !isDelete && isAppend(param?.id);
+	const id = Number(param?.id);
+	if (!inserting && !Number.isInteger(id)) return refuse(`Invalid user id: ${param?.id}`);
+
+	const confirming = confirmingUserOf(param ?? {}, principal);
+	if (confirming.error) return refuse(confirming.error);
+
+	try {
+		const password = param?.password;
+		if (!Number.isInteger(confirming.userId) || typeof password !== "string" || password === "") {
+			return refuse("Incorrect password");
+		}
+		const confirmRows = (await exec(buildFindUserByIdSql(confirming.userId), dbIndex)) ?? [];
+		const confirmName = confirmRows[0]?.username ?? confirmRows[0]?.USERNAME;
+		if (verifyCredential(confirmRows, confirmName, password).userId !== confirming.userId) {
+			return refuse("Incorrect password");
+		}
+
+		if (isDelete) {
+			const rows = await exec(buildDeleteUserSql(id), dbIndex);
+			return keyOf(rows) === undefined ? refuse(`User ${id} not found`) : answer({ id: String(keyOf(rows)) });
+		}
+
+		if (inserting) {
+			if (isBlank(master.username)) return refuse("A new user needs a user name.");
+			if (isBlank(master.plainpassword)) return refuse("A new user needs a password.");
+			const rows = await exec(
+				buildInsertUserSql({
+					username: master.username,
+					password: master.plainpassword,
+					fullname: master.fullname,
+					userlevel: master.userlevel,
+				}),
+				dbIndex,
+			);
+			return answer({ id: String(keyOf(rows) ?? "") });
+		}
+
+		const update = buildUpdateUserSql(id, master);
+		/* Nothing to change still has to name a user that exists, as FINA's DoEdit would. */
+		const rows = await exec(update ?? buildFindUserByIdSql(id), dbIndex);
+		return keyOf(rows) === undefined ? refuse(`User ${id} not found`) : answer({ id: String(keyOf(rows)) });
+	} catch (error) {
+		const message = describeFailure(error, master);
+		logger.error(`[json2fina] ${USER_API_DATASET}: ${message}`);
+		return refuse(message);
+	}
+};

package/package.json

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