CBDD/docs/features/storage-transactions.md

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 for triage.
• Follow ../security.md for data handling and control requirements.
• Use ../troubleshooting.md 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.