Skip to main content

RFC-0004: Submitted Document Mutability

  • Status: Rejected
  • Author: @revant.one
  • Created: 2026-02-13
  • Updated: 2026-02-24
  • TSC Decision: Rejected (Anti-Pattern)

Summary​

This RFC originally proposed a "Field-Level Mutability" model for Submitted Docs using an allow_on_submit flag. Based on compliance and auditability reviews, this proposal is formally rejected. Submitted documents in Framework M are strictly immutable.

Motivation for Rejection​

In business applications, documents are often parsed into:

  1. Ledger Data: Quantities, Rates, Items, Posting Dates. (Strictly immutable)
  2. Metadata: Transporter details, internal remarks, dispatch status. (Historically considered mutable)

The Flaw in allow_on_submit: While frameworks like Frappe support an "Allow on Submit" feature to let users change metadata without amending the document, this is fundamentally an anti-pattern. A submitted document represents an immutable, legally binding, or finalized state. Allowing post-submission mutations (even for metadata) compromises the database row as a single source of truth.

The Framework M Standard: Strict Immutability​

Framework M enforces strict immutability for all documents where docstatus == SUBMITTED. The only permitted change is a state transition to CANCELLED.

If a user needs to update information related to a submitted document, they must use one of the following compliant patterns:

1. The Amend Pattern (For Core Corrections)​

If the document itself is incorrect (e.g., wrong address, wrong item), the user must:

  1. Cancel the original document (docstatus goes to 2).
  2. Amend it (create a new draft document linked to the cancelled one).
  3. Update the data and Submit the new version.

2. The Sibling Entity Pattern (For Volatile Metadata)​

If the document requires ongoing operational updates (e.g., updating a Transporter Name or Dispatch Status on a Delivery Note), these fields should not exist on the submitted document schema.

Instead, create a separate "volatile" DocType:

class DeliveryDispatchInfo(DocType):
    delivery_note: Annotated[str, Link("DeliveryNote")]
    vehicle_no: str
    dispatch_status: str

This allows the operational data to change independently without breaking the immutability of the financial/ledger document.

3. The Timeline / Event Pattern​

If the user simply wants to add a "Remark" or note to a submitted document, this should be implemented as an append-only Comment via the TimelineMixin. This provides an auditable, timestamped log without attempting to mutate the underlying document row.

Implementation Standard​

  • The BaseController must forcibly reject any save operation on a SUBMITTED document where fields (other than docstatus) have changed by raising ImmutableDocumentError.
  • No properties like allow_on_submit will be supported in the schema.