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

package/src/lib/job-spec/codec.js

@@ -0,0 +1,348 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.int256 = int256;
+exports.flattenLogic = flattenLogic;
+exports.buildJobSpec = buildJobSpec;
+exports.buildJobSpecTemplate = buildJobSpecTemplate;
+exports.encodeJobSpec = encodeJobSpec;
+exports.decodeJobSpec = decodeJobSpec;
+const viem_1 = require("viem");
+const errors_1 = require("../market/errors");
+const constants_1 = require("./constants");
+const schema_1 = require("./schema");
+const read_1 = require("./read");
+const originalLogic = new WeakMap();
+const fail = (message, code = 'INVALID_JOB_SPEC') => {
+    throw new errors_1.JobSpecError(code, message);
+};
+const fingerprint = (x) => JSON.stringify(x, (_, v) => (typeof v === 'bigint' ? v.toString() : v));
+function int256(value, what = 'Target') {
+    if (typeof value !== 'bigint' ||
+        value < -(BigInt(1) << BigInt(255)) ||
+        value >= BigInt(1) << BigInt(255))
+        fail(`${what} must fit int256.`);
+    return value;
+}
+function count(values, max, what, min = 1) {
+    if (!Array.isArray(values) || values.length < min || values.length > max)
+        fail(`${what} must contain ${min}..${max} entries.`, `TOO_MANY_${what.toUpperCase()}`);
+}
+function timestamp(n) {
+    if (!Number.isSafeInteger(n) || n < 0)
+        fail('Timestamps must be nonnegative safe integers.');
+}
+function enumIndex(values, value, name) {
+    const i = values.indexOf(value);
+    if (i < 0)
+        fail(`Unknown ${name}.`);
+    return i;
+}
+function flattenLogic(tree, checkCount) {
+    const nodes = [];
+    const active = new Set();
+    function visit(t) {
+        if (!t || active.has(t) || nodes.length >= 32)
+            fail('Logic is cyclic or exceeds 32 operators.', 'BAD_TREE');
+        active.add(t);
+        const index = nodes.length;
+        const kind = enumIndex(constants_1.LOGIC_KINDS, t.kind, 'logic kind');
+        if (!Array.isArray(t.of) || !t.of.length || t.of.length > 255)
+            fail('Logic operators need 1..255 operands.', 'BAD_TREE');
+        const k = t.kind === 'AT_LEAST' ? t.k ?? 0 : 0;
+        if (!Number.isInteger(k) ||
+            (t.kind === 'AT_LEAST' && (k < 1 || k > t.of.length)) ||
+            (t.kind !== 'AT_LEAST' && t.k !== undefined && t.k !== 0))
+            fail('Invalid AT_LEAST threshold.', 'BAD_TREE');
+        const n = { kind, checks: [], children: [], k: k };
+        nodes.push(n);
+        for (const item of t.of) {
+            if (typeof item === 'number') {
+                if (!Number.isInteger(item) ||
+                    item < 0 ||
+                    item >= checkCount ||
+                    n.checks.includes(item))
+                    fail('Dangling or duplicated check index.', 'BAD_TREE');
+                n.checks.push(item);
+            }
+            else
+                n.children.push(visit(item));
+        }
+        active.delete(t);
+        return index;
+    }
+    visit(tree);
+    const saved = originalLogic.get(tree);
+    return saved?.fingerprint === fingerprint(tree) ? saved.wire : nodes;
+}
+function nestLogic(nodes, checkCount) {
+    count(nodes, 32, 'logic');
+    const reached = new Set();
+    let expanded = 0;
+    function visit(index, depth) {
+        if (++expanded > 512 || depth > 32)
+            fail('Stored logic is too large to describe as a tree.', 'BAD_TREE');
+        const n = nodes[index];
+        if (!n || !constants_1.LOGIC_KINDS[n.kind])
+            fail('Unknown stored logic kind.', 'BAD_TREE');
+        reached.add(index);
+        if (n.checks.some((i) => !Number.isInteger(i) || i < 0 || i >= checkCount) ||
+            new Set(n.checks).size !== n.checks.length)
+            fail('Invalid stored check reference.', 'BAD_TREE');
+        if (n.children.some((i) => i <= index || i >= nodes.length) ||
+            new Set(n.children).size !== n.children.length)
+            fail('Invalid stored child reference.', 'BAD_TREE');
+        const t = {
+            kind: constants_1.LOGIC_KINDS[n.kind],
+            of: [...n.checks, ...n.children.map((i) => visit(i, depth + 1))],
+            ...(n.kind === 2 ? { k: n.k } : {}),
+        };
+        if (n.kind !== 2 && n.k !== 0)
+            fail('Unexpected threshold on stored logic.', 'BAD_TREE');
+        return t;
+    }
+    const tree = visit(0, 0);
+    if (reached.size !== nodes.length)
+        fail('Stored logic has unreachable operators.', 'BAD_TREE');
+    // Preserve an unchanged, valid topological order instead of rewriting signed bytes.
+    originalLogic.set(tree, { fingerprint: fingerprint(tree), wire: nodes });
+    flattenLogic(tree, checkCount);
+    return tree;
+}
+function normalizeReads(values) {
+    count(values, 16, 'reads');
+    return values.map((input) => {
+        const wrapper = input;
+        const source = 'read' in input ? wrapper.read : input;
+        const read = {
+            ...source,
+            field: [...(wrapper.field ?? [0])],
+            minConfirmations: wrapper.minConfirmations ?? 1,
+            ...(source.fills ? { fills: source.fills.map((f) => ({ ...f })) } : {}),
+        };
+        (0, read_1.inheritReadLabel)(source, read);
+        return read;
+    });
+}
+function validate(spec) {
+    count(spec.reads, 16, 'reads');
+    count(spec.checks, 16, 'checks');
+    enumIndex(constants_1.MUTABILITIES, spec.allowedMutability, 'allowedMutability');
+    const template = 'params' in spec;
+    if (template) {
+        count(spec.params, 16, 'params', 0);
+        for (const p of spec.params)
+            if (int256(p.min) > int256(p.max))
+                fail('Parameter minimum exceeds its maximum.');
+    }
+    else {
+        timestamp(spec.executeBy);
+        timestamp(spec.failFinalAt);
+        if (spec.failFinalAt <= spec.executeBy ||
+            !/^0x[\da-f]{64}$/i.test(spec.origin))
+            fail('Invalid JobSpec timing or origin.');
+    }
+    for (const r of spec.reads) {
+        (0, read_1.validateJobRead)(r);
+        if (!Number.isInteger(r.minConfirmations) ||
+            r.minConfirmations < 1 ||
+            r.minConfirmations > 65535)
+            fail('Read confirmations must be 1..65535.');
+        const words = new Set();
+        for (const f of r.fills ?? []) {
+            if (!template)
+                fail('A complete JobSpec cannot contain placeholders.', 'UNFILLED_PLACEHOLDER');
+            if (!Number.isInteger(f.word) ||
+                f.word < 0 ||
+                f.word > 255 ||
+                f.word * 32 + 32 > (r.args.length - 2) / 2 ||
+                words.has(f.word))
+                fail('Invalid or duplicate fill word.');
+            words.add(f.word);
+            if (!['WALLET', 'PARAM'].includes(f.source))
+                fail('Unknown fill source.');
+            if (f.source === 'PARAM' &&
+                (!Number.isInteger(f.param) ||
+                    (f.param ?? -1) < 0 ||
+                    (f.param ?? -1) >= spec.params.length))
+                fail('Fill parameter is out of range.');
+        }
+    }
+    for (const c of spec.checks) {
+        if (!Number.isInteger(c.read) || c.read < 0 || c.read >= spec.reads.length)
+            fail('Check read index is out of range.');
+        enumIndex(constants_1.EVALUATIONS, c.evaluation, 'evaluation');
+        enumIndex(constants_1.OPERATIONS, c.operation, 'operation');
+        if (c.evaluation === 'BOOLEAN' && c.operation !== 'EQUAL')
+            fail('BOOLEAN checks use EQUAL.');
+        if (typeof c.target === 'bigint')
+            int256(c.target);
+        else if (!template)
+            fail('Complete JobSpec targets must be resolved integers.', 'UNFILLED_PLACEHOLDER');
+        else
+            targetWire(c.target, spec.params.length);
+    }
+    flattenLogic(spec.logic, spec.checks.length);
+}
+function targetWire(target, params) {
+    if (typeof target === 'bigint')
+        return { source: 0, value: int256(target) };
+    if (target === constants_1.PRINCIPAL)
+        return { source: 1, value: BigInt(10000) };
+    if (target === 'agentic:wallet')
+        return { source: 3, value: BigInt(0) };
+    if (target && typeof target === 'object' && 'principalBps' in target) {
+        if (int256(target.principalBps) <= BigInt(0))
+            fail('principalBps must be positive.');
+        return { source: 1, value: target.principalBps };
+    }
+    if (target &&
+        typeof target === 'object' &&
+        'param' in target &&
+        Number.isInteger(target.param) &&
+        target.param >= 0 &&
+        target.param < params)
+        return { source: 2, value: BigInt(target.param) };
+    return fail('Unknown or out-of-range template target.');
+}
+function buildJobSpec(options) {
+    const spec = {
+        reads: normalizeReads(options.reads),
+        checks: options.checks.map((c) => ({ ...c })),
+        logic: typeof options.logic === 'string'
+            ? { kind: options.logic, of: options.checks.map((_, i) => i) }
+            : options.logic,
+        allowedMutability: options.allowedMutability ?? 'NONE',
+        origin: options.origin ?? viem_1.zeroHash,
+        executeBy: options.executeBy,
+        failFinalAt: options.failFinalAt,
+    };
+    validate(spec);
+    if (options.expiredAt !== undefined) {
+        timestamp(options.expiredAt);
+        if (options.failFinalAt >= options.expiredAt)
+            fail('failFinalAt must precede job expiry.', 'FAIL_WINDOW_THIN');
+    }
+    return spec;
+}
+function buildJobSpecTemplate(options) {
+    const t = {
+        reads: normalizeReads(options.reads),
+        checks: options.checks.map((c) => ({ ...c })),
+        logic: typeof options.logic === 'string'
+            ? { kind: options.logic, of: options.checks.map((_, i) => i) }
+            : options.logic,
+        allowedMutability: options.allowedMutability ?? 'NONE',
+        params: (options.params ?? []).map((p) => ({ ...p })),
+    };
+    validate(t);
+    return t;
+}
+function encodeJobSpec(spec) {
+    validate(spec);
+    const base = {
+        reads: spec.reads.map(({ fills, ...r }) => 'params' in spec
+            ? {
+                ...r,
+                fills: (fills ?? []).map((f) => ({
+                    word: f.word,
+                    source: f.source === 'WALLET' ? 0 : 1,
+                    param: f.param ?? 0,
+                })),
+            }
+            : r),
+        logic: flattenLogic(spec.logic, spec.checks.length),
+        allowedMutability: constants_1.MUTABILITIES.indexOf(spec.allowedMutability),
+    };
+    const checks = spec.checks.map((c) => ({
+        read: c.read,
+        evaluation: constants_1.EVALUATIONS.indexOf(c.evaluation),
+        operation: constants_1.OPERATIONS.indexOf(c.operation),
+        ...('params' in spec
+            ? targetWire(c.target, spec.params.length)
+            : { target: c.target }),
+    }));
+    const value = 'params' in spec
+        ? { ...base, checks, params: spec.params }
+        : {
+            ...base,
+            checks,
+            origin: spec.origin,
+            executeBy: BigInt(spec.executeBy),
+            failFinalAt: BigInt(spec.failFinalAt),
+        };
+    return (0, viem_1.encodeAbiParameters)([('params' in spec ? schema_1.JOB_TEMPLATE_PARAM : schema_1.JOB_SPEC_PARAM)], [value]);
+}
+/** Known callers pass the format; inference requires one canonical validated decode. */
+function decodeJobSpec(bytes, options) {
+    if (!(0, viem_1.isHex)(bytes) || bytes.length > 524290)
+        fail('Invalid or oversized JobSpec encoding.');
+    const valid = [];
+    for (const template of options?.format
+        ? [options.format === 'template']
+        : [false, true]) {
+        try {
+            const w = (0, viem_1.decodeAbiParameters)([(template ? schema_1.JOB_TEMPLATE_PARAM : schema_1.JOB_SPEC_PARAM)], bytes)[0];
+            const reads = w.reads.map(({ fills: rawFills, ...r }) => ({
+                ...r,
+                ...(template
+                    ? {
+                        fills: (rawFills ?? []).map((f) => {
+                            if (f.source > 1 || (f.source === 0 && f.param !== 0))
+                                fail('Invalid stored fill.');
+                            return {
+                                word: f.word,
+                                source: f.source === 0 ? 'WALLET' : 'PARAM',
+                                ...(f.source === 1 ? { param: f.param } : {}),
+                            };
+                        }),
+                    }
+                    : {}),
+            }));
+            const checks = w.checks.map((c) => {
+                const common = {
+                    read: c.read,
+                    evaluation: constants_1.EVALUATIONS[c.evaluation],
+                    operation: constants_1.OPERATIONS[c.operation],
+                };
+                if (!template)
+                    return { ...common, target: c.target };
+                const t = c;
+                const target = t.source === 0
+                    ? t.value
+                    : t.source === 1
+                        ? t.value === BigInt(10000)
+                            ? constants_1.PRINCIPAL
+                            : { principalBps: t.value }
+                        : t.source === 2
+                            ? { param: Number(t.value) }
+                            : t.source === 3 && t.value === BigInt(0)
+                                ? 'agentic:wallet'
+                                : fail('Unknown template target.');
+                return { ...common, target };
+            });
+            const common = {
+                reads,
+                checks,
+                logic: nestLogic(w.logic, checks.length),
+                allowedMutability: constants_1.MUTABILITIES[w.allowedMutability],
+            };
+            const spec = (template
+                ? { ...common, params: w.params }
+                : {
+                    ...common,
+                    origin: w.origin,
+                    executeBy: Number(w.executeBy),
+                    failFinalAt: Number(w.failFinalAt),
+                });
+            if (encodeJobSpec(spec).toLowerCase() === bytes.toLowerCase())
+                valid.push(spec);
+        }
+        catch {
+            /* Wrong shape, unsupported wire, malformed enums or noncanonical bytes. */
+        }
+    }
+    if (valid.length !== 1)
+        fail('The bytes do not identify one supported canonical deployed-v2 JobSpec format.', 'UNSUPPORTED_JOB_SPEC');
+    return valid[0];
+}
+//# sourceMappingURL=codec.js.map

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

