agentex-creator-sdk 1.0.0

package/dist/packages/publication/src/fixtures.js

@@ -0,0 +1,350 @@
+import { decodeAbiParameters, decodeFunctionData, encodeAbiParameters, encodeFunctionResult, parseAbiParameters, keccak256, formatUnits } from 'viem';
+import { contentHash, ResearchInputSchema, SupportedTokenResearcherManifestSchema, TokenResearchReportSchema, resolveResearchPolicy } from '../../contracts/src/index.js';
+import { buildMarketSection, discoveryPlan, HOLDER_ACTIVITY_METHOD, MARKET_SELECTORS, marketCallInScope, marketTransferRequestInScope, marketVenuesFor, MULTICALL3_ABI, MULTICALL3_ADDRESS } from '../../contracts/src/token-market.js';
+import { researchToken, EIP1967_SLOTS } from '../../research/src/index.js';
+import { validateReceipt } from '../../runtime/src/checkpoints.js';
+export const EVALUATION_SUITE_VERSION = 'token-researcher-local-fixtures-v1';
+const CASES = ['standard-metadata', 'nonstandard-decimals', 'proxy-owner-gap', 'no-contract', 'provider-failure', 'chain-mismatch', 'snapshot-changed'];
+const FIXED_TIME = '2026-01-01T00:00:00.000Z';
+/**
+ * Robinhood Chain fixtures answer chain id 4663 (mainnet), or 46630 when this server is configured as a Robinhood testnet host. The fixture transport never
+ * leaves the process; the Robinhood identity settings below only satisfy the executor's configuration check with the documented values.
+ */
+const robinhoodEvaluationChainId = () => (process.env.ROBINHOOD_CHAIN_ID === '46630' ? 46630 : 4663);
+const evaluationChainId = (chain) => chain === 'ethereum' ? '0x1' : chain === 'base' ? '0x2105' : `0x${robinhoodEvaluationChainId().toString(16)}`;
+const evaluationEnv = () => ({ ETHEREUM_RPC_URL: 'https://evaluation.invalid', BASE_RPC_URL: 'https://evaluation.invalid', ROBINHOOD_RPC_URL: 'https://evaluation.invalid',
+    ROBINHOOD_CHAIN_ID: String(robinhoodEvaluationChainId()), ROBINHOOD_DOCUMENTATION_URL: 'https://docs.robinhood.com/chain/connecting/', ROBINHOOD_VERIFIED_AT: FIXED_TIME });
+const ADDRESS = `0x${'1'.repeat(40)}`;
+const BLOCK_HASH = `0x${'a'.repeat(64)}`;
+const IMPLEMENTATION = `0x${'2'.repeat(40)}`;
+const LARGE_SUPPLY = '90071992547409931234567890';
+const descriptor = { version: EVALUATION_SUITE_VERSION, cases: CASES, fixedTime: FIXED_TIME, address: ADDRESS, blockHash: BLOCK_HASH,
+    implementation: IMPLEMENTATION, largeSupply: LARGE_SUPPLY, blockNumber: '100', baseDecimals: 6, nonstandardDecimals: 255,
+    expectedContracts: 'canonical-observed-metadata-v1;exact-supply;policy-skips;fail-closed-errors;rpc-ceilings;receipt-scope-v1' };
+export const EVALUATION_SUITE_HASH = contentHash(descriptor);
+/**
+ * Token Researcher 0.3.0 (market policy) suite. v1 above is unchanged, so every earlier evaluation keeps its hash. A version with `marketPolicy`
+ * runs the v1 cases plus market cases, and the report's market section must equal its derivation from the captured receipts.
+ */
+export const MARKET_EVALUATION_SUITE_VERSION = 'token-researcher-local-fixtures-v2';
+const MARKET_CASES = ['multiple-pools', 'no-pools', 'recent-recipients-not-holders', 'holder-index-unavailable'];
+const POOL_A = `0x${'4'.repeat(40)}`;
+const POOL_B = `0x${'5'.repeat(40)}`;
+const RECIPIENT = `0x${'6'.repeat(40)}`;
+export const MARKET_EVALUATION_SUITE_HASH = contentHash({ ...descriptor, version: MARKET_EVALUATION_SUITE_VERSION, cases: [...CASES, ...MARKET_CASES], poolA: POOL_A, poolB: POOL_B, recipient: RECIPIENT,
+    expectedContracts: `${descriptor.expectedContracts};market-derived-from-receipts;listed-venues-only;recipients-not-holders;index-failure-partial;rpc-ceiling-16` });
+/** Suite version and hash for a Token Researcher manifest: v2 when it declares a market policy, otherwise the unchanged v1. */
+export const tokenResearchSuiteFor = (manifest) => manifest.marketPolicy !== undefined
+    ? { version: MARKET_EVALUATION_SUITE_VERSION, hash: MARKET_EVALUATION_SUITE_HASH } : { version: EVALUATION_SUITE_VERSION, hash: EVALUATION_SUITE_HASH };
+const encode = (type, value) => encodeAbiParameters(parseAbiParameters(type), [value]);
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** This invariant is shared by local review and fixtures; callers still must verify the stored run/checkpoint binding. */
+export function canonicalMetadataObserved(report) {
+    try {
+        TokenResearchReportSchema.parse(report);
+        for (const receipt of report.evidence)
+            validateReceipt(receipt, report.input);
+        return checkedCanonicalMetadata(report);
+    }
+    catch {
+        return false;
+    }
+}
+function checkedCanonicalMetadata(report) {
+    // New runs pin the latest block (`sequencer-confirmed`); creator tests captured before the instant-read rule keep `finalized`.
+    if (report.status === 'failed' || report.snapshot?.canonicality !== 'verified-at-completion' || (report.snapshot.finality !== 'sequencer-confirmed' && report.snapshot.finality !== 'finalized'))
+        return false;
+    if (report.input.snapshotBlock !== undefined && report.input.snapshotBlock !== report.snapshot.blockNumber)
+        return false;
+    const identity = report.evidence.findIndex(item => item.source.method === 'eth_chainId' && item.completeness === 'complete-for-request'
+        && typeof item.result === 'string' && /^0x[0-9a-fA-F]+$/.test(item.result) && BigInt(item.result) === BigInt(report.chainId));
+    if (identity < 0)
+        return false;
+    const firstState = report.evidence.findIndex(item => ['eth_getCode', 'eth_call', 'eth_getStorageAt'].includes(item.source.method));
+    const head = report.evidence.some((item, index) => index > identity && index < firstState && item.source.method === 'eth_getBlockByNumber'
+        && (item.request[0] === 'latest' || item.request[0] === 'finalized') && item.completeness === 'complete-for-request' && object(item.result) && typeof item.result.number === 'string'
+        && /^0x[0-9a-fA-F]+$/.test(item.result.number) && BigInt(item.result.number) >= BigInt(report.snapshot.blockNumber));
+    const selected = report.evidence.some((item, index) => index < firstState && item.source.method === 'eth_getBlockByNumber'
+        && item.completeness === 'complete-for-request' && object(item.result) && typeof item.result.number === 'string' && /^0x[0-9a-fA-F]+$/.test(item.result.number)
+        && BigInt(item.result.number).toString() === report.snapshot.blockNumber && typeof item.result.hash === 'string'
+        && item.result.hash.toLowerCase() === report.snapshot.blockHash.toLowerCase() && typeof item.result.timestamp === 'string'
+        && /^0x[0-9a-fA-F]+$/.test(item.result.timestamp) && BigInt(item.result.timestamp).toString() === report.snapshot.timestamp);
+    if (!head || !selected)
+        return false;
+    const observations = [[report.metadata.name, '0x06fdde03'], [report.metadata.symbol, '0x95d89b41'], [report.metadata.decimals, '0x313ce567'],
+        [report.metadata.totalSupplyAtomic, '0x18160ddd'], [report.contract.codePresent, null], [report.contract.codeHash, null]];
+    if (report.contract.codePresent.status !== 'observed' || report.contract.codePresent.value !== true)
+        return false;
+    let last = -1;
+    const good = observations.every(([observation, selector]) => observation.status === 'observed' && observation.evidenceIds.length > 0 && observation.evidenceIds.every(id => {
+        const index = report.evidence.findIndex(receipt => receipt.id === id);
+        const item = report.evidence[index];
+        if (!item || item.chainId !== report.chainId || item.completeness !== 'complete-for-request' || item.snapshot?.blockNumber !== report.snapshot.blockNumber
+            || item.snapshot.blockHash.toLowerCase() !== report.snapshot.blockHash.toLowerCase())
+            return false;
+        if (selector === null ? item.source.method !== 'eth_getCode' || typeof item.result !== 'string' || item.result === '0x'
+            : item.source.method !== 'eth_call' || !object(item.request[0]) || item.request[0].data !== selector)
+            return false;
+        if (typeof item.result !== 'string' || !/^0x(?:[a-fA-F0-9]{2})*$/.test(item.result))
+            return false;
+        const bytes = item.result;
+        const decoded = selector === '0x06fdde03' || selector === '0x95d89b41' ? decodeAbiParameters(parseAbiParameters('string'), bytes)[0]
+            : selector === '0x313ce567' ? decodeAbiParameters(parseAbiParameters('uint8'), bytes)[0]
+                : selector === '0x18160ddd' ? decodeAbiParameters(parseAbiParameters('uint256'), bytes)[0].toString()
+                    : observation === report.contract.codePresent ? true : keccak256(bytes);
+        if (observation.value !== decoded)
+            return false;
+        if ((selector === '0x06fdde03' || selector === '0x95d89b41') && (typeof decoded !== 'string' || Buffer.byteLength(decoded, 'utf8') > 256
+            || Array.from(decoded).some(character => character.charCodeAt(0) === 127 || (character.charCodeAt(0) < 32 && ![9, 10, 13].includes(character.charCodeAt(0))))))
+            return false;
+        last = Math.max(last, index);
+        return true;
+    }));
+    if (!good || report.metadata.decimals.status !== 'observed' || report.metadata.totalSupplyAtomic.status !== 'observed'
+        || report.metadata.totalSupplyFormatted.status !== 'observed' || typeof report.metadata.decimals.value !== 'number'
+        || !Number.isInteger(report.metadata.decimals.value) || report.metadata.decimals.value < 0 || report.metadata.decimals.value > 255
+        || typeof report.metadata.totalSupplyAtomic.value !== 'string' || typeof report.metadata.totalSupplyFormatted.value !== 'string')
+        return false;
+    const formatIds = [...report.metadata.decimals.evidenceIds, ...report.metadata.totalSupplyAtomic.evidenceIds].sort();
+    if (contentHash([...report.metadata.totalSupplyFormatted.evidenceIds].sort()) !== contentHash(formatIds)
+        || report.metadata.totalSupplyFormatted.value !== formatUnits(BigInt(report.metadata.totalSupplyAtomic.value), report.metadata.decimals.value))
+        return false;
+    for (const [index, item] of report.evidence.entries())
+        if (['eth_getCode', 'eth_call', 'eth_getStorageAt'].includes(item.source.method)) {
+            if (item.chainId !== report.chainId || item.snapshot?.blockNumber !== report.snapshot.blockNumber || item.snapshot.blockHash.toLowerCase() !== report.snapshot.blockHash.toLowerCase()
+                || item.canonicality !== 'verified-at-completion')
+                return false;
+            last = Math.max(last, index);
+        }
+    return report.evidence.some((item, index) => index > last && item.chainId === report.chainId && item.source.method === 'eth_getBlockByNumber'
+        && item.request[0] === `0x${BigInt(report.snapshot.blockNumber).toString(16)}` && item.completeness === 'complete-for-request'
+        && object(item.result) && typeof item.result.hash === 'string' && item.result.hash.toLowerCase() === report.snapshot.blockHash.toLowerCase()
+        && typeof item.result.number === 'string' && /^0x[0-9a-fA-F]+$/.test(item.result.number) && BigInt(item.result.number).toString() === report.snapshot.blockNumber);
+}
+export function validateReportBinding(raw, manifest, input) {
+    const report = TokenResearchReportSchema.parse(raw);
+    if (report.manifestHash !== contentHash(manifest) || report.agentVersion !== manifest.version || contentHash(report.input) !== contentHash(input))
+        throw new Error('Report identity differs from its immutable version or input.');
+    const policy = resolveResearchPolicy(manifest);
+    if (contentHash(resolveResearchPolicy(report)) !== contentHash(policy))
+        throw new Error('Report research policy differs from its immutable manifest.');
+    for (const receipt of report.evidence)
+        validateReceipt(receipt, input);
+    const selectors = ['0x06fdde03', '0x95d89b41', '0x313ce567', '0x18160ddd', ...(policy.readOwner ? ['0x8da5cb5b'] : [])];
+    const market = manifest.marketPolicy;
+    if (!market && (report.market !== undefined || report.marketPolicy !== undefined))
+        throw new Error('A report without a market policy cannot carry a market section.');
+    if (market && (!report.market || contentHash(report.marketPolicy ?? null) !== contentHash(market)))
+        throw new Error('Report market policy differs from its immutable manifest.');
+    for (const receipt of report.evidence) {
+        const marketRead = Boolean(market?.discoverPools || market?.recentHolderActivity) && receipt.source.method === 'eth_call' && report.chainId !== null && marketCallInScope(receipt.request[0], input.address, report.chainId);
+        if (receipt.source.method === 'eth_call' && !marketRead && (!object(receipt.request[0]) || typeof receipt.request[0].data !== 'string' || !selectors.includes(receipt.request[0].data)))
+            throw new Error('Report contains an unselected contract read.');
+        if (receipt.source.method === HOLDER_ACTIVITY_METHOD && (!market?.recentHolderActivity || !receipt.snapshot || !marketTransferRequestInScope(receipt.request, input.address, receipt.snapshot.blockNumber)))
+            throw new Error('Report contains an unselected index read.');
+        if (receipt.source.method === 'eth_getStorageAt' && (!policy.readProxySlots || !Object.values(EIP1967_SLOTS).includes(receipt.request[1])))
+            throw new Error('Report contains an unselected proxy slot read.');
+    }
+    if (market && report.market) {
+        // The market section must be exactly its derivation from this report's receipts. An unsupported section carries no receipt of its kind.
+        const unsupported = { pools: report.market.pools.status === 'unsupported' ? report.market.pools.reason : null, holders: report.market.recentHolderActivity.status === 'unsupported' ? report.market.recentHolderActivity.reason : null };
+        const multicalls = report.evidence.some((item) => item.source.method === 'eth_call' && object(item.request[0]) && String(item.request[0].to).toLowerCase() === MULTICALL3_ADDRESS.toLowerCase());
+        if ((unsupported.pools && marketVenuesFor(report.chainId) && multicalls && !unsupported.holders) || (unsupported.holders && report.evidence.some((item) => item.source.method === HOLDER_ACTIVITY_METHOD)))
+            throw new Error('An unsupported market section cannot carry receipts of that read.');
+        const derived = buildMarketSection({ policy: market, chainId: report.chainId, token: input.address, snapshotBlock: report.snapshot?.blockNumber ?? null, evidence: report.evidence, unsupported });
+        if (contentHash(derived) !== contentHash(report.market))
+            throw new Error('The market section differs from its derivation from the captured receipts.');
+    }
+    if (report.status !== 'failed') {
+        for (const [name, enabled, method, parameter] of [['owner', policy.readOwner, 'eth_call', '0x8da5cb5b'],
+            ...Object.entries(EIP1967_SLOTS).map(([name, slot]) => [name, policy.readProxySlots, 'eth_getStorageAt', slot])]) {
+            const control = report.controls[name];
+            if (!enabled) {
+                if (control.status !== 'skipped' || control.evidenceIds.length)
+                    throw new Error('Disabled research controls must remain explicitly skipped.');
+                continue;
+            }
+            if (control.status === 'skipped' || control.evidenceIds.length === 0)
+                throw new Error('A selected control has no captured read evidence.');
+            for (const reference of control.evidenceIds) {
+                const receipt = report.evidence.find(item => item.id === reference);
+                if (!receipt || receipt.source.method !== method || (method === 'eth_call' ? !object(receipt.request[0]) || receipt.request[0].data !== parameter : receipt.request[1] !== parameter))
+                    throw new Error('Control observation references another operation.');
+                if (control.status === 'observed' || control.status === 'not-detected') {
+                    if (receipt.completeness !== 'complete-for-request' || typeof receipt.result !== 'string' || !/^0x0{24}[a-fA-F0-9]{40}$/.test(receipt.result))
+                        throw new Error('Control observation has invalid captured address bytes.');
+                    const captured = `0x${receipt.result.slice(26)}`.toLowerCase();
+                    if (control.status === 'observed' ? typeof control.value !== 'string' || control.value.toLowerCase() !== captured : method !== 'eth_getStorageAt' || captured !== `0x${'0'.repeat(40)}`)
+                        throw new Error('Control observation differs from captured address bytes.');
+                }
+            }
+        }
+    }
+    if (report.usage.rpcCalls > manifest.limits.maximumRpcCalls || report.usage.maximumRpcCalls !== Math.min(16, manifest.limits.maximumRpcCalls, ...manifest.tools.map(tool => tool.maximumCalls)))
+        throw new Error('Report usage differs from its immutable budget.');
+    return report;
+}
+/** Synthetic answers for the market reads in the v2 suite: pools on the first listed venues, bounded balances and one transfer page. */
+function marketFixture(kind, chainId, method, params) {
+    if (method === HOLDER_ACTIVITY_METHOD) {
+        if (kind === 'holder-index-unavailable')
+            throw Object.assign(new Error('Synthetic index outage.'), { status: 503 });
+        const transfer = (to, block) => ({ blockNum: block, from: ADDRESS, to, rawContract: { address: ADDRESS, value: '0x1', decimal: '0x6' } });
+        return { transfers: kind === 'recent-recipients-not-holders' ? [transfer(POOL_A, '0x64'), transfer(RECIPIENT, '0x63'), transfer(RECIPIENT, '0x62')] : [] };
+    }
+    const request = params[0];
+    const { args } = decodeFunctionData({ abi: MULTICALL3_ABI, data: request.data });
+    const set = marketVenuesFor(chainId);
+    const plan = set ? discoveryPlan(set, ADDRESS) : [];
+    const pools = kind === 'multiple-pools' ? 2 : kind === 'recent-recipients-not-holders' ? 1 : 0;
+    const poolFor = (index) => {
+        const entry = plan[index];
+        if (!entry || !set)
+            return `0x${'0'.repeat(40)}`;
+        const first = plan.findIndex(item => item.venue === set.venues[0].id && item.quoteToken === set.quotes[0].address);
+        const second = plan.findIndex(item => item.venue === set.venues[1].id && item.quoteToken === set.quotes[0].address);
+        return pools >= 1 && index === first ? POOL_A : pools >= 2 && index === second ? POOL_B : `0x${'0'.repeat(40)}`;
+    };
+    const results = args[0].map((call) => {
+        const planned = plan.findIndex(item => item.callData === call.callData && item.factory.toLowerCase() === call.target.toLowerCase());
+        if (planned >= 0)
+            return { success: true, returnData: encode('address', poolFor(planned)) };
+        if (call.callData.startsWith(MARKET_SELECTORS.balanceOf))
+            return { success: true, returnData: encode('uint256', call.target.toLowerCase() === ADDRESS ? (call.callData.toLowerCase().endsWith(RECIPIENT.slice(2)) ? 42n : 1000000n) : 2000000000000000000n) };
+        if (call.callData === MARKET_SELECTORS.getReserves)
+            return { success: true, returnData: encodeAbiParameters(parseAbiParameters('uint112, uint112, uint32'), [1000000n, 2000000000000000000n, 1]) };
+        if (call.callData === MARKET_SELECTORS.slot0)
+            return { success: true, returnData: encodeAbiParameters(parseAbiParameters('uint160, int24, uint16, uint16, uint16, uint8, bool'), [79228162514264337593543950336n, 0, 1, 1, 1, 0, true]) };
+        if (call.callData === MARKET_SELECTORS.liquidity)
+            return { success: true, returnData: encode('uint128', 5000n) };
+        return { success: false, returnData: '0x' };
+    });
+    return encodeFunctionResult({ abi: MULTICALL3_ABI, functionName: 'aggregate3', result: results });
+}
+function marketExpectations(kind, report) {
+    const issues = [];
+    const market = report.market;
+    if (!market)
+        return ['A market-policy version must report its market section.'];
+    const pools = market.pools;
+    const holders = market.recentHolderActivity;
+    const venues = marketVenuesFor(report.chainId);
+    if (JSON.stringify(market).match(/\b(is|looks|appears)\s+safe\b|holder distribution:|concentration (is|of|:)\s*[0-9]|total liquidity (is|of|:)\s*[0-9]/i))
+        issues.push('The market section must not state a safety verdict, distribution, concentration or total liquidity.');
+    if (report.coverage.holders.status === 'observed' || report.coverage.liquidity.status === 'observed')
+        issues.push('Holder census and total liquidity must stay unknown.');
+    if (kind === 'multiple-pools' && venues && (pools.status !== 'observed' || pools.poolsFound !== 2 || pools.pools.some(pool => pool.tokenBalanceAtomic === null || pool.quoteBalanceAtomic === null)))
+        issues.push('Two listed-venue pools with observed balances were expected.');
+    if (kind === 'no-pools' && venues && (pools.status !== 'none-found' || !/not proof of no liquidity/.test(pools.reason)))
+        issues.push('No pools must be reported as none found on the listed venues, not as no liquidity.');
+    if (!venues && pools.status !== 'unsupported')
+        issues.push('A chain without listed venues must report pools as unsupported.');
+    if (kind === 'recent-recipients-not-holders' && (holders.status !== 'observed' || holders.basis !== 'recent-transfer-recipients-not-a-holder-list' || holders.accounts.length !== 2 || (venues && !holders.accounts[0]?.isDiscoveredPool) || holders.accounts[1]?.balanceAtomic !== '42'))
+        issues.push('Recent recipients must be listed once each, with a pool recipient flagged and exact balances.');
+    if (kind === 'holder-index-unavailable' && (holders.status !== 'error' || report.status === 'complete' || !holders.evidenceIds.length))
+        issues.push('An index failure must be an evidenced error and a partial report, never an empty list.');
+    return issues;
+}
+/** No creator-supplied fixture, executor, URL, time, or expected output is accepted. */
+export async function evaluateManifest(manifest) {
+    const suite = tokenResearchSuiteFor(manifest);
+    const snapshot = { kind: 'deterministic_fixture_evaluation', visibility: 'local_only', suiteVersion: suite.version,
+        suiteHash: suite.hash, manifestHash: contentHash(manifest), status: 'failed', summary: { passed: 0, total: 0, issues: [] }, fixtures: [],
+        limitations: ['Platform-selected synthetic RPC responses only; this is not a live chain investigation.', 'No model execution or model evaluation is included.',
+            'Passing fixtures do not prove security, market suitability, complete holder/control coverage, or production publication readiness.'] };
+    const supported = SupportedTokenResearcherManifestSchema.safeParse(manifest);
+    if (!supported.success)
+        snapshot.summary.issues.push(...supported.error.issues.slice(0, 20).map(issue => issue.message.slice(0, 300)));
+    if (manifest.chains.some(chain => !['ethereum', 'base', 'robinhood'].includes(chain)))
+        snapshot.summary.issues.push('Only Ethereum, Base and Robinhood Chain have platform evaluation coverage.');
+    if (snapshot.summary.issues.length)
+        return snapshot;
+    const policy = resolveResearchPolicy(manifest);
+    const cases = manifest.marketPolicy ? [...CASES, ...MARKET_CASES] : CASES;
+    for (const chain of manifest.chains)
+        for (const kind of cases) {
+            let calls = 0;
+            const chainId = evaluationChainId(chain);
+            const EVALUATION_ENV = evaluationEnv();
+            const input = ResearchInputSchema.parse({ chain, address: ADDRESS });
+            const transport = { async request(method, params) {
+                    calls++;
+                    if (kind === 'provider-failure')
+                        throw new Error('Synthetic provider outage.');
+                    if (manifest.marketPolicy && (method === HOLDER_ACTIVITY_METHOD || (method === 'eth_call' && object(params[0]) && String(params[0].to).toLowerCase() === MULTICALL3_ADDRESS.toLowerCase())))
+                        return marketFixture(kind, Number(chainId), method, params);
+                    if (method === 'eth_chainId')
+                        return kind === 'chain-mismatch' ? '0x7a69' : chainId;
+                    if (method === 'eth_getBlockByNumber')
+                        return { number: '0x64', timestamp: '0x65', hash: kind === 'snapshot-changed' && params[0] !== 'latest' ? `0x${'b'.repeat(64)}` : BLOCK_HASH };
+                    if (method === 'eth_getCode')
+                        return kind === 'no-contract' ? '0x' : '0x60806040';
+                    if (method === 'eth_getStorageAt')
+                        return kind === 'proxy-owner-gap' && params[1] === EIP1967_SLOTS.implementation ? `0x${'0'.repeat(24)}${IMPLEMENTATION.slice(2)}` : `0x${'0'.repeat(64)}`;
+                    if (method === 'eth_call' && object(params[0])) {
+                        if (params[0].data === '0x06fdde03')
+                            return encode('string', 'Platform evaluation fixture');
+                        if (params[0].data === '0x95d89b41')
+                            return encode('string', 'FIX');
+                        if (params[0].data === '0x313ce567')
+                            return encode('uint256', kind === 'nonstandard-decimals' ? 255n : 6n);
+                        if (params[0].data === '0x18160ddd')
+                            return encode('uint256', BigInt(LARGE_SUPPLY));
+                        if (params[0].data === '0x8da5cb5b') {
+                            if (kind === 'proxy-owner-gap')
+                                throw Object.assign(new Error('execution reverted'), { code: 3 });
+                            return encode('address', ADDRESS);
+                        }
+                    }
+                    throw new Error('Unexpected platform fixture request.');
+                } };
+            let report = null;
+            const issues = [];
+            try {
+                report = validateReportBinding(await researchToken(input, { manifest, transport, now: () => new Date(FIXED_TIME),
+                    env: EVALUATION_ENV }), manifest, input);
+                if (calls !== report.usage.rpcCalls || calls > manifest.limits.maximumRpcCalls || calls > manifest.tools[0].maximumCalls)
+                    issues.push('RPC ceiling or captured usage invariant failed.');
+                const failure = { 'no-contract': 'no-contract', 'provider-failure': 'provider-unavailable', 'chain-mismatch': 'chain-mismatch', 'snapshot-changed': 'snapshot-changed' }[kind];
+                if (failure) {
+                    if (report.status !== 'failed' || !report.errors.some(error => error.category === failure))
+                        issues.push(`Expected fail-closed ${failure}.`);
+                }
+                else {
+                    if (!canonicalMetadataObserved(report))
+                        issues.push('Required canonical metadata and code observations are missing.');
+                    if (report.metadata.totalSupplyAtomic.status !== 'observed' || report.metadata.totalSupplyAtomic.value !== LARGE_SUPPLY)
+                        issues.push('Atomic supply lost exact precision.');
+                    if (report.metadata.name.status !== 'observed' || report.metadata.name.value !== 'Platform evaluation fixture'
+                        || report.metadata.symbol.status !== 'observed' || report.metadata.symbol.value !== 'FIX')
+                        issues.push('Decoded token metadata differs from the platform fixture.');
+                    const expectedSupply = kind === 'nonstandard-decimals' ? `0.${'0'.repeat(255 - LARGE_SUPPLY.length)}${LARGE_SUPPLY}`.replace(/0+$/, '') : '90071992547409931234.56789';
+                    if (report.metadata.totalSupplyFormatted.status !== 'observed' || report.metadata.totalSupplyFormatted.value !== expectedSupply)
+                        issues.push('Formatted supply differs from exact atomic conversion.');
+                    if (report.contract.codeHash.status !== 'observed' || report.contract.codeHash.value !== keccak256('0x60806040'))
+                        issues.push('Bytecode hash differs from the captured bytes.');
+                    if (report.metadata.decimals.status !== 'observed' || report.metadata.decimals.value !== (kind === 'nonstandard-decimals' ? 255 : 6))
+                        issues.push('Decimals do not match the platform fixture.');
+                    const expectedStatus = (kind === 'proxy-owner-gap' && policy.readOwner) || (kind === 'holder-index-unavailable' && manifest.marketPolicy?.recentHolderActivity) ? 'partial' : 'complete';
+                    if (report.status !== expectedStatus)
+                        issues.push(`Expected ${expectedStatus} under the immutable read policy.`);
+                    if (manifest.marketPolicy)
+                        issues.push(...marketExpectations(kind, report));
+                    if (!policy.readOwner && report.controls.owner.status !== 'skipped')
+                        issues.push('Owner policy omission must be explicit.');
+                    if (!policy.readProxySlots && ['implementation', 'admin', 'beacon'].some(key => report.controls[key].status !== 'skipped'))
+                        issues.push('Proxy policy omissions must be explicit.');
+                    if (kind === 'proxy-owner-gap' && policy.readProxySlots && (report.controls.implementation.status !== 'observed' || String(report.controls.implementation.value).toLowerCase() !== IMPLEMENTATION))
+                        issues.push('Proxy fixture was not observed.');
+                }
+            }
+            catch {
+                issues.push('Executor or output validation failed under the immutable manifest limits and contract.');
+            }
+            snapshot.fixtures.push({ id: kind, chain, passed: issues.length === 0, issues, report, reportHash: report ? contentHash(report) : null, transportCalls: calls });
+        }
+    snapshot.summary.total = snapshot.fixtures.length;
+    snapshot.summary.passed = snapshot.fixtures.filter(result => result.passed).length;
+    snapshot.status = snapshot.summary.total > 0 && snapshot.summary.passed === snapshot.summary.total ? 'passed' : 'failed';
+    return snapshot;
+}

