Skip to content
LQMS
ADR-0104: The Issued Dossier Is a Persisted Artifact of Record — and Clones to a New Draft
Initializing search
nburri/lqms
LQMS
nburri/lqms
Home
Evaluate LQMS
Evaluate LQMS
LQMS Known Limits
LQMS Security Posture
Architecture
Architecture
1. Introduction and Goals
2. Architecture Constraints
3. Context and Scope
4. Solution Strategy
5. Building Block View
6. Runtime View
7. Deployment View
8. Crosscutting Concepts
9. Architecture Decisions
10. Quality Requirements
11. Risks and Technical Debt
12. Glossary
The arrival bundle format
Decisions (ADRs)
Decisions (ADRs)
ADR-0001: Content-Addressed Document Storage with PostgreSQL as Source of Truth
ADR-0002: Single Instance with Scope Hierarchy and Copy-on-Derive
ADR-0003: Fixed Life Cycle States with Configurable Review Processes
ADR-0004: Global Catalogs for Roles and Document Types with Per-Scope Activation
ADR-0005: Modular Monolith
ADR-0006: Three-Layer Search with In-Database Index and Pluggable LLM
ADR-0007: Angular Frontend with Server-Side-Only Enforcement
ADR-0008: Flyway Migrations and jOOQ Codegen from the Migrated Schema
ADR-0009: RLS Enforcement via a Session-Scoped Authorized Scope Set
ADR-0010: Self-Managed QMS via an Internal Mandator
ADR-0011: Authentication via OIDC SSO with Server-Side (BFF) Sessions
ADR-0012: Permission-Based Authorization and System Bootstrap
ADR-0013: User Identity Lifecycle
ADR-0014: Electronic Signatures (Part 11 / Annex 11-Capable)
ADR-0015: Document Effectivity, Periodic Review & Validity
ADR-0016: Data Retention, Disposal & Privacy (FADP / GDPR)
ADR-0017: Multi-Part Version Content
ADR-0018: Non-Functional Targets (Capacity, Availability, Security)
ADR-0019: Notifications & Tasks
ADR-0020: Internationalization (Content Language, Time Zones, Formatting)
ADR-0021: General Typed Document Relationships
ADR-0022: Read-Acknowledgement & Questionnaires
ADR-0023: Migration / Import — Current Released State
ADR-0024: Draft / In-Review Cancellation
ADR-0025: Disposal & Erasure Mechanics (Storage, Index, Backups)
ADR-0026: RLS Runtime Safety — Connection-Pool Scope Isolation
ADR-0027: RLS Boundary — Content-Plane vs Control-Plane
ADR-0028: Stateless Encrypted Token-State Cookie (no server-side session store)
ADR-0029: Document Content Model — Draft-Freeze, Content-Table RLS, Append-Only Audit
ADR-0030: Review & Life-Cycle Realization Model
ADR-0031: Released-base readability enforcement & copy-on-derive mechanics
ADR-0032: Frontend realization — Quinoa, Angular Material, i18n & E2E
ADR-0033: CSRF control for the BFF session — SameSite + JSON content-type
ADR-0034: Notification realization — in-process domain events + system-context fan-out
ADR-0035: Fan-out contract as shipped — gate semantics, count disclosure, audit protocol
ADR-0036: Repository layer — services carry rules, repositories carry jOOQ
ADR-0037: Task scheduler — in-process tick, advisory-lock election, SQL sweep
ADR-0038: Periodic-review realization — derived due date, policy-gated confirmation
ADR-0039: Sweep & periodic-review contract as shipped — grants, guards, addressing
ADR-0040: Disposal-due surfacing — closure-anchored retention, scope-level legal hold
ADR-0041: Email channel & notification i18n — notification-as-outbox, structured messages
ADR-0042: Disposal execution — document tombstoning, single-actor hard-gated destruction
ADR-0043: Disposal blob deletion is post-commit, GC-backstopped
ADR-0044: Search FTS baseline — event-indexed, RLS-scoped search_index
ADR-0045: Image Attachments as Content Parts (Rich-Content Slice R2)
ADR-0046: Four-Eyes — Submitter Excluded from Approval
ADR-0047: Four-Eyes — Submitter-Only Exclusion
ADR-0048: Document Organization — Folder Tree per Scope
ADR-0049: Content Model Round 2 — Type Categories, Template Instantiation, Trace Relations, Completeness Rules
ADR-0050: Live Frontend — SSE State Push, CodeMirror 6, Draft Presence
ADR-0051: In-Text Document Links (doc: Scheme)
ADR-0052: Addressees & Read-Acknowledgement (REQ-TRN Realization)
ADR-0053: Addressees Per Document + Process Owner (amends ADR-0052 K-1)
ADR-0054: Process Owner Is a Role (amends ADR-0053 P-3)
ADR-0055: WYSIWYG Editing Mode over Markdown (editor step R4)
ADR-0056: Visual-Editor Chrome via Milkdown Crepe (gated adoption)
ADR-0057: Content Record Is the ProseMirror Document Tree; Markdown Becomes a Derived Projection
ADR-0058: PM_DOC Is the Only Content Format (pre-production cut; amends ADR-0057 §5)
ADR-0059: Editor Engine Switches to TipTap (spike-gated; supersedes the Milkdown/Crepe choice)
ADR-0060: Backup & Restore — Scripted Ordered Backup with Automated Restore Rehearsal
ADR-0061: CSV — Generated Validation Package per Release
ADR-0062: SBOM — CycloneDX over the Production Layers, Validated Against the Artifact
ADR-0063: User Identity Binds on Subject Only (Issuer Becomes Provenance)
ADR-0064: Per-Document Workflow Role Bindings (Author / Reviewer / Releaser), Enforced
ADR-0065: Diagrams — Excalidraw as the Manual Layer, Mermaid Stays for Text-First/UML
ADR-0066: WITHDRAW — the Author Side May Reclaim a Version from Review
ADR-0067: Review Comments — Anchored, Immutable, Resolvable
ADR-0068: Confluence/Jira QMS Import — Staged, Read-Only, Repeatable
ADR-0069: Arbitrary File Attachments — Download-Only Confinement
ADR-0070: Training Questionnaires — Versioned, Auto-Scored, Release-Gated
ADR-0071: Training Plans — Document Obligations + External Trainings & Certifications
ADR-0072: Diagrams — Self-Hosted draw.io Replaces Excalidraw
ADR-0073: Per-Scope QMS Configuration Surface
ADR-0074: PDF Export of Released Documents — Server-Side via Apache FOP over the Canonical Projection
ADR-0075: Source History Import — Continuity Without Forged Audit
ADR-0076: Periodic-review status visibility (completing MVP gap #2)
ADR-0077: Requirement Items — Keyed Blocks Inside Controlled Documents
ADR-0078: Generalized Trace Items (Traceability Model — Stage A)
ADR-0079: Risk & Risk-Control Items (Traceability Model — Stage B)
ADR-0080: Traceability Workspace — Hub, Sub-Pages, and Role-Gated Views
ADR-0081: Draft-Only Trace-Structure Changes, Server-Enforced
ADR-0082: Table-Shaped Risk Authoring over Risk Blocks
ADR-0083: The TD Dossier — a Versioned, Cross-Scope, Regulatory-Structured Deliverable
ADR-0084: Validation & Regulatory Axes (Traceability Model — Stage C)
ADR-0085: Relation-Layer Consolidation — One Trace Vocabulary, One Surface
ADR-0086: Requirement Traceability Chains — End-to-End Path View + Flat Path Export
ADR-0087: The Scope Traceability Report — One Derived Overview Artifact, Never a Controlled Document
ADR-0088: Verification Evidence Classes — Planned vs. Verified, Derived at the Read Layer
ADR-0089: Recurring Obligations — Periodic Tasks With Record Evidence, Not Calendar Series
ADR-0090: Release & Versioning Policy — Deliberate Releases, One Auditor-Facing Number
ADR-0091: Release Modes — Single-Person Record Release With a Structural Four-Eyes Floor
ADR-0092: Orphan-Blob Garbage Collection With a Quarantine Bin
ADR-0093: One Scope Context — the Toolbar Switcher Is the Only Scope Selector
ADR-0094: Calendar-Anchored Obligation Schedules (Clamped, Never Too Late)
ADR-0095: Key-Rule Governance — Free Until First Use, Then Frozen
ADR-0096: Transition Permissions — Always Visible, Deny Unless Granted
ADR-0097: A Governed Provisioning Surface — MANAGE_SCOPES
ADR-0098: Org Chart × Role System — Marriage at the Evidence Level, Never in Authorization
ADR-0099: The User Manual is an In-App Topic Reference, Not a Document
ADR-0100: LQMS Is the Living Quality Management System
ADR-0101: The Executable Validation Journey (PQ Evidence That Cannot Drift)
ADR-0102: Typed Template Variables (text | date | number — and Deliberately No Enum)
ADR-0103: npm audit Joins the Verification Gate as a Second Standing Input
ADR-0104: The Issued Dossier Is a Persisted Artifact of Record — and Clones to a New Draft
ADR-0104: The Issued Dossier Is a Persisted Artifact of Record — and Clones to a New Draft
Table of contents
Context
Decision
Consequences
Amendment 2026-08-05 — realized (V079), with one decision this ADR did not take
1. §2 yields to scope separation for a reader who cannot reach every pin — RATIFIED (Nicolas, 2026-08-06: "ratify as implemented")
2. Storage shape: columns on the dossier row, not a dossier_artifact table
3. Rollout: lazy backfill, with the window narrowed structurally
4. Audit shape
ADR-0105: Navigation Information Architecture — Group by Moment-of-Use
ADR-0106: The Client Reflection Follows Assignments, Not Only Content Reach
ADR-0107: The Audit Append Gate Follows Assignment Reach, Not Content Reach
ADR-0108: Mandator Membership — Invite-Accept, with Pre-Assigned Responsibilities
ADR-0109: Organization Founding Is Its Own Process
ADR-0110: The Audit Trail Is Not a Read Model
ADR-0111: The Imported-Person Model, and Project Portability's First Doctrines
ADR-0112: The Element-Kind Catalog — Semantics in the Model, Not Only in the Code
ADR-0113: Project Arrival Import — Records Arrive as They Are, People Arrive as They Were
ADR-0114: The Operating Model Arrives — Roles as Functions, Names as Words, People as This Instance's Decision
ADR-0115: Collaborative Draft Editing — Two Carets, One Truth, Honest Credit
ADR-0116: The System Maintenance Surface — the App Backs Itself Up, the Host Keeps One Dumb Job
ADR-0117: Role Documentation — a Link, a Finding, Per-Source Recognizers; Substitution Rejected
ADR-0118: The Offline QMS Copy — the Repo Carries the Audit Pack, Not a Second Renderer
ADR-0119: Module-Internal Package Structure — Capabilities First, Layers Second, the Root Is the Surface
ADR-0120: The Shared Kernel — the Domain-Exception Vocabulary Leaves the Authorization Module
ADR-0121: The Project Administrator Role — Per-Scope Administration With Read Access, Seeded in the Base Catalog
ADR-0122: Organization-Level Administration — the Cascade Stays, Becomes Visible, and Founds Projects
ADR-0123: Draft Save-Points — Every Save Restorable, Kept for the Life of the Version
ADR-0124: The Birth Path Completes Without Borrowing Content Clothes
ADR-0125: The Export Twin — Export Emits an Arrival Bundle
ADR-0126: Project Dissolution — the Un-Birth of an Unused Scope
ADR-0127: The Base-QMS Layers — One Library, Derived Adaptations, Local Records
ADR-0128: The GLOBAL Cascade Carries Administration, Never Content
ADR-0129: Role Identity from a GLOBAL Assignment Acts in GLOBAL Alone
ADR-0130: Break-Glass — the Project Administrator's Escalation Is a First-Class, Witnessed, Self-Expiring Act
ADR-0131: Role Substitution as Declared Adoption Edges — Emergency Cover Is Governed, Own-Name, Timed Staffing
ADR-0132: Dual-Hat Reviewer Satisfaction Is a Declared Policy Choice — the Strict Floor Stays the Default
ADR-NNNN:
</span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" > <div class="md-nav__link md-nav__container"> <a href="../../requirements/" class="md-nav__link "> <span class="md-ellipsis"> Requirements </span> </a> <label class="md-nav__link " for="__nav_5" id="__nav_5_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5"> <span class="md-nav__icon md-icon"></span> Requirements </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../requirements/stakeholder_requirements/" class="md-nav__link"> <span class="md-ellipsis"> Stakeholder Requirements </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/gap-analysis/" class="md-nav__link"> <span class="md-ellipsis"> Requirements Gap Analysis </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_admin/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Administration, Permissions & Onboarding </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_api_ui/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: API & User Interface </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_audit_reporting/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Audit Trail & Regulatory Reporting </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_auth/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Authentication & Session </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_backup/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Backup & Restore </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_catalogs/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Catalogs, Roles & Users </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_data_protection/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Data Protection, Retention & Disposal </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_documents/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Documents, Versions & Storage </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_dossiers/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Technical Documentation Dossiers </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_effectivity/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Effectivity, Periodic Review & Validity </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_gspr/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Regulatory Conformity (GSPR / Essential Principles) </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_i18n/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Internationalization </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_lifecycle/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Life Cycle & Reviews </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_memberships/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Mandator Membership & Invitations </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_migration/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Migration & Import </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_nfr/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Non-Functional </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_notifications/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Notifications & Tasks </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_obligations/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Recurring Obligations </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_relationships/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Document Relationships </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_risk/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Risk Management (ISO 14971 Hazards & Controls) </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_sbom/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Software Bill of Materials & Supply-Chain Assurance </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_search/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Search </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_separation/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Scopes, Mandators & Separation </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_signatures/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Electronic Signatures </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_training/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Read-Acknowledgement & Questionnaires </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_users/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: User Identity & Lifecycle </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_validation/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Design Validation & the Validation Traceability Axis </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6" > <div class="md-nav__link md-nav__container"> <a href="../../process/" class="md-nav__link "> <span class="md-ellipsis"> Process (IEC 62304) </span> </a> <label class="md-nav__link " for="__nav_6" id="__nav_6_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_6"> <span class="md-nav__icon md-icon"></span> Process (IEC 62304) </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../process/configuration_management_plan/" class="md-nav__link"> <span class="md-ellipsis"> Configuration Management Plan </span> </a> </li> <li class="md-nav__item"> <a href="../../process/problem_resolution/" class="md-nav__link"> <span class="md-ellipsis"> Problem Resolution Process </span> </a> </li> <li class="md-nav__item"> <a href="../../process/risk_management/" class="md-nav__link"> <span class="md-ellipsis"> Risk Management </span> </a> </li> <li class="md-nav__item"> <a href="../../process/software_development_plan/" class="md-nav__link"> <span class="md-ellipsis"> Software Development Plan </span> </a> </li> <li class="md-nav__item"> <a href="../../process/verification_plan/" class="md-nav__link"> <span class="md-ellipsis"> Verification Plan </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7" > <label class="md-nav__link" for="__nav_7" id="__nav_7_label" tabindex="0"> <span class="md-ellipsis"> Operations </span> <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_7"> <span class="md-nav__icon md-icon"></span> Operations </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../operations/genesis-installation/" class="md-nav__link"> <span class="md-ellipsis"> Genesis: Birthing an LQMS Installation with a Base Library </span> </a> </li> <li class="md-nav__item"> <a href="../../operations/deployment/" class="md-nav__link"> <span class="md-ellipsis"> LQMS Deployment Guide </span> </a> </li> <li class="md-nav__item"> <a href="../../operations/server-deployment/" class="md-nav__link"> <span class="md-ellipsis"> LQMS Server Deployment (single Linux host, public HTTPS) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8" > <div class="md-nav__link md-nav__container"> <a href="../../traceability/" class="md-nav__link "> <span class="md-ellipsis"> Traceability </span> </a> <label class="md-nav__link " for="__nav_8" id="__nav_8_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_8_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8"> <span class="md-nav__icon md-icon"></span> Traceability </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../traceability/matrix/" class="md-nav__link"> <span class="md-ellipsis"> Requirements Traceability Matrix </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_9" > <div class="md-nav__link md-nav__container"> <a href="../../validation/" class="md-nav__link "> <span class="md-ellipsis"> Validation (tool lane) </span> </a> <label class="md-nav__link " for="__nav_9" id="__nav_9_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_9_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_9"> <span class="md-nav__icon md-icon"></span> Validation (tool lane) </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../validation/templates/ai-authorship-posture/" class="md-nav__link"> <span class="md-ellipsis"> AI-Authorship Posture — How LQMS Is Built, and Why the Validation Evidence Does Not Rest on It (TEMPLATE) </span> </a> </li> <li class="md-nav__item"> <a href="../../validation/templates/intended-use/" class="md-nav__link"> <span class="md-ellipsis"> Intended-Use Specification — LQMS as a QMS / Document-Control Tool (TEMPLATE) </span> </a> </li> <li class="md-nav__item"> <a href="../../validation/templates/tool-risk-assessment/" class="md-nav__link"> <span class="md-ellipsis"> Tool-Risk Assessment — LQMS as a QMS Tool (TEMPLATE) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10" > <label class="md-nav__link" for="__nav_10" id="__nav_10_label" tabindex="0"> <span class="md-ellipsis"> Regulatory </span> <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_10"> <span class="md-nav__icon md-icon"></span> Regulatory </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../regulatory/mdr-annex-i-skeleton/" class="md-nav__link"> <span class="md-ellipsis"> MDR Annex I — GSPR authoring skeleton (paraphrased) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" > <div class="md-nav__link md-nav__container"> <a href="../../user-guide/" class="md-nav__link "> <span class="md-ellipsis"> User guide </span> </a> <label class="md-nav__link " for="__nav_11" id="__nav_11_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_11"> <span class="md-nav__icon md-icon"></span> User guide </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../user-guide/tutorial/" class="md-nav__link"> <span class="md-ellipsis"> Tutorial — from zero to a released document </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/administration/" class="md-nav__link"> <span class="md-ellipsis"> Administering an LQMS Installation </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/diagrams/" class="md-nav__link"> <span class="md-ellipsis"> Diagrams </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/documents-lifecycle/" class="md-nav__link"> <span class="md-ellipsis"> Documents & the Lifecycle </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/exports/" class="md-nav__link"> <span class="md-ellipsis"> PDF Exports & the Audit Pack </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/obligations/" class="md-nav__link"> <span class="md-ellipsis"> Recurring Obligations </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/project-context/" class="md-nav__link"> <span class="md-ellipsis"> The Project Context & App Version </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/review-comments/" class="md-nav__link"> <span class="md-ellipsis"> Review Comments </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/activity-trail/" class="md-nav__link"> <span class="md-ellipsis"> Who did what, when — reading a project's activity </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/admin-scopes/" class="md-nav__link"> <span class="md-ellipsis"> Renaming a project, and what can never change </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/authority-view/" class="md-nav__link"> <span class="md-ellipsis"> Who holds each function here, and what may it do </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/break-glass/" class="md-nav__link"> <span class="md-ellipsis"> The permission I need is held by a role I do not hold — what now? </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/coverage-and-chains/" class="md-nav__link"> <span class="md-ellipsis"> Coverage or chains? — which requirement view answers your question </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/credentials/" class="md-nav__link"> <span class="md-ellipsis"> Your password: changing it, resetting it — and why LQMS never sees it </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/emergency-cover/" class="md-nav__link"> <span class="md-ellipsis"> Who may cover for whom here — declaring emergency cover, and reading where the glass was broken </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/key-rules/" class="md-nav__link"> <span class="md-ellipsis"> Special elements: what a project declares, and when its names freeze </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/memberships/" class="md-nav__link"> <span class="md-ellipsis"> Belonging to an organization: invitations, acceptance, and what they change </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/provisioning-birth-path/" class="md-nav__link"> <span class="md-ellipsis"> How a new organization and project are born </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/review-policies/" class="md-nav__link"> <span class="md-ellipsis"> What a review policy controls, and what an empty grant means </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/setup-wizard-lanes/" class="md-nav__link"> <span class="md-ellipsis"> The setup wizard: the lanes, and what it writes </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/staffing-and-assignments/" class="md-nav__link"> <span class="md-ellipsis"> Staffing people into roles, and the accountable holder </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/technical-dossier/" class="md-nav__link"> <span class="md-ellipsis"> How do I assemble a technical dossier? </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/trace-items/" class="md-nav__link"> <span class="md-ellipsis"> Trace Items — Requirements, Risks & Risk Controls </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/trace-links/" class="md-nav__link"> <span class="md-ellipsis"> Trace Links & the Suspect Cycle </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/traceability-workspace/" class="md-nav__link"> <span class="md-ellipsis"> The Traceability Workspace </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/training/" class="md-nav__link"> <span class="md-ellipsis"> Training & Acknowledgements </span> </a> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#context" class="md-nav__link"> <span class="md-ellipsis"> Context </span> </a> </li> <li class="md-nav__item"> <a href="#decision" class="md-nav__link"> <span class="md-ellipsis"> Decision </span> </a> </li> <li class="md-nav__item"> <a href="#consequences" class="md-nav__link"> <span class="md-ellipsis"> Consequences </span> </a> </li> <li class="md-nav__item"> <a href="#amendment-2026-08-05--realized-v079-with-one-decision-this-adr-did-not-take" class="md-nav__link"> <span class="md-ellipsis"> Amendment 2026-08-05 — realized (V079), with one decision this ADR did not take </span> </a> <nav class="md-nav" aria-label="Amendment 2026-08-05 — realized (V079), with one decision this ADR did not take"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#1-2-yields-to-scope-separation-for-a-reader-who-cannot-reach-every-pin--ratified-nicolas-2026-08-06-ratify-as-implemented" class="md-nav__link"> <span class="md-ellipsis"> 1. §2 yields to scope separation for a reader who cannot reach every pin — RATIFIED (Nicolas, 2026-08-06: "ratify as implemented") </span> </a> </li> <li class="md-nav__item"> <a href="#2-storage-shape-columns-on-the-dossier-row-not-a-dossier_artifact-table" class="md-nav__link"> <span class="md-ellipsis"> 2. Storage shape: columns on the dossier row, not a dossier_artifact table </span> </a> </li> <li class="md-nav__item"> <a href="#3-rollout-lazy-backfill-with-the-window-narrowed-structurally" class="md-nav__link"> <span class="md-ellipsis"> 3. Rollout: lazy backfill, with the window narrowed structurally </span> </a> </li> <li class="md-nav__item"> <a href="#4-audit-shape" class="md-nav__link"> <span class="md-ellipsis"> 4. Audit shape </span> </a> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-content" data-md-component="content"> <article class="md-content__inner md-typeset"> <a href="https://github.com/nburri/lqms/edit/main/docs/decisions/adr-0104-dossier-artifact-of-record.md" title="Edit this page" class="md-content__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4zm10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1z"/></svg> </a> <h1 id="adr-0104-the-issued-dossier-is-a-persisted-artifact-of-record--and-clones-to-a-new-draft">ADR-0104: The Issued Dossier Is a Persisted Artifact of Record — and Clones to a New Draft<a class="headerlink" href="#adr-0104-the-issued-dossier-is-a-persisted-artifact-of-record--and-clones-to-a-new-draft" title="Permanent link">¶</a></h1> <ul> <li><strong>Status:</strong> accepted</li> <li><strong>Date:</strong> 2026-08-05</li> <li><strong>Deciders:</strong> Nicolas Burri ("draft ADR-0104 with option 2… ideally I would like to be able to copy the settings of an issued export to a new dossier in draft mode. So we can have both, a precise copy of the delivered file… and create a new issue if we need updated timestamps").</li> <li><strong>Relates to:</strong> ADR-0083 (the TD dossier — 3a built the DRAFT→ISSUED lifecycle and on-the-fly export this supersedes for issued dossiers; 3b's re-issue-as-new-version is realized here), ADR-0092 (blob storage + never-delete-referenced GC — the store this reuses), ADR-0074 (the one render path — used ONCE at issue instead of per download), ADR-0075 (version continuity), ADR-0088/0087 (the derived-view artifacts this deliberately is NOT).</li> </ul> <h2 id="context">Context<a class="headerlink" href="#context" title="Permanent link">¶</a></h2> <p>3a renders the issued dossier's PDF and evidence zip <strong>on the fly on every download</strong>. The content is reproducible (frozen pins over immutable released versions), but the <em>file is not byte-identical across downloads</em> — the front matter stamps a fresh "generated at" and the downloading user, so the hash changes each time. For a regulatory submission that is the wrong property: you must be able to point at <em>the</em> file delivered on a given date, with a stable fingerprint, whose immutability does not depend on re-running a renderer that may change across dependency upgrades. The dossier's own DRAFT→ISSUED lifecycle already frames the issued state as a record, not a view (unlike the deliberately-derived traceability report, ADR-0087) — persisting the artifact makes the framing true.</p> <h2 id="decision">Decision<a class="headerlink" href="#decision" title="Permanent link">¶</a></h2> <ol> <li><strong>Render once, at issue; store immutably.</strong> <code>issue()</code> renders the merged PDF <strong>and</strong> the evidence zip through the ADR-0074 path and writes both to the content store (ADR-0092 blob boundary), keyed to the dossier version, with their SHA-256 recorded on the dossier version row. These bytes are the <strong>artifact of record</strong>; their hash is the issued dossier's identity.</li> <li><strong>Download serves the stored bytes, verbatim.</strong> An issued dossier's export returns exactly the file written at issue — same bytes, same hash, forever, independent of any later renderer change. The on-the-fly path is retired for issued dossiers. <em>(Drafts: originally 409 — superseded the same day by the draft-watermark decision (register 2026-08-05 #2): a DRAFT may export the merged PDF on the fly with a prominent DRAFT watermark, no hash, an uncontrolled review aid. The invariant that matters: </em><em>watermark present ⟺ not the record</em><em>.)</em></li> <li><strong>An issued dossier is a RECORD: plain deletion is FORBIDDEN</strong> (Nicolas 2026-08-05: "I would probably not allow that"). A <code>DELETE</code> on an issued dossier is refused; draft dossiers stay freely deletable (they claim nothing). Correcting a mistaken issue is <strong>correct-forward</strong>, not deletion: clone-to-draft (decision 4), fix, re-issue as a new version — the erroneous issue remains in the trail, superseded, because erasing a record is itself an integrity failure. <strong>Deliberate follow-on, NOT this decision:</strong> governed <em>disposal</em> under retention (the ADR-0092 record-disposal path — retention period, legal hold, audited) is the only route by which an issued dossier ever leaves the system, and it is deferred until retention policy for dossiers is a real need. "Cannot be deleted" ≠ "immortal"; today it means the former.</li> <li><strong>Clone-to-draft (3b, realized).</strong> An issued dossier offers <strong>"Create a new draft from this"</strong>: its sections and pins are copied into a fresh DRAFT. Default lineage is a <strong>new version of the same dossier</strong> (same name, <code>version_number + 1</code> — the "updated submission of the same deliverable" path, ADR-0075 continuity); cloning into a differently-named new dossier is the same mechanism with a new name (the "start one like this" path). The author re-points pins to newer released versions, edits sections, and re-issues — producing that version's <strong>own</strong> immutable artifact with its own timestamp and hash. The prior issue's stored file is untouched. Result: a lineage of issued records, each a precise copy of what was delivered.</li> </ol> <h2 id="consequences">Consequences<a class="headerlink" href="#consequences" title="Permanent link">¶</a></h2> <ul> <li>Migration/rollout: any dossier already ISSUED under 3a has no stored artifact — a one-time render-and-store at migration, or a stated on-the-fly fallback for pre-0104 issues (decide at implementation; the demo stack likely has such a dossier).</li> <li>Storage: two blobs per issued version; GC-protected by the version row reference (ADR-0092's never-delete-referenced invariant); freed only when the dossier version is disposed.</li> <li>Audit: <code>DOSSIER_ISSUED</code> gains the artifact hashes; a new clone act (<code>DOSSIER_CLONED</code> / <code>DOSSIER_REVISED</code>) is audited with the source version. Export of an issued dossier records <code>EXPORTED</code> as today but over stored bytes.</li> <li>The <code>(scope, name, version_number)</code> uniqueness already admits the version lineage; no schema reshape, one migration for the artifact columns + the clone act.</li> <li>Wave sizing ≈ 1–1.5 slices (issue-time render+store, download-from-store, the disposal gate, clone-to-draft + its UI, rollout handling). Implementation queued — does NOT start with this ADR.</li> </ul> <h2 id="amendment-2026-08-05--realized-v079-with-one-decision-this-adr-did-not-take">Amendment 2026-08-05 — realized (V079), with one decision this ADR did not take<a class="headerlink" href="#amendment-2026-08-05--realized-v079-with-one-decision-this-adr-did-not-take" title="Permanent link">¶</a></h2> <p>§1, §2 and §4 are implemented (§3's delete guard shipped earlier the same day). Four points where the implementation had to decide something the decision above left open or unstated:</p> <h3 id="1-2-yields-to-scope-separation-for-a-reader-who-cannot-reach-every-pin--ratified-nicolas-2026-08-06-ratify-as-implemented">1. §2 yields to scope separation for a reader who cannot reach every pin — <strong>RATIFIED (Nicolas, 2026-08-06: "ratify as implemented")</strong><a class="headerlink" href="#1-2-yields-to-scope-separation-for-a-reader-who-cannot-reach-every-pin--ratified-nicolas-2026-08-06-ratify-as-implemented" title="Permanent link">¶</a></h3> <p>§2 promises the download returns "exactly the file written at issue — same bytes, same hash, forever". That is written as an unqualified promise, and taken literally it <strong>breaks the system's top quality goal</strong>: a dossier's pins may target versions in OTHER scopes (ADR-0083 D-7), the curator who issued it legitimately reached them, so the stored artifact CONTAINS foreign-scope content — and serving it verbatim would hand that content to any <code>VIEW</code> holder of the dossier's <em>home</em> scope, including one with no reach into the pinned scope. This ADR never discusses reach; it reasons only about hash stability. So this is a <strong>gap in the decision, not a decision to override</strong>, and it was resolved the only way the project's non-negotiable rule admits:</p> <ul> <li>A caller receives the <strong>stored artifact</strong> only when they can see <strong>every</strong> pin of the baseline (a sufficient condition for "this caller could have produced these bytes themselves").</li> <li>Anyone else receives the ADR-0083 3a <strong>on-the-fly render under their own reach</strong> — every pin still named, only the reachable ones reproduced — <strong>marked</strong> as not the record: a <code>PARTIAL COPY</code> watermark on every page, a cover notice, a <code>_partial</code> file name, a fresh date.</li> </ul> <p>This <em>strengthens</em> rather than weakens the draft-watermark invariant: <strong>watermark present ⟺ NOT the artifact of record.</strong> An unmarked issued PDF is now the one file whose SHA-256 is that dossier's identity. The residual, accepted: a caller whose reach is exactly as narrow as the issuer's gets an equivalent fresh render instead of the identical stored bytes (closing it would mean recording <em>which</em> pins the artifact reproduced, not just how many — no auditor asked for that).</p> <h3 id="2-storage-shape-columns-on-the-dossier-row-not-a-dossier_artifact-table">2. Storage shape: <strong>columns on the dossier row</strong>, not a <code>dossier_artifact</code> table<a class="headerlink" href="#2-storage-shape-columns-on-the-dossier-row-not-a-dossier_artifact-table" title="Permanent link">¶</a></h3> <p>The format set is closed (§2 names exactly two artifacts, minted by one act, in one transaction, for one dossier version), the artifact stamp belongs beside <code>issued_at</code>/<code>issued_by</code>, and the all-or-nothing constraint is expressible as a row CHECK. A child table would have modelled nothing the columns do not, at the cost of a second RLS policy and a join on the hot read path. <strong>The blob ref <em>is</em> the SHA-256</strong> — the ADR-0092 store is content-addressed, so one column per format carries both facts the ADR asks for, and carrying them separately could only ever let them disagree.</p> <p>Two columns beyond what §1 listed: <code>artifact_pins_included</code> / <code>artifact_pins_excluded</code>. Once the download serves stored bytes, the <code>EXPORTED</code> event's reproduction counts are properties of the <strong>artifact</strong> (fixed by the issuer's reach), not of the reader; re-deriving them per caller would put a number in the trail describing a copy nobody was handed.</p> <h3 id="3-rollout-lazy-backfill-with-the-window-narrowed-structurally">3. Rollout: <strong>lazy backfill</strong>, with the window narrowed structurally<a class="headerlink" href="#3-rollout-lazy-backfill-with-the-window-narrowed-structurally" title="Permanent link">¶</a></h3> <p>SQL cannot render a PDF, so a migration-time backfill was never available. The first download of a pre-0104 issue renders and stores, and the record stabilizes from then on. The honest cost — for those dossiers only, the artifact of record is what the <em>first downloader</em> rendered, not what was handed out on the issue date — is made legible rather than disguised: <code>artifact_rendered_at</code> records the backfill instant, and the trail carries a <code>DOSSIER_ARTIFACT_STORED</code> event flagged <code>backfilled</code>. The window is narrowed by a rule, not just by prose: <strong>a backfill is stored only when the render was COMPLETE</strong> (no inert pins), so a partial-reach reader can never mint a permanently-truncated record. No <code>MANAGE_DOSSIERS</code> gate on the backfill — the artifact is a pure function of frozen data, so minting it decides nothing.</p> <h3 id="4-audit-shape">4. Audit shape<a class="headerlink" href="#4-audit-shape" title="Permanent link">¶</a></h3> <p><code>DOSSIER_ISSUED</code> keeps the house lifecycle shape (<code>fromState</code>/<code>toState</code>, no <code>changes</code> body — the two are never both populated), and the artifact's identity rides on a <strong>second</strong> event, <code>DOSSIER_ARTIFACT_STORED</code>, on the same transaction. Two events because they answer different questions ("when was this baseline frozen?" / "which bytes are the record?") and because only a separate event can also carry the backfill, which happens long after the issue. <code>DOSSIER_CLONED</code> is anchored on the <strong>new</strong> dossier (a creation act, the <code>DOSSIER_CREATED</code> shape) with the source named, its version, its state and which lineage was taken. <code>EXPORTED</code> keeps its shape exactly.</p> <p>Transactional posture, as built: the state flip happens <strong>first</strong>, then the render, then the hash record — all in one transaction. Flipping first is the only order that yields a correct artifact (the cover states the issue stamp and is unwatermarked, so the bytes may only exist once the row genuinely says ISSUED), and it costs nothing because a render failure rolls the whole thing back: the dossier stays DRAFT, unstamped, unaudited. The one thing a rollback cannot undo is the content-store file write, which is by construction the ADR-0092 orphan case and is swept.</p> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type="button" class="md-top md-icon" data-md-component="top" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class="md-footer"> <nav class="md-footer__inner md-grid" aria-label="Footer" > <a href="../adr-0103-npm-audit-gate/" class="md-footer__link md-footer__link--prev" aria-label="Previous: ADR-0103: npm audit Joins the Verification Gate as a Second Standing Input"> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class="md-footer__title"> <span class="md-footer__direction"> Previous </span> <div class="md-ellipsis"> ADR-0103: npm audit Joins the Verification Gate as a Second Standing Input </div> </div> </a> <a href="../adr-0105-navigation-information-architecture/" class="md-footer__link md-footer__link--next" aria-label="Next: ADR-0105: Navigation Information Architecture — Group by Moment-of-Use"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> ADR-0105: Navigation Information Architecture — Group by Moment-of-Use </div> </div> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> <div class="md-copyright__highlight"> Built from <code>v0.9.56-4-g06c7f811</code> (commit <code>06c7f811</code>, 2026-09-09) — the same Markdown the repository ships. </div> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"base": "../..", "features": ["navigation.instant", "navigation.tracking", "navigation.top", "navigation.footer", "navigation.indexes", "toc.follow", "search.suggest", "search.highlight", "content.code.copy", "content.action.edit"], "search": "../../assets/javascripts/workers/search.6ce7567c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src="../../assets/javascripts/bundle.83f73b43.min.js"></script> </body> </html>