@pikku/core 0.12.78 → 0.12.79

package/CHANGELOG.md

@@ -1,3 +1,76 @@
+## 0.12.79
+
+### Patch Changes
+
+- e848eb2: Add `relayUndispatchedSteps()`, which re-drives steps whose queue or scheduler
+  dispatch was lost.
+
+  Arming a step is two writes to two systems — the step row lands `pending`, then
+  a job is published — and nothing spans both, so a crash in between leaves a
+  durable row nothing will ever pick up. The run then neither finishes nor fails.
+
+  The step row is the outbox record and this is the relay. It is safe to
+  re-dispatch a step that already has a live job because `executeWorkflowStepInner`
+  claims the step under `withStepLock` before invoking anything: the loser reads
+  `running` and returns. Stores opt in by overriding `findUndispatchedSteps`; the
+  default returns nothing, so a store without an atomic step lock gains no
+  re-dispatches. Opted in: `kysely-postgres` and `kysely-mysql` (real locks) and
+  in-memory (inline, single-process, no queues). Not opted in: `mongodb` and
+  `kysely-sqlite`, whose `withStepLock` is a pass-through.
+
+  Not self-starting — call it from a scheduled task.
+
+- b170489: Gateway handlers now run under the metadata their author actually wrote, instead
+  of a fabricated meta object.
+
+  `registerGatewayHandler` used to synthesize `{ sessionless: true,
+inputSchemaName: null, outputSchemaName: null }` for every gateway handler, so a
+  function declared with `pikkuFunc` — which records "session required" in meta
+  rather than through an `auth` property — was silently made sessionless, and its
+  input schema was never validated. It now inherits `sessionless`, the schema
+  names, `scopes` and tag middleware from the function the gateway was wired with,
+  falling back to the old sessionless default only when nothing was declared (a
+  gateway wired by hand rather than through codegen).
+
+  Tag middleware also reaches gateways for the first time. `addTagMiddleware('x',
+…)` combined with `wireGateway({ tags: ['x'] })` previously resolved to nothing
+  at all — the inspector computed the middleware and no runtime path read it — so
+  a tag that read like a gate applied none.
+
+  **Both are tightening changes.** A gateway whose handler declared a session
+  requirement, or whose tags name registered middleware, now enforces what it
+  already said it enforced.
+
+- ae4e898: Carry a secret's `allowedHosts` through code generation, and close three gaps in
+  the SSRF guard.
+
+  `allowedHosts` was declared and enforced but never survived codegen: the
+  inspector did not read the property off the `defineSecret` literal, and the meta
+  builder rebuilt its objects without it. Enforcement in `assertSecretAllowedForHost`
+  then always saw `undefined`, so the egress restriction was a no-op by default —
+  and, with `secrets.requireAllowedHosts` set, threw for every secret including the
+  ones that correctly declared hosts. Both stages now carry the field, and the
+  secrets verifier asserts it against the generated JSON rather than a hand-written
+  meta literal, which is why the existing tests stayed green.
+
+  `isPrivateHost` now checks an explicit CIDR table instead of ad-hoc octet
+  comparisons. It previously missed `100.64.0.0/10` — which contains Alibaba
+  Cloud's `100.100.100.200` metadata endpoint — along with `192.0.0.0/24`,
+  `198.18.0.0/15`, `192.88.99.0/24`, the TEST-NETs, multicast and reserved space.
+  IPv6 gains a real parser, so `fec0::/10`, `ff00::/8`, and NAT64 (`64:ff9b::/96`)
+  and 6to4 (`2002::/16`) forms wrapping an internal IPv4 address are caught.
+
+  `safeFetch` takes an optional `resolveHost`, checked on the initial URL and every
+  redirect hop, so a _public_ hostname pointing at a private address is refused —
+  the `169-254-169-254.nip.io` shape a literal-only check cannot see. Core cannot
+  resolve DNS itself (Workers has no DNS API), so the Node resolver ships as
+  `@pikku/core/node-host-resolver` and the Node server runtimes install it during
+  `init()`. The connection is not pinned to the address that was checked, so a
+  rebind between check and connect is still possible.
+
+  The graph addon's `httpRequest` node called bare `fetch`, bypassing the guard
+  entirely; it now goes through `safeFetch`.
+
 ## 0.12.78
 
 ### Patch Changes

package/dist/services/in-memory-workflow-service.d.ts

