@hotmeshio/hotmesh 0.14.1 → 0.14.3

package/build/services/pipe/functions/symbol.d.ts

@@ -1,12 +1,124 @@
+/**
+ * Provides methods for returning common symbolic values and objects,
+ * such as `null`, `undefined`, `whitespace`, `object`, `array`, and `date`.
+ * These methods can be used in a variety of contexts where it is necessary
+ * to represent these values or objects programmatically.
+ *
+ * @remarks
+ * Invoked in mapping rules using `{@symbol.<method>}` syntax.
+ * Symbol methods take no parameters; they are called directly
+ * in the `@pipe` structure.
+ */
 declare class SymbolHandler {
+    /**
+     * Returns the value `null`, representing a deliberate non-value.
+     *
+     * @returns {null} The null value
+     * @example
+     * ```yaml
+     * set_null:
+     *   "@pipe":
+     *     - ["{@symbol.null}"]
+     * ```
+     */
     null(): null;
+    /**
+     * Returns the value `undefined`, representing a variable
+     * that has not been assigned a value.
+     *
+     * @returns {undefined} The undefined value
+     * @example
+     * ```yaml
+     * set_undefined:
+     *   "@pipe":
+     *     - ["{@symbol.undefined}"]
+     * ```
+     */
     undefined(): undefined;
+    /**
+     * Returns a single whitespace character as a string.
+     *
+     * @returns {string} A single space character
+     * @example
+     * ```yaml
+     * set_whitespace:
+     *   "@pipe":
+     *     - ["{@symbol.whitespace}"]
+     * ```
+     */
     whitespace(): string;
+    /**
+     * Returns an empty object (`{}`).
+     *
+     * @returns {object} An empty object
+     * @example
+     * ```yaml
+     * set_object:
+     *   "@pipe":
+     *     - ["{@symbol.object}"]
+     * ```
+     */
     object(): object;
+    /**
+     * Returns an empty array (`[]`).
+     *
+     * @returns {any[]} An empty array
+     * @example
+     * ```yaml
+     * set_array:
+     *   "@pipe":
+     *     - ["{@symbol.array}"]
+     * ```
+     */
     array(): any[];
+    /**
+     * Returns the positive infinity value (`Infinity`).
+     *
+     * @returns {number} Positive infinity
+     * @example
+     * ```yaml
+     * set_pos_infinity:
+     *   "@pipe":
+     *     - ["{@symbol.posInfinity}"]
+     * ```
+     */
     posInfinity(): number;
+    /**
+     * Returns the negative infinity value (`-Infinity`).
+     *
+     * @returns {number} Negative infinity
+     * @example
+     * ```yaml
+     * set_neg_infinity:
+     *   "@pipe":
+     *     - ["{@symbol.negInfinity}"]
+     * ```
+     */
     negInfinity(): number;
+    /**
+     * Returns the not-a-number value (`NaN`).
+     *
+     * @returns {number} NaN
+     * @example
+     * ```yaml
+     * set_nan:
+     *   "@pipe":
+     *     - ["{@symbol.NaN}"]
+     * ```
+     */
     NaN(): number;
+    /**
+     * Returns the current date and time as a Date object.
+     *
+     * @returns {Date} The current date and time
+     * @example
+     * ```yaml
+     * set_date:
+     *   "@pipe":
+     *     - ["{@symbol.date}"]
+     *     - ["{@json.stringify}"]
+     * ```
+     */
     date(): Date;
 }
 export { SymbolHandler };

package/build/services/pipe/functions/symbol.js

