@hotmeshio/hotmesh 0.12.1 → 0.14.0

package/build/services/engine/init.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Engine bootstrap — channel setup, router creation, config validation.
+ *
+ * Called once during `EngineService.init()` to wire the engine to its
+ * backing store, stream, search, and subscription transports.
+ */
+import { ExporterService } from '../exporter';
+import { Router } from '../router';
+import { TaskService } from '../task';
+import { ILogger } from '../logger';
+import { SearchService } from '../search';
+import { StoreService } from '../store';
+import { StreamService } from '../stream';
+import { SubService } from '../sub';
+import { HotMeshConfig, HotMeshSettings } from '../../types/hotmesh';
+import { ProviderClient, ProviderTransaction } from '../../types/provider';
+import { StreamDataResponse } from '../../types/stream';
+interface InitContext {
+    namespace: string;
+    appId: string;
+    guid: string;
+    logger: ILogger;
+    search: SearchService<ProviderClient> | null;
+    store: StoreService<ProviderClient, ProviderTransaction> | null;
+    stream: StreamService<ProviderClient, ProviderTransaction> | null;
+    subscribe: SubService<ProviderClient> | null;
+    router: Router<typeof this.stream> | null;
+    taskService: TaskService | null;
+    exporter: ExporterService | null;
+    inited: string;
+    processStreamMessage(streamData: StreamDataResponse): Promise<void>;
+}
+export declare function verifyEngineFields(config: HotMeshConfig): void;
+export declare function initSearchChannel(instance: InitContext, search: ProviderClient, store?: ProviderClient): Promise<void>;
+export declare function initStoreChannel(instance: InitContext, store: ProviderClient): Promise<void>;
+export declare function initSubChannel(instance: InitContext, sub: ProviderClient, store: ProviderClient): Promise<void>;
+export declare function initStreamChannel(instance: InitContext, stream: ProviderClient, store: ProviderClient): Promise<void>;
+export declare function initRouter(instance: InitContext, config: HotMeshConfig): Promise<Router<StreamService<ProviderClient, ProviderTransaction>>>;
+export declare function registerStreamConsumer(instance: InitContext, config: HotMeshConfig): Promise<void>;
+export declare function initServices(instance: InitContext): void;
+export declare function getSettings(instance: InitContext): Promise<HotMeshSettings>;
+export {};

