# Storage And Transactions

## Purpose And Business Outcome

Provide durable, ACID-compliant local persistence for embedded workloads that need consistent commit and recovery semantics.

## Scope And Non-Goals

Scope:
- Page-based storage
- Write-ahead logging
- Transaction lifecycle and commit/rollback semantics

Non-goals:
- Distributed transactions
- Multi-node replication

## User And System Workflows

1. Application writes through `DocumentDbContext`.
2. Engine records WAL entries.
3. Commit persists pages and marks transaction durable.
4. Recovery replays WAL to restore committed state after restart.

## Interfaces And APIs

- `DocumentDbContext`
- `Transaction` and `ITransaction`
- `WriteAheadLog`
- Storage engine modules under `src/CBDD.Core/Storage`

## Permissions And Data Handling

- Database files require host-managed filesystem access controls.
- Transaction data should be treated as sensitive if payloads contain regulated information.

## Dependencies And Failure Modes

Dependencies:
- Local filesystem I/O
- WAL and page file consistency

Failure modes:
- Interrupted writes
- Corrupted WAL entries
- Invalid page metadata after unsafe process termination

## Monitoring, Alerts, And Troubleshooting

- Use CI/test failures and incident issues as primary signals.
- Follow [`../runbook.md`](../runbook.md) for triage.
- Follow [`../security.md`](../security.md) for data handling and control requirements.
- Use [`../troubleshooting.md`](../troubleshooting.md#data-file-and-recovery-issues) for recovery issues.

## Rollout And Change Considerations

- Any storage format or WAL behavior change requires migration and rollback validation.
- Release notes must document backward compatibility impact.

## Validation Guidance

- Run transaction and recovery tests in `tests/CBDD.Tests`.
- Execute `dotnet test CBDD.slnx -c Release` before merge.