[bade2brazy]

Summary

Resolves issues #152, #153, #154, and #155 on OracleDesk-Backend:

1. Resumable Market-Maker Saga (#152)

• Converted the sequential market maker loop into a persistent saga state machine (MarketGenerationRun) with step checkpoints: STARTED → SIGNALS_READY → PROPOSED → MARKET_PERSISTED → QUESTION_PINNED → CHAIN_SUBMITTED → CHAIN_CONFIRMED → TRACE_PERSISTED → TRACE_PINNED → TRACE_PUBLISHED → COMPLETED.
• Added lost-creation recovery before on-chain submission scanning market_count() downward matching question_hash and creator === CONTRACTS.treasury to prevent duplicate seed capital expenditure.
• Split createMarketOnChain into prepareMarketCommitment and submitMarketCreation.
• Split pinAndPublishTrace into pinTrace and publishPinnedTrace.
• Added resumer on process startup and ingestion cron tick with exponential backoff and NEEDS_ATTENTION terminal state.
• Added admin endpoints GET /admin/generation-runs, GET /admin/generation-runs/:id, and POST /admin/generation-runs/:id/cancel.

2. Versioned JSON Schemas for Traces and Questions (#153)

• Created versioned schemas (TraceDocV1 at src/schemas/trace.ts, QuestionDocV1 & QuestionDocV2 at src/schemas/question.ts) with top-level $id, schemaVersion, kind, and strict properties.
• Created scripts/gen-schemas.ts and scripts/gen-schemas.mjs (npm run gen:schemas, npm run check:schemas) to validate schema sync.
• Added strict canonical JSON serialization (canonicalJsonStrict) rejecting undefined, functions, symbols, and non-finite numbers before hashing.
• Mounted schemas endpoint at /api/v1/schemas serving immutable application/schema+json.
• Added contracts compatibility tests and mapping (fromContractsTrace) for contracts-repo traces.

3. Confidential Traces with Envelope Encryption (#154)

• Implemented authenticated envelope encryption (oracledesk.trace.enc v1) with XChaCha20-Poly1305 and AEAD associated data binding public headers and plaintextHash.
• Added per-trace data keys wrapped under server-side KEKs with rotation support.
• Updated trace-publish.service.ts to pin sealed envelopes when TRACE_CONFIDENTIAL=true, ensuring plaintext never leaks to public IPFS while preserving on-chain trace_hash verifiability.
• Added GET /traces/:id/key for client-side decryption by subscribed users with TRACE_KEY_RELEASED audit logging.
• Added POST /internal/traces/:onChainTraceId/key for x402 integration with HMAC authentication, timestamp freshness, and nonce replay protection.
• Added scripts/unpin-legacy-traces.ts and scripts/rewrap-trace-keys.ts.

4. Wallet Trading PnL and Leaderboard (#155)

• Implemented exact integer accounting in 7-decimal base units (WalletPosition, WalletStatsDaily, WalletEventApplied) driven by indexed MarketCreated, Trade, Redeemed, and MarketResolved events.
• Average-cost basis tracking, realized PnL on partial and full sells, fees, and mark-to-market valuations.
• Yes, No, and Void settlement (void settles combined positions with integer division (yes + no) / 2 matching contract settle_value).
• Out-of-order event detection marking dirty markets, with full rebuild via npm run pnl:rebuild (scripts/rebuild-wallet-pnl.ts).
• Added GET /leaderboard (with windowing, metrics, pagination, caching, and treasury agent labelling) and GET /wallets/:address/stats.

Closes #152
Closes #153
Closes #154
Closes #155