feat(agent-003): real MsgRetire tx-stream for WF-MM-03

[brawlaphant]

Summary

Replaces the batch-supply-delta MVP proxy in WF-MM-03 with a real tx-search client that reads recent `MsgRetire` events from the Cosmos LCD. Closes the follow-up documented in #80's design-decision #3.

• Lands in: `agent-003-market-monitor/`
• Changes: new tx-search client methods + rewritten WF-MM-03 observe+orient phases + 16 new tests
• Validate: `cd agent-003-market-monitor && npm test && npx tsc --noEmit`

The change

Before (MVP)	After (real tx-stream)
Walk batches → supplies, derive retirement by `retired_amount` delta	Query LCD `tx-search` for `/regen.ecocredit.v1.MsgRetire`, parse per-tx
`topRetiree` / `topRetireeQuantity` / `pctWithJurisdiction` all empty	All fields populated from real `EventRetire` attributes
No tx hash, no retirement timestamp	`txHash` and `retiredAt` carried through from the tx response
Synthetic "unique retirees" proxied by batch count	Real unique retirees via Set of owner addresses

Ledger client additions

• `getRecentRetirementTxs(limit)` — public, queries the LCD tx-search endpoint with events filter, reverse-ordered, limited. Returns `[]` on any error.
• `parseRetirementsFromTx(tx)` — public pure function. Walks `logs[].events[]` AND top-level `events[]` for cross-SDK compatibility. Accepts both the Regen v1 and v1beta1 `EventRetire` type URLs. Skips malformed events (missing batch_denom, non-finite amount, non-positive amount).

Workflow refactor

• `observe()` replaced with `ledger.getRecentRetirementTxs(200)` call.
• `orient()` now calls a new pure function `aggregateRetirementsByClass` that groups retirements by class id, identifies the top retiree by cumulative quantity (not count — pinned by a unit test), counts unique retirees via a Set, and measures jurisdiction coverage.
• `act()` unchanged — still persists, outputs, and alerts on demand-index jumps.

Test additions — 16 new tests (68 total, up from 52 in #99)

`src/ledger.test.ts` (9 new tests)

Case	Pins
empty tx	Parser returns [] cleanly
single EventRetire	All 5 Retirement fields populated correctly
v1beta1 fallback	Both the v1 and v1beta1 EventRetire type URLs accepted
non-retirement events	Ignored
missing batch_denom	Skipped (not thrown)
non-finite / zero / negative amounts	All skipped
multiple retirements in one tx	Batched retirements all extracted
events in tx.events[]	Flat-event LCD shapes work alongside nested
tx hash + timestamp	Carried through to Retirement record

`src/workflows/retirement-tracking.test.ts` (7 new tests)

Case	Pins
empty retirements	Empty aggregator result
single retirement	One-entry summary with all fields
multiple by class	Correct grouping by class id
top retiree by quantity not count	3 small + 1 big → big is top
jurisdiction percentage	2 of 4 → 50%
zero-quantity classes skipped	Degenerate case
empty retiree string	Handled without crash

What this unlocks

Downstream consumers now get:

• Retiree identity in the narrative layer (replacing the `(none)` placeholder)
• Jurisdiction coverage that can surface compliance-driven demand (per the SPEC: ">50% jurisdiction coverage typically implies compliance-driven demand")
• Concrete tx hash + timestamp for every retirement, enabling downstream auditing and cross-referencing with the LCD
• Real unique retiree counts for the demand-breadth component of the index

PR relationship

Based on #99 (AGENT-003 unit tests), which is based on #80 (AGENT-003 initial implementation). If both land first, this PR rebases cleanly.

Refs `phase-2/2.2-agentic-workflows.md` §WF-MM-03
Refs #80's design decision #3 (MVP proxy → real tx-stream follow-up)

[gemini-code-assist]

Code Review

This pull request introduces AGENT-003, the Regen Market Monitor, a standalone Node.js agent that tracks ecocredit price anomalies, liquidity health, and retirement demand using OODA-based workflows and SQLite persistence. The review feedback highlights several opportunities for improving data accuracy and statistical consistency. Specifically, the ledger client should be updated to avoid duplicate event processing and to broaden transaction search filters. Additionally, the implementation should use BigInt for blockchain amounts to prevent precision loss, correct the Z-score logic to use means instead of medians for standard deviation consistency, and utilize median ask prices rather than hardcoded values for retirement summaries.

[gemini-code-assist]

The current implementation duplicates events when both logs[].events and the top-level tx.events are present in the LCD response. In most Cosmos SDK versions, tx.events is a flattened superset of all events found in the logs. This will result in every retirement being counted twice, leading to incorrect volume and count metrics in downstream workflows. It is safer to prefer the flattened list if available and fallback to logs otherwise.

    // Cosmos LCD responses can carry events at two levels: per-msg
    // inside `logs[i].events[]`, and flattened at `tx.events[]`. We
    // prefer the flattened list if available to avoid duplication.
    const events = (Array.isArray(tx.events) && tx.events.length > 0)
      ? (tx.events as Array<Record<string, unknown>>)
      : logs.flatMap(log => (log.events || []) as Array<Record<string, unknown>>);

[gemini-code-assist]

The tx-search query filter is restricted to the v1 MsgRetire type. While the parser (lines 190-197) correctly handles both v1 and v1beta1 event types, transactions using the v1beta1 message type will never be returned by this search. If the intention is to support both, you may need to perform separate queries or use a broader filter if supported by the specific LCD endpoint.

[gemini-code-assist]

Using Number() to parse blockchain amounts can lead to precision loss for very large values (above Number.MAX_SAFE_INTEGER). While ecocredits typically use 6 decimals, it is safer to use BigInt for the raw integer units to ensure accuracy across all possible credit types, especially if credits with higher precision (e.g., 18 decimals) are supported in the future.

[gemini-code-assist]

The Z-score calculation is statistically inconsistent because it uses the classMedian in the numerator but the classStd (standard deviation) in the denominator. Standard deviation is calculated relative to the mean. To compute a standard Z-score, you should use classMean. If you prefer robustness to outliers, consider using a Robust Z-score formula using the median and Median Absolute Deviation (MAD).

Suggested change

	const zClass = classStd > 0 ? (trade.pricePerCredit - classMedian) / classStd : 0;
	const zClass = classStd > 0 ? (trade.pricePerCredit - classMean) / classStd : 0;

[gemini-code-assist]

Similar to the class Z-score, the batch Z-score should use batchMean in the numerator to remain statistically consistent with the standard deviation used in the denominator.

Suggested change

	const zBatch = batchStd > 0 ? (trade.pricePerCredit - batchMean) / batchStd : 0;

[gemini-code-assist]

Hardcoding the USD value as 1:1 with the credit quantity can lead to significantly inaccurate reports in the narrative layer, as credit prices often deviate from $1.00. Since this agent already monitors sell orders in WF-MM-02, consider using the most recent median ask price for the credit class as a more accurate proxy for value until a full price oracle is integrated.