@jinn-network/client 0.1.2 → 0.1.3-canary.2d6b2676

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

@@ -1,213 +0,0 @@
-/**
- * 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';
-import type { Registry8004 } from '../../discovery/registry.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;
-    };
-    /**
-     * ERC-8004 Identity Registry client. When provided, the engine registers
-     * the envelope (adw:ExecutionEnvelope) and each artifact (adw:Artifact with
-     * parentEnvelopeCid) after successful pack().
-     *
-     * Optional — tests and development modes may skip registration.
-     */
-    erc8004Registry?: Registry8004;
-}
-/** 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'];
-    protected readonly erc8004Registry: RestorationEngineOptions['erc8004Registry'];
-    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;
-}