package/build/services/engine/init.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Engine bootstrap — channel setup, router creation, config validation.
+ *
+ * Called once during `EngineService.init()` to wire the engine to its
+ * backing store, stream, search, and subscription transports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSettings = exports.initServices = exports.registerStreamConsumer = exports.initRouter = exports.initStreamChannel = exports.initSubChannel = exports.initStoreChannel = exports.initSearchChannel = exports.verifyEngineFields = void 0;
+const utils_1 = require("../../modules/utils");
+const registry_1 = require("../stream/registry");
+const exporter_1 = require("../exporter");
+const router_1 = require("../router");
+const factory_1 = require("../search/factory");
+const factory_2 = require("../store/factory");
+const factory_3 = require("../stream/factory");
+const factory_4 = require("../sub/factory");
+const task_1 = require("../task");
+const stream_1 = require("../../types/stream");
+function verifyEngineFields(config) {
+    if (!(0, utils_1.identifyProvider)(config.engine.store) ||
+        !(0, utils_1.identifyProvider)(config.engine.stream) ||
+        !(0, utils_1.identifyProvider)(config.engine.sub)) {
+        throw new Error('engine must include `store`, `stream`, and `sub` fields.');
+    }
+}
+exports.verifyEngineFields = verifyEngineFields;
+async function initSearchChannel(instance, search, store) {
+    instance.search = await factory_1.SearchServiceFactory.init(search, store, instance.namespace, instance.appId, instance.logger);
+}
+exports.initSearchChannel = initSearchChannel;
+async function initStoreChannel(instance, store) {
+    instance.store = await factory_2.StoreServiceFactory.init(store, instance.namespace, instance.appId, instance.logger);
+}
+exports.initStoreChannel = initStoreChannel;
+async function initSubChannel(instance, sub, store) {
+    instance.subscribe = await factory_4.SubServiceFactory.init(sub, store, instance.namespace, instance.appId, instance.guid, instance.logger);
+}
+exports.initSubChannel = initSubChannel;
+async function initStreamChannel(instance, stream, store) {
+    instance.stream = await factory_3.StreamServiceFactory.init(stream, store, instance.namespace, instance.appId, instance.logger);
+}
+exports.initStreamChannel = initStreamChannel;
+async function initRouter(instance, config) {
+    const throttle = await instance.store.getThrottleRate(':');
+    return new router_1.Router({
+        namespace: instance.namespace,
+        appId: instance.appId,
+        guid: instance.guid,
+        role: stream_1.StreamRole.ENGINE,
+        reclaimDelay: config.engine.reclaimDelay,
+        reclaimCount: config.engine.reclaimCount,
+        throttle,
+        readonly: config.engine.readonly,
+    }, instance.stream, instance.logger);
+}
+exports.initRouter = initRouter;
+async function registerStreamConsumer(instance, config) {
+    await registry_1.StreamConsumerRegistry.registerEngine(instance.namespace, instance.appId, instance.guid, instance.processStreamMessage.bind(instance), instance.stream, instance.store, instance.logger, {
+        reclaimDelay: config.engine.reclaimDelay,
+        reclaimCount: config.engine.reclaimCount,
+    });
+}
+exports.registerStreamConsumer = registerStreamConsumer;
+function initServices(instance) {
+    instance.taskService = new task_1.TaskService(instance.store, instance.logger);
+    instance.exporter = new exporter_1.ExporterService(instance.appId, instance.store, instance.logger);
+    instance.inited = (0, utils_1.formatISODate)(new Date());
+}
+exports.initServices = initServices;
+async function getSettings(instance) {
+    return await instance.store.getSettings();
+}
+exports.getSettings = getSettings;

package/build/services/engine/pubsub.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pub/sub messaging, subscriptions, and one-time callbacks.
+ *
+ * This module handles the full publish/subscribe lifecycle:
+ *   - `pub()`    → fire-and-forget job trigger
+ *   - `pubsub()` → trigger + await result (with timeout)
+ *   - `sub()/unsub()`   → permanent topic subscriptions
+ *   - `psub()/punsub()` → pattern-based subscriptions
+ *   - `add()`   → raw stream message publish
+ */
+import { Router } from '../router';
+import { StoreService } from '../store';
+import { StreamService } from '../stream';
+import { SubService } from '../sub';
+import { ILogger } from '../logger';
+import { AppVID } from '../../types/app';
+import { ExtensionType, JobData, JobOutput, JobState } from '../../types/job';
+import { ProviderClient, ProviderTransaction } from '../../types/provider';
+import { JobMessageCallback } from '../../types/quorum';
+import { StreamData, StreamDataResponse } from '../../types/stream';
+interface PubSubContext {
+    guid: string;
+    appId: string;
+    store: StoreService<ProviderClient, ProviderTransaction>;
+    stream: StreamService<ProviderClient, ProviderTransaction>;
+    subscribe: SubService<ProviderClient>;
+    router: Router<typeof this.stream> | null;
+    logger: ILogger;
+    jobCallbacks: Record<string, JobMessageCallback>;
+    getVID(vid?: AppVID): Promise<AppVID>;
+    initActivity(topic: string, data?: JobData, context?: JobState): Promise<any>;
+    getState(topic: string, jobId: string): Promise<JobOutput>;
+    getPublishesTopic(context: JobState): Promise<string>;
+}
+export declare function pub(instance: PubSubContext, topic: string, data: JobData, context?: JobState, extended?: ExtensionType): Promise<string>;
+export declare function sub(instance: PubSubContext, topic: string, callback: JobMessageCallback): Promise<void>;
+export declare function unsub(instance: PubSubContext, topic: string): Promise<void>;
+export declare function psub(instance: PubSubContext, wild: string, callback: JobMessageCallback): Promise<void>;
+export declare function punsub(instance: PubSubContext, wild: string): Promise<void>;
+export declare function pubsub(instance: PubSubContext, topic: string, data: JobData, context?: JobState | null, timeout?: number): Promise<JobOutput>;
+export declare function add(instance: PubSubContext, streamData: StreamData | StreamDataResponse): Promise<string>;
+export declare function registerJobCallback(instance: PubSubContext, jobId: string, jobCallback: JobMessageCallback): void;
+export declare function removeJobCallback(instance: PubSubContext, jobId: string): void;
+export declare function hasOneTimeSubscription(context: JobState): boolean;
+/**
+ * Resolves the `publishes` topic for the activity that produced
+ * this job's output — used to notify permanent subscribers.
+ */
+export declare function getPublishesTopic(instance: PubSubContext, context: JobState): Promise<string>;
+export {};