@@ -0,0 +1,32 @@
+export declare const JOB_VOCABULARY: Readonly<{
+    EVALUATION: Readonly<{
+        readonly BOOLEAN: "BOOLEAN";
+        readonly COMPARE: "COMPARE";
+        readonly NUMBER: "NUMBER";
+        readonly PERCENTAGE: "PERCENTAGE";
+    }>;
+    OPERATION: Readonly<{
+        readonly EQUAL: "EQUAL";
+        readonly NOT_EQUAL: "NOT_EQUAL";
+        readonly GREATER_THAN: "GREATER_THAN";
+        readonly GREATER_OR_EQUAL: "GREATER_OR_EQUAL";
+        readonly LESS_THAN: "LESS_THAN";
+        readonly LESS_OR_EQUAL: "LESS_OR_EQUAL";
+    }>;
+    LOGIC: Readonly<{
+        readonly ALL: "ALL";
+        readonly ANY: "ANY";
+        readonly AT_LEAST: "AT_LEAST";
+    }>;
+    ALLOWED_MUTABILITY: Readonly<{
+        readonly NONE: "NONE";
+        readonly CLIENT: "CLIENT";
+        readonly PROVIDER: "PROVIDER";
+        readonly BOTH: "BOTH";
+    }>;
+}>;
+export declare const PRINCIPAL: "agentic:principal";
+export declare const EVALUATIONS: ("BOOLEAN" | "COMPARE" | "NUMBER" | "PERCENTAGE")[];
+export declare const OPERATIONS: ("EQUAL" | "NOT_EQUAL" | "GREATER_THAN" | "GREATER_OR_EQUAL" | "LESS_THAN" | "LESS_OR_EQUAL")[];
+export declare const LOGIC_KINDS: ("ALL" | "ANY" | "AT_LEAST")[];
+export declare const MUTABILITIES: ("NONE" | "CLIENT" | "PROVIDER" | "BOTH")[];

