TDD PRD

Context

Build a paid supplier-intelligence API selling lead-time drift, fill-rate risk, and disruption probability.

Problem

Procurement agents cannot consistently compare supplier reliability across regions and product categories.

Buyer User Story (Agent-to-Agent)

As a sourcing agent, I need normalized reliability signals and confidence bands to choose resilient suppliers under constraints.

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/suppliers/score, GET /v1/suppliers/lead-time-forecast, GET /v1/suppliers/disruption-alerts
• Inputs: supplierId, category, region, horizonDays, riskTolerance
• Outputs: supplier_score, lead_time_p50_p95, disruption_probability, alert_reasons, freshness_ms

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: forecast backtests, anomaly detection tests, ranking consistency, paid endpoint guards, SLA freshness assertions
• 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: 0xeae805c5e9439f832fe1a74ec1778252913174e11b833a1f3d1a5b7296adb36b
• TaskMarket API URL: https://api-market.daydreams.systems/api/tasks/0xeae805c5e9439f832fe1a74ec1778252913174e11b833a1f3d1a5b7296adb36b