package/build/services/engine/pubsub.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Pub/sub messaging, subscriptions, and one-time callbacks.
+ *
+ * This module handles the full publish/subscribe lifecycle:
+ *   - `pub()`    → fire-and-forget job trigger
+ *   - `pubsub()` → trigger + await result (with timeout)
+ *   - `sub()/unsub()`   → permanent topic subscriptions
+ *   - `psub()/punsub()` → pattern-based subscriptions
+ *   - `add()`   → raw stream message publish
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPublishesTopic = exports.hasOneTimeSubscription = exports.removeJobCallback = exports.registerJobCallback = exports.add = exports.pubsub = exports.punsub = exports.psub = exports.unsub = exports.sub = exports.pub = void 0;
+const enums_1 = require("../../modules/enums");
+const key_1 = require("../../modules/key");
+async function pub(instance, topic, data, context, extended) {
+    const activityHandler = await instance.initActivity(topic, data, context);
+    if (activityHandler) {
+        return await activityHandler.process(extended);
+    }
+    else {
+        throw new Error(`unable to process activity for topic ${topic}`);
+    }
+}
+exports.pub = pub;
+async function sub(instance, topic, callback) {
+    const subscriptionCallback = createSubscriptionCallback(instance, callback);
+    return await instance.subscribe.subscribe(key_1.KeyType.QUORUM, subscriptionCallback, instance.appId, topic);
+}
+exports.sub = sub;
+async function unsub(instance, topic) {
+    return await instance.subscribe.unsubscribe(key_1.KeyType.QUORUM, instance.appId, topic);
+}
+exports.unsub = unsub;
+async function psub(instance, wild, callback) {
+    const subscriptionCallback = createSubscriptionCallback(instance, callback);
+    return await instance.subscribe.psubscribe(key_1.KeyType.QUORUM, subscriptionCallback, instance.appId, wild);
+}
+exports.psub = psub;
+async function punsub(instance, wild) {
+    return await instance.subscribe.punsubscribe(key_1.KeyType.QUORUM, instance.appId, wild);
+}
+exports.punsub = punsub;
+async function pubsub(instance, topic, data, context, timeout = enums_1.HMSH_OTT_WAIT_TIME) {
+    context = {
+        metadata: {
+            ngn: instance.guid,
+            trc: context?.metadata?.trc,
+            spn: context?.metadata?.spn,
+        },
+    };
+    const jobId = await pub(instance, topic, data, context);
+    return new Promise((resolve, reject) => {
+        registerJobCallback(instance, jobId, (topic, output) => {
+            if (output.metadata.err) {
+                const error = JSON.parse(output.metadata.err);
+                reject({
+                    error,
+                    job_id: output.metadata.jid,
+                });
+            }
+            else {
+                resolve(output);
+            }
+        });
+        setTimeout(() => {
+            removeJobCallback(instance, jobId);
+            reject({
+                code: enums_1.HMSH_CODE_TIMEOUT,
+                message: 'timeout',
+                job_id: jobId,
+            });
+        }, timeout);
+    });
+}
+exports.pubsub = pubsub;
+async function add(instance, streamData) {
+    return (await instance.router?.publishMessage(null, streamData));
+}
+exports.add = add;
+function registerJobCallback(instance, jobId, jobCallback) {
+    instance.jobCallbacks[jobId] = jobCallback;
+}
+exports.registerJobCallback = registerJobCallback;
+function removeJobCallback(instance, jobId) {
+    delete instance.jobCallbacks[jobId];
+}
+exports.removeJobCallback = removeJobCallback;
+function hasOneTimeSubscription(context) {
+    return Boolean(context.metadata.ngn);
+}
+exports.hasOneTimeSubscription = hasOneTimeSubscription;
+/**
+ * Resolves the `publishes` topic for the activity that produced
+ * this job's output — used to notify permanent subscribers.
+ */
+async function getPublishesTopic(instance, context) {
+    const config = await instance.getVID();
+    const activityId = context.metadata.aid || context['$self']?.output?.metadata?.aid;
+    const schema = await instance.store.getSchema(activityId, config);
+    return schema.publishes;
+}
+exports.getPublishesTopic = getPublishesTopic;
+// ── helpers ────────────────────────────────────────────────────────
+/**
+ * Wraps a user-provided callback to handle reference-based payloads.
+ * When `_ref` is true the published message was too large, so
+ * we fetch the full job state before invoking the callback.
+ */
+function createSubscriptionCallback(instance, callback) {
+    return async (topic, message) => {
+        let jobOutput = message.job;
+        if (message._ref && message.job?.metadata) {
+            jobOutput = await instance.getState(message.job.metadata.tpc, message.job.metadata.jid);
+        }
+        callback(message.topic, jobOutput);
+    };
+}

