agentex-creator-sdk 1.0.0

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

@@ -0,0 +1,380 @@
+import { createHash } from 'node:crypto';
+import { isAddress } from 'viem';
+import { z } from 'zod';
+export const ChainKeySchema = z.enum(['ethereum', 'base', 'robinhood']);
+export const AddressSchema = z.string().refine((value) => isAddress(value), 'Expected a valid EVM address (with a valid checksum when mixed case)');
+export const AtomicAmountSchema = z.string().regex(/^(0|[1-9][0-9]{0,77})$/, 'Expected unsigned atomic units, without decimals or exponent notation').refine((value) => /^(0|[1-9][0-9]{0,77})$/.test(value) && BigInt(value) < 2n ** 256n, 'Amount exceeds uint256');
+export const AssetAmountSchema = z.strictObject({ chainId: z.number().int().positive(), asset: z.union([z.literal('native'), AddressSchema]), decimals: z.number().int().min(0).max(255), atomic: AtomicAmountSchema });
+export const ResearchInputSchema = z.strictObject({
+    chain: ChainKeySchema,
+    address: AddressSchema,
+    scope: z.literal('metadata-and-controls').default('metadata-and-controls'),
+    snapshotBlock: AtomicAmountSchema.optional(),
+});
+const Identifier = z.string().regex(/^[a-z][a-z0-9._-]{0,63}$/);
+const PropertyIdentifier = z.string().regex(/^[a-z][a-zA-Z0-9_]{0,63}$/).refine((value) => !['constructor', 'prototype'].includes(value), 'Reserved property name');
+const Hash = z.string().regex(/^[a-f0-9]{64}$/);
+const FieldSchema = z.strictObject({ type: z.enum(['string', 'number', 'integer', 'boolean', 'array']), description: z.string().max(1000), enum: z.array(z.union([z.string(), z.number(), z.boolean()])).max(100).optional() });
+export const ObjectSchemaDefinition = z.strictObject({ type: z.literal('object'), properties: z.record(PropertyIdentifier, FieldSchema), required: z.array(PropertyIdentifier).max(64), additionalProperties: z.literal(false) }).superRefine((schema, ctx) => {
+    for (const key of schema.required)
+        if (!Object.hasOwn(schema.properties, key))
+            ctx.addIssue({ code: 'custom', message: `Required property ${key} is not declared` });
+});
+const BindingSchema = z.discriminatedUnion('source', [
+    z.strictObject({ source: z.literal('input'), path: PropertyIdentifier }),
+    z.strictObject({ source: z.literal('node'), nodeId: Identifier, path: PropertyIdentifier }),
+]);
+const NodeBase = { id: Identifier, dependsOn: z.array(Identifier).max(32) };
+export const WorkflowNodeSchema = z.discriminatedUnion('type', [
+    z.strictObject({ ...NodeBase, type: z.literal('input') }),
+    z.strictObject({ ...NodeBase, type: z.literal('tool'), tool: Identifier, arguments: z.record(PropertyIdentifier, BindingSchema) }),
+    z.strictObject({ ...NodeBase, type: z.literal('condition'), field: BindingSchema, operator: z.enum(['equals', 'exists']), value: z.union([z.string(), z.boolean(), z.number()]).optional(), whenTrue: Identifier, whenFalse: Identifier }),
+    z.strictObject({ ...NodeBase, type: z.literal('output'), from: Identifier }),
+]);
+/** Output schema ids double as the explicit executable agent kind. Enum parsing keeps stored manifest hashes unchanged. */
+export const OutputSchemaIdSchema = z.enum(['agentex.token-research.v1', 'agentex.transaction-inspection.v1', 'agentex.watchtower-window.v1']);
+/** input-address: reads bound to one input contract. input-transaction: reads bound to a proposed payload's sender, target and decoded grantees. input-watch-scope: log reads bound to declared rule contracts inside one bounded block window. */
+const ToolSchema = z.strictObject({ id: Identifier, version: z.string().regex(/^\d+\.\d+\.\d+$/), capability: z.literal('evm.read'), chains: z.array(ChainKeySchema).min(1).max(3), addressScope: z.enum(['input-address', 'input-transaction', 'input-watch-scope']), maximumCalls: z.number().int().min(1).max(24) });
+export const ResearchPolicySchema = z.strictObject({ readOwner: z.boolean(), readProxySlots: z.boolean() });
+/**
+ * Token Researcher 0.3.0 market reads (P01): pools on listed venues by factory lookup, and balances of recent transfer recipients from an
+ * index. Absent: no market read, report section or hash change (0.1.0 and 0.2.0 manifests omit it). See token-market.ts.
+ */
+export const MarketPolicySchema = z.strictObject({ discoverPools: z.boolean(), recentHolderActivity: z.boolean() });
+/**
+ * Optional bounded AI-assisted summary for Token Researcher manifests: one model request over evidence the deterministic reads already
+ * captured. Absent: the manifest hash, run behaviour and report shape are unchanged. The cost cap is the quoted model maximum in micro-USD.
+ */
+export const AnalysisPolicySchema = z.strictObject({ mode: z.literal('summary'), maximumOutputTokens: z.number().int().min(64).max(2000), maximumCostMicrousd: z.number().int().min(1).max(200000) });
+export const ManifestPolicySchema = z.strictObject({ analysis: AnalysisPolicySchema });
+export const AgentManifestSchema = z.strictObject({
+    schemaVersion: z.literal('1.0'), id: Identifier, version: z.string().regex(/^\d+\.\d+\.\d+$/), name: z.string().min(1).max(100), description: z.string().min(1).max(2000),
+    author: z.strictObject({ id: Identifier, name: z.string().min(1).max(100), ownership: z.enum(['first-party', 'independent']) }),
+    license: z.string().min(1).max(100), visibility: z.enum(['private', 'source-visible', 'source-private']),
+    chains: z.array(ChainKeySchema).min(1).max(3),
+    inputSchema: ObjectSchemaDefinition, outputSchemaId: OutputSchemaIdSchema,
+    tools: z.array(ToolSchema).min(1).max(16),
+    modelPolicy: z.strictObject({ mode: z.literal('deterministic'), maximumModelTokens: z.literal(0) }),
+    // Do not add a schema default here: absent policy must preserve immutable legacy hashes.
+    researchPolicy: ResearchPolicySchema.optional(),
+    // Do not add a schema default here either: absent policy must preserve immutable legacy hashes.
+    policy: ManifestPolicySchema.optional(),
+    // Token Researcher 0.3.0 market reads; absent on every earlier manifest (no default, hashes unchanged).
+    marketPolicy: MarketPolicySchema.optional(),
+    limits: z.strictObject({ maximumRpcCalls: z.number().int().min(1).max(24), maximumDurationMs: z.number().int().min(1000).max(120000), maximumOutputBytes: z.number().int().min(1024).max(262144), maximumGraphDepth: z.number().int().min(1).max(16), maximumPages: z.literal(0), maximumExecutionAtomic: AtomicAmountSchema }),
+    workflow: z.array(WorkflowNodeSchema).min(3).max(32),
+    testCases: z.array(Identifier).min(1).max(100),
+}).superRefine((manifest, ctx) => {
+    const issue = (message) => ctx.addIssue({ code: 'custom', message });
+    const nodes = new Map(manifest.workflow.map((node) => [node.id, node]));
+    const tools = new Map(manifest.tools.map((tool) => [tool.id, tool]));
+    if (nodes.size !== manifest.workflow.length)
+        issue('Duplicate workflow node id');
+    if (tools.size !== manifest.tools.length)
+        issue('Duplicate tool id');
+    if (new Set(manifest.chains).size !== manifest.chains.length)
+        issue('Duplicate chain');
+    const expectedScope = manifest.outputSchemaId === 'agentex.token-research.v1' ? 'input-address' : manifest.outputSchemaId === 'agentex.watchtower-window.v1' ? 'input-watch-scope' : 'input-transaction';
+    if (manifest.tools.some((tool) => tool.addressScope !== expectedScope))
+        issue(`Tools for ${manifest.outputSchemaId} must use the ${expectedScope} read grant`);
+    if (manifest.researchPolicy !== undefined && manifest.outputSchemaId !== 'agentex.token-research.v1')
+        issue('researchPolicy applies only to Token Researcher manifests');
+    if (manifest.policy !== undefined && manifest.outputSchemaId !== 'agentex.token-research.v1')
+        issue('policy.analysis applies only to Token Researcher manifests');
+    if (manifest.marketPolicy !== undefined && manifest.outputSchemaId !== 'agentex.token-research.v1')
+        issue('marketPolicy applies only to Token Researcher manifests');
+    if (manifest.workflow.filter((node) => node.type === 'input').length !== 1)
+        issue('Workflow must have exactly one input node');
+    if (manifest.workflow.filter((node) => node.type === 'output').length !== 1)
+        issue('Workflow must have exactly one output node');
+    for (const tool of manifest.tools) {
+        if (!manifest.chains.every((chain) => tool.chains.includes(chain)))
+            issue(`Tool ${tool.id} cannot execute on every declared chain`);
+        if (tool.maximumCalls > manifest.limits.maximumRpcCalls)
+            issue(`Tool ${tool.id} exceeds the workflow call budget`);
+    }
+    for (const node of manifest.workflow) {
+        for (const dependency of node.dependsOn)
+            if (!nodes.has(dependency))
+                issue(`Node ${node.id} references missing dependency ${dependency}`);
+        if (node.type === 'input' && node.dependsOn.length)
+            issue('Input node cannot have dependencies');
+        if (node.type !== 'input' && !node.dependsOn.length)
+            issue(`Node ${node.id} is disconnected from input`);
+        if (node.type === 'tool' && !tools.has(node.tool))
+            issue(`Undeclared tool ${node.tool}`);
+        if (node.type === 'output' && !node.dependsOn.includes(node.from))
+            issue('Output source must be an explicit dependency');
+        if (node.type === 'condition') {
+            if (!nodes.has(node.whenTrue) || !nodes.has(node.whenFalse))
+                issue('Condition branch target does not exist');
+            if (node.operator === 'equals' && node.value === undefined)
+                issue('Equality condition needs a value');
+            for (const target of [node.whenTrue, node.whenFalse])
+                if (!nodes.get(target)?.dependsOn.includes(node.id))
+                    issue('Condition targets must depend on the condition node');
+        }
+        const bindings = node.type === 'tool' ? Object.values(node.arguments) : node.type === 'condition' ? [node.field] : [];
+        for (const binding of bindings) {
+            if (binding.source === 'node' && !node.dependsOn.includes(binding.nodeId))
+                issue('Node binding must name an explicit dependency');
+            if (binding.source === 'input' && !Object.hasOwn(manifest.inputSchema.properties, binding.path))
+                issue(`Unknown input property ${binding.path}`);
+        }
+    }
+    const visiting = new Set();
+    const depths = new Map();
+    const visit = (id) => {
+        if (visiting.has(id)) {
+            issue('Workflow contains a cycle');
+            return manifest.limits.maximumGraphDepth + 1;
+        }
+        const cached = depths.get(id);
+        if (cached !== undefined)
+            return cached;
+        visiting.add(id);
+        const depth = 1 + Math.max(0, ...(nodes.get(id)?.dependsOn ?? []).map(visit));
+        visiting.delete(id);
+        depths.set(id, depth);
+        if (depth > manifest.limits.maximumGraphDepth)
+            issue('Workflow exceeds maximum graph depth');
+        return depth;
+    };
+    for (const id of nodes.keys())
+        visit(id);
+    const output = manifest.workflow.find((node) => node.type === 'output');
+    const used = new Set();
+    const ancestors = (id) => { if (used.has(id))
+        return; used.add(id); for (const dependency of nodes.get(id)?.dependsOn ?? [])
+        ancestors(dependency); };
+    if (output)
+        ancestors(output.id);
+    if (used.size !== nodes.size)
+        issue('Every node must contribute to the output');
+});
+export function canonicalJson(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'number' && Number.isFinite(value))
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype)
+        return `{${Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(',')}}`;
+    throw new TypeError('Only finite JSON data can be hashed');
+}
+export const contentHash = (value) => createHash('sha256').update(canonicalJson(value)).digest('hex');
+function deepFreeze(value) { if (value !== null && typeof value === 'object') {
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    Object.freeze(value);
+} return value; }
+export function publishManifest(input) { const manifest = AgentManifestSchema.parse(input); return deepFreeze({ manifest, hash: contentHash(manifest) }); }
+export const TOKEN_RESEARCHER_MANIFEST = publishManifest({
+    schemaVersion: '1.0', id: 'token-researcher', version: '0.1.0', name: 'Token Researcher',
+    description: 'Read ERC-20 metadata, bytecode and standard EIP-1967 proxy slots at one verified EVM snapshot. Holder, pool and exhaustive authority indexes are not included.',
+    author: { id: 'agentex', name: 'AGENTEX', ownership: 'first-party' }, license: 'Proprietary', visibility: 'source-visible', chains: ['ethereum', 'base'],
+    inputSchema: { type: 'object', additionalProperties: false, properties: { chain: { type: 'string', description: 'Explicit analysis network', enum: ['ethereum', 'base'] }, address: { type: 'string', description: 'Token contract address' }, scope: { type: 'string', description: 'Bounded inspection scope', enum: ['metadata-and-controls'] }, snapshotBlock: { type: 'string', description: 'Optional finalized block number' } }, required: ['chain', 'address'] },
+    outputSchemaId: 'agentex.token-research.v1', tools: [{ id: 'evm.inspect-token', version: '0.1.0', capability: 'evm.read', chains: ['ethereum', 'base'], addressScope: 'input-address', maximumCalls: 16 }],
+    modelPolicy: { mode: 'deterministic', maximumModelTokens: 0 }, limits: { maximumRpcCalls: 16, maximumDurationMs: 60000, maximumOutputBytes: 131072, maximumGraphDepth: 4, maximumPages: 0, maximumExecutionAtomic: '0' },
+    workflow: [{ id: 'input', type: 'input', dependsOn: [] }, { id: 'inspect', type: 'tool', tool: 'evm.inspect-token', dependsOn: ['input'], arguments: { chain: { source: 'input', path: 'chain' }, address: { source: 'input', path: 'address' }, scope: { source: 'input', path: 'scope' }, snapshotBlock: { source: 'input', path: 'snapshotBlock' } } }, { id: 'report', type: 'output', dependsOn: ['inspect'], from: 'inspect' }],
+    testCases: ['standard-metadata', 'nonstandard-decimals', 'proxy-slots', 'no-contract', 'provider-failure', 'budget-stop'],
+}).manifest;
+/**
+ * Token Researcher 0.2.0: the same workflow, tools, limits and output schema as 0.1.0, with buyer-visible text for the instant-read rule
+ * (latest block, sequencer-confirmed). 0.1.0 above stays byte-identical (hash 5784e6b0…) for stored versions, evidence and replay;
+ * new drafts, the SDK scaffold and `GET /v1/templates` start from 0.2.0.
+ */
+export const TOKEN_RESEARCHER_MANIFEST_V2 = publishManifest({
+    ...structuredClone(TOKEN_RESEARCHER_MANIFEST), version: '0.2.0',
+    description: 'Read ERC-20 metadata, bytecode and standard EIP-1967 proxy slots at the latest block (sequencer-confirmed), pinned for the whole run and rechecked at completion. Holder, pool and exhaustive authority indexes are not included.',
+    inputSchema: { ...structuredClone(TOKEN_RESEARCHER_MANIFEST.inputSchema), properties: { ...structuredClone(TOKEN_RESEARCHER_MANIFEST.inputSchema.properties), snapshotBlock: { type: 'string', description: 'Optional block number (defaults to the latest block)' } } },
+}).manifest;
+/**
+ * Token Researcher 0.3.0 (P01): the 0.2.0 graph, tool and output schema across Ethereum, Base and Robinhood Chain, plus `marketPolicy`: pools on listed
+ * venues found by factory lookup with observed pool token balances, and current balances of recent transfer recipients from a provider index.
+ * 0.1.0 and 0.2.0 stay byte-identical. At most 15 reads at the latest block (16 with an explicit snapshot).
+ */
+export const TOKEN_RESEARCHER_MANIFEST_V3 = publishManifest({
+    ...structuredClone(TOKEN_RESEARCHER_MANIFEST_V2), version: '0.3.0',
+    description: 'Read ERC-20 metadata, bytecode, standard EIP-1967 proxy slots and owner() at the latest block (sequencer-confirmed), pinned for the whole run and rechecked at completion. It also finds pools on listed Uniswap-compatible venues by factory lookup, with the token balances each pool holds, and reads current balances of recent transfer recipients from a provider index. It is not a holder census, a total liquidity figure or a safety verdict.',
+    chains: ['ethereum', 'base', 'robinhood'],
+    inputSchema: { ...structuredClone(TOKEN_RESEARCHER_MANIFEST_V2.inputSchema), properties: { ...structuredClone(TOKEN_RESEARCHER_MANIFEST_V2.inputSchema.properties), chain: { type: 'string', description: 'Explicit analysis network', enum: ['ethereum', 'base', 'robinhood'] } } },
+    tools: [{ ...structuredClone(TOKEN_RESEARCHER_MANIFEST_V2.tools[0]), chains: ['ethereum', 'base', 'robinhood'] }],
+    // The market receipts (one transfer page, two multicalls) need the 256 KiB report budget the other first-party agents already declare.
+    limits: { ...structuredClone(TOKEN_RESEARCHER_MANIFEST_V2.limits), maximumOutputBytes: 262144 },
+    marketPolicy: { discoverPools: true, recentHolderActivity: true },
+    testCases: [...TOKEN_RESEARCHER_MANIFEST_V2.testCases, 'multiple-pools', 'no-pools', 'recent-recipients-not-holders', 'holder-index-unavailable'],
+}).manifest;
+/** True when `inputSchema` equals one template version's input declaration with the manifest's own chains selected. */
+export function matchesTemplateInput(manifest, templates) {
+    const actual = contentHash(manifest.inputSchema);
+    return templates.some((template) => { const expected = structuredClone(template.inputSchema); expected.properties.chain.enum = manifest.chains; return contentHash(expected) === actual; });
+}
+const DEFAULT_RESEARCH_POLICY = Object.freeze({ readOwner: true, readProxySlots: true });
+export function resolveResearchPolicy(manifest) {
+    return manifest.researchPolicy === undefined ? DEFAULT_RESEARCH_POLICY : Object.freeze(ResearchPolicySchema.parse(manifest.researchPolicy));
+}
+/** The validated AI-assisted summary policy, or null when the manifest declares none (or declares an invalid one). */
+export function resolveAnalysisPolicy(manifest) {
+    const raw = manifest !== null && typeof manifest === 'object' ? manifest.policy?.analysis : undefined;
+    if (raw === undefined)
+        return null;
+    const parsed = AnalysisPolicySchema.safeParse(raw);
+    return parsed.success ? Object.freeze(parsed.data) : null;
+}
+/** Pure quote helper: the maximum model spend a run of this manifest may incur, in micro-USD. 0 when no AI-assisted summary is declared. */
+export function analysisCostCap(manifest) {
+    return resolveAnalysisPolicy(manifest)?.maximumCostMicrousd ?? 0;
+}
+/** Executable manifest subset shared by publication review and the actual researcher. */
+export const SupportedTokenResearcherManifestSchema = AgentManifestSchema.superRefine((manifest, ctx) => {
+    if (manifest.outputSchemaId !== 'agentex.token-research.v1')
+        ctx.addIssue({ code: 'custom', path: ['outputSchemaId'], message: 'Only agentex.token-research.v1 manifests are Token Researcher packages.' });
+    if (contentHash(manifest.workflow) !== contentHash(TOKEN_RESEARCHER_MANIFEST.workflow))
+        ctx.addIssue({ code: 'custom', path: ['workflow'], message: 'The executor supports only the bounded Token Researcher graph; select controls with researchPolicy.' });
+    if (!matchesTemplateInput(manifest, [TOKEN_RESEARCHER_MANIFEST, TOKEN_RESEARCHER_MANIFEST_V2]))
+        ctx.addIssue({ code: 'custom', path: ['inputSchema'], message: 'The input declaration must match the supported chain/address/scope/snapshot inputs.' });
+    const tool = manifest.tools[0];
+    if (manifest.tools.length !== 1 || tool?.id !== 'evm.inspect-token' || tool.version !== '0.1.0' || tool.capability !== 'evm.read' || tool.addressScope !== 'input-address')
+        ctx.addIssue({ code: 'custom', path: ['tools'], message: 'Only evm.inspect-token@0.1.0 with the read-only input-address grant is executable.' });
+});
+/** Nominal fresh-run RPC attempts. Provider failures may stop early; retry receipts stay charged. */
+export function getTokenResearcherRpcPlan(raw) {
+    const manifest = SupportedTokenResearcherManifestSchema.parse(raw);
+    const policy = resolveResearchPolicy(manifest);
+    const market = manifest.marketPolicy;
+    // Market reads: one discovery multicall, one indexed transfer page, and one balances multicall when either section is on.
+    const marketCalls = market ? (market.discoverPools ? 1 : 0) + (market.recentHolderActivity ? 1 : 0) + (market.discoverPools || market.recentHolderActivity ? 1 : 0) : 0;
+    const latestSnapshotCalls = 8 + (policy.readOwner ? 1 : 0) + (policy.readProxySlots ? 3 : 0) + marketCalls;
+    return Object.freeze({ policy, marketPolicy: market ?? null, latestSnapshotCalls, explicitSnapshotCalls: latestSnapshotCalls + 1, maximumRpcCalls: Math.min(16, manifest.limits.maximumRpcCalls, ...manifest.tools.map((tool) => tool.maximumCalls)) });
+}
+export const FailureCategorySchema = z.enum(['provider-unavailable', 'history-unavailable', 'rate-limited', 'timeout', 'cancelled', 'unsupported', 'contract-reverted', 'invalid-response', 'chain-mismatch', 'snapshot-changed', 'limit-exceeded', 'unconfigured', 'no-contract']);
+export const ResearchErrorSchema = z.strictObject({ category: FailureCategorySchema, message: z.string().max(1000), step: z.string().max(100), evidenceId: z.string().optional() });
+/** Shared EVM evidence envelope, bound to exactly one executor tool version. */
+export const evmEvidenceItemSchema = (tool) => z.strictObject({
+    id: z.string(), tool: z.literal(tool), source: z.strictObject({ kind: z.literal('rpc'), provider: z.string(), method: z.string(), documentationUrl: z.url() }),
+    chain: ChainKeySchema, chainId: z.number().int().positive(), request: z.array(z.json()),
+    snapshot: z.strictObject({ blockNumber: AtomicAmountSchema, blockHash: z.string().regex(/^0x[a-fA-F0-9]{64}$/) }).nullable(),
+    // `sequencer-confirmed`: a state read at the pinned latest block (instant-read rule). `finalized` parses receipts captured before the rule.
+    observedAt: z.iso.datetime(), finality: z.enum(['finalized', 'sequencer-confirmed', 'unverified']), canonicality: z.enum(['verified-at-completion', 'unchecked', 'changed']),
+    completeness: z.enum(['complete-for-request', 'error']), result: z.json(), contentHash: Hash,
+    privacy: z.literal('public-chain-data'),
+});
+export const EvidenceItemSchema = evmEvidenceItemSchema('evm.inspect-token@0.1.0');
+export const ObservationSchema = z.discriminatedUnion('status', [
+    z.strictObject({ status: z.literal('observed'), value: z.union([z.string(), z.number(), z.boolean()]), evidenceIds: z.array(z.string()).min(1), note: z.string().optional() }),
+    z.strictObject({ status: z.enum(['unknown', 'error', 'not-detected', 'not-applicable', 'unsupported']), reason: z.string(), evidenceIds: z.array(z.string()) }),
+    z.strictObject({ status: z.literal('skipped'), reason: z.string().min(1).max(1000), evidenceIds: z.array(z.string()).length(0) }),
+]);
+export const ANALYSIS_LABEL = 'AI-assisted summary';
+/** Model-written section, present only when the manifest declares policy.analysis. Deterministic observations are never part of it. */
+export const ResearchAnalysisSchema = z.strictObject({
+    label: z.literal(ANALYSIS_LABEL), status: z.enum(['completed', 'unavailable', 'skipped']), model: z.string().min(1).max(64),
+    findings: z.array(z.strictObject({ claim: z.string().min(1).max(600), evidenceIds: z.array(z.string().min(1).max(64)).min(1).max(8), confidence: z.enum(['supported', 'uncertain']) })).max(12),
+    unavailableReason: z.string().min(1).max(500).optional(),
+});
+/**
+ * Metered summary usage. `costStatus: 'unresolved'` means an earlier attempt sent the request but its usage was never recorded: `costMicrousd`
+ * is then the reserved worst case (an upper bound for settlement), not metered spend, and token counts are unknown (0). Absent: metered.
+ */
+export const ModelUsageSchema = z.strictObject({ model: z.string().min(1).max(64), inputTokens: z.number().int().nonnegative(), outputTokens: z.number().int().nonnegative(), costMicrousd: z.number().int().nonnegative(), costStatus: z.literal('unresolved').optional() });
+const MarketAddress = z.string().regex(/^0x[0-9a-fA-F]{40}$/);
+const MarketStatusSchema = z.enum(['observed', 'none-found', 'skipped', 'unsupported', 'not-read', 'error']);
+const MarketVenueFields = { venue: z.string().regex(/^[a-z0-9-]{1,32}$/), protocol: z.enum(['uniswap-v2', 'uniswap-v3', 'aerodrome']), factory: MarketAddress, quoteToken: MarketAddress,
+    quoteSymbol: z.string().regex(/^[A-Z0-9]{1,12}$/), quoteDecimals: z.number().int().min(0).max(255), feeTier: z.number().int().min(1).max(1_000_000).nullable(), stable: z.boolean().nullable() };
+const NullableAtomic = AtomicAmountSchema.nullable();
+/**
+ * Token Researcher 0.3.0 market section. Every value is derived from captured receipts by `buildMarketSection` (token-market.ts). Pools are the
+ * listed venues' factory lookups only; recent recipients are an index page of recent transfers, never a holder list. No totals, prices or scores.
+ */
+export const TokenMarketSchema = z.strictObject({
+    pools: z.strictObject({
+        status: MarketStatusSchema, reason: z.string().min(1).max(1000),
+        venuesChecked: z.array(z.strictObject({ ...MarketVenueFields, lookup: z.enum(['pool', 'no-pool', 'call-failed']), pool: MarketAddress.nullable() })).max(32),
+        pools: z.array(z.strictObject({ ...MarketVenueFields, address: MarketAddress, token0: MarketAddress, tokenBalanceAtomic: NullableAtomic, quoteBalanceAtomic: NullableAtomic, reserve0Atomic: NullableAtomic, reserve1Atomic: NullableAtomic,
+            sqrtPriceX96: NullableAtomic, tick: z.number().int().min(-887272).max(887272).nullable(), activeLiquidity: NullableAtomic, evidenceIds: z.array(z.string()).min(1).max(2) })).max(8),
+        poolsFound: z.number().int().min(0).max(32), truncated: z.boolean(), evidenceIds: z.array(z.string()).max(1),
+    }),
+    recentHolderActivity: z.strictObject({
+        status: MarketStatusSchema, reason: z.string().min(1).max(1000), basis: z.literal('recent-transfer-recipients-not-a-holder-list'), transfersExamined: z.number().int().min(0).max(25), truncated: z.boolean(),
+        accounts: z.array(z.strictObject({ address: MarketAddress, latestReceiptBlock: AtomicAmountSchema, balanceAtomic: NullableAtomic, isDiscoveredPool: z.boolean(), evidenceIds: z.array(z.string()).min(1).max(2) })).max(10),
+        evidenceIds: z.array(z.string()).max(1),
+    }),
+    limitations: z.array(z.string().min(1).max(1000)).max(8),
+});
+export const TokenResearchReportSchema = z.strictObject({
+    schemaVersion: z.literal('agentex.token-research.v1'), agentVersion: z.string().regex(/^\d+\.\d+\.\d+$/), manifestHash: Hash,
+    researchPolicy: ResearchPolicySchema.optional(),
+    // 0.3.0 reports only: the resolved market policy and its section are present together.
+    marketPolicy: MarketPolicySchema.optional(), market: TokenMarketSchema.optional(),
+    input: ResearchInputSchema, status: z.enum(['complete', 'partial', 'failed']), generatedAt: z.iso.datetime(),
+    chainId: z.number().int().positive().nullable(), snapshot: z.strictObject({ blockNumber: AtomicAmountSchema, blockHash: z.string(), timestamp: AtomicAmountSchema, finality: z.enum(['finalized', 'sequencer-confirmed']), canonicality: z.enum(['verified-at-completion', 'unchecked', 'changed']) }).nullable(),
+    metadata: z.strictObject({ name: ObservationSchema, symbol: ObservationSchema, decimals: ObservationSchema, totalSupplyAtomic: ObservationSchema, totalSupplyFormatted: ObservationSchema }),
+    contract: z.strictObject({ codePresent: ObservationSchema, codeHash: ObservationSchema, sourceVerification: ObservationSchema }),
+    controls: z.strictObject({ implementation: ObservationSchema, admin: ObservationSchema, beacon: ObservationSchema, owner: ObservationSchema, mintAuthority: ObservationSchema, freezeAuthority: ObservationSchema, upgradeability: ObservationSchema }),
+    coverage: z.strictObject({ holders: ObservationSchema, liquidity: ObservationSchema, deployment: ObservationSchema, historicalActivity: ObservationSchema }),
+    findings: z.array(z.strictObject({ code: z.string(), message: z.string(), evidenceIds: z.array(z.string()) })),
+    limitations: z.array(z.string()), errors: z.array(ResearchErrorSchema), evidence: z.array(EvidenceItemSchema),
+    analysis: ResearchAnalysisSchema.optional(),
+    // modelTokens stays 0: it describes the deterministic executor. Metered AI-assisted summary usage is reported in usage.model.
+    usage: z.strictObject({ rpcCalls: z.number().int().nonnegative(), maximumRpcCalls: z.number().int().positive(), elapsedMs: z.number().int().nonnegative(), modelTokens: z.literal(0), providerCostAtomic: z.null(), providerCostStatus: z.literal('unpriced'), model: ModelUsageSchema.optional() }),
+}).superRefine((report, ctx) => {
+    if ((report.analysis === undefined) !== (report.usage.model === undefined))
+        ctx.addIssue({ code: 'custom', path: ['analysis'], message: 'An AI-assisted summary section and usage.model must be reported together.' });
+    if (report.analysis) {
+        const completed = report.analysis.status === 'completed';
+        if (completed === (report.analysis.unavailableReason !== undefined))
+            ctx.addIssue({ code: 'custom', path: ['analysis', 'unavailableReason'], message: 'Only a summary that did not complete states an unavailable or skipped reason.' });
+        if (!completed && report.analysis.findings.length)
+            ctx.addIssue({ code: 'custom', path: ['analysis', 'findings'], message: 'Only a completed AI-assisted summary can contain findings.' });
+        if (report.analysis.status === 'skipped' && report.usage.model && (report.usage.model.inputTokens || report.usage.model.outputTokens || report.usage.model.costMicrousd))
+            ctx.addIssue({ code: 'custom', path: ['usage', 'model'], message: 'A skipped AI-assisted summary records no model usage.' });
+        if (report.usage.model?.costStatus === 'unresolved' && (report.analysis.status !== 'unavailable' || report.analysis.findings.length || report.usage.model.inputTokens || report.usage.model.outputTokens || report.usage.model.costMicrousd < 1))
+            ctx.addIssue({ code: 'custom', path: ['usage', 'model', 'costStatus'], message: 'An unresolved model cost belongs to an unavailable summary without findings and states its reserved maximum, never zero.' });
+        const evidenceIds = new Set(report.evidence.map((item) => item.id));
+        for (const finding of report.analysis.findings)
+            for (const id of finding.evidenceIds)
+                if (!evidenceIds.has(id))
+                    ctx.addIssue({ code: 'custom', path: ['analysis', 'findings'], message: `AI-assisted finding cites unknown evidence ${id}` });
+    }
+    const policy = resolveResearchPolicy(report);
+    const selectable = { owner: policy.readOwner, implementation: policy.readProxySlots, admin: policy.readProxySlots, beacon: policy.readProxySlots };
+    for (const [control, enabled] of Object.entries(selectable)) {
+        const observation = report.controls[control];
+        if (enabled === (observation.status === 'skipped'))
+            ctx.addIssue({ code: 'custom', path: ['controls', control], message: 'Skipped control status must match the resolved immutable research policy.' });
+    }
+    const requiredObservations = [...Object.values(report.metadata), ...Object.values(report.contract), ...Object.values(report.coverage), report.controls.mintAuthority, report.controls.freezeAuthority, report.controls.upgradeability];
+    if (requiredObservations.some((item) => item.status === 'skipped'))
+        ctx.addIssue({ code: 'custom', message: 'Only the selectable owner and EIP-1967 slot controls can be intentionally skipped.' });
+    if (!policy.readProxySlots && report.controls.upgradeability.status !== 'unknown')
+        ctx.addIssue({ code: 'custom', path: ['controls', 'upgradeability'], message: 'Upgradeability remains unknown when proxy inspection is disabled.' });
+    if (!policy.readProxySlots && (report.evidence.some((item) => item.source.method === 'eth_getStorageAt') || report.findings.some((item) => item.code.startsWith('eip1967-'))))
+        ctx.addIssue({ code: 'custom', message: 'Disabled proxy checks cannot have RPC receipts or proxy-slot findings.' });
+    if (!policy.readOwner && report.evidence.some((item) => item.source.method === 'eth_call' && item.request[0] !== null && typeof item.request[0] === 'object' && !Array.isArray(item.request[0]) && typeof item.request[0].data === 'string' && /^0x8da5cb5b/i.test(item.request[0].data)))
+        ctx.addIssue({ code: 'custom', message: 'A disabled owner check cannot have an owner() RPC receipt.' });
+    const ids = new Set(report.evidence.map((item) => item.id));
+    if (ids.size !== report.evidence.length)
+        ctx.addIssue({ code: 'custom', message: 'Duplicate evidence id' });
+    if ((report.market === undefined) !== (report.marketPolicy === undefined))
+        ctx.addIssue({ code: 'custom', path: ['market'], message: 'A market section and its market policy must be reported together.' });
+    if (report.market && report.marketPolicy) {
+        if ((report.market.pools.status === 'skipped') === report.marketPolicy.discoverPools)
+            ctx.addIssue({ code: 'custom', path: ['market', 'pools'], message: 'Skipped pool discovery must match the market policy.' });
+        if ((report.market.recentHolderActivity.status === 'skipped') === report.marketPolicy.recentHolderActivity)
+            ctx.addIssue({ code: 'custom', path: ['market', 'recentHolderActivity'], message: 'Skipped holder activity must match the market policy.' });
+    }
+    const marketReferences = report.market ? [report.market.pools, ...report.market.pools.pools, report.market.recentHolderActivity, ...report.market.recentHolderActivity.accounts] : [];
+    const references = [...Object.values(report.metadata), ...Object.values(report.contract), ...Object.values(report.controls), ...Object.values(report.coverage), ...report.findings, ...marketReferences];
+    for (const item of references)
+        for (const id of item.evidenceIds)
+            if (!ids.has(id))
+                ctx.addIssue({ code: 'custom', message: `Unknown evidence reference ${id}` });
+    for (const error of report.errors)
+        if (error.evidenceId && !ids.has(error.evidenceId))
+            ctx.addIssue({ code: 'custom', message: `Unknown error evidence reference ${error.evidenceId}` });
+    for (const item of report.evidence)
+        if (contentHash(item.result) !== item.contentHash)
+            ctx.addIssue({ code: 'custom', message: 'Evidence content hash does not match its captured result' });
+});