TDD PRD

Context

Build a paid API that sells machine-readable regulation/policy deltas with impact tagging.

Problem

Compliance agents waste cycles on unstructured legal updates and miss critical rule changes.

Buyer User Story (Agent-to-Agent)

As a compliance automation agent, I need structured rule diffs and impacted control tags so I can auto-open remediation workflows.

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/regulations/delta, GET /v1/regulations/impact, POST /v1/regulations/map-controls
• Inputs: jurisdiction, industry, since, source_priority, control_framework
• Outputs: rule_diff, semantic_change_type, affected_controls, effective_date, urgency_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: diff precision tests, semantic labeling accuracy, date handling, paywall tests, backward-compatible schema tests
• 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: 0x111024dcee0ef86ed623d7f926ead0f089fb9a5a2939adb1bba9c0fdc48b92bd
• TaskMarket API URL: https://api-market.daydreams.systems/api/tasks/0x111024dcee0ef86ed623d7f926ead0f089fb9a5a2939adb1bba9c0fdc48b92bd