biz-a-cli 2.3.80-15317 → 2.3.80-15330

package/bin/app.js

@@ -13,6 +13,10 @@ import {
 import path, { basename } from "node:path";
 import os from "node:os";
 import { env } from "../envs/env.js";
+import {
+	SERVER_MODES,
+	resolveServerLink,
+} from "../envs/serverEndpoints.js";
 import { prepareScript, encryptScript } from "./script.js";
 import { spawn } from "node:child_process";
 import { newMigration, runMigrations } from "./migrate.js";
@@ -27,6 +31,7 @@ import {
 	getUpsertBlock,
 	isSemanticVersion,
 	parseConfigForVersion,
+	readConfigRows,
 } from "../engine/domain/appConfig.js";
 import {
 	isPostgresIndex,
@@ -34,6 +39,12 @@ import {
 	primeRegistry,
 } from "../engine/domain/dialect.js";
 import { addUser } from "../engine/orm/userAdmin.js";
+import {
+	preservePublishedAdditions,
+	renderApplicationConfig,
+	uploadSourceConfigName,
+} from "../engine/domain/publishedAdditions.js";
+import { validateTenancyDeclaration } from "../engine/orm/tenancyDeclaration.js";
 import { logger } from "../logger.js";
 
 const getKeyFolderPath = () => {
@@ -79,6 +90,23 @@ const options = {
 		type: "number",
 		demandOption: false,
 	},
+	/*
+	 * ⚠️ NOT the same link as `-s/--server`. `-s` is the FINA/hub URL the bundle is POSTed to;
+	 * this picks the Biz-A server that issues the bundle-encryption key, which `prepareKeys` must
+	 * fetch BEFORE anything is uploaded. It was hard-coded to production, so `biza add` could not
+	 * run against a local stack at all — it died on `ENOTFOUND server.biz-a.id` while every other
+	 * local service was healthy. `choices` + the `.strict()` below are what stop a typo from
+	 * silently falling back to production; see `envs/serverEndpoints.js`.
+	 */
+	serverMode: {
+		alias: "sMode",
+		describe:
+			"Which Biz-A backend issues the bundle encryption key: prod, dev, or local",
+		type: "string",
+		choices: SERVER_MODES,
+		default: "prod",
+		demandOption: false,
+	},
 };
 
 const addCommandOptions = {
@@ -96,6 +124,13 @@ const addCommandOptions = {
 		demandOption: false,
 		default: false,
 	},
+	include: {
+		describe:
+			"Config mode only: additional directories whose DOMAIN configs upload alongside this one's — for a Layer 3 domain package that lives in its own tree (repeatable). An application.js in an included directory is refused, never uploaded: that row belongs to -d.",
+		type: "array",
+		demandOption: false,
+		default: [],
+	},
 	publish: {
 		describe:
 			"Config mode only (directory contains application.js): after saving, publish the domain DDL then the application config — the same as the admin App Config Publish button",
@@ -122,7 +157,7 @@ const removeCommandOptions = {
 	},
 };
 
-const prepareKeys = async () => {
+const prepareKeys = async (serverLink = env.BIZA_SERVER_LINK) => {
 	const data = Buffer.from(
 		JSON.stringify({ issuer: "CLI", acquirer: "Client" }),
 	).toString("base64");
@@ -132,7 +167,7 @@ const prepareKeys = async () => {
 		passphrase: "Biz-A@cli",
 		padding: cryptoConstants.RSA_PKCS1_PSS_PADDING,
 	}).toString("base64");
-	const res = await axios.get(env.BIZA_SERVER_LINK + "/api/issuerKey", {
+	const res = await axios.get(serverLink + "/api/issuerKey", {
 		params: { data, signature },
 	});
 	if (
@@ -419,8 +454,64 @@ const resolveUpsertBlocks = (name, version, content, dbIndex) => {
    WHOLE set before anything is uploaded, so a stray lib or a typo'd metadata can never leave a
    half-applied config in SYS$CONFIG. Every problem is collected and reported at once, each
    naming its file. */
-const collectConfigUploads = ({ workingDir, fileNames = [] }) => {
+/*
+ * ⚠️ ADDITIONAL CONFIG DIRECTORIES (`--include`), for a Layer 3 domain package that lives in its
+ * own tree rather than beside the host's `application.js`.
+ *
+ * Config mode triggers on an `application.js` in the ONE directory `-d` names, so before this a
+ * package like `/biz-a-template/hr/src/config/` had no upload path whatsoever — and registering it in
+ * the host's `domains` map was INERT rather than broken, because the runtime loader skips a named
+ * domain with no row (`if (!row?.data) continue`). A domain that silently is not there is worse than
+ * one that fails loudly.
+ *
+ * ⚠️ AN `application.js` IN AN INCLUDED DIRECTORY IS REFUSED, NOT SKIPPED. Uploading it would
+ * replace the HOST's APPLICATION_CONFIG — its navigation, its domains map — with a package's, and the
+ * only symptom would be a console that lost its menus. Pointing `--include` at a host directory is a
+ * mistake worth being told about.
+ */
+const collectIncludedConfigFiles = (include = []) => {
+	const problems = [];
+	const files = [];
+
+	for (const entry of Array.isArray(include) ? include : [include]) {
+		const dir = String(entry ?? "").trim();
+		if (!dir) continue;
+		const resolved = path.resolve(dir);
+
+		let names;
+		try {
+			if (!fs.statSync(resolved).isDirectory()) {
+				problems.push(`--include ${dir}: not a directory.`);
+				continue;
+			}
+			names = fs.readdirSync(resolved);
+		} catch (error) {
+			problems.push(`--include ${dir}: ${error?.message ?? error}`);
+			continue;
+		}
+
+		const configs = names.filter((name) => name.toLowerCase().endsWith(".js"));
+		if (configs.some((name) => name.toLowerCase() === APPLICATION_CONFIG_FILE)) {
+			problems.push(
+				`--include ${dir}: contains ${APPLICATION_CONFIG_FILE}. An included directory supplies ` +
+					"DOMAIN configs only — the application config belongs to the directory named by -d.",
+			);
+			continue;
+		}
+		for (const name of configs) files.push(path.join(resolved, name));
+	}
+
+	return { files, problems };
+};
+
+/* PURE-ish, continued: `include` names extra directories whose DOMAIN configs join the set. They are
+   folded in BEFORE validation so an included file gets exactly the same checks — and the same
+   "nothing was uploaded" guarantee — as one sitting beside application.js. */
+const collectConfigUploads = ({ workingDir, fileNames = [], include = [] }) => {
 	const problems = [];
+	const included = collectIncludedConfigFiles(include);
+	problems.push(...included.problems);
+	fileNames = [...fileNames, ...included.files];
 	const readConfig = (fileName) =>
 		fs
 			.readFileSync(
@@ -455,6 +546,10 @@ const collectConfigUploads = ({ workingDir, fileNames = [] }) => {
 	}
 
 	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
+	   runtime. Validating file-by-file would refuse a declaration the runtime accepts. */
+	const parsedConfigs = [];
 	const seenNames = new Map();
 	for (const fileName of fileNames) {
 		const baseName = path.basename(String(fileName));
@@ -496,9 +591,16 @@ const collectConfigUploads = ({ workingDir, fileNames = [] }) => {
 			continue;
 		}
 		seenNames.set(name, baseName);
+		parsedConfigs.push(parsed);
 		domains.push({ name, version, content, fileName: baseName });
 	}
 
+	/* Doc 3 §11 — refuse a tenancy declaration the schema does not actually back. This is the last
+	   point where every config is in hand and NOTHING has been written to sys$config, which is what
+	   makes "nothing was uploaded" true. See engine/orm/tenancyDeclaration.js for why it refuses
+	   rather than warns. */
+	problems.push(...validateTenancyDeclaration(parsedConfigs));
+
 	if (problems.length > 0) {
 		throw new Error(
 			`Config upload aborted, nothing was uploaded:\n  - ${problems.join("\n  - ")}`,
@@ -512,24 +614,86 @@ const collectConfigUploads = ({ workingDir, fileNames = [] }) => {
    matches appConfig.service.ts publishEditorConfigs: every domain DDL publish first (sequential),
    then the application-config publish (which regenerates template scaffolding + rebuilds the
    bundle). */
+/*
+ * Fold the publisher's own additions back into the file about to be uploaded.
+ *
+ * Reads through `readConfigRows`, which is already dialect-aware, so this behaves identically on a
+ * Firebird tenant without a line of new SQL. Fails SOFT: if either row cannot be read we upload the
+ * file exactly as before, because preserving on a guess is what caused the earlier incident.
+ */
+const preserveApplicationAdditions = async (application, apiConfig) => {
+	const readParsed = async (name) => {
+		try {
+			const rows = await readConfigRows(name, application.version, apiConfig);
+			const data = rows?.[0]?.data;
+			return data ? parseConfigForVersion(String(data)) : null;
+		} catch {
+			return null;
+		}
+	};
+
+	let fileConfig;
+	try {
+		fileConfig = parseConfigForVersion(application.content);
+	} catch {
+		return { application };
+	}
+
+	const [storedConfig, lastUploadedConfig] = await Promise.all([
+		readParsed(application.name),
+		readParsed(uploadSourceConfigName(application.name)),
+	]);
+
+	const kept = preservePublishedAdditions({ fileConfig, storedConfig, lastUploadedConfig });
+	const keptKeys = Object.keys(kept);
+	if (keptKeys.length === 0) {
+		/* Say WHY nothing was kept when there plainly was something to keep — a silent revert is how
+		   this cost four round-trips before anyone worked out what was happening. */
+		if (storedConfig && !lastUploadedConfig) {
+			logger.info(
+				`[${application.name}] no record of a previous upload, so nothing is preserved; ` +
+					"re-run the application's own publish afterwards to regenerate what it adds.",
+			);
+		}
+		return { application };
+	}
+
+	logger.info(
+		`[${application.name}] keeping ${keptKeys.join(", ")} from the last application publish ` +
+			"(unchanged in application.js); every other key comes from the file.",
+	);
+	return {
+		application: {
+			...application,
+			content: renderApplicationConfig({ ...fileConfig, ...kept }),
+		},
+	};
+};
+
 async function uploadConfigs({
 	workingDir,
 	fileNames,
+	include = [],
 	server,
 	apiPort,
 	dbIndex,
 	sub,
 	publish = false,
 	forceFull = false,
+	serverMode = "prod",
 }) {
 	/* 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
 	   indexes would look like Firebird. No-op when --sub is absent or biz-a is unreachable. */
-	await primeRegistry({ subdomain: sub, serverLink: env.BIZA_SERVER_LINK });
+	await primeRegistry({
+		subdomain: sub,
+		serverLink: resolveServerLink(serverMode),
+	});
 
 	const { application, domains } = collectConfigUploads({
 		workingDir,
 		fileNames,
+		include,
 	});
 
 	const apiConfig = {
@@ -562,7 +726,28 @@ async function uploadConfigs({
 	};
 
 	if (application) {
-		await saveOne(application);
+		/*
+		 * ⚠️ APPLICATION_CONFIG HAS TWO WRITERS. This one uploads `application.js` verbatim — which
+		 * deliberately ships only the BOOTSTRAP navigation and the hand-authored domains — while the
+		 * APPLICATION's own publish rebuilds the same row with what it GENERATES (injected staff
+		 * consoles, the generated runtime domain). Overwriting it wholesale wiped every app menu until
+		 * someone re-ran the app publish by hand.
+		 *
+		 * ⚠️ The obvious fix is the one that already failed: "prefer whatever is stored" dropped the
+		 * generated domain and made the damage permanent. The publisher owns SOME keys and the author
+		 * owns the rest, so the question is not who wins but whether the AUTHOR touched this key —
+		 * answerable only against the previously uploaded file. See engine/domain/publishedAdditions.js.
+		 */
+		const preserved = await preserveApplicationAdditions(application, apiConfig);
+		await saveOne(preserved.application);
+		/* Record what was uploaded, so the NEXT run can tell an author edit from an untouched key.
+		   Written after the config itself: a failed upload must not leave a source row claiming the
+		   author's file is already stored. */
+		await saveOne({
+			name: uploadSourceConfigName(application.name),
+			version: application.version,
+			content: application.content,
+		});
 	}
 	for (const domain of domains) {
 		await saveOne(domain);
@@ -590,6 +775,10 @@ async function uploadConfigs({
 		port: apiPort,
 		dbindex: dbIndex,
 		subdomain: sub,
+		/* publishApplicationConfig -> publishApp -> addApp re-enters bundle mode and fetches the
+		   issuer key again, so the mode has to survive the round trip or the publish half of
+		   `--publish` still dials production. */
+		serverMode,
 	};
 
 	for (const domain of domains) {
@@ -773,6 +962,9 @@ async function addApp({
 	body = null,
 	publish = false,
 	forceFull = false,
+	serverMode = "prod",
+	/* Extra directories whose DOMAIN configs upload alongside this one's (see --include). */
+	include = [],
 } = {}) {
 	const oldCwd = process.cwd();
 
@@ -819,17 +1011,19 @@ async function addApp({
 			return await uploadConfigs({
 				workingDir: process.cwd(),
 				fileNames: mergedSourceFiles,
+				include,
 				server,
 				apiPort,
 				dbIndex,
 				sub,
 				publish,
 				forceFull,
+				serverMode,
 			});
 		}
 
 		if (mergedSourceFiles.length > 0) {
-			const keys = await prepareKeys();
+			const keys = await prepareKeys(resolveServerLink(serverMode));
 			if (!keys) {
 				const msg = "Can not prepare encryption keys";
 				logger.error(msg);
@@ -997,6 +1191,7 @@ async function runUnitTests(options) {
 					files: options.files,
 					publish: options.publish,
 					forceFull: options.forceFull,
+					serverMode: options.serverMode,
 				});
 			} else {
 				logger.error("Biz-A Add aborted");
@@ -1029,6 +1224,8 @@ const buildCli = () =>
 						files: commandOptions.files,
 						publish: commandOptions.publish,
 						forceFull: commandOptions.forceFull,
+						serverMode: commandOptions.serverMode,
+						include: commandOptions.include,
 					});
 					return;
 				}
@@ -1146,7 +1343,9 @@ const buildCli = () =>
 				try {
 					await primeRegistry({
 						subdomain: commandOptions.sub,
-						serverLink: env.BIZA_SERVER_LINK,
+						serverLink: resolveServerLink(
+							commandOptions.serverMode,
+						),
 					});
 					const result = await addUser(
 						{

package/bin/directHubEvent.js

@@ -7,6 +7,7 @@ import { ClientEmitter } from "../message-broker/clientEmitter.js";
 import { joinExtRooms } from "../engine/ext/esb.js";
 import { extClientListener } from "../engine/ext/socketListener.js";
 import { prefixedLogger } from "../logger.js";
+import { APP_URL, TEST_URL, ADMIN_URL, TEST_ADMIN_URL } from "../envs/hosts.js";
 
 const logger = prefixedLogger("[DirectHub]");
 
@@ -117,9 +118,19 @@ export function createSocketServer(httpServer, cliIpAddress = "127.0.0.1") {
 	return new ioServer(httpServer, {
 		cors: {
 			origin: [
+				// Browser apps only (client + admin). The server and hub reach the CLI
+				// server-to-server, not from a browser, so they need no entry here. Exact origins
+				// only — no wildcard: /\.biz-a\.id$/ trusted EVERY subdomain of the domain.
+				APP_URL,
+				TEST_URL,
+				ADMIN_URL,
+				TEST_ADMIN_URL,
+				// biz-a.id is still served alongside biz-a.app, so its browser origins stay allowed.
 				"https://biz-a.id",
 				"https://test.biz-a.id",
-				/\.biz-a\.id$/,
+				"https://admin.biz-a.id",
+				// NOT the wildcard (see above):
+				// /\.biz-a\.id$/,
 				"vscode-file://vscode-app",
 				/\.vscode-cdn\.net$/,
 			].concat(

package/bin/hub.js

@@ -19,6 +19,11 @@ import {
 	createSocketServer,
 } from "./directHubEvent.js";
 import { env } from "../envs/env.js";
+import {
+	SERVER_MODES,
+	resolveHubLink,
+	resolveServerLink,
+} from "../envs/serverEndpoints.js";
 import { setGlobalConfig } from "../db/ds.js";
 import { CLI_Agent } from "../message-broker/agent.js";
 import { initBpmAgent } from "../engine/bpm/bpm-agent.js";
@@ -94,7 +99,7 @@ const argv = yargs(process.argv.slice(2))
 		describe: "Backend server mode: prod, dev, or backup",
 		type: "string",
 		// choices: ["prod", "dev", "backup"],
-		choices: ["prod", "dev", "local"],
+		choices: SERVER_MODES,
 		default: "prod",
 	})
 	.options("mode", {
@@ -109,41 +114,42 @@ const argv = yargs(process.argv.slice(2))
 		type: "string",
 		default: "http://127.0.0.1:3002",
 	})
+	.options("principalMode", {
+		describe:
+			"Doc 3 §11: 'observe' logs what it sees and refuses nothing; 'enforce' refuses a data request without a valid principal (login is exempt).",
+		type: "string",
+		choices: ["observe", "enforce"],
+		/* ⚠️ The DEFAULT STAYS `observe`. This is platform code running for every tenant, and a
+		   default of `enforce` would refuse every request from any tenant whose client has not been
+		   rebuilt to send a principal. A tenant opts in explicitly. */
+		default: "observe",
+	})
 	.options("services", {
 		describe:
 			"Comma-separated list of engine jobs this agent handles (e.g., 'BPM,EMAIL')",
 		type: "string",
 		default: "ALL",
-	}).argv;
-
-// Server endpoint mapping by mode
-const SERVER_ENDPOINTS = {
-	prod: {
-		server: env.BIZA_SERVER_LINK,
-		hub: env.BIZA_HUB_SERVER_LINK,
-	},
-	dev: {
-		server: "https://devServer.biz-a.id",
-		hub: "https://devHub.biz-a.id",
-	},
-	// backup: {
-	// 	server: "https://backupServer.biz-a.id",
-	// 	hub: "https://backupHub.biz-a.id",
-	// },
-	local: {
-		server: "http://localhost:3000",
-		hub: "http://localhost:3001",
-	},
-};
+	})
+	/*
+	 * ⚠️⚠️ REFUSE UNKNOWN FLAGS, because the fallback when one is ignored is PRODUCTION.
+	 *
+	 * yargs aliases are case-sensitive, so `--SMode local` is not `--sMode local`: without this the
+	 * unknown key was silently dropped, `serverMode` kept its default `prod`, and the CLI quietly
+	 * dialled server.biz-a.id / hub.biz-a.id instead of the local stack. Nothing logged that, the CLI
+	 * looked healthy, and the only symptom was a 502 "<subdomain> is currently unregistered or
+	 * offline" from a component three hops away. That typo cost two debugging rounds.
+	 *
+	 * `bin/app.js` has had `.strict()` all along; this file simply never did.
+	 */
+	.strict().argv;
 
+/* The endpoint table moved to envs/serverEndpoints.js so `bin/app.js` resolves the SAME three
+   environments — it read env.BIZA_SERVER_LINK directly and so could only ever reach production. */
 if (!argv.server) {
-	argv.server =
-		SERVER_ENDPOINTS[argv.serverMode]?.server ||
-		SERVER_ENDPOINTS.prod.server;
+	argv.server = resolveServerLink(argv.serverMode);
 }
 if (!argv.hubServer) {
-	argv.hubServer =
-		SERVER_ENDPOINTS[argv.serverMode]?.hub || SERVER_ENDPOINTS.prod.hub;
+	argv.hubServer = resolveHubLink(argv.serverMode);
 }
 
 // handle required options manually, not using yargs demandOption
@@ -184,13 +190,18 @@ 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 { primeEntityConfig } from "../engine/orm/entityConfig.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 { createTenantContextApplier, APP_ROLE } from "../engine/orm/rlsApplier.js";
 import { createDomainConfigLoader } from "../engine/domain/entityConfigLoader.js";
 import {
 	execPostgres,
 	execPostgresStatements,
 	execPostgresTransaction,
 	isPostgresIndex,
+	setTenantContextApplier,
 } from "../engine/domain/dialect.js";
 
 import { logger } from "../logger.js";
@@ -217,6 +228,41 @@ app.use("/bpm", bpmRoutes);
 // socket-stream tunnel, which pipes bytes without reading them. bin/tunnelTarget.js points that
 // tunnel here for a PostgreSQL tenant, so both transports land on the same routing. Whatever the
 // ORM does not own is forwarded to the real FINA, so a part-migrated tenant keeps working.
+/* Built ONCE: the store is stateless, but rebuilding it per request would make that a promise
+   nobody checks rather than a fact. Null on a Firebird index — there is no SYS$SESSION there. */
+const hubSessionStore = isPostgresIndex(Number(argv.dbindex))
+	? createSessionStore({ exec: execPostgres, dbIndex: Number(argv.dbindex) })
+	: null;
+
+/*
+ * Doc 4 §9.5 housekeeping — "a periodic job deletes rows past `expires_at` plus a retention margin".
+ *
+ * ⚠️ A PLATFORM TIMER, not a SYS$DAILY row. The scheduler here is application-config driven, and a
+ * platform table's housekeeping must not depend on an application remembering to declare it — an
+ * install with no such row would simply grow SYS$SESSION forever.
+ *
+ * ⚠️ `unref()` so this never holds the process open, and failures are logged and swallowed: a sweep
+ * that cannot run is a table that grows, which is a problem for later — not a reason to take the hub
+ * down. Safe to run on every instance: the DELETE is idempotent.
+ *
+ * ⚠️ The RETENTION MARGIN is Dok. 4 §14 open item #2 (audit may want these rows longer than
+ * operations does). `DEFAULT_SESSION_RETENTION` is a placeholder until that is settled, not a ruling.
+ */
+if (hubSessionStore) {
+	const SESSION_SWEEP_INTERVAL_MS = 24 * 3600 * 1000;
+	const sweepSessions = () =>
+		hubSessionStore
+			.purgeExpired()
+			.then(({ purged }) => {
+				if (purged > 0) logger.info(`[session] purged ${purged} expired session row(s)`);
+			})
+			.catch((error) =>
+				logger.warn(`[session] could not purge expired sessions: ${error?.message ?? error}`),
+			);
+	setTimeout(sweepSessions, 60 * 1000).unref();
+	setInterval(sweepSessions, SESSION_SWEEP_INTERVAL_MS).unref();
+}
+
 app.use(
 	"/fina",
 	createFinaRouter({
@@ -225,6 +271,30 @@ app.use(
 		execTransaction: execPostgresTransaction,
 		isPostgresIndex,
 		defaultDbIndex: Number(argv.dbindex),
+		/* ⚠️ ONE BOUNDARY, ONE POLICY. bin/hubEvent.js reads this from argv for the socket entrance;
+		   without passing it here the HTTP entrance would stay on its `observe` default while the
+		   socket path enforced — enforcement arriving on one transport ahead of the other is exactly
+		   what finaEndpoint's own comment warns against. Login reaches the CLI through THIS door. */
+		principalMode: argv.principalMode,
+		/* Doc 4 §9.5 / B2 — the SAME session store both entrances use, for the same reason the
+		   principal mode is shared: a session that is authoritative on one transport and ignored
+		   on the other is worse than not having one. Null on a Firebird index, which puts the
+		   request on the deprecated principal path rather than failing it. */
+		sessionStore: hubSessionStore,
+		openSession: hubSessionStore ? (args) => hubSessionStore.open(args) : null,
+		/* Doc 4 §8 — the switcher's choice, persisted on the session row. */
+		chooseActiveTenant: hubSessionStore
+			? (sid, tenantId) => hubSessionStore.chooseActiveTenant(sid, tenantId)
+			: null,
+		resolveTenancy: hubSessionStore
+			? ({ userId }) =>
+					resolveUserTenancy({
+						userId,
+						dbIndex: Number(argv.dbindex),
+						exec: execPostgres,
+						buildBindingSql: buildUserTenantSql,
+					})
+			: 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() : {}),
@@ -282,6 +352,9 @@ app.use(
 		oidc: extDeps.oidc,
 		identityStore: extDeps.identityStore,
 		resolveTenant: extDeps.resolveTenant,
+		/* Doc 3 section 11 -- without this the external surface has NO tenant context and the
+		   fail-closed default hides every multi-tenant row from it. */
+		withTenantScope: extDeps.withTenantScope,
 		getChannelInfo: () => {
 			const a = argv.cliAddress ? argv.cliAddress() : {};
 			return { cliAddress: a.publicUrl, hubAddress: a.hubUrl };
@@ -349,7 +422,31 @@ if (isPostgresIndex(Number(argv.dbindex))) {
 			exec: execPostgres,
 			dbIndex: Number(argv.dbindex),
 		}),
-	}).catch(() => {});
+	})
+		.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",
+				);
+			}
+		})
+		.catch(() => {});
 }
 
 if (argv.mode.trim().toLowerCase() === "agent") {