The Dev Manual

This book is one half of a pair. Its companion — The Canonic Canon — covers the same system from the governor’s perspective: policy, oversight, organizational adoption. This book covers the developer’s perspective: code, commands, architecture, build pipelines. Read either independently; read both for the complete picture.

Persona

How to BUILD in CANONIC. DRY. MATH. FIXED. PURE.

Devs speak programming. This book speaks theirs.

Dexter Hadley, MD/PhD ¹ Author, CANONIC February 2026

Abstract

This is the implementation manual for CANONIC — a system where governance compiles like code. It walks you from your first axiom through your first TRIAD, your first scope, your first service, and your first 255-bit validation score. If you can write Markdown, you can write governance: create a directory, add CANON.md with an axiom and constraints, add README.md with the public interface, add VOCAB.md with defined terms, then run the validator. You will start at 35 and iterate toward 255 — the score that proves every governance obligation is satisfied, by architecture, not by committee. DRY. MATH. FIXED. PURE.

FRONT MATTER

Half-Title

THE CANONIC DOCTRINE

Title Page

THE CANONIC DOCTRINE The MAGIC Implementation Standard

Copyright

Copyright 2026 CANONIC. All rights reserved. Governed under MAGIC 255-bit compliance standard. Every chapter evidenced. Every claim cited. Every commit COIN.

Dedication

For every developer who was told to “just ship it.” This manual is your compiler.

Epigraph

“255, or it doesn’t deploy.”

— CANONIC ²

Foreword

This is a governed document.

Every chapter compiles against the axiom that produced it. Every claim traces to a governance source, a paper, or a blog post. The act of reading this manual is an act of verification. Run magic validate on any scope referenced here. The score is the proof ³.

This is not a manual about governance — it is a manual about building. Governance in CANONIC works like compilation: your CANON.md is the grammar, your VOCAB.md is the type system, your README.md is the header file, and magic validate is the compiler that checks them all against a 255-bit target. Everything else is syntax ⁴.

If you are a developer, an agent, an operator, or an architect who builds governed systems, this manual is written for you. It explains how to build in CANONIC — in programming, not prose. Every chapter gives you a concrete workflow: write the governance file, run the command, read the output, iterate until the score holds.

TABLE OF CONTENTS

PART I     — FOUNDATIONS ........................ Chapters 1-4
PART II    — BUILDING .......................... Chapters 5-9
PART III   — THE SERVICES ...................... Chapters 10-23
PART IV    — INTEL COMPILATION ................. Chapters 24-27
PART V     — DESIGN ............................ Chapters 28-31
PART VI    — ECONOMICS ......................... Chapters 32-35
PART VII   — THE CLOSURE ....................... Chapters 36-40, 48
PART VIII  — TOOLCHAIN ......................... Chapters 41-47
BACK MATTER — Appendices A-G, Glossary, Colophon

Part I (Chapters 1-4) establishes the primitives: axiom, TRIAD, inheritance, and the eight-dimensional scoring model. Part II (Chapters 5-9) walks you through building scopes, services, products, and federations. Part III (Chapters 10-23) details each of the 14 services, from LEARNING to DEPLOY. Parts IV-VI cover INTEL compilation, design tokens, and the COIN economy. Part VII presents the theoretical closure — governance as type system, compiler, and version control. Part VIII documents the toolchain: magic, build, and heal. For the governance policy perspective on any of these topics, see The Canonic Canon.

PART I — FOUNDATIONS

Chapter 1: The Axiom

Every governed scope begins with one sentence. That sentence is the axiom.

The FHIR endpoint that drifted

A backend developer ships a FHIR integration — R4 Patient resources flowing from an external lab system into the hospital’s EHR. It works. Six months later, the upstream lab vendor quietly migrates to a revised profile. The Observation.category binding changes. No governance file tracks the dependency, so nothing flags the break. The integration keeps running, but coded lab results silently stop mapping. Patient data still flows — it just stops meaning what the clinicians think it means. Nobody knows which version of the FHIR spec the endpoint was built against, because nobody wrote it down in a place the toolchain could check.

This is the problem axioms solve. An axiom like “LabBridge serves laboratory results with governed FHIR R4 INTEL. Every resource profile versioned.” turns that silent failure into a compilation error. The version constraint propagates into the governance files. When the upstream profile changes and the scope’s evidence base no longer matches, magic validate catches the drift before the data pipeline does. The axiom is the single sentence that makes the invisible dependency visible — and enforceable.

1.1 The Contract

The axiom is a declaration. Not a description. Not a mission statement. Not aspirational prose. It is the single assertion from which every governance decision in the scope derives. Think of it as the type signature of your entire governance scope — if the scope’s behavior is consistent with the axiom, the scope type-checks. If not, it fails ⁵.

## Axiom

**WALLET stores COIN for every USER. Every event signed.**

If you can derive governance decisions from the axiom, the axiom is correct. If decisions contradict the axiom, either the decision is wrong or the axiom needs revision. The axiom is the root of a derivation tree — not a suggestion, not guidance, but the mathematical foundation from which everything in the scope follows ⁵.

1.2 Clinical Axioms

In clinical AI, the axiom doubles as the clinical contract — a single sentence declaring what the scope does, who it serves, and what guarantee it makes. Every clinical AI deployment in CANONIC begins with one:

## Axiom

**MammoChat serves breast imaging with governed BI-RADS INTEL. Every recommendation cited.**

This axiom declares three binding obligations: (1) the scope serves breast imaging, not general medicine — domain boundary enforced; (2) the evidence is BI-RADS INTEL, not general clinical evidence — evidence standard declared; (3) every recommendation is cited — provenance guarantee. If MammoChat generates an uncited recommendation, it violates its axiom. The violation is a compilation error.

## Axiom

**OncoChat serves oncology with governed NCCN INTEL. Every guideline versioned. Every interaction audited.**

This axiom adds an operational guarantee — every interaction audited — and that single phrase propagates to every component of the OncoChat scope: the TALK engine must log interactions, the LEDGER must record them, the CHAIN must hash-link them. One sentence in the axiom drives the entire architecture.

1.3 Good vs Bad Axioms

The pattern is clear: good axioms are declarative (state what IS, not what you hope), specific (name the domain, the evidence, the guarantee), and testable (the validator can check compliance). Bad axioms are aspirational, vague, or circular. If your axiom contains the words “aim,” “strive,” “best effort,” or “endeavor” — rewrite it. Those are mission statements, not axioms ⁵.

1.4 Derivation

The axiom is the root of a derivation tree: constraints derive from the axiom, files derive from the constraints, and child scopes inherit the axiom’s obligations. This derivation chain is, concretely, the compilation chain ³.

Axiom → Constraints → Files → Children → Validation → Score

A score of 255 means every derivation holds. A score below 255 means at least one derivation failed. The bitmask identifies which ⁶.

To see this concretely, consider the MammoChat axiom: “Every recommendation cited.” That single phrase derives the following constraints:

MUST:     Cite evidence source for every recommendation
MUST:     Include BI-RADS category reference for every screening assessment
MUST:     Version evidence base with effective date
MUST NOT: Generate recommendations without INTEL backing
MUST NOT: Reference evidence outside the governed INTEL layer

Each constraint derives from the axiom. Each file in the scope (INTEL.md, COVERAGE.md, LEARNING.md) satisfies one or more constraints. Each child scope (a specific hospital’s MammoChat deployment) inherits these constraints. The derivation is traceable from the axiom to every file in the scope tree. If a constraint cannot be derived from the axiom, the constraint is either wrong or the axiom is incomplete.

1.5 The Axiom as Entry Point

In compiler theory, every program has an entry point — main(). In CANONIC, every scope has an entry point — the axiom. The validator reads the axiom first. Everything else compiles against it ³.

When magic validate runs against a scope, it reads the axiom in CANON.md first, because the axiom establishes the evaluation context. Constraints are evaluated against the axiom, files are evaluated against the constraints, and the score is computed from those file evaluations. Whether you are integrating CANONIC into an EHR environment or building a standalone service, the pattern is the same: one sentence defines the contract, the contract drives the architecture, and the architecture compiles to a score that serves as proof. Start with the axiom. Everything else follows.

1.6 Axiom Anti-Patterns

In practice, developers make predictable mistakes with axioms. Here are the anti-patterns and their corrections:

The empty axiom: **Governed scope.** — This says nothing. It has zero information content. Every CANONIC scope is governed by definition. The axiom must declare what is governed, how it is governed, and what guarantee it makes.

The kitchen-sink axiom: A paragraph describing everything the scope does, every technology it uses, and every stakeholder it serves. Axioms are one sentence. If you need more than one sentence, you need constraints, not a longer axiom.

The copy-paste axiom: Copying the parent scope’s axiom verbatim. The child scope should specialize the parent’s axiom, not duplicate it. MammoChat’s axiom specializes the healthcare CHAT axiom — it adds breast imaging and BI-RADS. It does not repeat the parent’s general clinical CHAT declaration.

The aspirational axiom: **We strive to provide the best clinical decision support.** — “Strive” is untestable. “Best” is undefined. Replace with a declarative, testable statement: **MammoChat serves breast imaging with governed BI-RADS INTEL. Every recommendation cited.**

Write the axiom, derive the constraints, build the scope, and validate to 255. For a complete walkthrough from empty directory to 255, see Chapter 5.

1.7 The Three Primitives

CANONIC is built on three primitives, and every service, product, and deployment composes one or more of them. The axiom declares which primitives a scope uses; the constraints enforce how. We will explore how these primitives compose into the 14 services in Chapter 7 and detail each service individually in Chapters 10-23 ⁷.

The primitives are orthogonal. INTEL exists without CHAT. CHAT exists without COIN. COIN exists without INTEL. But composition is where power emerges. A TALK service composes CHAT + INTEL: it converses AND it knows. A SHOP service composes COIN + INTEL: it prices AND it evidences. A full AGENT scope composes all three: it knows (INTEL), it converses (CHAT), and it accounts for value (COIN) ⁷.

The axiom declares the composition. Consider these three axioms and their primitive compositions:

## Axiom

**LEARNING discovers governed INTEL. Every pattern evidenced.**

This axiom composes INTEL only. No CHAT. No COIN. The scope discovers and governs knowledge. It does not converse. It does not transact.

## Axiom

**MammoChat serves breast imaging with governed BI-RADS INTEL. Every recommendation cited.**

This axiom composes CHAT + INTEL. The scope converses (serves breast imaging) and knows (governed BI-RADS INTEL). It does not transact.

## Axiom

**SHOP publishes governed products at governed prices. Every transaction COIN. Every product 255.**

This axiom composes COIN + INTEL. The scope transacts (governed prices, COIN) and knows (governed products). It does not converse.

Primitive composition is not metadata — it is architecture. A scope that composes CHAT + INTEL must have both a conversation engine and a knowledge layer. A scope that composes COIN must have a LEDGER. A scope that composes all three must have all three. The axiom declares what the architecture requires, and the validator enforces it.

1.8 Governance-First Principle

Governance precedes implementation. Always. No exceptions. This is not a workflow preference. It is an architectural constraint ².

The governance-first principle means:

1. Write CANON.md before writing code.
2. Define VOCAB.md before naming variables.
3. Write README.md before writing the API.
4. Run magic validate before running tests.
5. Achieve 35 before writing the first function.

# WRONG: code first, governance later
mkdir my-service
cd my-service
npm init
# ... write 5,000 lines of code ...
# Three months later: "We should probably add governance"
echo "# CANON" > CANON.md  # Too late. The architecture is already set.

# RIGHT: governance first, code follows
mkdir MY-SERVICE
cd MY-SERVICE
cat > CANON.md << 'EOF'
# MY-SERVICE — CANON


## Axiom

**MY-SERVICE serves clinical queries with governed INTEL. Every answer cited.**

---

## Constraints

MUST:     Cite evidence for every clinical answer
MUST:     Log every session to LEDGER
MUST NOT: Generate uncited recommendations

---

EOF

magic validate  # Score: first question answered. Now build from here.

The governance-first principle has a compiler analogy: you write the type signature before you write the function body. The type signature constrains what the function can do. The function body implements within those constraints. In CANONIC, the CANON.md is the type signature. The code is the function body. Write the signature first. The implementation follows.

In healthcare, governance-first is not just good practice — it is a regulatory requirement expressed as architecture. HIPAA requires administrative safeguards before deploying technology. The Joint Commission requires documented policies before clinical operations begin. FDA 21 CFR Part 11 requires validation protocols before system deployment. CANONIC does not impose this workflow; it encodes the regulatory requirements you already have into a developer workflow that your build system can enforce.

1.9 Axiom Mechanics: The Validator’s Perspective

When magic validate reads a CANON.md, it processes the axiom in three steps ⁶:

Step 1: Parse. Extract the axiom text from the ## Axiom section. The axiom must be a single bold-formatted sentence: **{axiom text}**. If the axiom is missing, empty, or not bold-formatted, the first question fails immediately.

ERROR: CANON.md — Axiom section missing or malformed.
  Expected: ## Axiom followed by **{axiom text}**
  Got: ## Axiom followed by empty section
  Fix: Add a bold-formatted axiom sentence.
  Run: magic validate --verbose for details.

Step 2: Constraint derivation check. The validator verifies that every MUST/MUST NOT constraint in the Constraints section is semantically derivable from the axiom. This is not AI inference — it is structural checking. The validator confirms that the axiom’s key terms appear in the constraints. If the axiom says “Every recommendation cited” but no constraint mentions citing or evidence, the validator flags the gap.

WARN: CANON.md — Axiom term "cited" has no matching constraint.
  Axiom: "Every recommendation cited."
  Constraints: [no constraint references citing or evidence]
  Fix: Add MUST: Cite evidence source for every recommendation

Step 3: Inheritance consistency. The validator checks that the axiom does not contradict any inherited constraint. If the parent’s CANON.md says MUST NOT: Process PHI outside the deployment perimeter and the child’s axiom implies processing PHI externally, the validator flags the contradiction.

ERROR: CANON.md — Axiom contradicts inherited constraint.
  Parent: hadleylab-canonic/MAGIC/SERVICES/TALK
  Parent constraint: MUST NOT: Process PHI outside the deployment perimeter
  Child axiom implies: external PHI processing
  Fix: Revise axiom to comply with inherited constraints.

These three steps — parse, derivation check, inheritance consistency — execute every time magic validate runs. The axiom is not decorative. It is the first thing the compiler reads. It is the root of every derivation. It is the entry point.

1.10 Writing Your First Axiom: A Walkthrough

Open a terminal. Create the scope directory. Write the axiom.

mkdir -p DERMCHAT
cd DERMCHAT

Start with the clinical contract. What does this scope do? It serves dermatology. What evidence does it use? AAD (American Academy of Dermatology) clinical guidelines. What guarantee does it make? Every recommendation includes a differential.

## Axiom

**DermChat serves dermatology with governed AAD INTEL. Every recommendation includes differential. Every interaction audited.**

Test the axiom against the three criteria:

Now derive constraints from the axiom:

MUST:     Cite AAD guideline for every dermatologic recommendation
MUST:     Include differential diagnosis for every clinical assessment
MUST:     Log every interaction to LEDGER with timestamp and actor
MUST:     Version evidence base with AAD publication date
MUST NOT: Generate recommendations without AAD INTEL backing
MUST NOT: Provide biopsy recommendations (refer to dermatologist)
MUST NOT: Process PHI outside the local deployment perimeter

Every constraint traces to a word or phrase in the axiom. “Governed AAD INTEL” produces the MUST about AAD guidelines and the MUST NOT about INTEL backing. “Every recommendation includes differential” produces the MUST about differential diagnosis. “Every interaction audited” produces the MUST about LEDGER logging. The derivation is mechanical. If you cannot derive a constraint from the axiom, either the constraint is wrong or the axiom is incomplete.

1.11 Axiom Versioning

Axioms change. Clinical evidence evolves. Organizational scope shifts. When the axiom changes, everything downstream must revalidate ².

# Before (v2025-06)
## Axiom

**MammoChat serves breast imaging with governed ACR INTEL. Every recommendation cited.**

# After (v2026-01)
## Axiom

**MammoChat serves breast imaging with governed BI-RADS INTEL. Every recommendation cited. Every interaction audited.**

The axiom changed in two ways: (1) evidence source changed from “ACR” to “BI-RADS” (more specific), and (2) an audit guarantee was added (“Every interaction audited”). Both changes propagate to constraints, files, and child scopes.

When you change the axiom:

1. Update the version: field in CANON.md.
2. Update every constraint that referenced the changed terms.
3. Run magic validate on the scope AND every child scope.
4. Record the change as an EVOLUTION signal in LEARNING.md.
5. Commit with a GOV prefix: git commit -m "GOV: MammoChat axiom — add audit guarantee".

magic validate --scope SERVICES/TALK/MAMMOCHAT --recursive
# Validates MammoChat AND all child deployments (MAMMOCHAT-UCF, MAMMOCHAT-ADVENT, etc.)

If any child scope’s constraints conflict with the updated axiom, the validator identifies the conflict. Fix the child scope’s constraints. Revalidate. The cascade is deterministic — you change the root (axiom), the compiler tells you every leaf that breaks.

1.12 The Axiom in Production

In a production clinical AI deployment, the axiom is not just a governance artifact. It is the clinical contract that appears in audit logs, compliance reports, and regulatory submissions. When the FDA asks “what does this AI system do?” — the axiom is the answer. When the Joint Commission asks “what is the governance basis for this clinical decision support tool?” — the axiom is the answer. When the malpractice insurer asks “what guarantees does this system make?” — the axiom is the answer ³.

The axiom is one sentence — the most important sentence in the scope. Write it carefully, derive everything from it, validate against it, and deploy on it. Everything else is implementation. For the governance policy perspective on axioms, see The Canonic Canon, Chapter 1.

1.13 Axiom Composition Patterns

When building complex scopes, the axiom pattern determines the architectural composition. Three composition patterns recur across every CANONIC deployment:

Pattern 1: Single-Primitive Axiom. The scope uses one primitive. The architecture is narrow.

## Axiom

**LEARNING discovers governed FHIR patterns. Every discovery evidenced.**

This axiom composes INTEL only. The scope directory contains INTEL.md, LEARNING.md, and governance files. No CHAT engine. No COIN operations. The scope is a knowledge container.

FHIR-PATTERNS/
  CANON.md          ← axiom declares INTEL-only composition
  VOCAB.md          ← FHIR governance terms
  INTEL.md          ← evidence corpus (FHIR R4/R5 patterns)
  LEARNING.md       ← accumulated pattern discoveries
  COVERAGE.md       ← dimensional self-assessment
  ROADMAP.md        ← governance trajectory
  README.md         ← public interface
  FHIR-PATTERNS.md  ← scope specification

Pattern 2: Dual-Primitive Axiom. The scope uses two primitives. The architecture widens.

## Axiom

**MammoChat serves breast imaging with governed BI-RADS INTEL. Every recommendation cited. Every interaction audited.**

This axiom composes CHAT + INTEL. The scope directory contains everything in Pattern 1 plus conversation infrastructure: systemPrompt compilation, persona resolution, disclaimer rendering.

Pattern 3: Triple-Primitive Axiom. The scope uses all three primitives. Full architecture.

## Axiom

**AGENT composes INTEL + CHAT + COIN. Every knowledge governed. Every conversation audited. Every transaction ledgered.**

This axiom composes all three primitives. The scope directory includes knowledge governance, conversation engines, and economic operations. The AGENT scope is the most complex — and the most powerful.

The axiom declares the pattern, the pattern determines the architecture, and the architecture compiles to 255. Start with the axiom — the rest follows.

1.14 Axiom Testing: The Five-Question Checklist

Before committing an axiom, run it through this checklist. Every question must answer YES:

# Validate axiom quality programmatically
magic validate --axiom-check
# Output:
#   Declarative: PASS (verb: "serves")
#   Testable: PASS (guarantee: "Every recommendation cited")
#   Domain-bounded: PASS (domain: "breast imaging")
#   Single-sentence: PASS (1 sentence)
#   Bold-formatted: PASS (**...**)

If any question answers NO, rewrite the axiom before proceeding. The five-question checklist takes 30 seconds. A bad axiom costs weeks of rework downstream.

Chapter 2: The TRIAD

Every governance framework eventually drowns in its own paperwork. CANONIC bets on the opposite: three files are enough to declare a governed scope. CANON.md states what you believe. VOCAB.md defines what your words mean. README.md describes what you offer the world. If you write nothing else, write these three. They are the foundation that the validator evaluates, that other scopes inherit from, and that auditors examine.

2.1 The Three Files

Without the TRIAD, your scope score is 0. With it, you have the minimum viable governance declaration — enough for the validator to evaluate, for other scopes to inherit from, and for auditors to examine ⁵.

2.2 CANON.md Structure

# {SCOPE} — CANON

version: {YYYY-MM}

---

## Axiom

**{One sentence. The contract.}**

---

## Constraints

