biz-a-cli 2.3.80-15367 → 2.3.80-15375

package/bin/app.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import "../envs/defaultEnv.js";
 import yargs from "yargs";
 import axios from "axios";
 import fs from "fs";

package/bin/deleteApp.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import "../envs/defaultEnv.js";
 import yargs from "yargs";
 import axios from "axios";
 import { logger } from "../logger.js";

package/bin/hub.js

@@ -1,9 +1,6 @@
 #!/usr/bin/env node
 
-if (!process.env.NODE_ENV) {
-	process.env.NODE_ENV = "production";
-}
-
+import "../envs/defaultEnv.js";
 import yargs from "yargs";
 import { io as ioClient } from "socket.io-client";
 import {

package/bin/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import "../envs/defaultEnv.js";
 import yargs from "yargs";
 import axios from "axios";
 import { promises as fs } from "fs";

package/bin/proxy.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import "../envs/defaultEnv.js";
 import express from 'express';
 import cors from 'cors';
 const app = express();

package/bin/uploadApp.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import "../envs/defaultEnv.js";
 import yargs from "yargs";
 import axios from "axios";
 import { promises as fs } from "fs";

package/bin/watcher.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import "../envs/defaultEnv.js";
 import express from 'express';
 import cors from 'cors';
 const app = express();

package/engine/domain/appConfig.js

@@ -9,6 +9,11 @@ import {
 	findRawColorsInStyles,
 	describeRawColorFindings,
 } from "./styleColors.js";
+import {
+	findImplicitNumericScale,
+	describeImplicitScaleFindings,
+	selectScaleRisks,
+} from "./numericScale.js";
 import { json2List } from "../orm/index.js";
 import { toDbName } from "./naming.js";
 import { logger } from "../../logger.js";
@@ -3242,6 +3247,49 @@ export const publishConfigs = async (payload = {}, argv = {}) => {
 			);
 		}
 
