@hotmeshio/long-tail 0.1.7 → 0.1.9

package/build/api/yaml-workflows.js

@@ -66,6 +66,21 @@ function isNotFoundError(err) {
 // ---------------------------------------------------------------------------
 // CRUD
 // ---------------------------------------------------------------------------
+/**
+ * List YAML workflows with optional filtering and pagination.
+ *
+ * Delegates to the DB layer. Returns 404 when a filter references an invalid UUID.
+ *
+ * @param input.status — lifecycle filter (draft, deployed, active, archived)
+ * @param input.graph_topic — filter by the HotMesh subscription topic
+ * @param input.app_id — filter by namespace (MCP server name)
+ * @param input.search — free-text search across workflow name/description
+ * @param input.source_workflow_id — filter by the execution trace this workflow was compiled from
+ * @param input.set_id — filter by compositional set membership
+ * @param input.limit — max rows to return
+ * @param input.offset — pagination offset
+ * @returns `{ status: 200, data: YamlWorkflow[] }` matching workflows
+ */
 async function listYamlWorkflows(input) {
     try {
         const result = await yamlDb.listYamlWorkflows({
@@ -87,6 +102,25 @@ async function listYamlWorkflows(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Compile an execution trace into a new YAML workflow (draft).
+ *
+ * Validates that the source execution did not exhaust its tool rounds, checks for
+ * topic collisions in the target namespace, then delegates to the LLM-based YAML
+ * generator. The resulting YAML, schemas, and activity manifest are persisted as a
+ * new draft record. Auto-derived tags are merged with any user-supplied tags.
+ *
+ * @param input.workflow_id — ID of the source execution trace to compile from
+ * @param input.task_queue — HotMesh task queue the source execution ran on
+ * @param input.workflow_name — type name of the source workflow
+ * @param input.name — tool name for the new workflow (no dashes; used to derive the topic)
+ * @param input.description — human-readable description passed to the generator
+ * @param input.app_id — target namespace (defaults to "longtail")
+ * @param input.subscribes — explicit subscription topic override (otherwise derived from name)
+ * @param input.tags — additional tags to merge with auto-derived tags
+ * @param input.compilation_feedback — natural-language feedback to steer the LLM compilation
+ * @returns `{ status: 201, data: YamlWorkflow }` the newly created draft record
+ */
 async function createYamlWorkflow(input) {
     try {
         const { workflow_id, task_queue, workflow_name, name, description, app_id, subscribes, tags: userTags, compilation_feedback } = input;
@@ -163,6 +197,23 @@ async function createYamlWorkflow(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Create a YAML workflow directly from user-supplied YAML content (no compilation).
+ *
+ * Sanitizes the name, app_id, and graph_topic to lowercase alphanumeric characters.
+ * Rewrites the `subscribes`, `id`, and `topic` fields inside the YAML to match the
+ * sanitized values. Checks for topic collisions before persisting.
+ *
+ * @param input.name — tool name (sanitized to lowercase alphanumeric, periods, dashes, underscores)
+ * @param input.description — human-readable description; also stored as original_prompt
+ * @param input.yaml_content — raw HotMesh YAML definition
+ * @param input.input_schema — JSON Schema describing the workflow's input (defaults to empty object)
+ * @param input.activity_manifest — list of activity declarations (defaults to empty array)
+ * @param input.tags — classification tags (defaults to empty array)
+ * @param input.app_id — target namespace / MCP server name (defaults to "longtail", sanitized to lowercase alphanumeric)
+ * @param input.graph_topic — subscription topic override (defaults to sanitized name; overridden by `subscribes` in YAML if present)
+ * @returns `{ status: 200, data: YamlWorkflow }` the persisted workflow record
+ */
 async function createYamlWorkflowDirect(input) {
     try {
         const { name, description, yaml_content, input_schema, activity_manifest, tags, app_id, graph_topic } = input;
@@ -219,6 +270,11 @@ async function createYamlWorkflowDirect(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Retrieve all distinct app_id namespaces that have at least one YAML workflow.
+ *
+ * @returns `{ status: 200, data: { app_ids: string[] } }` sorted list of namespace identifiers
+ */
 async function getAppIds() {
     try {
         const appIds = await yamlDb.getDistinctAppIds();
@@ -228,6 +284,12 @@ async function getAppIds() {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Fetch a single YAML workflow by its primary key.
+ *
+ * @param input.id — UUID of the workflow record
+ * @returns `{ status: 200, data: YamlWorkflow }` the full workflow record, or 404 if not found
+ */
 async function getYamlWorkflow(input) {
     try {
         const wf = await yamlDb.getYamlWorkflow(input.id);
@@ -243,6 +305,15 @@ async function getYamlWorkflow(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Partially update a YAML workflow record.
+ *
+ * Accepts arbitrary fields beyond `id` and forwards them to the DB update layer.
+ *
+ * @param input.id — UUID of the workflow to update
+ * @param input.[key] — any mutable workflow fields (name, description, yaml_content, tags, etc.)
+ * @returns `{ status: 200, data: YamlWorkflow }` the updated record, or 404 if not found
+ */
 async function updateYamlWorkflow(input) {
     try {
         const { id, ...fields } = input;
@@ -259,6 +330,19 @@ async function updateYamlWorkflow(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Re-compile an existing YAML workflow from its original execution trace.
+ *
+ * Looks up the source workflow reference, re-runs the LLM-based YAML generator, and
+ * overwrites the YAML content, schemas, manifest, and tags in place. When
+ * compilation_feedback is provided, the current YAML is passed as priorFailedYaml so
+ * the generator can incorporate the feedback. Archived workflows cannot be regenerated.
+ *
+ * @param input.id — UUID of the workflow to regenerate
+ * @param input.task_queue — override the task queue (otherwise resolved from the source task record)
+ * @param input.compilation_feedback — natural-language feedback to steer the re-compilation
+ * @returns `{ status: 200, data: YamlWorkflow }` the updated record with new YAML content
+ */
 async function regenerateYamlWorkflow(input) {
     try {
         const wf = await yamlDb.getYamlWorkflow(input.id);
@@ -307,6 +391,15 @@ async function regenerateYamlWorkflow(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Permanently delete a YAML workflow record.
+ *
+ * Only draft or archived workflows can be deleted. Active or deployed workflows must
+ * be archived first.
+ *
+ * @param input.id — UUID of the workflow to delete
+ * @returns `{ status: 200, data: { deleted: true } }` on success, or 400 if the workflow is active/deployed
+ */
 async function deleteYamlWorkflow(input) {
     try {
         const wf = await yamlDb.getYamlWorkflow(input.id);
@@ -329,6 +422,16 @@ async function deleteYamlWorkflow(input) {
 // ---------------------------------------------------------------------------
 // Deployment
 // ---------------------------------------------------------------------------
+/**
+ * Deploy a YAML workflow and all sibling workflows sharing its app_id namespace.
+ *
+ * Merges and deploys the full app_id YAML, registers HotMesh workers for every
+ * non-archived sibling, transitions draft/deployed siblings to active, and marks
+ * the app_id content as deployed. Uses the app_version declared in the workflow record.
+ *
+ * @param input.id — UUID of the workflow to deploy
+ * @returns `{ status: 200, data: YamlWorkflow }` the refreshed workflow record after deployment
+ */
 async function deployYamlWorkflow(input) {
     try {
         const wf = await yamlDb.getYamlWorkflow(input.id);
@@ -363,6 +466,16 @@ async function deployYamlWorkflow(input) {
         };
     }
 }
+/**
+ * Activate a previously deployed YAML workflow and its app_id siblings.
+ *
+ * Calls the deployer to activate the app_id at its current version, then registers
+ * HotMesh workers for all sibling workflows. Siblings in "deployed" status are
+ * transitioned to "active". The workflow must already be in deployed or active status.
+ *
+ * @param input.id — UUID of the workflow to activate
+ * @returns `{ status: 200, data: YamlWorkflow }` the refreshed workflow record after activation
+ */
 async function activateYamlWorkflow(input) {
     try {
         const wf = await yamlDb.getYamlWorkflow(input.id);
@@ -391,6 +504,21 @@ async function activateYamlWorkflow(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Invoke an active YAML workflow, executing its DAG pipeline.
+ *
+ * The workflow must be in "active" status. Delegates to the invoke service which
+ * starts the HotMesh execution. Supports both synchronous (wait for result) and
+ * asynchronous (fire-and-forget) invocation modes.
+ *
+ * @param input.id — UUID of the workflow to invoke
+ * @param input.data — input payload passed to the workflow's entry point
+ * @param input.sync — when true, block until the workflow completes and return its output
+ * @param input.timeout — max milliseconds to wait when sync is true
+ * @param input.execute_as — override identity for the execution context
+ * @param auth — authenticated user context; userId is forwarded to the invoke service
+ * @returns `{ status: 200, data: ... }` workflow execution result (sync) or job metadata (async)
+ */
 async function invokeYamlWorkflow(input, auth) {
     try {
         const wf = await yamlDb.getYamlWorkflow(input.id);
@@ -416,6 +544,16 @@ async function invokeYamlWorkflow(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Archive a YAML workflow, removing it from active service.
+ *
+ * If the workflow is currently active, its HotMesh engine is stopped before
+ * transitioning the status to "archived". Archived workflows cannot be invoked
+ * or regenerated but can still be viewed or deleted.
+ *
+ * @param input.id — UUID of the workflow to archive
+ * @returns `{ status: 200, data: YamlWorkflow }` the updated record with status "archived"
+ */
 async function archiveYamlWorkflow(input) {
     try {
         const wf = await yamlDb.getYamlWorkflow(input.id);
@@ -438,6 +576,16 @@ async function archiveYamlWorkflow(input) {
 // ---------------------------------------------------------------------------
 // Versions
 // ---------------------------------------------------------------------------
+/**
+ * Retrieve the version history for a YAML workflow.
+ *
+ * Returns a paginated list of version snapshots ordered by version number.
+ *
+ * @param input.id — UUID of the workflow
+ * @param input.limit — max versions to return (defaults to 20)
+ * @param input.offset — pagination offset (defaults to 0)
+ * @returns `{ status: 200, data: VersionSnapshot[] }` paginated version history
+ */
 async function getVersionHistory(input) {
     try {
         const limit = input.limit ?? 20;
@@ -452,6 +600,15 @@ async function getVersionHistory(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Retrieve a specific version snapshot of a YAML workflow.
+ *
+ * Validates that the version number is a positive integer before querying.
+ *
+ * @param input.id — UUID of the workflow
+ * @param input.version — 1-based version number to retrieve
+ * @returns `{ status: 200, data: VersionSnapshot }` the snapshot at the requested version, or 404
+ */
 async function getVersionSnapshot(input) {
     try {
         const version = input.version;
@@ -471,6 +628,16 @@ async function getVersionSnapshot(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Retrieve the raw YAML content for a workflow, optionally at a specific version.
+ *
+ * When a version is provided, fetches from the version snapshot table. Otherwise
+ * returns the current yaml_content from the live workflow record.
+ *
+ * @param input.id — UUID of the workflow
+ * @param input.version — optional version number; when omitted, returns the current content
+ * @returns `{ status: 200, data: string }` the raw YAML string
+ */
 async function getYamlContent(input) {
     try {
         if (input.version) {
@@ -496,6 +663,18 @@ async function getYamlContent(input) {
 // ---------------------------------------------------------------------------
 // Cron
 // ---------------------------------------------------------------------------
+/**
+ * Set or update the cron schedule for a YAML workflow.
+ *
+ * Persists the schedule in the DB and restarts the in-process cron timer via the
+ * cron registry so the change takes effect immediately.
+ *
+ * @param input.id — UUID of the workflow to schedule
+ * @param input.cron_schedule — cron expression (e.g. "0 * * * *")
+ * @param input.cron_envelope — optional payload passed to each scheduled invocation
+ * @param input.execute_as — optional identity override for scheduled executions
+ * @returns `{ status: 200, data: YamlWorkflow }` the updated workflow record with cron fields set
+ */
 async function setCronSchedule(input) {
     try {
         const wf = await yamlDb.getYamlWorkflow(input.id);
@@ -518,6 +697,14 @@ async function setCronSchedule(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Remove the cron schedule from a YAML workflow.
+ *
+ * Stops the in-process cron timer first, then clears the schedule fields in the DB.
+ *
+ * @param input.id — UUID of the workflow to unschedule
+ * @returns `{ status: 200, data: YamlWorkflow }` the updated workflow record with cron fields cleared
+ */
 async function clearCronSchedule(input) {
     try {
         const wf = await yamlDb.getYamlWorkflow(input.id);
@@ -535,6 +722,14 @@ async function clearCronSchedule(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * List all YAML workflows that have a cron schedule, with their live timer status.
+ *
+ * Fetches all cron-scheduled workflows from the DB and cross-references with the
+ * in-process cron registry to determine which timers are actually running.
+ *
+ * @returns `{ status: 200, data: { schedules: Array<{ id, name, graph_topic, app_id, cron_schedule, execute_as, active }> } }`
+ */
 async function getCronStatus() {
     try {
         const workflows = await yamlDb.getCronScheduledWorkflows();

package/build/examples/seed.js

@@ -137,6 +137,24 @@ const SEED_ENVELOPES = [
             },
         },
     },
+    // -- Process 6: Basic Signal
+    {
+        label: 'Process 6 — Basic Signal',
+        workflowName: 'basicSignal',
+        taskQueue: 'long-tail-examples',
+        envelope: {
+            data: {
+                message: 'Seed deployment needs approval before proceeding.',
+                role: 'reviewer',
+            },
+            metadata: {
+                certified: false,
+                source: 'seed',
+                process: 'basic-signal',
+                description: 'Lightweight signal-based escalation — workflow stays running, no interceptor. Claim the escalation, fill the form, and resolve to resume the workflow.',
+            },
+        },
+    },
 ];
 // Escalation chains: reviewer -> admin -> engineer (and cross-links)
 const SEED_CHAINS = [

package/build/examples/types/envelopes.d.ts

@@ -24,11 +24,46 @@ export interface BasicEchoEnvelopeData {
     /** Duration to sleep before echoing (seconds). */
     sleepSeconds?: number;
 }
+/** Basic signal — lightweight escalation via conditionLT. */
+export interface BasicSignalEnvelopeData {
+    /** Message shown to the reviewer in the escalation description. */
+    message?: string;
+    /** Role to assign the escalation to. */
+    role?: string;
+}
+/** Assembly line — durable orchestrator with sequential human task queues. */
+export interface AssemblyLineEnvelopeData {
+    /** Product name for the assembly run. */
+    productName: string;
+    /** Ordered stations the product passes through. */
+    stations: Array<{
+        stationName: string;
+        role: string;
+        instructions: string;
+    }>;
+}
+/** Step iterator — generic loop over data-driven steps with human escalations. */
+export interface StepIteratorEnvelopeData {
+    /** Display name for this run. */
+    name: string;
+    /** Dynamic list of steps — each spawns a child workflow with an escalation. */
+    steps: Array<{
+        stationName: string;
+        role: string;
+        instructions: string;
+    }>;
+}
+/** Reverter — step loop with revert support (same shape as stepIterator). */
+export type ReverterEnvelopeData = StepIteratorEnvelopeData;
 /** Map of invocable workflow type → its typed envelope data shape. */
 export type WorkflowEnvelopeMap = {
     reviewContent: ReviewContentEnvelopeData;
     kitchenSink: KitchenSinkEnvelopeData;
     basicEcho: BasicEchoEnvelopeData;
+    basicSignal: BasicSignalEnvelopeData;
+    assemblyLine: AssemblyLineEnvelopeData;
+    stepIterator: StepIteratorEnvelopeData;
+    reverter: ReverterEnvelopeData;
 };
 /** All invocable workflow type names. */
 export type InvocableWorkflowType = keyof WorkflowEnvelopeMap;

package/build/examples/types/index.d.ts

@@ -5,6 +5,6 @@
  * Resolver types define the payload shape for resolving escalations.
  * Per-workflow types are re-exported for convenience.
  */
-export type { ReviewContentEnvelopeData, KitchenSinkEnvelopeData, BasicEchoEnvelopeData, WorkflowEnvelopeMap, InvocableWorkflowType, } from './envelopes';
+export type { ReviewContentEnvelopeData, KitchenSinkEnvelopeData, BasicEchoEnvelopeData, BasicSignalEnvelopeData, AssemblyLineEnvelopeData, StepIteratorEnvelopeData, ReverterEnvelopeData, WorkflowEnvelopeMap, InvocableWorkflowType, } from './envelopes';
 export type { ResolverLTBlock, BaseResolverPayload, ReviewContentResolverPayload, } from './resolvers';
 export type { ReviewContentInput, ReviewAnalysis, ReviewContentReturnData, ReviewContentReturn, ReviewContentEscalationData, ReviewContentEscalation, } from '../workflows/review-content/types';

package/build/examples/workers.js

@@ -37,6 +37,11 @@ exports.exampleWorkers = void 0;
 const reviewContentWorkflow = __importStar(require("./workflows/review-content"));
 const kitchenSinkWorkflow = __importStar(require("./workflows/kitchen-sink"));
 const basicEchoWorkflow = __importStar(require("./workflows/basic-echo"));
+const assemblyLineWorkflow = __importStar(require("./workflows/assembly-line"));
+const workstationWorkflow = __importStar(require("./workflows/assembly-line/worker"));
+const stepIteratorWorkflow = __importStar(require("./workflows/assembly-line/iterator"));
+const reverterWorkflow = __importStar(require("./workflows/assembly-line/reverter"));
+const basicSignalWorkflow = __importStar(require("./workflows/basic-signal"));
 /**
  * Example workers that ship with Long Tail.
  * Pass these to `start({ workers: [...exampleWorkers] })` or enable
@@ -46,4 +51,9 @@ exports.exampleWorkers = [
     { taskQueue: 'long-tail-examples', workflow: reviewContentWorkflow.reviewContent },
     { taskQueue: 'long-tail-examples', workflow: kitchenSinkWorkflow.kitchenSink },
     { taskQueue: 'long-tail-examples', workflow: basicEchoWorkflow.basicEcho },
+    { taskQueue: 'long-tail-examples', workflow: assemblyLineWorkflow.assemblyLine },
+    { taskQueue: 'long-tail-examples', workflow: workstationWorkflow.workstation },
+    { taskQueue: 'long-tail-examples', workflow: stepIteratorWorkflow.stepIterator },
+    { taskQueue: 'long-tail-examples', workflow: reverterWorkflow.reverter },
+    { taskQueue: 'long-tail-examples', workflow: basicSignalWorkflow.basicSignal },
 ];

package/build/examples/workflows/assembly-line/activities.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Assembly Line Activities
+ *
+ * Side-effect functions that run outside the deterministic workflow
+ * sandbox. Each is wrapped via proxyActivities so results are
+ * checkpointed and replayed on restart.
+ *
+ * Two responsibilities:
+ *   1. Create an escalation with signal routing so the resolve API
+ *      can wake the paused child workflow.
+ *   2. Signal the parent orchestrator when the child completes.
+ */
+export declare function createStationEscalation(input: {
+    role: string;
+    stationName: string;
+    instructions: string;
+    workflowId: string;
+    workflowType: string;
+    taskQueue: string;
+    signalId: string;
+}): Promise<string>;
+export declare function signalParent(input: {
+    parentTaskQueue: string;
+    parentWorkflowType: string;
+    parentWorkflowId: string;
+    signalId: string;
+    data: any;
+}): Promise<void>;

package/build/examples/workflows/assembly-line/activities.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Assembly Line Activities
+ *
+ * Side-effect functions that run outside the deterministic workflow
+ * sandbox. Each is wrapped via proxyActivities so results are
+ * checkpointed and replayed on restart.
+ *
+ * Two responsibilities:
+ *   1. Create an escalation with signal routing so the resolve API
+ *      can wake the paused child workflow.
+ *   2. Signal the parent orchestrator when the child completes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStationEscalation = createStationEscalation;
+exports.signalParent = signalParent;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const db_1 = require("../../../lib/db");
+const escalation_1 = require("../../../services/escalation");
+// ── Create station escalation ──────────────────────────────────────
+async function createStationEscalation(input) {
+    const escalation = await (0, escalation_1.createEscalation)({
+        type: 'assemblyLine',
+        subtype: input.stationName,
+        description: input.instructions,
+        priority: 2,
+        role: input.role,
+        envelope: JSON.stringify({ station: input.stationName }),
+        workflow_id: input.workflowId,
+        task_queue: input.taskQueue,
+        workflow_type: input.workflowType,
+    });
+    await (0, escalation_1.enrichEscalationRouting)(escalation.id, {
+        signal_routing: {
+            engine: 'durable',
+            taskQueue: input.taskQueue,
+            workflowType: input.workflowType,
+            workflowId: input.workflowId,
+            signalId: input.signalId,
+        },
+    }, {
+        workflowType: input.workflowType,
+        workflowId: input.workflowId,
+        taskQueue: input.taskQueue,
+    });
+    return escalation.id;
+}
+// ── Signal parent orchestrator ─────────────────────────────────────
+async function signalParent(input) {
+    const client = new hotmesh_1.Durable.Client({ connection: (0, db_1.getConnection)() });
+    const handle = await client.workflow.getHandle(input.parentTaskQueue, input.parentWorkflowType, input.parentWorkflowId);
+    await handle.signal(input.signalId, input.data);
+}

package/build/examples/workflows/assembly-line/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Assembly Line — durable orchestrator with human task queues.
+ *
+ * Demonstrates the core composition pattern without the LT interceptor:
+ *   startChild  → spawn a child workflow (fire-and-forget)
+ *   condition   → pause until the child signals back
+ *   signal      → child wakes the parent when done
+ *
+ * A product moves through sequential workstations. Each station
+ * creates an escalation for a human operator, pauses, then signals
+ * the parent when the human resolves it.
+ *
+ * No registration, no certification, no interceptor — just Durable
+ * primitives and the escalation table.
+ */
+import type { LTEnvelope } from '../../../types';
+export declare function assemblyLine(envelope: LTEnvelope): Promise<any>;

package/build/examples/workflows/assembly-line/index.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Assembly Line — durable orchestrator with human task queues.
+ *
+ * Demonstrates the core composition pattern without the LT interceptor:
+ *   startChild  → spawn a child workflow (fire-and-forget)
+ *   condition   → pause until the child signals back
+ *   signal      → child wakes the parent when done
+ *
+ * A product moves through sequential workstations. Each station
+ * creates an escalation for a human operator, pauses, then signals
+ * the parent when the human resolves it.
+ *
+ * No registration, no certification, no interceptor — just Durable
+ * primitives and the escalation table.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assemblyLine = assemblyLine;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const defaults_1 = require("../../../modules/defaults");
+async function assemblyLine(envelope) {
+    const { productName, stations } = envelope.data;
+    const ctx = hotmesh_1.Durable.workflow.workflowInfo();
+    const results = [];
+    for (const [i, station] of stations.entries()) {
+        const signalId = `station-${i}-${ctx.workflowId}`;
+        const childWorkflowId = `workstation-${ctx.workflowId}-${i}`;
+        // Spawn child — fire-and-forget; only the start is awaited
+        await hotmesh_1.Durable.workflow.startChild({
+            workflowName: 'workstation',
+            args: [
+                {
+                    data: {
+                        ...station,
+                        parentSignalId: signalId,
+                        parentTaskQueue: 'long-tail-examples',
+                        parentWorkflowType: 'assemblyLine',
+                        parentWorkflowId: ctx.workflowId,
+                    },
+                    metadata: { source: 'assembly-line', station: station.stationName },
+                },
+            ],
+            taskQueue: 'long-tail-examples',
+            workflowId: childWorkflowId,
+            expire: defaults_1.JOB_EXPIRE_SECS,
+            entity: 'workstation',
+        });
+        // Pause until the child signals back with its result
+        const result = await hotmesh_1.Durable.workflow.condition(signalId);
+        results.push(result);
+    }
+    return {
+        type: 'return',
+        data: {
+            productName,
+            stations: results,
+            completedAt: new Date().toISOString(),
+        },
+    };
+}

package/build/examples/workflows/assembly-line/iterator.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Step Iterator — generic durable loop over dynamic steps.
+ *
+ * Proves that the number and shape of steps can be entirely
+ * data-driven. The orchestrator knows nothing about grinder,
+ * gluer, or any specific station — it just walks the list,
+ * spawns a child for each, and waits for the signal.
+ *
+ * Reuses the same `workstation` child workflow as the assembly line.
+ */
+import type { LTEnvelope } from '../../../types';
+export declare function stepIterator(envelope: LTEnvelope): Promise<any>;

package/build/examples/workflows/assembly-line/iterator.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Step Iterator — generic durable loop over dynamic steps.
+ *
+ * Proves that the number and shape of steps can be entirely
+ * data-driven. The orchestrator knows nothing about grinder,
+ * gluer, or any specific station — it just walks the list,
+ * spawns a child for each, and waits for the signal.
+ *
+ * Reuses the same `workstation` child workflow as the assembly line.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepIterator = stepIterator;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const defaults_1 = require("../../../modules/defaults");
+async function stepIterator(envelope) {
+    const { name, steps } = envelope.data;
+    const ctx = hotmesh_1.Durable.workflow.workflowInfo();
+    const results = [];
+    for (const [i, step] of steps.entries()) {
+        const signalId = `step-${i}-${ctx.workflowId}`;
+        const childWorkflowId = `workstation-${ctx.workflowId}-${i}`;
+        await hotmesh_1.Durable.workflow.startChild({
+            workflowName: 'workstation',
+            args: [
+                {
+                    data: {
+                        ...step,
+                        parentSignalId: signalId,
+                        parentTaskQueue: 'long-tail-examples',
+                        parentWorkflowType: 'stepIterator',
+                        parentWorkflowId: ctx.workflowId,
+                    },
+                    metadata: { source: 'step-iterator', step: i },
+                },
+            ],
+            taskQueue: 'long-tail-examples',
+            workflowId: childWorkflowId,
+            expire: defaults_1.JOB_EXPIRE_SECS,
+            entity: 'workstation',
+        });
+        const result = await hotmesh_1.Durable.workflow.condition(signalId);
+        results.push(result);
+    }
+    return {
+        type: 'return',
+        data: {
+            name,
+            totalSteps: steps.length,
+            steps: results,
+            completedAt: new Date().toISOString(),
+        },
+    };
+}

package/build/examples/workflows/assembly-line/reverter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Reverter — durable step loop with revert support.
+ *
+ * Like stepIterator, but each human resolution can send the
+ * pipeline backwards. The resolver payload controls flow:
+ *
+ *   { approved: true }              → advance to next step
+ *   { approved: false, revertSteps: 1 }  → go back 1 step
+ *   { approved: false, revertSteps: 2 }  → go back 2 steps
+ *
+ * The orchestrator tracks a monotonic attempt counter so every
+ * child spawn gets a unique workflow ID and signal key — even
+ * when revisiting a step after a revert.
+ *
+ * The full history (approvals + reverts) is recorded in the result.
+ */
+import type { LTEnvelope } from '../../../types';
+export declare function reverter(envelope: LTEnvelope): Promise<any>;