agentex-creator-sdk 1.0.0

package/dist/packages/providers/src/keyed.js

@@ -0,0 +1,240 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { parseJsonWithBigInts, stringifyJsonWithBigInts } from '@solana/rpc-spec-types';
+import { z } from 'zod';
+export class KeyedProviderError extends Error {
+    category;
+    status;
+    rpcCode;
+    constructor(category, message, status = null, rpcCode = null) {
+        super(message);
+        this.category = category;
+        this.status = status;
+        this.rpcCode = rpcCode;
+        this.name = 'KeyedProviderError';
+    }
+}
+/** Free-tier figures and terms were read from provider pricing, CU-cost and legal pages on 2026-09-14. Caps stay far below them. */
+export const KEYED_PROVIDER_POLICIES = Object.freeze({
+    alchemy: Object.freeze({
+        id: 'alchemy', credentialReference: 'ALCHEMY_API_KEY', unit: 'compute-unit', hosts: Object.freeze({ ethereum: 'eth-mainnet.g.alchemy.com', base: 'base-mainnet.g.alchemy.com', robinhood: 'robinhood-mainnet.g.alchemy.com', 'robinhood-testnet': 'robinhood-testnet.g.alchemy.com' }),
+        unitCosts: Object.freeze({ eth_chainId: 0, eth_getBlockByNumber: 20, eth_getBlockByHash: 20, eth_call: 26, eth_getLogs: 60, eth_getCode: 20, eth_getStorageAt: 20, eth_getBalance: 20, eth_getTransactionCount: 20, eth_getTransactionByHash: 20, eth_getTransactionReceipt: 20, debug_traceTransaction: 40, trace_filter: 40, alchemy_getAssetTransfers: 120, alchemy_getTokenBalances: 20, alchemy_getTokenMetadata: 10, alchemy_getContractMetadata: 160 }),
+        // Pay-as-you-go at $0.525 per 1M CU: 3M CU a day caps spend near $1.60 a day across every run, while one step stays within 2,000 CU.
+        defaultUnitCost: 60, perRunUnits: 2000, perDayUnits: 3000000, minimumSpacingMs: Object.freeze({}), defaultSpacingMs: 100,
+        freeTier: 'Pay-as-you-go (owner-confirmed 26 Sep 2026): $0.525 per 1M CU, 300 requests/second (alchemy.com/pricing). CU costs from alchemy.com/docs/reference/compute-unit-costs, read 26 Sep 2026.',
+        terms: 'legal.alchemy.com, plus written approval from Alchemy (September 2026) for AGENTEX to use Alchemy data in its paid reports, exports and shares. Buyers never get pass-through access to Alchemy; proprietary notices are kept.', checkedAt: '2026-09-26T00:00:00.000Z', billing: 'pay-as-you-go-units-metered'
+    }),
+    helius: Object.freeze({
+        id: 'helius', credentialReference: 'HELIUS_API_KEY', unit: 'credit', hosts: Object.freeze({ solana: 'mainnet.helius-rpc.com' }),
+        unitCosts: Object.freeze({ getGenesisHash: 1, getSlot: 1, getAccountInfo: 1, getTransaction: 10, getSignaturesForAddress: 1, getTransactionsForAddress: 10, getTokenAccounts: 10, getAsset: 10 }),
+        defaultUnitCost: 10, perRunUnits: 200, perDayUnits: 15000, minimumSpacingMs: Object.freeze({ getTokenAccounts: 1000, getAsset: 1000 }), defaultSpacingMs: 250,
+        freeTier: 'Free: 1M credits/month, 10 RPC requests/second, 2 DAS requests/second (helius.dev/pricing). Standard RPC 1 credit; archival and DAS 10; getTransactionsForAddress 10 credits per call (signatures) or per 100 transactions (full).',
+        billing: 'free-tier-units-not-invoiced',
+        terms: 'helius.dev/terms: no sublicensing, reselling, distributing or otherwise allowing use of the products for the benefit of third parties. Treated as internal evaluation only until an explicit licence review.', checkedAt: '2026-09-14T00:00:00.000Z'
+    }),
+});
+const dayOf = (at) => at.toISOString().slice(0, 10);
+/** Process-wide usage. It holds counters only: no request parameters, results, tenants or credentials. */
+export class KeyedUsageLedger {
+    #days = new Map();
+    #last = new Map();
+    #totals = new Map();
+    reserve(policy, units, at) {
+        const key = `${policy.id}:${dayOf(at)}`;
+        const used = this.#days.get(key) ?? 0;
+        if (used + units > policy.perDayUnits)
+            throw new KeyedProviderError('budget-exhausted', `The daily ${policy.id} ${policy.unit} cap is reached.`);
+        this.#days.set(key, used + units);
+        for (const stale of this.#days.keys())
+            if (!stale.endsWith(dayOf(at)) && stale.startsWith(`${policy.id}:`))
+                this.#days.delete(stale);
+    }
+    async space(policy, method, signal, now) {
+        const gap = policy.minimumSpacingMs[method] ?? policy.defaultSpacingMs;
+        const key = `${policy.id}:${gap === policy.defaultSpacingMs ? 'default' : method}`;
+        const wait = (this.#last.get(key) ?? 0) + gap - now();
+        this.#last.set(key, Math.max(now(), (this.#last.get(key) ?? 0) + gap));
+        if (wait > 0)
+            await delay(wait, undefined, { signal });
+    }
+    count(provider, event) {
+        const entry = this.#totals.get(provider) ?? { requests: 0, units: 0, rateLimited: 0, failures: 0 };
+        entry.requests++;
+        entry.units += event.units ?? 0;
+        if (event.rateLimited)
+            entry.rateLimited++;
+        if (event.failed)
+            entry.failures++;
+        this.#totals.set(provider, entry);
+    }
+    snapshot(at = new Date()) {
+        return Object.keys(KEYED_PROVIDER_POLICIES).map((id) => ({ provider: id, unit: KEYED_PROVIDER_POLICIES[id].unit, dayUnitsUsed: this.#days.get(`${id}:${dayOf(at)}`) ?? 0, dayUnitsCap: KEYED_PROVIDER_POLICIES[id].perDayUnits, ...(this.#totals.get(id) ?? { requests: 0, units: 0, rateLimited: 0, failures: 0 }), costUsd: null, costStatus: KEYED_PROVIDER_POLICIES[id].billing }));
+    }
+}
+export const KEYED_USAGE = new KeyedUsageLedger();
+let activeUsage = KEYED_USAGE;
+/** Server wiring replaces the process-local default with the database-backed ledger so the daily cap is shared and survives restarts. */
+export const setKeyedUsageLedger = (ledger) => { activeUsage = ledger; };
+export const activeKeyedUsage = () => activeUsage;
+export class RunUnitBudget {
+    maximum;
+    #used = 0;
+    constructor(maximum) {
+        this.maximum = maximum;
+        z.number().int().min(1).max(100000).parse(maximum);
+    }
+    get used() { return this.#used; }
+    reserve(units) { if (this.#used + units > this.maximum)
+        throw new KeyedProviderError('budget-exhausted', 'The per-run provider unit budget is exhausted.'); this.#used += units; }
+}
+export const keyedCredentialAvailable = (provider, env = process.env) => /^[A-Za-z0-9_-]{16,128}$/.test(env[KEYED_PROVIDER_POLICIES[provider].credentialReference] ?? '');
+export const keyedProviderHost = (provider, chain) => KEYED_PROVIDER_POLICIES[provider].hosts[chain] ?? null;
+/** Removes any configured credential from text before it can reach a log, error or artifact. */
+export function redactCredentials(text, env = process.env) {
+    let result = text;
+    for (const policy of Object.values(KEYED_PROVIDER_POLICIES)) {
+        const value = env[policy.credentialReference];
+        if (value && value.length >= 8)
+            result = result.split(value).join(`[${policy.credentialReference}]`);
+    }
+    return result.replace(/api-key=[^&\s"']+/gi, 'api-key=[redacted]').replace(/\/v2\/[A-Za-z0-9_-]{16,}/g, '/v2/[redacted]').replace(/\/nft\/v3\/[A-Za-z0-9_-]{16,}/g, '/nft/v3/[redacted]');
+}
+async function readBounded(response, maximum) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        return '';
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            size += chunk.value.length;
+            if (size > maximum) {
+                await reader.cancel();
+                throw new KeyedProviderError('limit-exceeded', 'The provider response exceeds the byte limit.');
+            }
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export function createKeyedTransport(provider, chain, options) {
+    const policy = KEYED_PROVIDER_POLICIES[provider];
+    const host = keyedProviderHost(provider, chain);
+    if (!host)
+        throw new KeyedProviderError('unsupported', `${provider} is not configured for ${chain}.`);
+    if (!(options?.runBudget instanceof RunUnitBudget))
+        throw new KeyedProviderError('budget-exhausted', 'Every keyed provider transport needs a per-run unit budget.');
+    if (options.runBudget.maximum > policy.perRunUnits)
+        throw new KeyedProviderError('limit-exceeded', `The per-run budget exceeds the ${provider} policy of ${policy.perRunUnits} ${policy.unit}s.`);
+    const env = options.env ?? process.env;
+    const usage = options.usage ?? activeUsage;
+    const now = options.now ?? (() => new Date());
+    const attemptsAllowed = 1 + (options.maximumRetries ?? 1);
+    const request = options.fetch ?? fetch;
+    const maximumBytes = options.maximumResponseBytes ?? 1048576;
+    let unitsUsed = 0;
+    let attempts = 0;
+    return {
+        provider, host, get unitsUsed() { return unitsUsed; },
+        async request(method, params, signal) {
+            const key = env[policy.credentialReference];
+            if (!keyedCredentialAvailable(provider, env) || !key)
+                throw new KeyedProviderError('credential-required', `${policy.credentialReference} is not configured on the server.`);
+            const units = policy.unitCosts[method] ?? policy.defaultUnitCost;
+            for (let retry = 0; retry < attemptsAllowed; retry++) {
+                if (signal.aborted)
+                    throw new KeyedProviderError(signal.reason?.name === 'TimeoutError' ? 'timeout' : 'cancelled', 'The request was interrupted.');
+                options.runBudget.reserve(units);
+                await usage.reserve(policy, units, now());
+                await options.beforeAttempt?.({ provider, method, attempt: ++attempts, units });
+                await usage.space(policy, method, signal, () => Date.now());
+                unitsUsed += units;
+                let url;
+                let init;
+                if (provider === 'alchemy' && method === 'alchemy_getContractMetadata') {
+                    const contract = String(params[0]);
+                    if (!/^0x[a-fA-F0-9]{40}$/.test(contract))
+                        throw new KeyedProviderError('request-rejected', 'A contract address is required.');
+                    url = `https://${host}/nft/v3/${key}/getContractMetadata?contractAddress=${contract}`;
+                    init = { method: 'GET', headers: { accept: 'application/json' } };
+                }
+                else {
+                    url = provider === 'alchemy' ? `https://${host}/v2/${key}` : `https://${host}/?api-key=${key}`;
+                    const payload = { jsonrpc: '2.0', id: 1, method, params: provider === 'helius' && ['getTokenAccounts', 'getAsset'].includes(method) ? params[0] : params };
+                    init = { method: 'POST', headers: { 'content-type': 'application/json', accept: 'application/json' }, body: stringifyJsonWithBigInts(payload) };
+                }
+                let response;
+                try {
+                    response = await request(url, { ...init, redirect: 'error', signal: AbortSignal.any([signal, AbortSignal.timeout(options.timeoutMs ?? 10000)]) });
+                }
+                catch {
+                    usage.count(provider, { units, failed: true });
+                    if (signal.aborted)
+                        throw new KeyedProviderError(signal.reason?.name === 'TimeoutError' ? 'timeout' : 'cancelled', 'The request was interrupted.');
+                    throw new KeyedProviderError('provider-unavailable', `${provider} could not be reached.`);
+                }
+                if (response.status === 429) {
+                    usage.count(provider, { units, rateLimited: true });
+                    await response.body?.cancel().catch(() => undefined);
+                    const retryAfter = Math.min(5, Math.max(1, Number.parseInt(response.headers.get('retry-after') ?? '1', 10) || 1));
+                    if (retry + 1 < attemptsAllowed) {
+                        await delay(retryAfter * 1000, undefined, { signal });
+                        continue;
+                    }
+                    throw new KeyedProviderError('rate-limited', `${provider} rate limited the request after one bounded retry.`, 429);
+                }
+                let text;
+                try {
+                    text = await readBounded(response, maximumBytes);
+                }
+                catch (error) {
+                    usage.count(provider, { units, failed: true });
+                    if (error instanceof KeyedProviderError)
+                        throw error;
+                    throw new KeyedProviderError('provider-unavailable', `${provider} returned an unreadable body.`);
+                }
+                if (response.status === 401 || response.status === 403) {
+                    usage.count(provider, { units, failed: true });
+                    throw new KeyedProviderError(/plan|upgrade|not available|not enabled|tier/i.test(text) ? 'plan-restricted' : 'credential-required', `${provider} refused this method for the configured key or plan.`, response.status);
+                }
+                if (response.status === 404 && provider === 'alchemy') {
+                    usage.count(provider, { units, failed: true });
+                    throw new KeyedProviderError('unsupported', `${provider} does not serve this method on ${chain}.`, 404);
+                }
+                let body;
+                try {
+                    body = (provider === 'helius' ? parseJsonWithBigInts(text) : JSON.parse(text));
+                }
+                catch {
+                    usage.count(provider, { units, failed: true });
+                    throw new KeyedProviderError(response.ok ? 'invalid-response' : 'provider-unavailable', `${provider} returned a non-JSON response (HTTP ${response.status}).`, response.status);
+                }
+                if (!response.ok && !body.error) {
+                    usage.count(provider, { units, failed: true });
+                    throw new KeyedProviderError('provider-unavailable', `${provider} returned HTTP ${response.status}.`, response.status);
+                }
+                if (method === 'alchemy_getContractMetadata' && provider === 'alchemy') {
+                    usage.count(provider, { units });
+                    return body;
+                }
+                if (body.error) {
+                    usage.count(provider, { units, failed: true });
+                    const code = typeof body.error.code === 'number' ? body.error.code : null;
+                    const message = typeof body.error.message === 'string' ? body.error.message.toLowerCase() : '';
+                    const category = code === 429 || code === -32005 || /rate limit|too many/.test(message) ? 'rate-limited' : /plan|upgrade|not available on|paid|tier/.test(message) || code === -32403 ? 'plan-restricted'
+                        : /header not found|unknown block|not currently canonical|missing trie/.test(message) ? 'history-unavailable'
+                            : code === 3 || /revert/.test(message) ? 'execution-result' : code === -32601 ? 'unsupported' : code === -32602 ? 'request-rejected' : 'provider-unavailable';
+                    throw new KeyedProviderError(category, `${provider} returned a JSON-RPC error (${category}).`, response.status, code);
+                }
+                usage.count(provider, { units });
+                return body.result;
+            }
+            throw new KeyedProviderError('rate-limited', `${provider} rate limited the request.`, 429);
+        },
+    };
+}

package/dist/packages/providers/src/snapshot.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Per-chain read-snapshot policy. Owner rule (2026-09-15): no part of the project waits for finality; reads are instant. Every EVM
+ * run reads the provider's `latest` block (sequencer-confirmed), pins it for the whole run and re-reads that height at completion:
+ * Ethereum and Base name the pinned block number in every state read, Robinhood Chain names the pinned block hash (EIP-1898
+ * `requireCanonical`). A changed hash marks the snapshot `changed`, so a reorg becomes an explicit failure or correction, never a wait.
+ * The confirmation level is always reported and never presented as finality. `finalized` and `safe` remain in the confirmation type
+ * only so reports captured before the rule still parse and render honestly; no policy reads them.
+ */
+export type SnapshotTag = 'latest';
+export type ReadConfirmation = 'finalized' | 'safe' | 'sequencer-confirmed';
+export interface ReadSnapshotPolicy {
+    chain: string;
+    chainId: number;
+    tags: readonly SnapshotTag[];
+    pinBy: 'number' | 'hash';
+    confirmationOf: Readonly<Record<SnapshotTag, ReadConfirmation>>;
+    basis: string;
+}
+export declare const CONFIRMATION_NOTES: Readonly<Record<ReadConfirmation, string>>;
+export declare const READ_SNAPSHOT_POLICIES: Readonly<Record<string, ReadSnapshotPolicy>>;
+export declare class ReadSnapshotError extends Error {
+    readonly category: 'unsupported' | 'chain-mismatch' | 'invalid-response' | 'snapshot-changed' | 'provider-unavailable';
+    constructor(category: 'unsupported' | 'chain-mismatch' | 'invalid-response' | 'snapshot-changed' | 'provider-unavailable', message: string);
+}
+export declare function readSnapshotPolicy(chain: string): ReadSnapshotPolicy;
+/** The block parameter for state reads: the pinned block number, or the pinned canonical block hash on hash-pinned chains. */
+export declare function snapshotBlockTag(block: {
+    blockNumber: string;
+    blockHash: string;
+    pinBy: 'number' | 'hash';
+}): string | {
+    blockHash: string;
+    requireCanonical: true;
+};
+export interface ChainReadTransport {
+    request(method: string, params: readonly unknown[], signal: AbortSignal): Promise<unknown>;
+}
+export interface PinnedReadSnapshot {
+    chain: string;
+    chainId: number;
+    blockNumber: string;
+    blockHash: string;
+    timestamp: string;
+    tag: SnapshotTag;
+    confirmation: ReadConfirmation;
+    note: string;
+    blockTag: string | {
+        blockHash: string;
+        requireCanonical: true;
+    };
+}
+/**
+ * Chain-read helper for services outside the tool recorder: verifies chain identity, pins the latest block under the chain's policy
+ * and returns the block tag every later read must use.
+ */
+export declare function pinReadSnapshot(chain: string, transport: ChainReadTransport, signal?: AbortSignal): Promise<PinnedReadSnapshot>;
+/** Rechecks that the pinned hash is still canonical at its height. `changed` means every read made at the snapshot must be discarded. */
+export declare function recheckReadSnapshot(pinned: PinnedReadSnapshot, transport: ChainReadTransport, signal?: AbortSignal): Promise<{
+    status: 'unchanged' | 'changed';
+    observedHash: string | null;
+}>;

package/dist/packages/providers/src/snapshot.js

@@ -0,0 +1,77 @@
+const CONFIRMATION_OF = Object.freeze({ latest: 'sequencer-confirmed' });
+export const CONFIRMATION_NOTES = Object.freeze({
+    finalized: 'Recorded before the instant-read rule: the snapshot was the configured provider\'s finalized tag, which is not independent consensus verification.',
+    safe: 'Recorded before the instant-read rule: the snapshot was the provider\'s safe block (batch posted to the parent chain); it was not finalized.',
+    'sequencer-confirmed': 'Snapshot is the latest block (sequencer-confirmed) when the run started. It is not finalized: a reorg can still replace it. Every state read names this block, and its hash is rechecked at completion; a changed hash is reported, never hidden.',
+});
+const INSTANT = 'Owner rule: reads never wait for finality. The latest block is pinned for the run and its hash is rechecked at completion.';
+const policy = (chain, chainId, pinBy, basis) => Object.freeze({ chain, chainId, tags: Object.freeze(['latest']), pinBy, confirmationOf: CONFIRMATION_OF, basis });
+const ROBINHOOD = `${INSTANT} Robinhood Chain state reads name the pinned block hash (EIP-1898); the official RPC served hash-pinned state on 2026-09-14.`;
+export const READ_SNAPSHOT_POLICIES = Object.freeze({
+    ethereum: policy('ethereum', 1, 'number', INSTANT),
+    base: policy('base', 8453, 'number', INSTANT),
+    robinhood: policy('robinhood', 4663, 'hash', ROBINHOOD),
+    'robinhood-testnet': policy('robinhood-testnet', 46630, 'hash', ROBINHOOD),
+});
+export class ReadSnapshotError extends Error {
+    category;
+    constructor(category, message) {
+        super(message);
+        this.category = category;
+        this.name = 'ReadSnapshotError';
+    }
+}
+export function readSnapshotPolicy(chain) {
+    const policy = READ_SNAPSHOT_POLICIES[chain];
+    if (!policy)
+        throw new ReadSnapshotError('unsupported', `No read-snapshot policy is registered for ${chain}.`);
+    return policy;
+}
+/** The block parameter for state reads: the pinned block number, or the pinned canonical block hash on hash-pinned chains. */
+export function snapshotBlockTag(block) {
+    return block.pinBy === 'hash' ? { blockHash: block.blockHash, requireCanonical: true } : `0x${BigInt(block.blockNumber).toString(16)}`;
+}
+const quantity = (value) => { if (typeof value !== 'string' || !/^0x[0-9a-fA-F]{1,64}$/.test(value))
+    throw new ReadSnapshotError('invalid-response', 'Expected a hex quantity.'); return BigInt(value); };
+function parseHeader(value) {
+    const block = value;
+    if (!block || typeof block.hash !== 'string' || !/^0x[a-fA-F0-9]{64}$/.test(block.hash))
+        throw new ReadSnapshotError('invalid-response', 'Malformed block header.');
+    return { blockNumber: quantity(block.number).toString(), blockHash: block.hash.toLowerCase(), timestamp: quantity(block.timestamp).toString() };
+}
+/**
+ * Chain-read helper for services outside the tool recorder: verifies chain identity, pins the latest block under the chain's policy
+ * and returns the block tag every later read must use.
+ */
+export async function pinReadSnapshot(chain, transport, signal = AbortSignal.timeout(20000)) {
+    const policy = readSnapshotPolicy(chain);
+    if (quantity(await transport.request('eth_chainId', [], signal)) !== BigInt(policy.chainId))
+        throw new ReadSnapshotError('chain-mismatch', `The RPC is not ${chain}.`);
+    for (const [index, tag] of policy.tags.entries()) {
+        const last = index === policy.tags.length - 1;
+        let result;
+        try {
+            result = await transport.request('eth_getBlockByNumber', [tag, false], signal);
+        }
+        catch (error) {
+            if (last || signal.aborted)
+                throw error;
+            continue;
+        }
+        if (result === null) {
+            if (last)
+                throw new ReadSnapshotError('provider-unavailable', `The RPC returned no ${tag} block.`);
+            continue;
+        }
+        const block = parseHeader(result);
+        const confirmation = policy.confirmationOf[tag];
+        return { chain, chainId: policy.chainId, ...block, tag, confirmation, note: CONFIRMATION_NOTES[confirmation], blockTag: snapshotBlockTag({ ...block, pinBy: policy.pinBy }) };
+    }
+    throw new ReadSnapshotError('provider-unavailable', 'No snapshot tag was served.');
+}
+/** Rechecks that the pinned hash is still canonical at its height. `changed` means every read made at the snapshot must be discarded. */
+export async function recheckReadSnapshot(pinned, transport, signal = AbortSignal.timeout(20000)) {
+    const result = await transport.request('eth_getBlockByNumber', [`0x${BigInt(pinned.blockNumber).toString(16)}`, false], signal);
+    const observedHash = result === null ? null : parseHeader(result).blockHash;
+    return { status: observedHash === pinned.blockHash ? 'unchanged' : 'changed', observedHash };
+}

package/dist/packages/publication/src/fixtures.d.ts

@@ -0,0 +1,45 @@
+import { type AgentManifest, type ResearchInput, type TokenResearchReport } from '../../contracts/src/index.js';
+export declare const EVALUATION_SUITE_VERSION = "token-researcher-local-fixtures-v1";
+export declare const EVALUATION_SUITE_HASH: string;
+/**
+ * Token Researcher 0.3.0 (market policy) suite. v1 above is unchanged, so every earlier evaluation keeps its hash. A version with `marketPolicy`
+ * runs the v1 cases plus market cases, and the report's market section must equal its derivation from the captured receipts.
+ */
+export declare const MARKET_EVALUATION_SUITE_VERSION = "token-researcher-local-fixtures-v2";
+export declare const MARKET_EVALUATION_SUITE_HASH: string;
+/** Suite version and hash for a Token Researcher manifest: v2 when it declares a market policy, otherwise the unchanged v1. */
+export declare const tokenResearchSuiteFor: (manifest: {
+    marketPolicy?: unknown;
+}) => {
+    version: string;
+    hash: string;
+};
+export interface FixtureResult {
+    id: string;
+    chain: string;
+    passed: boolean;
+    issues: string[];
+    report: TokenResearchReport | null;
+    reportHash: string | null;
+    transportCalls: number;
+}
+export interface EvaluationSnapshot {
+    kind: 'deterministic_fixture_evaluation';
+    visibility: 'local_only';
+    suiteVersion: string;
+    suiteHash: string;
+    manifestHash: string;
+    status: 'passed' | 'failed';
+    summary: {
+        passed: number;
+        total: number;
+        issues: string[];
+    };
+    fixtures: FixtureResult[];
+    limitations: string[];
+}
+/** This invariant is shared by local review and fixtures; callers still must verify the stored run/checkpoint binding. */
+export declare function canonicalMetadataObserved(report: TokenResearchReport): boolean;
+export declare function validateReportBinding(raw: unknown, manifest: AgentManifest, input: ResearchInput): TokenResearchReport;
+/** No creator-supplied fixture, executor, URL, time, or expected output is accepted. */
+export declare function evaluateManifest(manifest: AgentManifest): Promise<EvaluationSnapshot>;