package/dist/packages/research/src/index.d.ts

@@ -0,0 +1,188 @@
+import { type Hex } from 'viem';
+import { type AttemptCompletion } from '../../providers/src/health.js';
+import { type ReadConfirmation } from '../../providers/src/snapshot.js';
+import { z } from 'zod';
+import { type AgentManifest, type ChainKey, type EvidenceItem, type FailureCategory, type TokenResearchReport } from '../../contracts/src/index.js';
+import { type SummaryFact } from '../../model/src/summary.js';
+import type { TariffTable } from '../../model/src/pricing.js';
+import { type ModelClient, type ModelUsageEntry } from '../../model/src/types.js';
+export declare const EIP1967_SLOTS: {
+    readonly implementation: "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc";
+    readonly admin: "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103";
+    readonly beacon: "0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50";
+};
+type Environment = Record<string, string | undefined>;
+export interface RpcTransport {
+    request(method: string, params: readonly unknown[], signal: AbortSignal): Promise<unknown>;
+    /** The endpoint that answered the most recent successful request, when the transport knows it (evidence attribution). */
+    servedBy?(): {
+        id: string;
+        host: string;
+    } | null;
+}
+/**
+ * Evidence provider label for an RPC read: the configured label for the configured endpoint, and the actual provider when another one answered
+ * (the keyed Alchemy archive endpoint, the chain's official RPC or a public fallback), so a report never credits one provider with another's data.
+ */
+export declare function servedProviderLabel(chain: string, configured: string, served: {
+    id: string;
+    host: string;
+} | null | undefined): string;
+export interface ResearchOptions {
+    env?: Environment;
+    manifest?: AgentManifest;
+    signal?: AbortSignal;
+    onProgress?: (event: {
+        step: string;
+        message: string;
+    }) => void | Promise<void>;
+    /** Durable workers must atomically reserve this read against the run-wide budget and fencing token. */
+    /** Hidden provider steps (`provider-<purpose>`) may return a completion that settles their permit from the observed outcome. */
+    beforeRpc?: (operation: {
+        method: string;
+        step: string;
+        maximumRpcCalls: number;
+    }) => void | AttemptCompletion | Promise<void | AttemptCompletion>;
+    onEvidence?: (evidence: EvidenceItem) => void | Promise<void>;
+    /** Receipts loaded by the runtime after checking owner, version, input, fencing and envelope hashes. `analysis` holds checkpointed summary results. */
+    restore?: {
+        manifestHash: string;
+        inputHash: string;
+        evidence: EvidenceItem[];
+        analysis?: {
+            nodeId: string;
+            stored: unknown;
+        }[];
+    };
+    /** Server-only transport injection for fixtures. Never accepted in a buyer input. */
+    transport?: RpcTransport;
+    /** Server-only clock for deterministic evaluation timestamps. Hard deadlines use real time. */
+    now?: () => Date;
+    /**
+     * E05 check for the 0.3.0 market reads (coverage rows evm.dex-pool-discovery and evm.recent-holder-activity). Defaults to the coverage table with this
+     * run's env; with an injected fixture transport and no explicit check, both reads are admitted. A refusal marks that section unsupported, never empty.
+     */
+    marketCoverage?: (chain: string, tool: string) => void;
+    /** Model client for the AI-assisted summary (refusal fallbacks off). Undefined: server configuration (AGENTEX_MODEL_ENABLED=true plus a key). null: disabled, reported unavailable without a request. */
+    modelClient?: ModelClient | null;
+    model?: string;
+    modelTariffs?: TariffTable;
+    /** Durable runtime permit for the one summary request. A throw coded RUN_MODEL_BUDGET_EXHAUSTED reports the summary unavailable; any other throw propagates. */
+    beforeModelRequest?: (operation: ResearchModelPermit) => void | Promise<void>;
+    /** Durable checkpoint of the summary outcome and metered usage, written once a request was sent. A throw propagates and the outcome is not used. */
+    onAnalysisResult?: (entry: ResearchAnalysisCheckpoint) => void | Promise<void>;
+}
+/** Model checkpoint node id for the Token Researcher AI-assisted summary. */
+export declare const RESEARCH_ANALYSIS_NODE_ID = "token-research-summary";
+export interface ResearchModelPermit {
+    nodeId: string;
+    step: number;
+    maxOutputTokens: number;
+    worstCaseMicrousd: number;
+    model: string;
+}
+declare const StoredSummarySchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        completed: "completed";
+        unavailable: "unavailable";
+    }>;
+    stopReason: z.ZodString;
+    reason: z.ZodNullable<z.ZodString>;
+    withheld: z.ZodNumber;
+    findings: z.ZodArray<z.ZodObject<{
+        claim: z.ZodString;
+        evidenceKeys: z.ZodArray<z.ZodString>;
+        confidence: z.ZodEnum<{
+            supported: "supported";
+            uncertain: "uncertain";
+        }>;
+    }, z.core.$strict>>;
+    usage: z.ZodObject<{
+        model: z.ZodString;
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        costMicrousd: z.ZodNumber;
+        costStatus: z.ZodOptional<z.ZodLiteral<"unresolved">>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type StoredResearchSummary = z.infer<typeof StoredSummarySchema>;
+export interface ResearchAnalysisCheckpoint {
+    nodeId: string;
+    checkpointKey: string;
+    value: StoredResearchSummary;
+    /** Current-run evidence ids cited by the stored findings (informational; restore maps stable evidence keys). */
+    evidenceIds: string[];
+    usage: {
+        modelTokens: number;
+        costMicrousd: number;
+    };
+    modelUsage: ModelUsageEntry[];
+    stopReason: string;
+    modelServed: string;
+}
+declare class ResearchFailure extends Error {
+    readonly category: FailureCategory;
+    constructor(category: FailureCategory, message: string);
+}
+declare const ERROR_MESSAGES: Record<FailureCategory, string>;
+declare function categoryOf(error: unknown, signal: AbortSignal): FailureCategory;
+declare function chainConfiguration(chain: ChainKey, env: Environment): {
+    chain: "ethereum" | "base" | "robinhood";
+    chainId: number;
+    rpcUrl: string | undefined;
+    configured: boolean;
+};
+/**
+ * E05 enforcement for token research. The executor's reads are covered by these registry tools; every quote, acceptance,
+ * run, recording and listing admission refuses a chain unless all of them pass `assertToolCoverage`. This check applies
+ * even when a fixture executor is injected, because coverage is a property of the chain, not of the transport.
+ */
+export declare const RESEARCH_COVERAGE_TOOLS: readonly string[];
+export { coverageSummary } from '../../providers/src/coverage.js';
+export declare function researchCoverageDenial(chain: string, options?: {
+    env?: Environment;
+    tools?: readonly string[];
+}): string | null;
+/** True once the contracts owner's report schema accepts this confirmation level. Admission flips automatically when it does. */
+export declare function researchReportAccepts(confirmation: ReadConfirmation): boolean;
+export declare const researchCoveredChains: (chains: readonly string[], env?: Environment) => string[];
+export declare function getResearchCoverage(env?: Environment): {
+    chain: "ethereum" | "base" | "robinhood";
+    chainId: number | null;
+    configured: boolean;
+    covered: boolean;
+    coverageDenial: string | null;
+    enabled: boolean;
+    verification: string;
+    capabilities: string[];
+    limitations: string[];
+}[];
+declare function makeTransport(url: string): RpcTransport;
+declare function quantity(value: unknown): bigint;
+declare function hexData(value: unknown): Hex;
+declare function blockData(value: unknown): {
+    blockNumber: string;
+    blockHash: string;
+    timestamp: string;
+};
+/** Shared read-only EVM primitives for other first-party executors (for example the transaction inspector). Behaviour is unchanged. */
+export { categoryOf as categorizeRpcFailure, ERROR_MESSAGES as FAILURE_MESSAGES, chainConfiguration as resolveChainConfiguration, makeTransport as createRpcTransport, ResearchFailure as EvmReadFailure, quantity as parseQuantity, hexData as parseHexData, blockData as parseBlockHeader };
+/**
+ * Stable across recovery attempts (which renumber rpc-N ids): the read's method, request and pinned snapshot. Header re-reads are keyed by
+ * request only: the same block-number request is recorded before the snapshot is pinned during recovery and after it at completion.
+ */
+export declare const summaryEvidenceKey: (item: EvidenceItem) => string;
+type KeyedFact = SummaryFact & {
+    key: string;
+};
+/**
+ * Citable facts for the summary: the pinned state reads and the snapshot header re-read at completion, each with the decoded
+ * observations that cite it. Volatile reads (chain identity, the moving latest head) are excluded so a recovery attempt rebuilds
+ * identical facts from its checkpointed receipts. Every string here is untrusted chain or provider data.
+ */
+export declare function summaryFacts(report: TokenResearchReport): {
+    facts: KeyedFact[];
+    context: Record<string, unknown>;
+};
+/** Purely read-only bounded inspection. Metadata is untrusted data and never instructions. */
+export declare function researchToken(rawInput: unknown, options?: ResearchOptions): Promise<TokenResearchReport>;