agentex-creator-sdk 1.0.0

package/dist/packages/inspector/src/decode.d.ts

@@ -0,0 +1,23 @@
+import { type Address } from 'viem';
+import type { DecodedAction, TransactionInspectionInput, TransactionInspectionReport } from '../../contracts/src/inspection.js';
+/** Pure, offline calldata decoding. Unknown selectors stay unknown; nothing is looked up in public signature databases. */
+export declare const MAX_UINT256: bigint;
+export declare const MAX_MULTICALL_DEPTH = 2;
+export declare const MAX_DECODED_ACTIONS = 32;
+export declare const MAX_GRANTEES = 3;
+export interface DecodedGrant {
+    role: 'spender' | 'operator';
+    grantee: Address;
+    owner: Address;
+    approved: boolean;
+    actionPaths: string[];
+}
+export interface DecodedTransaction {
+    transaction: TransactionInspectionReport['transaction'];
+    actions: DecodedAction[];
+    grants: DecodedGrant[];
+    omittedGrants: number;
+    tokenFamily: 'fungible' | 'non-fungible' | null;
+    actionLimitReached: boolean;
+}
+export declare function decodeTransaction(input: TransactionInspectionInput): DecodedTransaction;

package/dist/packages/inspector/src/decode.js

@@ -0,0 +1,150 @@
+import { decodeFunctionData, encodeFunctionData, formatUnits, getAddress, keccak256, parseAbiItem, toFunctionSelector } from 'viem';
+/** Pure, offline calldata decoding. Unknown selectors stay unknown; nothing is looked up in public signature databases. */
+export const MAX_UINT256 = 2n ** 256n - 1n;
+export const MAX_MULTICALL_DEPTH = 2;
+export const MAX_DECODED_ACTIONS = 32;
+export const MAX_GRANTEES = 3;
+const INLINE_BYTES = 256;
+const GENERIC_NOTE = 'Decoded from the selector and canonical ABI encoding; the target is not verified to implement this standard.';
+const DECODERS = [
+    ['erc20.transfer', 'function transfer(address to, uint256 amount)'],
+    ['erc20.approve', 'function approve(address spender, uint256 amount)'],
+    ['erc20-or-erc721.transferFrom', 'function transferFrom(address from, address to, uint256 amountOrTokenId)'],
+    ['erc20.increaseAllowance', 'function increaseAllowance(address spender, uint256 addedValue)'],
+    ['erc20.decreaseAllowance', 'function decreaseAllowance(address spender, uint256 subtractedValue)'],
+    ['eip2612.permit', 'function permit(address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s)'],
+    ['erc721-or-erc1155.setApprovalForAll', 'function setApprovalForAll(address operator, bool approved)'],
+    ['erc721.safeTransferFrom', 'function safeTransferFrom(address from, address to, uint256 tokenId)'],
+    ['erc721.safeTransferFrom', 'function safeTransferFrom(address from, address to, uint256 tokenId, bytes data)'],
+    ['erc1155.safeTransferFrom', 'function safeTransferFrom(address from, address to, uint256 id, uint256 amount, bytes data)'],
+    ['weth.deposit', 'function deposit()'],
+    ['weth.withdraw', 'function withdraw(uint256 amount)'],
+    ['multicall', 'function multicall(bytes[] data)'],
+];
+const NOTES = {
+    'erc20.approve': 'ERC-721 approve(address,uint256) shares this selector; for an ERC-721 target the amount is a token id.',
+    'erc20-or-erc721.transferFrom': 'ERC-20 and ERC-721 transferFrom share this selector; the third value is an amount or a token id depending on the target.',
+    'eip2612.permit': 'Submits an off-chain signed allowance for the stated owner. The signature is not verified here; v, r and s remain only in the input calldata.',
+    'erc721-or-erc1155.setApprovalForAll': 'Grants or revokes an operator over every token of this contract held by the owner (ERC-721 and ERC-1155 share this selector).',
+    'weth.deposit': 'Interpreted as WETH-style wrapping by selector only; other contracts use deposit() differently.',
+    'weth.withdraw': 'Interpreted as WETH-style unwrapping by selector only; vaults and other contracts use withdraw(uint256) differently.',
+    multicall: 'Inner calls are decoded as calls to the same target (self-multicall); an implementation can route them differently.',
+};
+const TABLE = new Map(DECODERS.map(([kind, signature]) => { const abi = parseAbiItem(signature); return [toFunctionSelector(abi), { kind, abi, signature: `${abi.name}(${abi.inputs.map((input) => input.type).join(',')})` }]; }));
+const FUNGIBLE = new Set(['erc20.transfer', 'erc20.approve', 'erc20-or-erc721.transferFrom', 'erc20.increaseAllowance', 'erc20.decreaseAllowance', 'eip2612.permit', 'weth.deposit', 'weth.withdraw']);
+const NON_FUNGIBLE = new Set(['erc721-or-erc1155.setApprovalForAll', 'erc721.safeTransferFrom', 'erc1155.safeTransferFrom']);
+const bytesOf = (data) => (data.length - 2) / 2;
+function formatArgument(type, value) {
+    if (type === 'address')
+        return getAddress(value);
+    if (type === 'bool')
+        return value === true;
+    if (/^u?int\d*$/.test(type))
+        return value.toString();
+    const hex = value.toLowerCase();
+    if (type === 'bytes' && bytesOf(hex) > INLINE_BYTES)
+        return `${bytesOf(hex)} bytes, keccak256 ${keccak256(hex)}`;
+    return hex;
+}
+function decodeCall(data, target, path, depth, state) {
+    if (state.actions.length >= MAX_DECODED_ACTIONS) {
+        state.limit = true;
+        return;
+    }
+    const base = { path, depth, target };
+    if (bytesOf(data) < 4) {
+        state.actions.push({ ...base, status: 'invalid', kind: 'unknown', selector: null, signature: null, arguments: { dataBytes: String(bytesOf(data)) }, notes: ['Calldata is shorter than a four-byte function selector.'] });
+        return;
+    }
+    const selector = data.slice(0, 10);
+    const decoder = TABLE.get(selector);
+    const unknown = (status, note) => state.actions.push({ ...base, status, kind: 'unknown', selector, signature: null, arguments: { dataBytes: String(bytesOf(data)) }, notes: [note] });
+    if (!decoder) {
+        unknown('unknown', 'No supported decoder exists for this selector. Its effect is not guessed.');
+        return;
+    }
+    let args;
+    try {
+        args = decodeFunctionData({ abi: [decoder.abi], data }).args ?? [];
+    }
+    catch {
+        unknown('invalid', `The selector matches ${decoder.signature}, but the arguments are not a valid ABI encoding.`);
+        return;
+    }
+    const canonical = encodeFunctionData({ abi: [decoder.abi], functionName: decoder.abi.name, args }).toLowerCase();
+    const notes = [GENERIC_NOTE, ...(NOTES[decoder.kind] ? [NOTES[decoder.kind]] : [])];
+    if (canonical !== data) {
+        if (!data.startsWith(canonical)) {
+            unknown('invalid', `The selector matches ${decoder.signature}, but the encoding is not canonical; arguments are not reported.`);
+            return;
+        }
+        notes.push(`${bytesOf(data) - bytesOf(canonical)} trailing bytes follow the canonical ABI encoding and are not interpreted.`);
+    }
+    const record = {};
+    decoder.abi.inputs.forEach((input, index) => {
+        if (decoder.kind === 'eip2612.permit' && ['v', 'r', 's'].includes(input.name ?? ''))
+            return;
+        if (decoder.kind === 'multicall') {
+            record.calls = String(args[index].length);
+            return;
+        }
+        record[input.name] = formatArgument(input.type, args[index]);
+    });
+    const action = { ...base, status: 'decoded', kind: decoder.kind, selector, signature: decoder.signature, arguments: record, notes };
+    state.actions.push(action);
+    if (decoder.kind !== 'multicall')
+        return;
+    const calls = args[0];
+    if (depth >= MAX_MULTICALL_DEPTH) {
+        action.status = 'bound-reached';
+        action.notes.push(`The nested multicall depth limit (${MAX_MULTICALL_DEPTH}) was reached; ${calls.length} inner calls are not decoded.`);
+        return;
+    }
+    for (const [index, call] of calls.entries()) {
+        decodeCall(call.toLowerCase(), target, `${path}.${index}`, depth + 1, state);
+        if (state.limit) {
+            action.notes.push(`Decoding stopped at the ${MAX_DECODED_ACTIONS}-action limit; later inner calls are not decoded.`);
+            return;
+        }
+    }
+}
+export function decodeTransaction(input) {
+    const data = input.data.toLowerCase();
+    const kind = input.to === null ? 'contract-creation' : data === '0x' ? 'native-transfer' : 'call';
+    const transaction = { kind, selector: kind === 'call' && bytesOf(data) >= 4 ? data.slice(0, 10) : null, dataBytes: bytesOf(data), dataHash: keccak256(data),
+        valueAtomic: input.value, valueFormatted: formatUnits(BigInt(input.value), 18), valueUnit: 'native-18-decimals' };
+    const state = { actions: [], limit: false };
+    if (input.to === null)
+        state.actions.push({ path: '0', depth: 0, target: null, status: 'decoded', kind: 'contract-creation', selector: null, signature: null,
+            arguments: { initCodeBytes: String(bytesOf(data)), initCodeHash: keccak256(data) }, notes: ['Init code is not decoded. Constructor effects and the deployed runtime code are only partially observable through simulation.'] });
+    else if (data === '0x')
+        state.actions.push({ path: '0', depth: 0, target: getAddress(input.to), status: 'decoded', kind: 'native-transfer', selector: null, signature: null,
+            arguments: { valueAtomic: input.value }, notes: ['Empty calldata. If the target has code, its receive or fallback logic runs and is not decoded.'] });
+    else
+        decodeCall(data, getAddress(input.to), '0', 0, state);
+    const grants = new Map();
+    let omittedGrants = 0;
+    for (const action of state.actions) {
+        if (action.status !== 'decoded')
+            continue;
+        const args = action.arguments;
+        const grant = ['erc20.approve', 'erc20.increaseAllowance', 'erc20.decreaseAllowance'].includes(action.kind) ? { role: 'spender', grantee: getAddress(String(args.spender)), owner: getAddress(input.from), approved: true }
+            : action.kind === 'eip2612.permit' ? { role: 'spender', grantee: getAddress(String(args.spender)), owner: getAddress(String(args.owner)), approved: true }
+                : action.kind === 'erc721-or-erc1155.setApprovalForAll' ? { role: 'operator', grantee: getAddress(String(args.operator)), owner: getAddress(input.from), approved: args.approved === true } : null;
+        if (!grant)
+            continue;
+        const key = `${grant.role}:${grant.owner.toLowerCase()}:${grant.grantee.toLowerCase()}`;
+        const existing = grants.get(key);
+        if (existing) {
+            existing.actionPaths.push(action.path);
+            existing.approved ||= grant.approved;
+        }
+        else if (grants.size < MAX_GRANTEES)
+            grants.set(key, { ...grant, actionPaths: [action.path] });
+        else
+            omittedGrants++;
+    }
+    const decodedKinds = state.actions.filter((action) => action.status === 'decoded').map((action) => action.kind);
+    return { transaction, actions: state.actions, grants: [...grants.values()], omittedGrants, actionLimitReached: state.limit,
+        tokenFamily: decodedKinds.some((item) => FUNGIBLE.has(item)) ? 'fungible' : decodedKinds.some((item) => NON_FUNGIBLE.has(item)) ? 'non-fungible' : null };
+}

