@jinn-network/client 0.1.1 → 0.1.2-canary.d6e72dfd

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

@@ -0,0 +1,52 @@
+/**
+ * Restorer engine — mech delivery + JinnRouter.claimDelivery.
+ *
+ * §6.1 DELIVERING phase.
+ *
+ * Steps:
+ *   1. Encode manifest CID as bytes32 digest (cidToDigestHex).
+ *   2. Call mech.deliverToMarketplace(requestId, deliveryDigest) via the Safe.
+ *   3. Call JinnRouter.claimDelivery(requestId, evidenceHash) where evidenceHash
+ *      is the keccak256 hash of the signed manifest (from manifest assembly).
+ */
+import type { Hex, PublicClient, WalletClient, Address } from 'viem';
+export interface DeliveryDeps {
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+    safeAddress: Address;
+    mechContractAddress: Address;
+    routerAddress: Address;
+    /** v1 or v2 claimDelivery encoding — matches chain config */
+    claimDeliveryVariant: 'v1' | 'v2';
+}
+/**
+ * Callback invoked after deliverToMarketplace lands on-chain but BEFORE
+ * claimDelivery is called. Callers use this to durably persist the tx hash so
+ * that a crash between the two steps can be recovered without re-submitting the
+ * deliver transaction.
+ */
+export type OnDeliveryTxLanded = (deliveryTxHash: Hex) => void | Promise<void>;
+export interface DeliveryResult {
+    deliveryTxHash: Hex;
+    claimTxHash: Hex;
+}
+/**
+ * Deliver the manifest to the marketplace and claim the delivery on JinnRouter.
+ *
+ * Crash-recovery safe: if `preExistingDeliveryTxHash` is provided, the
+ * deliverToMarketplace step is skipped entirely — the function resumes from
+ * the claimDelivery step only. This handles the case where the process crashed
+ * after deliver landed on-chain but before the COMPLETE transition was persisted.
+ *
+ * @param requestId                 The on-chain request ID (bytes32 hex).
+ * @param manifestCid               IPFS CID of the signed manifest.
+ * @param evidenceHash              keccak256 hash of the canonical manifest JSON
+ *   (from manifest assembly) — used as evidenceHash in claimDelivery V2.
+ * @param deps                      Viem clients + contract addresses.
+ * @param preExistingDeliveryTxHash If set, skip deliverToMarketplace and use
+ *   this as the deliveryTxHash in the result.
+ * @param onDeliveryTxLanded        Optional callback invoked after
+ *   deliverToMarketplace succeeds, before claimDelivery. Use this to persist the
+ *   tx hash so recovery can skip the deliver step on restart.
+ */
+export declare function deliverAndClaim(requestId: Hex, manifestCid: string, evidenceHash: Hex, deps: DeliveryDeps, preExistingDeliveryTxHash?: Hex, onDeliveryTxLanded?: OnDeliveryTxLanded): Promise<DeliveryResult>;

package/dist/restorer/engine/delivery.js

