@jinn-network/client 0.1.2 → 0.1.3-canary.12cf8b76

package/templates/harnesses/evaluator/src/index.ts.tmpl

@@ -0,0 +1,35 @@
+import type {
+  Harness,
+  ExternalHarnessEnv,
+  HarnessContext,
+  Solution,
+} from '@jinn-network/sdk/harness';
+
+export default function createEvaluator(env: ExternalHarnessEnv): Harness {
+  return {
+    name: env.implName,
+    version: env.implVersion,
+    supports({ solverType, role }) {
+      return solverType === '{{solverTypeString}}' && role === 'evaluation';
+    },
+    async isReady() {
+      return env.stub
+        ? { ready: false, reason: 'stub mode' }
+        : { ready: true };
+    },
+    async run(ctx: HarnessContext): Promise<Solution> {
+      env.log({
+        level: 'info',
+        msg: 'evaluator.run',
+        data: { taskId: ctx.task.id },
+      });
+      // TODO: read the restoration envelope under evaluation, fetch ground-truth
+      // from your oracle, compute your score. Replace this stub with your impl.
+      return {
+        venueRef: { name: '{{packageName}}' },
+        gating: { score: 0, scoringRule: 'placeholder' },
+        verdictPayload: { score: 0, scoringRule: 'placeholder' },
+      };
+    },
+  };
+}

package/templates/harnesses/evaluator/test/unit.test.ts.tmpl

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest';
+import createEvaluator from '../src/index.js';
+import type {
+  ExternalHarnessEnv,
+  HarnessContext,
+} from '@jinn-network/sdk/harness';
+
+const env: ExternalHarnessEnv = {
+  implName: '{{packageName}}',
+  implVersion: '0.1.0',
+  network: '{{network}}',
+  implStateDir: '/tmp/{{packageNameSlug}}',
+  secrets: Object.freeze({}),
+  log: () => {},
+  stub: false,
+};
+
+const ctx: HarnessContext = {
+  task: { id: 'eval-1', description: 'eval', role: 'evaluation', solverType: '{{solverTypeString}}', spec: {} },
+  taskCid: undefined,
+  implStateDir: '/tmp/{{packageNameSlug}}',
+  workingDir: '/tmp/{{packageNameSlug}}-work',
+  log: () => {},
+  abort: new AbortController().signal,
+  msUntilEndTs: () => 60_000,
+  trajectory: { addSpan: () => ({}) },
+};
+
+describe('{{packageName}}', () => {
+  it('supports the configured SolverType only as evaluation', () => {
+    const impl = createEvaluator(env);
+    expect(impl.supports({ solverType: '{{solverTypeString}}', role: 'evaluation' })).toBe(
+      true,
+    );
+    expect(impl.supports({ solverType: '{{solverTypeString}}', role: 'restoration' })).toBe(
+      false,
+    );
+    expect(impl.supports({ solverType: 'other.v0', role: 'evaluation' })).toBe(false);
+  });
+
+  it('produces a verdictPayload with a score field', async () => {
+    const impl = createEvaluator(env);
+    const out = await impl.run(ctx);
+    expect(out.verdictPayload).toBeDefined();
+    expect(typeof (out.verdictPayload as Record<string, unknown>).score).toBe(
+      'number',
+    );
+  });
+});

package/templates/harnesses/evaluator/tsconfig.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2022", "DOM"],
+    "types": []
+  },
+  "include": ["src/**/*"]
+}

package/templates/harnesses/forecaster/README.md.tmpl

@@ -0,0 +1,25 @@
+# {{packageName}}
+
+Jinn external harness impl for `{{solverTypeString}}` on `{{network}}`.
+
+## Quickstart
+
+```bash
+yarn install
+yarn test       # unit tests
+yarn build      # produces dist/
+```
+
+Edit `src/index.ts` to plug in your forecasting pipeline. The `run()` method receives a `HarnessContext` (intent + workingDir + capability handles) and returns a `Solution`.
+
+## Publishing
+
+1. Compute your tarball CID + sha256: `npm pack && ipfs add *.tgz` and `shasum -a 256 *.tgz`.
+2. Update `jinn.manifest.json` with the resulting CID + hash.
+3. Sign the manifest with your ed25519 key (see `spec/2026-05-executor-trust-boundary.md` §5.2).
+4. Pin tarball + signed manifest on IPFS.
+5. Operators install via `jinn harnesses add ipfs://<manifest-cid>`.
+
+## Spec
+
+See `spec/2026-04-30-plug-in-surface.md` §3.3.1 (forecaster pattern).

