Skip to content

Mesh Distribution

Federation-verified in-memory module loading. Industry consumers pip install gaiaftcl to get the loader; the actual bridge artifacts distribute through the cell-mesh as federation-signed manifests.

Why mesh distribution

  • Operator-signed integrity. Every bridge artifact's SHA-256 verifies against the manifest's canonical witness; the manifest's seal verifies against the federation cosignature quintet.
  • In-memory module registration. No filesystem install step beyond the cache mirror; load_from_mesh registers the verified module in sys.modules.
  • Substrate-cadence update propagation. New bridge versions land as new manifests in the mesh cache; consumers re-load to pick up.

API

from gaiaftcl import load_from_mesh, MeshLoader
from gaiaftcl.federation.manifest import (
    Manifest, ManifestSigner, ManifestVerifier
)

load_from_mesh(module_name, cache_root=None, federation_public_keys=None) -> module

Convenience wrapper. Loads + verifies + registers a federation-signed Python module by fully-qualified name.

MeshLoader(cache_root=None, federation_public_keys=None)

For repeated loads sharing a cache root.

Cache layout

~/.gaiaftcl/mesh_cache/
├── gaiaftcl.bridges.numpy_bridge/
│   ├── manifest.json
│   └── artifacts/
│       └── __init__.py
├── gaiaftcl.bridges.pandas_bridge/
│   ├── manifest.json
│   └── artifacts/
│       └── __init__.py
└── ...

Override via env var GAIAFTCL_MESH_CACHE or MeshLoader(cache_root=...).

Manifest format

{
  "manifest_version": "1.0",
  "produced_at_iso": "2026-06-01T11:30:00Z",
  "cell_id": "gaiaftcl-mac-cell",
  "domain_id": "python-wrappers",
  "artifacts": [
    {"path": "gaiaftcl/__init__.py", "sha256": "...", "bytes": 1234},
    ...
  ],
  "canonical_witness": "manifest;cell=gaiaftcl-mac-cell;domain=python-wrappers;at=2026-06-01T11:30:00Z;count=19;artifacts_digest=...",
  "witness_hash_sha256": "...",
  "signature_quintet": ["selfsigned:...", ...]
}

The canonical_witness composes cell + domain + iso_time + artifact_count + artifacts_digest. witness_hash_sha256 is SHA-256(canonical_witness). signature_quintet is the federation 5-context cosignature.

Sign a manifest (operator-side)

from pathlib import Path
from gaiaftcl.federation.manifest import ManifestSigner

signer = ManifestSigner(
    cell_id="gaiaftcl-mac-cell",
    domain_id="python-wrappers",
)
manifest = signer.sign_directory(Path("src/gaiaftcl"))
Path("manifest.json").write_text(manifest.to_json())

Verify a manifest (consumer-side)

from pathlib import Path
from gaiaftcl.federation.manifest import Manifest, ManifestVerifier

manifest = Manifest.from_json(Path("manifest.json").read_text())
ok = ManifestVerifier().verify(manifest, Path("src/gaiaftcl"))
assert ok, "manifest verification failed"

verify recomputes each artifact's SHA-256 and the canonical-witness hash; returns True iff bit-exact equivalent.

Load a verified module

from gaiaftcl import load_from_mesh

bridge = load_from_mesh("gaiaftcl.bridges.numpy_bridge")
# Now importable
from gaiaftcl.bridges.numpy_bridge import leading_zero_histogram

MeshLoaderError raises on missing manifest, federation verification failure, or artifact hash mismatch.

Federation public keys

When federation_public_keys is supplied, the loader runs full quintet verification per context. With no keys provided (substrate-natural default), witness-hash equivalence is the verification anchor — appropriate for trusted-cell or single-operator deployments.

For multi-cell federations, supply keys per the operator's federation_keys.toml:

from pathlib import Path
import tomllib

with open(Path.home() / ".gaiaftcl" / "federation_keys.toml", "rb") as f:
    keys = tomllib.load(f)["public_keys"]

loader = MeshLoader(federation_public_keys=keys)
loader.load("gaiaftcl.bridges.rdkit_bridge")

The mesh is substrate-natural: signed, replay-bit-exact, operator-published.

Federation-cosigned

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