@hotmeshio/hotmesh 0.13.0 → 0.14.0

package/build/services/stream/providers/postgres/credentials.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Worker role credential lifecycle management.
+ *
+ * These are the low-level functions that create, rotate, and revoke
+ * Postgres roles for worker routers. Each role is scoped to specific
+ * stream_name(s) via the `app.allowed_streams` session variable.
+ *
+ * **Prefer the high-level API**: Call `HotMesh.provisionWorkerRole()`,
+ * `HotMesh.rotateWorkerPassword()`, etc. — those methods handle
+ * connection creation and cleanup automatically.
+ */
+import { PostgresClientType } from '../../../../types/postgres';
+export interface WorkerCredential {
+    roleName: string;
+    password: string;
+}
+export interface WorkerCredentialInfo {
+    id: number;
+    roleName: string;
+    streamNames: string[];
+    createdAt: Date;
+    revokedAt: Date | null;
+    lastRotatedAt: Date;
+}
+/**
+ * Provision a new Postgres role scoped to specific stream names.
+ *
+ * The role:
+ * - Can LOGIN with the returned password
+ * - Has USAGE on the schema
+ * - Has EXECUTE on the 5 worker stored procedures
+ * - Has `app.allowed_streams` set to the comma-separated stream names
+ * - Has NO direct table access
+ *
+ * @param adminClient - A Postgres client connected as the admin/owner
+ * @param schema - The appId schema name (e.g., 'durable')
+ * @param streamNames - Stream names this role can access (e.g., ['payment-activity'])
+ * @param password - Optional password (generated if not provided)
+ * @returns The created role name and password
+ */
+export declare function provisionWorkerRole(adminClient: PostgresClientType, schema: string, streamNames: string[], password?: string): Promise<WorkerCredential>;
+/**
+ * Rotate the password for an existing worker role.
+ */
+export declare function rotateWorkerPassword(adminClient: PostgresClientType, schema: string, roleName: string, newPassword?: string): Promise<{
+    password: string;
+}>;
+/**
+ * Revoke a worker role by disabling login.
+ * The role is not dropped — this preserves the audit trail.
+ */
+export declare function revokeWorkerRole(adminClient: PostgresClientType, schema: string, roleName: string): Promise<void>;
+/**
+ * List all worker roles for a schema.
+ */
+export declare function listWorkerRoles(adminClient: PostgresClientType, schema: string): Promise<WorkerCredentialInfo[]>;