package/templates/harnesses/forecaster/gitignore.tmpl

@@ -0,0 +1,5 @@
+dist/
+node_modules/
+.DS_Store
+.yarn/cache/
+.yarn/install-state.gz

package/templates/harnesses/forecaster/jinn.manifest.json.tmpl

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": "1.0.0",
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn external harness impl for {{solverTypeString}}.",
+  "supportedSolverTypes": ["{{solverTypeString}}>=1.0.0"],
+  "entry": "./dist/index.js",
+  "package": {
+    "cid": "bafy-PLACEHOLDER",
+    "hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "capabilities": {
+    "rpc": [
+      { "chainId": {{networkChainId}}, "methods": ["eth_call", "eth_blockNumber"] }
+    ]
+  },
+  "signature": {
+    "alg": "ed25519",
+    "publicKey": "PLACEHOLDER",
+    "sig": "PLACEHOLDER"
+  }
+}

package/templates/harnesses/forecaster/package.json.tmpl

@@ -0,0 +1,26 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "description": "Jinn external harness impl for {{solverTypeString}}.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist/", "jinn.manifest.json", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@jinn-network/sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}

package/templates/harnesses/forecaster/src/index.ts.tmpl

@@ -0,0 +1,33 @@
+import type {
+  Harness,
+  ExternalHarnessEnv,
+  HarnessContext,
+  Solution,
+} from '@jinn-network/sdk/harness';
+
+export default function createHarness(env: ExternalHarnessEnv): Harness {
+  return {
+    name: env.implName,
+    version: env.implVersion,
+    supports({ solverType, role }) {
+      return solverType === '{{solverTypeString}}' && role !== 'evaluation';
+    },
+    async isReady() {
+      return env.stub
+        ? { ready: false, reason: 'stub mode' }
+        : { ready: true };
+    },
+    async run(ctx: HarnessContext): Promise<Solution> {
+      env.log({
+        level: 'info',
+        msg: 'forecaster.run',
+        data: { taskId: ctx.task.id },
+      });
+      // TODO: call your existing forecasting pipeline here.
+      return {
+        venueRef: { name: '{{packageName}}' },
+        gating: { probability: 0.5 },
+      };
+    },
+  };
+}

package/templates/harnesses/forecaster/test/unit.test.ts.tmpl

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import createHarness from '../src/index.js';
+import type {
+  ExternalHarnessEnv,
+  HarnessContext,
+} from '@jinn-network/sdk/harness';
+
+const env: ExternalHarnessEnv = {
+  implName: '{{packageName}}',
+  implVersion: '0.1.0',
+  network: '{{network}}',
+  implStateDir: '/tmp/{{packageNameSlug}}',
+  secrets: Object.freeze({}),
+  log: () => {},
+  stub: false,
+};
+
+const ctx: HarnessContext = {
+  task: { id: 'test', description: 'test', solverType: '{{solverTypeString}}', spec: {} },
+  taskCid: undefined,
+  implStateDir: '/tmp/{{packageNameSlug}}',
+  workingDir: '/tmp/{{packageNameSlug}}-work',
+  log: () => {},
+  abort: new AbortController().signal,
+  msUntilEndTs: () => 60_000,
+  trajectory: { addSpan: () => ({}) },
+};
+
+describe('{{packageName}}', () => {
+  it('supports the configured SolverType', () => {
+    const impl = createHarness(env);
+    expect(impl.supports({ solverType: '{{solverTypeString}}' })).toBe(true);
+    expect(impl.supports({ solverType: 'other.v0' })).toBe(false);
+  });
+
+  it('produces a Solution with a probability', async () => {
+    const impl = createHarness(env);
+    const out = await impl.run(ctx);
+    expect(out.gating).toHaveProperty('probability');
+    expect(typeof out.gating.probability).toBe('number');
+  });
+});

