Skip to content
LQMS
ADR-0110: The Audit Trail Is Not a Read Model
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-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-0110: The Audit Trail Is Not a Read Model
Table of contents
Context
Decision
Why (so the rule survives its author)
Consequences
Amendment 2026-08-21 — the readers, named; and the rule restated on PURPOSE, not on module
1. What is false in the text above
2. The readers, enumerated (verified against the tree, 2026-08-21)
3. What the enumeration says about the rule
4. The rule, restated
5. Enforcement — stated honestly
6. What this amendment does NOT decide
Amendment §7, 2026-08-21 (same day) — the four-eyes reader is gone; the rule got stricter, not wider
What changed in the tree
What it teaches this ADR
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="#why-so-the-rule-survives-its-author" class="md-nav__link"> <span class="md-ellipsis"> Why (so the rule survives its author) </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-21--the-readers-named-and-the-rule-restated-on-purpose-not-on-module" class="md-nav__link"> <span class="md-ellipsis"> Amendment 2026-08-21 — the readers, named; and the rule restated on PURPOSE, not on module </span> </a> <nav class="md-nav" aria-label="Amendment 2026-08-21 — the readers, named; and the rule restated on PURPOSE, not on module"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#1-what-is-false-in-the-text-above" class="md-nav__link"> <span class="md-ellipsis"> 1. What is false in the text above </span> </a> </li> <li class="md-nav__item"> <a href="#2-the-readers-enumerated-verified-against-the-tree-2026-08-21" class="md-nav__link"> <span class="md-ellipsis"> 2. The readers, enumerated (verified against the tree, 2026-08-21) </span> </a> </li> <li class="md-nav__item"> <a href="#3-what-the-enumeration-says-about-the-rule" class="md-nav__link"> <span class="md-ellipsis"> 3. What the enumeration says about the rule </span> </a> </li> <li class="md-nav__item"> <a href="#4-the-rule-restated" class="md-nav__link"> <span class="md-ellipsis"> 4. The rule, restated </span> </a> </li> <li class="md-nav__item"> <a href="#5-enforcement--stated-honestly" class="md-nav__link"> <span class="md-ellipsis"> 5. Enforcement — stated honestly </span> </a> </li> <li class="md-nav__item"> <a href="#6-what-this-amendment-does-not-decide" class="md-nav__link"> <span class="md-ellipsis"> 6. What this amendment does NOT decide </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#amendment-7-2026-08-21-same-day--the-four-eyes-reader-is-gone-the-rule-got-stricter-not-wider" class="md-nav__link"> <span class="md-ellipsis"> Amendment §7, 2026-08-21 (same day) — the four-eyes reader is gone; the rule got stricter, not wider </span> </a> <nav class="md-nav" aria-label="Amendment §7, 2026-08-21 (same day) — the four-eyes reader is gone; the rule got stricter, not wider"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#what-changed-in-the-tree" class="md-nav__link"> <span class="md-ellipsis"> What changed in the tree </span> </a> </li> <li class="md-nav__item"> <a href="#what-it-teaches-this-adr" class="md-nav__link"> <span class="md-ellipsis"> What it teaches this ADR </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-0110-audit-trail-is-not-a-read-model.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-0110-the-audit-trail-is-not-a-read-model">ADR-0110: The Audit Trail Is Not a Read Model<a class="headerlink" href="#adr-0110-the-audit-trail-is-not-a-read-model" title="Permanent link">¶</a></h1> <ul> <li><strong>Status:</strong> accepted (2026-08-09 — "ADR 0110 looks good too")</li> <li><strong>Date:</strong> 2026-08-09</li> <li><strong>Deciders:</strong> Nicolas Burri (the register-#30 redirect — "instead of going the audit trail route, wouldn't it be easier to add the information to the database?" — and, on where the rule belongs: "I would prefer it in an ADR. If it helps, we may also add it additionally as an architecture note")</li> <li><strong>Relates to:</strong> ADR-0029 (the append-only trail and its guarantee), ADR-0107 §2 (audit reach follows VIEW — the reading rule for the trail's own surfaces), ADR-0109 §4 (the emptiness oracle — the one deliberate boundary case), register 2026-08-06 #30 (the near-miss that prompted writing the rule down), V088 (its realization).</li> </ul> <h2 id="context">Context<a class="headerlink" href="#context" title="Permanent link">¶</a></h2> <p>Register #30 asked for the PDF identity block to name who released a version. The first implementation route read the answer from the audit trail at export time: the <code>RELEASED</code> event carries the actor, the caller's audit reach covers every document they may export, so the query is <em>correct</em>. It was still the wrong design, and Nicolas redirected it mid-flight: the release actor became columns on <code>document_version</code> (V088), backfilled once from the trail, written henceforth by the release acts themselves.</p> <p>The sweep that followed found the invariant had held everywhere else <em>by accident</em>: no main-source code outside the audit module selects from <code>audit_event</code>. This ADR makes the accident a rule, because the second violation is always cheaper to justify than the first — "the trail already knows" is true for nearly every lifecycle fact in the system, and each use would quietly couple business behavior to the trail's internals.</p> <h2 id="decision">Decision<a class="headerlink" href="#decision" title="Permanent link">¶</a></h2> <p><strong>The trail is written by every act and read only to be shown or counted — never to answer a business question at runtime.</strong></p> <ol> <li><strong>Evidence, not state.</strong> The audit trail records that acts happened (ADR-0029: append-only, Part 11-shaped). Domain tables carry the state those acts produced. When a surface needs a lifecycle fact — who released, who invited, when something changed hands — that fact lives on the domain row, written in the same transaction as its trail event. If a needed fact exists only in the trail, the fix is a migration that promotes it to state (the V088 shape: add the column, backfill once from the trail, dual-write from then on) — not a runtime trail read.</li> <li><strong>What may read the trail:</strong></li> <li><strong>Display surfaces</strong> that present the trail <em>as</em> the trail (Admin › Activity, per-scope activity, entity histories) — under the ADR-0107 §2 reading rule, unchanged.</li> <li><strong>Evidence exports</strong> that carry the trail itself (the validation journey's bundle, audit packs including trail extracts).</li> <li><strong>Existence counts</strong>, where the <em>fact of recording</em> is itself the domain question. Sole current case: ADR-0109 §4's emptiness oracle — an organization that ever recorded anything stays permanent. Counts only, never row content.</li> <li><strong>One-time migrations</strong> backfilling promoted facts (each names this ADR).</li> <li><strong>Tests</strong>, asserting that acts leave their evidence.</li> <li><strong>What may not:</strong> any runtime path where trail row <em>content</em> becomes input to rendering, authorization, validation, computation, or any other business behavior. No exceptions by convenience; a new legitimate category amends this ADR first.</li> </ol> <h2 id="why-so-the-rule-survives-its-author">Why (so the rule survives its author)<a class="headerlink" href="#why-so-the-rule-survives-its-author" title="Permanent link">¶</a></h2> <ul> <li><strong>Coupling:</strong> trail rows are versioned prose-and-payload evidence; their shape serves the reader of history, not the runtime. A business feature depending on event names or payload keys makes every future trail refinement a breaking change.</li> <li><strong>Reach mismatch:</strong> trail reading follows VIEW (ADR-0107 §2); domain facts follow their own authority. The #30 route happened to be safe only because export requires VIEW — the <em>next</em> use would inherit that subtlety unexamined (the #21 blind-write family shows how such assumptions rot).</li> <li><strong>Honesty both directions:</strong> state answering questions and trail evidencing acts can be <em>checked against each other</em> (as the V088 backfill did). Collapse them and the check is gone.</li> </ul> <h2 id="consequences">Consequences<a class="headerlink" href="#consequences" title="Permanent link">¶</a></h2> <ul> <li>V088 realizes the rule for the release act; its header cites this ADR.</li> <li>The conventions checklist gains the one-line rule with a pointer here (Nicolas: an architecture note <em>in addition</em> is fine) — arc42 §8's audit paragraph gets the same pointer.</li> <li>Reviewers and agent briefs treat a <code>from(AUDIT_EVENT)</code> outside the audit module, migrations, and tests as a finding by default.</li> </ul> <h2 id="amendment-2026-08-21--the-readers-named-and-the-rule-restated-on-purpose-not-on-module">Amendment 2026-08-21 — the readers, named; and the rule restated on PURPOSE, not on module<a class="headerlink" href="#amendment-2026-08-21--the-readers-named-and-the-rule-restated-on-purpose-not-on-module" title="Permanent link">¶</a></h2> <p>The 2026-08-18 review arc found this ADR factually stale, and Nicolas ruled the fix on 2026-08-21 (fix-log decision 5, option (a)): <em>"There are now FOUR readers … Amend it to name the legitimate readers and restate the rule."</em> Enumerating them found more than four — and the oldest of them is five weeks OLDER than this ADR, which the sweep that produced this ADR did not see.</p> <h3 id="1-what-is-false-in-the-text-above">1. What is false in the text above<a class="headerlink" href="#1-what-is-false-in-the-text-above" title="Permanent link">¶</a></h3> <ul> <li><strong>"Sole current case: ADR-0109 §4's emptiness oracle" (§2, third bullet).</strong> There are <strong>six</strong> runtime readers outside <code>backend/audit</code> today, plus two SQL readers and one migration (§2 below).</li> <li><strong>"A new legitimate category amends this ADR first" (§3).</strong> It has been skipped twice. <strong>ADR-0114 §7</strong> (2026-08-11) declared two readers — the dissolution tripwire's no-local-release oracle and the change inventory's act counts — in a decision that never cites this ADR. And the four-eyes read below shipped on 2026-07-05, before this ADR existed, so it was never a "new category" anyone could have been asked to declare; it was simply missed.</li> <li>The ruling's own list is already one entry out of date: <code>ImportBatchRepository.hasLocalRelease</code> no longer exists. V106 (2026-08-19) folded it into the single SQL oracle, which is what removed the third copy of that rule.</li> </ul> <h3 id="2-the-readers-enumerated-verified-against-the-tree-2026-08-21">2. The readers, enumerated (verified against the tree, 2026-08-21)<a class="headerlink" href="#2-the-readers-enumerated-verified-against-the-tree-2026-08-21" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>#</th> <th>Reader</th> <th>What it reads</th> <th>What for</th> <th>Verdict</th> </tr> </thead> <tbody> <tr> <td>1</td> <td>~~<code>WorkflowActionEvaluator.submitterUnderFourEyes</code> (document)~~</td> <td>~~the ACTOR of a version's latest <code>SUBMITTED</code> (<code>latestActorFor</code>)~~</td> <td>the four-eyes bar: the round's submitter may not approve it (ADR-0046/-0047)</td> <td><strong>RETIRED the same day — see §7.</strong> Reads <code>document_version.submitted_by</code> (V107)</td> </tr> <tr> <td>2</td> <td>~~<code>TaskService.blockedSubmitterVersions</code> (notification)~~</td> <td>~~the same, batched (<code>latestActorsFor</code>)~~</td> <td>the same predicate over a whole task page</td> <td><strong>RETIRED with 1</strong> — reads the same column, via the row the inbox already fetched</td> </tr> <tr> <td>3</td> <td><code>ImportBatchRepository.workingRecordEvidence</code> (document)</td> <td>V106's oracle (below)</td> <td>the dissolution tripwire's refusal, and the preview that must agree with it</td> <td>legitimate — enforcement oracle</td> </tr> <tr> <td>4</td> <td><code>ImportBatchRepository.actCountsSince</code> (document)</td> <td><code>action</code> + <code>entity_type</code> of the scope's rows since finalize — the ONLY <code>from(AUDIT_EVENT)</code> outside <code>backend/audit</code></td> <td>ADR-0114 §7's "these will be destroyed" inventory (staffing / configuration counts)</td> <td>legitimate — counts of acts</td> </tr> <tr> <td>5</td> <td><code>DocumentService.auditTrail</code> (document)</td> <td>the document's and its versions' rows (<code>readForEntities</code>)</td> <td>the entity-history display surface</td> <td>legitimate — §2's first bullet</td> </tr> <tr> <td>6</td> <td><code>DocumentService.listVersions</code> (document)</td> <td>the OCCURRENCE TIME of <code>REVOKED</code> (<code>actionTimesByEntity</code>)</td> <td><code>invalidSince</code> on the version-history screen</td> <td><strong>violation</strong>, declared in place: revocation has no promoted column yet and the KDoc names the V088-shaped migration as the fix</td> </tr> <tr> <td>7</td> <td><code>lqms_working_record_evidence</code> (V106 §7, SQL)</td> <td>existence of <code>RELEASED</code>; counts of five acts that leave no row of their own</td> <td>the tripwire itself — read by both dissolution functions and by the preview</td> <td>legitimate — enforcement oracle; it also <code>create or replace</code>s V095's inline copy, so this is now the only live SQL guard</td> </tr> <tr> <td>8</td> <td><code>lqms_mandator_contents</code> (V087, SQL)</td> <td><code>count(*)</code> over every table with a scope/mandator FK, <code>audit_event</code> among them</td> <td>ADR-0109 §4's emptiness oracle</td> <td>legitimate — the case §2 already named</td> </tr> <tr> <td>9</td> <td>V088's backfill (migration)</td> <td>earliest <code>RELEASED</code> per version</td> <td>the one-time promotion this ADR prescribes</td> <td>legitimate — §2's fourth bullet, and it cites this ADR</td> </tr> </tbody> </table> <p>Reader 4 carried a defect of exactly the kind an unwatched trail read invites, fixed under the same ruling: its content-entity list named <code>"COMMENT"</code> while <code>CommentService</code> has always written <code>"DOCUMENT_COMMENT"</code>, so every comment act was reported to the operator as a <em>configuration</em> act on the pre-dissolution screen. <code>ContentActClassificationTest</code> now drives real acts and compares the reading side with the writing side, because nothing did.</p> <h3 id="3-what-the-enumeration-says-about-the-rule">3. What the enumeration says about the rule<a class="headerlink" href="#3-what-the-enumeration-says-about-the-rule" title="Permanent link">¶</a></h3> <p>The Context above records that the sweep "found the invariant had held everywhere else <em>by accident</em>: no main-source code outside the audit module selects from <code>audit_event</code>." That sentence was <strong>literally true and substantively false</strong>, and the gap is the lesson: there are two ways to read the trail, and it names one. <code>from(AUDIT_EVENT)</code> is the jOOQ way — exactly one reader outside <code>backend/audit</code> uses it. The other way is to call the audit module's own repository, which four of the six did, including the one that decided <strong>who may approve a document</strong>. A rule policed by a grep for the first form is blind to the second, and stayed blind for five weeks across a review that was looking directly at it. (Both of those readers were removed hours after this was written — §7 — which does not soften the lesson: nothing FOUND them; enumerating for this amendment did.)</p> <p>So the module boundary is the wrong line. <code>backend/audit</code> is not where trail reads become dangerous — it is merely where the SQL happens to be written. What makes a read dangerous is what the answer is <em>used for</em>, and that is what the "Why" section above was always arguing.</p> <h3 id="4-the-rule-restated">4. The rule, restated<a class="headerlink" href="#4-the-rule-restated" title="Permanent link">¶</a></h3> <p><strong>The trail may be read at runtime only where an ACT is genuinely the question. A fact about a THING is never asked of the trail — it belongs on the thing's row.</strong></p> <p>Three permitted purposes, and the direction test that separates them:</p> <ol> <li><strong>Show the trail as the trail</strong> — histories, activity feeds, evidence exports. Unchanged (ADR-0107 §2 reading rule).</li> <li><strong>Ask whether an act happened</strong> — its existence, its count, its actor, its instant, for a <strong>named</strong> action. Permitted where the ACT is what the question is about (<em>"did anyone release here?"</em>, <em>"how many acts would this destruction destroy?"</em>), and subject to three conditions: the read takes only existence / count / actor / instant of a named action — <strong>never <code>changes</code> payload, never prose</strong>; the reading site cites this ADR and says in one sentence why domain state cannot answer; and where state <em>could</em> carry it, the promotion is registered as a migration rather than left implicit.</li> <li><strong>One-time migrations and tests</strong> — unchanged.</li> </ol> <p><strong>The direction test.</strong> If the answer is a property of a THING — who released <em>this version</em>, when <em>this version</em> was revoked, when <em>this document</em> took effect, <strong>who owns the review round open on this version right now</strong> — it is state, and reading it from the trail is the V088 mistake regardless of which module the query lives in. If the answer is a property of an ACT — whether any release act <em>happened</em> in this scope, how many acts a destruction would destroy — the trail is its home, and no column can carry it without duplicating the act.</p> <p><strong>The tie-breaker, learned from reader 1 (added §7, 2026-08-21).</strong> Where a question can be phrased both ways, two things decide it. First, WHAT USES THE ANSWER: if it is an authorization decision, the trail is never the source — an evidence store that returns "nothing found" hands an authorization gate a PERMIT, so every reachability concern (RLS, retention, an index regression) becomes a silent fail-open. Second, WHETHER THE ANSWER CAN EXPIRE: an act is immutable and its record is forever, so a question whose true answer STOPS BEING TRUE — as "who submitted the open round" stops the moment the round closes — is not a question about the act at all. It is a question about the thing's current state that merely happens to have an act in its history, and only the thing's row can stop answering it. That combination is what moved reader 1 from admitted to condemned within a day.</p> <p>Applied to §2, the test is not vacuous: it admits readers 3–5 and 7–9 with an argument each, and it condemns two — reader 6, which already condemns itself in its own KDoc, and reader 1 (with its sibling 2), which this amendment first admitted and §7 corrects.</p> <h3 id="5-enforcement--stated-honestly">5. Enforcement — stated honestly<a class="headerlink" href="#5-enforcement--stated-honestly" title="Permanent link">¶</a></h3> <p>Today this rule is enforced by <strong>review convention only</strong>, and the enumeration above is what review convention is worth: two declarations skipped, one authorization-grade reader unseen for five weeks, and the one gate anybody had (<code>grep from(AUDIT_EVENT)</code>) blind to the path four of six readers take. No structural gate is built by this amendment. The shape one would take is named so it is not re-invented: an architecture test that treats <strong><code>ch.lqms.audit</code> imports outside <code>backend/audit</code></strong> — not just <code>AUDIT_EVENT</code> references — as the watched set, holding an allow-list of reader sites with the purpose each was admitted under, so adding a reader means editing the list where this ADR is cited. Registered, not decided.</p> <h3 id="6-what-this-amendment-does-not-decide">6. What this amendment does NOT decide<a class="headerlink" href="#6-what-this-amendment-does-not-decide" title="Permanent link">¶</a></h3> <ul> <li>~~<strong>Whether four-eyes should stop reading the trail.</strong>~~ <strong>DECIDED — 2026-08-21, hours later, by Nicolas: <em>"I'd prefer the promotion of the submitted_by column, even if this means we need to rewrite the import."</em></strong> He also ruled the semantics: PER-ROUND — the column names the submitter of the CURRENT round, not the last submitter ever. Realized by <strong>V107</strong>; see §7. (The import needed no rewrite: the ADR-0113 arrival importer provably cannot produce an <code>IN_REVIEW</code> version, so imported versions carry a null submitter honestly.)</li> <li><strong><code>revoked_by</code>/<code>revoked_at</code></strong> (reader 6's fix), already registered as its own migration.</li> <li><strong>The structural gate</strong> (§5).</li> </ul> <p>Decider: Nicolas Burri, 2026-08-21 (fix-log decision 5, option (a): <em>"amend it to name the legitimate readers and restate the rule"</em>). Written by the amendment agent, which also reported the one place it went beyond the ruling: §4 restates the rule on purpose rather than on module boundary, which legitimized reader 1 — a runtime read that §3 as written forbids — and that widening was flagged for his confirmation, with the promotion alternative registered above.</p> <p><strong>That flag is resolved, and in the stricter direction: he took the promotion, so §4 no longer has to admit reader 1 at all.</strong> The widening still stands as the rule's shape (purpose, not module), but it now costs nothing — the one reader it was straining to accommodate no longer exists. See §7.</p> <h2 id="amendment-7-2026-08-21-same-day--the-four-eyes-reader-is-gone-the-rule-got-stricter-not-wider">Amendment §7, 2026-08-21 (same day) — the four-eyes reader is gone; the rule got stricter, not wider<a class="headerlink" href="#amendment-7-2026-08-21-same-day--the-four-eyes-reader-is-gone-the-rule-got-stricter-not-wider" title="Permanent link">¶</a></h2> <p>The amendment above was written in the morning and flagged one widening for Nicolas: §4's purpose-based restatement admitted reader 1, the four-eyes trail read, which §3 as written forbade. He answered by removing the reader instead of blessing it — <em>"I'd prefer the promotion of the submitted_by column"</em> — and ruled its semantics PER-ROUND. <strong>V107</strong> realizes that, in V088's shape.</p> <h3 id="what-changed-in-the-tree">What changed in the tree<a class="headerlink" href="#what-changed-in-the-tree" title="Permanent link">¶</a></h3> <ul> <li><code>document_version</code> gains <strong><code>submitted_by</code> / <code>submitted_at</code></strong> — the submitter of the round CURRENTLY OPEN. Written by <code>submit</code> in the transaction that opens the round; <strong>CLEARED by all four transitions that end one</strong> (reject, withdraw, release, cancel). Backfilled once from the latest <code>SUBMITTED</code> per currently-IN_REVIEW version, in <code>latestActorFor</code>'s own ordering, so the handover is behaviour- preserving for existing data.</li> <li><code>WorkflowActionEvaluator.submitterUnderFourEyes</code> (reader 1) reads that column and became <strong>pure</strong> — no <code>DSLContext</code>, no query. <code>TaskService.blockedSubmitterVersions</code> (reader 2) reads it from the row its page query already fetches. <strong>Both audit-repository calls are gone</strong>, and with them the last runtime trail read outside the audit module that fed an authorization decision.</li> <li>Readers of the trail outside <code>backend/audit</code> drop from six to four (3, 4, 5, 6). Of those, only reader 6 is still condemned, and its <code>revoked_by</code>/<code>revoked_at</code> promotion remains registered.<blockquote> <p><strong>Amendment (2026-09-06, row 63 built):</strong> the promotion landed — V131 stamps <code>revoked_by</code>/<code>revoked_at</code> as real columns (backfilled to reproduce the retired read's exact latest-wins ordering), the condemned read is deleted, and no runtime trail read outside <code>backend/audit</code> feeds an authorization or projection decision any more. The V107-era dead helpers (<code>latestActorFor</code>/<code>latestActorsFor</code>) are flagged for removal on the next touch.</p> </blockquote> </li> </ul> <h3 id="what-it-teaches-this-adr">What it teaches this ADR<a class="headerlink" href="#what-it-teaches-this-adr" title="Permanent link">¶</a></h3> <p>The morning's enumeration found the rule too narrow and widened it to fit reality. The afternoon's ruling shows the other move was available: <strong>change the reality</strong>. A rule that has to stretch to admit its most dangerous reader is telling you about the reader, not about the rule — and the cost of the promotion (one migration, two call sites, fewer queries) was smaller than the cost of the exception it replaced. Where the two are close, prefer the promotion; the trail read is the one that cannot be made safe later.</p> <p><strong>The residual is closed too</strong> (ruled the same day). The first cut of V107 left one: an <code>IN_REVIEW</code> row with a null <code>submitted_by</code> bars nobody, exactly as an unreadable <code>SUBMITTED</code> event barred nobody before — four-eyes silently switched off for that round. Nicolas ruled it closed and explicitly accepted flattening deployed systems if that was the price. It was not: V107's constraints are now a <strong>biconditional</strong> (<code>..._present_when_open</code> + <code>..._absent_unless_open</code>, two named constraints so a violation says which half it broke), the columns stay nullable because DRAFT/RELEASED/CANCELLED rows legitimately carry no stamp, and a pre-constraint guard <strong>fails the migration</strong>, naming the offending version ids, rather than skipping a row it cannot backfill or inventing a submitter for it. A version that reached review with no submit act is a defect worth seeing, and there is no honest value to invent for an authorization control.</p> <p>Every producer of <code>IN_REVIEW</code> was verified rather than assumed: <code>markInReview</code> is the state's only writer, <code>LifecycleService.submit</code> its only caller, the REST submit endpoint its only entry — and the two non-REST producers (<code>deploy/seed-demo.sh</code>'s deliberately-in-review demo SOP, <code>scripts/import/load.py</code>'s release pass) both go through that endpoint. The three test fixtures that forged <code>IN_REVIEW</code> rows now stamp them, which is the honest fix: a fixture that fakes a state should fake a state the lifecycle can actually produce. So four-eyes can no longer fail open — that is now a schema property, not a code convention.</p> <p>Decider: Nicolas Burri, 2026-08-21 (<em>"I'd prefer the promotion of the submitted_by column, even if this means we need to rewrite the import"</em>; and, on semantics, per-round). Realized by V107.</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-0109-organization-founding-is-its-own-process/" class="md-footer__link md-footer__link--prev" aria-label="Previous: ADR-0109: Organization Founding Is Its Own Process"> <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-0109: Organization Founding Is Its Own Process </div> </div> </a> <a href="../adr-0111-imported-person-model-and-project-portability/" class="md-footer__link md-footer__link--next" aria-label="Next: ADR-0111: The Imported-Person Model, and Project Portability's First Doctrines"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> ADR-0111: The Imported-Person Model, and Project Portability's First Doctrines </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>