biz-a-cli 2.3.80-15333 → 2.3.80-15339

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,13 @@ 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 {
 	execPostgres,
 	execPostgresStatements,
@@ -477,6 +478,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,6 +504,7 @@ const handleCliCommand = async (data, cb, argv) => {
 						},
 						data.scriptName,
 						liveTriggerPayload,
+						cliScriptPrincipal,
 					),
 				);
 				break;
@@ -735,12 +753,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(
 		{

package/engine/domain/entityConfigLoader.js

@@ -98,3 +98,31 @@ export const createDomainConfigLoader = ({ exec, dbIndex }) => async () => {
 	}
 	return parsed;
 };
+
+/*
+ * ⚠️⚠️ Doc 6 Q5 — A CHEAP FINGERPRINT OF EVERYTHING THE DECLARATIONS ARE BUILT FROM.
+ *
+ * The entity-config cache is per THREAD and was read exactly once per thread, so a publish reached a
+ * running hub only by restarting it. `ensureEntityConfig` re-checks this fingerprint on a timer and
+ * re-primes when it moves.
+ *
+ * ⚠️ NOT `max(id)`. `sys$config` is UPDATED IN PLACE when name+version match, so republishing a
+ * domain at the SAME version — the commonest thing anyone does while iterating — leaves the highest
+ * id untouched. Verified on db 3: 12 rows, max id 14, `supertailsetup` present twice, one row per
+ * version. Only the content answers honestly.
+ *
+ * ⚠️ The hashing happens IN POSTGRES and only the 32-char digest crosses the wire; the configs
+ * themselves are hundreds of KB and must not be shipped every few seconds just to be compared.
+ *
+ * Returns null when the table cannot be read, which the caller treats as "do not change anything".
+ */
+export const readConfigGeneration = async ({ exec, dbIndex }) => {
+	const rows = await exec(
+		`SELECT md5(string_agg(id || ':' || name || ':' || version || ':' || md5(coalesce(data, '')), '|' ORDER BY id)) AS generation FROM ${PG_CONFIG_TABLE}`,
+		dbIndex,
+	);
+	const generation = rows?.[0]?.generation ?? rows?.[0]?.GENERATION ?? null;
+	/* An empty sys$config aggregates to NULL; a stable sentinel keeps "empty" distinguishable from
+	   "unreadable", which is the difference between leaving the cache alone and refreshing it. */
+	return generation == null ? "empty" : String(generation);
+};

package/engine/domain/entityConfigPrimer.js

@@ -27,10 +27,37 @@
  * `entityConfig.js`, and closing that cycle inside the ORM once left `createExecutor` uninitialised.
  */
 import { primeEntityConfig } from "../orm/entityConfig.js";
-import { createDomainConfigLoader } from "./entityConfigLoader.js";
+import { createDomainConfigLoader, readConfigGeneration } from "./entityConfigLoader.js";
 import { execPostgres, isPostgresIndex } from "./dialect.js";
 import { logger } from "../../logger.js";
 
+/*
+ * ⚠️⚠️ Doc 6 Q5 — HOW OFTEN A THREAD ASKS WHETHER THE DECLARATIONS MOVED.
+ *
+ * `resetEntityConfig` had no caller outside tests, so each thread read the declarations once and
+ * kept them: the hub's main thread until restart, a worker for the life of the thread. A publish
+ * that added or changed a declaration simply did not arrive, and the staleness is SILENT — the same
+ * five fallbacks described above, taken because the cache is OLD rather than empty. A newly
+ * soft-delete entity was PHYSICALLY deleted; a newly tenanted table was neither filtered nor stamped.
+ *
+ * The check is one small digest query, so this bounds staleness to seconds rather than to a restart.
+ * It is not zero-cost, which is why it is a TTL and not a per-request read.
+ */
+export const CONFIG_GENERATION_TTL_MS = 5000;
+
+/*
+ * Called with the dbIndex after a refresh ACTUALLY changed the declarations.
+ *
+ * ⚠️ It exists for one specific reason. `bin/hub.js` installs the RLS context applier ONCE, right
+ * after the first prime, gated on `isTenancyDeclared`. An app that declares tenancy for the first
+ * time in a publish would refresh this cache and still have no applier — tenancy declared and NOT
+ * enforced, which is quieter and worse than the stale cache this fixes.
+ */
+let onRefresh = null;
+export const setEntityConfigRefreshHook = (hook) => {
+	onRefresh = typeof hook === "function" ? hook : null;
+};
+
 /*
  * ⚠️ PROMISES, not booleans. A BPM agent runs effects continuously and they all enter through one
  * `run`; several can be in flight inside a single worker at once. Recording "started" as a promise
@@ -51,8 +78,29 @@ const degrade = (dbIndex, reason) => {
 	);
 };
 
+/* dbIndex -> { generation, checkedAt } for the copy this thread currently holds. */
+const freshness = new Map();
+/* dbIndex -> in-flight freshness check, so concurrent callers share one digest query. */
+const checking = new Map();
+
 const primeOnce = async (dbIndex) => {
 	try {
+		/*
+		 * ⚠️ THE FINGERPRINT IS READ BEFORE THE CONFIGS, NEVER AFTER. A publish landing between the
+		 * two reads must cost an EXTRA refresh, never a missed one — taking it afterwards would
+		 * record a fingerprint newer than the data just read, and that change would stay invisible
+		 * until something else happened to publish.
+		 *
+		 * ⚠️ And it must not be fatal: a digest we cannot read is no reason to skip priming. Recording
+		 * `null` simply means the next check has nothing to compare against and refreshes.
+		 */
+		let generation = null;
+		try {
+			generation = await readConfigGeneration({ exec: execPostgres, dbIndex });
+		} catch {
+			generation = null;
+		}
+
 		const loadDomainConfigs = createDomainConfigLoader({
 			exec: execPostgres,
 			dbIndex,
@@ -63,7 +111,10 @@ const primeOnce = async (dbIndex) => {
 		 * try/catch therefore treats a FAILED read as a successful one and memoises the failure
 		 * forever, which is worse than not caching at all. The boolean is the only honest signal.
 		 */
-		if (await primeEntityConfig({ dbIndex, loadDomainConfigs })) return;
+		if (await primeEntityConfig({ dbIndex, loadDomainConfigs })) {
+			freshness.set(dbIndex, { generation, checkedAt: Date.now() });
+			return;
+		}
 		degrade(dbIndex, "declarations could not be read");
 	} catch (error) {
 		/*
@@ -75,6 +126,59 @@ const primeOnce = async (dbIndex) => {
 	}
 };
 
+/*
+ * Doc 6 Q5 — has anything been published since this thread last looked?
+ *
+ * ⚠️ FAILS SOFT IN BOTH DIRECTIONS. A digest we cannot read leaves the declarations exactly as they
+ * are (blinding the thread is the state this module exists to end), and a re-prime that fails leaves
+ * the previous copy in place because `primeEntityConfig` only replaces the maps on success.
+ */
+const refreshIfStale = async (dbIndex) => {
+	const current = freshness.get(dbIndex);
+	const now = Date.now();
+	if (current && now - current.checkedAt < CONFIG_GENERATION_TTL_MS) return;
+
+	let generation;
+	try {
+		generation = await readConfigGeneration({ exec: execPostgres, dbIndex });
+	} catch (error) {
+		/* Checked, not read: wait out another TTL rather than hammering a database in trouble. */
+		if (current) {
+			freshness.set(dbIndex, { ...current, checkedAt: now });
+		}
+		logger.warn(
+			`[entityConfig] could not read the config fingerprint for db ${dbIndex} ` +
+				`(${error?.message ?? error}); keeping the declarations this thread already has.`,
+		);
+		return;
+	}
+
+	if (current && generation === current.generation) {
+		freshness.set(dbIndex, { ...current, checkedAt: now });
+		return;
+	}
+
+	const loadDomainConfigs = createDomainConfigLoader({ exec: execPostgres, dbIndex });
+	if (await primeEntityConfig({ dbIndex, loadDomainConfigs })) {
+		freshness.set(dbIndex, { generation, checkedAt: Date.now() });
+		logger.info(`[entityConfig] db ${dbIndex}: declarations changed since this thread last read them; refreshed.`);
+		if (onRefresh) {
+			/* ⚠️ A broken hook must not cost the refresh that already succeeded. */
+			try {
+				await onRefresh(dbIndex);
+			} catch (error) {
+				logger.warn(`[entityConfig] refresh hook failed for db ${dbIndex}: ${error?.message ?? error}`);
+			}
+		}
+		return;
+	}
+	/* Re-prime failed: the previous declarations stand, and the fingerprint is NOT recorded so the
+	   next check tries again rather than treating the failure as the new truth. */
+	if (current) {
+		freshness.set(dbIndex, { ...current, checkedAt: now });
+	}
+};
+
 /*
  * Prime this thread for `dbIndex` if it has not been primed already. Safe to await on every entry to
  * a worker: after the first call it resolves immediately.
@@ -88,10 +192,32 @@ export const ensureEntityConfig = async (dbIndex) => {
 	if (!Number.isFinite(index) || !isPostgresIndex(index)) return;
 	if (!priming.has(index)) {
 		priming.set(index, primeOnce(index));
+		await priming.get(index);
+		return;
 	}
 	await priming.get(index);
+
+	/*
+	 * Doc 6 Q5 — already primed, so ask (at most once per TTL) whether it is still true.
+	 *
+	 * ⚠️ Held as a PROMISE for the same reason the priming above is: several effects run concurrently
+	 * inside one worker and a whole console-load's worth of requests arrive together on the hub, so
+	 * they share ONE digest query instead of each issuing their own.
+	 */
+	if (!checking.has(index)) {
+		checking.set(
+			index,
+			refreshIfStale(index).finally(() => checking.delete(index)),
+		);
+	}
+	await checking.get(index);
 };
 
 /* Test hook. The cache it fronts has `resetEntityConfig`; this clears the "already started" record so
-   a test can prime again. */
-export const resetEntityConfigPrimer = () => priming.clear();
+   a test can prime again — and the freshness record with it, or the next prime would be judged
+   against a fingerprint belonging to declarations that are no longer there. */
+export const resetEntityConfigPrimer = () => {
+	priming.clear();
+	freshness.clear();
+	checking.clear();
+};

package/engine/orm/rlsPolicy.js

@@ -276,7 +276,18 @@ export const buildRlsSyncPlan = (table, rlsRows, policyRows) => {
 	}
 
 	const live = (Array.isArray(policyRows) ? policyRows : []).map(readPolicyRow);
-	const find = (policy) => live.find((row) => row.name === policy);
+	/*
+	 * ⚠️⚠️ CASE-INSENSITIVE, because PostgreSQL folds unquoted identifiers. A policy created on
+	 * `ST_OUTLET` comes back from pg_policies as `st_outlet_tenant_write`, while `writePolicyName`
+	 * keeps the DECLARATION's case. Comparing them verbatim never matched, so every policy looked
+	 * MISSING on every publish, took the create branch, and the guarded CREATE swallowed
+	 * `duplicate_object` — which meant the live policy was never compared and drift was never
+	 * corrected. The whole replace-on-drift path below was unreachable.
+	 *
+	 * Found live on db 3: a changed write predicate survived `--publish` and `--publish --forceFull`
+	 * untouched, while the log reported the policy as missing each time.
+	 */
+	const find = (policy) => live.find((row) => row.name.toLowerCase() === String(policy).toLowerCase());
 
 	/*
 	 * Create, or replace when what is live no longer says what it must.
@@ -307,7 +318,25 @@ export const buildRlsSyncPlan = (table, rlsRows, policyRows) => {
 	};
 
 	const readScope = buildTenantPredicate(tenantColumn);
-	const writeCheck = buildActiveTenantCheck(tenantColumn);
+	/*
+	 * ⚠️⚠️ THE TENANT TABLE IS NOT A TENANT-SCOPED TABLE, and its write scope is not the same question.
+	 *
+	 * §9.2 makes this check SCALAR on purpose, and for a scoped table that stands: its tenant column
+	 * says which outlet a row BELONGS TO, so checking against the whole read set would let a screen
+	 * opened in one context file a row into another. That is the data-corruption vector.
+	 *
+	 * On the TENANT TABLE the tenant column is the row's own `id`. Writing there renames the outlet;
+	 * it cannot misfile anything into it, because the row IS the outlet. Holding it to the scalar
+	 * active tenant meant an administrator bound to two outlets could only ever edit whichever one
+	 * their DEVICE was assigned to -- and the console that sets that assignment is itself an outlet
+	 * list. Live on db 3: user 3 holds both outlets, and editing either answered 403 until the active
+	 * tenant was set, after which the OTHER one answered 403.
+	 *
+	 * So the relaxation is scoped to the tenant table and nowhere else.
+	 */
+	const isTenantTable = table?.isTenantTable === true;
+	const writeCheck = isTenantTable ? readScope : buildActiveTenantCheck(tenantColumn);
+	const writeCheckSetting = isTenantTable ? TENANT_SETTING : ACTIVE_TENANT_SETTING;
 
 	ensure(
 		readPolicyName(name),
@@ -325,12 +354,16 @@ export const buildRlsSyncPlan = (table, rlsRows, policyRows) => {
 	 */
 	ensure(
 		writePolicyName(name),
-		`write predicate (${tenantColumn} against ${TENANT_SETTING}, checked against ${ACTIVE_TENANT_SETTING})`,
+		`write predicate (${tenantColumn} against ${TENANT_SETTING}, checked against ${writeCheckSetting})`,
 		`CREATE POLICY ${writePolicyName(name)} ON ${name} FOR ALL USING (${readScope}) WITH CHECK (${writeCheck})`,
+		/* ⚠️ A check naming the OTHER setting is drift in both directions: a scoped table carrying the
+		   tenant table's relaxed check reopens §9.2, and a tenant table still carrying the scalar one
+		   keeps an administrator locked to one outlet. */
 		(row) =>
 			row.cmd === "ALL" &&
 			mentions(row.qual, tenantColumn, TENANT_SETTING) &&
-			mentions(row.check, tenantColumn, ACTIVE_TENANT_SETTING),
+			mentions(row.check, tenantColumn, writeCheckSetting) &&
+			!mentions(row.check, tenantColumn, isTenantTable ? ACTIVE_TENANT_SETTING : TENANT_SETTING),
 	);
 
 	/* See insertPolicyName: without this a new tenant row could never be created. */

package/engine/orm/tenantApi.js

@@ -326,11 +326,29 @@ export const createTenantApi = ({
 	 * §7.3 lists only `revoke`. Without this the correction is inexpressible through the API, which
 	 * leaves a direct table write as the only option — the exact thing §7.3 exists to prevent.
 	 */
-	const deactivate = async ({ id }) => {
+	const deactivate = async ({ id = null, sourceRef = null }) => {
+		/*
+		 * ⚠️ Addressable by sourceRef as `revoke` is, and for a reason found live: a swap or a cancel
+		 * of a FUTURE-dated duty revokes nothing (revoke matches only rows in force, since stamping
+		 * `expired_at = now()` on a future row would violate `expired_at > issued_at`), leaving the
+		 * previous holder a grant for a shift they no longer have. §7.2's correction is the right one
+		 * — the row never took effect — but the bridge knows only the duty it created, not the
+		 * assignment id. Without this the correction was inexpressible through the API.
+		 */
+		if (id === null && sourceRef === null) {
+			throw new Error(
+				"deactivate needs an id or a sourceRef — refusing to deactivate every assignment (Doc 4 §7.3).",
+			);
+		}
+		const target =
+			id !== null
+				? `ut.ID = ${literal(assertUuid(id, "id"))}::uuid`
+				: `ut.SOURCE_REF = ${literal(assertUuid(sourceRef, "sourceRef"))}::uuid`;
+
 		const rows =
 			(await run(
 				`UPDATE SYS$USER_TENANT ut SET ACTIVE = false ` +
-					`WHERE ut.ID = ${literal(assertUuid(id, "id"))}::uuid AND ut.ACTIVE ` +
+					`WHERE ${target} AND ut.ACTIVE ` +
 					"RETURNING ut.USER_ID",
 			)) ?? [];
 		for (const user of new Set(rows.map((row) => row?.user_id ?? row?.USER_ID))) {

package/engine/orm/userGroups.js

@@ -0,0 +1,62 @@
+/*
+ * Doc 6 §8.3 — which usergroups a VERIFIED caller holds.
+ *
+ * ⚠️ WHY THIS IS PLATFORM CODE. `hrextensionlib.maySupervise` compares `hr_config.rights.dutyExtend`
+ * against the groups its actor holds, and Doc 5 §1–2 forbids a Layer 3 domain from touching any
+ * `sys$` table — its own tests enforce that. So the domain states the right it needs and the platform
+ * answers who holds what; the script receives names and never learns where they came from.
+ *
+ * ⚠️ IT ANSWERS ONLY FOR AN ALREADY-VERIFIED USER ID. Nothing here authenticates anybody: the id
+ * comes from inside a signature (security/internalPrincipal.js), and handing this a caller-supplied
+ * id would let anyone enumerate somebody else's rights.
+ */
+import { logger } from "../../logger.js";
+
+const MEMBERSHIP_TABLE = "sys$ugmember";
+const GROUP_TABLE = "sys$usergroup";
+
+/*
+ * The statement, or null when the id is not a plain number.
+ *
+ * ⚠️ NUMERIC OR NOTHING. This id is interpolated, so a value that is not a number must never reach
+ * the statement — returning null is the fail-closed answer, and the caller turns it into "no groups".
+ */
+export const buildUserGroupsSql = (userId) => {
+	/* ⚠️ Reject the empties BEFORE coercing: Number(null) and Number([]) are both 0, a perfectly
+	   valid-looking integer that would build a statement asking about user zero. */
+	if (userId === null || userId === undefined || userId === "") return null;
+	if (typeof userId === "object" || typeof userId === "boolean") return null;
+	const id = Number(userId);
+	if (!Number.isInteger(id)) return null;
+	return (
+		`SELECT g.group_name FROM ${MEMBERSHIP_TABLE} m ` +
+		`INNER JOIN ${GROUP_TABLE} g ON g.id = m."sys$usergroup_id" ` +
+		`WHERE m.user_id = ${id}`
+	);
+};
+
+/*
+ * The group names this user holds, or [].
+ *
+ * ⚠️ FAIL-CLOSED IN EVERY DIRECTION. An unreadable table, an odd row shape, a missing id — all yield
+ * NO groups. A rights check reading an empty list refuses, which is the safe outcome; a read that
+ * failed open would hand out the supervisor right on a database hiccup.
+ */
+export const resolveUserGroups = async ({ exec, dbIndex, userId }) => {
+	const sql = buildUserGroupsSql(userId);
+	if (!sql || typeof exec !== "function") return [];
+
+	try {
+		const rows = await exec(sql, dbIndex);
+		if (!Array.isArray(rows)) return [];
+		return rows
+			.map((row) => String(row?.group_name ?? row?.GROUP_NAME ?? "").trim())
+			.filter((name) => name.length > 0);
+	} catch (error) {
+		logger.warn(
+			`[principal] could not read usergroups for user ${userId}: ${error?.message ?? error}. ` +
+				"Treating the caller as holding none, so any right checked against them is refused.",
+		);
+		return [];
+	}
+};

package/package.json

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

package/scheduler/datalib.js

@@ -160,10 +160,44 @@ export async function setLibrary(config, libraries, defaultLib) {
 	return libs;
 }
 
+/*
+ * ⚠️⚠️ WHO THE SERVER VERIFIED IS ASKING — normalised, or null.
+ *
+ * Doc 6 §8.3 needed a right (`rights.dutyExtend`) checked inside a CLI script, and a script had only
+ * caller-shaped data to go on: gating on that would be security theatre, so the supervisor path was
+ * shut by construction rather than half-built.
+ *
+ * ⚠️ NULL IS THE FAIL-CLOSED ANSWER and it is the common one: `/cb` is an unauthenticated webhook
+ * surface and cron has no user at all. A script that gates on identity must refuse a null principal,
+ * never assume one.
+ *
+ * ⚠️ Anything it does not positively recognise becomes null. A principal is an authorisation input;
+ * "some object arrived" is not the same as "a caller was verified".
+ */
+const normalisePrincipal = (principal) => {
+	if (!principal || typeof principal !== "object" || Array.isArray(principal)) return null;
+	const actorType = String(principal.actorType ?? "").trim();
+	if (!actorType) return null;
+	return Object.freeze({
+		actorType,
+		userId: principal.userId ?? null,
+		sessionId: principal.sessionId ?? null,
+		dbIndex: principal.dbIndex ?? null,
+		subdomain: principal.subdomain ?? null,
+		/* Frozen too: a script that could push onto it would widen its own tenant scope. */
+		tenantIds: Object.freeze(Array.isArray(principal.tenantIds) ? [...principal.tenantIds] : []),
+		/* Doc 6 §8.3 — the usergroups this caller holds, resolved by the platform (a Layer 3 domain
+		   may not read sys$ tables). Frozen for the same reason: a script that could push onto it
+		   would grant itself the very right it is about to check. */
+		groups: Object.freeze(Array.isArray(principal.groups) ? [...principal.groups] : []),
+	});
+};
+
 export async function extractFunctionScript(
 	selectedConfig,
 	data,
 	extraLib = {},
+	principal = null,
 ) {
 	const config = getConfig(selectedConfig);
 
@@ -212,6 +246,19 @@ export async function extractFunctionScript(
 		);
 	}
 
+	/*
+	 * ⚠️ DEFINED LAST, AND NOT WRITABLE. It has to survive both `...extraLib` above and the loaded
+	 * libraries merged in just now — a value whose entire purpose is that the script cannot choose it
+	 * must not be shadowable by anything the script can influence, including a library it names in
+	 * its own useLibrary.
+	 */
+	Object.defineProperty(lib, "principal", {
+		value: normalisePrincipal(principal),
+		writable: false,
+		configurable: false,
+		enumerable: true,
+	});
+
 	return scriptFn(lib).functions;
 }
 

package/security/internalPrincipal.js

@@ -199,3 +199,36 @@ export function authorizeRequest(headers, { mode = "observe", exempt = false, no
 		allowed: exempt || mode === "observe" ? true : valid,
 	};
 }
+
+/*
+ * ⚠️⚠️ Doc 6 §8.3 — WHO IS ASKING, for a CLI script.
+ *
+ * A CLI script had no identity: the internal cliCommand dispatch "trusts caller-supplied
+ * identity/roles" (engine/ext/cliInvoke.js says so in its own header), so §8.3's supervisor path was
+ * shut by construction rather than half-built. This turns the SIGNED principal the client already
+ * sends on HTTP into one a script can trust.
+ *
+ * ⚠️ EVERYTHING IT REPORTS COMES FROM INSIDE THE SIGNATURE. `dbIndex`, `subdomain` and `tenantIds`
+ * are taken from the verified claims and never from the surrounding request, because a caller that
+ * could nominate its own tenant list would be choosing its own authority. The socket payload around
+ * this is entirely caller-shaped — `engine/ext/esb.js` already had to learn to ignore a handshake
+ * `userId` for the same reason.
+ *
+ * ⚠️ NULL IS THE NORMAL ANSWER and it is fail-closed: `/cb` is an unauthenticated webhook surface and
+ * cron has no user. `mode` decides whether a REQUEST is refused elsewhere; it never fabricates an
+ * identity here, so observe and enforce agree on who the caller is.
+ */
+export function principalForCliScript(headers, { mode = "observe", now = Date.now() } = {}) {
+	const decision = authorizeRequest(headers, { mode, now });
+	const claims = decision.claims;
+	if (!claims) return null;
+
+	return {
+		actorType: "USER",
+		userId: claims.userId ?? null,
+		sessionId: claims.sid ?? null,
+		dbIndex: claims.dbIndex ?? null,
+		subdomain: claims.subdomain ?? null,
+		tenantIds: Array.isArray(claims.tenantIds) ? claims.tenantIds : [],
+	};
+}

package/worker/cliScriptWorker.js

@@ -2,6 +2,8 @@ import workerpool from "workerpool";
 import { loadCliScript, extractFunctionScript } from "../scheduler/datalib.js";
 import * as db from "../db/db.js";
 import { ensureEntityConfig } from "../engine/domain/entityConfigPrimer.js";
+import { resolveUserGroups } from "../engine/orm/userGroups.js";
+import { execPostgres } from "../engine/domain/dialect.js";
 import { logger } from "../logger.js";
 
 // export const run = async (apiConfig, scriptIdentifier, scriptData) => {
@@ -35,7 +37,15 @@ import { logger } from "../logger.js";
 // 	}
 // };
 
-export const run = async (apiConfig, scriptIdentifier, scriptData) => {
+/*
+ * ⚠️⚠️ `principal` IS A SEPARATE ARGUMENT, NOT A FIELD ON `scriptData`.
+ *
+ * Every entrance builds `scriptData` out of what the caller sent, and script authors are trained
+ * to unwrap `scriptData.body` (the BPM effect wrapper). A principal living in there would be both
+ * forgeable by the caller and easy to read by mistake. Kept apart, it can only come from the code
+ * that actually verified it — see scheduler/datalib.js normalisePrincipal.
+ */
+export const run = async (apiConfig, scriptIdentifier, scriptData, principal = null) => {
 	const searchBy =
 		typeof scriptIdentifier === "object"
 			? scriptIdentifier.searchBy
@@ -196,10 +206,32 @@ export const run = async (apiConfig, scriptIdentifier, scriptData) => {
 		injectESBMethods(extraLib);
 		injectDBMethods(extraLib, apiConfig);
 
+		/*
+		 * Doc 6 §8.3 — the groups a VERIFIED caller holds, resolved HERE rather than by the script.
+		 *
+		 * ⚠️ A Layer 3 domain may not read `sys$` tables (Doc 5 §1–2, enforced by its own tests), so it
+		 * states the right it needs and the platform answers who holds what. Fail-closed: an
+		 * unreadable membership table yields none, and a rights check against an empty list refuses.
+		 *
+		 * ⚠️ Only for a principal that was actually verified — the id comes from inside a signature,
+		 * never from the request.
+		 */
+		const principalWithGroups = principal
+			? {
+					...principal,
+					groups: await resolveUserGroups({
+						exec: execPostgres,
+						dbIndex: db.resolveDbIndex(apiConfig),
+						userId: principal.userId,
+					}),
+				}
+			: null;
+
 		const functions = await extractFunctionScript(
 			apiConfig,
 			await loadCliScript(apiConfig, searchBy, searchValue),
 			extraLib,
+			principalWithGroups,
 		);
 
 		const result =

package/worker/cliWorkerPool.js

@@ -36,6 +36,12 @@ export const execCLIScriptWorker = async (
 	apiConfig,
 	scriptName,
 	scriptData,
+	/*
+	 * ⚠️ WHO THE ENTRANCE VERIFIED, or null. Each caller passes only what it has actually
+	 * verified: `/cb` is an unauthenticated webhook surface and cron has no user, so both pass
+	 * nothing. Kept OUT of `scriptData` on purpose — that is the caller's own payload.
+	 */
+	principal = null,
 ) => {
 	// callback
 	// {
@@ -78,7 +84,10 @@ export const execCLIScriptWorker = async (
 	}
 	const safeConfig = JSON.parse(JSON.stringify(apiConfig || {}));
 
-	return cliScriptWorkerPool.exec("run", [safeConfig, scriptName, safeData], {
+	/* Serialised like everything else crossing the thread boundary; normalised on arrival. */
+	const safePrincipal = principal ? JSON.parse(JSON.stringify(principal)) : null;
+
+	return cliScriptWorkerPool.exec("run", [safeConfig, scriptName, safeData, safePrincipal], {
 		on: (message) => {
 			// Catch the relay and bounce it to the main thread
 			if (message && message.type === "IPC_RELAY") {