+		/*
+		 * ⚠️⚠️ WHICH `number` COLUMNS LET A DISPLAY HINT CHOOSE THEIR STORAGE PRECISION.
+		 *
+		 * `resolveColumnType` takes a column's scale from `uiIntent` when none is declared: 'currency'
+		 * gives 2, anything else gives 0. In Supertail that made `st_order`'s header BIGINT while the
+		 * order LINES it sums stayed NUMERIC(18,2), and made `tax_rate` unable to hold 11.5%.
+		 *
+		 * ⚠️ REPORT-ONLY, and scanned here beside the Style colours for the same reason: 204 `number`
+		 * attributes across biz-a-template declare no scale at all, so refusing a publish would make
+		 * the platform un-upgradable for every application that has the problem. The countable list is
+		 * the deliverable.
+		 *
+		 * ⚠️ Its own try/catch: a warning must never be the thing that fails a publish.
+		 */
+		try {
+			const implicitScale = findImplicitNumericScale(parseDomainConfig(domainConfigContent));
+			const scaleRisks = selectScaleRisks(implicitScale);
+			/*
+			 * ⚠️ ONLY THE RISKS ARE LISTED. The raw scan finds 158 columns in one real config and most
+			 * are legitimately whole (sequence_no, timeout_minutes, foreign keys) — printing them all
+			 * is how a check gets switched off. The rest is a count, so the number is never lost.
+			 */
+			if (scaleRisks.length > 0) {
+				logger.warn(
+					`[AppConfig Publish] ${scaleRisks.length} money/rate column(s) in ` +
+					`${domainName}@${domainVersion} resolve to a WHOLE-NUMBER type because no \`scale\` ` +
+					"is declared and uiIntent decides it (REPORT ONLY). These cannot hold cents or a " +
+					"fractional rate:",
+				);
+				describeImplicitScaleFindings(scaleRisks).forEach((line) => logger.warn(line));
+			}
+			if (implicitScale.length > 0) {
+				logger.warn(
+					`[AppConfig Publish] (${implicitScale.length} numeric column(s) in total take their ` +
+					"scale from uiIntent rather than declaring it.)",
+				);
+			}
+		} catch (error) {
+			logger.warn(
+				`[AppConfig Publish] could not scan numeric scales: ${error?.message ?? error}`,
+			);
+		}
+
 		/*
 		 * Doc 3 §11 — resolve the tenancy declaration across EVERY published domain, not just this one.
 		 *

package/engine/domain/domainNavigation.js

@@ -71,7 +71,25 @@ export const mergeDomainNavigation = ({ applicationConfig, domainKey, menus } =
 		let group = kept.find((g) => String(g?.caption ?? "") === groupCaption);
 		if (!group) {
 			group = { caption: groupCaption, link: [], subMenu: [] };
-			kept.push(group);
+			/*
+			 * ⚠️ WHERE a group the host does not have is placed. Appending is fine for one stray leaf
+			 * and wrong for a domain that owns a whole group: "HR, beside Setup" appended after every
+			 * group the host emits is a group at the BOTTOM of the menu, which is not what was asked
+			 * for and not where anyone looks.
+			 *
+			 * ⚠️ ON CREATION ONLY. Once the group exists, `kept.find` above keeps its position, and so
+			 * does the host's own injector, which concats into a group it finds rather than
+			 * re-appending. Every entry of a multi-screen domain therefore carries the same hint and
+			 * only the first one acts on it.
+			 *
+			 * ⚠️ AN ANCHOR THE HOST DOES NOT HAVE APPENDS. Declining to place the group would hide
+			 * every screen the domain owns — far worse than placing it last, and a domain cannot know
+			 * what groups its host happens to emit.
+			 */
+			const anchor = String(entry?.groupAfter ?? "").trim();
+			const at = anchor ? kept.findIndex((g) => String(g?.caption ?? "") === anchor) : -1;
+			if (at >= 0) kept.splice(at + 1, 0, group);
+			else kept.push(group);
 		}
 		if (!Array.isArray(group.subMenu)) group.subMenu = [];
 

package/engine/domain/numericScale.js

