biz-a-cli 2.3.80-15333 → 2.3.80-15357

package/bin/app.js

@@ -20,6 +20,10 @@ import {
 import { prepareScript, encryptScript } from "./script.js";
 import { spawn } from "node:child_process";
 import { newMigration, runMigrations } from "./migrate.js";
+import {
+	validateThemeSource,
+	APPLICATION_THEME_NAME,
+} from "../engine/domain/themeConfig.js";
 import {
 	APP_CONFIG_NAME,
 	buildEnsureConfigTableSql,
@@ -367,6 +371,9 @@ const getFileList = ({ workingDir = process.cwd(), files = null } = {}) => {
    ============================================================================ */
 
 const APPLICATION_CONFIG_FILE = "application.js";
+/* Doc 6 §8.1 — the application theme source. JSON, because it is DATA that reaches the browser
+   via sys$config and must never be evaluated (AC 26). */
+const THEME_CONFIG_FILE = "theme.json";
 /* Parity with the admin editor (appConfig.component.ts executeBlockBodyLimit): the DataSnap
    `block` call body must stay under 64KB, so an oversized config is upserted in chunks. */
 const EXECUTE_BLOCK_BODY_LIMIT = 2 ** 16;
@@ -548,6 +555,41 @@ const collectConfigUploads = ({ workingDir, fileNames = [], include = [] }) => {
 		application = { name: APP_CONFIG_NAME, version, content };
 	}
 
+	/*
+	 * Doc 6 §8.1 — the application's theme, published beside its config.
+	 *
+	 * ⚠️ A SEPARATE FILE, AND JSON, for the reason §8.1 points 1-2 give: this ends up in
+	 * `sys$config` and is read by every user's browser, so if it were executable anyone who can
+	 * write `sys$config` could run code in all of them. It is parsed, never evaluated (AC 26).
+	 *
+	 * ⚠️ Validated at PUBLISH, not at runtime. A mistyped token name is silent at runtime — the
+	 * token is simply never applied — and the author is left believing the theme works. Refusing the
+	 * publish puts the error where somebody can act on it (§8.1 point 4).
+	 */
+	let theme = null;
+	const themeFile = fileNames.find(
+		(f) => path.basename(String(f)).toLowerCase() === THEME_CONFIG_FILE,
+	);
+	if (themeFile) {
+		const { theme: parsedTheme, problems: themeProblems } = validateThemeSource(
+			readConfig(themeFile),
+		);
+		if (themeProblems.length) {
+			problems.push(
+				...themeProblems.map((m) => `${path.basename(String(themeFile))}: ${m}`),
+			);
+		} else {
+			/* Versioned with the application: the theme belongs to that release of the app, and a
+			   rollback of one without the other would pair a config with a theme it never shipped
+			   with. */
+			theme = {
+				name: APPLICATION_THEME_NAME,
+				version: application?.version ?? "1.0.0",
+				content: JSON.stringify(parsedTheme),
+			};
+		}
+	}
+
 	const domains = [];
 	/* ⚠️ Kept because the tenancy rule is CROSS-FILE: a scoped entity in one domain may be given its
 	   foreign key by a relationship in another, and `buildTenancyMap` folds them all together at
@@ -610,7 +652,7 @@ const collectConfigUploads = ({ workingDir, fileNames = [], include = [] }) => {
 		);
 	}
 
-	return { application, domains };
+	return { application, domains, theme };
 };
 
 /* Upsert the configs, then optionally run the same publish the admin button does. Publish order
@@ -693,7 +735,7 @@ async function uploadConfigs({
 		serverLink: resolveServerLink(serverMode),
 	});
 
-	const { application, domains } = collectConfigUploads({
+	const { application, domains, theme } = collectConfigUploads({
 		workingDir,
 		fileNames,
 		include,
@@ -752,6 +794,12 @@ async function uploadConfigs({
 			content: application.content,
 		});
 	}
+
+	/* Doc 6 §8.1 — level 2. ⚠️ A DIFFERENT KEY from the company's own theme (level 3): sharing one
+	   would mean publishing an app silently overwrote a company's branding. */
+	if (theme) {
+		await saveOne(theme);
+	}
 	for (const domain of domains) {
 		await saveOne(domain);
 	}

package/bin/hub.js

@@ -193,9 +193,12 @@ import { createFinaRouter } from "../engine/orm/finaEndpoint.js";
 import { createSessionStore } from "../engine/orm/sessionStore.js";
 import { resolveUserTenancy } from "../engine/orm/tenantResolution.js";
 import { buildUserTenantSql } from "../engine/orm/finaAuth.js";
-import { primeEntityConfig, isTenancyDeclared } from "../engine/orm/entityConfig.js";
+import { isTenancyDeclared } from "../engine/orm/entityConfig.js";
+import {
+	ensureEntityConfig,
+	setEntityConfigRefreshHook,
+} from "../engine/domain/entityConfigPrimer.js";
 import { createTenantContextApplier, APP_ROLE } from "../engine/orm/rlsApplier.js";
-import { createDomainConfigLoader } from "../engine/domain/entityConfigLoader.js";
 import {
 	execPostgres,
 	execPostgresStatements,
@@ -263,6 +266,19 @@ if (hubSessionStore) {
 	setInterval(sweepSessions, SESSION_SWEEP_INTERVAL_MS).unref();
 }
 
+/*
+ * Doc 6 Q5 — keep this thread's declarations current on the request path.
+ *
+ * ⚠️ The check is TTL'd inside `ensureEntityConfig`, so the overwhelming majority of requests pay
+ * nothing; roughly once every few seconds one request awaits a single digest query.
+ *
+ * ⚠️ `.finally(next)`, never `.then(next)`: a database hiccup while checking freshness must not stop
+ * the request. The declarations this thread already holds are the ones it would have used anyway.
+ */
+app.use("/fina", (_req, _res, next) => {
+	ensureEntityConfig(Number(argv.dbindex)).finally(() => next());
+});
+
 app.use(
 	"/fina",
 	createFinaRouter({
@@ -415,40 +431,57 @@ server.listen(argv.serverport, () => {
  * ⚠️ Deliberately NOT awaited and never fatal. It fails soft to "every entity is hard" — exactly what
  * the ORM did before §6.6 existed — so a config problem must not delay or prevent the hub coming up.
  */
+/*
+ * Doc 3 §11 layer 2 — install the RLS context applier, but ONLY once an application has actually
+ * declared tenancy. Extracted and made IDEMPOTENT for Doc 6 Q5: declarations can now change while
+ * the hub is running, so this runs after the first prime AND after any refresh that moved them.
+ *
+ * ⚠️ IT NEVER UNINSTALLS. Un-declaring tenancy is rare, and dropping the applier mid-session would
+ * take RLS enforcement off in-flight requests — strictly worse than carrying a cost nobody asked for
+ * until the next restart.
+ */
+let tenantApplierInstalled = false;
+const installTenantApplierIfDeclared = () => {
+	if (tenantApplierInstalled) return;
+	if (!isTenancyDeclared(Number(argv.dbindex))) return;
+	setTenantContextApplier(createTenantContextApplier());
+	tenantApplierInstalled = true;
+	logger.info(
+		`[RLS] tenant context applier installed for db ${argv.dbindex}; ` +
+			"request-path queries now run as " + APP_ROLE + " inside a transaction",
+	);
+};
+
 if (isPostgresIndex(Number(argv.dbindex))) {
-	primeEntityConfig({
-		dbIndex: Number(argv.dbindex),
-		loadDomainConfigs: createDomainConfigLoader({
-			exec: execPostgres,
-			dbIndex: Number(argv.dbindex),
-		}),
-	})
-		.then(() => {
-			/*
-			 * Doc 3 §11 layer 2 — install the RLS context applier, but ONLY once an application has
-			 * actually declared tenancy.
-			 *
-			 * ⚠️ INSTALLING IT IS NOT FREE AND NOT INVISIBLE. `execPostgres` opens a transaction only
-			 * when an applier is present; until then every read and every single-statement write is a
-			 * bare `pool.query`. Installing it makes each one check out a pooled connection for a
-			 * BEGIN/COMMIT. Gating on the declaration keeps that cost — and the whole SET LOCAL ROLE
-			 * machinery — off every tenant that has not asked for it.
-			 *
-			 * ⚠️ ORDER: the applier must be installed BEFORE any policy exists. A policy whose
-			 * predicate reads `app.current_tenant` while nothing sets it hides every row from
-			 * everyone, which on a live POS is an outage rather than a security improvement.
-			 */
-			if (isTenancyDeclared(Number(argv.dbindex))) {
-				setTenantContextApplier(createTenantContextApplier());
-				logger.info(
-					`[RLS] tenant context applier installed for db ${argv.dbindex}; ` +
-						"request-path queries now run as " + APP_ROLE + " inside a transaction",
-				);
-			}
-		})
+	/*
+	 * Doc 6 Q5 — a publish that changes declarations must reach this thread without a restart, and
+	 * the applier has to be installed if that publish is the one that DECLARES tenancy. Registering
+	 * the hook before the first prime means even the startup read cannot outrun it.
+	 */
+	setEntityConfigRefreshHook(() => installTenantApplierIfDeclared());
+
+	/*
+	 * ⚠️ `ensureEntityConfig`, not `primeEntityConfig` directly: it is the same read, but it records
+	 * this thread's fingerprint so the refresh check has a baseline. Priming behind its back would
+	 * leave the first request to re-read the whole config for nothing.
+	 */
+	ensureEntityConfig(Number(argv.dbindex))
+		/*
+		 * ⚠️ INSTALLING IT IS NOT FREE AND NOT INVISIBLE. `execPostgres` opens a transaction only
+		 * when an applier is present; until then every read and every single-statement write is a
+		 * bare `pool.query`. Installing it makes each one check out a pooled connection for a
+		 * BEGIN/COMMIT. Gating on the declaration keeps that cost — and the whole SET LOCAL ROLE
+		 * machinery — off every tenant that has not asked for it.
+		 *
+		 * ⚠️ ORDER: the applier must be installed BEFORE any policy exists. A policy whose
+		 * predicate reads `app.current_tenant` while nothing sets it hides every row from
+		 * everyone, which on a live POS is an outage rather than a security improvement.
+		 */
+		.then(() => installTenantApplierIfDeclared())
 		.catch(() => {});
 }
 
+
 if (argv.mode.trim().toLowerCase() === "agent") {
 	// Message broker agent not need connection to server, hubServer, directHub
 	logger.info(`[Message Broker] Starting as isolated CLI Agent...`);

package/bin/hubEvent.js

@@ -17,12 +17,26 @@ import { makeExtReqHandler } from "../engine/ext/hubProxy.js";
 
 import { logger } from "../logger.js";
 import { routeApiRequest } from "../engine/orm/apiRoute.js";
+import { ensureEntityConfig } from "../engine/domain/entityConfigPrimer.js";
 import { runAsPrincipal, runTrusted, ACTIVE_TENANT_NOT_HELD } from "../engine/orm/tenantContext.js";
 import { resolveRequestScope, SESSION_NOT_USABLE } from "../engine/orm/requestScope.js";
 import { createSessionStore } from "../engine/orm/sessionStore.js";
 import { resolveUserTenancy } from "../engine/orm/tenantResolution.js";
 import { buildUserTenantSql } from "../engine/orm/finaAuth.js";
-import { authorizeRequest } from "../security/internalPrincipal.js";
+import { authorizeRequest, principalForCliScript } from "../security/internalPrincipal.js";
+import {
+	readUserPreferences,
+	writeUserPreferences,
+} from "../engine/orm/userPreferences.js";
+import {
+	readCompanyTheme,
+	writeCompanyTheme,
+} from "../engine/orm/companyTheme.js";
+import {
+	readCompanyLogo,
+	writeCompanyLogo,
+	clearCompanyLogo,
+} from "../engine/orm/companyLogo.js";
 import {
 	execPostgres,
 	execPostgresStatements,
@@ -477,6 +491,22 @@ const handleCliCommand = async (data, cb, argv) => {
 					query: { scriptName: data.scriptName },
 					headers: { "user-agent": "biz-a-client-socket" },
 				};
+				/*
+				 * ⚠️⚠️ Doc 6 §8.3 — WHO IS ASKING. Until now this entrance carried no verified identity
+				 * at all, which is why a CLI script could not gate anything on a right. The client sends
+				 * the same signed principal it already attaches to HTTP; everything the script sees comes
+				 * from inside that signature.
+				 *
+				 * ⚠️ OBSERVE-SHAPED, deliberately. An absent or invalid principal yields null and the script
+				 * still RUNS — it is the script's job to refuse when it needs an identity it did not get.
+				 * Refusing here would lock out every client that has not been rebuilt, which is exactly
+				 * what `--principalMode` exists to avoid.
+				 *
+				 * ⚠️ `data.headers`, never `data.scriptData`: the payload around this is caller-shaped.
+				 */
+				const cliScriptPrincipal = principalForCliScript(data.headers, {
+					mode: argv["principalMode"] || "observe",
+				});
 				cb(
 					null,
 					await execCLIScriptWorker(
@@ -487,9 +517,134 @@ const handleCliCommand = async (data, cb, argv) => {
 						},
 						data.scriptName,
 						liveTriggerPayload,
+						cliScriptPrincipal,
 					),
 				);
 				break;
+			/*
+			 * Doc 6 §4.2 / AC 19 — read or merge the SIGNED-IN USER'S preferences.
+			 *
+			 * ⚠️ A DEDICATED COMMAND, NOT `engine`. The `engine` case below runs `runTrusted` with no
+			 * principal at all — by design, because those are administrator operations. Routing user
+			 * preferences through it would take the user id from `data.payload`, i.e. from the
+			 * browser, and a user could then write somebody else's.
+			 *
+			 * ⚠️ AND NOT `runcliscript` EITHER. That resolves an app-authored script by name; a
+			 * platform operation would have to be seeded into SYS$CLI_SCRIPT per tenant and re-seeded
+			 * to change.
+			 *
+			 * ⚠️ REQUIRED, not observe-shaped. `runcliscript` deliberately lets a null principal
+			 * through so an un-rebuilt client still works — the script decides. Here there is nothing
+			 * to decide: without an identity there is no row to read or write, so userPreferences.js
+			 * throws and the client falls back to its localStorage mirror (§4.2 point 2b).
+			 */
+			case "userpreferences": {
+				const prefPrincipal = principalForCliScript(data.headers, {
+					mode: argv["principalMode"] || "observe",
+				});
+				const prefExec = (sql) => execPostgres(sql, argv["dbindex"]);
+				const prefs =
+					data.action === "write"
+						? await writeUserPreferences({
+								exec: prefExec,
+								principal: prefPrincipal,
+								patch: data.patch,
+							})
+						: await readUserPreferences({
+								exec: prefExec,
+								principal: prefPrincipal,
+							});
+				cb(null, { success: true, data: prefs });
+				break;
+			}
+			/*
+			 * Doc 6 §7.1.1 step 7 + §13 point 3 — save the COMPANY theme, with its audit trail.
+			 *
+			 * ⚠️ THIS EXISTS SO THE AUDIT TRAIL CAN NAME SOMEBODY. The client could write SYS$CONFIG
+			 * directly through executeBlock, as the App Config screen does — but then the audit row
+			 * would be authored by the thing being audited, with the user id read out of
+			 * localStorage. principalForCliScript is what makes "siapa" mean anything.
+			 *
+			 * ⚠️ Validation (token names, ranges, WCAG AA) happens inside writeCompanyTheme via the
+			 * SAME validateThemeSource that gates an application theme at publish — §7.1's one rule
+			 * for Jalur A and Jalur B.
+			 */
+			case "companytheme": {
+				const themePrincipal = principalForCliScript(data.headers, {
+					mode: argv["principalMode"] || "observe",
+				});
+				const themeExec = (sql) => execPostgres(sql, argv["dbindex"]);
+				if (data.action === "write") {
+					const saved = await writeCompanyTheme({
+						exec: themeExec,
+						execStatements: (statements) =>
+							execPostgresStatements(statements, argv["dbindex"]),
+						principal: themePrincipal,
+						theme: data.theme,
+					});
+					/*
+					 * ⚠️ A REFUSAL IS NOT AN ERROR. `problems` is what the settings screen shows the
+					 * admin so they can fix the colour — reporting it as a failed call would lose
+					 * the explanation and leave them with "save failed".
+					 */
+					cb(null, {
+						success: saved.ok,
+						problems: saved.problems,
+						data: saved.theme,
+					});
+				} else {
+					cb(null, {
+						success: true,
+						data: await readCompanyTheme({ exec: themeExec }),
+					});
+				}
+				break;
+			}
+			/*
+			 * Doc 6 §8.2 — the company logo, under its OWN sys$config key.
+			 *
+			 * ⚠️ A SEPARATE COMMAND FROM THE THEME, deliberately. §8.2 point 3 keeps the image out
+			 * of the theme JSON because the theme is read on every application start and a logo is
+			 * megabytes; folding it into `companytheme` would undo that at the transport layer even
+			 * if the storage stayed split.
+			 */
+			case "companylogo": {
+				const logoPrincipal = principalForCliScript(data.headers, {
+					mode: argv["principalMode"] || "observe",
+				});
+				const logoExec = (sql) => execPostgres(sql, argv["dbindex"]);
+				const logoStatements = (statements) =>
+					execPostgresStatements(statements, argv["dbindex"]);
+
+				if (data.action === "write") {
+					const saved = await writeCompanyLogo({
+						exec: logoExec,
+						execStatements: logoStatements,
+						principal: logoPrincipal,
+						dataUrl: data.dataUrl,
+					});
+					/* ⚠️ A refusal is NOT an error: `problems` is what the settings screen shows the
+					   admin so they can pick a different file. */
+					cb(null, {
+						success: saved.ok,
+						problems: saved.problems,
+						data: saved.logo ?? null,
+					});
+				} else if (data.action === "clear") {
+					const cleared = await clearCompanyLogo({
+						exec: logoExec,
+						execStatements: logoStatements,
+						principal: logoPrincipal,
+					});
+					cb(null, { success: cleared.ok, problems: cleared.problems, data: null });
+				} else {
+					cb(null, {
+						success: true,
+						data: await readCompanyLogo({ exec: logoExec }),
+					});
+				}
+				break;
+			}
 			case "runextcliscript": {
 				// External-access op invoker — enforces the capability boundary (dispatch.js),
 				// unlike raw `runcliscript`. Safe to expose: no valid token -> UNAUTHENTICATED.
@@ -735,12 +890,25 @@ export const clientListener = (socket, argv, via = "?") => {
 				   against the SIGNED claim, so it can only select among tenants already granted. */
 				/* Doc 4 §9.5 / B2 — the session ROW is the authority for tenancy. A principal minted
 				   before sessions existed has no id and falls back to its own deprecated claims. */
-				resolveRequestScope({
-					claims: decision.claims,
-					headers: reqData.headers,
-					sessionStore: sessionStoreFor(Number(argv["dbindex"])),
-					resolveTenancy: tenancyResolverFor(Number(argv["dbindex"])),
-				})
+				/*
+				 * Doc 6 Q5 — this is the OTHER entrance to the same ORM. `bin/hub.js` keeps the HTTP
+				 * path's declarations current with a `/fina` middleware; the browser's data calls
+				 * arrive here instead, so the same TTL'd check belongs in front of them or half the
+				 * request traffic would keep reading whatever this thread learned at startup.
+				 *
+				 * ⚠️ Chained, never awaited-and-thrown: a freshness check that fails must not refuse a
+				 * request the existing declarations could answer perfectly well.
+				 */
+				ensureEntityConfig(Number(argv["dbindex"]))
+					.catch(() => {})
+					.then(() =>
+						resolveRequestScope({
+							claims: decision.claims,
+							headers: reqData.headers,
+							sessionStore: sessionStoreFor(Number(argv["dbindex"])),
+							resolveTenancy: tenancyResolverFor(Number(argv["dbindex"])),
+						}),
+					)
 					.then((scope) =>
 						/* ⚠️ The ROUTER is handed the resolved scope too — see finaEndpoint for why. */
 						runAsPrincipalOr403(scope, () =>

package/engine/domain/applicationConfig.js

@@ -378,11 +378,98 @@ export const buildTemplateDomainConfigResolverSnippet = () => {
 			this._ensureDomainConfig = ensureDomainConfig;`;
 };
 
+/*
+ * ⚠️⚠️⚠️ THE GENERATED TEMPLATE MUST DECLARE ITS LIBRARIES.
+ *
+ * App + domain config publishing used to run in the CLIENT; moving it here dropped this step. The
+ * generated form then carried only beforeLoadData / afterLoadData / onInit / onDestroy / onPipe, so
+ * `form.component.ts` calling `doFunction('useLibrary')` got undefined and loaded nothing, and
+ * `db.service.loadScript` — which arms the template reloader from that SAME list — watched no
+ * libraries at all. A redeployed library was then never picked up by an open session, and nothing
+ * said so. See Doc 6 §7.12.
+ *
+ * ⚠️ THIS MUST MIRROR THE CLIENT EXACTLY — `resolveDomainLibraries` (render.domain.ts) and
+ * `normalizeDomainLibraryModules` (domain.service.ts). Any divergence means the form loads one set
+ * and the reloader watches another, which is a silent bug of precisely the kind this replaces.
+ *
+ * A module id is `<appName>-<fileName>`, e.g. `hrlib-hrpublishlib`: the app bundle that owns the
+ * file, then the file's own basename. A handler string carries both in its first two segments.
+ */
+export const resolveDomainLibraryModules = (parsedDomainConfig) => {
+	const config = parsedDomainConfig && typeof parsedDomainConfig === "object" ? parsedDomainConfig : {};
+
+	const rawLibraries = Array.isArray(config?.libraries)
+		? config.libraries
+		: Array.isArray(config?.ui?.libraries)
+			? config.ui.libraries
+			: [];
+	const configuredModules = [
+		...new Set(
+			rawLibraries
+				.map((item) => {
+					if (typeof item === "string") {
+						return item.trim();
+					}
+					if (item && typeof item === "object") {
+						if (typeof item.domain === "string") {
+							return item.domain.trim();
+						}
+						if (typeof item.module === "string") {
+							return item.module.trim();
+						}
+					}
+					return "";
+				})
+				.filter((moduleName) => moduleName.length > 0),
+		),
+	];
+
+	const events =
+		config?.events && typeof config.events === "object" && !Array.isArray(config.events)
+			? config.events
+			: config?.ui?.events && typeof config.ui.events === "object" && !Array.isArray(config.ui.events)
+				? config.ui.events
+				: {};
+	const derivedModules = new Set();
+	for (const eventDef of Object.values(events)) {
+		const handler = typeof eventDef?.handler === "string" ? eventDef.handler.trim() : "";
+		if (!handler) {
+			continue;
+		}
+		const segments = handler
+			.split(".")
+			.map((segment) => String(segment ?? "").trim())
+			.filter((segment) => segment.length > 0);
+		/* Fewer than 3 segments names a function in the template itself, not a library. */
+		if (segments.length >= 3) {
+			derivedModules.add(`${segments[0]}-${segments[1]}`);
+		}
+	}
+
+	if (configuredModules.length === 0) {
+		return [...derivedModules];
+	}
+
+	/* A bare domain name (`hrlib`) expands to the `hrlib-*` its handlers actually reference; if none
+	   do, it is kept as-is so an explicitly declared library is never silently dropped. */
+	const derivedModuleList = [...derivedModules];
+	const normalizedConfigured = configuredModules.flatMap((moduleName) => {
+		if (moduleName.includes("-")) {
+			return [moduleName];
+		}
+		const matchedDerived = derivedModuleList.filter((candidate) => candidate.startsWith(`${moduleName}-`));
+		return matchedDerived.length > 0 ? matchedDerived : [moduleName];
+	});
+
+	return [...new Set([...normalizedConfigured, ...derivedModuleList])];
+};
+
 export const buildHardcodedTemplateContent = (
 	entryPointName = "loginForm",
 	domainKey = null,
 	templateType = "form",
 	domainSource = null,
+	libraryModules = [],
 ) => {
 	const sharedDomainConfigResolverScript = buildTemplateDomainConfigResolverSnippet();
 	const formTemplateContent = `get = function () {
@@ -390,7 +477,7 @@ export const buildHardcodedTemplateContent = (
 		model: {},
 		tableName: "",
 		fields: [],
-		functions: {
+		functions: {__USE_LIBRARY_BLOCK__
 			beforeLoadData: function (id) {
 ${sharedDomainConfigResolverScript}
 				return new Promise((resolve) => {
@@ -450,7 +537,7 @@ ${sharedDomainConfigResolverScript}
 		filter: [],
 		buttons: [],
 		distinct: false,
-		functions: {
+		functions: {__USE_LIBRARY_BLOCK__
 			beforeLoadData: function () {
 ${sharedDomainConfigResolverScript}
 				return new Promise((resolve) => {
@@ -543,7 +630,20 @@ ${sharedDomainConfigResolverScript}
 	const safeDomainKey = typeof domainKey === "string" && domainKey.trim().length > 0 ? domainKey.trim() : "";
 	const safeDomainSource = typeof domainSource === "string" && domainSource.trim().length > 0 ? domainSource.trim() : "";
 	const domainResolverExpression = `(() => { const domains = appConfig && appConfig.domains && typeof appConfig.domains === 'object' ? appConfig.domains : null; if (!domains) { return null; } const preferredDomainKey = ${JSON.stringify(safeDomainKey)}; if (preferredDomainKey && domains[preferredDomainKey]) { return domains[preferredDomainKey]; } if (domains.salesOrderDomain) { return domains.salesOrderDomain; } const domainKeys = Object.keys(domains); return domainKeys.length > 0 ? domains[domainKeys[0]] : null; })()`;
+	/*
+	 * ⚠️ Emitted ONLY when there is something to declare, so a library-less domain publishes exactly
+	 * the template it always did. The list is inlined as JSON rather than computed at runtime: the
+	 * template is read back by `db.service.loadScript` with `JSON.parse`, which then calls this body
+	 * through `new Function` — it has no access to the domain config.
+	 */
+	const safeLibraryModules = Array.isArray(libraryModules)
+		? libraryModules.filter((moduleName) => typeof moduleName === "string" && moduleName.trim().length > 0)
+		: [];
+	const useLibraryBlock =
+		safeLibraryModules.length > 0 ? `\n\t\t\tuseLibrary: function () { return ${JSON.stringify(safeLibraryModules)}; },` : "";
+
 	const resolvedTemplateContent = templateContent
+		.replace(/__USE_LIBRARY_BLOCK__/g, useLibraryBlock)
 		.replace(/"__ENTRY_POINT_NAME__"/g, JSON.stringify(safeEntryPointName))
 		.replace(/"__DOMAIN_SOURCE__"/g, JSON.stringify(safeDomainSource))
 		.replace(
@@ -582,6 +682,11 @@ export const buildPublishBodyFromConfigs = (parsedApplicationConfig, parsedDomai
 			(name) => String(name ?? "").trim().length > 0,
 		),
 	);
+	/* ⚠️ Derived ONCE per domain, from the domain config this call is publishing — every template it
+	   generates belongs to that domain, so they all declare the same library set. See
+	   resolveDomainLibraryModules for why the generated template has to declare it at all. */
+	const libraryModules = resolveDomainLibraryModules(safeDomainConfig);
+
 	let unresolvedTargetIndex = 0;
 	const templateFiles = templateTargets.map((target, targetIndex) => {
 		const explicitDomainReference = String(target.domainKey ?? "").trim();
@@ -612,7 +717,27 @@ export const buildPublishBodyFromConfigs = (parsedApplicationConfig, parsedDomai
 			resolvedDomainKey && domainMap && typeof domainMap === "object" ? String(domainMap?.[resolvedDomainKey]?.source ?? "").trim() : "";
 		return {
 			name: target.fileName,
-			content: buildHardcodedTemplateContent(target.entryPointName, resolvedDomainKey, target.templateType ?? "form", resolvedDomainSource),
+			/*
+			 * ⚠️⚠️ DID THIS DOMAIN ACTUALLY DECLARE THE ENTRY POINT, or did we guess an owner for it?
+			 *
+			 * The guess above walks the other domain keys POSITIONALLY, which is a coin toss once more
+			 * than two domains are registered. `publishApplicationConfig` merges the passes first-wins,
+			 * so whichever domain is scanned first imposed its guess on every template name — and a
+			 * template naming the wrong domain makes the client throw E_ENTRYPOINT_NOT_FOUND, because
+			 * that domain declares no such entry point. Live on db 3: Order-In and several other
+			 * screens, owned by `supertailruntime`, were handed to `hr`.
+			 *
+			 * Every domain IS scanned, so the one that declares it claims it on its own pass. This flag
+			 * is what lets the merge prefer that claim over a guess.
+			 */
+			claimed: configuredEntryPointNames.has(target.entryPointName) && resolvedDomainKey === configuredDomainKey,
+			content: buildHardcodedTemplateContent(
+				target.entryPointName,
+				resolvedDomainKey,
+				target.templateType ?? "form",
+				resolvedDomainSource,
+				libraryModules,
+			),
 		};
 	});
 	const fileList = [{ name: "menu.json", content: menuContent }, ...templateFiles];
@@ -663,9 +788,23 @@ export const publishApplicationConfig = async (payload = {}, argv = {}) => {
 	/* Parsed once in the collect pass, reused in the build pass. */
 	const scannedDomains = [];
 	const seenFileNames = new Set();
+	/*
+	 * ⚠️ FIRST-WINS, EXCEPT THAT A CLAIM BEATS A GUESS. A domain that declares the entry point knows
+	 * it owns the template; a domain that merely got handed it by the positional fallback does not.
+	 * Without this, the domain scanned FIRST decided every template's owner and the screens it does
+	 * not declare answered E_ENTRYPOINT_NOT_FOUND in the browser.
+	 */
 	const addFilesToMergedList = (fileList) => {
 		for (const file of fileList) {
 			if (seenFileNames.has(file.name)) {
+				if (!file.claimed) {
+					continue;
+				}
+				const existingIndex = mergedFileList.findIndex((entry) => entry.name === file.name);
+				if (existingIndex < 0 || mergedFileList[existingIndex].claimed) {
+					continue;
+				}
+				mergedFileList[existingIndex] = file;
 				continue;
 			}
 			seenFileNames.add(file.name);
@@ -735,7 +874,11 @@ export const publishApplicationConfig = async (payload = {}, argv = {}) => {
 		}
 	}
 
-	const publishBody = { verbose: false, fileList: mergedFileList };
+	/* `claimed` is merge bookkeeping, not part of the bundle contract — strip it before it ships. */
+	const publishBody = {
+		verbose: false,
+		fileList: mergedFileList.map(({ name, content }) => ({ name, content })),
+	};
 
 	const response = await publishApp(
 		{