@jinn-network/client 0.1.1 → 0.1.2-canary.6237288d

package/dist/observability/emit-event.d.ts

@@ -0,0 +1,12 @@
+import type { Store } from '../store/store.js';
+export type LifecycleKind = 'intent_posted' | 'intent_registry_failed' | 'envelope_registry_failed' | 'request_claimed' | 'delivery_submitted' | 'evaluation_submitted' | 'reward_claimed' | 'balance_topup' | 'engine_transition' | 'tick_error' | 'startup' | 'shutdown';
+export interface LifecycleEvent {
+    kind: LifecycleKind;
+    requestId?: string;
+    serviceIndex?: number;
+    txHash?: string;
+    specKind?: string;
+    outcome?: 'ok' | 'failed' | 'warn';
+    detail?: string;
+}
+export declare function emitEvent(store: Store, event: LifecycleEvent, component?: string): void;

package/dist/observability/emit-event.js

@@ -0,0 +1,27 @@
+export function emitEvent(store, event, component = 'lifecycle') {
+    const ts = new Date().toISOString();
+    store.recordActivityEvent({
+        ts,
+        kind: event.kind,
+        requestId: event.requestId ?? null,
+        serviceIndex: event.serviceIndex ?? null,
+        txHash: event.txHash ?? null,
+        specKind: event.specKind ?? null,
+        outcome: event.outcome ?? null,
+        detail: event.detail ?? null,
+    });
+    const payload = {
+        ts,
+        level: event.outcome === 'failed' ? 'error' : event.outcome === 'warn' ? 'warn' : 'info',
+        component,
+        msg: event.detail ?? event.kind,
+        requestId: event.requestId ?? null,
+        txHash: event.txHash ?? null,
+        serviceIndex: event.serviceIndex ?? null,
+        specKind: event.specKind ?? null,
+        outcome: event.outcome ?? 'ok',
+        kind: event.kind,
+    };
+    process.stderr.write(`${JSON.stringify(payload)}\n`);
+}
+//# sourceMappingURL=emit-event.js.map

package/dist/observability/emit-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit-event.js","sourceRoot":"","sources":["../../src/observability/emit-event.ts"],"names":[],"mappings":"AA0BA,MAAM,UAAU,SAAS,CACvB,KAAY,EACZ,KAAqB,EACrB,SAAS,GAAG,WAAW;IAEvB,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,KAAK,CAAC,mBAAmB,CAAC;QACxB,EAAE;QACF,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;QAClC,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI;QACxC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI;QAChC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;KAC7B,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG;QACd,EAAE;QACF,KAAK,EAAE,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;QACxF,SAAS;QACT,GAAG,EAAE,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI;QAC/B,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;QAClC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI;QACxC,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,IAAI;QAChC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,IAAI,EAAE,KAAK,CAAC,IAAI;KACjB,CAAC;IACF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACvD,CAAC"}

package/dist/preflight/api-port.d.ts

@@ -0,0 +1,13 @@
+export interface ApiPortPreflightOk {
+    ok: true;
+    port: number;
+}
+export interface ApiPortPreflightFail {
+    ok: false;
+    port: number;
+    code?: string;
+    message: string;
+}
+export type ApiPortPreflightResult = ApiPortPreflightOk | ApiPortPreflightFail;
+export declare function checkApiPortAvailable(port: number): Promise<ApiPortPreflightResult>;
+export declare function apiPortFailureMessage(result: ApiPortPreflightFail): string;

package/dist/preflight/api-port.js

@@ -0,0 +1,32 @@
+import { createServer } from 'node:net';
+export async function checkApiPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            server.removeAllListeners();
+            resolve(result);
+        };
+        server.once('error', (error) => {
+            finish({
+                ok: false,
+                port,
+                code: error.code,
+                message: error.message,
+            });
+        });
+        server.listen({ port, host: '0.0.0.0', exclusive: true }, () => {
+            server.close(() => finish({ ok: true, port }));
+        });
+    });
+}
+export function apiPortFailureMessage(result) {
+    if (result.code === 'EADDRINUSE') {
+        return `Port ${result.port} is already in use. Stop the other daemon or set JINN_API_PORT / apiPort to another port.`;
+    }
+    return `Port ${result.port} is not available: ${result.message}`;
+}
+//# sourceMappingURL=api-port.js.map

