@pikku/kysely 0.13.31 → 0.13.34

package/CHANGELOG.md

@@ -1,3 +1,87 @@
+## 0.13.34
+
+### Patch Changes
+
+- 80c94f9: MySQL is a third dialect for the `pikku db` commands, beside sqlite and postgres.
+
+  Set `mysqlUrl` in `createConfig` and `db migrate`, `generate`, `check`, `baseline`, `reset`, `codegen` and the dev seed behave as they do elsewhere, with migrations in `db/mysql/` and the seed in `db/mysql-dev-seed.sql`. MySQL has no embedded engine, so a command that needs a throwaway database creates and drops a `pikku_scratch_<hex>` one on your server — the account needs `CREATE` and `DROP`. DDL is not transactional there, so a migration that fails halfway is replayed from the top. `db.schema` is refused, because a MySQL schema is a database.
+
+  `@pikku/migrator-sql` gains `@pikku/migrator-sql/mysql`. The runtime schemas in `@pikku/kysely` now compile for MySQL without changing what sqlite and postgres get: keys are `varchar(255)`, free text is `longtext`, literal text defaults are expressions, and foreign keys are table-level constraints, because MySQL parses an inline `REFERENCES` and silently drops it. A foreign key onto a column another source owns takes that column's full type (`varchar(36)`), not the bare `varchar` the introspector reports.
+
+  An addon that ships `db/mysql` migrations needs `db.mysqlUrl` in its `pikku.config.json` for `pikku all` to publish them. The standalone bundle does not support MySQL yet and refuses a MySQL project by name.
+
+- Updated dependencies [149faae]
+  - @pikku/core@0.12.136
+
+## 0.13.33
+
+### Patch Changes
+
+- a16b0ba: The workflow run lease takes the app's `leaseService` (`holdLease(leaseService, 'workflow-run:<id>', …)`) in place of `pg_advisory_lock` / `GET_LOCK`, for DSL and graph runs alike. A message for a run already being orchestrated elsewhere wakes the run again a second later instead of failing, so a long pass never spends the retry budget the queue keeps for real failures. An inline run whose lease was lost after its body finished keeps the outcome it wrote. `PgWorkflowQueueOptions` and `RunLockHoldTimeoutError` are removed. `WorkflowService.withRunLock` is renamed `withRunLease`, since what it holds runs out unless renewed; a custom workflow service overriding it renames the method.
+
+  Pass the lease service to the workflow service — `new PgKyselyWorkflowService(db, { leaseService })` — register the same instance as the app's `leaseService`, and migrate `pikku_lease`.
+
+  A step lease is renewed by the same loop as the run lease. A graph node whose worker died is dispatched again once its lease lapses, instead of leaving the run waiting on it. A replayed step on Kysely now sees its lease, as `getStepState` does. The in-memory store refuses a superseded worker's outcome, as the database stores do. The MySQL workflow service can now record a workflow version; it used `ON CONFLICT`, which MySQL does not have.
+
+  `pikku db generate` now writes the `pikku_lease` table for any project that runs workflows, not only one that reaches `leaseService`, since every persistent workflow service holds its runs and steps there.
+
+- a16b0ba: Give a running workflow step a lease, so a step whose worker dies can be claimed again
+
+  A step moving from `pending` to `running` only proves it was dispatched; it says
+  nothing about whether the worker holding it is still alive. A worker that died
+  mid-step therefore left the step wedged in `running` forever: unclaimable by the
+  next dispatch, and invisible to the stalled-run sweep.
+
+  The dispatch that claims a step now stamps a lease on it, refreshes that lease on
+  an interval for as long as it is working, and releases it when the step parks on
+  a child run. A step whose lease has lapsed is claimable again, and counts as
+  in-flight no longer, so the stalled sweep can pick its run back up. A step that
+  keeps losing its worker fails with `WorkflowStepLeaseExpiredError` once its
+  attempts run out, rather than looping.
+
+  The lease duration is taken from the queue the step is dispatched through, so the
+  lease and the queue lock never disagree about who owns the job.
+
+  The refresh runs at half the lease and never later, even when that is under the
+  one-second floor the interval otherwise respects: applying that floor as a
+  maximum would renew a shorter lease for the first time after it had already
+  lapsed, which is the double-claim the lease exists to prevent. A lease that
+  short is logged once, pointing at the queue's `lockDuration`.
+
+  The lease is written and judged on the database's clock, never the worker's,
+  so a worker whose clock runs fast cannot claim a step another worker still
+  holds. A dispatch whose step has since been claimed by another stops renewing,
+  and says so: `refreshStepLease(stepId, leaseMs, attempt)` resolves `false` once
+  the step is no longer that attempt's.
+
+  The lease lives in a new `workflow_step.lease_expires_at` column, in epoch
+  milliseconds (`bigint`). Run `pikku db generate` and `pikku db migrate` after
+  upgrading: the runtime does not add columns, and every step read selects this
+  one.
+
+- a16b0ba: Persistent workflow services take a required `leaseService` (`WorkflowServiceOptions`) and lock runs and steps on it. The Postgres advisory and MySQL `GET_LOCK` step locks, and Redis's own `SET NX` run and step locks, are removed; `RedisWorkflowService` now takes `(connection, { leaseService, keyPrefix? })`.
+- Updated dependencies [a16b0ba]
+- Updated dependencies [21e9c3a]
+- Updated dependencies [a16b0ba]
+- Updated dependencies [a16b0ba]
+  - @pikku/core@0.12.133
+
+## 0.13.32
+
+### Patch Changes
+
+- 942ebdd: Add `LeaseService`: named leases shared by every process on the same store. A lease is not a mutex: a holder that stalls past its expiry loses the key without knowing, so whatever the body writes to should check the lease's `token` and refuse an older one. `acquire` never blocks and answers `null` while someone else holds the key; a lease lapses on its own if its holder dies; and each lease carries a `token` that rises every time the key changes hands, so a stale holder cannot refresh or release its successor's lease. `holdLease` refreshes the lease while its body runs, hands the body an `AbortSignal` that fires the moment the lease is lost, and throws `LeaseLostError` once the body finishes if the lease lapsed or changed hands meanwhile, so a caller never takes that result as produced under the lease.
+
+  Ships as `InMemoryLeaseService`, `PgKyselyLeaseService` (`@pikku/kysely-postgres`), `MySQLKyselyLeaseService` (`@pikku/kysely-mysql`) and `KyselyLeaseService` (SQLite), all on `pikku_lease`. The Postgres and MySQL services judge every lease by the database's clock, so a worker whose clock runs fast cannot take a live lease or stretch its own; `KyselyLeaseService` reads the process clock and is for a single-host SQLite app. `pikku db generate` writes the table for any project that reaches `leaseService`.
+
+  `RedisLeaseService` (`@pikku/redis`) keeps each lease in a hash Redis expires itself, with every check-and-set in one Lua script that reads Redis's `TIME`, so it too judges leases by the server's clock; its token counter outlives release, so the next holder always gets a higher token.
+
+- Updated dependencies [d327fa5]
+- Updated dependencies [942ebdd]
+- Updated dependencies [8ac25a8]
+- Updated dependencies [6606777]
+  - @pikku/core@0.12.132
+
 ## 0.13.31
 
 ### Patch Changes