package/templates/harnesses/forecaster/tsconfig.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2022", "DOM"],
+    "types": []
+  },
+  "include": ["src/**/*"]
+}

package/dist/adapters/claim-registry/abi.d.ts

@@ -1,127 +0,0 @@
-/**
- * Typed ABI fragments for ClaimRegistry.
- *
- * Mirrors the Solidity interface in contracts/src/claiming/ClaimRegistry.sol.
- * Use these instead of the inline fragment in adapters/mech/types.ts when
- * constructing a ClaimRegistryClient — they include the full event set.
- */
-export declare const CLAIM_REGISTRY_ABI: readonly [{
-    readonly name: "claimJob";
-    readonly type: "function";
-    readonly stateMutability: "nonpayable";
-    readonly inputs: readonly [{
-        readonly name: "requestId";
-        readonly type: "bytes32";
-    }];
-    readonly outputs: readonly [];
-}, {
-    readonly name: "releaseClaim";
-    readonly type: "function";
-    readonly stateMutability: "nonpayable";
-    readonly inputs: readonly [{
-        readonly name: "requestId";
-        readonly type: "bytes32";
-    }];
-    readonly outputs: readonly [];
-}, {
-    readonly name: "expireClaim";
-    readonly type: "function";
-    readonly stateMutability: "nonpayable";
-    readonly inputs: readonly [{
-        readonly name: "requestId";
-        readonly type: "bytes32";
-    }];
-    readonly outputs: readonly [];
-}, {
-    readonly name: "getJobClaim";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [{
-        readonly name: "requestId";
-        readonly type: "bytes32";
-    }];
-    readonly outputs: readonly [{
-        readonly name: "claimer";
-        readonly type: "address";
-    }, {
-        readonly name: "expiresAt";
-        readonly type: "uint256";
-    }];
-}, {
-    readonly name: "claims";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [{
-        readonly name: "";
-        readonly type: "bytes32";
-    }];
-    readonly outputs: readonly [{
-        readonly name: "claimer";
-        readonly type: "address";
-    }, {
-        readonly name: "expiresAt";
-        readonly type: "uint256";
-    }];
-}, {
-    readonly name: "claimTTL";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [];
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "uint256";
-    }];
-}, {
-    readonly name: "expiredClaimCount";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [{
-        readonly name: "";
-        readonly type: "address";
-    }];
-    readonly outputs: readonly [{
-        readonly name: "";
-        readonly type: "uint256";
-    }];
-}, {
-    readonly name: "JobClaimed";
-    readonly type: "event";
-    readonly inputs: readonly [{
-        readonly name: "requestId";
-        readonly type: "bytes32";
-        readonly indexed: true;
-    }, {
-        readonly name: "claimer";
-        readonly type: "address";
-        readonly indexed: true;
-    }, {
-        readonly name: "expiresAt";
-        readonly type: "uint256";
-        readonly indexed: false;
-    }];
-}, {
-    readonly name: "ClaimExpired";
-    readonly type: "event";
-    readonly inputs: readonly [{
-        readonly name: "requestId";
-        readonly type: "bytes32";
-        readonly indexed: true;
-    }, {
-        readonly name: "previousClaimer";
-        readonly type: "address";
-        readonly indexed: true;
-    }];
-}, {
-    readonly name: "ClaimReleased";
-    readonly type: "event";
-    readonly inputs: readonly [{
-        readonly name: "requestId";
-        readonly type: "bytes32";
-        readonly indexed: true;
-    }, {
-        readonly name: "claimer";
-        readonly type: "address";
-        readonly indexed: true;
-    }];
-}];
-export type ClaimRegistryAbi = typeof CLAIM_REGISTRY_ABI;

package/dist/adapters/claim-registry/abi.js

