Skip to content

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-cosigned

This page's source is sealed in the GaiaFTCL federation manifest — page SHA-256 cdb2067bcdf0bee7…, 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.