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

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.