@@ -0,0 +1,113 @@
+/*
+ * ⚠️⚠️ WHICH `number` COLUMNS LET A PRESENTATION HINT CHOOSE THEIR STORAGE.
+ *
+ * `appConfig.js resolveColumnType` infers a column's scale from `uiIntent`: 'currency' gives 2, ANY
+ * other value gives 0 — so a money column labelled for DISPLAY silently becomes an integer, and the
+ * rounding is invisible until something produces a fraction.
+ *
+ * Found in Supertail, 2026-09-24: `st_order`'s header (`subtotal_amount`, `tax_amount`,
+ * `service_charge_amount`, `final_amount`) carried `uiIntent: 'label'` and became BIGINT, while the
+ * order LINES they sum kept NUMERIC(18,2) — one order, money at two precisions. And
+ * `st_finalisasi_profile.tax_rate` was BIGINT: 11% expressible, 11.5% silently truncated.
+ *
+ * ⚠️ WHY A REPORT AND NOT A RULE CHANGE. Measured across `biz-a-template`: 204 `type: 'number'`
+ * attributes, and NOT ONE declares an explicit `scale`. Flipping the inference today would drop the
+ * decimals on the 66 that currently rely on `uiIntent: 'currency'`. So the gap is made countable
+ * first, the configs state their storage over time, and only then can the default move. The same
+ * staging the raw-colour warning used (§10 point 3).
+ *
+ * ⚠️ REPORT-ONLY, ALWAYS. Refusing a publish would make the platform un-upgradable for exactly the
+ * applications that most need the fix — the argument styleColors.js already makes, and this file
+ * deliberately mirrors its shape so the two read as one idea.
+ */
+
+/* Everything here fails SOFT and returns a list: a warning must never fail a publish. */
+const entitiesOf = (config) => {
+	const entities = config?.model?.entities;
+	if (!entities || typeof entities !== "object" || Array.isArray(entities)) return [];
+	return Object.entries(entities);
+};
+
+/**
+ * Every `type: 'number'` attribute whose scale is INFERRED rather than declared.
+ *
+ * ⚠️ `uiIntent: 'currency'` is included too, deliberately. Those columns get the right storage for
+ * the wrong reason — a display hint — which is the coupling being retired. `resolved` says what each
+ * one becomes, so the two groups stay countable apart.
+ *
+ * Returns `[{ table, column, uiIntent, resolved }]`, or `[]` for anything it cannot read.
+ */
+export const findImplicitNumericScale = (config) => {
+	const findings = [];
+	for (const [entityName, entity] of entitiesOf(config)) {
+		const attributes = entity?.attributes;
+		if (!attributes || typeof attributes !== "object" || Array.isArray(attributes)) continue;
+		/* An entity may name no table; the entity key is what a reader would search for. */
+		const table = String(entity?.table ?? entityName);
+
+		for (const [column, attribute] of Object.entries(attributes)) {
+			if (!attribute || typeof attribute !== "object") continue;
+			if (String(attribute.type ?? "").toLowerCase() !== "number") continue;
+			/* Declared scale is the answer this check exists to encourage — including scale 0, which
+			   is a perfectly good statement that a column holds whole units. */
+			if (typeof attribute.scale === "number" && Number.isFinite(attribute.scale)) continue;
+
+			const uiIntent = String(attribute.uiIntent ?? "");
+			findings.push({
+				table,
+				column,
+				uiIntent: uiIntent || "(none)",
+				resolved:
+					uiIntent.toLowerCase() === "currency"
+						? `NUMERIC(${attribute.precision ?? attribute.size ?? 18},2)`
+						: "INTEGER/BIGINT",
+			});
+		}
+	}
+	return findings;
+};
+
+/*
+ * ⚠️⚠️ WHAT IS WORTH PRINTING AT EVERY PUBLISH — a much smaller set than what the scan finds.
+ *
+ * The raw scan reports 158 columns in Supertail alone, and most are legitimately whole: `sequence_no`,
+ * `timeout_minutes`, foreign-key `_id`s, `user_id`. A report that long is noise, and styleColors.js
+ * already records where noise leads: "false positives will make people switch the check off, along
+ * with the findings that were real". Named colours are excluded there for exactly this reason.
+ *
+ * So the publish prints the defect SHAPE that was actually found: a column whose NAME says money or
+ * rate, which nonetheless resolved to an integer. Everything else stays available from the scan and
+ * is summarised as a count.
+ *
+ * ⚠️ A column ending `_id` is a key however it is named — `payment_amount_id` is not money.
+ */
+const MONEY_OR_RATE = /(amount|price|total|subtotal|cost|fee|discount|paid|change|balance|tax|charge|rate|percent|pct)/i;
+const LOOKS_LIKE_KEY = /(^id$|_id$)/i;
+
+export const selectScaleRisks = (findings) =>
+	(Array.isArray(findings) ? findings : []).filter(
+		(f) =>
+			f?.resolved === "INTEGER/BIGINT" &&
+			MONEY_OR_RATE.test(String(f.column)) &&
+			!LOOKS_LIKE_KEY.test(String(f.column)),
+	);
+
+/* ⚠️ CAPPED. A report that dumps 204 lines is one nobody reads, and the point is that somebody
+   reads it. The tail says how many were hidden so the number is never lost. */
+const MAX_LINES = 20;
+
+export const describeImplicitScaleFindings = (findings) => {
+	const list = Array.isArray(findings) ? findings : [];
+	if (list.length === 0) return [];
+
+	const lines = list
+		.slice(0, MAX_LINES)
+		.map(
+			(f) =>
+				`  ${f.table}.${f.column}  uiIntent=${f.uiIntent}  ->  ${f.resolved}`,
+		);
+	if (list.length > MAX_LINES) {
+		lines.push(`  ... and ${list.length - MAX_LINES} more`);
+	}
+	return lines;
+};

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/connection.js