package/build/services/stream/providers/postgres/credentials.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * Worker role credential lifecycle management.
+ *
+ * These are the low-level functions that create, rotate, and revoke
+ * Postgres roles for worker routers. Each role is scoped to specific
+ * stream_name(s) via the `app.allowed_streams` session variable.
+ *
+ * **Prefer the high-level API**: Call `HotMesh.provisionWorkerRole()`,
+ * `HotMesh.rotateWorkerPassword()`, etc. — those methods handle
+ * connection creation and cleanup automatically.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listWorkerRoles = exports.revokeWorkerRole = exports.rotateWorkerPassword = exports.provisionWorkerRole = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Sanitize a stream name for use in a Postgres role name.
+ * Replaces non-alphanumeric characters with underscores.
+ */
+function sanitizeForRoleName(name) {
+    return name.replace(/[^a-zA-Z0-9]/g, '_');
+}
+/**
+ * Provision a new Postgres role scoped to specific stream names.
+ *
+ * The role:
+ * - Can LOGIN with the returned password
+ * - Has USAGE on the schema
+ * - Has EXECUTE on the 5 worker stored procedures
+ * - Has `app.allowed_streams` set to the comma-separated stream names
+ * - Has NO direct table access
+ *
+ * @param adminClient - A Postgres client connected as the admin/owner
+ * @param schema - The appId schema name (e.g., 'durable')
+ * @param streamNames - Stream names this role can access (e.g., ['payment-activity'])
+ * @param password - Optional password (generated if not provided)
+ * @returns The created role name and password
+ */
+async function provisionWorkerRole(adminClient, schema, streamNames, password) {
+    const safeSchema = schema.replace(/[^a-zA-Z0-9_]/g, '_');
+    const streamSuffix = streamNames.map(sanitizeForRoleName).join('__');
+    const roleName = `hmsh_wrk_${safeSchema}_${streamSuffix}`.substring(0, 63);
+    const rolePassword = password || (0, crypto_1.randomUUID)();
+    const allowedStreams = streamNames.join(',');
+    // Create the role (idempotent — drop if exists first for credential reset)
+    await adminClient.query(`
+    DO $$
+    BEGIN
+      IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${roleName}') THEN
+        EXECUTE format('ALTER ROLE %I LOGIN PASSWORD %L', '${roleName}', '${rolePassword}');
+      ELSE
+        EXECUTE format('CREATE ROLE %I LOGIN PASSWORD %L', '${roleName}', '${rolePassword}');
+      END IF;
+    END
+    $$;
+  `);
+    // Grant schema usage (required to call functions in the schema)
+    await adminClient.query(`GRANT USAGE ON SCHEMA ${safeSchema} TO ${roleName};`);
+    // Grant EXECUTE on the 5 worker procedures
+    const procedures = [
+        `${safeSchema}.worker_dequeue(TEXT, INT, TEXT, INT)`,
+        `${safeSchema}.worker_ack(TEXT, BIGINT[])`,
+        `${safeSchema}.worker_dead_letter(TEXT, BIGINT[])`,
+        `${safeSchema}.worker_respond(TEXT, TEXT, INT, NUMERIC, INT, TIMESTAMPTZ, INT)`,
+        `${safeSchema}.worker_listen(TEXT)`,
+        `${safeSchema}.worker_unlisten(TEXT)`,
+    ];
+    for (const proc of procedures) {
+        await adminClient.query(`GRANT EXECUTE ON FUNCTION ${proc} TO ${roleName};`);
+    }
+    // Set the allowed streams as a session default for this role
+    await adminClient.query(`ALTER ROLE ${roleName} SET app.allowed_streams = '${allowedStreams}';`);
+    // Explicitly revoke direct table access (defense in depth)
+    await adminClient.query(`
+    REVOKE ALL ON ALL TABLES IN SCHEMA ${safeSchema} FROM ${roleName};
+  `);
+    // Record in worker_credentials table
+    await adminClient.query(`INSERT INTO ${safeSchema}.worker_credentials (role_name, stream_names)
+     VALUES ($1, $2)
+     ON CONFLICT (role_name) DO UPDATE
+       SET stream_names = $2,
+           revoked_at = NULL,
+           last_rotated_at = NOW()`, [roleName, streamNames]);
+    return { roleName, password: rolePassword };
+}
+exports.provisionWorkerRole = provisionWorkerRole;
+/**
+ * Rotate the password for an existing worker role.
+ */
+async function rotateWorkerPassword(adminClient, schema, roleName, newPassword) {
+    const safeSchema = schema.replace(/[^a-zA-Z0-9_]/g, '_');
+    const password = newPassword || (0, crypto_1.randomUUID)();
+    await adminClient.query(`ALTER ROLE ${roleName} PASSWORD '${password}';`);
+    await adminClient.query(`UPDATE ${safeSchema}.worker_credentials
+     SET last_rotated_at = NOW()
+     WHERE role_name = $1`, [roleName]);
+    return { password };
+}
+exports.rotateWorkerPassword = rotateWorkerPassword;
+/**
+ * Revoke a worker role by disabling login.
+ * The role is not dropped — this preserves the audit trail.
+ */
+async function revokeWorkerRole(adminClient, schema, roleName) {
+    const safeSchema = schema.replace(/[^a-zA-Z0-9_]/g, '_');
+    await adminClient.query(`ALTER ROLE ${roleName} NOLOGIN;`);
+    await adminClient.query(`UPDATE ${safeSchema}.worker_credentials
+     SET revoked_at = NOW()
+     WHERE role_name = $1`, [roleName]);
+}
+exports.revokeWorkerRole = revokeWorkerRole;
+/**
+ * List all worker roles for a schema.
+ */
+async function listWorkerRoles(adminClient, schema) {
+    const safeSchema = schema.replace(/[^a-zA-Z0-9_]/g, '_');
+    const result = await adminClient.query(`SELECT id, role_name, stream_names, created_at, revoked_at, last_rotated_at
+     FROM ${safeSchema}.worker_credentials
+     ORDER BY created_at`);
+    return result.rows.map((row) => ({
+        id: row.id,
+        roleName: row.role_name,
+        streamNames: row.stream_names,
+        createdAt: row.created_at,
+        revokedAt: row.revoked_at,
+        lastRotatedAt: row.last_rotated_at,
+    }));
+}
+exports.listWorkerRoles = listWorkerRoles;

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getNotificationChannelName = exports.deploySchema = void 0;
 const enums_1 = require("../../../../modules/enums");
 const utils_1 = require("../../../../modules/utils");
