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

package/dist/harnesses/engine/engine.d.ts

@@ -0,0 +1,341 @@
+/**
+ * Harness engine — main TaskEngine class.
+ *
+ * §6.3, §6.5 of spec/2026-04-17-portfolio-v0-design.md
+ *
+ * Orchestrates the state machine lifecycle for each observed task.
+ * Transition method bodies are stubs; subsequent tasks fill them in.
+ */
+import { TaskRunPersistence, type PersistedTaskRun, type PersistedTaskRunInput } 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 EnvelopeAssemblyDeps } from './envelope-assembly.js';
+import { type DeliveryDeps } from './delivery.js';
+import type { Harness, RuntimePlugin } from '../types.js';
+import type { IdentityPublisher, ReputationRegistryClient, ResolvedAgent } from '../../erc8004/index.js';
+import { TrajectoryCollector } from '../../trajectory/index.js';
+export declare class NotImplementedError extends Error {
+    readonly transitionName: string;
+    constructor(transitionName: string);
+}
+/**
+ * Resolves a `Harness` for a given solverType (and optional role), or
+ * returns `undefined` when nothing is registered/enabled.
+ *
+ * The engine only needs `findFor` — `resolveImplName` was a redundant alias
+ * for `findFor(...)?.name` and was removed under jinn-mono-qip (supersedes
+ * jinn-mono-cy4). Concrete implementation lives in
+ * `harnesses/engine/registry.ts` (`HarnessRegistry`).
+ */
+export interface ImplRegistry {
+    findFor(ctx: {
+        solverType: string;
+        role?: 'restoration' | 'evaluation';
+    }): Harness | undefined;
+}
+export interface SolverNetRegistryLike {
+    forSolverType(solverType: string): {
+        name: string;
+        solverType: string;
+        harness: string;
+        canonicalPlugin: RuntimePlugin;
+        plugins: RuntimePlugin[];
+    } | undefined;
+}
+export interface TaskEngineOptions {
+    store: Store;
+    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.
+     *
+     * `requestId` is filled per-call by the engine from the in-flight task;
+     * `collector` is wired per-call from `trajectoryCollectors`.
+     */
+    packagingDeps?: Omit<PackagingDeps, 'requestId' | 'collector'>;
+    /**
+     * Envelope assembly dependencies. When provided, pack() can assemble + sign.
+     * When absent, pack() falls back to NotImplementedError.
+     *
+     * Replaces the old `manifestDeps` (ManifestAssemblyDeps). The safeAddress
+     * field that was on ManifestAssemblyDeps is now sourced from deliveryDeps
+     * or passed directly in EnvelopeInputs.participant.
+     */
+    envelopeDeps?: EnvelopeAssemblyDeps & {
+        safeAddress?: `0x${string}`;
+    };
+    /**
+     * Delivery dependencies. When provided, deliver() is functional.
+     * When absent, deliver() falls back to NotImplementedError.
+     */
+    deliveryDeps?: DeliveryDeps;
+    /**
+     * Impl registry for resolving which Harness to run.
+     * When provided and findFor() returns an impl, runImpl() dispatches to it.
+     */
+    implRegistry?: ImplRegistry;
+    solverNetRegistry?: SolverNetRegistryLike;
+    /**
+     * ERC-8004 Identity Registry per-execution publisher (jinn-mono-3zk).
+     * When provided, the engine calls
+     *   `IdentityRegistry.setMetadata(agentId, "envelope:<cid>", v1Payload)`
+     * after `pack()` returns the manifest CID + evidenceHash, anchoring the
+     * execution under the operator's agent NFT (DR §4.2).
+     *
+     * Failures are logged but NEVER fatal — JinnRouter.claimDelivery(evidenceHash)
+     * remains the authoritative on-chain commitment; this publish is the
+     * discovery anchor.
+     *
+     * Optional — when absent, the engine simply skips publishing.
+     */
+    identityPublisher?: IdentityPublisher;
+    /**
+     * ERC-8004 ReputationRegistry feedback hook (jinn-mono-yg4).
+     *
+     * When provided, the engine fires `submitEvaluatorFeedback` after a
+     * successful evaluator-side `claimDelivery`, so the harness's agent NFT
+     * accrues a rating per DR §4.3. Requires:
+     *
+     *   - `client`: a `ReputationRegistryClient` (writes are routed through the
+     *     evaluator's Safe so `msg.sender` matches the operator identity).
+     *   - `resolveAgentId`: looks up the harness's `agentId` from the parent
+     *     manifest's `evidenceHash`. Returns `null` when no match is found
+     *     (subgraph not yet indexed; envelope not published) — the engine
+     *     skips feedback gracefully without failing delivery.
+     *
+     * Failures inside the hook are logged but NEVER fatal: JinnRouter's
+     * `claimDelivery` is the authoritative settlement. Restoration-only
+     * tasks skip this branch entirely.
+     *
+     * Optional — when absent, the engine simply skips feedback.
+     */
+    reputationFeedback?: {
+        client: ReputationRegistryClient;
+        resolveAgentId: (manifestHash: `0x${string}`) => Promise<ResolvedAgent | null>;
+    };
+    /**
+     * Operator-local artifact serving config (Phase A.1, jinn-mono-vy37.1.3).
+     *
+     * `publicEndpoint` is the externally-reachable base URL stamped onto every
+     * artifact + trajectory `access.endpoint`. `defaultPriceUsdc` and
+     * `perArtifactTypePrice` are pinned here so the engine doesn't have to thread
+     * them through `packagingDeps` separately for trajectory refs.
+     *
+     * Required for production wiring; tests may construct a synthetic value.
+     */
+    operatorConfig?: {
+        publicEndpoint: string;
+        defaultPriceUsdc: string;
+        perArtifactTypePrice: Record<string, string>;
+    };
+}
+/** Per-task outcome from a recovery pass. */
+export interface RecoveryReport {
+    requestId: string;
+    outcome: 'ok' | 'failed';
+    error?: string;
+}
+export declare class TaskEngine {
+    protected readonly persistence: TaskRunPersistence;
+    protected readonly paths: TaskEngineOptions['paths'];
+    protected readonly claimDeps: TaskEngineOptions['claimDeps'];
+    protected readonly packagingDeps: TaskEngineOptions['packagingDeps'];
+    protected readonly envelopeDeps: TaskEngineOptions['envelopeDeps'];
+    protected readonly deliveryDeps: TaskEngineOptions['deliveryDeps'];
+    protected readonly implRegistry: TaskEngineOptions['implRegistry'];
+    protected readonly solverNetRegistry: TaskEngineOptions['solverNetRegistry'];
+    protected readonly identityPublisher: TaskEngineOptions['identityPublisher'];
+    protected readonly reputationFeedback: TaskEngineOptions['reputationFeedback'];
+    protected readonly operatorConfig: TaskEngineOptions['operatorConfig'];
+    /** Local SQLite-backed store; used to emit `restoration-result` /
+     *  `evaluation-verdict` artifact rows when a cycle completes via a
+     *  deterministic impl (the legacy claude/MCP path writes them itself). */
+    protected readonly store: Store;
+    private readonly solutionOutputs;
+    protected readonly trajectoryCollectors: Map<string, TrajectoryCollector>;
+    private readonly trajectoryRefs;
+    private readonly runtimePluginsByRequest;
+    /** Set by stop(); causes runTickLoop to exit at the next iteration. */
+    private stopped;
+    constructor(opts: TaskEngineOptions);
+    /**
+     * Called when an task is observed from an on-chain event.
+     * Persists a DISCOVERED row. Idempotent: if the row already exists, no-op.
+     */
+    observe(input: PersistedTaskRunInput): Promise<void>;
+    /**
+     * Recover all in-flight tasks from persisted state.
+     * Called at daemon startup before beginning normal event processing.
+     * Returns a per-task report for each task attempted.
+     */
+    recoverInFlight(): Promise<RecoveryReport[]>;
+    /**
+     * Periodic tick: advance every in-flight task by one transition.
+     * Called by `runTickLoop` so that tasks 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 tasks 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 task: 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(task: PersistedTaskRun): Promise<void>;
+    /**
+     * Release ClaimRegistry claims for all CLAIMED tasks 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
+     * task.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(run: PersistedTaskRun): Promise<void>;
+    /**
+     * RUNNING transition: dispatch to a Harness if implRegistry is provided.
+     *
+     * When no impl is found for the solverType, 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 `solutionOutputs` map for pack() to consume. Also
+     * records a minimal post-snapshot so data-driven advance can fire.
+     */
+    protected runImpl(task: PersistedTaskRun): Promise<void>;
+    protected takePostSnapshot(_intent: PersistedTaskRun): Promise<void>;
+    /**
+     * PACKAGING transition: walk workingDir, upload artifacts, assemble + sign
+     * envelope, upload envelope, persist envelope CID + artifact CIDs.
+     *
+     * Requires packagingDeps + envelopeDeps. When absent, falls back to
+     * NotImplementedError.
+     */
+    protected pack(task: PersistedTaskRun): Promise<void>;
+    /**
+     * DELIVERING transition: call mech.deliverToMarketplace + JinnRouter.claimDelivery.
+     *
+     * Requires deliveryDeps. When absent, falls back to NotImplementedError.
+     *
+     * Crash-recovery safe: if `task.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(task: PersistedTaskRun): Promise<void>;
+    /**
+     * Post evaluator feedback on the harness's agent NFT.
+     *
+     * Pulls the verdict from the persisted gating claim (the evaluator impl
+     * writes `{ verdict, score, scoreBasis, ... }` into `output.gating`),
+     * resolves the harness's `agentId` via the configured subgraph
+     * resolver, and submits a single `ReputationRegistry.giveFeedback` tx.
+     *
+     * Skipped silently when:
+     *   - No `reputationFeedback` deps wired.
+     *   - `gatingClaim` doesn't carry a verdict (impl shape mismatch — log and
+     *     return).
+     *   - The parent harness's manifest hash isn't reachable from the
+     *     persisted state — log and return).
+     *   - `resolveAgentId` returns null (subgraph not indexed yet, or no
+     *     subgraph URL configured at all — log and return).
+     *
+     * The mapping policy (PASS / FAIL / REJECTED / INDETERMINATE → score) lives
+     * inside `submitEvaluatorFeedback` / `mapVerdictToScore` in the
+     * feedback-hook module; we just hand it the verdict.
+     */
+    /**
+     * Insert a SQLite `artifacts` row for a successfully delivered cycle so the
+     * release acceptance gate (and the search API) can observe completion via
+     * the same surface as the legacy claude / MCP path.
+     *
+     * The legacy `legacy-claude` impl writes via the MCP `submit_restoration_result`
+     * tool when Claude reports success; deterministic impls don't go through MCP.
+     * This emitter closes that gap by writing the row from the engine when the
+     * cycle hits COMPLETE.
+     *
+     * Idempotent: if a row already exists for (requestId, tag) — e.g. the legacy
+     * MCP path got there first — we leave it alone.
+     */
+    private emitCycleArtifact;
+    private _maybePostEvaluatorFeedback;
+    /**
+     * Extract the harness's `evidenceHash` (and best-effort `manifestCid`)
+     * from the persisted evaluation task.
+     *
+     * The evaluator's `task.context.restorationResult` holds the harness's
+     * full signed manifest JSON inlined as a string (per
+     * `MechAdapter.tryCreateEvaluationJob`). We parse it and pull the
+     * `signature.hash`, which is exactly the on-chain `evidenceHash`.
+     *
+     * The CID is not always inlined — the manifest carries its own
+     * `task.cid` field (the *original task* CID), not its self-CID. We
+     * therefore return `manifestCid: null` here and rely on the subgraph
+     * resolver to surface the published manifest CID. Returns `null` when
+     * the inlined payload is missing or malformed.
+     */
+    private _extractHarnessManifestRef;
+    /**
+     * 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 task is marked FAILED with the error message.
+     */
+    private _runTransition;
+    /**
+     * Recovery handler for a single in-flight task.
+     * Dispatches by state per §6.5.
+     */
+    private _recoverOne;
+    /**
+     * Per-state recovery dispatch per §6.5.
+     */
+    private _recoverDispatch;
+}