@@ -29,6 +29,16 @@ export declare class InMemoryWorkflowService extends PikkuWorkflowService implem
     protected setStepErrorImpl(stepId: string, error: Error): Promise<void>;
     protected setStepChildRunIdImpl(stepId: string, childRunId: string): Promise<void>;
     protected createRetryAttemptImpl(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
+    /**
+     * Safe to opt in despite the pass-through `withStepLock`: this service wires
+     * no queues and runs every step inline in one process, so the relay's
+     * redundant dispatch has no second holder to race with. See
+     * knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
+     */
+    protected findUndispatchedSteps(before: Date, limit: number): Promise<Array<{
+        runId: string;
+        stepId: string;
+    }>>;
     protected findStalledRunIds(before: Date, limit: number): Promise<string[]>;
     listRuns(options?: {
         workflowName?: string;

package/dist/services/in-memory-workflow-service.js

@@ -199,6 +199,29 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         this.stepHistory.set(runId, history);
         return newStep;
     }
+    /**
+     * Safe to opt in despite the pass-through `withStepLock`: this service wires
+     * no queues and runs every step inline in one process, so the relay's
+     * redundant dispatch has no second holder to race with. See
+     * knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
+     */
+    async findUndispatchedSteps(before, limit) {
+        const undispatched = [];
+        for (const [runId, run] of this.runs) {
+            if (run.status !== 'running')
+                continue;
+            for (const step of this.stepHistory.get(runId) ?? []) {
+                if (step.status !== 'pending')
+                    continue;
+                if (step.updatedAt >= before)
+                    continue;
+                undispatched.push({ runId, stepId: step.stepId });
+                if (undispatched.length >= limit)
+                    return undispatched;
+            }
+        }
+        return undispatched;
+    }
     async findStalledRunIds(before, limit) {
         const stalled = [];
         for (const [runId, run] of this.runs) {

package/dist/utils/node-host-resolver.d.ts

@@ -0,0 +1,12 @@
+import { type HostResolver } from './safe-fetch.js';
+/**
+ * Resolves a hostname through the platform resolver, returning every address it
+ * points at so `safeFetch` can reject a public name aimed at an internal one.
+ *
+ * This module is Node-only and is never imported by core itself — Workers has no
+ * DNS API, and a static `node:dns` import in the shared path would break that
+ * build.
+ */
+export declare const nodeHostResolver: HostResolver;
+/** Installs {@link nodeHostResolver} as the default for every `safeFetch`. */
+export declare const installNodeHostResolver: () => void;

package/dist/utils/node-host-resolver.js

@@ -0,0 +1,16 @@
+import { lookup } from 'node:dns/promises';
+import { setDefaultHostResolver } from './safe-fetch.js';
+/**
+ * Resolves a hostname through the platform resolver, returning every address it
+ * points at so `safeFetch` can reject a public name aimed at an internal one.
+ *
+ * This module is Node-only and is never imported by core itself — Workers has no
+ * DNS API, and a static `node:dns` import in the shared path would break that
+ * build.
+ */
+export const nodeHostResolver = async (hostname) => {
+    const results = await lookup(hostname, { all: true, verbatim: true });
+    return results.map(({ address }) => address);
+};
+/** Installs {@link nodeHostResolver} as the default for every `safeFetch`. */
+export const installNodeHostResolver = () => setDefaultHostResolver(nodeHostResolver);

package/dist/utils/safe-fetch.d.ts

@@ -4,6 +4,18 @@
  * private IP.
  */
 export declare function isPrivateHost(hostname: string): boolean;
+/** Resolves a hostname to the IP addresses it points at. */
+export type HostResolver = (hostname: string) => Promise<string[]>;
+/**
+ * Installs the resolver {@link safeFetch} uses when a call passes no
+ * `resolveHost` of its own.
+ *
+ * Core cannot resolve DNS itself — Workers has no DNS API — so without a
+ * resolver the guard is literal-only and a public name pointing at
+ * `169.254.169.254` passes. Node runtimes install
+ * `nodeHostResolver` from `@pikku/core/node-host-resolver` at startup.
+ */
+export declare function setDefaultHostResolver(resolver: HostResolver | undefined): void;
 export interface SafeFetchOptions {
     /**
      * When set, the host of every hop must appear in this allowlist. When omitted,
@@ -12,6 +24,12 @@ export interface SafeFetchOptions {
     allowedHosts?: string[];
     /** Maximum redirect hops to follow (each re-validated). Defaults to 3. */
     maxRedirects?: number;
+    /**
+     * Resolves a hostname so a *public* name pointing at a private address is
+     * refused. Defaults to whatever {@link setDefaultHostResolver} installed;
+     * pass `null` to opt a call out of resolution entirely.
+     */
+    resolveHost?: HostResolver | null;
 }
 export declare function assertFetchableUrl(url: string, options?: SafeFetchOptions): URL;
 /**

package/dist/utils/safe-fetch.js

@@ -34,6 +34,120 @@ function parseIPv4Octets(host) {
     }
     return octets;
 }
+/**
+ * IPv4 blocks that must never be reachable from user-supplied URLs: private,
+ * loopback, link-local (cloud metadata), carrier-grade NAT (Alibaba's
+ * `100.100.100.200` metadata endpoint), IETF protocol assignments, benchmarking,
+ * 6to4 anycast, the documentation TEST-NETs, multicast and reserved space.
+ */
+const PRIVATE_IPV4_BLOCKS = [
+    ['0.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['100.64.0.0', 10],
+    ['127.0.0.0', 8],
+    ['169.254.0.0', 16],
+    ['172.16.0.0', 12],
+    ['192.0.0.0', 24],
+    ['192.0.2.0', 24],
+    ['192.88.99.0', 24],
+    ['192.168.0.0', 16],
+    ['198.18.0.0', 15],
+    ['198.51.100.0', 24],
+    ['203.0.113.0', 24],
+    ['224.0.0.0', 4],
+    ['240.0.0.0', 4],
+];
+const toUint32 = (octets) => ((octets[0] << 24) | (octets[1] << 16) | (octets[2] << 8) | octets[3]) >>> 0;
+const PRIVATE_IPV4_RANGES = PRIVATE_IPV4_BLOCKS.map(([base, prefix]) => {
+    const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+    return [(toUint32(parseIPv4Octets(base)) & mask) >>> 0, mask];
+});
+const isPrivateIPv4 = (octets) => {
+    const addr = toUint32(octets);
+    return PRIVATE_IPV4_RANGES.some(([base, mask]) => (addr & mask) >>> 0 === base);
+};
+/**
+ * Expands an IPv6 literal into its eight 16-bit groups, handling `::` elision
+ * and a trailing dotted-quad. `null` when not a well-formed IPv6 literal.
+ */
+function parseIPv6Groups(host) {
+    const zoneless = host.split('%')[0];
+    const halves = zoneless.split('::');
+    if (halves.length > 2)
+        return null;
+    const parseSide = (side) => {
+        if (side === '')
+            return [];
+        const parts = side.split(':');
+        const groups = [];
+        for (let i = 0; i < parts.length; i++) {
+            const part = parts[i];
+            if (i === parts.length - 1 && part.includes('.')) {
+                const v4 = parseIPv4Octets(part);
+                if (!v4)
+                    return null;
+                groups.push((v4[0] << 8) | v4[1], (v4[2] << 8) | v4[3]);
+                continue;
+            }
+            if (!/^[0-9a-f]{1,4}$/.test(part))
+                return null;
+            groups.push(parseInt(part, 16));
+        }
+        return groups;
+    };
+    const head = parseSide(halves[0]);
+    if (head === null)
+        return null;
+    if (halves.length === 1) {
+        return head.length === 8 ? head : null;
+    }
+    const tail = parseSide(halves[1]);
+    if (tail === null)
+        return null;
+    if (head.length + tail.length > 7)
+        return null;
+    return [...head, ...new Array(8 - head.length - tail.length).fill(0), ...tail];
+}
+const embeddedIPv4 = (hi, lo) => [
+    (hi >> 8) & 0xff,
+    hi & 0xff,
+    (lo >> 8) & 0xff,
+    lo & 0xff,
+];
+function isPrivateIPv6(groups) {
+    const [g0, g1, g2, g3, g4, g5, g6, g7] = groups;
+    if (groups.every((g) => g === 0))
+        return true; // :: unspecified
+    if (groups.slice(0, 7).every((g) => g === 0) && g7 === 1)
+        return true; // ::1
+    // IPv4-mapped ::ffff:0:0/96 and IPv4-compatible ::/96
+    if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0) {
+        if (g5 === 0xffff || g5 === 0)
+            return isPrivateIPv4(embeddedIPv4(g6, g7));
+    }
+    // NAT64 well-known prefix 64:ff9b::/96
+    if (g0 === 0x64 &&
+        g1 === 0xff9b &&
+        g2 === 0 &&
+        g3 === 0 &&
+        g4 === 0 &&
+        g5 === 0)
+        return isPrivateIPv4(embeddedIPv4(g6, g7));
+    // 6to4 2002::/16 carries the IPv4 address in the next 32 bits
+    if (g0 === 0x2002)
+        return isPrivateIPv4(embeddedIPv4(g1, g2));
+    if (g0 === 0x100 && g1 === 0 && g2 === 0 && g3 === 0)
+        return true; // discard-only 100::/64
+    if ((g0 & 0xffc0) === 0xfe80)
+        return true; // link-local fe80::/10
+    if ((g0 & 0xfe00) === 0xfc00)
+        return true; // unique-local fc00::/7
+    if ((g0 & 0xffc0) === 0xfec0)
+        return true; // deprecated site-local fec0::/10
+    if ((g0 & 0xff00) === 0xff00)
+        return true; // multicast ff00::/8
+    return false;
+}
 /**
  * Whether a hostname is an obvious internal target. Best-effort literal
  * matching only: it cannot catch a public hostname that *resolves* to a
@@ -47,36 +161,56 @@ export function isPrivateHost(hostname) {
     if (host === '' || host === 'localhost' || host.endsWith('.localhost'))
         return true;
     if (host.includes(':')) {
-        if (host === '::' || host === '::1')
-            return true;
-        const mappedV4 = host.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
-        if (mappedV4)
-            return isPrivateHost(mappedV4[1]);
-        const mappedHex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
-        if (mappedHex) {
-            const hi = parseInt(mappedHex[1], 16);
-            const lo = parseInt(mappedHex[2], 16);
-            return isPrivateHost(`${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`);
-        }
-        if (/^fe[89ab]/.test(host))
-            return true; // link-local fe80::/10
-        if (host.startsWith('fc') || host.startsWith('fd'))
-            return true; // unique-local fc00::/7
-        return false;
+        const groups = parseIPv6Groups(host);
+        return groups ? isPrivateIPv6(groups) : false;
     }
     const v4 = parseIPv4Octets(host);
-    if (v4) {
-        const [a, b] = v4;
-        if (a === 127 || a === 10 || a === 0)
-            return true;
-        if (a === 169 && b === 254)
-            return true; // link-local incl. cloud metadata
-        if (a === 172 && b >= 16 && b <= 31)
-            return true;
-        if (a === 192 && b === 168)
-            return true;
+    return v4 ? isPrivateIPv4(v4) : false;
+}
+let defaultHostResolver;
+/**
+ * Installs the resolver {@link safeFetch} uses when a call passes no
+ * `resolveHost` of its own.
+ *
+ * Core cannot resolve DNS itself — Workers has no DNS API — so without a
+ * resolver the guard is literal-only and a public name pointing at
+ * `169.254.169.254` passes. Node runtimes install
+ * `nodeHostResolver` from `@pikku/core/node-host-resolver` at startup.
+ */
+export function setDefaultHostResolver(resolver) {
+    defaultHostResolver = resolver;
+}
+/** Whether a hostname is already an IP literal, which the sync check covers. */
+function isIpLiteral(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '');
+    if (host.includes(':'))
+        return parseIPv6Groups(host.toLowerCase()) !== null;
+    return parseIPv4Octets(host) !== null;
+}
+/**
+ * Rejects a hostname that resolves to an internal address.
+ *
+ * Resolution happens once per hop and the connection is not pinned to the
+ * address checked, so a rebind between this check and the socket connecting is
+ * still possible; catching that needs a runtime-level connect hook.
+ */
+async function assertResolvedHostAllowed(hostname, options) {
+    if (options.allowedHosts)
+        return;
+    const resolver = options.resolveHost === null
+        ? undefined
+        : (options.resolveHost ?? defaultHostResolver);
+    if (!resolver || isIpLiteral(hostname))
+        return;
+    const addresses = await resolver(hostname);
+    if (addresses.length === 0) {
+        throw new Error(`Refusing to fetch: '${hostname}' resolved to no addresses`);
+    }
+    for (const address of addresses) {
+        if (isPrivateHost(address)) {
+            throw new Error(`Refusing to fetch from a private/internal host: '${hostname}' resolves to ${address}`);
+        }
     }
-    return false;
 }
 export function assertFetchableUrl(url, options = {}) {
     const parsed = new URL(url);
@@ -126,7 +260,9 @@ function redirectInit(status, init) {
  */
 export async function safeFetch(url, init = {}, options = {}) {
     const maxRedirects = options.maxRedirects ?? 3;
-    let currentUrl = assertFetchableUrl(url, options).toString();
+    const initial = assertFetchableUrl(url, options);
+    await assertResolvedHostAllowed(initial.hostname, options);
+    let currentUrl = initial.toString();
     let currentInit = init;
     for (let hop = 0;; hop++) {
         const response = await fetch(currentUrl, {
@@ -140,7 +276,9 @@ export async function safeFetch(url, init = {}, options = {}) {
         if (!location || hop >= maxRedirects) {
             return response;
         }
-        const nextUrl = assertFetchableUrl(new URL(location, currentUrl).toString(), options).toString();
+        const next = assertFetchableUrl(new URL(location, currentUrl).toString(), options);
+        await assertResolvedHostAllowed(next.hostname, options);
+        const nextUrl = next.toString();
         await response.body?.cancel();
         let nextInit = redirectInit(response.status, currentInit);
         if (new URL(nextUrl).origin !== new URL(currentUrl).origin) {

package/dist/wirings/gateway/gateway-runner.js

@@ -14,19 +14,42 @@ const bridgeMiddlewareSession = async (wire) => {
         wire.session = session;
     }
 };
+/**
+ * Metadata the inspector recorded for the function the gateway was wired with.
+ * The bootstrap loads every meta file before any wiring file, so this is
+ * already populated by the time a gateway wires itself. A gateway wired by
+ * hand rather than through codegen has no entry, and falls back to the
+ * sessionless default below.
+ */
+const declaredHandlerMeta = (config) => {
+    const declaredFuncId = pikkuState(null, 'gateway', 'meta')[config.name]
+        ?.pikkuFuncId;
+    return declaredFuncId
+        ? pikkuState(null, 'function', 'meta')[declaredFuncId]
+        : undefined;
+};
 // knowledge: decisions/security/gateway-handlers-run-through-the-function-runner-gate.md
 const registerGatewayHandler = (config) => {
     const funcId = gatewayHandlerFuncId(config.name);
     const funcMeta = pikkuState(null, 'function', 'meta');
+    const declared = declaredHandlerMeta(config);
     funcMeta[funcId] = {
+        ...declared,
         pikkuFuncId: funcId,
-        inputSchemaName: null,
-        outputSchemaName: null,
-        sessionless: true,
+        inputSchemaName: declared?.inputSchemaName ?? null,
+        outputSchemaName: declared?.outputSchemaName ?? null,
+        sessionless: declared?.sessionless ?? true,
     };
     addFunction(funcId, config.func);
     return funcId;
 };
+/**
+ * Tag middleware the inspector resolved for this gateway. It is keyed by
+ * gateway name rather than reachable from `config`, because `tags` is a
+ * compile-time input everywhere — nothing at runtime maps a tag to its
+ * middleware group.
+ */
+const gatewayInheritedMiddleware = (config) => pikkuState(null, 'gateway', 'meta')[config.name]?.middleware;
 export const resolveGatewayAdapter = (config, services) => {
     let resolved = resolvedAdapters.get(config);
     if (!resolved) {
@@ -100,6 +123,7 @@ const wireWebhookGateway = (config) => {
 const createWebhookPostHandler = (config) => {
     const { name, middleware: userMiddleware } = config;
     const handlerFuncId = registerGatewayHandler(config);
+    const inheritedMiddleware = gatewayInheritedMiddleware(config);
     return async (services, data, wire) => {
         const adapter = await resolveGatewayAdapter(config, services);
         if (adapter.verifyWebhook) {
@@ -126,6 +150,7 @@ const createWebhookPostHandler = (config) => {
                 singletonServices: services,
                 data: () => parsed,
                 auth: config.auth,
+                inheritedMiddleware,
                 wire: wire,
             });
         };
@@ -191,6 +216,7 @@ const wireWebsocketGateway = (config) => {
     };
     const userMiddleware = config.middleware;
     const handlerFuncId = registerGatewayHandler(config);
+    const inheritedMiddleware = gatewayInheritedMiddleware(config);
     addFunction(connectFuncId, {
         auth: false,
         func: async (services, _data, wire) => {
@@ -227,6 +253,7 @@ const wireWebsocketGateway = (config) => {
                     singletonServices: services,
                     data: () => parsed,
                     auth: config.auth,
+                    inheritedMiddleware,
                     wire: wire,
                 });
             };
@@ -256,6 +283,7 @@ const wireListenerGateway = (config) => {
 export const createListenerMessageHandler = (name, config, singletonServices) => {
     const userMiddleware = config.middleware;
     const handlerFuncId = registerGatewayHandler(config);
+    const inheritedMiddleware = gatewayInheritedMiddleware(config);
     return async (rawData) => {
         const adapter = await resolveGatewayAdapter(config, singletonServices);
         const parsed = adapter.parse(rawData);
@@ -275,6 +303,7 @@ export const createListenerMessageHandler = (name, config, singletonServices) =>
                 singletonServices,
                 data: () => parsed,
                 auth: config.auth,
+                inheritedMiddleware,
                 wire,
             });
         };

package/dist/wirings/secret/validate-secret-definitions.js

@@ -35,6 +35,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                     oauth2: def.oauth2,
                     rotationPeriod: def.rotationPeriod,
                     docsUrl: def.docsUrl,
+                    allowedHosts: def.allowedHosts,
                     sourceFile: def.sourceFile,
                 };
             }
@@ -51,6 +52,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                 oauth2: def.oauth2,
                 rotationPeriod: def.rotationPeriod,
                 docsUrl: def.docsUrl,
+                allowedHosts: def.allowedHosts,
                 sourceFile: def.sourceFile,
             };
         }

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -203,6 +203,58 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     }): Promise<{
         resumed: string[];
     }>;
+    /**
+     * Runs holding a step that has sat `pending` since before `before`, paired
+     * with the step that flagged them.
+     *
+     * Returns nothing by default so a store that cannot express the query keeps
+     * working unchanged — and, because it does not opt in, gains no re-dispatches
+     * either. A store must have an atomic `withStepLock` before overriding this,
+     * or no concurrency for one to exclude: the relay makes duplicate dispatch
+     * routine, and the claim in `executeWorkflowStepInner` is what keeps a
+     * duplicate from becoming a second execution. `kysely-postgres` and
+     * `kysely-mysql` qualify on the lock, `in-memory` on being inline and
+     * single-process; `mongodb` and `kysely-sqlite` qualify on neither.
+     */
+    protected findUndispatchedSteps(_before: Date, _limit: number): Promise<Array<{
+        runId: string;
+        stepId: string;
+    }>>;
+    /**
+     * Re-drive steps whose dispatch was lost, and report which runs were nudged.
+     *
+     * Arming a step is two writes to two systems: the step row lands `pending`,
+     * then a queue or scheduler job is published. Nothing spans both, so a crash
+     * in between leaves a durable row that nothing will ever pick up — the run
+     * neither finishes nor fails. (Seen on a `workflow.sleep()`: a deploy restart
+     * landed between the sleep step's insert and its timer.)
+     *
+     * The row is the outbox record and this is the relay. Age is the only signal
+     * available — a step `pending` because its dispatch was lost is
+     * indistinguishable from one whose job is merely still queued — so a step
+     * past `undispatchedAfterMs` is re-dispatched regardless, and correctness
+     * rests on the claim rather than on the guess being right. A redundant
+     * dispatch costs one queue message: the loser reads `running` and returns
+     * without invoking anything.
+     *
+     * Re-dispatches back off per step (doubling from 30s, capped at 10m) so a
+     * genuine queue backlog is not amplified by a tick that keeps firing at the
+     * steps the backlog is already delaying. The backoff is per process and
+     * advisory — losing it on restart costs extra dispatches, never correctness.
+     *
+     * This is not self-starting. Call it from a scheduled task; ~30s suits a
+     * queue whose `pending`→`running` latency is well under that.
+     */
+    relayUndispatchedSteps(options?: {
+        undispatchedAfterMs?: number;
+        limit?: number;
+    }): Promise<{
+        redispatched: string[];
+    }>;
+    /** Advisory, per-process record of when a run may next be re-dispatched. */
+    private readonly redispatchBackoff;
+    private readonly redispatchDelays;
+    private noteRedispatch;
     protected resolveStepJobOptions(stepOptions?: WorkflowStepOptions): JobOptions;
     queueStepWorker(runId: string, stepName: string, rpcName: string, data: any, stepOptions?: WorkflowStepOptions, fromStepName?: string): Promise<void>;
     executeWorkflowSleepCompleted(runId: string, stepId: string): Promise<void>;