@pikku/kysely 0.12.15 → 0.12.17

package/CHANGELOG.md

@@ -1,3 +1,87 @@
+## 0.12.17
+
+### 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.16
+
+### Patch Changes
+
+- 6565b97: Fix `KyselyWorkflowRunService.getRunSteps`: build the `runningAt` /
+  `succeededAt` / `failedAt` correlated subqueries through the query builder
+  instead of raw `sql` fragments, so the active schema (`withSchema(...)`)
+  qualifies `workflow_step_history`. The raw fragments hardcoded an unqualified
+  table name and failed with `relation "workflow_step_history" does not exist`
+  against a connection whose `search_path` did not include the schema.
+- 34f254e: Bump the `kysely` dependency range to `^0.29.0` so it dedupes onto a single
+  copy alongside Better Auth (which bundles kysely 0.29.x), avoiding two
+  incompatible `Kysely` classes (the `#private` brand mismatch) when both pikku's
+  adapters and Better Auth share a database connection.
+
+  kysely 0.29 is ESM-only, which the unmaintained `kysely-plugin-serialize`
+  (no `exports` map, CommonJS build) cannot import. Its `SerializePlugin` is now
+  maintained directly in `@pikku/kysely` and re-exported, and the external
+  dependency is dropped from `@pikku/kysely`, `@pikku/kysely-sqlite`, and
+  `@pikku/cloudflare`.
+
 ## 0.12.15
 
 ### Patch Changes

package/dist/src/index.d.ts

@@ -13,6 +13,7 @@ export { KyselyCredentialService } from './kysely-credential-service.js';
 export type { KyselyCredentialServiceConfig } from './kysely-credential-service.js';
 export { KyselySessionStore } from './kysely-session-store.js';
 export { createAuditedKysely, type CreateAuditedKyselyOptions, } from './create-audited-kysely.js';
+export { SerializePlugin, SqliteSerializePlugin, BaseSerializePlugin, defaultSerializer, defaultDeserializer, maybeJson, skipTransform, dateRegex, type Serializer, type Deserializer, type SerializePluginOptions, } from './serialize-plugin.js';
 export type { KyselyPikkuDB } from './kysely-tables.js';
 export type { WorkflowRunService } from '@pikku/core/workflow';
 export type { AgentRunService, AgentRunRow } from '@pikku/core/ai-agent';

package/dist/src/index.js

@@ -11,3 +11,4 @@ export { KyselySecretService } from './kysely-secret-service.js';
 export { KyselyCredentialService } from './kysely-credential-service.js';
 export { KyselySessionStore } from './kysely-session-store.js';
 export { createAuditedKysely, } from './create-audited-kysely.js';
+export { SerializePlugin, SqliteSerializePlugin, BaseSerializePlugin, defaultSerializer, defaultDeserializer, maybeJson, skipTransform, dateRegex, } from './serialize-plugin.js';

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

@@ -24,6 +24,6 @@ export declare class KyselySecretService implements SecretService {
     hasSecret(key: string): Promise<boolean>;
     setSecret(key: string, value: unknown): Promise<void>;
     deleteSecret(key: string): Promise<void>;
-    getSecrets(keys: string[]): Promise<Record<string, unknown>>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<T>;
     rotateKEK(): Promise<number>;
 }

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

@@ -122,8 +122,15 @@ export class KyselySecretService {
                 const kek = this.getKEK(row.keyVersion);
                 out[row.key] = await envelopeDecrypt(kek, row.ciphertext, row.wrappedDek);
             }
-            catch {
-                // skip secrets that fail to decrypt
+            catch (cause) {
+                // A stored secret that fails to decrypt is never expected — it means the
+                // KEK does not match what the value was wrapped under (mismatched
+                // PIKKU_SECRET_KEK, or a missing previousKey for an older key_version).
+                // Swallowing it produces an undefined secret and an opaque downstream
+                // failure (e.g. an auth "server configuration" 500). Fail loud, naming
+                // the key and key_version so the misconfiguration is diagnosable.
+                throw new Error(`Failed to decrypt secret "${row.key}" (key_version ${row.keyVersion}): ` +
+                    `the configured KEK does not match the key it was wrapped under`, { cause });
             }
         }
         return out;

package/dist/src/kysely-tables.d.ts

@@ -43,6 +43,7 @@ export interface WorkflowStepTable {
     branchTaken: string | null;
     retries: number | null;
     retryDelay: string | null;
+    fromStepName: string | null;
     createdAt: Generated<Date>;
     updatedAt: Generated<Date>;
 }

package/dist/src/kysely-workflow-run-service.js

