biz-a-cli 2.3.80-15381 → 2.3.80-15385

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,15 @@ 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("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,9 @@ 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 {
 	readUserPreferences,
 	writeUserPreferences,
@@ -483,6 +487,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 +554,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 +588,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 +630,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 +654,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 +667,34 @@ 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.
+			 */
+			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 +886,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/config/secrets.json

@@ -1,21 +1,27 @@
 {
-	"supertail.ledger": {
-		"currentKeyId": "st_ledger_v1",
-		"keys": {
-			"st_ledger_v1": "CdgBjUShgx7t9Wo/dfSOOJAHjHOD5KwAlRi6xwDMEfs="
-		}
-	},
-	"supertail.session": "3jepiFkSV6HxlbCSWiGqYWpmfapYxLHeHY/YgxyFQ8Q=",
-	"ext.capability": {
-		"currentKeyId": "ext_v1",
-		"keys": {
-			"ext_v1": "f4PLkG2QLn6OFyv0IlqWhq3tlSGs2VAyaYDM4kDKLZ8="
-		}
-	},
-	"internal.principal": {
-		"currentKeyId": "ip_v1",
-		"keys": {
-			"ip_v1": "GsoRIpPG0D7c0q+AtmMNrtKpZ104Uv4/tfmLHtAtbIM="
-		}
-	}
+  "supertail.ledger": {
+    "currentKeyId": "st_ledger_v1",
+    "keys": {
+      "st_ledger_v1": "CdgBjUShgx7t9Wo/dfSOOJAHjHOD5KwAlRi6xwDMEfs="
+    }
+  },
+  "supertail.session": "3jepiFkSV6HxlbCSWiGqYWpmfapYxLHeHY/YgxyFQ8Q=",
+  "ext.capability": {
+    "currentKeyId": "ext_v1",
+    "keys": {
+      "ext_v1": "f4PLkG2QLn6OFyv0IlqWhq3tlSGs2VAyaYDM4kDKLZ8="
+    }
+  },
+  "internal.principal": {
+    "currentKeyId": "ip_v1",
+    "keys": {
+      "ip_v1": "GsoRIpPG0D7c0q+AtmMNrtKpZ104Uv4/tfmLHtAtbIM="
+    }
+  },
+  "biza.ai.studiob": {
+    "currentKeyId": "ai_v1",
+    "keys": {
+      "ai_v1": "QxE6YiZdcjVRK1UbWGRMLuEgBKM3zFUte9euFldduZc="
+    }
+  }
 }

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");

package/engine/bpm/domainRules.js

@@ -0,0 +1,71 @@
+/*
+ * Doc 1 step 0b.2 — DOMAIN_RULE guards (design CC-DRAFTS-AND-ENGINE-GAPS §5B).
+ *
+ * A rule key names a REGISTERED CLI script (SYS$CLI_SCRIPT.SCRIPT_NAME = the key). The engine runs it with
+ * { entityType, entityId, entityData, transitionCode, principal } and reads back { pass, hint? }:
+ *
+ *  - FAIL-CLOSED: only `pass === true` passes. A missing script (the worker answers with a string, it does
+ *    not throw), an error, or no answer within the limit all block, with a hint naming the rule.
+ *  - Rolled out like --principalMode: `observe` evaluates and logs every would-block but lets the
+ *    transition pass (today's behaviour, with evidence); `enforce` blocks. Absent = observe; an
+ *    unrecognised value = enforce.
+ *
+ * The principal is the caller's CLAIM (userId, userRoles) marked `verified: false` — no verified principal
+ * reaches the BPM runtime yet (ruling 2026-09-29).
+ *
+ * Main-thread only (it runs scripts through the worker pool); rules.js stays pure and takes the evaluator
+ * it is given.
+ */
+export const RULE_TIMEOUT_MS = 2000;
+
+export const ruleModeOf = (config) => {
+	const mode = config?.ruleMode;
+	if (!mode || mode === "observe") return "observe";
+	return "enforce";
+};
+
+const seconds = (ms) => `${ms / 1000} s`;
+
+/* The verdict of one rule script: { pass, hint }. Never throws. */
+export async function judgeRule(key, ctx, { runScript, timeoutMs = RULE_TIMEOUT_MS }) {
+	let timer;
+	try {
+		const running = runScript(key, ctx);
+		/* workerpool can also stop the worker itself once the task leaves the queue. */
+		if (running && typeof running.timeout === "function") running.timeout(timeoutMs);
+		const expired = new Promise((_, reject) => {
+			timer = setTimeout(() => reject(Object.assign(new Error("timeout"), { ruleTimeout: true })), timeoutMs);
+		});
+		const result = await Promise.race([running, expired]);
+
+		if (typeof result === "string" && /not found/i.test(result)) {
+			return { pass: false, hint: `Rule ${key} is not registered: there is no CLI script of that name.` };
+		}
+		if (result && typeof result === "object" && result.pass === true) return { pass: true, hint: "" };
+		const hint = result && typeof result === "object" && typeof result.hint === "string" && result.hint ? result.hint : `Rule ${key} did not pass.`;
+		return { pass: false, hint };
+	} catch (error) {
+		if (error?.ruleTimeout || error?.name === "TimeoutError") return { pass: false, hint: `Rule ${key} did not answer within ${seconds(timeoutMs)}.` };
+		return { pass: false, hint: `Rule ${key} failed: ${error?.message ?? error}` };
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/* evaluateDomain(key, ctx) → { pass, hint }, with the rollout mode applied. */
+export function createDomainEvaluator({ mode, runScript, timeoutMs = RULE_TIMEOUT_MS, logger }) {
+	return async function evaluateDomain(key, ctx) {
+		const verdict = await judgeRule(key, ctx, { runScript, timeoutMs });
+		const where = `${ctx.transitionCode} on ${ctx.entityType} ${ctx.entityId}: ${key}`;
+		if (verdict.pass) {
+			logger?.debug?.(`[rules] passed ${where} (mode=${mode})`);
+			return verdict;
+		}
+		if (mode === "observe") {
+			logger?.warn?.(`[rules] would block ${where} — ${verdict.hint} (mode=observe)`);
+			return { pass: true, hint: "" };
+		}
+		logger?.info?.(`[rules] blocked ${where} — ${verdict.hint} (mode=${mode})`);
+		return verdict;
+	};
+}

package/engine/bpm/routes.js

@@ -24,6 +24,8 @@ const expressWrapper = (engineFunction) => async (req, res) => {
 // ==========================================
 router.post("/workflow/save", expressWrapper(workflow.save));
 router.post("/workflow/publish", expressWrapper(workflow.publish));
+/* Doc 1 0b.1: what publish would refuse, without publishing (read-only). */
+router.post("/workflow/validate", expressWrapper(workflow.validate));
 router.post("/workflow/remove", expressWrapper(workflow.remove));
 
 // ==========================================

package/engine/bpm/rules.d.ts

@@ -0,0 +1,121 @@
+/* Types of rules.js for Control Center (bcc imports the engine's rules directly — Doc 1 0a.6). */
+
+/* Doc 1 0b.2: a DOMAIN_RULE verdict (the engine injects the rule-script evaluator). */
+export type DomainEvaluate = (key: string, transitionCode?: string) => Promise<{ pass: boolean; hint: string }>;
+
+export type GuardEvaluate = (expr: string, m: unknown) => unknown | Promise<unknown>;
+
+export interface CompiledRole {
+	role_code: string;
+}
+
+export interface CompiledEffect {
+	effect_type: string;
+	event_name: string;
+	payload_template: string | null;
+	sort_no: number;
+}
+
+export interface CompiledState {
+	state_code: string;
+	label: string;
+	task_enabled: 0 | 1;
+	task_name: string | null;
+	assignment_type: string | null;
+	assignment_value: string | null;
+	sla_duration_minutes: number | null;
+	timeout_action_type: string | null;
+	timeout_event_name: string | null;
+	sort_no: number;
+}
+
+export interface CompiledTransition {
+	transition_code: string;
+	from_state_code: string;
+	to_state_code: string;
+	trigger_type: string;
+	label: string | undefined;
+	guard_type: string | null;
+	guard_rule_key: string | null;
+	sort_no: number;
+	roles: CompiledRole[];
+	effects: CompiledEffect[];
+}
+
+export interface CompiledDefinition {
+	workflow: { workflow_key: string; name: string; entity_type: string; description: string; initial_state_code: string };
+	states: CompiledState[];
+	transitions: CompiledTransition[];
+}
+
+export interface GuardResult {
+	isPassed: boolean;
+	errorMsg: string;
+}
+
+export type WithGuard<T> = T & { isGuardPassed: boolean; guardHint: string };
+
+export interface EntryTimer {
+	id: null;
+	sys$bpm_wf_instance_id: number | null;
+	sys$bpm_task_id?: null;
+	state_code: string;
+	timer_type: 'SLA_TIMEOUT';
+	sla_minutes: number;
+	status: 'OPEN';
+}
+
+export interface EntryTask {
+	id: null;
+	state_code: string;
+	name: string | null;
+	status: 'OPEN';
+	assignment_type: string | null;
+	assignment_value: string | null;
+	assigned_user_id: number | null;
+	sla_minutes: number | null;
+	SYS$BPM_TIMER_JOB?: EntryTimer[];
+}
+
+export type TimerOutcome<T> =
+	| { kind: 'EMIT'; eventName: string }
+	| { kind: 'AUTO'; transition: T }
+	| { kind: 'ERROR'; message: string }
+	| { kind: 'NONE' };
+
+export const DEFAULT_TRIGGER: 'USER_EVENT';
+export const SYSTEM_ROLES: string[];
+
+export function compileDefinition(json: Record<string, any>): CompiledDefinition;
+export function permitsRoles(roleCodes: string[] | null | undefined, userRoles: string[]): boolean;
+export function guardVerdict(
+	guardType: string | null,
+	guardRuleKey: string | null,
+	entityData: unknown,
+	evaluate: GuardEvaluate,
+	evaluateDomain?: (key: string) => Promise<{ pass: boolean; hint: string }>,
+): Promise<GuardResult>;
+export function withGuardVerdicts<T extends { guard_type: string | null; guard_rule_key: string | null }>(
+	transitions: T[],
+	entityData: unknown,
+	evaluate: GuardEvaluate,
+	evaluateDomain?: DomainEvaluate,
+): Promise<WithGuard<T>[]>;
+export function selectTransitions(
+	transitions: CompiledTransition[],
+	options: { fromState: string; triggerType?: string; userRoles?: string[]; m?: unknown; evaluate: GuardEvaluate; evaluateDomain?: DomainEvaluate },
+): Promise<WithGuard<CompiledTransition>[]>;
+export function isTerminal(transitions: CompiledTransition[], stateCode: string): boolean;
+export function stateEntry(
+	targetStateDef: CompiledState | null | undefined,
+	terminal: boolean,
+	instanceId: number | string | null,
+): { tasks: EntryTask[]; standaloneTimers: EntryTimer[] };
+export function timerOutcome<T extends { guard_type: string | null; guard_rule_key: string | null }>(
+	stateRow: CompiledState | null | undefined,
+	stateCode: string,
+	loadTimerTransitions: () => Promise<T[]>,
+	evaluate: GuardEvaluate,
+	evaluateDomain?: DomainEvaluate,
+): Promise<TimerOutcome<T>>;
+export function effectPayload(payloadTemplate: string | null | undefined, effectData: Record<string, unknown> | null | undefined): string | null;