@hotmeshio/hotmesh 0.13.0 → 0.14.0

package/build/services/activities/activity.d.ts

@@ -1,192 +0,0 @@
-import { EngineService } from '../engine';
-import { ILogger } from '../logger';
-import { StoreService } from '../store';
-import { ActivityData, ActivityLeg, ActivityMetadata, ActivityType } from '../../types/activity';
-import { ProviderClient, ProviderTransaction, TransactionResultList } from '../../types/provider';
-import { JobState, JobStatus } from '../../types/job';
-import { StringAnyType } from '../../types/serializer';
-import { StreamCode, StreamData, StreamStatus } from '../../types/stream';
-/**
- * Base class for all HotMesh activity types. Activities are the execution
- * units within a YAML-defined workflow graph. Each activity represents a
- * node in a Directed Acyclic Graph (DAG) that the engine orchestrates.
- *
- * ## Activity Categories
- *
- * Activities fall into three execution categories:
- *
- * - **Category A (Duplex)**: Two-phase activities with Leg 1 (dispatch) and
- *   Leg 2 (response). Used by `Worker` and `Await`. Leg 1
- *   publishes a message and waits; Leg 2 handles the response via
- *   `processEvent` and transitions to adjacent activities.
- *
- * - **Category B (Leg1-only with children)**: Single-phase activities that
- *   execute work and transition to children using the crash-safe
- *   `executeLeg1StepProtocol`. Used by `Hook` (passthrough mode),
- *   `Signal`, and `Interrupt` (target mode).
- *
- * - **Category C (Leg1-only, no children)**: Terminal activities that
- *   execute without spawning children. Used by `Interrupt` (self mode).
- *
- * ## Shared YAML Configuration
- *
- * All activity types support these base properties in the YAML descriptor:
- *
- * | Property             | Type    | Description |
- * |----------------------|---------|-------------|
- * | `type`               | string  | Activity type: `trigger`, `worker`, `await`, `hook`, `signal`, `interrupt`, `cycle` |
- * | `title`              | string  | Human-readable label for the activity |
- * | `input.schema`       | object  | JSON Schema for input validation |
- * | `input.maps`         | object  | Maps data from other activities into this activity's input |
- * | `output.schema`      | object  | JSON Schema for output validation |
- * | `output.maps`        | object  | Maps/transforms the activity's own output data |
- * | `job.maps`           | object  | Maps activity data to the shared job state |
- * | `emit`               | boolean | If `true`, emits a message to the graph's `publishes` topic |
- * | `persist`            | boolean | If `true`, emits the job-completed event while keeping the job active |
- * | `expire`             | number  | Seconds until the job expires after completion (`-1` = forever) |
- * | `statusThreshold`    | number  | Custom semaphore threshold for Dynamic Activation Control |
- * | `cycle`              | boolean | If `true`, leaves Leg 2 open so the activity can be re-entered |
- *
- * ## Data Mapping Syntax
- *
- * Mapping expressions use curly-brace references to bind data between
- * activities and the shared job state:
- *
- * ```yaml
- * input:
- *   maps:
- *     x: '{t1.output.data.fieldName}'      # reference another activity's output
- *     y: '{$self.output.data.fieldName}'    # reference own output
- *     z: '{$job.data.fieldName}'            # reference shared job state
- *     s: '{$app.settings.configKey}'        # reference app-level settings
- * ```
- *
- * @see {@link https://hotmeshio.github.io/sdk-typescript/docs/quickstart | Quick Start Guide}
- * @see [Model Driven Development](https://hotmeshio.github.io/sdk-typescript/docs/model_driven_development)
- */
-declare class Activity {
-    config: ActivityType;
-    data: ActivityData;
-    hook: ActivityData;
-    metadata: ActivityMetadata;
-    /** @hidden */
-    store: StoreService<ProviderClient, ProviderTransaction>;
-    context: JobState;
-    engine: EngineService;
-    logger: ILogger;
-    status: StreamStatus;
-    code: StreamCode;
-    leg: ActivityLeg;
-    adjacencyList: StreamData[];
-    adjacentIndex: number;
-    guidLedger: number;
-    constructor(config: ActivityType, data: ActivityData, metadata: ActivityMetadata, hook: ActivityData | null, engine: EngineService, context?: JobState);
-    setLeg(leg: ActivityLeg): void;
-    /**
-     * A job is assumed to be complete when its status (a semaphore)
-     * reaches `0`. A different threshold can be set in the
-     * activity YAML, in support of Dynamic Activation Control.
-     */
-    mapStatusThreshold(): number;
-    /**
-     * Upon entering leg 1 of a duplexed activity
-     */
-    verifyEntry(): Promise<void>;
-    /**
-     * Upon entering leg 2 of a duplexed activity.
-     * Increments both the activity ledger (+1) and GUID ledger (+1).
-     * Stores the GUID ledger value for step-level resume decisions.
-     */
-    verifyReentry(): Promise<number>;
-    processEvent(status?: StreamStatus, code?: StreamCode, type?: 'hook' | 'output'): Promise<void>;
-    /**
-     * Executes the 3-step Leg2 protocol using GUID ledger for
-     * crash-safe resume. Each step bundles durable writes with
-     * its concluding digit update in a single transaction.
-     *
-     * @returns true if this transition caused the job to complete
-     */
-    executeStepProtocol(delta: number, shouldFinalize: boolean): Promise<boolean>;
-    /**
-     * Extracts the thresholdHit value from transaction results.
-     * The setStatusAndCollateGuid result is the last item.
-     */
-    resolveThresholdHit(results: TransactionResultList): boolean;
-    /**
-     * Extracts the job status from the last result of a transaction.
-     * Used by subclass Leg1 process methods for telemetry.
-     */
-    resolveStatus(multiResponse: TransactionResultList): number;
-    /**
-     * Leg1 entry verification for Category B activities (Leg1-only with children).
-     * Returns true if this is a resume (Leg1 already completed on a prior attempt).
-     * On resume, loads the GUID ledger for step-level resume decisions.
-     */
-    verifyLeg1Entry(): Promise<boolean>;
-    /**
-     * Executes the 3-step Leg1 protocol for Category B activities
-     * (Leg1-only with children, e.g., Hook passthrough, Signal, Interrupt-another).
-     * Uses the incoming Leg1 message GUID as the GUID ledger key.
-     *
-     * Step A: setState + notarizeLeg1Completion + step1 markers (transaction 1)
-     * Step B: publish children + step2 markers + setStatusAndCollateGuid (transaction 2)
-     * Step C: if edge → runJobCompletionTasks + step3 markers + finalize (transaction 3)
-     *
-     * @returns true if this transition caused the job to complete
-     */
-    executeLeg1StepProtocol(delta: number): Promise<boolean>;
-    mapJobData(): void;
-    mapInputData(): void;
-    mapOutputData(): void;
-    registerTimeout(): Promise<void>;
-    /**
-     * Any StreamMessage with a status of ERROR is bound to the activity
-     */
-    bindActivityError(data: Record<string, unknown>): void;
-    /**
-     * unhandled activity errors (activities that return an ERROR StreamMessage
-     * status and have no adjacent children to transition to) are bound to the job
-     */
-    bindJobError(data: Record<string, unknown>): void;
-    getTriggerConfig(): Promise<ActivityType>;
-    getJobStatus(): null | number;
-    setStatus(amount: number, transaction?: ProviderTransaction): Promise<void | any>;
-    authorizeEntry(_state: StringAnyType): string[];
-    bindDimensionalAddress(state: StringAnyType): void;
-    setState(transaction?: ProviderTransaction): Promise<string>;
-    bindJobMetadata(): void;
-    bindActivityMetadata(): void;
-    bindJobState(state: StringAnyType): Promise<void>;
-    bindActivityState(state: StringAnyType): void;
-    bindJobMetadataPaths(): string[];
-    bindActivityMetadataPaths(): string[];
-    getState(): Promise<void>;
-    /**
-     * if the job is created/deleted/created with the same key,
-     * the 'gid' ensures no stale messages (such as sleep delays)
-     * enter the workstream. Any message with a mismatched gid
-     * belongs to a prior job and can safely be ignored/dropped.
-     */
-    assertGenerationalId(jobGID: string, msgGID?: string): void;
-    initDimensionalAddress(dad: string): void;
-    initSelf(context: StringAnyType): JobState;
-    initPolicies(context: JobState): void;
-    bindActivityData(type: 'output' | 'hook'): void;
-    resolveDad(): string;
-    resolveAdjacentDad(): string;
-    filterAdjacent(): Promise<StreamData[]>;
-    isJobComplete(jobStatus: JobStatus): boolean;
-    shouldEmit(): boolean;
-    /**
-     * emits the job completed event while leaving the job active, allowing
-     * a `main` thread to exit while other threads continue to run.
-     * @private
-     */
-    shouldPersistJob(): boolean;
-    /**
-     * A job with a vale < -100_000_000 is considered interrupted,
-     * as the interruption event decrements the job status by 1billion.
-     */
-    jobWasInterrupted(jobStatus: JobStatus): boolean;
-}
-export { Activity, ActivityType };