--- id: STATE-ACC-BKS-003 title: Document template lifecycle object: DOM-ACC-BKS-004 product_area: accounting module: books revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f states: - name: built-in meaning: 'Rhythm provides protected content that may be read, previewed or copied.' - name: absent meaning: No customer template exists under the selected code. - name: active meaning: >- Customer content is available for eligible configuration selections and resolution. - name: in use meaning: >- An active template is currently selected by a unit or statement default; this is derived usage, not a separate stored status. - name: inactive meaning: >- The customer content remains stored but is excluded from eligible selection and resolution. - name: deleted meaning: The customer template row has been removed. transitions: - from: absent to: active trigger: Create active content or make a copy guard: 'Sources and parts match the kind, and the customer code is not reserved' side_effects: - >- A copy receives its own code and is active regardless of the source’s availability who: Administrator with template creation permission provenance: test source: >- services-accounting:modules/books/tests/e2e/document-templates.e2e.spec.js#copies a built-in into a new, active tenant template with the built-in’s content - from: built-in to: active trigger: Copy built-in content guard: The caller holds creation permission side_effects: - Create a separate active customer template without changing the built-in who: Template administrator provenance: test source: >- services-accounting:modules/books/tests/e2e/document-templates.e2e.spec.js#copies a built-in into a new, active tenant template with the built-in’s content - from: active to: in use trigger: Select the template guard: >- The selected customer content is active, in the workspace and of the expected kind side_effects: - Include the selecting unit or settings in the computed usage list who: Administrator with unit or settings update permission provenance: test source: >- services-accounting:modules/books/tests/e2e/document-templates.e2e.spec.js#answers 400 to a business unit naming an inactive template - from: in use to: active trigger: Release every configuration selection guard: All selecting records clear or replace their references side_effects: [] who: Configuration administrator provenance: test source: >- services-accounting:modules/books/tests/integration/services/persistence/document-templates.integration.spec.js#returns a unit to the built-in when a replacement leaves its reference out - from: active to: inactive trigger: Deactivate unused content guard: >- The current version passes update-lock checks and no unit or settings selects the content side_effects: - Explicit resolution of that inactive template is refused who: Administrator with template update permission provenance: observed source: >- services-accounting:modules/books/db/document-templates.table.ts:document_templates_reference_guard_trigger - from: inactive to: active trigger: Reactivate content guard: The version and update-lock checks succeed side_effects: [] who: Administrator with template update permission provenance: observed source: >- services-accounting:modules/books/services/persistence/document-templates.ts - from: active to: deleted trigger: Delete unused active content guard: No deletion lock or selecting unit or settings reference remains side_effects: [] who: Administrator with template deletion permission provenance: test source: >- services-accounting:modules/books/tests/e2e/document-templates.e2e.spec.js#answers 409 to deleting the business unit’s template, naming the unit - from: inactive to: deleted trigger: Delete inactive content guard: The template is not protected against deletion side_effects: [] who: Administrator with template deletion permission provenance: observed source: >- services-accounting:modules/books/services/persistence/document-templates.ts - from: absent to: inactive trigger: Create inactive content guard: The same content and reserved-code validation applies as active creation side_effects: [] who: Administrator with template creation permission provenance: observed source: >- services-accounting:modules/books/services/persistence/document-templates.ts:createDocumentTemplate invalid: - from: built-in to: deleted why: Built-ins reject both replacement and deletion. - from: in use to: inactive why: >- A selecting unit or statement default prevents deactivation and is named in the refusal. - from: in use to: deleted why: >- Configured references prevent physical removal until their choices are cleared. - from: inactive to: in use why: >- New configuration references must select active content of the matching kind. concurrency: >- Template edits use expected versions. New unit and settings references take a shared template lock in their database validation; deactivation checks references, while restricting keys protect removal. The editor keeps its loaded version across focus changes. invariants: - INV-DOM-ACC-BKS-004-01 - INV-DOM-ACC-BKS-004-04 - INV-DOM-ACC-BKS-004-05 evidence: - >- services-accounting at f47cb263: modules/books/db/document-templates.table.ts; services/persistence/document-templates.ts; services/document-templates/built-ins.ts - >- react-console at baf6dae3: components/configuration/resources/document-templates.tsx (built-ins read-only, never deactivated or deleted) --- # Document template lifecycle ## The Lifecycle ```mermaid stateDiagram-v2 state "built-in" as s0 state "absent" as s1 state "active" as s2 state "in use" as s3 state "inactive" as s4 state "deleted" as s5 s1 --> s2: Create active content or make a copy s0 --> s2: Copy built-in content s2 --> s3: Select the template s3 --> s2: Release every configuration selection s2 --> s4: Deactivate unused content s4 --> s2: Reactivate content s2 --> s5: Delete unused active content s4 --> s5: Delete inactive content s1 --> s4: Create inactive content ``` ## Transitions Explained Creation can produce active or inactive customer content. Duplication always produces a new active copy and leaves its source intact. A built-in therefore does not itself change state when copied; the arrow represents creation of the copy. Usage is derived from current selections. Clearing every reference releases the content for deactivation or deletion. Unit replacements that omit a template choice also release that reference by restoring built-in selection. ## What Cannot Happen Protected built-ins cannot be edited or removed through configuration. Customer kinds are fixed. A selected customer template must remain active and cannot be deleted. ## Concurrency and Timing Reference validation locks the selected template before accepting a new choice. Deactivation and deletion apply their database guards within the mutation transaction. Expected-version edits reject stale saves, and the console does not refresh the loaded editor on window focus.