System Architecture Specification (SDS)¶

Document reference: GFTCL-SDS-001 · Framework: GAMP 5 Category 5 · EU Annex 11 Verified by: IQ — Installation Qualification

This specification describes the design of the GaiaFTCL vQbit Quantum VM: its components, boundaries, data flows, and persistence. It is the "left arm" of the V-model verified by IQ.

1. System context¶

The system is a single bespoke macOS application, Franklin.app, distributed as a code-signed, notarized DMG and run on operator-controlled Apple Silicon hardware. It has no external runtime dependencies — pure Swift 6.2 / Swift Package Manager. It is a sovereign, self-contained system: the operator configures bounded authority once, and the substrate operates autonomously through Franklin's heartbeat.

Attribute	Value
Distributable	`Franklin.app` / `GaiaFTCL.dmg` (code-signed, notarized)
Platform	macOS 26.0+, Apple Silicon (arm64)
Runtime	Pure Swift 6.2 / SPM; no external services required to start
Substrate geometry	M⁸ = S⁴ × C⁴ (UUM-8D origin geometry)
Compute boundary	The `VQbit` module owns all Metal/Accelerate access

2. Component architecture¶

Franklin is the cell's only public interface. All load-bearing call sites route through FranklinCellSurface. Subsystems are internal implementation detail.

Franklin.app  (single sovereign entry point)
├── Franklin            sovereign orchestrator + cell surface (FranklinCellSurface)
├── VQbitVM             vQbit virtual machine — M⁸ measurement engine (child process)
├── FranklinConsciousnessService   awakening + heartbeat service (child process)
├── VQbit module        compute boundary — owns Metal / Accelerate
├── Substrate store     append-only SQLite (GRDB), federation-cosigned rows
└── Embedded NATS bus   127.0.0.1:4222 — internal subsystem messaging

The 19 C⁴-rail algorithms (QC-001…QC-019) plus QC-020/QC-021 are recipes composed inside the vQbit VM; they call the VQbit API and never import Metal directly.

3. Data architecture¶

The system of record is an append-only SQLite database at ~/Library/Application Support/GaiaFTCL/substrate.sqlite. Every table:

is append-only — BEFORE UPDATE/BEFORE DELETE triggers RAISE(ABORT);
carries a canonical_witness and witness_hash_sha256 (SHA-256 seal);
carries a signature_quintet (federation cosignature, five contexts);
declares a nats_subject_sealed broadcast subject.

Schema versions and their columns are catalogued, generated from source, in the Substrate Schema Catalog. Exact-rational (IntRational) representation is used throughout substrate arithmetic; floating-point amounts are refused at the column level.

4. Interfaces¶

Interface	Surface	Reference
Operator CLI	`gaiaftcl …` — inspection + manual override	CLI Reference
GUI	`Franklin.app` window + in-app qualification runner	Installation Guide
Programmatic read	Python `gaiaftcl` client (read-only)	Programming & API Guide
Federation mesh	NATS sealed subjects, cosignature quintet	Functional Specification

The CLI is a comms projection ingestion surface (Klein-bottle topology): operator messages enter Franklin through projection; there is no direct function-call into Franklin internals.

5. Host-aware capacity¶

At startup the substrate detects host resources (hw.memsize, Metal working set, Apple-silicon generation) and allocates per-algorithm cell capacity proportional to the host — 5% of unified memory ÷ 64 B/cell ÷ 21 algorithms, rounded to a power of two, clamped to [1024, 1,048,576]. The measurement-correctness invariants hold identically at any allocation.

6. Constitutional floor¶

Predicates C-007 (no military aggression), C-008 (no planetary harm), C-009 (Entropy License compliance), C-010 (substrate stress under capacity) are evaluated per measurement and recorded in V174 substrate_constitutional_evaluations. The substrate refuses any operation that breaches the floor.

Cross-references: User Requirements · Functional Specification · Configuration Specification · Franklin as the Cell's Surface.

Federation-cosigned

This page's source is sealed in the GaiaFTCL federation manifest — page SHA-256 ea187d2dd491a572…, manifest witness a090592e0609adc8…, signed 2026-06-02T18:58:22Z by cell gaiaftcl-mac-cell. Verify with gaiaftcl wiki sign --all and compare wiki-all-signatures.json.