package/README.md

@@ -15,16 +15,26 @@ npm install @pikku/kysely kysely
 ## Usage
 
 ```typescript
-import { KyselyWorkflowService, KyselySecretService } from '@pikku/kysely'
+import {
+  KyselyLeaseService,
+  KyselySecretService,
+  KyselyWorkflowService,
+} from '@pikku/kysely'
 import type { KyselyPikkuDB } from '@pikku/kysely'
 import type { Kysely } from 'kysely'
 
 declare const db: Kysely<KyselyPikkuDB>
 
-const workflowService = new KyselyWorkflowService(db)
+const leaseService = new KyselyLeaseService(db)
+await leaseService.init()
+
+const workflowService = new KyselyWorkflowService(db, { leaseService })
 const secretService = new KyselySecretService(db, { key: encryptionKey })
 ```
 
+The workflow service locks runs and steps on the `leaseService` you give it;
+register the same instance as the app's `leaseService`.
+
 ## Docs
 
 https://pikku.dev/docs

package/dist/src/index.d.ts

@@ -15,6 +15,7 @@ export { KyselyFeatureFlagStore } from './kysely-feature-flag-store.js';
 export type { KyselyFeatureFlagStoreOptions } from './kysely-feature-flag-store.js';
 export { KyselyWebhookService } from './kysely-webhook-service.js';
 export { KyselyTriggerSourceStore } from './kysely-trigger-source-store.js';
