@pikku/mongodb 0.12.5 → 0.12.7

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # @pikku/mongodb
 
+## 0.12.7
+
+### Patch Changes
+
+- 92cd5b1: feat(workflow): workflow-owned step retries + stable invocationId
+
+  The workflow — not the queue — now owns step retry policy, and each step
+  invocation gets a stable idempotency key.
+  - **Default `retries: 5` with exponential backoff.** A step with no `retries`
+    previously inherited the queue's bare default (e.g. pg-boss `retry_limit 2`,
+    no backoff) so retries fired instantly and couldn't outlast a transient
+    outage. Retries now default to 5 with backoff, resolved at the workflow layer.
+  - **`retries: 0` is honored.** Dispatch previously passed `undefined` options
+    for `retries: 0`, letting the queue re-run a non-idempotent step up to its own
+    default. The resolved policy now always sets `attempts` (`retries: 0` →
+    `attempts: 1`), so the queue never second-guesses the workflow. The persisted
+    step retries and the dispatched `attempts` are resolved together so
+    "retries exhausted" and "no more redeliveries" are the same event.
+  - **`workflowStep.invocationId`** — a deterministic, dependency-free
+    `uuidv5(runId:stepName)` handed to every step. Unlike `stepId` (minted per
+    attempt), it is identical across retries, so a step can dedupe on it
+    (`ON CONFLICT (invocationId)`, Stripe idempotency keys, etc.).
+  - **queue-bullmq**: `mapPikkuJobToBull` now maps `backoff` (previously dropped,
+    so a step's backoff silently never applied on Redis), and `registerQueues`
+    throws a clear error when no logger is available (matching queue-pg-boss).
+  - **Dispatch failures are recoverable, not fatal.** A step is now marked
+    `scheduled` only _after_ it is successfully handed to its transport (queue or
+    scheduler) — a failed hand-off leaves it `pending` so a replay re-dispatches
+    it, instead of stranding it in `scheduled` (replay would pause forever on a
+    job that was never enqueued). A transport outage (e.g. pg-boss momentarily
+    down) is surfaced as a new `WorkflowDispatchException`, which the orchestrator
+    treats as transient: the run is left running and the orchestrator job is
+    rethrown for redelivery (it replays idempotently from the snapshot) rather
+    than the whole run being marked `failed`. The orchestrator job now also
+    carries its own retry policy, so this holds even when the orchestrator queue
+    is configured `retry_limit 0`. A genuine step error still fails the run.
+  - **Same step name can be invoked multiple times in one run.** Step rows are now
+    keyed per _invocation_: the Nth reach of a step name in a replay resolves to a
+    physical key (`name` for the first, `name#N` for repeats), so a literal
+    duplicate name no longer clobbers the earlier step's state. The first reach
+    keeps the bare name, so existing rows, graph-node matching and `invocationId`s
+    are unchanged. Ordinals are derived deterministically from DSL execution order
+    and reset each replay.
+  - **Step provenance (`fromStepName`) + graph cycles.** Every step now records
+    the predecessor it was scheduled from (`fromStepName`; entry steps have none),
+    persisted on the step row across all stores (in-memory, kysely, redis,
+    mongodb, cloudflare DO) and carried in the queued payload. The DSL wire
+    exposes the derived `fromInvocationId` (`uuidv5(runId:fromStepName)`) so
+    consumers get the stable predecessor key without a second persisted id —
+    `fromStepName` is the source of truth (it is replay-deterministic; `stepId`,
+    minted per row, is not). This makes the walked path reconstructable even when
+    a node is reached more than once: in `a → b → a → c` the second `a` is a
+    distinct ordinal instance (`a#1`) whose `fromStepName` is `b`.
+    The graph runner now supports **cycles**: a forward edge into an
+    already-started node still collapses to a single run (joins/diamonds are
+    unchanged), but a _back-edge_ — one whose target can reach its source — fires
+    a fresh ordinal instance, so a node can loop back to itself. Termination is
+    the graph's responsibility (branch routing must converge); the engine enforces
+    no visit cap.
+
+- Updated dependencies [92cd5b1]
+  - @pikku/core@0.12.38
+
+## 0.12.6
+
+### Patch Changes
+
+- 4b5c75b: feat(auth-js): wire OIDC config (issuer/tenantId) as variables, expand provider registry
+  - Move `issuer` and `tenantId` out of the secret blob for OIDC providers (auth0, okta, azure-ad, keycloak, cognito, microsoft-entra-id) — they are public config URLs, not secrets. Now registered via `wireVariable` and loaded at runtime via `services.variables.get()`.
+  - Expand provider registry from 13 to 31 providers: reddit, notion, instagram, zoom, figma, tiktok, threads, patreon, dropbox, bitbucket, hubspot, salesforce, atlassian, strava, keycloak, cognito, microsoft-entra-id added.
+  - `serialize-auth-gen` emits `wireVariable({...})` declarations and `services.variables.get()` calls in the generated factory for OIDC providers.
+  - Integration verifier exercises real `/auth/providers` endpoint with `LocalSecretService` + `LocalVariablesService`, including a spy test proving `services.variables.get('AUTH0_ISSUER')` is called at request time.
+
+- Updated dependencies [4b5c75b]
+- Updated dependencies [4b5c75b]
+  - @pikku/core@0.12.27
+
 ## 0.12.5
 
 ### Patch Changes

package/dist/src/mongodb-agent-run-service.d.ts

@@ -8,6 +8,7 @@ export declare class MongoDBAgentRunService implements AgentRunService {
     constructor(db: Db);
     listThreads(options?: {
         agentName?: string;
+        resourceId?: string;
         limit?: number;
         offset?: number;
     }): Promise<AIThread[]>;

package/dist/src/mongodb-agent-run-service.js

@@ -10,8 +10,11 @@ export class MongoDBAgentRunService {
         this.runs = db.collection('ai_run');
     }
     async listThreads(options) {
-        const { agentName, limit = 50, offset = 0 } = options ?? {};
+        const { agentName, resourceId, limit = 50, offset = 0 } = options ?? {};
         let filter = {};
+        if (resourceId) {
+            filter.resourceId = resourceId;
+        }
         if (agentName) {
             const threadIds = await this.runs.distinct('threadId', {
                 agentName,

package/dist/src/mongodb-channel-store.d.ts

@@ -14,5 +14,8 @@ export declare class MongoDBChannelStore extends ChannelStore {
     getChannel(channelId: string): Promise<Channel & {
         pikkuUserId?: string;
     }>;
+    setState(channelId: string, state: unknown): Promise<void>;
+    getState(channelId: string): Promise<unknown | undefined>;
+    clearState(channelId: string): Promise<void>;
     close(): Promise<void>;
 }

package/dist/src/mongodb-channel-store.js

@@ -48,5 +48,15 @@ export class MongoDBChannelStore extends ChannelStore {
             pikkuUserId: row.pikkuUserId ?? undefined,
         };
     }
+    async setState(channelId, state) {
+        await this.channels.updateOne({ _id: channelId }, { $set: { state } });
+    }
+    async getState(channelId) {
+        const row = await this.channels.findOne({ _id: channelId }, { projection: { state: 1 } });
+        return row?.state ?? undefined;
+    }
+    async clearState(channelId) {
+        await this.channels.updateOne({ _id: channelId }, { $unset: { state: '' } });
+    }
     async close() { }
 }

package/dist/src/mongodb-secret-service.d.ts

@@ -21,10 +21,10 @@ export declare class MongoDBSecretService implements SecretService {
     init(): Promise<void>;
     private logAudit;
     private getKEK;
-    getSecret(key: string): Promise<string>;
-    getSecretJSON<R = {}>(key: string): Promise<R>;
+    getSecret<T = string>(key: string): Promise<T>;
     hasSecret(key: string): Promise<boolean>;
-    setSecretJSON(key: string, value: unknown): Promise<void>;
+    setSecret(key: string, value: unknown): Promise<void>;
     deleteSecret(key: string): Promise<void>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<T>;
     rotateKEK(): Promise<number>;
 }

package/dist/src/mongodb-secret-service.js

@@ -56,17 +56,12 @@ export class MongoDBSecretService {
         await this.logAudit(key, 'read');
         return result;
     }
-    async getSecretJSON(key) {
-        const raw = await this.getSecret(key);
-        return JSON.parse(raw);
-    }
     async hasSecret(key) {
         const count = await this.secrets.countDocuments({ _id: key }, { limit: 1 });
         return count > 0;
     }
-    async setSecretJSON(key, value) {
-        const plaintext = JSON.stringify(value);
-        const { ciphertext, wrappedDEK } = await envelopeEncrypt(this.key, plaintext);
+    async setSecret(key, value) {
+        const { ciphertext, wrappedDEK } = await envelopeEncrypt(this.key, value);
         const now = new Date();
         await this.secrets.updateOne({ _id: key }, {
             $set: {
@@ -86,6 +81,22 @@ export class MongoDBSecretService {
         await this.secrets.deleteOne({ _id: key });
         await this.logAudit(key, 'delete');
     }
+    async getSecrets(keys) {
+        const rows = await this.secrets
+            .find({ _id: { $in: keys } })
+            .toArray();
+        const out = {};
+        for (const row of rows) {
+            try {
+                const kek = this.getKEK(row.keyVersion);
+                out[row._id] = await envelopeDecrypt(kek, row.ciphertext, row.wrappedDek);
+            }
+            catch {
+                // skip secrets that fail to decrypt
+            }
+        }
+        return out;
+    }
     async rotateKEK() {
         if (!this.previousKey) {
             throw new Error('No previousKey configured — nothing to rotate from');

package/dist/src/mongodb-workflow-service.d.ts

@@ -1,5 +1,5 @@
 import type { SerializedError } from '@pikku/core';
-import { PikkuWorkflowService, type WorkflowPlannedStep, type WorkflowRun, type WorkflowRunWire, type StepState, type WorkflowStatus, type WorkflowVersionStatus } from '@pikku/core/workflow';
+import { PikkuWorkflowService, type WorkflowPlannedStep, type WorkflowRun, type WorkflowRunWire, type StepState, type StepStatus, type WorkflowStatus, type WorkflowVersionStatus } from '@pikku/core/workflow';
 import type { Db } from 'mongodb';
 export declare class MongoDBWorkflowService extends PikkuWorkflowService {
     private initialized;
@@ -10,28 +10,28 @@ export declare class MongoDBWorkflowService extends PikkuWorkflowService {
     private versions;
     constructor(db: Db);
     init(): Promise<void>;
-    createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
+    protected createRunImpl(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
         deterministic?: boolean;
         plannedSteps?: WorkflowPlannedStep[];
     }): Promise<string>;
     getRun(id: string): Promise<WorkflowRun | null>;
-    updateRunStatus(id: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
-    insertStepState(runId: string, stepName: string, rpcName: string | null, data: any, stepOptions?: {
+    protected updateRunStatusImpl(id: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
+    protected insertStepStateImpl(runId: string, stepName: string, rpcName: string | null, data: any, stepOptions?: {
         retries?: number;
         retryDelay?: string | number;
-    }): Promise<StepState>;
+    }, fromStepName?: string): Promise<StepState>;
     getStepState(runId: string, stepName: string): Promise<StepState>;
     getRunHistory(runId: string): Promise<Array<StepState & {
         stepName: string;
     }>>;
-    setStepRunning(stepId: string): Promise<void>;
-    setStepScheduled(stepId: string): Promise<void>;
+    protected setStepRunningImpl(stepId: string): Promise<void>;
+    protected setStepScheduledImpl(stepId: string): Promise<void>;
     private insertHistoryRecord;
     private getTimestampFieldForStatus;
-    setStepChildRunId(stepId: string, childRunId: string): Promise<void>;
-    setStepResult(stepId: string, result: any): Promise<void>;
-    setStepError(stepId: string, error: Error): Promise<void>;
-    createRetryAttempt(stepId: string, status: 'pending' | 'running'): Promise<StepState>;
+    protected setStepChildRunIdImpl(stepId: string, childRunId: string): Promise<void>;
+    protected setStepResultImpl(stepId: string, result: any): Promise<void>;
+    protected setStepErrorImpl(stepId: string, error: Error): Promise<void>;
+    protected createRetryAttemptImpl(stepId: string, status: 'pending' | 'running'): Promise<StepState>;
     withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>;
     withStepLock<T>(_runId: string, _stepName: string, fn: () => Promise<T>): Promise<T>;
     getCompletedGraphState(runId: string): Promise<{
@@ -40,12 +40,17 @@ export declare class MongoDBWorkflowService extends PikkuWorkflowService {
         branchKeys: Record<string, string>;
     }>;
     getNodesWithoutSteps(runId: string, nodeIds: string[]): Promise<string[]>;
+    getStepInstances(runId: string): Promise<Array<{
+        stepName: string;
+        status: StepStatus;
+        fromStepName?: string;
+    }>>;
     getNodeResults(runId: string, nodeIds: string[]): Promise<Record<string, any>>;
-    setBranchTaken(stepId: string, branchKey: string): Promise<void>;
-    updateRunState(runId: string, name: string, value: unknown): Promise<void>;
+    protected setBranchTakenImpl(stepId: string, branchKey: string): Promise<void>;
+    protected updateRunStateImpl(runId: string, name: string, value: unknown): Promise<void>;
     getRunState(runId: string): Promise<Record<string, unknown>>;
-    upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
-    updateWorkflowVersionStatus(name: string, graphHash: string, status: WorkflowVersionStatus): Promise<void>;
+    protected upsertWorkflowVersionImpl(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
+    protected updateWorkflowVersionStatusImpl(name: string, graphHash: string, status: WorkflowVersionStatus): Promise<void>;
     getWorkflowVersion(name: string, graphHash: string): Promise<{
         graph: any;
         source: string;

package/dist/src/mongodb-workflow-service.js

@@ -28,7 +28,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
         await this.versions.createIndex({ workflowName: 1, graphHash: 1 }, { unique: true });
         this.initialized = true;
     }
-    async createRun(workflowName, input, inline, graphHash, wire, options) {
+    async createRunImpl(workflowName, input, inline, graphHash, wire, options) {
         const id = crypto.randomUUID();
         const now = new Date();
         await this.runs.insertOne({
@@ -52,7 +52,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     async getRun(id) {
         return this.runService.getRun(id);
     }
-    async updateRunStatus(id, status, output, error) {
+    async updateRunStatusImpl(id, status, output, error) {
         await this.runs.updateOne({ _id: id }, {
             $set: {
                 status,
@@ -62,7 +62,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
             },
         });
     }
-    async insertStepState(runId, stepName, rpcName, data, stepOptions) {
+    async insertStepStateImpl(runId, stepName, rpcName, data, stepOptions, fromStepName) {
         const stepId = crypto.randomUUID();
         const now = new Date();
         await this.steps.insertOne({
@@ -77,6 +77,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
             branchTaken: null,
             retries: stepOptions?.retries ?? null,
             retryDelay: stepOptions?.retryDelay?.toString() ?? null,
+            fromStepName: fromStepName ?? null,
             createdAt: now,
             updatedAt: now,
         });
@@ -89,6 +90,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
             attemptCount: 1,
             retries: stepOptions?.retries,
             retryDelay: stepOptions?.retryDelay?.toString(),
+            fromStepName,
             createdAt: now,
             updatedAt: now,
         };
@@ -112,6 +114,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
             attemptCount,
             retries: row.retries != null ? Number(row.retries) : undefined,
             retryDelay: row.retryDelay ?? undefined,
+            fromStepName: row.fromStepName ?? undefined,
             createdAt: new Date(row.createdAt),
             updatedAt: new Date(row.updatedAt),
         };
@@ -119,7 +122,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     async getRunHistory(runId) {
         return this.runService.getRunHistory(runId);
     }
-    async setStepRunning(stepId) {
+    async setStepRunningImpl(stepId) {
         await this.steps.updateOne({ _id: stepId }, { $set: { status: 'running', updatedAt: new Date() } });
         const latestHistory = await this.stepHistory
             .find({ workflowStepId: stepId })
@@ -130,7 +133,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
             await this.stepHistory.updateOne({ _id: latestHistory[0]._id }, { $set: { status: 'running' } });
         }
     }
-    async setStepScheduled(stepId) {
+    async setStepScheduledImpl(stepId) {
         await this.steps.updateOne({ _id: stepId }, { $set: { status: 'scheduled', updatedAt: new Date() } });
     }
     async insertHistoryRecord(stepId, status, result, error) {
@@ -167,7 +170,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
                 return 'createdAt';
         }
     }
-    async setStepChildRunId(stepId, childRunId) {
+    async setStepChildRunIdImpl(stepId, childRunId) {
         await this.steps.updateOne({ _id: stepId }, {
             $set: {
                 childRunId,
@@ -175,7 +178,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
             },
         });
     }
-    async setStepResult(stepId, result) {
+    async setStepResultImpl(stepId, result) {
         await this.steps.updateOne({ _id: stepId }, {
             $set: {
                 status: 'succeeded',
@@ -193,7 +196,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
             await this.stepHistory.updateOne({ _id: latestHistory[0]._id }, { $set: { status: 'succeeded', result } });
         }
     }
-    async setStepError(stepId, error) {
+    async setStepErrorImpl(stepId, error) {
         const serializedError = {
             message: error.message,
             stack: error.stack,
@@ -216,7 +219,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
             await this.stepHistory.updateOne({ _id: latestHistory[0]._id }, { $set: { status: 'failed', error: serializedError } });
         }
     }
-    async createRetryAttempt(stepId, status) {
+    async createRetryAttemptImpl(stepId, status) {
         await this.steps.updateOne({ _id: stepId }, {
             $set: {
                 status,
@@ -240,6 +243,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
             attemptCount,
             retries: row.retries != null ? Number(row.retries) : undefined,
             retryDelay: row.retryDelay ?? undefined,
+            fromStepName: row.fromStepName ?? undefined,
             createdAt: new Date(row.createdAt),
             updatedAt: new Date(row.updatedAt),
         };
@@ -293,6 +297,17 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
         const existingStepNames = new Set(result.map((r) => r.stepName));
         return nodeIds.filter((id) => !existingStepNames.has(id));
     }
+    async getStepInstances(runId) {
+        const rows = await this.steps
+            .find({ workflowRunId: runId })
+            .project({ stepName: 1, status: 1, fromStepName: 1 })
+            .toArray();
+        return rows.map((r) => ({
+            stepName: r.stepName,
+            status: r.status,
+            fromStepName: r.fromStepName ?? undefined,
+        }));
+    }
     async getNodeResults(runId, nodeIds) {
         if (nodeIds.length === 0)
             return {};
@@ -309,10 +324,10 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
         }
         return results;
     }
-    async setBranchTaken(stepId, branchKey) {
+    async setBranchTakenImpl(stepId, branchKey) {
         await this.steps.updateOne({ _id: stepId }, { $set: { branchTaken: branchKey, updatedAt: new Date() } });
     }
-    async updateRunState(runId, name, value) {
+    async updateRunStateImpl(runId, name, value) {
         if (!/^[a-zA-Z0-9_]+$/.test(name)) {
             throw new Error('Invalid state key name');
         }
@@ -329,7 +344,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
             return {};
         return row.state ?? {};
     }
-    async upsertWorkflowVersion(name, graphHash, graph, source, status) {
+    async upsertWorkflowVersionImpl(name, graphHash, graph, source, status) {
         await this.versions.updateOne({ workflowName: name, graphHash }, {
             $setOnInsert: {
                 workflowName: name,
@@ -341,7 +356,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
             },
         }, { upsert: true });
     }
-    async updateWorkflowVersionStatus(name, graphHash, status) {
+    async updateWorkflowVersionStatusImpl(name, graphHash, status) {
         await this.versions.updateOne({ workflowName: name, graphHash }, { $set: { status } });
     }
     async getWorkflowVersion(name, graphHash) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/mongodb",
-  "version": "0.12.5",
+  "version": "0.12.7",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/src/index.js",
@@ -17,7 +17,7 @@
     "prepublishOnly": "yarn build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.19"
+    "@pikku/core": "^0.12.38"
   },
   "dependencies": {
     "mongodb": "^6.12.0"
@@ -26,5 +26,8 @@
     "mongodb": "^6.12.0",
     "mongodb-memory-server": "^10.4.0",
     "typescript": "^5.9"
+  },
+  "exports": {
+    ".": "./dist/src/index.js"
   }
 }

package/src/mongodb-agent-run-service.ts

@@ -70,13 +70,18 @@ export class MongoDBAgentRunService implements AgentRunService {
 
   async listThreads(options?: {
     agentName?: string
+    resourceId?: string
     limit?: number
     offset?: number
   }): Promise<AIThread[]> {
-    const { agentName, limit = 50, offset = 0 } = options ?? {}
+    const { agentName, resourceId, limit = 50, offset = 0 } = options ?? {}
 
     let filter: Record<string, any> = {}
 
+    if (resourceId) {
+      filter.resourceId = resourceId
+    }
+
     if (agentName) {
       const threadIds = await this.runs.distinct('threadId', {
         agentName,

package/src/mongodb-channel-store.ts

@@ -8,6 +8,7 @@ interface ChannelDoc {
   createdAt: Date
   openingData: any
   pikkuUserId: string | null
+  state?: unknown
   lastWire: Date
 }
 
@@ -88,5 +89,21 @@ export class MongoDBChannelStore extends ChannelStore {
     }
   }
 
+  public async setState(channelId: string, state: unknown): Promise<void> {
+    await this.channels.updateOne({ _id: channelId }, { $set: { state } })
+  }
+
+  public async getState(channelId: string): Promise<unknown | undefined> {
+    const row = await this.channels.findOne(
+      { _id: channelId },
+      { projection: { state: 1 } }
+    )
+    return row?.state ?? undefined
+  }
+
+  public async clearState(channelId: string): Promise<void> {
+    await this.channels.updateOne({ _id: channelId }, { $unset: { state: '' } })
+  }
+
   public async close(): Promise<void> {}
 }

package/src/mongodb-secret-service.ts

@@ -87,36 +87,23 @@ export class MongoDBSecretService implements SecretService {
     throw new Error(`No KEK available for key_version ${version}`)
   }
 
-  async getSecret(key: string): Promise<string> {
+  async getSecret<T = string>(key: string): Promise<T> {
     const row = await this.secrets.findOne({ _id: key })
     if (!row) throw new Error('Requested secret not found')
 
     const kek = this.getKEK(row.keyVersion)
-    const result = await envelopeDecrypt<string>(
-      kek,
-      row.ciphertext,
-      row.wrappedDek
-    )
+    const result = await envelopeDecrypt<T>(kek, row.ciphertext, row.wrappedDek)
     await this.logAudit(key, 'read')
     return result
   }
 
-  async getSecretJSON<R = {}>(key: string): Promise<R> {
-    const raw = await this.getSecret(key)
-    return JSON.parse(raw) as R
-  }
-
   async hasSecret(key: string): Promise<boolean> {
     const count = await this.secrets.countDocuments({ _id: key }, { limit: 1 })
     return count > 0
   }
 
-  async setSecretJSON(key: string, value: unknown): Promise<void> {
-    const plaintext = JSON.stringify(value)
-    const { ciphertext, wrappedDEK } = await envelopeEncrypt(
-      this.key,
-      plaintext
-    )
+  async setSecret(key: string, value: unknown): Promise<void> {
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(this.key, value)
     const now = new Date()
 
     await this.secrets.updateOne(
@@ -144,6 +131,28 @@ export class MongoDBSecretService implements SecretService {
     await this.logAudit(key, 'delete')
   }
 
+  async getSecrets<
+    T extends Record<string, unknown> = Record<string, unknown>,
+  >(keys: (keyof T & string)[]): Promise<T> {
+    const rows = await this.secrets
+      .find({ _id: { $in: keys } } as any)
+      .toArray()
+    const out: Record<string, unknown> = {}
+    for (const row of rows) {
+      try {
+        const kek = this.getKEK(row.keyVersion)
+        out[row._id] = await envelopeDecrypt(
+          kek,
+          row.ciphertext,
+          row.wrappedDek
+        )
+      } catch {
+        // skip secrets that fail to decrypt
+      }
+    }
+    return out as T
+  }
+
   async rotateKEK(): Promise<number> {
     if (!this.previousKey) {
       throw new Error('No previousKey configured — nothing to rotate from')

package/src/mongodb-services.test.ts

@@ -71,7 +71,7 @@ function registerTests(name: string, getDb: () => Db) {
         auditReads: true,
       })
       await service.init()
-      await service.setSecretJSON('audit-test', 'value')
+      await service.setSecret('audit-test', 'value')
       await service.getSecret('audit-test')
       await service.deleteSecret('audit-test')
 
@@ -94,7 +94,7 @@ function registerTests(name: string, getDb: () => Db) {
         auditReads: false,
       })
       await service.init()
-      await service.setSecretJSON('no-read-audit', 'value')
+      await service.setSecret('no-read-audit', 'value')
       await service.getSecret('no-read-audit')
 
       const logs = await getDb()

package/src/mongodb-workflow-service.ts

@@ -5,6 +5,7 @@ import {
   type WorkflowRun,
   type WorkflowRunWire,
   type StepState,
+  type StepStatus,
   type WorkflowStatus,
   type WorkflowVersionStatus,
 } from '@pikku/core/workflow'
@@ -41,6 +42,7 @@ interface WorkflowStepDoc {
   branchTaken: string | null
   retries: number | null
   retryDelay: string | null
+  fromStepName?: string | null
   createdAt: Date
   updatedAt: Date
 }
@@ -110,7 +112,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     this.initialized = true
   }
 
-  async createRun(
+  protected async createRunImpl(
     workflowName: string,
     input: any,
     inline: boolean,
@@ -148,7 +150,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     return this.runService.getRun(id)
   }
 
-  async updateRunStatus(
+  protected async updateRunStatusImpl(
     id: string,
     status: WorkflowStatus,
     output?: any,
@@ -167,12 +169,13 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     )
   }
 
-  async insertStepState(
+  protected async insertStepStateImpl(
     runId: string,
     stepName: string,
     rpcName: string | null,
     data: any,
-    stepOptions?: { retries?: number; retryDelay?: string | number }
+    stepOptions?: { retries?: number; retryDelay?: string | number },
+    fromStepName?: string
   ): Promise<StepState> {
     const stepId = crypto.randomUUID()
     const now = new Date()
@@ -189,6 +192,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
       branchTaken: null,
       retries: stepOptions?.retries ?? null,
       retryDelay: stepOptions?.retryDelay?.toString() ?? null,
+      fromStepName: fromStepName ?? null,
       createdAt: now,
       updatedAt: now,
     })
@@ -203,6 +207,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
       attemptCount: 1,
       retries: stepOptions?.retries,
       retryDelay: stepOptions?.retryDelay?.toString(),
+      fromStepName,
       createdAt: now,
       updatedAt: now,
     }
@@ -232,6 +237,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
       attemptCount,
       retries: row.retries != null ? Number(row.retries) : undefined,
       retryDelay: row.retryDelay ?? undefined,
+      fromStepName: row.fromStepName ?? undefined,
       createdAt: new Date(row.createdAt),
       updatedAt: new Date(row.updatedAt),
     }
@@ -243,7 +249,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     return this.runService.getRunHistory(runId)
   }
 
-  async setStepRunning(stepId: string): Promise<void> {
+  protected async setStepRunningImpl(stepId: string): Promise<void> {
     await this.steps.updateOne(
       { _id: stepId },
       { $set: { status: 'running', updatedAt: new Date() } }
@@ -263,7 +269,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     }
   }
 
-  async setStepScheduled(stepId: string): Promise<void> {
+  protected async setStepScheduledImpl(stepId: string): Promise<void> {
     await this.steps.updateOne(
       { _id: stepId },
       { $set: { status: 'scheduled', updatedAt: new Date() } }
@@ -313,7 +319,10 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     }
   }
 
-  async setStepChildRunId(stepId: string, childRunId: string): Promise<void> {
+  protected async setStepChildRunIdImpl(
+    stepId: string,
+    childRunId: string
+  ): Promise<void> {
     await this.steps.updateOne(
       { _id: stepId },
       {
@@ -325,7 +334,10 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     )
   }
 
-  async setStepResult(stepId: string, result: any): Promise<void> {
+  protected async setStepResultImpl(
+    stepId: string,
+    result: any
+  ): Promise<void> {
     await this.steps.updateOne(
       { _id: stepId },
       {
@@ -352,7 +364,10 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     }
   }
 
-  async setStepError(stepId: string, error: Error): Promise<void> {
+  protected async setStepErrorImpl(
+    stepId: string,
+    error: Error
+  ): Promise<void> {
     const serializedError: SerializedError = {
       message: error.message,
       stack: error.stack,
@@ -385,7 +400,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     }
   }
 
-  async createRetryAttempt(
+  protected async createRetryAttemptImpl(
     stepId: string,
     status: 'pending' | 'running'
   ): Promise<StepState> {
@@ -418,6 +433,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
       attemptCount,
       retries: row.retries != null ? Number(row.retries) : undefined,
       retryDelay: row.retryDelay ?? undefined,
+      fromStepName: row.fromStepName ?? undefined,
       createdAt: new Date(row.createdAt),
       updatedAt: new Date(row.updatedAt),
     }
@@ -491,6 +507,20 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     return nodeIds.filter((id) => !existingStepNames.has(id))
   }
 
+  async getStepInstances(runId: string): Promise<
+    Array<{ stepName: string; status: StepStatus; fromStepName?: string }>
+  > {
+    const rows = await this.steps
+      .find({ workflowRunId: runId })
+      .project({ stepName: 1, status: 1, fromStepName: 1 })
+      .toArray()
+    return rows.map((r: any) => ({
+      stepName: r.stepName,
+      status: r.status as StepStatus,
+      fromStepName: r.fromStepName ?? undefined,
+    }))
+  }
+
   async getNodeResults(
     runId: string,
     nodeIds: string[]
@@ -512,14 +542,17 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     return results
   }
 
-  async setBranchTaken(stepId: string, branchKey: string): Promise<void> {
+  protected async setBranchTakenImpl(
+    stepId: string,
+    branchKey: string
+  ): Promise<void> {
     await this.steps.updateOne(
       { _id: stepId },
       { $set: { branchTaken: branchKey, updatedAt: new Date() } }
     )
   }
 
-  async updateRunState(
+  protected async updateRunStateImpl(
     runId: string,
     name: string,
     value: unknown
@@ -547,7 +580,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     return row.state ?? {}
   }
 
-  async upsertWorkflowVersion(
+  protected async upsertWorkflowVersionImpl(
     name: string,
     graphHash: string,
     graph: any,
@@ -570,7 +603,7 @@ export class MongoDBWorkflowService extends PikkuWorkflowService {
     )
   }
 
-  async updateWorkflowVersionStatus(
+  protected async updateWorkflowVersionStatusImpl(
     name: string,
     graphHash: string,
     status: WorkflowVersionStatus