feat(negotiation): add first-class buyer and seller proposal APIs

[garvitkaushik-123]

Summary

Implements the foundation for #36 — first-class proposal negotiation types for the refine_proposals tool surface introduced in AdCP 3.2.

This covers the three modules referenced in the issue's acceptance criteria:

Client (adcp module)

• Sealed RefinementResult with four outcome variants (Revised, Partial, Finalized, Unable) supporting Java 21 exhaustive pattern matching and Jackson polymorphic deserialization on the outcome discriminator
• RefineProposalsRequest builder enforcing batch size ceilings, unique proposal IDs, finalize-only homogeneity, and idempotency key format — all validated before transport
• Typed constraint records for the three new 3.2 constraints: CpmConstraint (max CPM + currency), ImpressionsConstraint (minimum summed impressions), FlightConstraint (start/end bounds with the "asap never satisfies start" rule noted in the spec)
• TermsDigest — self-contained RFC 8785 JCS canonicalization + SHA-256 digest computation and verification. Recomputes and compares rather than trusting the string, per the 3.2 normative spec. Also provides areDistinct() for alternative distinctness checks
• ResponseVerifier checking result ordering against the request, lineage (parent_proposal_id == source_proposal_id), finalize atomicity, outcome-specific structural constraints (status/expires_at/reason/notes), partial invariant (unsatisfied_constraints must be present), unique proposal IDs, and digest integrity
• RefinementCapability with the post-rename product_changes dimension key
• UnsupportedRefinementDetails for typed UNSUPPORTED_FEATURE error recovery
• AdcpClient.refineProposals() convenience method delegating to callNamedTool

Server (adcp-server module)

• ProposalHandler interface with capability declaration, optional preflight hook for cross-entry validation, and refine() callback. Framework does batch validation; commercial decisions stay in the application callback

Testing (adcp-testing module)

• NegotiationFixtures with factory methods for single revise, batch finalize, draft/committed proposals, constraint objects, and JSON response fragments for revised and unable outcomes

Design decisions

• unsatisfied_constraints is List<String> (open strings), not an enum — per the 3.2 delta comment
• Reason code precedence rule is documented but not enforced at the type level (it's a server-side business rule)
• JCS canonicalization is self-contained to avoid a mandatory runtime dep on org.webpki.jcs for the common case. The risky JCS number formatting follows ES2015 rules
• ProposalRefinement factory methods cover the four common patterns (revise with instructions, revise with criteria, finalize, cancel)

Not in this PR

• Reactive (Reactor/Mutiny) and Kotlin coroutine surfaces — these will mirror the same types once the sync API shape stabilizes
• Integration tests against a live mock server (will follow in a separate PR extending adcp-testing)
• Wiring ProposalHandler into AdcpServerBuilder tool registration (needs the codegen track to emit the input schema)

Test plan

• RefineProposalsRequestTest — builder validation: valid requests, null/short idempotency keys, empty refinements, mixed finalize/revise rejection, duplicate proposal IDs, batch size ceiling, immutable list, cancellation refinements
• RefinementResultTest — sealed interface permits, Jackson round-trip for all four outcomes, pattern matching exhaustiveness
• TermsDigestTest — sha256 prefix, determinism, key-order independence, verify/tamper detection, null/wrong-prefix rejection, distinctness, JCS canonicalization of nested objects/strings/numbers/booleans/nulls
• ResponseVerifierTest — valid response passes, count mismatch, ordering mismatch, mixed finalize, missing lineage, wrong proposal_status for finalized, async skip, digest mismatch detection
• ConstraintsTest — validation for all three constraint types, rejection of invalid inputs, Jackson round-trip serialization
• Full ./gradlew build passes (all 55 tasks, all existing tests still green)

Closes #36 (partial — see "Not in this PR" above; reactive/Kotlin surfaces and integration tests tracked separately)

[aao-ipr-bot]

⚠️ Argus review could not complete

The automated review encountered an issue (possibly reached max turns, timed out, or failed to post the final gh pr review). A human reviewer should take this PR.

View workflow run

_{This is an automated message from the Argus AI review workflow.}

[aao-ipr-bot]

⚠️ Argus review could not complete

The automated review encountered an issue (possibly reached max turns, timed out, or failed to post the final gh pr review). A human reviewer should take this PR.

View workflow run

_{This is an automated message from the Argus AI review workflow.}