agentex-creator-sdk 1.0.0

package/dist/packages/research/src/index.js

@@ -0,0 +1,829 @@
+import { createPublicClient, decodeFunctionResult, encodeFunctionData, formatUnits, getAddress, http, keccak256, parseAbi } from 'viem';
+import { assertToolCoverage, CoverageError, coveredChains } from '../../providers/src/coverage.js';
+import { createChainReadTransport } from '../../providers/src/chain-transport.js';
+import { AttemptRefusedError } from '../../providers/src/health.js';
+import { createKeyedTransport, KEYED_PROVIDER_POLICIES, keyedCredentialAvailable, keyedProviderHost, RunUnitBudget } from '../../providers/src/keyed.js';
+import { CONFIRMATION_NOTES, READ_SNAPSHOT_POLICIES, readSnapshotPolicy, snapshotBlockTag } from '../../providers/src/snapshot.js';
+import { z } from 'zod';
+import { AgentManifestSchema, ANALYSIS_LABEL, EvidenceItemSchema, ModelUsageSchema, ResearchInputSchema, SupportedTokenResearcherManifestSchema, TOKEN_RESEARCHER_MANIFEST, TokenResearchReportSchema, contentHash, resolveAnalysisPolicy, resolveResearchPolicy } from '../../contracts/src/index.js';
+import { buildMarketSection, decodeAggregate, discoveryPlan, encodeDiscovery, HOLDER_ACTIVITY_DOCUMENTATION, HOLDER_ACTIVITY_METHOD, holderTransferRequest, marketBalancesData, marketCall, marketCallInScope, MARKET_COVERAGE_TOOLS, marketVenuesFor, MAXIMUM_MARKET_POOLS, MULTICALL3_ADDRESS, MULTICALL3_DOCUMENTATION, poolsFromDiscovery, recipientsFromTransfers } from '../../contracts/src/token-market.js';
+import { checkSummaryFindings, groundingStringsOf, runEvidenceSummary } from '../../model/src/summary.js';
+import { DEFAULT_MODEL_ID } from '../../model/src/types.js';
+const ABI = parseAbi(['function name() view returns (string)', 'function symbol() view returns (string)', 'function decimals() view returns (uint8)', 'function totalSupply() view returns (uint256)', 'function owner() view returns (address)']);
+export const EIP1967_SLOTS = {
+    implementation: '0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc',
+    admin: '0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103',
+    beacon: '0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50',
+};
+const ZERO_ADDRESS = `0x${'0'.repeat(40)}`;
+const RPC_DOCUMENTATION = 'https://ethereum.org/en/developers/docs/apis/json-rpc/';
+const RH_DOCUMENTATION = 'https://docs.robinhood.com/chain/connecting/';
+/**
+ * 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 function servedProviderLabel(chain, configured, served) {
+    if (!served || served.id === 'primary' || served.id === 'configured-rpc')
+        return configured;
+    if (served.id === 'alchemy' || /(^|\.)alchemy\.com$/.test(served.host))
+        return `${chain}-alchemy`;
+    if (served.id === 'official-rpc')
+        return `${chain}-official-rpc`;
+    // Evidence provider labels allow only letters, digits, dots, colons and hyphens.
+    return `${chain}-fallback-rpc:${served.host.replace(/[^a-zA-Z0-9.:-]/g, '')}`.slice(0, 120);
+}
+/** Model checkpoint node id for the Token Researcher AI-assisted summary. */
+export const RESEARCH_ANALYSIS_NODE_ID = 'token-research-summary';
+const StoredSummarySchema = z.strictObject({
+    status: z.enum(['completed', 'unavailable']), stopReason: z.string().min(1).max(40), reason: z.string().min(1).max(500).nullable(), withheld: z.number().int().min(0).max(12),
+    findings: z.array(z.strictObject({ claim: z.string().min(1).max(600), evidenceKeys: z.array(z.string().regex(/^[a-f0-9]{64}$/)).min(1).max(8), confidence: z.enum(['supported', 'uncertain']) })).max(12),
+    usage: ModelUsageSchema,
+});
+/** Resolution of an earlier attempt's summary request, attached by the runtime to its one-request refusal (`priorRequest`). */
+const PriorRequestSchema = z.strictObject({ status: z.enum(['unresolved', 'metered']), model: z.string().min(1).max(64), inputTokens: z.number().int().nonnegative(), outputTokens: z.number().int().nonnegative(), costMicrousd: z.number().int().nonnegative() });
+class ResearchFailure extends Error {
+    category;
+    constructor(category, message) {
+        super(message);
+        this.category = category;
+        this.name = 'ResearchFailure';
+    }
+}
+class RuntimeInterruption extends Error {
+    original;
+    constructor(original) {
+        super('The runtime refused or could not persist this operation.');
+        this.original = original;
+    }
+}
+const ERROR_MESSAGES = {
+    'provider-unavailable': 'The configured RPC provider could not complete this request.', 'history-unavailable': 'The RPC provider does not have the state or metadata needed at the pinned historical block.', 'rate-limited': 'The RPC provider rate limited this request.', timeout: 'The bounded research deadline or RPC timeout was reached.', cancelled: 'The run was cancelled; no new reads were started.', unsupported: 'This operation or workflow is not supported by this executor.', 'contract-reverted': 'The contract call reverted or the requested method is not exposed.', 'invalid-response': 'The provider or contract returned data outside the expected schema.', 'chain-mismatch': 'The configured RPC returned a different chain identity.', 'snapshot-changed': 'The pinned block changed during the investigation; findings are not a consistent canonical snapshot.', 'limit-exceeded': 'The immutable execution or output budget was reached.', unconfigured: 'A verified server-side provider configuration is not available for this chain.', 'no-contract': 'No contract bytecode was present at the supplied address and snapshot.',
+};
+function categoryOf(error, signal) {
+    if (error instanceof ResearchFailure)
+        return error.category;
+    if (signal.aborted)
+        return signal.reason?.name === 'TimeoutError' ? 'timeout' : 'cancelled';
+    const parts = [];
+    let current = error;
+    for (let i = 0; current && typeof current === 'object' && i < 8; i++) {
+        const item = current;
+        if (item.status === 429 || item.code === -32005 || item.category === 'rate-limited')
+            return 'rate-limited';
+        // Keyed provider errors (packages/providers keyed.ts) carry their classification as `category` and the JSON-RPC code as `rpcCode`.
+        if (item.code === 3 || item.rpcCode === 3 || item.category === 'execution-result')
+            return 'contract-reverted';
+        if (item.category === 'history-unavailable')
+            return 'history-unavailable';
+        if (item.category === 'budget-exhausted' || item.category === 'limit-exceeded')
+            return 'limit-exceeded';
+        if (item.category === 'credential-required')
+            return 'unconfigured';
+        if (item.category === 'unsupported' || item.category === 'plan-restricted')
+            return 'unsupported';
+        parts.push(item.name ?? '', item.message ?? '');
+        current = item.cause;
+    }
+    const text = parts.join(' ').toLowerCase();
+    if (/429|rate limit|too many requests/.test(text))
+        return 'rate-limited';
+    if (/revert|execution reverted/.test(text))
+        return 'contract-reverted';
+    if (/missing trie|historical state|state.*prun|archive|metadata is not found|header not found/.test(text))
+        return 'history-unavailable';
+    if (/timeout|timed out/.test(text))
+        return 'timeout';
+    if (/responsebodysize|response body.*size/.test(text))
+        return 'limit-exceeded';
+    return 'provider-unavailable';
+}
+function validRpcUrl(value) {
+    if (!value)
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && !url.username && !url.password && !/^(localhost|127\.|0\.0\.0\.0|\[?::1\]?)/i.test(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function chainConfiguration(chain, env) {
+    const rpcUrl = env[`${chain.toUpperCase()}_RPC_URL`];
+    const chainId = chain === 'ethereum' ? 1 : chain === 'base' ? 8453 : Number(env.ROBINHOOD_CHAIN_ID);
+    const rhVerified = chain !== 'robinhood' || ([4663, 46630].includes(chainId) && env.ROBINHOOD_DOCUMENTATION_URL === RH_DOCUMENTATION && Number.isFinite(Date.parse(env.ROBINHOOD_VERIFIED_AT ?? '')) && Date.parse(env.ROBINHOOD_VERIFIED_AT ?? '') <= Date.now());
+    // A configured RPC, a server-side Alchemy key for a chain Alchemy serves, or Robinhood's documented official RPC.
+    const keyedChain = chain === 'robinhood' && chainId === 46630 ? 'robinhood-testnet' : chain;
+    const providerAvailable = validRpcUrl(rpcUrl) || (keyedProviderHost('alchemy', keyedChain) !== null && keyedCredentialAvailable('alchemy', env)) || chain === 'robinhood';
+    return { chain, chainId, rpcUrl, configured: providerAvailable && rhVerified };
+}
+/**
+ * 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 const RESEARCH_COVERAGE_TOOLS = Object.freeze(['evm.token-metadata@0.1.0', 'evm.contract-inspect@0.1.0', 'evm.permissions@0.1.0']);
+export { coverageSummary } from '../../providers/src/coverage.js';
+export function researchCoverageDenial(chain, options = {}) {
+    for (const tool of options.tools ?? RESEARCH_COVERAGE_TOOLS) {
+        try {
+            assertToolCoverage(chain, tool, { env: options.env ?? process.env });
+        }
+        catch (error) {
+            if (error instanceof CoverageError)
+                return `Token research is not covered on ${chain}: ${error.message}`;
+            throw error;
+        }
+    }
+    const policy = READ_SNAPSHOT_POLICIES[chain];
+    const refused = policy ? [...new Set(policy.tags.map((tag) => policy.confirmationOf[tag]))].filter((confirmation) => !researchReportAccepts(confirmation)) : [];
+    if (refused.length)
+        return `Token research is not covered on ${chain}: the Token Researcher report contract in packages/contracts does not yet accept ${refused.join(' or ')} snapshots, so a report could not state its confirmation level honestly.`;
+    return null;
+}
+/** True once the contracts owner's report schema accepts this confirmation level. Admission flips automatically when it does. */
+export function researchReportAccepts(confirmation) {
+    const snapshot = TokenResearchReportSchema.shape?.snapshot;
+    return Boolean(snapshot?.safeParse({ blockNumber: '1', blockHash: `0x${'0'.repeat(64)}`, timestamp: '1', finality: confirmation, canonicality: 'unchecked' }).success);
+}
+export const researchCoveredChains = (chains, env = process.env) => coveredChains(chains, RESEARCH_COVERAGE_TOOLS, { env });
+export function getResearchCoverage(env = process.env) {
+    return ['ethereum', 'base', 'robinhood'].map((chain) => {
+        const config = chainConfiguration(chain, env);
+        const coverageDenial = researchCoverageDenial(chain, { env });
+        return { chain, chainId: Number.isSafeInteger(config.chainId) && config.chainId > 0 ? config.chainId : null, configured: config.configured, covered: coverageDenial === null, coverageDenial, enabled: config.configured && coverageDenial === null, verification: 'identity-checked-on-every-run', capabilities: ['erc20-metadata', 'bytecode', 'eip1967-slots', 'owner-method-probe'], limitations: ['Provider configuration is not live coverage evidence.', ...(chain === 'robinhood' ? ['Robinhood Chain reads the latest block pinned by block hash; the official public RPC served hash-pinned state on 2026-09-14.'] : []), 'Holder and liquidity indexes are not connected.', 'Authority inspection is incomplete.', 'Solana is not an EVM adapter.'] };
+    });
+}
+function makeTransport(url) {
+    const client = createPublicClient({ transport: http(url, { retryCount: 0, timeout: 8000, maxResponseBodySize: 65536, fetchOptions: { redirect: 'error' } }), cacheTime: 0 });
+    return { request: (method, params, signal) => client.request({ method, params }, { signal, retryCount: 0 }) };
+}
+const unknown = (reason, evidenceIds = []) => ({ status: 'unknown', reason, evidenceIds });
+const observed = (value, evidenceId, note) => ({ status: 'observed', value, evidenceIds: [evidenceId], ...(note ? { note } : {}) });
+const unsupported = (reason) => ({ status: 'unsupported', reason, evidenceIds: [] });
+const skipped = (control) => ({ status: 'skipped', reason: `Intentionally skipped by the immutable research policy (${control}=false); absence of privileged controls is not established.`, evidenceIds: [] });
+function quantity(value) {
+    if (typeof value !== 'string' || !/^0x(?:0|[1-9a-fA-F][a-fA-F0-9]*)$/.test(value) || value.length > 66)
+        throw new ResearchFailure('invalid-response', ERROR_MESSAGES['invalid-response']);
+    return BigInt(value);
+}
+function hexData(value) {
+    if (typeof value !== 'string' || !/^0x(?:[a-fA-F0-9]{2})*$/.test(value))
+        throw new ResearchFailure('invalid-response', ERROR_MESSAGES['invalid-response']);
+    return value;
+}
+function blockData(value) {
+    if (!value || typeof value !== 'object')
+        throw new ResearchFailure('invalid-response', ERROR_MESSAGES['invalid-response']);
+    const block = value;
+    if (typeof block.hash !== 'string' || !/^0x[a-fA-F0-9]{64}$/.test(block.hash))
+        throw new ResearchFailure('invalid-response', ERROR_MESSAGES['invalid-response']);
+    return { blockNumber: quantity(block.number).toString(), blockHash: block.hash, timestamp: quantity(block.timestamp).toString() };
+}
+/** 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 };
+const ANALYSIS_REPORT_LIMITATION = 'Deterministic observations and findings in this report come only from the recorded RPC evidence. The separately labelled AI-assisted summary is one bounded model request over that same evidence; it makes no chain reads and is not a security review.';
+const SUMMARY_SELECTORS = { '0x06fdde03': 'name()', '0x95d89b41': 'symbol()', '0x313ce567': 'decimals()', '0x18160ddd': 'totalSupply()', '0x8da5cb5b': 'owner()' };
+const STATE_READS = new Set(['eth_getCode', 'eth_call', 'eth_getStorageAt']);
+const decimalQuantity = (value) => typeof value === 'string' && /^0x[0-9a-fA-F]{1,64}$/.test(value) ? BigInt(value).toString() : null;
+/**
+ * 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 const summaryEvidenceKey = (item) => item.source.method === 'eth_getBlockByNumber'
+    ? contentHash({ method: item.source.method, request: item.request })
+    : contentHash({ method: item.source.method, request: item.request, snapshot: item.snapshot ? { blockNumber: item.snapshot.blockNumber, blockHash: item.snapshot.blockHash.toLowerCase() } : null });
+/**
+ * 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 function summaryFacts(report) {
+    const snapshot = report.snapshot;
+    const numberTag = snapshot ? `0x${BigInt(snapshot.blockNumber).toString(16)}` : null;
+    const observations = ['metadata', 'contract', 'controls'].flatMap((group) => Object.entries(report[group]).map(([field, observation]) => ({ field: `${group}.${field}`, observation })));
+    const chosen = new Map();
+    for (const item of report.evidence) {
+        const state = (STATE_READS.has(item.source.method) || item.source.method === HOLDER_ACTIVITY_METHOD) && item.snapshot !== null;
+        const header = item.source.method === 'eth_getBlockByNumber' && numberTag !== null && item.request[0] === numberTag;
+        if (state || header)
+            chosen.set(summaryEvidenceKey(item), item);
+    }
+    const facts = [...chosen].map(([key, item]) => {
+        if (item.source.method === 'eth_getBlockByNumber') {
+            const block = item.result !== null && typeof item.result === 'object' && !Array.isArray(item.result) ? item.result : {};
+            return { key, evidenceId: item.id, completeness: item.completeness, summary: { read: 'snapshot block header', method: item.source.method, block: { number: decimalQuantity(block.number), hash: typeof block.hash === 'string' ? block.hash : null, timestamp: decimalQuantity(block.timestamp) } } };
+        }
+        const call = item.request[0] !== null && typeof item.request[0] === 'object' && !Array.isArray(item.request[0]) ? item.request[0] : null;
+        const slot = item.source.method === 'eth_getStorageAt' ? Object.entries(EIP1967_SLOTS).find(([, value]) => value === item.request[1])?.[0] ?? 'unrecognised' : null;
+        // 0.3.0 market receipts are summarised from the derived market section, never from raw multicall bytes.
+        const marketRead = item.source.method === HOLDER_ACTIVITY_METHOD ? 'recent transfer recipients (provider index page, not a holder list)'
+            : typeof call?.to === 'string' && call.to.toLowerCase() === MULTICALL3_ADDRESS.toLowerCase() ? 'DEX pool lookup or pool and recipient balances (Multicall3)' : null;
+        const read = marketRead ?? (item.source.method === 'eth_getCode' ? 'contract bytecode' : slot ? `EIP-1967 ${slot} slot` : SUMMARY_SELECTORS[String(call?.data ?? '').toLowerCase()] ?? 'contract call');
+        const cited = observations.filter(({ observation }) => observation.evidenceIds.includes(item.id))
+            .map(({ field, observation }) => observation.status === 'observed' ? { field, status: observation.status, value: observation.value } : { field, status: observation.status, reason: observation.reason });
+        const findings = report.findings.filter((finding) => finding.evidenceIds.includes(item.id)).map((finding) => finding.message);
+        const pools = report.market?.pools.pools.filter((pool) => pool.evidenceIds.includes(item.id)).map((pool) => ({ venue: pool.venue, pool: pool.address, quoteToken: pool.quoteSymbol, feeTier: pool.feeTier, stable: pool.stable, tokenBalanceAtomic: pool.tokenBalanceAtomic, quoteBalanceAtomic: pool.quoteBalanceAtomic })) ?? [];
+        const recipients = report.market?.recentHolderActivity.accounts.filter((account) => account.evidenceIds.includes(item.id)).map((account) => ({ recipient: account.address, balanceAtomic: account.balanceAtomic, isDiscoveredPool: account.isDiscoveredPool })) ?? [];
+        return { key, evidenceId: item.id, completeness: item.completeness, summary: { read, method: item.source.method, target: report.input.address, block: item.snapshot ? { number: item.snapshot.blockNumber, hash: item.snapshot.blockHash } : null, observations: cited, ...(findings.length ? { deterministicFindings: findings } : {}),
+                ...(pools.length ? { pools } : {}), ...(recipients.length ? { recentRecipientsNotHolders: recipients } : {}) } };
+    });
+    const context = {
+        chain: report.input.chain, chainId: report.chainId, tokenAddress: report.input.address, deterministicReportStatus: report.status, snapshotBlock: snapshot?.blockNumber ?? null,
+        errors: report.errors.map((error) => ({ step: error.step, category: error.category })),
+        notInspected: [...Object.entries(report.coverage).map(([field, observation]) => ({ field: `coverage.${field}`, status: observation.status })),
+            ...['mintAuthority', 'freezeAuthority', 'upgradeability'].map((field) => ({ field: `controls.${field}`, status: report.controls[field].status }))],
+    };
+    return { facts, context };
+}
+function summaryCheckpointKey(report, policy, model, facts, context) {
+    const ordered = facts.map(({ key, completeness, summary }) => ({ key, completeness, summary })).sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+    return contentHash({ scope: 'agentex.token-research-summary.v1', manifestHash: report.manifestHash, inputHash: contentHash(report.input), model, policy: { ...policy }, context, facts: ordered });
+}
+/** Reuses a checkpointed outcome only when it matches these exact facts and every stored citation still passes the provenance gate. */
+function restoreSummary(stored, checkpointKey, facts) {
+    const parsed = z.object({ checkpointKey: z.string(), value: StoredSummarySchema }).safeParse(stored);
+    if (!parsed.success || parsed.data.checkpointKey !== checkpointKey)
+        return null;
+    const { value } = parsed.data;
+    if (value.status !== 'completed' && value.findings.length)
+        return null;
+    const idByKey = new Map(facts.map((fact) => [fact.key, fact.evidenceId]));
+    const findings = [];
+    for (const finding of value.findings) {
+        const ids = finding.evidenceKeys.map((key) => idByKey.get(key));
+        if (ids.some((id) => id === undefined))
+            return null;
+        findings.push({ claim: finding.claim, evidenceIds: [...new Set(ids)], confidence: finding.confidence });
+    }
+    const known = new Map(facts.map((fact) => [fact.evidenceId, { strings: groundingStringsOf(fact.summary), completeness: fact.completeness }]));
+    const checked = checkSummaryFindings(findings, known);
+    if (checked.rejected.length || checked.findings.length !== findings.length || checked.findings.some((finding, index) => finding.confidence !== findings[index].confidence))
+        return null;
+    return { value, findings: checked.findings };
+}
+function applySummary(report, value, findings) {
+    const analysis = report.analysis;
+    analysis.status = value.status;
+    analysis.model = value.usage.model;
+    analysis.findings = value.status === 'completed' ? findings : [];
+    if (value.status === 'completed')
+        delete analysis.unavailableReason;
+    else
+        analysis.unavailableReason = value.reason ?? 'The AI-assisted summary did not complete.';
+    report.usage.model = { ...value.usage };
+    if (value.withheld)
+        report.limitations.push(`${value.withheld} AI-assisted claim${value.withheld === 1 ? ' was' : 's were'} withheld because ${value.withheld === 1 ? 'it' : 'they'} cited evidence outside this report, used values absent from the cited evidence, or gave a verdict or advice.`);
+}
+/**
+ * Server model client for the summary, with the same gate as workflow AI analysis: AGENTEX_MODEL_ENABLED=true and a server-side Anthropic key.
+ * Refusal fallbacks are off, because a second billed model hop would break the single-request worst-case bound.
+ */
+async function serverSummaryClient(env) {
+    if (env.AGENTEX_MODEL_ENABLED !== 'true')
+        return null;
+    const { createClaudeModelClient, resolveAnthropicKey } = await import('../../model/src/claude.js');
+    const apiKey = resolveAnthropicKey(env);
+    return apiKey ? createClaudeModelClient({ apiKey, fallbacks: false, timeoutMs: 45_000 }) : null;
+}
+async function attachAnalysis(report, policy, options, signal, deadlineAt) {
+    const model = options.model ?? DEFAULT_MODEL_ID;
+    const analysis = report.analysis;
+    const notRun = (reason) => { analysis.status = 'skipped'; analysis.findings = []; analysis.unavailableReason = reason; };
+    if (report.status === 'failed')
+        return notRun('The deterministic report did not complete, so no AI-assisted summary was requested.');
+    if (signal.aborted)
+        return notRun('The run was cancelled or reached its deadline before the AI-assisted summary was requested.');
+    const { facts, context } = summaryFacts(report);
+    const checkpointKey = summaryCheckpointKey(report, policy, model, facts, context);
+    for (const entry of options.restore?.analysis ?? []) {
+        if (entry?.nodeId !== RESEARCH_ANALYSIS_NODE_ID)
+            continue;
+        const restored = restoreSummary(entry.stored, checkpointKey, facts);
+        if (!restored)
+            continue;
+        applySummary(report, restored.value, restored.findings);
+        report.limitations.push('The AI-assisted summary was restored from this run\'s checkpoint after its citations were re-checked; no second model request was made.');
+        return;
+    }
+    if (Date.now() > deadlineAt - 5000)
+        return notRun('Too little of the run deadline remained to request the AI-assisted summary.');
+    let result;
+    try {
+        result = await runEvidenceSummary({ context, facts: facts.map(({ evidenceId, summary, completeness }) => ({ evidenceId, summary, completeness })), limits: { maximumOutputTokens: policy.maximumOutputTokens, maximumCostMicrousd: policy.maximumCostMicrousd }, signal }, { client: options.modelClient !== undefined ? options.modelClient : await serverSummaryClient(options.env ?? process.env), model, ...(options.modelTariffs ? { tariffs: options.modelTariffs } : {}),
+            ...(options.beforeModelRequest ? { beforeModelRequest: (permit) => options.beforeModelRequest({ nodeId: RESEARCH_ANALYSIS_NODE_ID, step: 1, ...permit }) } : {}) });
+    }
+    catch (error) {
+        if (error?.code !== 'RUN_MODEL_BUDGET_EXHAUSTED')
+            throw error;
+        analysis.status = 'unavailable';
+        analysis.findings = [];
+        const prior = PriorRequestSchema.safeParse(error.priorRequest);
+        if (!prior.success) {
+            analysis.unavailableReason = 'The run model budget refused the AI-assisted summary request; no new request was sent.';
+            return;
+        }
+        const { status, model: priorModel, inputTokens, outputTokens, costMicrousd } = prior.data;
+        analysis.model = priorModel;
+        if (status === 'unresolved') {
+            // Never report zero for a request that may have been billed: carry the reserved maximum that settlement also counts.
+            const reserved = Math.max(1, costMicrousd);
+            report.usage.model = { model: priorModel, inputTokens: 0, outputTokens: 0, costMicrousd: reserved, costStatus: 'unresolved' };
+            analysis.unavailableReason = `An earlier attempt sent the AI-assisted summary request but stopped before recording its outcome. Its cost is unresolved, at most ${reserved} micro-USD as reserved; no new request was sent.`;
+        }
+        else {
+            report.usage.model = { model: priorModel, inputTokens, outputTokens, costMicrousd };
+            analysis.unavailableReason = 'An earlier attempt already made the AI-assisted summary request and recorded its cost, but its outcome could not be reused for this evidence; no new request was sent.';
+        }
+        return;
+    }
+    if (result.status === 'skipped')
+        return notRun(result.reason ?? 'The AI-assisted summary was not requested.');
+    const keyById = new Map(facts.map((fact) => [fact.evidenceId, fact.key]));
+    const value = { status: result.status === 'completed' ? 'completed' : 'unavailable', stopReason: result.stopReason, reason: result.reason, withheld: Math.min(12, result.rejected.length),
+        findings: result.findings.map((finding) => ({ claim: finding.claim, evidenceKeys: finding.evidenceIds.map((id) => keyById.get(id)), confidence: finding.confidence })),
+        usage: { model: result.usage.model, inputTokens: result.usage.inputTokens, outputTokens: result.usage.outputTokens, costMicrousd: result.usage.costMicrousd } };
+    if (result.requestSent)
+        await options.onAnalysisResult?.({ nodeId: RESEARCH_ANALYSIS_NODE_ID, checkpointKey, value, evidenceIds: [...new Set(result.findings.flatMap((finding) => finding.evidenceIds))],
+            usage: { modelTokens: result.usage.inputTokens + result.usage.outputTokens, costMicrousd: result.usage.costMicrousd }, modelUsage: result.usage.entries, stopReason: result.usage.stopReason ?? result.stopReason, modelServed: result.usage.model });
+    applySummary(report, value, result.findings);
+}
+/** Purely read-only bounded inspection. Metadata is untrusted data and never instructions. */
+export async function researchToken(rawInput, options = {}) {
+    const input = ResearchInputSchema.parse(rawInput);
+    const manifest = AgentManifestSchema.parse(options.manifest ?? TOKEN_RESEARCHER_MANIFEST);
+    const policy = resolveResearchPolicy(manifest);
+    const analysisPolicy = resolveAnalysisPolicy(manifest);
+    const env = options.env ?? process.env;
+    const config = chainConfiguration(input.chain, env);
+    // Per-chain read-snapshot policy: the latest block, pinned by number (Ethereum, Base) or by block hash (Robinhood). Never a finality wait.
+    const readPolicy = readSnapshotPolicy(input.chain === 'robinhood' && config.chainId === 46630 ? 'robinhood-testnet' : input.chain);
+    const stateTag = (block) => snapshotBlockTag({ ...block, pinBy: readPolicy.pinBy });
+    let confirmation = 'sequencer-confirmed';
+    const now = options.now ?? (() => new Date());
+    const started = now().getTime();
+    const deadlineAt = Date.now() + Math.min(60000, manifest.limits.maximumDurationMs);
+    const deadline = AbortSignal.timeout(Math.min(60000, manifest.limits.maximumDurationMs));
+    const signal = options.signal ? AbortSignal.any([options.signal, deadline]) : deadline;
+    const report = {
+        schemaVersion: 'agentex.token-research.v1', agentVersion: manifest.version, manifestHash: contentHash(manifest), researchPolicy: policy, input, status: 'failed', generatedAt: now().toISOString(), chainId: Number.isSafeInteger(config.chainId) && config.chainId > 0 ? config.chainId : null, snapshot: null,
+        metadata: { name: unknown('Not read.'), symbol: unknown('Not read.'), decimals: unknown('Not read.'), totalSupplyAtomic: unknown('Not read.'), totalSupplyFormatted: unknown('Decimals and supply must both be observed.') },
+        contract: { codePresent: unknown('Not read.'), codeHash: unknown('Not read.'), sourceVerification: unsupported('A verified source-code provider is not connected.') },
+        controls: { implementation: policy.readProxySlots ? unknown('Not read.') : skipped('readProxySlots'), admin: policy.readProxySlots ? unknown('Not read.') : skipped('readProxySlots'), beacon: policy.readProxySlots ? unknown('Not read.') : skipped('readProxySlots'), owner: policy.readOwner ? unknown('Not read.') : skipped('readOwner'), mintAuthority: unknown('Generic ERC-20 RPC calls cannot enumerate mint permissions.'), freezeAuthority: unknown('Generic ERC-20 RPC calls cannot enumerate freeze or denylist permissions.'), upgradeability: unknown(policy.readProxySlots ? 'Slot probes cannot rule out custom proxies or other upgrade mechanisms.' : 'Standard proxy-slot reads were intentionally skipped by research policy. Upgrade mechanisms have not been inspected.') },
+        coverage: { holders: unsupported('No complete holder index is connected; distribution is not calculated.'), liquidity: unsupported('No supported DEX pool index is connected; liquidity is not calculated.'), deployment: unsupported('No creation-transaction index is connected; issuer identity is not inferred.'), historicalActivity: unsupported('This scope performs no historical activity queries.') },
+        findings: [], limitations: [analysisPolicy ? ANALYSIS_REPORT_LIMITATION : 'This report records deterministic reads of token metadata and contract controls. It contains no AI-written investigation or narrative.', 'Token names and symbols are untrusted labels; they do not authenticate an issuer or payment asset.', 'Empty EIP-1967 slots and a missing owner() method do not establish an immutable contract or the absence of privileged controls.', 'A returned owner() address is a contract response, not proof of exclusive control or a human identity.', CONFIRMATION_NOTES['sequencer-confirmed'], 'No security score, investment recommendation or complete holder/liquidity assessment is produced.'],
+        errors: [], evidence: [], usage: { rpcCalls: 0, maximumRpcCalls: Math.min(16, manifest.limits.maximumRpcCalls, ...manifest.tools.map((tool) => tool.maximumCalls)), elapsedMs: 0, modelTokens: 0, providerCostAtomic: null, providerCostStatus: 'unpriced' },
+    };
+    if (!policy.readOwner || !policy.readProxySlots)
+        report.limitations.push('Complete status refers to the selected inspection policy only. Intentionally skipped controls carry no observation or evidence of absence.');
+    if (analysisPolicy) {
+        const requestedModel = (options.model ?? DEFAULT_MODEL_ID).slice(0, 64);
+        report.analysis = { label: ANALYSIS_LABEL, status: 'skipped', model: requestedModel, findings: [], unavailableReason: 'The AI-assisted summary runs only after the deterministic reads finish.' };
+        report.usage.model = { model: requestedModel, inputTokens: 0, outputTokens: 0, costMicrousd: 0 };
+    }
+    // 0.3.0 market reads: availability is decided before any read, and an unavailable section is reported unsupported with its reason.
+    const marketPolicy = manifest.marketPolicy;
+    const marketUnsupported = { pools: null, holders: null };
+    if (marketPolicy) {
+        const coverageChain = input.chain === 'robinhood' && config.chainId === 46630 ? 'robinhood-testnet' : input.chain;
+        const availability = (tool) => {
+            if (!options.marketCoverage && options.transport)
+                return null;
+            try {
+                (options.marketCoverage ?? ((chain, ref) => { assertToolCoverage(chain, ref, { env }); }))(coverageChain, tool);
+                return null;
+            }
+            catch (error) {
+                if (error instanceof CoverageError)
+                    return `Not available on this server for ${coverageChain}: ${error.message}`;
+                throw error;
+            }
+        };
+        if (marketPolicy.discoverPools)
+            marketUnsupported.pools = availability(MARKET_COVERAGE_TOOLS.pools);
+        if (marketPolicy.recentHolderActivity)
+            marketUnsupported.holders = availability(MARKET_COVERAGE_TOOLS.holders);
+        report.marketPolicy = { ...marketPolicy };
+        report.market = buildMarketSection({ policy: marketPolicy, chainId: report.chainId, token: input.address, snapshotBlock: null, evidence: [], unsupported: marketUnsupported });
+        report.coverage.holders = { status: 'unknown', reason: 'No holder census or distribution is computed. Balances of recent transfer recipients are shown in the market section; they are not a holder list.', evidenceIds: [] };
+        report.coverage.liquidity = { status: 'unknown', reason: 'Total liquidity is not computed. Pools found on the listed venues are shown in the market section with the token balances they hold.', evidenceIds: [] };
+    }
+    let transport;
+    /** 0.3.0 only: the keyed Alchemy host for the transfer index, which no other endpoint can serve. */
+    let indexTransport = null;
+    const restoredReads = new Map();
+    let restoredSnapshot = null;
+    const addError = (category, step, evidenceId) => { report.errors.push({ category, message: ERROR_MESSAGES[category], step, ...(evidenceId ? { evidenceId } : {}) }); };
+    // Hidden provider work (failover retries, identity checks, cross-checks) needs its own runtime permit and counts against the RPC budget.
+    let prepaidAttempt = false;
+    const providerAttempt = async ({ method, purpose }) => {
+        if (prepaidAttempt) {
+            prepaidAttempt = false;
+            return;
+        }
+        if (report.usage.rpcCalls >= report.usage.maximumRpcCalls)
+            throw new ResearchFailure('limit-exceeded', 'The RPC call budget was exhausted by provider failover work.');
+        let complete;
+        try {
+            complete = await options.beforeRpc?.({ method, step: `provider-${purpose}`, maximumRpcCalls: report.usage.maximumRpcCalls });
+        }
+        catch (error) {
+            throw new RuntimeInterruption(error);
+        }
+        report.usage.rpcCalls++;
+        if (!complete)
+            return;
+        const settle = complete;
+        return async (result) => { try {
+            await settle(result);
+        }
+        catch (error) {
+            throw new RuntimeInterruption(error);
+        } };
+    };
+    const call = async (method, params, step) => {
+        if (signal.aborted)
+            throw new ResearchFailure(signal.reason?.name === 'TimeoutError' ? 'timeout' : 'cancelled', 'Research interrupted.');
+        const requestKey = contentHash({ method, params });
+        const cached = report.snapshot ? restoredReads.get(requestKey) : undefined;
+        if (cached) {
+            try {
+                await options.onProgress?.({ step, message: `Reusing checkpointed ${step} at the verified original snapshot.` });
+            }
+            catch (error) {
+                throw new RuntimeInterruption(error);
+            }
+            if (signal.aborted)
+                throw new ResearchFailure(signal.reason?.name === 'TimeoutError' ? 'timeout' : 'cancelled', 'Research interrupted.');
+            const id = `rpc-${report.evidence.length + 1}`;
+            const evidence = { ...structuredClone(cached), id, canonicality: 'unchecked' };
+            report.evidence.push(evidence);
+            if (cached.completeness === 'error') {
+                addError('contract-reverted', step, id);
+                throw new ResearchFailure('contract-reverted', ERROR_MESSAGES['contract-reverted']);
+            }
+            return { result: evidence.result, id };
+        }
+        if (report.usage.rpcCalls >= report.usage.maximumRpcCalls)
+            throw new ResearchFailure('limit-exceeded', 'RPC call budget exhausted.');
+        try {
+            await options.onProgress?.({ step, message: `Reading ${step}.` });
+        }
+        catch (error) {
+            throw new RuntimeInterruption(error);
+        }
+        if (signal.aborted)
+            throw new ResearchFailure(signal.reason?.name === 'TimeoutError' ? 'timeout' : 'cancelled', 'Research interrupted.');
+        try {
+            await options.beforeRpc?.({ method, step, maximumRpcCalls: report.usage.maximumRpcCalls });
+        }
+        catch (error) {
+            throw new RuntimeInterruption(error);
+        }
+        if (signal.aborted)
+            throw new ResearchFailure(signal.reason?.name === 'TimeoutError' ? 'timeout' : 'cancelled', 'Research interrupted.');
+        report.usage.rpcCalls++;
+        prepaidAttempt = true;
+        const id = `rpc-${report.evidence.length + 1}`;
+        let result;
+        let errorCategory;
+        try {
+            result = await (method === HOLDER_ACTIVITY_METHOD && indexTransport ? indexTransport : transport).request(method, params, signal);
+        }
+        catch (error) {
+            if (error instanceof AttemptRefusedError)
+                throw error.original;
+            if (error instanceof RuntimeInterruption)
+                throw error;
+            errorCategory = categoryOf(error, signal);
+            result = { error: errorCategory };
+        }
+        prepaidAttempt = false;
+        const resultJson = JSON.parse(JSON.stringify(result));
+        const indexed = method === HOLDER_ACTIVITY_METHOD;
+        const multicall = method === 'eth_call' && typeof params[0]?.to === 'string' && params[0].to.toLowerCase() === MULTICALL3_ADDRESS.toLowerCase();
+        const evidence = { id, tool: 'evm.inspect-token@0.1.0', source: { kind: 'rpc', provider: indexed ? `${input.chain}-alchemy-transfer-index` : servedProviderLabel(input.chain, `${input.chain}-configured-rpc`, transport.servedBy?.()), method, documentationUrl: indexed ? HOLDER_ACTIVITY_DOCUMENTATION : multicall ? MULTICALL3_DOCUMENTATION : RPC_DOCUMENTATION }, chain: input.chain, chainId: config.chainId, request: params, snapshot: report.snapshot ? { blockNumber: report.snapshot.blockNumber, blockHash: report.snapshot.blockHash } : null, observedAt: now().toISOString(), finality: report.snapshot ? 'sequencer-confirmed' : 'unverified', canonicality: 'unchecked', completeness: errorCategory ? 'error' : 'complete-for-request', result: resultJson, contentHash: contentHash(resultJson), privacy: 'public-chain-data' };
+        report.evidence.push(evidence);
+        try {
+            await options.onEvidence?.(structuredClone(evidence));
+        }
+        catch (error) {
+            throw new RuntimeInterruption(error);
+        }
+        if (errorCategory) {
+            addError(errorCategory, step, id);
+            throw new ResearchFailure(errorCategory, ERROR_MESSAGES[errorCategory]);
+        }
+        return { result, id };
+    };
+    const probe = async (method, params, step, decode) => {
+        let id;
+        try {
+            const response = await call(method, params, step);
+            id = response.id;
+            return observed(decode(response.result), id);
+        }
+        catch (error) {
+            if (error instanceof RuntimeInterruption)
+                throw error;
+            const category = categoryOf(error, signal);
+            if (!report.errors.some((item) => item.step === step))
+                addError(category, step, id);
+            if (['cancelled', 'timeout', 'limit-exceeded'].includes(category))
+                throw error;
+            return { status: category === 'contract-reverted' ? 'unknown' : 'error', reason: ERROR_MESSAGES[category], evidenceIds: id ? [id] : report.errors.filter((item) => item.step === step && item.evidenceId).map((item) => item.evidenceId) };
+        }
+    };
+    try {
+        if (!SupportedTokenResearcherManifestSchema.safeParse(manifest).success || !manifest.chains.includes(input.chain))
+            throw new ResearchFailure('unsupported', 'This version asks for research steps the Token Researcher does not support.');
+        if (!config.configured)
+            throw new ResearchFailure('unconfigured', 'No verified data provider is configured on this server for this chain.');
+        if (options.restore) {
+            if (options.restore.manifestHash !== report.manifestHash || options.restore.inputHash !== contentHash(input) || !Array.isArray(options.restore.evidence) || options.restore.evidence.length > 16 || Buffer.byteLength(JSON.stringify(options.restore.evidence)) > 1048576)
+                throw new ResearchFailure('invalid-response', 'Checkpoint identity or size is invalid.');
+            for (const raw of options.restore.evidence) {
+                const checked = EvidenceItemSchema.safeParse(raw);
+                if (!checked.success)
+                    throw new ResearchFailure('invalid-response', 'Checkpoint receipt schema is invalid.');
+                const item = checked.data;
+                if (item.chain !== input.chain || item.chainId !== config.chainId || item.contentHash !== contentHash(item.result) || item.canonicality === 'changed')
+                    throw new ResearchFailure('invalid-response', 'Checkpoint receipt integrity is invalid.');
+                const isStateRead = ['eth_getCode', 'eth_call', 'eth_getStorageAt'].includes(item.source.method);
+                if (!item.snapshot) {
+                    if (isStateRead)
+                        throw new ResearchFailure('invalid-response', 'Checkpointed state reads must have a pinned snapshot.');
+                    continue;
+                }
+                if (restoredSnapshot && (item.snapshot.blockNumber !== restoredSnapshot.blockNumber || item.snapshot.blockHash.toLowerCase() !== restoredSnapshot.blockHash.toLowerCase()))
+                    throw new ResearchFailure('invalid-response', 'Checkpoint receipts do not share one snapshot.');
+                restoredSnapshot = item.snapshot;
+                if (input.snapshotBlock !== undefined && input.snapshotBlock !== item.snapshot.blockNumber)
+                    throw new ResearchFailure('invalid-response', 'Checkpoint snapshot disagrees with the accepted input.');
+                if (!isStateRead)
+                    continue;
+                const blockTag = stateTag(item.snapshot);
+                const allowedReads = new Set([contentHash({ method: 'eth_getCode', params: [input.address, blockTag] })]);
+                for (const name of ['name', 'symbol', 'decimals', 'totalSupply', ...(policy.readOwner ? ['owner'] : [])])
+                    allowedReads.add(contentHash({ method: 'eth_call', params: [{ to: input.address, data: encodeFunctionData({ abi: ABI, functionName: name }), gas: '0x7a120' }, blockTag] }));
+                if (policy.readProxySlots)
+                    for (const slot of Object.values(EIP1967_SLOTS))
+                        allowedReads.add(contentHash({ method: 'eth_getStorageAt', params: [input.address, slot, blockTag] }));
+                const venues = marketVenuesFor(config.chainId);
+                if (manifest.marketPolicy?.discoverPools && venues)
+                    allowedReads.add(contentHash({ method: 'eth_call', params: [marketCall(encodeDiscovery(discoveryPlan(venues, input.address))), blockTag] }));
+                const key = contentHash({ method: item.source.method, params: item.request });
+                // A balances multicall is derived from earlier reads, so it is admitted by shape: the bounded balanceOf and pool-state selectors only.
+                const marketBalances = Boolean(manifest.marketPolicy) && item.source.method === 'eth_call' && item.request.length === 2 && contentHash(item.request[1]) === contentHash(blockTag) && marketCallInScope(item.request[0], input.address, config.chainId);
+                if (!allowedReads.has(key) && !marketBalances)
+                    throw new ResearchFailure('invalid-response', 'Checkpoint request is outside the immutable inspection policy or accepted address/block scope.');
+                const deterministicRevert = item.completeness === 'error' && contentHash(item.result) === contentHash({ error: 'contract-reverted' });
+                if (item.completeness !== 'complete-for-request' && !deterministicRevert)
+                    continue;
+                const prior = restoredReads.get(key);
+                if (prior && prior.contentHash !== item.contentHash)
+                    throw new ResearchFailure('invalid-response', 'Checkpointed reads disagree at the same scope.');
+                restoredReads.set(key, item);
+            }
+        }
+        // Product transport: Alchemy (keyed, mandatory per-run unit budget) first when configured, then the configured or official RPC.
+        const runBudget = new RunUnitBudget(KEYED_PROVIDER_POLICIES.alchemy.perRunUnits);
+        transport = options.transport ?? createChainReadTransport(readPolicy.chain, { env, rpcUrl: validRpcUrl(config.rpcUrl) ? config.rpcUrl : null, rpcTransport: makeTransport, runBudget, beforeAttempt: providerAttempt });
+        // The transfer index is an Alchemy method: it goes only to the keyed Alchemy host, never failed over to an RPC that cannot serve it,
+        // under the same run unit budget and with every attempt permitted and counted like any other read (no retry).
+        if (!options.transport && marketPolicy?.recentHolderActivity && !marketUnsupported.holders && keyedProviderHost('alchemy', readPolicy.chain) && keyedCredentialAvailable('alchemy', env)) {
+            indexTransport = createKeyedTransport('alchemy', readPolicy.chain, { env, runBudget, maximumRetries: 0, // With no retries each keyed request is one attempt, prepaid by the tool's own permit, so no hidden completion arises here.
+                beforeAttempt: async ({ method }) => { await providerAttempt({ method, purpose: 'request' }); } });
+        }
+        const identity = await call('eth_chainId', [], 'chain-identity');
+        if (quantity(identity.result) !== BigInt(config.chainId))
+            throw new ResearchFailure('chain-mismatch', 'RPC chain mismatch.');
+        let head = null;
+        for (const [index, tag] of readPolicy.tags.entries()) {
+            const last = index === readPolicy.tags.length - 1;
+            try {
+                const read = await call('eth_getBlockByNumber', [tag, false], `${tag}-snapshot`);
+                if (read.result === null && !last)
+                    continue;
+                head = read;
+                confirmation = readPolicy.confirmationOf[tag];
+                break;
+            }
+            catch (error) {
+                if (last || error instanceof RuntimeInterruption || ['cancelled', 'timeout', 'limit-exceeded', 'rate-limited'].includes(categoryOf(error, signal)))
+                    throw error;
+            }
+        }
+        if (!head)
+            throw new ResearchFailure('provider-unavailable', 'The provider served no snapshot block.');
+        if (!researchReportAccepts(confirmation))
+            throw new ResearchFailure('unsupported', `The Token Researcher report contract does not yet accept ${confirmation} snapshots.`);
+        const headBlock = blockData(head.result);
+        let selectedBlock = headBlock;
+        if (restoredSnapshot) {
+            // Recovery re-reads the original height: an unchanged hash is reused, a reorged one fails the run instead of mixing states.
+            if (BigInt(restoredSnapshot.blockNumber) > BigInt(headBlock.blockNumber))
+                throw new ResearchFailure('snapshot-changed', 'The prior snapshot is above this provider\'s latest block.');
+            const original = await call('eth_getBlockByNumber', [`0x${BigInt(restoredSnapshot.blockNumber).toString(16)}`, false], 'restored-snapshot-canonicality');
+            selectedBlock = blockData(original.result);
+            if (selectedBlock.blockNumber !== restoredSnapshot.blockNumber || selectedBlock.blockHash.toLowerCase() !== restoredSnapshot.blockHash.toLowerCase())
+                throw new ResearchFailure('snapshot-changed', 'The prior snapshot changed before recovery.');
+            report.limitations.push('Checkpointed state reads retain their original observation times; the original snapshot was revalidated before reuse and again at completion.');
+        }
+        else if (input.snapshotBlock !== undefined) {
+            if (BigInt(input.snapshotBlock) > BigInt(headBlock.blockNumber))
+                throw new ResearchFailure('unsupported', 'Requested snapshot is newer than the latest block.');
+            const requested = await call('eth_getBlockByNumber', [`0x${BigInt(input.snapshotBlock).toString(16)}`, false], 'requested-snapshot');
+            selectedBlock = blockData(requested.result);
+            if (selectedBlock.blockNumber !== input.snapshotBlock)
+                throw new ResearchFailure('invalid-response', 'Returned snapshot height does not match the request.');
+        }
+        report.snapshot = { ...selectedBlock, finality: confirmation, canonicality: 'unchecked' };
+        const blockTag = stateTag(selectedBlock);
+        const numberTag = `0x${BigInt(selectedBlock.blockNumber).toString(16)}`;
+        const code = await call('eth_getCode', [input.address, blockTag], 'contract-bytecode');
+        const bytecode = hexData(code.result);
+        report.contract.codePresent = observed(bytecode !== '0x', code.id);
+        report.contract.codeHash = observed(keccak256(bytecode), code.id);
+        if (bytecode === '0x')
+            throw new ResearchFailure('no-contract', 'No deployed code at this snapshot.');
+        report.status = 'partial';
+        for (const name of ['name', 'symbol', 'decimals', 'totalSupply']) {
+            const destination = name === 'totalSupply' ? 'totalSupplyAtomic' : name;
+            report.metadata[destination] = await probe('eth_call', [{ to: input.address, data: encodeFunctionData({ abi: ABI, functionName: name }), gas: '0x7a120' }, blockTag], `token-${name}`, (value) => {
+                const data = hexData(value);
+                if (data === '0x')
+                    throw new ResearchFailure('contract-reverted', 'Method returned no data.');
+                let decoded;
+                try {
+                    decoded = decodeFunctionResult({ abi: ABI, functionName: name, data });
+                }
+                catch {
+                    throw new ResearchFailure('invalid-response', 'ABI response invalid.');
+                }
+                if (typeof decoded === 'string') {
+                    if (Buffer.byteLength(decoded, 'utf8') > 256 || Array.from(decoded).some((character) => { const code = character.charCodeAt(0); return code === 127 || (code < 32 && ![9, 10, 13].includes(code)); }))
+                        throw new ResearchFailure('invalid-response', 'Token label exceeds metadata limits.');
+                    return decoded;
+                }
+                if (typeof decoded === 'bigint')
+                    return decoded.toString();
+                if (typeof decoded === 'number' && Number.isInteger(decoded) && decoded >= 0 && decoded <= 255)
+                    return decoded;
+                throw new ResearchFailure('invalid-response', 'Unexpected token metadata type.');
+            });
+        }
+        if (report.metadata.decimals.status === 'observed' && report.metadata.totalSupplyAtomic.status === 'observed') {
+            const decimals = Number(report.metadata.decimals.value);
+            report.metadata.totalSupplyFormatted = { status: 'observed', value: formatUnits(BigInt(String(report.metadata.totalSupplyAtomic.value)), decimals), evidenceIds: [...report.metadata.decimals.evidenceIds, ...report.metadata.totalSupplyAtomic.evidenceIds], note: 'Exact display conversion; atomic supply is retained.' };
+        }
+        if (!policy.readProxySlots) {
+            try {
+                await options.onProgress?.({ step: 'eip1967-slots', message: 'Skipping standard proxy-slot reads as selected by the immutable research policy.' });
+            }
+            catch (error) {
+                throw new RuntimeInterruption(error);
+            }
+        }
+        if (policy.readProxySlots)
+            for (const [role, slot] of Object.entries(EIP1967_SLOTS)) {
+                const slotResult = await probe('eth_getStorageAt', [input.address, slot, blockTag], `eip1967-${role}`, (value) => {
+                    const data = hexData(value);
+                    if (!/^0x0{24}[a-fA-F0-9]{40}$/.test(data))
+                        throw new ResearchFailure('invalid-response', 'EIP-1967 slot does not encode an address.');
+                    return getAddress(`0x${data.slice(26)}`);
+                });
+                report.controls[role] = slotResult.status === 'observed' && slotResult.value === ZERO_ADDRESS ? { status: 'not-detected', reason: 'The standard EIP-1967 slot is zero at this snapshot. Other control mechanisms are not excluded.', evidenceIds: slotResult.evidenceIds } : slotResult;
+                if (slotResult.status === 'observed' && slotResult.value !== ZERO_ADDRESS)
+                    report.findings.push({ code: `eip1967-${role}-populated`, message: `The standard ${role} slot contains ${String(slotResult.value)}. This is an observed storage value; proxy behaviour and controller permissions are not fully verified.`, evidenceIds: slotResult.evidenceIds });
+            }
+        if (!policy.readOwner) {
+            try {
+                await options.onProgress?.({ step: 'owner-method', message: 'Skipping owner() as selected by the immutable research policy.' });
+            }
+            catch (error) {
+                throw new RuntimeInterruption(error);
+            }
+        }
+        if (policy.readOwner)
+            report.controls.owner = await probe('eth_call', [{ to: input.address, data: encodeFunctionData({ abi: ABI, functionName: 'owner' }), gas: '0x7a120' }, blockTag], 'owner-method', (value) => {
+                const data = hexData(value);
+                if (data === '0x')
+                    throw new ResearchFailure('contract-reverted', 'No owner response.');
+                try {
+                    return getAddress(decodeFunctionResult({ abi: ABI, functionName: 'owner', data }));
+                }
+                catch {
+                    throw new ResearchFailure('invalid-response', 'Owner response invalid.');
+                }
+            });
+        if (marketPolicy) {
+            // At most three reads at the pinned block: pool discovery, one indexed transfer page, and one balances multicall. A failed read is a
+            // recorded error (partial report), never an empty result; budget, cancellation and deadline stops propagate.
+            const marketRead = async (method, params, step) => {
+                try {
+                    return await call(method, params, step);
+                }
+                catch (error) {
+                    if (error instanceof RuntimeInterruption)
+                        throw error;
+                    const category = categoryOf(error, signal);
+                    if (!report.errors.some((item) => item.step === step))
+                        addError(category, step);
+                    if (['cancelled', 'timeout', 'limit-exceeded'].includes(category))
+                        throw error;
+                    return null;
+                }
+            };
+            const venues = marketVenuesFor(report.chainId);
+            let found = [];
+            let recipients = [];
+            if (marketPolicy.discoverPools && !marketUnsupported.pools && venues) {
+                const plan = discoveryPlan(venues, input.address);
+                const read = await marketRead('eth_call', [marketCall(encodeDiscovery(plan)), blockTag], 'dex-pool-discovery');
+                if (read) {
+                    try {
+                        found = poolsFromDiscovery(plan, decodeAggregate(read.result, plan.length)).found;
+                    }
+                    catch {
+                        addError('invalid-response', 'dex-pool-discovery', read.id);
+                    }
+                }
+            }
+            if (marketPolicy.recentHolderActivity && !marketUnsupported.holders) {
+                const read = await marketRead(HOLDER_ACTIVITY_METHOD, [holderTransferRequest(input.address, selectedBlock.blockNumber)], 'recent-holder-activity');
+                if (read) {
+                    try {
+                        recipients = recipientsFromTransfers(read.result, input.address, selectedBlock.blockNumber).recipients;
+                    }
+                    catch {
+                        addError('invalid-response', 'recent-holder-activity', read.id);
+                    }
+                }
+            }
+            const balances = marketBalancesData(input.address, found.slice(0, MAXIMUM_MARKET_POOLS), recipients);
+            if (balances) {
+                const read = await marketRead('eth_call', [marketCall(balances.data), blockTag], 'market-balances');
+                if (read) {
+                    try {
+                        decodeAggregate(read.result, balances.plan.length);
+                    }
+                    catch {
+                        addError('invalid-response', 'market-balances', read.id);
+                    }
+                }
+            }
+        }
+        const ending = await call('eth_getBlockByNumber', [numberTag, false], 'snapshot-canonicality');
+        const endBlock = blockData(ending.result);
+        if (endBlock.blockHash.toLowerCase() !== selectedBlock.blockHash.toLowerCase() || endBlock.blockNumber !== selectedBlock.blockNumber) {
+            report.snapshot.canonicality = 'changed';
+            for (const item of report.evidence)
+                if (item.snapshot)
+                    item.canonicality = 'changed';
+            throw new ResearchFailure('snapshot-changed', 'Snapshot changed.');
+        }
+        report.snapshot.canonicality = 'verified-at-completion';
+        for (const item of report.evidence)
+            if (item.snapshot)
+                item.canonicality = 'verified-at-completion';
+        report.status = report.errors.length ? 'partial' : 'complete';
+    }
+    catch (error) {
+        if (error instanceof RuntimeInterruption)
+            throw error.original;
+        const category = categoryOf(error, signal);
+        if (!report.errors.some((item) => item.category === category))
+            addError(category, 'research');
+        if (['chain-mismatch', 'snapshot-changed', 'no-contract', 'unconfigured', 'cancelled'].includes(category))
+            report.status = 'failed';
+    }
+    // The market section is always derived from this report's own receipts, including after an interruption.
+    if (marketPolicy) {
+        report.market = buildMarketSection({ policy: marketPolicy, chainId: report.chainId, token: input.address, snapshotBlock: report.snapshot?.blockNumber ?? null, evidence: report.evidence, unsupported: marketUnsupported });
+        report.coverage.holders.evidenceIds = [...report.market.recentHolderActivity.evidenceIds];
+        report.coverage.liquidity.evidenceIds = [...report.market.pools.evidenceIds];
+    }
+    // Captured facts remain inspectable after interruption, but an unchecked snapshot is
+    // never an accepted partial deliverable, including when facts came from checkpoints.
+    if (report.status === 'partial' && report.snapshot?.canonicality !== 'verified-at-completion')
+        report.status = 'failed';
+    // One bounded model request over the finished evidence. Runtime refusals other than the model budget propagate unchanged.
+    if (analysisPolicy)
+        await attachAnalysis(report, analysisPolicy, options, signal, deadlineAt);
+    report.generatedAt = now().toISOString();
+    report.usage.elapsedMs = Math.max(0, now().getTime() - started);
+    // 0.1.0/0.2.0 keep the 128 KiB ceiling; a 0.3.0 market report may use up to 256 KiB, as the other first-party agents do.
+    const outputBudget = Math.min(manifest.marketPolicy ? 262144 : 131072, manifest.limits.maximumOutputBytes);
+    if (report.analysis?.findings.length && Buffer.byteLength(JSON.stringify(report)) > outputBudget) {
+        report.analysis.status = 'unavailable';
+        report.analysis.findings = [];
+        report.analysis.unavailableReason = 'The AI-assisted findings did not fit the report output budget and were withheld.';
+    }
+    if (Buffer.byteLength(JSON.stringify(report)) > outputBudget) {
+        report.status = 'failed';
+        // Preserve verifiable hashes while withholding the oversized artifact from callers.
+        throw new ResearchFailure('limit-exceeded', 'The captured report exceeds the configured output budget; no truncated report is accepted.');
+    }
+    return TokenResearchReportSchema.parse(report);
+}