@jinn-network/client 0.1.2 → 0.1.3-canary.24b69ea4

package/dist/solvernets/daemon-init.d.ts

@@ -0,0 +1,291 @@
+/**
+ * Daemon-side bootstrap of the SolverNet subsystem.
+ *
+ * Spec: `spec/2026-05-05-solvernet-creation-and-launch.md` Task 11 (daemon
+ * startup integration). Wires the persistence, recovery, and operator
+ * catalog surfaces so the daemon can resume in-flight launches/lifecycle
+ * transitions and serve the operator catalog UI.
+ *
+ * This module is intentionally THIN: it composes existing pieces (`SolverNetStore`,
+ * `recoverInFlightLaunches`, `recoverInFlightLifecycleTransitions`, and the
+ * `IdentityRegistryBackedSolverNetRegistryClient`) into a single
+ * `initSolverNetSubsystem(deps)` call that `main.ts` invokes once after the
+ * `FleetBootstrapper` finishes. Task 11 sets up the SCAFFOLDING; Task 12
+ * is responsible for the gating refactor that swaps out the legacy
+ * `collectTestnetAutoTaskGenerators` path for owned launched-record-driven
+ * generator construction.
+ *
+ * Order of operations (mirrors the per-section ordering in
+ * `launch-state-machine.ts` and `lifecycle-transitions.ts`):
+ *
+ *   1. Resume any record stuck in `status: 'launching'` →
+ *      `recoverInFlightLaunches`. Safe to call when no records are in flight.
+ *   2. Resume any record with `lifecycleProgress` set →
+ *      `recoverInFlightLifecycleTransitions`. Same safety property.
+ *   3. Load owned records → identify which ones have
+ *      `status in {'launched','paused'} && generatorEnabled`; those are the
+ *      "ready-to-spawn" set the next-task generator wiring will iterate.
+ *   4. Start the operator catalog refresher loop (interval-driven) so the
+ *      daemon API can hand SPA reads without a synchronous subgraph round
+ *      trip on every poll.
+ *
+ * Out of scope for Task 11 (do NOT add here):
+ *
+ *   - Actually constructing `prediction.v1` generators per launched record
+ *     (Task 12).
+ *   - Wiring the catalog cache into the API server's `/v1/solvernets/*`
+ *     endpoints (Task 14/15).
+ *   - Removing the legacy `collectTestnetAutoTaskGenerators` path
+ *     (Task 12).
+ *
+ * Day-1 SubgraphClient note: the canonical Jinn subgraph has not yet
+ * surfaced the `solvernet-manifest:` setMetadata index (Task 25 wires the
+ * extension). Until then, callers may pass `createNoopSubgraphClient()` so
+ * `recoverInFlightLaunches` and `listLaunched` return empty arrays
+ * gracefully — recovery only short-circuits via subgraph events on
+ * mempool-drop (rare); the catalog refresher logs a one-line warning when
+ * it observes the no-op path so the operator can see the wiring is
+ * incomplete. Production wiring happens in Task 25.
+ */
+import { type IpfsClient, type MetadataPublisher, type SubgraphClient } from './registry-client-erc8004.js';
+import { type LaunchActionDeps, type ResolveSigner } from './launch-state-machine.js';
+import { type LifecycleTransitionDeps } from './lifecycle-transitions.js';
+import type { SolverNetRegistryClient, SolverNetManifestSummary } from './registry-client.js';
+import type { LaunchedSolverNetRecord, SolverNetStore } from './store.js';
+import type { PublicClient, WalletClient } from 'viem';
+/**
+ * How often the operator catalog cache is refreshed against the registry
+ * client. 30 seconds is conservative — operators rarely launch multiple
+ * SolverNets per minute, and the SPA's join-flow polling is on a similar
+ * cadence. Tunable via `initSolverNetSubsystem.catalogRefreshIntervalMs`.
+ */
+export declare const DEFAULT_CATALOG_REFRESH_INTERVAL_MS = 30000;
+/**
+ * Catalog-cache surface — what the daemon API will read in Task 14/15.
+ *
+ * `getCatalog()` returns the most recently fetched summaries (or an empty
+ * array before the first refresh succeeds). `refresh()` forces an immediate
+ * fetch outside the periodic interval — useful for tests and for
+ * post-action UI invalidation. `stop()` cancels the periodic interval.
+ */
+export interface SolverNetCatalogCache {
+    getCatalog(): SolverNetManifestSummary[];
+    refresh(): Promise<void>;
+    stop(): void;
+    /** Last successful refresh. `null` until the first refresh lands. */
+    lastRefreshedAt(): Date | null;
+    /** Last refresh error, if any. Cleared on the next successful refresh. */
+    lastError(): {
+        message: string;
+        at: Date;
+    } | null;
+}
+/**
+ * One spawn-ready entry surfaced to `main.ts`. The daemon constructs a
+ * generator per entry using `makePredictionV1GeneratorForLaunchedRecord`
+ * (Task 12 of spec/2026-05-05-solvernet-creation-and-launch.md §11) and
+ * passes the same `recordRef` and `configRef` so:
+ *
+ *   - Lifecycle transitions (pause/resume/retire) update `recordRef.current`
+ *     and the per-tick gate sees the new status within one cadence.
+ *   - The SolverNet config API endpoint (Task 14) mutates `configRef.current`
+ *     and the per-tick reads the new cadence / allowlist / caps within one
+ *     cadence — no daemon restart, no generator recreation.
+ *
+ * The same refs are also the source of truth that the catalog/status
+ * endpoints read so SPA reads always match what the generator is actually
+ * doing. Task 12 wires the generator construction; Tasks 14/15 hand these
+ * refs to the API server.
+ */
+export interface PendingGeneratorSpawn {
+    /** Snapshot of the launched record at subsystem-init time. */
+    record: LaunchedSolverNetRecord;
+    /**
+     * Live mirror of the launched record. The lifecycle-transition path
+     * mutates `recordRef.current` immediately after persisting status changes
+     * to disk (and Task 12 also wires lifecycle resume to mutate it on
+     * recovery).
+     */
+    recordRef: {
+        current: LaunchedSolverNetRecord;
+    };
+    /**
+     * Live mirror of the hot-applyable runtime generator config. The
+     * subsystem seeds it with the record's last-saved config (or all-default
+     * empty config when no per-record overrides are set yet). Task 14 mutates
+     * this when the operator edits the generator config.
+     */
+    configRef: {
+        current: unknown;
+    };
+}
+/**
+ * What `initSolverNetSubsystem` returns. Tasks 14/15 hand
+ * `pendingGenerators` and the catalog cache to the API server; `main.ts`
+ * iterates `pendingGenerators` to actually construct generators (Task 12
+ * wires the generator factory).
+ */
+export interface SolverNetSubsystem {
+    /** All launched records currently on disk (post-recovery). */
+    records: LaunchedSolverNetRecord[];
+    /**
+     * Subset of `records` where `status` is `launched` or `paused` and
+     * `generatorEnabled === true`, paired with the live refs the generator
+     * factory and the API endpoints share. Paused records are intentionally
+     * wired so a lifecycle resume only has to mutate `recordRef.current`.
+     */
+    pendingGenerators: PendingGeneratorSpawn[];
+    /** Operator catalog cache, populated on first refresh. */
+    catalog: SolverNetCatalogCache;
+    /** The registry client (for reuse by the daemon API). */
+    registryClient: SolverNetRegistryClient;
+    /** Outcomes of the recovery scans. Useful for test assertions and logging. */
+    recovery: {
+        inFlightLaunches: {
+            resumed: number;
+            failed: Array<{
+                solverNetId: string;
+                error: Error;
+            }>;
+        };
+        inFlightLifecycle: {
+            resumed: number;
+            failed: Array<{
+                solverNetId: string;
+                error: Error;
+            }>;
+        };
+    };
+    /** Stop the catalog refresher and any future timers. Idempotent. */
+    stop(): void;
+}
+/**
+ * Required inputs. The store / clients can be the production
+ * implementations or test mocks — the module is dep-injected end to end
+ * so unit tests don't have to mock viem.
+ *
+ * `network` is the chain the catalog cache filters on (per
+ * `IdentityRegistryBackedSolverNetRegistryClient.listLaunched`).
+ *
+ * `resolveSigner` is required for the launch-recovery branch (the launch
+ * state machine signs re-broadcasts on resume). Lifecycle resume takes
+ * a single `signer` directly — production passes the same signer for
+ * both, since one daemon owns one launcher.
+ */
+export interface InitSolverNetSubsystemDeps {
+    store: SolverNetStore;
+    ipfs: IpfsClient;
+    publisher: MetadataPublisher;
+    subgraph: SubgraphClient;
+    registryClient: SolverNetRegistryClient;
+    network: 'base-sepolia' | 'base';
+    resolveSigner: ResolveSigner;
+    /**
+     * Single signer used by the lifecycle-resume scan. Production owns one
+     * launcher per daemon; multi-launcher recovery is out of scope.
+     */
+    lifecycleSigner: LifecycleTransitionDeps['signer'];
+    /** Resolves a tx hash to a confirmed receipt. Same as the state machines. */
+    awaitTxConfirmation: LaunchActionDeps['awaitTxConfirmation'];
+    /** Optional override for `setInterval` / `clearInterval` (tests). */
+    scheduler?: {
+        setInterval: (cb: () => void, ms: number) => unknown;
+        clearInterval: (handle: unknown) => void;
+    };
+    /** Period (ms) for the catalog refresher. */
+    catalogRefreshIntervalMs?: number;
+    /**
+     * If `true`, skip starting the catalog refresher interval — useful for
+     * tests that only assert the load+recover flow. The catalog is still
+     * exposed; tests call `catalog.refresh()` manually.
+     */
+    disableCatalogAutoRefresh?: boolean;
+    /**
+     * Optional logger for catalog-refresh errors and recovery summaries.
+     * Defaults to `console`.
+     */
+    logger?: {
+        warn: (msg: string) => void;
+        info: (msg: string) => void;
+    };
+    /** Override the wall clock for deterministic tests. */
+    now?: () => Date;
+}
+/**
+ * Initialise the SolverNet subsystem at daemon startup.
+ *
+ * Call after `FleetBootstrapper` resolves (so the master Safe + agent EOA
+ * referenced by launched records are available) and before any task
+ * generators are constructed.
+ *
+ * Errors during the recovery scans are captured per-record into
+ * `recovery.inFlightLaunches.failed` / `recovery.inFlightLifecycle.failed`
+ * so a single broken record cannot block daemon startup. Errors during
+ * the initial catalog refresh are logged and stored on the cache; the
+ * refresher continues ticking.
+ */
+export declare function initSolverNetSubsystem(deps: InitSolverNetSubsystemDeps): Promise<SolverNetSubsystem>;
+/**
+ * Wrap the existing global `uploadToIpfs` / `fetchFromIpfs` helpers in the
+ * `IpfsClient` interface used by the SolverNet registry client. Same
+ * canonical-JSON semantics as the rest of the daemon.
+ */
+export declare function createIpfsClientAdapter(args: {
+    registryUrl: string;
+    gatewayUrl: string;
+}): IpfsClient;
+/**
+ * Day-1 stub `SubgraphClient` returning empty arrays for both queries. The
+ * real subgraph extension lands in Task 25; until then the launch state
+ * machine and registry catalog still function (recovery only consults
+ * the subgraph on mempool-drop, which is rare; catalog refresh produces an
+ * empty list, which the SPA renders as "no SolverNets launched yet" — a
+ * truthful zero state until Task 25 indexes the events).
+ *
+ * Exported so tests can pin a deterministic baseline.
+ */
+export declare function createNoopSubgraphClient(): SubgraphClient;
+/**
+ * jinn-mono-{follow-up}: real subgraph adapter that queries the deployed
+ * Jinn subgraph (e.g. https://api.studio.thegraph.com/query/.../jinn-testnet/...)
+ * for `SolverNetManifestEvent` rows and JCS-decodes each event's payload
+ * bytes into the typed lifecycle payload. Replaces `createNoopSubgraphClient`
+ * for any daemon that reads `JINN_SUBGRAPH_URL`.
+ *
+ * The schema only stores `solvernet-manifest:<cid>` events (lifecycle and
+ * launch share the prefix). `keyPrefix` is therefore an effective filter:
+ * the entity itself encodes that constraint, so we do not pass it to the
+ * GraphQL query. Callers passing a different prefix get an empty list.
+ */
+export declare function createGraphqlSubgraphClient(args: {
+    url: string;
+}): SubgraphClient;
+/**
+ * Adapter that turns a viem (walletClient, publicClient, identityRegistryAddress)
+ * triple into a `MetadataPublisher` whose `value` is treated as raw bytes
+ * (the JCS-encoded SolverNet lifecycle payload), bypassing the
+ * `IdentityPublisher`'s ABI-encoded execution-payload tuple. Production
+ * `main.ts` constructs one of these alongside the existing `IdentityPublisher`
+ * — they share the same on-chain `setMetadata` ABI but encode different
+ * payload schemas under different `metadataKey` prefixes.
+ *
+ * `signer` from the call site is passed through but unused here — the
+ * walletClient is bound at construction time. The interface keeps it so
+ * tests can swap in a mock that does inspect it.
+ */
+export declare function createMetadataPublisherFromViem(args: {
+    identityRegistryAddress: `0x${string}`;
+    walletClient: WalletClient;
+    publicClient: PublicClient;
+}): MetadataPublisher;
+/**
+ * Build a production `IdentityRegistryBackedSolverNetRegistryClient` from a
+ * pre-built deps bundle. Convenience wrapper kept here so `main.ts` only
+ * imports from `./solvernets/daemon-init.js` for the whole subsystem.
+ */
+export declare function createDefaultRegistryClient(args: {
+    ipfs: IpfsClient;
+    publisher: MetadataPublisher;
+    subgraph: SubgraphClient;
+    network: 'base-sepolia' | 'base';
+}): SolverNetRegistryClient;