package/dist/preflight/api-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-port.js","sourceRoot":"","sources":["../../src/preflight/api-port.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAgBxC,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAAY;IACtD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;QAC9B,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,MAAM,MAAM,GAAG,CAAC,MAA8B,EAAE,EAAE;YAChD,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,CAAC,kBAAkB,EAAE,CAAC;YAC5B,OAAO,CAAC,MAAM,CAAC,CAAC;QAClB,CAAC,CAAC;QAEF,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAA4B,EAAE,EAAE;YACpD,MAAM,CAAC;gBACL,EAAE,EAAE,KAAK;gBACT,IAAI;gBACJ,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE;YAC7D,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAA4B;IAChE,IAAI,MAAM,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QACjC,OAAO,QAAQ,MAAM,CAAC,IAAI,2FAA2F,CAAC;IACxH,CAAC;IACD,OAAO,QAAQ,MAAM,CAAC,IAAI,sBAAsB,MAAM,CAAC,OAAO,EAAE,CAAC;AACnE,CAAC"}

package/dist/preflight/claude-auth.d.ts

@@ -6,11 +6,22 @@
  *   - 'docker-compose' — a docker-compose.yml with a jinn-daemon service lives in cwd
  *   - 'bare'           — plain host environment (default)
  *
- * Priority: container > docker-compose > bare.
+ * Priority:
+ *   1. JINN_RUNTIME_MODE env var (authoritative; CI/scripted operators)
+ *   2. `runtimeMode` field in the resolved config (persisted by `jinn auth`)
+ *   3. Filesystem heuristic (container → docker-compose → bare) as a last resort
+ *
+ * The filesystem path is a LAST RESORT because running from the `client/`
+ * checkout dir misdetects as docker-compose (the package's own compose file
+ * names `jinn-daemon`). Operators should set `runtimeMode` at `jinn auth`.
  */
 export type AuthContext = 'container' | 'docker-compose' | 'bare';
 export interface DetectContextOptions {
     cwd: string;
+    /** Optional explicit mode, typically from `config.runtimeMode`. Highest priority. */
+    configuredMode?: AuthContext;
+    /** Optional env (default: process.env). Tests can inject a stub. */
+    env?: NodeJS.ProcessEnv;
     /** Override the /.dockerenv existence check (for testing). */
     dockerenvExists?: boolean;
     /** Override the docker-compose.yml jinn-daemon check (for testing). */

package/dist/preflight/claude-auth.js

@@ -6,7 +6,14 @@
  *   - 'docker-compose' — a docker-compose.yml with a jinn-daemon service lives in cwd
  *   - 'bare'           — plain host environment (default)
  *
- * Priority: container > docker-compose > bare.
+ * Priority:
+ *   1. JINN_RUNTIME_MODE env var (authoritative; CI/scripted operators)
+ *   2. `runtimeMode` field in the resolved config (persisted by `jinn auth`)
+ *   3. Filesystem heuristic (container → docker-compose → bare) as a last resort
+ *
+ * The filesystem path is a LAST RESORT because running from the `client/`
+ * checkout dir misdetects as docker-compose (the package's own compose file
+ * names `jinn-daemon`). Operators should set `runtimeMode` at `jinn auth`.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
@@ -21,13 +28,24 @@ import { join } from 'node:path';
  */
 export function detectAuthContext(opts) {
     const { cwd } = opts;
-    // Resolve dockerenv — injected override takes precedence over filesystem.
+    const env = opts.env ?? process.env;
+    // 1. JINN_RUNTIME_MODE env var (CI / scripted operators).
+    const envMode = env['JINN_RUNTIME_MODE'];
+    if (envMode === 'bare' || envMode === 'docker-compose' || envMode === 'container') {
+        return envMode;
+    }
+    // 2. Explicit config (persisted by `jinn auth`).
+    if (opts.configuredMode) {
+        return opts.configuredMode;
+    }
+    // 3. Filesystem heuristic — last resort. Flawed inside the client/ checkout dir
+    // because the package's own docker-compose.yml names jinn-daemon. Prefer
+    // setting runtimeMode explicitly.
     const inContainer = opts.dockerenvExists !== undefined
         ? opts.dockerenvExists
         : existsSync('/.dockerenv');
     if (inContainer)
         return 'container';
-    // Resolve compose service — injected override or parse the file.
     const hasComposeService = opts.composeServiceExists !== undefined
         ? opts.composeServiceExists
         : _composeHasJinnDaemon(cwd);

package/dist/preflight/claude-auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude-auth.js","sourceRoot":"","sources":["../../src/preflight/claude-auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claude-auth.js","sourceRoot":"","sources":["../../src/preflight/claude-auth.ts"],"names":[],"mappings":"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"}

package/dist/preflight/rpc-network.d.ts

@@ -0,0 +1,44 @@
+import type { JinnConfig } from '../config.js';
+export type ExpectedRpcNetwork = 'mainnet' | 'testnet';
+export interface RpcNetworkPreflightOk {
+    ok: true;
+    network: ExpectedRpcNetwork;
+    expectedChainId: number;
+    actualChainId: number;
+    rpcHost: string;
+    /**
+     * True when the RPC reports an Anvil/Hardhat default chain id that does not
+     * match the configured network, but the endpoint is on loopback — we only
+     * allow this for local dev to avoid misreading a remote 313/1337 as healthy.
+     */
+    localDev?: true;
+}
+export interface RpcNetworkPreflightFail {
+    ok: false;
+    network: ExpectedRpcNetwork;
+    expectedChainId: number;
+    actualChainId?: number;
+    rpcHost: string;
+    reason: 'chain_mismatch' | 'unreachable';
+    message: string;
+}
+export type RpcNetworkPreflightResult = RpcNetworkPreflightOk | RpcNetworkPreflightFail;
+export declare function expectedChainIdForNetwork(network: ExpectedRpcNetwork): number;
+/**
+ * True when the RPC host is a loopback address. Remote endpoints that return
+ * Anvil/Hardhat chain ids are still treated as a mismatch.
+ */
+export declare function isLoopbackRpcUrl(rpcUrl: string): boolean;
+/**
+ * Used by tests: whether checkRpcNetwork would take the Anvil/Hardhat override path.
+ * Not used by production code beyond the equivalent inline check in {@link checkRpcNetwork}.
+ */
+export declare function evmLocalDevOverrideAcceptable(expectedChainId: number, actualChainId: number, rpcUrl: string): boolean;
+/**
+ * When {@link checkRpcNetwork} returns ok with `localDev: true`, log a single stderr line
+ * (also surfaced in `jinn doctor` detail) so run/bootstrap are not silent about the mismatch.
+ */
+export declare function logRpcLocalDevToStderr(r: RpcNetworkPreflightOk, write?: (m: string) => void): void;
+export declare function rpcHostForDisplay(rpcUrl: string): string;
+export declare function checkRpcNetwork(config: Pick<JinnConfig, 'network' | 'rpcUrl'>): Promise<RpcNetworkPreflightResult>;
+export declare function rpcNetworkFailureHint(result: RpcNetworkPreflightFail): string;

package/dist/preflight/rpc-network.js

@@ -0,0 +1,121 @@
+import { createPublicClient, http } from 'viem';
+import { base, baseSepolia } from 'viem/chains';
+export function expectedChainIdForNetwork(network) {
+    return network === 'testnet' ? 84532 : 8453;
+}
+/**
+ * Anvil / Hardhat default chain IDs. Fork workflows point `rpcUrl` at a local
+ * node without reconfiguring the chain; `eth_chainId` then reports these
+ * values instead of Base (8453 / 84532). We treat them as valid for preflight
+ * only for loopback RPCs so a misconfigured public URL cannot silently pass.
+ */
+const LOCAL_EVM_DEV_CHAIN_IDS = new Set([31337, 1337]);
+/**
+ * True when the RPC host is a loopback address. Remote endpoints that return
+ * Anvil/Hardhat chain ids are still treated as a mismatch.
+ */
+export function isLoopbackRpcUrl(rpcUrl) {
+    try {
+        const h = new URL(rpcUrl).hostname;
+        return h === '127.0.0.1' || h === 'localhost' || h === '::1' || h === '[::1]';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Used by tests: whether checkRpcNetwork would take the Anvil/Hardhat override path.
+ * Not used by production code beyond the equivalent inline check in {@link checkRpcNetwork}.
+ */
+export function evmLocalDevOverrideAcceptable(expectedChainId, actualChainId, rpcUrl) {
+    return (actualChainId !== expectedChainId &&
+        LOCAL_EVM_DEV_CHAIN_IDS.has(actualChainId) &&
+        isLoopbackRpcUrl(rpcUrl));
+}
+/**
+ * When {@link checkRpcNetwork} returns ok with `localDev: true`, log a single stderr line
+ * (also surfaced in `jinn doctor` detail) so run/bootstrap are not silent about the mismatch.
+ */
+export function logRpcLocalDevToStderr(r, write = (m) => {
+    process.stderr.write(m.endsWith('\n') ? m : `${m}\n`);
+}) {
+    if (!r.localDev)
+        return;
+    write(`[jinn] Local dev: ${r.rpcHost} has chainId ${r.actualChainId} (config expects Base ${r.network} id ` +
+        `${r.expectedChainId} from a live or forked-with-matching-id RPC). Continuing.\n`);
+}
+export function rpcHostForDisplay(rpcUrl) {
+    try {
+        const parsed = new URL(rpcUrl);
+        return parsed.host || parsed.hostname || '(unknown host)';
+    }
+    catch {
+        return '(invalid rpc url)';
+    }
+}
+function expectedChainForNetwork(network) {
+    return network === 'testnet' ? baseSepolia : base;
+}
+function errorMessage(error) {
+    if (error instanceof Error && error.message.trim())
+        return error.message;
+    return String(error);
+}
+export async function checkRpcNetwork(config) {
+    const expectedChainId = expectedChainIdForNetwork(config.network);
+    const rpcHost = rpcHostForDisplay(config.rpcUrl);
+    const client = createPublicClient({
+        chain: expectedChainForNetwork(config.network),
+        transport: http(config.rpcUrl),
+    });
+    let actualChainId;
+    try {
+        actualChainId = await client.getChainId();
+    }
+    catch (error) {
+        return {
+            ok: false,
+            network: config.network,
+            expectedChainId,
+            rpcHost,
+            reason: 'unreachable',
+            message: `RPC preflight failed for ${config.network} via ${rpcHost}: ${errorMessage(error)}`,
+        };
+    }
+    if (actualChainId !== expectedChainId) {
+        if (evmLocalDevOverrideAcceptable(expectedChainId, actualChainId, config.rpcUrl)) {
+            return {
+                ok: true,
+                network: config.network,
+                expectedChainId,
+                actualChainId,
+                rpcHost,
+                localDev: true,
+            };
+        }
+        return {
+            ok: false,
+            network: config.network,
+            expectedChainId,
+            actualChainId,
+            rpcHost,
+            reason: 'chain_mismatch',
+            message: `RPC chain mismatch for ${config.network}: expected chain ${expectedChainId}, ` +
+                `got ${actualChainId} from ${rpcHost}.`,
+        };
+    }
+    return {
+        ok: true,
+        network: config.network,
+        expectedChainId,
+        actualChainId,
+        rpcHost,
+    };
+}
+export function rpcNetworkFailureHint(result) {
+    if (result.network === 'testnet') {
+        return 'Set rpcUrl to a Base Sepolia endpoint such as https://sepolia.base.org, or set BASE_SEPOLIA_RPC_URL.';
+    }
+    return 'Set rpcUrl to a Base mainnet endpoint such as https://mainnet.base.org, or set BASE_RPC_URL.';
+}
+//# sourceMappingURL=rpc-network.js.map

package/dist/preflight/rpc-network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-network.js","sourceRoot":"","sources":["../../src/preflight/rpc-network.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAChD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA+BhD,MAAM,UAAU,yBAAyB,CAAC,OAA2B;IACnE,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;AAEvD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC;QACnC,OAAO,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,OAAO,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CAC3C,eAAuB,EACvB,aAAqB,EACrB,MAAc;IAEd,OAAO,CACL,aAAa,KAAK,eAAe;QACjC,uBAAuB,CAAC,GAAG,CAAC,aAAa,CAAC;QAC1C,gBAAgB,CAAC,MAAM,CAAC,CACzB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,CAAwB,EACxB,QAA6B,CAAC,CAAC,EAAE,EAAE;IACjC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACxD,CAAC;IAED,IAAI,CAAC,CAAC,CAAC,QAAQ;QAAE,OAAO;IACxB,KAAK,CACH,qBAAqB,CAAC,CAAC,OAAO,gBAAgB,CAAC,CAAC,aAAa,yBAAyB,CAAC,CAAC,OAAO,MAAM;QACnG,GAAG,CAAC,CAAC,eAAe,6DAA6D,CACpF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;QAC/B,OAAO,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,IAAI,gBAAgB,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,mBAAmB,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,SAAS,uBAAuB,CAAC,OAA2B;IAC1D,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IACzE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAA8C;IAE9C,MAAM,eAAe,GAAG,yBAAyB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClE,MAAM,OAAO,GAAG,iBAAiB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,kBAAkB,CAAC;QAChC,KAAK,EAAE,uBAAuB,CAAC,MAAM,CAAC,OAAO,CAAC;QAC9C,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;KAC/B,CAAC,CAAC;IAEH,IAAI,aAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,aAAa,GAAG,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,eAAe;YACf,OAAO;YACP,MAAM,EAAE,aAAa;YACrB,OAAO,EAAE,4BAA4B,MAAM,CAAC,OAAO,QAAQ,OAAO,KAAK,YAAY,CAAC,KAAK,CAAC,EAAE;SAC7F,CAAC;IACJ,CAAC;IAED,IAAI,aAAa,KAAK,eAAe,EAAE,CAAC;QACtC,IAAI,6BAA6B,CAAC,eAAe,EAAE,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YACjF,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,eAAe;gBACf,aAAa;gBACb,OAAO;gBACP,QAAQ,EAAE,IAAI;aACf,CAAC;QACJ,CAAC;QACD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,eAAe;YACf,aAAa;YACb,OAAO;YACP,MAAM,EAAE,gBAAgB;YACxB,OAAO,EACL,0BAA0B,MAAM,CAAC,OAAO,oBAAoB,eAAe,IAAI;gBAC/E,OAAO,aAAa,SAAS,OAAO,GAAG;SAC1C,CAAC;IACJ,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,eAAe;QACf,aAAa;QACb,OAAO;KACR,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAA+B;IACnE,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,sGAAsG,CAAC;IAChH,CAAC;IACD,OAAO,8FAA8F,CAAC;AACxG,CAAC"}

package/dist/restorer/engine/canonical-json.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Canonical JSON serialisation — sorted keys, no whitespace.
+ *
+ * Used for manifest signing: produce a deterministic byte string that two
+ * independent parties can reproduce from the same object graph.
+ *
+ * Rules:
+ * - Object keys are sorted lexicographically (UTF-16 code-unit order, same as
+ *   Array.prototype.sort() on strings — matches JSON.stringify key insertion
+ *   order when we control insertion).
+ * - Arrays preserve element order.
+ * - Numbers: JS default toString (no special formatting).
+ * - null, boolean, string: standard JSON encoding.
+ * - undefined values in objects are dropped (same as JSON.stringify).
+ * - NaN and Infinity are not valid JSON; this function will produce "null" for
+ *   those values, matching JSON.stringify behaviour.
+ */
+export declare function canonicalJson(value: unknown): string;

package/dist/restorer/engine/canonical-json.js

@@ -0,0 +1,59 @@
+/**
+ * Canonical JSON serialisation — sorted keys, no whitespace.
+ *
+ * Used for manifest signing: produce a deterministic byte string that two
+ * independent parties can reproduce from the same object graph.
+ *
+ * Rules:
+ * - Object keys are sorted lexicographically (UTF-16 code-unit order, same as
+ *   Array.prototype.sort() on strings — matches JSON.stringify key insertion
+ *   order when we control insertion).
+ * - Arrays preserve element order.
+ * - Numbers: JS default toString (no special formatting).
+ * - null, boolean, string: standard JSON encoding.
+ * - undefined values in objects are dropped (same as JSON.stringify).
+ * - NaN and Infinity are not valid JSON; this function will produce "null" for
+ *   those values, matching JSON.stringify behaviour.
+ */
+export function canonicalJson(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'null';
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number') {
+        // NaN / Infinity → null, matching JSON.stringify
+        if (!isFinite(value))
+            return 'null';
+        return String(value);
+    }
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        const items = value.map((v) => canonicalJson(v)).join(',');
+        return `[${items}]`;
+    }
+    if (typeof value === 'object') {
+        const obj = value;
+        const pairs = Object.keys(obj)
+            .sort()
+            .flatMap((key) => {
+            const v = obj[key];
+            if (v === undefined)
+                return []; // drop undefined (matches JSON.stringify)
+            return [`${JSON.stringify(key)}:${canonicalJson(v)}`];
+        });
+        return `{${pairs.join(',')}}`;
+    }
+    // Bigint: emit raw decimal digits WITHOUT quotes, matching RFC 8785 and other
+    // canonical-JSON libs. JSON.stringify would throw; converting through String()
+    // would produce a quoted "12345" instead of the unquoted integer 12345.
+    // We do NOT convert through Number() because bigints can exceed JS number precision.
+    if (typeof value === 'bigint')
+        return value.toString();
+    // Fallback: other exotic types — JSON.stringify would throw;
+    // we convert to string to avoid hard failures.
+    return JSON.stringify(String(value));
+}
+//# sourceMappingURL=canonical-json.js.map

package/dist/restorer/engine/canonical-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.js","sourceRoot":"","sources":["../../../src/restorer/engine/canonical-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACvC,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAChE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,iDAAiD;QACjD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,MAAM,CAAC;QACpC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3D,OAAO,IAAI,KAAK,GAAG,CAAC;IACtB,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,KAAgC,CAAC;QAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;aAC3B,IAAI,EAAE;aACN,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;YACf,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACnB,IAAI,CAAC,KAAK,SAAS;gBAAE,OAAO,EAAE,CAAC,CAAC,0CAA0C;YAC1E,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACxD,CAAC,CAAC,CAAC;QACL,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAChC,CAAC;IACD,8EAA8E;IAC9E,+EAA+E;IAC/E,wEAAwE;IACxE,qFAAqF;IACrF,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;IACvD,6DAA6D;IAC7D,+CAA+C;IAC/C,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACvC,CAAC"}

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

@@ -0,0 +1,69 @@
+/**
+ * Two-layer claim orchestration for the restorer engine.
+ *
+ * §6.1, §9.1, §9.2 of spec/2026-04-17-portfolio-v0-design.md
+ *
+ * Layer 1: ClaimRegistry claim — Jinn's work-coordination contract.
+ * Layer 2: Marketplace priority claim — calls MechAdapter.claimRequest() to
+ *   register the priority-mech exclusivity window (300 s responseTimeout).
+ *
+ * The ClaimRegistry claimTTL is owner-configured per-deployment and is not
+ * passed by the client.
+ *
+ * Recovery:
+ *   On resume, ClaimRegistryClient.weAlreadyClaimed() is checked before any
+ *   on-chain write.  If we already hold the claim, the ClaimRegistry step is
+ *   skipped entirely.  The marketplace claim is re-attempted because it is
+ *   stateless from the engine's perspective (MechAdapter is idempotent there).
+ *
+ * Failure modes:
+ *   - ClaimRegistry claim fails → throw, no marketplace call, engine marks FAILED.
+ *   - Marketplace claim fails → release ClaimRegistry claim, throw.
+ */
+import type { ClaimRegistryClient } from '../../adapters/claim-registry/client.js';
+/**
+ * Minimal interface for the marketplace adapter's claim path.
+ * The full MechAdapter satisfies this; tests can inject a stub.
+ */
+export interface MarketplaceClaimer {
+    claimRequest(requestId: string): Promise<void>;
+}
+/**
+ * Parameters describing a single intent's timing window.
+ * Extracted from PersistedIntent for testability (no DB dependency).
+ */
+export interface ClaimWindow {
+    requestId: string;
+    /** Window start timestamp in ms (epoch). Used for graceful release decision. */
+    windowStartTs: number;
+}
+/** Result of a successful two-layer claim. */
+export interface ClaimResult {
+    /** True if the ClaimRegistry claim was freshly placed (false = pre-existing). */
+    registryClaimWasFresh: boolean;
+}
+/**
+ * Execute the two-layer claim for a single intent.
+ *
+ * // Claim ordering: ClaimRegistry FIRST (cheap coordination lock), marketplace SECOND.
+ * // Spec §6.1 lists them in opposite order but doesn't enforce sequencing — registry-first
+ * // is preferred because: (a) ClaimRegistry revert is fast and signals "another restorer
+ * // is on it" cleanly; (b) marketplace claim is more expensive (Safe tx + actual gas);
+ * // (c) we release ClaimRegistry on marketplace failure to avoid leaking a stale claim.
+ *
+ * @param claimWindow - Timing data for the intent (requestId, windowStartTs).
+ * @param registryClient - ClaimRegistryClient for the deployed ClaimRegistry contract.
+ * @param marketplaceClaimer - Adapter whose claimRequest() performs the marketplace claim.
+ * @returns ClaimResult on success.
+ * @throws If either layer cannot be claimed (after graceful cleanup).
+ */
+export declare function executeTwoLayerClaim(claimWindow: ClaimWindow, registryClient: ClaimRegistryClient, marketplaceClaimer: MarketplaceClaimer): Promise<ClaimResult>;
+/**
+ * Release the ClaimRegistry claim for an intent that was CLAIMED but whose
+ * work window has not yet started (windowStartTs not reached).
+ *
+ * Used during graceful engine shutdown. No-op if we don't hold the claim.
+ *
+ * @returns true if the claim was released, false if there was nothing to release.
+ */
+export declare function releaseClaimedNotStarted(claimWindow: ClaimWindow, registryClient: ClaimRegistryClient): Promise<boolean>;

package/dist/restorer/engine/claim.js

@@ -0,0 +1,104 @@
+/**
+ * Two-layer claim orchestration for the restorer engine.
+ *
+ * §6.1, §9.1, §9.2 of spec/2026-04-17-portfolio-v0-design.md
+ *
+ * Layer 1: ClaimRegistry claim — Jinn's work-coordination contract.
+ * Layer 2: Marketplace priority claim — calls MechAdapter.claimRequest() to
+ *   register the priority-mech exclusivity window (300 s responseTimeout).
+ *
+ * The ClaimRegistry claimTTL is owner-configured per-deployment and is not
+ * passed by the client.
+ *
+ * Recovery:
+ *   On resume, ClaimRegistryClient.weAlreadyClaimed() is checked before any
+ *   on-chain write.  If we already hold the claim, the ClaimRegistry step is
+ *   skipped entirely.  The marketplace claim is re-attempted because it is
+ *   stateless from the engine's perspective (MechAdapter is idempotent there).
+ *
+ * Failure modes:
+ *   - ClaimRegistry claim fails → throw, no marketplace call, engine marks FAILED.
+ *   - Marketplace claim fails → release ClaimRegistry claim, throw.
+ */
+// ── Two-layer claim ───────────────────────────────────────────────────────────
+/**
+ * Execute the two-layer claim for a single intent.
+ *
+ * // Claim ordering: ClaimRegistry FIRST (cheap coordination lock), marketplace SECOND.
+ * // Spec §6.1 lists them in opposite order but doesn't enforce sequencing — registry-first
+ * // is preferred because: (a) ClaimRegistry revert is fast and signals "another restorer
+ * // is on it" cleanly; (b) marketplace claim is more expensive (Safe tx + actual gas);
+ * // (c) we release ClaimRegistry on marketplace failure to avoid leaking a stale claim.
+ *
+ * @param claimWindow - Timing data for the intent (requestId, windowStartTs).
+ * @param registryClient - ClaimRegistryClient for the deployed ClaimRegistry contract.
+ * @param marketplaceClaimer - Adapter whose claimRequest() performs the marketplace claim.
+ * @returns ClaimResult on success.
+ * @throws If either layer cannot be claimed (after graceful cleanup).
+ */
+export async function executeTwoLayerClaim(claimWindow, registryClient, marketplaceClaimer) {
+    const requestIdHex = claimWindow.requestId;
+    // ── Layer 1: ClaimRegistry ────────────────────────────────────────────────
+    // Idempotency check: if we already hold the claim, skip the on-chain write.
+    const alreadyClaimed = await registryClient.weAlreadyClaimed(requestIdHex);
+    let registryClaimWasFresh = false;
+    if (!alreadyClaimed) {
+        const result = await registryClient.claimJob(requestIdHex);
+        if (!result.claimed) {
+            throw new Error(`[claim-orchestration] ClaimRegistry claim failed for ${claimWindow.requestId} — another operator may hold the claim`);
+        }
+        registryClaimWasFresh = true;
+    }
+    else {
+        console.log(`[claim-orchestration] ClaimRegistry: pre-existing claim found for ${claimWindow.requestId}, skipping re-claim`);
+    }
+    // ── Layer 2: Marketplace ──────────────────────────────────────────────────
+    try {
+        await marketplaceClaimer.claimRequest(claimWindow.requestId);
+    }
+    catch (marketplaceErr) {
+        // Marketplace claim failed — release the ClaimRegistry claim we just placed
+        // (only if we placed it fresh; pre-existing claims are not ours to release here)
+        // TODO(v0 trade-off): on the resume path (weAlreadyClaimed = true, registryClaimWasFresh = false)
+        // we do NOT release the ClaimRegistry claim here.  Releasing on a transient marketplace failure
+        // would forfeit our coordination lock and let a competing restorer take it.  The downside is that
+        // on a *persistent* failure the claim sits locked until TTL expiry (owner-configured per-deployment).
+        // Distinguishing transient vs. permanent failures is non-trivial; for v0 we accept the TTL wait.
+        // Future: inspect the marketplace error type and release only on permanent failures.
+        if (registryClaimWasFresh) {
+            try {
+                await registryClient.releaseClaim(requestIdHex);
+                console.log(`[claim-orchestration] released ClaimRegistry claim for ${claimWindow.requestId} after marketplace failure`);
+            }
+            catch (releaseErr) {
+                const releaseMsg = releaseErr instanceof Error ? releaseErr.message : String(releaseErr);
+                console.error(`[claim-orchestration] failed to release ClaimRegistry claim for ${claimWindow.requestId} after marketplace failure: ${releaseMsg}`);
+            }
+        }
+        throw marketplaceErr;
+    }
+    return { registryClaimWasFresh };
+}
+// ── Graceful release ──────────────────────────────────────────────────────────
+/**
+ * Release the ClaimRegistry claim for an intent that was CLAIMED but whose
+ * work window has not yet started (windowStartTs not reached).
+ *
+ * Used during graceful engine shutdown. No-op if we don't hold the claim.
+ *
+ * @returns true if the claim was released, false if there was nothing to release.
+ */
+export async function releaseClaimedNotStarted(claimWindow, registryClient) {
+    const requestIdHex = claimWindow.requestId;
+    // Only release if the work window hasn't started yet
+    if (Date.now() >= claimWindow.windowStartTs) {
+        console.log(`[claim-orchestration] NOT releasing claim for ${claimWindow.requestId} — window already started`);
+        return false;
+    }
+    const released = await registryClient.releaseClaim(requestIdHex);
+    if (released) {
+        console.log(`[claim-orchestration] released ClaimRegistry claim for ${claimWindow.requestId} (graceful shutdown, before window start)`);
+    }
+    return released;
+}
+//# sourceMappingURL=claim.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"claim.js","sourceRoot":"","sources":["../../../src/restorer/engine/claim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA+BH,iFAAiF;AAEjF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,WAAwB,EACxB,cAAmC,EACnC,kBAAsC;IAEtC,MAAM,YAAY,GAAG,WAAW,CAAC,SAAgB,CAAC;IAElD,6EAA6E;IAE7E,4EAA4E;IAC5E,MAAM,cAAc,GAAG,MAAM,cAAc,CAAC,gBAAgB,CAAC,YAAY,CAAC,CAAC;IAC3E,IAAI,qBAAqB,GAAG,KAAK,CAAC;IAElC,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;QAC3D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,wDAAwD,WAAW,CAAC,SAAS,wCAAwC,CACtH,CAAC;QACJ,CAAC;QACD,qBAAqB,GAAG,IAAI,CAAC;IAC/B,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CACT,qEAAqE,WAAW,CAAC,SAAS,qBAAqB,CAChH,CAAC;IACJ,CAAC;IAED,6EAA6E;IAE7E,IAAI,CAAC;QACH,MAAM,kBAAkB,CAAC,YAAY,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IAC/D,CAAC;IAAC,OAAO,cAAc,EAAE,CAAC;QACxB,4EAA4E;QAC5E,iFAAiF;QACjF,kGAAkG;QAClG,gGAAgG;QAChG,kGAAkG;QAClG,sGAAsG;QACtG,iGAAiG;QACjG,qFAAqF;QACrF,IAAI,qBAAqB,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,MAAM,cAAc,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;gBAChD,OAAO,CAAC,GAAG,CACT,0DAA0D,WAAW,CAAC,SAAS,4BAA4B,CAC5G,CAAC;YACJ,CAAC;YAAC,OAAO,UAAU,EAAE,CAAC;gBACpB,MAAM,UAAU,GAAG,UAAU,YAAY,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;gBACzF,OAAO,CAAC,KAAK,CACX,mEAAmE,WAAW,CAAC,SAAS,+BAA+B,UAAU,EAAE,CACpI,CAAC;YACJ,CAAC;QACH,CAAC;QACD,MAAM,cAAc,CAAC;IACvB,CAAC;IAED,OAAO,EAAE,qBAAqB,EAAE,CAAC;AACnC,CAAC;AAED,iFAAiF;AAEjF;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,WAAwB,EACxB,cAAmC;IAEnC,MAAM,YAAY,GAAG,WAAW,CAAC,SAAgB,CAAC;IAElD,qDAAqD;IACrD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,WAAW,CAAC,aAAa,EAAE,CAAC;QAC5C,OAAO,CAAC,GAAG,CACT,iDAAiD,WAAW,CAAC,SAAS,2BAA2B,CAClG,CAAC;QACF,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;IACjE,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,CAAC,GAAG,CACT,0DAA0D,WAAW,CAAC,SAAS,2CAA2C,CAC3H,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}