Skip to content
LQMS
The arrival bundle format
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
The arrival bundle format
Table of contents
Table of contents
0. What a bundle is
1. Versioning, and the change discipline
The 1.3 compatibility statement
The 1.2 compatibility statement
2. The tree
3. scope-manifest.json — scope, catalog, flags
4. manifest.json — documents and folders
5. version-chains.json — the chains
6. docs/<key>.json — the per-document sidecar
7. Bodies, trees and attachments
Bodies and trees
doc: links in a body
Attachments
8. operating-model.json
substitutionEdges[] — the declared emergency-cover matrix (1.3, ADR-0131 §2)
9. source-training.json
10. Files the reader never reads
11. Identity: keys, ids and adoption
The document key
Predicted ids (the default)
Adopted ids (idsAuthoritative: true) — Amendment 1 rule 1
12. Version kinds and the chain grammar
The chain grammar
13. What the reader refuses
14. What travels, what stays
15. The server contract this format assumes
16. Writing an exporter: the checklist
Appendix A — What the first real exporter taught the spec (2026-08-26)
Appendix B — Amendment 2 on the wire (2026-08-27)
Appendix C — Format 1.2 and what the rehearsal left standing (2026-09-05)
Appendix D — Format 1.3 and the promise ADR-0131 §2 had made (2026-09-09)
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-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="#table-of-contents" class="md-nav__link"> <span class="md-ellipsis"> Table of contents </span> </a> </li> <li class="md-nav__item"> <a href="#0-what-a-bundle-is" class="md-nav__link"> <span class="md-ellipsis"> 0. What a bundle is </span> </a> </li> <li class="md-nav__item"> <a href="#1-versioning-and-the-change-discipline" class="md-nav__link"> <span class="md-ellipsis"> 1. Versioning, and the change discipline </span> </a> <nav class="md-nav" aria-label="1. Versioning, and the change discipline"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#the-13-compatibility-statement" class="md-nav__link"> <span class="md-ellipsis"> The 1.3 compatibility statement </span> </a> </li> <li class="md-nav__item"> <a href="#the-12-compatibility-statement" class="md-nav__link"> <span class="md-ellipsis"> The 1.2 compatibility statement </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#2-the-tree" class="md-nav__link"> <span class="md-ellipsis"> 2. The tree </span> </a> </li> <li class="md-nav__item"> <a href="#3-scope-manifestjson--scope-catalog-flags" class="md-nav__link"> <span class="md-ellipsis"> 3. scope-manifest.json — scope, catalog, flags </span> </a> </li> <li class="md-nav__item"> <a href="#4-manifestjson--documents-and-folders" class="md-nav__link"> <span class="md-ellipsis"> 4. manifest.json — documents and folders </span> </a> </li> <li class="md-nav__item"> <a href="#5-version-chainsjson--the-chains" class="md-nav__link"> <span class="md-ellipsis"> 5. version-chains.json — the chains </span> </a> </li> <li class="md-nav__item"> <a href="#6-docsjson--the-per-document-sidecar" class="md-nav__link"> <span class="md-ellipsis"> 6. docs/<key>.json — the per-document sidecar </span> </a> </li> <li class="md-nav__item"> <a href="#7-bodies-trees-and-attachments" class="md-nav__link"> <span class="md-ellipsis"> 7. Bodies, trees and attachments </span> </a> <nav class="md-nav" aria-label="7. Bodies, trees and attachments"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#bodies-and-trees" class="md-nav__link"> <span class="md-ellipsis"> Bodies and trees </span> </a> </li> <li class="md-nav__item"> <a href="#doc-links-in-a-body" class="md-nav__link"> <span class="md-ellipsis"> doc: links in a body </span> </a> </li> <li class="md-nav__item"> <a href="#attachments" class="md-nav__link"> <span class="md-ellipsis"> Attachments </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#8-operating-modeljson" class="md-nav__link"> <span class="md-ellipsis"> 8. operating-model.json </span> </a> <nav class="md-nav" aria-label="8. operating-model.json"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#substitutionedges--the-declared-emergency-cover-matrix-13-adr-0131-2" class="md-nav__link"> <span class="md-ellipsis"> substitutionEdges[] — the declared emergency-cover matrix (1.3, ADR-0131 §2) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#9-source-trainingjson" class="md-nav__link"> <span class="md-ellipsis"> 9. source-training.json </span> </a> </li> <li class="md-nav__item"> <a href="#10-files-the-reader-never-reads" class="md-nav__link"> <span class="md-ellipsis"> 10. Files the reader never reads </span> </a> </li> <li class="md-nav__item"> <a href="#11-identity-keys-ids-and-adoption" class="md-nav__link"> <span class="md-ellipsis"> 11. Identity: keys, ids and adoption </span> </a> <nav class="md-nav" aria-label="11. Identity: keys, ids and adoption"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#the-document-key" class="md-nav__link"> <span class="md-ellipsis"> The document key </span> </a> </li> <li class="md-nav__item"> <a href="#predicted-ids-the-default" class="md-nav__link"> <span class="md-ellipsis"> Predicted ids (the default) </span> </a> </li> <li class="md-nav__item"> <a href="#adopted-ids-idsauthoritative-true--amendment-1-rule-1" class="md-nav__link"> <span class="md-ellipsis"> Adopted ids (idsAuthoritative: true) — Amendment 1 rule 1 </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#12-version-kinds-and-the-chain-grammar" class="md-nav__link"> <span class="md-ellipsis"> 12. Version kinds and the chain grammar </span> </a> <nav class="md-nav" aria-label="12. Version kinds and the chain grammar"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#the-chain-grammar" class="md-nav__link"> <span class="md-ellipsis"> The chain grammar </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#13-what-the-reader-refuses" class="md-nav__link"> <span class="md-ellipsis"> 13. What the reader refuses </span> </a> </li> <li class="md-nav__item"> <a href="#14-what-travels-what-stays" class="md-nav__link"> <span class="md-ellipsis"> 14. What travels, what stays </span> </a> </li> <li class="md-nav__item"> <a href="#15-the-server-contract-this-format-assumes" class="md-nav__link"> <span class="md-ellipsis"> 15. The server contract this format assumes </span> </a> </li> <li class="md-nav__item"> <a href="#16-writing-an-exporter-the-checklist" class="md-nav__link"> <span class="md-ellipsis"> 16. Writing an exporter: the checklist </span> </a> </li> <li class="md-nav__item"> <a href="#appendix-a--what-the-first-real-exporter-taught-the-spec-2026-08-26" class="md-nav__link"> <span class="md-ellipsis"> Appendix A — What the first real exporter taught the spec (2026-08-26) </span> </a> </li> <li class="md-nav__item"> <a href="#appendix-b--amendment-2-on-the-wire-2026-08-27" class="md-nav__link"> <span class="md-ellipsis"> Appendix B — Amendment 2 on the wire (2026-08-27) </span> </a> </li> <li class="md-nav__item"> <a href="#appendix-c--format-12-and-what-the-rehearsal-left-standing-2026-09-05" class="md-nav__link"> <span class="md-ellipsis"> Appendix C — Format 1.2 and what the rehearsal left standing (2026-09-05) </span> </a> </li> <li class="md-nav__item"> <a href="#appendix-d--format-13-and-the-promise-adr-0131-2-had-made-2026-09-09" class="md-nav__link"> <span class="md-ellipsis"> Appendix D — Format 1.3 and the promise ADR-0131 §2 had made (2026-09-09) </span> </a> </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/architecture/arrival-bundle-format.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="the-arrival-bundle-format">The arrival bundle format<a class="headerlink" href="#the-arrival-bundle-format" title="Permanent link">¶</a></h1> <p><strong>Status:</strong> PUBLISHED INTERFACE (ADR-0125). This is the structure <code>scripts/import/load_arrival.py</code> consumes and the structure an LQMS export emits — one format, both directions. Everything below is written from the reader's own code and is pinned by <code>scripts/import/test_arrival_bundle_format.py</code> and <code>scripts/import/test_load_arrival.py</code>.</p> <ul> <li><strong>Format version:</strong> <code>1.3</code> (<code>load_arrival.FORMAT_VERSION</code>)</li> <li><strong>Spec:</strong> ADR-0125 (the export twin; §2 the declared dependency manifest, §3 the fidelity line, §5 identity, <strong>Amendment 1</strong> rows 31/32/33, <strong>Amendment 4</strong> rows 52/53/55), ADR-0113 (the arrival import this format feeds, and its head-only floor), ADR-0114 (the operating model that travels), ADR-0131 §2 (the substitution matrix that travels with it — register row 76), ADR-0075 §3 (the claims record), ADR-0111 (external persons), ADR-0088 (the verification-evidence classification), ADR-0040 D3 / ADR-0038 (the two type-level clocks)</li> <li><strong>The wire this format is loaded through:</strong> <code>docs/planning/arrival-import-wire.md</code></li> <li><strong>The gap audit that produced it:</strong> <code>docs/planning/export-format-gap-audit.md</code></li> </ul> <hr /> <h2 id="table-of-contents">Table of contents<a class="headerlink" href="#table-of-contents" title="Permanent link">¶</a></h2> <ol> <li><a href="#0-what-a-bundle-is">What a bundle is</a></li> <li><a href="#1-versioning-and-the-change-discipline">Versioning, and the change discipline</a></li> <li><a href="#2-the-tree">The tree</a></li> <li><a href="#3-scope-manifestjson--scope-catalog-flags"><code>scope-manifest.json</code> — scope, catalog, flags</a></li> <li><a href="#4-manifestjson--documents-and-folders"><code>manifest.json</code> — documents and folders</a></li> <li><a href="#5-version-chainsjson--the-chains"><code>version-chains.json</code> — the chains</a></li> <li><a href="#6-docskeyjson--the-per-document-sidecar"><code>docs/<key>.json</code> — the per-document sidecar</a></li> <li><a href="#7-bodies-trees-and-attachments">Bodies, trees and attachments</a></li> <li><a href="#8-operating-modeljson"><code>operating-model.json</code></a></li> <li><a href="#9-source-trainingjson"><code>source-training.json</code></a></li> <li><a href="#10-files-the-reader-never-reads">Files the reader never reads</a></li> <li><a href="#11-identity-keys-ids-and-adoption">Identity: keys, ids and adoption</a></li> <li><a href="#12-version-kinds-and-the-chain-grammar">Version kinds and the chain grammar</a></li> <li><a href="#13-what-the-reader-refuses">What the reader refuses</a></li> <li><a href="#14-what-travels-what-stays">What travels, what stays</a></li> <li><a href="#15-the-server-contract-this-format-assumes">The server contract this format assumes</a></li> <li><a href="#16-writing-an-exporter-the-checklist">Writing an exporter: the checklist</a></li> </ol> <hr /> <h2 id="0-what-a-bundle-is">0. What a bundle is<a class="headerlink" href="#0-what-a-bundle-is" title="Permanent link">¶</a></h2> <p>A <strong>bundle</strong> is a directory holding one project scope's corpus: its documents, every version of each that travels, the folders they sit in, their attachments, the catalog rows they need, and the operating model that lets somebody continue working on them. It is read by <code>load_arrival.py</code>, which speaks only the governed <code>/api/admin/import</code> surface — no SQL, no workflow driving, no personas.</p> <p>Two lineages produce bundles and both are first class:</p> <ul> <li>a <strong>source-system bundle</strong>, written by the Confluence transform in <code>scripts/import/</code>. It carries no <code>scope-manifest.json</code>; everything not in the directory comes from <code>scripts/import/sources.py</code>. This is the LEGACY shape and it is read byte-for-byte as it always was.</li> <li>an <strong>LQMS-origin bundle</strong>, written by the ADR-0125 exporter. It carries a <code>scope-manifest.json</code>, which makes it self-describing: no repository, no <code>SourceConfig</code>, no Confluence directory.</li> </ul> <p>The difference is one file. Everything else in this document applies to both.</p> <h2 id="1-versioning-and-the-change-discipline">1. Versioning, and the change discipline<a class="headerlink" href="#1-versioning-and-the-change-discipline" title="Permanent link">¶</a></h2> <p><code>scope-manifest.json.formatVersion</code> is <code><major>.<minor></code>.</p> <table> <thead> <tr> <th>Step</th> <th>Means</th> <th>The reader does</th> </tr> </thead> <tbody> <tr> <td><strong>MAJOR</strong></td> <td>a field this reader knows now means something else</td> <td><strong>REFUSES.</strong> Reading it anyway would land a corpus that looks plausible and says the wrong thing.</td> </tr> <tr> <td><strong>MINOR</strong></td> <td>ADDITIVE only — new optional fields, new permitted values of an existing one</td> <td>reads it. A <strong>forward</strong> minor logs a warning and IGNORES what it does not know.</td> </tr> </tbody> </table> <p>That asymmetry is what lets an exporter add a field without stranding every installed loader, and it is why a minor step may never change the meaning of an existing field or make an optional one required. A bundle with no <code>scope-manifest.json</code> declares no version and is read as legacy.</p> <p>ADR-0125 promotes this format to a published interface: <strong>a format change now needs the same care as an API change.</strong> In practice — bump the minor, state the new field here with its behaviour-when-absent, pin it with a test, and keep the reader able to read every 1.x bundle.</p> <p>Version history:</p> <table> <thead> <tr> <th>Version</th> <th>Change</th> </tr> </thead> <tbody> <tr> <td>1.0</td> <td>the format as the arrival import consumed it, plus <code>scope-manifest.json</code> (ADR-0125 §2 / gap G-1), the optional <code>snapshot/</code> (G-2) and the <code>titleRule</code> (G-4)</td> </tr> <tr> <td><strong>1.1</strong></td> <td><code>REVOKED</code> as a version kind (Amendment 1 rule 2) and <code>versions[].treeJson</code> (rule 3) — the ONE step those two rulings land as</td> </tr> <tr> <td><strong>1.2</strong></td> <td><code>documentTypes[].verificationEvidence</code>, <code>.retentionPeriodDays</code> and <code>.reviewIntervalDays</code> (Amendment 4, register rows 52/53) — the three GLOBAL catalog properties a corpus's <em>meaning</em> depends on and a 1.1 bundle had no slot for</td> </tr> <tr> <td><strong>1.3</strong></td> <td><code>operating-model.json.substitutionEdges[]</code> (ADR-0131 §2, register row <strong>76</strong>) — the declared emergency-cover matrix, the one operating-model member that had never travelled</td> </tr> </tbody> </table> <h3 id="the-13-compatibility-statement">The 1.3 compatibility statement<a class="headerlink" href="#the-13-compatibility-statement" title="Permanent link">¶</a></h3> <p><strong>A 1.3 reader accepts every 1.2 bundle, unchanged.</strong> The new field is ONE optional array on <code>operating-model.json</code>, and no existing field's meaning moves — the MINOR rule above, applied literally. Absent means exactly what a 1.2 bundle's silence always meant: <strong>this corpus declares no emergency cover.</strong> It never means cover that could not be read, because before 1.3 there was no slot to lose it from. A 1.2 <em>reader</em> meeting a 1.3 bundle behaves as §1's table says — it warns and ignores what it does not know — so the matrix stays behind exactly as it did before this step, which is the pre-1.3 behaviour and therefore no worse than before.</p> <p><strong>Why it needed a format step</strong> (register row 76). ADR-0131 §2 put the matrix in the operating model and said in as many words that it <em>"travels in the arrival bundle with the rest of it (format extension at build time), beside role mapping and review policies"</em>. The format extension was never built, so the matrix was the operating-model member that did NOT travel — and it did not travel <strong>silently</strong>: a customer landing an operating model received roles, review policies and per-document bindings, no emergency cover, and nothing in the bundle, the preview or the run report that said so. The ADR's own argument — that an organization's paper substitution rules become declared, exported, auditable system configuration — rests on the travel, so the gap made the ADR untrue rather than incomplete.</p> <p><strong>Mandatory on write, like 1.2's classification.</strong> An LQMS export states <code>substitutionEdges</code> on every bundle, <code>[]</code> included: <em>"this corpus declares no emergency cover"</em> is a claim the bundle makes, not a silence the reader has to guess at.</p> <h3 id="the-12-compatibility-statement">The 1.2 compatibility statement<a class="headerlink" href="#the-12-compatibility-statement" title="Permanent link">¶</a></h3> <p><strong>A 1.2 reader accepts every 1.1 bundle, unchanged.</strong> The three new fields are <strong>optional on read</strong> — absent means exactly what a 1.1 bundle's silence always meant, that the target's own catalog governs — and <strong>mandatory on write</strong>: an LQMS export states <code>verificationEvidence</code> on every type row (<code>false</code> is a claim the bundle makes, not a silence the reader has to guess at) and states each clock the catalog actually holds. A 1.1 <em>reader</em> meeting a 1.2 bundle behaves as §1's table says: it warns and ignores what it does not know, which is the pre-1.2 behaviour and therefore no worse than before — the loss is the one this step exists to close, so a target should be upgraded before a corpus whose classification matters is landed on it.</p> <p><strong>Why these three needed a format step at all</strong> (the row-37 rehearsal, <code>docs/planning/row-37-rehearsal-local.md</code> D1 and D2). <code>document_type.verification_evidence</code> (ADR-0088) decides whether an inbound <code>verifies</code> claim reads <em>verified</em> or merely <em>planned</em>. A rehearsal corpus whose Verification Reports were classified as evidence in the source landed in the target with the flag off: <code>GET /scopes/{id}/requirement-chains</code> answered <code>total=2, satisfied=1, fullyVerified=0</code> with <code>VERIFICATION_PLANNED_ONLY</code> where the source answered <code>fullyVerified=1</code> — over a corpus that was <strong>bit-identical</strong>, with the landing reporting zero refusals and the operator's count diff coming out clean. <code>retention_period</code> (ADR-0040 D3) disappeared the same way, dropping a records obligation silently. The corpus was right and the conclusion drawn from it was wrong, which is the one failure mode a portability format may not have.</p> <h2 id="2-the-tree">2. The tree<a class="headerlink" href="#2-the-tree" title="Permanent link">¶</a></h2> <pre class="mermaid"><code>flowchart TD R["bundle root/"] --> SM["scope-manifest.json<br/>scope · catalog · flags"] R --> M["manifest.json<br/>documents · folders"] R --> VC["version-chains.json<br/>per document: the versions that travel"] R --> D["docs/"] R --> A["attachments/"] R --> OM["operating-model.json<br/><i>optional</i>"] D --> DJ["<key>.json<br/>per-document sidecar"] D --> MD["<key>.v<N>.md<br/>the version body"] D --> TJ["<key>.v<N>.tree.json<br/><i>optional — the native tree</i>"] A --> AK["<key>/<file><br/>attachment binaries"] SM -. "absent ⇒ legacy bundle,<br/>read from sources.py" .-> M</code></pre> <p>Required at the root: <code>manifest.json</code>, <code>version-chains.json</code>, <code>docs/</code>. Everything else is optional, and every "when absent" below is measured behaviour, not intent.</p> <p>The legacy layout additionally has a sibling <code>snapshot/</code> directory (<code>snapshot/pages.json</code>, <code>snapshot/attachments/<key>/</code>). <strong>It is optional as of 1.0.</strong> A bundle written to this format needs none of it: <code>pages.json</code> is read when present and contributes nothing a well-formed <code>manifest.json</code> does not already carry, and attachments have their own home at the root.</p> <h2 id="3-scope-manifestjson--scope-catalog-flags">3. <code>scope-manifest.json</code> — scope, catalog, flags<a class="headerlink" href="#3-scope-manifestjson--scope-catalog-flags" title="Permanent link">¶</a></h2> <p>The ADR-0125 §2 <strong>declared dependency manifest</strong>. Present ⇒ it is the AUTHORITY for everything that is not per-document. Absent ⇒ the legacy path reads all of it from <code>sources.py::SourceConfig</code>. Never a merge of the two: a half-declared bundle would land a corpus named partly after itself and partly after the importing repository's vocabulary.</p> <table> <thead> <tr> <th>Field</th> <th>Required</th> <th>Meaning / when absent</th> </tr> </thead> <tbody> <tr> <td><code>formatVersion</code></td> <td><strong>yes</strong></td> <td><code><major>.<minor></code> — see §1. Missing or unparseable ⇒ refusal.</td> </tr> <tr> <td><code>scope.code</code></td> <td><strong>yes</strong></td> <td>the scope code the corpus lands under, and the head of every human id. Also the default for <code>--scope-code</code>.</td> </tr> <tr> <td><code>scope.name</code></td> <td>no</td> <td>the scope's display name. Absent ⇒ the source config's.</td> </tr> <tr> <td><code>scope.type</code></td> <td>no</td> <td><code>PROJECT</code> | <code>GLOBAL</code>. Absent ⇒ the source config's.</td> </tr> <tr> <td><code>scope.mayBeDeriveSource</code></td> <td>no</td> <td>ADR-0074 derive-source flag. Absent ⇒ the source config's.</td> </tr> <tr> <td><code>scope.mayHoldRecords</code></td> <td>no</td> <td>declared; sent on the target payload only when present (server contract, §15).</td> </tr> <tr> <td><code>scope.mandatorName</code></td> <td>no</td> <td>the organization the corpus belongs to, for the operator's check against <code>--mandator-id</code>. Sent on the target payload only when present.</td> </tr> <tr> <td><code>idsAuthoritative</code></td> <td>no (default <code>false</code>)</td> <td><strong>row 31.</strong> <code>true</code> ⇒ the bundle's document keys ARE the ids; they are adopted, not predicted. See §11.</td> </tr> <tr> <td><code>titleRule</code></td> <td>no</td> <td><code>verbatim</code> | <code>source-de-prefix</code>. <strong>Default when a manifest is present: <code>verbatim</code>.</strong> See §4.</td> </tr> <tr> <td><code>lossStatement</code></td> <td><strong>yes when <code>idsAuthoritative</code></strong></td> <td>ADR-0125 §3's sentence, in Markdown, <strong>in bold</strong>. See §14.</td> </tr> <tr> <td><code>sourceSystem</code></td> <td>no</td> <td>the ADR-0111 origin key every EXTERNAL person of this bundle is minted under. Absent ⇒ <code>--source-system</code>, else the installation's configured default.</td> </tr> <tr> <td><code>originLabel</code></td> <td>no</td> <td>the free label naming this concrete snapshot; rides into every <code>DOCUMENT_IMPORTED</code> payload. Absent ⇒ the legacy <code>Confluence space <key>, snapshot <date></code>.</td> </tr> <tr> <td><code>sourceKeyPrefix</code></td> <td>no (default <code>confluence</code>)</td> <td>the prefix of the ADR-0113 D6 replay key: <code><prefix>:<document key></code>. An LQMS export sets e.g. <code>lqms:<instance-id></code> — that is what makes a re-export distinguishable from a Confluence arrival.</td> </tr> <tr> <td><code>documentTypes[]</code></td> <td><strong>yes when present</strong></td> <td>the catalog rows this corpus needs. See below.</td> </tr> <tr> <td><code>elementKinds[]</code></td> <td>no</td> <td><code>{slug, families:[{label, prefix}]}</code>. Absent ⇒ <strong>derived</strong> from the union of the types' <code>mayDefine</code>, with the key families computed from the corpus's own <code>requirementItems</code> (register #49c).</td> </tr> <tr> <td><code>roles[]</code></td> <td>no</td> <td><code>{name, description}</code> — the role VOCABULARY. Merged into the operating model's roles: a role the manifest names and no policy uses arrives with no functions (which is honest, and keeps an addressee-only role from being dropped). Never overwrites a role's <code>functions</code>.</td> </tr> <tr> <td><code>generator</code>, <code>generatedAt</code></td> <td>no</td> <td>provenance for a human reader; never read.</td> </tr> </tbody> </table> <p><code>documentTypes[]</code> rows:</p> <table> <thead> <tr> <th>Field</th> <th>Required</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td><code>code</code></td> <td><strong>yes</strong> (or <code>prefix</code>)</td> <td>the token <code>manifest.json</code>'s <code>documents[].docType</code> uses</td> </tr> <tr> <td><code>prefix</code></td> <td><strong>yes</strong></td> <td>the human-id type prefix (<code>SOP</code> in <code>MERIDIAN-QMS-SOP-001</code>)</td> </tr> <tr> <td><code>name</code></td> <td>no</td> <td>the catalog row's display name. Absent ⇒ <code>code</code>.</td> </tr> <tr> <td><code>category</code></td> <td>no</td> <td><code>PRESCRIPTIVE</code> | <code>RECORD</code> | … — the target's adopt-or-create input</td> </tr> <tr> <td><code>description</code></td> <td>no</td> <td>absent ⇒ no <code>description</code> on the wire (the field is nullable)</td> </tr> <tr> <td><code>mayDefine[]</code></td> <td>no</td> <td>the element kinds documents of this type may DEFINE. <strong>Load-bearing:</strong> the trace registries walk the frozen content of defining types only, so a corpus whose requirements arrive under a type that may not define them lands its prose and no requirements at all.</td> </tr> <tr> <td><code>verificationEvidence</code></td> <td>no (<strong>1.2</strong>)</td> <td>ADR-0088: does a RELEASED document of this type count as VERIFICATION EVIDENCE? Absent ⇒ the target's own value (the column default <code>false</code> on a type this import creates). An LQMS export always states it.</td> </tr> <tr> <td><code>retentionPeriodDays</code></td> <td>no (<strong>1.2</strong>)</td> <td>ADR-0040 D3: the type-level records-retention period, in whole days. Absent ⇒ the target's own (none, on a created type).</td> </tr> <tr> <td><code>reviewIntervalDays</code></td> <td>no (<strong>1.2</strong>)</td> <td>ADR-0038: the type-level periodic-review interval, in whole days. Absent ⇒ the target's own.</td> </tr> </tbody> </table> <p>A <code>docType</code> no row declares is a <strong>refusal</strong> naming the type and listing the declared ones. (Before 1.0 it was a bare <code>KeyError</code> on a Python dict.)</p> <p><strong>The three 1.2 fields are GLOBAL, and that governs what the target does with them</strong> (§15 item 4). <code>verification_evidence</code>, <code>retention_period</code> and <code>review_interval</code> are columns on the installation-wide <code>document_type</code> row — one value for every tenant — not on the per-scope activation. So the rule is <strong>create applies, adopt reports</strong>: a type this import MINTS takes the declaration (through the surfaces that already govern those columns, each audited as itself); a type the catalog ALREADY carries keeps the target's values and the difference is REPORTED — at preview, in the vocabulary outcome and on the operator's terminal. An arriving corpus may not silently re-decide what counts as verified for every tenant of the receiving installation; it may also not drop the difference on the floor.</p> <h2 id="4-manifestjson--documents-and-folders">4. <code>manifest.json</code> — documents and folders<a class="headerlink" href="#4-manifestjson--documents-and-folders" title="Permanent link">¶</a></h2> <table> <thead> <tr> <th>Field</th> <th>Required</th> <th>When absent</th> </tr> </thead> <tbody> <tr> <td><code>documents[]</code></td> <td><strong>yes</strong></td> <td><code>KeyError</code></td> </tr> <tr> <td><code>documents[].pageId</code></td> <td><strong>yes</strong></td> <td>the corpus-wide <strong>document key</strong> (§11). The name is a historical Confluence-ism; the value is any stable unique string.</td> </tr> <tr> <td><code>documents[].title</code></td> <td><strong>yes</strong></td> <td>the document's title, read under <code>titleRule</code></td> </tr> <tr> <td><code>documents[].docType</code></td> <td><strong>yes</strong></td> <td>a <code>code</code> of the declared catalog (§3)</td> </tr> <tr> <td><code>documents[].ancestors[]</code></td> <td>no</td> <td>the document lands at the scope root</td> </tr> <tr> <td><code>documents[].isContainer</code></td> <td>no</td> <td>treated as a leaf; <code>true</code> makes the document a folder for its children too (never its own parent)</td> </tr> <tr> <td><code>folders[]</code></td> <td><strong>yes</strong> (may be <code>[]</code>)</td> <td><code>KeyError</code></td> </tr> <tr> <td><code>folders[].pageId</code>, <code>.title</code></td> <td><strong>yes</strong> if any folder row exists</td> <td><code>KeyError</code></td> </tr> <tr> <td><code>transformed_at</code></td> <td>no</td> <td>only used to date the legacy <code>originLabel</code></td> </tr> <tr> <td><code>counts</code>, <code>folders[].ancestors</code>, <code>folders[].position</code>, <code>documents[].state</code>, <code>documents[].ticketKey</code></td> <td>—</td> <td><strong>never read.</strong> Folder ORDERING does not travel.</td> </tr> </tbody> </table> <p><strong><code>counts</code> is written for the OPERATOR, and its honesty counters say what could not be carried.</strong> The reader ignores the whole block; an auditor does not, and the numbers a migration is diffed against come from here. Beside <code>documents</code> / <code>versions</code> / <code>attachments</code> / <code>folders</code>, an LQMS export writes three loss counters (register row 53 corrected the first and added the other two):</p> <table> <thead> <tr> <th>Counter</th> <th>Counts</th> </tr> </thead> <tbody> <tr> <td><code>crossScopeReferencesNotCarried</code></td> <td>trace links whose target is <strong>outside this scope</strong> — by <code>target_scope_id</code>, <em>or</em> by naming a target DOCUMENT that is not one of this scope's. The second disjunct is the row-53 fix: <code>target_scope_id</code> is NULL for a document-target link even when the target lives elsewhere, so the counter used to answer <code>0</code> while dropping one (the rehearsal's D3).</td> </tr> <tr> <td><code>documentTargetReferencesNotCarried</code></td> <td>in-scope links whose target is a DOCUMENT rather than a requirement KEY — no slot (Appendix A item 8).</td> </tr> <tr> <td><code>documentRelationsNotCarried</code></td> <td>ADR-0021/ADR-0049 document RELATIONS the bundle carries nowhere (the rehearsal's D4). A MANUAL edge is always counted; a <code>from_text</code> edge is counted only when its target is outside the scope, because an in-scope one is re-derived by the far side's own freeze — counting it would over-state the loss as badly as the old cross-scope counter under-stated it.</td> </tr> </tbody> </table> <p><code>attachments</code> here counts <strong>distinct FILES</strong>; <code>load_arrival</code>'s run report counts <strong>upload ACTS</strong>, so a file pinned to two versions is 1 in the manifest and 2 in the report. Both are right; the rehearsal's D6 was that neither was labelled. Both are now.</p> <p><strong><code>titleRule</code>.</strong> <code>source-de-prefix</code> (the legacy default) drops a redundant <code><AREA>-<TYPE>-</code> head and replaces every hyphen with a space. That is a Confluence-ism, and it is unconditional: it rewrites <code>Post-Market Surveillance</code> → <code>Post Market Surveillance</code> and <code>Risk-Benefit Analysis</code> → <code>Risk Benefit Analysis</code>. <code>verbatim</code> — what a manifest-bearing bundle declares by default — carries the title exactly as the bundle spells it, which is what makes export→import idempotent on the one field a human reads first (gap G-4).</p> <p>Titles are the fallback idempotency key, so they must be unique across the corpus. Under <code>source-de-prefix</code>, a de-prefixing collision makes both documents keep their ORIGINAL titles.</p> <h2 id="5-version-chainsjson--the-chains">5. <code>version-chains.json</code> — the chains<a class="headerlink" href="#5-version-chainsjson--the-chains" title="Permanent link">¶</a></h2> <p><code>{"chains": {"<document key>": {"versions": [...]}}}</code>. Every document in <code>manifest.json</code> needs a chain, and every chain at least one arriving version — both are refusals otherwise.</p> <table> <thead> <tr> <th>Field</th> <th>Required</th> <th>When absent</th> </tr> </thead> <tbody> <tr> <td><code>versions[].kind</code></td> <td><strong>yes for an <code>idsAuthoritative</code> bundle</strong>; optional otherwise</td> <td>absent ⇒ silently <code>DRAFT</code> on a legacy bundle (gap G-8's second silent acceptance) and a <strong>refusal</strong> on an authoritative one. See §12.</td> </tr> <tr> <td><code>versions[].body</code></td> <td><strong>yes</strong></td> <td><code>KeyError</code> — a path RELATIVE TO THE BUNDLE ROOT</td> </tr> <tr> <td><code>versions[].treeJson</code></td> <td>no</td> <td><strong>1.1.</strong> A path, relative to the bundle root, to the native ProseMirror tree. Present ⇒ posted as it stands. Absent ⇒ the tree is derived from the markdown. See §7.</td> </tr> <tr> <td><code>versions[].version</code></td> <td>no</td> <td>the server numbers the chain 1, 2, 3 …</td> </tr> <tr> <td><code>versions[].at</code></td> <td>no</td> <td>the release stamp falls back to <code>evidence.approvedAt</code> only</td> </tr> <tr> <td><code>versions[].by</code></td> <td>no</td> <td>the version is authored by the OPERATOR — never by anyone invented</td> </tr> <tr> <td><code>versions[].evidence.approvedAt</code></td> <td>no</td> <td>falls back to <code>versions[].at</code></td> </tr> <tr> <td><code>versions[].evidence.approvedBy</code> | <code>approverName</code> | <code>releasedBy</code></td> <td>no</td> <td>the releaser becomes the source-system placeholder <code><origin>@<origin>.invalid</code> — visibly synthetic, structurally unmailable</td> </tr> <tr> <td><code>versions[].evidence.grade</code></td> <td>no</td> <td>preview cosmetics; not on the seal wire</td> </tr> <tr> <td><code>versions[].evidence.draftCause</code></td> <td>no</td> <td>the value <code>automatic-conversion</code> <strong>SKIPS</strong> the version (ADR-0113 Amendment 1: the Atlassian macro migration's own edit is machine noise, not a draft anybody wrote). An LQMS export must never emit it.</td> </tr> <tr> <td><code>versions[].caveats[]</code></td> <td>no</td> <td><code>[]</code>. An LQMS export's is empty: attachments ARE version-pinned here.</td> </tr> <tr> <td><code>versions[].imageRefs</code> / <code>attachmentLinks</code> / <code>diagramSources</code> / <code>diagramNodes</code></td> <td>no</td> <td>falls back to the same keys on <code>docs/<key>.json</code>, then to none. See §7.</td> </tr> <tr> <td><code>versions[].role</code>, <code>isCurrentBody</code>, <code>sourceTitle</code>, <code>requirementKeys</code>; <code>chains[k].title</code> / <code>docType</code> / <code>outcomes</code>; top-level <code>stats</code></td> <td>—</td> <td><strong>never read</strong></td> </tr> </tbody> </table> <p><code>evidence.approvedBy</code> may be a string or <code>{name, email}</code>. A recorded human approver is used whenever the evidence carries one; nothing else is ever promoted into that role — saving a version and releasing it are different acts, and the format keeps them apart.</p> <h2 id="6-docsjson--the-per-document-sidecar">6. <code>docs/<key>.json</code> — the per-document sidecar<a class="headerlink" href="#6-docsjson--the-per-document-sidecar" title="Permanent link">¶</a></h2> <p>The FILE is required for every document. <strong>Every field in it is optional</strong> (<code>{}</code> is accepted).</p> <table> <thead> <tr> <th>Field</th> <th>Becomes</th> </tr> </thead> <tbody> <tr> <td><code>sourceUrl</code></td> <td>the <code>source</code> of each claims-record entry; the document's provenance link</td> </tr> <tr> <td><code>sourceHistory[]</code></td> <td>the ADR-0075 §3 claims record, prepended to the chain-derived entries. <code>{version, at, by, action, kind, source}</code>. <strong>It may carry version and release FACTS, never ACTS BY PERSONS</strong> — see §14.</td> </tr> <tr> <td><code>changeSummary</code></td> <td><code>changeDescription</code> on the first version</td> </tr> <tr> <td><code>roles {author, reviewer, releaser}</code></td> <td>the ADR-0114 D5 per-document workflow binding, in SOURCE role names</td> </tr> <tr> <td><code>addresseeRoles[]</code></td> <td>the acknowledgement audience. <code>[]</code> is a CLAIM ("nobody is addressed"); absent is a SILENCE (the type policy's pre-fill stands)</td> </tr> <tr> <td><code>trainingMode</code></td> <td>the per-document ADR-0070 §3 override</td> </tr> <tr> <td><code>trainingRelevant</code></td> <td>rides the <strong>last RELEASED</strong> version only — never a REVOKED one, which is not a release anybody must be trained on</td> </tr> <tr> <td><code>requirementItems[] {key, kind, category}</code></td> <td>the element-kind KEY FAMILIES (register #49c). Never travels as a document field — a category is derived from the key wherever it is read.</td> </tr> <tr> <td><code>requirementLinks[] {type, sourceRequirementKey, targetRequirementKey, provenance}</code></td> <td>typed trace claims (ADR-0085)</td> </tr> <tr> <td><code>imageRefs</code> / <code>attachmentLinks</code> / <code>diagramSources</code> / <code>diagramNodes</code></td> <td>the per-version attachment fallback</td> </tr> <tr> <td><code>allInternal</code></td> <td>carried; unused downstream in this client</td> </tr> <tr> <td><code>pageId</code>, <code>title</code>, <code>docType</code>, <code>state</code>, <code>reviewDue</code>, <code>statusName</code>, <code>position</code>, <code>sourceVersion</code>, <code>ticketKey</code>, <code>releasedVersion</code>, <code>nextReview</code>, <code>purpose</code>, <code>scope</code>, <code>pageLinks</code>, <code>drawio</code>, <code>isContainer</code></td> <td><strong>never read</strong></td> </tr> </tbody> </table> <h2 id="7-bodies-trees-and-attachments">7. Bodies, trees and attachments<a class="headerlink" href="#7-bodies-trees-and-attachments" title="Permanent link">¶</a></h2> <h3 id="bodies-and-trees">Bodies and trees<a class="headerlink" href="#bodies-and-trees" title="Permanent link">¶</a></h3> <p>Every version has a <strong>markdown body</strong> at <code>versions[].body</code>. It may additionally carry its <strong>native tree</strong> at <code>versions[].treeJson</code>.</p> <p><strong>Precedence is per version:</strong></p> <table> <thead> <tr> <th>The version carries</th> <th>The loader posts</th> <th><code>deploy/md-to-tree.mjs</code></th> </tr> </thead> <tbody> <tr> <td><code>treeJson</code></td> <td>the tree file's bytes, verbatim, with the <code>.md</code> as its <code>projection</code></td> <td>not run for that version</td> </tr> <tr> <td>no <code>treeJson</code></td> <td>a tree derived from the markdown</td> <td>run (one batched call for the whole corpus)</td> </tr> </tbody> </table> <p>A bundle may mix the two; a bundle that carries every tree never starts node at all. This is Amendment 1 rule 3: <strong>the native tree is the record, markdown is the human-readable projection and the fallback for foreign bundles.</strong> It removes the node-coverage dependency from the import path entirely — nothing about fidelity then rests on what the markdown projection happens to express, now or for any future node type.</p> <p>Two rules keep a carried tree honest, and both are refusals:</p> <ul> <li>a stated <code>treeJson</code> that is missing or unparseable is <strong>refused</strong>, never silently replaced by the derived tree — the version named its tree as the record;</li> <li>a version that carries a tree AND markdown the <code>doc:PAGE-<n></code> / <code>doc:XPAGE-<n></code> rewriter would CHANGE is <strong>refused</strong>: rewriting the markdown without rewriting the tree would freeze a version whose record and whose readable body cite different documents. A bundle carrying trees carries ids, not markers.</li> </ul> <p>The ADR-0072 image→diagram swap is a repair of the DERIVED tree only. A native tree already has its <code>diagram</code> nodes and is never subjected to it.</p> <h3 id="doc-links-in-a-body"><code>doc:</code> links in a body<a class="headerlink" href="#doc-links-in-a-body" title="Permanent link">¶</a></h3> <p><code>doc:PAGE-<n></code> is rewritten to the arriving document's id; <code>doc:XPAGE-<n></code> to the other space's, via <code>--xpage-map</code>. Both regexes are digit-anchored, so <code>doc:<HUMAN-ID></code> passes through untouched — an exported body needs no rewriting and gets none.</p> <p>A <code>doc:</code> reference to a document in ANOTHER scope is, today, inert text on arrival: it degrades with no count and no record. That is gap G-10 and it is explicitly out of this format's 1.x scope (ADR-0125 §6, sequenced after the single-scope round trip).</p> <h3 id="attachments">Attachments<a class="headerlink" href="#attachments" title="Permanent link">¶</a></h3> <p>Binaries live at <strong><code>attachments/<document key>/<filename></code></strong>, relative to the bundle root. The legacy <code>snapshot/attachments/<document key>/</code> is the fallback and is used whenever the root <code>attachments/</code> directory does not exist.</p> <p>Which files a version uploads is <code>imageRefs</code> + <code>attachmentLinks</code> + <code>diagramSources</code> + <code>diagramNodes[].srcFile</code>, read from the VERSION first and from <code>docs/<key>.json</code> as a fallback, in that order, deduplicated.</p> <p>A referenced file with <strong>no bytes on disk</strong>:</p> <ul> <li>on a legacy bundle it is DROPPED, silently — the right answer for a Confluence snapshot, where a page may cite an attachment the fetch could not retrieve and the corpus is still the best record available;</li> <li>on an <code>idsAuthoritative</code> bundle it is a <strong>refusal</strong> naming the file (gap G-8): the exporter wrote both the reference and the store, so a missing binary means the bundle is corrupt, not sloppy, and importing anyway would freeze a body citing content that will never arrive.</li> </ul> <p>Attachments land BEFORE the seal — the frozen-tree discipline: the version manifest must pin them.</p> <h2 id="8-operating-modeljson">8. <code>operating-model.json</code><a class="headerlink" href="#8-operating-modeljson" title="Permanent link">¶</a></h2> <p>Optional. Absent ⇒ the ADR-0114 flow is skipped and the project arrives with no roles and no review policies (loudly logged). Consumed:</p> <ul> <li><code>roles[] {name, description, functions[] {docType, slots[]}}</code></li> <li><code>policies[] {docType, authors, reviewers, reviewerMinCount, releasers, revise, revoke, cancel, addressees, fourEyes, releaseMode, typePrefix, typeName, documentCount}</code></li> <li><code>unconfiguredTypes[] {docType, documentCount, reason}</code></li> <li><code>substitutionEdges[] {sourceRole, targetRole}</code> — <strong>1.3</strong></li> </ul> <p>Never read: <code>generated_at</code>, <code>source</code>, <code>scopeCode</code>, <code>trainingBindings</code>, <code>counts</code>.</p> <p>The model is NARROWED to the types this run actually imports, then extended by <code>scope-manifest.json</code>'s <code>roles[]</code> (§3). Every source role must be resolved by the operator through the two-step mapping flow (<code>proposed-role-mapping.json</code> → <code>--mapping</code>) before a single document arrives.</p> <h3 id="substitutionedges--the-declared-emergency-cover-matrix-13-adr-0131-2"><code>substitutionEdges[]</code> — the declared emergency-cover matrix (1.3, ADR-0131 §2)<a class="headerlink" href="#substitutionedges--the-declared-emergency-cover-matrix-13-adr-0131-2" title="Permanent link">¶</a></h3> <p><em>"In this project, a holder of <code>sourceRole</code> may take over <code>targetRole</code> in an emergency."</em> Governance configuration of the same rank as a review policy, and the same three rules apply to it as to everything else in this file:</p> <ul> <li><strong>Roles are named, never identified by id.</strong> Both ends are SOURCE ROLE NAMES, resolved through the confirmed mapping exactly as a policy's slot lists are — the mapping table is keyed by that same name, and a role UUID would name the exporting installation's catalog. No field of this format carries one.</li> <li><strong>The edge's ends JOIN the set the operator must confirm.</strong> A name reaching the model only through an edge is still a role of the model, so the operating-model act refuses while it is undecided (<em>"nobody has decided what 'X' becomes here"</em>). Nothing about a role is adopted silently — ADR-0114 §2, through a new door.</li> <li><strong>The DECLARATION ACT does not travel.</strong> <code>substitution_edge</code> records who judged the source's holders competent and when; those are acts the source instance witnessed, and §14 keeps them there. The receiving operator declares each edge in their own name, through the same audited act the UI performs — which is ADR-0131 §2 taken literally: <em>the declaration act IS the qualification statement</em>, and a judgment can only be made by whoever makes it.</li> </ul> <p>Behaviour when absent: no emergency cover is declared (see §1's 1.3 compatibility statement). An LQMS export always states the array, <code>[]</code> included.</p> <p>Two landing outcomes are REPORTED rather than raised, because both are the operator's own confirmed mapping talking back and the only remedy is to re-map: an edge whose two ends <strong>collapse onto one instance role</strong> (many-to-one mapping is the normal case — see §8's mapping flow), and an edge whose target resolves onto an <strong>ADMINISTRATIVE-class role of the receiving installation</strong>, which ADR-0131 §3 refuses structurally. The run prints each with the refusing surface's own sentence; the corpus lands. An edge <strong>grants nothing by itself</strong> — it authorizes a future timed, witnessed, self-expiring act — so a project that lands one edge short is visibly incomplete and one governance act from complete, which is not the class of loss that justifies refusing a corpus.</p> <h2 id="9-source-trainingjson">9. <code>source-training.json</code><a class="headerlink" href="#9-source-trainingjson" title="Permanent link">¶</a></h2> <p>Optional. <code>{"documents": {"<key>": {"completions": [...]}}, "stats": …, "unmatchedDocuments": …, "persons": …}</code>. An entry that exists without <code>completions</code> is a <code>KeyError</code>.</p> <p><strong>An LQMS-origin bundle must contain none, and one that does is refused.</strong> This is the single slot in the format that would smuggle an ADR-0125 §3 "stays" item: <code>completions</code> are training ACTS — who acknowledged which document, and when — and the obvious server-side fill for them on export is the acknowledgement table. §3 puts acknowledgements on the side that stays. A legacy Confluence bundle's claims record is exactly what ADR-0075 §3 built the slot for and travels unchanged.</p> <h2 id="10-files-the-reader-never-reads">10. Files the reader never reads<a class="headerlink" href="#10-files-the-reader-never-reads" title="Permanent link">¶</a></h2> <p><code>conversion-report.json</code>, <code>diagrams/</code>, and <code>pageid-map.json</code> (except when explicitly named by <code>--xpage-map</code>). They may be present; they change nothing.</p> <p><code>deploy/md-to-tree.mjs</code> plus the webui <code>node_modules</code> are needed by the READER (not the format) wherever any version arrives without a <code>treeJson</code>.</p> <h2 id="11-identity-keys-ids-and-adoption">11. Identity: keys, ids and adoption<a class="headerlink" href="#11-identity-keys-ids-and-adoption" title="Permanent link">¶</a></h2> <h3 id="the-document-key">The document key<a class="headerlink" href="#the-document-key" title="Permanent link">¶</a></h3> <p><code>manifest.documents[].pageId</code> is the corpus-wide key. It names the chain in <code>version-chains.json</code>, the sidecar <code>docs/<key>.json</code>, the body files <code>docs/<key>.v<N>.md</code>, and the attachment directory <code>attachments/<key>/</code>. Nothing parses it as a number. A human id works unmodified in all four places.</p> <h3 id="predicted-ids-the-default">Predicted ids (the default)<a class="headerlink" href="#predicted-ids-the-default" title="Permanent link">¶</a></h3> <p>An ordinary source-system bundle's ids are <strong>minted by the target</strong> from its own per-(scope, type) counter. The loader PREDICTS them — <code><SCOPE>-<PREFIX>-<nnn></code> from a dense sequence — because a body's <code>doc:</code> links must be rewritten to real ids BEFORE the version is created and the arrival surface has no re-save. Prediction is a claim, so every create answer is verified against it and a miss is reported loudly (it cannot be repaired: a frozen version's bytes land once).</p> <h3 id="adopted-ids-idsauthoritative-true--amendment-1-rule-1">Adopted ids (<code>idsAuthoritative: true</code>) — Amendment 1 rule 1<a class="headerlink" href="#adopted-ids-idsauthoritative-true--amendment-1-rule-1" title="Permanent link">¶</a></h3> <p>The bundle's keys ARE the corpus's names. The loader stops predicting entirely and asks the target to adopt each id verbatim. Three things are checked before a single call is made:</p> <ol> <li><strong>the target code.</strong> Every human id embeds its scope code, so a bundle of <code>MERIDIAN-QMS-*</code> ids refuses to land in a scope called anything else. The refusal names both codes and the remedy (<code>--scope-code MERIDIAN-QMS</code>). Adoption REQUIRES the target to adopt the source's code.</li> <li><strong>the shape of every key</strong>, which must be <code><scope code>-<type prefix>-<designator></code> for the type the document claims. A key that is not an id cannot be adopted.</li> <li><strong>the bundle is LQMS-origin</strong>: it carries the bold loss statement (§14) and no <code>source-training.json</code> (§9).</li> </ol> <p>Why this matters more than it looks: a source scope with ANY gap in its numbering — one disposed or cancelled document is enough — comes back RENUMBERED under prediction, and from the first gap onward every frozen body carries the wrong <code>doc:</code> targets. Adoption has no sequence to be wrong about.</p> <p><strong>The adopted id is also the REPLAY KEY</strong>, and that has a consequence for what a bundle may contain. An ordinary bundle is replayed against <code>(document type, title)</code> — the only key a client whose ids the target mints can offer on a first run — so two documents of one type under one title collapse into one there, by construction. An authoritative bundle is replayed against the id it names, so it may carry as many same-titled documents of a type as the corpus really has (review minutes, test reports, supplier assessments): each lands under its own name and each resumes as itself. The other half of the same rule: <strong>one id may be named by exactly one document.</strong> Two documents claiming one id is a defective export — refused at preview, and refused again at the second document if the preview was skipped.</p> <h2 id="12-version-kinds-and-the-chain-grammar">12. Version kinds and the chain grammar<a class="headerlink" href="#12-version-kinds-and-the-chain-grammar" title="Permanent link">¶</a></h2> <p><code>versions[].kind</code> is one of:</p> <table> <thead> <tr> <th>Kind</th> <th>Sealed?</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td><code>RELEASED</code></td> <td>yes</td> <td>released in the source, carrying its source release date and releaser</td> </tr> <tr> <td><code>REVOKED</code></td> <td>yes</td> <td><strong>1.1.</strong> Released in the source and later withdrawn there. The resulting STATE is corpus truth; the revocation ACT stays at the source.</td> </tr> <tr> <td><code>DRAFT</code></td> <td>no</td> <td>an open draft — the version arrives by NOT being sealed</td> </tr> </tbody> </table> <p>Two source states deliberately have no kind, and an exporter maps them:</p> <ul> <li><strong><code>IN_REVIEW</code> → <code>DRAFT</code>.</strong> The review round is an act in progress: it stays where it is happening, and the target restarts its own review. (The submitter, the round, the approvals are all working-record layer — §14.)</li> <li><strong><code>CANCELLED</code> → skipped</strong>, on the machine-noise precedent: a cancelled version is not a state of the corpus anybody needs on the far side.</li> </ul> <h3 id="the-chain-grammar">The chain grammar<a class="headerlink" href="#the-chain-grammar" title="Permanent link">¶</a></h3> <pre class="mermaid"><code>flowchart LR V1["v1 RELEASED<br/><i>sealed</i>"] --> V2["v2 REVOKED<br/><i>sealed</i>"] --> V3["v3 DRAFT<br/><i>unsealed</i>"] V3 -. "no successor is possible:<br/>an append behind an unsealed<br/>version is refused" .-> END(("end of<br/>the chain"))</code></pre> <p>Each version is created UNSEALED, receives its attachments, and is then sealed in the state the source had it in — <code>RELEASED</code>, <code>REVOKED</code>, or left as the <code>DRAFT</code> it is.</p> <p>A version may only be APPENDED behind a <strong>sealed</strong> predecessor. That is not a rule this format adds; it is the document model's own "one non-terminal version" invariant, and it is what makes ADR-0113 D3's <em>"a DRAFT only as the LAST version of a chain"</em> structural rather than declarative. <code>RELEASED</code> and <code>REVOKED</code> are both sealed, so both are legal predecessors — which is what makes <code>v1 RELEASED, v2 REVOKED, v3 DRAFT</code> expressible at all. (The gap audit found that chain unrepresentable; that is what Amendment 1 rule 2 fixed.)</p> <p>Version numbers are honoured when stated and must strictly increase. A source chain legitimately runs 9 → 11 → 14: the gaps are versions the source could not prove, and they stay in the claims record rather than being invented.</p> <p>A REVOKED version seals with the SAME release provenance a RELEASED one does, because it WAS released. What never travels is the revocation act — no revoker, no revocation date, no reason.</p> <h2 id="13-what-the-reader-refuses">13. What the reader refuses<a class="headerlink" href="#13-what-the-reader-refuses" title="Permanent link">¶</a></h2> <p>Every refusal is in the <strong>V107 grammar</strong>: the delta NAMED, why continuing would be worse than stopping, and a remedy the operator can actually perform.</p> <table> <thead> <tr> <th>Refusal</th> <th>Applies to</th> </tr> </thead> <tbody> <tr> <td><code>formatVersion</code> unparseable, or of another MAJOR</td> <td>any manifest-bearing bundle</td> </tr> <tr> <td><code>titleRule</code> this reader does not know</td> <td>any manifest-bearing bundle</td> </tr> <tr> <td>a <code>docType</code> no catalog row declares</td> <td>all</td> </tr> <tr> <td>a document with no chain, or a chain with no arriving version</td> <td>all</td> </tr> <tr> <td>a stated <code>treeJson</code> that is missing or unparseable</td> <td>all</td> </tr> <tr> <td>a carried tree beside markdown the <code>doc:</code> rewriter would change</td> <td>all</td> </tr> <tr> <td>a version with no usable <code>kind</code></td> <td><code>idsAuthoritative</code> only</td> </tr> <tr> <td>a referenced attachment with no bytes</td> <td><code>idsAuthoritative</code> only</td> </tr> <tr> <td>no bold <code>lossStatement</code></td> <td><code>idsAuthoritative</code> only</td> </tr> <tr> <td>a <code>source-training.json</code> is present</td> <td><code>idsAuthoritative</code> only</td> </tr> <tr> <td>the target scope code differs from the bundle's</td> <td><code>idsAuthoritative</code> only</td> </tr> <tr> <td>a document key that is not a well-formed id</td> <td><code>idsAuthoritative</code> only</td> </tr> <tr> <td>the target adopted a DIFFERENT id than the one asked for (collision, or a target too old to know the field)</td> <td><code>idsAuthoritative</code> only</td> </tr> <tr> <td>an adopted document is already here in a state this bundle cannot complete</td> <td>all (the resume gate)</td> </tr> </tbody> </table> <p>The pattern is deliberate: <strong>a legacy bundle's ambiguity is tolerated, an LQMS-origin bundle's is not.</strong> A Confluence snapshot is the best record available of a system nobody controls. An export is written by software that knows the answer, so a gap in it is a defect in the exporter, and finding it at import time — loudly — is the cheapest place to find it.</p> <h2 id="14-what-travels-what-stays">14. What travels, what stays<a class="headerlink" href="#14-what-travels-what-stays" title="Permanent link">¶</a></h2> <p><strong>ADR-0125 §3, and it is the sentence a recipient most needs:</strong></p> <blockquote> <p><strong>A migration LOSES the working-record layer by design.</strong> The audit trail, acknowledgements, approvals, comments, periodic reviews, tasks and save-points do not travel; the source instance (or its final backup) remains the archive of record for them.</p> </blockquote> <table> <thead> <tr> <th>Travels</th> <th>Stays</th> </tr> </thead> <tbody> <tr> <td>all versions per the arrival floor</td> <td>the audit trail (ADR-0075: the target must never claim acts it did not witness)</td> </tr> <tr> <td>folders (not their ordering)</td> <td>acknowledgements</td> </tr> <tr> <td>attachments</td> <td>approvals and review rounds</td> </tr> <tr> <td>trace links (in-scope)</td> <td>comments</td> </tr> <tr> <td>releaser + release-date provenance</td> <td>periodic reviews</td> </tr> <tr> <td>the operating model (roles, policies, bindings)</td> <td>tasks</td> </tr> <tr> <td>the source's own claims record (<code>sourceHistory</code>)</td> <td>save-points</td> </tr> <tr> <td>the types' GLOBAL catalog properties — classification + the two clocks (<strong>1.2</strong>), applied on create and reported on adopt</td> <td>document RELATIONS (counted, §4)</td> </tr> <tr> <td>the declared substitution matrix — which role may cover which (<strong>1.3</strong>, ADR-0131 §2)</td> <td><strong>who declared an edge, and when</strong> — the qualification judgment is re-made by the receiving operator as their own audited act</td> </tr> </tbody> </table> <p>An <code>idsAuthoritative</code> bundle <strong>must carry that statement in <code>scope-manifest.json.lossStatement</code>, in bold</strong>, and the loader reads it out to the operator before the preview. A bundle without it is refused. ADR-0125's own words: <em>never in fine print</em> — and a statement that only ever lives inside a JSON file nobody opened is fine print with extra steps.</p> <p>None of the "stays" column has a field anywhere in this format. That silence is a structural guarantee, not an accident — with the one exception §9 fences off.</p> <p><code>sourceHistory</code> is the boundary worth stating twice: it is the legitimate carrier of release provenance, and it is also exactly the shape audit rows would fit into. The line is that it may carry <strong>what state a version reached and when</strong>, never <strong>who approved, commented or acknowledged</strong>.</p> <h2 id="15-the-server-contract-this-format-assumes">15. The server contract this format assumes<a class="headerlink" href="#15-the-server-contract-this-format-assumes" title="Permanent link">¶</a></h2> <p><code>load_arrival.py</code> speaks <code>/api/admin/import</code> (<code>docs/planning/arrival-import-wire.md</code>). Format 1.1 needed three things from that surface, and 1.2 a fourth. Each is pinned as executable contract in <code>FakeArrival</code> (<code>scripts/import/test_load_arrival.py</code>) as well as in the server's own tests.</p> <p><strong>1. Id adoption (row 31).</strong></p> <ul> <li><code>POST /api/admin/import/batches</code> accepts <code>idsAuthoritative: true</code> on the target payload. It is a property of the BATCH, permitted only on an import-born scope.</li> <li><code>POST …/batches/{id}/documents</code> accepts <code>adoptHumanId</code> — the id to adopt verbatim. It is a SEPARATE field from <code>humanId</code>, which keeps its ADR-0113 D6 replay-key meaning ("never a request to mint a particular id"); overloading it would make an adoption request and a replay key indistinguishable on the wire.</li> <li><code>adoptHumanId</code> on a batch that did not declare <code>idsAuthoritative</code> → <strong>400</strong>.</li> <li>No <code>adoptHumanId</code> in an authoritative batch → <strong>400</strong>.</li> <li>An <code>adoptHumanId</code> the scope already holds → <strong>409</strong> (the collision the ADR says refuses loudly).</li> <li>After an adoption the per-(scope, type) counter is <strong>seeded past</strong> the adopted number, so the next minted id continues after the highest adopted one.</li> <li>On such a batch <code>adoptHumanId</code> is ALSO the D6 replay key, and the <code>(type, title)</code> fallback does not apply: a re-sent document resumes the document that carries that id, and a document naming an id the scope does not hold is created however it is titled. Two documents of one type under one title are two documents when they name two ids.</li> <li>The DRY RUN sees the field too — <code>POST …/preview</code> accepts <code>adoptHumanId</code> per document and refuses, before anything is written, a document of an authoritative bundle that names no id and an id named by more than one document. Both are refusals of the act as well; the preview is where they are cheap, because documents land one committed row at a time.</li> </ul> <p><strong>2. <code>REVOKED</code> as a seal state (row 32).</strong></p> <ul> <li><code>POST …/versions/{id}/seal</code> accepts <code>{"state": "REVOKED", "sourceReleasedAt": …, "sourceReleaser": …}</code> and lands the version in state <code>REVOKED</code>, carrying the same release stamps a <code>RELEASED</code> seal carries. No revoker, no revocation date, no event claiming this instance withdrew anything.</li> <li><code>REVOKED</code> is sealed: it seals once, refuses a second seal, refuses attachments.</li> <li><code>appendVersion</code> accepts a <code>REVOKED</code> predecessor exactly as it accepts a <code>RELEASED</code> one. Today it refuses anything that is not <code>RELEASED</code>; the honest condition is <em>not unsealed</em>.</li> </ul> <p><strong>3. Native trees (row 33).</strong> Nothing new on the wire — <code>treeJson</code> is already the create/append payload's field. What changes is that the client may send the bundle's OWN tree rather than one it derived, so the tree the format carries must be accepted and validated exactly as a derived one is.</p> <p><strong>4. The three GLOBAL catalog properties (register rows 52/53, format 1.2).</strong></p> <ul> <li><code>POST …/batches/{id}/vocabulary</code> accepts <code>verificationEvidence</code>, <code>retentionPeriodDays</code> and <code>reviewIntervalDays</code> on each <code>documentTypes[]</code> row.</li> <li>On a type this call <strong>CREATES</strong>, the declaration is APPLIED — through the surfaces that already own those columns (<code>VERIFICATION_EVIDENCE_SET</code> and <code>DOCUMENT_TYPE_DEFAULTS_UPDATED</code>, both MANAGE_CATALOG at GLOBAL, the same gate the type creation just passed), so each sub-act audits as itself (ADR-0113 D5) and no new authority is asked for. <code>verificationEvidence: false</code> on a created type writes nothing: <code>false</code> is the column default, and a write with no change is not a change (ADR-0095).</li> <li>On a type it <strong>ADOPTS</strong>, nothing is written and every difference is REPORTED, as <code>documentTypes[].catalogDivergences[]</code> in the 200 body — one sentence per differing property, naming what the bundle declared, what this installation holds, and which one governs.</li> <li><code>POST /api/admin/import/preview</code> answers the same difference in the <code>DOCUMENT_TYPE</code> proposal item's <code>detail</code> map, so the operator reads it BEFORE the one-shot window closes rather than inferring it from a coverage matrix weeks later.</li> <li>An absent field declares nothing: neither applied nor reported.</li> </ul> <p><strong>5. The substitution matrix (register row 76, format 1.3).</strong></p> <ul> <li><code>POST …/batches/{id}/operating-model</code> accepts <code>substitutionEdges[] {sourceRole, targetRole}</code> beside <code>roles[]</code> and <code>policies[]</code>. Both ends are resolved through the CONFIRMED role mapping, so an edge naming an undecided role earns the act's existing refusal (<em>"nobody has decided what 'X' becomes here"</em>) rather than a refusal of its own.</li> <li>Each edge is landed by the SHIPPED emergency-cover declaration (ADR-0131 §2's own act: <code>ACTIVATE_CATALOG_ENTRIES</code> in the scope, the ADR-0131 §3 content-class refusal, one <code>SUBSTITUTION_EDGE_DECLARED</code> row in the break-glass trail) — ADR-0113 D5, so an imported edge is exactly as declared as a typed one. <strong>The actor is the importing operator</strong>, and <code>declared_by</code> says so.</li> <li>The 200 body answers <code>substitutionEdges[] {sourceRole, targetRole, declared, standing, reason}</code>. <code>declared</code> is true only where THIS call made the judgment, so a <strong>replay declares nothing twice</strong> and reports it honestly; <code>standing</code> says whether the edge is in force afterwards; <code>reason</code> carries the refusing surface's own sentence for the two per-edge outcomes §8 describes.</li> <li>An absent or empty array declares nothing and changes nothing — the pre-1.3 behaviour exactly.</li> </ul> <p>Additionally, when the manifest declares them, the target payload carries <code>mayHoldRecords</code> and <code>mandatorName</code>. Both are declarations for the target to honour or refuse (<code>mandatorName</code> is the operator-facing check that <code>--mandator-id</code> names the organization the bundle says it belongs to).</p> <h2 id="16-writing-an-exporter-the-checklist">16. Writing an exporter: the checklist<a class="headerlink" href="#16-writing-an-exporter-the-checklist" title="Permanent link">¶</a></h2> <ol> <li><strong>Emit <code>scope-manifest.json</code> first.</strong> <code>formatVersion</code>, the scope block, the full <code>documentTypes[]</code> for every type the corpus uses, <code>idsAuthoritative: true</code>, <code>titleRule: verbatim</code>, the bold <code>lossStatement</code>, <code>sourceSystem</code> and <code>sourceKeyPrefix</code> naming THIS instance. 1b. <strong>State every type's <code>verificationEvidence</code>, always</strong> (1.2), and its <code>retentionPeriodDays</code> / <code>reviewIntervalDays</code> wherever the catalog holds them. The classification is what makes a released Verification Report <em>evidence</em> rather than a plan; a bundle that leaves it out lands a corpus whose verification status reads one level weaker than it is, and says nothing about it.</li> <li><strong>Key everything by the human id.</strong> Manifest rows, chain keys, sidecar filenames, body filenames, attachment directories.</li> <li><strong>State every version's <code>kind</code> explicitly.</strong> Map <code>IN_REVIEW</code> → <code>DRAFT</code>, skip <code>CANCELLED</code>, emit <code>REVOKED</code> as itself. Never emit <code>evidence.draftCause: automatic-conversion</code>.</li> <li><strong>Emit <code>treeJson</code> beside every <code>.md</code>.</strong> The stored ProseMirror tree is the record; the stored markdown projection is the body.</li> <li><strong>Assert completeness before writing the manifest</strong> (ADR-0125 G-8): every referenced attachment has bytes, every version has a <code>kind</code>. The loader refuses either, but the exporter is where the defect is.</li> <li><strong>Emit no <code>source-training.json</code></strong>, and nothing else from the "stays" column of §14.</li> <li><strong>Emit <code>operating-model.json</code></strong> — records and vocabulary alone import a project that can be read forever and continued never. 7b. <strong>State <code>substitutionEdges</code>, always</strong> (1.3), <code>[]</code> included, and emit BOTH ends by role NAME. The matrix is the operating model's fourth member; leaving it out lands a project whose emergency cover silently does not exist. Never emit the source's <code>declaredBy</code>/<code>declaredAt</code>: the receiving operator makes that judgment (§8, §14).</li> <li><strong>Leave <code>caveats</code> empty.</strong> Attachments are version-pinned here, unlike the Confluence source.</li> <li><strong>Do not emit <code>snapshot/</code>.</strong> It is a Confluence-shaped directory and this bundle did not come from Confluence.</li> </ol> <hr /> <h2 id="appendix-a--what-the-first-real-exporter-taught-the-spec-2026-08-26">Appendix A — What the first real exporter taught the spec (2026-08-26)<a class="headerlink" href="#appendix-a--what-the-first-real-exporter-taught-the-spec-2026-08-26" title="Permanent link">¶</a></h2> <p>The reference exporter (<code>PortabilityExportService</code>, commit 4a5ddeaa) surfaced eight points the sections above understate. The spec text stands; this appendix is the honest delta, folded in rather than silently patched:</p> <ol> <li><strong>Two writer-emitted, reader-inert files</strong> join §10's list: <code>README.txt</code> (the loss statement, human-visible, FIRST entry) and <code>manifest.sha256.txt</code> (a digest of every entry, the PackWriter discipline — the reader ignores it; an auditor does not).</li> <li><strong>§16 item 1 means authorship order, not zip order</strong>: <code>manifest.json</code> is the LAST entry (the completeness marker); <code>scope-manifest.json</code> is the second, after the README.</li> <li><strong><code>treeJson</code> rides beside every version that HAS a stored tree.</strong> A MARKDOWN-format version has none and carries none; §7's derive fallback covers it. §16 item 4's "every .md" is therefore conditional in practice.</li> <li><strong>Folders travel as document ancestry.</strong> The reader derives paths from documents' ancestors, so an EMPTY folder does not survive the trip. §14's "folders travel" carries this caveat.</li> <li><strong><code>sourceSystem</code>/<code>sourceKeyPrefix</code> use the exported scope's CODE as the origin identifier</strong> — unique, immutable, the head of every id. No installation-instance identifier exists yet; when one does (the departure-dissolve design is where it first becomes load-bearing), it replaces the code here.</li> <li><strong><code>evidence.approvedBy</code> is emitted name-only.</strong> Emitting the email splits one human into two external persons (the persons call mints <code><name>@<origin>.invalid</code>; the seal would mint the declared address; ADR-0111 keys on <code>(origin, lower(email))</code>). Name-only is also what ADR-0125 §5 / ADR-0108 mean by "real accounts never travel".</li> <li><strong><code>addresseeRoles: []</code> vs absent</strong> — §6 draws a claim-vs-silence distinction the current reader does not: both land as no bindings. The distinction stays in the spec as intent; a reader change would realize it.</li> <li><strong>Document-target trace links have no slot</strong> in a declaring bundle (<code>requirementLinks</code> is key-target only; the document-target convention edge is Confluence-legacy and OFF for declaring bundles). Cross-scope and document-target references are §6/G-10 territory — the re-binding chapter, still open.</li> </ol> <h2 id="appendix-b--amendment-2-on-the-wire-2026-08-27">Appendix B — Amendment 2 on the wire (2026-08-27)<a class="headerlink" href="#appendix-b--amendment-2-on-the-wire-2026-08-27" title="Permanent link">¶</a></h2> <p>The bundle format is UNCHANGED (the id namespace is <code>scope-manifest.json</code>'s existing <code>code</code>). The import wire gained: <code>ImportTarget.idNamespace</code> (persisted on the batch; null means the target's own code) and <code>ImportTarget.adoptForeignNamespace</code> (unpersisted — the human's explicit declaration that landing ids under a differently-coded scope is deliberate; without it, divergence refuses). Adoption validates <code>adoptHumanId</code> against the batch's namespace, not the target's code. The organization declaration is checked only where the target scope has one (GLOBAL is structurally mandator-less). A GLOBAL target requires an explicit namespace, because GLOBAL mints unprefixed ids. New preview refusal kind: <code>ID_NAMESPACE</code>. Client: <code>--land-into CODE</code> sends the pair, prints the deliberate-landing banner, and verifies the batch's namespace echo before writing anything. An adopted-scope landing cannot be undone through the import's own dissolve path (that path still refuses to destroy a scope the batch did not create) — inspect at preview, then finalize.</p> <h2 id="appendix-c--format-12-and-what-the-rehearsal-left-standing-2026-09-05">Appendix C — Format 1.2 and what the rehearsal left standing (2026-09-05)<a class="headerlink" href="#appendix-c--format-12-and-what-the-rehearsal-left-standing-2026-09-05" title="Permanent link">¶</a></h2> <p>The point release that closes register rows <strong>52</strong> and <strong>53</strong> (ADR-0125 Amendment 4), driven entirely by the row-37 two-instance rehearsal (<code>docs/planning/row-37-rehearsal-local.md</code>). §1's version history and the compatibility statement carry the change itself; this appendix is the honest remainder — the rehearsal's smaller divergences, each either closed here or argued and left, so a later reader is never left wondering whether an item was missed or decided.</p> <table> <thead> <tr> <th>#</th> <th>Divergence</th> <th>Verdict</th> </tr> </thead> <tbody> <tr> <td>D1</td> <td>a fully-verified chain arrives PLANNED-ONLY (<code>verification_evidence</code> has no slot)</td> <td><strong>CLOSED — 1.2.</strong> <code>documentTypes[].verificationEvidence</code>; create applies, adopt reports (§3/§15 item 4).</td> </tr> <tr> <td>D2</td> <td><code>retention_period</code> / <code>review_interval</code> do not travel</td> <td><strong>CLOSED — 1.2.</strong> Two more fields, same rule. The number travels faithfully; the target's own <code>/defaults</code> write path owns what it stores for it (register row <strong>67</strong>'s interval skew is that path's fix, deliberately not worked around here — an imported period must not disagree with a hand-typed one on the same installation).</td> </tr> <tr> <td>D3</td> <td>a dropped cross-scope link counted as zero</td> <td><strong>CLOSED.</strong> The counter keys on the target being outside this scope, by scope id <em>or</em> by target document (§4).</td> </tr> <tr> <td>D4</td> <td>document RELATIONS have no slot and no count</td> <td><strong>COUNTED, not carried</strong> (<code>documentRelationsNotCarried</code>, §4). Carrying them is the same identity re-binding problem as a cross-scope reference — ADR-0125 §6 / gap G-10, explicitly out of 1.x — and a slot without re-binding would land edges pointing at documents the target does not have. What was indefensible was the silence, and that is what is fixed.</td> </tr> <tr> <td>D5</td> <td><code>DOCUMENT_IMPORTED</code> is written for 12 of 13 documents</td> <td><strong>CLOSED as a claim, not as a row.</strong> The trail row is written by the seal of a document's first SEALED version, because that is the only act carrying the source's release stamps; a draft-only document arrives as <code>DOCUMENT_CREATED</code>. Writing a second import row from the create path would either double-count or backfill at finalize — inventing an act to make an operator's arithmetic close. The arithmetic is made to close instead: <code>load_arrival</code>'s header states the rule and its run report states <code>draftOnlyDocuments</code>, so <code>DOCUMENT_IMPORTED == documents - draftOnlyDocuments</code> is checkable.</td> </tr> <tr> <td>D6</td> <td>"attachments" means three different things</td> <td><strong>CLOSED by labelling.</strong> §4 above states the manifest's unit (distinct FILES) and the loader's summary now says "attachment uploads" (upload ACTS). All three numbers were defensible; none was labelled.</td> </tr> <tr> <td>D7</td> <td>the batch evidence artifact speaks Confluence</td> <td><strong>CLOSED.</strong> <code>attachmentCaveats</code> and <code>training.bindings</code> join <code>evidenceLadder</code> / <code>releaserRule</code> as PER-LINEAGE prose in <code>load_arrival.finalize</code>. An LQMS-origin batch's caveats are <code>[]</code> (§5/§16 item 8 — its attachments <em>are</em> version-pinned) and its training sentence names no Jira custom field.</td> </tr> <tr> <td>D8</td> <td>the origin key is a scope code, not an instance</td> <td><strong>LEFT, argued.</strong> Appendix A item 5 already states it: no installation-instance identifier exists yet, and inventing one here would mint an identity with no owner, no uniqueness guarantee and no lifecycle. It becomes load-bearing in the departure-dissolve design (register row 36), which is where it is sequenced.</td> </tr> <tr> <td>D9a</td> <td>element-kind DESCRIPTIONS do not travel</td> <td><strong>LEFT, argued.</strong> Labels and prefixes travel, and those are what a key resolves through; a description is display prose on an activation, carries no meaning a reader derives anything from, and adding a field to <code>elementKinds[]</code> for it would spend a format step on cosmetics. Worth folding into the next real <code>elementKinds</code> change.</td> </tr> <tr> <td>D9b</td> <td>the loader's log undercounts element kinds</td> <td><strong>CLOSED.</strong> <code>activated</code> answers true only for what THIS call did, so it was never the scope's total. The line now states both numbers, each labelled.</td> </tr> <tr> <td>D9c</td> <td><code>manifest.json</code> is not covered by <code>manifest.sha256.txt</code></td> <td><strong>LEFT, documented.</strong> It cannot be: it is written LAST as the completeness marker and cannot digest itself. §16 item 2 and <code>README.txt</code> say so; an auditor told to "verify the digests" is told which two entries are outside them.</td> </tr> </tbody> </table> <hr /> <h2 id="appendix-d--format-13-and-the-promise-adr-0131-2-had-made-2026-09-09">Appendix D — Format 1.3 and the promise ADR-0131 §2 had made (2026-09-09)<a class="headerlink" href="#appendix-d--format-13-and-the-promise-adr-0131-2-had-made-2026-09-09" title="Permanent link">¶</a></h2> <p>The point release that closes register row <strong>76</strong>. Its whole content is one array, and what makes it worth an appendix is not the array but the KIND of gap it closed.</p> <p><strong>The gap was a promise, not an oversight.</strong> 1.2's three fields closed divergences the row-37 rehearsal MEASURED — a corpus arriving and saying something subtly wrong about itself. Row 76 is the other shape: ADR-0131 §2 stated, as accepted architecture, that the substitution matrix travels with the operating model, and no code ever made it so. Nothing measured it because nothing looked; the manual lane found it by verifying the guide against the code, and the guide's first fix was to go SILENT about a feature the ADR promised. A published interface whose specification is true of the design and false of the implementation is the worst of the three states — worse than a documented gap, because everybody downstream reasons from the promise.</p> <p><strong>What travels, restated once:</strong> the RULE (<em>"a holder of A may take over B here"</em>), as two role names. <strong>What does not:</strong> the act behind it. <code>substitution_edge.declared_by</code> / <code>.declared_at</code> are the source's witness of a governance judgment, and §14's line holds — the receiving operator declares the edge in their own name, through the same audited act the emergency-cover surface performs, and the target's trail says who did it there. That is not a degradation of ADR-0131 §2; it is §2 read literally, because <em>"the declaration act IS the qualification statement"</em> means the statement cannot be inherited from somebody else's instance.</p> <table> <thead> <tr> <th>#</th> <th>Question this step had to answer</th> <th>Verdict</th> </tr> </thead> <tbody> <tr> <td>E1</td> <td>identify roles by name or by id?</td> <td><strong>NAME.</strong> The operating model's own convention: policies name roles, the confirmed mapping table is KEYED by the source name, and no field of this format carries a role UUID. An id would name the exporting installation's catalog and be inert here — and writing an unread field suggests the reader uses it (the same rule that keeps <code>sort_order</code> out of the folder rows).</td> </tr> <tr> <td>E2</td> <td>do an edge's ends have to be confirmed in the role mapping?</td> <td><strong>YES.</strong> They join the set an execute demands be confirmed. Otherwise the matrix would resolve against a decision nobody made — the silent adoption ADR-0114 §2 forbids, arriving by a new door.</td> </tr> <tr> <td>E3</td> <td>what about the source's <code>declaredBy</code> / <code>declaredAt</code>?</td> <td><strong>STAY</strong> (§14). See above.</td> </tr> <tr> <td>E4</td> <td>an edge the mapping collapses onto ONE instance role</td> <td><strong>REPORTED, corpus lands.</strong> Many-to-one mapping is the normal case (ADR-0114 §2, the PULSEMED five-onto-three), so refusing the operating model over its consequence would make the matrix and many-to-one mapping mutually exclusive. The run names the instance role and the two source roles.</td> </tr> <tr> <td>E5</td> <td>an edge whose target maps onto an ADMINISTRATIVE role here</td> <td><strong>REPORTED, corpus lands.</strong> ADR-0131 §3 refuses it structurally and rightly — the master key through a side door — but the refusal is about THIS installation's catalog, which the exporting instance could not know. The remedy is to re-map, so the run prints the refusal's own sentence (it names the offending permissions) and lands the rest.</td> </tr> <tr> <td>E6</td> <td>an edge naming a role a <code>--limit</code> run does not carry</td> <td><strong>DROPPED and NAMED, client-side.</strong> The narrowing that keeps a trial run coherent would otherwise leave an edge pointing at a role the operator is never asked about. <code>load_arrival</code> reports it as <code>bundle.substitutionEdgesNotCarried</code> and prints it before the mapping is confirmed.</td> </tr> <tr> <td>E7</td> <td>landing inside the D1 "together or not at all" cage?</td> <td><strong>NOT YET, argued.</strong> The edges are declared AFTER the operating-model transaction commits, because the shipped declaration act opens its own transaction and the roles it needs are created inside that one. The seam a later step should take is a <code>declareEdgeOnTransaction</code> on the emergency-cover service, exactly as <code>activateRoleOnTransaction</code> and <code>setPolicyOnTransaction</code> exist for roles and policies. The residue is bounded and bounded safely: an edge <strong>grants nothing by itself</strong> (V130's own table comment) — it authorizes a future timed, witnessed, self-expiring act — whereas a missing policy makes a type's documents unsubmittable forever. A landed corpus with an undeclared edge is one governance act from complete; a landed corpus with half its policies is the state D1 exists to prevent. Recorded in <code>docs/planning/row-76-lane-report.md</code>.</td> </tr> <tr> <td>E8</td> <td>prove it by the row, or by the round trip?</td> <td><strong>ROUND TRIP.</strong> <code>PortabilityRoundTripFullStackTest</code> exports, lands through the real <code>load_arrival.py</code>, and <strong>re-exports the target</strong>, comparing the two <code>substitutionEdges</code> arrays. A one-way assertion would leave the writer's half untested, which is the exact shape of the defect this row closed.</td> </tr> </tbody> </table> </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="../12_glossary/" class="md-footer__link md-footer__link--prev" aria-label="Previous: 12. Glossary"> <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"> 12. Glossary </div> </div> </a> <a href="../../decisions/" class="md-footer__link md-footer__link--next" aria-label="Next: Architecture Decision Records"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> Architecture Decision Records </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>