+export { KyselyLeaseService } from './kysely-lease-service.js';
 export { KyselyIncomingWebhookService } from './kysely-incoming-webhook-service.js';
 export { createAuditedKysely, type CreateAuditedKyselyOptions, } from './create-audited-kysely.js';
 export { KyselyAuditService } from './kysely-audit-service.js';
@@ -26,7 +27,7 @@ export { SerializePlugin, BaseSerializePlugin, type Serializer, type Deserialize
 export { createCoercionPlugin, type ColumnKind, type CoercionMap, type CreateCoercionPluginOptions, } from './coercion-plugin.js';
 export { createClassificationPlugin, type CreateClassificationPluginOptions, } from './classification-plugin.js';
 export { ClassificationCrypto, DEFAULT_KEY_ID, isColumnEnvelope, parseColumnEnvelope, type ClassificationCryptoOptions, type ColumnEnvelope, type KEKResolver, type ResolvedKEK, } from './classification-crypto.js';
-export { agentSchema, analyticsSchema, auditSchema, channelSchema, credentialSchema, deploymentSchema, flagSchema, incomingWebhookSchema, scopeSchema, secretSchema, sessionSchema, virtualUserSchema, webhookSchema, workflowSchema, pikkuSchemas, requiredPikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, requirePikkuSchema, resolveRequirements, type PikkuSchema, type RequiredTypes, type UnmetRequirement, type SchemaStatementFactory, } from './schema/index.js';
+export { agentSchema, analyticsSchema, auditSchema, channelSchema, credentialSchema, deploymentSchema, flagSchema, incomingWebhookSchema, leaseSchema, scopeSchema, secretSchema, sessionSchema, virtualUserSchema, webhookSchema, workflowSchema, pikkuSchemas, requiredPikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, requirePikkuSchema, resolveRequirements, type PikkuSchema, type RequiredTypes, type UnmetRequirement, type SchemaStatementFactory, } from './schema/index.js';
 export type { KyselyPikkuDB } from './kysely-tables.js';
 export type { WorkflowRunService } from '@pikku/core/workflow';
 export type { AgentRunService, AgentRunRow } from '@pikku/core/agent';

package/dist/src/index.js

@@ -14,6 +14,7 @@ export { KyselyScopeService } from './kysely-scope-service.js';
 export { KyselyFeatureFlagStore } from './kysely-feature-flag-store.js';
 export { KyselyWebhookService } from './kysely-webhook-service.js';
 export { KyselyTriggerSourceStore } from './kysely-trigger-source-store.js';
+export { KyselyLeaseService } from './kysely-lease-service.js';
 export { KyselyIncomingWebhookService } from './kysely-incoming-webhook-service.js';
 export { createAuditedKysely, } from './create-audited-kysely.js';
 export { KyselyAuditService } from './kysely-audit-service.js';
@@ -28,4 +29,4 @@ export { SerializePlugin, BaseSerializePlugin, } from './serialize-plugin.js';
 export { createCoercionPlugin, } from './coercion-plugin.js';
 export { createClassificationPlugin, } from './classification-plugin.js';
 export { ClassificationCrypto, DEFAULT_KEY_ID, isColumnEnvelope, parseColumnEnvelope, } from './classification-crypto.js';
-export { agentSchema, analyticsSchema, auditSchema, channelSchema, credentialSchema, deploymentSchema, flagSchema, incomingWebhookSchema, scopeSchema, secretSchema, sessionSchema, virtualUserSchema, webhookSchema, workflowSchema, pikkuSchemas, requiredPikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, requirePikkuSchema, resolveRequirements, } from './schema/index.js';
+export { agentSchema, analyticsSchema, auditSchema, channelSchema, credentialSchema, deploymentSchema, flagSchema, incomingWebhookSchema, leaseSchema, scopeSchema, secretSchema, sessionSchema, virtualUserSchema, webhookSchema, workflowSchema, pikkuSchemas, requiredPikkuSchemas, applyPikkuSchemas, compilePikkuSchemas, requirePikkuSchema, resolveRequirements, } from './schema/index.js';

package/dist/src/kysely-lease-clock.d.ts

@@ -0,0 +1,14 @@
+import { type RawBuilder } from 'kysely';
+/**
+ * Now, in epoch milliseconds, as a SQL expression: the clock every lease in
+ * this package is granted and judged on.
+ *
+ * A lease is compared by whichever worker reads it next, so judging it on each
+ * worker's own clock lets a worker running ahead take a lease that is still
+ * held. The dialect services read the database's clock instead, which every
+ * worker shares. This default binds the process clock, for SQLite, where the
+ * database lives in the process anyway.
+ */
+export declare const appNowMs: () => RawBuilder<number>;
+/** `now + ms`, for a lease that runs `ms` from the clock's now. */
+export declare const leaseUntil: (now: RawBuilder<number>, ms: number) => RawBuilder<number>;

package/dist/src/kysely-lease-clock.js

@@ -0,0 +1,14 @@
+import { sql } from 'kysely';
+/**
+ * Now, in epoch milliseconds, as a SQL expression: the clock every lease in
+ * this package is granted and judged on.
+ *
+ * A lease is compared by whichever worker reads it next, so judging it on each
+ * worker's own clock lets a worker running ahead take a lease that is still
+ * held. The dialect services read the database's clock instead, which every
+ * worker shares. This default binds the process clock, for SQLite, where the
+ * database lives in the process anyway.
+ */
+export const appNowMs = () => sql `cast(${Date.now()} as bigint)`;
+/** `now + ms`, for a lease that runs `ms` from the clock's now. */
+export const leaseUntil = (now, ms) => sql `${now} + ${ms}`;

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

@@ -0,0 +1,37 @@
+import type { Lease, LeaseService } from '@pikku/core/services';
+import type { Kysely } from 'kysely';
+import type { KyselyPikkuDB } from './kysely-tables.js';
+/**
+ * Leases on the `pikku_lease` table.
+ *
+ * Use it directly on SQLite. On PostgreSQL and MySQL use
+ * `PgKyselyLeaseService` and `MySQLKyselyLeaseService`, which judge every lease
+ * on the database's clock rather than on each worker's own.
+ *
+ * Every statement is one MySQL can run too — no `RETURNING`, no conditional
+ * upsert — so the dialects differ only in `nowMs` and `insertIfAbsent`.
+ */
+export declare class KyselyLeaseService implements LeaseService {
+    protected db: Kysely<KyselyPikkuDB>;
+    private initialized;
+    constructor(db: Kysely<KyselyPikkuDB>);
+    init(): Promise<void>;
+    /** Now, in epoch milliseconds, on the clock leases are judged by. */
+    protected nowMs(): import("kysely").RawBuilder<number>;
+    /** Create the key's row, lapsed, unless it already has one. */
+    protected insertIfAbsent(key: string, holder: string): Promise<void>;
+    /**
+     * The row is created lapsed and then taken by the same guarded `UPDATE` as
+     * any other lapsed lease, so there is one path to holding a key. `token` is
+     * assigned first: MySQL evaluates `SET` left to right against the values
+     * already assigned, and the holder test must see the previous holder.
+     *
+     * Whether the update won is read back rather than taken from its row count,
+     * because MySQL counts rows changed, not rows matched.
+     */
+    acquire(key: string, holder: string, ttlMs: number): Promise<Lease | null>;
+    refresh(lease: Lease, ttlMs: number): Promise<Lease | null>;
+    release(lease: Lease): Promise<void>;
+    get(key: string): Promise<Lease | null>;
+    private readHeld;
+}

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

@@ -0,0 +1,116 @@
+import { appNowMs, leaseUntil } from './kysely-lease-clock.js';
+import { requirePikkuSchema } from './schema/index.js';
+import { leaseSchema } from './schema/lease.schema.js';
+const toLease = (row) => ({
+    key: row.key,
+    holder: row.holder,
+    token: Number(row.token),
+    expiresAt: new Date(Number(row.expiresAt)),
+});
+/**
+ * Leases on the `pikku_lease` table.
+ *
+ * Use it directly on SQLite. On PostgreSQL and MySQL use
+ * `PgKyselyLeaseService` and `MySQLKyselyLeaseService`, which judge every lease
+ * on the database's clock rather than on each worker's own.
+ *
+ * Every statement is one MySQL can run too — no `RETURNING`, no conditional
+ * upsert — so the dialects differ only in `nowMs` and `insertIfAbsent`.
+ */
+export class KyselyLeaseService {
+    db;
+    initialized = false;
+    constructor(db) {
+        this.db = db;
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        await requirePikkuSchema(this.db, leaseSchema);
+        this.initialized = true;
+    }
+    /** Now, in epoch milliseconds, on the clock leases are judged by. */
+    nowMs() {
+        return appNowMs();
+    }
+    /** Create the key's row, lapsed, unless it already has one. */
+    async insertIfAbsent(key, holder) {
+        await this.db
+            .insertInto('pikkuLease')
+            .values({ key, holder, token: 0, expiresAt: 0 })
+            .onConflict((oc) => oc.column('key').doNothing())
+            .execute();
+    }
+    /**
+     * The row is created lapsed and then taken by the same guarded `UPDATE` as
+     * any other lapsed lease, so there is one path to holding a key. `token` is
+     * assigned first: MySQL evaluates `SET` left to right against the values
+     * already assigned, and the holder test must see the previous holder.
+     *
+     * Whether the update won is read back rather than taken from its row count,
+     * because MySQL counts rows changed, not rows matched.
+     */
+    async acquire(key, holder, ttlMs) {
+        await this.insertIfAbsent(key, holder);
+        const now = this.nowMs();
+        await this.db
+            .updateTable('pikkuLease')
+            .set((eb) => ({
+            token: eb
+                .case()
+                .when(eb.and([eb('holder', '=', holder), eb('expiresAt', '>', now)]))
+                .then(eb.ref('token'))
+                .else(eb('token', '+', 1))
+                .end(),
+            holder,
+            expiresAt: leaseUntil(now, ttlMs),
+        }))
+            .where('key', '=', key)
+            .where((eb) => eb.or([eb('holder', '=', holder), eb('expiresAt', '<=', now)]))
+            .execute();
+        return this.readHeld(key, holder);
+    }
+    async refresh(lease, ttlMs) {
+        const now = this.nowMs();
+        await this.db
+            .updateTable('pikkuLease')
+            .set({ expiresAt: leaseUntil(now, ttlMs) })
+            .where('key', '=', lease.key)
+            .where('holder', '=', lease.holder)
+            .where('token', '=', lease.token)
+            .where('expiresAt', '>', now)
+            .execute();
+        return this.readHeld(lease.key, lease.holder, lease.token);
+    }
+    async release(lease) {
+        await this.db
+            .updateTable('pikkuLease')
+            .set({ expiresAt: 0 })
+            .where('key', '=', lease.key)
+            .where('holder', '=', lease.holder)
+            .where('token', '=', lease.token)
+            .execute();
+    }
+    async get(key) {
+        const row = await this.db
+            .selectFrom('pikkuLease')
+            .selectAll()
+            .where('key', '=', key)
+            .where('expiresAt', '>', this.nowMs())
+            .executeTakeFirst();
+        return row ? toLease(row) : null;
+    }
+    async readHeld(key, holder, token) {
+        let query = this.db
+            .selectFrom('pikkuLease')
+            .selectAll()
+            .where('key', '=', key)
+            .where('holder', '=', holder)
+            .where('expiresAt', '>', this.nowMs());
+        if (token !== undefined) {
+            query = query.where('token', '=', token);
+        }
+        const row = await query.executeTakeFirst();
+        return row ? toLease(row) : null;
+    }
+}

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

@@ -46,6 +46,13 @@ export interface WorkflowStepTable {
     fromStepName: string | null;
     /** The history attempt currently in flight; see WorkflowStepHistoryTable.attempt. */
     currentAttempt: number | null;
+    /**
+     * When the dispatch holding a `running` step stops owning it. Null is a step
+     * nothing is expected to hand back — one parked on a child run, or written
+     * before it was ever claimed. Epoch milliseconds, on the clock leases are
+     * judged by; see `appNowMs`.
+     */
+    leaseExpiresAt: number | null;
     createdAt: Generated<Date>;
     updatedAt: Generated<Date>;
 }
@@ -250,6 +257,14 @@ export interface PikkuTriggerSourceTable {
     detail: string | null;
     updatedAt: Generated<Date>;
 }
+/** A named lease, current or last. */
+export interface PikkuLeaseTable {
+    key: string;
+    holder: string;
+    token: number;
+    /** Epoch milliseconds on the clock leases are judged by; see `appNowMs`. */
+    expiresAt: number;
+}
 /** One subject's short-circuit, in either direction, over a flag's rollout. */
 export interface PikkuFeatureFlagOverridesTable {
     flag: string;
@@ -436,6 +451,7 @@ export interface KyselyPikkuDB {
     pikkuFeatureFlags: PikkuFeatureFlagsTable;
     pikkuFeatureFlagOverrides: PikkuFeatureFlagOverridesTable;
     pikkuTriggerSource: PikkuTriggerSourceTable;
+    pikkuLease: PikkuLeaseTable;
     channels: ChannelsTable;
     channelSubscriptions: ChannelSubscriptionsTable;
     workflowRuns: WorkflowRunsTable;

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

@@ -1,13 +1,13 @@
 import type { SerializedError } from '@pikku/core/errors';
 import { PikkuWorkflowService } from '@pikku/core/workflow';
-import type { WorkflowPlannedStep, WorkflowQueueOptions, WorkflowRun, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus } from '@pikku/core/workflow';
+import type { WorkflowPlannedStep, WorkflowServiceOptions, WorkflowRun, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus } from '@pikku/core/workflow';
 import { type Kysely } from 'kysely';
 import type { KyselyPikkuDB } from './kysely-tables.js';
 export declare class KyselyWorkflowService extends PikkuWorkflowService {
     protected db: Kysely<KyselyPikkuDB>;
     private initialized;
     private runService;
-    constructor(db: Kysely<KyselyPikkuDB>, options?: WorkflowQueueOptions);
+    constructor(db: Kysely<KyselyPikkuDB>, options: WorkflowServiceOptions);
     init(): Promise<void>;
     protected createRunImpl(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire, options?: {
         deterministic?: boolean;
@@ -23,10 +23,18 @@ export declare class KyselyWorkflowService extends PikkuWorkflowService {
     protected listStepStates(runId: string): Promise<Array<StepState & {
         stepName: string;
     }>>;
+    getRunSteps(runId: string): Promise<Array<StepState & {
+        stepName: string;
+        rpcName?: string;
+        data?: any;
+    }>>;
     getRunHistory(runId: string): Promise<Array<StepState & {
         stepName: string;
     }>>;
     protected setStepRunningImpl(stepId: string): Promise<void>;
+    refreshStepLease(stepId: string, leaseMs: number | null, attempt?: number): Promise<boolean>;
+    /** Now, in epoch milliseconds, on the clock step leases are judged by. */
+    protected nowMs(): import("kysely").RawBuilder<number>;
     protected setStepScheduledImpl(stepId: string): Promise<void>;
     /**
      * Move a step and its current history attempt to the same status in one
@@ -43,21 +51,10 @@ export declare class KyselyWorkflowService extends PikkuWorkflowService {
     private insertHistoryRecord;
     private getTimestampFieldForStatus;
     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 setStepResultImpl(stepId: string, result: any, attempt?: number): Promise<void>;
+    protected setStepErrorImpl(stepId: string, error: Error, attempt?: number): Promise<void>;
     protected createRetryAttemptImpl(stepId: string, status: 'pending' | 'running'): Promise<StepState>;
-    withRunLock<T>(_id: string, fn: () => Promise<T>): Promise<T>;
-    /**
-     * A pass-through, and deliberately so: the one decision that must exclude —
-     * claiming a step to execute it — is made by `claimStepForExecution` below as
-     * a single conditional write, which needs no lock to be exclusive.
-     *
-     * What is left are the suspend and approval sections in the engine, where the
-     * lock is genuine mutual exclusion rather than a claim. A dialect with a real
-     * primitive overrides this to cover them — `kysely-postgres` with
-     * `pg_advisory_xact_lock`, `kysely-mysql` with `GET_LOCK`.
-     */
-    withStepLock<T>(_runId: string, _stepName: string, fn: () => Promise<T>): Promise<T>;
+    private readStepAttempt;
     /**
      * Claim the step with a status-guarded `UPDATE` and read the affected-row
      * count: the database decides the winner in one statement, so two dispatches
@@ -70,11 +67,29 @@ export declare class KyselyWorkflowService extends PikkuWorkflowService {
      *
      * The winner then goes through the ordinary transition methods, so history
      * rows and the mirror see exactly what they saw before.
+     *
+     * A `running` step is taken back only once its lease has lapsed, and the
+     * lease is part of the same guarded `UPDATE` — checking it here and writing
+     * it afterwards would let two dispatches read one lapsed lease and both
+     * proceed. Whether it has lapsed is the database's call, on its own clock:
+     * a live lease simply matches no row.
+     */
+    protected claimStepForExecution(runId: string, stepName: string, rpcName: string, leaseMs: number): Promise<StepState | null>;
+    /**
+     * Take back a failed or lapsed step as a new attempt. The attempt number is
+     * advanced by the same guarded `UPDATE` that grants the lease, so the worker
+     * it is taken from is fenced out of its step at once — deferring that to
+     * `createRetryAttempt` would leave a window in which its result still lands,
+     * only to be cleared and the step run again.
      */
-    protected claimStepForExecution(runId: string, stepName: string, rpcName: string): Promise<StepState | null>;
+    private reclaimStepAttempt;
     /**
-     * Move a step to `running` only if it is still in one of `from`, reporting
-     * whether this caller is the one that moved it.
+     * Move a step to `running` under a fresh lease, only if it is still in one of
+     * `from`, reporting whether this caller is the one that moved it.
+     *
+     * Claiming back a `running` step additionally requires its lease to have
+     * lapsed. A null lease never matches, which is what keeps a step parked on a
+     * child run — running, with no worker on it by design — out of reach.
      */
     private claimStepStatus;
     getCompletedGraphState(runId: string): Promise<{
@@ -86,6 +101,7 @@ export declare class KyselyWorkflowService extends PikkuWorkflowService {
         stepName: string;
         status: StepStatus;
         fromStepName?: string;
+        leaseExpiresAt?: Date;
     }>>;
     getNodeResults(runId: string, nodeIds: string[]): Promise<Record<string, any>>;
     protected setBranchTakenImpl(stepId: string, branchKey: string): Promise<void>;
@@ -113,7 +129,7 @@ export declare class KyselyWorkflowService extends PikkuWorkflowService {
      * The undispatched-step query, shared by every dialect.
      *
      * It used to be deliberately NOT an override, because this class's
-     * `withStepLock` is a pass-through: a subclass inheriting it (kysely-sqlite)
+     * `withStepLock` was a pass-through: a subclass inheriting it (kysely-sqlite)
      * had no atomic claim, so the relay's redundant dispatches would have become
      * double executions, and only `kysely-postgres` and `kysely-mysql` opted in
      * on the strength of their real locks. `claimStepForExecution` no longer