feat: add versioned returns and deterministic calculation foundation

[lahiruudayakumara]

Summary

• Add immutable form and calculation-rule version references to return drafts.
• Implement the explicit DRAFT → VALIDATED → CALCULATED → SUBMITTED lifecycle.
• Produce deterministic field-level validation codes.
• Add a side-effect-free calculation interface and fictional flat-rate implementation.
• Record calculation inputs, explanations, rounding policy, payload hashes, and result hashes.
• Reject stale versions, incompatible rules, and payload changes after validation or calculation.
• Freeze submitted return payload fingerprints.
• Implement copy-on-amend behavior while preserving the original return and complete revision history.
• Add filing repository and immutable form-catalog ports.
• Add return retrieval, calculation, amendment, and history API endpoints.
• Add a fictional versioned country-pack form schema.
• Update database constraints, OpenAPI, event contracts, metrics, diagrams, and domain documentation.
• Add domain, authorization, deterministic calculation, amendment, and HTTP integration tests.

Closes #12

Risk and security impact

Risk is critical because this establishes foundational filing and calculation behavior.

Controls introduced include:

• Mandatory tenant and jurisdiction isolation
• Authorization checks for creating, validating, calculating, submitting, reading, and amending returns
• Immutable form and rule version references
• Payload fingerprints to detect changes after validation
• Deterministic integer-only financial calculations
• Explicit overflow and incompatible-rule rejection
• Safe API problem responses without internal error details
• No raw return lines or taxpayer data in logs, traces, or metric labels
• Immutable submitted returns and append-only amendment history

All included forms, rules, rates, currencies, and amounts are fictional examples.

Database, API, event, or country-pack changes

Database

• Extend filing records with:
  • Tenant and jurisdiction scope
  • Lifecycle status constraints
  • Revision and original-return identifiers
  • Superseded-return references
  • Validation and calculation results
  • Payload and frozen-payload hashes
  • Submission integrity constraints

API

Added or expanded:

• POST /api/v1/returns
• GET /api/v1/returns/{returnId}
• POST /api/v1/returns/{returnId}/validate
• POST /api/v1/returns/{returnId}/calculate
• POST /api/v1/returns/{returnId}/submit
• POST /api/v1/returns/{returnId}/amend
• GET /api/v1/returns/{returnId}/history

Events

Added:

• ReturnCalculated

Updated contextual events:

• ReturnCreated
• ReturnValidated
• ReturnSubmitted
• ReturnAmended

Country packs

• Add immutable fictional form schema sample-income-v1.
• Pin it to fictional-flat-rate-v1.
• Document the HALF_AWAY_FROM_ZERO_TO_MINOR_UNIT rounding policy.
• No authoritative country tax values are included.

Verification

• Go tests pass with race detection
• Go vet passes
• Go build passes
• OpenAPI validation passes
• Event-schema validation passes
• Country-pack JSON validation passes
• Developer configuration validation passes
• Formatting and Git diff checks pass
• Tests added or updated
• No real taxpayer data, secrets, or authoritative unverified tax values
• Module ownership and append-only rules preserved
• Documentation and diagrams updated