GaiaFTCL Mac Cell — Sovereign M⁸ Technical Guide¶

New here? Start with these.¶

This page is the technical guide. It's dense on purpose — it's the reference manual for engineers shipping the cell.

If you have never opened Franklin.app before, do not start here. Start with one of these plain-English pages instead, then come back:

Franklin First — your first five minutes with the cell.
Reading the Franklin Window — what every label, chip, and shape on the screen means.
Scene Strip: The Five Rooms — a tour of M⁸, QUANTUM, FUSION, HEALTH, LITHO.
Cell Boot Recall — how the cell remembers itself every time it wakes up.
License Readiness — new (v107) — how a cure crosses to a human and becomes licensable, across all 70 language games.
The Reflective Mesh — new (v102/v104/v105) — the five actors that watch the cell while you work.
Licensing in Plain Words — what the LICENSING button does and why it's there.

These pages are written for a junior-high reader. You can read all of them in about forty minutes and you will understand the cell well enough to use it. The rest of this page is for the people building the cell.

What This Is¶

GaiaFTCL M⁸ is a sovereign macOS application — Franklin.app — that embodies an eight-dimensional manifold: four structural dimensions (S1–S4) and four constitutional dimensions (C1–C4). It runs entirely in pure Swift 6.2 on Apple Silicon, ships as a single ad-hoc-signed DMG, and is qualified to GAMP 5 (156 build-time tests + 18 in-app IQ/OQ/PQ checks).

Three processes, one NATS bus, no external dependencies:

Franklin.app
  ├── Franklin (SwiftUI macOS app)
  │     ├── FranklinSceneView   — RealityKit S4 projection layer
  │     ├── FranklinDriver      — sovereign gate: propose(_:origin:)
  │     └── SwiftNATSServer     — embedded NATS broker on 127.0.0.1:4222
  │
  ├── VQbitVM (child process)
  │     ├── S4DeltaWire → ManifoldTensorStore → C4ProjectionWire pipeline
  │     ├── VQbitMeasurementGate — Bell/CHSH gates, constitutional invariants
  │     └── Publishes: gaiaftcl.vm.ready · gaiaftcl.vm.heartbeat (30s)
  │
  └── FranklinConsciousnessService (child process)
        ├── FranklinConsciousnessActor — C4 projection loop, self-review
        ├── GRDB substrate — SQLite v1→v11 migrations
        └── Publishes: gaiaftcl.franklin.consciousness.state

The vQbit Data Model¶

Every sovereign state in the M⁸ manifold flows through a VQbitPrimitive — one prim = one domain entity = one point on the eight-dimensional manifold.

// Sources/GaiaFTCLCore/VQbitPrimitive.swift
public struct VQbitPrimitive: Sendable, Codable {
    // S⁴ — structural dimensions
    public var s1_structural:  Float32   // geometry / topology
    public var s2_temporal:    Float32   // time / sequence
    public var s3_spatial:     Float32   // location / space
    public var s4_observable:  Float32   // rendered / visible

    // C⁴ — constitutional dimensions
    public var c1_trust:       Float32   // epistemic authority
    public var c2_identity:    Float32   // prim identity integrity
    public var c3_closure:     Float32   // gate closure state
    public var c4_consequence: Float32   // action consequence weight

    public var primID:         UUID
    public var domain:         String    // FUSION / HEALTH / QUANTUM / etc.
    public var timestampUTC:   String
}

Terminal state derivation from constitutional health mean(c1..c4):

Health range	Terminal state
≥ 0.65	`CALORIE` — value produced
0.35 – 0.65	`CURE` — converging
< 0.35	`BLOCKED` — structural failure
Explicit refusal	`REFUSED` — with closure condition

The Apple Silicon Advantage — Unified Memory¶

Apple Silicon M-chips eliminate the CPU→GPU copy. Memory is unified physical DRAM — both CPU and GPU read from the same physical address. RealityKit entity components updated by C4ProjectionSystem.update() go directly from FranklinDriver's Swift actors to the GPU without a staging buffer or DMA transfer.

S4 Projection Layer (RealityKit)¶

The S4 dimension — "observable" — is rendered by RealityKit. Every domain has a USD scene (FranklinSceneDirector.catalog) with a three-level hierarchy:

def Xform "<FileName>" (kind="group")        ← defaultPrim
    def Xform "<SCOPE_NAME>" (kind="group")  ← must match catalog entry
        def Xform "CatalogAnchor"            ← M⁸ origin for sphere + portals
            …geometry children…

C4ProjectionSystem runs every render tick, reading from C4ManifoldRuntimeBridge (which is only written via FranklinDriver.propose()) and updating RealityKit entity components. Entity state is always derived from validated bridge state — never mutated directly.

The Sovereign Gate¶

Every S4/C4 mutation in the system routes through a single method:

// Sources/GaiaFTCLApp/FranklinDriver.swift
@MainActor
public func propose(_ move: UIProjectionMove,
                    origin: ValidationOrigin,
                    modelContext: ModelContext? = nil) async -> UIValidationResult

VQbitUIValidator runs the move through: 1. Bounds gate — all 8 dimensions ∈ [0, 1] 2. Entropy gate — ΔE = current.health − proposed.health ≤ 0 (health must improve or hold) 3. Terminal gate — proposed state must not be .refused or .blocked 4. Mooring gate — primID must not be the zero UUID

On .closed(receipt): state is committed, ClosureReceiptRecord is persisted to SwiftData, activeTone updates from domain.
On .refused(code, reason): a SHA-256-sealed refused receipt is persisted, activeTone shifts to .diagnostic. No state mutation occurs.

Wire Formats (frozen)¶

Format	Subject	Size	Carries
`S4DeltaWire`	`gaiaftcl.substrate.s4.delta`	53 bytes	One S4 dimension update per prim
`C4ProjectionWire`	`gaiaftcl.substrate.c4projection`	53 bytes	Full C4 constitutional state per prim

Both sizes locked by IQ-007. Any change requires a full GAMP 5 re-qualification.

The Nine-Cell Sovereign Mesh¶

Region	Cells	Purpose
HEL (Helsinki)	hel-01..hel-05	Primary computation
NBG (Nuremberg)	nbg-01..nbg-04	Secondary computation

Quorum: ≥5/9 cells. In standalone sovereign mode (single DMG), VQbitVM's gaiaftcl.vm.heartbeat marks all 9 cells live.

Configuration management¶

Item	Requirement
`S4DeltaWire.byteCount`	53 bytes (CI-007) — change requires full PQ re-execution
`Franklin.usda`	Exactly one authoritative copy in `Sources/GaiaFTCL/Resources/`
`FranklinSceneDirector.catalog`	`scope` must exactly match `def Xform` name in USDA
`language_game_contracts`	`SUM(algorithm_count WHERE domain LIKE 'quantum%') == 19`