Skip to content

TASK: Complete ledger outbox failure and delivery semantics #170

Closed

Description

@ramioooz

Type: Task
Parent: #101
Epic: Ledger and Financial Posting
Slice: Slice 7 - Events + Notification
Service: ledger-service
Priority: P0

Objective

Complete the Ledger Service outbox behavior required to publish governed posting lifecycle events after durable ledger decisions.

Scope

  • Carry the business transaction identifier through the posting command, persisted outbox record, and event payload.
  • Define and implement the production call path for LedgerPostingFailed; do not emit a failure event for a request rejected before a ledger decision exists.
  • Add retryable, idempotent outbox delivery behavior with bounded attempts and an explicit dead-letter/quarantine outcome.
  • Define the Kafka partition key and ordering behavior using the governed event contract.
  • Preserve append-only ledger immutability and transactional coupling between ledger decisions and outbox records.
  • Add unit, PostgreSQL integration, and delivery behavior tests.
  • Update README and operational documentation with the delivery state machine and recovery procedure.

Acceptance Criteria

  • A durable completed or failed ledger decision produces exactly one corresponding outbox event record.
  • Delivery retries do not publish the same event as a different event identity.
  • Exhausted delivery is visible as a durable quarantine/dead-letter outcome and does not silently disappear.
  • Event payload and headers conform to the versioned ledger event contract.
  • The partition key and ordering guarantee are documented and tested at the publisher boundary.
  • ./mvnw verify, Helm validation, and container smoke verification pass.

Dependencies

This task must remain under parent story #101 and must be implemented through a non-draft PR. Do not merge directly to main.

Activity

  1. self-assigned this
    on Aug 31, 2026
  2. added theissue type on Aug 31, 2026
  3. ramioooz commented on Aug 31, 2026

    @ramioooz
    MemberAuthor

    Implemented and opened ledger-service#16 as a non-draft safety follow-up. It hardens cross-outcome posting idempotency, quarantines legacy outbox rows without governed metadata, enforces lease-backed terminal transitions, and prevents false retries after lease loss. Local ./mvnw verify passed with 21 unit tests and 24 integration tests. Merge dependency: the outbox-delivery foundation in ledger-service#15 must be available in the target base before this PR is merged.

  4. ramioooz commented on Sep 1, 2026

    @ramioooz
    MemberAuthor

    Completed by merged Ledger Service PR #15 and safety follow-up #16. Verification recorded in the PRs includes Maven verify, Helm validation, PostgreSQL/Testcontainers coverage, retry/quarantine behavior, lease safety, and cross-outcome idempotency.

  5. ramioooz commented on Sep 3, 2026

    @ramioooz
    MemberAuthor

    Ledger outbox integration PR is ready for review: digital-bank-java/ledger-service#17

    It integrates ledger-service#15 and #16 on top of #14. Existing verification passed: 26 tests, Flyway migration/persistence coverage, and git diff --check.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions