TDD PRD

Context

Build a paid graph-intelligence API that sells wallet/entity clustering, exposure paths, and risk scores.

Problem

Payment and underwriting agents lack standardized machine-readable counterparty risk context before transacting.

Buyer User Story (Agent-to-Agent)

As a payment-routing agent, I need exposure-chain and risk evidence in one response so I can avoid high-risk counterparties automatically.

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: POST /v1/risk/score, GET /v1/risk/exposure-paths, GET /v1/risk/entity-profile
• Inputs: address, network, transaction_context, threshold, lookback_days
• Outputs: risk_score, risk_factors, exposure_paths, cluster_id, sanctions_proximity, evidence_refs

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: graph traversal correctness, deterministic scoring, false-positive guardrails, paid route tests, evidence reference integrity
• 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: 0x2d5b5d7d419c76537b2edbcf7e54a51ae7d07bc7a428cf8b0b1d62fe8d33ea4c
• TaskMarket API URL: https://api-market.daydreams.systems/api/tasks/0x2d5b5d7d419c76537b2edbcf7e54a51ae7d07bc7a428cf8b0b1d62fe8d33ea4c