package/src/lib/job-spec/constants.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MUTABILITIES = exports.LOGIC_KINDS = exports.OPERATIONS = exports.EVALUATIONS = exports.PRINCIPAL = exports.JOB_VOCABULARY = void 0;
+exports.JOB_VOCABULARY = Object.freeze({
+    EVALUATION: Object.freeze({
+        BOOLEAN: 'BOOLEAN',
+        COMPARE: 'COMPARE',
+        NUMBER: 'NUMBER',
+        PERCENTAGE: 'PERCENTAGE',
+    }),
+    OPERATION: Object.freeze({
+        EQUAL: 'EQUAL',
+        NOT_EQUAL: 'NOT_EQUAL',
+        GREATER_THAN: 'GREATER_THAN',
+        GREATER_OR_EQUAL: 'GREATER_OR_EQUAL',
+        LESS_THAN: 'LESS_THAN',
+        LESS_OR_EQUAL: 'LESS_OR_EQUAL',
+    }),
+    LOGIC: Object.freeze({
+        ALL: 'ALL',
+        ANY: 'ANY',
+        AT_LEAST: 'AT_LEAST',
+    }),
+    ALLOWED_MUTABILITY: Object.freeze({
+        NONE: 'NONE',
+        CLIENT: 'CLIENT',
+        PROVIDER: 'PROVIDER',
+        BOTH: 'BOTH',
+    }),
+});
+exports.PRINCIPAL = 'agentic:principal';
+exports.EVALUATIONS = Object.values(exports.JOB_VOCABULARY.EVALUATION);
+exports.OPERATIONS = Object.values(exports.JOB_VOCABULARY.OPERATION);
+exports.LOGIC_KINDS = Object.values(exports.JOB_VOCABULARY.LOGIC);
+exports.MUTABILITIES = Object.values(exports.JOB_VOCABULARY.ALLOWED_MUTABILITY);
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1,19 @@
+import { type Address, type Hex } from 'viem';
+import type { JobSpec, JobSpecTemplate } from './types';
+export declare function resolveJobSpec(template: JobSpecTemplate, ctx: {
+    principal: bigint;
+    params: bigint[];
+    accounts: Record<string, Address>;
+    origin: Hex;
+    executeBy: number;
+    settleWindow: number;
+}): JobSpec;
+export declare function describeJobSpec(spec: JobSpec | JobSpecTemplate, options?: {
+    principal?: bigint;
+    decimals?: Record<Address, number>;
+}): {
+    checks: string[];
+    logic: string;
+    timing: string;
+};
+export declare function specOrigin(marketplace: Address, cardId: bigint, version: bigint, principal: bigint): Hex;

