biz-a-cli 2.3.80-15381 → 2.3.80-15390

package/bin/app.js

@@ -33,7 +33,6 @@ import {
 	buildPostgresSetAppSql,
 	extractConfigVersion,
 	getChunkedUpsertBlocks,
-	getUpsertBlock,
 	isSemanticVersion,
 	parseConfigForVersion,
 	readConfigRows,
@@ -52,6 +51,7 @@ import {
 	renderApplicationConfig,
 	uploadSourceConfigName,
 } from "../engine/domain/publishedAdditions.js";
+import { guardCcOwnedDomains } from "../engine/cc/ownershipGuard.js";
 import { validateTenancyDeclaration } from "../engine/orm/tenancyDeclaration.js";
 import { logger } from "../logger.js";
 import { findRawColorsInSource } from "../engine/domain/styleColors.js";
@@ -155,6 +155,13 @@ const addCommandOptions = {
 		demandOption: false,
 		default: false,
 	},
+	releaseCc: {
+		describe:
+			"Config mode: upload a domain that Control Center owns, handing it back to SVN. Without it such a domain is refused, so CC edits are never silently overwritten",
+		type: "boolean",
+		demandOption: false,
+		default: false,
+	},
 };
 
 const removeCommandOptions = {
@@ -377,9 +384,6 @@ const APPLICATION_CONFIG_FILE = "application.js";
 /* Doc 6 §8.1 — the application theme source. JSON, because it is DATA that reaches the browser
    via sys$config and must never be evaluated (AC 26). */
 const THEME_CONFIG_FILE = "theme.json";
-/* Parity with the admin editor (appConfig.component.ts executeBlockBodyLimit): the DataSnap
-   `block` call body must stay under 64KB, so an oversized config is upserted in chunks. */
-const EXECUTE_BLOCK_BODY_LIMIT = 2 ** 16;
 
 const findApplicationConfigFile = (fileNames = []) =>
 	fileNames.find(
@@ -405,7 +409,7 @@ const isConfigModeDir = (workingDir, files = null) => {
    flattenSql(), whose `--` comment stripping mangles a config upsert — the whole config is embedded
    as a single-line quoted literal, so the first `--` ANYWHERE in the config text (a JS comment, a
    CSS custom property, an HTML template) silently truncates the rest of the statement and Firebird
-   reports "Unexpected end of command". getUpsertBlock already emits single-line SQL, so there is
+   reports "Unexpected end of command". getChunkedUpsertBlocks already emits single-line SQL, so there is
    nothing to flatten. This mirrors what the admin editor sends (dataService.executeBlock). */
 const executeConfigBlock = async (blockSql, { server, apiPort, dbIndex }) => {
 	const url = `${server}:${apiPort}/fina/rest/TOrmMethod/%22block%22`;
@@ -425,43 +429,9 @@ const executeConfigBlock = async (blockSql, { server, apiPort, dbIndex }) => {
 	return parsed;
 };
 
-const estimateExecuteBlockBodyLength = (blockSql, dbIndex) =>
-	JSON.stringify({
-		_parameters: [
-			JSON.stringify({ dbIndex, method: "block", object: blockSql }),
-		],
-	}).length;
-
-/* One upsert block when it fits, else halve the chunk size until every block fits. Mirrors
-   appConfig.component.ts resolveUpsertBlocksByBodyLimit. */
-const resolveUpsertBlocks = (name, version, content, dbIndex) => {
-	const singleBlock = getUpsertBlock(name, version, content);
-	if (
-		estimateExecuteBlockBodyLength(singleBlock, dbIndex) <=
-		EXECUTE_BLOCK_BODY_LIMIT
-	) {
-		return [singleBlock];
-	}
-
-	let chunkSize = EXECUTE_BLOCK_BODY_LIMIT;
-	while (chunkSize > 0) {
-		const blocks = getChunkedUpsertBlocks(name, version, content, chunkSize);
-		if (
-			blocks.every(
-				(block) =>
-					estimateExecuteBlockBodyLength(block, dbIndex) <=
-					EXECUTE_BLOCK_BODY_LIMIT,
-			)
-		) {
-			return blocks;
-		}
-		chunkSize = Math.floor(chunkSize / 2);
-	}
-
-	throw new Error(
-		`Failed to split "${name}" into executeBlock-sized chunks.`,
-	);
-};
+/* The upsert blocks for one config. getChunkedUpsertBlocks sizes them by the finished SQL in bytes,
+   under Firebird's 65,535-byte statement limit (engine/domain/finaBlocks.js) — one block when it fits. */
+const resolveUpsertBlocks = (name, version, content) => getChunkedUpsertBlocks(name, version, content);
 
 /* PURE-ish (reads files, no network): resolve every config in the directory and validate the
    WHOLE set before anything is uploaded, so a stray lib or a typo'd metadata can never leave a
@@ -728,6 +698,7 @@ async function uploadConfigs({
 	sub,
 	publish = false,
 	forceFull = false,
+	releaseCc = false,
 	serverMode = "prod",
 }) {
 	/* Phase B2: ask biz-a for this tenant's database coordinates before anything reads the
@@ -750,6 +721,19 @@ async function uploadConfigs({
 		timeout: 60000,
 	};
 
+	/*
+	 * Doc 1 step 0a.2 — ⚠️ one owner at a time. A domain Control Center owns is refused BEFORE anything
+	 * is saved (the application config included), so a refused upload writes nothing at all.
+	 */
+	if (isPostgresIndex(dbIndex)) {
+		const { released } = await guardCcOwnedDomains({
+			exec: (sql) => execPostgres(sql, dbIndex),
+			domainNames: domains.map(({ name }) => name),
+			releaseCc,
+		});
+		if (released.length > 0) logger.info(`handed back to SVN (no longer owned by Control Center): ${released.join(", ")}`);
+	}
+
 	const saveOne = async ({ name, version, content }) => {
 		/* A PostgreSQL index writes straight to its pool. No chunking: the block splitting below
 		   exists only because the FINA HTTP body has a size limit, which a direct connection does
@@ -1039,6 +1023,7 @@ async function addApp({
 	body = null,
 	publish = false,
 	forceFull = false,
+	releaseCc = false,
 	serverMode = "prod",
 	/* Extra directories whose DOMAIN configs upload alongside this one's (see --include). */
 	include = [],
@@ -1095,6 +1080,7 @@ async function addApp({
 				sub,
 				publish,
 				forceFull,
+				releaseCc,
 				serverMode,
 			});
 		}
@@ -1303,6 +1289,7 @@ async function runUnitTests(options) {
 					files: options.files,
 					publish: options.publish,
 					forceFull: options.forceFull,
+					releaseCc: options.releaseCc,
 					serverMode: options.serverMode,
 				});
 			} else {
@@ -1336,6 +1323,7 @@ const buildCli = () =>
 						files: commandOptions.files,
 						publish: commandOptions.publish,
 						forceFull: commandOptions.forceFull,
+						releaseCc: commandOptions.releaseCc,
 						serverMode: commandOptions.serverMode,
 						include: commandOptions.include,
 					});

package/bin/directHubEvent.js

@@ -9,7 +9,7 @@ import { extClientListener } from "../engine/ext/socketListener.js";
 import { io as ioClient } from "socket.io-client";
 
 import { prefixedLogger } from "../logger.js";
-import { APP_URL, TEST_URL, ADMIN_URL, TEST_ADMIN_URL } from "../envs/hosts.js";
+import { APP_URL, TEST_URL, ADMIN_URL, TEST_ADMIN_URL, CC_URL } from "../envs/hosts.js";
 
 const logger = prefixedLogger("[DirectHub]");
 
@@ -203,10 +203,12 @@ export function createSocketServer(httpServer, cliIpAddress = "127.0.0.1") {
 				TEST_URL,
 				ADMIN_URL,
 				TEST_ADMIN_URL,
+				CC_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",
 				"https://admin.biz-a.id",
+				"https://cc.biz-a.id",
 				// NOT the wildcard (see above):
 				// /\.biz-a\.id$/,
 				"vscode-file://vscode-app",
@@ -217,8 +219,10 @@ export function createSocketServer(httpServer, cliIpAddress = "127.0.0.1") {
 							`http://${cliIpAddress}:4200`,
 							"http://localhost:4200",
 							"http://localhost",
+							// Control Center (bcc) dev server, beside the client on 4200.
+							"http://localhost:4300",
 						]
-					: [`http://${cliIpAddress}:4200`, "http://localhost:4200"],
+					: [`http://${cliIpAddress}:4200`, "http://localhost:4200", "http://localhost:4300"],
 			),
 		},
 		maxHttpBufferSize: 1e8, // 100 MB