@@ -1,31 +1,143 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SymbolHandler = void 0;
+/**
+ * Provides methods for returning common symbolic values and objects,
+ * such as `null`, `undefined`, `whitespace`, `object`, `array`, and `date`.
+ * These methods can be used in a variety of contexts where it is necessary
+ * to represent these values or objects programmatically.
+ *
+ * @remarks
+ * Invoked in mapping rules using `{@symbol.<method>}` syntax.
+ * Symbol methods take no parameters; they are called directly
+ * in the `@pipe` structure.
+ */
 class SymbolHandler {
+    /**
+     * Returns the value `null`, representing a deliberate non-value.
+     *
+     * @returns {null} The null value
+     * @example
+     * ```yaml
+     * set_null:
+     *   "@pipe":
+     *     - ["{@symbol.null}"]
+     * ```
+     */
     null() {
         return null;
     }
+    /**
+     * Returns the value `undefined`, representing a variable
+     * that has not been assigned a value.
+     *
+     * @returns {undefined} The undefined value
+     * @example
+     * ```yaml
+     * set_undefined:
+     *   "@pipe":
+     *     - ["{@symbol.undefined}"]
+     * ```
+     */
     undefined() {
         return undefined;
     }
+    /**
+     * Returns a single whitespace character as a string.
+     *
+     * @returns {string} A single space character
+     * @example
+     * ```yaml
+     * set_whitespace:
+     *   "@pipe":
+     *     - ["{@symbol.whitespace}"]
+     * ```
+     */
     whitespace() {
         return ' ';
     }
+    /**
+     * Returns an empty object (`{}`).
+     *
+     * @returns {object} An empty object
+     * @example
+     * ```yaml
+     * set_object:
+     *   "@pipe":
+     *     - ["{@symbol.object}"]
+     * ```
+     */
     object() {
         return {};
     }
+    /**
+     * Returns an empty array (`[]`).
+     *
+     * @returns {any[]} An empty array
+     * @example
+     * ```yaml
+     * set_array:
+     *   "@pipe":
+     *     - ["{@symbol.array}"]
+     * ```
+     */
     array() {
         return [];
     }
+    /**
+     * Returns the positive infinity value (`Infinity`).
+     *
+     * @returns {number} Positive infinity
+     * @example
+     * ```yaml
+     * set_pos_infinity:
+     *   "@pipe":
+     *     - ["{@symbol.posInfinity}"]
+     * ```
+     */
     posInfinity() {
         return Infinity;
     }
+    /**
+     * Returns the negative infinity value (`-Infinity`).
+     *
+     * @returns {number} Negative infinity
+     * @example
+     * ```yaml
+     * set_neg_infinity:
+     *   "@pipe":
+     *     - ["{@symbol.negInfinity}"]
+     * ```
+     */
     negInfinity() {
         return -Infinity;
     }
+    /**
+     * Returns the not-a-number value (`NaN`).
+     *
+     * @returns {number} NaN
+     * @example
+     * ```yaml
+     * set_nan:
+     *   "@pipe":
+     *     - ["{@symbol.NaN}"]
+     * ```
+     */
     NaN() {
         return NaN;
     }
+    /**
+     * Returns the current date and time as a Date object.
+     *
+     * @returns {Date} The current date and time
+     * @example
+     * ```yaml
+     * set_date:
+     *   "@pipe":
+     *     - ["{@symbol.date}"]
+     *     - ["{@json.stringify}"]
+     * ```
+     */
     date() {
         return new Date();
     }

package/build/services/pipe/functions/unary.d.ts

@@ -1,7 +1,72 @@
+/**
+ * Provides unary operation functions for use in HotMesh mapping rules.
+ * The functions facilitate unary operations such as logical negation,
+ * making a number positive or negative, and bitwise negation during
+ * the mapping process. Each transformation is a function that expects
+ * one input parameter from the prior row in the `@pipe` structure.
+ *
+ * @remarks
+ * Invoked in mapping rules using `{@unary.<method>}` syntax.
+ */
 declare class UnaryHandler {
+    /**
+     * Returns the logical negation of a boolean value.
+     *
+     * @param {boolean} value - The boolean value to negate
+     * @returns {boolean} The negated boolean value
+     * @example
+     * ```yaml
+     * not_value:
+     *   "@pipe":
+     *     - ["{a.output.data.value}"]
+     *     - ["{@unary.not}"]
+     * ```
+     */
     not(value: boolean): boolean;
+    /**
+     * Returns the positive representation of a number using
+     * the unary plus operator.
+     *
+     * @param {number} value - The number to convert
+     * @returns {number} The positive representation of the value
+     * @example
+     * ```yaml
+     * positive_value:
+     *   "@pipe":
+     *     - ["{a.output.data.value}"]
+     *     - ["{@unary.positive}"]
+     * ```
+     */
     positive(value: number): number;
+    /**
+     * Returns the negative representation of a number using
+     * the unary negation operator.
+     *
+     * @param {number} value - The number to negate
+     * @returns {number} The negated number
+     * @example
+     * ```yaml
+     * negative_value:
+     *   "@pipe":
+     *     - ["{a.output.data.value}"]
+     *     - ["{@unary.negative}"]
+     * ```
+     */
     negative(value: number): number;
+    /**
+     * Returns the bitwise negation of a number using the
+     * bitwise NOT operator (`~`).
+     *
+     * @param {number} value - The number to bitwise negate
+     * @returns {number} The bitwise negation of the value
+     * @example
+     * ```yaml
+     * bitwise_not_value:
+     *   "@pipe":
+     *     - ["{a.output.data.value}"]
+     *     - ["{@unary.bitwise_not}"]
+     * ```
+     */
     bitwise_not(value: number): number;
 }
 export { UnaryHandler };

package/build/services/pipe/functions/unary.js

@@ -1,16 +1,81 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UnaryHandler = void 0;
+/**
+ * Provides unary operation functions for use in HotMesh mapping rules.
+ * The functions facilitate unary operations such as logical negation,
+ * making a number positive or negative, and bitwise negation during
+ * the mapping process. Each transformation is a function that expects
+ * one input parameter from the prior row in the `@pipe` structure.
+ *
+ * @remarks
+ * Invoked in mapping rules using `{@unary.<method>}` syntax.
+ */
 class UnaryHandler {
+    /**
+     * Returns the logical negation of a boolean value.
+     *
+     * @param {boolean} value - The boolean value to negate
+     * @returns {boolean} The negated boolean value
+     * @example
+     * ```yaml
+     * not_value:
+     *   "@pipe":
+     *     - ["{a.output.data.value}"]
+     *     - ["{@unary.not}"]
+     * ```
+     */
     not(value) {
         return !value;
     }
+    /**
+     * Returns the positive representation of a number using
+     * the unary plus operator.
+     *
+     * @param {number} value - The number to convert
+     * @returns {number} The positive representation of the value
+     * @example
+     * ```yaml
+     * positive_value:
+     *   "@pipe":
+     *     - ["{a.output.data.value}"]
+     *     - ["{@unary.positive}"]
+     * ```
+     */
     positive(value) {
         return +value;
     }
+    /**
+     * Returns the negative representation of a number using
+     * the unary negation operator.
+     *
+     * @param {number} value - The number to negate
+     * @returns {number} The negated number
+     * @example
+     * ```yaml
+     * negative_value:
+     *   "@pipe":
+     *     - ["{a.output.data.value}"]
+     *     - ["{@unary.negative}"]
+     * ```
+     */
     negative(value) {
         return -value;
     }
+    /**
+     * Returns the bitwise negation of a number using the
+     * bitwise NOT operator (`~`).
+     *
+     * @param {number} value - The number to bitwise negate
+     * @returns {number} The bitwise negation of the value
+     * @example
+     * ```yaml
+     * bitwise_not_value:
+     *   "@pipe":
+     *     - ["{a.output.data.value}"]
+     *     - ["{@unary.bitwise_not}"]
+     * ```
+     */
     bitwise_not(value) {
         return ~value;
     }

package/build/services/quorum/index.js

@@ -54,7 +54,7 @@ class QuorumService {
      * @private
      */
     async initStoreChannel(store) {
-        this.store = await factory_2.StoreServiceFactory.init(store, this.namespace, this.appId, this.logger);
+        this.store = await factory_2.StoreServiceFactory.init(store, this.namespace, this.appId, this.logger, this.guid, 'quorum');
     }
     /**
      * @private

package/build/services/router/consumption/index.js

@@ -439,8 +439,26 @@ class ConsumptionManager {
             output = this.errorHandler.structureUnhandledError(input, err instanceof Error ? err : new Error(String(err)));
         }
         try {
-            const messageId = await this.publishResponse(input, output);
-            telemetry.setStreamAttributes({ 'app.worker.mid': messageId });
+            // When the ENGINE itself fails to process a message (e.g., schema not
+            // found, missing subscription), do NOT republish the error back to the
+            // engine stream — that creates an infinite poison loop. The engine
+            // When the ENGINE encounters an infrastructure error (schema not found,
+            // subscription missing — code 598), the message is permanently unprocessable.
+            // Do NOT republish it — that creates an infinite poison loop. Only suppress
+            // these specific infrastructure errors; application-level errors (retries,
+            // duplicates, workflow failures) must still flow through normally.
+            if (group === 'ENGINE' && output?.code === 598) {
+                this.logger.error(`stream-engine-dispatch-fatal`, {
+                    stream, id, group,
+                    aid: input.metadata?.aid,
+                    jid: input.metadata?.jid,
+                    message: output.data?.message,
+                });
+            }
+            else {
+                const messageId = await this.publishResponse(input, output);
+                telemetry.setStreamAttributes({ 'app.worker.mid': messageId });
+            }
         }
         catch (publishErr) {
             // If publishResponse fails, still ack the message to prevent

package/build/services/router/error-handling/index.js

@@ -55,7 +55,7 @@ class ErrorHandler {
         }
         const result = {
             status: 'error',
-            code: config_1.HMSH_CODE_UNKNOWN,
+            code: err.code || config_1.HMSH_CODE_UNKNOWN,
             metadata: { ...input.metadata, guid: (0, utils_1.guid)() },
             data: error,
         };

package/build/services/store/factory.d.ts

@@ -3,6 +3,6 @@ import { ProviderClient, ProviderTransaction } from '../../types/provider';
 import { StoreInitializable } from './providers/store-initializable';
 import { StoreService } from './index';
 declare class StoreServiceFactory {
-    static init(providerClient: ProviderClient, namespace: string, appId: string, logger: ILogger): Promise<StoreService<ProviderClient, ProviderTransaction> & StoreInitializable>;
+    static init(providerClient: ProviderClient, namespace: string, appId: string, logger: ILogger, guid?: string, role?: string): Promise<StoreService<ProviderClient, ProviderTransaction> & StoreInitializable>;
 }
 export { StoreServiceFactory };

package/build/services/store/factory.js

@@ -4,12 +4,12 @@ exports.StoreServiceFactory = void 0;
 const utils_1 = require("../../modules/utils");
 const postgres_1 = require("./providers/postgres/postgres");
 class StoreServiceFactory {
-    static async init(providerClient, namespace, appId, logger) {
+    static async init(providerClient, namespace, appId, logger, guid, role) {
         let service;
         if ((0, utils_1.identifyProvider)(providerClient) === 'postgres') {
             service = new postgres_1.PostgresStoreService(providerClient);
         } //etc
-        await service.init(namespace, appId, logger);
+        await service.init(namespace, appId, logger, guid, role);
         return service;
     }
 }

package/build/services/store/index.d.ts

@@ -21,7 +21,7 @@ declare abstract class StoreService<Provider extends ProviderClient, Transaction
     serializer: Serializer;
     constructor(client: Provider);
     abstract transact(): TransactionProvider;
-    abstract init(namespace: string, appId: string, logger: ILogger): Promise<HotMeshApps>;
+    abstract init(namespace: string, appId: string, logger: ILogger, guid?: string, role?: string): Promise<HotMeshApps>;
     abstract mintKey(type: KeyType, params: KeyStoreParams): string;
     abstract getSettings(bCreate?: boolean): Promise<HotMeshSettings>;
     abstract setSettings(manifest: HotMeshSettings): Promise<any>;

package/build/services/store/providers/postgres/kvsql.d.ts

@@ -26,9 +26,19 @@ export declare class KVSQL {
     exec(...args: any[]): Promise<Array<any>>;
     mintKey(type: KeyType, params: KeyStoreParams): string;
     /**
-     * Resolves the table name when provided a key
+     * Resolves the table name when provided a key.
+     * Public tables (applications, connections) are no longer routed through
+     * the KV layer — they use direct SQL in postgres.ts.
      */
     tableForKey(key: string, stats_type?: 'hash' | 'sorted_set' | 'list'): string;
+    /**
+     * Strips the `hmsh:<appId>:<entity>:` prefix from a full Redis-style key,
+     * keeping only the meaningful suffix for SQL storage. Applied only to the
+     * `key` column in SQL params — never to member values, field names, or values.
+     *
+     * Excluded tables (jobs, streams, job attributes) retain the full key.
+     */
+    storageKey(fullKey: string): string;
     safeName(input: string, prefix?: string): string;
     set: (key: string, value: string, options?: import("./kvtypes/hash/index").SetOptions, multi?: ProviderTransaction) => Promise<boolean>;
     _set: (key: string, value: string, options?: import("./kvtypes/hash/index").SetOptions) => {

package/build/services/store/providers/postgres/kvsql.js

@@ -110,16 +110,12 @@ class KVSQL {
         return '';
     }
     /**
-     * Resolves the table name when provided a key
+     * Resolves the table name when provided a key.
+     * Public tables (applications, connections) are no longer routed through
+     * the KV layer — they use direct SQL in postgres.ts.
      */
     tableForKey(key, stats_type) {
-        if (key === key_1.HMNS) {
-            return 'public.hotmesh_connections';
-        }
         const [_, appName, abbrev, ...rest] = key.split(':');
-        if (appName === 'a') {
-            return 'public.hotmesh_applications';
-        }
         const id = rest?.length ? rest.join(':') : '';
         const entity = key_1.KeyService.resolveEntityType(abbrev, id);
         if (this.safeName(this.appId) !== this.safeName(appName)) {
@@ -145,13 +141,27 @@ class KVSQL {
         if (entity === 'unknown_entity') {
             throw new Error(`Unknown entity type abbreviation: ${abbrev}`);
         }
-        else if (entity === 'applications') {
-            return 'public.hotmesh_applications';
-        }
         else {
             return `${schemaName}.${entity}`;
         }
     }
+    /**
+     * Strips the `hmsh:<appId>:<entity>:` prefix from a full Redis-style key,
+     * keeping only the meaningful suffix for SQL storage. Applied only to the
+     * `key` column in SQL params — never to member values, field names, or values.
+     *
+     * Excluded tables (jobs, streams, job attributes) retain the full key.
+     */
+    storageKey(fullKey) {
+        const parts = fullKey.split(':');
+        if (parts.length < 3)
+            return fullKey;
+        const entity = parts[2];
+        // Excluded tables: jobs (j), streams (x), job attributes (d)
+        if (entity === 'j' || entity === 'x' || entity === 'd')
+            return fullKey;
+        return parts.slice(3).join(':');
+    }
     safeName(input, prefix = '') {
         if (!input) {
             return 'connections';
@@ -186,6 +196,7 @@ class KVSQL {
           AND (expired_at IS NULL OR expired_at > NOW())
         LIMIT 1;
       `;
+            return { sql, params: [key] };
         }
         else {
             sql = `
@@ -194,9 +205,8 @@ class KVSQL {
           AND (expiry IS NULL OR expiry > NOW())
         LIMIT 1;
       `;
+            return { sql, params: [this.storageKey(key)] };
         }
-        const params = [key];
-        return { sql, params };
     }
 }
 exports.KVSQL = KVSQL;

package/build/services/store/providers/postgres/kvtables.js

@@ -137,6 +137,39 @@ const KVTables = (context) => ({
             for (const tableDef of tableDefinitions) {
                 const fullTableName = `${tableDef.schema}.${tableDef.name}`;
                 switch (tableDef.type) {
+                    case 'relational_app':
+                        await client.query(`
+              CREATE TABLE IF NOT EXISTS ${fullTableName} (
+                app_id TEXT PRIMARY KEY,
+                version TEXT NOT NULL DEFAULT '1',
+                active BOOLEAN DEFAULT TRUE,
+                settings JSONB DEFAULT '{}',
+                created_at TIMESTAMPTZ DEFAULT NOW(),
+                updated_at TIMESTAMPTZ DEFAULT NOW()
+              );
+            `);
+                        await client.query(`
+              CREATE TABLE IF NOT EXISTS public.hmsh_application_versions (
+                app_id TEXT NOT NULL REFERENCES public.hmsh_applications(app_id) ON DELETE CASCADE,
+                version TEXT NOT NULL,
+                status TEXT NOT NULL DEFAULT 'deployed',
+                deployed_at TIMESTAMPTZ DEFAULT NOW(),
+                PRIMARY KEY (app_id, version)
+              );
+            `);
+                        break;
+                    case 'relational_connection':
+                        await client.query(`
+              CREATE TABLE IF NOT EXISTS ${fullTableName} (
+                guid TEXT NOT NULL,
+                app_id TEXT NOT NULL,
+                role TEXT NOT NULL,
+                version TEXT NOT NULL,
+                connected_at TIMESTAMPTZ DEFAULT NOW(),
+                PRIMARY KEY (guid, app_id)
+              );
+            `);
+                        break;
                     case 'string':
                         await client.query(`
               CREATE TABLE IF NOT EXISTS ${fullTableName} (
@@ -375,8 +408,8 @@ const KVTables = (context) => ({
     },
     getTableNames(appName) {
         const tableNames = [];
-        // Applications table (only hotmesh prefix)
-        tableNames.push('hotmesh_applications', 'hotmesh_connections');
+        // Public relational tables
+        tableNames.push('public.hmsh_applications', 'public.hmsh_application_versions', 'public.hmsh_connections');
         // Other tables with appName
         const tablesWithAppName = [
             'throttles',
@@ -404,13 +437,13 @@ const KVTables = (context) => ({
         const tableDefinitions = [
             {
                 schema: 'public',
-                name: 'hotmesh_applications',
-                type: 'hash',
+                name: 'hmsh_applications',
+                type: 'relational_app',
             },
             {
                 schema: 'public',
-                name: 'hotmesh_connections',
-                type: 'hash',
+                name: 'hmsh_connections',
+                type: 'relational_connection',
             },
             {
                 schema: schemaName,