agentex-creator-sdk 1.0.0

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

@@ -0,0 +1,786 @@
+import { createPublicClient, getAddress, http, keccak256, toEventSelector, toHex } from 'viem';
+import { AgentManifestSchema, contentHash } from '../../contracts/src/index.js';
+import { CONTROL_EVENTS, GOVERNANCE_EVENTS, POOL_EVENTS, SupportedWatchtowerManifestSchema, WATCHTOWER_MANIFEST, WATCH_MAX_LOGS, WATCH_RPC_CEILING, WATCH_TOOL, WatchEvidenceItemSchema, WatchtowerWindowInputSchema, WatchtowerWindowReportSchema, watchRuleRefusal } from '../../contracts/src/watchtower.js';
+import { EvmReadFailure, FAILURE_MESSAGES, categorizeRpcFailure, servedProviderLabel, parseBlockHeader, parseQuantity, resolveChainConfiguration } from '../../research/src/index.js';
+const RPC_DOCUMENTATION = 'https://ethereum.org/en/developers/docs/apis/json-rpc/';
+const OUTPUT_CEILING = 262144;
+const HEX32 = /^0x[a-fA-F0-9]{64}$/;
+const MAX_UINT256 = 2n ** 256n - 1n;
+export const WATCH_TOPICS = {
+    Transfer: toEventSelector('Transfer(address,address,uint256)'),
+    Approval: toEventSelector('Approval(address,address,uint256)'),
+    Upgraded: toEventSelector('Upgraded(address)'),
+    AdminChanged: toEventSelector('AdminChanged(address,address)'),
+    BeaconUpgraded: toEventSelector('BeaconUpgraded(address)'),
+    OwnershipTransferred: toEventSelector('OwnershipTransferred(address,address)'),
+};
+/** 0.3.0 pool events. Uniswap V2 forks, Uniswap V3 forks and Aerodrome (Solidly) pools use different Swap and Burn layouts. */
+export const POOL_TOPICS = {
+    'uniswap-v2': { Swap: toEventSelector('Swap(address,uint256,uint256,uint256,uint256,address)'), Mint: toEventSelector('Mint(address,uint256,uint256)'), Burn: toEventSelector('Burn(address,uint256,uint256,address)') },
+    'uniswap-v3': { Swap: toEventSelector('Swap(address,address,int256,int256,uint160,uint128,int24)'), Mint: toEventSelector('Mint(address,address,int24,int24,uint128,uint256,uint256)'), Burn: toEventSelector('Burn(address,int24,int24,uint128,uint256,uint256)') },
+    aerodrome: { Swap: toEventSelector('Swap(address,address,uint256,uint256,uint256,uint256)'), Mint: toEventSelector('Mint(address,uint256,uint256)'), Burn: toEventSelector('Burn(address,address,uint256,uint256)') },
+};
+/** 0.3.0 governor, OpenZeppelin TimelockController and Compound Timelock events. */
+export const GOVERNANCE_TOPICS = Object.freeze({
+    ProposalCreated: toEventSelector('ProposalCreated(uint256,address,address[],uint256[],string[],bytes[],uint256,uint256,string)'), ProposalQueued: toEventSelector('ProposalQueued(uint256,uint256)'),
+    ProposalExecuted: toEventSelector('ProposalExecuted(uint256)'), ProposalCanceled: toEventSelector('ProposalCanceled(uint256)'),
+    CallScheduled: toEventSelector('CallScheduled(bytes32,uint256,address,uint256,bytes,bytes32,uint256)'), CallExecuted: toEventSelector('CallExecuted(bytes32,uint256,address,uint256,bytes)'),
+    Cancelled: toEventSelector('Cancelled(bytes32)'), MinDelayChange: toEventSelector('MinDelayChange(uint256,uint256)'),
+    QueueTransaction: toEventSelector('QueueTransaction(bytes32,address,uint256,string,bytes,uint256)'), ExecuteTransaction: toEventSelector('ExecuteTransaction(bytes32,address,uint256,string,bytes,uint256)'),
+    CancelTransaction: toEventSelector('CancelTransaction(bytes32,address,uint256,string,bytes,uint256)'), NewDelay: toEventSelector('NewDelay(uint256)'), NewAdmin: toEventSelector('NewAdmin(address)'), NewPendingAdmin: toEventSelector('NewPendingAdmin(address)'),
+});
+/** 0.3.0 OpenZeppelin AccessControl and Pausable events. */
+export const CONTROL_TOPICS = Object.freeze({
+    RoleGranted: toEventSelector('RoleGranted(bytes32,address,address)'), RoleRevoked: toEventSelector('RoleRevoked(bytes32,address,address)'), RoleAdminChanged: toEventSelector('RoleAdminChanged(bytes32,bytes32,bytes32)'),
+    Paused: toEventSelector('Paused(address)'), Unpaused: toEventSelector('Unpaused(address)'),
+});
+/** Names for widely used AccessControl role ids, used only to explain an event. An unknown role is shown by its id. */
+export const KNOWN_ROLES = Object.freeze(Object.fromEntries([[`0x${'0'.repeat(64)}`, 'DEFAULT_ADMIN_ROLE'],
+    ...['MINTER_ROLE', 'BURNER_ROLE', 'PAUSER_ROLE', 'UPGRADER_ROLE', 'OPERATOR_ROLE', 'ADMIN_ROLE', 'PROPOSER_ROLE', 'EXECUTOR_ROLE', 'CANCELLER_ROLE', 'TIMELOCK_ADMIN_ROLE', 'GUARDIAN_ROLE', 'MANAGER_ROLE', 'RESCUER_ROLE', 'BLACKLISTER_ROLE', 'FREEZER_ROLE', 'ORACLE_ROLE', 'KEEPER_ROLE']
+        .map((name) => [keccak256(toHex(name)), name])]));
+export const SHARED_READ_PROVIDER_SUFFIX = '-shared-public-read';
+export function sharedReadKey(chain, chainId, rule, input, fromBlockHash, toBlockHash) {
+    const filter = logFilter(rule, input);
+    const edges = { fromBlockHash: fromBlockHash.toLowerCase(), toBlockHash: toBlockHash.toLowerCase() };
+    return { key: contentHash({ kind: 'agentex.watchtower.shared-logs.v1', chainId, filter, ...edges }), chain, chainId, fromBlock: input.fromBlock, toBlock: input.toBlock, ...edges, address: Array.isArray(filter.address) ? filter.address.join(',') : filter.address, topics: filter.topics };
+}
+export const blockTag = (block) => `0x${BigInt(block).toString(16)}`;
+const topicOf = (address) => `0x${'0'.repeat(24)}${address.slice(2).toLowerCase()}`;
+/** Contracts whose logs a rule reads: one contract, or the token list of a 0.3.0 wallet-token-flow rule. */
+const ruleAddresses = (rule) => rule.type === 'wallet-token-flow' ? rule.tokens.map((token) => token.toLowerCase())
+    : [(rule.type === 'erc20-transfer' || rule.type === 'erc20-approval' ? rule.token : rule.type === 'pool-activity' ? rule.pool : rule.contract).toLowerCase()];
+const selectedPoolEvents = (rule) => rule.events ?? [...POOL_EVENTS];
+/** The exact, deterministic eth_getLogs filter for a rule. Receipt validation checks saved requests against these filters. */
+export function logFilter(rule, input) {
+    const topics = rule.type === 'erc20-transfer' ? [WATCH_TOPICS.Transfer, rule.from ? topicOf(rule.from) : null, rule.to ? topicOf(rule.to) : null]
+        : rule.type === 'erc20-approval' ? [WATCH_TOPICS.Approval, topicOf(rule.owner), rule.spender ? topicOf(rule.spender) : null]
+            : rule.type === 'wallet-token-flow' ? (rule.direction === 'out' ? [WATCH_TOPICS.Transfer, topicOf(rule.wallet)] : [WATCH_TOPICS.Transfer, null, topicOf(rule.wallet)])
+                : rule.type === 'pool-activity' ? [selectedPoolEvents(rule).map((name) => POOL_TOPICS[rule.dex][name])]
+                    : rule.type === 'governance-change' ? [(rule.events ?? [...GOVERNANCE_EVENTS]).map((name) => GOVERNANCE_TOPICS[name])]
+                        : rule.type === 'control-change' ? [(rule.events ?? [...CONTROL_EVENTS]).map((name) => CONTROL_TOPICS[name])]
+                            : [(rule.events ?? Object.keys(WATCH_TOPICS).filter((name) => !['Transfer', 'Approval'].includes(name))).map((name) => WATCH_TOPICS[name])];
+    while (topics.length > 1 && topics.at(-1) === null)
+        topics.pop();
+    const addresses = ruleAddresses(rule);
+    return { address: rule.type === 'wallet-token-flow' ? addresses : addresses[0], fromBlock: blockTag(input.fromBlock), toBlock: blockTag(input.toBlock), topics };
+}
+/** Wallet flows name a participant and read an address list, so they are never shared across monitors (R01). */
+const shareableRule = (rule) => rule.type !== 'wallet-token-flow';
+export const watchRequests = {
+    logs: (rule, input) => ({ method: 'eth_getLogs', params: [logFilter(rule, input)] }),
+    header: (tag) => ({ method: 'eth_getBlockByNumber', params: [tag, false] }),
+};
+export const requestKey = (request) => contentHash({ method: request.method, params: request.params });
+/** Method, request and snapshot scope for a Watchtower receipt. Schema, chain identity and hash checks stay with the caller. */
+export function watchReceiptInScope(receipt, input) {
+    const { method } = receipt.source;
+    const params = receipt.request;
+    if (method === 'eth_chainId')
+        return params.length === 0 && receipt.snapshot === null;
+    if (method === 'eth_getBlockByNumber') {
+        if (params.length !== 2 || params[1] !== false || typeof params[0] !== 'string' || receipt.snapshot !== null)
+            return false;
+        // `latest` is the instant-read head; `finalized` only admits receipts checkpointed before that rule.
+        if (params[0] === 'latest' || params[0] === 'finalized')
+            return true;
+        if (!/^0x(?:0|[1-9a-fA-F][a-fA-F0-9]*)$/.test(params[0]))
+            return false;
+        const block = BigInt(params[0]);
+        return block >= BigInt(input.fromBlock) && block <= BigInt(input.toBlock);
+    }
+    if (method !== 'eth_getLogs' || !receipt.snapshot || (receipt.finality !== 'sequencer-confirmed' && receipt.finality !== 'finalized') || receipt.snapshot.blockNumber !== input.toBlock || params.length !== 1)
+        return false;
+    const planned = new Set(input.rules.map((rule) => requestKey(JSON.parse(JSON.stringify(watchRequests.logs(rule, input))))));
+    return planned.has(requestKey({ method, params }));
+}
+const invalid = (message) => new EvmReadFailure('invalid-response', message);
+export function parseLogs(raw, input) {
+    if (!Array.isArray(raw) || raw.length > 100000)
+        throw invalid('eth_getLogs did not return a bounded log array.');
+    const from = BigInt(input.fromBlock);
+    const to = BigInt(input.toBlock);
+    return raw.map((item) => {
+        if (item === null || typeof item !== 'object' || Array.isArray(item))
+            throw invalid('Malformed log.');
+        const log = item;
+        if (typeof log.address !== 'string' || !/^0x[a-fA-F0-9]{40}$/.test(log.address) || !Array.isArray(log.topics) || log.topics.length > 4 || log.topics.some((topic) => typeof topic !== 'string' || !HEX32.test(topic))
+            || typeof log.data !== 'string' || !/^0x(?:[a-fA-F0-9]{2})*$/.test(log.data) || log.data.length > 2 + 2 * 4096 || typeof log.blockHash !== 'string' || !HEX32.test(log.blockHash)
+            || typeof log.transactionHash !== 'string' || !HEX32.test(log.transactionHash) || (log.removed !== undefined && typeof log.removed !== 'boolean'))
+            throw invalid('Malformed log fields.');
+        const blockNumber = parseQuantity(log.blockNumber);
+        const logIndex = parseQuantity(log.logIndex);
+        if (blockNumber < from || blockNumber > to)
+            throw invalid('A returned log lies outside the requested window.');
+        if (logIndex > 1000000n)
+            throw invalid('Log index out of range.');
+        return { address: log.address.toLowerCase(), topics: log.topics.map((topic) => topic.toLowerCase()), data: log.data.toLowerCase(), blockNumber, blockHash: log.blockHash.toLowerCase(),
+            transactionHash: log.transactionHash.toLowerCase(), logIndex: Number(logIndex), removed: log.removed === true, raw: item };
+    }).sort((a, b) => a.blockNumber === b.blockNumber ? a.logIndex - b.logIndex : a.blockNumber < b.blockNumber ? -1 : 1);
+}
+/** Keeps whole blocks only: if the cap falls inside a block, that block and later blocks are reported as not examined. */
+export function capLogs(logs, capacity, input) {
+    if (logs.length <= capacity)
+        return { kept: logs, coveredThrough: BigInt(input.toBlock), truncated: false };
+    const coveredThrough = logs[capacity].blockNumber - 1n;
+    return { kept: logs.filter((log) => log.blockNumber <= coveredThrough), coveredThrough, truncated: true };
+}
+const addressFromTopic = (topic) => topic.slice(2, 26) === '0'.repeat(24) ? getAddress(`0x${topic.slice(26)}`) : null;
+const addressFromWord = (data, index) => { const word = data.slice(2 + index * 64, 2 + (index + 1) * 64); return word.length === 64 && word.slice(0, 24) === '0'.repeat(24) ? getAddress(`0x${word.slice(24)}`) : null; };
+/** Rules fire only on their stated conditions. The provider filter is not trusted: address, topic layout, data size and every filter are re-checked here. */
+// --------------------------------------------------------------------------------------------------- 0.3.0 rule matchers
+const TOPIC_MISMATCH = { fired: false, reason: 'topic-mismatch' };
+const DATA_MISMATCH = { fired: false, reason: 'data-mismatch' };
+const wordCount = (data) => (data.length - 2) / 64;
+const uintAt = (data, index) => { const word = data.slice(2 + index * 64, 2 + (index + 1) * 64); return word.length === 64 ? BigInt(`0x${word}`) : null; };
+const intAt = (data, index) => { const value = uintAt(data, index); return value === null ? null : value >= 2n ** 255n ? value - 2n ** 256n : value; };
+const magnitude = (value) => value < 0n ? -value : value;
+/** Dynamic ABI bytes whose head offset sits in word `index`. Offsets must be word-aligned and inside the data; returns null otherwise. */
+function dynamicAt(data, index, maximumBytes) {
+    const offset = uintAt(data, index);
+    const size = (data.length - 2) / 2;
+    if (offset === null || offset % 32n !== 0n || offset + 32n > BigInt(size))
+        return null;
+    const start = 2 + Number(offset) * 2;
+    const length = BigInt(`0x${data.slice(start, start + 64)}`);
+    if (length > BigInt(size) - offset - 32n)
+        return null;
+    return { hex: data.slice(start + 64, start + 64 + Math.min(Number(length), maximumBytes) * 2), length: Number(length) };
+}
+/** Untrusted on-chain text reduced to a short single printable line; never interpreted. */
+/** Control, invisible and bidirectional-override characters in untrusted event text. */
+const UNSAFE_TEXT = new RegExp(String.raw `[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2066-\u2069]+`, 'g');
+const shortText = (hex, maximum) => Buffer.from(hex, 'hex').toString('utf8').replace(UNSAFE_TEXT, ' ').replace(/^[#\s]+/, '').replace(/\s+/g, ' ').trim().slice(0, maximum);
+const roleName = (role) => KNOWN_ROLES[role] ?? `role ${role.slice(0, 10)}…`;
+function matchWalletFlow(rule, log) {
+    if (log.topics[0] !== WATCH_TOPICS.Transfer || log.topics.length !== 3)
+        return TOPIC_MISMATCH;
+    if (log.data.length !== 66)
+        return DATA_MISMATCH;
+    const from = addressFromTopic(log.topics[1]);
+    const to = addressFromTopic(log.topics[2]);
+    if (!from || !to)
+        return TOPIC_MISMATCH;
+    const wallet = rule.wallet.toLowerCase();
+    if ((rule.direction === 'in' ? to : from).toLowerCase() !== wallet)
+        return { fired: false, reason: 'filter-mismatch' };
+    const amount = BigInt(log.data);
+    const token = getAddress(log.address);
+    const counterparty = rule.direction === 'in' ? from : to;
+    return { fired: true, event: 'Transfer', fields: { token, from, to, amountAtomic: amount.toString(), direction: rule.direction },
+        explanation: `Rule ${rule.id}: ${getAddress(rule.wallet)} ${rule.direction === 'in' ? 'received' : 'sent'} ${amount} atomic units of ${token} ${rule.direction === 'in' ? 'from' : 'to'} ${counterparty}.` };
+}
+function matchPool(rule, log) {
+    const selected = selectedPoolEvents(rule);
+    const topics = POOL_TOPICS[rule.dex];
+    const name = Object.entries(topics).find(([, value]) => value === log.topics[0])?.[0];
+    if (!name || !selected.includes(name))
+        return TOPIC_MISMATCH;
+    const v3 = rule.dex === 'uniswap-v3';
+    const words = wordCount(log.data);
+    const pool = getAddress(log.address);
+    let fields;
+    let amount0;
+    let amount1;
+    let explanation;
+    if (name === 'Swap') {
+        if (log.topics.length !== 3)
+            return TOPIC_MISMATCH;
+        const sender = addressFromTopic(log.topics[1]);
+        const recipient = addressFromTopic(log.topics[2]);
+        if (!sender || !recipient)
+            return TOPIC_MISMATCH;
+        if (v3) {
+            if (words !== 5)
+                return DATA_MISMATCH;
+            const a0 = intAt(log.data, 0);
+            const a1 = intAt(log.data, 1);
+            const sqrtPrice = uintAt(log.data, 2);
+            const tick = intAt(log.data, 4);
+            if (sqrtPrice >= 2n ** 160n || tick < -887272n || tick > 887272n)
+                return DATA_MISMATCH;
+            amount0 = magnitude(a0);
+            amount1 = magnitude(a1);
+            fields = { sender, recipient, amount0Atomic: a0.toString(), amount1Atomic: a1.toString(), sqrtPriceX96: sqrtPrice.toString(), tick: tick.toString() };
+            explanation = `Rule ${rule.id}: swap on ${pool}: token0 ${a0 >= 0n ? 'into' : 'out of'} the pool ${amount0}, token1 ${a1 >= 0n ? 'into' : 'out of'} the pool ${amount1} (atomic units); recipient ${recipient}.`;
+        }
+        else {
+            if (words !== 4)
+                return DATA_MISMATCH;
+            const [in0, in1, out0, out1] = [0, 1, 2, 3].map((index) => uintAt(log.data, index));
+            amount0 = in0 > out0 ? in0 : out0;
+            amount1 = in1 > out1 ? in1 : out1;
+            fields = { sender, recipient, amount0InAtomic: in0.toString(), amount1InAtomic: in1.toString(), amount0OutAtomic: out0.toString(), amount1OutAtomic: out1.toString() };
+            explanation = `Rule ${rule.id}: swap on ${pool}: ${in0} token0 and ${in1} token1 in, ${out0} token0 and ${out1} token1 out (atomic units); recipient ${recipient}.`;
+        }
+    }
+    else if (v3) {
+        if (log.topics.length !== 4)
+            return TOPIC_MISMATCH;
+        if (words !== (name === 'Mint' ? 4 : 3))
+            return DATA_MISMATCH;
+        const owner = addressFromTopic(log.topics[1]);
+        const lower = BigInt.asIntN(24, BigInt(log.topics[2]));
+        const upper = BigInt.asIntN(24, BigInt(log.topics[3]));
+        if (!owner)
+            return TOPIC_MISMATCH;
+        const offset = name === 'Mint' ? 1 : 0;
+        const liquidity = uintAt(log.data, offset);
+        amount0 = uintAt(log.data, offset + 1);
+        amount1 = uintAt(log.data, offset + 2);
+        fields = { owner, tickLower: lower.toString(), tickUpper: upper.toString(), liquidity: liquidity.toString(), amount0Atomic: amount0.toString(), amount1Atomic: amount1.toString() };
+        explanation = `Rule ${rule.id}: ${name === 'Mint' ? 'liquidity added to' : 'liquidity removed from'} ${pool} by ${owner}: ${amount0} token0 and ${amount1} token1 (atomic units), ticks ${lower} to ${upper}.`;
+    }
+    else {
+        if (log.topics.length !== (name === 'Mint' ? 2 : 3))
+            return TOPIC_MISMATCH;
+        if (words !== 2)
+            return DATA_MISMATCH;
+        const sender = addressFromTopic(log.topics[1]);
+        const to = name === 'Burn' ? addressFromTopic(log.topics[2]) : null;
+        if (!sender || (name === 'Burn' && !to))
+            return TOPIC_MISMATCH;
+        amount0 = uintAt(log.data, 0);
+        amount1 = uintAt(log.data, 1);
+        fields = { sender, ...(to ? { to } : {}), amount0Atomic: amount0.toString(), amount1Atomic: amount1.toString() };
+        explanation = `Rule ${rule.id}: ${name === 'Mint' ? 'liquidity added to' : 'liquidity removed from'} ${pool}: ${amount0} token0 and ${amount1} token1 (atomic units)${to ? `, sent to ${to}` : ''}.`;
+    }
+    const min0 = rule.minimumAmount0Atomic === undefined ? null : BigInt(rule.minimumAmount0Atomic);
+    const min1 = rule.minimumAmount1Atomic === undefined ? null : BigInt(rule.minimumAmount1Atomic);
+    if ((min0 !== null || min1 !== null) && !((min0 !== null && amount0 >= min0) || (min1 !== null && amount1 >= min1)))
+        return { fired: false, reason: 'below-minimum' };
+    return { fired: true, event: name, fields, explanation };
+}
+function matchGovernance(rule, log) {
+    const name = Object.entries(GOVERNANCE_TOPICS).find(([, value]) => value === log.topics[0])?.[0];
+    if (!name || !(rule.events ?? GOVERNANCE_EVENTS).includes(name))
+        return TOPIC_MISMATCH;
+    const contract = getAddress(log.address);
+    const words = wordCount(log.data);
+    const topics = log.topics.length;
+    const fired = (fields, explanation) => ({ fired: true, event: name, fields, explanation: `Rule ${rule.id}: ${explanation}` });
+    switch (name) {
+        case 'ProposalCreated': {
+            if (topics !== 1)
+                return TOPIC_MISMATCH;
+            if (words < 9)
+                return DATA_MISMATCH;
+            const proposer = addressFromWord(log.data, 1);
+            const targets = dynamicAt(log.data, 2, 0);
+            const description = dynamicAt(log.data, 8, 4096);
+            if (!proposer || !targets || !description)
+                return DATA_MISMATCH;
+            const id = uintAt(log.data, 0);
+            const title = shortText(description.hex, 140);
+            return fired({ proposalId: id.toString(), proposer, actions: String(targets.length), voteStart: uintAt(log.data, 6).toString(), voteEnd: uintAt(log.data, 7).toString(), ...(title ? { title } : {}) }, `${contract} created proposal ${id} with ${targets.length} action${targets.length === 1 ? '' : 's'}, proposed by ${proposer}${title ? `: "${title}"` : ''}.`);
+        }
+        case 'ProposalQueued':
+            if (topics !== 1)
+                return TOPIC_MISMATCH;
+            if (words !== 2)
+                return DATA_MISMATCH;
+            return fired({ proposalId: uintAt(log.data, 0).toString(), eta: uintAt(log.data, 1).toString() }, `${contract} queued proposal ${uintAt(log.data, 0)} for execution at timestamp ${uintAt(log.data, 1)}.`);
+        case 'ProposalExecuted':
+        case 'ProposalCanceled':
+            if (topics !== 1)
+                return TOPIC_MISMATCH;
+            if (words !== 1)
+                return DATA_MISMATCH;
+            return fired({ proposalId: uintAt(log.data, 0).toString() }, `${contract} ${name === 'ProposalExecuted' ? 'executed' : 'cancelled'} proposal ${uintAt(log.data, 0)}.`);
+        case 'CallScheduled':
+        case 'CallExecuted': {
+            if (topics !== 3)
+                return TOPIC_MISMATCH;
+            if (words < (name === 'CallScheduled' ? 5 : 3))
+                return DATA_MISMATCH;
+            const target = addressFromWord(log.data, 0);
+            const call = dynamicAt(log.data, 2, 4);
+            if (!target || !call)
+                return DATA_MISMATCH;
+            const selector = call.length >= 4 ? `0x${call.hex.slice(0, 8)}` : 'none';
+            const value = uintAt(log.data, 1);
+            const fields = { operationId: log.topics[1], index: BigInt(log.topics[2]).toString(), target, valueAtomic: value.toString(), selector };
+            if (name === 'CallScheduled')
+                fields.delaySeconds = uintAt(log.data, 4).toString();
+            return fired(fields, `${contract} ${name === 'CallScheduled' ? `scheduled a call (delay ${fields.delaySeconds} s)` : 'executed a call'} to ${target}, selector ${selector}, value ${value} wei; operation ${log.topics[1].slice(0, 18)}….`);
+        }
+        case 'Cancelled':
+            if (topics !== 2)
+                return TOPIC_MISMATCH;
+            if (words !== 0)
+                return DATA_MISMATCH;
+            return fired({ operationId: log.topics[1] }, `${contract} cancelled timelock operation ${log.topics[1].slice(0, 18)}….`);
+        case 'MinDelayChange':
+            if (topics !== 1)
+                return TOPIC_MISMATCH;
+            if (words !== 2)
+                return DATA_MISMATCH;
+            return fired({ oldDelaySeconds: uintAt(log.data, 0).toString(), newDelaySeconds: uintAt(log.data, 1).toString() }, `${contract} changed its minimum delay from ${uintAt(log.data, 0)} to ${uintAt(log.data, 1)} seconds.`);
+        case 'QueueTransaction':
+        case 'ExecuteTransaction':
+        case 'CancelTransaction': {
+            if (topics !== 3)
+                return TOPIC_MISMATCH;
+            const target = addressFromTopic(log.topics[2]);
+            const signature = words >= 4 ? dynamicAt(log.data, 1, 100) : null;
+            if (!target)
+                return TOPIC_MISMATCH;
+            if (!signature)
+                return DATA_MISMATCH;
+            const text = shortText(signature.hex, 100) || 'raw calldata';
+            const eta = uintAt(log.data, 3);
+            const verb = name === 'QueueTransaction' ? 'queued' : name === 'ExecuteTransaction' ? 'executed' : 'cancelled';
+            return fired({ transactionId: log.topics[1], target, valueAtomic: uintAt(log.data, 0).toString(), signature: text, eta: eta.toString() }, `${contract} ${verb} ${text} on ${target} (eta ${eta}).`);
+        }
+        case 'NewDelay':
+            if (topics !== 2)
+                return TOPIC_MISMATCH;
+            if (words !== 0)
+                return DATA_MISMATCH;
+            return fired({ newDelaySeconds: BigInt(log.topics[1]).toString() }, `${contract} set its delay to ${BigInt(log.topics[1])} seconds.`);
+        case 'NewAdmin':
+        case 'NewPendingAdmin': {
+            if (topics !== 2)
+                return TOPIC_MISMATCH;
+            if (words !== 0)
+                return DATA_MISMATCH;
+            const admin = addressFromTopic(log.topics[1]);
+            if (!admin)
+                return TOPIC_MISMATCH;
+            return fired({ [name === 'NewAdmin' ? 'newAdmin' : 'newPendingAdmin']: admin }, `${contract} ${name === 'NewAdmin' ? 'accepted a new admin' : 'proposed a new pending admin'}: ${admin}.`);
+        }
+    }
+}
+function matchControl(rule, log) {
+    const name = Object.entries(CONTROL_TOPICS).find(([, value]) => value === log.topics[0])?.[0];
+    if (!name || !(rule.events ?? CONTROL_EVENTS).includes(name))
+        return TOPIC_MISMATCH;
+    const contract = getAddress(log.address);
+    if (name === 'Paused' || name === 'Unpaused') {
+        if (log.topics.length !== 1)
+            return TOPIC_MISMATCH;
+        const account = log.data.length === 66 ? addressFromWord(log.data, 0) : null;
+        if (!account)
+            return DATA_MISMATCH;
+        return { fired: true, event: name, fields: { account }, explanation: `Rule ${rule.id}: ${contract} was ${name === 'Paused' ? 'paused' : 'unpaused'} by ${account}.` };
+    }
+    if (log.topics.length !== 4)
+        return TOPIC_MISMATCH;
+    if (log.data !== '0x')
+        return DATA_MISMATCH;
+    const role = log.topics[1];
+    if (name === 'RoleAdminChanged')
+        return { fired: true, event: name, fields: { role, previousAdminRole: log.topics[2], newAdminRole: log.topics[3] },
+            explanation: `Rule ${rule.id}: on ${contract}, the admin of ${roleName(role)} changed from ${roleName(log.topics[2])} to ${roleName(log.topics[3])}.` };
+    const account = addressFromTopic(log.topics[2]);
+    const sender = addressFromTopic(log.topics[3]);
+    if (!account || !sender)
+        return TOPIC_MISMATCH;
+    return { fired: true, event: name, fields: { role, account, sender }, explanation: `Rule ${rule.id}: on ${contract}, ${sender} ${name === 'RoleGranted' ? 'granted' : 'revoked'} ${roleName(role)} ${name === 'RoleGranted' ? 'to' : 'from'} ${account}.` };
+}
+export function matchLog(rule, log) {
+    if (log.removed)
+        return { fired: false, reason: 'removed' };
+    if (!ruleAddresses(rule).includes(log.address))
+        return { fired: false, reason: 'address-mismatch' };
+    const [topic0] = log.topics;
+    if (rule.type === 'wallet-token-flow')
+        return matchWalletFlow(rule, log);
+    if (rule.type === 'pool-activity')
+        return matchPool(rule, log);
+    if (rule.type === 'governance-change')
+        return matchGovernance(rule, log);
+    if (rule.type === 'control-change')
+        return matchControl(rule, log);
+    if (rule.type === 'erc20-transfer' || rule.type === 'erc20-approval') {
+        const expected = rule.type === 'erc20-transfer' ? WATCH_TOPICS.Transfer : WATCH_TOPICS.Approval;
+        // ERC-721 Transfer/Approval share topic0 but index the token id as a fourth topic.
+        if (topic0 !== expected || log.topics.length !== 3)
+            return { fired: false, reason: 'topic-mismatch' };
+        if (log.data.length !== 66)
+            return { fired: false, reason: 'data-mismatch' };
+        const first = addressFromTopic(log.topics[1]);
+        const second = addressFromTopic(log.topics[2]);
+        if (!first || !second)
+            return { fired: false, reason: 'topic-mismatch' };
+        const amount = BigInt(log.data);
+        if (rule.type === 'erc20-transfer') {
+            if ((rule.from && rule.from.toLowerCase() !== first.toLowerCase()) || (rule.to && rule.to.toLowerCase() !== second.toLowerCase()))
+                return { fired: false, reason: 'filter-mismatch' };
+            if (rule.minimumAtomic !== undefined && amount < BigInt(rule.minimumAtomic))
+                return { fired: false, reason: 'below-minimum' };
+            const matched = [rule.from ? 'sender' : '', rule.to ? 'recipient' : '', rule.minimumAtomic !== undefined ? `minimum ${rule.minimumAtomic}` : ''].filter(Boolean);
+            return { fired: true, event: 'Transfer', fields: { from: first, to: second, amountAtomic: amount.toString() },
+                explanation: `Rule ${rule.id}: Transfer of ${amount} atomic units on ${getAddress(log.address)} from ${first} to ${second}${matched.length ? ` (matched ${matched.join(', ')})` : ''}.` };
+        }
+        if (rule.owner.toLowerCase() !== first.toLowerCase() || (rule.spender && rule.spender.toLowerCase() !== second.toLowerCase()))
+            return { fired: false, reason: 'filter-mismatch' };
+        return { fired: true, event: 'Approval', fields: { owner: first, spender: second, amountAtomic: amount.toString() },
+            explanation: `Rule ${rule.id}: ${first} approved ${second} for ${amount} atomic units${amount === MAX_UINT256 ? ' (maximum uint256)' : ''} on ${getAddress(log.address)}.` };
+    }
+    const selected = rule.events ?? ['Upgraded', 'AdminChanged', 'BeaconUpgraded', 'OwnershipTransferred'];
+    const name = Object.entries(WATCH_TOPICS).find(([, topic]) => topic === topic0)?.[0];
+    if (!name || name === 'Transfer' || name === 'Approval' || !selected.includes(name))
+        return { fired: false, reason: 'topic-mismatch' };
+    const contract = getAddress(log.address);
+    if (name === 'Upgraded' || name === 'BeaconUpgraded') {
+        const value = log.topics.length === 2 && log.data === '0x' ? addressFromTopic(log.topics[1]) : null;
+        if (!value)
+            return { fired: false, reason: 'topic-mismatch' };
+        return name === 'Upgraded' ? { fired: true, event: name, fields: { implementation: value }, explanation: `Rule ${rule.id}: ${contract} emitted Upgraded; its implementation is now ${value}.` }
+            : { fired: true, event: name, fields: { beacon: value }, explanation: `Rule ${rule.id}: ${contract} emitted BeaconUpgraded; its beacon is now ${value}.` };
+    }
+    if (name === 'AdminChanged') {
+        if (log.topics.length !== 1)
+            return { fired: false, reason: 'topic-mismatch' };
+        const previous = addressFromWord(log.data, 0);
+        const next = addressFromWord(log.data, 1);
+        if (log.data.length !== 130 || !previous || !next)
+            return { fired: false, reason: 'data-mismatch' };
+        return { fired: true, event: name, fields: { previousAdmin: previous, newAdmin: next }, explanation: `Rule ${rule.id}: ${contract} emitted AdminChanged from ${previous} to ${next}.` };
+    }
+    const previous = log.topics.length === 3 && log.data === '0x' ? addressFromTopic(log.topics[1]) : null;
+    const next = log.topics.length === 3 ? addressFromTopic(log.topics[2]) : null;
+    if (!previous || !next)
+        return { fired: false, reason: 'topic-mismatch' };
+    return { fired: true, event: 'OwnershipTransferred', fields: { previousOwner: previous, newOwner: next }, explanation: `Rule ${rule.id}: ownership of ${contract} was transferred from ${previous} to ${next}.` };
+}
+export const eventKey = (chain, transactionHash, logIndex, ruleId) => contentHash({ chain, transactionHash: transactionHash.toLowerCase(), logIndex, ruleId });
+export function createWatchTransport(url) {
+    const client = createPublicClient({ transport: http(url, { retryCount: 0, timeout: 10000, maxResponseBodySize: 1_048_576, fetchOptions: { redirect: 'error' } }), cacheTime: 0 });
+    return { request: (method, params, signal) => client.request({ method, params }, { signal, retryCount: 0 }) };
+}
+class RuntimeInterruption extends Error {
+    original;
+    constructor(original) {
+        super('The runtime refused or could not persist this operation.');
+        this.original = original;
+    }
+}
+const fatal = (category) => ['cancelled', 'timeout'].includes(category);
+/**
+ * Read-only scan of one window at or below the latest head (instant reads; no finality wait). Truncation, provider failure and reorgs
+ * are reported; none becomes "nothing happened". A reorg of the window end fails the window, and monitors retract and redo it.
+ */
+export async function watchWindow(rawInput, options = {}) {
+    const input = WatchtowerWindowInputSchema.parse(rawInput);
+    const manifest = AgentManifestSchema.parse(options.manifest ?? WATCHTOWER_MANIFEST);
+    const config = resolveChainConfiguration(input.chain, options.env ?? process.env);
+    const now = options.now ?? (() => new Date());
+    const started = now().getTime();
+    const deadline = AbortSignal.timeout(Math.min(60000, manifest.limits.maximumDurationMs));
+    const signal = options.signal ? AbortSignal.any([options.signal, deadline]) : deadline;
+    const from = BigInt(input.fromBlock);
+    const to = BigInt(input.toBlock);
+    const report = {
+        schemaVersion: 'agentex.watchtower-window.v1', agentVersion: manifest.version, manifestHash: contentHash(manifest), input, status: 'failed', generatedAt: now().toISOString(),
+        chainId: Number.isSafeInteger(config.chainId) && config.chainId > 0 ? config.chainId : null,
+        window: { fromBlock: input.fromBlock, toBlock: input.toBlock, fromBlockHash: null, toBlockHash: null, toBlockTimestamp: null, finality: 'sequencer-confirmed', canonicality: 'unchecked', coverage: 'unavailable',
+            coveredThroughBlock: null, coveredThroughBlockHash: null, finalizedBlock: null, finalityLagBlocks: null, dataLagSeconds: null, headBlock: null, headLagBlocks: null },
+        rules: input.rules.map((rule) => ({ id: rule.id, type: rule.type, coverage: 'not-read', logsReturned: 0, logsMatched: 0, ignored: {}, coveredThroughBlock: null, reason: 'Not read.', evidenceIds: [] })),
+        events: [], unknowns: [], errors: [], evidence: [],
+        limitations: [watchRuleRefusal(manifest.version, [{ id: 'probe', type: 'pool-activity' }]) === null
+                ? 'Only the declared standard events emitted by the declared contracts are watched: ERC-20 Transfer/Approval, EIP-1967/Ownable authority, AccessControl/Pausable, Governor and timelock events, and Uniswap V2/V3 or Aerodrome pool Swap/Mint/Burn. Custom events, native transfers, internal calls and pool price or depth are not observed.'
+                : 'Only ERC-20 Transfer/Approval events and EIP-1967/Ownable authority events emitted by the declared contracts are watched. Other permission or upgrade mechanisms, native transfers and internal calls are not observed.',
+            'Rules match by event signature and topic layout; a contract emitting a standard event is not verified to implement the standard.',
+            'The window is read at or below the latest block (sequencer-confirmed), not finalized blocks. Its end-block hash is rechecked at completion; earlier blocks rely on that ancestry. A later reorg is detected on the next window and the affected events are retracted and redone.',
+            'eth_getLogs results are accepted as complete for the requested filter. A provider that silently omits logs cannot be detected from its response alone.',
+            'Amounts are exact atomic units. Token decimals, prices and identities are not read or inferred.',
+            'Events are observations, not a verdict about intent, fraud or safety.'],
+        usage: { rpcCalls: 0, maximumRpcCalls: Math.min(WATCH_RPC_CEILING, manifest.limits.maximumRpcCalls, ...manifest.tools.map((tool) => tool.maximumCalls)), elapsedMs: 0, modelTokens: 0, providerCostAtomic: null, providerCostStatus: 'unpriced' },
+    };
+    let transport;
+    let snapshot = null;
+    const restoredReads = new Map();
+    let restoredSnapshot = null;
+    const addError = (category, step, evidenceId) => { report.errors.push({ category, message: FAILURE_MESSAGES[category], step, ...(evidenceId ? { evidenceId } : {}) }); };
+    const interrupted = () => new EvmReadFailure(signal.reason?.name === 'TimeoutError' ? 'timeout' : 'cancelled', 'Watch window interrupted.');
+    const progress = async (step, message) => { try {
+        await options.onProgress?.({ step, message });
+    }
+    catch (error) {
+        throw new RuntimeInterruption(error);
+    } };
+    /** `capture` decides what is stored as evidence; over-cap log responses keep only the examined whole blocks plus a hash of the full response. */
+    const call = async ({ method, params }, step, capture) => {
+        if (signal.aborted)
+            throw interrupted();
+        const cached = snapshot ? restoredReads.get(requestKey({ method, params })) : undefined;
+        if (cached) {
+            await progress(step, `Reusing checkpointed ${step} at the verified original window end.`);
+            const id = `rpc-${report.evidence.length + 1}`;
+            report.evidence.push({ ...structuredClone(cached), id, canonicality: 'unchecked' });
+            return { result: structuredClone(cached.result), id };
+        }
+        if (report.usage.rpcCalls >= report.usage.maximumRpcCalls)
+            throw new EvmReadFailure('limit-exceeded', 'RPC call budget exhausted.');
+        await progress(step, `Reading ${step}.`);
+        if (signal.aborted)
+            throw interrupted();
+        try {
+            await options.beforeRpc?.({ method, step, maximumRpcCalls: report.usage.maximumRpcCalls });
+        }
+        catch (error) {
+            throw new RuntimeInterruption(error);
+        }
+        if (signal.aborted)
+            throw interrupted();
+        report.usage.rpcCalls++;
+        const id = `rpc-${report.evidence.length + 1}`;
+        let result;
+        let stored;
+        let complete = true;
+        let errorCategory;
+        let captureFailure;
+        try {
+            result = await transport.request(method, params, signal);
+        }
+        catch (error) {
+            errorCategory = categorizeRpcFailure(error, signal);
+            result = { error: errorCategory };
+        }
+        stored = result ?? null;
+        if (!errorCategory && capture) {
+            try {
+                const captured = capture(result);
+                stored = captured.stored;
+                complete = captured.complete;
+            }
+            catch (error) {
+                captureFailure = error;
+                errorCategory = categorizeRpcFailure(error, signal);
+                stored = { error: errorCategory };
+            }
+        }
+        const resultJson = JSON.parse(JSON.stringify(stored));
+        const evidence = { id, tool: WATCH_TOOL, source: { kind: 'rpc', provider: servedProviderLabel(input.chain, `${input.chain}-configured-rpc`, errorCategory ? null : transport.servedBy?.()), method, documentationUrl: RPC_DOCUMENTATION }, chain: input.chain, chainId: config.chainId,
+            request: JSON.parse(JSON.stringify(params)), snapshot: method === 'eth_getLogs' ? snapshot : null, observedAt: now().toISOString(),
+            finality: method === 'eth_getLogs' && snapshot ? 'sequencer-confirmed' : 'unverified', canonicality: 'unchecked', completeness: errorCategory || !complete ? '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 captureFailure ?? new EvmReadFailure(errorCategory, FAILURE_MESSAGES[errorCategory]);
+        }
+        return { result, id };
+    };
+    const header = async (block, step) => parseBlockHeader((await call(watchRequests.header(block === 'latest' ? 'latest' : blockTag(block)), step)).result);
+    const candidates = [];
+    try {
+        if (!SupportedWatchtowerManifestSchema.safeParse(manifest).success || !manifest.chains.includes(input.chain))
+            throw new EvmReadFailure('unsupported', 'This version asks for monitoring steps the Watchtower does not support.');
+        const refusal = watchRuleRefusal(manifest.version, input.rules);
+        if (refusal) {
+            report.unknowns.push(refusal);
+            throw new EvmReadFailure('unsupported', refusal);
+        }
+        if (!config.configured || !config.rpcUrl)
+            throw new EvmReadFailure('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 > WATCH_RPC_CEILING * 2)
+                throw invalid('Checkpoint identity or size is invalid.');
+            for (const raw of options.restore.evidence) {
+                const checked = WatchEvidenceItemSchema.safeParse(raw);
+                if (!checked.success)
+                    throw invalid('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' || !watchReceiptInScope(item, input))
+                    throw invalid('Checkpoint receipt integrity or scope is invalid.');
+                if (item.source.method !== 'eth_getLogs' || !item.snapshot)
+                    continue;
+                if (restoredSnapshot && item.snapshot.blockHash.toLowerCase() !== restoredSnapshot.blockHash.toLowerCase())
+                    throw invalid('Checkpoint receipts do not share one window end.');
+                restoredSnapshot = item.snapshot;
+                if (item.completeness === 'complete-for-request')
+                    restoredReads.set(requestKey({ method: item.source.method, params: item.request }), item);
+            }
+        }
+        transport = options.transport ?? createWatchTransport(config.rpcUrl);
+        if (parseQuantity((await call({ method: 'eth_chainId', params: [] }, 'chain-identity')).result) !== BigInt(config.chainId))
+            throw new EvmReadFailure('chain-mismatch', 'RPC chain mismatch.');
+        const head = await header('latest', 'latest-head');
+        report.window.headBlock = head.blockNumber;
+        if (to > BigInt(head.blockNumber))
+            throw new EvmReadFailure('unsupported', 'The window extends beyond the provider\'s latest block.');
+        report.window.headLagBlocks = Number(BigInt(head.blockNumber) - to);
+        const fromHeader = await header(from, 'window-start');
+        const toHeader = from === to ? fromHeader : await header(to, 'window-end');
+        if (fromHeader.blockNumber !== input.fromBlock || toHeader.blockNumber !== input.toBlock)
+            throw invalid('Returned window header height does not match the request.');
+        report.window.fromBlockHash = fromHeader.blockHash.toLowerCase();
+        report.window.toBlockHash = toHeader.blockHash.toLowerCase();
+        report.window.toBlockTimestamp = toHeader.timestamp;
+        if (restoredSnapshot && restoredSnapshot.blockHash.toLowerCase() !== report.window.toBlockHash)
+            throw new EvmReadFailure('snapshot-changed', 'The checkpointed window end changed before recovery.');
+        if (restoredSnapshot)
+            report.limitations.push('Checkpointed log reads retain their original observation times; the window end was revalidated before reuse and again at completion.');
+        snapshot = { blockNumber: input.toBlock, blockHash: report.window.toBlockHash };
+        report.status = 'partial';
+        let capacity = input.maximumLogs;
+        let coveredThrough = to;
+        const checkHeaders = (log) => {
+            if ((log.blockNumber === to && log.blockHash !== report.window.toBlockHash) || (log.blockNumber === from && log.blockHash !== report.window.fromBlockHash))
+                throw new EvmReadFailure('snapshot-changed', 'A log block hash differs from the window headers.');
+        };
+        /** A shared read is used only after this run's own window headers are read; the capture recheck binds its logs to those headers. */
+        const reuseShared = async (rule, request, step, capture) => {
+            if (!options.sharedReads || !snapshot || !report.window.fromBlockHash || !report.window.toBlockHash || restoredReads.has(requestKey(request)))
+                return null;
+            const key = sharedReadKey(input.chain, config.chainId, rule, input, report.window.fromBlockHash, report.window.toBlockHash);
+            let hit;
+            try {
+                hit = await options.sharedReads.get(key);
+            }
+            catch {
+                return null;
+            }
+            if (!hit || signal.aborted || !Number.isFinite(Date.parse(hit.observedAt)))
+                return null;
+            let captured;
+            try {
+                captured = capture(hit.result);
+            }
+            catch {
+                return null;
+            }
+            await progress(step, `Reusing a shared public read for ${step}.`);
+            const id = `rpc-${report.evidence.length + 1}`;
+            const resultJson = JSON.parse(JSON.stringify(captured.stored));
+            report.evidence.push({ id, tool: WATCH_TOOL, source: { kind: 'rpc', provider: `${input.chain}${SHARED_READ_PROVIDER_SUFFIX}`, method: request.method, documentationUrl: RPC_DOCUMENTATION }, chain: input.chain, chainId: config.chainId,
+                request: JSON.parse(JSON.stringify(request.params)), snapshot, observedAt: new Date(hit.observedAt).toISOString(), finality: 'sequencer-confirmed', canonicality: 'unchecked',
+                completeness: captured.complete ? 'complete-for-request' : 'error', result: resultJson, contentHash: contentHash(resultJson), privacy: 'public-chain-data' });
+            if (!report.limitations.some((line) => line.startsWith('Shared public read')))
+                report.limitations.push('Shared public read: at least one log read reused the raw public response another run captured for the same chain, block range, window-edge hashes, contract and topic filter. It was rechecked against this window\'s own headers; events, notifications, deliveries and charges are computed for this run only.');
+            return { result: hit.result, id };
+        };
+        const pendingShares = [];
+        for (const [index, rule] of input.rules.entries()) {
+            const coverage = report.rules[index];
+            const step = `logs-${rule.id}`;
+            try {
+                const remaining = capacity;
+                const capture = (raw) => {
+                    const logs = parseLogs(raw, input);
+                    const plan = capLogs(logs, remaining, input);
+                    plan.kept.forEach(checkHeaders);
+                    return plan.truncated ? { stored: { error: 'limit-exceeded', logsReturned: logs.length, retainedLogs: plan.kept.map((log) => log.raw), coveredThroughBlock: plan.coveredThrough.toString(), fullResultHash: contentHash(raw) }, complete: false } : { stored: raw, complete: true };
+                };
+                const request = watchRequests.logs(rule, input);
+                const shared = shareableRule(rule) ? await reuseShared(rule, request, step, capture) : null;
+                const response = shared ?? await call(request, step, capture);
+                if (!shared && options.sharedReads && shareableRule(rule) && Array.isArray(response.result) && response.result.length <= WATCH_MAX_LOGS && report.window.fromBlockHash && report.window.toBlockHash) {
+                    const observedAt = report.evidence.find((item) => item.id === response.id)?.observedAt ?? now().toISOString();
+                    pendingShares.push({ key: sharedReadKey(input.chain, config.chainId, rule, input, report.window.fromBlockHash, report.window.toBlockHash), result: response.result, observedAt, logs: response.result.length });
+                }
+                const logs = parseLogs(response.result, input);
+                const plan = capLogs(logs, remaining, input);
+                plan.kept.forEach(checkHeaders);
+                coverage.evidenceIds = [response.id];
+                coverage.logsReturned = logs.length;
+                coverage.coverage = plan.truncated ? 'truncated' : 'complete';
+                coverage.coveredThroughBlock = plan.coveredThrough >= from ? plan.coveredThrough.toString() : null;
+                coverage.reason = plan.truncated ? `Returned ${logs.length} logs, more than the remaining cap of ${remaining}; only whole blocks through ${plan.coveredThrough >= from ? plan.coveredThrough : 'none'} were examined.` : 'Every returned log in the window was examined.';
+                if (plan.truncated) {
+                    coveredThrough = plan.coveredThrough < coveredThrough ? plan.coveredThrough : coveredThrough;
+                    report.unknowns.push(`Rule ${rule.id} returned ${logs.length} logs, above the remaining cap of ${remaining}. Blocks ${plan.coveredThrough + 1n}-${input.toBlock} were not examined for any rule in this window.`);
+                }
+                capacity -= plan.kept.length;
+                for (const log of plan.kept) {
+                    const match = matchLog(rule, log);
+                    if (!match.fired) {
+                        coverage.ignored[match.reason] = (coverage.ignored[match.reason] ?? 0) + 1;
+                        continue;
+                    }
+                    coverage.logsMatched++;
+                    candidates.push({ eventKey: eventKey(input.chain, log.transactionHash, log.logIndex, rule.id), ruleId: rule.id, ruleType: rule.type, event: match.event, blockNumber: log.blockNumber.toString(), blockHash: log.blockHash,
+                        transactionHash: log.transactionHash, logIndex: log.logIndex, address: getAddress(log.address), fields: match.fields, explanation: match.explanation, evidenceIds: [response.id] });
+                }
+            }
+            catch (error) {
+                if (error instanceof RuntimeInterruption)
+                    throw error;
+                const category = categorizeRpcFailure(error, signal);
+                if (fatal(category) || category === 'snapshot-changed' || category === 'limit-exceeded' && report.usage.rpcCalls >= report.usage.maximumRpcCalls)
+                    throw error;
+                if (!report.errors.some((item) => item.step === step))
+                    addError(category, step);
+                coverage.coverage = 'unavailable';
+                coverage.reason = FAILURE_MESSAGES[category];
+                coverage.evidenceIds = report.errors.filter((item) => item.step === step && item.evidenceId).map((item) => item.evidenceId);
+                report.unknowns.push(`Rule ${rule.id} could not be read (${category}). This window makes no claim that the watched activity did not happen.`);
+            }
+        }
+        const unavailable = report.rules.some((rule) => rule.coverage === 'unavailable');
+        if (unavailable)
+            coveredThrough = from - 1n;
+        for (const event of candidates) {
+            if (BigInt(event.blockNumber) <= coveredThrough) {
+                report.events.push(event);
+                continue;
+            }
+            const rule = report.rules.find((item) => item.id === event.ruleId);
+            rule.logsMatched--;
+            rule.ignored['outside-coverage'] = (rule.ignored['outside-coverage'] ?? 0) + 1;
+        }
+        if (coveredThrough >= from && coveredThrough < to) {
+            report.window.coveredThroughBlockHash = coveredThrough === from ? report.window.fromBlockHash : (await header(coveredThrough, 'covered-through')).blockHash.toLowerCase();
+        }
+        else if (coveredThrough === to)
+            report.window.coveredThroughBlockHash = report.window.toBlockHash;
+        report.window.coveredThroughBlock = coveredThrough >= from ? coveredThrough.toString() : null;
+        report.window.coverage = unavailable ? 'unavailable' : coveredThrough === to ? 'complete' : 'partial';
+        if (!unavailable && coveredThrough < from)
+            report.unknowns.push(`Block ${input.fromBlock} alone exceeded the log cap of ${input.maximumLogs}; no block in this window was fully examined.`);
+        const ending = await header(to, 'window-end-canonicality');
+        if (ending.blockHash.toLowerCase() !== report.window.toBlockHash) {
+            report.window.canonicality = 'changed';
+            for (const item of report.evidence)
+                if (item.snapshot)
+                    item.canonicality = 'changed';
+            throw new EvmReadFailure('snapshot-changed', 'The window end changed during the scan.');
+        }
+        report.window.canonicality = 'verified-at-completion';
+        for (const item of report.evidence)
+            if (item.snapshot)
+                item.canonicality = 'verified-at-completion';
+        // Only reads whose window end was rechecked as canonical become shareable. Sharing is an optimization and never fails the window.
+        for (const share of pendingShares) {
+            try {
+                await options.sharedReads.put(share.key, { result: share.result, observedAt: share.observedAt, logs: share.logs });
+            }
+            catch { /* not shared */ }
+        }
+        report.status = report.window.coverage === 'unavailable' ? 'failed' : report.window.coverage === 'complete' && !report.errors.length ? 'complete' : 'partial';
+    }
+    catch (error) {
+        if (error instanceof RuntimeInterruption)
+            throw error.original;
+        const category = categorizeRpcFailure(error, signal);
+        if (!report.errors.some((item) => item.category === category))
+            addError(category, 'watch-window');
+        report.status = 'failed';
+    }
+    if (report.status === 'failed') {
+        // A failed window never carries events or coverage claims.
+        report.window.coverage = 'unavailable';
+        report.window.coveredThroughBlock = null;
+        report.window.coveredThroughBlockHash = null;
+        report.events = [];
+        if (!report.unknowns.some((item) => item.includes('no claim')))
+            report.unknowns.push('The window could not be completed. It makes no claim that the watched activity did not happen.');
+    }
+    report.generatedAt = now().toISOString();
+    report.usage.elapsedMs = Math.max(0, now().getTime() - started);
+    if (report.window.toBlockTimestamp !== null)
+        report.window.dataLagSeconds = Math.max(0, Math.floor(now().getTime() / 1000) - Number(report.window.toBlockTimestamp));
+    report.unknowns = report.unknowns.slice(0, 32);
+    if (Buffer.byteLength(JSON.stringify(report)) > Math.min(OUTPUT_CEILING, manifest.limits.maximumOutputBytes))
+        throw new EvmReadFailure('limit-exceeded', 'The captured window exceeds the configured output budget; no truncated report is accepted.');
+    if (report.events.length > WATCH_MAX_LOGS)
+        throw new EvmReadFailure('limit-exceeded', 'Event count exceeds the Watchtower bound.');
+    return WatchtowerWindowReportSchema.parse(report);
+}