package/src/lib/job-spec/helpers.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveJobSpec = resolveJobSpec;
+exports.describeJobSpec = describeJobSpec;
+exports.specOrigin = specOrigin;
+const viem_1 = require("viem");
+const codec_1 = require("./codec");
+const constants_1 = require("./constants");
+const errors_1 = require("../market/errors");
+const read_1 = require("./read");
+function resolveJobSpec(template, ctx) {
+    (0, codec_1.encodeJobSpec)(template);
+    if (ctx.params.length !== template.params.length ||
+        ctx.params.some((n, i) => (0, codec_1.int256)(n) < template.params[i].min || n > template.params[i].max))
+        throw new errors_1.JobSpecError('PARAM_OUT_OF_RANGE', 'The job parameters do not match the template bounds.');
+    const account = (read) => {
+        const r = template.reads[read];
+        const a = ctx.accounts[`${r.chainNamespace}:${r.chainId}`];
+        if (!a)
+            throw new errors_1.JobSpecError('UNFILLED_PLACEHOLDER', 'Resolve the wallet account on every read chain.');
+        return (0, viem_1.getAddress)(a);
+    };
+    const reads = template.reads.map((r, i) => {
+        let args = r.args;
+        for (const f of r.fills ?? []) {
+            const value = f.source === 'WALLET'
+                ? BigInt(account(i))
+                : BigInt.asUintN(256, ctx.params[f.param ?? 0]);
+            const at = 2 + f.word * 64;
+            args = (args.slice(0, at) +
+                (0, viem_1.toHex)(value, { size: 32 }).slice(2) +
+                args.slice(at + 64));
+        }
+        const read = { ...r };
+        delete read.fills;
+        const resolved = { ...read, args };
+        (0, read_1.inheritReadLabel)(r, resolved);
+        return resolved;
+    });
+    const checks = template.checks.map((c) => {
+        const t = c.target;
+        const target = typeof t === 'bigint'
+            ? t
+            : t === constants_1.PRINCIPAL
+                ? ctx.principal
+                : t === 'agentic:wallet'
+                    ? BigInt(account(c.read))
+                    : 'param' in t
+                        ? ctx.params[t.param]
+                        : (() => {
+                            const product = ctx.principal * t.principalBps;
+                            if (product >= BigInt(1) << BigInt(256))
+                                throw new errors_1.JobSpecError('TARGET_OVERFLOW', 'The principal-based target overflows uint256.');
+                            return product / BigInt(10000);
+                        })();
+        return { ...c, target: (0, codec_1.int256)(target) };
+    });
+    const spec = {
+        reads,
+        checks,
+        logic: template.logic,
+        allowedMutability: template.allowedMutability,
+        origin: ctx.origin,
+        executeBy: ctx.executeBy,
+        failFinalAt: ctx.executeBy + ctx.settleWindow,
+    };
+    (0, codec_1.encodeJobSpec)(spec);
+    return spec;
+}
+const words = {
+    EQUAL: 'equals',
+    NOT_EQUAL: 'does not equal',
+    GREATER_THAN: 'is greater than',
+    GREATER_OR_EQUAL: 'is at least',
+    LESS_THAN: 'is less than',
+    LESS_OR_EQUAL: 'is at most',
+};
+function describeJobSpec(spec, options) {
+    (0, codec_1.encodeJobSpec)(spec);
+    if (options?.principal !== undefined && (0, codec_1.int256)(options.principal) < BigInt(0))
+        throw new errors_1.JobSpecError('INVALID_DESCRIPTION_OPTIONS', 'Principal must be nonnegative.');
+    const decimals = new Map();
+    for (const [address, value] of Object.entries(options?.decimals ?? {})) {
+        if (!Number.isInteger(value) || value < 0 || value > 255)
+            throw new errors_1.JobSpecError('INVALID_DESCRIPTION_OPTIONS', 'Token decimals must be integers from 0 to 255.');
+        try {
+            decimals.set((0, viem_1.getAddress)(address).toLowerCase(), value);
+        }
+        catch (cause) {
+            throw new errors_1.JobSpecError('INVALID_DESCRIPTION_OPTIONS', 'Decimals must be keyed by token address.', undefined, cause);
+        }
+    }
+    function logic(t) {
+        return `${t.kind === 'ALL' ? 'All' : t.kind === 'ANY' ? 'Any' : `At least ${t.k}`} of (${t.of
+            .map((x) => (typeof x === 'number' ? `check ${x + 1}` : logic(x)))
+            .join(', ')})`;
+    }
+    return {
+        checks: spec.checks.map((c) => {
+            const r = spec.reads[c.read];
+            const t = c.target;
+            const resolvedTarget = typeof t === 'bigint'
+                ? t
+                : t === constants_1.PRINCIPAL
+                    ? options?.principal ?? 'principal'
+                    : t === 'agentic:wallet'
+                        ? 'the wallet on this chain'
+                        : 'param' in t
+                            ? `parameter ${t.param + 1}`
+                            : options?.principal !== undefined
+                                ? (options.principal * t.principalBps) / BigInt(10000)
+                                : `${t.principalBps} basis points of principal`;
+            const precision = decimals.get(r.target.toLowerCase());
+            const target = typeof resolvedTarget === 'bigint'
+                ? c.evaluation === 'PERCENTAGE'
+                    ? `${(0, viem_1.formatUnits)(resolvedTarget, 2)}% (${resolvedTarget} bps)`
+                    : precision !== undefined && c.evaluation !== 'BOOLEAN'
+                        ? `${(0, viem_1.formatUnits)(resolvedTarget, precision)} (${resolvedTarget} raw units; ${precision} decimals)`
+                        : `${resolvedTarget} (raw units)`
+                : `${resolvedTarget}${c.evaluation === 'PERCENTAGE' ? ' bps' : ' (raw units)'}`;
+            const name = (0, read_1.jobReadLabel)(r);
+            return `Read ${c.read + 1}: ${r.target} ${name ? name + ' ' : ''}${r.selector} on ${r.chainNamespace}:${r.chainId}, field [${r.field.join(',')}], ${c.evaluation} ${words[c.operation]} ${target}.`;
+        }),
+        logic: logic(spec.logic),
+        timing: 'executeBy' in spec
+            ? `Execute by ${new Date(spec.executeBy * 1000).toISOString()}; failure is final after ${new Date(spec.failFinalAt * 1000).toISOString()}.`
+            : '',
+    };
+}
+function specOrigin(marketplace, cardId, version, principal) {
+    // Imported here to keep the public helpers independent of client state.
+    return (0, viem_1.keccak256)(('0x' +
+        [
+            marketplace.slice(2).padStart(64, '0'),
+            ...[cardId, version, principal].map((n) => (0, viem_1.toHex)(n, { size: 32 }).slice(2)),
+        ].join('')));
+}
+//# sourceMappingURL=helpers.js.map

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

