@mantajs/core 0.1.7 → 0.2.0-beta.1

package/dist/workflows/step.js

@@ -0,0 +1,949 @@
+// Step API — direct, module-aware, typed.
+//
+// step.product.create({ title: 'Widget' }, ctx)   → auto-compensated
+// step.product.activate(id, ctx)                   → auto-compensation via SnapshotRepository
+// step.product.delete(id, ctx)                     → smart delete: cascade + dismiss based on link types
+// step.product.link.inventoryItem(pId, iId, ctx)   → link via pivot, auto-compensated
+// step.emit('product.created', data, ctx)           → fire-and-forget event
+//
+// `step` is a Proxy. When you access step.product, it returns a module helper
+// that resolves the service from ctx.app at call time.
+import { and, eq, isNull } from 'drizzle-orm';
+import { MantaError } from '../errors/manta-error.js';
+import { getRegisteredLinks } from '../link/index.js';
+import { pluralize } from '../naming.js';
+import { createForEach } from './for-each.js';
+import { workflowContextStorage } from './manager.js';
+import { CancelledError, createProgress } from './progress-helper.js';
+import { isWorkflowYield, WorkflowYield } from './yield.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/**
+ * Resolve registered links from the app context (preferred) or global registry (fallback).
+ * The app's __linkRegistry is set by the bootstrap and avoids module instance mismatch.
+ */
+function resolveLinks(ctx) {
+    try {
+        const registry = ctx.app.resolve('__linkRegistry');
+        if (registry && registry.length > 0)
+            return registry;
+    }
+    catch {
+        /* not registered */
+    }
+    return getRegisteredLinks();
+}
+/**
+ * Get the Drizzle db instance from the step context.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Drizzle db is dynamically typed across adapters
+function getDb(ctx) {
+    return ctx.app.infra.db;
+}
+/**
+ * Resolve a generated Drizzle pgTable by name.
+ * Tables are generated at boot from DML entities and links, registered as __generatedTables.
+ */
+function getLinkTable(ctx, tableName) {
+    try {
+        const tables = ctx.app.resolve('__generatedTables');
+        const table = tables.get(tableName);
+        if (table)
+            return table;
+    }
+    catch {
+        /* not registered */
+    }
+    throw new MantaError('INVALID_STATE', `Link table "${tableName}" not found. Ensure the link is defined via defineLink() in src/links/ and that migrations are up to date (manta db:generate && manta db:migrate).`);
+}
+/**
+ * Get a column from a Drizzle table by name.
+ * Returns any because the column is passed to Drizzle query builders (eq, select, etc.)
+ * which require their internal column types we can't express from a string key.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Drizzle column dynamic access — see JSDoc
+function getColumn(table, columnName) {
+    return table[columnName];
+}
+function resolveService(ctx, entity) {
+    const moduleName = entity.toLowerCase();
+    const modules = ctx.app.modules;
+    // Try by module name first (catalog, inventory, etc.)
+    const direct = modules[moduleName] ?? modules[entity];
+    if (direct)
+        return direct;
+    // Try by entity name — search all modules for one whose __entity.name matches
+    for (const [_key, svc] of Object.entries(modules)) {
+        const s = svc;
+        if (s?.__entity && s.__entity.name === entity) {
+            return s;
+        }
+    }
+    // Fallback: resolve from app registry
+    try {
+        return ctx.app.resolve(`${moduleName}ModuleService`);
+    }
+    catch {
+        const available = Object.keys(ctx.app.modules).join(', ');
+        throw new MantaError('UNKNOWN_MODULES', `Service for "${entity}" not found. Available modules: [${available}]. Check that the module is in src/modules/ and exports a defineService().`);
+    }
+}
+/**
+ * Run a step within the workflow context: checkpoint, execute, register compensation.
+ * Also reports step lifecycle to `wfCtx.store` (durable run store) on a best-effort
+ * basis — store errors MUST NOT fail the workflow.
+ */
+async function runStep(name, ctx, handler, compensate) {
+    const wfCtx = workflowContextStorage.getStore() ?? ctx.__wfCtx ?? null;
+    if (!wfCtx) {
+        return handler();
+    }
+    const count = (wfCtx.stepCounter.get(name) ?? 0) + 1;
+    wfCtx.stepCounter.set(name, count);
+    const stepKey = count === 1 ? name : `${name}-${count}`;
+    if (wfCtx.checkpoints.has(stepKey)) {
+        const cached = wfCtx.checkpoints.get(stepKey);
+        if (compensate) {
+            wfCtx.completedSteps.push({
+                name: stepKey,
+                output: cached,
+                compensate: async (out) => compensate(out),
+            });
+        }
+        return cached;
+    }
+    // Cooperative cancel check at step boundary (see WORKFLOW_PROGRESS.md §10.3).
+    if (wfCtx.signal?.aborted) {
+        throw new CancelledError(`Workflow ${wfCtx.runId} cancelled before step "${stepKey}"`);
+    }
+    const previousStepName = wfCtx.stepName;
+    wfCtx.stepName = stepKey;
+    if (wfCtx.store) {
+        try {
+            await wfCtx.store.updateStep(wfCtx.runId, stepKey, {
+                status: 'running',
+                started_at: new Date(),
+            });
+        }
+        catch {
+            /* store errors are non-fatal */
+        }
+    }
+    let output;
+    try {
+        output = await handler();
+    }
+    catch (err) {
+        // Yield is NOT a failure — the manager catches WorkflowYield above the
+        // retry loop and schedules a continuation. We persist resume_state here
+        // so the next invocation's step can read it via `ctx.resumeState`.
+        if (isWorkflowYield(err)) {
+            if (wfCtx.store) {
+                try {
+                    await wfCtx.store.updateStep(wfCtx.runId, stepKey, {
+                        status: 'paused',
+                        resume_state: err.resumeState,
+                    });
+                }
+                catch {
+                    /* store errors are non-fatal; manager retries on resume */
+                }
+            }
+            wfCtx.stepName = previousStepName;
+            throw err;
+        }
+        if (wfCtx.store) {
+            const cancelled = err?.code === 'WORKFLOW_CANCELLED' ||
+                err?.name === 'CancelledError';
+            try {
+                await wfCtx.store.updateStep(wfCtx.runId, stepKey, {
+                    status: cancelled ? 'cancelled' : 'failed',
+                    completed_at: new Date(),
+                    error: cancelled ? undefined : { message: err?.message ?? String(err) },
+                });
+            }
+            catch {
+                /* non-fatal */
+            }
+        }
+        wfCtx.stepName = previousStepName;
+        throw err;
+    }
+    if (compensate) {
+        wfCtx.completedSteps.push({
+            name: stepKey,
+            output,
+            compensate: async (out) => compensate(out),
+        });
+    }
+    else {
+        wfCtx.completedSteps.push({ name: stepKey, output });
+    }
+    wfCtx.checkpoints.set(stepKey, output);
+    if (wfCtx.saveCheckpoint)
+        await wfCtx.saveCheckpoint(stepKey, output);
+    if (wfCtx.store) {
+        try {
+            await wfCtx.store.updateStep(wfCtx.runId, stepKey, {
+                status: 'succeeded',
+                completed_at: new Date(),
+            });
+        }
+        catch {
+            /* non-fatal */
+        }
+    }
+    wfCtx.stepName = previousStepName;
+    return output;
+}
+// ---------------------------------------------------------------------------
+// Auto-resolve: find the last created entity ID from workflow context
+// ---------------------------------------------------------------------------
+function findLastCreatedId(ctx, entityName) {
+    const wfCtx = workflowContextStorage.getStore() ?? ctx.__wfCtx ?? null;
+    if (!wfCtx)
+        return null;
+    const stepName = `create-${entityName.toLowerCase()}`;
+    // Scan completed steps in reverse to find the most recent create for this entity
+    for (let i = wfCtx.completedSteps.length - 1; i >= 0; i--) {
+        const step = wfCtx.completedSteps[i];
+        if (step.name.startsWith(stepName)) {
+            const output = step.output;
+            if (output?.id)
+                return output.id;
+        }
+    }
+    // Also check checkpoints (for crash recovery)
+    for (const [key, value] of wfCtx.checkpoints) {
+        if (key.startsWith(stepName)) {
+            const output = value;
+            if (output?.id)
+                return output.id;
+        }
+    }
+    return null;
+}
+function _findCascadeLinks(ctx, entityModule, entityName) {
+    return resolveLinks(ctx).filter((link) => (link.leftModule === entityModule || link.leftEntity === entityName) && link.cascadeLeft === true);
+}
+// ---------------------------------------------------------------------------
+// Step implementations
+// ---------------------------------------------------------------------------
+async function stepCreate(entity, data, ctx) {
+    const suffix = capitalize(pluralize(entity));
+    return runStep(`create-${entity.toLowerCase()}`, ctx, async () => {
+        const service = resolveService(ctx, entity);
+        const method = service[`create${suffix}`];
+        if (!method)
+            throw new MantaError('NOT_FOUND', `Service for "${entity}" has no create${suffix} method`);
+        const result = (await method.call(service, data));
+        // Tag with entity name so step.link() can auto-resolve
+        Object.defineProperty(result, ENTITY_TAG, { value: entity, enumerable: false });
+        return result;
+    }, async (output) => {
+        const service = resolveService(ctx, entity);
+        const deleteMethod = service[`delete${suffix}`];
+        if (deleteMethod && output.id)
+            await deleteMethod.call(service, [output.id]);
+    });
+}
+async function stepUpdate(entity, id, data, ctx) {
+    const suffix = capitalize(pluralize(entity));
+    const entityCap = capitalize(entity);
+    let previousData;
+    try {
+        const service = resolveService(ctx, entity);
+        const retrieveMethod = service[`retrieve${entityCap}`];
+        if (retrieveMethod)
+            previousData = (await retrieveMethod.call(service, id));
+    }
+    catch {
+        /* best effort */
+    }
+    return runStep(`update-${entity.toLowerCase()}`, ctx, async () => {
+        const service = resolveService(ctx, entity);
+        const method = service[`update${suffix}`];
+        if (!method)
+            throw new MantaError('NOT_FOUND', `Service for "${entity}" has no update${suffix} method`);
+        const result = (await method.call(service, { id, ...data }));
+        Object.defineProperty(result, ENTITY_TAG, { value: entity, enumerable: false });
+        return result;
+    }, previousData
+        ? async () => {
+            const service = resolveService(ctx, entity);
+            const method = service[`update${suffix}`];
+            if (method)
+                await method.call(service, { id, ...previousData });
+        }
+        : undefined);
+}
+async function stepDelete(entity, id, ctx) {
+    const suffix = capitalize(pluralize(entity));
+    const entityModule = entity.toLowerCase();
+    return runStep(`delete-${entityModule}`, ctx, async () => {
+        const service = resolveService(ctx, entity);
+        const db = getDb(ctx);
+        const deletedLinks = [];
+        const deletedChildren = [];
+        const dismissedLinks = [];
+        const allLinks = resolveLinks(ctx).filter((l) => l.leftModule === entityModule || l.leftEntity === entity);
+        for (const link of allLinks) {
+            const linkTable = getLinkTable(ctx, link.tableName);
+            const leftCol = getColumn(linkTable, link.leftFk);
+            const rightCol = getColumn(linkTable, link.rightFk);
+            const idCol = getColumn(linkTable, 'id');
+            const deletedAtCol = getColumn(linkTable, 'deleted_at');
+            const rows = await db
+                .select({
+                id: idCol,
+                child_id: rightCol,
+            })
+                .from(linkTable)
+                .where(and(eq(leftCol, id), isNull(deletedAtCol)));
+            if (link.cascadeLeft) {
+                const childEntity = link.rightEntity;
+                const childSuffix = capitalize(pluralize(childEntity));
+                let childService = null;
+                try {
+                    childService = resolveService(ctx, childEntity);
+                }
+                catch {
+                    /* not loaded */
+                }
+                for (const row of rows) {
+                    const childId = row.child_id;
+                    if (childService) {
+                        const softDel = childService[`softDelete${childSuffix}`];
+                        if (softDel) {
+                            await softDel.call(childService, [childId]);
+                            deletedChildren.push({ entity: childEntity, id: childId });
+                        }
+                    }
+                    const linkId = row.id;
+                    await db.update(linkTable).set({ deleted_at: new Date() }).where(eq(idCol, linkId));
+                    deletedLinks.push({ tableName: link.tableName, linkId });
+                }
+            }
+            else {
+                for (const row of rows) {
+                    const linkId = row.id;
+                    await db.delete(linkTable).where(eq(idCol, linkId));
+                    dismissedLinks.push({ tableName: link.tableName, linkId });
+                }
+            }
+        }
+        const softDel = service[`softDelete${suffix}`];
+        if (softDel)
+            await softDel.call(service, [id]);
+        return { id, deletedLinks, deletedChildren, dismissedLinks };
+    }, async (output) => {
+        const service = resolveService(ctx, entity);
+        const db = getDb(ctx);
+        const restoreMethod = service[`restore${suffix}`];
+        if (restoreMethod)
+            await restoreMethod.call(service, [output.id]);
+        for (const child of output.deletedChildren) {
+            try {
+                const childService = resolveService(ctx, child.entity);
+                const childSuffix = capitalize(pluralize(child.entity));
+                const childRestore = childService[`restore${childSuffix}`];
+                if (childRestore)
+                    await childRestore.call(childService, [child.id]);
+            }
+            catch {
+                /* best effort */
+            }
+        }
+        for (const link of output.deletedLinks) {
+            const linkTable = getLinkTable(ctx, link.tableName);
+            const idCol = getColumn(linkTable, 'id');
+            await db.update(linkTable).set({ deleted_at: null }).where(eq(idCol, link.linkId));
+        }
+        for (const link of output.dismissedLinks) {
+            const linkTable = getLinkTable(ctx, link.tableName);
+            await db
+                .insert(linkTable)
+                .values({
+                id: link.linkId,
+                created_at: new Date(),
+                updated_at: new Date(),
+            })
+                .onConflictDoNothing();
+        }
+    });
+}
+// stepCascadeDelete removed — stepDelete handles cascade automatically
+// ---------------------------------------------------------------------------
+// Entity ref — tagged objects returned by step.service.*.create/update
+// ---------------------------------------------------------------------------
+/** Symbol used to tag objects with their entity name (set by create/update steps). */
+export const ENTITY_TAG = Symbol.for('manta:entity');
+function isTaggedEntity(obj) {
+    return typeof obj === 'object' && obj !== null && ENTITY_TAG in obj;
+}
+function resolveEntityRef(arg) {
+    if (isTaggedEntity(arg)) {
+        return { entity: arg[ENTITY_TAG], id: arg.id };
+    }
+    if (typeof arg === 'object' && arg !== null && 'entity' in arg && 'id' in arg) {
+        return arg;
+    }
+    throw new MantaError('INVALID_DATA', 'step.link() arguments must be entity objects (from step.service.*.create()) ' +
+        'or explicit refs { entity: "product", id: "prod_123" }.');
+}
+/**
+ * Find a link definition between two entities (order-agnostic).
+ * Returns the link and whether the arguments are in the same order as the link definition.
+ */
+function findLinkDef(ctx, entityA, entityB) {
+    const links = resolveLinks(ctx);
+    const aLower = entityA.toLowerCase();
+    const bLower = entityB.toLowerCase();
+    // Try A=left, B=right
+    const forward = links.find((l) => (l.leftEntity === entityA || l.leftEntity.toLowerCase() === aLower) &&
+        (l.rightEntity === entityB || l.rightEntity.toLowerCase() === bLower));
+    if (forward)
+        return { link: forward, leftId: 'a' };
+    // Try B=left, A=right
+    const reverse = links.find((l) => (l.leftEntity === entityB || l.leftEntity.toLowerCase() === bLower) &&
+        (l.rightEntity === entityA || l.rightEntity.toLowerCase() === aLower));
+    if (reverse)
+        return { link: reverse, leftId: 'b' };
+    return null;
+}
+/**
+ * List available link partners for an entity (for error messages).
+ */
+function availableLinksFor(ctx, entity) {
+    const links = resolveLinks(ctx);
+    const eLower = entity.toLowerCase();
+    const partners = [];
+    for (const l of links) {
+        if (l.leftEntity === entity || l.leftEntity.toLowerCase() === eLower)
+            partners.push(l.rightEntity);
+        if (l.rightEntity === entity || l.rightEntity.toLowerCase() === eLower)
+            partners.push(l.leftEntity);
+    }
+    return [...new Set(partners)];
+}
+// ---------------------------------------------------------------------------
+// step.link() — first-level link step
+// ---------------------------------------------------------------------------
+/**
+ * Create a link between two entities.
+ *
+ * Accepts:
+ *   step.link(product, item)                     — tagged objects from create()
+ *   step.link(product, item, { quantity: 10 })   — with extra columns
+ *   step.link(product, { entity: 'inventory_item', id: 'inv_123' })
+ *   step.link({ entity: 'product', id: 'p1' }, { entity: 'inventory_item', id: 'p2' }, { qty: 1 })
+ *
+ * Validations:
+ *   1. Link must exist in defineLink registry
+ *   2. Required extra columns must be provided
+ *   3. Unknown extra columns are rejected
+ */
+async function stepLink(a, b, extraColumns, ctx) {
+    const refA = resolveEntityRef(a);
+    const refB = resolveEntityRef(b);
+    // 1. Find link definition (order-agnostic)
+    const found = findLinkDef(ctx, refA.entity, refB.entity);
+    if (!found) {
+        const partnersA = availableLinksFor(ctx, refA.entity);
+        const partnersB = availableLinksFor(ctx, refB.entity);
+        const hint = partnersA.length > 0
+            ? `Available links for ${refA.entity}: [${partnersA.join(', ')}].`
+            : partnersB.length > 0
+                ? `Available links for ${refB.entity}: [${partnersB.join(', ')}].`
+                : 'No links defined. Add a defineLink() in src/links/.';
+        throw new MantaError('NOT_FOUND', `Cannot link ${refA.entity} to ${refB.entity} — no defineLink found. ${hint}`);
+    }
+    const { link: linkDef, leftId: leftSide } = found;
+    const leftId = leftSide === 'a' ? refA.id : refB.id;
+    const rightId = leftSide === 'a' ? refB.id : refA.id;
+    // 2. Validate extra columns
+    const definedExtras = linkDef.extraColumns ?? {};
+    const definedKeys = Object.keys(definedExtras);
+    const providedKeys = Object.keys(extraColumns ?? {});
+    // Check for unknown columns
+    for (const key of providedKeys) {
+        if (!definedKeys.includes(key)) {
+            throw new MantaError('INVALID_DATA', `Unknown column "${key}" on link ${refA.entity} ↔ ${refB.entity}. ` +
+                (definedKeys.length > 0
+                    ? `Available extra columns: [${definedKeys.join(', ')}].`
+                    : 'This link has no extra columns.'));
+        }
+    }
+    // Check for required extra columns (those without defaults)
+    for (const key of definedKeys) {
+        const def = definedExtras[key];
+        const hasDefault = def && ('default_value' in def || 'is_nullable' in def);
+        if (!hasDefault && !(extraColumns && key in extraColumns)) {
+            throw new MantaError('INVALID_DATA', `Link ${refA.entity} ↔ ${refB.entity} requires extra column "${key}". ` +
+                `Pass it as the third argument: step.link(a, b, { ${key}: value }).`);
+        }
+    }
+    const leftKey = linkDef.leftEntity.toLowerCase();
+    const rightKey = linkDef.rightEntity.toLowerCase();
+    const linkId = `link_${leftId}_${rightId}`;
+    return runStep(`link-${leftKey}-${rightKey}`, ctx, async () => {
+        const db = getDb(ctx);
+        const linkTable = getLinkTable(ctx, linkDef.tableName);
+        await db.insert(linkTable).values({
+            id: linkId,
+            [linkDef.leftFk]: leftId,
+            [linkDef.rightFk]: rightId,
+            ...(extraColumns ?? {}),
+            created_at: new Date(),
+            updated_at: new Date(),
+        });
+        return { linkId };
+    }, async () => {
+        const db = getDb(ctx);
+        const linkTable = getLinkTable(ctx, linkDef.tableName);
+        const idCol = getColumn(linkTable, 'id');
+        await db.delete(linkTable).where(eq(idCol, linkId));
+    });
+}
+/**
+ * Legacy: Create a link with explicit entity names and IDs.
+ * Used by the old bound proxy in defineCommand.
+ */
+function stepLinkExplicit(leftEntity, leftId, rightEntity, rightId, ctx, extraColumns) {
+    return stepLink({ entity: leftEntity, id: leftId }, { entity: rightEntity, id: rightId }, extraColumns, ctx);
+}
+// ---------------------------------------------------------------------------
+// step.unlink() — remove a link between two entities
+// ---------------------------------------------------------------------------
+/**
+ * Remove a link between two entities (delete from pivot table).
+ * Compensation re-creates the link.
+ *
+ * @example
+ *   step.unlink(customer, group)
+ *   step.unlink({ entity: 'customer', id: 'cus_1' }, { entity: 'customer_group', id: 'grp_1' })
+ */
+function _stepUnlink(a, b, ctx) {
+    const refA = resolveEntityRef(a);
+    const refB = resolveEntityRef(b);
+    const found = findLinkDef(ctx, refA.entity, refB.entity);
+    if (!found) {
+        throw new MantaError('NOT_FOUND', `No defineLink found between "${refA.entity}" and "${refB.entity}". Create one in src/links/ or src/modules/{mod}/links/.`);
+    }
+    const link = found.link;
+    const leftId = link.leftEntity.toLowerCase() === refA.entity.toLowerCase() ? refA.id : refB.id;
+    const rightId = link.leftEntity.toLowerCase() === refA.entity.toLowerCase() ? refB.id : refA.id;
+    const leftKey = link.leftEntity.toLowerCase();
+    const rightKey = link.rightEntity.toLowerCase();
+    return runStep(`unlink-${leftKey}-${rightKey}`, ctx, async () => {
+        const db = getDb(ctx);
+        const linkTable = getLinkTable(ctx, link.tableName);
+        const leftFkCol = getColumn(linkTable, link.leftFk);
+        const rightFkCol = getColumn(linkTable, link.rightFk);
+        await db.delete(linkTable).where(and(eq(leftFkCol, leftId), eq(rightFkCol, rightId)));
+        return { success: true };
+    }, async () => {
+        // Compensation: re-create the link
+        const db = getDb(ctx);
+        const linkTable = getLinkTable(ctx, link.tableName);
+        await db.insert(linkTable).values({
+            id: `link_${leftId}_${rightId}`,
+            [link.leftFk]: leftId,
+            [link.rightFk]: rightId,
+            created_at: new Date(),
+            updated_at: new Date(),
+        });
+    });
+}
+async function stepInvoke(moduleName, methodName, args, ctx) {
+    return runStep(`invoke-${moduleName}-${methodName}`, ctx, async () => {
+        const service = resolveService(ctx, moduleName);
+        const method = service[methodName];
+        if (!method)
+            throw new MantaError('NOT_FOUND', `Service "${moduleName}" has no method "${methodName}"`);
+        // Clear snapshots before executing so we only track this method's mutations
+        const snapshotRepo = service.__snapshotRepo;
+        if (snapshotRepo)
+            snapshotRepo.clearSnapshots();
+        return method.apply(service, args);
+    }, async () => {
+        // Auto-compensation via SnapshotRepository — rollback all mutations made during the method
+        const service = resolveService(ctx, moduleName);
+        const snapshotRepo = service.__snapshotRepo;
+        if (snapshotRepo?.hasSnapshots)
+            await snapshotRepo.rollback();
+    });
+}
+async function stepEmit(eventName, data, ctx) {
+    return runStep(`emit-${eventName}`, ctx, async () => {
+        const eventBus = ctx.app.infra.eventBus;
+        await eventBus.emit({ eventName, data, metadata: { timestamp: Date.now() } });
+    });
+}
+// ---------------------------------------------------------------------------
+// Module Proxy — step.product.create(...), step.product.activate(...), etc.
+// ---------------------------------------------------------------------------
+function createLinkProxy(entityName) {
+    const leftEntity = entityName;
+    return new Proxy({}, {
+        get(_target, rightEntityProp) {
+            // step.product.link.inventoryItem(ctx) — IDs auto-resolved
+            // step.product.link.inventoryItem(extraColumns, ctx) — with extra columns
+            return (...args) => {
+                const rightEntity = rightEntityProp.charAt(0).toUpperCase() + rightEntityProp.slice(1);
+                const ctx = args[args.length - 1];
+                const leftId = findLastCreatedId(ctx, leftEntity);
+                const rightId = findLastCreatedId(ctx, rightEntity);
+                if (!leftId)
+                    throw new MantaError('INVALID_DATA', `Cannot link: no ${leftEntity} created yet in this workflow. Call step.service.${leftEntity.toLowerCase()}.create() first.`);
+                if (!rightId)
+                    throw new MantaError('INVALID_DATA', `Cannot link: no ${rightEntity} created yet in this workflow. Call step.service.${rightEntity.toLowerCase()}.create() first.`);
+                return stepLinkExplicit(leftEntity, leftId, rightEntity, rightId, ctx);
+            };
+        },
+    });
+}
+function createModuleProxy(entityName) {
+    const entity = entityName.charAt(0).toUpperCase() + entityName.slice(1);
+    return new Proxy({}, {
+        get(_target, methodName) {
+            switch (methodName) {
+                case 'create':
+                    return (data, ctx) => stepCreate(entity, data, ctx);
+                case 'update':
+                    return (id, data, ctx) => stepUpdate(entity, id, data, ctx);
+                case 'delete':
+                    return (id, ctx) => stepDelete(entity, id, ctx);
+                case 'link':
+                    return createLinkProxy(entity);
+                default:
+                    // Any other method → resolve from service (compensable methods like activate, archive)
+                    return (...args) => {
+                        const ctx = args[args.length - 1];
+                        const methodArgs = args.slice(0, -1);
+                        return stepInvoke(entityName, methodName, methodArgs, ctx);
+                    };
+            }
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Dismiss link step
+// ---------------------------------------------------------------------------
+async function stepDismissLink(leftEntity, leftId, rightEntity, rightId, ctx) {
+    const leftKey = leftEntity.toLowerCase();
+    const rightKey = rightEntity.toLowerCase();
+    const links = resolveLinks(ctx);
+    const linkDef = links.find((l) => (l.leftEntity === leftEntity || l.leftEntity.toLowerCase() === leftKey) &&
+        (l.rightEntity === rightEntity || l.rightEntity.toLowerCase() === rightKey));
+    if (!linkDef)
+        throw new MantaError('NOT_FOUND', `No link defined between "${leftEntity}" and "${rightEntity}"`);
+    return runStep(`dismiss-link-${leftKey}-${rightKey}`, ctx, async () => {
+        const db = getDb(ctx);
+        const linkTable = getLinkTable(ctx, linkDef.tableName);
+        const leftCol = getColumn(linkTable, linkDef.leftFk);
+        const rightCol = getColumn(linkTable, linkDef.rightFk);
+        await db.delete(linkTable).where(and(eq(leftCol, leftId), eq(rightCol, rightId)));
+    }, async () => {
+        const db = getDb(ctx);
+        const linkTable = getLinkTable(ctx, linkDef.tableName);
+        const linkId = `link_${leftId}_${rightId}`;
+        await db.insert(linkTable).values({
+            id: linkId,
+            [linkDef.leftFk]: leftId,
+            [linkDef.rightFk]: rightId,
+            created_at: new Date(),
+            updated_at: new Date(),
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Public API — step Proxy
+//
+// 4 categories:
+//   step.service.catalog.create({...}, ctx)    — service CRUD + compensable methods
+//   step.command.createProduct({...}, ctx)      — sub-workflow (command invocation)
+//   step.action('name', { invoke, compensate }) — custom external action
+//   step.emit('event.name', data, ctx)          — fire-and-forget event
+// ---------------------------------------------------------------------------
+function stepAction(name, config) {
+    if (!config.compensate) {
+        throw new MantaError('INVALID_DATA', `step.action("${name}") requires a compensate function. Usage: step.action("${name}", { invoke: async (input) => {...}, compensate: async (result) => {...} })`);
+    }
+    return async (input, ctx) => {
+        // Inject progress/signal/forEach/yield into the ctx passed to the user's invoke/compensate.
+        // Without this, `ctx.forEach` stays undefined inside step.action handlers — which
+        // breaks any long-running step that relies on it (e.g. rebuildCarts → PostHog replay).
+        const wfCtx = workflowContextStorage.getStore() ?? ctx.__wfCtx ?? null;
+        // Unique stepKey for resumeState lookup — mirrors the counter logic in
+        // runStep. Safe to peek ahead: runStep increments the same counter so
+        // our lookup uses the same key runStep will use.
+        const stepKey = wfCtx ? buildStepKey(wfCtx, name) : name;
+        const yieldFn = ((state) => {
+            throw new WorkflowYield(state);
+        });
+        const augmentedCtx = wfCtx
+            ? {
+                ...ctx,
+                __wfCtx: wfCtx,
+                signal: wfCtx.signal ?? ctx.signal,
+                progress: createProgress(wfCtx),
+                forEach: createForEach(wfCtx),
+                yield: yieldFn,
+                resumeState: wfCtx.resumeStates?.get(stepKey),
+                budgetMs: wfCtx.budgetMs,
+            }
+            : ctx;
+        return runStep(name, augmentedCtx, () => config.invoke(input, augmentedCtx), (output) => config.compensate(output, augmentedCtx));
+    };
+}
+/**
+ * Compute the stepKey runStep will use for a given step name, WITHOUT
+ * bumping the counter (runStep will bump it itself). Lets the action wrapper
+ * look up `resumeState` by the same key runStep uses.
+ */
+function buildStepKey(wfCtx, name) {
+    const count = (wfCtx.stepCounter.get(name) ?? 0) + 1;
+    return count === 1 ? name : `${name}-${count}`;
+}
+/**
+ * Service proxy — step.service.catalog.create(), step.service.catalog.activate()
+ * Accessed via step.service.MODULE_NAME
+ */
+function createServiceNamespace() {
+    return new Proxy({}, {
+        get(_target, moduleName) {
+            return createModuleProxy(moduleName);
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Link namespace — step.link.<linkName>.{ list, create, delete, update }
+// Pivot-backed CRUD on link tables. Intra-module FK-backed links throw
+// NOT_SUPPORTED — will be implemented when the first use case appears.
+// ---------------------------------------------------------------------------
+/** Convert 'customerAddress' → 'customer_address' (matches ResolvedLink.tableName). */
+function linkNameToTableName(name) {
+    return name.replace(/([a-z])([A-Z])/g, '$1_$2').toLowerCase();
+}
+/** Convert 'customer_address' → 'customerAddress' (used for available-link hints). */
+function tableNameToLinkName(tableName) {
+    return tableName.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+/** Resolve a ResolvedLink by its user-facing camelCase name. Throws if not found or FK-backed. */
+function resolveLinkByName(ctx, name) {
+    const expected = linkNameToTableName(name);
+    const links = resolveLinks(ctx);
+    const link = links.find((l) => l.tableName === expected);
+    if (!link) {
+        const available = links.map((l) => tableNameToLinkName(l.tableName)).join(', ');
+        throw new MantaError('NOT_FOUND', `Link "${name}" not found. Available links: [${available}]. Define it via defineLink() in src/links/ or src/modules/*/links/.`);
+    }
+    if (link.isDirectFk) {
+        throw new MantaError('NOT_SUPPORTED', `Link "${name}" is FK-backed (intra-module ${link.cardinality}). step.link.${name}.* is only implemented for pivot-backed links currently. Use step.service.<entity>.update() to manipulate the FK column directly.`);
+    }
+    return link;
+}
+/** Build a drizzle WHERE clause from a plain {col: value} object. */
+// biome-ignore lint/suspicious/noExplicitAny: drizzle column types are dynamic
+function buildWhere(table, where) {
+    const conditions = Object.entries(where).map(([key, value]) => {
+        const col = getColumn(table, key);
+        return value === null ? isNull(col) : eq(col, value);
+    });
+    if (conditions.length === 0)
+        return undefined;
+    if (conditions.length === 1)
+        return conditions[0];
+    return and(...conditions);
+}
+/**
+ * Link proxy — step.link.customerAddress.list({ customer_id, type: 'billing' })
+ *
+ * API (parallel to a model service CRUD):
+ *   list(where)            → pivot rows matching the where clause
+ *   create(data)           → insert a pivot row (data must include both FKs + any required extras)
+ *   update(where, patch)   → update extra columns on matching pivot rows
+ *   delete(where)          → delete matching pivot rows
+ *
+ * For pivot-backed links only. FK-backed intra-module links throw NOT_SUPPORTED
+ * at resolution time with a clear message.
+ */
+function createLinkNamespace() {
+    return new Proxy({}, {
+        get(_target, linkName) {
+            return {
+                list: async (where, ctx) => {
+                    const link = resolveLinkByName(ctx, linkName);
+                    return runStep(`link-list-${link.tableName}`, ctx, async () => {
+                        const db = getDb(ctx);
+                        const table = getLinkTable(ctx, link.tableName);
+                        const whereClause = buildWhere(table, where ?? {});
+                        const query = db.select().from(table);
+                        const rows = whereClause ? await query.where(whereClause) : await query;
+                        return rows;
+                    });
+                },
+                create: async (data, ctx) => {
+                    const link = resolveLinkByName(ctx, linkName);
+                    if (!(link.leftFk in data) || !(link.rightFk in data)) {
+                        throw new MantaError('INVALID_DATA', `step.link.${linkName}.create requires both "${link.leftFk}" and "${link.rightFk}" in the payload.`);
+                    }
+                    const leftId = data[link.leftFk];
+                    const rightId = data[link.rightFk];
+                    const linkId = `link_${leftId}_${rightId}`;
+                    return runStep(`link-create-${link.tableName}`, ctx, async () => {
+                        const db = getDb(ctx);
+                        const table = getLinkTable(ctx, link.tableName);
+                        const now = new Date();
+                        await db.insert(table).values({
+                            id: linkId,
+                            ...data,
+                            created_at: now,
+                            updated_at: now,
+                        });
+                        return { id: linkId, ...data };
+                    }, async () => {
+                        const db = getDb(ctx);
+                        const table = getLinkTable(ctx, link.tableName);
+                        const idCol = getColumn(table, 'id');
+                        await db.delete(table).where(eq(idCol, linkId));
+                    });
+                },
+                update: async (where, patch, ctx) => {
+                    const link = resolveLinkByName(ctx, linkName);
+                    const extraKeys = Object.keys(link.extraColumns ?? {});
+                    if (extraKeys.length === 0) {
+                        throw new MantaError('NOT_SUPPORTED', `Link "${linkName}" has no extra columns to update. step.link.${linkName}.update requires defined extraColumns on defineLink().`);
+                    }
+                    for (const key of Object.keys(patch)) {
+                        if (!extraKeys.includes(key)) {
+                            throw new MantaError('INVALID_DATA', `Unknown column "${key}" on link "${linkName}". Available extras: [${extraKeys.join(', ')}].`);
+                        }
+                    }
+                    return runStep(`link-update-${link.tableName}`, ctx, async () => {
+                        const db = getDb(ctx);
+                        const table = getLinkTable(ctx, link.tableName);
+                        const whereClause = buildWhere(table, where ?? {});
+                        if (!whereClause) {
+                            throw new MantaError('INVALID_DATA', `step.link.${linkName}.update requires a non-empty where clause.`);
+                        }
+                        await db
+                            .update(table)
+                            .set({ ...patch, updated_at: new Date() })
+                            .where(whereClause);
+                        return { ok: true };
+                    });
+                },
+                delete: async (where, ctx) => {
+                    const link = resolveLinkByName(ctx, linkName);
+                    return runStep(`link-delete-${link.tableName}`, ctx, async () => {
+                        const db = getDb(ctx);
+                        const table = getLinkTable(ctx, link.tableName);
+                        const whereClause = buildWhere(table, where ?? {});
+                        if (!whereClause) {
+                            throw new MantaError('INVALID_DATA', `step.link.${linkName}.delete requires a non-empty where clause.`);
+                        }
+                        await db.delete(table).where(whereClause);
+                        return { ok: true };
+                    });
+                },
+            };
+        },
+    });
+}
+/**
+ * Command proxy — step.command.createProduct(), step.command.catalog.activateProduct()
+ * Resolves commands from CommandRegistry and executes them as sub-workflows.
+ */
+function createCommandNamespace() {
+    return new Proxy({}, {
+        get(_target, commandName) {
+            // step.command.createProduct(input, ctx) → resolves command and runs it
+            return async (input, ctx) => {
+                return runStep(`command-${commandName}`, ctx, async () => {
+                    // Resolve the command callable from the app
+                    const camelCase = commandName.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+                    const commands = ctx.app.commands;
+                    const callable = commands[camelCase] ?? commands[commandName];
+                    if (!callable) {
+                        throw new MantaError('NOT_FOUND', `Command "${commandName}" not found in app.commands`);
+                    }
+                    return callable(input);
+                });
+            };
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Agent step — step.agent.NAME(input, ctx)
+// AI SDK imports are in a separate file (ai-step.ts) to avoid compile-time
+// dependency on the 'ai' package. Loaded dynamically via await import().
+// ---------------------------------------------------------------------------
+// biome-ignore lint/suspicious/noExplicitAny: AgentDefinition generic
+async function stepAgent(agentDef, input, ctx) {
+    const parsed = agentDef.input.parse(input);
+    const promptText = agentDef.instructions({ input: parsed });
+    return runStep(`agent-${agentDef.name}`, ctx, async () => {
+        // Dynamic import to avoid compile-time dependency on AI SDK
+        const mod = await import('./ai-step.js');
+        return mod.executeAgent(agentDef, parsed, promptText);
+    });
+}
+/**
+ * Agent proxy — step.agent.categorizeProduct(input, ctx)
+ * Resolves agent definitions from __agentRegistry in app.
+ */
+function createAgentNamespace() {
+    return new Proxy({}, {
+        get(_target, agentName) {
+            return async (input, ctx) => {
+                // Resolve agent definition from registry
+                // biome-ignore lint/suspicious/noExplicitAny: dynamic registry
+                let registry = null;
+                try {
+                    registry = ctx.app.resolve('__agentRegistry');
+                }
+                catch {
+                    throw new MantaError('NOT_FOUND', `Agent "${agentName}" not found. No agents registered. Create agents in src/agents/.`);
+                }
+                // Convert camelCase to kebab-case for lookup
+                const kebab = agentName.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+                const agentDef = registry.get(kebab) ?? registry.get(agentName);
+                if (!agentDef) {
+                    const available = [...registry.keys()].join(', ');
+                    throw new MantaError('NOT_FOUND', `Agent "${agentName}" not found. Available agents: [${available}]. Create it in src/agents/${kebab}.ts.`);
+                }
+                return stepAgent(agentDef, input, ctx);
+            };
+        },
+    });
+}
+const stepBase = {
+    emit: stepEmit,
+    action: stepAction,
+    service: createServiceNamespace(),
+    command: createCommandNamespace(),
+    link: createLinkNamespace(),
+    agent: createAgentNamespace(),
+    // Low-level access (used by framework internals)
+    create: stepCreate,
+    update: stepUpdate,
+    delete: stepDelete,
+    linkExplicit: stepLinkExplicit,
+    dismissLink: stepDismissLink,
+    invoke: stepInvoke,
+};
+export const step = new Proxy(stepBase, {
+    get(target, prop) {
+        if (prop in target)
+            return target[prop];
+        // Fallback: treat unknown property as module name (backward compat during migration)
+        return createModuleProxy(prop);
+    },
+});
+//# sourceMappingURL=step.js.map