CBDD/docs/features/change-data-capture.md

Change Data Capture

Purpose And Business Outcome

Expose transactional change events so consumers can react to committed inserts, updates, and deletes.

Scope And Non-Goals

Scope:

• Collection-level change stream subscriptions
• Event publication after successful commit

Non-goals:

• Cross-process event transport guarantees
• External message broker delivery semantics

User And System Workflows

1. Consumer subscribes to a collection change stream.
2. Application performs data mutations.
3. On commit, CDC publishes events to active subscribers.
4. Subscriber handlers process entity and metadata payloads.

Interfaces And APIs

• Watch(...) collection API
• ChangeStreamObservable
• ChangeStreamDispatcher
• ChangeStreamEvent

Permissions And Data Handling

• CDC payloads can include document identifiers and entity data.
• Restrict subscription access to trusted application components.

Dependencies And Failure Modes

Dependencies:

• Transaction commit lifecycle
• Subscriber channel health

Failure modes:

• Subscriber backpressure or handler exceptions
• Event handling assumptions that conflict with rollback behavior

Monitoring, Alerts, And Troubleshooting

• Review CDC behavior in integration and scalability tests.
• Follow ../runbook.md for incident response.
• Follow ../security.md for event payload handling controls.
• Use ../troubleshooting.md for diagnosis guidance.

Rollout And Change Considerations

• Behavioral CDC changes require explicit release-note callouts.
• Maintain compatibility expectations for event payload shape.

Validation Guidance

• Run CdcTests and CdcScalabilityTests before release.
• Validate commit-only emission behavior in regression tests.