RFC-0008: Compliance, Versioning, and Corrections

Submitted documents in Framework M are strictly immutable. To handle real-world edits, complex temporal reporting, and external system integrations without breaking the ledger, we are proposing four formal patterns:

1. The Sensible Default: Audit Timeline (AuditMixin)

   • Append-only global JSON log.
   • Provides out-of-the-box traceability ("Who changed what, when, and why") with minimal database footprint.
   • Ideal for UI rendering and indie deployments.

2. The Enterprise Escalation: Shadow Tables (VersionedMixin)

   • Provisions dedicated _history SQL tables mirroring the primary schema.
   • Enables fast temporal SQL querying ("Time Travel") for high-compliance environments.
   • Crucially: Gated by Deployment-Level configuration (config.toml). Indie deployments face zero DB bloat unless they explicitly opt-in, at which point the DB Adapter handles routing and DDL.

3. Sibling Extensions (Metadata Overlays)

   • Keep core financial documents locked.
   • Link an editable "Sibling" DocType for volatile, non-ledger metadata (Driver, Vehicle, ETA).
   • The UI overlays these fields so it feels like a single document, without causing race conditions or invalidating the ledger.

4. The Correction Wizard (3 Regulated Flows)

   • Controlled via DocTypeMeta (correction_strategy):
     • Amend: The universal default. Cancels the document and creates a new Draft under a new incremented ID.
     • Restore: Rollback to a previous snapshot.
     • In-Place Edit (PK Acrobatics): For operational workflows (e-commerce, WMS integrations) where external systems crash if the machine id or human name changes. This executes a strict transaction: deep-copies the submitted row to _history, rolls the primary row back to Draft, and retains the exact same ID for external APIs.

Discussion MR: GitLab MR !111

Thoughts?

Edit: Track the progress here https://gitlab.com/castlecraft/framework-m/-/merge_requests/132