@@ -1,4 +1,3 @@
-import { sql } from 'kysely';
 import { parseJson } from './kysely-json.js';
 export class KyselyWorkflowRunService {
     db;
@@ -83,9 +82,26 @@ export class KyselyWorkflowRunService {
             .select(eb.fn.countAll().as('cnt'))
             .whereRef('workflowStepHistory.workflowStepId', '=', 's.workflowStepId')
             .as('attemptCount'))
-            .select(sql `(SELECT MAX(h.running_at) FROM workflow_step_history h WHERE h.workflow_step_id = s.workflow_step_id)`.as('runningAt'))
-            .select(sql `(SELECT MAX(h.succeeded_at) FROM workflow_step_history h WHERE h.workflow_step_id = s.workflow_step_id)`.as('succeededAt'))
-            .select(sql `(SELECT MAX(h.failed_at) FROM workflow_step_history h WHERE h.workflow_step_id = s.workflow_step_id)`.as('failedAt'))
+            // Build these correlated subqueries through the query builder rather
+            // than a raw `sql` fragment so the active schema (e.g.
+            // `withSchema('app')`) is applied to `workflow_step_history`. A raw
+            // fragment hardcodes an unqualified table name and dies against a
+            // connection whose search_path does not include the schema.
+            .select((eb) => eb
+            .selectFrom('workflowStepHistory')
+            .select((eb2) => eb2.fn.max('workflowStepHistory.runningAt').as('m'))
+            .whereRef('workflowStepHistory.workflowStepId', '=', 's.workflowStepId')
+            .as('runningAt'))
+            .select((eb) => eb
+            .selectFrom('workflowStepHistory')
+            .select((eb2) => eb2.fn.max('workflowStepHistory.succeededAt').as('m'))
+            .whereRef('workflowStepHistory.workflowStepId', '=', 's.workflowStepId')
+            .as('succeededAt'))
+            .select((eb) => eb
+            .selectFrom('workflowStepHistory')
+            .select((eb2) => eb2.fn.max('workflowStepHistory.failedAt').as('m'))
+            .whereRef('workflowStepHistory.workflowStepId', '=', 's.workflowStepId')
+            .as('failedAt'))
             .where('s.workflowRunId', '=', runId)
             .orderBy('s.createdAt', 'asc')
             .execute();

package/dist/src/kysely-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 { Kysely } from 'kysely';
 import type { KyselyPikkuDB } from './kysely-tables.js';
 export declare class KyselyWorkflowService extends PikkuWorkflowService {
@@ -17,7 +17,7 @@ export declare class KyselyWorkflowService extends PikkuWorkflowService {
     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;
@@ -38,6 +38,11 @@ export declare class KyselyWorkflowService 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>>;
     protected setBranchTakenImpl(stepId: string, branchKey: string): Promise<void>;
     protected updateRunStateImpl(runId: string, name: string, value: unknown): Promise<void>;

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

@@ -55,6 +55,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
             .addColumn('branch_taken', 'text')
             .addColumn('retries', 'integer')
             .addColumn('retry_delay', 'text')
+            .addColumn('from_step_name', 'text')
             .addColumn('created_at', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
             .addColumn('updated_at', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
             .addUniqueConstraint('workflow_step_run_name_unique', [
@@ -62,6 +63,14 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
             'step_name',
         ])
             .execute();
+        // Additive: backfill the column on tables created before from_step_name.
+        await this.db.schema
+            .alterTable('workflow_step')
+            .addColumn('from_step_name', 'text')
+            .execute()
+            .catch(() => {
+            // Column already exists (fresh tables include it above) — nothing to do.
+        });
         await this.db.schema
             .createTable('workflow_step_history')
             .ifNotExists()
@@ -132,7 +141,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
             .where('workflowRunId', '=', id)
             .execute();
     }
-    async insertStepStateImpl(runId, stepName, rpcName, data, stepOptions) {
+    async insertStepStateImpl(runId, stepName, rpcName, data, stepOptions, fromStepName) {
         const stepId = crypto.randomUUID();
         const now = new Date();
         await this.db
@@ -146,6 +155,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
             status: 'pending',
             retries: stepOptions?.retries ?? null,
             retryDelay: stepOptions?.retryDelay?.toString() ?? null,
+            fromStepName: fromStepName ?? null,
             createdAt: now,
             updatedAt: now,
         })
@@ -159,6 +169,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
             attemptCount: 1,
             retries: stepOptions?.retries,
             retryDelay: stepOptions?.retryDelay?.toString(),
+            fromStepName,
             createdAt: now,
             updatedAt: now,
         };
@@ -173,6 +184,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
             's.error',
             's.retries',
             's.retryDelay',
+            's.fromStepName',
             's.createdAt',
             's.updatedAt',
         ])
@@ -195,6 +207,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
             attemptCount: Number(row.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),
         };
