GAMP 5 Qualification System

Audience: Engineers running, interpreting, and extending the IQ/OQ/PQ qualification suite.

Updated: 2026-05-05

---

What GAMP 5 means here

GAMP 5 (Good Automated Manufacturing Practice 5) is borrowed from pharmaceutical

software validation. It gives the sovereign qualification a three-phase structure:

---

Test counts

The 156 swift test tests are the build-time gate. The 18 in-app checks are

the live runtime gate — they run inside the shipping Franklin.app against the

actual running stack.

Sovereign loop threshold: ≥155/156 tests passing = CALORIE-eligible.

In-app gate: 18/18 = CALORIE.

---

Running the in-app qualification

1. Launch Franklin.app (from the DMG or directly from .build/)

2. Click the hexagon ⬡ status bar icon → Run Qualification…

3. The Sovereign Qualification window opens.

4. Click RUN QUALIFICATION (top right, teal button).

5. IQ runs immediately, OQ and PQ follow sequentially.

6. Results are written to ~/Library/Application Support/GaiaFTCL/qualification/.

---

IQ checks (7 total)

---

OQ checks (7 total)

OQ-004: Cell quorum in standalone mode

OQ-004 has two pass paths:

Path A — External mesh (production deployment with HEL/NBG nodes):

Mesh edge IQ (deploy tooling tracked + staged): scripts/gamp5_mesh_deploy_iq.sh — see MESH_SUBSTRATE_DEPLOY_GAMP5.md.

liveCells >= CellDescriptor.quorumRequired (5)

liveCells is populated in FranklinDriver when gaiaftcl.cell.<id>.heartbeat

messages arrive from HEL-01..HEL-05 / NBG-01..NBG-04 external nodes.

Path B — Standalone sovereign (single-machine DMG deployment):

stackReady == true  (SovereignStackLauncher.phase == .ready)

VQbitVM is the sovereign substrate. When it publishes gaiaftcl.vm.heartbeat,

FranklinDriver marks all 9 mesh cell IDs live (see NATS architecture doc).

After the first heartbeat (~30s post-launch), OQ-004 passes via Path A with

9/9 cells live. Before the first heartbeat, it passes via Path B.

---

PQ checks (4 total)

---

Receipt files

After each run, three JSON receipts are written:

~/Library/Application Support/GaiaFTCL/qualification/
  IQ-<timestamp>.json
  OQ-<timestamp>.json
  PQ-<timestamp>.json
  qualification.log          ← human-readable one-line-per-phase summary

qualification.log format:

[2026-05-05T20-30-28Z] IQ: CALORIE — 7/7 pass
[2026-05-05T20-30-28Z] OQ: CALORIE — 7/7 pass
[2026-05-05T20-30-28Z] PQ: CALORIE — 4/4 pass

Each JSON receipt has overallStatus ("CALORIE" or "BLOCKED"), platform,

swiftVersion, and a testResults array with id, name, passed, detail,

and durationMs.

---

Adding a new check

1. Add a record(QualResult(...)) call in SovereignQualificationRunner.swift

inside runIQ(), runOQ(), or runPQ().

2. Update the total count comment in this doc.

3. The check is included automatically in the phase receipt.

4. Never change an existing passed: expression to make a failing check pass.

Fix the implementation; the check is the spec.

---

The swift test GAMP 5 suites

The build-time tests live in Tests/GAMP5/ and cover:

LiveGameIntegrationTests (PQ-LIVE-001 and PQ-LIVE-002) are the PQ closure tests:

they run the real FranklinDriver.propose() gate against an in-memory SwiftData

container and assert that every domain produces a sealed ClosureReceiptRecord.

---

Sovereign qualification window — implementation notes

SovereignQualificationWindow (Sources/GaiaFTCLApp/SovereignQualificationWindow.swift)

is a SwiftUI view opened via:

// In GaiaFTCLApp.swift:
Window("Sovereign Qualification", id: "qualification") {
    SovereignQualificationWindow(launcher: launcher)
        .environment(franklinDriver)
        .environment(overlay)
}
.defaultSize(width: 620, height: 580)

// In FranklinMenuBarView:
@Environment(\.openWindow) private var openWindow
Button("Run Qualification…") { openWindow(id: "qualification") }

SovereignQualificationRunner is @Observable @MainActor. Its run() method

stores weak references to FranklinDriver, ManifoldOverlayStore, and

SovereignStackLauncher. Results stream into runner.results as each check

completes, driving the live list in SovereignQualificationWindow.