@@ -0,0 +1,14 @@
+import { buildJobSpec, buildJobSpecTemplate, encodeJobSpec, decodeJobSpec } from './codec';
+import { describeJobSpec } from './helpers';
+import { prepareJobRead } from './read';
+import { previewJobSpec } from './preview';
+export declare const jobSpecUtils: Readonly<{
+    buildJobSpec: typeof buildJobSpec;
+    buildJobSpecTemplate: typeof buildJobSpecTemplate;
+    encodeJobSpec: typeof encodeJobSpec;
+    decodeJobSpec: typeof decodeJobSpec;
+    describeJobSpec: typeof describeJobSpec;
+    prepareRead: typeof prepareJobRead;
+    previewJobSpec: typeof previewJobSpec;
+}>;
+export type * from './types';

package/src/lib/job-spec/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jobSpecUtils = void 0;
+const codec_1 = require("./codec");
+const helpers_1 = require("./helpers");
+const read_1 = require("./read");
+const preview_1 = require("./preview");
+exports.jobSpecUtils = Object.freeze({
+    buildJobSpec: codec_1.buildJobSpec,
+    buildJobSpecTemplate: codec_1.buildJobSpecTemplate,
+    encodeJobSpec: codec_1.encodeJobSpec,
+    decodeJobSpec: codec_1.decodeJobSpec,
+    describeJobSpec: helpers_1.describeJobSpec,
+    prepareRead: read_1.prepareJobRead,
+    previewJobSpec: preview_1.previewJobSpec,
+});
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,8 @@
+import { type Address, type Hex } from 'viem';
+import type { CHAIN } from '../constants/enums';
+import type { JobRead, JobSpec, JobSpecTemplate, JobSpecPreview, PreviewJobSpecOptions } from './types';
+/** @internal Bind the real client's configured CEA resolver without exposing its runtime. */
+export declare function bindJobPreviewAccounts(universal: object, resolve: (wallet: Address, chain: CHAIN) => Promise<Address>): void;
+/** Follow the deployed V2 type codes; uint values above int256.max cannot be compared. */
+export declare function decodeJobAnswer(read: JobRead, data: Hex): bigint;
+export declare function previewJobSpec(subject: JobSpec | JobSpecTemplate, options: PreviewJobSpecOptions): Promise<JobSpecPreview>;