package/dist/packages/inspector/src/scope.d.ts

@@ -0,0 +1,87 @@
+import type { InspectionEvidenceItem, TransactionInspectionInput } from '../../contracts/src/inspection.js';
+import { type DecodedGrant } from './decode.js';
+/**
+ * Every state read the inspector may perform is derived from the accepted input alone. The executor builds its
+ * requests here, and the runtime validates saved receipts against the same set, so a receipt cannot widen scope.
+ */
+export declare const READ_ABI: readonly [{
+    readonly name: "name";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly name: "symbol";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly name: "decimals";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+}, {
+    readonly name: "allowance";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "owner";
+    }, {
+        readonly type: "address";
+        readonly name: "spender";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "isApprovedForAll";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "owner";
+    }, {
+        readonly type: "address";
+        readonly name: "operator";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}];
+export declare const INSPECTION_STATE_METHODS: readonly string[];
+export interface RpcRequest {
+    method: string;
+    params: unknown[];
+}
+export declare const blockTagOf: (blockNumber: string) => string;
+/** The sender-context call object. No gas price, nonce or signature is ever supplied. */
+export declare const transactionCall: (input: TransactionInspectionInput) => {
+    data: string;
+    value: string;
+    to?: `0x${string}` | undefined;
+    from: `0x${string}`;
+};
+export declare const inspectionRequests: {
+    code: (address: string, tag: string) => RpcRequest;
+    slot: (address: string, slot: string, tag: string) => RpcRequest;
+    metadata: (address: string, name: "name" | "symbol" | "decimals", tag: string) => RpcRequest;
+    grant: (token: string, grant: DecodedGrant, tag: string) => RpcRequest;
+    simulate: (input: TransactionInspectionInput, tag: string) => RpcRequest;
+    estimate: (input: TransactionInspectionInput, tag: string) => RpcRequest;
+};
+export declare const requestKey: (request: {
+    method: string;
+    params: readonly unknown[];
+}) => string;
+export declare function plannedStateRequestKeys(input: TransactionInspectionInput, tag: string): Set<string>;
+/** Method, snapshot and request-scope rules for an inspector receipt. Schema, chain identity and hash checks stay with the caller. */
+export declare function inspectionReceiptInScope(receipt: InspectionEvidenceItem, input: TransactionInspectionInput): boolean;

