biz-a-cli 2.3.80-15230 → 2.3.80-15238

package/bin/deployEvent.js

@@ -1,7 +1,7 @@
 import axios from 'axios';
 import { prepareScript, encryptScript } from './script.js';
 import { IDLE_SOCKET_TIMEOUT_MILLISECONDS } from './hubEvent.js';
-import { CLIENT_ROOM } from './directHubEvent.js';
+import { CLIENT_ROOM } from '../message-broker/clientEmitter.js';
 
 export async function getAppData(apiOpts){
     return await axios.request({

package/bin/directHubEvent.js

@@ -2,8 +2,8 @@ import { clientListener, RECONNECT_SOCKET_DELAY } from "./hubEvent.js";
 import { deploymentListenerForVSCode } from "./deployEvent.js";
 import { Tunnel as QuickTunnel } from "cloudflared";
 import { Server as ioServer } from "socket.io";
-
-export const CLIENT_ROOM = "clientRoom";
+import { CLIENT_ROOM } from "../message-broker/clientEmitter.js";
+import { ClientEmitter } from "../message-broker/clientEmitter.js";
 
 export async function localhostTunnel(port, notifier) {
 	let tunnelUrl = "";
@@ -69,6 +69,16 @@ export function directHubEvent(serverSocket, argv) {
 			setConnectListeners(clientSocket);
 			clientListener(clientSocket, argv);
 			clientSocket.join(CLIENT_ROOM);
+
+			// for ESB clientEmitter
+			const clientInstanceId =
+				clientSocket.handshake.query.clientInstanceId;
+			if (clientInstanceId) {
+				clientSocket.join(clientInstanceId);
+				clientSocket.on("ESB_ACK", (msgId) => {
+					ClientEmitter.acknowledgeMessage(msgId, clientInstanceId);
+				});
+			}
 		} else if (clientSocket.handshake.query.isDeploy) {
 			setConnectListeners(clientSocket);
 			deploymentListenerForVSCode(clientSocket, argv);
@@ -89,7 +99,7 @@ export function createSocketServer(httpServer, cliIpAddress = "127.0.0.1") {
 				/\.vscode-cdn\.net$/,
 			].concat(
 				process.env.NODE_ENV === "production"
-					? []
+					? [`http://${cliIpAddress}:4200`, "http://localhost:4200", "http://localhost"]
 					: [`http://${cliIpAddress}:4200`, "http://localhost:4200"],
 			),
 		},

package/bin/hub.js

@@ -24,6 +24,7 @@ import { setGlobalConfig } from "../db/ds.js";
 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";
 
 const logger = createLogger({
 	level: "info",
@@ -294,6 +295,8 @@ if (argv.mode.trim().toLowerCase() === "agent") {
 	// directHubEvent(createSocketServer(server, argv.cliAddress().ip), argv);
 	directHubEvent(ioServerInstance, argv);
 
+	ClientEmitter.init(ioServerInstance, socket);
+
 	bootMicroservices(argv, ioServerInstance);
 
 	if (argv.publish == true) {

package/bin/hubEvent.js

@@ -10,6 +10,7 @@ const packageJson = require("../package.json");
 // import { pipeline } from 'node:stream'
 import { deploymentListenerForHubServer } from "./deployEvent.js";
 import { execCLIScriptWorker, workerStats } from "../worker/cliWorkerPool.js";
+import { ClientEmitter } from "../message-broker/clientEmitter.js";
 
 export const IDLE_SOCKET_TIMEOUT_MILLISECONDS = 1000 * 28;
 export const RECONNECT_SOCKET_DELAY = 60 * 1000;
@@ -227,6 +228,12 @@ export const hubEvent = (socket, argv, notifier) => {
 	});
 	clientListener(socket, argv);
 	deploymentListenerForHubServer(socket, argv);
+
+	// ESB client emitter. Catch the forwarded ACK from the Hub Server
+	socket.on("ESB_ACK", ({ msgId, clientInstanceId }) => {
+		ClientEmitter.acknowledgeMessage(msgId, clientInstanceId);
+	});
+
 	return socket;
 };
 

package/db/db.js

@@ -17,7 +17,11 @@ export const save = async (payload, config = {}) => {
 	return await adapter.save(payload, config);
 };
 
-export const deleteMD = async (id, masterTable, detailTables, config = {}) => {
+export const remove = async (payload, config = {}) => {
+	return await adapter.remove(payload, config);
+};
+
+export const removeMD = async (id, masterTable, detailTables, config = {}) => {
 	const payload = {
 		id: id,
 		master: masterTable,
@@ -26,10 +30,6 @@ export const deleteMD = async (id, masterTable, detailTables, config = {}) => {
 	return await adapter.removeMD(payload, config);
 };
 
-export const remove = async (payload, config = {}) => {
-	return await adapter.remove(payload, config);
-};
-
 export const list = async (payload, config = {}) => {
 	return await adapter.list(payload, config);
 };
@@ -37,3 +37,7 @@ export const list = async (payload, config = {}) => {
 export const executeBlock = async (sqlString, config = {}) => {
 	return await adapter.executeBlock(sqlString, config);
 };
+
+export const ormGet = async (payload, config = {}) => {
+	return await adapter.ormGet(payload, config);
+};

package/db/ds.js

@@ -269,3 +269,17 @@ export const executeBlock = async (sqlString, config = {}) => {
 	const data = buildDataSnapPayload(cfg, "block", flatSql);
 	return await dsReq(url, data, cfg.timeout);
 };
+
+export const ormGet = async (payload, config = {}) => {
+	const cfg = resolveConfig(config);
+	const url = buildDataSnapUrl(cfg, "orm");
+	const data = buildDataSnapPayload(cfg, "get", payload);
+
+	const res = await dsReq(url, data, cfg.timeout);
+
+	if (res && res.data) {
+		return typeof res.data === "string" ? JSON.parse(res.data) : res.data;
+	}
+
+	return res;
+};

package/engine/bpm/workflow-runtime.js

@@ -1,12 +1,14 @@
 import {
 	queryData,
 	save as dbSave,
-	deleteMD,
+	removeMD,
 	getGlobalConfig,
+	ormGet,
 } from "../../db/db.js";
 import vm from "node:vm";
 import { execCLIScriptWorker } from "../../worker/cliWorkerPool.js";
 import axios from "axios";
+import { ClientEmitter } from "../../message-broker/clientEmitter.js";
 
 // ================
 // INTERNAL HELPERS
@@ -98,6 +100,42 @@ async function evaluateGuardRule(guardType, guardRuleKey, entityData) {
 	}
 }
 
+async function processInstanceUpsertResult(
+	requesterPayload,
+	apiConfig,
+	result,
+	fallbackId,
+) {
+	if (result && result.success == "OK") {
+		try {
+			const savedId = result.data?.[0]?.ID || fallbackId;
+			if (savedId) {
+				const newRecord = await ormGet(
+					{
+						SYS$BPM_WF_INSTANCE: {
+							ID: savedId,
+							"*": "",
+						},
+					},
+					apiConfig,
+				);
+
+				ClientEmitter.broadcastClient(
+					"SYS$BPM_WF_INSTANCE_UPSERT",
+					newRecord,
+				);
+
+				ClientEmitter.notifyRequester(requesterPayload, newRecord);
+			}
+		} catch (esbError) {
+			console.error(
+				"[ESB Error] Failed to broadcast instance upsert :",
+				esbError,
+			);
+		}
+	}
+}
+
 // ===============
 // ENGINE ENDPOINT
 // ===============
@@ -246,6 +284,9 @@ export async function initiate(payload) {
 		{ SYS$BPM_WF_INSTANCE: instanceModel },
 		apiConfig,
 	);
+
+	await processInstanceUpsertResult(payload, apiConfig, result, null);
+
 	return result.data;
 }
 
@@ -389,6 +430,7 @@ export async function executeTransition(payload) {
 		entityData = {},
 		apiConfig,
 		userId,
+		effectData = {},
 	} = payload;
 
 	const instParam = {
@@ -614,19 +656,49 @@ export async function executeTransition(payload) {
 	};
 
 	if (effects && effects.length > 0) {
-		transitionPayload.SYS$BPM_EFFECT_LOG = effects.map((eff) => ({
-			id: null,
-			sys$bpm_wf_instance_id: Number(instanceId),
-			sys$bpm_trans_def_id: transition.id,
-			effect_type: eff.effect_type,
-			event_name: eff.event_name,
-			payload_evaluated: eff.payload_template || null,
-			status: "PENDING",
-			retry_count: 0,
-		}));
+		transitionPayload.SYS$BPM_EFFECT_LOG = effects.map((eff) => {
+			let mergedPayload = {};
+
+			// 1. Parse the static template from the Workflow Definition
+			if (eff.payload_template) {
+				try {
+					mergedPayload = JSON.parse(eff.payload_template);
+				} catch (e) {}
+			}
+
+			// 2. Merge the dynamic context injected by the Biz-A Client (e.g., clientInstanceId)
+			if (effectData && Object.keys(effectData).length > 0) {
+				mergedPayload = { ...mergedPayload, ...effectData };
+			}
+
+			// 3. Stringify the result, or fall back to null if completely empty
+			const finalPayloadString =
+				Object.keys(mergedPayload).length > 0
+					? JSON.stringify(mergedPayload)
+					: null;
+
+			return {
+				id: null,
+				sys$bpm_wf_instance_id: Number(instanceId),
+				sys$bpm_trans_def_id: transition.id,
+				effect_type: eff.effect_type,
+				event_name: eff.event_name,
+				payload_evaluated: finalPayloadString || null,
+				status: "PENDING",
+				retry_count: 0,
+			};
+		});
 	}
 
 	const result = await dbSave(transitionPayload, apiConfig);
+
+	await processInstanceUpsertResult(
+		payload,
+		apiConfig,
+		result,
+		Number(instanceId),
+	);
+
 	return result.data;
 }
 
@@ -723,6 +795,14 @@ export async function terminate(payload) {
 	};
 
 	const result = await dbSave(ormPayload, apiConfig);
+
+	await processInstanceUpsertResult(
+		payload,
+		apiConfig,
+		result,
+		Number(instanceId),
+	);
+
 	return result.data;
 }
 
@@ -735,13 +815,27 @@ export async function remove(payload) {
 		"SYS$BPM_EFFECT_LOG",
 	];
 
-	const result = await deleteMD(
+	const result = await removeMD(
 		Number(instanceId),
 		"SYS$BPM_WF_INSTANCE",
 		detailTables,
 		apiConfig,
 	);
-	return result.data;
+
+	if (result && result.success == "OK") {
+		try {
+			const data = [{ ID: instanceId }];
+			ClientEmitter.broadcastClient("SYS$BPM_WF_INSTANCE_REMOVE", data);
+			ClientEmitter.notifyRequester(payload, data);
+		} catch (esbError) {
+			console.error(
+				"[ESB Error] Failed to broadcast instance deletion:",
+				esbError,
+			);
+		}
+	}
+
+	return result;
 }
 
 export async function myTasks(payload) {
@@ -1233,7 +1327,9 @@ export async function executeEffect(effectData) {
 			// instance when the effect carries no payloadTemplate.
 			const scriptData = Object.assign(
 				{},
-				parsedPayload && typeof parsedPayload === "object" && !Array.isArray(parsedPayload)
+				parsedPayload &&
+					typeof parsedPayload === "object" &&
+					!Array.isArray(parsedPayload)
 					? parsedPayload
 					: {},
 				{
@@ -1242,10 +1338,17 @@ export async function executeEffect(effectData) {
 						effectData.SYS$BPM_WF_INSTANCE_ID,
 				},
 			);
+
 			const scriptResult = await execCLIScriptWorker(
 				apiConfig,
 				eventName,
-				scriptData,
+				// scriptData,
+				{
+					// to be same format as callback, live trigger and watcher, script data must be inside "body"
+					body: scriptData,
+					// You can even add mock headers if future scripts expect them
+					headers: { "user-agent": "biz-a-bpm-engine" },
+				},
 			);
 
 			// --- if cliScript of Effect need to run executeTransition ---

package/engine/bpm/workflow.js

@@ -1,4 +1,36 @@
-import { save as dbSave, queryData, deleteMD } from "../../db/db.js";
+import { save as dbSave, queryData, removeMD, ormGet } from "../../db/db.js";
+import { ClientEmitter } from "../../message-broker/clientEmitter.js";
+
+async function processUpsertResult(requesterPayload, apiConfig, result) {
+	if (result.success == "OK") {
+		try {
+			const savedId = result.data[0]?.ID || id;
+			if (savedId) {
+				const newRecord = await ormGet(
+					{
+						SYS$BPM_WORKFLOW_DEF: {
+							ID: savedId,
+							"*": "",
+						},
+					},
+					apiConfig,
+				);
+
+				ClientEmitter.broadcastClient(
+					"SYS$BPM_WORKFLOW_DEF_UPSERT",
+					newRecord,
+				);
+
+				ClientEmitter.notifyRequester(requesterPayload, newRecord);
+			}
+		} catch (esbError) {
+			console.error(
+				"[ESB Error] Failed to broadcast workflow upsert :",
+				esbError,
+			);
+		}
+	}
+}
 
 export async function save(payload) {
 	const { id, rawJsonString, apiConfig, userId } = payload;
@@ -48,6 +80,9 @@ export async function save(payload) {
 		},
 		apiConfig,
 	);
+
+	await processUpsertResult(payload, apiConfig, result);
+
 	return result.data;
 }
 
@@ -175,6 +210,9 @@ export async function publish(payload) {
 		{ SYS$BPM_WORKFLOW_DEF: workflowModel },
 		apiConfig,
 	);
+
+	await processUpsertResult(payload, apiConfig, result);
+
 	return result.data;
 }
 
@@ -221,12 +259,25 @@ export async function remove(payload) {
 		},
 	];
 
-	const result = await deleteMD(
+	const result = await removeMD(
 		Number(id),
 		"SYS$BPM_WORKFLOW_DEF",
 		detailTables,
 		apiConfig,
 	);
 
-	return result.data;
+	if (result.success == "OK") {
+		try {
+			const data = [{ ID: id }];
+			ClientEmitter.broadcastClient("SYS$BPM_WORKFLOW_DEF_REMOVE", data);
+			ClientEmitter.notifyRequester(payload, data);
+		} catch (esbError) {
+			console.error(
+				"[ESB Error] Failed to broadcast workflow deletion:",
+				esbError,
+			);
+		}
+	}
+
+	return result;
 }

package/engine/domain/appConfig.js

@@ -852,6 +852,93 @@ export const buildTableSyncPlan = (expected, actual, options) => {
 	};
 };
 
+const normalizeScopedDropIdentifier = (value, label) => {
+	const identifier = String(value ?? "").trim().toUpperCase();
+	if (!identifier || identifier.length > 31 || !/^[A-Z_][A-Z0-9_$]*$/.test(identifier)) {
+		throw new Error(`${label} contains an invalid Firebird identifier.`);
+	}
+	return identifier;
+};
+
+const collectionUsesColumn = (item, columnName) =>
+	(item?.columns ?? []).some((column) => String(column ?? "").trim().toUpperCase() === columnName);
+
+const checkUsesColumn = (check, columnName) => {
+	if (collectionUsesColumn(check, columnName)) return true;
+	return new RegExp(`(^|[^A-Z0-9_$])${columnName}([^A-Z0-9_$]|$)`).test(String(check?.expression ?? "").toUpperCase());
+};
+
+const validateProtectedMasterDataColumn = (actual, tableName, columnName) => {
+	if (["ID", "SUSPEND"].includes(columnName)) {
+		throw new Error(`Column "${columnName}" is protected and cannot be dropped from ${tableName}.`);
+	}
+	const primaryKey = new Set(
+		(actual?.primaryKey ?? []).map((column) => String(column ?? "").trim().toUpperCase()),
+	);
+	if (primaryKey.has(columnName)) {
+		throw new Error(`Column "${columnName}" is part of the primary key in ${tableName}.`);
+	}
+};
+
+const getIncomingMasterDataReferences = (actual, columnName) => (actual?.incomingForeignKeys ?? []).filter((foreignKey) =>
+	(foreignKey?.referenceColumns ?? []).some((column) => String(column ?? "").trim().toUpperCase() === columnName));
+
+export const buildMasterDataColumnDropPlan = (actual, requestedColumnNames) => {
+	const tableName = normalizeScopedDropIdentifier(actual?.tableName, "Table name");
+	const requestedColumns = [...new Set((requestedColumnNames ?? []).map((name) => normalizeScopedDropIdentifier(name, "Column name")))];
+	const actualColumns = new Set(
+		(actual?.columns ?? []).map((column) => String(column?.name ?? "").trim().toUpperCase()),
+	);
+	const statements = [];
+	const droppedColumns = [];
+	const alreadyMissingColumns = [];
+	for (const columnName of requestedColumns) {
+		validateProtectedMasterDataColumn(actual, tableName, columnName);
+		if (!actualColumns.has(columnName)) {
+			alreadyMissingColumns.push(columnName);
+			continue;
+		}
+
+		const incoming = getIncomingMasterDataReferences(actual, columnName);
+		if (incoming.length > 0) {
+			const names = incoming.map((item) => item.name).filter(Boolean).join(", ");
+			throw new Error(`Column "${columnName}" in ${tableName} is referenced by incoming foreign key ${names}.`);
+		}
+
+		const foreignKeys = (actual?.foreignKeys ?? []).filter((item) => collectionUsesColumn(item, columnName));
+		const checks = (actual?.checks ?? []).filter((item) => checkUsesColumn(item, columnName));
+		const uniqueKeys = (actual?.uniqueKeys ?? []).filter((item) => collectionUsesColumn(item, columnName));
+		const indexes = (actual?.indexes ?? []).filter((item) => collectionUsesColumn(item, columnName));
+		const removableNames = new Set(
+			[...foreignKeys, ...checks, ...uniqueKeys, ...indexes]
+				.flatMap((item) => [item?.name, item?.triggerName])
+				.map((name) => String(name ?? "").trim().toUpperCase())
+				.filter(Boolean),
+		);
+		const blockers = (actual?.columnDependencies ?? []).filter(
+			(dependency) =>
+				String(dependency?.columnName ?? "").trim().toUpperCase() === columnName &&
+				!removableNames.has(String(dependency?.dependentName ?? "").trim().toUpperCase()),
+		);
+		if (blockers.length > 0) {
+			const names = blockers.map((item) => item.dependentName).filter(Boolean).join(", ");
+			throw new Error(`Column "${columnName}" in ${tableName} has dependent database objects: ${names}.`);
+		}
+
+		foreignKeys.forEach((item) => statements.push(`ALTER TABLE ${tableName} DROP CONSTRAINT ${item.name};`));
+		checks.forEach((item) => statements.push(`ALTER TABLE ${tableName} DROP CONSTRAINT ${item.name};`));
+		uniqueKeys.forEach((item) => statements.push(`ALTER TABLE ${tableName} DROP CONSTRAINT ${item.name};`));
+		indexes.forEach((item) => statements.push(`DROP INDEX ${item.name};`));
+		statements.push(`ALTER TABLE ${tableName} DROP ${columnName};`);
+		droppedColumns.push(columnName);
+	}
+	return {
+		statements: [...new Set(statements.map((statement) => toSingleLine(statement)))],
+		droppedColumns,
+		alreadyMissingColumns,
+	};
+};
+
 export const buildGeneratorStructureQueries = (table) => {
 	const generatorName = toDbName(table.generatorName ?? buildObjectName(table.name, "GEN"));
 	const triggerName = toDbName(table.triggerName ?? buildObjectName(table.name, "BI"));
@@ -2218,6 +2305,46 @@ export const resolveConfigFromPayload = (payload = {}, argv = {}) => {
 	};
 };
 
+export const dropMasterDataColumns = async (payload = {}, argv = {}) => {
+	try {
+		const tableName = normalizeScopedDropIdentifier(payload?.tableName, "Table name");
+		const columnNames = Array.isArray(payload?.columnNames) ? payload.columnNames : [];
+		if (columnNames.length === 0) {
+			return { success: true, tableName, droppedColumns: [], alreadyMissingColumns: [] };
+		}
+
+		const config = resolveConfigFromPayload(payload, argv);
+		const dbIndex = resolveExecutionDbIndex(payload?.dbIndex, config);
+		const normalizedColumns = [
+			...new Set(columnNames.map((name) => normalizeScopedDropIdentifier(name, "Column name"))),
+		];
+		const exists = await loadTableExists(tableName, dbIndex, config);
+		if (!exists) {
+			return {
+				success: true,
+				tableName,
+				droppedColumns: [],
+				alreadyMissingColumns: normalizedColumns,
+			};
+		}
+
+		const snapshot = await loadTableSnapshot(tableName, true, dbIndex, config);
+		const plan = buildMasterDataColumnDropPlan(snapshot, normalizedColumns);
+		await executeSqlStatements(plan.statements, dbIndex, config, {
+			dryRun: false,
+			executedBlockSignatures: new Set(),
+		});
+		return {
+			success: true,
+			tableName,
+			droppedColumns: plan.droppedColumns,
+			alreadyMissingColumns: plan.alreadyMissingColumns,
+		};
+	} catch (error) {
+		return { success: false, error: error?.message ?? String(error) };
+	}
+};
+
 export const buildPublishStatusConfigKey = (domainName, domainVersion) => ({
 	name: `${domainName}__PUBLISH_STATUS`,
 	version: domainVersion,

package/engine/domain/firebird-ddl.js

@@ -77,6 +77,7 @@ export const buildTableStructureQueries = (tableName) => {
 		checkConstraintsSql: [
 			'SELECT',
 			'  TRIM(rc.RDB$CONSTRAINT_NAME) AS CONSTRAINT_NAME,',
+			'  TRIM(cc.RDB$TRIGGER_NAME) AS TRIGGER_NAME,',
 			'  TRIM(CAST(t.RDB$TRIGGER_SOURCE AS VARCHAR(4096))) AS CHECK_SOURCE',
 			'FROM RDB$RELATION_CONSTRAINTS rc',
 			'JOIN RDB$CHECK_CONSTRAINTS cc ON cc.RDB$CONSTRAINT_NAME = rc.RDB$CONSTRAINT_NAME',
@@ -832,6 +833,7 @@ const groupCheckConstraints = (rows) => {
 	return (rows ?? [])
 		.map((row) => ({
 			name: toUpperText(row['CONSTRAINT_NAME'] ?? row['constraint_name']),
+			triggerName: toUpperText(row['TRIGGER_NAME'] ?? row['trigger_name']),
 			expression: normalizeExpression(
 				row['CHECK_SOURCE'] ??
 					row['check_source'] ??

package/message-broker/clientEmitter.js

@@ -0,0 +1,171 @@
+import crypto from "node:crypto";
+import { createLogger, transports, format } from "winston";
+
+export const CLIENT_ROOM = "clientRoom";
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 10000; // 10 seconds
+
+// 1. STRICT DLQ SCHEMA (Ready for DB imports later)
+const dlqLogger = createLogger({
+	level: "error",
+	format: format.combine(format.timestamp(), format.json()),
+	transports: [new transports.File({ filename: "log/dlq.log" })],
+});
+
+class ClientEmitterService {
+	constructor() {
+		this.ioServerInstance = null;
+		this.hubSocket = null;
+
+		// Map<clientInstanceId, Map<msgId, PendingData>>
+		this.clientQueues = new Map();
+	}
+
+	init(ioServerInstance, hubSocket) {
+		this.ioServerInstance = ioServerInstance;
+		this.hubSocket = hubSocket;
+	}
+
+	/**
+	 * Process the incoming ESB_ACK from the Angular Client
+	 * PRUNE OLDER PENDING EVENTS
+	 * Since we just received an ACK for this event, any older event in this queue is now officially a phantom/stale."
+	 */
+	acknowledgeMessage(msgId, clientInstanceId) {
+		const queue = this.clientQueues.get(clientInstanceId);
+		if (queue && queue.has(msgId)) {
+			const ackedEvent = queue.get(msgId);
+
+			for (const [id, pending] of queue.entries()) {
+				if (pending.timestamp <= ackedEvent.timestamp) {
+					clearTimeout(pending.timer);
+					queue.delete(id);
+				}
+			}
+
+			if (queue.size === 0) this.clientQueues.delete(clientInstanceId); // Memory cleanup
+		}
+	}
+
+	/**
+	 * TARGETED EMIT: Blasts to a specific client with Superseding Logic
+	 */
+	emitClient(clientInstanceId, eventName, payload, attempt = 1) {
+		const msgId = attempt === 1 ? crypto.randomUUID() : payload.msgId;
+		const creationTime = attempt === 1 ? Date.now() : payload.timestamp;
+
+		const wrappedPayload =
+			attempt === 1
+				? { msgId: msgId, timestamp: creationTime, data: payload }
+				: payload;
+
+		if (!this.clientQueues.has(clientInstanceId)) {
+			this.clientQueues.set(clientInstanceId, new Map());
+		}
+		const queue = this.clientQueues.get(clientInstanceId);
+
+		if (attempt === 1) {
+			// Supersede Logic: Kill older phantom retries of the exact same event type
+			for (const [existingMsgId, pending] of queue.entries()) {
+				if (
+					pending.eventName === eventName &&
+					pending.timestamp < creationTime
+				) {
+					console.log(
+						`[ESB] Superseding older '${eventName}' event for ${clientInstanceId}`,
+					);
+					clearTimeout(pending.timer);
+					queue.delete(existingMsgId);
+				}
+			}
+		}
+
+		// SETUP THE RETRY TIMER
+		const timer = setTimeout(() => {
+			if (queue.has(msgId)) {
+				if (attempt <= MAX_RETRIES) {
+					console.log(
+						`[ESB] Retry ${attempt}/${MAX_RETRIES} for event '${eventName}' to ${clientInstanceId}`,
+					);
+					this.emitClient(
+						clientInstanceId,
+						eventName,
+						wrappedPayload,
+						attempt + 1,
+					);
+				} else {
+					// DLQ RECORD FORMAT
+					const dlqRecord = {
+						msgId: msgId,
+						clientInstanceId: clientInstanceId,
+						eventName: eventName,
+						createdAt: creationTime,
+						failedAt: Date.now(),
+						retryCount: MAX_RETRIES,
+						payload: wrappedPayload.data,
+					};
+
+					dlqLogger.error("ESB_DELIVERY_FAILURE", dlqRecord);
+
+					queue.delete(msgId);
+					if (queue.size === 0)
+						this.clientQueues.delete(clientInstanceId);
+				}
+			}
+		}, RETRY_DELAY_MS);
+
+		// Register the expectation and payload explicitly
+		queue.set(msgId, {
+			timer,
+			eventName,
+			timestamp: creationTime,
+			payload: wrappedPayload,
+		});
+
+		// FIRE TO THE DUAL CHANNELS
+		if (this.ioServerInstance) {
+			this.ioServerInstance
+				.to(clientInstanceId)
+				.emit(eventName, wrappedPayload);
+		}
+
+		if (this.hubSocket && this.hubSocket.connected) {
+			this.hubSocket.emit("emitToClient", {
+				clientInstanceId,
+				eventName,
+				payload: wrappedPayload,
+			});
+		}
+	}
+
+	broadcastClient(eventName, payload) {
+		const wrappedPayload = {
+			msgId: crypto.randomUUID(),
+			timestamp: Date.now(),
+			data: payload,
+		};
+
+		if (this.ioServerInstance)
+			this.ioServerInstance
+				.to(CLIENT_ROOM)
+				.emit(eventName, wrappedPayload);
+		if (this.hubSocket && this.hubSocket.connected) {
+			this.hubSocket.emit("broadcastToClient", {
+				eventName,
+				payload: wrappedPayload,
+			});
+		}
+	}
+
+	/**
+	 * Standardized Acknowledgment Emit
+	 * Automatically checks if the frontend requested a targeted response.
+	 */
+	notifyRequester(payload, data) {
+		if (payload && payload.clientInstanceId && payload.eventName) {
+			this.emitClient(payload.clientInstanceId, payload.eventName, data);
+		}
+	}
+}
+
+export const ClientEmitter = new ClientEmitterService();

package/message-broker/dispatcher.js

@@ -1,5 +1,6 @@
 import { EventEmitter } from "node:events";
 import { workerEvents } from "../worker/cliWorkerPool.js";
+import { ClientEmitter } from "./clientEmitter.js";
 
 export class CLI_Dispatcher {
 	constructor(mode, ioServerInstance = null) {
@@ -52,31 +53,25 @@ export class CLI_Dispatcher {
 			});
 		}
 
-		workerEvents.on("IPC_RELAY", (topic, payload) => {
-			this.balanceAndDispatchEvent(topic, payload);
+		workerEvents.on("IPC_RELAY", (topic, data) => {
+			this.balanceAndDispatchEvent(topic, data);
 		});
 	}
 
 	balanceAndDispatchEvent(topic, payload) {
 		// --- EMIT TO SPECIFIC BIZ-A CLIENT ---
-		// ex: this.lib.emitClient(scriptData.clientSockId, scriptData.eventUUIDName, { status: "Done!" });
+		// ex: this.lib.emitClient(scriptData.clientInstanceId, scriptData.eventName, { status: "Done!" });
 		if (topic === "emitClient") {
-			console.log(
-				`\n[Future Dev] Target: Biz-A Client Socket ID [${payload?.clientSockId}]`,
-			);
-			console.log(`[Future Dev] Event: ${payload?.eventUUIDName}`);
-			console.log(`[Future Dev] Payload:`, payload?.payload, `\n`);
-			// TODO: this.agentNamespace.to(payload.clientSockId).emit(payload.eventUUIDName, payload.payload);
+			const { clientInstanceId, eventName, data } = payload;
+			ClientEmitter.emitClient(clientInstanceId, eventName, data);
 			return;
 		}
 
 		// --- EMIT TO ALL BIZ-A CLIENT ---
 		// ex: this.lib.broadcastClient("ui:alert", { message: "System maintenance in 5 mins" });
 		if (topic === "broadcastClient") {
-			console.log(`\n[Future Dev] Broadcast: ALL Clients in CLIENT_ROOM`);
-			console.log(`[Future Dev] Event: ${payload?.topic}`);
-			console.log(`[Future Dev] Payload:`, payload?.payload, `\n`);
-			// TODO: this.agentNamespace.to("clientRoom").emit(payload.topic, payload.payload);
+			const { eventName, data } = payload;
+			ClientEmitter.broadcastClient(eventName, data);
 			return;
 		}
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "biz-a-cli",
-	"version": "2.3.80-15230",
+	"version": "2.3.80-15238",
 	"description": "",
 	"main": "bin/index.js",
 	"type": "module",

package/worker/cliScriptWorker.js

@@ -71,20 +71,20 @@ export const run = async (apiConfig, scriptIdentifier, scriptData) => {
 		};
 
 		// 2. Targeted Client UI Update
-		lib.emitClient = (clientSockId, eventUUIDName, payload) => {
+		lib.emitClient = (clientInstanceId, eventName, data) => {
 			workerpool.workerEmit({
 				type: "IPC_RELAY",
 				topic: "emitClient",
-				payload: { clientSockId, eventUUIDName, payload },
+				payload: { clientInstanceId, eventName, data },
 			});
 		};
 
 		// 3. Broadcast Client UI Update
-		lib.broadcastClient = (topic, payload) => {
+		lib.broadcastClient = (eventName, data) => {
 			workerpool.workerEmit({
 				type: "IPC_RELAY",
 				topic: "broadcastClient",
-				payload: { topic, payload },
+				payload: { eventName, data },
 			});
 		};
 	};
@@ -100,12 +100,15 @@ export const run = async (apiConfig, scriptIdentifier, scriptData) => {
 				db.save(payload, mergeConfig(customCfg)),
 			remove: (payload, customCfg) =>
 				db.remove(payload, mergeConfig(customCfg)),
-			deleteMD: (id, master, details, customCfg) =>
-				db.deleteMD(id, master, details, mergeConfig(customCfg)),
+			removeMD: (id, master, details, customCfg) =>
+				db.removeMD(id, master, details, mergeConfig(customCfg)),
 			list: (payload, customCfg) =>
 				db.list(payload, mergeConfig(customCfg)),
 			executeBlock: (sql, customCfg) =>
 				db.executeBlock(sql, mergeConfig(customCfg)),
+			ormGet: (payload, customCfg) =>
+				db.ormGet(payload, mergeConfig(customCfg)),
+			getGlobalConfig: () => db.getGlobalConfig(),
 		};
 	};