@jinn-network/client 0.1.2 → 0.1.3-canary.216cf7e6

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

@@ -0,0 +1,534 @@
+/**
+ * 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 PackagingDeps } from './packaging.js';
+import { type EnvelopeAssemblyDeps } from './envelope-assembly.js';
+import { type DeliveryDeps } from './delivery.js';
+import type { Harness, HarnessContext, RuntimePlugin } from '../types.js';
+import type { IdentityPublisher, ReputationRegistryClient, ResolvedAgent } from '../../erc8004/index.js';
+import type { Task } from '../../types/task.js';
+import { TrajectoryCollector } from '../../trajectory/index.js';
+import type { SolverNetManifestV1 } from '../../vendor/@jinn-network/sdk/dist/solvernets/index.js';
+import { type FreezeViolation } from '../../daemon/freeze-fence.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, taskRole?: 'restoration' | 'evaluation'): {
+        name: string;
+        solverType: string;
+        harness: string;
+        model?: string;
+        runtimePlugins: RuntimePlugin[];
+    } | undefined;
+}
+/**
+ * Read-only view of the operator config's `joinedSolverNets` map.
+ *
+ * Per spec §14 of `spec/2026-05-05-solvernet-creation-and-launch.md`,
+ * operator claim eligibility is per-launch via `manifestDigest`
+ * (= keccak256(manifestCid)) — an operator who joined Launcher A's
+ * Prediction net is not automatically eligible for Launcher B's
+ * Prediction tasks even though both share the same SolverNet contract.
+ *
+ * Keys are the manifest CID (CIDv0 / CIDv1) the operator joined under.
+ * Values declare which roles ('solver' / 'evaluator') the operator
+ * agreed to fulfil for that net.
+ *
+ * Wired by `main.ts` from `config.joinedSolverNets` (Task 21). Tests and
+ * legacy paths that don't exercise per-launch attribution can omit it; the
+ * engine then falls back to its prior solverType-driven eligibility check.
+ */
+export interface JoinedSolverNetsView {
+    /** Returns the joined-net entry for the given manifest CID, or undefined. */
+    get(manifestCid: string): {
+        roles: Array<'solver' | 'evaluator'>;
+    } | undefined;
+    /** Enumerate all joined manifest CIDs (used for digest-based filtering). */
+    manifestCids(): string[];
+}
+/**
+ * Build a `JoinedSolverNetsView` from the raw operator-config block.
+ *
+ * The config carries the full `JoinedSolverNetEntry` shape (manifestCid,
+ * name, roles, harness, model, plugins, ...). The engine only needs
+ * `roles` and the CID-keyed lookup, so this helper narrows it.
+ */
+export declare function joinedSolverNetsViewFromConfig(joined: Record<string, {
+    manifestCid: string;
+    roles: Array<'solver' | 'evaluator'>;
+}> | undefined): JoinedSolverNetsView | undefined;
+/**
+ * Resolves a launched SolverNet manifest by IPFS CID.
+ *
+ * Engine-internal contract; the production wiring passes
+ * `IdentityRegistryBackedSolverNetRegistryClient` (Task 4 of
+ * `spec/2026-05-05-solvernet-creation-and-launch.md`), which fetches the
+ * manifest from IPFS and verifies the canonical hash before returning.
+ *
+ * Per spec §14, task validation goes manifest → contract → schemas:
+ * the engine resolves the task's `solverNetManifestCid`, reads
+ * `manifest.contract.{id, version}`, and validates the task body against
+ * that contract's schema. The legacy `solverType`-keyed schema lookup
+ * is retired here.
+ *
+ * Optional — when absent, engines without a registry wired (e.g. unit
+ * tests for non-validation paths) skip task-body schema validation.
+ */
+export interface ManifestResolver {
+    getManifest(args: {
+        manifestCid: string;
+    }): Promise<SolverNetManifestV1>;
+}
+export interface TaskEngineOptions {
+    store: Store;
+    paths: {
+        workingDirRoot: string;
+        implStateDirRoot: string;
+    };
+    /**
+     * 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;
+    /**
+     * Per-launch operator eligibility filter (Task 28 of
+     * `spec/2026-05-05-solvernet-creation-and-launch.md`).
+     *
+     * When wired, `canAcceptTask` filters incoming tasks by
+     * `manifestDigest = keccak256(task.solverNetManifestCid)` against the set
+     * of CIDs the operator has joined, plus a role gate
+     * (restoration → 'solver', evaluation → 'evaluator'). Tasks whose
+     * `manifestDigest` doesn't match any joined CID are rejected before any
+     * harness is consulted — this disambiguates "Launcher A's Prediction" from
+     * "Launcher B's Prediction" even when they share the same SolverNet
+     * contract.
+     *
+     * Optional — engines without it (legacy unit tests, in-memory adapter)
+     * fall back to the prior solverType-keyed eligibility path on the
+     * SolverNet registry.
+     */
+    joinedSolverNets?: JoinedSolverNetsView;
+    /**
+     * Resolves a launched SolverNet manifest by `solverNetManifestCid`.
+     * Required for production wiring; tests that don't exercise schema
+     * validation can omit it.
+     *
+     * See `ManifestResolver` and `spec/2026-05-05-solvernet-creation-and-launch.md` §14.
+     */
+    manifestResolver?: ManifestResolver;
+    /**
+     * 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>;
+        donation?: {
+            enabled: boolean;
+        };
+    };
+    /**
+     * Harness execution mode from operator config (JinnConfig.harness.mode).
+     * Controls whether implStateDir writes are permitted during each Task run.
+     *
+     * 'train' (default): harness may mutate implStateDir — normal learning mode.
+     * 'frozen': freeze-fence enforces read-only implStateDir; violations cause
+     *   the envelope to be rejected and the task to fail.
+     *
+     * Defaults to 'train' when absent so existing callers are unaffected.
+     *
+     * Spec: docs/superpowers/specs/2026-05-06-agent-harness-solvernet-design.md §6.3
+     */
+    harnessMode?: 'train' | 'frozen';
+}
+/** Per-task outcome from a recovery pass. */
+export interface RecoveryReport {
+    requestId: string;
+    outcome: 'ok' | 'failed';
+    error?: string;
+}
+interface TickOptions {
+    /**
+     * When true, wait for newly scheduled task processing to settle before
+     * returning. Direct callers keep the historical behavior. The daemon's
+     * periodic loop uses wait=false so one long harness run cannot starve
+     * other in-flight tasks discovered later.
+     */
+    wait?: boolean;
+}
+export declare class TaskEngine {
+    protected readonly persistence: TaskRunPersistence;
+    protected readonly paths: TaskEngineOptions['paths'];
+    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 joinedSolverNets: TaskEngineOptions['joinedSolverNets'];
+    protected readonly manifestResolver: TaskEngineOptions['manifestResolver'];
+    protected readonly identityPublisher: TaskEngineOptions['identityPublisher'];
+    protected readonly reputationFeedback: TaskEngineOptions['reputationFeedback'];
+    protected readonly operatorConfig: TaskEngineOptions['operatorConfig'];
+    /**
+     * Operator-configured harness mode. Defaults to 'train' when absent.
+     * Propagated to HarnessContext.mode for each runImpl dispatch.
+     */
+    protected readonly harnessMode: 'train' | 'frozen';
+    /** 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;
+    private readonly modesByRequest;
+    private readonly codeDigestsByRequest;
+    protected readonly trajectoryCollectors: Map<string, TrajectoryCollector>;
+    private readonly trajectoryRefs;
+    private readonly runtimePluginsByRequest;
+    private readonly processingRequestIds;
+    /** Set by stop(); causes runTickLoop to exit at the next iteration. */
+    private stopped;
+    private stopResolve?;
+    private readonly stopPromise;
+    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>;
+    canAcceptTask(input: {
+        solverType?: string;
+        taskRole?: 'restoration' | 'evaluation';
+        task?: Task;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /**
+     * 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(options?: TickOptions): 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;
+    private scheduleProcess;
+    private logProcessReport;
+    /**
+     * 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>;
+    /**
+     * TaskCoordinator clean-break claim transition.
+     *
+     * The on-chain Task claim happens before observe(), producing the internal
+     * Mech requestId stored in this row. The engine's CLAIM step now only verifies
+     * the operator has an enabled, ready Harness and advances DISCOVERED → CLAIMED.
+     */
+    protected claim(task: PersistedTaskRun): Promise<void>;
+    releaseClaimedNotStarted(): Promise<string[]>;
+    /**
+     * Internal routing key alias for the daemon-internal `solverType`-keyed
+     * harness map. Per spec §15 (non-goal of
+     * `spec/2026-05-05-solvernet-creation-and-launch.md`), the harness
+     * dispatch alias is intentionally retained for one cycle past Task 30;
+     * the user-facing surface (manifest, SPA, SDK shapes) is `solverType`-
+     * free. Prefers the canonical `${contractId}.${contractVersion}` when
+     * the task carries them, and falls back to the legacy `task.solverType`
+     * field for pre-Task-24 shapes / health-check tasks. Mirrors the SDK's
+     * internal `solverTypeAlias` helper but operates on a `Task`.
+     */
+    private routingKeyForTask;
+    /**
+     * Resolve the task's `solverNetManifestCid` via the registry, fetch the
+     * manifest, and validate the task body against `manifest.contract.schemas.task`.
+     *
+     * Returns `null` when validation passes (or is skipped because no
+     * `manifestResolver` is wired and the task carries no `solverNetManifestCid`),
+     * or a human-readable failure reason otherwise.
+     *
+     * Day-1 compatibility note: this validates via the SDK template's Zod schema
+     * looked up by `{contract.id, contract.version}`. The manifest's embedded
+     * JSON Schema is the canonical wire format; once external launchers can
+     * publish manifests with arbitrary task schemas, this will switch to a JSON
+     * Schema validator (or `jsonSchemaToZod`) over the manifest's own schema.
+     * See `spec/2026-05-05-solvernet-creation-and-launch.md` §14.
+     */
+    private manifestBackedValidation;
+    /**
+     * Returns a human-readable failure reason when the task is NOT eligible
+     * for this operator under the manifest-bound per-launch attribution
+     * model (spec §14, Task 28), or `null` when the task passes the filter.
+     *
+     * Eligibility logic:
+     *   - The operator must have an entry in `joinedSolverNets` whose
+     *     `manifestCid` matches `task.solverNetManifestCid` (or whose
+     *     `keccak256(manifestCid)` matches the task's on-chain
+     *     `manifestDigest` when only the digest is available).
+     *   - The entry's `roles` must include the role required by this task
+     *     ('solver' for restoration, 'evaluator' for evaluation).
+     *
+     * Caller must have already guarded `this.joinedSolverNets` non-null and
+     * `task` non-null.
+     */
+    private evaluateJoinedEligibility;
+    private runnableFailureReason;
+    /**
+     * 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 verdictCodeForTask;
+    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. 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;
+}
+/**
+ * Thin, test-friendly entry point for the freeze-fence + mode propagation
+ * path.  Runs a single `harness.run(ctx)` call through `runHarnessWithFreezeFence`
+ * and returns either a minimal envelope stub (carrying `executor.mode`) or a
+ * structured violation result — without requiring a full DB-backed TaskEngine
+ * state machine.
+ *
+ * This function is *not* the production dispatch path; it exists so integration
+ * tests can drive the mode-propagation and freeze-fence behaviour in isolation.
+ *
+ * @returns
+ *   `{ envelope: { executor: { mode } } }` on success.
+ *   `{ violation: FreezeViolation }` when the fence rejects the harness output.
+ *
+ * Spec: docs/superpowers/specs/2026-05-06-agent-harness-solvernet-design.md §6.3
+ */
+export declare function runHarnessOnce(params: {
+    harness: Harness;
+    implStateDir: string;
+    mode: 'train' | 'frozen';
+    /** Optional working directory (defaults to implStateDir). */
+    workingDir?: string;
+    /** Optional task stub (defaults to a minimal no-op task). */
+    task?: HarnessContext['task'];
+}): Promise<{
+    envelope?: {
+        executor: {
+            mode: 'train' | 'frozen';
+            codeDigest: string;
+        };
+    };
+    violation?: FreezeViolation;
+}>;
+export {};