biz-a-cli 2.3.80-15407 → 2.3.80-15419

package/bin/app.js

@@ -27,6 +27,8 @@ import {
 } from "../engine/domain/themeConfig.js";
 import {
 	APP_CONFIG_NAME,
+	appConfigNameFor,
+	secondaryAppNameOf,
 	buildEnsureConfigTableSql,
 	buildPostgresConfigUpsertSql,
 	buildPostgresApplicationConfigLookupSql,
@@ -56,6 +58,7 @@ import { validateTenancyDeclaration } from "../engine/orm/tenancyDeclaration.js"
 import { logger } from "../logger.js";
 import { findRawColorsInSource } from "../engine/domain/styleColors.js";
 import { resolveMenuLayout } from "../engine/domain/domainNavigation.js";
+import { bumpPatch, registerDomainVersions, unregisterDomains } from "../engine/domain/domainRegistration.js";
 
 const getKeyFolderPath = () => {
 	const scriptPath =
@@ -162,6 +165,13 @@ const addCommandOptions = {
 		demandOption: false,
 		default: false,
 	},
+	register: {
+		describe:
+			"Config mode for a directory of DOMAIN configs only (no application.js): upload them and ADD them to the tenant's application config, keeping everything else in it (other apps, Control Center's domains, menus). For a second application on a tenant. PostgreSQL only",
+		type: "boolean",
+		demandOption: false,
+		default: false,
+	},
 };
 
 const removeCommandOptions = {
@@ -395,7 +405,9 @@ const findApplicationConfigFile = (fileNames = []) =>
    gate exists to validate app scripts before they are bundled, and a config directory has nothing
    to test — worse, jest exits non-zero there ("Could not find a config file", after traversing up),
    which would abort the upload outright. */
-const isConfigModeDir = (workingDir, files = null) => {
+const isConfigModeDir = (workingDir, files = null, { register = false } = {}) => {
+	/* Doc 8 — `--register` ships domain configs with no application.js: config mode by declaration. */
+	if (register) return true;
 	try {
 		return !!findApplicationConfigFile(
 			getFileList({ workingDir: path.resolve(workingDir), files }),
@@ -525,7 +537,15 @@ const collectConfigUploads = ({ workingDir, fileNames = [], include = [] }) => {
 				`${path.basename(applicationFile)}: metadata.version "${version}" must be semantic (x.y.z).`,
 			);
 		}
-		application = { name: APP_CONFIG_NAME, version, content };
+		/* Doc 8 (2026-10-10): an application.js declaring `metadata.app` is ANOTHER application on the tenant, saved
+		   as `APPLICATION_CONFIG.<app>` beside the host's (engine/domain/appConfig.js appConfigNameFor). */
+		let name = APP_CONFIG_NAME;
+		try {
+			name = appConfigNameFor(parseConfigForVersion(content)?.metadata);
+		} catch (error) {
+			problems.push(`${path.basename(applicationFile)}: ${error?.message ?? error}`);
+		}
+		application = { name, version, content };
 	}
 
 	/*
@@ -543,7 +563,12 @@ const collectConfigUploads = ({ workingDir, fileNames = [], include = [] }) => {
 	const themeFile = fileNames.find(
 		(f) => path.basename(String(f)).toLowerCase() === THEME_CONFIG_FILE,
 	);
-	if (themeFile) {
+	if (themeFile && secondaryAppNameOf(application?.name)) {
+		problems.push(
+			`${path.basename(String(themeFile))}: the theme is the tenant's, published with its host application — ` +
+				`not with ${application.name}.`,
+		);
+	} else if (themeFile) {
 		const { theme: parsedTheme, problems: themeProblems } = validateThemeSource(
 			readConfig(themeFile),
 		);
@@ -688,6 +713,89 @@ const preserveApplicationAdditions = async (application, apiConfig) => {
 	};
 };
 
+/*
+ * Doc 8 — `--register`: what the domains are added to, read BEFORE anything is written.
+ *
+ * ⚠️ The tenant's NEWEST application config, the row every reader takes (buildPostgresApplicationConfigLookupSql).
+ * Refused when the directory carries its own application.js (that is the replacing mode), on Firebird (PostgreSQL
+ * only, as Control Center), and when the tenant has no application config yet (there is nothing to add to — the
+ * host application comes first).
+ */
+const readRegistrationBase = async ({ application, dbIndex }) => {
+	if (application) {
+		throw new Error(
+			"--register adds domains to the tenant's application config, but this directory has application.js, which would " +
+				"REPLACE it. Upload the domains without application.js, or drop --register.",
+		);
+	}
+	if (!isPostgresIndex(dbIndex)) {
+		throw new Error(`--register needs a PostgreSQL database; index ${dbIndex} is not one.`);
+	}
+	const row = (await execPostgres(buildPostgresApplicationConfigLookupSql(), dbIndex))?.[0];
+	if (!row?.data) {
+		throw new Error(
+			"--register: this database has no application config to add the domains to. Upload the host application first.",
+		);
+	}
+	return { version: String(row.version ?? ""), config: parseConfigForVersion(String(row.data)) };
+};
+
+/*
+ * Doc 8 — `--register`: name the uploaded domains in the application config, as Control Center's publish does
+ * (engine/domain/domainRegistration.js). Answers the row the application publish must rebuild.
+ *
+ * Already named at these versions → nothing is written. Otherwise a NEW patch version, so the row every reader takes
+ * is the one that names them; every other key (other apps' domains, menus, theme) comes through unchanged.
+ */
+const registerUploadedDomains = async ({ registration, domains, dbIndex, saveOne }) => {
+	const next = registerDomainVersions(registration.config, new Map(domains.map(({ name, version }) => [name, version])));
+	if (JSON.stringify(next) === JSON.stringify(registration.config)) {
+		logger.info(`${APP_CONFIG_NAME}@${registration.version} already names ${domains.map((d) => `${d.name}@${d.version}`).join(", ")}; not rewritten`);
+		return { name: APP_CONFIG_NAME, version: registration.version };
+	}
+
+	const version = bumpPatch(registration.version);
+	if (next.metadata && typeof next.metadata === "object" && next.metadata.version !== undefined) next.metadata.version = version;
+	await saveOne({ name: APP_CONFIG_NAME, version, content: renderApplicationConfig(next) });
+	logger.info(`registered ${domains.map((d) => d.name).join(", ")} in ${APP_CONFIG_NAME}@${version}`);
+
+	/* Control Center checks a draft against the row it started from, so an open application draft is now behind. */
+	try {
+		const open = await execPostgres("SELECT ID FROM SYS$CC_DRAFT WHERE KIND = 'APPLICATION' AND STATUS = 'OPEN'", dbIndex);
+		if (open?.length) {
+			logger.warn(
+				"Control Center has an open application draft, which started from the previous application config. " +
+					"Publishing it will be refused as stale until it is re-opened from the current one.",
+			);
+		}
+	} catch {
+		/* No Control Center tables on this tenant: nothing to warn about. */
+	}
+	return { name: APP_CONFIG_NAME, version };
+};
+
+/*
+ * Doc 8 (2026-10-10) — a SECONDARY application (`APPLICATION_CONFIG.<app>`), checked BEFORE anything is written.
+ *
+ * PostgreSQL only, as --register. And never the host's own SYS$APPS row: the host's row is keyed by its display name,
+ * so an app named like it would publish over the host's bundle.
+ */
+const assertSecondaryApplication = async ({ application, dbIndex }) => {
+	const app = secondaryAppNameOf(application.name);
+	if (!isPostgresIndex(dbIndex)) {
+		throw new Error(`${application.name}: a second application on a tenant needs a PostgreSQL database; index ${dbIndex} is not one.`);
+	}
+	const host = (await execPostgres(buildPostgresApplicationConfigLookupSql(), dbIndex))?.[0];
+	const hostConfig = host?.data ? parseConfigForVersion(String(host.data)) : null;
+	const hostApp = normalizeAppName(hostConfig?.metadata?.name);
+	if (hostApp && hostApp === app) {
+		throw new Error(
+			`metadata.app "${app}" is the host application's own row (${APP_CONFIG_NAME} "${hostConfig.metadata.name}"); ` +
+				"name the second application something else.",
+		);
+	}
+};
+
 async function uploadConfigs({
 	workingDir,
 	fileNames,
@@ -700,6 +808,7 @@ async function uploadConfigs({
 	forceFull = false,
 	releaseCc = false,
 	serverMode = "prod",
+	register = false,
 }) {
 	/* Phase B2: ask biz-a for this tenant's database coordinates before anything reads the
 	   dialect. A deployed CLI has no config/databases.json, so without this the registry
@@ -715,6 +824,11 @@ async function uploadConfigs({
 		include,
 	});
 
+	/* Doc 8 — `--register`: these domains are ADDED to the tenant's application config, never replace it. Every
+	   refusal happens here, before anything is written. */
+	const registration = register ? await readRegistrationBase({ application, dbIndex }) : null;
+	if (secondaryAppNameOf(application?.name)) await assertSecondaryApplication({ application, dbIndex });
+
 	const apiConfig = {
 		url: `${server}:${apiPort}`,
 		dbindex: dbIndex,
@@ -791,12 +905,20 @@ async function uploadConfigs({
 		await saveOne(domain);
 	}
 
+	/* The application config the publish below rebuilds: the uploaded one, or — with --register — the tenant's
+	   newest one, now naming these domains. */
+	let applicationTarget = application ? { name: application.name, version: application.version } : null;
+	if (registration) {
+		applicationTarget = await registerUploadedDomains({ registration, domains, dbIndex, saveOne });
+	}
+
 	if (!publish) {
 		return {
 			success: true,
 			data: {
 				applicationConfig: application,
 				domains: domains.map(({ name, version }) => ({ name, version })),
+				...(registration ? { registeredIn: applicationTarget } : {}),
 			},
 		};
 	}
@@ -838,7 +960,7 @@ async function uploadConfigs({
 		logger.info(`published ${domain.name}@${domain.version}`);
 	}
 
-	if (application) {
+	if (applicationTarget) {
 		/* publishApplicationConfig -> publishApp -> addApp({ workingDir: process.cwd() }), and
 		   addApp folds getFileList(cwd) into the bundle. cwd is the CONFIG directory right now, so
 		   without this the configs themselves would be packed as app scripts. Run the publish from
@@ -851,8 +973,8 @@ async function uploadConfigs({
 			process.chdir(scratchDir);
 			const result = await publishApplicationConfig(
 				{
-					applicationConfigName: application.name,
-					applicationConfigVersion: application.version,
+					applicationConfigName: applicationTarget.name,
+					applicationConfigVersion: applicationTarget.version,
 					dbIndex,
 					url: apiConfig.url,
 					subdomain: sub,
@@ -861,10 +983,10 @@ async function uploadConfigs({
 			);
 			if (!result || result.success !== true) {
 				throw new Error(
-					`Publish ${application.name}@${application.version} failed: ${result?.error ?? "no error message from server"}`,
+					`Publish ${applicationTarget.name}@${applicationTarget.version} failed: ${result?.error ?? "no error message from server"}`,
 				);
 			}
-			logger.info(`published ${application.name}@${application.version}`);
+			logger.info(`published ${applicationTarget.name}@${applicationTarget.version}`);
 		} finally {
 			process.chdir(previousCwd);
 			fs.rmSync(scratchDir, { force: true, recursive: true });
@@ -881,6 +1003,79 @@ async function uploadConfigs({
 	};
 }
 
+/*
+ * Doc 8 (2026-10-10) — `biza unregister --domains a,b [--publish]`: the inverse of --register. Takes the domains OUT of
+ * the host APPLICATION_CONFIG (their entries and the menu leaves their publishes stamped; engine/domain/
+ * domainRegistration.js unregisterDomains) as a new patch version, and with --publish rebuilds the host from it.
+ *
+ * The domain configs themselves stay in sys$config, and their tables stay in the database — only the host stops
+ * naming them. How a domain moves out of the host into its own application.
+ *
+ * PostgreSQL only, as --register. A domain Control Center owns is refused: it is CC's to publish.
+ */
+async function unregisterAppDomains({
+	domains,
+	server = "http://localhost",
+	apiPort = 212,
+	dbIndex = 2,
+	sub,
+	publish = false,
+	serverMode = "prod",
+} = {}) {
+	try {
+		await primeRegistry({ subdomain: sub, serverLink: resolveServerLink(serverMode) });
+
+		const names = String(domains ?? "")
+			.split(",")
+			.map((name) => name.trim())
+			.filter(Boolean);
+		if (names.length === 0) throw new Error("unregister: name the domains to take out with --domains a,b.");
+		if (!isPostgresIndex(dbIndex)) throw new Error(`unregister needs a PostgreSQL database; index ${dbIndex} is not one.`);
+
+		await guardCcOwnedDomains({ exec: (sql) => execPostgres(sql, dbIndex), domainNames: names, releaseCc: false });
+
+		const row = (await execPostgres(buildPostgresApplicationConfigLookupSql(), dbIndex))?.[0];
+		if (!row?.data) throw new Error("unregister: this database has no application config.");
+		const current = parseConfigForVersion(String(row.data));
+		const { config: next, removed } = unregisterDomains(current, names);
+		if (removed.length === 0) {
+			logger.info(`${APP_CONFIG_NAME}@${row.version} names none of ${names.join(", ")}; not rewritten`);
+			return { success: true, data: { removed } };
+		}
+
+		const version = bumpPatch(String(row.version ?? ""));
+		if (next.metadata && typeof next.metadata === "object" && next.metadata.version !== undefined) next.metadata.version = version;
+		await execPostgres(buildEnsureConfigTableSql(), dbIndex);
+		await execPostgres(buildPostgresConfigUpsertSql(APP_CONFIG_NAME, version, renderApplicationConfig(next), false), dbIndex);
+		logger.info(`unregistered ${removed.join(", ")} from ${APP_CONFIG_NAME}@${version}`);
+
+		if (publish) {
+			const { publishApplicationConfig } = await import("../engine/domain/applicationConfig.js");
+			/* From an empty scratch dir, as uploadConfigs: addApp folds the working dir's own files into the bundle. */
+			const scratchDir = fs.mkdtempSync(path.join(os.tmpdir(), "biza-publish-"));
+			const previousCwd = process.cwd();
+			try {
+				process.chdir(scratchDir);
+				const result = await publishApplicationConfig(
+					{ applicationConfigName: APP_CONFIG_NAME, applicationConfigVersion: version, dbIndex, url: `${server}:${apiPort}`, subdomain: sub },
+					{ server, port: apiPort, dbindex: dbIndex, subdomain: sub, serverMode },
+				);
+				if (!result || result.success !== true) {
+					throw new Error(`Publish ${APP_CONFIG_NAME}@${version} failed: ${result?.error ?? "no error message from server"}`);
+				}
+				logger.info(`published ${APP_CONFIG_NAME}@${version}`);
+			} finally {
+				process.chdir(previousCwd);
+				fs.rmSync(scratchDir, { force: true, recursive: true });
+			}
+		}
+		return { success: true, data: { removed, version, published: !!publish } };
+	} catch (error) {
+		logger.error(error?.message ?? error);
+		return { success: false, error: error?.message ?? String(error) };
+	}
+}
+
 const parseApplicationConfigData = (rawConfig) => {
 	if (rawConfig == null) {
 		return null;
@@ -1027,6 +1222,12 @@ async function addApp({
 	serverMode = "prod",
 	/* Extra directories whose DOMAIN configs upload alongside this one's (see --include). */
 	include = [],
+	/* Doc 8 — add the domains to the tenant's application config instead of replacing it (see --register). */
+	register = false,
+	/* Doc 8 (2026-10-10) — the SYS$APPS row this publish writes, from the config being published
+	   (applicationConfig.js appMetadataOf): { appName, displayName, menuLayout }. Without it the row is named
+	   from the host APPLICATION_CONFIG, as before. */
+	appMeta = null,
 } = {}) {
 	const oldCwd = process.cwd();
 
@@ -1069,7 +1270,7 @@ async function addApp({
 		   SYS$CONFIG rows, not libs — upload the configs instead of packing a bundle. Guarded on
 		   `body == null` so the publish path (publishApplicationConfig -> publishApp -> addApp with
 		   generated template scripts) can never recurse back into config mode. */
-		if (body == null && findApplicationConfigFile(mergedSourceFiles)) {
+		if (body == null && (register || findApplicationConfigFile(mergedSourceFiles))) {
 			return await uploadConfigs({
 				workingDir: process.cwd(),
 				fileNames: mergedSourceFiles,
@@ -1082,6 +1283,7 @@ async function addApp({
 				forceFull,
 				releaseCc,
 				serverMode,
+				register,
 			});
 		}
 
@@ -1171,13 +1373,14 @@ async function addApp({
 				: `${server}:${apiPort}/${baseUrl}`;
 
 			const headers = { "Content-Type": "text/plain" };
-			const { displayName: appDisplayName, menuLayout } =
-				await resolveAppMetadataFromApplicationConfig({
-					server,
-					apiPort,
-					dbIndex,
-					sub,
-				});
+			const { displayName: appDisplayName, menuLayout } = appMeta?.appName
+				? { displayName: String(appMeta.displayName ?? "").trim(), menuLayout: appMeta.menuLayout ?? null }
+				: await resolveAppMetadataFromApplicationConfig({
+						server,
+						apiPort,
+						dbIndex,
+						sub,
+					});
 			const useApplicationConfigName = body != null;
 			if (useApplicationConfigName && appDisplayName.length > 0) {
 				keys.metadata["name"] = appDisplayName;
@@ -1187,9 +1390,11 @@ async function addApp({
 			if (useApplicationConfigName && menuLayout) {
 				keys.metadata["menuLayout"] = menuLayout;
 			}
-			const uploadAppName = normalizeAppName(
-				(useApplicationConfigName ? appDisplayName : "") || bundleName,
-			);
+			const uploadAppName = appMeta?.appName
+				? normalizeAppName(appMeta.appName)
+				: normalizeAppName(
+						(useApplicationConfigName ? appDisplayName : "") || bundleName,
+					);
 			/* SYS$APPS is a Biz-A table, not a FINA one, so a PostgreSQL tenant is written
 			   directly — no FINA server in the path at all. On Firebird the FINA stored
 			   procedure TOrmMethod/"setApp" still owns the write. */
@@ -1312,7 +1517,7 @@ const buildCli = () =>
 			addCommandOptions,
 			async (commandOptions) => {
 				/* Config mode uploads SYS$CONFIG rows, not app scripts — skip the jest gate. */
-				if (isConfigModeDir(commandOptions.workingDir, commandOptions.files)) {
+				if (isConfigModeDir(commandOptions.workingDir, commandOptions.files, { register: commandOptions.register })) {
 					await addApp({
 						workingDir: path.resolve(commandOptions.workingDir),
 						verbose: commandOptions.verbose,
@@ -1326,6 +1531,7 @@ const buildCli = () =>
 						releaseCc: commandOptions.releaseCc,
 						serverMode: commandOptions.serverMode,
 						include: commandOptions.include,
+						register: commandOptions.register,
 					});
 					return;
 				}
@@ -1386,6 +1592,34 @@ const buildCli = () =>
 				})();
 			},
 		)
+		.command(
+			"unregister",
+			"Take domains out of the host application config (Doc 8), e.g. when they move to their own application",
+			(yargs) =>
+				yargs
+					.option("domains", {
+						describe: "Comma-separated domain names to take out",
+						type: "string",
+						demandOption: true,
+					})
+					.option("publish", {
+						describe: "Republish the host application config afterwards",
+						type: "boolean",
+						default: false,
+					}),
+			async (commandOptions) => {
+				const result = await unregisterAppDomains({
+					domains: commandOptions.domains,
+					server: commandOptions.server,
+					apiPort: commandOptions.apiPort,
+					dbIndex: Number(commandOptions.dbIndex),
+					sub: commandOptions.sub,
+					publish: commandOptions.publish,
+					serverMode: commandOptions.serverMode,
+				});
+				if (!result.success) process.exitCode = 1;
+			},
+		)
 		.command(
 			"migrate:new",
 			"Create a new blank migration file with an epoch timestamp",
@@ -1506,4 +1740,5 @@ export {
 	resolveUpsertBlocks,
 	uploadConfigs,
 	isConfigModeDir,
+	unregisterAppDomains,
 };

package/bin/hub.js

@@ -136,6 +136,13 @@ const argv = yargs(process.argv.slice(2))
 			"Doc 1 0b.6b: base URL of the central AI gateway (biz-a-server /ai) that ccai calls. Defaults to this hub's server (serverMode).",
 		type: "string",
 	})
+	.options("finaCloudDbindex", {
+		describe:
+			"Doc 8: the FINA API database FINA Cloud works on (FINA's own index, not Biz-A's). Absent = FINA Cloud off. When set, browser writes to that database are refused: they go through engine/fina.",
+		type: "number",
+		/* ⚠️ No default, and an operator setting rather than a console one: one FINA API can serve several
+		   companies, and the index chooses whose books these are. */
+	})
 	.options("services", {
 		describe:
 			"Comma-separated list of engine jobs this agent handles (e.g., 'BPM,EMAIL')",
@@ -203,6 +210,7 @@ import { createExtRouter } from "../engine/ext/routes.js";
 import { createLiveExtDeps } from "../engine/ext/live.js";
 import axios from "axios";
 import { createFinaRouter } from "../engine/orm/finaEndpoint.js";
+import { createLiveFinaReadPolicy } from "../engine/fina/readPolicy.js";
 import { createSessionStore } from "../engine/orm/sessionStore.js";
 import { resolveUserTenancy } from "../engine/orm/tenantResolution.js";
 import { buildUserTenantSql } from "../engine/orm/finaAuth.js";
@@ -332,6 +340,14 @@ app.use(
 		/* A v2 save that creates a record of an entity declaring its workflow starts it — the same
 		   starter the socket entrance (bin/hubEvent.js) hands the router. */
 		startWorkflow: startWorkflowOnCreate,
+		/* Doc 8 D2 — the FINA Cloud write guard, the same one the socket entrance runs (bin/hubEvent.js). */
+		finaCloudDbIndex: argv.finaCloudDbindex,
+		/* Doc 8 M8 — and the read policy (a mapped FINA user), as the socket entrance runs it. */
+		finaReadPolicy: createLiveFinaReadPolicy({
+			argv,
+			isPostgresIndex,
+			readSession: hubSessionStore ? (sid) => hubSessionStore.read(sid) : null,
+		}),
 		/* So a locally-served response still tells the client where to open its sockets — the
 		   tunnel's byte-level injection only fires for real FINA responses. */
 		cliAddress: () => (argv.cliAddress ? argv.cliAddress() : {}),

package/bin/hubEvent.js

@@ -21,6 +21,9 @@ import { tenantSqlFor } from "../engine/orm/tenantSql.js";
 import { ensureEntityConfig } from "../engine/domain/entityConfigPrimer.js";
 import { startWorkflowOnCreate } from "../engine/bpm/workflowOnCreate.js";
 import { bpmContextFromHeaders } from "../engine/bpm/bpmContext.js";
+import { finaContext } from "../engine/fina/context.js";
+import { refuseFinaCloudWrite } from "../engine/fina/guard.js";
+import { createLiveFinaReadPolicy } from "../engine/fina/readPolicy.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";
@@ -51,6 +54,7 @@ import {
 	writeCompanyLogo,
 	clearCompanyLogo,
 } from "../engine/orm/companyLogo.js";
+import { readCompanyLocale, writeCompanyLocale } from "../engine/orm/companyLocale.js";
 import {
 	execPostgres,
 	execPostgresStatements,
@@ -92,6 +96,23 @@ const sessionStoreFor = (dbIndex) => {
 	}
 	return sessionStores.get(dbIndex);
 };
+/* Doc 8 M8 — the FINA read policy (S-02: reading FINA takes a mapped FINA user), one per hub, built on first use from
+   the hub's own argv and session store: the same context the `fina/*` engine routes get. */
+let finaReadPolicyOfHub = null;
+const finaReadPolicyFor = (argv) => {
+	if (!finaReadPolicyOfHub) {
+		finaReadPolicyOfHub = createLiveFinaReadPolicy({
+			argv,
+			isPostgresIndex,
+			readSession: (sid) => {
+				const store = sessionStoreFor(Number(argv["dbindex"]));
+				return store ? store.read(sid) : null;
+			},
+		});
+	}
+	return finaReadPolicyOfHub;
+};
+
 const openSessionFor = (dbIndex) => {
 	const store = sessionStoreFor(dbIndex);
 	return store ? (args) => store.open(args) : null;
@@ -500,6 +521,21 @@ const EngineRegistry = {
 	"domain/appConfig": () => import("../engine/domain/appConfig.js"),
 	"domain/applicationConfig": () =>
 		import("../engine/domain/applicationConfig.js"),
+	/* Doc 8 — FINA Cloud. ⚠️ Route files only: every export of a registered module is callable from a browser. */
+	"fina/setup": () => import("../engine/fina/routes/setup.js"),
+	"fina/session": () => import("../engine/fina/routes/session.js"),
+	"fina/master": () => import("../engine/fina/routes/master.js"),
+	/* Doc 8 M4 — the template engine's server side. */
+	"fina/template": () => import("../engine/fina/routes/template.js"),
+	"fina/document": () => import("../engine/fina/routes/document.js"),
+	"fina/print": () => import("../engine/fina/routes/print.js"),
+	"fina/recurring": () => import("../engine/fina/routes/recurring.js"),
+	/* Doc 8 M5b — which months FINA keeps open, for the rows a list shows (L-08). */
+	"fina/period": () => import("../engine/fina/routes/period.js"),
+	/* Doc 8 M6 — a FINA document's attachments, kept in Biz-A (SYS$ATTACHMENT). */
+	"fina/attachment": () => import("../engine/fina/routes/attachment.js"),
+	/* Doc 8 M7 — JV submissions (pengajuan) with Need Approval on; the approval workflow posts them. */
+	"fina/submission": () => import("../engine/fina/routes/submission.js"),
 };
 
 /* Doc 1 step 3 — what a Phase B turn needs: the draft store, the gap list, a draft opener that applies the
@@ -665,6 +701,30 @@ const handleCliCommand = async (data, cb, argv) => {
 				}
 				break;
 			}
+			/*
+			 * Agung 2026-10-10 — the company number format (id / en-US), the theme's path: read by anyone signed
+			 * in (every screen formats numbers by it), written only by a verified administrator
+			 * (companyLocale.js), audited. A refused value is an answer with `problems`, not an error.
+			 */
+			case "companylocale": {
+				const localePrincipal = principalForCliScript(data.headers, {
+					mode: argv["principalMode"] || "observe",
+				});
+				const localeDb = tenantSqlFor(argv["dbindex"]);
+				if (data.action === "write") {
+					const saved = await writeCompanyLocale({
+						exec: localeDb.exec,
+						execStatements: localeDb.atomic,
+						sql: localeDb,
+						principal: localePrincipal,
+						locale: data.locale,
+					});
+					cb(null, { success: saved.ok, problems: saved.problems, data: saved.locale });
+				} else {
+					cb(null, { success: true, data: await readCompanyLocale({ exec: localeDb.exec }) });
+				}
+				break;
+			}
 			/*
 			 * Doc 6 §8.2 — the company logo, under its OWN sys$config key.
 			 *
@@ -846,12 +906,23 @@ const handleCliCommand = async (data, cb, argv) => {
 				 * These are engine operations invoked by an administrator, not tenant data reads, so
 				 * they are trusted for the same reason everything behind db/db.js is.
 				 */
-				/* The BPM runtime alone gets who is asking — the signed principal in `data.headers`, never the
-				   caller-shaped payload — for transitions that ask for verified roles (bpm/bpmContext.js). */
+				/* Who is asking — the signed principal in `data.headers`, never the caller-shaped payload — for the
+				   modules that act on it: the BPM runtime, for transitions that ask for verified roles
+				   (bpm/bpmContext.js), and FINA Cloud, whose every route acts as the verified user (Doc 8 D2,
+				   engine/fina/context.js). */
 				const engineContext =
 					modulePath === "bpm/workflowRT"
 						? bpmContextFromHeaders(data.headers, { mode: argv["principalMode"] || "observe" })
-						: undefined;
+						: modulePath.startsWith("fina/")
+							? await finaContext(data.headers, {
+									argv,
+									isPostgresIndex,
+									readSession: (() => {
+										const store = sessionStoreFor(Number(argv["dbindex"]));
+										return store ? (sid) => store.read(sid) : null;
+									})(),
+								})
+							: undefined;
 				const result = await runTrusted(() =>
 					engineContext
 						? engineModule[methodName](data.payload, argv, engineContext)
@@ -988,7 +1059,28 @@ export const clientListener = (socket, argv, via = "?") => {
 					: undefined,
 			});
 			if (argv["subdomain"].localeCompare(reqData.subDomain) == 0) {
-				const forwardToApi = () =>
+				/* Doc 8 D2 — a browser may not write to the FINA Cloud database directly: engine/fina does it,
+				   checking the user's FINA rights and the date lock. Checked HERE, the one place this transport
+				   hands a request to FINA; the HTTP entrance runs the same guard (finaEndpoint.js). */
+				/* Doc 8 M8 — and READING FINA takes a Biz-A user mapped to a FINA user (S-02, engine/fina/readPolicy.js). */
+				const finaReadPolicy = finaReadPolicyFor(argv);
+				const forwardToApi = async () => {
+					const refused =
+						refuseFinaCloudWrite({ path: reqData.path, body: reqBody, finaCloudDbIndex: argv["finaCloudDbindex"] }) ??
+						(await finaReadPolicy({ path: reqData.path, body: reqBody, headers: reqData.headers }));
+					if (refused) {
+						logger.warn(`[apiRequest] refused ${reqData.path}: ${refused.body.error}`);
+						return resCB(null, {
+							status: refused.status,
+							statusText: "Forbidden",
+							headers: { "content-type": "application/json", ...cliAddressHeaders() },
+							body: refused.body,
+							url: apiAddress + reqData.path,
+						});
+					}
+					return forwardToFina();
+				};
+				const forwardToFina = () =>
 					axios
 						.request({
 							timeout:
@@ -1116,7 +1208,8 @@ export const clientListener = (socket, argv, via = "?") => {
 							status: routed.status,
 							statusText: routed.status === 200 ? "OK" : "Error",
 							headers: {
-								"content-type": "application/json",
+								/* An image read answers bytes with its own type (apiRoute.js `img`). */
+								"content-type": routed.contentType ?? "application/json",
 								...cliAddressHeaders(),
 							},
 							body: routed.body,

package/bin/tunnelTarget.js

@@ -48,6 +48,10 @@ export const resolveTunnelTarget = (argv, isPostgresIndex, firstChunk) => {
 	};
 
 	if (isLoginRequest(firstChunk)) return ownEndpoint(argv);
+	/* Doc 8 D2 — with FINA Cloud on, everything loops back: the FINA Cloud write guard sits on the CLI's own
+	   endpoint (finaEndpoint.js), and a byte pipe straight to FINA would pass it by. */
+	const finaCloud = Number(argv.finaCloudDbindex);
+	if (Number.isInteger(finaCloud) && finaCloud > 0) return ownEndpoint(argv);
 	if (!argv.dbindex) return fina;
 
 	let servedHere = false;