package/dist/packages/inspector/src/scope.js

@@ -0,0 +1,64 @@
+import { encodeFunctionData, parseAbi } from 'viem';
+import { contentHash } from '../../contracts/src/index.js';
+import { EIP1967_SLOTS } from '../../research/src/index.js';
+import { decodeTransaction } from './decode.js';
+/**
+ * Every state read the inspector may perform is derived from the accepted input alone. The executor builds its
+ * requests here, and the runtime validates saved receipts against the same set, so a receipt cannot widen scope.
+ */
+export const READ_ABI = parseAbi(['function name() view returns (string)', 'function symbol() view returns (string)', 'function decimals() view returns (uint8)',
+    'function allowance(address owner, address spender) view returns (uint256)', 'function isApprovedForAll(address owner, address operator) view returns (bool)']);
+const READ_GAS = '0x7a120';
+export const INSPECTION_STATE_METHODS = ['eth_getCode', 'eth_getStorageAt', 'eth_call', 'eth_estimateGas'];
+export const blockTagOf = (blockNumber) => `0x${BigInt(blockNumber).toString(16)}`;
+/** The sender-context call object. No gas price, nonce or signature is ever supplied. */
+export const transactionCall = (input) => ({ from: input.from, ...(input.to === null ? {} : { to: input.to }), data: input.data, value: `0x${BigInt(input.value).toString(16)}` });
+export const inspectionRequests = {
+    code: (address, tag) => ({ method: 'eth_getCode', params: [address, tag] }),
+    slot: (address, slot, tag) => ({ method: 'eth_getStorageAt', params: [address, slot, tag] }),
+    metadata: (address, name, tag) => ({ method: 'eth_call', params: [{ to: address, data: encodeFunctionData({ abi: READ_ABI, functionName: name }), gas: READ_GAS }, tag] }),
+    grant: (token, grant, tag) => ({ method: 'eth_call', params: [{ to: token, gas: READ_GAS, data: grant.role === 'spender'
+                    ? encodeFunctionData({ abi: READ_ABI, functionName: 'allowance', args: [grant.owner, grant.grantee] })
+                    : encodeFunctionData({ abi: READ_ABI, functionName: 'isApprovedForAll', args: [grant.owner, grant.grantee] }) }, tag] }),
+    simulate: (input, tag) => ({ method: 'eth_call', params: [transactionCall(input), tag] }),
+    estimate: (input, tag) => ({ method: 'eth_estimateGas', params: [transactionCall(input), tag] }),
+};
+export const requestKey = (request) => contentHash({ method: request.method, params: request.params });
+export function plannedStateRequestKeys(input, tag) {
+    const keys = new Set();
+    const add = (request) => keys.add(requestKey(JSON.parse(JSON.stringify(request))));
+    const requests = inspectionRequests;
+    if (input.to !== null) {
+        add(requests.code(input.to, tag));
+        for (const slot of Object.values(EIP1967_SLOTS))
+            add(requests.slot(input.to, slot, tag));
+        for (const name of ['name', 'symbol', 'decimals'])
+            add(requests.metadata(input.to, name, tag));
+        for (const grant of decodeTransaction(input).grants) {
+            add(requests.code(grant.grantee, tag));
+            add(requests.grant(input.to, grant, tag));
+        }
+    }
+    add(requests.simulate(input, tag));
+    add(requests.estimate(input, tag));
+    return keys;
+}
+/** Method, snapshot and request-scope rules for an inspector receipt. Schema, chain identity and hash checks stay with the caller. */
+export function inspectionReceiptInScope(receipt, input) {
+    const method = receipt.source.method;
+    const params = receipt.request;
+    if (method === 'eth_chainId')
+        return params.length === 0 && receipt.snapshot === null;
+    if (method === 'eth_getBlockByNumber') {
+        // `latest` is the instant-read head; `finalized` only admits receipts checkpointed before that rule.
+        if (params.length !== 2 || params[1] !== false || typeof params[0] !== 'string' || (params[0] !== 'latest' && params[0] !== 'finalized' && !/^0x(?:0|[1-9a-fA-F][a-fA-F0-9]*)$/.test(params[0])))
+            return false;
+        return !receipt.snapshot || params[0] === blockTagOf(receipt.snapshot.blockNumber);
+    }
+    if (!INSPECTION_STATE_METHODS.includes(method) || !receipt.snapshot || (receipt.finality !== 'sequencer-confirmed' && receipt.finality !== 'finalized'))
+        return false;
+    if (input.snapshotBlock !== undefined && receipt.snapshot.blockNumber !== input.snapshotBlock)
+        return false;
+    const tag = blockTagOf(receipt.snapshot.blockNumber);
+    return params.at(-1) === tag && plannedStateRequestKeys(input, tag).has(requestKey({ method, params }));
+}