+const procedures_1 = require("./procedures");
 async function deploySchema(streamClient, appId, logger) {
     const isPool = streamClient?.totalCount !== undefined &&
         streamClient?.idleCount !== undefined;
@@ -279,6 +280,23 @@ async function createTables(client, schemaName) {
     ON ${workerTable} (jid, msg_type, created_at)
     WHERE jid != '';
   `);
+    // ---- ROLES table (used by scout for distributed leader election) ----
+    const rolesTable = `${schemaName}.roles`;
+    await client.query(`
+    CREATE TABLE IF NOT EXISTS ${rolesTable} (
+      key TEXT PRIMARY KEY,
+      value TEXT,
+      expiry TIMESTAMP WITH TIME ZONE
+    );
+  `);
+    // ---- WORKER ACCESS CONTROL ----
+    // SECURITY DEFINER stored procedures for scoped worker access
+    const procedureStatements = (0, procedures_1.getCreateProceduresSQL)(schemaName);
+    for (const sql of procedureStatements) {
+        await client.query(sql);
+    }
+    // Worker credentials registry
+    await client.query((0, procedures_1.getCreateWorkerCredentialsTableSQL)(schemaName));
 }
 async function createNotificationTriggers(client, schemaName) {
     const engineTable = `${schemaName}.engine_streams`;

package/build/services/stream/providers/postgres/messages.js

@@ -57,13 +57,13 @@ function buildPublishSQL(tableName, streamName, isEngine, messages, options) {
         const msgType = data.type || '';
         const topic = data.metadata?.topic || '';
         // Determine if this message has explicit retry config
-        const hasExplicitConfig = (retryConfig && 'max_retry_attempts' in retryConfig) || options?.retryPolicy;
+        const hasExplicitConfig = (retryConfig && 'max_retry_attempts' in retryConfig) || options?.retry;
         let normalizedPolicy = null;
         if (retryConfig && 'max_retry_attempts' in retryConfig) {
             normalizedPolicy = retryConfig;
         }
-        else if (options?.retryPolicy) {
-            normalizedPolicy = (0, utils_1.normalizeRetryPolicy)(options.retryPolicy, {
+        else if (options?.retry) {
+            normalizedPolicy = (0, utils_1.normalizeRetryPolicy)(options.retry, {
                 maximumAttempts: 3,
                 backoffCoefficient: 10,
                 maximumInterval: 120,
@@ -72,7 +72,7 @@ function buildPublishSQL(tableName, streamName, isEngine, messages, options) {
         return {
             message: JSON.stringify(data),
             hasExplicitConfig,
-            retryPolicy: normalizedPolicy,
+            retry: normalizedPolicy,
             visibilityDelayMs: visibilityDelayMs || 0,
             retryAttempt: retryAttempt || 0,
             workflowName,
@@ -123,7 +123,7 @@ function buildPublishSQL(tableName, streamName, isEngine, messages, options) {
                 if (pm.hasExplicitConfig) {
                     const paramOffset = params.length + 1;
                     valuesClauses.push(`($1, $${paramOffset}, $${paramOffset + 1}, $${paramOffset + 2}, $${paramOffset + 3}, ${visibleAtClause}, $${paramOffset + 4})`);
-                    params.push(pm.message, pm.retryPolicy.max_retry_attempts, pm.retryPolicy.backoff_coefficient, pm.retryPolicy.maximum_interval_seconds, pm.retryAttempt);
+                    params.push(pm.message, pm.retry.max_retry_attempts, pm.retry.backoff_coefficient, pm.retry.maximum_interval_seconds, pm.retryAttempt);
                 }
                 else {
                     const paramOffset = params.length + 1;
@@ -167,7 +167,7 @@ function buildPublishSQL(tableName, streamName, isEngine, messages, options) {
                 if (pm.hasExplicitConfig) {
                     const paramOffset = params.length + 1;
                     valuesClauses.push(`($1, $${paramOffset}, $${paramOffset + 1}, $${paramOffset + 2}, $${paramOffset + 3}, $${paramOffset + 4}, $${paramOffset + 5}, $${paramOffset + 6}, $${paramOffset + 7}, $${paramOffset + 8}, $${paramOffset + 9}, ${visibleAtClause}, $${paramOffset + 10})`);
-                    params.push(pm.workflowName, pm.jid, pm.aid, pm.dad, pm.msgType, pm.topic, pm.message, pm.retryPolicy.max_retry_attempts, pm.retryPolicy.backoff_coefficient, pm.retryPolicy.maximum_interval_seconds, pm.retryAttempt);
+                    params.push(pm.workflowName, pm.jid, pm.aid, pm.dad, pm.msgType, pm.topic, pm.message, pm.retry.max_retry_attempts, pm.retry.backoff_coefficient, pm.retry.maximum_interval_seconds, pm.retryAttempt);
                 }
                 else {
                     const paramOffset = params.length + 1;
@@ -243,7 +243,7 @@ async function fetchMessages(client, tableName, streamName, isEngine, consumerNa
                 return {
                     id: row.id.toString(),
                     data,
-                    retryPolicy: (row.max_retry_attempts !== null && !hasDefaultRetryPolicy) ? {
+                    retry: (row.max_retry_attempts !== null && !hasDefaultRetryPolicy) ? {
                         maximumAttempts: row.max_retry_attempts,
                         backoffCoefficient: parseFloat(row.backoff_coefficient),
                         maximumInterval: row.maximum_interval_seconds,

package/build/services/stream/providers/postgres/notifications.js

@@ -192,7 +192,14 @@ class NotificationManager {
             // Set up LISTEN for this channel (only once per channel)
             try {
                 const listenStart = Date.now();
-                await this.client.query(`LISTEN "${channelName}"`);
+                // In secured mode, use stored procedure for validated LISTEN
+                if (serviceAny.securedMode && serviceAny.safeName) {
+                    const schema = serviceAny.safeName(serviceAny.appId);
+                    await this.client.query(`SELECT ${schema}.worker_listen($1)`, [resolvedStreamName]);
+                }
+                else {
+                    await this.client.query(`LISTEN "${channelName}"`);
+                }
                 this.logger.debug('postgres-stream-listen-start', {
                     streamName,
                     groupName,
@@ -257,7 +264,14 @@ class NotificationManager {
                 clientNotificationConsumers.delete(consumerKey);
                 const channelName = (0, kvtables_1.getNotificationChannelName)(resolvedStreamName, isEngine);
                 try {
-                    await this.client.query(`UNLISTEN "${channelName}"`);
+                    // In secured mode, use stored procedure for validated UNLISTEN
+                    if (serviceAny.securedMode && serviceAny.safeName) {
+                        const schema = serviceAny.safeName(serviceAny.appId);
+                        await this.client.query(`SELECT ${schema}.worker_unlisten($1)`, [resolvedStreamName]);
+                    }
+                    else {
+                        await this.client.query(`UNLISTEN "${channelName}"`);
+                    }
                     this.logger.debug('postgres-stream-unlisten', {
                         streamName,
                         groupName,

package/build/services/stream/providers/postgres/postgres.d.ts

@@ -24,6 +24,12 @@ declare class PostgresStreamService extends StreamService<PostgresClientType & P
     namespace: string;
     appId: string;
     logger: ILogger;
+    /**
+     * When true, all worker stream operations use SECURITY DEFINER
+     * stored procedures instead of raw SQL. Enabled when the worker
+     * connects with scoped `workerCredentials`.
+     */
+    securedMode: boolean;
     private scoutManager;
     private notificationManager;
     constructor(streamClient: PostgresClientType & ProviderClient, storeClient: ProviderClient, config?: StreamConfig);
@@ -104,6 +110,7 @@ declare class PostgresStreamService extends StreamService<PostgresClientType & P
         supportsTrimming: boolean;
         supportsRetry: boolean;
         supportsNotifications: boolean;
+        supportsParallelProcessing: boolean;
         maxMessageSize: number;
         maxBatchSize: number;
     };

package/build/services/stream/providers/postgres/postgres.js

@@ -29,6 +29,7 @@ const index_1 = require("../../index");
 const kvtables_1 = require("./kvtables");
 const Stats = __importStar(require("./stats"));
 const Messages = __importStar(require("./messages"));
+const Secured = __importStar(require("./secured"));
 const scout_1 = require("./scout");
 const notifications_1 = require("./notifications");
 const Lifecycle = __importStar(require("./lifecycle"));
@@ -42,21 +43,35 @@ const Lifecycle = __importStar(require("./lifecycle"));
 class PostgresStreamService extends index_1.StreamService {
     constructor(streamClient, storeClient, config = {}) {
         super(streamClient, storeClient, config);
+        /**
+         * When true, all worker stream operations use SECURITY DEFINER
+         * stored procedures instead of raw SQL. Enabled when the worker
+         * connects with scoped `workerCredentials`.
+         */
+        this.securedMode = false;
+        if (config?.securedWorker) {
+            this.securedMode = true;
+        }
     }
     async init(namespace, appId, logger) {
         this.namespace = namespace;
         this.appId = appId;
         this.logger = logger;
-        await (0, kvtables_1.deploySchema)(this.streamClient, this.appId, this.logger);
-        // Initialize scout manager
-        this.scoutManager = new scout_1.ScoutManager(this.streamClient, this.appId, this.getEngineTableName.bind(this), this.mintKey.bind(this), this.logger);
+        // Secured workers skip schema deployment and scout initialization —
+        // they use SECURITY DEFINER stored procedures for all stream ops
+        // and never need direct table access.
+        if (!this.securedMode) {
+            await (0, kvtables_1.deploySchema)(this.streamClient, this.appId, this.logger);
+        }
+        // Initialize scout manager (skipped in secured mode — roles table inaccessible)
+        this.scoutManager = this.securedMode ? null : new scout_1.ScoutManager(this.streamClient, this.appId, this.getEngineTableName.bind(this), this.mintKey.bind(this), this.logger);
         // Initialize notification manager
         this.notificationManager = new notifications_1.NotificationManager(this.streamClient, this.getEngineTableName.bind(this), () => (0, notifications_1.getFallbackInterval)(this.config), this.logger);
         // Set up notification handler if supported
         if (this.streamClient.on && this.isNotificationsEnabled()) {
             this.notificationManager.setupClientNotificationHandler(this);
             this.notificationManager.startClientFallbackPoller(this.checkForMissedMessages.bind(this));
-            this.scoutManager.startRouterScoutPoller();
+            this.scoutManager?.startRouterScoutPoller();
         }
     }
     isNotificationsEnabled() {
@@ -152,6 +167,10 @@ class PostgresStreamService extends index_1.StreamService {
      * added to the transaction for atomic execution.
      */
     async publishMessages(streamName, messages, options) {
+        if (this.securedMode) {
+            const target = this.resolveStreamTarget(streamName);
+            return Secured.publishMessagesSecured(this.streamClient, this.safeName(this.appId), target.streamName, messages, this.logger);
+        }
         const target = this.resolveStreamTarget(streamName);
         return Messages.publishMessages(this.streamClient, target.tableName, target.streamName, target.isEngine, messages, options, this.logger);
     }
@@ -213,14 +232,26 @@ class PostgresStreamService extends index_1.StreamService {
         await this.notificationManager.stopNotificationConsumer(this, streamName, groupName);
     }
     async fetchMessages(streamName, groupName, consumerName, options) {
+        if (this.securedMode) {
+            const target = this.resolveStreamTarget(streamName);
+            return Secured.fetchMessagesSecured(this.streamClient, this.safeName(this.appId), target.streamName, consumerName, options || {}, this.logger);
+        }
         const target = this.resolveStreamTarget(streamName);
         return Messages.fetchMessages(this.streamClient, target.tableName, target.streamName, target.isEngine, consumerName, options || {}, this.logger);
     }
     async ackAndDelete(streamName, groupName, messageIds) {
+        if (this.securedMode) {
+            const target = this.resolveStreamTarget(streamName);
+            return Secured.ackAndDeleteSecured(this.streamClient, this.safeName(this.appId), target.streamName, messageIds, this.logger);
+        }
         const target = this.resolveStreamTarget(streamName);
         return Messages.ackAndDelete(this.streamClient, target.tableName, target.streamName, messageIds, this.logger);
     }
     async deadLetterMessages(streamName, groupName, messageIds) {
+        if (this.securedMode) {
+            const target = this.resolveStreamTarget(streamName);
+            return Secured.deadLetterMessagesSecured(this.streamClient, this.safeName(this.appId), target.streamName, messageIds, this.logger);
+        }
         const target = this.resolveStreamTarget(streamName);
         return Messages.deadLetterMessages(this.streamClient, target.tableName, target.streamName, messageIds, this.logger);
     }

package/build/services/stream/providers/postgres/procedures.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SECURITY DEFINER stored procedures for worker router access control.
+ *
+ * Each procedure runs as the schema owner (admin) and validates the
+ * caller's `app.allowed_streams` session variable before executing.
+ * Worker roles are granted EXECUTE on these procedures only — they
+ * have zero direct table access.
+ *
+ * ## Procedures
+ *
+ * | Procedure | Purpose |
+ * |-----------|---------|
+ * | `worker_dequeue` | Fetch and reserve messages from `worker_streams` |
+ * | `worker_ack` | Soft-delete (ack) messages in `worker_streams` |
+ * | `worker_dead_letter` | Dead-letter messages in `worker_streams` |
+ * | `worker_respond` | Publish a response into `engine_streams` |
+ * | `worker_listen` | Subscribe to NOTIFY channel for a stream |
+ * | `worker_unlisten` | Unsubscribe from NOTIFY channel |
+ */
+export declare function getCreateProceduresSQL(schemaName: string): string[];
+export declare function getCreateWorkerCredentialsTableSQL(schemaName: string): string;

package/build/services/stream/providers/postgres/procedures.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * SECURITY DEFINER stored procedures for worker router access control.
+ *
+ * Each procedure runs as the schema owner (admin) and validates the
+ * caller's `app.allowed_streams` session variable before executing.
+ * Worker roles are granted EXECUTE on these procedures only — they
+ * have zero direct table access.
+ *
+ * ## Procedures
+ *
+ * | Procedure | Purpose |
+ * |-----------|---------|
+ * | `worker_dequeue` | Fetch and reserve messages from `worker_streams` |
+ * | `worker_ack` | Soft-delete (ack) messages in `worker_streams` |
+ * | `worker_dead_letter` | Dead-letter messages in `worker_streams` |
+ * | `worker_respond` | Publish a response into `engine_streams` |
+ * | `worker_listen` | Subscribe to NOTIFY channel for a stream |
+ * | `worker_unlisten` | Unsubscribe from NOTIFY channel |
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCreateWorkerCredentialsTableSQL = exports.getCreateProceduresSQL = void 0;
+const STREAM_ACCESS_CHECK = `
+  DECLARE
+    allowed_streams TEXT[];
+  BEGIN
+    allowed_streams := string_to_array(current_setting('app.allowed_streams', true), ',');
+    IF allowed_streams IS NULL OR NOT (p_stream_name = ANY(allowed_streams)) THEN
+      RAISE EXCEPTION 'access denied: stream_name "%" not in allowed streams', p_stream_name
+        USING ERRCODE = '42501';
+    END IF;
+`;
+function getCreateProceduresSQL(schemaName) {
+    const engineTable = `${schemaName}.engine_streams`;
+    const workerTable = `${schemaName}.worker_streams`;
+    return [
+        // -- worker_dequeue --
+        `CREATE OR REPLACE FUNCTION ${schemaName}.worker_dequeue(
+      p_stream_name TEXT,
+      p_batch_size INT,
+      p_consumer_id TEXT,
+      p_reservation_timeout_sec INT DEFAULT 30
+    )
+    RETURNS TABLE (
+      id BIGINT,
+      message TEXT,
+      workflow_name TEXT,
+      max_retry_attempts INT,
+      backoff_coefficient NUMERIC,
+      maximum_interval_seconds INT,
+      retry_attempt INT
+    )
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path = ${schemaName}, pg_temp
+    AS $$
+    ${STREAM_ACCESS_CHECK}
+      RETURN QUERY
+      UPDATE ${workerTable} ws
+      SET reserved_at = NOW(), reserved_by = p_consumer_id
+      WHERE ws.id IN (
+        SELECT ws2.id FROM ${workerTable} ws2
+        WHERE ws2.stream_name = p_stream_name
+          AND (ws2.reserved_at IS NULL OR ws2.reserved_at < NOW() - (p_reservation_timeout_sec || ' seconds')::INTERVAL)
+          AND ws2.expired_at IS NULL
+          AND ws2.visible_at <= NOW()
+        ORDER BY ws2.id
+        LIMIT p_batch_size
+        FOR UPDATE SKIP LOCKED
+      )
+      RETURNING ws.id, ws.message, ws.workflow_name, ws.max_retry_attempts,
+                ws.backoff_coefficient, ws.maximum_interval_seconds, ws.retry_attempt;
+    END;
+    $$;`,
+        // -- worker_ack --
+        `CREATE OR REPLACE FUNCTION ${schemaName}.worker_ack(
+      p_stream_name TEXT,
+      p_message_ids BIGINT[]
+    )
+    RETURNS INT
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path = ${schemaName}, pg_temp
+    AS $$
+    DECLARE
+      affected INT;
+    ${STREAM_ACCESS_CHECK}
+      UPDATE ${workerTable}
+      SET expired_at = NOW()
+      WHERE stream_name = p_stream_name AND id = ANY(p_message_ids);
+      GET DIAGNOSTICS affected = ROW_COUNT;
+      RETURN affected;
+    END;
+    $$;`,
+        // -- worker_dead_letter --
+        `CREATE OR REPLACE FUNCTION ${schemaName}.worker_dead_letter(
+      p_stream_name TEXT,
+      p_message_ids BIGINT[]
+    )
+    RETURNS INT
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path = ${schemaName}, pg_temp
+    AS $$
+    DECLARE
+      affected INT;
+    ${STREAM_ACCESS_CHECK}
+      UPDATE ${workerTable}
+      SET dead_lettered_at = NOW(), expired_at = NOW()
+      WHERE stream_name = p_stream_name AND id = ANY(p_message_ids);
+      GET DIAGNOSTICS affected = ROW_COUNT;
+      RETURN affected;
+    END;
+    $$;`,
+        // -- worker_respond --
+        // Inserts into engine_streams. The engine stream_name is the appId
+        // (hardcoded from the schema name, not caller-controlled).
+        // NOTE: Does NOT use STREAM_ACCESS_CHECK because p_stream_name is
+        // not the target — the engine stream is always hardcoded. Instead,
+        // we verify the caller has at least one allowed stream (i.e., is a
+        // legitimate provisioned worker).
+        `CREATE OR REPLACE FUNCTION ${schemaName}.worker_respond(
+      p_stream_name TEXT,
+      p_message TEXT,
+      p_max_retry_attempts INT DEFAULT NULL,
+      p_backoff_coefficient NUMERIC DEFAULT NULL,
+      p_maximum_interval_seconds INT DEFAULT NULL,
+      p_visible_at TIMESTAMPTZ DEFAULT NOW(),
+      p_retry_attempt INT DEFAULT 0
+    )
+    RETURNS BIGINT
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path = ${schemaName}, pg_temp
+    AS $$
+    DECLARE
+      new_id BIGINT;
+      engine_stream_name TEXT;
+      allowed_streams TEXT[];
+    BEGIN
+      allowed_streams := string_to_array(current_setting('app.allowed_streams', true), ',');
+      IF allowed_streams IS NULL OR array_length(allowed_streams, 1) IS NULL THEN
+        RAISE EXCEPTION 'access denied: caller has no allowed streams'
+          USING ERRCODE = '42501';
+      END IF;
+      -- Engine stream_name is the schema/appId name
+      engine_stream_name := '${schemaName}';
+
+      IF p_max_retry_attempts IS NOT NULL THEN
+        INSERT INTO ${engineTable}
+          (stream_name, message, max_retry_attempts, backoff_coefficient, maximum_interval_seconds, visible_at, retry_attempt)
+        VALUES
+          (engine_stream_name, p_message, p_max_retry_attempts, p_backoff_coefficient, p_maximum_interval_seconds, p_visible_at, p_retry_attempt)
+        RETURNING id INTO new_id;
+      ELSE
+        INSERT INTO ${engineTable}
+          (stream_name, message, visible_at, retry_attempt)
+        VALUES
+          (engine_stream_name, p_message, p_visible_at, p_retry_attempt)
+        RETURNING id INTO new_id;
+      END IF;
+
+      RETURN new_id;
+    END;
+    $$;`,
+        // -- worker_listen --
+        `CREATE OR REPLACE FUNCTION ${schemaName}.worker_listen(
+      p_stream_name TEXT
+    )
+    RETURNS VOID
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path = ${schemaName}, pg_temp
+    AS $$
+    DECLARE
+      channel_name TEXT;
+    ${STREAM_ACCESS_CHECK}
+      channel_name := 'wrk_' || p_stream_name;
+      IF length(channel_name) > 63 THEN
+        channel_name := left(channel_name, 63);
+      END IF;
+      EXECUTE format('LISTEN %I', channel_name);
+    END;
+    $$;`,
+        // -- worker_unlisten --
+        `CREATE OR REPLACE FUNCTION ${schemaName}.worker_unlisten(
+      p_stream_name TEXT
+    )
+    RETURNS VOID
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path = ${schemaName}, pg_temp
+    AS $$
+    DECLARE
+      channel_name TEXT;
+    ${STREAM_ACCESS_CHECK}
+      channel_name := 'wrk_' || p_stream_name;
+      IF length(channel_name) > 63 THEN
+        channel_name := left(channel_name, 63);
+      END IF;
+      EXECUTE format('UNLISTEN %I', channel_name);
+    END;
+    $$;`,
+    ];
+}
+exports.getCreateProceduresSQL = getCreateProceduresSQL;
+function getCreateWorkerCredentialsTableSQL(schemaName) {
+    return `
+    CREATE TABLE IF NOT EXISTS ${schemaName}.worker_credentials (
+      id SERIAL PRIMARY KEY,
+      role_name TEXT NOT NULL UNIQUE,
+      stream_names TEXT[] NOT NULL,
+      created_at TIMESTAMPTZ DEFAULT NOW(),
+      revoked_at TIMESTAMPTZ,
+      last_rotated_at TIMESTAMPTZ DEFAULT NOW()
+    );
+  `;
+}
+exports.getCreateWorkerCredentialsTableSQL = getCreateWorkerCredentialsTableSQL;