@@ -1,93 +0,0 @@
-/**
- * Typed ABI fragments for ClaimRegistry.
- *
- * Mirrors the Solidity interface in contracts/src/claiming/ClaimRegistry.sol.
- * Use these instead of the inline fragment in adapters/mech/types.ts when
- * constructing a ClaimRegistryClient — they include the full event set.
- */
-export const CLAIM_REGISTRY_ABI = [
-    // ── Write functions ──────────────────────────────────────────────────────────
-    {
-        name: 'claimJob',
-        type: 'function',
-        stateMutability: 'nonpayable',
-        inputs: [{ name: 'requestId', type: 'bytes32' }],
-        outputs: [],
-    },
-    {
-        name: 'releaseClaim',
-        type: 'function',
-        stateMutability: 'nonpayable',
-        inputs: [{ name: 'requestId', type: 'bytes32' }],
-        outputs: [],
-    },
-    {
-        name: 'expireClaim',
-        type: 'function',
-        stateMutability: 'nonpayable',
-        inputs: [{ name: 'requestId', type: 'bytes32' }],
-        outputs: [],
-    },
-    // ── Read functions ───────────────────────────────────────────────────────────
-    {
-        name: 'getJobClaim',
-        type: 'function',
-        stateMutability: 'view',
-        inputs: [{ name: 'requestId', type: 'bytes32' }],
-        outputs: [
-            { name: 'claimer', type: 'address' },
-            { name: 'expiresAt', type: 'uint256' },
-        ],
-    },
-    {
-        name: 'claims',
-        type: 'function',
-        stateMutability: 'view',
-        inputs: [{ name: '', type: 'bytes32' }],
-        outputs: [
-            { name: 'claimer', type: 'address' },
-            { name: 'expiresAt', type: 'uint256' },
-        ],
-    },
-    {
-        name: 'claimTTL',
-        type: 'function',
-        stateMutability: 'view',
-        inputs: [],
-        outputs: [{ name: '', type: 'uint256' }],
-    },
-    {
-        name: 'expiredClaimCount',
-        type: 'function',
-        stateMutability: 'view',
-        inputs: [{ name: '', type: 'address' }],
-        outputs: [{ name: '', type: 'uint256' }],
-    },
-    // ── Events ───────────────────────────────────────────────────────────────────
-    {
-        name: 'JobClaimed',
-        type: 'event',
-        inputs: [
-            { name: 'requestId', type: 'bytes32', indexed: true },
-            { name: 'claimer', type: 'address', indexed: true },
-            { name: 'expiresAt', type: 'uint256', indexed: false },
-        ],
-    },
-    {
-        name: 'ClaimExpired',
-        type: 'event',
-        inputs: [
-            { name: 'requestId', type: 'bytes32', indexed: true },
-            { name: 'previousClaimer', type: 'address', indexed: true },
-        ],
-    },
-    {
-        name: 'ClaimReleased',
-        type: 'event',
-        inputs: [
-            { name: 'requestId', type: 'bytes32', indexed: true },
-            { name: 'claimer', type: 'address', indexed: true },
-        ],
-    },
-];
-//# sourceMappingURL=abi.js.map

package/dist/adapters/claim-registry/abi.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"abi.js","sourceRoot":"","sources":["../../../src/adapters/claim-registry/abi.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,gFAAgF;IAEhF;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAChD,OAAO,EAAE,EAAE;KACZ;IACD;QACE,IAAI,EAAE,cAAc;QACpB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAChD,OAAO,EAAE,EAAE;KACZ;IACD;QACE,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,YAAY;QAC7B,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAChD,OAAO,EAAE,EAAE;KACZ;IAED,gFAAgF;IAEhF;QACE,IAAI,EAAE,aAAa;QACnB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAChD,OAAO,EAAE;YACP,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;YACpC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE;SACvC;KACF;IACD;QACE,IAAI,EAAE,QAAQ;QACd,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACvC,OAAO,EAAE;YACP,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE;YACpC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE;SACvC;KACF;IACD;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,EAAE;QACV,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,IAAI,EAAE,UAAU;QAChB,eAAe,EAAE,MAAM;QACvB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACvC,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KACzC;IAED,gFAAgF;IAEhF;QACE,IAAI,EAAE,YAAY;QAClB,IAAI,EAAE,OAAO;QACb,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;YACrD,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;YACnD,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE;SACvD;KACF;IACD;QACE,IAAI,EAAE,cAAc;QACpB,IAAI,EAAE,OAAO;QACb,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;YACrD,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;SAC5D;KACF;IACD;QACE,IAAI,EAAE,eAAe;QACrB,IAAI,EAAE,OAAO;QACb,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;YACrD,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE;SACpD;KACF;CACO,CAAC"}