@@ -348,6 +361,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
             's.error',
             's.retries',
             's.retryDelay',
+            's.fromStepName',
             's.createdAt',
             's.updatedAt',
         ])
@@ -366,6 +380,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
             attemptCount: Number(row.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),
         };
@@ -420,6 +435,18 @@ export class KyselyWorkflowService 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.db
+            .selectFrom('workflowStep')
+            .select(['stepName', 'status', 'fromStepName'])
+            .where('workflowRunId', '=', runId)
+            .execute();
+        return rows.map((r) => ({
+            stepName: r.stepName,
+            status: r.status,
+            fromStepName: r.fromStepName ?? undefined,
+        }));
+    }
     async getNodeResults(runId, nodeIds) {
         if (nodeIds.length === 0)
             return {};

package/dist/src/serialize-plugin.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Serialize / deserialize plugin for Kysely.
+ *
+ * Adapted from `kysely-plugin-serialize` (MIT, by subframe7536 —
+ * https://github.com/subframe7536/kysely-plugin-serialize), which is
+ * unmaintained and ships no `exports` map, so modern Node16/ESM resolution
+ * falls back to its CommonJS build and cannot import ESM-only kysely (>= 0.29).
+ * Maintained here directly as part of @pikku/kysely so we publish it ourselves.
+ *
+ * Serializes object/array/Date/boolean parameters to strings on the way into
+ * SQLite-style dialects, and deserializes them back on the way out.
+ */
+import { type KyselyPlugin, type PluginTransformQueryArgs, type PluginTransformResultArgs, type QueryResult, type RootOperationNode, type UnknownRow } from 'kysely';
+export type Serializer = (parameter: unknown) => unknown;
+export type Deserializer = (parameter: unknown) => unknown;
+export declare const defaultSerializer: Serializer;
+export declare const dateRegex: RegExp;
+export declare const defaultDeserializer: Deserializer;
+/**
+ * Checks if a given string parameter is a JSON-like string.
+ *
+ * Determines whether the input starts and ends with curly braces `{}` or
+ * square brackets `[]`, the typical indicators of JSON objects and arrays.
+ */
+export declare function maybeJson(parameter: string): boolean;
+/**
+ * Determines whether a given parameter should be skipped during transformation.
+ *
+ * Skipped when it is `undefined`, `null`, a `bigint`, a `number`, or an object
+ * that exposes a `buffer` property (e.g. a typed array / Buffer).
+ */
+export declare function skipTransform(parameter: unknown): boolean;
+export declare class BaseSerializePlugin implements KyselyPlugin {
+    private readonly transformer;
+    private readonly deserializer;
+    private readonly skipNodeSet?;
+    private readonly ctx?;
+    /**
+     * Base class for {@link SerializePlugin}, without default options.
+     */
+    constructor(serializer: Serializer, deserializer: Deserializer, skipNodeKind: Array<RootOperationNode['kind']>);
+    transformQuery({ node, queryId, }: PluginTransformQueryArgs): RootOperationNode;
+    transformResult({ result, queryId, }: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>>;
+    private parseRows;
+}
+export interface SerializePluginOptions {
+    /**
+     * serialize params
+     */
+    serializer?: Serializer;
+    /**
+     * deserialize params
+     */
+    deserializer?: Deserializer;
+    /**
+     * node kind to skip transform
+     */
+    skipNodeKind?: Array<RootOperationNode['kind']>;
+}
+export declare class SerializePlugin extends BaseSerializePlugin {
+    /**
+     * _**THIS PLUGIN SHOULD BE PLACED AT THE END OF PLUGINS ARRAY !!!**_
+     *
+     * reference from https://github.com/koskimas/kysely/pull/138
+     *
+     * Serializes object/array/Date/boolean column values to strings for
+     * SQLite-style dialects and deserializes them on the way back out. Pass a
+     * custom `serializer`/`deserializer` to override the default behaviour.
+     */
+    constructor(options?: SerializePluginOptions);
+}
+/**
+ * @deprecated use {@link SerializePlugin} instead
+ */
+export declare const SqliteSerializePlugin: typeof SerializePlugin;

package/dist/src/serialize-plugin.js

@@ -0,0 +1,177 @@
+/**
+ * Serialize / deserialize plugin for Kysely.
+ *
+ * Adapted from `kysely-plugin-serialize` (MIT, by subframe7536 —
+ * https://github.com/subframe7536/kysely-plugin-serialize), which is
+ * unmaintained and ships no `exports` map, so modern Node16/ESM resolution
+ * falls back to its CommonJS build and cannot import ESM-only kysely (>= 0.29).
+ * Maintained here directly as part of @pikku/kysely so we publish it ourselves.
+ *
+ * Serializes object/array/Date/boolean parameters to strings on the way into
+ * SQLite-style dialects, and deserializes them back on the way out.
+ */
+import { OperationNodeTransformer, } from 'kysely';
+class SerializeParametersTransformer extends OperationNodeTransformer {
+    serializer;
+    constructor(serializer) {
+        super();
+        this.serializer = serializer;
+    }
+    transformPrimitiveValueList(node) {
+        return {
+            ...node,
+            values: node.values.map(this.serializer),
+        };
+    }
+    // https://www.npmjs.com/package/zodsql
+    transformColumnUpdate(node) {
+        const { value: valueNode } = node;
+        if (valueNode.kind !== 'ValueNode') {
+            return super.transformColumnUpdate(node);
+        }
+        const { value, ...item } = valueNode;
+        const serializedValue = this.serializer(value);
+        if (value === serializedValue) {
+            return super.transformColumnUpdate(node);
+        }
+        const serializedNode = { ...item, value: serializedValue };
+        return super.transformColumnUpdate({ ...node, value: serializedNode });
+    }
+    transformValue(node) {
+        return {
+            ...node,
+            value: this.serializer(node.value),
+        };
+    }
+}
+export const defaultSerializer = (parameter) => {
+    if (skipTransform(parameter) || typeof parameter === 'string') {
+        return parameter;
+    }
+    else if (typeof parameter === 'boolean') {
+        return '' + parameter;
+    }
+    else if (parameter instanceof Date) {
+        return parameter.toISOString();
+    }
+    else {
+        try {
+            return JSON.stringify(parameter);
+        }
+        catch {
+            return parameter;
+        }
+    }
+};
+export const dateRegex = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?$/;
+export const defaultDeserializer = (parameter) => {
+    if (skipTransform(parameter)) {
+        return parameter;
+    }
+    if (typeof parameter === 'string') {
+        if (parameter === 'true') {
+            return true;
+        }
+        else if (parameter === 'false') {
+            return false;
+        }
+        else if (dateRegex.test(parameter)) {
+            return new Date(parameter);
+        }
+        else if (maybeJson(parameter)) {
+            try {
+                return JSON.parse(parameter);
+            }
+            catch {
+                // not valid JSON — fall through and return the raw string
+            }
+        }
+        return parameter;
+    }
+    return parameter;
+};
+/**
+ * Checks if a given string parameter is a JSON-like string.
+ *
+ * Determines whether the input starts and ends with curly braces `{}` or
+ * square brackets `[]`, the typical indicators of JSON objects and arrays.
+ */
+export function maybeJson(parameter) {
+    return ((parameter.startsWith('{') && parameter.endsWith('}')) ||
+        (parameter.startsWith('[') && parameter.endsWith(']')));
+}
+/**
+ * Determines whether a given parameter should be skipped during transformation.
+ *
+ * Skipped when it is `undefined`, `null`, a `bigint`, a `number`, or an object
+ * that exposes a `buffer` property (e.g. a typed array / Buffer).
+ */
+export function skipTransform(parameter) {
+    return (parameter === undefined ||
+        parameter === null ||
+        typeof parameter === 'bigint' ||
+        typeof parameter === 'number' ||
+        (typeof parameter === 'object' && 'buffer' in parameter));
+}
+export class BaseSerializePlugin {
+    transformer;
+    deserializer;
+    skipNodeSet;
+    ctx;
+    /**
+     * Base class for {@link SerializePlugin}, without default options.
+     */
+    constructor(serializer, deserializer, skipNodeKind) {
+        this.transformer = new SerializeParametersTransformer(serializer);
+        this.deserializer = deserializer;
+        if (skipNodeKind.length) {
+            this.skipNodeSet = new Set(skipNodeKind);
+            this.ctx = new WeakSet();
+        }
+    }
+    transformQuery({ node, queryId, }) {
+        if (this.skipNodeSet?.has(node.kind)) {
+            this.ctx?.add(queryId);
+            return node;
+        }
+        return this.transformer.transformNode(node);
+    }
+    async transformResult({ result, queryId, }) {
+        return this.ctx?.has(queryId)
+            ? result
+            : { ...result, rows: this.parseRows(result.rows) };
+    }
+    parseRows(rows) {
+        const result = [];
+        for (const row of rows) {
+            if (!row) {
+                continue;
+            }
+            const parsedRow = {};
+            for (const [key, value] of Object.entries(row)) {
+                parsedRow[key] = this.deserializer(value);
+            }
+            result.push(parsedRow);
+        }
+        return result;
+    }
+}
+export class SerializePlugin extends BaseSerializePlugin {
+    /**
+     * _**THIS PLUGIN SHOULD BE PLACED AT THE END OF PLUGINS ARRAY !!!**_
+     *
+     * reference from https://github.com/koskimas/kysely/pull/138
+     *
+     * Serializes object/array/Date/boolean column values to strings for
+     * SQLite-style dialects and deserializes them on the way back out. Pass a
+     * custom `serializer`/`deserializer` to override the default behaviour.
+     */
+    constructor(options = {}) {
+        const { deserializer = defaultDeserializer, serializer = defaultSerializer, skipNodeKind = [], } = options;
+        super(serializer, deserializer, skipNodeKind);
+    }
+}
+/**
+ * @deprecated use {@link SerializePlugin} instead
+ */
+export const SqliteSerializePlugin = SerializePlugin;

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/create-audited-kysely.ts","../src/index.ts","../src/kysely-ai-agent-run-service.ts","../src/kysely-ai-run-state-service.ts","../src/kysely-ai-storage-service.ts","../src/kysely-channel-store.ts","../src/kysely-credential-service.ts","../src/kysely-deployment-service.ts","../src/kysely-eventhub-store.ts","../src/kysely-json.ts","../src/kysely-secret-service.ts","../src/kysely-session-store.ts","../src/kysely-tables.ts","../src/kysely-workflow-mirror.ts","../src/kysely-workflow-run-service.ts","../src/kysely-workflow-service.ts","../bin/pikku-kysely-pure.ts"],"version":"5.9.3"}
+{"root":["../src/create-audited-kysely.ts","../src/index.ts","../src/kysely-ai-agent-run-service.ts","../src/kysely-ai-run-state-service.ts","../src/kysely-ai-storage-service.ts","../src/kysely-channel-store.ts","../src/kysely-credential-service.ts","../src/kysely-deployment-service.ts","../src/kysely-eventhub-store.ts","../src/kysely-json.ts","../src/kysely-secret-service.ts","../src/kysely-session-store.ts","../src/kysely-tables.ts","../src/kysely-workflow-mirror.ts","../src/kysely-workflow-run-service.ts","../src/kysely-workflow-service.ts","../src/serialize-plugin.ts","../bin/pikku-kysely-pure.ts"],"version":"5.9.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/kysely",
-  "version": "0.12.15",
+  "version": "0.12.17",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/src/index.js",
@@ -20,16 +20,15 @@
     "prepublishOnly": "yarn build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.28"
+    "@pikku/core": "^0.12.38"
   },
   "dependencies": {
-    "kysely": "^0.28.12"
+    "kysely": "^0.29.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "better-sqlite3": "^12.10.0",
     "kysely-codegen": "^0.20.0",
-    "kysely-plugin-serialize": "^0.8.2",
     "kysely-postgres-js": "^3.0.0",
     "postgres": "^3.4.8",
     "typescript": "^5.9"

package/src/index.ts

@@ -17,6 +17,20 @@ export {
   type CreateAuditedKyselyOptions,
 } from './create-audited-kysely.js'
 
+export {
+  SerializePlugin,
+  SqliteSerializePlugin,
+  BaseSerializePlugin,
+  defaultSerializer,
+  defaultDeserializer,
+  maybeJson,
+  skipTransform,
+  dateRegex,
+  type Serializer,
+  type Deserializer,
+  type SerializePluginOptions,
+} from './serialize-plugin.js'
+
 export type { KyselyPikkuDB } from './kysely-tables.js'
 export type { WorkflowRunService } from '@pikku/core/workflow'
 export type { AgentRunService, AgentRunRow } from '@pikku/core/ai-agent'

package/src/kysely-secret-service.ts

@@ -149,7 +149,9 @@ export class KyselySecretService implements SecretService {
     await this.logAudit(key, 'delete')
   }
 
-  async getSecrets(keys: string[]): Promise<Record<string, unknown>> {
+  async getSecrets<
+    T extends Record<string, unknown> = Record<string, unknown>,
+  >(keys: (keyof T & string)[]): Promise<T> {
     const rows = await this.db
       .selectFrom('secrets')
       .select(['key', 'ciphertext', 'wrappedDek', 'keyVersion'])
@@ -165,11 +167,21 @@ export class KyselySecretService implements SecretService {
           row.ciphertext,
           row.wrappedDek
         )
-      } catch {
-        // skip secrets that fail to decrypt
+      } catch (cause) {
+        // A stored secret that fails to decrypt is never expected — it means the
+        // KEK does not match what the value was wrapped under (mismatched
+        // PIKKU_SECRET_KEK, or a missing previousKey for an older key_version).
+        // Swallowing it produces an undefined secret and an opaque downstream
+        // failure (e.g. an auth "server configuration" 500). Fail loud, naming
+        // the key and key_version so the misconfiguration is diagnosable.
+        throw new Error(
+          `Failed to decrypt secret "${row.key}" (key_version ${row.keyVersion}): ` +
+            `the configured KEK does not match the key it was wrapped under`,
+          { cause }
+        )
       }
     }
-    return out
+    return out as T
   }
 
   async rotateKEK(): Promise<number> {

package/src/kysely-services.test.ts

@@ -1,7 +1,7 @@
 import { describe, test, before, after } from 'node:test'
 import assert from 'node:assert/strict'
 import { CamelCasePlugin, Kysely, SqliteDialect } from 'kysely'
-import { SerializePlugin } from 'kysely-plugin-serialize'
+import { SerializePlugin } from './serialize-plugin.js'
 import Database from 'better-sqlite3'
 import { PostgresJSDialect } from 'kysely-postgres-js'
 import postgres from 'postgres'

package/src/kysely-tables.ts

@@ -51,6 +51,7 @@ export interface WorkflowStepTable {
   branchTaken: string | null
   retries: number | null
   retryDelay: string | null
+  fromStepName: string | null
   createdAt: Generated<Date>
   updatedAt: Generated<Date>
 }

package/src/kysely-workflow-mirror.test.ts

@@ -1,7 +1,7 @@
 import { describe, test, beforeEach, afterEach } from 'node:test'
 import assert from 'node:assert/strict'
 import { CamelCasePlugin, Kysely, SqliteDialect } from 'kysely'
-import { SerializePlugin } from 'kysely-plugin-serialize'
+import { SerializePlugin } from './serialize-plugin.js'
 import Database from 'better-sqlite3'
 
 import type { KyselyPikkuDB } from './kysely-tables.js'

package/src/kysely-workflow-run-service.ts

@@ -5,7 +5,6 @@ import type {
   WorkflowRunService,
 } from '@pikku/core/workflow'
 import type { Kysely } from 'kysely'
-import { sql } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { parseJson } from './kysely-json.js'
 
@@ -112,14 +111,43 @@ export class KyselyWorkflowRunService implements WorkflowRunService {
           )
           .as('attemptCount')
       )
-      .select(
-        sql<string | null>`(SELECT MAX(h.running_at) FROM workflow_step_history h WHERE h.workflow_step_id = s.workflow_step_id)`.as('runningAt')
+      // Build these correlated subqueries through the query builder rather
+      // than a raw `sql` fragment so the active schema (e.g.
+      // `withSchema('app')`) is applied to `workflow_step_history`. A raw
+      // fragment hardcodes an unqualified table name and dies against a
+      // connection whose search_path does not include the schema.
+      .select((eb) =>
+        eb
+          .selectFrom('workflowStepHistory')
+          .select((eb2) => eb2.fn.max('workflowStepHistory.runningAt').as('m'))
+          .whereRef(
+            'workflowStepHistory.workflowStepId',
+            '=',
+            's.workflowStepId'
+          )
+          .as('runningAt')
       )
-      .select(
-        sql<string | null>`(SELECT MAX(h.succeeded_at) FROM workflow_step_history h WHERE h.workflow_step_id = s.workflow_step_id)`.as('succeededAt')
+      .select((eb) =>
+        eb
+          .selectFrom('workflowStepHistory')
+          .select((eb2) => eb2.fn.max('workflowStepHistory.succeededAt').as('m'))
+          .whereRef(
+            'workflowStepHistory.workflowStepId',
+            '=',
+            's.workflowStepId'
+          )
+          .as('succeededAt')
       )
-      .select(
-        sql<string | null>`(SELECT MAX(h.failed_at) FROM workflow_step_history h WHERE h.workflow_step_id = s.workflow_step_id)`.as('failedAt')
+      .select((eb) =>
+        eb
+          .selectFrom('workflowStepHistory')
+          .select((eb2) => eb2.fn.max('workflowStepHistory.failedAt').as('m'))
+          .whereRef(
+            'workflowStepHistory.workflowStepId',
+            '=',
+            's.workflowStepId'
+          )
+          .as('failedAt')
       )
       .where('s.workflowRunId', '=', runId)
       .orderBy('s.createdAt', 'asc')

package/src/kysely-workflow-service.ts

@@ -5,6 +5,7 @@ import {
   type WorkflowRun,
   type WorkflowRunWire,
   type StepState,
+  type StepStatus,
   type WorkflowStatus,
   type WorkflowVersionStatus,
 } from '@pikku/core/workflow'
@@ -79,6 +80,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
       .addColumn('branch_taken', 'text')
       .addColumn('retries', 'integer')
       .addColumn('retry_delay', 'text')
+      .addColumn('from_step_name', 'text')
       .addColumn('created_at', 'timestamp', (col) =>
         col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
       )
@@ -91,6 +93,15 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
       ])
       .execute()
 
+    // Additive: backfill the column on tables created before from_step_name.
+    await this.db.schema
+      .alterTable('workflow_step')
+      .addColumn('from_step_name', 'text')
+      .execute()
+      .catch(() => {
+        // Column already exists (fresh tables include it above) — nothing to do.
+      })
+
     await this.db.schema
       .createTable('workflow_step_history')
       .ifNotExists()
@@ -196,7 +207,8 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
     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()
@@ -212,6 +224,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
         status: 'pending',
         retries: stepOptions?.retries ?? null,
         retryDelay: stepOptions?.retryDelay?.toString() ?? null,
+        fromStepName: fromStepName ?? null,
         createdAt: now,
         updatedAt: now,
       })
@@ -227,6 +240,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
       attemptCount: 1,
       retries: stepOptions?.retries,
       retryDelay: stepOptions?.retryDelay?.toString(),
+      fromStepName,
       createdAt: now,
       updatedAt: now,
     }
@@ -242,6 +256,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
         's.error',
         's.retries',
         's.retryDelay',
+        's.fromStepName',
         's.createdAt',
         's.updatedAt',
       ])