package/dist/packages/model/src/analysis.d.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+import type { ToolContext, WorkflowToolRegistry } from '../../workflow/src/registry.js';
+import { type TariffTable } from './pricing.js';
+import { type RetryPolicy } from './retry.js';
+import { type ModelClient, type ModelEffort, type ModelUsageEntry } from './types.js';
+/**
+ * G02 bounded analysis node. Deterministic tools produce every on-chain fact; the model chooses permitted investigative steps,
+ * synthesises cited evidence and states uncertainty. Everything that grants or limits capability is enforced here, outside the
+ * model: the tool set is fixed before the first request, arguments are validated by zod, every read goes through the caller's
+ * `ToolContext` permits, and step/tool/token/cost caps are checked before each request. Tool output and supplied facts are
+ * untrusted data and cannot change the tool set or limits. Findings survive only when every cited evidence id was supplied or
+ * captured in this node and every address, hash and significant number in the claim appears in that cited evidence.
+ */
+export declare const EVIDENCE_ID: RegExp;
+export declare const AnalysisLimitsSchema: z.ZodObject<{
+    maxSteps: z.ZodNumber;
+    maxInputTokens: z.ZodNumber;
+    maxOutputTokens: z.ZodNumber;
+    maxCostMicrousd: z.ZodNumber;
+    maxToolCalls: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type AnalysisLimits = z.infer<typeof AnalysisLimitsSchema>;
+/** Final structured output. Completion criteria: an end_turn response whose text parses against this schema. */
+export declare const AnalysisOutputSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        answered: "answered";
+        "insufficient-evidence": "insufficient-evidence";
+    }>;
+    findings: z.ZodArray<z.ZodObject<{
+        claim: z.ZodString;
+        evidenceIds: z.ZodArray<z.ZodString>;
+        confidence: z.ZodEnum<{
+            supported: "supported";
+            uncertain: "uncertain";
+        }>;
+    }, z.core.$strict>>;
+    unknowns: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type AnalysisOutput = z.infer<typeof AnalysisOutputSchema>;
+export type AnalysisFinding = {
+    claim: string;
+    evidenceIds: string[];
+    confidence: 'supported' | 'uncertain';
+};
+export type RejectedFinding = {
+    claim: string;
+    evidenceIds: string[];
+    reason: 'unknown-evidence' | 'ungrounded-value';
+    detail: string;
+};
+export type AnalysisStopReason = 'completed' | 'insufficient-evidence' | 'step-limit' | 'input-token-limit' | 'output-token-limit' | 'cost-limit' | 'refusal' | 'max-tokens' | 'invalid-output' | 'unexpected-stop' | 'provider-error' | 'cancelled';
+export interface AnalysisProgressEvent {
+    step: string;
+    message: string;
+}
+export interface AnalysisNodeInput {
+    task: string;
+    allowedTools: string[];
+    /** Supplied evidence. `completeness` (from the evidence envelope) downgrades findings citing incomplete evidence to "uncertain". */
+    facts: {
+        evidenceId: string;
+        summary: unknown;
+        completeness?: string;
+    }[];
+    limits: {
+        maxSteps: number;
+        maxInputTokens: number;
+        maxOutputTokens: number;
+        maxCostMicrousd: number;
+        maxToolCalls?: number;
+    };
+    toolContext: ToolContext;
+    signal: AbortSignal;
+}
+export interface AnalysisNodeDeps {
+    client: ModelClient;
+    now?: () => Date;
+    /** Approved deterministic tools (packages/tools TOOL_REGISTRY). Required when `allowedTools` is non-empty. */
+    registry?: WorkflowToolRegistry;
+    model?: string;
+    effort?: ModelEffort;
+    retry?: RetryPolicy;
+    tariffs?: TariffTable;
+    onProgress?: (event: AnalysisProgressEvent) => void | Promise<void>;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /**
+     * Runtime permit before each model request (lease/fencing check and worst-case spend reservation against the run budget).
+     * A throw is a runtime refusal: it propagates unchanged and no request is sent.
+     */
+    beforeModelRequest?: (operation: {
+        step: number;
+        maxOutputTokens: number;
+        worstCaseMicrousd: number;
+        model: string;
+    }) => void | Promise<void>;
+    /** Durable usage checkpoint after each billed model response. A throw propagates unchanged (the response is not used). */
+    onModelUsage?: (entry: {
+        step: number;
+        usage: ModelUsageEntry[];
+        costMicrousd: number;
+        stopReason: string;
+        modelServed: string;
+    }) => void | Promise<void>;
+}
+export interface AnalysisUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    costMicrousd: number;
+    steps: number;
+    toolCalls: number;
+    requests: number;
+    retries: number;
+    model: string;
+    requestedModel: string;
+    fallbackUsed: boolean;
+    elapsedMs: number;
+}
+export interface AnalysisNodeResult {
+    findings: AnalysisFinding[];
+    unknowns: string[];
+    rejected: RejectedFinding[];
+    /** Evidence captured by tool executions in this node (supplied facts excluded). */
+    evidenceIds: string[];
+    usage: AnalysisUsage;
+    stopReason: AnalysisStopReason;
+    refusalCategory: string | null;
+    providerError: string | null;
+}
+export declare class AnalysisConfigurationError extends Error {
+    readonly code = "ANALYSIS_CONFIGURATION";
+    constructor(message: string);
+}
+export declare const ANALYSIS_SYSTEM_PROMPT: string;
+/** Scalars in a value as strings, bounded against hostile nesting and size. Addresses inside label strings are masked (V03 review). */
+export declare function groundingStrings(value: unknown, limit?: number): string[];
+/** Null when every address, hash and significant number in the claim appears in the cited evidence. */
+export declare function groundingIssue(claim: string, cited: readonly string[]): string | null;
+export interface KnownEvidence {
+    strings: string[];
+    completeness: string | null;
+}
+/** Provenance gate: rejects findings citing unknown evidence or ungrounded values; downgrades findings citing incomplete evidence. */
+export declare function checkFindings(findings: AnalysisOutput['findings'], known: ReadonlyMap<string, KnownEvidence>): {
+    findings: AnalysisFinding[];
+    rejected: RejectedFinding[];
+};
+export declare function runAnalysisNode(rawInput: AnalysisNodeInput, deps: AnalysisNodeDeps): Promise<AnalysisNodeResult>;