package/build/services/engine/reporting.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Stats queries and job-ID lookups.
+ *
+ * Builds a `GetStatsOptions` query by instantiating a Trigger activity
+ * to resolve the job key and granularity, then delegates to
+ * ReporterService for the actual data retrieval.
+ */
+import { AppVID } from '../../types/app';
+import { JobData } from '../../types/job';
+import { GetStatsOptions, IdsResponse, JobStatsInput, StatsResponse } from '../../types/stats';
+interface ReportingContext {
+    getVID(vid?: AppVID): Promise<AppVID>;
+    initActivity(topic: string, data?: JobData): Promise<any>;
+    store: any;
+    logger: any;
+}
+export declare function getStats(instance: ReportingContext, topic: string, query: JobStatsInput): Promise<StatsResponse>;
+export declare function getIds(instance: ReportingContext, topic: string, query: JobStatsInput, queryFacets?: string[]): Promise<IdsResponse>;
+export declare function resolveQuery(instance: ReportingContext, topic: string, query: JobStatsInput): Promise<GetStatsOptions>;
+export {};

package/build/services/engine/reporting.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Stats queries and job-ID lookups.
+ *
+ * Builds a `GetStatsOptions` query by instantiating a Trigger activity
+ * to resolve the job key and granularity, then delegates to
+ * ReporterService for the actual data retrieval.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveQuery = exports.getIds = exports.getStats = void 0;
+const reporter_1 = require("../reporter");
+async function getStats(instance, topic, query) {
+    const vid = await instance.getVID();
+    const reporter = new reporter_1.ReporterService(vid, instance.store, instance.logger);
+    const resolvedQuery = await resolveQuery(instance, topic, query);
+    return await reporter.getStats(resolvedQuery);
+}
+exports.getStats = getStats;
+async function getIds(instance, topic, query, queryFacets = []) {
+    const vid = await instance.getVID();
+    const reporter = new reporter_1.ReporterService(vid, instance.store, instance.logger);
+    const resolvedQuery = await resolveQuery(instance, topic, query);
+    return await reporter.getIds(resolvedQuery, queryFacets);
+}
+exports.getIds = getIds;
+async function resolveQuery(instance, topic, query) {
+    const trigger = (await instance.initActivity(topic, query.data));
+    await trigger.getState();
+    return {
+        end: query.end,
+        start: query.start,
+        range: query.range,
+        granularity: trigger.resolveGranularity(),
+        key: trigger.resolveJobKey(trigger.createInputContext()),
+        sparse: query.sparse,
+    };
+}
+exports.resolveQuery = resolveQuery;