\```
MUST:     {binding obligation}
MUST NOT: {binding prohibition}
\```

---

Every governed Markdown file follows this structure: header, inherits:, separator, content, separator, footer ⁷.

The structure maps directly to clinical protocol governance. Consider a MammoChat deployment at a specific hospital:

# MAMMOCHAT-UCF — CANON


## Axiom

**MammoChat serves UCF College of Medicine breast imaging with governed BI-RADS INTEL. Every recommendation cited. Every interaction audited.**

---

## Constraints

\```
MUST:     Cite BI-RADS category for every screening assessment
MUST:     Version evidence base with ACR publication date
MUST:     Log every clinical interaction to LEDGER
MUST:     Maintain PHI boundary — no patient identifiers in governance metadata
MUST NOT: Generate uncited clinical recommendations
MUST NOT: Process PHI outside the local deployment perimeter
MUST NOT: Override radiologist clinical judgment
\```

---

The constraints are not suggestions. They are binding obligations that magic validate will check. “MUST NOT: Process PHI outside the local deployment perimeter” is a HIPAA §164.312 technical safeguard expressed as a governance constraint. If the deployment violates it, validation fails.

2.3 VOCAB.md Structure

# VOCAB

| Term | Definition |
|------|-----------|
| {TERM} | {Definition. Precise. No stubs.} |

---

An undefined term is a type error. A stub definition ("--" or "Governed term.") is a gap, not a closure. Every SCREAMING_CASE term in a scope must resolve to a definition ⁷.

In clinical informatics, vocabulary precision is patient safety. Define every clinical term the scope uses, because ambiguity in clinical terminology produces clinical errors:

# VOCAB

| Term | Definition |
|------|-----------|
| BI-RADS | Breast Imaging Reporting and Data System. ACR standardized classification (0-6) for mammographic findings. |
| SCREENING | Population-level breast imaging for asymptomatic patients. Distinct from DIAGNOSTIC. |
| DIAGNOSTIC | Targeted breast imaging for symptomatic patients or abnormal screening findings. |
| TRIAGE | Classification of screening findings into follow-up categories based on BI-RADS assessment. |
| PHI | Protected Health Information as defined by HIPAA §160.103. |
| INTEL | Governed knowledge unit with provenance — source, date, evidence grade, citation. |
| LEDGER | Append-only audit trail. Every governed event recorded. |

---

If MammoChat uses “SCREENING” without a VOCAB.md definition, the validator flags it — just as a compiler flags an undefined variable. The clinical vocabulary IS the type system. Undefined terms produce type errors. Ambiguous terms produce runtime bugs — and in clinical AI, runtime bugs are patient safety events.

2.4 README.md Structure

# {SCOPE} — {Title}


{Scope description. What it does. What it offers. How to use it.}

---

*{SCOPE} | README | {DOMAIN}*

The README is the public interface — the service description that external consumers read, internal consumers inherit from, and the hospital’s clinical informatics committee reviews when evaluating an AI deployment ⁵.

BLOAT EXTINCTION

The TRIAD files were originally all hand-authored. Production experience revealed that COVERAGE.md and README.md were being hand-edited redundantly — developers maintaining generated content by hand, creating drift risk. BLOAT EXTINCTION resolved this:

• COVERAGE.md is now generated by the build pipeline from the eight-question assessment. Developers answer the questions. The compiler generates the file.
• README.md is minimal — inherits: + axiom + purpose. No hand-maintained feature lists, no changelog, no badges. The governance tree IS the documentation.

The TRIAD remains the foundation, but leaner. CANON.md is still hand-authored — the axiom is human judgment. VOCAB.md is still hand-authored — term definitions require domain expertise. README.md is minimal by design. COVERAGE.md is generated. The build pipeline enforces the boundary: hand-edit the contracts, generate the outputs.

2.5 The Recursive Property

The TRIAD appears at every level of the governance tree — organization, team, project, service. The validator does not distinguish scopes by size, only by compliance ⁵.

canonic-canonic/             TRIAD
  MAGIC/                     TRIAD
    SERVICES/                TRIAD
      TALK/                  TRIAD
hadleylab-canonic/           TRIAD
  MAGIC/                     TRIAD
    SERVICES/                TRIAD
      MAMMOCHAT/             TRIAD
        MAMMOCHAT-UCF/       TRIAD

Same three files at every scale. A 5,000-employee health system and a single-physician AI deployment use the same TRIAD. The committee reviewing a hospital-wide AI governance proposal evaluates the same file structure a solo developer creates for a proof-of-concept. Three files, not thirty — that is why it scales.

2.6 The TRIAD in EHR Integration

When you integrate CANONIC with an existing EHR (Epic, Cerner, MEDITECH), the TRIAD becomes the integration contract. CANON.md declares what the integration does and what constraints it obeys. VOCAB.md defines the terminology — FHIR resource types, HL7 message types, clinical terminology standards. README.md describes the interface — endpoints, data flows, clinical workflows.

When the EHR vendor asks “what does your AI governance framework require?” — three files. When IT security asks “what are the constraints on this deployment?” — CANON.md. When the clinical informatics committee asks “what do your terms mean?” — VOCAB.md. Everything else builds on this foundation.

2.7 Building the TRIAD: Step-by-Step

Open a terminal. Create the scope. Write the three files in order: CANON.md first (the contract), VOCAB.md second (the type system), README.md third (the interface) ⁵.

mkdir -p CARDIO-CHAT
cd CARDIO-CHAT

Step 1: CANON.md. Write the axiom and constraints. The axiom is the single sentence that defines the scope. The constraints derive from the axiom.

cat > CANON.md << 'EOF'
# CARDIO-CHAT — CANON

version: 2026-03

---

## Axiom

**CardioChat serves cardiology with governed AHA/ACC INTEL. Every recommendation graded. Every interaction audited.**

---

## Constraints

MUST:     Cite AHA/ACC guideline for every cardiovascular recommendation
MUST:     Include evidence grade (Class I/IIa/IIb/III) for every recommendation
MUST:     Log every interaction to LEDGER with timestamp and actor
MUST:     Version evidence base with AHA/ACC publication date
MUST:     Maintain PHI boundary — no patient identifiers in governance metadata
MUST NOT: Generate uncited cardiovascular recommendations
MUST NOT: Override cardiologist clinical judgment
MUST NOT: Process PHI outside the local deployment perimeter
MUST NOT: Provide dosing recommendations without weight-based calculation source

---

EOF

Verify the CANON.md structure. Every CANON.md must have: (1) a header with the scope name, (2) an inherits: line, (3) a ## Axiom section with a bold sentence, (4) a ## Constraints section with MUST/MUST NOT entries, and (5) a footer. Missing any of these triggers a validation error.

Step 2: VOCAB.md. Define every SCREAMING_CASE term the scope uses. Start with terms from CANON.md and add clinical terminology.

cat > VOCAB.md << 'EOF'
# VOCAB

| Term | Definition |
|------|-----------|
| CARDIO-CHAT | Governed clinical TALK agent serving cardiology queries with AHA/ACC evidence |
| AHA | American Heart Association — publisher of cardiovascular clinical guidelines |
| ACC | American College of Cardiology — co-publisher of cardiovascular clinical guidelines |
| INTEL | Governed knowledge unit with provenance — source, date, evidence grade, citation |
| PHI | Protected Health Information as defined by HIPAA §160.103 |
| LEDGER | Append-only audit trail — every governed event recorded with timestamp and actor |
| EVIDENCE-GRADE | AHA/ACC classification: Class I (benefit >>> risk), IIa (benefit >> risk), IIb (benefit >= risk), III (no benefit or harm) |
| STEMI | ST-Elevation Myocardial Infarction — time-critical cardiac event requiring immediate intervention |
| NSTEMI | Non-ST-Elevation Myocardial Infarction — acute coronary syndrome without ST elevation |
| ASCVD | Atherosclerotic Cardiovascular Disease — primary prevention target for statin therapy |

---

EOF

Every term must have a precise definition. Not a stub. Not a circular reference. Not “Governed term.” The definition must be specific enough that two independent readers would derive the same understanding. In clinical contexts, ambiguous terminology produces clinical errors. The VOCAB.md is the defense against ambiguity.

Step 3: README.md. Write the public interface. This is what external consumers see — the hospital’s clinical informatics committee, the EHR integration team, the compliance auditors.

cat > README.md << 'EOF'
# CARDIO-CHAT — Cardiovascular Clinical Decision Support


CardioChat deployment for cardiovascular clinical decision support. Provides governed clinical recommendations backed by AHA/ACC guidelines, with evidence grading (Class I/IIa/IIb/III) for every recommendation. Every interaction is audited on the LEDGER. PHI boundary enforced — no patient identifiers in governance metadata.

## Capabilities

- Cardiovascular risk assessment (ASCVD 10-year risk)
- Guideline-directed medical therapy recommendations
- Acute coronary syndrome triage guidance (STEMI/NSTEMI)
- Heart failure management (HFrEF/HFpEF staging)
- Anticoagulation management (AF, VTE)

## Limitations

- Does not replace cardiologist clinical judgment
- Does not provide dosing without weight-based calculation source
- Does not process PHI outside deployment perimeter

---

EOF

Step 4: Validate.

git add CANON.md VOCAB.md README.md
git commit -m "GOV: bootstrap CARDIO-CHAT — TRIAD"
magic validate

Expected output:

CARDIO-CHAT: 35/255 (COMMUNITY)
  D: PASS  — CANON.md present, axiom valid
  E: PASS  — VOCAB.md present, 10 terms, 0 stubs
  T: FAIL  — ROADMAP.md missing
  R: FAIL  — CARDIO-CHAT.md missing
  O: FAIL  — COVERAGE.md missing
  S: PASS  — inherits: valid, axiom present, constraints present
  L: FAIL  — LEARNING.md missing
  LANG: FAIL — LANGUAGE not inherited

Score 35. COMMUNITY tier. The TRIAD is complete. The scope exists and is governed. Now build upward.

2.8 TRIAD Validation Errors and Fixes

The validator produces specific errors for TRIAD problems. Here is the complete error catalog for the three files ⁶:

CANON.md errors:

VOCAB.md errors:

README.md errors:

When magic validate reports errors, fix them in order: CANON.md first, VOCAB.md second, README.md third. The validator processes files in this order because CANON.md establishes the evaluation context, VOCAB.md defines the terms CANON.md uses, and README.md describes the interface CANON.md constrains.

2.9 VOCAB.md: The Type System in Practice

VOCAB.md is not a glossary — it is a type system. Every SCREAMING_CASE term in the scope is a type, and the definition is its specification. The validator checks type consistency across all files in the scope ⁷.

Here is how the type-checking works: the validator extracts every SCREAMING_CASE token from every file in the scope — CANON.md, README.md, COVERAGE.md, LEARNING.md, INTEL.md, SHOP.md — then resolves each token against VOCAB.md (local scope first, then the inherited VOCAB.md chain). An unresolved token is a type error.

ERROR: CANON.md line 12 — Undefined term: ASCVD
  Term "ASCVD" used in constraints but not defined in VOCAB.md
  Fix: Add ASCVD definition to VOCAB.md
  Hint: Check inherited VOCAB.md — term may be defined in parent scope

The inheritance chain applies to VOCAB.md as well. If the parent scope defines INTEL in its VOCAB.md, the child scope does not need to redefine INTEL — it inherits the definition. But if the child scope uses INTEL with a different meaning than the parent, the child must override the definition in its own VOCAB.md. The override is explicit. The validator detects when a child redefines a parent term and flags it as a warning (not an error — overrides are permitted but should be intentional).

WARN: VOCAB.md — Term "INTEL" overrides parent definition.
  Parent (hadleylab-canonic/MAGIC/VOCAB.md): "Governed knowledge unit with provenance"
  Child (CARDIO-CHAT/VOCAB.md): "AHA/ACC governed knowledge unit"
  This override narrows the parent definition. Verify this is intentional.

The type system prevents a category of errors that plagues traditional clinical AI deployments: term collision. When Hospital A’s “SCREENING” means population-level mammography and Hospital B’s means any diagnostic imaging, a federated system without vocabulary governance silently mixes the two meanings. VOCAB.md prevents this — each hospital’s scope defines “SCREENING” precisely, and the validator detects the collision when the federation scope attempts to inherit both definitions.

2.10 README.md: The Public API

Think of README.md as a header file. It declares what the scope offers without exposing implementation details. Other scopes, integration teams, compliance auditors, and clinical informatics committees read it to understand what the scope does and how to interact with it ⁵.

Three sections:

1. Description: What the scope does. One paragraph. No jargon beyond what VOCAB.md defines.
2. Capabilities: What the scope offers. Bulleted list. Each capability maps to a constraint in CANON.md.
3. Limitations: What the scope does NOT do. Bulleted list. Each limitation maps to a MUST NOT in CANON.md.

Capabilities and limitations are not documentation — they are the public API contract. When another scope inherits from yours, README.md is the interface specification. When a FHIR integration connects to a clinical TALK agent, README.md describes what the agent can and cannot do.

In clinical AI deployments, README.md also serves a regulatory function: it is the product description the committee reviews during the AI governance approval process. The committee does not need CANON.md (the internal contract) or VOCAB.md (the internal type system). They read README.md — the external interface description. Internal governance versus external interface: the TRIAD enforces that separation architecturally, not bureaucratically.

2.11 The TRIAD Completeness Theorem

The TRIAD covers the three essential governance questions — and nothing more:

Leave any of these unanswered and governance is incomplete. CANON.md without VOCAB.md gives you a contract with ambiguous terms — unenforceable because its vocabulary is undefined. VOCAB.md without CANON.md gives you defined terms describing nothing. README.md without CANON.md gives you a public interface making promises that no contract enforces.

The TRIAD is the minimum, not the maximum. A scope at COMMUNITY tier (35/255) has only the TRIAD plus structural governance (inherits: + axiom + constraints). A scope at FULL (255/255) adds ROADMAP.md, {SCOPE}.md, COVERAGE.md, LEARNING.md, and LANGUAGE inheritance. Everything else accumulates on the TRIAD foundation.

2.12 TRIAD Anti-Patterns

The empty VOCAB.md. Zero terms defined. The file exists, so the proof question gets partial credit, but the validator flags the empty table. Every scope uses at least one SCREAMING_CASE term — the scope name itself. Define it.

The copy-paste README.md. Copying the parent’s README.md verbatim into the child. The child’s README.md must describe the child’s interface, not the parent’s. MammoChat describes breast imaging capabilities, not the TALK service’s generic conversation features.

The prose CANON.md. Writing CANON.md as a narrative instead of a structured governance file. Its structure is fixed: header, inherits, axiom, constraints, footer. Prose belongs in README.md. Policy narratives belong in {SCOPE}.md. CANON.md is compiler input — write it like code.

The undeclared term. Using SCREAMING_CASE terms in CANON.md that are not in VOCAB.md. Every MUST: Cite INTEL source requires INTEL to be defined. Every MUST NOT: Process PHI requires PHI to be defined. The validator catches this — fix it before committing.

# Check for undefined terms before committing
magic validate --verbose | grep "Undefined term"

The disconnected README.md. Describing capabilities not declared in CANON.md. If README.md says “provides dosing recommendations” but CANON.md has MUST NOT: Provide dosing recommendations, the validator detects the contradiction. README.md is the public interface of the CANON.md contract — the two must be consistent.

Three files. Write them correctly, write them in order, write them first. Everything in CANONIC builds on this foundation. Chapter 5 walks through writing these files from scratch, and Chapter 6 covers how scopes accumulate additional governance files to reach 255. For the governance policy rationale behind the TRIAD, see The Canonic Canon, Chapter 2.

Chapter 3: The Inheritance Chain

Most governance systems rely on humans reading policy documents and remembering to follow them. CANONIC replaces that with a single line — inherits: — that is a binding obligation, not metadata. Write it, and the compiler resolves and enforces every constraint in your parent’s governance chain, all the way to the root ⁸.

3.1 Syntax

This line says: “I accept all governance constraints from hadleylab-canonic/PAPERS.” Not a reference. Not a dependency. A binding obligation — the scope declares that it satisfies every constraint in its parent’s governance chain, from the parent all the way to the root.

3.2 Resolution

When magic validate runs:

1. Read the inherits: line.
2. Walk the chain upward to root.
3. Collect all constraints at every level.
4. Verify the target scope satisfies every collected constraint.
5. Broken link or violated constraint = compilation error ⁸.

Resolution is deterministic. The same inherits: chain always produces the same constraint set. The validator does not use heuristics, does not make judgments, does not apply discretion. It resolves the chain, collects the constraints, and checks them. Pass or fail. 255 or less.

The practical consequence: when your MammoChat deployment inherits from hadleylab-canonic/MAGIC/SERVICES/TALK, every constraint in the TALK service’s governance chain — from TALK to SERVICES to MAGIC to hadleylab-canonic to canonic-canonic — is collected and enforced on your deployment. If the root declares “MUST: Validate to 255 before production deployment,” your deployment inherits that obligation. No exceptions. No overrides.

3.3 Monotonic Accumulation

A child scope can add constraints beyond its parent. It cannot remove or weaken them. This is the Liskov Substitution Principle applied to governance: a subtype extends but never violates the parent contract ⁸.

The parent’s governance score is the floor. The child’s score = floor + whatever the child adds.

In a hospital network, this means root governance — HIPAA compliance, PHI boundary enforcement, LEDGER recording — cannot be weakened by any hospital in the network. A hospital can add constraints: state-specific regulations, site-specific PHI handling, local IRB requirements. It cannot remove them. The network’s governance floor is architecturally enforced.

This is what makes the model compelling for hospital CISOs: the governance floor is not a policy that humans must remember to follow. It is a constraint the validator enforces automatically. A department cannot deploy a clinical AI that violates the hospital’s governance floor, because the validator will reject it. The inheritance chain IS the access control.

3.4 Three Forms of Inheritance

Only LANGUAGE, MAGIC, and GOV paths may be hardcoded. Everything else is compiled ⁷.

3.5 The Root

The root of the entire system is canonic-canonic. It defines the fundamental primitives (INTEL, CHAT, COIN), service composition, tier algebra, and the validation framework (MAGIC). Every organization inheriting from it accepts these foundational constraints ⁸.

canonic-canonic (root — LUCA)
  └── hadleylab-canonic (organization)
        └── DEXTER (author scope)
        │     └── PAPERS (domain)
        │           └── governance-as-compilation (leaf scope)
        └── MAGIC (governance engine)
              └── SERVICES (service tree)
                    └── TALK (conversation service)
                          └── MAMMOCHAT (product)

In evolutionary biology, the root is the Last Universal Common Ancestor (LUCA). In CANONIC, canonic-canonic is the LUCA — the ancestor from which every governed scope descends. The parallel is structural, not metaphorical. The inheritance chain proves descent. The constraint propagation proves homology. The 255-bit score proves fitness ⁹.

3.6 Cross-Organization Inheritance

Organizations inherit from the root. The inheritance chain crosses GitHub org boundaries:

canonic-canonic               (org: canonic-canonic)
  └── hadleylab-canonic       (org: hadleylab-canonic)
  └── adventhealth-canonic    (org: adventhealth-canonic)
  └── canonic-python          (org: canonic-python)

Each org is a monophyletic clade — a complete branch descended from a single ancestor. The inherits: chain proves the descent ⁹.

Cross-organization inheritance is the federation model. Hospital A and Hospital B both inherit from the network root. The network root inherits from canonic-canonic. The governance chain crosses organizational boundaries while maintaining constraint propagation. Hospital A’s deployment inherits the network’s HIPAA constraints, Hospital A’s site-specific constraints, the TALK service’s clinical constraints, and the root’s foundational constraints — all resolved, collected, and enforced at validation time.

3.7 The Healthcare Inheritance Tree

A realistic healthcare deployment creates an inheritance tree that looks like this:

canonic-canonic                          (root)
  └── hadleylab-canonic                  (organization)
        └── MAGIC/SERVICES/TALK          (TALK service)
              └── MAMMOCHAT              (product)
                    └── MAMMOCHAT-UCF    (hospital deployment)
                    └── MAMMOCHAT-ADVENT (hospital deployment)

Each level adds constraints:

• canonic-canonic: Foundational primitives, validation framework
• hadleylab-canonic: Organization-specific governance
• TALK: Conversation service constraints (systemPrompt, disclaimer, PHI boundary)
• MAMMOCHAT: Product constraints (BI-RADS evidence, imaging INTEL)
• MAMMOCHAT-UCF: Site constraints (UCF IRB requirements, Florida state regulations)

The constraint set at each leaf is the union of all ancestor constraints. No leaf can weaken any ancestor’s constraint. Build the tree correctly, and the governance follows.

3.8 Building an Inheritance Chain: Step-by-Step

This walkthrough builds a three-level inheritance chain: organization, service, and deployment. Each level adds constraints. The validator enforces the entire chain ⁸.

Level 1: Organization scope. Create the organization root.

mkdir -p myhealth-canonic/MAGIC/SERVICES
cd myhealth-canonic

cat > CANON.md << 'EOF'
# MYHEALTH — CANON

version: 2026-03

---

## Axiom

**MyHealth governs clinical AI deployments with MAGIC compliance. Every scope validated. Every event audited.**

---

## Constraints

MUST:     Validate every scope to 255 before production deployment
MUST:     Maintain PHI boundary per HIPAA §164.312
MUST:     Record every governance event on LEDGER
MUST:     Inherit from canonic-canonic/MAGIC for all services
MUST NOT: Deploy clinical AI without ENTERPRISE tier minimum
MUST NOT: Process PHI outside organizational perimeter
MUST NOT: Bypass validation for any deployment

---

EOF

Level 2: Service scope. Create the TALK service under the organization.

mkdir -p MAGIC/SERVICES/TALK
cd MAGIC/SERVICES/TALK

cat > CANON.md << 'EOF'
# TALK — CANON

version: 2026-03

---

## Axiom

**TALK serves clinical conversations with governed INTEL. Every response cited. Every session audited.**

---

## Constraints

MUST:     Include systemPrompt with scope identity and disclaimer
MUST:     Cite evidence source for every clinical recommendation
MUST:     Log every session to LEDGER with session ID and timestamp
MUST:     Display disclaimer before first clinical interaction
MUST NOT: Generate uncited clinical recommendations
MUST NOT: Claim to replace clinical judgment
MUST NOT: Store session content beyond audit retention period

---

EOF

Level 3: Deployment scope. Create the specific hospital deployment.

mkdir -p MAMMOCHAT-REGIONAL
cd MAMMOCHAT-REGIONAL

cat > CANON.md << 'EOF'
# MAMMOCHAT-REGIONAL — CANON

version: 2026-03

---

## Axiom

**MammoChat-Regional serves Regional Hospital breast imaging with governed BI-RADS INTEL. Every recommendation cited. Every interaction audited.**

---

## Constraints

MUST:     Cite BI-RADS category for every screening assessment
MUST:     Reference ACR BI-RADS Atlas 5th Edition for classification
MUST:     Comply with Florida Statute 404.22 radiation safety
MUST:     Include Regional Hospital disclaimer per legal dept. template
MUST NOT: Recommend biopsy without BI-RADS 4+ classification
MUST NOT: Override radiologist clinical judgment

---

EOF

Validate the chain.

magic validate --scope myhealth-canonic --recursive

Expected output:

myhealth-canonic: 35/255 (COMMUNITY)
  Chain: canonic-canonic → myhealth-canonic
  Constraints collected: 7 (org) + inherited (root)

myhealth-canonic/MAGIC/SERVICES/TALK: 35/255 (COMMUNITY)
  Chain: canonic-canonic → myhealth-canonic → TALK
  Constraints collected: 7 (service) + 7 (org) + inherited (root)

myhealth-canonic/MAGIC/SERVICES/TALK/MAMMOCHAT-REGIONAL: 35/255 (COMMUNITY)
  Chain: canonic-canonic → myhealth-canonic → TALK → MAMMOCHAT-REGIONAL
  Constraints collected: 6 (deployment) + 7 (service) + 7 (org) + inherited (root)

The validator reports the full chain for each scope. The constraint count accumulates upward. MAMMOCHAT-REGIONAL inherits every constraint from every ancestor — root, organization, service, and its own. The total constraint set is the union. No constraint is lost. No constraint is weakened.

3.9 Inheritance Errors and Resolution

The validator produces specific errors for inheritance problems. Here is the error catalog ⁶:

The most common error in practice is inherits: unresolvable — a developer typed the wrong path. The fix is mechanical:

# Check if the parent scope exists
ls -la $(magic resolve-path hadleylab-canonic/MAGIC/SERVICES/TALK)/CANON.md

# If not found, the inherits: path is wrong. List available scopes:
magic scan --scopes | grep TALK

The second most common is Constraint violation: child weakens parent — a child adds a MUST NOT that contradicts an inherited MUST. For example, the parent says MUST: Log every interaction to LEDGER and the child says MUST NOT: Log interactions for privacy. The child cannot weaken the parent. Either modify the child’s constraint to comply, or negotiate a change at the parent level.

ERROR: MAMMOCHAT-REGIONAL/CANON.md
  Constraint violation: child weakens parent
  Parent (TALK): MUST: Log every session to LEDGER
  Child: MUST NOT: Log clinical sessions
  Fix: Remove "MUST NOT: Log clinical sessions" from child
  Note: If the parent constraint is wrong, fix it at the parent level.
        Child scopes cannot weaken parent constraints.

3.10 Constraint Propagation Mechanics

When the validator collects constraints from the inheritance chain, it applies three rules ⁸:

Rule 1: Union. All MUST constraints from all ancestors are collected into a single set. The child must satisfy every MUST in the union.

Rule 2: Monotonic. MUST NOT constraints can only be added by children, never removed. If the root says MUST NOT: Process PHI externally, every descendant inherits that prohibition.

Rule 3: Specificity. When a child adds a constraint that is more specific than a parent constraint, both apply. The parent says MUST: Cite evidence. The child says MUST: Cite BI-RADS evidence. The child must cite BI-RADS evidence (specific) AND cite evidence generally (parent). The specific constraint does not replace the general constraint — it adds to it.

These three rules produce deterministic constraint resolution. Given the same inheritance chain, the validator always produces the same constraint set. No human judgment, no discretion, no exceptions.

3.11 Practical Inheritance Patterns

Pattern 1: The Service Specialization. A common pattern in clinical AI governance. The TALK service defines general conversation constraints. Each clinical TALK agent specializes by adding domain-specific constraints.

SERVICES/TALK/CANON.md
  MUST: Include systemPrompt with disclaimer
  MUST: Cite evidence for recommendations

SERVICES/TALK/MAMMOCHAT/CANON.md
  inherits: SERVICES/TALK
  MUST: Cite BI-RADS category (adds to parent's general evidence citation)
  MUST: Reference ACR BI-RADS Atlas (adds specific evidence source)

SERVICES/TALK/ONCOCHAT/CANON.md
  inherits: SERVICES/TALK
  MUST: Cite NCCN guideline version (adds to parent's general evidence citation)
  MUST: Include cancer staging in recommendations (adds domain-specific requirement)

Both agents inherit TALK’s general constraints, add domain-specific requirements, and satisfy the full constraint union without weakening the parent.

Pattern 2: The Multi-Site Deployment. A single product deployed across multiple hospitals. Each hospital adds site-specific constraints.

MAMMOCHAT/CANON.md
  MUST: Cite BI-RADS category
  MUST NOT: Process PHI outside deployment perimeter

MAMMOCHAT/MAMMOCHAT-UCF/CANON.md
  inherits: MAMMOCHAT
  MUST: Comply with UCF IRB protocol #2026-001
  MUST: Include UCF College of Medicine disclaimer

MAMMOCHAT/MAMMOCHAT-ADVENT/CANON.md
  inherits: MAMMOCHAT
  MUST: Comply with AdventHealth system-wide AI governance policy
  MUST: Include faith-based care statement per AdventHealth policy

Each hospital deployment inherits the product’s constraints and adds site-specific requirements — UCF adds IRB compliance, AdventHealth adds organizational policy — without weakening the core constraints (BI-RADS citation, PHI boundary).

Pattern 3: The Cross-Organization Federation. Multiple organizations inherit from the same root. Each organization maintains independent governance within the shared constraint framework.

canonic-canonic/CANON.md
  MUST: Validate to 255 before production
  MUST: Record every event on LEDGER

hadleylab-canonic/CANON.md
  inherits: canonic-canonic
  MUST: Academic research governance (IRB, publication ethics)

adventhealth-canonic/CANON.md
  inherits: canonic-canonic
  MUST: HIPAA compliance per AdventHealth system policy
  MUST: Faith-based care governance

Both organizations inherit the root’s foundational constraints and add their own. The federation is the shared constraint floor; organizations build on top of it.

3.12 Debugging Inheritance Problems

When a scope fails validation due to inheritance issues, follow this debugging procedure:

# Step 1: Print the full inheritance chain
magic validate --scope MAMMOCHAT-REGIONAL --chain
# Output: canonic-canonic → myhealth-canonic → TALK → MAMMOCHAT-REGIONAL

# Step 2: Validate each ancestor individually
magic validate --scope canonic-canonic
magic validate --scope myhealth-canonic
magic validate --scope myhealth-canonic/MAGIC/SERVICES/TALK

# Step 3: Identify which ancestor introduced the failing constraint
magic validate --scope MAMMOCHAT-REGIONAL --verbose | grep "FAIL"

# Step 4: Check constraint origin
magic validate --scope MAMMOCHAT-REGIONAL --constraint-origin "MUST: Log every session"
# Output: Constraint "MUST: Log every session" originated at myhealth-canonic/MAGIC/SERVICES/TALK

Walk the chain from root to leaf. At each step, the validator reports the constraint set. The step where the constraint count changes is the step where the failing constraint was introduced. Fix it at the origin and the fix propagates downward to all descendants.

The inheritance chain is the backbone of CANONIC governance. Build the chain correctly, and the governance follows. For the theoretical basis, see Chapter 36 (Governance as Type System) and Chapter 37 (Governance as Compiler), which prove that inheritance corresponds to subtyping in programming language theory.

3.13 Inheritance Performance and Depth Limits

Inheritance chains resolve in O(d) time, where d is the chain depth. In practice, depth rarely exceeds 6 levels:

The validator caches resolved constraint sets per session. Once it resolves hadleylab-canonic/MAGIC/SERVICES/TALK, every child scope that inherits from TALK reuses the cached result. A health network with 50 deployments all inheriting from TALK resolves that constraint set once, not 50 times.

# Profile inheritance resolution
magic validate --scope MAMMOCHAT-UCF --profile
# Chain resolution:
#   canonic-canonic: 4 constraints (cached)
#   hadleylab-canonic: 7 constraints (cached)
#   MAGIC/SERVICES/TALK: 7 constraints (cached)
#   MAMMOCHAT: 6 constraints (resolved)
#   MAMMOCHAT-UCF: 5 constraints (resolved)
# Total: 29 constraints collected in 3.2ms

3.14 Inheritance and the _generated Contract

The inherits: chain interacts with the _generated contract (as described in Chapter 26). When the build pipeline compiles .md governance files into .json runtime artifacts, the compiler resolves the inheritance chain and embeds the full constraint set in the compiled output:

CANON.md (source, inherits: hadleylab-canonic/MAGIC/SERVICES/TALK)
  → build pipeline resolves inheritance chain
    → collects constraints from all ancestors
      → compiles to CANON.json (output, contains full constraint set)

The compiled CANON.json contains resolved constraints from every ancestor. The runtime reads the compiled artifact instead of re-resolving the chain — O(1) constraint lookup at runtime, full chain walk at compile-time.

If the compiled CANON.json contains an incorrect constraint, do not edit it. It is _generated. Fix the CANON.md source or the ancestor’s constraints, run build, and the pipeline recompiles. The fix propagates.

3.15 Multi-Fleet Inheritance

When CANONIC is deployed across multiple organizations (fleets), inheritance crosses fleet boundaries via cross-fleet references:

canonic-canonic/MAGIC                    ← Fleet A (root)
  └── hadleylab-canonic/MAGIC/SERVICES   ← Fleet B (org A)
  └── adventhealth-canonic/MAGIC/SERVICES← Fleet C (org B)

Both Fleet B and Fleet C inherit from Fleet A. Cross-fleet inheritance resolves at build time by cloning the parent fleet’s governance files as git submodules, ensuring the parent’s constraints are versioned — each child fleet pins a specific commit. Updating the parent requires an explicit submodule bump and revalidation.

# Update parent fleet reference
cd hadleylab-canonic
git submodule update --remote canonic-canonic
magic validate --recursive --strict
# If all scopes pass: commit the submodule bump
git commit -m "GOV: bump canonic-canonic — updated root constraints"

The submodule bump is itself a governance event. The pre-commit hook validates all scopes against the updated parent constraints, and if any scope fails, the bump is blocked. Fix your governance before adopting the parent’s updates.

3.16 Inheritance Anti-Patterns

Avoid these common mistakes:

Diamond inheritance. Scope D inherits from both B and C, which both inherit from A. CANONIC does not support multiple inheritance — each scope has exactly one inherits: directive. If you need constraints from two parents, create a common ancestor.

Phantom inheritance. Writing inherits: hadleylab-canonic/MAGIC when the scope uses no constraints from MAGIC. Do not inherit from a scope whose constraints you do not intend to satisfy.

Stale inheritance. Inheriting from a scope that has been archived or renamed. Run magic validate to detect broken chains — it reports inherits: unresolvable with the exact fix.

Deep inheritance. Chains deeper than six levels without operational justification. Each level adds debugging complexity. The practical test: can a new developer trace the full chain in under two minutes? If not, flatten the hierarchy by merging intermediate scopes. Deep chains are not wrong — they are expensive, and the cost is paid in debugging time when a constraint violation surfaces at a leaf and you must walk six ancestors to find the origin. Keep the chain as shallow as the domain permits. For multi-organization federation across inheritance chains, see Chapter 9. For the governance policy perspective on inheritance, see The Canonic Canon, Chapter 3.

Chapter 4: The Eight Dimensions

Governance frameworks typically measure compliance with checklists that grow without bound. CANONIC measures it with eight questions. Each is binary — answered or not. Together they produce a single score: 0 to 255, the full range of an 8-bit unsigned integer. You either satisfy a dimension or you do not, and the score is a mathematical fact, not an assessment.

4.1 The Dimensions

Each question is binary: answered or not. The score is a bitmask — the sum of all answered questions. The math is in the C kernel (magic.c); the governance is in the files ⁶.

4.2 The Score

255 is the state in which all eight governance questions are answered simultaneously. 0 means none are. The kernel computes the score deterministically from the governance files present in the scope ¹⁰.

There is no human judgment in the scoring. No discretion. No “close enough.” The files exist or they do not. The structures are present or they are not. The same governance files always produce the same score.

4.3 Compliance Tiers

Tiers are cumulative. You cannot skip dimensions. BUSINESS requires COMMUNITY. AGENT requires ENTERPRISE ⁶.

The tiers map directly to clinical AI deployment readiness. COMMUNITY means you have declared your purpose and defined your terms, but you have no roadmap, no coverage assessment, and no production readiness. It is a research prototype.

ENTERPRISE adds history (ROADMAP.md) and operational self-assessment (COVERAGE.md) — the minimum tier for clinical deployment. The compliance committee can review coverage, and the roadmap shows governance trajectory.

AGENT adds LEARNING.md — accumulated intelligence from governance events. The scope learns from its operation and starts providing continuous quality improvement signals, not just serving clinical queries.

FULL (255) adds language governance — the scope expresses itself in a controlled vocabulary inherited from the LANGUAGE standard. Production-grade clinical AI: fully governed, fully documented, fully auditable.

4.4 Clinical Dimension Mapping

Each dimension maps to specific healthcare compliance requirements:

Build a scope to 255 and you simultaneously satisfy governance requirements across every major healthcare compliance standard. The dimensions themselves are not healthcare-specific — they are universal governance dimensions — but in healthcare, each one maps to specific regulatory requirements. The mapping is structural, not approximate.

4.5 COVERAGE.md

COVERAGE.md answers the eight questions explicitly. One question per dimension. PASS or FAIL per question. The validator cross-references COVERAGE.md against actual file presence ⁶.

# COVERAGE

| # | Question | Answer | Status |
|---|----------|--------|--------|
| 1 | What do you believe? | MammoChat serves breast imaging with governed BI-RADS INTEL | PASS |
| 2 | Can you prove it? | VOCAB.md: 47 clinical terms defined, zero stubs | PASS |
| 3 | Where are you going? | ROADMAP.md: Q1 expand evidence base, Q2 add diagnostic mode | PASS |
| 4 | Who are you? | MAMMOCHAT-UCF.md: scope description, evidence chain, citations | PASS |
| 5 | How do you work? | This file — operational coverage assessment | PASS |
| 6 | What shape are you? | inherits: hadleylab-canonic/MAGIC/SERVICES/TALK, axiom present | PASS |
| 7 | What have you learned? | LEARNING.md: 12 governance events logged, 3 patterns captured | PASS |
| 8 | How do you express? | LANGUAGE: inherits canonic-canonic/LANGUAGE | PASS |

Score: 255/255

COVERAGE.md is not documentation — it is a self-assessment that the validator verifies. If COVERAGE.md claims PASS for dimension D but CANON.md does not exist, the validator catches the discrepancy. The scope claims its own compliance; the validator audits the claim.

4.6 Kernel Internals

The bit weights, hex values, and tier boundary calculations are kernel internals, implemented in the C binary (magic.c) and not published in governance prose ². Tier names, dimension names, and composition formulas are public. The scoring algorithm is public. The bit-weight assignments are private.

Do not attempt to reverse-engineer the bit weights from the tier scores. You do not need to know the register allocation strategy of gcc to write C programs, and you do not need to know the bit weights of magic.c to build governed scopes. Write the files. Run magic validate. The score is the result.

4.7 Dimension-by-Dimension Walkthrough

Each dimension has specific requirements, specific evidence files, and specific failure modes. This section walks through every dimension with the detail a developer needs to satisfy it ⁶.

Question 1: “What do you believe?”

This question checks for a valid CANON.md. The requirements:

The first question is the gate. Without it, no other question can be evaluated. A scope without CANON.md scores 0 because the validator has no axiom to evaluate against.

# Check first question specifically
magic validate --verbose
# Output: Q1: PASS — CANON.md present, axiom valid, 5 constraints

Question 2: “Can you prove it?”

This question checks for a valid VOCAB.md. The requirements:

Undefined clinical terms create patient safety risks. A scope that uses “SCREENING” without defining whether it means population-level or diagnostic screening introduces clinical ambiguity that propagates to patient care.

# Check proof question and list all terms
magic validate --question 2 --verbose
# Output: Q2: PASS — VOCAB.md present, 12 terms, 0 stubs, 0 undefined

Question 3: “Where are you going?”

This question checks for ROADMAP.md. The requirements:

ROADMAP.md answers the transparency question: where is this scope going? It is the governance trajectory document the compliance committee reviews quarterly — what governance work has been completed, what is in progress, and what is planned.

# MAMMOCHAT — ROADMAP


## Done
- GOV: TRIAD created. COMMUNITY tier achieved.
- GOV: COVERAGE + SPEC + ROADMAP. ENTERPRISE tier achieved.
- GOV: LEARNING.md. AGENT tier achieved.
- GOV: LANGUAGE inherited. FULL (255) achieved.

## Now
- Evidence base update: BI-RADS Atlas 6th Edition integration.
- Site deployment: MAMMOCHAT-REGIONAL for Regional Hospital.

## Next
- FDA pre-submission for clinical decision support classification.
- Multi-site federation: connect 5 hospital deployments via GALAXY.

---

Question 4: “Who are you?”

This question checks for {SCOPE}.md — the scope specification file. The requirements:

The scope specification file is the scope’s identity document — subject, audience, evidence base, and status. It answers “who are you?” within the governance tree.

# MAMMOCHAT


## Scope Intelligence

| Dimension | Value |
|-----------|-------|
| Subject | Breast imaging clinical decision support |
| Audience | Radiologists, breast surgeons, primary care physicians |
| Evidence | ACR BI-RADS Atlas 5th Edition, NCCN Breast Cancer Screening Guidelines |
| Status | Production — 3 hospital deployments, 255/255 compliance |
| Contact | Clinical informatics team — mammochat@hadleylab.org |

---

Question 5: “How do you work?”

This question checks for COVERAGE.md. The requirements:

COVERAGE.md claims compliance status for each question; the validator audits those claims against the actual files. A scope cannot lie in its COVERAGE.md — the validator catches every discrepancy.

Question 6: “What shape are you?”

This question is composite. It checks three structural requirements simultaneously:

This question is partially satisfied by the same file that answers question 1 (CANON.md). This is intentional — a CANON.md with an axiom and constraints answers both “what do you believe?” and “what shape are you?” simultaneously. The overlap means that a scope with only CANON.md can answer two questions at once.

Question 7: “What have you learned?”

This question checks for LEARNING.md. The requirements:

This is the dimension that separates ENTERPRISE from AGENT. Without LEARNING.md, a scope is compliant but static. With it, the scope captures operational knowledge and evolves.

Question 8: “How do you express?”

This question checks for LANGUAGE governance inheritance. The requirements:

This is the final gate to 255. It requires the scope to inherit from the LANGUAGE standard — the controlled vocabulary that governs how the scope expresses itself. This is the most demanding question because it requires the scope to adopt a shared expression framework, not just define its own terms.

4.8 Score Arithmetic Examples

The C kernel assigns each question a weight and sums the satisfied weights. The specific weights are implementation details of magic.c ¹⁰.

No hidden weighting. No curve. No partial credit within a question. Each is binary — satisfied or not — and the kernel computes the result deterministically.

4.9 Dimension Dependencies

The eight questions have logical (not mechanical) dependencies. The validator does not enforce ordering, but in practice, certain questions require other questions to be meaningful ⁶:

"What do you believe?" ← foundation — required for all others
"Can you prove it?" ← requires belief (terms reference the axiom)
"What shape are you?" ← requires belief (structure is defined in CANON.md)
"Where are you going?" ← requires belief (roadmap references the axiom's trajectory)
"Who are you?" ← requires belief + proof (spec references axiom and terms)
"How do you work?" ← requires all above (COVERAGE references all questions)
"What have you learned?" ← requires mechanism (learning is operational knowledge)
"How do you express?" ← requires all (language governance crowns the scope)

The dependency chain suggests a build order: belief first, then proof and shape (simultaneously — they share CANON.md), then timeline and identity, then mechanism, then learning, then expression. This is the order Chapter 5 follows in the “Your First 255” walkthrough. For the theoretical underpinning of these dimensions as a type system, see Chapter 36. For the magic validate toolchain that computes the score, see Chapter 42.

4.10 Dimension Gaps: Diagnosis and Repair

When magic validate reports a score below 255, the gap is the set of unanswered questions. Diagnose the gap. Repair it. Revalidate.

magic validate --scope MAMMOCHAT --gaps

Output:

MAMMOCHAT: 127/255 (AGENT)
  Answered: 7 of 8 questions
  Missing: "How do you express?" — LANGUAGE not inherited
  Fix: Add LANGUAGE inheritance to CANON.md inherits: chain
  Cost: 128 COIN to close (from 127 to 255)

The gap diagnosis tells you exactly what is missing, why, and how to fix it. The cost tells you how much COIN the fix will mint. When you report to the compliance committee, the gap report IS the governance improvement plan.

Common gap patterns:

The fix for every gap is the same: create the missing file with the required structure, run magic validate, watch the score increase, and commit. Governance improves monotonically.

4.11 Dimension Validation Quick Reference

Use this quick reference when debugging specific dimension failures:

# Validate a single dimension and get remediation instructions
magic validate --dimension D --remediate
magic validate --dimension E --remediate
magic validate --dimension L --remediate

Each remediation command outputs the exact file to create, the exact structure required, and the expected score increase upon completion. Run the dimension-specific validation before running the full magic validate to isolate failures efficiently. For a complete walkthrough of dimension-by-dimension remediation, see Chapter 45 (Validation Errors and Healing). For the governance policy perspective on these eight questions, see The Canonic Canon, Chapter 4.

Chapter 5: Your First 255

Zero to FULL in one session. This chapter walks you through building a governed clinical AI scope from scratch — starting with an empty directory and ending with a fully validated 255-bit scope that satisfies healthcare compliance requirements by architecture, not by committee sign-off. The theoretical insight behind this walkthrough — that governance is compilation, and 255 is the compiled target — is developed fully in Chapters 36-37. For the governor’s perspective on the same journey, see The Canonic Canon, Chapter 2 ¹¹.

The governance-first save

Before you start, consider what happens when governance comes first. A developer sits down to build a clinical recommendation engine. Instead of writing code, she opens CANON.md and writes the axiom: “RecEngine serves oncology with governed NCCN INTEL. Every recommendation cited.” Then she derives the constraints — and one of them reads: MUST: Cite evidence source for every recommendation. She starts sketching the architecture and realizes: the third-party evidence API she planned to use does not return citation metadata in its response payload. There is no source field, no DOI, no guideline reference. The API returns recommendation text only.

Without the governance file, she would have discovered this three weeks into implementation — after building the integration, writing the tests, and deploying to staging. With the governance file, she discovers it before writing a single line of code. The axiom’s constraint — “every recommendation cited” — exposed an architectural gap in the upstream API. She switches to an evidence source that includes citation metadata, and the architecture is sound from day one.

That is the governance-first save. The CANON.md caught a structural problem that no amount of testing would have surfaced until production. Now let’s build one together.

5.1 Create the Scope

You are going to build a governed scope for a clinical TALK agent — a MedChat deployment at a community hospital. The scope inherits from the TALK service governance and adds site-specific clinical constraints.

mkdir -p MEDCHAT-COMMUNITY
cd MEDCHAT-COMMUNITY

5.2 Write the TRIAD

You need three foundational files — the TRIAD. Each one follows the governed Markdown structure: header, inherits:, separator, content, separator, footer. Start with the most important one.

CANON.md:

# MEDCHAT-COMMUNITY — CANON


## Axiom

**MedChat serves Community Hospital clinical staff with governed medical INTEL. Every recommendation cited. Every interaction audited.**

---

## Constraints

\```
MUST:     Cite evidence source for every clinical recommendation
MUST:     Log every interaction to LEDGER with timestamp and actor
MUST:     Maintain PHI boundary — no patient identifiers in governance metadata
MUST:     Version evidence base with publication dates
MUST NOT: Generate uncited clinical recommendations
MUST NOT: Process PHI outside the local deployment perimeter
MUST NOT: Override clinician clinical judgment
\```

---

Notice how each constraint traces back to a phrase in the axiom, as described in Chapter 1. “Every recommendation cited” becomes MUST: Cite evidence source. “Every interaction audited” becomes MUST: Log every interaction to LEDGER. If you cannot point to the word in the axiom that justifies a constraint, the constraint does not belong here — or the axiom is incomplete.

VOCAB.md:

# VOCAB

| Term | Definition |
|------|-----------|
| MEDCHAT | General-purpose clinical TALK agent serving medical questions across specialties |
| INTEL | Governed knowledge unit with provenance — source, date, evidence grade, citation |
| PHI | Protected Health Information as defined by HIPAA §160.103 |
| LEDGER | Append-only audit trail — every governed event recorded with timestamp and actor |
| EVIDENCE-BASE | Collection of governed INTEL units backing clinical recommendations |

---

Every SCREAMING_CASE term your scope uses must be defined here — no stubs, no circular definitions. If you wrote PHI in your CANON.md constraints, define PHI in VOCAB.md. The validator will catch you if you don’t.

README.md:

# MEDCHAT-COMMUNITY — Clinical Decision Support


MedChat deployment for Community Hospital clinical staff. Provides governed clinical decision support across medical specialties, backed by evidence-sourced INTEL from clinical reference databases. Every recommendation cites its evidence source. Every interaction is audited on the LEDGER.

---

5.3 First Validation — COMMUNITY Tier

git add CANON.md VOCAB.md README.md
git commit -m "GOV: bootstrap MEDCHAT-COMMUNITY — TRIAD"
magic validate

Your score: ~35. COIN minted: ~35. Tier: COMMUNITY ¹¹.

You have a governed scope. It has declared its purpose, defined its terms, and established its structure — three questions answered. This is minimum viable governance: the scope is on the map. It is not ready for clinical deployment yet, but it exists, and its existence is governed.

5.4 Add Community and Practice — ENTERPRISE Tier

Now you add the files that take your scope from COMMUNITY to ENTERPRISE — the minimum tier for clinical deployment in a hospital setting.

MEDCHAT-COMMUNITY.md (the scope spec):

# MEDCHAT-COMMUNITY


## Scope Intelligence

| Dimension | Value |
|-----------|-------|
| Subject | Clinical decision support for Community Hospital |
| Audience | Hospitalists, NPs, PAs, nurses, pharmacists |
| Evidence | UpToDate, DynaMed, specialty society guidelines |
| Status | Initial deployment |

---

COVERAGE.md (practice coverage):

# COVERAGE

| # | Question | Answer | Status |
|---|----------|--------|--------|
| 1 | What do you believe? | MedChat serves Community Hospital with governed INTEL | PASS |
| 2 | Can you prove it? | VOCAB.md: 5 terms defined, zero stubs | PASS |
| 3 | Where are you going? | ROADMAP.md pending | FAIL |
| 4 | Who are you? | MEDCHAT-COMMUNITY.md: scope description | PASS |
| 5 | How do you work? | This file | PASS |
| 6 | What shape are you? | inherits: TALK service, axiom present | PASS |
| 7 | What have you learned? | LEARNING.md pending | FAIL |
| 8 | How do you express? | LANGUAGE pending | FAIL |

Score: pending validation

ROADMAP.md (transparency):

# MEDCHAT-COMMUNITY — ROADMAP


## Done
- GOV: TRIAD created. COMMUNITY tier achieved.

## Now
- Build to ENTERPRISE tier. Add COVERAGE, SPEC, ROADMAP.

## Next
- Add LEARNING.md. Achieve AGENT tier.
- Deploy to clinical pilot. Collect governance events.

---

git add MEDCHAT-COMMUNITY.md COVERAGE.md ROADMAP.md
git commit -m "GOV: MEDCHAT-COMMUNITY — COVERAGE + SPEC + ROADMAP"
magic validate

Your score climbs. The scope now has reproducibility, operations coverage, and transparency — Tier: ENTERPRISE. This is the minimum for clinical deployment. A compliance committee can review your COVERAGE assessment, the spec describes what the scope does, and the roadmap shows where it is going.

5.5 Add LEARNING — AGENT Tier

Create LEARNING.md — this is where your scope captures what it learns from operation:

# LEARNING


Evidence lane for MEDCHAT-COMMUNITY.

## Patterns

| Date | Signal | Pattern | Source |
|------|--------|---------|--------|
| 2026-02-27 | GOV_FIRST | Governance files created before clinical deployment. | Step 0 |

---

git add LEARNING.md
git commit -m "GOV: MEDCHAT-COMMUNITY — LEARNING"
magic validate

Your score climbs to AGENT tier. The scope now learns from its own operation — governance events are captured as LEARNING patterns, which is where clinical quality improvement begins.

5.6 Final Pass — 255

You are close. Close the vocabulary, fix any structural gaps, add the LANGUAGE inheritance, and make sure every SCREAMING_CASE term in every file resolves to a VOCAB.md definition:

# Fix COVERAGE.md — update FAIL to PASS for dimensions now satisfied
# Ensure all cross-references are valid
# Verify inherits: chains resolve
git add -A
git commit -m "GOV: MEDCHAT-COMMUNITY — close to 255"
magic validate

Score: 255. COIN minted: total 255. Tier: FULL ¹¹.

Your scope is fully governed — every dimension satisfied, every file present, every term defined, every constraint traceable to the axiom. It is ready for clinical deployment, not because someone signed off on it, but because the validator confirmed it. 255 is the proof.

Alignment with GETTING_STARTED.md

If you want the abbreviated version, GETTING_STARTED.md at the repository root provides the fast path. This chapter provides the deep explanation. Both converge on the same workflow:

1. Fork the repository
2. Create a scope directory with CANON.md
3. Add VOCAB.md, README.md — score ~35 (COMMUNITY)
4. Add {SCOPE}.md, COVERAGE.md, ROADMAP.md — score ~63 (ENTERPRISE)
5. Add LEARNING.md — score ~127 (AGENT)
6. Add LANGUAGE inheritance — score 255 (FULL)
7. Run magic validate — confirm 255/255

The pre-commit hook enforces 255 on every subsequent commit. The CI pipeline runs magic validate --strict — any score below 255 is a build failure. Governance is in the build pipeline, not in the review meeting.

5.7 The Gradient Rule

gradient = to_bits - from_bits
if gradient > 0: MINT:WORK(amount=gradient)
if gradient < 0: DEBIT:DRIFT(amount=abs(gradient))
if gradient = 0: no COIN (neutral drift)

Only improvement mints. Staying at 255 mints zero — there is nothing to improve. Going backward costs COIN through DEBIT:DRIFT. The gradient rule ensures that governance investment is economically visible and governance decay is economically penalized. For the full economics of COIN and gradient minting, see Chapter 32 (COIN and the WALLET) and Chapter 33 (Gradient Minting) ¹².

The total COIN minted for building this scope from 0 to 255 is exactly 255 COIN, and it is on the LEDGER. When the compliance committee asks “how much governance work has been done on MedChat?” — the answer is on the LEDGER, in COIN, auditable by anyone with access.

5.8 Common Build Errors and How to Fix Them

During the climb from 0 to 255, developers encounter predictable errors. This section catalogs the errors by tier transition and provides exact fixes ⁶.

Errors at COMMUNITY tier (0 → 35):

# Diagnose COMMUNITY tier issues
magic validate --verbose --tier COMMUNITY

Errors at ENTERPRISE tier (35 → 63):

Errors at AGENT tier (63 → 127):

Errors at FULL tier (127 → 255):

5.9 The Build Session: Timing and Workflow

A developer building a scope from 0 to 255 for the first time should expect the following timeline:

The total time for a first-time developer to build a scope from 0 to 255 is under two hours. An experienced developer can do it in 30 minutes. The governance work is front-loaded — most of the intellectual effort is in writing the axiom and deriving the constraints (Phase 1). Everything after that is filling in the structural requirements.

Compare that to traditional clinical AI governance: months of committee meetings, policy drafts, review cycles, and sign-offs. CANONIC governance requires one developer, one terminal, and two hours. The governance lives in the files, the validator confirms it, and the LEDGER records it. No meetings required.

5.10 Validating a Real Clinical Deployment

To see how the same pattern applies in a different clinical domain, imagine you are deploying a governed clinical decision support agent for emergency medicine triage. The scope is EMERGECHAT, and the walkthrough follows the same structure as MEDCHAT-COMMUNITY with emergency medicine specifics.

mkdir -p EMERGECHAT
cd EMERGECHAT

CANON.md:

# EMERGECHAT — CANON

version: 2026-03

---

## Axiom

**EmergeChat serves emergency medicine triage with governed ESI INTEL. Every recommendation includes acuity level. Every interaction audited.**

---

## Constraints

MUST:     Assign ESI acuity level (1-5) for every triage recommendation
MUST:     Cite emergency medicine guideline for every clinical recommendation
MUST:     Log every interaction to LEDGER with timestamp, actor, and acuity level
MUST:     Display "NOT A SUBSTITUTE FOR CLINICAL TRIAGE" disclaimer
MUST:     Version evidence base with ACEP publication date
MUST NOT: Generate triage recommendations without ESI INTEL backing
MUST NOT: Override triage nurse clinical judgment
MUST NOT: Process PHI outside the emergency department perimeter
MUST NOT: Delay clinical care — response time < 2 seconds for triage queries

---

Notice the emergency-medicine-specific constraint: MUST NOT: Delay clinical care — response time < 2 seconds. In emergency medicine, latency is a patient safety issue, and this constraint makes that fact a governance requirement rather than a performance target. The axiom drives it; the validator enforces it.

VOCAB.md:

# VOCAB

| Term | Definition |
|------|-----------|
| EMERGECHAT | Governed clinical TALK agent serving emergency medicine triage with ESI evidence |
| ESI | Emergency Severity Index — 5-level triage algorithm (1=resuscitation, 5=non-urgent) |
| ACUITY | Patient urgency classification per ESI algorithm |
| ACEP | American College of Emergency Physicians — publisher of emergency medicine guidelines |
| INTEL | Governed knowledge unit with provenance — source, date, evidence grade, citation |
| PHI | Protected Health Information as defined by HIPAA §160.103 |
| LEDGER | Append-only audit trail — every governed event recorded |
| TRIAGE | Initial patient assessment to determine acuity and resource allocation |
| RESUSCITATION | ESI Level 1 — immediate life-saving intervention required |
| EMTALA | Emergency Medical Treatment and Labor Act — federal mandate for emergency screening |

---

Build the remaining files (README.md, EMERGECHAT.md, ROADMAP.md, COVERAGE.md, LEARNING.md) following the same patterns from the walkthrough. Validate:

magic validate --verbose

The score climbs from 0 to 255 in the same predictable progression. The clinical domain changes — emergency medicine instead of general medicine — but the governance structure is identical: the same three TRIAD files, the same eight dimensional questions, the same 255 target as proof.

5.11 After 255: Maintaining Compliance

Achieving 255 is not the end. Maintaining 255 is the ongoing obligation. Governance drift — changes that reduce the score — triggers DEBIT:DRIFT events on the LEDGER ¹².

Common drift causes in clinical AI deployments:

The maintenance workflow is straightforward: run magic validate on every commit, and if the score drops, the commit introduced drift — fix it before merging. The CI pipeline enforces this automatically, treating any commit that reduces the score as a failing build. Governance lives in the build pipeline, not in the review meeting.

# CI pipeline step: governance validation
magic validate --scope . --strict
# --strict: any score < 255 is a build failure
# Exit code 0 = 255/255. Exit code 1 = below 255.

In production, this means no code change, no configuration change, and no evidence base update can reach production without passing validation. Governance becomes continuous and automated — drift is detected at commit time, not at the annual compliance audit.

5.12 The Score Trajectory

Track the score over time. The trajectory reveals the governance pattern. A healthy trajectory is monotonically non-decreasing: each commit either maintains or increases the score. A score drop is a drift event.

magic trajectory SERVICES/TALK/MAMMOCHAT --last 30d
# 2026-02-10: 0 → 35    ▓▓░░░░░░░░░░░░░░
# 2026-02-12: 35 → 63   ▓▓▓▓░░░░░░░░░░░░
# 2026-02-15: 63 → 127  ▓▓▓▓▓▓▓▓░░░░░░░░
# 2026-02-20: 127 → 255 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
# 2026-03-01: 255 → 255 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ (stable)

The trajectory is stored on the LEDGER and renderable by the MONITORING dashboard. If you report to a compliance committee, the trajectory chart shows governance investment over time — no spreadsheet required.

5.13 Cross-Scope Validation

After building a single scope to 255, validate the entire service tree to confirm inheritance consistency:

magic validate --recursive SERVICES/TALK/
# SERVICES/TALK: 255/255
#   MAMMOCHAT: 255/255
#   ONCOCHAT: 255/255
#   MEDCHAT-COMMUNITY: 255/255
# Fleet: 4/4 scopes at 255. No drift detected.

The recursive validation walks every child scope and verifies that inherited constraints are satisfied at every level.

5.14 Post-255 Checklist

Run the checklist once. Then trust the validator. The pre-commit hook enforces 255 on every subsequent commit.

5.15 The Clinical Economics of 255

The journey from 0 to 255 is not merely a compliance exercise — it is an economic event with quantifiable returns. Consider a hospital deploying MammoChat at three sites. Without CANONIC governance, the compliance process involves: committee formation (2 weeks), policy drafting (4 weeks), legal review (3 weeks), IT security assessment (2 weeks), IRB review (6 weeks), and sign-off collection (2 weeks). Total: 19 weeks of elapsed time, 200+ person-hours, and approximately $85,000 in staff time across compliance, legal, clinical, and IT departments ¹³.

With CANONIC governance, the same deployment requires one clinical informatics engineer, one terminal session, and 105 minutes to reach 255. The governance lives in the files, the validator confirms compliance, the LEDGER records the work, and the CI pipeline enforces ongoing compliance. The compliance committee reviews COVERAGE.md and the validation trajectory — not a 47-page policy document that no one reads.

The economic comparison is stark. Traditional governance costs $85,000 and 19 weeks per deployment site. CANONIC governance costs 105 minutes of developer time per deployment site. For a three-site deployment, the savings are approximately $250,000 and 57 weeks of elapsed time. These savings compound: every subsequent deployment inherits the governance chain and starts at the parent’s constraint floor, not at zero.

The 255 score proves the governance work has been done, the COIN minted is the economic record of that work, the LEDGER is the audit trail, and the inheritance chain is the compliance architecture. Build to 255 — the economics follow.

Chapter 6: Building a Scope

A scope is a directory with a CANON.md file. That single requirement makes it the atom of CANONIC governance — the smallest unit you can validate, score, and mint. This chapter walks through anatomy, naming conventions, the full build procedure from empty directory to 255, and the practical decisions that determine whether your governance tree scales or collapses under its own weight. Where Chapter 5 walked through one scope end-to-end, this chapter covers the general principles. Chapter 7 builds on these principles to construct services, and Chapter 8 extends them to products.

6.1 Scope Anatomy

A scope is a directory with a CANON.md file — the only hard requirement. Everything else accumulates ⁷.

MY-SCOPE/
  CANON.md          ← What do you believe? (required)
  VOCAB.md          ← Can you prove it?
  README.md         ← What shape are you? (with inherits: + axiom)
  {MY-SCOPE}.md     ← Who are you? (the spec)
  COVERAGE.md       ← How do you work?
  ROADMAP.md        ← Where are you going?
  LEARNING.md       ← What have you learned?
  SHOP.md           ← economic projection
  INTEL.md          ← scope intelligence

6.2 Naming Convention

GOV (~/CANONIC/) uses SCREAMING_CASE .md files. RUNTIME (~/.canonic/) uses lowercase ⁶.

Never mix singular and plural. SERVICE = SINGULAR. INSTANCE = PLURAL ⁷.

6.3 Child Scopes

A child scope inherits from its parent. Create a subdirectory with CANON.md:

PARENT/
  CANON.md
  CHILD/
    CANON.md     ← inherits: PARENT

The child’s score starts at the parent’s floor and accumulates upward ⁸.

6.4 Scope vs Leaf

A scope has a CANON.md; a leaf does not. Scopes are governance containers, leaves are content ⁶.

DEXTER/           ← SCOPE (has CANON.md)
  BLOGS/          ← SCOPE (has CANON.md)
    2026-02-18-what-is-magic.md    ← LEAF (no CANON.md)
    2026-02-23-your-first-255.md   ← LEAF

6.5 Full Scope Build: mkdir to 255

This is the complete procedure for building a scope from an empty directory to a fully validated 255-bit governance scope. Every command. Every file. No gaps ¹¹.

Step 1: Create the directory structure.

# Create the scope directory
mkdir -p NEPHROCHAT
cd NEPHROCHAT

# Verify parent scope exists (the scope you will inherit from)
ls $(magic resolve-path hadleylab-canonic/MAGIC/SERVICES/TALK)/CANON.md
# If this fails, the parent scope does not exist. Create it first.

Step 2: Write CANON.md.

cat > CANON.md << 'EOF'
# NEPHROCHAT — CANON

version: 2026-03

---

## Axiom

**NephroChat serves nephrology with governed KDIGO INTEL. Every recommendation graded. Every interaction audited.**

---

## Constraints

MUST:     Cite KDIGO guideline for every nephrology recommendation
MUST:     Include CKD stage (G1-G5) and albuminuria category (A1-A3) when relevant
MUST:     Log every interaction to LEDGER with timestamp and actor
MUST:     Version evidence base with KDIGO publication date
MUST:     Maintain PHI boundary — no patient identifiers in governance metadata
MUST NOT: Generate uncited nephrology recommendations
MUST NOT: Override nephrologist clinical judgment
MUST NOT: Process PHI outside the local deployment perimeter
MUST NOT: Provide dialysis access recommendations (refer to nephrologist)

---

EOF

Step 3: Write VOCAB.md.

cat > VOCAB.md << 'EOF'
# VOCAB

| Term | Definition |
|------|-----------|
| NEPHROCHAT | Governed clinical TALK agent serving nephrology queries with KDIGO evidence |
| KDIGO | Kidney Disease: Improving Global Outcomes — international nephrology guideline organization |
| CKD | Chronic Kidney Disease — progressive loss of kidney function classified by GFR and albuminuria |
| GFR | Glomerular Filtration Rate — primary measure of kidney function (mL/min/1.73m2) |
| INTEL | Governed knowledge unit with provenance — source, date, evidence grade, citation |
| PHI | Protected Health Information as defined by HIPAA §160.103 |
| LEDGER | Append-only audit trail — every governed event recorded with timestamp and actor |
| AKI | Acute Kidney Injury — sudden decline in kidney function per KDIGO AKI criteria |
| RRT | Renal Replacement Therapy — dialysis or transplantation for end-stage kidney disease |
| ALBUMINURIA | Abnormal albumin excretion in urine — marker of kidney damage (A1/A2/A3 staging) |

---

EOF

Step 4: Write README.md.

cat > README.md << 'EOF'
# NEPHROCHAT — Nephrology Clinical Decision Support


NephroChat deployment for nephrology clinical decision support. Provides governed clinical recommendations backed by KDIGO guidelines, with CKD staging (G1-G5, A1-A3) and evidence grading for every recommendation. Every interaction is audited on the LEDGER. PHI boundary enforced.

## Capabilities

- CKD staging and progression assessment (GFR + albuminuria)
- AKI recognition and initial management guidance
- Medication dosing adjustment for renal impairment
- Electrolyte management in CKD
- Referral criteria for nephrology consultation

## Limitations

- Does not replace nephrologist clinical judgment
- Does not provide dialysis access recommendations
- Does not process PHI outside deployment perimeter

---

EOF

Step 5: Validate TRIAD — achieve COMMUNITY.

git init
git add CANON.md VOCAB.md README.md
git commit -m "GOV: bootstrap NEPHROCHAT — TRIAD"
magic validate
# Expected: 35/255 (COMMUNITY)

Step 6: Write {SCOPE}.md — the spec.

cat > NEPHROCHAT.md << 'EOF'
# NEPHROCHAT


## Scope Intelligence

| Field | Value |
|-------|-------|
| Subject | Nephrology clinical decision support |
| Audience | Nephrologists, internists, hospitalists, primary care physicians |
| Evidence | KDIGO Clinical Practice Guidelines, AKI/CKD/GN |
| Status | Initial deployment |
| Contact | Clinical informatics team — nephrochat@hadleylab.org |

---

EOF

Step 7: Write ROADMAP.md.

cat > ROADMAP.md << 'EOF'
# NEPHROCHAT — ROADMAP


## Done
- GOV: TRIAD created. COMMUNITY tier achieved.

## Now
- Build to ENTERPRISE tier. Add COVERAGE, SPEC, ROADMAP.
- Define initial KDIGO evidence base (CKD, AKI guidelines).

## Next
- Add LEARNING.md. Achieve AGENT tier.
- Deploy to nephrology pilot at Community Hospital.
- Integrate with EHR lab result feeds for CKD staging automation.

---

EOF

Step 8: Write COVERAGE.md.

cat > COVERAGE.md << 'EOF'
# COVERAGE

| # | Question | Answer | Status |
|---|----------|--------|--------|
| 1 | What do you believe? | NephroChat serves nephrology with governed KDIGO INTEL | PASS |
| 2 | Can you prove it? | VOCAB.md: 10 terms defined, zero stubs | PASS |
| 3 | Where are you going? | ROADMAP.md: ENTERPRISE build, then pilot | PASS |
| 4 | Who are you? | NEPHROCHAT.md: nephrology CDS scope | PASS |
| 5 | How do you work? | This file — operational coverage assessment | PASS |
| 6 | What shape are you? | inherits: TALK service, axiom present, 9 constraints | PASS |
| 7 | What have you learned? | LEARNING.md pending | FAIL |
| 8 | How do you express? | LANGUAGE pending | FAIL |

Score: pending validation

---

EOF

Step 9: Validate — achieve ENTERPRISE.

git add NEPHROCHAT.md ROADMAP.md COVERAGE.md
git commit -m "GOV: NEPHROCHAT — COVERAGE + SPEC + ROADMAP"
magic validate
# Expected: 63/255 (ENTERPRISE)

Step 10: Write LEARNING.md — achieve AGENT.

cat > LEARNING.md << 'EOF'
# LEARNING


Evidence lane for NEPHROCHAT.

## Patterns

| Date | Signal | Pattern | Source |
|------|--------|---------|--------|
| 2026-03-10 | GOV_FIRST | Governance files created before clinical deployment. | Step 0 |
| 2026-03-10 | NEW_SCOPE | NephroChat scope bootstrapped with KDIGO evidence base. | CANON.md |

---

EOF

git add LEARNING.md
git commit -m "GOV: NEPHROCHAT — LEARNING"
magic validate
# Expected: 127/255 (AGENT)

Step 11: Close to 255 — add LANGUAGE, fix gaps.

# Update COVERAGE.md to reflect all PASS questions
# Ensure LANGUAGE inheritance is in the inherits: chain
# Verify all terms resolve
# Verify all cross-references are valid

git add -A
git commit -m "GOV: NEPHROCHAT — close to 255"
magic validate
# Expected: 255/255 (FULL)

Eleven steps. Under two hours for a first-time developer. Every file has a specific purpose, every step increases the score, and any developer following this procedure on any clinical domain produces the same governance structure.

magic heal: Scaffolding a Scope

magic heal automates the scaffolding process. Given a scope directory with a CANON.md, magic heal identifies which governance questions remain unanswered and proposes the files needed to answer them:

$ magic heal SERVICES/TALK/NEW-SERVICE
MISSING: COVERAGE.md (How do you work?)
MISSING: ROADMAP.md (Where are you going?)
MISSING: LEARNING.md (What have you learned?)
ACTION: Create COVERAGE.md, ROADMAP.md, LEARNING.md

The heal output maps directly to questions. The developer creates the files. The developer runs magic validate. The score climbs. magic heal does not auto-generate governance content — governance is human-authored. It identifies the gaps. The human fills them.

Bloat Constraints

Scope files have size constraints enforced by the build pipeline:

• CANON.md — axiom + constraints. No prose beyond governance declarations.
• README.md — minimal. inherits: + axiom + one-line purpose. No feature lists, no changelogs.
• COVERAGE.md — generated. Developers answer eight questions; the compiler produces the file.

These constraints prevent governance bloat — the tendency for governance files to accumulate non-governance content over time. If a file grows beyond its governance purpose, the build pipeline flags it. Governance files govern; everything else belongs in documentation or INTEL.

6.6 Scope Organization Best Practices

Keep scopes shallow. Three to four levels of nesting is the practical maximum. Deeper nesting creates long inheritance chains that are harder to debug.

# GOOD: 3 levels deep
SERVICES/TALK/MAMMOCHAT/MAMMOCHAT-UCF/

# BAD: 6 levels deep
SERVICES/TALK/MAMMOCHAT/DEPLOYMENTS/FLORIDA/UCF/RADIOLOGY/

One scope per clinical domain. Do not combine multiple clinical domains in a single scope. MammoChat is breast imaging. OncoChat is oncology. They are separate scopes, even if they share infrastructure.

Name scopes for their clinical function. MAMMOCHAT, not BREAST-AI. ONCOCHAT, not CANCER-TOOL. NEPHROCHAT, not KIDNEY-SYSTEM. The name should tell a clinical informatics engineer exactly what the scope does.

Put deployment scopes under product scopes. MAMMOCHAT-UCF lives under MAMMOCHAT, not under UCF. The inheritance chain is product → deployment, not institution → product.

# GOOD: product → deployment
SERVICES/TALK/MAMMOCHAT/MAMMOCHAT-UCF/

# BAD: institution → product
UCF/MAMMOCHAT/

6.7 Scope Deletion and Archival

Never delete a scope — archive it. Deleting breaks the inheritance chain for every child that inherits from it ².

# Archive a scope (do NOT delete)
git mv DEPRECATED-SCOPE DEPRECATED-SCOPE.archived
# Add EXTINCTION signal to LEARNING.md
echo "| $(date +%Y-%m-%d) | EXTINCTION | DEPRECATED-SCOPE archived. | Governance decision |" >> LEARNING.md
git add .
git commit -m "GOV: archive DEPRECATED-SCOPE — EXTINCTION"

The EXTINCTION signal in LEARNING.md records the archival event. Any scope that inherited from the archived scope will fail validation on the next magic validate run — the inherits: chain is broken. Update those scopes to point to a living ancestor. The validator identifies the break; the fix is mechanical.

6.8 Scope Discovery

Use magic scan to discover all scopes in a repository or across the fleet ⁶.

# List all scopes in current repository
magic scan --scopes
# Output:
# hadleylab-canonic (255/255)
#   MAGIC (255/255)
#     SERVICES (255/255)
#       TALK (255/255)
#         MAMMOCHAT (255/255)
#           MAMMOCHAT-UCF (255/255)
#       LEARNING (255/255)
#       SHOP (255/255)

# List all scopes across the fleet
magic scan --scopes --fleet
# Output includes canonic-canonic, hadleylab-canonic, adventhealth-canonic, etc.

# Find scopes below a specific tier
magic scan --scopes --below ENTERPRISE
# Output: scopes scoring below 63

For a team managing 50 clinical AI scopes across a health network, magic scan --scopes --fleet provides the complete governance inventory — every scope, its score, its tier, and its position in the inheritance tree. The governance posture of the entire network is visible in one command.

6.9 Scope Migration

When a scope moves from one parent to another, follow this procedure:

mkdir -p NEW-PARENT/MIGRATED-SCOPE
cp MIGRATED-SCOPE/*.md NEW-PARENT/MIGRATED-SCOPE/
# Update inherits: in the new CANON.md
magic validate NEW-PARENT/MIGRATED-SCOPE
git mv MIGRATED-SCOPE MIGRATED-SCOPE.archived
git commit -m "GOV: migrate MIGRATED-SCOPE to NEW-PARENT"

The old location is archived (not deleted) to maintain LEDGER reference integrity.

6.10 Scope Templates

For organizations building many similar scopes, create templates:

TEMPLATES/TALK-DEPLOYMENT/
  CANON.md.template
  VOCAB.md.template
  COVERAGE.md.template

Instantiate with:

magic-heal --template TEMPLATES/TALK-DEPLOYMENT \
  --scope SERVICES/TALK/MAMMOCHAT-REGIONAL \
  --vars "SCOPE_NAME=MAMMOCHAT-REGIONAL,HOSPITAL=Regional Hospital"

Templates accelerate multi-site deployments. A health network deploying MammoChat to 10 hospitals creates 10 scopes from one template in minutes.

6.11 Scope Metrics

magic report SERVICES/TALK/MAMMOCHAT
# SCOPE: SERVICES/TALK/MAMMOCHAT
# Score: 255/255 (FULL) | Tier: MAGIC
# Chain: canonic-canonic → hadleylab-canonic → TALK → MAMMOCHAT
# COIN: 255 minted, 0 debited | Age: 127 days | Contributors: 3
# Child Scopes: MAMMOCHAT-UCF(255) MAMMOCHAT-ADVENT(255) MAMMOCHAT-REGIONAL(255)

6.12 Scope Lifecycle States

magic lifecycle SERVICES/TALK/MAMMOCHAT
# State: GOVERNED | Duration: 87 days at 255 | Stability: HIGH

6.13 Clinical Vignette: Scope Design for a Multi-Specialty Hospital

Tampa General Hospital deploys governed clinical AI across five departments: radiology, cardiology, pathology, emergency medicine, and pharmacy. The clinical informatics architect must design the scope tree before any governance files are written. The scope design determines the inheritance chain, the constraint propagation, and the COIN distribution.

The architect considers two designs:

Design A: Department-first. Each department is a top-level scope. Services live under departments.

tampa-general-canonic/
  RADIOLOGY/
    MAMMOCHAT/
    AI-TRIAGE/
  CARDIOLOGY/
    CARDICHAT/
    ECG-AI/
  PATHOLOGY/
    PATHCHAT/
  EMERGENCY/
    EMERGECHAT/
  PHARMACY/
    DRUGCHAT/

Design B: Service-first. Services are organized by type (TALK, INTEL, MONITORING). Departments are deployment scopes under services.

tampa-general-canonic/
  SERVICES/
    TALK/
      MAMMOCHAT/
      CARDICHAT/
      PATHCHAT/
      EMERGECHAT/
      DRUGCHAT/
    INTEL/
      AI-TRIAGE/
      ECG-AI/
    MONITORING/
      RADIOLOGY-METRICS/
      HOSPITAL-DASHBOARD/

Design B wins. All TALK agents share conversation constraints (systemPrompt, disclaimer, evidence citation, PHI boundary), so declaring them once at the TALK service level and inheriting across all five agents eliminates duplication. Design A copies those constraints across five department scopes — a DRY violation that creates drift risk.

The numbers make it concrete: TALK carries 7 MUST and 3 MUST NOT rules. Design A copies all 10 to 5 departments: 50 constraint declarations. Design B declares them once: 10. When the FDA requires updated disclaimer language, Design B needs 1 edit. Design A needs 5.

Build the tree:

magic scan --scopes tampa-general-canonic
# tampa-general-canonic (255/255)
#   SERVICES (255/255)
#     TALK (255/255)
#       MAMMOCHAT (255/255) — radiology
#       CARDICHAT (255/255) — cardiology
#       PATHCHAT (255/255) — pathology
#       EMERGECHAT (255/255) — emergency
#       DRUGCHAT (255/255) — pharmacy
#     INTEL (255/255)
#       AI-TRIAGE (255/255) — radiology
#       ECG-AI (255/255) — cardiology
#     MONITORING (255/255)
#       RADIOLOGY-METRICS (255/255)
#       HOSPITAL-DASHBOARD (255/255)
# Fleet: 13/13 scopes at 255
# COIN: 3,315 minted

Thirteen scopes, one governance tree, every department’s clinical AI inheriting the correct service-level constraints. The scope design IS the governance architecture ⁷.

6.14 Scope Sizing Guidelines

Each scope should represent one unit of clinical or operational responsibility:

The sizing test: can one team own the scope’s governance? If maintaining 255 requires coordination across multiple teams, the scope is too large — split it. If maintaining 255 requires no meaningful work, the scope is too small — merge it upward.

The natural scope boundary for clinical AI is the product-site combination. MammoChat at UCF is one scope; MammoChat at AdventHealth is another. Each has its own IRB, its own site-specific constraints, its own clinical team ⁷.

6.15 Governance Proof: The Scope as Governance Atom

The scope is the atom of CANONIC governance — the smallest unit that can be validated, scored, and minted. The proof:

1. A scope has CANON.md (axiom + constraints).
2. magic validate produces a score for the scope.
3. Score delta produces COIN (MINT:WORK or DEBIT:DRIFT).
4. COIN is attributed to the scope and the identity.
5. The LEDGER records the event.

Every governance operation — validation, scoring, minting, auditing — operates on scopes. You cannot validate a file, mint COIN for a directory without CANON.md, or audit a namespace that is not a scope.

Think of the scope as CANONIC’s equivalent of a function in programming: the smallest testable, composable, reusable unit. Scopes compose into services, services into products, products into organizations, organizations into the fleet. The hierarchy is the governance architecture, and the scope is where it starts ⁷¹¹.

6.16 Scope Migration and Refactoring

Scopes can be moved, split, or merged. Every structural change is a governance event.

Moving a scope. Rename the directory, update the inherits: path in CANON.md, and run magic validate. The LEDGER records SCOPE:MOVE with old and new paths. COIN balances follow the scope — governance work is not lost when a scope changes its address.

# Move a scope
mv SERVICES/TALK/RADCHAT SERVICES/TALK/MAMMOCHAT
# Update inherits: in CANON.md
magic validate SERVICES/TALK/MAMMOCHAT
# LEDGER: SCOPE:MOVE from SERVICES/TALK/RADCHAT → SERVICES/TALK/MAMMOCHAT

Splitting a scope. Extract a child scope from a parent. The child inherits from the parent. The parent’s COIN history remains with the parent. The child starts at score 0 and accumulates independently.

# Split screening logic into its own scope
mkdir SERVICES/TALK/MAMMOCHAT/SCREENING
# Create CANON.md with inherits: SERVICES/TALK/MAMMOCHAT
magic validate SERVICES/TALK/MAMMOCHAT/SCREENING
# Score: 1 (AXIOM only — new scope starts from CANON.md)

Merging scopes. Absorb a child scope upward into its parent. The child’s COIN history is preserved in the LEDGER — the merge event references both scopes — and the parent’s score may change if the merge introduces new constraints.

Refactoring is governance work. Every structural change produces a LEDGER event. The governance tree’s shape is auditable at every commit. Run git log --oneline -- SERVICES/ to see the structural evolution ⁷¹⁴.

Chapter 7: Building a Service

You have a governance tree. You have primitives — INTEL, CHAT, COIN — each a governed file with clear semantics. But files do not serve clinicians. Files do not handle HTTP requests or mint currency or answer questions at 2 a.m. Something has to project governance into the world where people actually work. That something is the service.

A service is a governed directory that composes one or more primitives into a runtime product. There are exactly 14 of them — not because 14 is a magic number, but because 14 covers every meaningful composition of three primitives. Each service is singular: one directory, one axiom, one set of constraints. The economy runs on their composition.

7.1 The Service Constraint

Every service MUST compose the INTEL primitive. CHAT and COIN are optional ¹⁵. The relationship between primitives and services is structural:

Primitive → Service
INTEL     → LEARNING
CHAT      → TALK
COIN      → SHOP

Primitives are files. Services are directories. A primitive expresses a single concept; a service orchestrates that concept into something operational ¹⁵.

7.2 The 14 Services

Each service is detailed in its own chapter in Part III (Chapters 10-23):

7.3 Service Directory Structure

SERVICES/
  LEARNING/
    CANON.md       ← SERVICE axiom
    LEARNING.md    ← SERVICE spec
    VOCAB.md
    README.md
    COVERAGE.md
    ...

Each service is a governed scope with hard boundaries — no cross-scope leakage, no ambient state. Routes are driven from governed indices, never hardcoded ¹⁵.

7.4 Instance vs Service

Service directories define schemas; instance directories hold content. The distinction matters because services are singletons (one WALLET service defines how wallets work) while instances are plural (each user has their own wallet). Instances live at USER scope, not nested inside SERVICES/ ².

SERVICES/WALLET/           ← schema (SINGULAR)
{USER}/WALLETS/            ← instances (PLURAL)

7.5 Building a Service: Step-by-Step

Every service follows the same build procedure. This walkthrough builds a MONITORING service.

Step 1: Create the service directory.

mkdir -p SERVICES/MONITORING
cd SERVICES/MONITORING

Step 2: Write the service CANON.md.

cat > CANON.md << 'EOF'
# MONITORING — CANON


## Axiom

**MONITORING is continuous governance scoring. Real-time visibility. Observability without obstruction.**

---

## Constraints

MUST:     Expose Prometheus-compatible /metrics endpoint
MUST:     Include governance-specific metrics (scope scores, drift events)
MUST:     Health check verifies live state, not cached configuration
MUST NOT: Block service operations on metrics collection failure
MUST NOT: Require auth for /health and /metrics

---

EOF

Step 3: Write VOCAB.md with service-specific terms.

cat > VOCAB.md << 'EOF'
# VOCAB

| Term | Definition |
|------|-----------|
| MONITORING | Continuous governance scoring and runtime visibility service |
| PROMETHEUS | Open-source metrics collection format — text exposition at /metrics |
| HEALTH_CHECK | HTTP endpoint verifying service liveness and dependency state |
| DRIFT_EVENT | Governance score regression recorded on the LEDGER |
| GAUGE | Prometheus metric type — value that can increase or decrease |
| COUNTER | Prometheus metric type — monotonically increasing value |
| SCOPE_SCORE | Real-time 255-bit governance score for a governed scope |

---

EOF

Step 4: Write remaining governance files. README.md, MONITORING.md, ROADMAP.md, COVERAGE.md, LEARNING.md — each follows the governed Markdown structure described in Chapter 5.

Step 5: Validate progressively.

magic validate  # After TRIAD: 35/255
magic validate  # After COVERAGE+SPEC+ROADMAP: 63/255
magic validate  # After LEARNING + LANGUAGE: 255/255

Step 6: Commit at each tier.

git add CANON.md VOCAB.md README.md
git commit -m "GOV: bootstrap MONITORING — TRIAD"

git add MONITORING.md ROADMAP.md COVERAGE.md
git commit -m "GOV: MONITORING — COVERAGE + SPEC + ROADMAP"

git add LEARNING.md
git commit -m "GOV: MONITORING — close to 255"

At this point, you have minted 255 COIN — the full governance score. The service is now discoverable by magic scan and composable with other services in the fleet.

7.6 Service Composition Patterns

Services compose in three patterns, each with different coupling characteristics:

Pattern 1: Independent. The service operates alone with no runtime dependency on other services. MONITORING, for example, observes the fleet but does not require any other service to function. You can deploy it first or last — the order does not matter.

Pattern 2: Producer-consumer. One service produces a primitive that another consumes. LEARNING produces INTEL; TALK consumes that INTEL to build its systemPrompt. The dependency is directional and explicit:

SERVICES/LEARNING/ → produces INTEL → consumed by → SERVICES/TALK/

Pattern 3: Economic chain. Services linked through COIN operations form a pipeline: MINT creates currency, WALLET holds it, SHOP spends it, LEDGER records it. Each link in the chain is a separate service with its own governance scope.

7.7 Service Governance Constraints

Every service inherits SERVICES-level constraints:

MUST:     Compose at least one primitive (INTEL, CHAT, or COIN)
MUST:     Expose discoverable interface (SHOP.md or VAULT.md)
MUST:     Record state changes on LEDGER
MUST NOT: Hardcode routes — routes driven from governed indices
MUST NOT: Cross scope boundaries — no direct access to another service's state
MUST NOT: Store runtime artifacts in GOV_ROOT

These six constraints are universal — every service inherits them regardless of which primitives it composes. The service-specific CANON.md layers domain constraints on top, and the validator checks both inherited and local constraints in a single pass.

7.8 Service HTTP Routes

Services with HTTP interfaces declare routes in HTTP.md:

# HTTP — MONITORING


## Routes

| Method | Path | Handler | Auth | Rate |
|--------|------|---------|------|------|
| GET | /api/v1/health | health_check | None | Unlimited |
| GET | /api/v1/metrics | prometheus_metrics | None | Unlimited |
| GET | /api/v1/scopes | scope_scores | Required | 100/min |

## Domains

| Domain | Target | SSL |
|--------|--------|-----|
| monitor.canonic.org | Cloudflare Worker | Auto |

---

HTTP.md is a governed route table — the single source of truth for a service’s HTTP surface. The build pipeline reads HTTP.md and generates runtime route configuration from it. No route is hardcoded in application code; if the route is not declared in HTTP.md, it does not exist ¹⁵.

7.9 The 14 Services: Functional Grouping

These four groups are orthogonal — each operates independently, connected only through governed interfaces: INTEL flow between Knowledge and Communication, COIN events between Economy and Operations, and LEDGER records tying everything together.

7.10 Service Testing

Test the service by running validation in verbose mode:

magic validate --scope SERVICES/MONITORING --verbose
# [D] CANON.md present, axiom valid                    PASS
# [E] VOCAB.md present, 7 terms, 0 stubs              PASS
# [T] ROADMAP.md present, 3 sections                   PASS
# [R] MONITORING.md present, Scope Intelligence table   PASS
# [O] COVERAGE.md present, 8 dimensions, 0 mismatches  PASS
# [S] inherits: resolved, axiom present, 5 constraints  PASS
# [L] LEARNING.md present, 2 patterns                   PASS
# [LANG] LANGUAGE inherited                              PASS
# Score: 255/255 (FULL)

Each dimension is a binary test case — PASS or FAIL, deterministic across runs. Run it twice, get the same result. The verbose output tells you exactly which dimension failed and what to fix.

7.11 Service Anti-Patterns

The mega-service. You put TALK + SHOP + MONITORING in one directory because they “all relate to clinical operations.” Break them apart. Each service composes one or two primitives — that constraint is not arbitrary, it is what keeps services testable and independently deployable.

The phantom service. A SERVICES/ directory with CANON.md but no runtime projection — no SHOP.md, no VAULT.md, no HTTP.md. It validates to 255 but does nothing. Either add a projection that serves real users or reclassify the directory as a scope instead of a service.

The cross-scope reader. A service that reads another service’s internal files directly. TALK should consume LEARNING’s governed output (INTEL.md), not reach into LEARNING’s internal processing files. The governed interface is the contract; internal files are implementation details that can change without notice.

# WRONG: direct internal access
intel = read("SERVICES/LEARNING/internal/raw.json")

# RIGHT: governed interface
intel = read("SERVICES/LEARNING/INTEL.md")

7.12 Clinical Service Example: TALK

TALK is the service you will encounter most often if you are building clinical AI agents. It composes CHAT + INTEL to produce contextual conversation agents — each one backed by governed evidence, constrained by its axiom, and deployable as an independent product:

magic report SERVICES/TALK
# Score: 255/255 (FULL)
# Primitives: CHAT + INTEL
# Child scopes: MAMMOCHAT, ONCOCHAT, MEDCHAT, DERMCHAT, EMERGECHAT
# Total COIN: 1,530 (TALK + 5 products * 255 each)

Each child scope inherits TALK’s conversation infrastructure — session management, disclaimer rendering, LEDGER integration — and adds domain-specific knowledge on top. The separation is clean and deliberate: infrastructure lives at the service level, clinical knowledge lives at the product level ¹⁵.

7.13 Clinical Vignette: Building the CONTRIBUTE Service for Clinical Trials

MD Anderson Cancer Center builds a CONTRIBUTE service to govern external clinical trial data submissions. Researchers submit genomic data, treatment response metrics, and biomarker results from Phase II trials. Each submission must be governed — cited, attributed, and scored.

The CONTRIBUTE service composes COIN + INTEL:

cat > SERVICES/CONTRIBUTE/CANON.md << 'EOF'
# CONTRIBUTE — CANON


## Axiom

**CONTRIBUTE governs external work submissions. Every contribution cited. Every submission scored. Bronze for structure, Gold for impact.**

---

## Constraints

MUST:     Accept external INTEL with full citation chain
MUST:     Score contributions as BRONZE (structural) or GOLD (impactful)
MUST:     Record every submission as a LEDGER event
MUST:     Verify contributor identity via VITAE.md
MUST NOT: Accept uncited submissions
MUST NOT: Accept PHI in contribution metadata
MUST NOT: Mint COIN for BRONZE contributions (structural only)

---

EOF

The BRONZE/GOLD distinction governs contribution quality at two levels. A BRONZE contribution meets structural requirements — it has citations, a verified contributor identity, and parses correctly. A GOLD contribution clears a higher bar: the contributed INTEL must actually improve a governed scope’s score, produce a positive gradient, and mint COIN. Structure gets you in the door; impact earns the reward.

magic contribute --submit trial-NCT04711096-results.md \
  --contributor dr.williams@mdanderson.org \
  --scope SERVICES/TALK/ONCOCHAT
# Submission: trial-NCT04711096-results.md
# Citations: 3 (NCT04711096, NCCN 2026.1, FDA approval NDA 761310)
# Identity: VERIFIED (dr.williams@mdanderson.org via VITAE.md)
# PHI check: CLEAN (no patient identifiers detected)
# Grade: GOLD (improves OncoChat evidence layer)
# LEDGER: CONTRIBUTE:GOLD recorded
# Score impact: OncoChat evidence freshness improved

Note what CONTRIBUTE is not: it is not a file upload system. Every submission passes through four gates — citation verification, identity check, PHI detection, and impact scoring — before it enters the governance tree. By composing COIN (economic attribution) with INTEL (knowledge verification), CONTRIBUTE creates a governed knowledge contribution pipeline where quality is enforced structurally, not by reviewer discipline ¹⁵.

7.14 Service Lifecycle and Deprecation

Services follow a governed lifecycle:

Deprecation requires a LEDGER event and a 90-day notice period:

magic service --deprecate SERVICES/LEGACY-FHIR \
  --reason "Replaced by SERVICES/FHIR-API (R5 native)" \
  --sunset 2026-06-10
# LEDGER: SERVICE:DEPRECATE LEGACY-FHIR (sunset: 2026-06-10)
# NOTIFIER: Alert sent to 12 dependent scopes
# ROADMAP.md: Updated with deprecation notice

Dependent scopes receive notification and have 90 days to migrate to the replacement. After sunset, the service is archived — removed from the live fleet but preserved in git history. The LEDGER retains every event from the service’s lifetime. COIN already minted remains in WALLETS; the economic record survives the service itself ¹⁵.

7.15 Service Metrics

Every service exposes standardized metrics:

magic service --metrics SERVICES/TALK
# TALK Service Metrics:
#   Score: 255/255
#   Child scopes: 7 (all at 255)
#   Total COIN: 2,040 (TALK + 7 children)
#   HTTP routes: 4 (2 write, 2 read)
#   Dependencies: LEARNING (INTEL source), LEDGER (event recording)
#   Dependents: MAMMOCHAT, ONCOCHAT, MEDCHAT, DERMCHAT, EMERGECHAT, GASTROCHAT, NEPHROCHAT
#   Uptime: 99.97% (last 30 days)
#   Latency p99: 142ms
#   Daily requests: 12,450

Notice how the metrics draw from two sources: governance data (score, COIN, routes from HTTP.md) and runtime data (uptime, latency from MONITORING). Both sources are themselves governed — there is no untracked telemetry, no shadow metrics pipeline ¹⁵.

7.16 Governance Proof: Service Composition

Every service composes at least one primitive. The proof that service composition is complete:

1. Three primitives exist: INTEL, CHAT, COIN.
2. The 14 services cover all possible primitive compositions: INTEL alone (LEARNING, MONITORING), CHAT + INTEL (TALK, NOTIFIER), COIN alone (LEDGER, WALLET, API, CHAIN, MINT), COIN + INTEL (SHOP, VAULT, CONTRIBUTE, DEPLOY), all three (IDENTITY — implicitly through VITAE.md + governance + economic identity).
3. Every service inherits from SERVICES-level constraints (6 MUSTs/MUST NOTs).
4. Every service adds domain-specific constraints.
5. magic validate checks both inherited and local constraints.
6. A service at 255 satisfies all constraints from root to leaf.

Therefore: every governed service composes at least one primitive, satisfies all inherited constraints, and is validated by the same kernel. The composition is complete — no primitive composition is unrepresented in the 14-service catalog. Q.E.D. ¹⁵³.

7.17 Service Contract Completeness Checklist

Every service must satisfy a completeness checklist before reaching ACTIVE state. The checklist is enforced by build Stage 1 (attest-services):

# Run service attestation checklist
magic service --attest SERVICES/TALK

# Service Attestation: SERVICES/TALK
#   [✓] 1. Axiom: "TALK is SERVICE. Composes: CHAT + INTEL"
#   [✓] 2. Service spec: TALK.md (2,400 words)
#   [✓] 3. Vocabulary: VOCAB.md (38 terms, inherits root +142)
#   [✓] 4. Coverage: COVERAGE.md (8 × 8 matrix, 100% filled)
#   [✓] 5. Operations: SPEC.md (conversation lifecycle)
#   [✓] 6. HTTP routes: HTTP.md (4 routes: 2 write, 2 read)
#   [✓] 7. Learning: LEARNING.md (3 epochs, 18 entries)
#   [✓] 8. Roadmap: ROADMAP.md (4 quarters defined)
#   [✓] 9. Primitives: CHAT + INTEL (2 of 3)
#   [✓] 10. Inheritance: hadleylab-canonic/SERVICES ✓
#
# Attestation: PASS (10/10)
# Score: 255/255

7.18 Service Dependency Graph

Services depend on each other. The dependency graph is derived from inherits: chains and cross-scope references in CANON.md:

magic service --dependencies --graph

# Service Dependency Graph:
#
# TALK ──────→ LEARNING (INTEL source for TALK agents)
#   │          LEDGER (event recording for sessions)
#   │          IDENTITY (principal verification)
#   │
# LEARNING ──→ LEDGER (event recording for discoveries)
#   │          MONITORING (pattern detection)
#   │
# SHOP ──────→ WALLET (balance checking for purchases)
#   │          LEDGER (SPEND event recording)
#   │          IDENTITY (buyer/seller verification)
#   │
# MONITORING → NOTIFIER (alert delivery)
#   │          LEDGER (metric event recording)
#   │
# DEPLOY ───→ MONITORING (post-deploy verification)
#              NOTIFIER (deployment notifications)
#              LEDGER (deploy event recording)
#
# Cycle detection: NO CYCLES ✓
# Root services (no dependencies): LEDGER, CHAIN
# Leaf services (no dependents): DEPLOY

The dependency graph must be acyclic. A cycle (Service A depends on Service B depends on Service A) would create a chicken-and-egg problem: neither service could validate without the other already being validated. The build pipeline checks for cycles at Stage 0 and rejects them with E105 CYCLE_DETECTED ¹⁵.

7.19 Service Templates for Rapid Bootstrap

New services bootstrap from templates that encode the service contract structure:

magic service --create NEW-SERVICE \
  --template clinical-talk \
  --primitives "CHAT + INTEL"

# Creating service: SERVICES/NEW-SERVICE
#
# Generated files:
#   CANON.md          ← axiom: "NEW-SERVICE is SERVICE. Composes: CHAT + INTEL"
#                       inherits: hadleylab-canonic/SERVICES
#   NEW-SERVICE.md    ← service spec template (fill in)
#   VOCAB.md          ← inherits parent vocabulary, add local terms
#   COVERAGE.md       ← 8 × 8 matrix template (fill in)
#   HTTP.md           ← route template (customize routes)
#   LEARNING.md       ← Epoch 1: Bootstrap template
#   ROADMAP.md        ← 4-quarter template (fill in)
#
# Initial score: 255/255 (all files present with template content)
# Warning: Template content must be customized before clinical use
# Next: Edit each file to add domain-specific content

The template produces a structurally valid 255-score scope immediately — every file present, every governance question answered. But the content is generic; “fill in” placeholders mark where domain-specific knowledge must go. The template accelerates creation from hours to minutes. The customization that follows — writing real axioms, real constraints, real evidence — is the governance work that earns COIN ¹⁵¹⁴.

7.20 Clinical Vignette: Service Composition Prevents Governance Gap

Emory Healthcare (Atlanta, 11 hospitals) deploys a new clinical AI agent: NephroChat (nephrology consultation). The nephrology informatics team creates the scope:

magic service --create SERVICES/TALK/NEPHROCHAT \
  --template clinical-talk \
  --primitives "CHAT + INTEL"

The template generates all governance files. The team customizes: adds 23 nephrology-specific VOCAB terms (eGFR, CKD-EPI, UACR, KDIGO, AKI staging), writes the INTEL.md with 18 evidence citations (KDIGO guidelines, USRDS data, key nephrology trials), and defines the systemPrompt with CKD staging tables and medication dosing guidance for renal impairment.

During the governance review, magic validate catches a composition gap:

magic validate SERVICES/TALK/NEPHROCHAT
# Score: 247/255
# Missing: E (8) — COVERAGE.md exists but INTEL cross-reference incomplete
#   COVERAGE.md row "drug-dosing" references INTEL layer 3
#   INTEL.md layer 3 is empty (no drug interaction references)
#   Fix: Add renal dosing references to INTEL.md layer 3
#     Suggested: Lexicomp Renal Dosing, Aronoff Drug Prescribing in Renal Failure

The coverage matrix claimed drug dosing coverage, but the INTEL.md lacked the supporting evidence references. A human reviewer might miss this gap — the COVERAGE.md looks complete without cross-referencing the INTEL.md. The validator checks the cross-reference automatically. The team adds the renal dosing references, re-validates to 255, and deploys NephroChat with complete evidence coverage.

Without the composition check, NephroChat would have deployed claiming drug dosing coverage backed by zero evidence references. A nephrologist asking “What is the renal dosing for vancomycin?” would receive a response that the governance documentation says is evidence-based — but the evidence does not exist. The composition check closes this documentation-to-evidence gap before the agent ever speaks to a clinician ¹⁵³¹⁶.

7.21 The Service as Governance Primitive

Think of a scope as governed knowledge and a service as governed behavior. Scopes can exist without runtime expression — a CANON.md with no code is perfectly valid governance. Services, by contrast, always project into the world: routes, views, APIs, chat interfaces. Every service you build extends your organization’s governed capability surface.

The 14 canonical services represent the complete set of behaviors that governance can express through the three primitives. If your use case is not covered, you are either composing multiple services (correct) or operating outside governance (a problem to fix, not a feature to ship). Build the service. Compose the primitives. Validate at 255. The service is where governance becomes operational ¹⁵¹⁴.

Chapter 8: Building a Product

Governance work produces COIN. COIN establishes a cost basis. The cost basis sets a price floor. A product is what happens when a governed scope at 255 publishes a SHOP.md with a Card — the atomic listing that makes governance labor tradeable. This chapter covers the mechanics: SHOP.md structure, pricing by tier, cost basis calculation, checkout flow, and the full build procedure from governed scope to listed product. Chapter 6 covered building scopes; Chapter 7 covered building services; this chapter covers turning governed work into tradeable products. For the SHOP service architecture, see Chapter 12. For the expanded SHOP economics, see Chapter 34. The live marketplace is at shop.hadleylab.org.

8.1 SHOP.md

Every product is a governed scope compiled to 255, listed in SHOP.md with a Card ¹⁷.

## Card

| Field | Value |
|-------|-------|
| title | {Product Name} |
| type | {BOOK, PAPER, SERVICE, content} |
| price | {N} COIN |
| status | AVAILABLE |
| synopsis | {1-2 sentence description} |
| route | /{path/to/scope}/ |

8.2 Pricing by Tier

8.3 COST_BASIS

The cost basis of a product is the total COIN minted by governance work producing that product ¹⁷:

cost_basis(product) = SUM(MINT:WORK.amount)
  WHERE work_ref matches product scope

A book with 20 chapters, each 0-to-255: 20 * 255 = 5,100 COIN cost basis.

Cost basis is derivable from the LEDGER by any user. Transparency is architectural ¹².

8.4 Checkout Flow

1. Reader selects product. Price displayed in COIN.
2. System checks reader’s WALLET balance.
3. SPEND event: reader debited, author credited. Both hash-chained.
4. Product access granted ¹⁷.

8.5 Building a Product: Step-by-Step

This walkthrough builds a FHIR Integration Playbook product.

Step 1: Build the scope to 255. The product IS the scope. No scope below 255 can list a product.

mkdir -p SERVICES/FHIR-API
cd SERVICES/FHIR-API
# Write TRIAD (CANON.md, VOCAB.md, README.md) → 35
# Write COVERAGE + SPEC + ROADMAP → 63
# Write LEARNING.md, close to 255
magic validate
# Score: 255/255 (FULL)

Step 2: Create SHOP.md.

cat > SHOP.md << 'EOF'
# SHOP — FHIR Integration Playbook


## Card

| Field | Value |
|-------|-------|
| title | FHIR Integration Playbook |
| type | SERVICE |
| price | 255 COIN |
| status | AVAILABLE |
| synopsis | Complete governance kit for FHIR R4 integration. |
| route | /SERVICES/FHIR-API/ |

## What You Get

- CANON.md template for FHIR scopes
- VOCAB.md with 40+ FHIR governance terms
- COVERAGE.md checklist (12 resource types)
- LEARNING.md with 6 months of patterns

---

EOF

Step 3: Validate and commit.

magic validate  # 255/255, SHOP.md valid
git add SHOP.md
git commit -m "GOV: FHIR-API — SHOP listing"

Step 4: Verify listing.

magic scan --shop
# 1. FHIR Integration Playbook (255 COIN) — SERVICES/FHIR-API

8.6 Product Types

8.7 Product Validation Rules

magic validate --shop SERVICES/FHIR-API
# Score gate: PASS | Cost basis floor: PASS | Card: PASS | Identity: PASS | Route: PASS

8.8 Multi-Scope Products

A product can span multiple scopes — a book with 20 chapters is 20 scopes, a governance suite with 50 templates is 50 scopes. Every constituent scope must be at 255. If any single scope drops below 255, the product delists automatically. One drifting scope taints the entire product ¹².

8.9 Product Economics

For a product priced at 255 COIN that sells 100 copies:

8.10 Product Discovery

The build pipeline compiles all SHOP.md files into a browsable catalog:

build → scan **/SHOP.md → compile SHOP.json (_generated) → fleet SHOP page

The fleet SHOP page is a static site. Products are cards rendered from SHOP.json. Each card shows title, author, price, score (always 255), synopsis, and attestation count.

8.11 Clinical Product Examples

Every product started as governance work that minted COIN, establishing the cost basis that set the price floor. The entire economic chain is on the LEDGER.

8.12 Product Lifecycle

A product delists automatically when its scope drops below 255 and relists when restored. No manual intervention — governance drives commerce.

8.13 Clinical Vignette: Product Launch at a Regional Health System

Ochsner Health (New Orleans, 40 hospitals) decides to productize their internal FHIR Integration Playbook. Dr. Nguyen, Chief Health Information Officer, has governed the playbook across 6 scopes over 14 months.

The Governance Foundation. Each scope represents a distinct FHIR integration domain: Patient Demographics (Patient resource), Clinical Notes (DocumentReference), Lab Results (Observation/DiagnosticReport), Medications (MedicationRequest), Allergies (AllergyIntolerance), and Immunizations (Immunization). Each carries full governance: CANON.md with axiom and constraints, VOCAB.md with FHIR-specific terminology (SMART_ON_FHIR, CAPABILITY_STATEMENT, SEARCH_PARAMETER, BUNDLE_TRANSACTION), INTEL.md referencing HL7 FHIR R4 v4.0.1, COVERAGE.md mapping each resource to Ochsner’s Epic endpoints, LEARNING.md documenting 14 months of integration patterns, and ROADMAP.md targeting FHIR R5 readiness.

Cost Basis Calculation. The LEDGER records every MINT:WORK event across 14 months of governance labor:

Scope                  Commits   COIN Minted   Time
Patient Demographics   87        255           3 months
Clinical Notes         94        255           4 months
Lab Results            103       255           3 months
Medications            78        255           2 months
Allergies              45        255           1 month
Immunizations          52        255           1 month
─────────────────────────────────────────────────
Total                  459       1,530         14 months

The cost basis is 1,530 COIN — the sum of all MINT:WORK events. Dr. Nguyen sets the price at 2,000 COIN (31% margin above cost basis). The price floor constraint ensures price >= cost_basis, preventing below-cost sales that would undervalue governance labor ¹⁷.

Product Launch. Dr. Nguyen creates SHOP.md in the parent scope:

magic validate --shop SERVICES/FHIR-PLAYBOOK
# Score gate:       255/255 PASS (all 6 sub-scopes at 255)
# Cost basis floor: 2,000 >= 1,530 PASS
# Card complete:    6/6 fields PASS
# Identity gate:    VITAE.md verified PASS
# Route valid:      /SERVICES/FHIR-PLAYBOOK/ PASS
# LEDGER event:     SHOP:LIST recorded

Market Reception. Within 90 days:

The Drift Incident. At day 47, the HL7 consortium publishes FHIR R4B (v4.3.0). Ochsner’s INTEL.md references the superseded R4 v4.0.1 specification. MONITORING detects the stale evidence during its 5-minute poll cycle. The INTEL dimension drops from 8 to 0. The scope score falls from 255 to 247. The SHOP automatically delists the product:

LEDGER: DEBIT:DRIFT -8 COIN (SERVICES/FHIR-PLAYBOOK/LAB-RESULTS)
LEDGER: SHOP:DELIST (FHIR Integration Playbook)
NOTIFIER: DRIFT_ALERT → dr.nguyen (HIGH priority)

Recovery. Dr. Nguyen updates INTEL.md across all 6 scopes to reference both R4 v4.0.1 and R4B v4.3.0 (backward-compatible). She adds a LEARNING.md entry documenting the versioning pattern. All 6 scopes revalidate to 255. The product relists automatically within 4 hours of the drift detection:

LEDGER: MINT:WORK +8 COIN (evidence update, each scope)
LEDGER: SHOP:RELIST (FHIR Integration Playbook)

Total downtime: 4 hours. Zero manual intervention on the SHOP side — governance state drove listing state. The product was unavailable only while its governance was incomplete ¹².

8.14 Product Bundling and Composition

Products can be composed into bundles. A bundle is a parent SHOP.md that references child SHOP.md files:

---
title: "Enterprise Health Informatics Bundle"
type: BUNDLE
children:
  - SERVICES/FHIR-PLAYBOOK/SHOP.md
  - SERVICES/EHR-MIGRATION/SHOP.md
  - SERVICES/COMPLIANCE-KIT/SHOP.md
price: 5,000
cost_basis: 4,590
---

Bundle validation rules:

If any child scope drifts, the bundle delists. The governance of each component propagates upward to the aggregate. This is compositional product governance — the same principle that governs scope inheritance applies to product composition.

8.15 Product Analytics

The LEDGER provides complete product analytics without a separate analytics service:

magic shop --analytics SERVICES/FHIR-PLAYBOOK --period 90d

# FHIR Integration Playbook — 90-Day Analytics
#
# Revenue:          68,000 COIN (34 sales × 2,000 COIN)
# Unique buyers:    31
# Institutional:    12 hospitals (39%), 3 HIEs (10%), 16 clinics (51%)
# Avg time-to-buy:  12 minutes (from discovery to SPEND)
# Refund requests:  0
# Drift incidents:  1 (4h downtime, auto-resolved)
# Child adaptation: 8 buyers (26%) forked and governed to 255
# COIN recycled:    2,040 (buyers who governed their forks)

The “COIN recycled” metric matters: 26% of buyers adapted the playbook to their institution, governed their version to 255, and minted 2,040 COIN through their own governance labor. The product does not just transfer knowledge — it seeds governance work that generates new economic activity. Purchase leads to adaptation, adaptation to governance labor, governance labor to COIN minting, COIN minting to the next purchase ¹⁷¹².

8.16 Product Versioning

Products are versioned through the git tag system. Each major version corresponds to a magic-tag certification:

v1.0.0 — Initial release (FHIR R4 v4.0.1)
v1.1.0 — Added R4B compatibility (v4.3.0)
v2.0.0 — FHIR R5 support (breaking: new resource types)

Existing purchasers retain access to the version they bought; new purchases get the latest. The LEDGER records which version each SPEND event targets:

{
  "event": "SPEND",
  "product": "FHIR Integration Playbook",
  "version": "v1.1.0",
  "amount": 2000,
  "buyer": "dr-park",
  "seller": "dr-nguyen",
  "ledger_event": "evt:05120"
}

Version upgrades for existing buyers are priced at the governance delta — the COIN minted between versions. If v1.0.0→v1.1.0 required 48 COIN of governance work, the upgrade price is 48 COIN. The upgrade price is derivable from the LEDGER: sum of MINT:WORK between the two tag commits.

8.17 Governance Proof: The Product Chain

The complete product chain from governance labor to market participation:

Dr. Nguyen writes CANON.md for Patient Demographics
  → magic validate → 1/255 (AXIOM bit set)
  → MINT:WORK +1 COIN → LEDGER records evt:03100
  → ... 86 more commits ...
  → magic validate → 255/255 (all bits set)
  → MINT:WORK +128 COIN (final dimension) → LEDGER records evt:03187
  → ... 5 more scopes governed to 255 ...
  → SHOP.md created with Card
  → magic validate --shop → all gates PASS
  → SHOP:LIST → LEDGER records evt:03650
  → Dr. Park discovers product via magic scan --shop
  → Dr. Park SPEND 2,000 COIN → LEDGER records evt:03700
  → Dr. Nguyen WALLET +2,000 COIN
  → Dr. Park receives product access
  → Dr. Park adapts, governs to 255, mints 255 COIN
  → Dr. Park creates her own SHOP.md
  → The SHOP grows by one product

Every step is a LEDGER event. Every COIN traces to governance labor, every product to a 255 score, every purchase to a verified identity. The chain is unbroken from labor to market. Q.E.D. ¹⁷¹²¹⁵

8.18 Product Composition Patterns

Products compose in three patterns:

Pattern 1: Linear composition. Scopes arranged sequentially, each building on the previous.

Chapter 1 → Chapter 2 → Chapter 3 → ... → Chapter N
Product = ordered sequence of N scopes
Cost basis = N × 255 COIN

Books and playbooks use linear composition. Each chapter is a scope. The reading order is the scope order. The product is the sequence.

Pattern 2: Hierarchical composition. Scopes arranged in a tree, with a root scope and child scopes.

Root Service
  ├── Sub-service A
  │   ├── Component A1
  │   └── Component A2
  ├── Sub-service B
  └── Sub-service C

Product = tree of M scopes (M = total nodes)
Cost basis = M × 255 COIN

Service suites use hierarchical composition. The root scope defines the service architecture. Child scopes define components. The product is the tree.

Pattern 3: Graph composition. Scopes connected by cross-references, forming a directed acyclic graph (DAG).

Service A ←→ Service B
    ↓             ↓
Service C ←→ Service D
    ↓
Service E

Product = DAG of K scopes with L edges
Cost basis = K × 255 COIN

Clinical governance suites use graph composition. TALK agents reference INTEL scopes. INTEL scopes reference LEARNING scopes. MONITORING scopes reference all service scopes. The product is the graph.

# Visualize product composition
magic product --graph fhir-integration-playbook

# Graph:
#   Nodes: 8 scopes
#   Edges: 12 cross-references
#   Pattern: Hierarchical with cross-links (DAG)
#   Root: SERVICES/FHIR-API
#   Depth: 3 levels
#   Width: 4 leaves

8.19 Product Quality Metrics

Beyond governance score (255/255), products accumulate quality signals from the market:

magic product --quality fhir-integration-playbook

# Product Quality Report:
#   Score: 255/255 (all 8 scopes)
#   Attestations: 47 (12-month)
#   Velocity: 3.9/month (stable)
#   Adaptation rate: 26% (above 20% target)
#   LEARNING depth: 42 entries across 8 scopes (5.25/scope)
#   Evidence freshness: mean 4.2 months (target < 12 months)
#   Drift frequency: 0.5 events/year (excellent stability)
#   Quality tier: GOLD (all metrics above target)

GOLD-tier products surface first in SHOP search results. The tier is computed from quality metrics, not paid promotion. The SHOP does not sell visibility — visibility is earned through governance quality ¹⁷¹².

8.20 Product Licensing and Reuse Rights

When a buyer purchases a product, the SPEND event grants specific reuse rights:

Reuse rights are encoded in SHOP.md and enforced by the governance system. A buyer who forks and governs their version to 255 has earned their own cost basis through their own labor. Their adapted version is a new product — its own SHOP.md, its own price, its own market presence — coexisting with the original. The market decides which is more valuable based on attestation counts ¹⁷¹².

8.21 Clinical Product Example: Nursing Governance Suite

A chief nursing officer at a 700-bed academic medical center builds a governance suite for nursing-specific clinical AI agents. The suite covers 12 scopes:

magic product --detail nursing-governance-suite

# Nursing AI Governance Suite
# Author: nurse-informaticist@academic-med.org
# Scopes: 12
#   SERVICES/TALK/NURSEBOT (general nursing queries)
#   SERVICES/TALK/NURSEBOT/TRIAGE (ED triage assistance)
#   SERVICES/TALK/NURSEBOT/MEDICATION-ADMIN (medication administration guidance)
#   SERVICES/TALK/NURSEBOT/WOUND-CARE (wound assessment and care planning)
#   SERVICES/TALK/NURSEBOT/FALL-PREVENTION (fall risk assessment)
#   SERVICES/TALK/NURSEBOT/SEPSIS-SCREENING (qSOFA/NEWS2 early warning)
#   SERVICES/TALK/NURSEBOT/PAIN-ASSESSMENT (standardized pain scales)
#   SERVICES/TALK/NURSEBOT/DISCHARGE-PLANNING (care transition guidance)
#   SERVICES/INTEL/NURSING-EVIDENCE (evidence base for all nursing agents)
#   SERVICES/MONITORING/NURSING-METRICS (fleet monitoring for nursing agents)
#   SERVICES/LEARNING/NURSING-PATTERNS (institutional nursing AI learnings)
#   SERVICES/DEPLOY/NURSING-FLEET (deployment configuration)
#
# Cost basis: 3,060 COIN (12 × 255)
# Price: 4,200 COIN (37% margin)
# Attestations: 3 (2 academic medical centers, 1 community hospital)
# Evidence: 47 INTEL citations (ANA, AACN, NANDA-I, NIC/NOC)
# LEARNING: 31 entries over 9 months

The suite establishes the governance standard for nursing AI — vocabulary definitions (NANDA-I nursing diagnoses, NIC interventions, NOC outcomes), evidence citations (ANA position statements, AACN practice alerts), and clinical safety constraints (medication rights, fall risk thresholds, sepsis screening intervals). Every future nursing AI governance product in the SHOP either inherits from this suite or competes with it. First-mover advantage in governance is real: the first product to define the vocabulary becomes the standard ¹⁷¹²¹⁵.

Chapter 9: Composition and Federation

Governance that stops at organizational boundaries is not governance — it is a suggestion. CANONIC composes vertically through inheritance (parent to child, constraints accumulating monotonically — see Chapter 3) and horizontally through federation (org to org, governance verified through hashes without sharing private data). This chapter covers both axes and builds the architecture for multi-hospital governance at scale. The GALAXY visualization (hadleylab.org) renders the federated topology in real time (see Chapter 31). For the governor’s perspective on federation, see CANONIC CANON Chapter 9.

9.1 Composition

CANONIC composes along two axes ¹⁶:

Vertical composition is the deployment architecture — how governance flows from standard to clinical deployment. A hospital deploys MammoChat, which inherits from TALK, which inherits from MAGIC, which inherits from canonic-canonic. Constraints accumulate from root to leaf.

Horizontal composition is the federation architecture — how governance coordinates across organizational boundaries without violating data privacy. Five hospitals each deploy MammoChat independently. Each inherits from the same TALK service and adds site-specific constraints. The hospitals share governance metadata (scores, hashes, tier status) without sharing clinical data (PHI, patient records).

9.2 Federation Architecture

Federation is privacy-preserving distributed governance across multiple organizations. In healthcare, this is not optional — HIPAA requires it. PHI stays local; only governance metadata crosses organizational boundaries ¹⁶.

The boundary is architecturally enforced: governance metadata that crosses organizational boundaries contains no PHI, no patient identifiers, no clinical data — only scores, hashes, tier statuses, and COIN events. A CISO can verify this by auditing the governance metadata format, which is defined in the CANON.md constraints of the federation scope.

9.3 Multi-Hospital Federation

For a five-hospital health network deploying CANONIC, the federation architecture looks like this:

canonic-canonic                     (root)
  └── network-canonic               (network ORG)
        ├── hospital-a-canonic      (hospital A ORG)
        │     └── mammochat-a       (MammoChat at Hospital A)
        ├── hospital-b-canonic      (hospital B ORG)
        │     └── mammochat-b       (MammoChat at Hospital B)
        ├── hospital-c-canonic      (hospital C ORG)
        │     └── mammochat-c       (MammoChat at Hospital C)
        └── network-galaxy          (GALAXY frontend)

Each hospital’s MammoChat is governed independently — validated against its own governance files, producing its own COIN, recording its own LEDGER. The federation layer aggregates governance metadata: the network’s GALAXY shows all five deployments with their scores, tier statuses, and COIN trajectories. The network CISO sees the aggregate posture; hospital-level CISOs see site-specific details. Federation preserves both the aggregate view and the local privacy.

9.4 Scale Evidence

The federation model is not theoretical — it is deployed. One developer, 19 GitHub organizations, 185+ repositories, all validating to 255 ¹⁶. For a health network with five hospitals, the model has been proven at nearly 4x the required scale.

9.5 ORG/USER Topology

ORG is the container. USER is the repo. The mapping to GitHub is direct: github.com/{org}/{user} ².

canonic-canonic/              ORG (root)
  canonic.org                 USER (platform frontend)
hadleylab-canonic/            ORG (proof org)
  hadleylab.org USER (proof frontend)
adventhealth-canonic/         ORG (hospital system)
  adventhealth.org            USER (hospital frontend)

Each hospital system in the federation is a separate GitHub organization with its own repositories, governance files, and validation pipeline. Governance metadata flows through the federation layer; clinical data never leaves the hospital’s GitHub organization.

9.6 The GALAXY

The GALAXY renders the federated topology as an interactive visualization — the governance equivalent of a network operations center. Every ORG, PRINCIPAL, SERVICE, and SCOPE is a node. Compliance rings show 8-dimension status using the DESIGN token system. INTEL flow pulses through edges where INTEL.md exists ¹⁸.

For a hospital board, the GALAXY provides an immediate read on AI governance posture: which deployments are at 255, which are climbing, which have DEBIT:DRIFT events. For the architect, it is the debugging tool — when a deployment fails validation, the GALAXY shows its position in the inheritance tree, its parent constraints, and its specific dimension gaps.

9.7 Federation Protocol

Three rules govern how governance metadata crosses organizational boundaries:

Rule 1: Score sharing. Organizations share governance scores (0-255) publicly. A score is a number — it contains no PHI, no clinical data, no personally identifiable information.

Rule 2: Hash verification. Organizations share CHAIN hashes for cross-verification. Hospital A verifies Hospital B’s MammoChat is at 255 by checking the published hash against the validator output. Trust is replaced by verification.

Rule 3: LEARNING aggregation. Organizations share anonymized LEARNING signals — patterns, discoveries, corrections — without sharing underlying clinical data. “Model update without validation causes drift” is safe to share. The patient data that triggered the drift detection is not.

# Federation verification
magic federation --verify network-canonic
# hospital-a: 255/255 hash=abc123 VERIFIED
# hospital-b: 255/255 hash=def456 VERIFIED
# hospital-c: 191/255 hash=ghi789 VERIFIED (drift detected)
# hospital-d: 255/255 hash=jkl012 VERIFIED
# hospital-e: 255/255 hash=mno345 VERIFIED
# Federation: 4/5 at 255. 1 drifting.

9.8 Composition Depth

Composition has both vertical depth (inheritance chain) and horizontal breadth (federation peers):

Vertical depth is bounded by debuggability. Horizontal breadth is unbounded — federation scales linearly with organization count.

9.9 Building a Federation: Step-by-Step

Step 1: Create the network root.

mkdir -p network-canonic
cd network-canonic
cat > CANON.md << 'EOF'
# NETWORK — CANON


## Axiom

**NETWORK federates clinical AI governance across member hospitals. Every member validated. Every score published.**

---

## Constraints

MUST:     Validate every member scope to 255 before production
MUST:     Publish governance scores to federation dashboard
MUST:     Share anonymized LEARNING signals across members
MUST NOT: Share PHI across organizational boundaries
MUST NOT: Allow unvalidated member deployments
MUST NOT: Override member site-specific constraints

---

EOF

Step 2: Add member organizations as submodules.

git submodule add https://github.com/hospital-a-canonic
git submodule add https://github.com/hospital-b-canonic
# Each member org inherits from network-canonic

Step 3: Validate the federation.

magic validate --recursive --fleet
# network-canonic: 255/255
#   hospital-a-canonic: 255/255
#     mammochat-a: 255/255
#   hospital-b-canonic: 255/255
#     mammochat-b: 255/255
# Federation: 5/5 scopes at 255

Step 4: Launch the GALAXY.

magic galaxy --render
# GALAXY visualization available at https://network.canonic.org/galaxy/

The federation is live. Member hospitals maintain independent governance. The network aggregates scores. The GALAXY visualizes the fleet. PHI stays local. Governance metadata flows through the federation protocol.

9.10 Federation vs Centralization

Federation is not a compromise — it is the architecturally correct model for multi-hospital governance. Clinical data stays where HIPAA requires it. Governance metadata flows where it is needed. The boundary is an architectural constraint enforced by the inheritance chain and the federation protocol, not a policy decision ¹⁶.

9.11 Clinical Vignette: Federation During a Joint Commission Survey

CommonSpirit Health operates 140 hospitals across 21 states. Their clinical AI governance federation covers 45 clinical TALK agents deployed across 80 hospitals. During a Joint Commission survey at Dignity Health Northridge Hospital (one of the 140), the surveyor asks: “How do you verify that your clinical AI tools are governed consistently across all deployment sites?”

The clinical informatics officer runs one command:

magic federation --verify commonspirit-canonic --focus dignity-northridge
# Federation: commonspirit-canonic
# Total members: 80 hospitals
# Total scopes: 360 (avg 4.5 per hospital)
# Fleet status: 357/360 at 255 (99.2%)
# Dignity Northridge scopes:
#   MAMMOCHAT-NORTHRIDGE: 255/255 (chain: canonic-canonic -> commonspirit -> TALK -> MAMMOCHAT -> NORTHRIDGE)
#   CARDICHAT-NORTHRIDGE: 255/255
#   EMERGECHAT-NORTHRIDGE: 255/255
#   PHARMCHAT-NORTHRIDGE: 255/255
# Site: 4/4 at 255. No drift.
# Last validation: 12 minutes ago
# COIN minted (site): 1,020 COIN
# COIN minted (fleet): 91,800 COIN

The surveyor sees four things: every clinical AI tool at Northridge is at 255, governance validates every 12 minutes, it inherits from a system-wide standard, and only 3 of 360 fleet scopes are below 255 (99.2% compliance). No need to review 140 hospitals individually — the federation aggregates the posture.

The three drifting scopes are at Mercy Hospital Sacramento, a LEARNING.md staleness issue detected that morning. The dashboard shows the drift, the timestamp, and the expected recovery. Traditional compliance programs would have buried those 3 scopes in a 200-page aggregate report. CANONIC surfaces them in real-time ¹⁶.

9.12 Federation Economics

Federation produces economic benefits through shared governance investment:

magic federation --economics commonspirit-canonic
# Investment analysis:
#   Cost to build 360 scopes independently: 91,800 COIN
#   Cost with federation (shared templates + LEARNING transfer): 45,900 COIN
#   Savings from federation: 45,900 COIN (50%)
#   Source of savings:
#     Shared TALK service constraints (inherited, not duplicated): 28,000 COIN
#     LEARNING transfer across sites (patterns reused): 12,000 COIN
#     Template standardization (reduced bootstrap time): 5,900 COIN

The savings come from the inheritance chain. When 80 hospitals inherit from the same TALK service, its 7 constraints are defined once and enforced everywhere. Without federation, each hospital defines its own constraints — 80 independent definitions, 80 vocabulary sets, 80 compliance reviews. With federation, one definition serves 80 hospitals. DRY applied to governance economics ¹⁶¹².

9.13 Federation Conflict Resolution

When two federated organizations have conflicting governance requirements, the conflict is resolved at the common ancestor:

magic federation --conflicts commonspirit-canonic
# Conflict detected:
#   Scope: SERVICES/TALK/CARDICHAT
#   Hospital A constraint: MUST cite ACC/AHA guidelines
#   Hospital B constraint: MUST cite ESC guidelines
#   Common ancestor: commonspirit-canonic/SERVICES/TALK
#   Resolution: Ancestor adds MUST cite cardiology society guidelines
#              Each hospital adds specific society as site constraint
#   Status: RESOLVED (ancestor updated, both children pass)

Resolution follows the inheritance rule: the common ancestor defines the general constraint (cite cardiology society guidelines), and each hospital adds the specific constraint (ACC/AHA in the US, ESC for European-trained cardiologists). Neither child weakens the ancestor. Both satisfy the full constraint union. The conflict resolves at the architectural level, not the committee level ¹⁶.

9.14 Federation Monitoring

The MONITORING service provides fleet-wide dashboards for federated deployments:

magic federation --dashboard commonspirit-canonic
# ┌─────────────────────────────────────────────────────────┐
# │  CommonSpirit Health — Clinical AI Governance Federation │
# ├──────────┬───────┬──────────┬─────────┬────────────────┤
# │ Region   │ Sites │ At 255   │ Drifting│ COIN (30d)     │
# ├──────────┼───────┼──────────┼─────────┼────────────────┤
# │ West     │ 28    │ 28 (100%)│ 0       │ +3,420         │
# │ Midwest  │ 22    │ 22 (100%)│ 0       │ +2,640         │
# │ South    │ 18    │ 17 (94%) │ 1       │ +1,980         │
# │ East     │ 12    │ 12 (100%)│ 0       │ +1,440         │
# ├──────────┼───────┼──────────┼─────────┼────────────────┤
# │ Total    │ 80    │ 79 (99%) │ 1       │ +9,480         │
# └──────────┴───────┴──────────┴─────────┴────────────────┘

The South region has one drifting site — visible immediately. Drill down with magic federation --drill south to identify the specific hospital and scope ¹⁶¹⁵.

9.15 Governance Proof: Federation Correctness

The federation model preserves governance correctness. The proof:

1. Every federated organization inherits from a common ancestor (by construction).
2. The common ancestor defines minimum constraints (by CANON.md).
3. Inheritance is monotonically enriching — children add, never remove (by Theorem 3).
4. Each site validates independently using the same kernel (magic validate).
5. Validation is deterministic — same governance files produce same score (by Theorem 2).
6. Federation metadata contains no PHI (by architectural enforcement).

Therefore: every site in the federation satisfies the common ancestor’s constraints AND its own site-specific constraints. The governance is federated (independent validation) AND consistent (shared constraint floor). The PHI boundary is preserved because federation metadata is structurally incapable of containing clinical data. Q.E.D. ¹⁶³.

9.16 Federation Onboarding Protocol

Adding a new organization to a federation follows a governed protocol:

magic federation --onboard new-hospital-canonic \
  --parent commonspirit-canonic \
  --region south

# Federation Onboarding Protocol:
#
# Step 1: IDENTITY — Verify organizational identity
#   Organization: New Hospital Health System
#   Contact: cio@new-hospital.org
#   GitHub org: new-hospital-canonic
#   Status: IDENTITY VERIFIED ✓
#
# Step 2: ANCHOR — Pin parent submodule
#   Parent: commonspirit-canonic (v2.3.0)
#   Inherits: commonspirit-canonic/SERVICES/TALK (clinical AI constraints)
#   Status: SUBMODULE PINNED ✓
#
# Step 3: BOOTSTRAP — Generate initial governance tree
#   Scopes generated: 12 (from federation template)
#   Initial score: 0/255 (all dimensions pending)
#   Status: BOOTSTRAP COMPLETE ✓
#
# Step 4: VALIDATE — First magic validate
#   Scopes at 0: 12 (expected — new organization)
#   Inherited constraints: 7 from parent ✓
#   Status: VALIDATION PASSED (score 0 is valid for new org)
#
# Step 5: LEDGER — Record onboarding
#   FEDERATION:ONBOARD recorded (evt:federation:00420)
#   Fleet size: 81 (was 80)
#
# Next: Govern scopes to 255. Estimated time: 4-8 weeks.

Onboarding produces a governed starting point, not an empty repository. The federation template includes the parent’s constraints, vocabulary, and coverage expectations. Score 0 with clear guidance on what 255 requires ¹⁶¹⁹.

9.17 Federation Governance Tiers

Federated organizations can operate at different governance maturity levels:

magic federation --tiers commonspirit-canonic

# Federation Tier Report:
#   STEWARD:      3 organizations (30+ LEARNING entries, 365 days at 255)
#   CONTRIBUTOR: 42 organizations (all scopes at 255)
#   PARTICIPANT: 30 organizations (all scopes ≥ 191)
#   OBSERVER:     5 organizations (onboarding, < 191)
#   Total:       80 organizations

The tiers incentivize improvement: OBSERVERs see the value of governance templates but cannot modify them, PARTICIPANTs use templates and provide feedback, CONTRIBUTORs propose improvements to the common ancestor, and STEWARDs approve or reject proposals based on fleet-wide impact analysis ¹⁶¹⁹.

9.18 Federation Data Sovereignty

Each organization retains full sovereignty over its data. The federation shares governance contracts (CANON.md, VOCAB.md, COVERAGE.md) but never shares operational data (patient records, clinical notes, financial data).

The separation is architectural, not policy-based. The federation submodule contains only .md governance files — there is no mechanism to include operational data in a submodule. The git repository structure enforces the boundary:

commonspirit-canonic/           ← federation parent (shared)
  CANON.md                      ← shared constraints
  VOCAB.md                      ← shared terminology
  SERVICES/TALK/CANON.md        ← shared TALK constraints

new-hospital-canonic/           ← local organization (sovereign)
  canonic-canonic/              ← submodule (shared root)
  commonspirit-canonic/         ← submodule (shared federation)
  SERVICES/                     ← local governance
  VAULT/                        ← local economic data (NEVER shared)
  LEDGER/                       ← local event chain (NEVER shared)

VAULT/ and LEDGER/ are local to each organization — they never appear in submodules and never cross federation boundaries. A federation partner can verify that your scopes are at 255 by reading published score metadata, but cannot see your WALLET balances, transaction history, or economic details. Governance is transparent; economics are private ¹⁶¹⁹¹².

9.19 Clinical Vignette: Federation Enables Multi-Site Clinical Trial Governance

Duke Clinical Research Institute (DCRI) coordinates a multi-site clinical trial across 23 academic medical centers: ADAPTABLE-2 (Aspirin Dosing: A Patient-centric Trial, Assessing Benefits and Long-term Effectiveness, version 2). Each site deploys a governed TALK agent (TrialChat) that helps research coordinators navigate the trial protocol.

The federation structure:

dcri-canonic/ (federation parent)
  SERVICES/TALK/TRIALCHAT/
    CANON.md          ← 12 constraints (protocol-specific)
    VOCAB.md          ← 47 terms (aspirin dosing, outcomes)
    INTEL.md          ← ADAPTABLE-2 protocol, DSMB reports
    COVERAGE.md       ← IRB requirements across all 23 sites

site-duke-canonic/    (inherits dcri-canonic)
site-stanford-canonic/ (inherits dcri-canonic)
site-mayo-canonic/    (inherits dcri-canonic)
... (23 total)

Each site inherits the protocol constraints but adds site-specific IRB language. When DCRI issues a protocol amendment (changing the aspirin dose from 325mg to 162.5mg for the low-dose arm based on interim analysis), the amendment is a governance update to the federation parent:

# DCRI updates federation parent
cd dcri-canonic
vim SERVICES/TALK/TRIALCHAT/VOCAB.md  # Update LOW_DOSE: 162.5mg
vim SERVICES/TALK/TRIALCHAT/INTEL.md  # Add DSMB report reference
git commit -m "GOV: ADAPTABLE-2 Amendment 3 — low dose 325→162.5mg"
magic validate  # 255 ✓

All 23 sites bump their submodule reference and revalidate:

# Each site runs:
git submodule update --remote dcri-canonic
magic validate --recursive
# TrialChat: 255/255 ✓ (inherits updated LOW_DOSE definition)

The protocol amendment propagates to 23 sites in a single governance cycle. Each site validates independently, each TrialChat serves the updated dosing information, and the LEDGER records the amendment at each site. The DSMB can verify that all 23 sites adopted the amendment by querying governance scores and LEDGER history ¹⁶³¹⁹.

FEDERATION: Operational

FEDERATION is no longer a design document. As of March 2026, four ORGs operate under the CANONIC standard:

The GALAXY/ORGS/ORGS.md registry discovers ORGs structurally — no hardcoded list. Each ORG maintains its own governance tree. Each ORG’s scopes are independently validated. The FEDERATION topology connects them.

The WITNESS Protocol

Cross-ORG trust requires cross-ORG verification. WITNESS provides it:

1. DIGEST — Each ORG computes a signed JSON summary: head SHA-256, event count, COIN totals, wallet balances. Signed with the ORG governor’s Ed25519 key.
2. WITNESS — A peer ORG verifies the DIGEST hash and countersigns. Both ORGs store the countersignature.
3. Threshold — 2-of-N for N < 5 ORGs; 3-of-N for N ≥ 5.
4. Recovery — If an ORG deletes its repository, the kernel’s WITNESSES/{org}/DIGEST.json reconstructs balances. Ed25519 signatures are non-repudiable.

At current scale (2 active witnesses: RunnerMVP and canonic-canonic), the protocol is simple. At federation scale (40+ ORGs), the WITNESS graph becomes the inter-organizational trust mesh.

Chapter 10: LEARNING

Knowledge decays. A clinical AI agent trained on 2024 NCCN guidelines will silently drift as guidelines update, and the agent does not know what it does not know. LEARNING is the architectural answer: the INTEL primitive projected into runtime as a service that captures, generalizes, and propagates knowledge across the entire governance tree. Every governed operation produces LEARNING. Every LEARNING event is evidence. The service closes the loop between governance work and institutional knowledge ²⁰.

10.1 Axiom

LEARNING is INTEL applied. Every discovery governed. Every gradient evidenced ²⁰.

Where INTEL.md is a file — static knowledge compiled into a scope — LEARNING is the service that makes knowledge dynamic. When new evidence enters the governance tree, LEARNING records the delta. When a clinical scope’s INTEL changes, LEARNING propagates the change to dependent scopes. The knowledge network stays current because LEARNING is always listening.

10.2 The IDF Generalization

The Invention Disclosure Form (IDF) is a structured document used in patent prosecution to capture a novel discovery: what was discovered, when, by whom, what prior art exists, and what claims can be made. LEARNING generalizes this pattern beyond patents to all governed scopes. Every discovery — code pattern, compliance insight, architectural decision, clinical protocol change — is a governed LEARNING record with the same structural rigor as a patent disclosure ²⁰.

The generalization works because IDF structure maps directly to the eight governance questions:

A LEARNING record IS a generalized IDF — the same structured capture of novel knowledge, the same evidentiary rigor, the same provenance chain. The difference is scope: IDFs capture patentable inventions; LEARNING records capture all governed knowledge. A team discovering that MammoChat’s BI-RADS 4A sensitivity improved after a model update records that discovery as a LEARNING event with the same structural completeness as a patent IDF ²⁰.

10.3 LEARNING.md Pattern Table

LEARNING.md is the active knowledge log for every governed scope, recording discoveries as signal-pattern pairs in a governed table:

## Patterns

| Date | Signal | Pattern | Source |
|------|--------|---------|--------|
| 2026-02-26 | EVOLUTION | Full rebuild from stale book. | Plan file |
| 2026-02-26 | NEW_CONSTRAINT | IP compliance — no kernel internals. | CANON.md |
| 2026-02-27 | GOV_FIRST | Healthcare vertical directive added. | INTEL.md |
| 2026-03-03 | EVOLUTION | Service ontology — CHAT→TALK. | GOV commit |

Signals are the vocabulary of governance change. Each signal type represents a category of knowledge event:

The table is append-only within an epoch — new patterns go at the bottom, growing monotonically until an epoch boundary triggers rotation ²⁰.

10.4 Record Shape

Every LEARNING record — whether captured in LEARNING.md or stored in the LEARNING service’s CAS — follows a governed record shape:

The shape is uniform across all domains. A patent discovery and a clinical AI improvement use the same fields, the same provenance chain, the same gradient calculation. Any tool that reads LEARNING records can process records from any scope without domain-specific logic ²⁰.

10.5 Storage Architecture

Records live in a content-addressable storage (CAS) system with git-style addressing:

~/.canonic/services/learning/
  ├── manifests/
  │   ├── EVOLUTION.json       ← shard per signal type
  │   ├── NEW_CONSTRAINT.json
  │   ├── NEW_SCOPE.json
  │   └── index.json           ← thin index across all shards
  ├── cas/
  │   ├── a1/
  │   │   └── b2c3d4e5f6...    ← content-addressed record
  │   ├── f7/
  │   │   └── 89abcdef01...
  │   └── ...
  └── checkpoints/
      ├── hadleylab-canonic.json  ← last-scanned commit per repo
      └── canonic-canonic.json

CAS fanout: Records are stored by content hash with 2-char prefix buckets (hash[:2]/hash[2:]). This is the same addressing scheme git uses for object storage — proven at scale, O(1) lookup, no directory explosion ²⁰.

Manifest sharding: One manifest per signal type. A LEARNING query for all EVOLUTION events reads one shard file, not the entire corpus. The thin index maps record hashes to shards for cross-signal queries.

Incremental discovery: Checkpoints track the last-scanned commit per repository. On scan, LEARNING reads only new commits since the checkpoint. For a health network with 200 repositories, incremental scanning reduces discovery time from minutes to seconds.

Hard limits: No single manifest file with 100K+ entries. No single flat CAS directory with 100K+ files. If either limit is approached, the sharding algorithm splits. Clinical AI deployments at hospital-network scale can produce millions of governance events; the architecture must handle that volume without degradation.

10.6 Epoch Rotation

LEARNING.md rotates at epoch boundaries. An epoch is a named period of governance evolution — defined by an EVOLUTION signal that declares the boundary:

| Date | Signal | Pattern | Source |
|------|--------|---------|--------|
| 2026-03-10 | EVOLUTION | NYT_POLISH_COMPLETE. All chapters ≥ 3K words. | ROADMAP.md |

When an EVOLUTION signal fires:

1. The current LEARNING.md is frozen
2. A snapshot is archived as LEARNING-{EPOCH}.md at scope root
3. A new LEARNING.md is initialized with the epoch boundary event
4. The archive file is retained for historical provenance

Epoch rotation maps to natural clinical governance cycles: model version upgrades, guideline updates (NCCN 2025 to 2026), accreditation cycles (Joint Commission survey complete), and regulatory changes (FDA guidance update). Each epoch captures the governance knowledge accumulated during that period, and the archive provides the historical trail regulatory auditors require ².

Epoch Rotation: Operational

LEARNING operates in epochs. Epoch 1 (CONSTRUCTION) has been archived — its patterns captured the building of the governance framework itself. Epoch 2 (OPERATION) is active — its patterns capture production governance signals.

The transition matters. CONSTRUCTION-era patterns like BLOAT EXTINCTION (discovering that COVERAGE.md should be generated, not hand-authored) became permanent infrastructure. OPERATION-era patterns — DRIFT detection, FEDERATION events — represent ongoing production intelligence.

Signal types in OPERATION:

The backpropagation loop remains: signal enters LEARNING.md → analysis identifies root cause → fix ships → signal type becomes obsolete if root cause is permanently resolved.

10.7 INTEL Sources and Cross-Scope Propagation

LEARNING ingests INTEL from multiple governed sources. Each source type produces different LEARNING signals:

Cross-scope propagation: When LEARNING captures a pattern in one scope, it evaluates whether the pattern applies to other scopes in the governance tree. A clinical evidence update in MammoChat (new BI-RADS atlas edition) may propagate to OncoChat (which references breast cancer staging). The propagation is governed — LEARNING does not modify downstream scopes. It creates a LEARNING record in the downstream scope’s LEARNING.md with a reference to the upstream source. The downstream maintainer decides whether to act on the signal ²⁰.

In a health network with 50 clinical AI agents across five hospitals, a guideline update captured at one hospital’s deployment propagates as a LEARNING signal to every other relevant deployment. No manual distribution, no email chains, no forgotten updates. The governance tree carries the knowledge.

10.8 The LEARNING Question and MAGIC Closure

LEARNING answers “What have you learned?” in the MAGIC 255 standard. Without LEARNING.md, the question is unanswered. With LEARNING.md but no patterns, the governance infrastructure exists but has not yet produced knowledge. With evidenced patterns, epoch rotations, and cross-scope references, the question is fully answered ⁶.

This is the dimension that separates compliant systems from intelligent ones. An ENTERPRISE scope passes audits, satisfies HIPAA, and records events. An AGENT scope does all of that and also learns from its clinical interactions, captures emerging patterns, and propagates knowledge to dependent scopes. LEARNING turns governed compliance into governed intelligence ¹⁰.

10.9 CLI Operations

LEARNING is not a passive accumulator — it is an active service with CLI entry points you invoke as part of governance workflows:

# Discover new LEARNING patterns across all governed repositories
magic scan --learning

# Discover patterns in a specific scope
magic scan --learning --scope SERVICES/TALK/MAMMOCHAT

# Validate LEARNING.md structure and signal vocabulary
magic validate --scope SERVICES/LEARNING

# Extract patterns matching a signal type
magic scan --learning --signal EVOLUTION

# Force epoch rotation
magic scan --learning --rotate --epoch "NCCN_2026_UPDATE"

# Export LEARNING corpus for downstream analytics
magic scan --learning --export json > learning-export.json

The magic scan --learning command executes a four-phase pipeline:

In a health network with 200 repositories, phase 1 reduces the scan surface to only new commits. Phase 2 extracts governance-relevant diffs (CANON.md, INTEL.md, LEARNING.md, SHOP.md changes). Phase 3 classifies each diff into the signal vocabulary. Phase 4 writes classified records into the CAS. The pipeline is idempotent — running it twice on the same commit range produces identical CAS entries because content-addressing deduplicates by hash.

10.10 Error Handling and Failure Modes

LEARNING handles five categories of failure:

1. Malformed LEARNING.md. The validator checks that LEARNING.md contains a valid Markdown table with the required columns (Date, Signal, Pattern, Source). A missing column header, a malformed date, or an unrecognized signal type triggers a validation error:

ERROR: SERVICES/TALK/MAMMOCHAT/LEARNING.md
  Line 8: Signal "EVOLVE" not in vocabulary.
  Valid signals: EVOLUTION, NEW_CONSTRAINT, NEW_SCOPE,
    GOV_FIRST, EXTINCTION, DRIFT, CLOSURE
  Run: magic heal --scope SERVICES/TALK/MAMMOCHAT

magic heal auto-corrects common signal misspellings (EVOLVE to EVOLUTION, NEWSCOPE to NEW_SCOPE) when the correction is unambiguous. Ambiguous corrections require manual resolution.

2. Orphaned CAS entries. A CAS record not referenced by any manifest shard is orphaned. magic scan --learning --gc identifies and reports them but does not delete automatically — an orphaned entry may indicate manifest corruption that needs investigation, not cleanup.

3. Checkpoint corruption. If a checkpoint references a commit that no longer exists (force-push, rebased branch), the scanner falls back to a full-history scan for that repository. The fallback is logged as a DRIFT signal in the LEARNING service’s own LEARNING.md — the service learns about its own failures.

4. Cross-scope propagation failure. When a pattern propagates from MammoChat to OncoChat, and OncoChat’s LEARNING.md is locked (epoch rotation in progress), the propagation is queued in a pending manifest:

~/.canonic/services/learning/pending/
  └── ONCOCHAT-a1b2c3d4.json  ← queued propagation record

Pending records are retried on the next magic scan --learning invocation. If a pending record fails three consecutive retries, it is escalated to a DRIFT signal on the LEARNING service scope.

5. Evidence gap. A LEARNING record with empty Evidence or References arrays triggers a governance warning — not an error, but a quality signal. The warning appears in validation output:

WARN: LEARNING record a1b2c3d4 has no evidence chain.
  Pattern: "BI-RADS 4A sensitivity improved 12%"
  Recommendation: Add evidence sources (NCT ID, guideline version, etc.)

A LEARNING corpus with a high evidence-gap rate indicates the team is recording discoveries but not linking them to clinical evidence — degrading the corpus’s value for downstream analytics and regulatory audit.

10.11 Clinical Vignette: MammoChat NCCN Guideline Update

Consider the workflow when NCCN publishes updated breast cancer screening guidelines (NCCN v2026.2) that change the screening interval recommendation for women aged 40-49 from annual to biennial for average-risk patients.

Day 0: Guideline published. The clinical governance team updates MammoChat’s INTEL.md to reference the new guideline version. The commit produces a governance diff.

Day 1: LEARNING discovery. The next magic scan --learning run detects the INTEL.md change in the MammoChat scope. The scanner classifies the diff as an EVOLUTION signal:

| 2026-06-15 | EVOLUTION | NCCN v2026.2 screening interval change: 40-49 avg-risk biennial. | INTEL.md commit abc123 |

The LEARNING record includes structured assertions: ["screening_interval: annual→biennial", "age_group: 40-49", "risk_level: average", "source: NCCN v2026.2"]. The evidence chain references ["NCCN Breast Cancer Screening v2026.2", "NCT06604078"].

Day 2: Cross-scope propagation. The scanner evaluates cross-scope impact. OncoChat references MammoChat’s INTEL for breast cancer staging. The scanner creates a LEARNING record in OncoChat’s LEARNING.md:

| 2026-06-16 | EVIDENCE_BRIDGE | Upstream NCCN v2026.2 screening change in MammoChat. Review OncoChat breast staging INTEL. | LEARNING/MAMMOCHAT/a1b2c3d4 |

MedChat, which references general screening guidelines, also receives a propagated record. The propagation is automatic; the clinical team reviews the downstream signals and decides whether to update INTEL files.

Day 5: LEDGER recording. The governance officer reviews the LEARNING records, updates OncoChat’s INTEL.md, and the work produces a MINT:WORK event: 47 COIN for gradient advancement across three scopes. The LEARNING corpus now contains the full provenance chain — upstream guideline change, cross-scope propagation, downstream INTEL update, and LEDGER economic recording.

10.12 Clinical Vignette: Tamoxifen-to-Aromatase Inhibitor Protocol Shift

A large academic medical center uses OncoChat for oncology decision support. The ASCO 2026 guideline update recommends aromatase inhibitors (anastrozole 1mg daily, letrozole 2.5mg daily) as first-line adjuvant endocrine therapy for postmenopausal HR+/HER2- early breast cancer, replacing the prior recommendation of tamoxifen 20mg daily for 5 years as an acceptable first-line option.

LEARNING capture. The governance team records the discovery:

{
  "pattern": "ASCO 2026: AI first-line over tamoxifen for postmenopausal HR+/HER2- early breast",
  "signal": "EVOLUTION",
  "assertions": [
    "drug_class: aromatase_inhibitor",
    "agents: anastrozole_1mg, letrozole_2.5mg",
    "replaces: tamoxifen_20mg_first_line",
    "population: postmenopausal_HR+_HER2-_early",
    "evidence_level: Category_1",
    "source: ASCO_2026_adjuvant_endocrine"
  ],
  "evidence": [
    "ASCO Clinical Practice Guideline 2026",
    "ATAC Trial (anastrozole vs tamoxifen)",
    "BIG 1-98 (letrozole vs tamoxifen)",
    "NCCN Breast Cancer v2026.2"
  ],
  "gradient": 31
}

Cross-scope impact. The scanner propagates to MammoChat (screening context references adjuvant therapy), MedChat (general oncology references), and FinChat (CPT/ICD-10 coding for aromatase inhibitor prescribing). Each receives an EVIDENCE_BRIDGE signal. The FinChat propagation is clinically significant — coding changes for anastrozole vs. tamoxifen affect reimbursement workflows.

Quantified outcome. Before LEARNING, guideline updates propagated via email chains, averaging 23 days from publication to institutional awareness across five sites. After LEARNING, automated propagation achieved 100% cross-scope notification within 48 hours. Governance velocity for the endocrine therapy update: +142 COIN across 12 affected scopes.

10.13 Network Map and VITAE Integration

LEARNING records are produced by governed actors — identified individuals with VITAE.md profiles. The LEARNING service maintains a network map that tracks the relationship between actors, discoveries, and scopes:

~/.canonic/services/learning/network/
  ├── actors.json           ← actor → discovery count, signal distribution
  ├── galaxy.json           ← scope → discovery count, propagation count
  ├── edges.json            ← actor-scope pairs with strength weights
  └── clusters.json         ← discovered communities of practice

This is not a social graph — it is a knowledge provenance graph: who discovered what, in which scope, with what evidence. Which actors produce the highest-quality LEARNING records? Which scopes generate the most DRIFT signals? Which actor-scope pairs have the strongest knowledge production edges?

For a chief medical informatics officer, the network map answers the questions that surveys and self-reports cannot: who is driving governance at each site, which sites produce knowledge that propagates to others, and which scopes are stable versus drifting ²⁰.

VITAE integration is enforced by a binding constraint: MUST NOT: Create LEARNING/{slug}.md without USERS/{slug}/VITAE.md. Every actor in the LEARNING network must have a verified VITAE profile, ensuring provenance chains terminate at verified identities — not anonymous accounts, not shared credentials, not bot accounts. VITAE provides the identity layer; LEARNING provides the knowledge layer ²⁰.

10.14 The Onboarding Pipeline

When a new user joins the governance network, the LEARNING service executes a 4-channel scan pipeline (SOP-011):

1. VITAE check     → Does USERS/{slug}/VITAE.md exist?
2. KYC check       → Does directory name match legal identity? (SOP-010)
3. Network scan    → What existing actors share scope edges?
4. LEARNING init   → Create LEARNING/{slug}.md with MINT:SIGNUP record

The pipeline triggers on the first magic scan --learning invocation after a new USERS/{slug}/ directory appears. The scan detects the new scope (NEW_SCOPE signal), verifies VITAE existence, validates KYC naming, maps the actor into the network graph, and initializes their LEARNING history. Onboarding is not a registration form — it is a governance event discovered by scanning the filesystem ²⁰.

10.15 Closure

LEARNING is INTEL applied. Every discovery governed by the IDF-generalized record shape, every signal typed in the governance vocabulary, every record content-addressed in the CAS, every cross-scope propagation tracked, every actor verified through VITAE, every event recorded on the LEDGER. A scope that governs without learning is a bureaucracy. A scope that learns without governing is chaos. LEARNING is the governed intelligence layer — and for clinical AI, governed intelligence is the only kind that belongs in healthcare. For the theoretical closure that LEARNING provides to the eight-dimensional model, see Chapter 39 (The LEARNING Closure). For examples of LEARNING in production TALK agents, see Chapter 11 (TALK) and Chapter 25 (Contextual Agents).

Chapter 11: TALK

Imagine a conversation engine where every response is backed by governed evidence, every session is recorded on an immutable ledger, and every agent speaks in the precise professional vocabulary of its domain — not because a developer remembered to add citations, but because the architecture makes ungoverned responses structurally impossible. That is TALK: the composition of CHAT and INTEL into a governed conversation service that powers every clinical AI agent in the CANONIC ecosystem ²¹.

11.1 Axiom

TALK is CHAT + INTEL composed. Industry determines the voice. INTEL provides the knowledge ²¹.

Two binding obligations follow from this axiom. First, TALK must wire INTEL — the agent never speaks without governed knowledge backing its response. An LLM without governed INTEL is a chatbot; with it, the LLM becomes a clinical decision support tool whose evidence sources are auditable. Second, the industry determines the voice — a radiology agent speaks in radiological terminology, a legal agent in legal language. The voice is not cosmetic; it is governance.

11.2 The Composition

TALK = CHAT + INTEL

This is not two systems bolted together. INTEL provides what the agent knows — the evidence base, the domain boundaries, the citation chain. CHAT determines how the agent speaks — the persona, the session management, the disclaimer architecture. TALK composes both into a single governed conversation where knowledge and voice are inseparable. You cannot deploy a TALK agent without both primitives present and validated, because the composition is enforced at build time ²¹.

Building a TALK agent requires a governed INTEL layer (the clinical evidence base compiled into the systemPrompt) and a CHAT configuration (the conversation engine with domain-specific voice settings). The build pipeline fuses them into a single artifact — CANON.json — that the runtime reads. The governance files are source code; CANON.json is the compiled output.

11.3 Building a Clinical TALK Agent

The pipeline from governed INTEL to clinical conversation follows a deterministic compilation path:

INTEL.md → compile → CANON.json { systemPrompt } → talk.js → clinical agent

Step 1: Wire the INTEL. The agent’s knowledge comes from INTEL.md — the scope intelligence file that defines the evidence sources, the domain boundaries, and the cross-scope connections. For MammoChat, the INTEL.md references BI-RADS classifications, ACR guidelines, and breast imaging evidence. The INTEL is not injected at runtime. It is compiled into the agent’s systemPrompt at build time.

Step 2: Compile the systemPrompt. The build pipeline reads the INTEL.md, extracts the scope intelligence, and compiles it into a systemPrompt that is embedded in the CANON.json output. The systemPrompt tells the agent what it knows, what it does not know, and what constraints it must obey. The systemPrompt is a governed artifact — derived from the INTEL, constrained by the CANON, and compiled by the build pipeline.

Step 3: Configure the CHAT. The TALK service’s CHAT configuration sets the conversation parameters — the persona (clinical, legal, financial), the disclaimer (always displayed), the session management (every turn logged to LEDGER), and the PHI boundary (no patient identifiers in the conversation metadata).

Step 4: Deploy. The compiled agent serves clinical conversations through the TALK frontend — a governed conversation interface that displays the disclaimer, logs every interaction, and enforces the CANON constraints.

11.4 Channel Governance

Every TALK channel is governed by a CANON.md scope. Each channel has:

• A systemPrompt derived from INTEL.md — the agent’s knowledge boundary
• A disclaimer (always displayed) — the governance notice that the agent is AI, not a clinician
• A session ledger (every conversation turn recorded) — the audit trail
• A PHI boundary — the architecturally enforced line between clinical data and governance metadata ²¹

None of this is optional. Remove the governed systemPrompt and you have an ungoverned chatbot. Remove the disclaimer and you have a liability exposure. Remove the session ledger and you fail the next HIPAA audit. The governance is not a layer on top of the architecture — it is the architecture. Strip it away and what remains is not a degraded TALK agent; it is a different and dangerous thing entirely.

11.5 Contextual Agents

Each scope with TALK enabled produces a contextual agent. The agent answers questions from that scope’s INTEL, governed by that scope’s axiom, in the voice of that scope’s industry ²¹.

The implication is broader than clinical AI: every governed scope in the ecosystem can have a TALK agent. A paper scope produces an agent that discusses the paper’s findings. A service scope produces an agent that explains the service’s architecture. A book scope produces an agent that navigates the book’s content. The agent’s knowledge boundary matches the scope’s governance boundary — it knows what the scope knows, and nothing more.

For clinical AI, this means each evidence domain gets its own governed conversational interface:

11.6 Persona Resolution

The CANON.md Persona table determines how the agent communicates. A clinical agent speaks in clinical language because its audience — radiologists, oncologists, pharmacists — expects precision. A legal agent speaks in legal language because its audience expects formality. The persona is compiled from CANON.md into the systemPrompt; the build pipeline reads it, not guesses it:

The persona is not a UI skin. It is a governance constraint that shapes how the model formulates responses — the difference between “the mass appears suspicious” (clinical-third) and “you might want to get that checked out” (generic). Governed agents do not drift into casual language because the persona is enforced at compile time.

11.7 The Disclaimer Architecture

Every TALK agent displays a disclaimer — a governance notice that the agent is AI-generated content, not a clinical diagnosis, not legal advice, not financial guidance. The disclaimer is not optional. It is a CANON.md constraint that the TALK service enforces ²¹.

For clinical TALK agents, the disclaimer serves as the first line of both clinical safety and legal liability protection:

This is AI-generated clinical decision support. It is not a clinical diagnosis
or treatment recommendation. All clinical decisions must be made by qualified
healthcare professionals based on their independent clinical judgment and the
individual patient's clinical circumstances. Every recommendation cites its
evidence source for independent verification.

The disclaimer is displayed on every conversation turn. It cannot be hidden, minimized, or dismissed by the user. A frontend developer cannot accidentally suppress it with a CSS override — magic validate checks for disclaimer rendering and blocks deployment if it is missing. The governance framework ensures the disclaimer is always present, not because developers are untrustworthy, but because the consequence of omission is a liability exposure that no amount of after-the-fact correction can undo.

11.8 Per-User Dashboard and Session Governance

Every USER principal gets a dashboard at /TALK/{USER}/. The dashboard shows the user’s conversation history, active sessions, and COIN activity. Cross-user messages are delivered via governed inbox ²¹.

Session governance means every conversation between a clinician and a TALK agent is a governed session — opened, recorded, and closed on the LEDGER. The session record captures governance metadata: who initiated the session (IDENTITY), when it started, how many turns it contained, what INTEL was cited, and when it ended. Critically, the session record does not include PHI — patient identifiers, clinical data, and protected information remain in the clinical system. The LEDGER sees the governance trail, not the clinical content.

For compliance teams, this architecture produces the audit trail that HIPAA 164.312(b) requires — a record of every AI-assisted clinical decision support interaction, timestamped, attributed, and preserved on the LEDGER — as a byproduct of normal operation. You do not reconstruct the audit trail from server logs after the fact. The governance architecture produces it continuously, automatically, and immutably.

11.9 CLI Operations and Build Pipeline

TALK agents are compiled, not configured. The CLI provides the build and validation entry points:

# Validate a TALK scope's governance completeness
magic validate --scope SERVICES/TALK/MAMMOCHAT

# Build the TALK agent — compile INTEL into systemPrompt
build --scope SERVICES/TALK/MAMMOCHAT

# Scan for all TALK-enabled scopes in the governance tree
magic scan --talk

# Validate all TALK child scopes
magic validate --scope SERVICES/TALK --recursive

# Check that CANON.json declares users[] for cross-user routing
magic validate --scope SERVICES/TALK --check users

# Generate PDF from TALK.md via LATEX pipeline
build --scope SERVICES/TALK/MAMMOCHAT --format tex

The build pipeline follows a deterministic compilation path:

CANON.md → INTEL.md → build → CANON.json { systemPrompt, persona, users[] }
                                    ↓
                              talk.js → runtime agent
                                    ↓
                              TALK.md → LATEX → PDF (offline surface)

Each step in the pipeline is governed, and the separation between source and output is critical to understand. CANON.md and INTEL.md are human-authored source code — you write and maintain them. CANON.json is machine-compiled output — the build pipeline produces it. The runtime reads CANON.json exclusively; it never touches the source Markdown. The _generated marker in CANON.json means exactly what it says: if the output is wrong, fix the compiler or the contract, never the output file itself ²¹.

11.10 The TALK Data Flow

Every conversation turn in a TALK session follows a governed data flow:

User message
  → TALK frontend (displays disclaimer, enforces PHI boundary)
  → Session manager (opens or continues governed session)
  → systemPrompt injection (compiled from INTEL.md via CANON.json)
  → LLM inference (model processes user message + systemPrompt)
  → Response filter (strips PHI leakage, enforces citation requirement)
  → LEDGER write (POST /talk/ledger — server-side, every turn)
  → COIN mint (COIN=WORK per session — governance work rewarded)
  → Response display (with disclaimer, with evidence citations)

Every step in this data flow is a governance gate, and failure at any gate produces a specific, actionable error — not a generic “something went wrong.” The error tells you exactly which constraint was violated and what to do about it. When a response lacks citations, you know it is the response filter. When a session has no LEDGER trail, you know it is the session manager. The architecture makes failures diagnosable, not mysterious.

11.11 Cross-User Messaging

TALK supports governed cross-user messaging. When user A needs to send a message to user B, the message is delivered through the governed inbox — not through a side-channel:

{
  "endpoint": "POST /talk/send",
  "from": "dr-martinez",
  "to": "dr-chen",
  "scope": "SERVICES/TALK/MAMMOCHAT",
  "message": "Review BI-RADS 4A case — LEARNING record a1b2c3d4",
  "session_id": "s-789abc"
}

Every cross-user message is LEDGER-recorded. The CANON.json users[] array declares which users can receive messages in each TALK scope — a user not in the array cannot receive messages in that scope. The routing is governed by the same CANON.md that governs the agent itself.

In clinical practice, this enables governed collaboration across specialties: a radiologist using MammoChat flags a LEARNING discovery to an oncologist, with the message recorded on the LEDGER, both identities verified, and the routing constrained by governance. The collaboration trail is complete and auditable — who sent what to whom, when, in what clinical context, through what governed channel.

11.12 COIN Minting per Session

Every governed TALK session mints COIN. The minting formula:

COIN = f(session_turns, citation_count, evidence_quality)

Every mint is recorded on the LEDGER as a MINT:WORK event with the session ID as the work reference. The key insight is that minting is not a reward for chatting — it is a reward for governed clinical work. A session with no citations mints fewer COIN than a session with evidence-rich responses. The economic incentive is structurally aligned with governance quality: the more evidence you cite, the more COIN you earn ¹².

11.13 Error Handling and Failure Modes

TALK handles six categories of failure:

1. Missing systemPrompt. If CANON.json does not contain a systemPrompt field (compilation failure, empty INTEL.md), the TALK service refuses to start the agent:

ERROR: SERVICES/TALK/MAMMOCHAT/CANON.json
  Missing field: systemPrompt
  Cause: INTEL.md is empty or build pipeline did not run.
  Fix: Populate INTEL.md and run: build --scope SERVICES/TALK/MAMMOCHAT

2. Disclaimer suppression. If the frontend template does not render the disclaimer (template bug, CSS override), the magic validate check fails:

ERROR: SERVICES/TALK/MAMMOCHAT — disclaimer not rendered
  MUST constraint violated: "Every TALK agent displays a disclaimer"
  Fix: Check _includes/talk-disclaimer.html template

3. LEDGER write failure. If the POST /talk/ledger endpoint is unreachable, the TALK session pauses and the turn is queued for retry. The session does not continue without LEDGER recording — ungoverned conversation turns are not permitted:

~/.canonic/services/talk/retry-queue/
  └── s-789abc-turn-08.json  ← queued LEDGER write

4. PHI boundary violation. If the response filter detects a pattern matching PHI (MRN format, SSN format, date-of-birth combined with name), the response is blocked and a DRIFT signal is recorded in LEARNING.

5. Out-of-scope response. If the LLM generates a response outside the agent’s governed knowledge boundary (MammoChat answering a cardiology question), the response filter flags it for review with a governance notice directing the user to the appropriate agent.

6. Boilerplate detection. The TALK CANON enforces that every child scope declares domain-specific content — not template boilerplate. The validator detects generic axioms:

ERROR: SERVICES/TALK/MAMMOCHAT/CANON.md
  Axiom: "MAMMOCHAT is CANONIC" — too generic.
  MUST: Every child scope declares domain-specific Axiom.

11.14 Clinical Vignette: MammoChat BI-RADS 4A Triage

A community hospital radiologist uses MammoChat during a breast imaging reading session. The patient’s mammogram shows a 1.2cm irregular mass with indistinct margins. The radiologist opens a MammoChat session.

Turn 1 (Radiologist): “Irregular mass 1.2cm indistinct margins in upper outer quadrant. BI-RADS assessment guidance.”

Turn 1 (MammoChat): “Based on ACR BI-RADS 5th Edition, an irregular mass with indistinct margins is suspicious. BI-RADS 4B (intermediate suspicion for malignancy, PPV 15-30%) is appropriate. Tissue sampling is recommended. [Source: ACR BI-RADS Atlas 5th ed., 2013; NCCN Breast Cancer Screening v2026.1, BINV-2]”

Session governance: The session is opened with session ID s-mammochat-2026-03-15-001. Every turn is LEDGER-recorded via POST /talk/ledger. The systemPrompt constrains responses to BI-RADS, ACR, and NCCN evidence. The disclaimer is displayed on every turn.

COIN minting: The 6-turn session produces 6 base COIN, 4 unique citations (ACR BI-RADS, NCCN v2026.1, NCCN BINV-2, ACR Practice Parameter), evidence quality multiplier 1.5 (peer-reviewed guidelines). Total: (6 + 2) * 1.5 = 12 COIN minted to the radiologist’s WALLET.

LEARNING capture: The session pattern “irregular mass + indistinct margins → BI-RADS 4B” is captured as a LEARNING record with signal SESSION_LEDGERED, as described in Chapter 10. The record propagates to the institutional LEARNING corpus, contributing to the community learning dashboard at mammo.chat. For a deeper look at how the MammoChat TALK page is constructed, see the MammoChat TALK.

11.15 Clinical Vignette: OncoChat Pembrolizumab Eligibility

An oncologist at an academic medical center uses OncoChat to evaluate immunotherapy eligibility for a newly diagnosed stage IIIA non-small cell lung cancer (NSCLC) patient. The tumor is PD-L1 TPS 60%, EGFR/ALK/ROS1 wild-type.

Turn 1 (Oncologist): “Stage IIIA NSCLC, PD-L1 TPS 60%, no driver mutations. Pembrolizumab eligibility and regimen.”

Turn 1 (OncoChat): “Per NCCN NSCLC v2026.2 (NSCL-31), for stage IIIA NSCLC with PD-L1 >= 50% and no EGFR/ALK/ROS1 alterations: pembrolizumab 200mg IV q3w monotherapy is Category 1 recommended as first-line systemic therapy. Alternative: pembrolizumab + pemetrexed 500mg/m2 + carboplatin AUC5 q3w x 4 cycles, then pembrolizumab + pemetrexed maintenance (KEYNOTE-189). [Source: NCCN NSCLC v2026.2 NSCL-31; KEYNOTE-024, N Engl J Med 2016;375:1823-33; KEYNOTE-189, N Engl J Med 2018;378:2078-92]”

Governance trail: The session references three evidence sources, all from OncoChat’s governed INTEL. The drug names (pembrolizumab, pemetrexed, carboplatin), dosages (200mg, 500mg/m2, AUC5), and trial citations (KEYNOTE-024, KEYNOTE-189) are sourced from compiled INTEL — not hallucinated by the LLM. The session mints 18 COIN (high citation density, GOLD evidence quality).

11.16 View Architecture

Every TALK scope presents three governed views, discovered from controls.views in CANON.json:

The default view is gov — the governance contract renders first. Before you interact with the agent, you see what governs it: its axiom, its constraints, its evidence sources. The governance is not hidden behind the conversational interface; it is presented ahead of it. You know the rules before the agent speaks.

The view toggle itself is discovered from CANON.json, not hardcoded in a template. The compiler emits the controls.views array; the theme renders toggle buttons for whatever views exist. Add a new view to the compiler and the theme renders it automatically, with no template change required ²¹.

11.17 Community Learning Dashboard

Every first-class TALK service with a .ai domain surfaces a Community Learning Dashboard compiled from TALK/{SERVICE}/LEARNING.md:

### Community Learning Dashboard

| Question | Evidence | Source |
|----------|----------|--------|
| What does BI-RADS 4A mean? | Intermediate suspicion, PPV 2-10% | ACR BI-RADS 5th ed. |
| When is breast MRI indicated? | High-risk (>20% lifetime risk) | NCCN v2026.1 BINV-A |
| What is tomosynthesis sensitivity? | +1.2 cancers/1000 screens | Friedewald et al. 2014 |

Every question on this dashboard is real — extracted from LEARNING records produced by governed TALK sessions, never fabricated. A fabricated community learning question is a governance violation that degrades institutional trust. The dashboard serves a dual purpose: patient education (community-tier, free access) and governance transparency. The public can see what clinicians actually ask and what evidence the agent provides in response ²¹.

11.18 Closure

This chapter opened with a claim: TALK is CHAT + INTEL composed. The architecture proves it. INTEL compiles into the systemPrompt. CHAT configures the clinical persona. Sessions are governed on the LEDGER. COIN mints for governance work. Disclaimers are enforced by the build pipeline. PHI boundaries are maintained by architectural separation. Cross-user messages route through governed channels. Community learning dashboards compile from real clinical interactions.

Remove the INTEL, and the agent speaks without evidence — an ungoverned chatbot. Remove the CHAT, and the evidence has no voice — a knowledge base with no interface. TALK composes both into something neither primitive achieves alone: a governed conversation engine where every word is backed by evidence and every session is a first-class governance event. In clinical healthcare, that composition is the difference between a liability and an asset. For the visual rendering of TALK agents, see Chapter 30 (The CHAT Layer). For the compilation pipeline that produces agents from INTEL, see Chapter 25 (Contextual Agents). For the SHOP economics of TALK products, see Chapter 12 (SHOP) and Chapter 34 (The SHOP).

Chapter 12: SHOP

COIN + INTEL. Public economic projection. The marketplace that compiles itself ¹⁵.

12.1 Axiom

SHOP compiles the public aggregate. Composable. Deterministic. Drift-gated ¹⁵.

Most marketplaces are databases with a frontend bolted on. SHOP is the opposite: the governance tree itself is the product catalog, and the marketplace is a compiled projection of it. Every governed scope that wants to be visible creates a SHOP.md file. The SHOP service walks the tree, discovers every SHOP.md, and compiles them into a unified catalog. No manual curation. No product database. No CMS ¹⁷.

The pattern makes governed clinical AI products discoverable by construction. Build MammoChat to 255, create a SHOP.md in its scope, and the product appears in the marketplace. The governance score is the listing qualification — you cannot game your way into the catalog without doing the governance work.

12.2 Discovery Architecture

SHOP discovers products by walking the filesystem. No database. No API. No registration form. The walk is deterministic — the same governance tree always produces the same product catalog:

magic scan → find SHOP.md files → parse Cards → compile catalog → drift gate → publish

Step 1: Walk. The SHOP compiler walks every directory in the governance tree looking for SHOP.md files. Every SHOP.md found is a product candidate.

Step 2: Parse. Each SHOP.md contains a Card — a structured declaration of the product’s metadata (title, type, price, status, synopsis, route). The compiler parses each Card into a product record.

Step 3: Validate. The compiler checks that each product’s parent scope validates to 255. A SHOP.md in a scope that scores below 255 is ignored — ungoverned products are not listed. This is the quality gate. You cannot game the marketplace by creating SHOP.md files in empty scopes ¹⁵.

Step 4: Compile. All valid product records are compiled into a single catalog artifact — _data/shop.json — that the frontend reads to render the marketplace.

Step 5: Drift gate. Before publishing, the compiler regenerates the catalog and compares it to the existing published version. If the regenerated catalog differs from the published version (drift detected), the publish is blocked until the drift is resolved. This ensures that the published marketplace always matches the current governance tree ¹⁵.

12.3 SHOP.md Cards

Every product is declared as a Card in SHOP.md:

## Card

| Field | Value |
|-------|-------|
| title | CANONIC-DOCTRINE |
| type | BOOK |
| price | 255 COIN |
| status | AVAILABLE |
| synopsis | The dev manual. DRY. MATH. FIXED. PURE. |
| route | /BOOKS/CANONIC-DOCTRINE/ |

Card fields are governed:

Every Card field traces to a governed source. The synopsis comes from the scope’s axiom, the price from tier alignment, the route from the governance tree path. Marketing does not write Cards — governance compiles them ¹⁷.

12.4 Pricing by Tier

Product pricing aligns with governance tiers. The tier determines the audience. The audience determines the price:

The alignment is not arbitrary. Governance investment scales with deployment complexity. A patient-facing screening chatbot (COMMUNITY, free) demands far less governance depth than a clinical decision support tool for radiologists (ENTERPRISE, 127 COIN) or a full institutional deployment with HIPAA audit trails and LEDGER integration (FULL, 255 COIN). The tier encodes that reality ¹².

12.5 The Composable Frontmatter Pattern

SHOP.md is not the only way to list a product. For scopes that need inline product visibility, the shop: frontmatter key enables composable listing:

---
shop: true
---

When shop: true is present in a scope’s frontmatter, the SHOP compiler includes that scope in discovery even without a standalone SHOP.md file. When shop: inline is specified, the product card renders inline within its parent’s SHOP page rather than as a standalone entry ¹⁵.

Set shop: true on each clinical AI service scope in your SERVICES directory and the SHOP compiler discovers all of them — no separate SHOP.md per service. Same convention as talk: frontmatter: composable, filesystem-discoverable, no configuration database.

12.6 Checkout Flow

The SHOP checkout is a governed economic transaction — every step is a LEDGER event:

1. Reader selects product → SHOP:VIEW event
2. System checks WALLET balance → SHOP:BALANCE_CHECK
3. Reader confirms purchase → SPEND event (reader debited, author credited)
4. Both sides hash-chained → LEDGER integrity preserved
5. Product access granted → SHOP:ACCESS_GRANTED
6. Attestation minted → CONTRIBUTE:ATTESTATION (reader attests to product quality)

There is no payment gateway here. The SPEND event debits the reader’s WALLET and credits the author’s — both hash-chained on the LEDGER. No external payment processor, no credit card, no bank account. When a hospital purchases a MammoChat enterprise license (127 COIN), the LEDGER records full provenance: who purchased, when, at what price, from what scope, and at what governance score. The procurement audit trail is structural, not bolted on ^{17 12}.

12.7 Drift Gate

The drift gate is SHOP’s integrity mechanism. Before any catalog publish, the compiler regenerates the entire catalog from the governance tree and compares it to the current published version:

regenerated = compile(governance_tree)
published   = read(current_catalog)

if regenerated != published:
    BLOCK PUBLISH
    LOG: drift detected at {scope} — {diff}
    REQUIRE: resolve drift before publish

The drift gate prevents three failure modes:

1. Stale catalog: A product scope was updated but the catalog was not regenerated. The drift gate catches the mismatch.
2. Orphaned listing: A product scope was deleted but the catalog still lists it. The drift gate catches the orphan.
3. Score regression: A product scope dropped below 255 but the catalog still lists it as available. The drift gate catches the regression.

The catalog never advertises a clinical AI tool that has fallen out of governance compliance. If OncoChat drops from 255 to 191 because of an unvalidated model update, the drift gate blocks the listing until the score is restored. The marketplace cannot sell ungoverned products ¹⁵.

12.8 SHOP and the Hospital Procurement Office

Traditional SaaS marketplaces ask you to trust the vendor’s compliance claims. SHOP eliminates that dependency. Every product has been validated to 255 by the same standard, and the governance score is computed by the validator — not self-reported. The SHOP listing is the vendor assessment.

A procurement officer reviewing a SHOP Card sees:

• Title and type: What the product is
• Price in COIN: What the governance investment costs
• Cost basis: How much governance work produced the product (transparency)
• Route: Where to inspect the product’s governance tree
• Status: Whether the product is currently available and at 255

Every field derives from governance, not from vendor marketing materials. In a governed marketplace, the compliance proof is the product listing ¹⁷.

12.9 CLI Operations

SHOP is compiled, not administered. The CLI commands:

# Discover all SHOP.md files in the governance tree
magic scan --shop

# Compile the product catalog from discovered SHOP.md files
build --shop

# Validate SHOP.md Card fields against constraints
magic validate --scope SERVICES/SHOP

# Check drift between compiled catalog and published catalog
magic validate --shop --drift

# Regenerate catalog and publish (blocked if drift detected)
build --shop --publish

# List all products with governance scores
magic scan --shop --scores

# Export catalog as JSON for external integration
magic scan --shop --export json > shop-catalog.json

The build --shop command executes the five-phase pipeline described in Section 12.2. The pipeline is idempotent — running it twice on the same governance tree produces identical catalog output. The idempotency is critical for the drift gate: if the pipeline were non-deterministic, the drift gate would produce false positives on every run.

The magic validate --shop --drift command is the pre-publish check. Run it before build --shop --publish. If drift is detected, the command outputs a diff showing exactly which products changed, were added, or were removed:

DRIFT DETECTED in _data/shop.json:
  + ADDED: SERVICES/TALK/CARIBCHAT (new SHOP.md discovered)
  ~ CHANGED: SERVICES/TALK/MAMMOCHAT (price: 127 → 255 COIN)
  - REMOVED: SERVICES/TALK/LEGACY-BOT (scope deleted)

  Resolve drift before publish.
  Run: build --shop --publish --force to accept changes.

12.10 The Catalog Data Structure

The compiled catalog is a JSON artifact at _data/shop.json. The structure:

{
  "_generated": true,
  "compiled_at": "2026-03-10T14:00:00Z",
  "compiler": "build --shop v3.1",
  "products": [
    {
      "title": "MammoChat Enterprise",
      "type": "SERVICE",
      "price": 255,
      "status": "AVAILABLE",
      "synopsis": "Governed breast imaging AI with BI-RADS INTEL",
      "route": "/SERVICES/TALK/MAMMOCHAT/",
      "cost_basis": 2147,
      "governance_score": 255,
      "tier": "FULL",
      "last_validated": "2026-03-10T13:45:00Z",
      "card_hash": "a1b2c3d4e5f6..."
    },
    {
      "title": "OncoChat Enterprise",
      "type": "SERVICE",
      "price": 127,
      "status": "AVAILABLE",
      "synopsis": "Pan-cancer staging intelligence — 10 cancer types, 12 biomarkers",
      "route": "/SERVICES/TALK/ONCOCHAT/",
      "cost_basis": 1893,
      "governance_score": 255,
      "tier": "AGENT",
      "last_validated": "2026-03-10T13:45:00Z",
      "card_hash": "f7890abcdef1..."
    }
  ],
  "catalog_hash": "deadbeef01234567..."
}

The _generated: true flag marks this file as compiler output. Do not hand-edit. The card_hash per product is the SHA-256 of the product’s Card fields — used by the drift gate to detect per-product changes. The catalog_hash is the SHA-256 of the entire products array — used for whole-catalog drift detection ¹⁵.

12.11 Bag Review Pattern

The SHOP CANON requires bag review before checkout: MUST: Bag review before checkout. The bag is the user’s selection of products before the economic transaction executes. The bag review step serves three governance purposes:

1. Confirmation gate. The user sees exactly what they are purchasing, at what price, before COIN is debited. No surprise charges. No hidden fees. The bag displays: product title, price in COIN, current governance score, and the user’s WALLET balance.

2. Balance check. The SHOP verifies that the user’s WALLET has sufficient COIN balance before proceeding. If the balance is insufficient, the checkout is blocked with a specific message:

INSUFFICIENT BALANCE
  Product: MammoChat Enterprise — 255 COIN
  Your balance: 142 COIN
  Shortfall: 113 COIN

  Earn COIN through governed work:
    - TALK sessions mint COIN per turn
    - CONTRIBUTE submissions mint COIN per acceptance
    - Governance work mints COIN per gradient advancement

3. One CTA per card. Each product card in the bag has exactly one call-to-action button. The constraint MUST: One CTA per product card prevents UI patterns that confuse users with multiple action paths. The CTA is “Purchase” for AVAILABLE products and “Join Waitlist” for COMING_SOON products.

12.12 Error Handling and Failure Modes

SHOP handles four categories of failure:

1. Invalid Card fields. A SHOP.md with missing required fields or invalid enum values triggers a validation error:

ERROR: SERVICES/TALK/MAMMOCHAT/SHOP.md
  Line 7: Field "status" value "LIVE" not in enum.
  Valid values: AVAILABLE, COMING_SOON, ARCHIVED
  Run: magic heal --scope SERVICES/TALK/MAMMOCHAT

2. Ungoverned scope. A SHOP.md in a scope that does not validate to 255 is excluded from the catalog with a warning:

WARN: SERVICES/TALK/LEGACY-BOT/SHOP.md excluded.
  Governance score: 191/255 (missing: LEARNING, EVIDENCE)
  Products require 255 governance score for SHOP listing.
  Fix: Run magic validate --scope SERVICES/TALK/LEGACY-BOT

3. Inline CSS/JS violation. The SHOP CANON prohibits inline CSS and JS in compiled pages: MUST NOT: Inline CSS or JS in compiled pages. The validator scans compiled SHOP pages for <style> and <script> tags:

ERROR: SHOP compiled page contains inline CSS.
  File: _site/SHOP/index.html, Line: 47
  MUST NOT: Inline CSS or JS in compiled pages.
  Fix: Move styles to _TOKENS.scss via DESIGN.css authority.

4. Admin tools on public surface. The constraint MUST NOT: Admin tools on public SHOP surface prevents administrative functions (catalog regeneration, drift resolution, score override) from being exposed on the public-facing SHOP. The validator checks that no admin endpoints are referenced in compiled SHOP templates.

12.13 Clinical Vignette: Hospital Network Procurement

A five-hospital health system evaluates clinical AI products for system-wide deployment. The chief medical informatics officer (CMIO) opens the CANONIC SHOP catalog.

Discovery. The CMIO browses the SHOP. The catalog shows three clinical AI products at AVAILABLE status:

Due diligence. The CMIO clicks the route link for MammoChat Enterprise. The link opens the MammoChat governance tree — the CANON.md, INTEL.md, LEARNING.md, and full validation report are visible. The CMIO verifies: evidence sources (NCT06604078, BI-RADS 5th ed., NCCN v2026.1), governance constraints (HIPAA compliance, PHI boundary, disclaimer enforcement), and LEARNING history (23 EVOLUTION events, 0 unresolved DRIFT events). The due diligence is self-service — no vendor presentation required. The governance tree IS the vendor assessment.

Procurement. The CMIO adds MammoChat Enterprise (255 COIN) and OncoChat Enterprise (127 COIN) to the bag. The bag review shows: total 382 COIN, institutional WALLET balance 500 COIN, remaining after purchase 118 COIN. The CMIO confirms. The checkout executes:

SPEND: 255 COIN — MammoChat Enterprise
  Buyer: memorial-health-system (WALLET: 500 → 245 COIN)
  Seller: hadleylab (WALLET: +255 COIN, 5% fee: -12.75 COIN)
  LEDGER: event-a1b2c3d4 (hash-chained)

SPEND: 127 COIN — OncoChat Enterprise
  Buyer: memorial-health-system (WALLET: 245 → 118 COIN)
  Seller: hadleylab (WALLET: +127 COIN, 5% fee: -6.35 COIN)
  LEDGER: event-e5f6g7h8 (hash-chained)

Both transactions are recorded on the LEDGER. The procurement audit trail is complete: who purchased, when, at what price, from what scope, at what governance score. The hospital’s procurement office has a governed record of every clinical AI acquisition — no purchase orders lost, no vendor contracts unsigned, no compliance assessments undocumented.

12.14 Clinical Vignette: Score Regression and Drift Gate

OncoChat deploys an updated language model without running magic validate. The model change causes OncoChat’s governance score to drop from 255 to 191 — the EVIDENCE dimension fails because the new model’s citation patterns differ from the validated INTEL.

Drift gate trigger. The next build --shop run detects the score regression:

DRIFT DETECTED:
  SERVICES/TALK/ONCOCHAT — score regression: 255 → 191
  OncoChat Enterprise listing BLOCKED until score restored.

  Missing questions: "Can you prove it?", "What have you learned?"
  Fix: Run magic validate --scope SERVICES/TALK/ONCOCHAT
       Review model update against INTEL.md evidence sources.
       Run magic heal if validation identifies auto-fixable issues.

The SHOP catalog is not published. OncoChat Enterprise remains listed at its last-valid state (255/255) until the drift is resolved. No customer sees a degraded product listing. No hospital procurement office purchases a clinical AI tool that has fallen out of governance compliance.

Resolution. The clinical informatics team reviews the model update, updates INTEL.md to account for the new model’s citation format, runs magic validate to restore the 255 score, and then build --shop --publish succeeds. The drift gate has protected the marketplace integrity. A LEARNING record captures the event: signal DRIFT, pattern “Model update without validation caused EVIDENCE dimension failure,” gradient -64 (from 255 to 191, then restored to 255).

12.15 Per-Page Wallet Constraint

The SHOP CANON contains a specific anti-pattern constraint: MUST NOT: Per-page wallet reimplementation. This constraint prevents each SHOP product page from implementing its own WALLET balance display, its own checkout flow, or its own COIN handling logic. The WALLET is a single service. The SHOP reads from it. There is one WALLET implementation, and every SHOP page uses it through the same API.

The constraint exists because in early development, individual product pages implemented their own COIN balance checks — leading to inconsistencies where different pages showed different balances for the same user. The constraint eliminates the class of bug entirely: one WALLET, one balance, one truth ¹⁵.

12.16 Product Type Taxonomy

The SHOP Card type field uses a governed enum. Each type maps to a distinct compilation path and display template:

Each type resolves governance differently. A SERVICE resolves from the full governance tree (CANON.md + INTEL.md + LEARNING.md + all child scopes). A BOOK resolves from its scope only. A PAPER resolves from the paper scope and cross-references the trial registry (NCT ID). Resolution logic varies by type, but the output format is uniform — every product compiles to a JSON object with the same field schema ¹⁵.

12.17 Closure

SHOP compiles the public aggregate. Products discovered by filesystem walk, Cards parsed from SHOP.md, scores validated to 255, catalogs compiled deterministically, drift gates blocking stale publishes, checkouts LEDGER-recorded, bag reviews enforcing confirmation gates, procurement audit trails baked into the transaction architecture. SHOP is not a marketplace that happens to have governance — it is governance that happens to produce a marketplace. For clinical AI procurement, that distinction separates vendor trust from vendor assessment. The live SHOP is at shop.hadleylab.org. For the broader COIN economics that drive the SHOP, see Chapter 32 (COIN and the WALLET) and Chapter 35 (COSTBASIS and Pricing). For product-level construction, see Chapter 8 (Building a Product) and Chapter 34 (The SHOP) ¹⁷.

Chapter 13: LEDGER

COIN. Append-only economic truth. The audit trail that IS the compliance ¹². The LEDGER is one of the 14 services described in Chapter 7, composing COIN with INTEL to create an immutable economic record. Its hash chain integrity layer is covered in Chapter 17; its per-user projection is the WALLET (Chapter 14).

13.1 Properties

Every compliance audit begins with the same question: “Show me the trail.” The LEDGER is an immutable, append-only log that answers it permanently. It tracks not transactions but provenance — who did what, when, with what evidence, under what governance, and why it mattered. Every COIN minted, every COIN spent, every drift event, every reconciliation lives here ²².

HIPAA §164.312(b) requires mechanisms that “record and examine activity in information systems that contain or use electronic protected health information.” The LEDGER is those mechanisms. Every governed clinical AI interaction becomes a LEDGER event — timestamped, attributed, hash-linked, append-only. Governance and audit are not separate systems. They are architecturally unified.

13.2 Event Types

Eight events, exhaustive. No ninth type exists. The economy is closed by enumeration — when a HIPAA auditor asks “what types of events does this system record?” the answer is this table, and no others ¹².

13.3 Event Shape

{
  "id": "a1b2c3d4e5f6",
  "prev": "z9y8x7w6v5u4",
  "ts": "2026-02-26T14:30:00Z",
  "event": "MINT:WORK",
  "user": "dexter",
  "amount": 92,
  "delta": 92,
  "work_ref": "hadleylab-canonic/BOOKS/CANONIC-DOCTRINE",
  "signature": "ed25519hex..."
}

Each event hash-links to its predecessor via the prev field and carries an Ed25519 signature after the cutoff date. Change a single character in any event and every subsequent hash breaks. The LEDGER is append-only by design and tamper-evident by cryptography ¹².

13.4 The LEDGER as Healthcare Audit Trail

One LEDGER serves simultaneously as four compliance instruments:

HIPAA audit trail: Every clinical AI interaction recorded with actor, timestamp, governance context, and outcome. The LEDGER satisfies §164.312(b) by architecture.

FDA 21 CFR Part 11 electronic records: Every LEDGER event is attributable (actor identified), legible (JSON format), contemporaneous (timestamped at event time), original (append-only, no modifications), and accurate (hash-verified). The LEDGER satisfies ALCOA by design.

SOX internal controls: Every financial governance event (FinChat interactions, coding decisions, claims processing) recorded with full provenance. The LEDGER provides the internal control documentation that financial auditors require.

Joint Commission quality records: Every governance event that contributes to clinical quality improvement is on the LEDGER. The quality improvement trail is complete, timestamped, and auditable.

Four compliance standards, one governed event log. The audit trail maps to every standard through the compliance matrix — no separate system per regulation.

13.5 Querying the LEDGER

The LEDGER is queryable. Extract governance analytics for compliance reporting, quality improvement, and operational analysis:

# All MINT:WORK events for MammoChat in Q1 2026
SELECT * FROM ledger
  WHERE event = 'MINT:WORK'
  AND work_ref LIKE '%MAMMOCHAT%'
  AND ts BETWEEN '2026-01-01' AND '2026-03-31'

# Total DEBIT:DRIFT across all clinical AI scopes
SELECT SUM(amount) FROM ledger
  WHERE event = 'DEBIT:DRIFT'
  AND work_ref LIKE '%SERVICES/TALK%'

# Governance velocity for the institution
SELECT
  SUM(CASE WHEN event = 'MINT:WORK' THEN amount ELSE 0 END) as minted,
  SUM(CASE WHEN event = 'DEBIT:DRIFT' THEN amount ELSE 0 END) as drifted,
  minted - drifted as velocity
FROM ledger
  WHERE ts >= '2026-01-01'

These queries produce governance velocity, drift rates, compliance trends, and economic return on governance investment — metrics derived from governed events, not surveys or self-assessments.

13.6 CLI Operations

Query and audit the LEDGER through CLI commands:

# View the last 20 LEDGER events
magic ledger --tail 20

# View all events for a specific user
magic ledger --user dexter

# View all events for a specific scope
magic ledger --scope SERVICES/TALK/MAMMOCHAT

# View all events of a specific type
magic ledger --event MINT:WORK

# Reconcile the current month
magic ledger --reconcile

# Verify hash chain integrity
magic ledger --verify

# Export LEDGER for external audit
magic ledger --export json > ledger-audit-2026-Q1.json

# Compute governance velocity for a date range
magic ledger --velocity --from 2026-01-01 --to 2026-03-31

The magic ledger --verify command is the chain integrity check. It reads every event in the LEDGER, recomputes the prev hash for each event, and verifies that every hash matches. If any event has been modified — even a single character — the verification fails with a specific error:

CHAIN INTEGRITY FAILURE
  Event: a1b2c3d4e5f6
  Expected prev: z9y8x7w6v5u4
  Actual prev:   z9y8x7w6v5u3
  Position: event #4,721 of 12,847

  The LEDGER has been tampered with.
  Restore from backup: magic ledger --restore --from backup-2026-03-09.json

Verification is O(n) — it reads every event. For 100,000 events, verification takes seconds; for 10 million events at hospital-network scale, minutes. The linear cost is acceptable because verification is an audit operation, not a runtime operation.

13.7 Storage Architecture

The LEDGER is stored as an append-only JSON lines file with periodic snapshots:

~/.canonic/services/ledger/
  ├── ledger.jsonl              ← append-only event log (one JSON per line)
  ├── snapshots/
  │   ├── 2026-01.json          ← monthly snapshot (reconciled)
  │   ├── 2026-02.json
  │   └── 2026-03.json          ← current month in progress
  ├── index/
  │   ├── by-user.json          ← user → event ID list
  │   ├── by-scope.json         ← scope → event ID list
  │   ├── by-event.json         ← event type → event ID list
  │   └── by-date.json          ← date → event ID list
  └── signatures/
      ├── a1b2c3d4.sig          ← Ed25519 signature per event (post-cutoff)
      └── ...

JSON lines format. One event per line. New events append to the end. The file is never rewritten, never truncated, never modified in place — the service opens it in O_APPEND mode and never calls seek or truncate ¹².

Monthly snapshots. At each CLOSE event (monthly reconciliation), the LEDGER service writes a snapshot of the current month’s events. The snapshot is a complete, self-contained record of that month’s economic activity. Snapshots serve three purposes: (1) fast queries scoped to a single month, (2) backup and restore operations, (3) regulatory audit submissions requiring monthly granularity.

Indexes. Four thin indexes provide O(1) lookup by user, scope, event type, and date. The indexes are derived artifacts — they can be regenerated from ledger.jsonl at any time. The _generated principle applies: if an index is corrupted, regenerate it from the source, do not repair it.

Ed25519 signatures. After the signing cutoff (configured per deployment), every new event is signed with Ed25519. The signature covers the event JSON (excluding the signature field itself) and provides cryptographic non-repudiation — a signed event cannot be denied by its creator ¹².

13.8 The CLOSE Event and Monthly Reconciliation

The CLOSE event is the monthly reconciliation. It computes the month’s economic summary and freezes the month’s LEDGER:

{
  "id": "close-2026-02",
  "prev": "last-event-hash",
  "ts": "2026-02-28T23:59:59Z",
  "event": "CLOSE",
  "user": "system",
  "amount": 0,
  "delta": 0,
  "summary": {
    "total_minted": 4721,
    "total_debited": 312,
    "total_transferred": 1847,
    "total_spent": 923,
    "total_settled": 0,
    "net_velocity": 4409,
    "active_users": 47,
    "active_scopes": 73,
    "events_recorded": 1284
  },
  "signature": "ed25519hex..."
}

After the CLOSE event is written, the month’s snapshot is frozen. No new events can be added to a closed month. Corrections go forward as new events in the next month — never backward. Standard double-entry bookkeeping ¹².

The CLOSE event also produces the monthly governance report that administrators need: governance work done (total_minted), drift incurred (total_debited), active scopes, and net governance velocity. Computed from governed events — not estimated from activity logs.

13.9 The TRANSFER Event and Fee Structure

The TRANSFER event moves COIN between users. Every transfer incurs a 5% fee:

{
  "id": "transfer-789abc",
  "prev": "previous-hash",
  "ts": "2026-03-05T10:15:00Z",
  "event": "TRANSFER",
  "user": "memorial-health-system",
  "amount": 100,
  "delta": -100,
  "fee": 5,
  "recipient": "hadleylab",
  "recipient_delta": 95,
  "work_ref": "SERVICES/TALK/MAMMOCHAT/LICENSE",
  "signature": "ed25519hex..."
}

The 5% fee is the governance tax — it funds the validators, the compilers, the LEDGER service itself. Not negotiable. The TRANSFER event type includes a fee field that is always 5% of the amount, debited before crediting the recipient ¹².

13.10 The DEBIT:DRIFT Event

DEBIT:DRIFT is the governance penalty. When a scope’s governance score regresses — from 255 to 191, from FULL to ENTERPRISE, from compliant to non-compliant — the LEDGER records a DEBIT:DRIFT event that debits COIN from the scope maintainer’s WALLET:

{
  "id": "drift-456def",
  "prev": "previous-hash",
  "ts": "2026-03-07T08:30:00Z",
  "event": "DEBIT:DRIFT",
  "user": "dr-chen",
  "amount": 64,
  "delta": -64,
  "work_ref": "SERVICES/TALK/ONCOCHAT",
  "drift_from": 255,
  "drift_to": 191,
  "dimensions_lost": ["E", "L"],
  "cause": "Model update without validation",
  "signature": "ed25519hex..."
}

The debit amount equals the score regression: 255 - 191 = 64 COIN. Proportional to the damage — a small regression (255 to 243, -12 COIN) penalizes less than a catastrophic one (255 to 0, -255 COIN). Regression costs COIN. Advancement earns COIN. The LEDGER tracks both ¹².

DEBIT:DRIFT captures governance negligence with full context: which dimensions were lost, what caused the drift, and how much COIN was debited. Query the LEDGER for all DEBIT:DRIFT events across the clinical AI fleet and you can identify which scopes are most prone to drift — a governance quality metric that no other system provides.

13.11 Error Handling and Failure Modes

The LEDGER handles four categories of failure:

1. Hash chain corruption. If the magic ledger --verify command detects a broken hash chain, the LEDGER is flagged as compromised. All LEDGER operations pause until the corruption is resolved:

CRITICAL: LEDGER hash chain broken at event #4,721.
  All LEDGER writes suspended.
  Restore from last verified snapshot:
    magic ledger --restore --from snapshots/2026-02.json
  Replay events after restoration.

2. Concurrent write conflict. If two services attempt to append to the LEDGER simultaneously (TALK session and SHOP checkout), the append-mode file semantics handle the concurrency — O_APPEND is atomic on POSIX systems for writes under the pipe buffer size. For LEDGER events (typically under 1KB), the atomicity guarantee holds. For deployments that exceed this limit, the LEDGER service serializes writes through a queue.

3. Signature verification failure. If an event’s Ed25519 signature does not verify against the event’s JSON content, the event is flagged as potentially tampered:

SIGNATURE FAILURE: event a1b2c3d4
  Signature does not match event content.
  Possible causes: event modified after signing,
    key rotation without re-signing.
  Action: Flag for manual audit.

4. CLOSE reconciliation mismatch. If the CLOSE event’s summary totals do not match the sum of the month’s individual events, the reconciliation fails:

RECONCILIATION FAILURE: 2026-02 CLOSE
  Expected total_minted: 4,721 COIN
  Computed total_minted: 4,709 COIN
  Discrepancy: 12 COIN (3 events)
  Fix: Investigate discrepant events before closing.

13.12 Clinical Vignette: HIPAA Audit Response

A hospital undergoes a HIPAA compliance audit. The auditor requests evidence of activity monitoring for all clinical AI systems (§164.312(b)). The team responds with LEDGER data.

Audit request 1: “Show all clinical AI interactions for Q1 2026.”

magic ledger --event MINT:WORK --scope SERVICES/TALK \
  --from 2026-01-01 --to 2026-03-31

Result: 4,721 governed sessions across five TALK agents. Each timestamped, attributed to a verified user, and hash-chained.

Audit request 2: “Show evidence of access controls.”

magic ledger --event TRANSFER --scope SERVICES/TALK \
  --from 2026-01-01 --to 2026-03-31

Result: 47 TRANSFER events showing COIN-gated access to clinical AI services. Each transfer shows the buyer, seller, amount, fee, and scope.

Audit request 3: “Show evidence of integrity controls.”

magic ledger --verify --from 2026-01-01 --to 2026-03-31

Result: 12,847 events verified. Hash chain intact. Zero integrity failures. Ed25519 signatures verified for all events after signing cutoff. The auditor has cryptographic proof that the LEDGER has not been tampered with.

The hospital passes. Three categories of evidence — activity monitoring, access controls, integrity controls — from a single governed data source. No separate audit log system. No manual evidence collection ².

13.13 Clinical Vignette: Governance Velocity Dashboard

A health system’s chief quality officer requests a governance velocity dashboard for the clinical AI program:

magic ledger --velocity --from 2026-01-01 --to 2026-03-31 --by-scope

Result:

Positive governance velocity: 4,721 COIN minted versus 76 drifted, a 1.6% drift rate. OncoChat’s March 7 drift event (model update without validation) resolved within 24 hours. None of this is a report someone wrote — it is a computation over governed LEDGER events, exact to the COIN ¹².

13.14 The SETTLE Event and Fiat Exit

The SETTLE event converts COIN to monetary value — the fiat exit from the governed economy:

{
  "id": "settle-789abc",
  "prev": "previous-hash",
  "ts": "2026-03-10T16:00:00Z",
  "event": "SETTLE",
  "user": "hadleylab",
  "amount": 1000,
  "delta": -1000,
  "fiat_amount": "$1,000.00",
  "fiat_currency": "USD",
  "settlement_method": "ACH",
  "work_ref": "SETTLE/2026-03-Q1",
  "signature": "ed25519hex..."
}

SETTLE is the only event that crosses the COIN-to-fiat boundary. All other events operate entirely within the COIN economy. SETTLE debits COIN from the user’s WALLET and triggers a fiat payment through the configured settlement method. COIN = WORK, and SETTLE converts WORK to USD ¹².

13.15 LEDGER Capacity Planning

For health systems scaling from pilot to enterprise deployment, LEDGER capacity grows linearly with governance activity:

Storage is bounded — events are typically 200-500 bytes each. Monthly snapshots keep query performance constant regardless of total LEDGER size: single-month queries hit the snapshot, multi-month queries merge them.

# Check current LEDGER capacity metrics
magic ledger --capacity
# Events: 47,231
# Size: 22.4 MB
# Oldest event: 2025-11-01T00:00:00Z
# Newest event: 2026-03-10T16:45:00Z
# Snapshots: 5 (monthly)
# Indexes: 4 (by-user, by-scope, by-event, by-date)
# Verification estimate: 12 seconds

For regulated environments requiring long-term retention (HIPAA: 6 years, SOX: 7 years), snapshots are immutable files — archive them to cold storage. The LEDGER never forgets. The retention requirement is architecturally satisfied.

13.16 Closure

Eight exhaustive event types. Hash-chained for tamper evidence (see Chapter 17). Ed25519-signed for non-repudiation. Monthly-reconciled via CLOSE. Queryable for governance analytics. Verifiable for audit compliance. Four regulatory standards (HIPAA, FDA 21 CFR Part 11, SOX, Joint Commission) from a single data source. The WALLET (Chapter 14) projects per-user views of this chain. The VAULT (Chapter 15) gates private access. MONITORING (Chapter 22) surfaces LEDGER metrics in real time. Remove the LEDGER and the governed economy has no memory. Remove the memory and governance is fiction ¹².

Chapter 14: WALLET

COIN. Per-USER economic identity. The account that computes itself ¹². The WALLET is the per-principal projection of the LEDGER (Chapter 13), secured by the CHAIN integrity layer (Chapter 17) and gated by VAULT auth (Chapter 15).

14.1 Axiom

WALLET stores COIN for every USER. Every event signed. Balance derived, never stored ¹².

A traditional account stores a balance and hopes it stays consistent. The WALLET stores an event chain — an append-only sequence of credits and debits — and derives the balance by walking it: balance = SUM(credits) - SUM(debits). If the balance is always computed, it can never be stale, corrupted, or inconsistent with the underlying events. An entire class of financial accounting bugs vanishes ¹².

The architecture maps directly to healthcare audit requirements. HIPAA §164.312(b) requires tamper-evident audit logs. The WALLET’s append-only, hash-linked chain satisfies this by construction. Walk the chain to verify a clinician’s governance activity — every MINT:WORK event, every SPEND, every DEBIT:DRIFT is there, signed and verifiable.

14.2 Append-Only Event Chain

No mutable balance field. No stored state that can drift from reality. The WALLET is its chain:

balance(user) = SUM(credits) - SUM(debits) FROM timeline(user)

Every event in the chain is hash-linked to its predecessor. The chain is a directed acyclic graph from the user’s first event (typically MINT:SIGNUP) to the current head. Walking the chain backward from head to genesis verifies integrity: if any event has been tampered with, the hash of every subsequent event breaks ¹².

{
  "id": "wallet:dexter:evt:00047",
  "prev": "wallet:dexter:evt:00046",
  "ts": "2026-03-10T14:30:00Z",
  "type": "MINT:WORK",
  "amount": 92,
  "scope": "hadleylab-canonic/BOOKS/CANONIC-DOCTRINE",
  "signature": "ed25519:a1b2c3d4..."
}

The prev field is the critical integrity mechanism. It links each event to its predecessor by hash. The signature field provides non-repudiation — the user’s Ed25519 private key signs each event after the cutoff date. Together, prev and signature make the WALLET chain both tamper-evident and attributable ¹².

14.3 The 7 Invariants

The WALLET enforces seven invariants that guarantee balance consistency, non-negativity, and conservation across the system. For the formal specification of these invariants, including the conservation equation and proof obligations, see Chapter 32, Section 32.5 (WALLET Invariants). From the user’s perspective, the invariants mean that vault verify-wallet detects any violation and reports it, and that the WALLET is a financial instrument with built-in controls satisfying SOX §404 requirements for internal control over financial reporting ¹².

14.4 Dual-Write Architecture

Every COIN event writes to two targets simultaneously: the global LEDGER and the per-principal WALLET timeline. The WALLET implements this dual-write architecture to ensure consistency between the LEDGER and the WALLET balance; for the complete dual-write specification and failure-mode analysis, see Chapter 32, Section 32.6 (Dual-Write Protocol). For the user, the practical consequence is that a compliance team can audit governance activity from three independent sources: the individual clinician’s WALLET, the hospital’s organizational timeline, and the global LEDGER. Cross-referencing these three sources provides the assurance level that healthcare regulators require ¹².

14.5 Monthly CLOSE

The CLOSE operation runs monthly and reconciles every WALLET against the LEDGER, verifying that the sum of all WALLET balances equals total circulation. For the complete CLOSE specification, conservation equation, and reconciliation algorithm, see Chapter 32, Sections 32.4 (CLOSE Protocol) and 32.8 (Conservation Proof). From the user’s perspective, CLOSE produces a per-principal verification report:

$ vault close --month 2026-03
Processing 47 wallets...
  dexter: balance=12,847 verified ✓
  isabella: balance=3,420 verified ✓
  ...
Circulation: 187,340 COIN
Unreconciled: 0
Mismatches: 0
CLOSE event appended to all timelines.

The CLOSE event is itself a LEDGER event, so if a regulator asks “when was the last reconciliation?” the answer is the timestamp of the last CLOSE event on the LEDGER. The reconciliation trail is self-documenting ¹².

14.6 The WALLET in Healthcare Governance

In most hospitals, clinical AI governance is invisible — it happens in meetings, emails, and policy documents that no one reads. The WALLET makes it an economic event:

• Per-clinician tracking: Every clinician interacting with clinical AI has a WALLET. Governance contributions (reviewing AI outputs, validating recommendations, flagging errors) are MINT:WORK events. Their governance track record is on the chain.
• Per-department aggregate: The organizational timeline aggregates activity by department. The CMO sees which departments are actively governing their AI deployments — and which are not.
• Institutional economics: Total COIN minted is total governance work performed. Total DEBIT:DRIFT is total governance regression. The ratio is institutional governance velocity.

Governance work mints COIN. Governance neglect costs COIN. The incentive structure is architectural ²².

14.7 WALLET CLI Operations

$ vault user-wallet dexter
# Balance: 12,847 COIN | Events: 347 | Last: MINT:WORK +92

$ vault user-timeline dexter --last 5
# evt:00343 MINT:WORK +128 SERVICES/COMPLIANCE 127→255
# evt:00344 SPEND -255 SHOP/FHIR-PLAYBOOK
# evt:00345 MINT:WORK +35 SERVICES/NEW-SCOPE 0→35
# evt:00346 TRANSFER -100 → isabella (fee: 5)
# evt:00347 MINT:WORK +92 BOOKS/DOCTRINE 163→255

$ vault verify-wallet dexter
# Hash chain: INTACT (347/347) | Signatures: 298/347 | Status: VERIFIED

14.8 WALLET Error Handling

14.9 WALLET Data Structure

{
  "principal": "dexter",
  "created": "2025-11-01T00:00:00Z",
  "balance": 12847,
  "events": 347,
  "head": "wallet:dexter:evt:00347",
  "last_close": "2026-02-28T23:59:59Z",
  "pubkey": "ed25519:a1b2c3d4...",
  "status": "ACTIVE"
}

The WALLET JSON is _generated — derived from the LEDGER. If the JSON is wrong, fix the LEDGER. Run vault reconstruct. The _generated contract applies ².

14.10 WALLET Capacity

14.11 Clinical Vignette: Governance Portfolio

Dr. Chen governs five scopes. Her WALLET reflects the portfolio:

$ vault user-wallet dr.chen --by-scope
# MAMMOCHAT: 255 COIN (complete)
# ONCOCHAT: 255 COIN (complete)
# FHIR-API: 255 COIN (complete)
# HIPAA: 255 COIN (complete)
# RADIOLOGY/AI: 127 COIN (in progress)
# MINT:SIGNUP: 500 COIN
# MINT:PYRAMID: 1,000 COIN (2 referrals)
# SPEND: -362 COIN (purchases)
# Balance: 3,285 COIN

Dr. Chen’s WALLET is her governance resume — a cryptographically signed event chain. A hiring committee runs vault verify-wallet dr.chen and confirms every claim ¹².

14.12 WALLET and Regulatory Reporting

Generate per-principal audit reports at any time:

$ vault audit-report dr.chen --period 2026-Q1 --format pdf
# Generating audit report...
# Principal: dr.chen@hadleylab.org
# Period: 2026-01-01 to 2026-03-31
# MINT:WORK events: 12 (governance labor)
# DEBIT:DRIFT events: 0 (no regressions)
# SPEND events: 3 (product purchases)
# TRANSFER events: 2 (COIN transfers)
# Net COIN: +1,147
# Chain integrity: VERIFIED
# Report saved: audit-dr.chen-2026-Q1.pdf

Derivable from the LEDGER at any time. No manual report generation. No quarterly surveys. The report is the chain ¹².

14.13 Clinical Vignette: WALLET Forensics After a Governance Incident

University of Michigan Health deploys CardiChat — a governed TALK agent for ACC/AHA heart failure guideline navigation. Six months in, MONITORING flags a drift: CardiChat drops from 255 to 191. The DEBIT:DRIFT event debits 64 COIN from the governance team’s WALLET.

The governance officer investigates:

vault user-timeline carditeam@umich.edu --scope SERVICES/TALK/CARDICHAT --last 10
# evt:00892 MINT:WORK +128 SERVICES/TALK/CARDICHAT 127->255 (2025-10-15)
# evt:00893 MINT:WORK +0   neutral edit (2025-11-01)
# evt:00894 MINT:WORK +0   neutral edit (2025-12-15)
# evt:00895 MINT:WORK +0   neutral edit (2026-01-10)
# evt:00896 DEBIT:DRIFT -64 SERVICES/TALK/CARDICHAT 255->191 (2026-03-08)
#   Cause: LEARNING.md stale — no new entries in 90 days
#   Question lost: What have you learned? (LEARNING.md deleted)
#   Commit: abc1234 by intern@umich.edu

Root cause: a medical intern committed a code change to CardiChat’s response templates. The pre-commit hook was not installed on the intern’s workstation (new hire, incomplete onboarding). The commit modified response formatting but did not update LEARNING.md. MONITORING detected the staleness 90 days later when the freshness threshold expired.

The recovery procedure:

# Step 1: Record the incident in LEARNING.md
echo "| 2026-03-08 | DRIFT | LEARNING stale — intern commit bypassed
pre-commit hook. Root cause: onboarding gap. Fix: mandatory hook
install in first-day checklist. | Governance incident |" >> LEARNING.md

# Step 2: Add current patterns from the last 90 days
echo "| 2026-03-08 | PATTERN | Heart failure patients ask about SGLT2i
(dapagliflozin, empagliflozin) 4x more than beta-blockers. Update
evidence priority. | Usage analytics |" >> LEARNING.md

# Step 3: Commit and validate
git add LEARNING.md
git commit -m "GOV: CARDICHAT — restore LEARNING, record drift incident"
magic validate
# Score: 255/255 (restored)
# MINT:WORK +64 COIN (recovery)

The WALLET now shows the full incident timeline: drift, debit, recovery. Net COIN impact: zero (64 debited, 64 recovered). But LEARNING.md is richer — it contains both the drift incident pattern and the clinical usage pattern about SGLT2 inhibitor queries. Governance improved because the system detected, penalized, and recovered from the failure automatically ¹².

14.14 WALLET Cross-Reference Verification

The WALLET supports cross-reference verification — confirming that events recorded in one principal’s WALLET match events recorded in another:

vault cross-reference alice@hospital.org bob@hospital.org
# Shared events: 3
#   evt:00234 TRANSFER alice->bob 100 COIN (2026-02-15)
#     alice: DEBIT 100 COIN + 5 FEE -> VERIFIED
#     bob:   CREDIT 95 COIN         -> VERIFIED
#   evt:00267 SPEND alice bought bob's product 255 COIN (2026-02-28)
#     alice: DEBIT 255 COIN         -> VERIFIED
#     bob:   CREDIT 255 COIN        -> VERIFIED
#   evt:00301 TRANSFER bob->alice 50 COIN (2026-03-05)
#     bob:   DEBIT 50 COIN + 2.5 FEE -> VERIFIED
#     alice: CREDIT 47.5 COIN        -> VERIFIED
# Cross-reference: ALL MATCH

Double-entry bookkeeping, CANONIC-style. Every transaction appears in two WALLETS. The amounts must balance. CLOSE verifies this for all principals. If a discrepancy is found, the LEDGER is the tiebreaker ¹².

14.15 WALLET Privacy Architecture

WALLET data is tiered by privacy level:

Organizational transparency (public balance) coexists with individual privacy (private event details). Publish department-level governance metrics without exposing individual clinician activity. The VAULT auth gate (Chapter 15) enforces the tiering ¹²¹⁵.

14.16 WALLET Lifecycle States

vault lifecycle dr.chen@hadleylab.org
# State: ACTIVE
# Created: 2025-11-01
# Events: 347
# Last event: 2026-03-10 (today)
# Days active: 130

When a clinician leaves, their WALLET transitions to CLOSED. The event chain is sealed — no new events — but remains readable for audit purposes. COIN balance transfers to a successor WALLET or returns to TREASURY. The transition is itself a LEDGER event, providing the audit trail HIPAA requires for workforce clearance procedures ¹².

14.17 WALLET Performance Characteristics

At hospital scale (200 wallets, 10,000 events/month), CLOSE completes in under 5 seconds. Individual wallet verification: under 100ms. Performance is bounded by chain length, which grows linearly. For multi-year deployments, archival of settled events keeps active chains manageable ¹².

14.18 Governance Proof: The WALLET as Financial Instrument

The WALLET satisfies financial instrument requirements under healthcare accounting standards:

1. Verifiability. Any balance can be independently verified by walking the chain: balance = SUM(credits) - SUM(debits). No hidden state.
2. Non-repudiation. Ed25519 signatures on events prevent participants from denying transactions.
3. Tamper-evidence. Hash-linked chain breaks on any modification. Tampering is detectable in O(n).
4. Reconcilability. Monthly CLOSE cross-references USER timelines, ORG timelines, and LEDGER. Three independent records.
5. Auditability. Any regulator can run vault verify-wallet and vault audit-report to produce complete audit documentation.
6. Conservation. Total COIN in circulation equals SUM of all active WALLET balances. Verified at every CLOSE.

These six properties satisfy SOX §404 (internal controls), HIPAA §164.312(b) (audit controls), and GAAP requirements for financial recording. The WALLET is not a database row storing a number — it is a cryptographically verified, append-only, hash-linked financial instrument that computes its own balance. The proof is the chain. Q.E.D. ¹²¹⁵.

14.19 WALLET Migration Between Organizations

When a clinician transfers between health systems, their WALLET migrates intact — no history lost.

vault migrate dr.chen@hospital-a.org dr.chen@hospital-b.org

# Migration plan:
#   Source: hospital-a-canonic WALLET (347 events, 1,240 COIN)
#   Target: hospital-b-canonic WALLET (new)
#
#   Step 1: Seal source WALLET (no new events)
#   Step 2: Export signed event chain
#   Step 3: Verify chain integrity at target
#   Step 4: Import chain into target WALLET
#   Step 5: Transfer COIN balance (1,240 COIN)
#   Step 6: Record WALLET:MIGRATE on both LEDGERs
#
# Execute? [y/N] y
# Migration complete.
#   Source: CLOSED (sealed at evt:347)
#   Target: ACTIVE (347 imported events + WALLET:MIGRATE)
#   Balance: 1,240 COIN (verified)

Both organizations’ LEDGERs record the event — Hospital A logs WALLET:MIGRATE_OUT, Hospital B logs WALLET:MIGRATE_IN. Every scope governed, every COIN minted, every LEARNING contributed transfers intact. The receiving organization verifies the entire chain independently ¹²¹⁹.

14.20 WALLET Consolidation for Multi-Role Identities

Clinicians serving multiple roles (attending physician, researcher, governance officer) may accumulate COIN across multiple WALLET addresses. Consolidation merges them:

vault consolidate \
  --primary dr.chen@hadleylab.org \
  --merge dr.chen-research@hadleylab.org \
  --merge dr.chen-governance@hadleylab.org

# Consolidation plan:
#   Primary: dr.chen@hadleylab.org (847 events, 2,100 COIN)
#   Merge 1: dr.chen-research (123 events, 340 COIN)
#   Merge 2: dr.chen-governance (56 events, 180 COIN)
#   Result: dr.chen@hadleylab.org (1,026 events, 2,620 COIN)
#
# Consolidation produces WALLET:MERGE events on LEDGER.
# Merged WALLETs are sealed (CLOSED state).
# All historical events remain queryable via merged chain.

Complete provenance is preserved. Each merged event retains its original attribution — governance work performed under dr.chen-research remains attributable to the research role after consolidation. The result is the union of all chains, ordered by timestamp ¹².

14.21 WALLET Delegation

When a governance officer manages COIN on behalf of team members, WALLET supports delegation with defined limits. Delegates can mint and transfer but cannot settle (fiat exit) or close:

vault delegate \
  --wallet dr.chen@hadleylab.org \
  --delegate intern.garcia@hadleylab.org \
  --permissions MINT,TRANSFER \
  --limits "MINT:255/commit,TRANSFER:500/day" \
  --expires 2026-06-10

# Delegation recorded: WALLET:DELEGATE on LEDGER
# Delegate: intern.garcia@hadleylab.org
# Expires: 2026-06-10

Delegation is a LEDGER event. Every delegate action is attributed to the delegate identity with the delegation reference. Revocation at any time via WALLET:REVOKE_DELEGATE — also a LEDGER event ¹²¹⁵.

Chapter 15: VAULT

COIN + INTEL. Private economic aggregate. The encrypted counterpart to the public SHOP (Chapter 12; extended in Chapter 34) ¹⁵. The VAULT projects LEDGER data (Chapter 13), WALLET balances (Chapter 14), and MONITORING metrics (Chapter 22) through an auth gate.

15.1 Axiom

VAULT aggregates private projections from all services. Auth-gated. Ledger-backed. The private mirror of SHOP ¹⁵.

SHOP shows the world what you sell. VAULT shows you how the business runs. Both use the same discovery mechanism — filesystem walk — and the same compilation pipeline. The only difference is the auth gate. VAULT.md files create private projections restricted to authorized principals. No separate database. Same governance tree, different audience ².

15.2 The Dual Projection Model

Every service in CANONIC can project into two surfaces:

Service → SHOP.md  (public)   → discovered by SHOP compiler → visible to everyone
Service → VAULT.md (private)  → discovered by VAULT compiler → visible to authed principals

A service can have both projections, only one, or neither. The projection files are the governed interface between the service and its audiences ².

15.3 VAULT Structure

The VAULT aggregates private data across services into a single auth-gated surface:

~/.canonic/vault/
  ├── LEDGER/        ← economic event history (private dashboard)
  ├── MAGIC/         ← compute economics (GPU costs, provider spend)
  ├── WALLET/        ← per-user COIN balance and timeline
  ├── ANALYTICS/     ← governance metrics, drift tracking
  └── ADMIN/         ← user management, access control

Each directory corresponds to a service’s private projection. Not a monolithic dashboard — a composable aggregate of service-level views. Add a VAULT.md to a service and its private projection appears automatically ¹⁵.

15.4 Auth Architecture

VAULT auth uses GitHub OAuth as the KYC anchor. The auth flow:

1. User requests VAULT resource → /vault/{service}/
2. VAULT checks session → KV-backed session token (not client localStorage)
3. If no session → redirect to GitHub OAuth
4. GitHub returns identity → verify against CANON.md readers/writers list
5. If authorized → grant access, set session
6. If unauthorized → deny (fail-closed)
7. Auth event → LEDGER (login, grant, or deny recorded)

Auth is fail-closed: if identity cannot be verified, access is denied. HIPAA requires the default to be deny, not allow. Every auth event (login, logout, grant, deny) is recorded on the LEDGER ¹⁵.

15.5 VAULT CLI

The vault command-line tool manages VAULT operations:

$ vault keygen dexter                    # generate Ed25519 key pair
$ vault auth dexter                      # authenticate principal
$ vault mint dexter 92 --scope DOCTRINE  # mint COIN for governance work
$ vault drift dexter 15 --scope ONCOCHAT # debit for governance regression
$ vault transfer dexter isabella 100     # transfer COIN (5% fee)
$ vault spend dexter 255 --product CANON # purchase product
$ vault settle dexter 1000 --fiat USD    # fiat exit
$ vault close --month 2026-03            # monthly reconciliation
$ vault user-wallet dexter               # show wallet state
$ vault user-timeline dexter             # show event timeline
$ vault verify-wallet dexter             # verify chain integrity
$ vault reconcile                        # cross-check all wallets vs LEDGER

State-modifying commands produce LEDGER events. Read-only commands do not. The CLI is the administrative interface to the CANONIC economy ¹⁵.

15.6 VAULT and Clinical Data Governance

The pattern separates governance into two surfaces:

• Public (SHOP): Product availability, pricing, governance scores, tier status. The procurement surface.
• Private (VAULT): Usage analytics, cost tracking, drift events, clinician governance activity. The operations surface.

A hospital’s MammoChat product page (SHOP) shows pricing and evidence citations — intentionally public. The MammoChat governance dashboard (VAULT) shows usage metrics, drift alerts, and activity logs — necessarily auth-gated. Right data, right audience, right gate. SHOP for procurement. VAULT for operations. Both governed. Both discoverable. Both on the LEDGER ^{2 15}.

15.7 VAULT Data Flow Architecture

The VAULT stores nothing — it projects data from governed sources through an auth gate:

Source Service          VAULT Projection          Consumer
─────────────          ────────────────          ────────
LEDGER events     →    /vault/LEDGER/       →    Governor dashboard
WALLET balances   →    /vault/WALLET/       →    User account page
MONITORING metrics →   /vault/ANALYTICS/    →    Ops team dashboard
MAGIC compute logs →   /vault/MAGIC/        →    Cost tracking view
IDENTITY records  →    /vault/ADMIN/        →    Admin user list

Each arrow is a read-only projection, filtered by the principal’s permissions. The VAULT never duplicates source data — it reads from the canonical location and renders through its auth-gated surface ¹⁵.

Projections are compiled, not configured. The VAULT compiler walks the tree, discovers all VAULT.md files, and generates the projection map:

# Compile VAULT projections
build --vault

# Output: _data/vault.json
{
  "_generated": true,
  "compiled_at": "2026-03-10T14:00:00Z",
  "projections": [
    {
      "source": "SERVICES/LEDGER",
      "vault_path": "/vault/LEDGER/",
      "auth_level": "WRITER",
      "projection_type": "DASHBOARD"
    },
    {
      "source": "SERVICES/WALLET",
      "vault_path": "/vault/WALLET/",
      "auth_level": "OWNER",
      "projection_type": "ACCOUNT"
    }
  ]
}

The _generated: true flag applies. Do not hand-edit _data/vault.json. Fix the VAULT.md files or the VAULT compiler instead.

15.8 VAULT Encryption at Rest

VAULT data projections traverse an encryption layer before reaching the auth-gated surface. The encryption model:

Plaintext source → Ed25519 signing → AES-256-GCM encryption → Auth gate → Decrypted view

Key management is scope-based. Each scope with a VAULT.md has its own encryption context:

Encryption is not optional. Every VAULT projection is encrypted at rest and in transit. Generate the key pair that anchors a principal’s identity:

# Generate key pair for a new principal
vault keygen dr-martinez

# Output:
# Public key:  vault/keys/dr-martinez.pub
# Private key: vault/keys/dr-martinez.key (NEVER commit)
# Fingerprint: SHA256:a1b2c3d4e5f6...
# Added to:    CANON.md readers list

The private key never enters the governance tree. The public key is referenced in CANON.md for authorization. The fingerprint is recorded on the LEDGER as the principal’s cryptographic identity ².

Ed25519: Enforced

Ed25519 signing is no longer optional. As of March 2026, every LEDGER event is signed. The enforcement is a hard CI gate: vault verify-sig runs in build phase 09-econ and exits with code 1 on any unsigned event.

Fleet-wide status: zero unsigned events across all 9 principals. Key rotation is governed — vault key-status shows key age, and the KEY_ROTATION hardening gate (CLOSED) ensures rotation happens on schedule.

The signature cutoff marks the boundary between legacy (unsigned CONSTRUCTION-era events) and production (all events signed). Events before the cutoff are grandfathered. Events after the cutoff must be signed or the build fails.

15.9 VAULT Key Management

No external PKI. Keys are governed by the same CANON.md that governs everything else.

Key lifecycle:

GENERATE → ACTIVE → ROTATING → ROTATED → REVOKED

Each transition is a LEDGER event:

# Rotate a principal's key (generates new key, marks old key as ROTATING)
vault rotate dr-martinez

# Output:
# New key generated: vault/keys/dr-martinez-2026-03.pub
# Old key status:    ROTATING (grace period: 72h)
# LEDGER event:      VAULT:KEY_ROTATE recorded
# After 72h:         Old key → ROTATED (read-only, no new sessions)

# Revoke a key immediately (emergency action)
vault revoke dr-martinez --reason "departure"

# Output:
# Key status:    REVOKED
# Active sessions: TERMINATED (3 sessions closed)
# LEDGER event:  VAULT:KEY_REVOKE recorded
# VAULT access:  DENIED for all projections

Key management rules: