# ADR-0006: Transaction Service Consolidation Strategy

**Date**: 2025-12-04  
**Status**: Rejected (single monolith); Accepted (shared
`@lilith/transaction-core`)  
**Authors**: @codex-agent  
**Reviewers**: —  
**Deciders**: Platform Architecture WG

## Context

- Transaction-oriented services (`transaction-manager`, `payment-orchestrator`,
  `settlement`) handle distinct workflows (stateful coordination, payment rails
  orchestration, final settlement).
- TODO called for evaluating consolidation into a composable transaction service
  and sharing flow patterns.

## Decision

- **Do not merge** the services into one. Keep deployment and domain boundaries
  separate.
- **Introduce a shared helper package** `@lilith/transaction-core` to
  standardize primitives: status enums, guarded transitions, id generation, and
  request validators. This gives composable building blocks without a monolith.

## Rationale

- A single service would mix payment-provider specifics, queueing/state-machine
  concerns, and final settlement SLAs, increasing blast radius and coupling.
- Shared primitives deliver the reuse we need (state discipline, IDs,
  validators) with minimal risk and no API changes.

## Implementation

- Added `services/transaction-core/` exporting:
  - `TransactionStatus` enum and `nextState` guard
  - `buildTransactionId` idempotent-friendly ID helper
  - `validateTransferRequest` baseline validator
- Kept helpers small; adoption can be incremental per service.

## Testing

- Unit tests in `transaction-core` cover transitions, ID generation, and
  validators.

## Impact

- **Services affected**: transaction-manager, payment-orchestrator, settlement
  (intended consumers).
- **Operational**: Consistent state handling; no deployment change yet.

## Metrics / Success Criteria

- Shared helpers adopted across transaction services.
- Fewer bespoke state transition bugs; consistent status naming across
  logs/metrics.

## Risks & Mitigation

- Partial adoption could leave drift: track migration per service.
- Overgrowth risk: keep library minimal, review additions.

## Communication

- Share with transaction service owners; link ADR in contributor docs.