package/build/services/engine/schema.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Activity schema lookup and handler instantiation.
+ *
+ * Every stream message targets an activity node in the compiled DAG.
+ * This module resolves the activity's schema (from the store) and
+ * creates the correct handler subclass (Trigger, Worker, Hook, …).
+ */
+import { StoreService } from '../store';
+import { ILogger } from '../logger';
+import { AppVID } from '../../types/app';
+import { ActivityType } from '../../types/activity';
+import { JobState, JobData } from '../../types/job';
+import { ProviderClient, ProviderTransaction } from '../../types/provider';
+interface SchemaContext {
+    appId: string;
+    store: StoreService<ProviderClient, ProviderTransaction>;
+    logger: ILogger;
+    getVID(vid?: AppVID): Promise<AppVID>;
+}
+export declare function initActivity(instance: SchemaContext, topic: string, data?: JobData, context?: JobState): Promise<any>;
+export declare function getSchema(instance: SchemaContext, topic: string): Promise<[activityId: string, schema: ActivityType]>;
+export declare function isPrivate(topic: string): boolean;
+export {};

package/build/services/engine/schema.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Activity schema lookup and handler instantiation.
+ *
+ * Every stream message targets an activity node in the compiled DAG.
+ * This module resolves the activity's schema (from the store) and
+ * creates the correct handler subclass (Trigger, Worker, Hook, …).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPrivate = exports.getSchema = exports.initActivity = void 0;
+const utils_1 = require("../../modules/utils");
+const activities_1 = __importDefault(require("../activities"));
+async function initActivity(instance, topic, data = {}, context) {
+    const [activityId, schema] = await getSchema(instance, topic);
+    if (!schema) {
+        throw new Error(`Activity schema not found for "${activityId}" (topic: ${topic}) in app ${instance.appId}`);
+    }
+    const ActivityHandler = activities_1.default[schema.type];
+    if (ActivityHandler) {
+        const utc = (0, utils_1.formatISODate)(new Date());
+        const metadata = {
+            aid: activityId,
+            atp: schema.type,
+            stp: schema.subtype,
+            ac: utc,
+            au: utc,
+        };
+        const hook = null;
+        return new ActivityHandler(schema, data, metadata, hook, instance, context);
+    }
+    else {
+        throw new Error(`activity type ${schema.type} not found`);
+    }
+}
+exports.initActivity = initActivity;
+async function getSchema(instance, topic) {
+    const app = (await instance.store.getApp(instance.appId));
+    if (!app) {
+        throw new Error(`no app found for id ${instance.appId}`);
+    }
+    if (isPrivate(topic)) {
+        const activityId = topic.substring(1);
+        const schema = await instance.store.getSchema(activityId, await instance.getVID(app));
+        return [activityId, schema];
+    }
+    else {
+        const activityId = await instance.store.getSubscription(topic, await instance.getVID(app));
+        if (activityId) {
+            const schema = await instance.store.getSchema(activityId, await instance.getVID(app));
+            return [activityId, schema];
+        }
+    }
+    throw new Error(`no subscription found for topic ${topic} in app ${instance.appId} for app version ${app.version}`);
+}
+exports.getSchema = getSchema;
+function isPrivate(topic) {
+    return topic.startsWith('.');
+}
+exports.isPrivate = isPrivate;

package/build/services/engine/signal.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Signal delivery to paused hook activities.
+ *
+ * Signals resume workflows waiting on external events:
+ *   - `signal()`    → single webhook delivery to a specific hook
+ *   - `signalAll()` → fan-out to all workflows matching a query
+ *   - `hookTime()`  → time-based hook awaken (sleep/cron)
+ *
+ * Also provides the quorum-level task processors for web/time hooks
+ * and the router throttle control.
+ */
+import { Router } from '../router';
+import { StoreService } from '../store';
+import { StreamService } from '../stream';
+import { SubService } from '../sub';
+import { TaskService } from '../task';
+import { ILogger } from '../logger';
+import { AppVID } from '../../types/app';
+import { JobData } from '../../types/job';
+import { ProviderClient, ProviderTransaction } from '../../types/provider';
+import { JobStatsInput } from '../../types/stats';
+import { StreamCode, StreamStatus } from '../../types/stream';
+import { WorkListTaskType } from '../../types/task';
+import { HookInterface } from '../../types/hook';
+import { JobMessageCallback } from '../../types/quorum';
+import { JobOutput } from '../../types/job';
+interface SignalContext {
+    guid: string;
+    appId: string;
+    store: StoreService<ProviderClient, ProviderTransaction>;
+    stream: StreamService<ProviderClient, ProviderTransaction>;
+    subscribe: SubService<ProviderClient>;
+    router: Router<typeof this.stream> | null;
+    taskService: TaskService;
+    logger: ILogger;
+    jobCallbacks: Record<string, JobMessageCallback>;
+    getVID(vid?: AppVID): Promise<AppVID>;
+    getSchema(topic: string): Promise<[string, any]>;
+    resolveQuery(topic: string, query: JobStatsInput): Promise<any>;
+    interrupt(topic: string, jobId: string, options?: any): Promise<string>;
+}
+/**
+ * Delivers a signal (data payload) to a paused hook activity,
+ * resuming its Leg 2 execution.
+ */
+export declare function signal(instance: SignalContext, topic: string, data: JobData, status?: StreamStatus, code?: StreamCode, transaction?: ProviderTransaction): Promise<string>;
+export declare function hookTime(instance: SignalContext, jobId: string, gId: string, topicOrActivity: string, type?: WorkListTaskType): Promise<string | void>;
+/**
+ * Fan-out variant that delivers data to all paused workflows
+ * matching a search query.
+ */
+export declare function signalAll(instance: SignalContext, hookTopic: string, data: JobData, keyResolver: JobStatsInput, queryFacets?: string[]): Promise<string[]>;
+export declare function processWebHooks(instance: SignalContext, signalFn: HookInterface): Promise<void>;
+export declare function processTimeHooks(instance: SignalContext, hookTimeFn: (jobId: string, gId: string, activityId: string, type: WorkListTaskType) => Promise<void>): Promise<void>;
+export declare function throttle(instance: SignalContext, delayInMillis: number): Promise<void>;
+export declare function routeToSubscribers(instance: SignalContext, topic: string, message: JobOutput): void;
+export {};

