@jinn-network/client 0.1.1 → 0.1.2-canary.647548b7

package/dist/restorer/engine/engine.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Restorer engine — main RestorationEngine class.
+ *
+ * §6.3, §6.5 of spec/2026-04-17-portfolio-v0-design.md
+ *
+ * Orchestrates the state machine lifecycle for each observed intent.
+ * Transition method bodies are stubs; subsequent tasks fill them in.
+ */
+import { IntentPersistence, type PersistedIntent, type PersistedIntentInput } from './persistence.js';
+import type { Store } from '../../store/store.js';
+import { type MarketplaceClaimer } from './claim.js';
+import type { ClaimRegistryClient } from '../../adapters/claim-registry/client.js';
+import { type PackagingDeps } from './packaging.js';
+import { type ManifestAssemblyDeps } from './manifest-assembly.js';
+import { type DeliveryDeps } from './delivery.js';
+import type { RestorerImpl } from '../types.js';
+export declare class NotImplementedError extends Error {
+    readonly transitionName: string;
+    constructor(transitionName: string);
+}
+export interface RestorerImplRegistry {
+    /** Returns the impl name for a given spec kind (and optional type), or null if none registered. */
+    resolveImplName(ctx: {
+        kind: string | null;
+        type?: 'restoration' | 'evaluation';
+    }): string | null;
+}
+export interface RestorationEngineOptions {
+    store: Store;
+    registry: RestorerImplRegistry;
+    paths: {
+        workingDirRoot: string;
+        implStateDirRoot: string;
+    };
+    /**
+     * Injected claim dependencies. When provided, engine.claim() is functional.
+     * When absent, claim() falls back to NotImplementedError (useful for tests
+     * that don't exercise the claim path).
+     */
+    claimDeps?: {
+        registryClient: ClaimRegistryClient;
+        marketplaceClaimer: MarketplaceClaimer;
+    };
+    /**
+     * Packaging dependencies. When provided, pack() is functional.
+     * When absent, pack() falls back to NotImplementedError.
+     */
+    packagingDeps?: PackagingDeps;
+    /**
+     * Manifest assembly dependencies. When provided, pack() can assemble + sign.
+     * When absent, pack() falls back to NotImplementedError.
+     */
+    manifestDeps?: ManifestAssemblyDeps;
+    /**
+     * Delivery dependencies. When provided, deliver() is functional.
+     * When absent, deliver() falls back to NotImplementedError.
+     */
+    deliveryDeps?: DeliveryDeps;
+    /**
+     * Impl registry for resolving which RestorerImpl to run.
+     * When provided and findFor() returns an impl, runImpl() dispatches to it.
+     */
+    implRegistry?: {
+        findFor(ctx: {
+            kind: string;
+            type?: 'restoration' | 'evaluation';
+        }): RestorerImpl | undefined;
+    };
+}
+/** Per-intent outcome from a recovery pass. */
+export interface RecoveryReport {
+    requestId: string;
+    outcome: 'ok' | 'failed';
+    error?: string;
+}
+export declare class RestorationEngine {
+    protected readonly persistence: IntentPersistence;
+    protected readonly registry: RestorerImplRegistry;
+    protected readonly paths: RestorationEngineOptions['paths'];
+    protected readonly claimDeps: RestorationEngineOptions['claimDeps'];
+    protected readonly packagingDeps: RestorationEngineOptions['packagingDeps'];
+    protected readonly manifestDeps: RestorationEngineOptions['manifestDeps'];
+    protected readonly deliveryDeps: RestorationEngineOptions['deliveryDeps'];
+    protected readonly implRegistry: RestorationEngineOptions['implRegistry'];
+    private readonly implOutputs;
+    /** Set by stop(); causes runTickLoop to exit at the next iteration. */
+    private stopped;
+    constructor(opts: RestorationEngineOptions);
+    /**
+     * Called when an intent is observed from an on-chain event.
+     * Persists a DISCOVERED row. Idempotent: if the row already exists, no-op.
+     */
+    observe(input: PersistedIntentInput): Promise<void>;
+    /**
+     * Recover all in-flight intents from persisted state.
+     * Called at daemon startup before beginning normal event processing.
+     * Returns a per-intent report for each intent attempted.
+     */
+    recoverInFlight(): Promise<RecoveryReport[]>;
+    /**
+     * Periodic tick: advance every in-flight intent by one transition.
+     * Called by `runTickLoop` so that intents which entered a non-event-driven
+     * state (e.g. CLAIMED waiting for windowStartTs) get re-driven without
+     * waiting for a daemon restart or a fresh marketplace event.
+     *
+     * Errors from individual intents are logged but do not stop the loop.
+     */
+    tick(): Promise<void>;
+    /**
+     * Drive `tick()` on a fixed interval until `stop()` is called.
+     * Errors thrown by tick() itself are logged and do not stop the loop.
+     */
+    runTickLoop(intervalMs: number): Promise<void>;
+    /** Signal `runTickLoop` to exit at the next iteration. */
+    stop(): void;
+    /**
+     * Process a single intent: dispatch by current state to the appropriate
+     * transition. Drives one state transition per call.
+     *
+     * Called both by recovery and by the ongoing event-processing loop.
+     */
+    process(requestId: string): Promise<void>;
+    /**
+     * Two-layer claim: ClaimRegistry + Marketplace.
+     *
+     * Idempotent on resume: checks ClaimRegistry for a pre-existing claim before
+     * sending any on-chain transaction.
+     *
+     * Advances state DISCOVERED → CLAIMED on success.
+     * Marks FAILED if either layer cannot be claimed.
+     *
+     * Requires claimDeps to be injected via constructor options. Falls back to
+     * NotImplementedError if claimDeps is absent (development / test mode).
+     */
+    protected claim(intent: PersistedIntent): Promise<void>;
+    /**
+     * Release ClaimRegistry claims for all CLAIMED intents whose work window has
+     * not yet started. Called on graceful engine shutdown.
+     *
+     * Returns the list of requestIds that were successfully released.
+     */
+    releaseClaimedNotStarted(): Promise<string[]>;
+    /**
+     * PRE_SNAPSHOT transition: provision workingDir + implStateDir, write
+     * intent.json + env/ files, create sessions/ directory.
+     *
+     * Requires no external deps beyond filesystem access — always implemented.
+     * Advances state PRE_SNAPSHOT with workingDir + implStateDir patch.
+     */
+    protected takePreSnapshot(intent: PersistedIntent): Promise<void>;
+    /**
+     * RUNNING transition: dispatch to a RestorerImpl if implRegistry is provided.
+     *
+     * When no impl is found for the spec kind, falls back to NotImplementedError
+     * so the engine does not silently swallow the request. In tests that don't
+     * exercise the impl path, override this method.
+     *
+     * Captures impl output in `implOutputs` map for pack() to consume. Also
+     * records a minimal post-snapshot so data-driven advance can fire.
+     */
+    protected runImpl(intent: PersistedIntent): Promise<void>;
+    protected takePostSnapshot(_intent: PersistedIntent): Promise<void>;
+    /**
+     * PACKAGING transition: walk workingDir, upload artifacts, assemble + sign
+     * manifest, upload manifest, persist manifest CID + artifact CIDs.
+     *
+     * Requires packagingDeps + manifestDeps. When absent, falls back to
+     * NotImplementedError.
+     */
+    protected pack(intent: PersistedIntent): Promise<void>;
+    /**
+     * DELIVERING transition: call mech.deliverToMarketplace + JinnRouter.claimDelivery.
+     *
+     * Requires deliveryDeps. When absent, falls back to NotImplementedError.
+     *
+     * Crash-recovery safe: if `intent.deliveryTxHash` is already set (persisted
+     * after a previous deliverToMarketplace call that completed before the process
+     * crashed), we skip the deliver step and go straight to claimDelivery.
+     */
+    protected deliver(intent: PersistedIntent): Promise<void>;
+    /**
+     * Returns the next state if the current state can be advanced purely from
+     * persisted data (no external work needed), or null if external work is required.
+     *
+     * Used for crash recovery and for collapsing transitions in process()
+     * when a previous run already produced the data.
+     */
+    private dataDrivenAdvance;
+    /**
+     * Wraps a transition method call with error handling: if the transition
+     * throws, the intent is marked FAILED with the error message.
+     */
+    private _runTransition;
+    /**
+     * Recovery handler for a single in-flight intent.
+     * Dispatches by state per §6.5.
+     */
+    private _recoverOne;
+    /**
+     * Per-state recovery dispatch per §6.5.
+     */
+    private _recoverDispatch;
+}