biz-a-cli 2.3.80-15397 → 2.3.80-15407

package/bin/hub.js

@@ -26,6 +26,7 @@ import { CLI_Agent } from "../message-broker/agent.js";
 import { initBpmAgent } from "../engine/bpm/bpm-agent.js";
 import { bootMicroservices } from "../message-broker/orchestrator.js";
 import { ClientEmitter } from "../message-broker/clientEmitter.js";
+import crypto from "node:crypto";
 
 process.on("uncaughtException", (err) => {
 	logger.error("Unhandled Exception:", err);
@@ -197,6 +198,7 @@ import http from "http";
 import https from "https";
 import path from "node:path";
 import bpmRoutes from "../engine/bpm/routes.js";
+import { startWorkflowOnCreate } from "../engine/bpm/workflowOnCreate.js";
 import { createExtRouter } from "../engine/ext/routes.js";
 import { createLiveExtDeps } from "../engine/ext/live.js";
 import axios from "axios";
@@ -235,6 +237,11 @@ app.use("/status", (req, res) => {
 	res.status(200).json(status(argv));
 });
 
+/* The engine mirrors a workflow's state onto a declaring entity's record (bpm/stateMirror.js) — keep the
+   declarations current on this route too. `.finally(next)`: never refuse a request over the freshness check. */
+app.use("/bpm", (_req, _res, next) => {
+	ensureEntityConfig(Number(argv.dbindex)).finally(() => next());
+});
 app.use("/bpm", bpmRoutes);
 
 // FINA-compatible endpoint. Requests reach this CLI two ways: the client's data calls over the
@@ -322,6 +329,9 @@ app.use(
 						buildBindingSql: buildUserTenantSql,
 					})
 			: null,
+		/* 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,
 		/* 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() : {}),
@@ -504,9 +514,10 @@ if (argv.mode.trim().toLowerCase() === "agent") {
 	const genericAgent = new CLI_Agent(argv.dispatcherUrl, argv.services);
 	initBpmAgent(genericAgent, argv.services);
 } else {
+	const cliInstanceId = crypto.randomUUID();
 	// as socket client to BizA SERVER
 	await streamEvent(
-		ioClient(argv["server"], { query: { isSockStream: true } }),
+		ioClient(argv["server"], { query: { isSockStream: true, CLIInstanceId: cliInstanceId } }),
 		argv,
 	);
 
@@ -516,7 +527,7 @@ if (argv.mode.trim().toLowerCase() === "agent") {
 			ioClient(argv["hubServer"], {
 				reconnectionDelay: RECONNECT_SOCKET_DELAY,
 				reconnectionDelayMax: RECONNECT_SOCKET_DELAY,
-				query: { isCLI: true, room: argv["subdomain"] },
+				query: { isCLI: true, room: argv["subdomain"], CLIInstanceId: cliInstanceId },
 			}),
 			argv,
 			(url) => {

package/bin/hubEvent.js

@@ -19,6 +19,8 @@ import { logger } from "../logger.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 { startWorkflowOnCreate } from "../engine/bpm/workflowOnCreate.js";
+import { bpmContextFromHeaders } from "../engine/bpm/bpmContext.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";
@@ -107,6 +109,29 @@ export const IDLE_SOCKET_TIMEOUT_MILLISECONDS = 1000 * 28;
 export const RECONNECT_SOCKET_DELAY = 60 * 1000;
 const DISCONNECT_REASON_BY_SOCKET_SERVER = "io server disconnect";
 
+export const JITTER_DELAY_MIN_MS = 500;
+export const JITTER_DELAY_MAX_MS = 2500;
+
+export const attachResilientDisconnect = (socket, getPrefix, serverName, notifier = null) => {
+	socket.on("disconnect", (reason) => {
+		if (notifier) notifier("");
+		logger.info(
+			`${new Date()}: ${getPrefix()}disconnected from ${serverName}. Reason: ${reason}`,
+		);
+		if (reason.toLowerCase() === DISCONNECT_REASON_BY_SOCKET_SERVER) {
+			socket.connect();
+		} else if (reason === "transport close" || reason === "ping timeout" || reason === "transport error") {
+			const jitterMs = Math.floor(Math.random() * (JITTER_DELAY_MAX_MS - JITTER_DELAY_MIN_MS)) + JITTER_DELAY_MIN_MS;
+			setTimeout(() => {
+				if (socket.disconnected) {
+					logger.info(`${new Date()}: ${getPrefix()}injecting jittered reconnect to ${serverName} (${jitterMs}ms)`);
+					socket.connect();
+				}
+			}, jitterMs);
+		}
+	});
+};
+
 /* biz-a's answer when the subdomain is still registered to a socket it has not yet reaped
    (hubController.js createSockStream2CLI). It clears itself once that socket times out. */
 const isSubdomainClaimConflict = (error) =>
@@ -318,14 +343,27 @@ export const streamEvent = async (socket, argv) =>
 		socket.on("ext-req", extReqCb);
 		socket.on("cliCommand", (data, cb) => handleCliCommand(data, cb, argv));
 
-		socket.on("disconnect", (reason) => {
+		// socket.on("disconnect", (reason) => {
+		// 	logger.info(
+		// 		`${new Date()}: ${getIdText(id)}disconnected from BizA Server. Reason: ${reason}`,
+		// 	);
+		// 	id = undefined;
+		// 	if (reason.toLowerCase() === DISCONNECT_REASON_BY_SOCKET_SERVER) {
+		// 		socket.connect();
+		// 	}
+		// });
+
+		attachResilientDisconnect(socket, () => getIdText(id), "BizA Server");
+		const logError = (msg) => {
 			logger.info(
-				`${new Date()}: ${getIdText(id)}disconnected from BizA Server. Reason: ${reason}`,
+				`${new Date()}: ${getIdText(id)}connection error to BizA Server at ${argv["server"]} using sub domain "${argv["subdomain"]}". Error : ${msg}`,
 			);
-			id = undefined;
-			if (reason.toLowerCase() === DISCONNECT_REASON_BY_SOCKET_SERVER) {
-				socket.connect();
-			}
+		};
+		socket.on("connect_error", (error) => {
+			logError(error.message);
+		});
+		socket.on("error", (error) => {
+			logError(error);
 		});
 
 		socket.io.on("reconnect", () => {
@@ -345,16 +383,17 @@ export const hubEvent = (socket, argv, notifier) => {
 			`${new Date()}: ${getIdText(id)}connected to BizA Hub at ${argv["hubServer"]} using sub domain "${argv["subdomain"]}"`,
 		);
 	});
-	socket.on("disconnect", (reason) => {
-		notifier("");
-		logger.info(
-			`${new Date()}: ${getIdText(id)}disconnected from BizA Hub. Reason: ${reason}`,
-		);
-		id = undefined;
-		if (reason.toLowerCase() === DISCONNECT_REASON_BY_SOCKET_SERVER) {
-			socket.connect();
-		}
-	});
+	// socket.on("disconnect", (reason) => {
+	// 	notifier("");
+	// 	logger.info(
+	// 		`${new Date()}: ${getIdText(id)}disconnected from BizA Hub. Reason: ${reason}`,
+	// 	);
+	// 	id = undefined;
+	// 	if (reason.toLowerCase() === DISCONNECT_REASON_BY_SOCKET_SERVER) {
+	// 		socket.connect();
+	// 	}
+	// });
+	attachResilientDisconnect(socket, () => getIdText(id), "BizA Hub", notifier);
 	const logError = (msg) => {
 		logger.info(
 			`${new Date()}: ${getIdText(id)}connection error to BizA Hub at ${argv["hubServer"]} using sub domain "${argv["subdomain"]}". Error : ${msg}`,
@@ -781,6 +820,11 @@ const handleCliCommand = async (data, cb, argv) => {
 
 				const engineModule = await EngineRegistry[modulePath]();
 
+				/* The BPM engine mirrors a workflow's state onto the record of an entity that declares it
+				   (bpm/stateMirror.js reads the entity declarations) — keep them current here as the data
+				   entrance below does. Never fatal: the declarations already held still answer. */
+				await ensureEntityConfig(Number(argv["dbindex"])).catch(() => {});
+
 				if (typeof engineModule[methodName] !== "function") {
 					throw new Error(
 						`Method '${methodName}' does not exist on target '${modulePath}'.`,
@@ -802,8 +846,16 @@ 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). */
+				const engineContext =
+					modulePath === "bpm/workflowRT"
+						? bpmContextFromHeaders(data.headers, { mode: argv["principalMode"] || "observe" })
+						: undefined;
 				const result = await runTrusted(() =>
-					engineModule[methodName](data.payload, argv),
+					engineContext
+						? engineModule[methodName](data.payload, argv, engineContext)
+						: engineModule[methodName](data.payload, argv),
 				);
 
 				cb(null, { success: true, data: result });
@@ -1044,6 +1096,7 @@ export const clientListener = (socket, argv, via = "?") => {
 									openSession: openSessionFor(Number(argv["dbindex"])),
 									chooseActiveTenant: (sid, tenantId) =>
 										sessionStoreFor(Number(argv["dbindex"]))?.chooseActiveTenant(sid, tenantId),
+									startWorkflow: startWorkflowOnCreate,
 								},
 							),
 						),

package/bin/watcher.js

@@ -1,51 +1,108 @@
-#!/usr/bin/env node
-
-import "../envs/defaultEnv.js";
-import express from 'express';
-import cors from 'cors';
-const app = express();
-import yargs from 'yargs';
-import * as timer from '../scheduler/timer.js'
-import { logger } from "../logger.js";
-
-process.on('uncaughtException', (err) => {
-    logger.error('Unhandled Exception:', err);
-});
-
-process.on('unhandledRejection', (err) => {
-    logger.error('Unhandled Rejection:', err);
-});
-
-const port = 3001;
-
-const options = yargs(process.argv.slice(2))
-    .option('c', {
-        alias: 'company',
-        describe: 'Company',
-        type: 'string',
-        demandOption: true
-    })
-    .option('p', {
-        alias: 'port',
-        default: port,
-        describe: 'Port to use',
-        type: 'string',
-        demandOption: false
-    })
-    // .option('m', {
-    //     alias: 'mode',
-    //     describe: 'Fill with "prod" / "dev"',
-    //     type: 'string',
-    //     demandOption: false
-    // })
-    .argv;
-
-
-app.use(cors());
-timer.runScheduler(options.company);
-
-app.listen((options.port || port), () => {
-    logger.info(`Biz-A CLI is listening at ${process.env.HOST || 'http://localhost'}:${options.port || port} `);
-});
-
-// export const MODE = (options.mode == 'prod') ? 'production' : 'development';
+#!/usr/bin/env node
+
+import "../envs/defaultEnv.js";
+import express from 'express';
+import cors from 'cors';
+const app = express();
+import yargs from 'yargs';
+import * as timer from '../scheduler/timer.js'
+import { logger } from "../logger.js";
+import { SERVER_MODES, resolveServerLink } from "../envs/serverEndpoints.js";
+
+process.on('uncaughtException', (err) => {
+    logger.error('Unhandled Exception:', err);
+});
+
+process.on('unhandledRejection', (err) => {
+    logger.error('Unhandled Rejection:', err);
+});
+
+const port = 3001;
+
+const options = yargs(process.argv.slice(2))
+    .option('c', {
+        alias: 'company',
+        describe: 'Company',
+        type: 'string',
+        demandOption: true
+    })
+    .option('p', {
+        alias: 'port',
+        default: port,
+        describe: 'Port to use',
+        type: 'string',
+        demandOption: false
+    })
+    /* Which Biz-A backend to ask for this company's configuration. Without it the scheduler can only
+       ever reach PRODUCTION, because nothing on the config path reads NODE_ENV, so envs/env.dev.js is
+       never consulted — and production currently serves a build with no registry endpoint at all. */
+    .options('serverMode', {
+        alias: 'sMode',
+        describe: `Backend server mode: ${SERVER_MODES.join(', ')}`,
+        type: 'string',
+        choices: SERVER_MODES,
+        default: 'prod'
+    })
+    /*
+     * ⚠️ REFUSE UNKNOWN FLAGS, because the fallback when one is ignored is PRODUCTION. yargs aliases
+     * are case-sensitive, so `--sMod dev` is not `--sMode dev`: without this the unknown key is
+     * silently dropped, serverMode keeps its `prod` default, and the watcher quietly asks a server that
+     * cannot answer — surfacing as the confusing `Cannot POST /config/resolveBySubdomain` 404 this flag
+     * exists to avoid. bin/app.js and bin/hub.js both do this already.
+     */
+    .strict()
+    .argv;
+
+const serverLink = resolveServerLink(options.serverMode);
+
+app.use(cors());
+
+/* Say what is being asked, and of whom, before asking it. This names the CONFIG server only; which API
+   the timers then call is decided by that company's API_URL and is logged from the resolved config
+   below — the two are different addresses and conflating them cost a long debugging detour. */
+logger.info(`Biz-A watcher: company "${options.company}" via ${options.serverMode} -> ${serverLink}`);
+
+/* CATCH THE STARTUP FAILURE. This used to be fire-and-forget, so a legitimate "no such company"
+   surfaced through the unhandledRejection handler as a bare `Unhandled Rejection: { code: 'ENOENT' }`
+   — and app.listen() ran regardless, leaving a process that reported itself listening while no
+   scheduler existed.
+ *
+ * ⚠️ Listen from `onReady`, NOT from .then(): runScheduler's interval loop never resolves, so a
+ * `.then()` here would never fire and the HTTP server would never start. */
+let started = false;
+
+timer
+    .runScheduler(options.company, {
+        serverLink,
+        onReady: (config) => {
+            started = true;
+            /* THE ADDRESS EVERY TIMER AND CLI SCRIPT WILL CALL, taken from this company's API_URL in
+               the configuration document. It is the thing to change when the scheduler is talking to
+               the wrong place, and printing it once is the difference between a bare "502" and
+               "502 from the host I can now go and check". */
+            logger.info(
+                `Resolved config for subdomain "${config?.subdomain}": api=${config?.url} dbindex=${config?.dbindex}`,
+            );
+            app.listen((options.port || port), () => {
+                logger.info(`Biz-A CLI is listening at ${process.env.HOST || 'http://localhost'}:${options.port || port} `);
+            });
+        },
+    })
+    .catch((err) => {
+        /* STARTUP AND RUNTIME FAILURES ARE DIFFERENT THINGS, and `started` is the only way to tell
+           them apart — runScheduler rejects for either. Reporting a timer that died hours in as
+           "cannot start" sends whoever reads the log looking at the wrong thing. */
+        if (!started) {
+            /* ENOENT is an answer, not a crash: the server has no such company. Its message already
+               names the company and the server, so print it plainly. Nothing is listening yet, so the
+               process exits on its own — non-zero, so a supervisor sees it. */
+            logger.error(
+                err?.code === 'ENOENT'
+                    ? `Cannot start the watcher: ${err.message}`
+                    : `Cannot start the watcher (${options.serverMode} -> ${serverLink}): ${err?.message || err}`,
+            );
+        } else {
+            logger.error(`Scheduler stopped after startup: ${err?.message || err}`);
+        }
+        process.exitCode = 1;
+    });

package/engine/bpm/bpmContext.js

@@ -0,0 +1,23 @@
+/*
+ * The verified caller of a BPM engine command — ruling 2026-10-06 (Agung): workflow roles come from user groups.
+ *
+ * Both entrances build it the same way: the socket `engine` command (bin/hubEvent.js, `data.headers`) and the HTTP
+ * `/bpm` routes (engine/bpm/routes.js, `req.headers`). The runtime (workflow-runtime.js callerOf) uses it only for a
+ * call that asks for verified roles (`verifiedRoles: true`, what v2 screens send).
+ *
+ * ⚠️ THE HEADERS, NEVER THE PAYLOAD: the payload is caller-shaped. Everything here comes from inside the signature
+ * (security/internalPrincipal.js principalForCliScript); a missing or forged token is nobody (`principal: null`).
+ * ⚠️ Roles are read TRUSTED (no tenant scope) — SYS$ tables, server-side, for the id the signature names.
+ */
+import { principalForCliScript } from "../../security/internalPrincipal.js";
+import { execPostgres } from "../domain/dialect.js";
+import { runTrusted } from "../orm/tenantContext.js";
+import { resolveBpmRoles } from "./bpmRoles.js";
+
+export const bpmContextFromHeaders = (headers, { mode = "observe", exec = execPostgres } = {}) => {
+	const verified = principalForCliScript(headers ?? {}, { mode });
+	return {
+		principal: verified && verified.userId !== null && verified.userId !== undefined ? { userId: verified.userId, dbIndex: verified.dbIndex } : null,
+		resolveRoles: ({ userId, dbIndex }) => resolveBpmRoles({ exec: (sql, db) => runTrusted(() => exec(sql, db)), dbIndex, userId }),
+	};
+};

package/engine/bpm/bpmRoles.js

@@ -0,0 +1,55 @@
+/*
+ * Which workflow roles a VERIFIED user holds — ruling 2026-10-06 (Agung): map roles to user groups.
+ *
+ * A transition names role codes (SYS$BPM_TRANS_ROLE, e.g. MARKETING); SYS$BPM_ROLE_GROUP maps a role code to the user
+ * groups whose members hold it (edited on the admin User Group form). A company administrator (SYS$ADMINISTRATOR)
+ * holds every role any workflow names, so a company can work before it has mapped anything.
+ *
+ * ⚠️ THE USER ID COMES FROM INSIDE A SIGNATURE (security/internalPrincipal.js), never from the request: the roles a
+ * caller CLAIMED are exactly what this replaces. Same guard as orm/userGroups.js — numeric or nothing.
+ * ⚠️ FAIL-CLOSED: a missing table (a Firebird tenant has none), a bad id, an unreadable row — no role. A role check
+ * that failed open would hand out every approval on a database hiccup.
+ */
+import { logger } from "../../logger.js";
+import { resolveIsAdministrator } from "../orm/userGroups.js";
+
+const numericId = (userId) => {
+	if (userId === null || userId === undefined || userId === "") return null;
+	if (typeof userId === "object" || typeof userId === "boolean") return null;
+	const id = Number(userId);
+	return Number.isInteger(id) && String(userId).trim() === String(id) ? id : null;
+};
+
+export const buildBpmRolesSql = (userId) => {
+	const id = numericId(userId);
+	if (id === null) return null;
+	return (
+		`SELECT DISTINCT r.role_code FROM sys$bpm_role_group r ` +
+		`INNER JOIN sys$ugmember m ON m."sys$usergroup_id" = r."sys$usergroup_id" ` +
+		`WHERE m.user_id = ${id}`
+	);
+};
+const ALL_ROLE_CODES_SQL = "SELECT DISTINCT role_code FROM sys$bpm_trans_role";
+
+const codesOf = (rows) =>
+	(Array.isArray(rows) ? rows : [])
+		.map((row) => String(row?.role_code ?? row?.ROLE_CODE ?? "").trim().toUpperCase())
+		.filter((code) => code.length > 0);
+
+const read = async (exec, sql, dbIndex, what, userId) => {
+	try {
+		return codesOf(await exec(sql, dbIndex));
+	} catch (error) {
+		logger.warn(`[bpm] could not read ${what} for user ${userId}: ${error?.message ?? error}. Treating it as none.`);
+		return [];
+	}
+};
+
+export const resolveBpmRoles = async ({ exec, dbIndex, userId }) => {
+	const sql = buildBpmRolesSql(userId);
+	if (!sql || typeof exec !== "function") return [];
+	const mapped = await read(exec, sql, dbIndex, "workflow roles", userId);
+	const admin = await resolveIsAdministrator({ exec, dbIndex, userId: numericId(userId) });
+	const all = admin ? await read(exec, ALL_ROLE_CODES_SQL, dbIndex, "the workflow role codes", userId) : [];
+	return [...new Set([...mapped, ...all])];
+};

package/engine/bpm/routes.js

@@ -2,13 +2,18 @@ import express from "express";
 import { logger } from "../../logger.js";
 import * as workflow from "./workflow.js";
 import * as workflowRT from "./workflow-runtime.js";
+import { bpmContextFromHeaders } from "./bpmContext.js";
 
 const router = express.Router();
 
 // The Wrapper: Translates HTTP requests into pure Engine payloads
-const expressWrapper = (engineFunction) => async (req, res) => {
+/* `withCaller` (the runtime routes): a third argument, who is asking, from the signed header — what the socket
+   entrance hands the runtime too (bpm/bpmContext.js); used only by a transition that asks for verified roles. */
+const expressWrapper = (engineFunction, withCaller = false) => async (req, res) => {
 	try {
-		const result = await engineFunction(req.body);
+		const result = withCaller
+			? await engineFunction(req.body, undefined, bpmContextFromHeaders(req.headers))
+			: await engineFunction(req.body);
 		res.json({ success: true, data: result });
 	} catch (error) {
 		/* The message goes to the browser, where it is shown as a toast and then lost. An engine
@@ -19,6 +24,8 @@ const expressWrapper = (engineFunction) => async (req, res) => {
 	}
 };
 
+const runtimeWrapper = (engineFunction) => expressWrapper(engineFunction, true);
+
 // ==========================================
 // DESIGN TIME: /workflow/ Prefix
 // ==========================================
@@ -31,38 +38,38 @@ router.post("/workflow/remove", expressWrapper(workflow.remove));
 // ==========================================
 // RUNTIME EXECUTION: /workflowRT/ Prefix
 // ==========================================
-router.post("/workflowRT/initiate", expressWrapper(workflowRT.initiate));
+router.post("/workflowRT/initiate", runtimeWrapper(workflowRT.initiate));
 router.post(
 	"/workflowRT/availableTransitions",
-	expressWrapper(workflowRT.availableTransitions),
+	runtimeWrapper(workflowRT.availableTransitions),
 );
 router.post(
 	"/workflowRT/executeTransition",
-	expressWrapper(workflowRT.executeTransition),
+	runtimeWrapper(workflowRT.executeTransition),
 );
-router.post("/workflowRT/terminate", expressWrapper(workflowRT.terminate));
-router.post("/workflowRT/remove", expressWrapper(workflowRT.remove));
-router.post("/workflowRT/myTasks", expressWrapper(workflowRT.myTasks));
+router.post("/workflowRT/terminate", runtimeWrapper(workflowRT.terminate));
+router.post("/workflowRT/remove", runtimeWrapper(workflowRT.remove));
+router.post("/workflowRT/myTasks", runtimeWrapper(workflowRT.myTasks));
 router.post(
 	"/workflowRT/instanceState",
-	expressWrapper(workflowRT.instanceState),
+	runtimeWrapper(workflowRT.instanceState),
 );
 router.post(
 	"/workflowRT/instanceLogs",
-	expressWrapper(workflowRT.instanceLogs),
+	runtimeWrapper(workflowRT.instanceLogs),
 );
 router.post(
 	"/workflowRT/instanceTasks",
-	expressWrapper(workflowRT.instanceTasks),
+	runtimeWrapper(workflowRT.instanceTasks),
 );
 router.post(
 	"/workflowRT/instanceTimers",
-	expressWrapper(workflowRT.instanceTimers),
+	runtimeWrapper(workflowRT.instanceTimers),
 );
 router.post(
 	"/workflowRT/instanceEffectLogs",
-	expressWrapper(workflowRT.instanceEffectLogs),
+	runtimeWrapper(workflowRT.instanceEffectLogs),
 );
-router.post("/workflowRT/retryEffect", expressWrapper(workflowRT.retryEffect));
+router.post("/workflowRT/retryEffect", runtimeWrapper(workflowRT.retryEffect));
 
 export default router;

package/engine/bpm/stateMirror.js

@@ -0,0 +1,26 @@
+/*
+ * The workflow state, mirrored onto the record of an entity that DECLARES it (entityConfig.buildWorkflowMap).
+ *
+ * Found live 2026-10-06 (studiob "marketing"): a v2 record's state lived only in SYS$BPM_WF_INSTANCE, so its form
+ * and its list could not show it. stateMirror(entityType, entityId, stateCode, dbIndex) is the extra top-level table
+ * the engine adds to the SAME save that moves the instance — { <table>: { id, <stateColumn>: stateCode } } — so the
+ * record and the instance can never disagree. The v1 keyed upsert updates only the columns it is given
+ * (orm/masterDetail.js upsertByKeyCtes). Null when the entity declares nothing: every other workflow is unchanged.
+ *
+ * ⚠️ Keyed by `id` only — the ORM's key convention (masterDetail isPrimaryKey). An entity keyed otherwise would be
+ * INSERTED, not updated, so it is refused with a warning instead.
+ */
+import { workflowOfEntityType } from "../orm/entityConfig.js";
+import { logger } from "../../logger.js";
+
+export const stateMirror = (entityType, entityId, stateCode, dbIndex) => {
+	const workflow = workflowOfEntityType(entityType, dbIndex);
+	if (!workflow || entityId === null || entityId === undefined || entityId === "" || !stateCode) return null;
+	if (workflow.primaryKey !== "id") {
+		logger.warn(`[workflow] ${entityType} is keyed by ${workflow.primaryKey}, not id; its state is not mirrored.`);
+		return null;
+	}
+	const numeric = Number(entityId);
+	const id = Number.isFinite(numeric) && String(numeric) === String(entityId).trim() ? numeric : entityId;
+	return { [workflow.table]: { id, [workflow.stateColumn]: stateCode } };
+};