Programming & API Guide

Document reference: GFTCL-API-001 · Audience: integrators & developers

Framework: GAMP 5 Category 5 · EU Annex 11

FortressAI Research Institute · Norwich, Connecticut

Patents: USPTO 19/460,960 · USPTO 19/096,071 — © 2026 Richard Gillespie

How to program against the GaiaFTCL vQbit Quantum VM. Three surfaces: the operator CLI,

the read-side Python client, and the substrate data model with its NATS event bus.

Franklin's heartbeat is the only writer; every external surface is read or

projection-ingestion — there is no direct mutation of substrate state.

---

1. The CLI surface

gaiaftcl is the operator interface and the scripting surface. It ingests each command

as a comms projection and projects Franklin's response back. Full grammar — every

command, generated from source — is in the CLI Reference.

Top-level groups:

franklin   qc   qc020   substrate   shor   pq   wallet   subscription   mesh   cell   wiki

Exit codes follow the substrate verdict vocabulary: 0 CALORIE, 2 REFUSED, 1 BLOCKED.

2. The Python client (gaiaftcl)

The federation-verified Python wrapper reads Franklin's externalised, sealed tables.

Install and use:

pip install gaiaftcl            # base client
pip install gaiaftcl[all]       # + numpy/pandas/sklearn/biopython/rdkit/ase/pymatgen/root

from gaiaftcl import FranklinClient

# read-only against ~/Library/Application Support/GaiaFTCL/substrate.sqlite
with FranklinClient.connect() as franklin:
    for hb in franklin.heartbeat_history(limit=5):       # V184
        print(hb.tick_at_iso, hb.observations_count)

    wallet = franklin.local_wallet()                      # V209 self-custody
    print(wallet.qfot_balance_canonical, wallet.euro_balance_canonical)

    for d in franklin.shor_demonstrations(limit=3):       # V188 (no key surfaced)
        print(d.wallet_label, d.terminal, d.verification_match)

Read surfaces (v1.1): heartbeat_history, research_telemetry,

health_observations, healing_history, replay_session, list_substrate_development,

evaluate_algorithm, franklin_authority_show; economy local_wallet,

wallet_ledger, qfot_ledger; brain wound_ledger, reward_gradient,

strategic_shifts; post-quantum shor_demonstrations, pq_migrations,

randomness_provenance. Full reference: Python Wrappers.

The recovered-key column of V188 is deliberately not surfaced by the client;

verification_match is the proof of recovery without re-exposing key material.

3. Federation cosignature verification

Every row is independently verifiable:

from gaiaftcl import verify_signature_quintet
ok = verify_signature_quintet(row.canonical_witness,
                              row.witness_hash_sha256,
                              row.signature_quintet)

ManifestSigner / ManifestVerifier cover artifact and wiki-section manifests.

4. Industry bridges

Eight optional bridges turn substrate evidence into native types — numpy, pandas,

scikit-learn, biopython, rdkit, ase, pymatgen, root — e.g. a scikit-learn

SubstrateFeatureExtractor / V178LeadingZeroFeatureExtractor transformer over

research telemetry. Each bridge is an install extra; the base client imports without it.

5. The data model

The substrate is an append-only SQLite store; every table carries canonical_witness,

witness_hash_sha256, signature_quintet, and nats_subject_sealed. Every schema

version and its columns are documented, generated from source, in the

Substrate Schema Catalog. Value amounts are exact-rational

num/den strings — never parse them as floats.

6. The NATS event bus

Each persisted row is broadcast on its nats_subject_sealed. Subscribe for live events:

async with FranklinClient.connect() as fr:
    async for evt in fr.subscribe("gaiaftcl.substrate.franklin_heartbeat.sealed"):
        print(evt)

Subjects follow gaiaftcl.substrate.<surface>.sealed and

gaiaftcl.qc020.<surface>.sealed; the exact subject per schema is in the catalog.

7. Engineering rules

• Read, don't mutate. Franklin's heartbeat is the only authorized writer. Clients

read; operators project through the CLI.

• Verify before trusting. Re-compute witness hashes / verify cosignatures on any

row you act on.

• Never reconstruct secrets. No client surface exposes private keys; do not infer or

store them.

---

*Cross-references: CLI Reference ·

Python Wrappers · Schema Catalog ·

System Architecture.*

*Federation cosignature: pending — gaiaftcl wiki sign --section GAMP5.*