Document Lifecycle: Draft to Approved

A Canvas memo moves through exactly three document states. Understanding them tells you when the memo is editable, when it is locked in for the record, and what unlocks exports.

draft ──▶ editing ──▶ approved
            ▲             │
            └─────────────┘
              (reopen)

State	Meaning
Draft	Freshly loaded from the analysis pipeline. No human has edited the memo yet.
Editing	A human has made at least one change. Auto-set on the first save.
Approved	An owner has approved the memo. This is the record-of-decision state and unlocks exports.

These three are the only document states. Earlier internal states named exported and generating no longer exist.

The transitions

The state machine permits exactly three transitions :

• Draft → Editing — happens automatically the first time you save the memo. You do not trigger this deliberately; touching the memo promotes it.
• Editing → Approved — happens when a deal owner approves the memo (POST /api/canvas/{deal_id}/approve). Only owners can approve.
• Approved → Editing — the reopen. A deal owner reopens an approved memo to make further changes (POST /api/canvas/{deal_id}/reopen).

That last one — reopen — is the only backward transition in the entire lifecycle. There is no Approved → Draft, no Editing → Draft, and no way to skip from Draft straight to Approved.

Note

Approve and reopen both require the owner role. Editors and commenters can change memo content, but only an owner moves the document across the approval boundary. See Roles and Permissions.

Why “Approved” is effectively terminal

Approved is the memo’s resting state. Its only outgoing transition is the backward reopen to Editing — there is no forward transition out of Approved, and no automatic transition to any later or terminal state. A memo stays Approved indefinitely.

Concretely, this means:

• Approving the memo does not archive it, lock it permanently, or move it anywhere. It marks the memo as the approved record and unlocks exports.
• If you need to change an approved memo, an owner reopens it (Approved → Editing), makes the edits, and approves again (Editing → Approved). That round-trip is the supported way to revise after approval.
• Reopening a memo releases any stale section edit locks left over from the prior editing session, so the document is clean to edit again.

PDF export is stateless

Exporting the memo to PDF is a read-only action that does not change the document state. It is not a transition, and there is no exported state to move into.

Because of this:

• You can export the memo to PDF as many times as you want while it sits in the Approved state — each export reads the current memo and renders it; nothing is consumed or “spent.”
• Re-exporting after a reopen-edit-reapprove cycle simply renders the new version.

Tip

Approval is the gate; export is the action. Approval unlocks the export surfaces — the Investor Packet (DOCX/PDF), the Canvas PDF, and OMCMS publishing — and you can re-run any of them freely while the memo remains Approved. See the approval gate, Investor Packet, and Canvas PDF.

Legacy “exported” memos

The lifecycle once included an exported state. It was removed. If you (or a long-lived session) carry an older memo whose stored state was the literal string exported, Canvas silently coerces it to approved when the session is restored . This is automatic and requires nothing from you:

• A memo that was previously “exported” is treated as Approved — which is correct, since you can only export after approving anyway.
• There is no migration step, no warning, and no data loss. The memo simply opens in the Approved state, ready to re-export or to reopen for edits.

The companion internal state generating was likewise removed from the document lifecycle. (Web-chat intake still has its own separate “generating” status while a memo is being produced — that is a different state machine and does not appear in the Canvas document lifecycle. See web chat intake.)

State and your editor mode

The document state interacts with your role to decide what you can do:

Your role	Draft / Editing	Approved
Owner / Editor	Edit directly, suggest, or view; can switch modes	View or suggest (re-edit requires an owner to reopen first)
Commenter	Suggest only	Suggest only
Viewer	View only	View only

This is why an owner who wants to directly edit an approved memo must reopen it first — in the Approved state, even owners and editors default to suggesting rather than direct editing. The full mode/role/state mapping lives in Editing and AI Suggestions.

Sources

• src/canvas/models/section_lifecycle.py — DocumentState enum (DRAFT/EDITING/APPROVED), DOCUMENT_TRANSITIONS (the three allowed transitions), is_terminal, is_editable; the docstring states PDF export is a stateless read-only action
• src/canvas/services/session_manager.py — legacy "exported" → approved coercion on session restore; APPROVED-state restore overrides section states
• src/canvas/routes/canvas_routes.py — POST .../approve (RequireOwner, editing→approved), POST .../reopen (RequireOwner, approved→editing), permission matrix
• src/canvas/services/edit_lock_service.py — release_all_locks_for_deal clears stale locks on reopen and approval
• canvas-ui/src/utils/editorModeDerivation.ts — role × document-state → available editor modes
• CLAUDE.md — document lifecycle (DRAFT→EDITING→APPROVED; EXPORTED/GENERATING removed; reopen the only backward transition; approval unlocks exports)