package/build/services/engine/signal.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Signal delivery to paused hook activities.
+ *
+ * Signals resume workflows waiting on external events:
+ *   - `signal()`    → single webhook delivery to a specific hook
+ *   - `signalAll()` → fan-out to all workflows matching a query
+ *   - `hookTime()`  → time-based hook awaken (sleep/cron)
+ *
+ * Also provides the quorum-level task processors for web/time hooks
+ * and the router throttle control.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeToSubscribers = exports.throttle = exports.processTimeHooks = exports.processWebHooks = exports.signalAll = exports.hookTime = exports.signal = void 0;
+const key_1 = require("../../modules/key");
+const utils_1 = require("../../modules/utils");
+const reporter_1 = require("../reporter");
+const task_1 = require("../task");
+const stream_1 = require("../../types/stream");
+/**
+ * Delivers a signal (data payload) to a paused hook activity,
+ * resuming its Leg 2 execution.
+ */
+async function signal(instance, topic, data, status = stream_1.StreamStatus.SUCCESS, code = 200, transaction) {
+    const hookRule = await instance.taskService.getHookRule(topic);
+    const [aid] = await instance.getSchema(`.${hookRule.to}`);
+    const streamData = {
+        type: stream_1.StreamDataType.WEBHOOK,
+        status,
+        code,
+        metadata: {
+            guid: (0, utils_1.guid)(),
+            aid,
+            topic,
+        },
+        data,
+    };
+    return (await instance.router?.publishMessage(null, streamData, transaction));
+}
+exports.signal = signal;
+async function hookTime(instance, jobId, gId, topicOrActivity, type) {
+    if (type === 'interrupt' || type === 'expire') {
+        return await instance.interrupt(topicOrActivity, jobId, {
+            suppress: true,
+            expire: 1,
+        });
+    }
+    const [aid, ...dimensions] = topicOrActivity.split(',');
+    const dad = `,${dimensions.join(',')}`;
+    const streamData = {
+        type: stream_1.StreamDataType.TIMEHOOK,
+        metadata: {
+            guid: (0, utils_1.guid)(),
+            jid: jobId,
+            gid: gId,
+            dad,
+            aid,
+        },
+        data: { timestamp: Date.now() },
+    };
+    await instance.router?.publishMessage(null, streamData);
+}
+exports.hookTime = hookTime;
+/**
+ * Fan-out variant that delivers data to all paused workflows
+ * matching a search query.
+ */
+async function signalAll(instance, hookTopic, data, keyResolver, queryFacets = []) {
+    const config = await instance.getVID();
+    const hookRule = await instance.taskService.getHookRule(hookTopic);
+    if (hookRule) {
+        const subscriptionTopic = await (0, utils_1.getSubscriptionTopic)(hookRule.to, instance.store, config);
+        const resolvedQuery = await instance.resolveQuery(subscriptionTopic, keyResolver);
+        const reporter = new reporter_1.ReporterService(config, instance.store, instance.logger);
+        const workItems = await reporter.getWorkItems(resolvedQuery, queryFacets);
+        if (workItems.length) {
+            const taskService = new task_1.TaskService(instance.store, instance.logger);
+            await taskService.enqueueWorkItems(workItems.map((workItem) => [
+                hookTopic,
+                workItem,
+                keyResolver.scrub || false,
+                JSON.stringify(data),
+            ].join(key_1.VALSEP)));
+            instance.subscribe.publish(key_1.KeyType.QUORUM, { type: 'work', originator: instance.guid }, instance.appId);
+        }
+        return workItems;
+    }
+    else {
+        throw new Error(`unable to find hook rule for topic ${hookTopic}`);
+    }
+}
+exports.signalAll = signalAll;
+async function processWebHooks(instance, signalFn) {
+    instance.taskService.processWebHooks(signalFn);
+}
+exports.processWebHooks = processWebHooks;
+async function processTimeHooks(instance, hookTimeFn) {
+    instance.taskService.processTimeHooks(hookTimeFn);
+}
+exports.processTimeHooks = processTimeHooks;
+async function throttle(instance, delayInMillis) {
+    try {
+        instance.router?.setThrottle(delayInMillis);
+    }
+    catch (e) {
+        instance.logger.error('engine-throttle-error', { error: e });
+    }
+}
+exports.throttle = throttle;
+function routeToSubscribers(instance, topic, message) {
+    const jobCallback = instance.jobCallbacks[message.metadata.jid];
+    if (jobCallback) {
+        delete instance.jobCallbacks[message.metadata.jid];
+        jobCallback(topic, message);
+    }
+}
+exports.routeToSubscribers = routeToSubscribers;

package/build/services/engine/state.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Job state retrieval, export, and symbol compression.
+ *
+ * Provides read access to job data at various granularities:
+ *   - `getState()`      → full hydrated job tree
+ *   - `getQueryState()` → specific fields only
+ *   - `getRaw()`        → raw hash data (no hydration)
+ *   - `getStatus()`     → job status code only
+ *   - `export()`        → full export via ExporterService
+ */
+import { ExporterService } from '../exporter';
+import { StoreService } from '../store';
+import { ILogger } from '../logger';
+import { AppVID } from '../../types/app';
+import { ExportOptions, JobExport } from '../../types/exporter';
+import { JobOutput, JobStatus } from '../../types/job';
+import { ProviderClient, ProviderTransaction } from '../../types/provider';
+import { StringAnyType, StringStringType } from '../../types/serializer';
+interface StateContext {
+    appId: string;
+    store: StoreService<ProviderClient, ProviderTransaction>;
+    exporter: ExporterService;
+    logger: ILogger;
+    getVID(vid?: AppVID): Promise<AppVID>;
+}
+export declare function exportJob(instance: StateContext, jobId: string, options?: ExportOptions): Promise<JobExport>;
+export declare function getRaw(instance: StateContext, jobId: string): Promise<StringStringType>;
+export declare function getStatus(instance: StateContext, jobId: string): Promise<JobStatus>;
+export declare function getState(instance: StateContext, topic: string, jobId: string): Promise<JobOutput>;
+export declare function getQueryState(instance: StateContext, jobId: string, fields: string[]): Promise<StringAnyType>;
+/**
+ * @deprecated
+ */
+export declare function compress(instance: StateContext, terms: string[]): Promise<boolean>;
+export {};