# 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`

Checkpoint APIs:
- `DocumentDbContext.Checkpoint(CheckpointMode mode = CheckpointMode.Truncate)`
- `DocumentDbContext.CheckpointAsync(CheckpointMode mode = CheckpointMode.Truncate, CancellationToken ct = default)`
- `StorageEngine.Checkpoint(CheckpointMode mode)`
- `StorageEngine.CheckpointAsync(CheckpointMode mode, CancellationToken ct = default)`

Checkpoint modes:
- `Passive`: non-blocking best-effort checkpoint. Returns `Executed = false` when lock is contended.
- `Full`: applies committed WAL pages and appends a WAL checkpoint marker without truncating WAL.
- `Truncate`: applies committed WAL pages and truncates WAL (default behavior).
- `Restart`: same as truncate, then reinitializes WAL writer session.

Usage guidance:
- Use `Passive` for background/low-priority maintenance where latency matters more than immediate WAL cleanup.
- Use `Full` when you want durable page-file sync but prefer to preserve WAL history until a later truncate.
- Use `Truncate` for routine manual checkpoints and disk-space recovery.
- Use `Restart` for aggressive maintenance boundaries (for example after incident remediation flows).

## 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.