@jinn-network/client 0.1.2 → 0.1.3-canary.12cf8b76

package/dist/solvernets/launch-state-machine.js

@@ -0,0 +1,406 @@
+/**
+ * Forward-only checkpointed launch state machine for SolverNet creation.
+ *
+ * Spec: `spec/2026-05-05-solvernet-creation-and-launch.md` §10 (the launch
+ * action) and §6.2 (the `LaunchedSolverNetRecord.launchProgress` shape).
+ *
+ * The five phases — each persisted to disk *before* the side effect runs —
+ * give the daemon a recovery checkpoint at every boundary:
+ *
+ *   pinning      → upload canonical manifest JSON to IPFS
+ *   recording    → atomic-write the launched record to disk with the cid
+ *   broadcasting → submit IdentityRegistry.setMetadata tx
+ *   confirming   → wait for tx receipt (or detect anchored event in subgraph)
+ *   spawning     → start the launcher-owned generator
+ *   → status: 'launched', launchProgress: undefined
+ *
+ * Idempotency invariants (per spec §10):
+ *
+ *   - IPFS pin: same canonical body → same cid (content-addressed). Re-pinning
+ *     is free and produces no protocol-level duplicate.
+ *   - setMetadata: event-only, harmless to re-fire — most-recent-wins
+ *     resolver picks the latest. We still avoid unnecessary re-broadcasts by
+ *     scanning the subgraph for an existing event under the cid before
+ *     re-firing.
+ *   - Disk write: atomic-rename via the SolverNetStore.
+ *   - spawnGenerator: caller-owned. The state machine assumes the spawner
+ *     guards against double-spawn for a given record (Task 12 wires the
+ *     real launcher).
+ *
+ * Architectural choice: the state machine takes ipfs / publisher / subgraph
+ * directly (not the wrapped `SolverNetRegistryClient`). The registry client's
+ * `publishManifest` collapses pin+broadcast into one call, which is
+ * incompatible with the spec's per-phase checkpointing. By holding the
+ * lower-level deps here we can place a disk checkpoint between every phase.
+ *
+ * The state machine never throws on caller-recoverable errors (broadcast
+ * revert, mempool drop, RPC timeout). Instead, it persists `txError` to the
+ * record and rethrows the error so the caller (launch UI / daemon scan) can
+ * decide whether to retry. After `maxAttempts` failed attempts the record
+ * flips to `status: 'failed'`; a manual reset to 'launching' + clear of
+ * `txError` makes the record retryable again.
+ */
+import { manifestHash } from './manifest.js';
+import { encodeLifecyclePayload, LIFECYCLE_PAYLOAD_SCHEMA_VERSION, SOLVERNET_MANIFEST_KEY_PREFIX, } from './registry-client-erc8004.js';
+// ── Constants ────────────────────────────────────────────────────────────────
+/**
+ * Default ceiling on retries before a record is marked `status: 'failed'`.
+ * Tunable via `LaunchActionDeps.maxAttempts`.
+ */
+export const DEFAULT_MAX_ATTEMPTS = 5;
+// ── LaunchAction ────────────────────────────────────────────────────────────
+export class LaunchAction {
+    deps;
+    now;
+    maxAttempts;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? (() => new Date());
+        this.maxAttempts = deps.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    }
+    /**
+     * Launch a new SolverNet from a signed manifest. Forward-only; advances
+     * through pinning → recording → broadcasting → confirming → spawning.
+     *
+     * If a record with the same `solverNetId` already exists, the call is
+     * delegated to `resume()` (idempotent): an already-`launched` record is
+     * returned unchanged; an in-flight record continues from its checkpoint.
+     *
+     * Throws on side-effect failure (revert, RPC error, etc). The record on
+     * disk reflects the failed phase + `txError`; the caller can either retry
+     * via `resume(record)` or, after `maxAttempts`, mark the record as failed
+     * and surface the error.
+     */
+    async launch(args) {
+        if (args.signer.agentId !== args.manifest.launcher.agentId) {
+            throw new Error(`signer.agentId (${args.signer.agentId}) does not match manifest.launcher.agentId (${args.manifest.launcher.agentId})`);
+        }
+        // If a record already exists, fall through to resume — same idempotency
+        // invariants apply.
+        const existing = await this.deps.store.loadRecord(args.manifest.solverNetId);
+        if (existing !== null) {
+            return this.resume({ record: existing, signer: args.signer, manifest: args.manifest });
+        }
+        // Phase 1 — pinning. No record on disk yet; the cid is the only
+        // information produced. We can re-pin freely (content-addressed).
+        let manifestCid;
+        try {
+            manifestCid = await this.deps.ipfs.upload(args.manifest);
+        }
+        catch (err) {
+            // No record yet, so nothing to checkpoint — surface the error and let
+            // the caller retry the whole launch. (A repeat call is a fresh
+            // launch() since no record was ever written.)
+            throw err;
+        }
+        // Phase 2 — recording. Atomic-write the record before any on-chain side
+        // effect. From here on, all retries flow through `resume()`.
+        const initialRecord = {
+            schemaVersion: 'solvernet.launched.v1',
+            solverNetId: args.manifest.solverNetId,
+            manifestCid,
+            manifestHash: manifestHash(args.manifest),
+            launcherAgentId: args.signer.agentId,
+            launcherSafeAddress: args.manifest.launcher.safeAddress,
+            launchedAt: this.now().toISOString(),
+            status: 'launching',
+            statusUpdatedAt: this.now().toISOString(),
+            generatorEnabled: true,
+            // jinn-mono-jnr1: persist the wizard's generatorConfig so the daemon's
+            // generator factory's configRef seeds with the operator's choice on
+            // the next restart, not the DEFAULTS.
+            ...(args.generatorConfig !== undefined && {
+                generatorConfig: args.generatorConfig,
+            }),
+            registry: {},
+            launchProgress: { phase: 'broadcasting', attemptCount: 0 },
+        };
+        await this.deps.store.writeRecord(initialRecord);
+        return this.resume({ record: initialRecord, signer: args.signer, manifest: args.manifest });
+    }
+    /**
+     * Resume an in-flight launch from its current checkpoint. Safe to call
+     * multiple times for the same record; idempotent under the invariants in
+     * the module-level docblock.
+     */
+    async resume(args) {
+        let record = args.record;
+        // Already-terminal status: nothing to do.
+        if (record.status === 'launched') {
+            return record;
+        }
+        if (record.status === 'paused' || record.status === 'retired') {
+            // Lifecycle transitions are handled by a separate state machine; the
+            // launch state machine is not authoritative here. Return the record
+            // as-is; callers should not be asking us to launch a paused/retired
+            // record.
+            return record;
+        }
+        if (record.status === 'failed') {
+            throw new Error(`launch is in 'failed' state (cid=${record.manifestCid}); caller must reset status to 'launching' and clear launchProgress.txError before retrying`);
+        }
+        // Loop forward through phases. Most paths advance monotonically
+        // (broadcasting → confirming → spawning → launched), but the
+        // mempool-drop recovery in `runConfirmingPhase` may bounce back to
+        // 'broadcasting'. The loop exits when status flips terminal or a
+        // phase function throws.
+        //
+        // Bound the loop generously — the only way to re-enter a phase is via
+        // mempool-drop re-broadcast, which is itself bounded by
+        // `attemptCount >= maxAttempts`.
+        const maxIterations = (this.maxAttempts + 1) * 5;
+        for (let i = 0; i < maxIterations; i += 1) {
+            const phase = record.launchProgress?.phase;
+            if (phase === undefined)
+                break; // launchProgress cleared = launched
+            if (phase === 'pinning' || phase === 'recording') {
+                // 'pinning' and 'recording' phases are conceptual checkpoints in
+                // the spec, but the current `launch()` entry point never persists
+                // a record at these phases — pinning runs before any disk write,
+                // and the first persisted record already carries the cid (so the
+                // record IS the recording-phase output). If a caller hands us a
+                // record stuck in either phase, surface a clear error so they
+                // re-call launch() with the original manifest.
+                throw new Error(`cannot resume from phase '${phase}': the launch() entry point does not persist this phase. Re-call launch() with the original manifest instead.`);
+            }
+            if (phase === 'broadcasting') {
+                record = await this.runBroadcastingPhase(record, args.signer);
+                continue;
+            }
+            if (phase === 'confirming') {
+                record = await this.runConfirmingPhase(record, args.signer);
+                continue;
+            }
+            if (phase === 'spawning') {
+                record = await this.runSpawningPhase(record);
+                continue;
+            }
+            // Exhaustive-check: if a new phase appears, fail loudly.
+            const _exhaustive = phase;
+            throw new Error(`unknown launch phase: ${String(_exhaustive)}`);
+        }
+        return record;
+    }
+    // ── Phase implementations ───────────────────────────────────────────────
+    /**
+     * Phase 3 — broadcasting. Submit setMetadata; capture txHash. Persist the
+     * record at `confirming` *with* the txHash before returning.
+     *
+     * Pre-broadcast guard: scan the subgraph for an existing event under this
+     * cid. If one exists, the broadcast already happened (possibly in a prior
+     * crash that lost the txHash) — short-circuit straight to confirming.
+     */
+    async runBroadcastingPhase(record, signer) {
+        // Idempotency check: did a prior broadcast already land?
+        const existingEvents = await this.deps.subgraph.fetchSetMetadataEventsForCid({
+            manifestCid: record.manifestCid,
+        });
+        if (existingEvents.length > 0) {
+            const latestForCid = pickLatest(existingEvents);
+            const advanced = {
+                ...record,
+                registry: {
+                    ...record.registry,
+                    metadataBlockNumber: latestForCid.blockNumber,
+                },
+                statusUpdatedAt: this.now().toISOString(),
+                launchProgress: { phase: 'spawning', attemptCount: 0 },
+            };
+            await this.deps.store.writeRecord(advanced);
+            return advanced;
+        }
+        // Persist the attempt-bump *before* the side effect — if we crash
+        // mid-broadcast the next resume sees the higher attemptCount.
+        const attemptCount = (record.launchProgress?.attemptCount ?? 0) + 1;
+        const checkpointing = {
+            ...record,
+            launchProgress: { phase: 'broadcasting', attemptCount },
+        };
+        await this.deps.store.writeRecord(checkpointing);
+        const lifecycle = {
+            schemaVersion: LIFECYCLE_PAYLOAD_SCHEMA_VERSION,
+            status: 'launched',
+            at: this.now().toISOString(),
+            hash: record.manifestHash,
+        };
+        let txHash;
+        try {
+            const result = await this.deps.publisher.setMetadata({
+                signer,
+                agentId: record.launcherAgentId,
+                key: `${SOLVERNET_MANIFEST_KEY_PREFIX}${record.manifestCid}`,
+                value: encodeLifecyclePayload(lifecycle),
+            });
+            txHash = result.txHash;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const failed = {
+                ...checkpointing,
+                launchProgress: {
+                    phase: 'broadcasting',
+                    attemptCount,
+                    txError: { message, at: this.now().toISOString() },
+                },
+                status: attemptCount >= this.maxAttempts ? 'failed' : 'launching',
+                statusUpdatedAt: this.now().toISOString(),
+            };
+            await this.deps.store.writeRecord(failed);
+            throw err;
+        }
+        const advanced = {
+            ...checkpointing,
+            registry: {
+                ...checkpointing.registry,
+                metadataTxHash: txHash,
+            },
+            statusUpdatedAt: this.now().toISOString(),
+            launchProgress: { phase: 'confirming', txHash, attemptCount },
+        };
+        await this.deps.store.writeRecord(advanced);
+        return advanced;
+    }
+    /**
+     * Phase 4 — confirming. Wait for the receipt for the recorded txHash.
+     *
+     * If the tx is missing from the mempool / chain, fall back to the
+     * subgraph: if the cid has a setMetadata event, treat as confirmed (block
+     * number from the event); otherwise re-broadcast.
+     */
+    async runConfirmingPhase(record, signer) {
+        const txHash = record.launchProgress?.txHash;
+        if (!txHash) {
+            throw new Error(`internal: 'confirming' phase reached for cid ${record.manifestCid} without a txHash`);
+        }
+        let blockNumber;
+        try {
+            const receipt = await this.deps.awaitTxConfirmation(txHash);
+            blockNumber = receipt.blockNumber;
+        }
+        catch (rpcErr) {
+            // Receipt missing — could be mempool-dropped, RPC stale, or tx pruned
+            // before we polled. Consult the subgraph as the authoritative
+            // "anchored on chain" source.
+            const events = await this.deps.subgraph.fetchSetMetadataEventsForCid({
+                manifestCid: record.manifestCid,
+            });
+            if (events.length > 0) {
+                // Anchored: take the block number from the latest matching event.
+                const latest = pickLatest(events);
+                blockNumber = latest.blockNumber;
+            }
+            else {
+                // Genuinely dropped — re-broadcast on the next loop iteration. We
+                // reset to 'broadcasting' (not 'failed') and let the resume loop
+                // pick it up. attemptCount carries over from the prior phase so
+                // the broadcast retry budget is shared.
+                const attemptCount = (record.launchProgress?.attemptCount ?? 0);
+                const requeued = {
+                    ...record,
+                    registry: { ...record.registry, metadataTxHash: undefined },
+                    launchProgress: { phase: 'broadcasting', attemptCount },
+                    statusUpdatedAt: this.now().toISOString(),
+                };
+                await this.deps.store.writeRecord(requeued);
+                // We deliberately do NOT throw here — the resume loop will pick up
+                // the requeued record and re-enter `runBroadcastingPhase`.
+                // Reference signer to satisfy noUnusedParameters strictness on
+                // edited tooling configurations.
+                void signer;
+                return requeued;
+            }
+        }
+        const advanced = {
+            ...record,
+            registry: {
+                ...record.registry,
+                metadataBlockNumber: blockNumber,
+            },
+            statusUpdatedAt: this.now().toISOString(),
+            launchProgress: { phase: 'spawning', attemptCount: 0 },
+        };
+        await this.deps.store.writeRecord(advanced);
+        return advanced;
+    }
+    /**
+     * Phase 5 — spawning. Hand the launched record to the generator-spawner.
+     * On success, finalize the record: clear `launchProgress`, flip `status`
+     * to 'launched', stamp `statusUpdatedAt`.
+     */
+    async runSpawningPhase(record) {
+        try {
+            await this.deps.spawnGenerator(record);
+        }
+        catch (err) {
+            const attemptCount = (record.launchProgress?.attemptCount ?? 0) + 1;
+            const message = err instanceof Error ? err.message : String(err);
+            const failed = {
+                ...record,
+                status: attemptCount >= this.maxAttempts ? 'failed' : 'launching',
+                statusUpdatedAt: this.now().toISOString(),
+                launchProgress: {
+                    phase: 'spawning',
+                    attemptCount,
+                    txError: { message, at: this.now().toISOString() },
+                },
+            };
+            await this.deps.store.writeRecord(failed);
+            throw err;
+        }
+        const finalRecord = {
+            ...record,
+            status: 'launched',
+            statusUpdatedAt: this.now().toISOString(),
+        };
+        delete finalRecord.launchProgress;
+        await this.deps.store.writeRecord(finalRecord);
+        return finalRecord;
+    }
+}
+// ── Crash-resume on daemon startup ──────────────────────────────────────────
+/**
+ * Scan the launched-records directory and resume any record whose
+ * `status === 'launching'`. Returns counts of successful resumes and any
+ * per-record errors (so a single broken record cannot block daemon startup).
+ *
+ * Daemons should call this once at boot, before starting the generator
+ * loops — Task 12 wires the call site.
+ */
+export async function recoverInFlightLaunches(deps) {
+    const records = await deps.store.loadOwnedRecords();
+    const inFlight = records.filter((r) => r.status === 'launching');
+    const action = new LaunchAction(deps);
+    let resumed = 0;
+    const failed = [];
+    for (const record of inFlight) {
+        try {
+            const signer = await deps.resolveSigner(record.launcherAgentId);
+            const advanced = await action.resume({ record, signer });
+            if (advanced.status === 'launched') {
+                resumed += 1;
+            }
+        }
+        catch (err) {
+            failed.push({
+                solverNetId: record.solverNetId,
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+        }
+    }
+    return { resumed, failed };
+}
+// ── Helpers ────────────────────────────────────────────────────────────────
+/**
+ * Pick the event with the highest `(blockNumber, transactionIndex)` from a
+ * non-empty array. Used for breaking ties when multiple setMetadata events
+ * exist for the same cid.
+ */
+function pickLatest(events) {
+    return events.reduce((acc, cur) => {
+        if (cur.blockNumber !== acc.blockNumber) {
+            return cur.blockNumber > acc.blockNumber ? cur : acc;
+        }
+        return cur.transactionIndex > acc.transactionIndex ? cur : acc;
+    });
+}
+//# sourceMappingURL=launch-state-machine.js.map

package/dist/solvernets/launch-state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch-state-machine.js","sourceRoot":"","sources":["../../src/solvernets/launch-state-machine.ts"],"names":[],"mappings":"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"}

package/dist/solvernets/lifecycle-transitions.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Forward-only checkpointed lifecycle-transition state machine for SolverNets.
+ *
+ * Spec: `spec/2026-05-05-solvernet-creation-and-launch.md` §10 (post-launch
+ * dashboard), §11 (generator ownership), and Decision 11 in §17 (lifecycle
+ * action surface = Pause + Resume + Retire).
+ *
+ * Two phases — simpler than the launch state machine because the manifest
+ * itself is already pinned and immutable. Every transition is a single
+ * `IdentityRegistry.setMetadata` write under the existing
+ * `solvernet-manifest:<cid>` key:
+ *
+ *   broadcasting → submit setMetadata(target) tx
+ *   confirming   → wait for tx receipt (or detect anchored event in subgraph)
+ *   → status: <target>, lifecycleProgress: undefined, generator side-effect
+ *
+ * Side effects fire AFTER the on-chain anchor lands, so a daemon that crashes
+ * mid-transition recovers a consistent (status, generator-state) pair on
+ * resume.
+ *
+ *   target = 'paused' | 'retired'  → stopGenerator
+ *   target = 'launched' (resume)   → startGenerator
+ *
+ * State transitions allowed (precondition: record.status):
+ *
+ *   launched → paused
+ *   launched → retired
+ *   paused   → launched
+ *   paused   → retired
+ *   retired  → ANY  → reject (terminal — relaunch with a new SolverNet)
+ *
+ * Idempotency invariants:
+ *
+ *   - record.status === target → no-op, returns the record unchanged.
+ *   - lifecycleProgress.target === call target → resume from checkpoint.
+ *   - lifecycleProgress.target !== call target → reject; one transition in
+ *     flight at a time per record.
+ *   - setMetadata is event-only on chain; re-firing is harmless because the
+ *     most-recent-wins resolver picks the latest matching event.
+ *
+ * Mempool-drop edge case mirrors the launch state machine: if `txHash` is set
+ * and the receipt is missing, consult the subgraph for a setMetadata event
+ * matching this `(cid, target)` tuple. An event whose payload status equals
+ * the target is treated as anchored; otherwise re-broadcast.
+ */
+import type { SubgraphClient } from './registry-client-erc8004.js';
+import type { SignerWithAgentEoa, SolverNetRegistryClient } from './registry-client.js';
+import type { LaunchedSolverNetRecord, SolverNetStore } from './store.js';
+/**
+ * Default ceiling on retries before a record's status flips to `'failed'`.
+ * Tunable via `LifecycleTransitionDeps.maxAttempts`.
+ */
+export declare const DEFAULT_LIFECYCLE_MAX_ATTEMPTS = 5;
+type LifecycleTarget = NonNullable<LaunchedSolverNetRecord['lifecycleProgress']>['target'];
+export interface LifecycleTransitionDeps {
+    store: SolverNetStore;
+    registry: SolverNetRegistryClient;
+    /**
+     * Signer for the launcher's agent EOA. The state machine is single-launcher
+     * by construction (one daemon owns one record); cross-launcher recovery is
+     * not in scope.
+     */
+    signer: SignerWithAgentEoa;
+    /**
+     * Subgraph used for the "already-anchored" recovery path: when `txHash` is
+     * set but the receipt is missing, scan for a matching setMetadata event
+     * before deciding to re-broadcast.
+     */
+    subgraph: SubgraphClient;
+    /**
+     * Resolve a tx hash to a confirmed receipt. Implementations may poll an
+     * RPC, watch logs, or wrap viem's `waitForTransactionReceipt`. Throwing is
+     * the signal that the tx is missing from the mempool / chain.
+     */
+    awaitTxConfirmation: (txHash: `0x${string}`) => Promise<{
+        blockNumber: number;
+    }>;
+    startGenerator?: (record: LaunchedSolverNetRecord) => Promise<void>;
+    stopGenerator?: (record: LaunchedSolverNetRecord) => Promise<void>;
+    now?: () => Date;
+    maxAttempts?: number;
+}
+export declare class LifecycleTransition {
+    private readonly deps;
+    private readonly now;
+    private readonly maxAttempts;
+    constructor(deps: LifecycleTransitionDeps);
+    /**
+     * Drive a record toward the target lifecycle state. Forward-only;
+     * advances through broadcasting → confirming → target.
+     *
+     * Pre-flight rejects are surfaced as throws (terminal/in-flight conflicts).
+     * Idempotent no-ops (already-at-target) return the record unchanged.
+     *
+     * On side-effect failure (RPC revert, mempool drop, generator-spawn error),
+     * persists the failed phase + `txError`, then rethrows. Caller may retry
+     * via `resume()`.
+     */
+    transition(record: LaunchedSolverNetRecord, target: LifecycleTarget): Promise<LaunchedSolverNetRecord>;
+    /**
+     * Resume a record whose `lifecycleProgress` is set. Safe to call multiple
+     * times; idempotent under the invariants above.
+     *
+     * If `lifecycleProgress` is undefined (no in-flight transition), returns
+     * the record unchanged — the daemon's resume scan can call this on every
+     * record without filtering.
+     */
+    resume(record: LaunchedSolverNetRecord): Promise<LaunchedSolverNetRecord>;
+    private runLoop;
+    /**
+     * Phase 1 — broadcasting. Submit publishLifecycleTransition; capture the
+     * tx hash. Persist the record at `confirming` (with `txHash` set) before
+     * returning so the next iteration can poll for the receipt.
+     *
+     * Pre-broadcast guard: if the subgraph already has a setMetadata event
+     * for this `(cid, target)` tuple — i.e. an earlier broadcast landed but
+     * we lost the txHash — short-circuit straight to confirmed.
+     */
+    private runBroadcastingPhase;
+    /**
+     * Phase 2 — confirming. Wait for the recorded txHash to confirm.
+     *
+     * Three resolution paths:
+     *   1. Receipt found → finalize with that block number.
+     *   2. Receipt missing AND subgraph has a matching event → finalize with
+     *      the event's block number.
+     *   3. Receipt missing AND subgraph has no matching event → re-broadcast.
+     */
+    private runConfirmingPhase;
+    /**
+     * Flip the record to `status: <target>`, clear `lifecycleProgress`, write
+     * the new metadata block number. The generator side effect is the
+     * caller's responsibility (so we can fire it after the disk write lands).
+     */
+    private finalizeAtTarget;
+    /**
+     * Same as `finalizeAtTarget` but sourced from a subgraph event (used when
+     * the broadcasting phase finds an existing anchored event).
+     */
+    private finalizeFromAnchoredEvent;
+    /**
+     * Fire the start/stop generator callback corresponding to the target. We
+     * call the callbacks AFTER the on-chain anchor lands and the disk write
+     * succeeds — so a generator-spawn failure does NOT roll back the
+     * lifecycle state. The daemon can retry generator-spawn separately.
+     *
+     * Errors from the callback are rethrown so the caller can surface them;
+     * the lifecycle record itself is already at the target status by the
+     * time we call this.
+     */
+    private fireGeneratorSideEffect;
+    /**
+     * Find the latest setMetadata event for `(cid, target)` — i.e. an event
+     * whose payload status equals the target. Returns null when no matching
+     * event is indexed.
+     *
+     * Why filter by target? A pause-in-flight scenario could have an existing
+     * `launched` event from the original launch — that event is NOT evidence
+     * the pause anchored. We must only treat events whose payload status
+     * matches the in-flight target as "anchored".
+     *
+     * Tiebreak: among matching events, pick the one with the highest
+     * `(blockNumber, transactionIndex)` so a re-broadcast scenario picks up
+     * the most recent anchor.
+     */
+    private findMatchingEvent;
+}
+/**
+ * Scan the launched-records directory and resume any record whose
+ * `lifecycleProgress` is set. Returns counts of successful resumes and any
+ * per-record errors (so a single broken record cannot block daemon startup).
+ *
+ * Daemons should call this once at boot, after `recoverInFlightLaunches`,
+ * before starting the generator loops.
+ */
+export declare function recoverInFlightLifecycleTransitions(deps: LifecycleTransitionDeps): Promise<{
+    resumed: number;
+    failed: Array<{
+        solverNetId: string;
+        error: Error;
+    }>;
+}>;
+export {};