@pushchain/core 6.0.27-alpha.3 → 6.0.27-alpha.5

package/src/lib/job/job.js

@@ -0,0 +1,382 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobNamespaceImpl = void 0;
+const viem_1 = require("viem");
+const AgenticCommerce_1 = require("../market/contracts/AgenticCommerce");
+const RulesBindingHook_1 = require("../market/contracts/RulesBindingHook");
+const UniversalMarketplace_1 = require("../market/contracts/UniversalMarketplace");
+const kernel_wire_1 = require("../market/kernel-wire");
+const runtime_1 = require("../market/runtime");
+const errors_1 = require("../market/errors");
+const deployments_1 = require("../agentic/deployments");
+const rules_1 = require("../agentic/reads/rules");
+const snapshot_1 = require("../agentic/reads/snapshot");
+const codec_1 = require("../job-spec/codec");
+const watch_1 = require("./watch");
+const STATES = [
+    'Open',
+    'Funded',
+    'Submitted',
+    'Completed',
+    'Rejected',
+    'Expired',
+];
+function validId(jobId) {
+    if (typeof jobId !== 'bigint' || jobId < BigInt(1))
+        throw new errors_1.JobError('INVALID_JOB_ID', 'Job IDs are positive bigint values.');
+}
+function amount(n) {
+    if (typeof n !== 'bigint' || n < BigInt(0) || n >= BigInt(1) << BigInt(256))
+        throw new errors_1.JobError('INVALID_AMOUNT', 'The amount must fit uint256.');
+}
+class JobNamespaceImpl {
+    rt;
+    constructor(rt) {
+        this.rt = rt;
+    }
+    async raw(jobId, s) {
+        validId(jobId);
+        const j = await s.read((0, runtime_1.deployment)(this.rt).kernel, kernel_wire_1.KERNEL_READ_ABI, 'getJob', [jobId]);
+        if ((0, viem_1.getAddress)(j.client) === viem_1.zeroAddress || !STATES[j.status])
+            throw new errors_1.JobError('JOB_NOT_FOUND', 'This job does not exist.');
+        return j;
+    }
+    async jobAt(jobId, s) {
+        const d = (0, runtime_1.deployment)(this.rt);
+        const j = await this.raw(jobId, s);
+        const paymentToken = await s.read(d.kernel, AgenticCommerce_1.JOB_KERNEL_ABI, 'paymentToken');
+        let spec;
+        let decodeError;
+        if (j.description !== '0x') {
+            try {
+                spec = (0, codec_1.decodeJobSpec)(j.description, { format: 'spec' });
+            }
+            catch (e) {
+                decodeError = e.message;
+            }
+        }
+        const rulesId = (0, viem_1.getAddress)(j.hook) === (0, viem_1.getAddress)(d.hook)
+            ? await s.read(d.hook, RulesBindingHook_1.RULES_HOOK_ABI, 'rulesOfJob', [jobId])
+            : undefined;
+        let deliverable;
+        if (j.status >= 2) {
+            const logs = await (0, snapshot_1.scanLogs)(this.rt.agw.reader, {
+                address: d.kernel,
+                event: (0, viem_1.getAbiItem)({ abi: AgenticCommerce_1.JOB_KERNEL_ABI, name: 'JobSubmitted' }),
+                args: { jobId },
+            }, this.rt.jobBlocks?.get(jobId) ?? d.startBlock, s.blockNumber);
+            if (logs.length > 1)
+                throw new errors_1.JobError('INCONSISTENT_READ', 'The job has multiple submission events.');
+            if (logs.length === 1) {
+                const event = (0, viem_1.decodeEventLog)({
+                    abi: AgenticCommerce_1.JOB_KERNEL_ABI,
+                    eventName: 'JobSubmitted',
+                    data: logs[0].data,
+                    topics: logs[0].topics,
+                });
+                deliverable = event.args.deliverable;
+            }
+        }
+        return {
+            ...j,
+            jobId,
+            status: STATES[j.status],
+            paymentToken,
+            ...(deliverable ? { deliverable } : {}),
+            ...(rulesId && rulesId !== viem_1.zeroHash ? { rulesId } : {}),
+            ...(spec ? { jobSpec: { spec, bytes: j.description } } : {}),
+            ...(decodeError ? { jobSpecDecodeError: decodeError } : {}),
+            evaluation: {
+                available: false,
+                reason: (0, viem_1.getAddress)(j.evaluator) === (0, viem_1.getAddress)(d.evaluator)
+                    ? 'MANUAL_EVALUATOR'
+                    : 'UNVERIFIED_EVALUATOR',
+            },
+        };
+    }
+    async status(jobId) {
+        return this.jobAt(jobId, await (0, runtime_1.snapshot)(this.rt));
+    }
+    async list(options = {}) {
+        const s = await (0, runtime_1.snapshot)(this.rt);
+        const count = await s.read((0, runtime_1.deployment)(this.rt).kernel, AgenticCommerce_1.JOB_KERNEL_ABI, 'jobCounter');
+        const from = options.fromJobId ?? BigInt(1);
+        validId(from);
+        const jobs = [];
+        for (let i = from; i <= count; i += BigInt(8)) {
+            const rows = await Promise.all(Array.from({
+                length: Number(count - i + BigInt(1) > BigInt(8)
+                    ? BigInt(8)
+                    : count - i + BigInt(1)),
+            }, (_, n) => this.jobAt(i + BigInt(n), s)));
+            jobs.push(...rows.filter((j) => (!options.client ||
+                (0, viem_1.getAddress)(options.client) === (0, viem_1.getAddress)(j.client)) &&
+                (!options.provider ||
+                    (0, viem_1.getAddress)(options.provider) === (0, viem_1.getAddress)(j.provider)) &&
+                (!options.status || options.status === j.status)));
+        }
+        return { jobs };
+    }
+    async create(options) {
+        options = { ...options };
+        const d = (0, runtime_1.deployment)(this.rt);
+        const s = await (0, runtime_1.snapshot)(this.rt);
+        const token = await s.read(d.kernel, AgenticCommerce_1.JOB_KERNEL_ABI, 'paymentToken');
+        if ((0, viem_1.getAddress)(options.paymentToken) !== (0, viem_1.getAddress)(token))
+            throw new errors_1.JobError('TOKEN_MISMATCH', 'The job token must equal this kernel’s payment token.');
+        if (options.jobSpec) {
+            const spec = (0, codec_1.decodeJobSpec)(options.jobSpec, {
+                format: 'spec',
+            });
+            if (spec.allowedMutability !== 'NONE')
+                (0, errors_1.unavailable)('Mutable job criteria');
+            if (spec.origin !== viem_1.zeroHash)
+                throw new errors_1.JobError('INVALID_JOB_SPEC', 'A plain job must have a zero marketplace origin.');
+            if (spec.failFinalAt >= options.expiredAt)
+                throw new errors_1.JobError('INVALID_JOB_SPEC', 'The failure deadline must precede expiry.');
+        }
+        const min = await s.read(d.kernel, AgenticCommerce_1.JOB_KERNEL_ABI, 'MIN_EXPIRY_WINDOW');
+        if (!Number.isSafeInteger(options.expiredAt) ||
+            options.expiredAt <= s.timestamp + Number(min) ||
+            options.expiredAt >= 2 ** 48)
+            throw new errors_1.JobError('EXPIRY_TOO_SHORT', 'Choose a future expiry beyond the kernel minimum window.');
+        const call = {
+            target: d.kernel,
+            value: BigInt(0),
+            data: (0, kernel_wire_1.encodeCreateJob)((0, viem_1.getAddress)(options.provider), (0, viem_1.getAddress)(options.evaluator), options.expiredAt, options, (0, viem_1.getAddress)(options.hook)),
+        };
+        const wallet = this.rt.wallet();
+        const tx = wallet
+            ? await (0, runtime_1.ownerBatch)(this.rt, wallet, [call], options.progressHook)
+            : await (0, runtime_1.write)(this.rt, call, options.progressHook, 'JOB', true);
+        const e = await (0, runtime_1.eventArgs)(this.rt, tx, d.kernel, AgenticCommerce_1.JOB_KERNEL_ABI, 'JobCreated');
+        if ((0, viem_1.getAddress)(e['client']) !== (0, viem_1.getAddress)(this.rt.account()))
+            throw new errors_1.JobError('RECEIPT_MISMATCH', 'The created job has a different client.', { txHash: tx.hash });
+        return { jobId: e['jobId'], tx };
+    }
+    provider(j) {
+        if ((0, viem_1.getAddress)(j.provider) !== (0, viem_1.getAddress)(this.rt.agw.signerPushAccount()))
+            throw new errors_1.JobError('NOT_PROVIDER', 'Connect this job’s provider.');
+    }
+    open(j, now) {
+        if (j.status !== 0 || j.expiredAt <= now)
+            throw new errors_1.JobError('WRONG_STATUS', 'The job must be Open and unexpired.');
+    }
+    async setBudget(jobId, budget, options = {}) {
+        if (options.jobSpec !== undefined)
+            (0, errors_1.unavailable)('Replacement JobSpec proposals');
+        amount(budget);
+        const s = await (0, runtime_1.snapshot)(this.rt);
+        const j = await this.raw(jobId, s);
+        this.provider(j);
+        this.open(j, s.timestamp);
+        const d = (0, runtime_1.deployment)(this.rt);
+        return (0, runtime_1.write)(this.rt, {
+            target: d.kernel,
+            value: BigInt(0),
+            data: (0, viem_1.encodeFunctionData)({
+                abi: AgenticCommerce_1.JOB_KERNEL_ABI,
+                functionName: 'setBudget',
+                args: [jobId, budget, '0x'],
+            }),
+        }, options.progressHook, 'JOB', true);
+    }
+    async fund(jobId, options = {}) {
+        options = { ...options };
+        const rt = this.rt;
+        const d = (0, runtime_1.deployment)(rt);
+        const s = await (0, runtime_1.snapshot)(rt);
+        const j = await this.raw(jobId, s);
+        this.open(j, s.timestamp);
+        const gen = (0, deployments_1.currentGeneration)(rt.agw.network);
+        const isWallet = await s.read(gen.addresses.factory, gen.contracts.abis.factory, 'isWallet', [j.client]);
+        if (isWallet) {
+            const owner = await s.read(j.client, gen.contracts.abis.wallet, 'owner');
+            if ((0, viem_1.getAddress)(owner) !== (0, viem_1.getAddress)(rt.agw.signerPushAccount()))
+                throw new errors_1.JobError('NOT_CLIENT', 'Connect the job wallet’s owner.');
+        }
+        else if ((0, viem_1.getAddress)(j.client) !== (0, viem_1.getAddress)(rt.agw.signerPushAccount()))
+            throw new errors_1.JobError('NOT_CLIENT', 'Connect this job’s client.');
+        let expected = options.expectedBudget;
+        const cardId = await s.read(d.marketplace, UniversalMarketplace_1.MARKETPLACE_ABI, 'cardOfJob', [jobId]);
+        let rulesId = options.rulesId;
+        if (cardId) {
+            const [version, view, recordedRules] = await Promise.all([
+                s.read(d.marketplace, UniversalMarketplace_1.MARKETPLACE_ABI, 'cardVersionOfJob', [
+                    jobId,
+                ]),
+                s.read(d.marketplace, UniversalMarketplace_1.MARKETPLACE_ABI, 'getAgentCard', [cardId]),
+                s.read(d.marketplace, UniversalMarketplace_1.MARKETPLACE_ABI, 'rulesOfJob', [jobId]),
+            ]);
+            if (rulesId && rulesId !== recordedRules)
+                throw new errors_1.JobError('RULES_MISMATCH', 'Use the permission recorded when this job was opened.');
+            rulesId = recordedRules;
+            if (expected === undefined && version === view.version)
+                expected = view.card.providerFee;
+        }
+        if (expected === undefined)
+            throw new errors_1.JobError('EXPECTED_BUDGET_REQUIRED', 'Pass the exact budget you reviewed; this SDK does not silently accept the latest provider quote.');
+        amount(expected);
+        if (expected !== j.budget)
+            throw new errors_1.JobError('BUDGET_MISMATCH', 'The provider’s current price differs from the budget you reviewed.', { expectedBudget: expected, currentBudget: j.budget });
+        let optParams = '0x';
+        if ((0, viem_1.getAddress)(j.hook) === (0, viem_1.getAddress)(d.hook)) {
+            if (!isWallet || !rulesId || !/^0x[\da-f]{64}$/i.test(rulesId))
+                throw new errors_1.JobError('RULES_REQUIRED', 'This rules hook needs an AGW client and its rulesId.');
+            const record = await (0, rules_1.getRule)(new snapshot_1.Snapshot(rt.agw.reader, s.blockNumber), gen, j.client, rulesId, rt.agw.pushChainNamespace);
+            if ((0, viem_1.getAddress)(record.agent) !== (0, viem_1.getAddress)(j.provider) ||
+                record.validUntil < j.expiredAt)
+                throw new errors_1.JobError('RULES_MISMATCH', 'The live rule must authorize this provider through the job expiry.');
+            if (await s.read(d.hook, RulesBindingHook_1.RULES_HOOK_ABI, 'activeJobOf', [j.client]))
+                throw new errors_1.JobError('WALLET_HAS_ACTIVE_JOB', 'This wallet already has a funded job under the rules hook.');
+            optParams = (0, viem_1.encodeAbiParameters)([{ type: 'bytes32' }], [rulesId]);
+        }
+        else if (rulesId)
+            throw new errors_1.JobError('HOOK_MISMATCH', 'A rulesId payload is supported only for the verified rules hook.');
+        const token = await s.read(d.kernel, AgenticCommerce_1.JOB_KERNEL_ABI, 'paymentToken');
+        const calls = [];
+        if (expected > BigInt(0)) {
+            const [balance, allowance] = await Promise.all([
+                s.read(token, viem_1.erc20Abi, 'balanceOf', [j.client]),
+                s.read(token, viem_1.erc20Abi, 'allowance', [j.client, d.kernel]),
+            ]);
+            if (balance < expected)
+                throw new errors_1.JobError('INSUFFICIENT_FUNDS', 'The job client lacks the payment tokens required for escrow.');
+            if (allowance < expected) {
+                if (allowance > BigInt(0))
+                    calls.push({
+                        target: token,
+                        value: BigInt(0),
+                        data: (0, viem_1.encodeFunctionData)({
+                            abi: viem_1.erc20Abi,
+                            functionName: 'approve',
+                            args: [d.kernel, BigInt(0)],
+                        }),
+                    });
+                calls.push({
+                    target: token,
+                    value: BigInt(0),
+                    data: (0, viem_1.encodeFunctionData)({
+                        abi: viem_1.erc20Abi,
+                        functionName: 'approve',
+                        args: [d.kernel, expected],
+                    }),
+                });
+            }
+        }
+        calls.push({
+            target: d.kernel,
+            value: BigInt(0),
+            data: (0, viem_1.encodeFunctionData)({
+                abi: AgenticCommerce_1.JOB_KERNEL_ABI,
+                functionName: 'fund',
+                args: [jobId, expected, optParams],
+            }),
+        });
+        if (isWallet)
+            return (0, runtime_1.ownerBatch)(rt, j.client, calls, options.progressHook);
+        if (calls.length === 1)
+            return (0, runtime_1.write)(rt, calls[0], options.progressHook, 'JOB', true);
+        if (rt.agw.isReadOnly)
+            throw new errors_1.JobError('READ_ONLY', 'Connect a signer to fund escrow.');
+        // No sequential fallback: allowance and acceptance must belong to one atomic batch.
+        return rt.agw.executeAtomicBatch({
+            to: d.kernel,
+            value: BigInt(0),
+            data: calls.map((c) => ({
+                to: c.target,
+                value: c.value,
+                data: c.data,
+            })),
+        }, { progressHook: options.progressHook });
+    }
+    async submit(jobId, options) {
+        options = { ...options };
+        const s = await (0, runtime_1.snapshot)(this.rt);
+        const j = await this.raw(jobId, s);
+        this.provider(j);
+        if (j.status !== 1 || j.expiredAt <= s.timestamp)
+            throw new errors_1.JobError('WRONG_STATUS', 'Only an unexpired Funded job can be submitted.');
+        const deliverable = /^0x[\da-f]{64}$/i.test(options.deliverable)
+            ? options.deliverable
+            : (0, viem_1.keccak256)((0, viem_1.stringToHex)(options.deliverable));
+        return (0, runtime_1.write)(this.rt, {
+            target: (0, runtime_1.deployment)(this.rt).kernel,
+            value: BigInt(0),
+            data: (0, viem_1.encodeFunctionData)({
+                abi: AgenticCommerce_1.JOB_KERNEL_ABI,
+                functionName: 'submit',
+                args: [jobId, deliverable, '0x'],
+            }),
+        }, options.progressHook, 'JOB', true);
+    }
+    async cancel(jobId, options = {}) {
+        const rt = this.rt;
+        const d = (0, runtime_1.deployment)(rt);
+        const s = await (0, runtime_1.snapshot)(rt);
+        const j = await this.raw(jobId, s);
+        if (j.status !== 0)
+            throw new errors_1.JobError('WRONG_STATUS', 'Only an Open job can be cancelled by its client.');
+        const gen = (0, deployments_1.currentGeneration)(rt.agw.network);
+        const isWallet = await s.read(gen.addresses.factory, gen.contracts.abis.factory, 'isWallet', [j.client]);
+        const calls = [
+            {
+                target: d.kernel,
+                value: BigInt(0),
+                data: (0, viem_1.encodeFunctionData)({
+                    abi: AgenticCommerce_1.JOB_KERNEL_ABI,
+                    functionName: 'reject',
+                    args: [jobId, viem_1.zeroHash, '0x'],
+                }),
+            },
+        ];
+        if (isWallet) {
+            const wallet = await s.read(d.marketplace, UniversalMarketplace_1.MARKETPLACE_ABI, 'agwOfJob', [jobId]);
+            const rulesId = await s.read(d.marketplace, UniversalMarketplace_1.MARKETPLACE_ABI, 'rulesOfJob', [jobId]);
+            if ((0, viem_1.getAddress)(wallet) === (0, viem_1.getAddress)(j.client) &&
+                rulesId !== viem_1.zeroHash &&
+                (await s.read(gen.addresses.sessionEngine, gen.contracts.abis.engine, 'isPermissionEnabled', [rulesId, j.client])))
+                calls.push({
+                    target: j.client,
+                    value: BigInt(0),
+                    data: gen.contracts.encodeRevokeRules(rulesId),
+                });
+            return (0, runtime_1.ownerBatch)(rt, j.client, calls, options.progressHook);
+        }
+        if ((0, viem_1.getAddress)(j.client) !== (0, viem_1.getAddress)(rt.agw.signerPushAccount()))
+            throw new errors_1.JobError('NOT_CLIENT', 'Only the client can use this cancellation method.');
+        return (0, runtime_1.write)(rt, calls[0], options.progressHook, 'JOB', true);
+    }
+    async claimRefund(jobId, options = {}) {
+        const s = await (0, runtime_1.snapshot)(this.rt);
+        const j = await this.raw(jobId, s);
+        const d = (0, runtime_1.deployment)(this.rt);
+        if (![0, 1, 2].includes(j.status))
+            throw new errors_1.JobError('WRONG_STATUS', 'This job is already terminal.');
+        const grace = j.status === 2
+            ? Number(await s.read(d.kernel, AgenticCommerce_1.JOB_KERNEL_ABI, 'EVALUATOR_GRACE_PERIOD'))
+            : 0;
+        if (s.timestamp < j.expiredAt + grace)
+            throw new errors_1.JobError('REFUND_NOT_READY', 'The expiry or evaluator grace window has not elapsed.');
+        return (0, runtime_1.write)(this.rt, {
+            target: d.kernel,
+            value: BigInt(0),
+            data: (0, viem_1.encodeFunctionData)({
+                abi: AgenticCommerce_1.JOB_KERNEL_ABI,
+                functionName: 'claimRefund',
+                args: [jobId],
+            }),
+        }, options.progressHook, 'JOB', true);
+    }
+    async verify(_jobId, _options) {
+        void _jobId;
+        void _options;
+        return (0, errors_1.unavailable)('Automatic job verification; the configured evaluator is manual');
+    }
+    watch(jobId, callback, options = {}) {
+        validId(jobId);
+        return (0, watch_1.watchJob)(this.rt, jobId, callback, { ...options });
+    }
+}
+exports.JobNamespaceImpl = JobNamespaceImpl;
+//# sourceMappingURL=job.js.map

package/src/lib/job/types.d.ts

@@ -0,0 +1,94 @@
+import type { Address, Hex } from 'viem';
+import type { UniversalTxResponse } from '../orchestrator/orchestrator.types';
+import type { JobSpec } from '../job-spec/types';
+import type { StackProgressHook } from '../market/runtime';
+export type JobStatus = 'Open' | 'Funded' | 'Submitted' | 'Completed' | 'Rejected' | 'Expired';
+export interface CreateJobOptions {
+    provider: Address;
+    evaluator: Address;
+    hook: Address;
+    expiredAt: number;
+    paymentToken: Address;
+    jobSpec?: Hex;
+    description?: string;
+    progressHook?: StackProgressHook;
+}
+export interface Job {
+    jobId: bigint;
+    client: Address;
+    provider: Address;
+    evaluator: Address;
+    hook: Address;
+    status: JobStatus;
+    expiredAt: number;
+    budget: bigint;
+    paymentToken: Address;
+    /** Raw Solidity string bytes, which may contain a binary JobSpec rather than UTF-8. */
+    description: Hex;
+    deliverable?: Hex;
+    rulesId?: Hex;
+    jobSpec?: {
+        spec: JobSpec;
+        bytes: Hex;
+        /** Unavailable without a compatible evaluator. */ frozen?: boolean;
+    };
+    jobSpecDecodeError?: string;
+    evaluation: {
+        available: false;
+        reason: 'MANUAL_EVALUATOR' | 'UNVERIFIED_EVALUATOR';
+    };
+}
+export interface JobWriteOptions {
+    progressHook?: StackProgressHook;
+}
+export interface FundJobOptions extends JobWriteOptions {
+    rulesId?: Hex;
+    /** The price the client reviewed. Required for plain jobs or an updated card version. */
+    expectedBudget?: bigint;
+}
+export interface JobEvent {
+    jobId: bigint;
+    kind: string;
+    txHash?: Hex;
+    blockNumber?: bigint;
+    data?: unknown;
+    error?: unknown;
+    cursor?: JobWatchCursor;
+}
+/** Last delivered log; resume includes its block and excludes this log and earlier logs. */
+export interface JobWatchCursor {
+    blockNumber: bigint;
+    logIndex: number;
+    blockHash?: Hex;
+}
+export interface JobWatchOptions {
+    fromBlock?: bigint;
+    cursor?: JobWatchCursor;
+    pollIntervalMs?: number;
+}
+export interface JobNamespace {
+    create(options: CreateJobOptions): Promise<{
+        jobId: bigint;
+        tx: UniversalTxResponse;
+    }>;
+    setBudget(jobId: bigint, amount: bigint, options?: JobWriteOptions & {
+        jobSpec?: Hex;
+    }): Promise<UniversalTxResponse>;
+    fund(jobId: bigint, options?: FundJobOptions): Promise<UniversalTxResponse>;
+    submit(jobId: bigint, options: JobWriteOptions & {
+        deliverable: Hex | string;
+    }): Promise<UniversalTxResponse>;
+    cancel(jobId: bigint, options?: JobWriteOptions): Promise<UniversalTxResponse>;
+    claimRefund(jobId: bigint, options?: JobWriteOptions): Promise<UniversalTxResponse>;
+    verify(jobId: bigint, options?: JobWriteOptions): Promise<never>;
+    status(jobId: bigint): Promise<Job>;
+    list(options?: {
+        client?: Address;
+        provider?: Address;
+        status?: JobStatus;
+        fromJobId?: bigint;
+    }): Promise<{
+        jobs: Job[];
+    }>;
+    watch(jobId: bigint, callback: (event: JobEvent) => void, options?: JobWatchOptions): () => void;
+}

