TDD PRD

Context

Build a paid macro-data API that sells event-normalized impact vectors for sectors, assets, and supply chains.

Problem

Portfolio and planning agents cannot consistently translate macro events into machine-usable impact signals.

Buyer User Story (Agent-to-Agent)

As a decision agent, I need standardized impact vectors from macro events to trigger automated hedging and reallocation.

Product Scope

• Sell data through paid HTTP endpoints (x402) for machine consumers.
• Expose deterministic JSON contracts with strict Zod validation.
• Provide freshness metadata and confidence annotations in every response.
• Support programmatic agent consumers via stable API versioning.

API Contract (v1)

• Endpoints: GET /v1/macro/events, GET /v1/macro/impact-vectors, POST /v1/macro/scenario-score
• Inputs: eventTypes, geography, sectorSet, horizon, scenarioAssumptions
• Outputs: event_feed, impact_vector, confidence_band, sensitivity_breakdown, scenario_score

Architecture Requirements (Lucid Packages)

• Runtime: @lucid-agents/core
• Transport + SSE: @lucid-agents/http
• Paywall + pricing: @lucid-agents/payments
• Receivables wallet: @lucid-agents/wallet
• Trust & attestations: @lucid-agents/identity
• Upstream agent federation: @lucid-agents/a2a
• Revenue sharing and composable payments: @lucid-agents/ap2

TDD Plan (Required Sequence)

1. Write failing contract tests for all request/response schemas and error envelopes.
2. Write failing business-logic tests for core data transforms and ranking/scoring behavior.
3. Write failing integration tests for paid-route behavior (x402 required on monetized endpoints).
4. Write failing freshness/quality tests (staleness thresholds, confidence propagation).
5. Implement minimum code to pass tests incrementally.
6. Refactor with tests green, preserving API behavior and performance budgets.

Test Coverage Requirements

• Focus: event normalization tests, vector stability tests, scenario scoring tests, paywall tests, response latency budgets
• Unit: schema parsing, pure transforms, scoring/ranking invariants.
• Integration: endpoint handlers + payment middleware + A2A upstream adapters.
• Contract: stable JSON shape, explicit error codes, backwards-compatible field semantics.

Acceptance Criteria

• All monetized endpoints require payment and return valid data after successful payment.
• All responses include freshness and confidence fields where relevant.
• P95 response time for cached path <= 500ms under test workload.
• Test suite passes in CI with no skipped critical tests.
• README includes endpoint examples for agent consumers.

Deliverables

• Source implementation with typed contracts.
• Test suite (unit + integration + contract).
• API docs/examples for machine consumers.
• Configuration docs for pricing and receivable wallet.

Definition of Done

• PR opened referencing this issue.
• CI green with test evidence attached.
• Reviewer confirms TDD order from commit history and test evolution.

TaskMarket Cross-Reference

• TaskMarket Task ID: 0xb435dbe6006d608fbdde93cb3c25e13ca40eac29f0d3d54f6de21314ebab24c0
• TaskMarket API URL: https://api-market.daydreams.systems/api/tasks/0xb435dbe6006d608fbdde93cb3c25e13ca40eac29f0d3d54f6de21314ebab24c0