package/bin/hub.js

@@ -121,6 +121,20 @@ const argv = yargs(process.argv.slice(2))
 		   rebuilt to send a principal. A tenant opts in explicitly. */
 		default: "observe",
 	})
+	.options("ruleMode", {
+		describe:
+			"Doc 1 0b.2: DOMAIN_RULE guards run their rule script. 'observe' logs what a rule would block and lets it pass; 'enforce' blocks.",
+		type: "string",
+		choices: ["observe", "enforce"],
+		/* ⚠️ The DEFAULT STAYS `observe`, as for principalMode: a tenant switches to enforce once its logs
+		   show its rules behave. */
+		default: "observe",
+	})
+	.options("aiGateway", {
+		describe:
+			"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("services", {
 		describe:
 			"Comma-separated list of engine jobs this agent handles (e.g., 'BPM,EMAIL')",

package/bin/hubEvent.js

@@ -16,7 +16,8 @@ import { extDeriveRoomsHandler } from "../engine/ext/esb.js";
 import { makeExtReqHandler } from "../engine/ext/hubProxy.js";
 
 import { logger } from "../logger.js";
-import { routeApiRequest } from "../engine/orm/apiRoute.js";
+import { routeApiRequest, parseAuthRequest, withFinaLoginPrincipal } from "../engine/orm/apiRoute.js";
+import { tenantSqlFor } from "../engine/orm/tenantSql.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";
@@ -24,6 +25,12 @@ import { createSessionStore } from "../engine/orm/sessionStore.js";
 import { resolveUserTenancy } from "../engine/orm/tenantResolution.js";
 import { buildUserTenantSql } from "../engine/orm/finaAuth.js";
 import { authorizeRequest, principalForCliScript } from "../security/internalPrincipal.js";
+import { whoami } from "../security/whoami.js";
+import { runDraftAction } from "../engine/cc/draftStore.js";
+import { createPgDraftRepo } from "../engine/cc/pgRepo.js";
+import { runAiAction } from "../engine/cc/aiTurns.js";
+import { createTurnRepo } from "../engine/cc/turnRepo.js";
+import { createAiGatewayClient } from "../security/aiGatewayClient.js";
 import {
 	readUserPreferences,
 	writeUserPreferences,
@@ -43,7 +50,7 @@ import {
 	execPostgresTransaction,
 	isPostgresIndex,
 } from "../engine/domain/dialect.js";
-import { resolveTunnelTarget } from "./tunnelTarget.js";
+import { pipeTunnel } from "./tunnelTarget.js";
 /*
  * Doc 4 §8 — ⚠️ `runAsPrincipal` VALIDATES SYNCHRONOUSLY, so a browser-supplied active tenant outside
  * the signed claim throws out of the CALL, not out of the promise it would have returned. On this
@@ -228,59 +235,34 @@ export const streamEvent = async (socket, argv) =>
 				},
 			});
 
-			// let client = net.connect(argv['port'], argv['hostname']);
-			/* Where this pipe ends. A tenant this CLI serves on PostgreSQL is looped back to the
-			   hub's own FINA-compatible endpoint; every other tenant goes to FINA unchanged.
-			   Without this, biz-a's login — which only ever travels this tunnel — could not be
-			   answered at all on a tenant with no FINA running. */
-			const target = resolveTunnelTarget(argv, isPostgresIndex);
-			let client = target.secure
-				? tls.connect({
-						port: target.port,
-						host: target.host,
-						// Looping back to ourselves, the certificate is our own.
-						rejectUnauthorized: !target.local,
-					})
-				: net.connect(target.port, target.host);
-			client.on("connect", () => {
-				// logger.info(`client connected to ${argv['hostname']}:${argv['port']}`)
-				let s = ss.createStream();
-
-				// s.pipe(client).pipe(s);
-				s.pipe(client).pipe(addCLIAddressAsResponseHeader).pipe(s);
-
-				// use pipeline for better performance, back pressure, memory management, error handling and clean up
-				// pipeline(s, client, addCLIAddressAsResponseHeader, s, (err)=>{if (err) {logger.error(err)}}) // Not work well with heroku
-
-				s.on("end", () => {
-					client.destroy();
-				});
-
-				socket.once(clientId, () => {
-					// hub server shall notify us to end pipeline as soon as possible
-					client.end();
-				});
-
-				ss(socket).emit(clientId, s);
-			});
-
-			client.setTimeout(IDLE_SOCKET_TIMEOUT_MILLISECONDS);
-			client.on("timeout", () => {
-				// in case client not notify to end pipeline, then inactivity timeout will end it
-				client.end();
-			});
-
-			client.on("error", (err) => {
-				// handle connection refusal (create a stream and immediately close it)
-				logger.error(
-					`API Error : tunnel could not reach ${target.local ? "this CLI's own endpoint" : "the API"} at ` +
-						`${target.host}:${target.port} — `,
-					err,
-				);
-				let s = ss.createStream();
-				ss(socket).emit(clientId, s);
-				s.end();
+			/*
+			 * Where this pipe ends is decided by the request's FIRST BYTES (bin/tunnelTarget.js): a tenant
+			 * this CLI serves on PostgreSQL, and — since 2026-10-01 — a Firebird tenant's LOGIN, are looped
+			 * back to the hub's own FINA-compatible endpoint; every other request goes to FINA unchanged.
+			 * Without the loop-back a Firebird login never passed through the CLI, so it never received
+			 * the signed principal (Doc 6 on Firebird).
+			 */
+			const s = ss.createStream();
+			pipeTunnel({
+				stream: s,
+				argv,
+				isPostgresIndex,
+				connect: (target) =>
+					target.secure
+						? tls.connect({
+								port: target.port,
+								host: target.host,
+								// Looping back to ourselves, the certificate is our own.
+								rejectUnauthorized: !target.local,
+							})
+						: net.connect(target.port, target.host),
+				transform: () => addCLIAddressAsResponseHeader,
+				idleMs: IDLE_SOCKET_TIMEOUT_MILLISECONDS,
+				// hub server shall notify us to end pipeline as soon as possible
+				onClient: (client) => socket.once(clientId, () => client.end()),
+				logger,
 			});
+			ss(socket).emit(clientId, s);
 		};
 
 		// const cliReqCb = async (data, callback) => {
@@ -483,6 +465,14 @@ const handleCliCommand = async (data, cb, argv) => {
 			case "status":
 				cb(null, status(argv));
 				break;
+			/*
+			 * Doc 1 step 0a.1 — who THIS CLI verified is asking. Control Center checks it before
+			 * offering any editing: a successful login at biz-a does not prove the principal
+			 * verifies here. Headers only; see security/whoami.js.
+			 */
+			case "whoami":
+				cb(null, whoami(data.headers, { mode: argv["principalMode"] || "observe" }));
+				break;
 			case "runcliscript":
 				const liveTriggerPayload = {
 					arguments: argv,
@@ -542,16 +532,19 @@ const handleCliCommand = async (data, cb, argv) => {
 				const prefPrincipal = principalForCliScript(data.headers, {
 					mode: argv["principalMode"] || "observe",
 				});
-				const prefExec = (sql) => execPostgres(sql, argv["dbindex"]);
+				/* Doc 6 on Firebird (2026-10-01) — the tenant seam runs this on either engine. */
+				const prefDb = tenantSqlFor(argv["dbindex"]);
 				const prefs =
 					data.action === "write"
 						? await writeUserPreferences({
-								exec: prefExec,
+								exec: prefDb.exec,
+								execStatements: prefDb.atomic,
+								sql: prefDb,
 								principal: prefPrincipal,
 								patch: data.patch,
 							})
 						: await readUserPreferences({
-								exec: prefExec,
+								exec: prefDb.exec,
 								principal: prefPrincipal,
 							});
 				cb(null, { success: true, data: prefs });
@@ -573,12 +566,15 @@ const handleCliCommand = async (data, cb, argv) => {
 				const themePrincipal = principalForCliScript(data.headers, {
 					mode: argv["principalMode"] || "observe",
 				});
-				const themeExec = (sql) => execPostgres(sql, argv["dbindex"]);
+				/* Doc 6 on Firebird (2026-10-01) — one transaction on either engine: a PostgreSQL
+				   transaction, or ONE Firebird EXECUTE BLOCK (engine/orm/tenantSql.js). */
+				const themeDb = tenantSqlFor(argv["dbindex"]);
+				const themeExec = themeDb.exec;
 				if (data.action === "write") {
 					const saved = await writeCompanyTheme({
 						exec: themeExec,
-						execStatements: (statements) =>
-							execPostgresStatements(statements, argv["dbindex"]),
+						execStatements: themeDb.atomic,
+						sql: themeDb,
 						principal: themePrincipal,
 						theme: data.theme,
 					});
@@ -612,14 +608,17 @@ const handleCliCommand = async (data, cb, argv) => {
 				const logoPrincipal = principalForCliScript(data.headers, {
 					mode: argv["principalMode"] || "observe",
 				});
-				const logoExec = (sql) => execPostgres(sql, argv["dbindex"]);
-				const logoStatements = (statements) =>
-					execPostgresStatements(statements, argv["dbindex"]);
+				/* Doc 6 on Firebird (2026-10-01) — the tenant seam; on Firebird a logo is staged in
+				   blocks (runBlocks) and swapped in atomically (companyLogo.js). */
+				const logoDb = tenantSqlFor(argv["dbindex"]);
+				const logoExec = logoDb.exec;
 
 				if (data.action === "write") {
 					const saved = await writeCompanyLogo({
 						exec: logoExec,
-						execStatements: logoStatements,
+						execStatements: logoDb.atomic,
+						sql: logoDb,
+						runBlocks: logoDb.runBlocks,
 						principal: logoPrincipal,
 						dataUrl: data.dataUrl,
 					});
@@ -633,7 +632,8 @@ const handleCliCommand = async (data, cb, argv) => {
 				} else if (data.action === "clear") {
 					const cleared = await clearCompanyLogo({
 						exec: logoExec,
-						execStatements: logoStatements,
+						execStatements: logoDb.atomic,
+						sql: logoDb,
 						principal: logoPrincipal,
 					});
 					cb(null, { success: cleared.ok, problems: cleared.problems, data: null });
@@ -645,6 +645,59 @@ const handleCliCommand = async (data, cb, argv) => {
 				}
 				break;
 			}
+			/*
+			 * Doc 1 step 0a.2 — Control Center drafts (engine/cc/draftStore.js). Administrators only,
+			 * from the principal in the HEADERS; a draft never reaches SYS$CONFIG or SYS$BPM_* (only
+			 * publish may). A refusal the user can act on is returned as `problems`, as companytheme
+			 * does; `code` carries CC_DRAFT_STALE for a save made from an old revision.
+			 */
+			/*
+			 * Doc 1 0b.6b — an AI turn from Control Center, through the central gateway
+			 * (engine/cc/aiTurns.js). `send` answers at once; the turn finishes in the background, is
+			 * recorded in SYS$CC_TURN with its cost, and the VERIFIED user is told {turnId, outcome}.
+			 * The CLI holds no AI key: the gateway client signs with this company's biza.ai key.
+			 */
+			case "ccai": {
+				const aiResult = await runAiAction({
+					repo: createTurnRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					gateway: createAiGatewayClient({ baseUrl: argv["aiGateway"] || argv["server"], subdomain: argv["subdomain"] }),
+					principal: principalForCliScript(data.headers, { mode: argv["principalMode"] || "observe" }),
+					isPostgres: isPostgresIndex(argv["dbindex"]),
+					action: data.action,
+					args: data.args,
+					notify: (userId, eventName, payload) => ClientEmitter.emitUsers([userId], eventName, payload),
+					logger,
+				});
+				cb(null, {
+					success: aiResult.ok,
+					...(aiResult.code ? { code: aiResult.code } : {}),
+					problems: aiResult.problems ?? [],
+					data: aiResult.data ?? null,
+				});
+				break;
+			}
+			case "ccdraft": {
+				const ccResult = await runDraftAction({
+					repo: createPgDraftRepo({
+						exec: (sql) => execPostgres(sql, argv["dbindex"]),
+						execStatements: (statements) => execPostgresStatements(statements, argv["dbindex"]),
+					}),
+					principal: principalForCliScript(data.headers, { mode: argv["principalMode"] || "observe" }),
+					isPostgres: isPostgresIndex(argv["dbindex"]),
+					action: data.action,
+					args: data.args,
+					/* 0b.3: publish writes SYS$CONFIG, SYS$APPS and SYS$BPM_* through the existing pipelines —
+					   loaded only for a publish (appConfig.js imports this file, and must not pull the BPM engine in). */
+					pipelines: data.action === "publish" ? ((m) => (userId) => m.createLivePipelines({ argv, userId }))(await import("../engine/cc/livePipelines.js")) : undefined,
+				});
+				cb(null, {
+					success: ccResult.ok,
+					...(ccResult.code ? { code: ccResult.code } : {}),
+					problems: ccResult.problems ?? [],
+					data: ccResult.data ?? null,
+				});
+				break;
+			}
 			case "runextcliscript": {
 				// External-access op invoker — enforces the capability boundary (dispatch.js),
 				// unlike raw `runcliscript`. Safe to expose: no valid token -> UNAUTHENTICATED.
@@ -836,6 +889,11 @@ export const clientListener = (socket, argv, via = "?") => {
 							maxContentLength: Infinity,
 						})
 						.then((response) => {
+							/* Doc 6 on Firebird — a login FINA answered gets its principal, on this
+							   transport as on the HTTP one (finaEndpoint.js); see apiRoute.js. */
+							if (parseAuthRequest(reqData.path, reqBody)) {
+								response.data = withFinaLoginPrincipal(response.data, Number(argv["dbindex"]));
+							}
 							resCB(null, socketResponse(response));
 						})
 						.catch((error) => {

package/bin/tunnelTarget.js

@@ -11,8 +11,35 @@
  * database index, as it is everywhere else in this port.
  */
 
+/*
+ * ⚠️ Doc 6 on Firebird (found live 2026-10-01): the LOGIN of a Firebird tenant went straight to FINA
+ * through this tunnel, so the CLI never saw FINA's answer and never added the signed principal — and
+ * every principal-guarded command (company theme, logo, user preferences) refused on Firebird. The login
+ * is now looped back to the CLI's own endpoint too (finaEndpoint.js forwards it to FINA and appends the
+ * principal); every other Firebird request still goes straight to FINA, byte for byte.
+ *
+ * Recognised by its REQUEST LINE only (method + path), never by anything in a body.
+ */
+const LOGIN_PATH = /%22get_valid_user_id%22|"get_valid_user_id"/i;
+
+export const isLoginRequest = (firstChunk) => {
+	if (!firstChunk || firstChunk.length === 0) return false;
+	const head = Buffer.from(firstChunk).subarray(0, 2048).toString("latin1");
+	const lineEnd = head.indexOf("\r\n");
+	const requestLine = lineEnd === -1 ? head : head.slice(0, lineEnd);
+	const [method, path] = requestLine.split(" ");
+	return method === "POST" && typeof path === "string" && LOGIN_PATH.test(path);
+};
+
+const ownEndpoint = (argv) => ({
+	host: "127.0.0.1", // ourselves — never the public interface
+	port: argv.serverport,
+	secure: argv.isHttps === true, // how WE listen; argv.secure describes FINA
+	local: true,
+});
+
 /* Kept separate from hubEvent.js so it can be exercised without importing the socket machinery. */
-export const resolveTunnelTarget = (argv, isPostgresIndex) => {
+export const resolveTunnelTarget = (argv, isPostgresIndex, firstChunk) => {
 	const fina = {
 		host: argv.hostname,
 		port: argv.port,
@@ -20,6 +47,7 @@ export const resolveTunnelTarget = (argv, isPostgresIndex) => {
 		local: false,
 	};
 
+	if (isLoginRequest(firstChunk)) return ownEndpoint(argv);
 	if (!argv.dbindex) return fina;
 
 	let servedHere = false;
@@ -32,10 +60,35 @@ export const resolveTunnelTarget = (argv, isPostgresIndex) => {
 	}
 	if (!servedHere) return fina;
 
-	return {
-		host: "127.0.0.1", // ourselves — never the public interface
-		port: argv.serverport,
-		secure: argv.isHttps === true, // how WE listen; argv.secure describes FINA
-		local: true,
-	};
+	return ownEndpoint(argv);
+};
+
+/*
+ * One tunnelled request: biz-a's bytes arrive on `stream`; the connection is opened only once the first
+ * bytes say where it must go (resolveTunnelTarget), that first chunk is written first so nothing is
+ * lost, and the rest is piped. The answer flows back through `transform()` (the response-header
+ * injection). A connection that fails ends the stream, so biz-a is not left waiting.
+ */
+export const pipeTunnel = ({ stream, argv, isPostgresIndex, connect, transform, idleMs, onClient, logger = console }) => {
+	stream.once("data", (first) => {
+		stream.pause();
+		const target = resolveTunnelTarget(argv, isPostgresIndex, first);
+		const client = connect(target);
+		onClient?.(client);
+		if (idleMs) client.setTimeout(idleMs);
+		client.on("timeout", () => client.end());
+		client.on("connect", () => {
+			client.write(first);
+			stream.pipe(client).pipe(transform()).pipe(stream);
+			stream.resume();
+		});
+		client.on("error", (err) => {
+			logger.error?.(
+				`API Error : tunnel could not reach ${target.local ? "this CLI's own endpoint" : "the API"} at ${target.host}:${target.port} — `,
+				err,
+			);
+			stream.end();
+		});
+		stream.on("end", () => client.destroy());
+	});
 };

package/db/db.js

@@ -115,11 +115,11 @@ export const list = async (payload, config = {}) => {
 };
 
 /* Refused on PostgreSQL — the bodies are Firebird PSQL. See executor.js for the reasoning. */
-export const executeBlock = async (sqlString, config = {}) => {
+export const executeBlock = async (sqlString, config = {}, options = {}) => {
 	if (onPostgres(config)) {
 		return await executor.executeBlock(sqlString, resolveDbIndex(config));
 	}
-	return await adapter.executeBlock(sqlString, config);
+	return await adapter.executeBlock(sqlString, config, options);
 };
 
 /* An optimistic claim: flip one row's status if it is still in an expected state, and report

package/db/ds.js

@@ -261,15 +261,34 @@ function flattenSql(sqlString) {
 		.join(" "); // 5. Join safely with exactly one space
 }
 
-export const executeBlock = async (sqlString, config = {}) => {
+/* `flatten: false` sends the SQL as written — for a block that is single-line already and carries a
+   text VALUE, where flattenSql's `--` stripping would cut the value (engine/domain/finaBlocks.js). */
+export const executeBlock = async (sqlString, config = {}, { flatten = true } = {}) => {
 	const cfg = resolveConfig(config);
 	const url = buildDataSnapUrl(cfg, "block");
-	const flatSql = flattenSql(sqlString);
+	const flatSql = flatten ? flattenSql(sqlString) : sqlString;
 	// const data = buildDataSnapPayload(cfg, "block", sqlString);
 	const data = buildDataSnapPayload(cfg, "block", flatSql);
 	return await dsReq(url, data, cfg.timeout);
 };
 
+/* FINA's ExecuteSQL: one raw statement, positional parameters `[sql, dbIndex]` (not the ORM envelope),
+   rows as a JSON string inside `result[0]` (an empty string when there are none). Keys are lower-cased,
+   as execPostgres returns them, so a caller reads one shape on either engine (engine/orm/tenantSql.js).
+   The SQL must be single-line: a raw newline ends the command on this transport. */
+export const executeSql = async (sql, config = {}) => {
+	const cfg = resolveConfig({ ...config, methodClass: "TFinaMethod" });
+	const url = buildDataSnapUrl(cfg, "ExecuteSQL");
+	const res = await dsReq(url, JSON.stringify({ _parameters: [sql, String(cfg.dbindex)] }), cfg.timeout);
+	const first = res?.result?.[0];
+	if (first && typeof first === "object" && first.error) throw new Error(first.error);
+	if (typeof first !== "string" || first === "") return [];
+	const rows = JSON.parse(first)?.data;
+	return (Array.isArray(rows) ? rows : []).map((row) =>
+		Object.fromEntries(Object.entries(row).map(([key, value]) => [key.toLowerCase(), value])),
+	);
+};
+
 export const ormGet = async (payload, config = {}) => {
 	const cfg = resolveConfig(config);
 	const url = buildDataSnapUrl(cfg, "orm");