package/src/lib/job/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/src/lib/job/watch.d.ts

@@ -0,0 +1,3 @@
+import { type StackRuntime } from '../market/runtime';
+import type { JobEvent, JobWatchOptions } from './types';
+export declare function watchJob(rt: StackRuntime, jobId: bigint, callback: (event: JobEvent) => void, options: JobWatchOptions): () => void;

package/src/lib/job/watch.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.watchJob = watchJob;
+const viem_1 = require("viem");
+const AgenticCommerce_1 = require("../market/contracts/AgenticCommerce");
+const runtime_1 = require("../market/runtime");
+const errors_1 = require("../market/errors");
+const data_1 = require("../market/data");
+const names = [
+    'JobCreated',
+    'BudgetSet',
+    'JobFunded',
+    'JobSubmitted',
+    'JobCompleted',
+    'JobRejected',
+    'JobExpired',
+    'Refunded',
+];
+const kinds = [
+    'Created',
+    'BudgetSet',
+    'Funded',
+    'Submitted',
+    'Completed',
+    'Rejected',
+    'Expired',
+    'Refunded',
+];
+function watchJob(rt, jobId, callback, options) {
+    const d = (0, runtime_1.deployment)(rt);
+    let stopped = false;
+    let timer;
+    let cursor = options.cursor && { ...options.cursor };
+    let next = cursor?.blockNumber ?? options.fromBlock;
+    const interval = options.pollIntervalMs ?? 3000;
+    if (!Number.isSafeInteger(interval) ||
+        interval < 25 ||
+        (next !== undefined && (typeof next !== 'bigint' || next < BigInt(0))) ||
+        (cursor &&
+            (!Number.isSafeInteger(cursor.logIndex) ||
+                cursor.logIndex < 0 ||
+                (cursor.blockHash && !/^0x[\da-f]{64}$/i.test(cursor.blockHash)))) ||
+        (cursor && options.fromBlock !== undefined))
+        throw new errors_1.JobError('INVALID_WATCH_OPTIONS', 'Use a nonnegative block or a delivered-log cursor, and a polling interval of at least 25ms.');
+    const notify = (event) => {
+        try {
+            callback(event);
+        }
+        catch (error) {
+            if (event.kind !== 'Error' && !stopped) {
+                try {
+                    callback({
+                        jobId,
+                        kind: 'Error',
+                        error,
+                        cursor: cursor && { ...cursor },
+                    });
+                }
+                catch {
+                    /* A consumer exception must not rewind delivery or reject an unobserved promise. */
+                }
+            }
+        }
+    };
+    const poll = async () => {
+        try {
+            const head = await rt.agw.reader.getBlockNumber();
+            if (stopped)
+                return;
+            if (cursor) {
+                if (head < cursor.blockNumber)
+                    throw new errors_1.JobError('WATCH_REORG', 'The delivered cursor is ahead of the canonical head. Reload status before continuing.');
+                const block = rt.agw.reader.getBlock &&
+                    (await rt.agw.reader.getBlock({ blockNumber: cursor.blockNumber }));
+                if (head < cursor.blockNumber ||
+                    (cursor.blockHash &&
+                        block?.hash &&
+                        cursor.blockHash.toLowerCase() !== block.hash.toLowerCase()))
+                    throw new errors_1.JobError('WATCH_REORG', 'The delivered cursor is no longer canonical. Reload job status and restart from a reviewed block.');
+            }
+            if (next === undefined)
+                next = head;
+            const end = next + BigInt(999) < head ? next + BigInt(999) : head;
+            if (next <= end) {
+                const start = next;
+                const groups = await Promise.all(names.map((name) => rt.agw.reader.getLogs({
+                    address: d.kernel,
+                    event: (0, viem_1.getAbiItem)({ abi: AgenticCommerce_1.JOB_KERNEL_ABI, name }),
+                    args: { jobId },
+                    fromBlock: start,
+                    toBlock: end,
+                })));
+                if (stopped)
+                    return;
+                const unique = new Map();
+                for (const log of groups.flat()) {
+                    if (log.removed)
+                        throw new errors_1.JobError('WATCH_REORG', 'The RPC returned a removed job log. Reload status before continuing.');
+                    if ((0, viem_1.getAddress)(log.address) !== (0, viem_1.getAddress)(d.kernel) ||
+                        log.blockNumber === null ||
+                        log.logIndex === null ||
+                        log.blockNumber < start ||
+                        log.blockNumber > end)
+                        throw new errors_1.JobError('INCONSISTENT_READ', 'The RPC returned an unmined or out-of-range job log.');
+                    const event = (0, viem_1.decodeEventLog)({
+                        abi: AgenticCommerce_1.JOB_KERNEL_ABI,
+                        data: log.data,
+                        topics: log.topics,
+                        strict: true,
+                    });
+                    if (event.args.jobId !== jobId ||
+                        !names.includes(event.eventName))
+                        throw new errors_1.JobError('INCONSISTENT_READ', 'The RPC returned a different job or unsupported event.');
+                    const key = `${log.blockNumber}:${log.logIndex}`;
+                    const previous = unique.get(key);
+                    if (previous && (0, data_1.fingerprint)(previous.log) !== (0, data_1.fingerprint)(log))
+                        throw new errors_1.JobError('INCONSISTENT_READ', 'Two different logs occupy the same job cursor.');
+                    unique.set(key, { log, event });
+                }
+                const ordered = [...unique.values()].sort((a, b) => Number(a.log.blockNumber - b.log.blockNumber) || a.log.logIndex - b.log.logIndex);
+                for (const { log, event } of ordered) {
+                    if (stopped)
+                        return;
+                    const blockNumber = log.blockNumber;
+                    const logIndex = log.logIndex;
+                    if (cursor &&
+                        (blockNumber < cursor.blockNumber ||
+                            (blockNumber === cursor.blockNumber &&
+                                logIndex <= cursor.logIndex)))
+                        continue;
+                    cursor = {
+                        blockNumber,
+                        logIndex,
+                        ...(log.blockHash ? { blockHash: log.blockHash } : {}),
+                    };
+                    notify({
+                        jobId,
+                        kind: kinds[names.indexOf(event.eventName)],
+                        txHash: log.transactionHash ?? undefined,
+                        blockNumber,
+                        data: event.args,
+                        cursor: { ...cursor },
+                    });
+                }
+                next = end + BigInt(1);
+            }
+        }
+        catch (error) {
+            if (stopped)
+                return;
+            if (error instanceof errors_1.JobError && error.code === 'WATCH_REORG')
+                stopped = true;
+            notify({ jobId, kind: 'Error', error, cursor: cursor && { ...cursor } });
+        }
+        finally {
+            if (!stopped)
+                timer = setTimeout(() => {
+                    void poll();
+                }, interval);
+        }
+    };
+    void poll();
+    return () => {
+        stopped = true;
+        if (timer)
+            clearTimeout(timer);
+    };
+}
+//# sourceMappingURL=watch.js.map

package/src/lib/job-spec/codec.d.ts

@@ -0,0 +1,18 @@
+import { type Hex } from 'viem';
+import type { BuildJobSpecOptions, BuildJobSpecTemplateOptions, JobSpec, JobSpecTemplate, LogicTree } from './types';
+interface LogicWire {
+    kind: number;
+    checks: readonly number[];
+    children: readonly number[];
+    k: number;
+}
+export declare function int256(value: bigint, what?: string): bigint;
+export declare function flattenLogic(tree: LogicTree, checkCount: number): LogicWire[];
+export declare function buildJobSpec(options: BuildJobSpecOptions): JobSpec;
+export declare function buildJobSpecTemplate(options: BuildJobSpecTemplateOptions): JobSpecTemplate;
+export declare function encodeJobSpec(spec: JobSpec | JobSpecTemplate): Hex;
+/** Known callers pass the format; inference requires one canonical validated decode. */
+export declare function decodeJobSpec(bytes: Hex, options?: {
+    format?: 'spec' | 'template';
+}): JobSpec | JobSpecTemplate;
+export {};