biz-a-cli 2.3.80-15359 → 2.3.80-15367

package/bin/app.js

@@ -53,6 +53,7 @@ import {
 } from "../engine/domain/publishedAdditions.js";
 import { validateTenancyDeclaration } from "../engine/orm/tenancyDeclaration.js";
 import { logger } from "../logger.js";
+import { findRawColorsInSource } from "../engine/domain/styleColors.js";
 
 const getKeyFolderPath = () => {
 	const scriptPath =
@@ -1093,6 +1094,36 @@ async function addApp({
 				const scriptSource = bodyScripts.has(fileName)
 					? bodyScripts.get(fileName)
 					: fs.readFileSync(sourceFilePath).toString();
+				/*
+				 * Doc 6 §10 point 3 — raw colours in this library's own style declarations.
+				 *
+				 * ⚠️ SCANNED HERE BECAUSE NOTHING DOWNSTREAM CAN. `publishConfigs` reads the domain config
+				 * out of sys$config, and a library's styles never go there — they are emitted into
+				 * structures at publish. Measured on a real app, the config held 26 and the libraries 157,
+				 * and only the 26 were ever reported. This is the only point that has the source in hand.
+				 *
+				 * ⚠️ REPORT ONLY, like every other part of this check: a warning must never fail an upload.
+				 */
+				try {
+					const styleColors = findRawColorsInSource(scriptSource);
+					if (styleColors.length > 0) {
+						const total = styleColors.reduce((n, f) => n + f.colors.length, 0);
+						logger.warn(
+							`[Add] Doc 6 §10: ${total} raw colour(s) in ${fileName} style declarations ` +
+							`(REPORT ONLY). A Style wins over the theme, so these will NOT follow a company's ` +
+							`brand colour:`,
+						);
+						for (const f of styleColors.slice(0, 20)) {
+							logger.warn(`  ${fileName}:${f.line}  ${f.colors.join(', ')}`);
+						}
+						if (styleColors.length > 20) {
+							logger.warn(`  ... and ${styleColors.length - 20} more line(s) in ${fileName}`);
+						}
+					}
+				} catch (error) {
+					logger.warn(`[Add] could not scan ${fileName} for style colours: ${error?.message ?? error}`);
+				}
+
 				const preparedScript = await prepareScript(
 					fileName,
 					scriptSource,

package/bin/hub.js

@@ -368,6 +368,11 @@ app.use(
 		oidc: extDeps.oidc,
 		identityStore: extDeps.identityStore,
 		resolveTenant: extDeps.resolveTenant,
+		/* Doc 6 section 14 -- the anonymous theme + logo endpoints, and the PWA install card
+		   they now also feed. Absent on a FINA tenant, where those routes simply 404. */
+		getPublicTheme: extDeps.getPublicTheme,
+		getPublicLogo: extDeps.getPublicLogo,
+		getBranding: extDeps.getBranding,
 		/* Doc 3 section 11 -- without this the external surface has NO tenant context and the
 		   fail-closed default hides every multi-tenant row from it. */
 		withTenantScope: extDeps.withTenantScope,

package/engine/domain/appConfig.js

@@ -5,6 +5,10 @@ import { createHash } from "node:crypto";
 import * as firebirdDdl from "./firebird-ddl.js";
 import * as postgresDdl from "./postgres-ddl.js";
 import { ddlFor, isPostgresIndex, execPostgres } from "./dialect.js";
+import {
+	findRawColorsInStyles,
+	describeRawColorFindings,
+} from "./styleColors.js";
 import { json2List } from "../orm/index.js";
 import { toDbName } from "./naming.js";
 import { logger } from "../../logger.js";
@@ -3208,6 +3212,36 @@ export const publishConfigs = async (payload = {}, argv = {}) => {
 
 		const domainConfigContent = String(domainRecord.data);
 
+		/*
+		 * Doc 6 §10 point 3 — raw colours in a `Style` are reported here, with their locations.
+		 *
+		 * ⚠️ REPORT ONLY, exactly like the redundant-index report below: §10 point 3 says warning,
+		 * and it has to be — every existing application is full of raw colours today, so refusing
+		 * the publish would make the platform un-upgradable for the people who most need the fix.
+		 *
+		 * ⚠️ SCANNED HERE, BEFORE THE `tables.length === 0` EARLY RETURN. A domain that declares
+		 * only UI and no entities is exactly the kind that is all styles, and skipping it would
+		 * quietly exempt the configs with the most to report.
+		 *
+		 * ⚠️ Its own try/catch: a warning must never be the thing that fails a publish.
+		 */
+		let rawStyleColors = [];
+		try {
+			rawStyleColors = findRawColorsInStyles(parseDomainConfig(domainConfigContent));
+			if (rawStyleColors.length > 0) {
+				logger.warn(
+					`[AppConfig Publish] Doc 6 §10: ${rawStyleColors.length} raw colour(s) in Style ` +
+					`declarations of ${domainName}@${domainVersion} (REPORT ONLY). A Style wins over the ` +
+					`theme, so these will NOT follow a company's brand colour:`,
+				);
+				describeRawColorFindings(rawStyleColors).forEach((line) => logger.warn(line));
+			}
+		} catch (error) {
+			logger.warn(
+				`[AppConfig Publish] could not scan Style colours: ${error?.message ?? error}`,
+			);
+		}
+
 		/*
 		 * Doc 3 §11 — resolve the tenancy declaration across EVERY published domain, not just this one.
 		 *
@@ -3240,7 +3274,7 @@ export const publishConfigs = async (payload = {}, argv = {}) => {
 
 		const report = [];
 		if (preview.schema.tables.length === 0) {
-			return { success: true, domainName, domainVersion, tablesProcessed: 0, report };
+			return { success: true, domainName, domainVersion, tablesProcessed: 0, report, rawStyleColors };
 		}
 
 		/* An explicitly declared index can duplicate a foreign key just as the auto-generated one
@@ -3322,6 +3356,7 @@ export const publishConfigs = async (payload = {}, argv = {}) => {
 			tablesSkipped,
 			redundantIndexes,
 			orphanColumns,
+			rawStyleColors,
 			report,
 		};
 	} catch (error) {

package/engine/domain/contrast.js

@@ -135,19 +135,27 @@ export const nearestPassing = (foreground, background, { large = false, maxSteps
  * ⚠️ Checking every combination of twelve tokens would report failures for pairs nothing puts
  * together, and a check that cries wolf is one people learn to skip.
  *
- * ⚠️ `outlineColor` IS DELIBERATELY ABSENT, and the reason is a gap in Doc 6's vocabulary. WCAG
- * 1.4.11 wants 3:1 for a boundary that IDENTIFIES a control, but Material has two roles here —
- * `outline` (meaningful) and `outline-variant` (decorative divider) — with very different bars, and
- * §5 collapses both into one token. All three presets chose a pale value for it (~1.6:1 on white),
- * i.e. they mean the decorative role; enforcing 3:1 would refuse every shipped preset. The cost is
- * that a boundary which really does identify a control goes unchecked; the fix is a second
- * `outlineVariantColor` token, which is a Doc 6 change, not a code one.
+ * ⚠️⚠️ `outlineColor` IS CHECKED AT 3:1, NOT 4.5:1 — the WCAG 1.4.11 bar for a NON-TEXT boundary
+ * that identifies a control (the edge of a text input, the border of an outlined button). This is
+ * what the `true` in its row means.
+ *
+ * ⚠️ IT WAS SKIPPED ENTIRELY UNTIL 2026-09-23, and the reason is worth keeping. Material has TWO
+ * line roles with very different bars — `outline` (identifies a control) and `outline-variant` (a
+ * decorative divider) — and Doc 6 §5 originally collapsed them into one token. All three presets
+ * chose a pale value (~1.6:1 on white), i.e. they meant the decorative role, so enforcing 3:1 would
+ * have refused every shipped preset. §5 gained `outlineVariantColor`, the presets' pale values
+ * moved to it, and `outlineColor` took new values with real headroom (~3.3:1).
+ *
+ * ⚠️ `outlineVariantColor` IS STILL ABSENT, and must stay absent: WCAG sets no contrast requirement
+ * for a decorative line, and checking it would refuse every preset all over again.
  *
  * ⚠️ Kept identical to the client's `CHECKED_PAIRS` on purpose — one rule for Jalur A and Jalur B
  * (§7.1) means a theme accepted on save must not be refused at publish, or vice versa.
  */
 export const CHECKED_PAIRS = [
 	["onSurfaceColor", "surfaceColor", false],
+	/* ⚠️ `true` = the 3:1 boundary bar (WCAG 1.4.11), not the 4.5:1 text bar. */
+	["outlineColor", "surfaceColor", true],
 	["onSurfaceColor", "surfaceContainerColor", false],
 	["onPrimaryColor", "primaryColor", false],
 	["primaryColor", "surfaceColor", false],

package/engine/domain/styleColors.js

@@ -0,0 +1,235 @@
+/*
+ * Doc 6 §10 point 3 — raw colours in a `Style` produce a WARNING at publish, with the list of
+ * locations to fix.
+ *
+ * ⚠️⚠️ WHY THIS MATTERS MORE THAN IT LOOKS. §10 point 4 makes `Style` WIN over the theme for its
+ * component. So when a company changes its brand colour, a screen carrying hard-coded hex values
+ * comes back half re-themed: the Material components follow, the styled ones do not. That reads as
+ * broken rather than merely unbranded — and nobody can tell which screens are at fault, because a
+ * raw colour is invisible until somebody changes the theme it was supposed to follow.
+ *
+ * ⚠️ A WARNING, NEVER A REFUSAL. Every existing application is full of raw colours today — the
+ * Tahap 0 scan counted 740 overrides across 36 projects. Refusing a publish would make the platform
+ * un-upgradable for the people who most need the fix. The LIST OF LOCATIONS is the deliverable: it
+ * turns "your styles are wrong somewhere" into work somebody can actually do.
+ *
+ * ⚠️ PLATFORM CODE, SO IT IS SHAPE-DRIVEN, NOT APP-DRIVEN. It knows only that a `style` object maps
+ * CSS properties to values; no application, screen or token name is written into it.
+ */
+
+/*
+ * ⚠️ EXACTLY THE HEX SHAPES CSS ACCEPTS — 3, 4, 6 or 8 digits — longest first so `#aabbccdd` is
+ * not read as `#aabbcc` followed by junk. Matching a loose {3,8} would also accept `#12345`, which
+ * is not a colour at all, and a check that reports non-colours is a check people learn to ignore.
+ */
+const HEX = /#(?:[0-9a-f]{8}|[0-9a-f]{6}|[0-9a-f]{4}|[0-9a-f]{3})\b/gi;
+
+/** `rgb(`, `rgba(`, `hsl(`, `hsla(` — the functional notations, wherever they appear in a value. */
+const FUNCTIONAL = /\b(?:rgba?|hsla?)\s*\([^)]*\)/gi;
+
+/*
+ * ⚠️ A `var()` FALLBACK IS NOT A RAW COLOUR. `var(--mat-sys-primary, #1B5FCB)` still follows the
+ * theme — the hex applies only if the token is missing, which is defensive spelling, not a
+ * hard-coded colour. Flagging it would punish the more careful author, so `var(...)` is removed
+ * before scanning.
+ *
+ * ⚠️ Non-greedy to the FIRST `)`, so it does not swallow the rest of a multi-value declaration:
+ * `0 0 0 1px var(--x), 0 2px 4px #00000022` must still report the hex. The cost is that a nested
+ * `var(--a, var(--b, #fff))` leaves a stray `#fff` visible — rare, and erring towards reporting.
+ */
+const VAR_CALL = /\bvar\s*\([^()]*\)/gi;
+
+/*
+ * ⚠️ NAMED COLOURS ARE DELIBERATELY NOT MATCHED. §10 point 3 says "hex/rgb", and the words that
+ * would have to be matched — `white`, `black`, `red` — also occur in class names, font families and
+ * content strings. A keyword list would report correct code, and a check with false positives gets
+ * switched off, taking the true positives with it.
+ */
+
+/*
+ * ⚠️⚠️ A `template` IS A STYLESHEET TOO — the second blind spot this check had.
+ *
+ * Structures carry raw HTML strings with inline `style="..."` attributes, and 48 of them lived in
+ * ONE console structure while this reported none: the scan only understood a key literally named
+ * `style`. So it is the CONTENT that decides, not the field name — the same markup turns up under
+ * `template`, `label`, `html` and unnamed fields.
+ *
+ * ⚠️ ONLY THE ATTRIBUTE, NEVER THE WHOLE STRING. Markup is full of things shaped like colours that
+ * are not: `href="#abc123"`, an element id, the word "#ffffff" in visible prose. Grepping the
+ * document would report all of them, and a check with false positives gets switched off.
+ */
+const STYLE_ATTR = /style\s*=\s*("([^"]*)"|'([^']*)')/gi;
+
+const styleAttributeText = (markup) => {
+	const parts = [];
+	let m;
+	STYLE_ATTR.lastIndex = 0;
+	while ((m = STYLE_ATTR.exec(markup)) !== null) {
+		parts.push(m[2] !== undefined ? m[2] : m[3] || "");
+	}
+	return parts.join(" ; ");
+};
+
+const isPlainObject = (v) =>
+	typeof v === "object" && v !== null && !Array.isArray(v);
+
+/*
+ * The key whose object is a CSS map. Everything else in a config is left alone.
+ *
+ * ⚠️ `style`, NOT `styles`. The real shape is `styles.<ref>.<variant>.style.<prop>` — `styles` is a
+ * namespace of style refs, and only the inner `style` object holds CSS. Treating the whole `styles`
+ * subtree as CSS flagged `className: 'card-#ffffff'` as a raw colour, which is exactly the kind of
+ * false positive that gets a check switched off.
+ */
+const STYLE_KEYS = new Set(["style"]);
+
+/**
+ * Raw colours in one CSS value, or `[]`.
+ *
+ * ⚠️ Order preserved and duplicates kept as written: the author is going to read this list against
+ * their own declaration, and reordering it makes that harder than it needs to be.
+ */
+export const rawColorsIn = (value) => {
+	if (typeof value !== "string" || value === "") return [];
+	const scannable = value.replace(VAR_CALL, " ");
+	return [
+		...(scannable.match(HEX) || []),
+		...(scannable.match(FUNCTIONAL) || []),
+	];
+};
+
+/**
+ * Every raw colour inside the config's `Style` declarations.
+ *
+ * @returns `[{ path, property, value, colors }]` — `path` is the dotted location in the config, so
+ *          the author can go straight to it.
+ *
+ * ⚠️ NEVER THROWS. This runs inside publish, on data that may be any shape at all; a scan that
+ * failed would take down a publish for the sake of a warning.
+ */
+export const findRawColorsInStyles = (config) => {
+	const findings = [];
+	if (!isPlainObject(config)) return findings;
+
+	const walk = (node, path, inStyle) => {
+		if (Array.isArray(node)) {
+			node.forEach((item, i) => walk(item, `${path}[${i}]`, inStyle));
+			return;
+		}
+		if (isPlainObject(node)) {
+			for (const [key, value] of Object.entries(node)) {
+				walk(
+					value,
+					path ? `${path}.${key}` : key,
+					/* Sticky: a CSS map is flat, but staying true costs nothing and covers a nested
+					   value should one ever appear. */
+					inStyle || STYLE_KEYS.has(key),
+				);
+			}
+			return;
+		}
+		if (typeof node !== "string") return;
+		/* Inside a `style` map every value is CSS; anywhere else, only what a style ATTRIBUTE holds. */
+		const scannable = inStyle ? node : styleAttributeText(node);
+		const colors = rawColorsIn(scannable);
+		if (colors.length === 0) return;
+		const lastDot = path.lastIndexOf(".");
+		findings.push({
+			path,
+			property: lastDot >= 0 ? path.slice(lastDot + 1) : path,
+			value: String(node),
+			colors,
+		});
+	};
+
+	try {
+		walk(config, "", false);
+	} catch {
+		/* A cyclic or otherwise hostile config costs the warning, not the publish. */
+		return findings;
+	}
+	return findings;
+};
+
+/**
+ * The lines the publisher prints — §10 point 3's "daftar lokasi yang perlu diperbaiki".
+ *
+ * ⚠️ THE PATH IS THE DELIVERABLE. A count ("12 raw colours found") tells nobody what to change; the
+ * dotted path takes them to the exact declaration.
+ */
+export const describeRawColorFindings = (findings) => {
+	const list = Array.isArray(findings) ? findings : [];
+	if (list.length === 0) return [];
+	return list.map(
+		(f) =>
+			`  ${f.path}: ${f.colors.join(", ")}  (value: ${f.value})` +
+			`  - use a theme token, e.g. var(--mat-sys-primary)`,
+	);
+};
+
+/*
+ * ⚠️⚠️ THE THIRD POPULATION: styles written in APPLICATION SOURCE rather than in the domain config.
+ *
+ * Screens are also built by app libraries — JavaScript returning `{ style: {...} }` structures at
+ * publish time. Those colours never enter `sys$config`, so `findRawColorsInStyles` could not see
+ * them however well it scanned: there is nothing to walk. Measured on a real application, the
+ * config held 26 and the libraries held 157, and only the 26 were ever reported. A list that is six
+ * times short is worse than no list — it says the work is nearly done when it has barely started.
+ *
+ * ⚠️ TEXT, NOT A TREE, so this reports a LINE NUMBER. "Somewhere in a 4000-line library" is not a
+ * location anybody can act on.
+ */
+
+/* Comments blanked but every newline kept, so the reported line stays true. Counting colours in
+   prose is what inflated an early estimate of this very population from 157 to 347. */
+const NEWLINE = String.fromCharCode(10);
+const blankComments = (text) =>
+	text
+		.replace(/\/\*[\s\S]*?\*\//g, (m) =>
+			m.split(NEWLINE).map((line) => " ".repeat(line.length)).join(NEWLINE),
+		)
+		.replace(/(^|[^:])\/\/.*/g, (m, p1) => p1 + " ".repeat(m.length - p1.length));
+
+/** `style: { ... }` and `style: '...'` — the two shapes real configs and libraries both use. */
+const SOURCE_STYLE = /style\s*:\s*(\{[^{}]*\}|'[^']*'|"[^"]*")/g;
+
+/**
+ * Raw colours in a JavaScript/TypeScript source file's style declarations.
+ *
+ * @returns `[{ line, colors, snippet }]`
+ *
+ * ⚠️ NEVER THROWS, for the same reason as the object scan: this runs during a publish, and a
+ * warning must never be the thing that fails one.
+ */
+export const findRawColorsInSource = (source) => {
+	const findings = [];
+	if (typeof source !== "string" || source === "") return findings;
+
+	try {
+		const text = blankComments(source);
+		const lineAt = (index) => text.slice(0, index).split(NEWLINE).length;
+
+		const record = (index, scannable, snippet) => {
+			const colors = rawColorsIn(scannable);
+			if (colors.length === 0) return;
+			findings.push({ line: lineAt(index), colors, snippet: snippet.slice(0, 120) });
+		};
+
+		SOURCE_STYLE.lastIndex = 0;
+		let m;
+		while ((m = SOURCE_STYLE.exec(text)) !== null) {
+			record(m.index, m[1], m[0]);
+		}
+
+		/* Markup the source emits — the same style-attribute rule as the object scan. */
+		STYLE_ATTR.lastIndex = 0;
+		while ((m = STYLE_ATTR.exec(text)) !== null) {
+			record(m.index, m[2] !== undefined ? m[2] : m[3] || "", m[0]);
+		}
+	} catch {
+		return findings;
+	}
+
+	/* One order, by position, so a reader can walk the file top to bottom. */
+	return findings.sort((a, b) => a.line - b.line);
+};

package/engine/domain/theme-presets.json

@@ -36,6 +36,10 @@
 					"dark": "#E4E8EF"
 				},
 				"outlineColor": {
+					"light": "#878C96",
+					"dark": "#636A76"
+				},
+				"outlineVariantColor": {
 					"light": "#C5CBD6",
 					"dark": "#454C59"
 				},
@@ -98,6 +102,10 @@
 					"dark": "#E3E6E0"
 				},
 				"outlineColor": {
+					"light": "#8B8B84",
+					"dark": "#666A66"
+				},
+				"outlineVariantColor": {
 					"light": "#C9C7BD",
 					"dark": "#474B47"
 				},
@@ -160,6 +168,10 @@
 					"dark": "#E8EAEE"
 				},
 				"outlineColor": {
+					"light": "#888C94",
+					"dark": "#62676F"
+				},
+				"outlineVariantColor": {
 					"light": "#B9BEC7",
 					"dark": "#3C424B"
 				},

package/engine/domain/themeConfig.js

@@ -46,6 +46,7 @@ const TOKEN_KEYS = [
 	"surfaceContainerColor",
 	"onSurfaceColor",
 	"outlineColor",
+	"outlineVariantColor",
 	"errorColor",
 	"warningColor",
 	"successColor",

package/engine/ext/live.js

@@ -22,14 +22,39 @@ import { createOidcService } from "./oidc.js";
 import { OIDC_ENDPOINTS, makeOidcProvider } from "./providers.js";
 import { makeTokenExchange, makeIdTokenVerifier } from "./oidcHttp.js";
 import { mintT1 } from "./token.js";
+import {
+	createPublicThemeReader,
+	createPublicLogoReader,
+	brandingFromPublicTheme,
+} from "./publicTheme.js";
 import { createAllTenantScope } from "../orm/tenantScope.js";
 import { execPostgres, isPostgresIndex } from "../domain/dialect.js";
+import { nextGeneratorValue } from "../orm/dialect.js";
 
 const DEFAULT_FINA_URL = "http://127.0.0.1:212";
 
 // Next value from a Firebird generator (for SYS$EXT_USER ids). Mirrors datalib.genId's
 // endpoint without importing datalib (which pulls the worker pool + watcher).
+//
+// ⚠️ ON POSTGRESQL THERE IS NO GENERATOR AND NO FINA TO ASK. The migrations translate
+// `<TABLE>_GEN` + BI trigger into an IDENTITY column, so this call could only ever fail — the same
+// defect the admin client's `genId` hit live ("add user group" -> ECONNREFUSED 127.0.0.1:212), in a
+// second hand-rolled copy. Shared with apiRoute.js through `nextGeneratorValue` so the two cannot
+// drift; the Firebird branch below is untouched.
 async function genId(cfg, genName) {
+	if (isPostgresIndex(cfg.dbindex)) {
+		const { sequence, value } = await nextGeneratorValue({
+			exec: execPostgres,
+			dbIndex: cfg.dbindex,
+			generator: genName,
+		});
+		if (sequence === null) {
+			throw new Error(
+				`no sequence backs generator ${genName} on database ${cfg.dbindex}`,
+			);
+		}
+		return value;
+	}
 	const url = `${cfg.url}/fina/rest/TOrmMethod/genId/${genName}/${cfg.dbindex}`;
 	const res = await axios.get(url, {
 		headers: { "content-type": "text/plain" },
@@ -280,10 +305,42 @@ export function createLiveExtDeps({
 		? createAllTenantScope({ exec: execPostgres, dbIndex: dbindex })
 		: (fn) => fn();
 
+	/*
+	 * Doc 6 §14 — the ANONYMOUS theme + logo endpoints, for a customer who has scanned a QR code
+	 * and has no session yet. Both read through an allowlist of `sys$config` names and nothing else
+	 * (see publicTheme.js); the router exposes them at GET /ext/{slug}/theme and /logo.
+	 *
+	 * ⚠️ POSTGRESQL ONLY, like every other part of the theming feature: `execPostgres` is the path
+	 * these readers take, and on a FINA tenant the company theme is not stored here at all. On such
+	 * a tenant the hooks are simply absent and the routes 404 — the same way the whole boundary
+	 * 404s until a tenant is provisioned, rather than failing in some new way of its own.
+	 */
+	const themeExecFor = (tenant) => (sql) => execPostgres(sql, tenant.dbindex);
+	const themingAvailable = isPostgresIndex(dbindex);
+
+	const getPublicTheme = themingAvailable
+		? createPublicThemeReader({ resolveTenant, execFor: themeExecFor })
+		: undefined;
+	const getPublicLogo = themingAvailable
+		? createPublicLogoReader({ resolveTenant, execFor: themeExecFor })
+		: undefined;
+
+	/*
+	 * ⚠️ AND THIS FINALLY FEEDS `getBranding`, which has been an injected hook with no supplier
+	 * since M10 — so every tenant's PWA install card has read "Biz-A · {slug}" in Material's
+	 * default blue. Same payload, same read; see brandingFromPublicTheme.
+	 */
+	const getBranding = getPublicTheme
+		? async (slug) => brandingFromPublicTheme(await getPublicTheme(slug))
+		: undefined;
+
 	return {
 		resolveTenant,
 		getManifest: manifestStore.loadManifest,
 		getAppBundle: appBundle.getAppBundle,
+		getPublicTheme,
+		getPublicLogo,
+		getBranding,
 		auditSink,
 		identityStore,
 		oidc,

package/engine/ext/publicTheme.js

@@ -0,0 +1,268 @@
+/*
+ * Doc 6 §14 — the PUBLIC theme, for a customer who is not signed in.
+ *
+ * §14 describes a customer scanning a QR code at a table or opening a link to a merchant's menu.
+ * There is no session yet, so the normal theme path — which reads `sys$config` through an
+ * authenticated command — cannot run; §14 point 1 calls for "endpoint publik yang mengembalikan
+ * tema dan logo berdasarkan company/outlet di URL".
+ *
+ * ⚠️⚠️ §14 POINT 2 IS THE WHOLE SECURITY STORY. "Endpoint tersebut hanya boleh mengembalikan data
+ * tampilan (token, logo, nama). Tidak boleh membocorkan konfigurasi lain dari `sys$config`."
+ *
+ * That table is not a theme table. It holds APPLICATION_CONFIG, every domain's declarations, the
+ * per-entity DDL hashes and the publish status — the entire shape of the tenant's system. This
+ * endpoint is reachable by anyone who knows a slug, with no token and no login, so the reader must
+ * never ASK for anything outside an exact allowlist of names. A filter applied to a fetched row
+ * would be one refactor away from leaking; a query that was never issued cannot.
+ *
+ * ⚠️ IT RETURNS THE STORED LEVELS, NOT A RESOLVED PALETTE. The client already owns the resolver
+ * (`theme-resolver.ts`) and the seed→palette generator (`palette.ts`, which needs HCT and is not
+ * available here). Sending levels keeps ONE implementation of the merge — §8.1 point 3's reason for
+ * storing a diff rather than an expansion applies just as much on the wire.
+ */
+import { APPLICATION_THEME_NAME } from "../domain/themeConfig.js";
+import { resolveThemeTokens } from "../domain/themePresets.js";
+import { COMPANY_THEME_NAME } from "../orm/companyTheme.js";
+import {
+	COMPANY_LOGO_NAME,
+	readCompanyLogo,
+	parseLogoDataUrl,
+} from "../orm/companyLogo.js";
+
+/**
+ * ⚠️⚠️ THE BOUNDARY. Every `sys$config` name this endpoint may ever name, and it is exported so a
+ * test can assert that nothing else is asked for. Adding a name here is a security decision: the
+ * value becomes readable by the anonymous public.
+ */
+export const PUBLIC_THEME_KEYS = [
+	APPLICATION_THEME_NAME,
+	COMPANY_THEME_NAME,
+	COMPANY_LOGO_NAME,
+];
+
+/*
+ * ⚠️ §14 POINT 5 — WHAT `system` MEANS IN A CUSTOMER'S BROWSER.
+ *
+ * "Perlu diputuskan apakah `colorScheme: system` mengikuti preferensi device pelanggan atau
+ * dipaksa mengikuti pilihan merchant." The decision recorded there: the customer channel follows
+ * the MERCHANT. A customer whose phone happens to be in dark mode would otherwise see the
+ * merchant's menu in dark — the merchant's branding, decided by a stranger's OS setting.
+ *
+ * `system` is the merchant declining to choose, so there is nothing to follow; this falls back to
+ * the same LIGHT that §4.3 note 1 makes the level-1 fallback, rather than inventing a third rule.
+ */
+const CUSTOMER_SCHEME_FOR_SYSTEM = "light";
+
+const isPlainObject = (v) =>
+	typeof v === "object" && v !== null && !Array.isArray(v);
+
+/*
+ * ⚠️ A STORED THEME IS DATA AND MAY BE MALFORMED (§8.1 point 1, AC 26) — hand-edited, or written by
+ * an older shape. Degrading to "no theme at this level" costs branding on one screen; throwing would
+ * take the endpoint down for every customer of every merchant on this hub.
+ */
+const parseTheme = (raw) => {
+	if (raw == null || raw === "") return null;
+	if (isPlainObject(raw)) return raw;
+	try {
+		const parsed = JSON.parse(String(raw));
+		return isPlainObject(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+};
+
+const forCustomer = (theme) => {
+	if (!theme) return null;
+	/* Applied at BOTH levels: the merge is per key, so an application-level `system` surfaces
+	   whenever the company has not set one of its own. */
+	return theme.colorScheme === "system"
+		? { ...theme, colorScheme: CUSTOMER_SCHEME_FOR_SYSTEM }
+		: theme;
+};
+
+/**
+ * Build the anonymous theme reader.
+ *
+ * @param resolveTenant  slug → tenant, or null. ⚠️ THE SLUG IS NOT A CREDENTIAL, but it must still
+ *                       name a tenant this hub serves: an unknown slug gets `null`, never another
+ *                       merchant's branding.
+ * @param execFor        tenant → an `exec(sql)` bound to that tenant's database, mirroring the
+ *                       `{exec}` shape `readCompanyTheme`/`readCompanyLogo` already take.
+ */
+export const createPublicThemeReader = ({ resolveTenant, execFor }) => {
+	return async (slug) => {
+		const tenant = resolveTenant ? await resolveTenant(slug) : null;
+		if (resolveTenant && !tenant) return null;
+
+		const exec = execFor(tenant);
+
+		/*
+		 * ⚠️ ONE QUERY PER ALLOWLISTED NAME, each spelling its name as a literal. There is no code
+		 * path here that takes a name from the request — the customer cannot ask for a fourth row.
+		 *
+		 * ⚠️ ORDER BY ID for the same reason `readCompanyTheme` has it: SYS$CONFIG's only constraint
+		 * is PRIMARY KEY (id), so nothing stops a duplicate, and picking the lowest id beats picking
+		 * whichever row the planner returned.
+		 */
+		const readOne = async (name, columns) => {
+			try {
+				const rows = await exec(
+					`SELECT ${columns} FROM SYS$CONFIG WHERE NAME = '${name}' ORDER BY ID`,
+				);
+				return Array.isArray(rows) ? rows[0] || null : null;
+			} catch {
+				/* ⚠️ A database that is down must not 500 the customer's first paint. They get the
+				   level-1 fallback, which is what an unbranded merchant looks like anyway. */
+				return null;
+			}
+		};
+
+		const [applicationRow, companyRow, logoRow] = await Promise.all([
+			readOne(APPLICATION_THEME_NAME, "ID, DATA"),
+			readOne(COMPANY_THEME_NAME, "ID, DATA"),
+			/*
+			 * ⚠️ ID ONLY — EXISTENCE, NOT THE IMAGE (§8.2 point 3, §14 point 3). A logo is up to 2 MB
+			 * and base64 inflates it by a third; carrying it inside the theme payload would put a
+			 * multi-megabyte download in front of a customer's first paint, on mobile data, every
+			 * time the theme is read. The image has its own endpoint and its own cache lifetime.
+			 */
+			readOne(COMPANY_LOGO_NAME, "ID"),
+		]);
+
+		const application = forCustomer(
+			parseTheme(applicationRow?.DATA ?? applicationRow?.data ?? null),
+		);
+		const company = forCustomer(
+			parseTheme(companyRow?.DATA ?? companyRow?.data ?? null),
+		);
+
+		return {
+			application,
+			company,
+			/* The merchant's display name, company level first — §14 point 2 names it as one of the
+			   three things a customer is allowed to see. */
+			name: company?.name ?? application?.name ?? null,
+			hasLogo: logoRow !== null,
+		};
+	};
+};
+
+/*
+ * ⚠️⚠️ THE STORED-SVG HAZARD, AND WHY THE LOGO COMES BACK AS JSON.
+ *
+ * §8.2 point 2 allows SVG, and it is the right format for a logo: one small file, sharp at every
+ * size. But an SVG is a DOCUMENT. Loaded through `<img src>` it is inert; served as `image/svg+xml`
+ * and opened as a TOP-LEVEL NAVIGATION it runs its own `<script>` in the origin that served it —
+ * and the file behind it was uploaded by a company admin, since `writeCompanyLogo` checks the media
+ * type and the size but never the markup inside.
+ *
+ * The first version of this endpoint returned the raw bytes under a `sandbox` CSP, which closes
+ * that. ⚠️ IT DOES NOT SURVIVE THE PRODUCTION TRANSPORT. In production the CLI never faces the
+ * browser: biz-a relays `/ext/{slug}/*` over a hub socket and returns `{status, contentType, body}`
+ * (`biz-a/src/hubController.js`) — EVERY OTHER RESPONSE HEADER IS DROPPED, the CSP among them. So
+ * the protection would have been present in every test and absent in production, on biz-a's own
+ * origin. (The relay would also have corrupted the bytes: `hubProxy.js` re-issues through axios as
+ * JSON, which decodes a PNG as UTF-8 text.)
+ *
+ * So the image travels as a base64 data URL inside an `application/json` body. A browser pointed at
+ * this URL gets JSON and renders text; the client puts the data URL in an `<img src>`, where SVG
+ * never executes script. The hazard is closed by the SHAPE of the response rather than by a header
+ * that a transport in the middle is free to discard.
+ *
+ * The headers below are still sent — they cost nothing and they do apply on the direct path, where
+ * the client reaches this router itself — but nothing depends on them any more.
+ */
+export const LOGO_RESPONSE_HEADERS = {
+	"Content-Security-Policy":
+		"default-src 'none'; script-src 'none'; style-src 'unsafe-inline'; sandbox",
+	"X-Content-Type-Options": "nosniff",
+	/* ⚠️ §14 point 3 — the logo is the largest thing a customer downloads and it changes about once
+	   a year. An hour is short enough that a rebrand is visible the same day. ⚠️ Also dropped by the
+	   relay, so the CLIENT caches this per slug rather than relying on it. */
+	"Cache-Control": "public, max-age=3600",
+};
+
+/**
+ * Build the anonymous logo reader.
+ *
+ * ⚠️ RETURNS THE DATA URL, not bytes — see the note above on why the response is JSON.
+ *
+ * ⚠️ VALIDATION IS `readCompanyLogo`'s, unchanged: it re-checks the media type on the way out, so a
+ * row hand-edited in the database cannot turn this into a serve-anything endpoint. That check is now
+ * load-bearing rather than belt-and-braces, since the response carries no policy of its own.
+ */
+export const createPublicLogoReader = ({ resolveTenant, execFor }) => {
+	return async (slug) => {
+		const tenant = resolveTenant ? await resolveTenant(slug) : null;
+		if (resolveTenant && !tenant) return null;
+
+		let dataUrl = null;
+		try {
+			dataUrl = await readCompanyLogo({ exec: execFor(tenant) });
+		} catch {
+			return null;
+		}
+
+		const parsed = dataUrl ? parseLogoDataUrl(dataUrl) : null;
+		if (!parsed) return null;
+
+		return { contentType: parsed.contentType, dataUrl: parsed.dataUrl };
+	};
+};
+
+/*
+ * The per-tenant PWA install card (webmanifest.js, PW-2) — `createExtRouter`'s `getBranding` hook.
+ *
+ * ⚠️ THAT HOOK HAS BEEN DEAD SINCE M10: it is an injected parameter that nothing ever supplied, so
+ * every tenant's install prompt has read "Biz-A · {slug}" in Material's default blue. The public
+ * theme is the missing source — §14's "nama, logo, tema" is precisely what an install card shows.
+ *
+ * ⚠️⚠️ THE COMPANY LEVEL IS USED WHOLE, NOT MERGED WITH THE APPLICATION'S. The real resolver has a
+ * rule this deliberately does NOT re-implement — §4.3's "a named preset REPLACES the palette, it
+ * does not blend with the level above" — and a second, subtly different merge living in the CLI is
+ * exactly the duplication this endpoint avoids by sending levels to the client. An install card
+ * needs a name and two colours; it does not need its own resolver.
+ */
+export const brandingFromPublicTheme = (payload) => {
+	if (!isPlainObject(payload)) return {};
+
+	const level = payload.company ?? payload.application;
+	if (!isPlainObject(level)) {
+		return payload.name ? { name: payload.name } : {};
+	}
+
+	/* `system` is already resolved to a definite scheme by the reader (§14 point 5); this is the
+	   same fallback for a level that never named one. */
+	const scheme = level.colorScheme === "dark" ? "dark" : "light";
+
+	/* ⚠️ A token is EITHER a `{light, dark}` pair or a single colour — an override may legitimately
+	   supply one value for both. Assuming the pair is what an AOT build once caught at the same
+	   spot in the client. */
+	const pick = (token) => {
+		if (typeof token === "string") return token;
+		return isPlainObject(token) ? token[scheme] || null : null;
+	};
+
+	const tokens = resolveThemeTokens(level) || {};
+
+	return {
+		...(payload.name ? { name: payload.name } : {}),
+		...(pick(tokens.primaryColor) ? { themeColor: pick(tokens.primaryColor) } : {}),
+		...(pick(tokens.surfaceColor)
+			? { backgroundColor: pick(tokens.surfaceColor) }
+			: {}),
+		/*
+		 * ⚠️ NO ICON FROM THE LOGO, deliberately, even though `hasLogo` is right there. A PWA icon
+		 * must declare its `sizes`, and declaring the wrong ones makes the app UNINSTALLABLE —
+		 * worse than a default icon.
+		 *
+		 * ⚠️ AND THE SERVER CANNOT MEASURE IT. It stores a base64 data URL, not a decoded image;
+		 * learning the dimensions here would mean an image library in `cli`, on every tenant's hub,
+		 * to produce an install-card nicety. (§8.2 point 4's resize now caps the LONG edge at 512
+		 * and preserves aspect ratio, so the result is usually not square either — which is what a
+		 * maskable icon wants.) If this is ever worth doing, store the dimensions at upload time,
+		 * where they are already known.
+		 */
+	};
+};

package/engine/ext/routes.js

@@ -11,6 +11,7 @@ import { anonymousOperationNames } from "./manifest.js";
 import { makeExtDispatch, EXT_ERROR_STATUS } from "./dispatch.js";
 import { buildExtWebManifest } from "./webmanifest.js";
 import { createRateLimiter } from "./rateLimit.js";
+import { LOGO_RESPONSE_HEADERS } from "./publicTheme.js";
 
 // Real source IP behind the hub/tunnel: first hop of X-Forwarded-For, else the socket peer.
 function clientIp(req) {
@@ -35,6 +36,8 @@ export function createExtRouter({
 	resolveTenant,
 	getChannelInfo,
 	getBranding,
+	getPublicTheme,
+	getPublicLogo,
 	rateLimit,
 	withTenantScope,
 }) {
@@ -113,6 +116,58 @@ export function createExtRouter({
 			.json(buildExtWebManifest(slug, branding));
 	});
 
+	// Doc 6 §14 — GET /ext/:slug/theme. ANONYMOUS, like manifest.webmanifest: a customer who has
+	// scanned a QR code has no token yet, and the page must be branded before anything else
+	// happens (§14 point 4). It returns the stored theme LEVELS, which the client resolves with
+	// its own resolver + palette generator — one implementation of the merge, not two.
+	//
+	// ⚠️⚠️ AC 18: display data ONLY. The reader (publicTheme.js) is allowlist-driven and never asks
+	// sys$config for anything but the theme keys; this route adds NOTHING of its own — no tenant
+	// record, no manifest, no dbindex. Merging in "context" here is how an allowlisted reader
+	// quietly stops being enough.
+	router.get("/theme", async (req, res) => {
+		const { slug } = req.params;
+		if (!getPublicTheme) return fail(res, 404, "NOT_FOUND");
+		let theme = null;
+		try {
+			theme = await getPublicTheme(slug);
+		} catch {
+			// ⚠️ A reader that throws must not become a 500 on a customer's first paint — they get
+			// the level-1 fallback, which is what an unbranded merchant looks like anyway.
+			theme = null;
+		}
+		if (!theme) return fail(res, 404, "NOT_FOUND");
+		// Short: a company theme changes rarely but an admin editing it wants to see it, and this
+		// is small JSON. The LOGO is the one worth caching hard (LOGO_RESPONSE_HEADERS).
+		res.set("Cache-Control", "public, max-age=60");
+		return res.status(200).json(theme);
+	});
+
+	// Doc 6 §8.2 point 3 + §14 point 3 — GET /ext/:slug/logo, SEPARATE from the theme so a
+	// multi-megabyte image is not carried in front of the customer's first paint.
+	//
+	// ⚠️⚠️ JSON, NOT AN IMAGE RESPONSE, AND THAT IS THE SECURITY DECISION. The stored file may be an
+	// SVG (§8.2 point 2 allows it), and an SVG served as image/svg+xml runs its own <script> when a
+	// browser navigates straight to it. Serving it under a `sandbox` CSP would close that — except
+	// biz-a's relay forwards only {status, contentType, body} and drops every other header, so the
+	// CSP would exist in tests and be absent in production. A base64 data URL inside JSON cannot be
+	// navigated into an executing document at all. See LOGO_RESPONSE_HEADERS in publicTheme.js.
+	router.get("/logo", async (req, res) => {
+		const { slug } = req.params;
+		if (!getPublicLogo) return fail(res, 404, "NOT_FOUND");
+		let logo = null;
+		try {
+			logo = await getPublicLogo(slug);
+		} catch {
+			logo = null;
+		}
+		if (!logo) return fail(res, 404, "NOT_FOUND");
+		/* Defence in depth on the DIRECT path (local, or a client that reaches this router itself);
+		   the relay drops them, which is why the JSON shape is what the safety rests on. */
+		res.set(LOGO_RESPONSE_HEADERS);
+		return res.status(200).json(logo);
+	});
+
 	// GET /ext/:slug/app — the tenant's external app bundle (SYS$APPS metadata + packaged
 	// TEMPLATES blob) for the apps the manifest references. T0+; the client caches + expands
 	// it into its slug-scoped IndexedDB and renders operation forms from it.

package/engine/orm/apiRoute.js

@@ -20,6 +20,7 @@
  *   failure           -> {"error":"..."} , which db/ds.js's dsReq already looks for.
  */
 import { json2List, addTableNameToArray, lookupToSql, lookupTotalToSql, resolveDbIndex, buildWriteSql } from "./index.js";
+import { nextGeneratorValue } from "./dialect.js";
 import { createReaders } from "./changeInference.js";
 import { CONFLICT_CODE, ROW_VERSION_KEY, refreshRowVersion } from "./concurrency.js";
 import {
@@ -135,6 +136,27 @@ export const parseExecuteSqlRequest = (path, body) => {
 	}
 };
 
+/*
+ * `genId` carries EVERYTHING IN THE PATH and posts a null body:
+ * `/fina/rest/TOrmMethod/%22genId%22/SYS$USERGROUP_GEN/3` (data.service.ts genId).
+ *
+ * ⚠️ Which is why `parseDataSnapRequest` never recognised it — that one needs `_parameters[0]` and
+ * quietly declines a body it cannot read. The call fell through to FINA, and on a tenant with no
+ * FINA the admin screen answered `502 ECONNREFUSED 127.0.0.1:212`.
+ *
+ * Returns { generator, dbIndex } or null.
+ */
+const GENID_PATH = /\/fina\/rest\/\w+\/(?:%22|")genId(?:%22|")\/([^/?#]+)\/(\d+)/i;
+
+export const parseGenIdRequest = (path) => {
+	const match = GENID_PATH.exec(String(path ?? ""));
+	if (!match) return null;
+	const generator = decodeURIComponent(match[1]).trim();
+	if (!generator) return null;
+	const dbIndex = Number(match[2]);
+	return { generator, dbIndex: Number.isFinite(dbIndex) ? dbIndex : null };
+};
+
 export const parseDataSnapRequest = (path, body) => {
 	const match = DATASNAP_PATH.exec(String(path ?? ""));
 	if (!match) return null;
@@ -580,6 +602,53 @@ export const routeApiRequest = async (
 		}
 	}
 
+	/*
+	 * ⚠️⚠️ `genId` — a Firebird GENERATOR, answered from PostgreSQL's own counter.
+	 *
+	 * This used to fall through to FINA with the rest of the non-ORM surface, which was honest while
+	 * the generator was merely SOMEWHERE ELSE. It is not: the PostgreSQL migrations translate
+	 * `<TABLE>_GEN` + BI trigger into `GENERATED BY DEFAULT AS IDENTITY`, so on a PostgreSQL tenant
+	 * the generator does not exist at all and the forward could only ever reach a Firebird counter
+	 * for a different database — or, on a tenant with no FINA, `ECONNREFUSED`.
+	 *
+	 * ⚠️ Answering it from FINA was the WORSE outcome of the two. `buildUpsert` honours a supplied
+	 * key, so a value drawn from one database and inserted into another collides with the identity
+	 * column's own sequence as soon as the two counters cross. Resolving to the table's OWN sequence
+	 * is what makes the pre-allocated key and the column default one counter again.
+	 *
+	 * ⚠️ A Firebird index still has a real generator, so it still forwards — the mixed tenant
+	 * `finaEndpoint.js` protects keeps working untouched.
+	 */
+	const genIdRequest = parseGenIdRequest(path);
+	if (genIdRequest) {
+		if (!isPostgresIndex(genIdRequest.dbIndex)) return null;
+		try {
+			const { sequence, value } = await nextGeneratorValue({
+				exec,
+				dbIndex: genIdRequest.dbIndex,
+				generator: genIdRequest.generator,
+			});
+			/* ⚠️ A caller can act on "no sequence backs SYS$NOPE_GEN". It cannot act on a connection
+			   error, and telling the two apart is most of what made this bug hard to place. */
+			if (sequence === null) {
+				return {
+					status: 400,
+					body: {
+						error:
+							`no sequence backs generator ${genIdRequest.generator} on database ` +
+							`${genIdRequest.dbIndex} — no sequence of that name, and no identity column on ` +
+							`${genIdRequest.generator.replace(/_GEN$/i, "")}`,
+					},
+				};
+			}
+			/* ⚠️ A BARE NUMBER, captured from the live FINA rather than guessed: it answers `2`, not
+			   `{data:…}` and not a string. data.service.ts hands the body straight to the caller. */
+			return { status: 200, body: value };
+		} catch (error) {
+			return { status: 500, body: { error: error?.message ?? String(error) } };
+		}
+	}
+
 	const parsed = parseDataSnapRequest(path, body);
 	if (!parsed) return null;
 

package/engine/orm/dialect.js

@@ -25,6 +25,71 @@ export const buildPagingClause = (start, length) => {
 export const buildSequenceNextValue = (sequenceName) =>
 	`SELECT nextval('${String(sequenceName).replace(/'/g, "''")}')`;
 
+/*
+ * Doc 3 §5 item 11 — which PostgreSQL sequence stands in for a Firebird GENERATOR.
+ *
+ * ⚠️⚠️ THE SECOND BRANCH IS THE WHOLE POINT. On Firebird a table's key comes from `<TABLE>_GEN`
+ * plus a BEFORE INSERT trigger; the PostgreSQL migrations translate that pair into
+ * `GENERATED BY DEFAULT AS IDENTITY`, so the generator does not exist here and cannot. Measured on
+ * both live PostgreSQL databases: not one `%_GEN` sequence.
+ *
+ * So `SYS$USERGROUP_GEN` resolves to the sequence `SYS$USERGROUP`'s identity column ALREADY OWNS.
+ * That is not a convenience — it is the correctness condition. A caller that pre-allocates a key
+ * and then inserts it explicitly (`admin/userGroup.component.ts`, because SYS$UGPRIV is written as
+ * an independent row carrying `usergroup_id`) must draw from the SAME counter the column's DEFAULT
+ * would use, or the two drift apart and collide on the primary key. That is exactly what was
+ * happening while `genId` was forwarded to a FINA whose own generator was a different number in a
+ * different database.
+ *
+ * ⚠️ The exact-name branch comes FIRST so an application that genuinely created `FOO_GEN` keeps
+ * working, and so a Firebird-shaped schema restored onto PostgreSQL is still answered correctly.
+ *
+ * ⚠️ The column is not assumed to be `id`: the lookup asks which of the table's columns owns a
+ * sequence. A table whose key is named otherwise resolves just the same.
+ *
+ * ⚠️ `pg_table_is_visible` keeps both branches inside the caller's search path — without it a
+ * same-named sequence in another schema could answer for a table this connection cannot even see.
+ *
+ * ⚠️ Both names are rendered as LITERALS, compared with `lower(...)`, never as identifiers. Nothing
+ * from the request reaches an identifier position: the `nextval` that follows uses the name the
+ * DATABASE returned, not the one the caller sent.
+ */
+export const buildGeneratorSequenceSql = (generator) => {
+	const name = String(generator ?? "");
+	const table = name.replace(/_GEN$/i, "");
+	return (
+		"SELECT COALESCE(" +
+		"(SELECT c.oid::regclass::text FROM pg_class c " +
+		`WHERE c.relkind = 'S' AND pg_table_is_visible(c.oid) AND lower(c.relname) = lower(${quoteLiteral(name)}) ` +
+		"LIMIT 1), " +
+		"(SELECT pg_get_serial_sequence(t.oid::regclass::text, a.attname) FROM pg_class t " +
+		"JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum > 0 AND NOT a.attisdropped " +
+		`WHERE t.relkind = 'r' AND pg_table_is_visible(t.oid) AND lower(t.relname) = lower(${quoteLiteral(table)}) ` +
+		"AND pg_get_serial_sequence(t.oid::regclass::text, a.attname) IS NOT NULL " +
+		"LIMIT 1)" +
+		") AS sequence_name"
+	);
+};
+
+/*
+ * The next value of a Firebird-named generator, from PostgreSQL.
+ *
+ * ⚠️ ONE COPY, because there are two callers and they must not drift: `apiRoute.js` answers the
+ * admin client's `genId`, and `engine/ext/live.js` pre-generates SYS$EXT_USER ids. The second was
+ * a hand-rolled axios call to FINA and carried the identical latent failure — a PostgreSQL tenant
+ * has no FINA to ask and no generator to ask for.
+ *
+ * Resolves to `{ sequence, value }`, or `{ sequence: null, value: null }` when nothing backs the
+ * name. The caller decides what an unresolvable generator means; here it is simply a fact.
+ */
+export const nextGeneratorValue = async ({ exec, dbIndex, generator }) => {
+	const resolved = (await exec(buildGeneratorSequenceSql(generator), dbIndex)) ?? [];
+	const sequence = resolved[0]?.sequence_name ?? resolved[0]?.SEQUENCE_NAME ?? null;
+	if (!sequence) return { sequence: null, value: null };
+	const next = (await exec(buildSequenceNextValue(sequence), dbIndex)) ?? [];
+	return { sequence, value: Number(next[0]?.nextval ?? next[0]?.NEXTVAL) };
+};
+
 export const quoteLiteral = (value) => `'${String(value).replace(/'/g, "''")}'`;
 
 /* A JS Date as a SQL literal. `String(date)` gives

package/engine/orm/executeBlock.js

@@ -210,6 +210,25 @@ const rewriteGenId = (statement) =>
 		),
 	);
 
+/*
+ * ASCII_CHAR(<n>) -> CHR(<n>). Firebird's spelling; PostgreSQL has only CHR.
+ *
+ * ⚠️⚠️ THIS IS HOW A NEWLINE REACHES EITHER ENGINE. A raw newline in the statement ends the command
+ * on the FINA/Firebird transport — the CLI Script screen failed live with "Unexpected end of
+ * command - line 1, column 59", column 59 being exactly where the script literal begins in
+ * `... SET SCRIPT = '`. The admin client therefore builds the break instead of typing it: one
+ * literal per line, joined by ASCII_CHAR(10). Collapsing the lines was not an option, because a CLI
+ * script is JavaScript and one `//` comment would comment out the rest of the file.
+ *
+ * ⚠️ OUTSIDE LITERALS ONLY, for the same reason as GEN_ID and more sharply: the value being written
+ * IS a script, and a script may legitimately contain the text "ASCII_CHAR". Rewriting it there
+ * would corrupt the very source being installed.
+ */
+const rewriteAsciiChar = (statement) =>
+	outsideLiterals(statement, (segment) =>
+		segment.replace(/\bASCII_CHAR\s*\(\s*(\d+)\s*\)/gi, (_all, code) => `CHR(${code})`),
+	);
+
 /* DATEADD(<n> <unit> TO <expr>) -> (<expr> + INTERVAL '<n> <unit>').
 
    Firebird-only, and unlike GEN_ID it usually cannot be fixed app-side: most of the 23 call sites
@@ -459,7 +478,11 @@ const translateReadBlock = (sql) => {
    statement path cannot drift apart. */
 const translateStatement = (statement) =>
 	lowerQuotedIdentifiers(
-		rewriteFirstSkip(rewriteRdbDatabase(rewriteDateAdd(rewriteGenId(rewriteUpsert(statement))))),
+		rewriteFirstSkip(
+			rewriteRdbDatabase(
+				rewriteDateAdd(rewriteAsciiChar(rewriteGenId(rewriteUpsert(statement)))),
+			),
+		),
 	);
 
 const WRAPPER = /^\s*EXECUTE\s+BLOCK\b[\s\S]*?\bAS\b\s*BEGIN\b/i;

package/engine/orm/listQuery.js

@@ -4,6 +4,7 @@
  * Delphi TListRecord (QuerySQL / recordsTotalSQL).
  */
 import { buildPagingClause } from "./dialect.js";
+import { isPostgresIndex } from "../domain/dialect.js";
 import { softDeleteFilter, tenantFilter, isBooleanColumn } from "./entityConfig.js";
 import { createJoinRegistry, splitKey } from "./joinChain.js";
 
@@ -105,6 +106,52 @@ const buildProjection = (columns, registry) => {
  * values mirror the JSON type "exactly as Delphi did"). An unknown table or column returns false from
  * `isBooleanColumn`, so the unsure case is always "leave it alone".
  */
+/*
+ * ⚠️⚠️ FIREBIRD'S `CONTAINING`, WHICH POSTGRESQL DOES NOT HAVE.
+ *
+ * `buildCondition` renders `<column> <operator> <value>`, so whatever the client sends lands in the
+ * SQL as typed — and the client sends `containing` for every substring search: every lookup dropdown
+ * (`select-lookup.service.ts`) and every "contains" filter (`filter-list.service.ts`). On a
+ * PostgreSQL tenant that is a hard `syntax error at or near "containing"`, so no search box in the
+ * entire client worked.
+ *
+ * ⚠️ TRANSLATED HERE RATHER THAN IN THE CLIENT, for the reason the boolean coercion above already
+ * gives: the call sites sit inside generic components used everywhere, every miss stays silent until
+ * somebody types in a search box, and the next application would start the same hunt.
+ *
+ * ⚠️ `ILIKE`, NOT `LIKE`. Firebird's CONTAINING is case-INSENSITIVE; rendering `LIKE` would quietly
+ * narrow what every existing search matches, which is a wrong answer rather than an error.
+ */
+const CONTAINING = "containing";
+const NOT_CONTAINING = "not containing";
+
+/*
+ * Wrap the value in wildcards, escaping the ones it already contains.
+ *
+ * ⚠️⚠️ THE ESCAPING IS THE POINT. `%` and `_` are wildcards to ILIKE but ORDINARY CHARACTERS to
+ * CONTAINING — so without this, searching for "50%" would match every row and "a_b" would match
+ * "axb". A wrong answer, silently, which is worse than the syntax error this replaces.
+ *
+ * ⚠️ Backslash FIRST, or the escapes added afterwards get escaped in turn.
+ */
+const toContainingPattern = (value) => {
+	const text = value === null || value === undefined ? "" : String(value);
+	/* The client sends the value already quoted; take what is inside so the wildcards go within it. */
+	const quoted = /^'([\s\S]*)'$/.exec(text.trim());
+	const inner = quoted ? quoted[1] : text.trim();
+	/*
+	 * ⚠️ Built with split/join and a char-code backslash rather than regex escapes — the escaping
+	 * here is the whole point, and a backslash that does not survive editing produces a silently
+	 * wrong pattern rather than a syntax error.
+	 */
+	const BACKSLASH = String.fromCharCode(92);
+	const escaped = inner
+		.split(BACKSLASH).join(BACKSLASH + BACKSLASH)
+		.split('%').join(BACKSLASH + '%')
+		.split('_').join(BACKSLASH + '_');
+	return `'%${escaped}%'`;
+};
+
 const BARE_BOOLEAN_LITERAL = /^[01]$/;
 const coerceBooleanFilterValue = (rawColumn, value, dbIndex) => {
 	const text = value === null || value === undefined ? "" : String(value).trim();
@@ -138,6 +185,16 @@ const buildCondition = (filter, registry, dbIndex) => {
 	if (VALUELESS_OPERATORS.has(operator.toLowerCase())) {
 		return rendered;
 	}
+	/*
+	 * ⚠️ POSTGRESQL ONLY. On Firebird `CONTAINING` is the correct operator and must be left alone —
+	 * this is a translation for one engine, not a change to the filter language.
+	 */
+	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)}`;
+	}
+
 	if (operator.toLowerCase() === "between") {
 		return `${rendered} ${filter.value1} AND ${filter.value2}`;
 	}

package/package.json

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