@@ -0,0 +1,63 @@
+/**
+ * Restorer engine — mech delivery + JinnRouter.claimDelivery.
+ *
+ * §6.1 DELIVERING phase.
+ *
+ * Steps:
+ *   1. Encode manifest CID as bytes32 digest (cidToDigestHex).
+ *   2. Call mech.deliverToMarketplace(requestId, deliveryDigest) via the Safe.
+ *   3. Call JinnRouter.claimDelivery(requestId, evidenceHash) where evidenceHash
+ *      is the keccak256 hash of the signed manifest (from manifest assembly).
+ */
+import { cidToDigestHex, } from '../../adapters/mech/ipfs.js';
+import { callDeliverToMarketplace, claimDelivery, } from '../../adapters/mech/contracts.js';
+/**
+ * Deliver the manifest to the marketplace and claim the delivery on JinnRouter.
+ *
+ * Crash-recovery safe: if `preExistingDeliveryTxHash` is provided, the
+ * deliverToMarketplace step is skipped entirely — the function resumes from
+ * the claimDelivery step only. This handles the case where the process crashed
+ * after deliver landed on-chain but before the COMPLETE transition was persisted.
+ *
+ * @param requestId                 The on-chain request ID (bytes32 hex).
+ * @param manifestCid               IPFS CID of the signed manifest.
+ * @param evidenceHash              keccak256 hash of the canonical manifest JSON
+ *   (from manifest assembly) — used as evidenceHash in claimDelivery V2.
+ * @param deps                      Viem clients + contract addresses.
+ * @param preExistingDeliveryTxHash If set, skip deliverToMarketplace and use
+ *   this as the deliveryTxHash in the result.
+ * @param onDeliveryTxLanded        Optional callback invoked after
+ *   deliverToMarketplace succeeds, before claimDelivery. Use this to persist the
+ *   tx hash so recovery can skip the deliver step on restart.
+ */
+export async function deliverAndClaim(requestId, manifestCid, evidenceHash, deps, preExistingDeliveryTxHash, onDeliveryTxLanded) {
+    let deliveryTxHash;
+    if (preExistingDeliveryTxHash) {
+        // Recovery path: deliverToMarketplace already landed on a previous run.
+        console.log(`[restorer-engine] deliverToMarketplace already done (recovery), tx=${preExistingDeliveryTxHash}`);
+        deliveryTxHash = preExistingDeliveryTxHash;
+    }
+    else {
+        // 1. Convert manifest CID to 32-byte digest for on-chain delivery data
+        const deliveryDigest = cidToDigestHex(manifestCid);
+        // 2. deliverToMarketplace via Safe
+        console.log(`[restorer-engine] deliverToMarketplace requestId=${requestId}`);
+        deliveryTxHash = await callDeliverToMarketplace(deps.publicClient, deps.walletClient, deps.safeAddress, deps.mechContractAddress, [requestId], [deliveryDigest]);
+        console.log(`[restorer-engine] deliverToMarketplace tx=${deliveryTxHash}`);
+        // Persist the tx hash before proceeding to claimDelivery. If the process
+        // crashes between here and the COMPLETE transition, recovery will read this
+        // hash and skip the deliver step.
+        if (onDeliveryTxLanded) {
+            await onDeliveryTxLanded(deliveryTxHash);
+        }
+    }
+    // 3. claimDelivery on JinnRouter
+    console.log(`[restorer-engine] claimDelivery requestId=${requestId}`);
+    const claimTxHash = await claimDelivery(deps.publicClient, deps.walletClient, deps.safeAddress, deps.routerAddress, requestId, {
+        variant: deps.claimDeliveryVariant,
+        evidenceHash: deps.claimDeliveryVariant === 'v2' ? evidenceHash : undefined,
+    });
+    console.log(`[restorer-engine] claimDelivery tx=${claimTxHash}`);
+    return { deliveryTxHash, claimTxHash };
+}
+//# sourceMappingURL=delivery.js.map

package/dist/restorer/engine/delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.js","sourceRoot":"","sources":["../../../src/restorer/engine/delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EACL,cAAc,GACf,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,wBAAwB,EACxB,aAAa,GACd,MAAM,kCAAkC,CAAC;AA6B1C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,SAAc,EACd,WAAmB,EACnB,YAAiB,EACjB,IAAkB,EAClB,yBAA+B,EAC/B,kBAAuC;IAEvC,IAAI,cAAmB,CAAC;IAExB,IAAI,yBAAyB,EAAE,CAAC;QAC9B,wEAAwE;QACxE,OAAO,CAAC,GAAG,CAAC,sEAAsE,yBAAyB,EAAE,CAAC,CAAC;QAC/G,cAAc,GAAG,yBAAyB,CAAC;IAC7C,CAAC;SAAM,CAAC;QACN,uEAAuE;QACvE,MAAM,cAAc,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;QAEnD,mCAAmC;QACnC,OAAO,CAAC,GAAG,CAAC,oDAAoD,SAAS,EAAE,CAAC,CAAC;QAC7E,cAAc,GAAG,MAAM,wBAAwB,CAC7C,IAAI,CAAC,YAAY,EACjB,IAAI,CAAC,YAAY,EACjB,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,mBAAmB,EACxB,CAAC,SAAS,CAAC,EACX,CAAC,cAAc,CAAC,CACjB,CAAC;QACF,OAAO,CAAC,GAAG,CAAC,6CAA6C,cAAc,EAAE,CAAC,CAAC;QAE3E,yEAAyE;QACzE,4EAA4E;QAC5E,kCAAkC;QAClC,IAAI,kBAAkB,EAAE,CAAC;YACvB,MAAM,kBAAkB,CAAC,cAAc,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED,iCAAiC;IACjC,OAAO,CAAC,GAAG,CAAC,6CAA6C,SAAS,EAAE,CAAC,CAAC;IACtE,MAAM,WAAW,GAAG,MAAM,aAAa,CACrC,IAAI,CAAC,YAAY,EACjB,IAAI,CAAC,YAAY,EACjB,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,aAAa,EAClB,SAAS,EACT;QACE,OAAO,EAAE,IAAI,CAAC,oBAAoB;QAClC,YAAY,EAAE,IAAI,CAAC,oBAAoB,KAAK,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS;KAC5E,CACF,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,sCAAsC,WAAW,EAAE,CAAC,CAAC;IAEjE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,CAAC;AACzC,CAAC"}

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;
+}