@@ -274,6 +289,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
       attemptCount: Number(row.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),
     }
@@ -467,6 +483,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
         's.error',
         's.retries',
         's.retryDelay',
+        's.fromStepName',
         's.createdAt',
         's.updatedAt',
       ])
@@ -492,6 +509,7 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
       attemptCount: Number(row.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),
     }
@@ -568,6 +586,21 @@ export class KyselyWorkflowService 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.db
+      .selectFrom('workflowStep')
+      .select(['stepName', 'status', 'fromStepName'])
+      .where('workflowRunId', '=', runId)
+      .execute()
+    return rows.map((r) => ({
+      stepName: r.stepName,
+      status: r.status as StepStatus,
+      fromStepName: r.fromStepName ?? undefined,
+    }))
+  }
+
   async getNodeResults(
     runId: string,
     nodeIds: string[]

package/src/serialize-plugin.ts

@@ -0,0 +1,238 @@
+/**
+ * Serialize / deserialize plugin for Kysely.
+ *
+ * Adapted from `kysely-plugin-serialize` (MIT, by subframe7536 —
+ * https://github.com/subframe7536/kysely-plugin-serialize), which is
+ * unmaintained and ships no `exports` map, so modern Node16/ESM resolution
+ * falls back to its CommonJS build and cannot import ESM-only kysely (>= 0.29).
+ * Maintained here directly as part of @pikku/kysely so we publish it ourselves.
+ *
+ * Serializes object/array/Date/boolean parameters to strings on the way into
+ * SQLite-style dialects, and deserializes them back on the way out.
+ */
+import {
+  OperationNodeTransformer,
+  type ColumnUpdateNode,
+  type KyselyPlugin,
+  type PluginTransformQueryArgs,
+  type PluginTransformResultArgs,
+  type PrimitiveValueListNode,
+  type QueryId,
+  type QueryResult,
+  type RootOperationNode,
+  type UnknownRow,
+  type ValueNode,
+} from 'kysely'
+
+export type Serializer = (parameter: unknown) => unknown
+export type Deserializer = (parameter: unknown) => unknown
+
+class SerializeParametersTransformer extends OperationNodeTransformer {
+  private readonly serializer: Serializer
+
+  constructor(serializer: Serializer) {
+    super()
+    this.serializer = serializer
+  }
+
+  protected override transformPrimitiveValueList(
+    node: PrimitiveValueListNode
+  ): PrimitiveValueListNode {
+    return {
+      ...node,
+      values: node.values.map(this.serializer),
+    }
+  }
+
+  // https://www.npmjs.com/package/zodsql
+  protected override transformColumnUpdate(
+    node: ColumnUpdateNode
+  ): ColumnUpdateNode {
+    const { value: valueNode } = node
+    if (valueNode.kind !== 'ValueNode') {
+      return super.transformColumnUpdate(node)
+    }
+    const { value, ...item } = valueNode as ValueNode
+    const serializedValue = this.serializer(value)
+    if (value === serializedValue) {
+      return super.transformColumnUpdate(node)
+    }
+    const serializedNode: ValueNode = { ...item, value: serializedValue }
+    return super.transformColumnUpdate({ ...node, value: serializedNode })
+  }
+
+  protected override transformValue(node: ValueNode): ValueNode {
+    return {
+      ...node,
+      value: this.serializer(node.value),
+    }
+  }
+}
+
+export const defaultSerializer: Serializer = (parameter) => {
+  if (skipTransform(parameter) || typeof parameter === 'string') {
+    return parameter
+  } else if (typeof parameter === 'boolean') {
+    return '' + parameter
+  } else if (parameter instanceof Date) {
+    return parameter.toISOString()
+  } else {
+    try {
+      return JSON.stringify(parameter)
+    } catch {
+      return parameter
+    }
+  }
+}
+
+export const dateRegex = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?$/
+
+export const defaultDeserializer: Deserializer = (parameter) => {
+  if (skipTransform(parameter)) {
+    return parameter
+  }
+  if (typeof parameter === 'string') {
+    if (parameter === 'true') {
+      return true
+    } else if (parameter === 'false') {
+      return false
+    } else if (dateRegex.test(parameter)) {
+      return new Date(parameter)
+    } else if (maybeJson(parameter)) {
+      try {
+        return JSON.parse(parameter)
+      } catch {
+        // not valid JSON — fall through and return the raw string
+      }
+    }
+    return parameter
+  }
+  return parameter
+}
+
+/**
+ * Checks if a given string parameter is a JSON-like string.
+ *
+ * Determines whether the input starts and ends with curly braces `{}` or
+ * square brackets `[]`, the typical indicators of JSON objects and arrays.
+ */
+export function maybeJson(parameter: string): boolean {
+  return (
+    (parameter.startsWith('{') && parameter.endsWith('}')) ||
+    (parameter.startsWith('[') && parameter.endsWith(']'))
+  )
+}
+
+/**
+ * Determines whether a given parameter should be skipped during transformation.
+ *
+ * Skipped when it is `undefined`, `null`, a `bigint`, a `number`, or an object
+ * that exposes a `buffer` property (e.g. a typed array / Buffer).
+ */
+export function skipTransform(parameter: unknown): boolean {
+  return (
+    parameter === undefined ||
+    parameter === null ||
+    typeof parameter === 'bigint' ||
+    typeof parameter === 'number' ||
+    (typeof parameter === 'object' && 'buffer' in parameter)
+  )
+}
+
+export class BaseSerializePlugin implements KyselyPlugin {
+  private readonly transformer: SerializeParametersTransformer
+  private readonly deserializer: Deserializer
+  private readonly skipNodeSet?: Set<RootOperationNode['kind']>
+  private readonly ctx?: WeakSet<QueryId>
+
+  /**
+   * Base class for {@link SerializePlugin}, without default options.
+   */
+  constructor(
+    serializer: Serializer,
+    deserializer: Deserializer,
+    skipNodeKind: Array<RootOperationNode['kind']>
+  ) {
+    this.transformer = new SerializeParametersTransformer(serializer)
+    this.deserializer = deserializer
+    if (skipNodeKind.length) {
+      this.skipNodeSet = new Set(skipNodeKind)
+      this.ctx = new WeakSet()
+    }
+  }
+
+  transformQuery({
+    node,
+    queryId,
+  }: PluginTransformQueryArgs): RootOperationNode {
+    if (this.skipNodeSet?.has(node.kind)) {
+      this.ctx?.add(queryId)
+      return node
+    }
+    return this.transformer.transformNode(node)
+  }
+
+  async transformResult({
+    result,
+    queryId,
+  }: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+    return this.ctx?.has(queryId)
+      ? result
+      : { ...result, rows: this.parseRows(result.rows) }
+  }
+
+  private parseRows(rows: UnknownRow[]): UnknownRow[] {
+    const result: UnknownRow[] = []
+    for (const row of rows) {
+      if (!row) {
+        continue
+      }
+      const parsedRow: UnknownRow = {}
+      for (const [key, value] of Object.entries(row)) {
+        parsedRow[key] = this.deserializer(value)
+      }
+      result.push(parsedRow)
+    }
+    return result
+  }
+}
+
+export interface SerializePluginOptions {
+  /**
+   * serialize params
+   */
+  serializer?: Serializer
+  /**
+   * deserialize params
+   */
+  deserializer?: Deserializer
+  /**
+   * node kind to skip transform
+   */
+  skipNodeKind?: Array<RootOperationNode['kind']>
+}
+
+export class SerializePlugin extends BaseSerializePlugin {
+  /**
+   * _**THIS PLUGIN SHOULD BE PLACED AT THE END OF PLUGINS ARRAY !!!**_
+   *
+   * reference from https://github.com/koskimas/kysely/pull/138
+   *
+   * Serializes object/array/Date/boolean column values to strings for
+   * SQLite-style dialects and deserializes them on the way back out. Pass a
+   * custom `serializer`/`deserializer` to override the default behaviour.
+   */
+  constructor(options: SerializePluginOptions = {}) {
+    const {
+      deserializer = defaultDeserializer,
+      serializer = defaultSerializer,
+      skipNodeKind = [],
+    } = options
+    super(serializer, deserializer, skipNodeKind)
+  }
+}
+
+/**
+ * @deprecated use {@link SerializePlugin} instead
+ */
+export const SqliteSerializePlugin = SerializePlugin