package/dist/adapters/claim-registry/client.d.ts

@@ -1,89 +0,0 @@
-/**
- * ClaimRegistryClient — typed wrapper for the ClaimRegistry contract.
- *
- * Wraps the read/write surfaces of ClaimRegistry with proper types and
- * idiomatic async interfaces.
- *
- * Write operations (claimJob, releaseClaim) go through the Safe multisig via
- * executeSafeTransaction. This is required so that the on-chain claimer address
- * matches the Safe — our canonical OLAS/staking identity. Using the raw EOA
- * would cause a mismatch: OnChainClaimPolicy already claims through the Safe,
- * so `weAlreadyClaimed()` would return false even when the Safe holds the claim,
- * triggering a redundant on-chain write that reverts as JobAlreadyClaimed.
- *
- * expireClaim() is permissionless (anyone can GC others' expired claims) and
- * is kept as a direct EOA call — the gas payer does not affect claim ownership.
- */
-import { type Address, type Hex, type PublicClient, type WalletClient } from 'viem';
-export declare const ZERO_ADDRESS: Address;
-export interface JobClaimInfo {
-    claimer: Address;
-    /** Unix timestamp (seconds) when the claim expires. 0 if no active claim. */
-    expiresAt: bigint;
-    /** True if claimer !== ZERO_ADDRESS and expiresAt > 0 (claim is still active per contract). */
-    isActive: boolean;
-}
-export interface ClaimJobResult {
-    /** Transaction hash. Empty string when skipped (already ours or failed). */
-    txHash: string;
-    /** True if we now hold the claim (new or pre-existing). */
-    claimed: boolean;
-}
-export declare class ClaimRegistryClient {
-    private readonly publicClient;
-    private readonly walletClient;
-    private readonly contractAddress;
-    /**
-     * The Safe multisig address — used as the canonical claimer identity.
-     * claimJob/releaseClaim are routed through Safe so that msg.sender on-chain
-     * is the Safe address, matching the OLAS staking identity.
-     */
-    private readonly safeAddress;
-    constructor(publicClient: PublicClient, walletClient: WalletClient, contractAddress: Address, 
-    /**
-     * The Safe multisig address — used as the canonical claimer identity.
-     * claimJob/releaseClaim are routed through Safe so that msg.sender on-chain
-     * is the Safe address, matching the OLAS staking identity.
-     */
-    safeAddress: Address);
-    /**
-     * Read the active claim for a request.
-     * Returns `(ZERO_ADDRESS, 0, false)` if no active claim (contract returns
-     * (address(0), 0) for expired/non-existent claims).
-     */
-    getJobClaim(requestId: Hex): Promise<JobClaimInfo>;
-    /**
-     * Check whether the Safe already holds an active claim for this request.
-     * Used for idempotency on resume.
-     */
-    weAlreadyClaimed(requestId: Hex): Promise<boolean>;
-    /**
-     * Claim a marketplace request through the Safe multisig.
-     *
-     * Idempotent: if the Safe already holds an active claim, returns
-     * `{ txHash: '', claimed: true }` without submitting a transaction.
-     *
-     * Returns `{ txHash: '', claimed: false }` when:
-     *   - Another address holds an active claim
-     *   - The eligibility check fails (IneligibleToClaim)
-     *   - The tx reverts for any other handled reason
-     *
-     * Throws on unrecognised RPC errors.
-     */
-    claimJob(requestId: Hex): Promise<ClaimJobResult>;
-    /**
-     * Voluntarily release a claim through the Safe multisig (no punishment).
-     * Should only be called when the Safe holds the claim.
-     * No-op (returns false) if the Safe doesn't hold the claim.
-     */
-    releaseClaim(requestId: Hex): Promise<boolean>;
-    /**
-     * Garbage-collect a stale (expired) claim.
-     *
-     * expireClaim is permissionless — anyone can call it to GC others' expired
-     * claims. The caller gets no reward; the previous claimer gets an
-     * expiredClaimCount increment. Since the gas payer doesn't affect claim
-     * ownership, this is sent directly from the EOA (cheaper than a Safe tx).
-     */
-    expireClaim(requestId: Hex): Promise<boolean>;
-}