@@ -21,6 +21,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { logger } from "../../logger.js";
 
 /* ABSOLUTE, resolved from this module — NOT process.cwd(). The hub is routinely launched from
    another directory (a global `hub` binary, a service wrapper, `node cli/bin/hub.js` from the repo
@@ -257,11 +258,61 @@ export const PG_DATE_OID = 1082;
  */
 export const PG_BOOL_OID = 16;
 
+/*
+ * ⚠️⚠️ NUMERIC AND BIGINT MUST ARRIVE AS NUMBERS — the same argument as DATE and BOOL above, and the
+ * one that cost a real mis-priced screen.
+ *
+ * node-postgres hands arbitrary-precision types back as STRINGS so precision is never silently lost
+ * to IEEE-754. That is the right default for a general driver and the wrong one for an application
+ * written against what FINA sent, which was numbers. Left as strings, `a + b` CONCATENATES and
+ * `row.qty > 5` compares text.
+ *
+ * ⚠️ Live, 2026-09-23 (company bkd): `NUMERIC(18,2)` arrived as `"18000.00"` and the client read it
+ * as LOCALE text — Indonesian groups with `.` — so an 18,000 item rendered as Rp 1.800.000 on the
+ * screen used to cancel, void and refund. The display edge was fixed then; this fixes the shape.
+ */
+export const PG_NUMERIC_OID = 1700;
+export const PG_INT8_OID = 20;
+
+/*
+ * ⚠️⚠️ THE PRECISION RISK IS REAL, SO IT IS MADE LOUD RATHER THAN ASSUMED AWAY.
+ *
+ * A double represents every integer exactly only up to 2^53-1; `NUMERIC(18,2)` can hold more, which
+ * is exactly why node-pg returns strings. Measured on db 3 the largest real amount is 900,000 —
+ * roughly ten million times of headroom — but "today's data fits" is not a guarantee, and a value
+ * that does not fit must NOT be rounded in silence. That would be the same class of defect this
+ * change exists to remove, one layer down.
+ *
+ * ⚠️ IT WARNS, IT DOES NOT THROW. A type parser runs inside every row of every read; throwing would
+ * turn one oversized value into a failed query with no obvious cause.
+ *
+ * ⚠️ AND AN UNPARSEABLE VALUE IS HANDED BACK UNTOUCHED, never NaN. PostgreSQL's `numeric` accepts
+ * 'NaN' and the infinities; coercing those would spread a JS NaN through every sum that touched them
+ * with nothing to trace it to.
+ */
+const parseNumeric = (value) => {
+	if (value === null || value === undefined) return value;
+	const text = String(value);
+	const parsed = Number(text);
+	if (!Number.isFinite(parsed)) return value;
+
+	if (Math.abs(parsed) > Number.MAX_SAFE_INTEGER) {
+		logger.warn(
+			`[pg] ${text} exceeds the range a JavaScript number represents exactly ` +
+				`(±${Number.MAX_SAFE_INTEGER}); it has been read as ${parsed} and is no longer exact. ` +
+				"Handle this column as a string at the call site.",
+		);
+	}
+	return parsed;
+};
+
 export const registerPgTypeParsers = (pg) => {
 	pg.types.setTypeParser(PG_DATE_OID, (value) => value);
 	pg.types.setTypeParser(PG_BOOL_OID, (value) =>
 		value === null || value === undefined ? value : value === "t" ? 1 : 0,
 	);
+	pg.types.setTypeParser(PG_NUMERIC_OID, parseNumeric);
+	pg.types.setTypeParser(PG_INT8_OID, parseNumeric);
 };
 
 /* Registered once per process, at the same lazy point `pg` itself is first loaded — the parser is