GaiaFTCL Swift TestRobit — Fusion Cell OQ Harness¶

Document: GFTCL-SWIFT-OQ-001¶

Status: SPECIFICATION (harness implementation pending — see CURSOR_BUILD_PLAN.md Task 12)¶

Framework: GAMP 5 OQ | FDA 21 CFR Part 11 | EU Annex 11¶

Patents: USPTO 19/460,960 | USPTO 19/096,071¶

Overview¶

The GAIAFTCL Swift TestRobit is the Swift-layer OQ harness for the GaiaFTCL Fusion Cell. It mirrors the GaiaHealth Swift TestRobit pattern (66 tests, 5 suites) and validates the Swift-native component boundaries that the GaiaFusion macOS application relies on.

The GaiaHealth TestRobit (already built, 66 tests) is the reference implementation. The GAIAFTCL TestRobit follows the same architecture, test series naming, and receipt format.

Target: 5 suites, ≥30 Swift tests, evidence/testrobit_receipt.json (ALCOA+ compliant)

Architecture¶

GaiaFTCL Swift TestRobit
├── Package.swift                    (Swift Package Manager — .executable target)
├── Sources/GaiaFTCLTestRobit/
│   ├── main.swift                   (harness runner + ALCOA+ receipt writer)
│   ├── TauStateTests.swift          (Suite 1 — τ sovereign time, Swift actor)
│   ├── vQbitABITests.swift          (Suite 2 — vQbitPrimitive ABI + parser)
│   ├── WalletTests.swift            (Suite 3 — zero-PII wallet: gaia1 prefix)
│   ├── OwlProtocolTests.swift       (Suite 4 — Owl identity: 66-char secp256k1)
│   └── RendererTests.swift          (Suite 5 — Metal renderer lifecycle)

Test Suites¶

Suite 1 — TauStateTests (target: 10 tests)¶

Tests the τ (Bitcoin block height) sovereign time Swift actor (TauSyncMonitor).

Test	Assertion
tau_001_initial_zero	`TauSyncMonitor().currentTau == 0` on create
tau_002_set_get_roundtrip	`setTau(100)` → `currentTau == 100`
tau_003_set_large_height	`setTau(870_000)` → `currentTau == 870_000`
tau_004_set_zero	`setTau(0)` → `currentTau == 0`
tau_005_update_increments	Three sequential setTau calls → latest value returned
tau_006_actor_isolation	Concurrent writes are actor-serialised — no data race
tau_007_nats_disconnect_holds_last	NATS disconnect → `currentTau` holds last known value
tau_008_max_block_height	`setTau(UInt64.max)` → `currentTau == UInt64.max`
tau_009_create_destroy_lifecycle	actor init → setTau → currentTau → deinit → no leak
tau_010_multiple_monitors_independent	Two TauSyncMonitor instances have independent τ values

Suite 2 — vQbitABITests (target: 8 tests)¶

Tests the S4DeltaWire 53-byte frozen wire format and VQbitPrimitive Swift struct layout (IQ-007 compliance).

Test	Assertion
abi_001_s4wire_size	`S4DeltaWire.byteCount == 53` (IQ-007 frozen)
abi_002_c4wire_size	`C4ProjectionWire.byteCount == 53` (IQ-007 frozen)
abi_003_vqbit_s4_count	`VQbitPrimitive` has exactly 4 S⁴ Float32 fields
abi_004_vqbit_c4_count	`VQbitPrimitive` has exactly 4 C⁴ Float32 fields
abi_005_vqbit_default_zero	Default `VQbitPrimitive()`: all Float32 fields == 0.0
abi_006_s4wire_round_trip	Encode → decode S4DeltaWire → byte-exact equality
abi_007_c4wire_round_trip	Encode → decode C4ProjectionWire → byte-exact equality
abi_008_vqbit_sendable	`VQbitPrimitive` conforms to `Sendable` (Swift 6 actor isolation)

Suite 3 — WalletTests (target: 8 tests)¶

Tests the zero-PII sovereign wallet (gaia1 prefix, mode 0600).

Test	Assertion
wallet_001_address_prefix	Address starts with `"gaia1"`
wallet_002_address_length	Address length is 43 chars (`gaia1` + 38 hex)
wallet_003_file_exists	`~/.gaiaftcl/wallet.key` exists after IQ
wallet_004_mode_0600	File permissions are `0o600`
wallet_005_no_pii	File content contains no `@`, SSN, DOB patterns
wallet_006_pii_stored_false	`iq_receipt.json` has `"pii_stored": false`
wallet_007_deterministic	Same entropy → same wallet address (seeded test)
wallet_008_idempotent	Running IQ twice → wallet unchanged, receipt appended

Suite 4 — OwlProtocolTests (target: 6 tests)¶

Tests Owl Protocol secp256k1 identity validation.

Test	Assertion
owl_001_66char_02prefix_accepted	`"02" + 64 hex chars` → accepted
owl_002_66char_03prefix_accepted	`"03" + 64 hex chars` → accepted
owl_003_64char_rejected	64-char key → `InvalidLength` error
owl_004_04prefix_rejected	`"04"` prefix → `InvalidPrefix` error
owl_005_nonhex_rejected	Non-hex characters → `InvalidCharacters` error
owl_006_audit_log_hashed	Audit entry stores SHA-256 of pubkey, not raw key

Suite 5 — RendererTests (target: 6 tests)¶

Tests the RealityKit C4ProjectionSystem lifecycle as used by Franklin.app.

Test	Assertion
renderer_001_system_registers	`C4ProjectionSystem` registers with RealityKit scene on init
renderer_002_bridge_drives_entity	Writing to `C4ManifoldRuntimeBridge` → entity component updated on next tick
renderer_003_null_prim_safe	nil primID in bridge write → system skips gracefully, no crash
renderer_004_entity_update_cycle	100× bridge write/read cycles → no memory growth
renderer_005_tau_and_renderer_independent	`TauSyncMonitor.currentTau` and entity components are orthogonal
renderer_006_unvalidated_prim_skipped	Entity with empty `lastReceiptID` → C4ProjectionSystem skips update

Receipt Format (ALCOA+ Required)¶

Written to evidence/testrobit_receipt.json on all-pass:

{
  "spec":                 "GFTCL-SWIFT-OQ-001",
  "cell":                 "GaiaFTCL",
  "gamp_category":        "Category 5",
  "timestamp":            "2026-04-16T18:30:00Z",
  "operator_pubkey_hash": "<SHA-256 of Owl pubkey — not raw key>",
  "pii_stored":           false,
  "training_mode":        true,
  "total_tests":          38,
  "passed":               38,
  "failed":               0,
  "skipped":              0,
  "suites": {
    "TauStateTests":      { "total": 10, "passed": 10 },
    "vQbitABITests":      { "total": 8,  "passed": 8  },
    "WalletTests":        { "total": 8,  "passed": 8  },
    "OwlProtocolTests":   { "total": 6,  "passed": 6  },
    "RendererFFITests":   { "total": 6,  "passed": 6  }
  },
  "status":               "PASS"
}

Building the TestRobit¶

Prerequisites¶

Swift 6.2+ / Xcode Command Line Tools installed
swift build passes in cells/xcode/

Steps¶

cd cells/xcode

# 1. Build (pure Swift Package Manager — no external deps)
swift build --target GaiaFTCLTestRobit

# 2. Run
swift run GaiaFTCLTestRobit
# → writes evidence/testrobit_receipt.json on all-pass

Package.swift Template¶

// swift-tools-version:5.9
import PackageDescription

let package = Package(
    name: "GaiaFTCLTestRobit",
    platforms: [.macOS(.v14)],
    targets: [
        .executableTarget(
            name: "GaiaFTCLTestRobit",
            path: "Sources/GaiaFTCLTestRobit",
            linkerSettings: [
                .linkedFramework("Metal"),
                .linkedFramework("QuartzCore"),
                .linkedFramework("RealityKit")
            ]
        )
    ]
)

Relationship to GaiaHealth TestRobit¶

Aspect	GaiaFTCL TestRobit	GaiaHealth TestRobit
Target	≥30 tests, 5 suites	66 tests, 5 suites (✅ built)
Library	Swift Package Manager (no staticlib)	Swift Package Manager (no staticlib)
Wallet prefix	`gaia1`	`gaiahealth1`
State machine	`TauState` (plant swap)	`BioState` (11-state MD)
Epistemic tags	M/T/I/A (4 tags)	M/I/A (3 tags)
Receipt spec	GFTCL-SWIFT-OQ-001	GH-SWIFT-OQ-001

The two TestRobits share the same ALCOA+ receipt format and the same SovereignWallet / OwlPubkey test patterns (from shared Swift packages). Suite 3 (WalletTests) and Suite 4 (OwlProtocolTests) are nearly identical except for the gaia1 vs gaiahealth1 prefix.

Federation cosignature: pending

This page is not yet in the signed manifest. Run gaiaftcl wiki sign --all.