GIGI

Using a coding agent on this repo? Read [`AGENTS.md`](AGENTS.md) first. It documents the traps that make agents report GIGI as broken when it is not — a refusal mistaken for a bug, a stale binary, a {"status":"ok"} that executed nothing. Every one of them actually happened.

Geometric Intrinsic Global Index — a fiber-bundle database engine.

Records are sections of a fiber bundle. Keys live on the base space; values live on the fiber. Curvature, spectral connectivity, holonomy, and confidence are properties of the bundle — they update incrementally with every insert and ride along on every query response. Geometry is not a plugin.

Licensing: GIGI is released under the PolyForm Noncommercial License 1.0.0 — free for personal use, research, education, and nonprofit/government use. Commercial use is not granted by this license and is reserved by the copyright holder under a separate commercial agreement. See License & commercial use below.

Davis Geometric · 2026 · Bee Rosa Davis

Plain-English primer

What's a fiber bundle, really?

Imagine a phone book. Names are how you find an entry; the stuff about each person — address, phone, age, occupation — is what you find when you look them up. The names form an index. The stuff at each name is the fiber (the values).

A fiber bundle is the same shape, taken seriously. The index is the base space B. The stuff at each index point is the fiber F. Every "row" in the bundle is a section — a way of assigning one fiber to each base point. That's the same thing every relational DB does: keys on one side, values on the other.

Where it changes is what GIGI does with that shape. Imagine the index isn't a flat list — it's the surface of the moon. Every point on the moon (a base point) has terrain underneath it (the fiber). The way the terrain changes as you walk around the moon — that's curvature. The presence of crater rings — that's non-trivial topology. If you walk in a closed loop and end up facing a different direction than when you started — that's holonomy. None of that is in the phone book. All of it is in the moon.

GIGI treats your database like the moon, not like the phone book. Every record is a point on a curved surface. The shape of that surface tells you things the rows alone never could:

• Curvature κ at a record = *"how anomalous is this row compared to

what's nearby?"*

• Spectral gap λ₁ of the whole bundle = *"how clumpy or smooth is

the data?"*

• Holonomy around a categorical loop = *"does this category

implicitly twist the values somehow?"*

• Parallel transport between two records = *"if I had to walk from

row A to row B along the data's natural geometry, what path would I take?"*

• Confidence 1/(1+κ) = "how much should I trust this answer?"

These aren't add-ons. They are what GIGI computes during normal operation. Curvature updates on every insert via Welford's online algorithm. Spectral gap is cached and incrementally refreshed. Holonomy is a verb in the query language (HOLONOMY corpus ...).

The headline: a conventional database stores rows. GIGI stores the geometry that rows live on. The rows are still there — every GIGI query returns the same shape Postgres or Mongo would — but every response also carries the geometric quantities, free, because the substrate computed them on the way through.

Day-one operations: GIGI vs Postgres / MySQL / Mongo

How the basics work, side by side. Every row here is a real operation the engine implements, not an aspirational future.

The compounding effect: because curvature updates on every insert, you don't have to decide later to add anomaly detection — it's already running. Because spectral gap is cached, "is this data clumpy?" is a constant-time read instead of an offline batch job. Because confidence ships in every response, "should I trust this?" doesn't need a separate ML stack. Geometry is not a plugin. It's the substrate.

What it costs

• Insert latency: ~the same as a relational DB doing the same

number of column writes. The Welford updates are O(1) per numeric field; the mutation_counter is a single atomic increment.

• Memory: ~1.5× a row-store for the same data, because the geometric

metadata (per-field stats, fiber index, mutation epoch) lives alongside the records.

• Cold-start after restart: bundles reload from mmap snapshots in

seconds, not the minutes a B-tree rebuild can take. Brain endpoints (curvature reads, SUDOKU, SAMPLE_TRANSPORT) are available immediately, not after a warm-up.

Why GIGI

Conventional databases see rows. GIGI sees a section σ: B → E of a fiber bundle (E, B, F, π, Φ): the base space B is the queryable keys, the fiber F is the value schema, and every record is a point in the total space E. This isn't decoration — it's how the engine indexes, queries, and reasons about your data:

Status

GIGI is the substrate. As of this README, end-to-end:

• Halcyon Parts I–IV are LIVE. SU(2) Yang-Mills on the buckyball runs as a GQL block (LATTICE → GAUGE_FIELD → GIBBS_SAMPLE → E_FIELD → SYMPLECTIC_FLOW). All six Halcyon HTTP read routes resolve on the production deployment; embedded-only declarers correctly return 404 (the II.6c reframe — embedded GQL is canonical for restart-crossing consumers). Gates pinned by per-part gold gates (halcyon_part_iv_gold 5/0, halcyon_part_iv_a2_matrix 5/0 with the cross-OS row honestly ignored). See theory/halcyon/HALCYON_PART_I_GATES.md through Part IV.
• Brain primitives L9–L13 are LIVE. All 12 cognitive primitives (SAMPLE / DREAM / FORECAST / RECONSTRUCT / INPAINT / PREDICT / SELF-MONITOR / ATTEND / FOCUS / EPISODIC / SEMANTIC / EXPLAIN) sit on the Friston master equation ẋ = B⁻¹∇(−log p) on the Kähler bundle. Production HTTP at /v1/bundles/{name}/brain/*. 16 of 21 catalog items shipped — 100% of the items I classified as ship-able.
• Kähler upgrade is LIVE. Twelve layers (L1–L12) behind the kahler feature flag; byte-identical no-feature build. The Marcella A/B harness pinned the closed-form 7.6pp non-associativity bound to within 0.0013.
• Causal-states substrate is LIVE. Davis (2026) shipped with TV / Hellinger / KL diagnostics, the update-commutator orchestrator, and the Sofic / Smooth / Borderline regime classifier behind the causal_states feature flag. POST /v1/causal_states/commutator live in production.
• Gauge encryption v0.4 is LIVE. Six modes (Affine / Probabilistic / Opaque / Indexed / Isometric / Identity). κ, λ₁, holonomy preserved at native speed. Public deterministic invariant verification with bundle-id binding.
• WISH verb is LIVE. IMAGINE + DREAM + SUDOKU composed as a single boundary-value-problem verb behind the wish feature flag. Marcella's load-bearing curvature ceiling (4.0 = K(CP¹ Fubini-Study)) is the default safety envelope.
• Marcella consumer pattern is documented. Substrate spec at theory/kahler_upgrade/marcella_substrate.md; pure-fiber LM that reads through the brain endpoints and refuses rather than confabulates when /brain/confidence_with_explain says she doesn't know.
• Bridge Trilogy + SPECTRAL_GAUGE Phase 1 + Yang-Mills topology verbs are LIVE (2026-06-28). Three substrate items unblock Halcyon's 4D SU(3) pipeline: LATTICE … FROM CUBIC L=N DIM=K PERIODIC declares n-D cubic lattices (L=12 D=4 gives 20736 vertices / 82944 edges / 124416 plaquettes); INGEST bundle FROM 'file.npz' FORMAT NPZ reads NumPy arrays via the npyz crate; GROUP SU(3) is a first-class structure group (raw 3×3 complex storage, 144 B / link, Mezzadri 2007 Haar). On top: SPECTRAL_GAUGE bundle ON FIBER (q0..) returns the fiber-weighted spectral gap λ₁ of the gauge-covariant Laplacian; CHERN_CLASS … ORDER 2 returns the discrete instanton number via the Lüscher 1982 clover construction; PONTRYAGIN … ORDER 1 returns p₁ (= 2·c₂ for SU(N)); PI_1 lattice returns the fundamental-group rank via spanning-tree + face-relator construction; OBSTRUCTION bundle returns the principal-bundle section-existence class; BETTI … ORDER k extends Betti to the cell complex. The December L=12 D=4 SU(3) harvest gets a one-line CHERN_CLASS ensemble ORDER 2; topological-sector readout once Halcyon regenerates configs. See theory/halcyon/HALCYON_BRIDGE_TRILOGY_2026-06-28_SHIPPED.md, theory/halcyon/SPECTRAL_GAUGE_PHASE1_SHIPPED_2026-06-28.md, and theory/halcyon/YANG_MILLS_TOPOLOGY_VERBS_SHIPPED_2026-06-28.md.
• Halcyon L=24 OBC substrate + the sixteen-feature engine batch + the hardening trio are LIVE (2026-07-01 → 2026-07-03). 2026-07-01 — four grammar extensions unblock Halcyon's SU(2) 4D L=24 β=2.3 open-boundary sectoral workflow: LATTICE … FROM CUBIC L=N DIM=K OBC AXIS <k> (wrap edges + boundary-crossing plaquettes omitted along the named axis; vertex set stays L^D — L=24 D=4 gives 331,776 vertices / 1,313,280 edges / 1,949,184 plaquettes), INGEST … FORMAT NPZ [KEY <member>] AS GAUGE_FIELD GROUP <g> ON LATTICE <l> (one-step NPZ → gauge-field bundle: canonical per-group fiber names, vertex_a / vertex_b base fields from the lattice's own column-major site numbering, OBC wrap records omitted so the record set equals the lattice edge set, f32 upconverts exactly to f64), CHERN_CLASS … PER <field> INTO_COLUMN <col> (per-configuration topological sectors, written back through the new append-only ALTER BUNDLE … ADD BASE <field> <type>), and SPECTRAL_GAUGE … WHERE <cond> … (sector-stratified gaps). 2026-07-03 — the sixteen-feature batch: human parse errors (token names, near-context, did-you-mean) + trailing-token rejection (a parsed statement with leftover input refuses instead of silently discarding it); INTEGRATE … WITH JACKKNIFE ALONG <field> [SKIP FIRST n] evidence-grade error bars with a thermalization cut; no-op statements return an explicit notice instead of a bare ok; SHOW FIELDS ON b returns real rows; poison-proof locks (a panicked handler no longer wedges the server); INGEST FORMAT CSV / FORMAT JSONL; EMIT CSV TO 'f.csv'; EXPLAIN SECTION … AT … per-field κ decomposition; TIMESTAMP field type + ISO-8601 literals + NOW; the gigi CLI (gigi doctor, rustyline REPL, -f script.gql) and the gigi-stream first-contact banner — plus the same-day review fixes (patterns-feature compile break, multibyte-safe error truncation and ISO-timestamp parsing, Statement::Emit dispatched over HTTP, TIMESTAMP coercion on the update path). 2026-07-03, second deploy — the hardening trio: src/pathguard.rs shared containment (component screen rejects absolute / drive-prefixed / UNC / .. shapes before joining; canonical-to-canonical compare defeats symlink and junction tunnels), the fail-closed GIGI_INGEST_DIR gate on every file-reading INGEST format (unset ⇒ server-side file reads are disabled; prod pins /data/ingest), GIGI_EMIT_DIR routed through the same guard, and record_kappa stamped constant on every EXPLAIN row (mean of the per-field κ column == the record's total κ from compute_record_k — the response certifies its own invariant). Known residuals, named: DEFINE PATTERN … OR does not parse (pre-existing, queued); EMIT wrapping a bundle-less statement (e.g. SHOW BUNDLES … EMIT CSV) still returns ok without emitting (queued). See theory/halcyon/HALCYON_L24_OBC_WORKFLOW_UNBLOCKED_2026-06-29.md and theory/halcyon/DEPLOY_2026-07-03_SIXTEEN_FEATS.md.
• The durability encoder fix + the RIEMANN / Poincaré / P≠NP observable line + the Marcella EXPLAIN and dials family are LIVE (2026-07-16/17). The DHOOM snapshot encoder's computed-field detection was O(F³·N) — days of compute on wide numeric bundles (384 scalar fibers), wedging the boot snapshot; it is now cached and capped at 64 candidate fields (O(F·N + F³)), so high-field bundles snapshot in seconds, with .dhoom + WAL formats byte-unchanged and old snapshots still opening. That is a durability fix for the boot-snapshot wedge only — heap-only bundles stay ephemeral until a whole-engine /v1/admin/snapshot. Three Millennium verbs restage geometric signatures Bee documents elsewhere as gigi-native observables — evidence inside the Davis framework, never proofs of the Clay problems: SPECTRAL_GAUGE … MODE MAGNETIC [FULL [LIMIT k] | BULK k] assembles a complex Hermitian magnetic Laplacian whose level-spacing reads in the GUE symmetry class (measured mean r̃ ≈ 0.605) against the real cos-weight Laplacian's GOE (≈ 0.527); HOLONOMY … AROUND CYCLE reads the lens-space π₁ = ℤ/p order off an SU(2) loop; SPECTRAL … MODE MATRIX exposes the raw signed-symmetric spectrum's negative fraction. Marcella-facing: EXPLAIN SECTION … VECTOR / IN (typed 404 on a missing key, additive kappa_v rows, mmap on-demand Welford stats), scoped horizon / capacity reads, and POST …/windowed_coherence. The dense eigensolver ceiling is opt-in via GIGI_DENSE_CEIL (default 4096, up to 8192); the sparse interior arm (Phase 2.1) merged and went live 2026-07-18 — BULK past the ceiling routes to it, FULL still returns the typed SparseUnavailable. See theory/halcyon/SPECTRAL_PHASE2_MAGNETIC_SHIPPED_2026-07-16.md, HOLONOMY_CYCLE_SHIPPED_2026-07-17.md, and MODE_MATRIX_SHIPPED_2026-07-17.md.

• TEXTURE + PRECEDENCE are LIVE (2026-08-09). Two general-purpose verbs for "what shape is this data in", answered without resampling onto a grid whose bin width the caller guessed — a guess that is not free: on live asynchronous data, 3 of 6 channel pairs reported a different lead-lag under a time warp that preserved event order, and one reversed direction. POST /v1/bundles/{name}/texture returns the self-similarity (Hurst) exponent of one ordered numeric field plus an r_squared that tells the caller when the signal is not self-similar and H should not be read as a single number. POST /v1/bundles/{name}/precedence returns the normalised Lévy area between two fields — the level-2 antisymmetric part of the path signature — reading record order and never a timestamp, so there is no bin width to get wrong; area > 0 means x leads y, and swapping the arguments negates it exactly. No domain vocabulary in either API (field, x, y, order): the shipped walkthrough measures queue latency, not markets. Sixteen blocking gates (TXP-1..15) cover planted-answer recovery, invariance to rescaling and to order-field spacing, six refusal paths that each name their reason, disclosure of skipped rows rather than coercion to 0.0, determinism, and record caps that error rather than return null. Suite 1001 passing, 985 pre-existing untouched. Spec: theory/gigi/TDD-TXP_texture_precedence.md; runnable example with planted answers and deliberate refusals: examples/texture_precedence_walkthrough.py.

• CADENCE is LIVE (2026-08-09). The third shape verb, and the complement of the other two: TEXTURE and PRECEDENCE read record order and discard timestamps, while POST /v1/bundles/{name}/cadence reads exactly what they throw away — the spacing between events. It answers "is this stream arriving steadily or in bursts, and does the unevenness have memory?" for anything timestamped: log lines, sensor pings, request traces, seismic events, trades. It returns two numbers and always both, because one is not enough: index is the Greenwood dispersion statistic, whose null is exactly Dirichlet(1,…,1) at finite n for every arrival rate, so E[index²] = 1 needs no simulation and does not move when the stream speeds up. But R_n = Σt²/(Σt)² is a symmetric function of the gaps — permuting them cannot change it — so index provably cannot see ordering, and a self-exciting stream reads identically to its own shuffle (measured: 1.448 vs 1.448). memory, the lag-1 autocorrelation of ln τ, is therefore an exactly non-overlapping second measurement rather than a correlated add-on. Verdict bands are derived, not chosen: null_sd = n/√((n−1)(n+2)(n+3)), bands at ±2 sd, checked against simulation from n = 64 to 8192. Eighteen blocking gates (CAD-1..18) include a gate that pins the order-blindness deliberately, a three-way separation of streams index alone would call identical, a refusal for a row index passed where a clock belongs (which would otherwise return a confident index = 0 on a healthy feed), and a granularity refusal derived from a bias budget. Suite 1019 passing, 1001 pre-existing untouched. Spec: theory/gigi/TDD-CAD_cadence.md; runnable example: examples/cadence_walkthrough.py.

• Post-Kähler Phase 1 (PK-1..4) is LIVE (2026-07-25). Four geometry verbs behind the post_kahler_phase1 feature, each tied exactly to theory/post_kahler_directions/validation_tests.py: FISHER (the information-geometry metric g = diag(1/σ², 2/σ²) per fiber, read free from L4 Welford variance), WASSERSTEIN (exact 1D W₂ between two cohorts via the monotone rearrangement), PERSISTENCE (H₀ via MST + elder rule → an honest cluster count that returns 1 when there is no real grouping), and REEB (the standard contact form α = dz − y·dx + Reeb-field verification). Each has a REST twin (/v1/bundles/{name}/{fisher_metric, ml/wasserstein, topology/persistence, brain/reeb_flow}). 18 module ground-truth tests + 3 endpoint/GQL integration tests; the default no-feature build stays byte-unchanged. Verbatim examples on R.A. Fisher's iris dataset in theory/reviews/iris_pk_results.json (reproduce with scripts/pk_iris_examples.py). Spec: GIGI_POST_KAHLER_SPEC_v0.1.md.

Test counts, dated to their last full run:

• cargo test --lib → 1020 passed / 0 failed (2026-08-09, CADENCE + GQL surface; 1001 pre-existing untouched).
• cargo test --no-default-features --lib → 911 passed / 0 failed (2026-07-03 pre-deploy gate). The byte-identical no-feature build.
• cargo test --features halcyon --lib --test-threads=1 → 965 passed / 0 failed (2026-06-28). Halcyon Parts I–IV on the substrate.
• cargo test --features "kahler imagine sharded transactions patterns causal_states wish halcyon" --lib --test-threads=1 → 1488 passed / 0 failed (2026-06-28). The full production feature surface.

Detailed gate-by-gate ledgers live under theory/halcyon/, theory/kahler_upgrade/, theory/causal_states/, and theory/imagine/.

Measured: geometric vs flat

Store-vs-store benchmark: GIGI vs SQLite vs DuckDB on ingest / point query / aggregate / anomaly — losses unsoftened (GIGI loses its own thesis anomaly task 8.5x on PR-AUC to 15 lines of SQL) — lives in BENCHMARKS_VS_STORES.md, harness committed under benchmarks/vs_stores/.

Same data, same split, same metric on both sides. Every number below is mean ± sample std across 5 fixed seeds (20260801–20260805), captured in scripts/sweep_results_multiseed.json, written by scripts/multiseed_sweep.py driving a live GIGI release server against sklearn. Verdicts use the artifact's rule: WIN/LOSS only when the signed delta clears max(combined std, 0.005), else PARITY. The GIGI arm exposes no seed parameter and is deterministic for fixed data across server restarts and repeated calls (base-point-sorted records() + fixed-LCG inits + sorted SVM training pool — fixes df4997c / d5ceb6f, after artifact verification caught reproducibility holding only within one server process, and for SVM not even that); its std 0.0 is measured per seed, not assumed, and re-verified by scripts/multiseed_repro_probe.py (two fresh server processes, values identical to the artifact). Tally over all 27 cells: 11 WIN / 10 PARITY / 6 LOSS.

Where the geometric method wins:

The representation row is a controlled experiment, not a benchmark comparison: both arms run one shared EM implementation (gmm_em, src/ml/cluster.rs) with identical covariance, init, and convergence — only the representation changes, so the +0.356 ARI is the isolated representation effect. (sklearn GMM on the same raw pixels rides along in the artifact at 0.491 ± 0.063.) Earlier single-run figures for this row (0.594 → 0.708) predate two fixes the 2026-08-01 artifact verification forced — the spectral head previously ran a different GMM implementation than the raw arm, and record order was process-dependent — and are superseded; the diffusion row's earlier figures survived the re-run unchanged.

Parity with zero configuration (10 cells): iris kmeans (0.620 vs 0.618 ± 0.005), iris gmm (0.904 vs 0.826 ± 0.173), wine svm (0.983 vs 0.983), bcancer knn (0.965 vs 0.968), bcancer svm (0.975 vs 0.974), diabetes ols R² (0.486 vs 0.482), all three PCA rows (equal to ≤ 3·10⁻⁶), and anomaly · bcancer-rare PR-AUC (GIGI /scan 0.539 ± 0.099 vs IsolationForest 0.542 ± 0.078 — the seeded malignant subsample varies both arms; formerly presented as a single-run win at 0.559 vs 0.552, which the multiseed variance dissolves). GIGI's own flat implementations also post WINs against sklearn on wine kmeans (0.915 vs 0.897), wine gmm (0.947 vs 0.884 ± 0.023), iris/wine/digits knn, digits svm, and MovieLens matrix factorization RMSE (0.911 vs 0.929 ± 0.006) — implementation-quality evidence, not geometric wins.

Where flat wins (6 cells): digits gmm ARI 0.256 vs sklearn 0.491 ± 0.063 (the largest loss in the sweep; the eigenspace recovery of that same GMM to 0.612 is the representation row above), digits kmeans ARI 0.454 vs 0.506 ± 0.049, wine spectral ARI 0.833 vs 0.880 (a geometric method losing, not a control arm), iris SVM accuracy 0.913 vs SVC(rbf) 0.967, diabetes local_linear R² 0.408 vs KNN-reg 0.449, and diabetes gp 90%-coverage 0.878 vs 0.907 ± 0.024 (the sklearn intervals land nearer the target; the prior single-run snapshot had this as a GIGI win at 0.919 vs 0.902 — the multiseed re-run flips it, reported as the loss it now is). The catalog's own positioning text concedes "On flat data they tie."

Sources: scripts/sweep_results_multiseed.json (per-seed raws, means, stds, thresholds, verdicts for all 27 cells; meta records seeds, server lifecycle, binary, and commit). Harness: scripts/multiseed_sweep.py; standing reproducibility gate: scripts/multiseed_repro_probe.py. The older single-run snapshot scripts/sweep_results.json is retained for provenance ("an honest snapshot, not a re-runnable gate" — theory/reviews/ML_SUITE_REVIEW_2026-07-18.md §3); where the two disagree, the multiseed artifact supersedes it. Claim text: src/bin/gigi_stream.rs (ml_catalog). The review's "guaranteed coverage" flag on the gp code comment still stands (cross-conformal, empirically calibrated).

Cost footnote. On a 5,000-record × 17-dimension bundle with no indexed fiber fields, SPECTRAL timed out at 30 s and passed at 180 s; the warm second run completed in ~120 s (GIGI_PERF_ANALYSIS.md, 2026-04-15). The O(n²) part is the proximity adjacency build — 25M pairwise comparisons at n=5,000; the eigensolve itself is tabulated O(n·k) Lanczos. Same run: HOLONOMY >180 s, fail (O(n²) + no loops). (CONSISTENCY also logged ~120 s in that 2026-04-15 run, but that measured the pre-fix code path — since f912c22 it is a bounded ≤100-record sampled contradiction scan, and the old O(n²) Čech attribution no longer applies; see the closed flag in GIGI_PERF_ANALYSIS.md.) The dense eigensolver is capped at 4,096 vertices (SPECTRAL_DENSE_MAX_V, src/spectral.rs); GIGI_DENSE_CEIL raises it, clamped to [4096, 8192] — raise-only, because a V ≈ 8000 complex-Hermitian dense solve is ~2–3 GB peak RSS. Past the ceiling, FULL returns a typed SparseUnavailable; BULK routes to the sparse interior arm — completeness-proven vs dense ground truth for V ≤ 2048 (+ fresh-seed), merged and live 2026-07-18 (live probe V=4913: mode_used="sparse_interior", converged 32/32, max_residual 2.528e-12, 30.2 s wall — theory/halcyon/SPARSE_INTERIOR_LIVE_2026-07-18.md). Its wall cost is O(V²) per solve — 739.69 s measured at V=8000, k=64; projected ~37 min at V=13824 and ~3.4 h at V=32768 — inherent to the narrow-window/wide-band ratio and explicitly out of scope to break.

The buried numeric validation artifacts — the Wilson-loop holonomy table on bilayer graphene, Wu-Yang integrality, Berezin-Toeplitz semiclassics, the Poincaré-to-sharding TDD gates, the encryption golden vectors — are indexed with verbatim numbers and source paths in VALIDATION.md.

The Kähler upgrade in one paragraph

GIGI v3 shipped the Kähler upgrade: twelve layers of geometric machinery extending the fiber-bundle substrate with a complex structure J, a closed 2-form B, and everything that follows from the pair — Hadamard substructure detection, holomorphic curvature decomposition, Morse compression, line-bundle integrality checks, quantum cohomology on toy manifolds, Berezin-Toeplitz operators, Riemann-Roch representational capacity, moment-map / Noether conservation along Hamiltonian B-flows, the Friston-FEP keystone (generative flow on the Kähler bundle that parametrizes its boundary conditions to deliver SAMPLE / FORECAST / DREAM / RECONSTRUCT as one piece of infrastructure), predictive-coding primitives (INPAINT, PREDICT, SELF-MONITOR), and the attention + memory pillar (ATTEND, FOCUS, EPISODIC, SEMANTIC). All 12 brain primitives operational. The catalog closes at 16 of 21 items shipped — 100% of the items classified as ship-able.

GIGI ships three companion catalogs:

• theory/kahler_upgrade/ — Kähler

catalog, 16/21 shipped; 15/15 Python validation tests pass.

• theory/post_kahler_directions/ —

nine post-Kähler geometric programs (Sasaki, information geometry, OT/Wasserstein, persistent homology, Gromov δ-hyperbolicity, tropical, synthetic DG, NCG, CAT(κ)); 30/30 numerical checks pass.

• theory/brain_primitives/ — twelve

brain-like operations forced by one master equation ẋ = B⁻¹∇(−log p) on the Kähler bundle — the same equation Friston writes down for variational free-energy minimization. 26/26 checks.

The first downstream consumer (Marcella) ran a 30-prompt A/B harness on her real marcella_source_embeddings_bge substrate. Perfect monotonicity: 21/21 reply-different when residue moved, 9/9 byte- identical when it did not. Peak per-turn Δ-residue = 0.0747, matching the closed-form non-associativity bound of 7.6pp to within rounding (0.0013). Deep-trace held coherence through 86° accumulated rotation across 10 turns — exactly 10 × 8.6° per turn, linear. The full audit trail is in theory/kahler_upgrade/.

What's in this repo

src/ is a single Rust crate; the module-by-module reference lives in rustdoc and CHANGELOG.md. Top-level shape:

• Engine — fiber-bundle store, GQL parser + executor, mmap persistence,

WAL, Kähler-feature modules (gated on --features kahler; absent paths are bit-identical to the pre-upgrade engine), Halcyon lattice / gauge / observable modules (gated on --features halcyon), causal-states substrate (gated on --features causal_states), the six-mode gauge encryption suite, and the DHOOM wire protocol.

• Binaries (src/main.rs + src/bin/ + examples/) — gigi (the

interactive CLI, and the default-run target so plain cargo run lands here: a rustyline REPL with arrow-key editing and per-database history, -e "QUERY" one-shot execution, -f script.gql for files of ;-separated statements with --keep-going to continue past errors, and gigi doctor [--dir p] — a health report that opens the engine, replays the WAL, and inventories bundles and geometry; exit 0 healthy, 1 warnings, 2 failures), gigi-server (REST + WebSocket on :3142), gigi-stream (the binary the production deployment runs; prints a first-contact banner — listening URL + three curl lines to try — when the engine goes ready, muted by GIGI_QUIET=1), gigi-edge (local-first), gigi-convert (CLI ingestion), gigi-stress (load harness). Examples include kahler_tour, predictive_coding_demo, attention_memory_demo, and the Halcyon worked examples.

• SDKs — Python (pip install gigi-client, pandas-aware), JavaScript /

TypeScript (@gigi-db/client, browser + Node), and gigi-notebook (a Jupyter kernel with GQL as the default cell language and a %%commutator cell magic for the causal-states endpoint).

• UIs — operator dashboard (dashboard/, React/Vite) and an in-browser

GQL REPL (playground/) backed by a live gigi-server.

• Theory & specs (theory/) — the math (*.tex) and the build-ready

specs alongside the code. Spec index at theory/SPECS_INDEX.md; per-area catalogs under theory/halcyon/, theory/kahler_upgrade/, theory/causal_states/, theory/imagine/, theory/post_kahler_directions/, theory/brain_primitives/, theory/encryption/, and theory/ggog/.

• End-to-end tests (e2e/) — Playwright + Node against a running server;

worked-example probes across 24 distinct SUDOKU / SAMPLE_TRANSPORT domains.

Quick start

Two paths from a fresh checkout. Both target ten minutes wall-clock on a laptop.

Path A — Your first 10 minutes with GIGI (the database)

A bundle, an insert, a point query, a curvature read.

# 1. Start gigi-stream on localhost
cargo run --release --bin gigi-stream
# → http://localhost:3142  (the production deployment runs the same binary)

# 2. Create a bundle (HTTP, GQL passthrough)
curl -X POST http://localhost:3142/v1/gql \
  -H "Content-Type: application/json" \
  -d '{"query": "CREATE BUNDLE sensors FIBER (sensor_id CATEGORICAL, temp NUMERIC, humidity NUMERIC) KEYS (sensor_id);"}'

# 3. Insert two records
curl -X POST http://localhost:3142/v1/bundles/sensors/insert \
  -H "Content-Type: application/json" \
  -d '{"records":[
        {"sensor_id":"S-001","temp":22.5,"humidity":60.1},
        {"sensor_id":"S-002","temp":19.3,"humidity":71.4}]}'

# 4. Point query — O(1) via the GIGI hash. Response carries κ and confidence.
curl -X POST http://localhost:3142/v1/gql \
  -H "Content-Type: application/json" \
  -d '{"query":"SECTION sensors AT (sensor_id='\''S-001'\'');"}'

# 5. Read the bundle's scalar curvature
curl http://localhost:3142/v1/bundles/sensors/curvature

Every response from step 4 onward carries the geometric quantities (κ, confidence = 1/(1+κ), the dhoom event envelope with KL / JS divergences against the running base). That isn't a logging layer — the substrate computed it on the way through.

Path B — Your first 10 minutes with Halcyon (lattice gauge theory)

The first ~80 lines of Halcyon's inertia_damping/run_validation_report.py (build_graph → heatbath_thermalize → measure → leapfrog) collapse into a five-statement GQL block:

LATTICE buckyball FROM TRUNCATED_ICOSAHEDRON TOPOLOGY "S2";

GAUGE_FIELD U ON LATTICE buckyball GROUP SU(2) INIT IDENTITY;

GIBBS_SAMPLE U
  BETA 2.5
  N_SWEEPS 200
  MEASURE_EVERY 1
  MEASURE (MEAN(PLAQUETTE), Q_SURROGATE)
  SEED 20260616;

E_FIELD E ON GAUGE_FIELD U INIT MAXWELL_BOLTZMANN BETA 2.5 SEED 20260617;

SYMPLECTIC_FLOW U FROM (U=U, E=E)
  BETA 2.5 DT 0.02 N_STEPS 1000
  PROJECT_GAUSS TRUE
  MEASURE_EVERY 20
  MEASURE (H_TOTAL, MEAN(PLAQUETTE), GAUSS_RESIDUAL_MAX, Q_SURROGATE)
  SEED 20260617;

Two ways to run it:

# Embedded — the canonical declarer/mutator surface per II.6c
cargo run --release --features halcyon --example halcyon_buckyball

# HTTP — through the universal /v1/gql reach-through. The ~46-min production
# wall is the soft-edge; nobody runs a 1000-step symplectic flow over JSON
# and waits for it. Use the embedded path for production sweeps.
curl -X POST http://localhost:3142/v1/gql \
  -H "Content-Type: application/json" \
  --data @theory/halcyon/examples/buckyball_five_statement.json

Reproduces Halcyon's published <P>_meas = 0.501598 ± 0.001463 at β = 2.5 inside the Flyvbjerg–Petersen SEM band, and the 1000-step symplectic flow satisfies max|ΔH/H₀| < 1e-3 and gauss_residual_max < 1e-9. Full verb-by-verb spec under §6.4 below.

Both paths work on a fresh git clone — no external services, no API keys, no out-of-tree fixtures.

Build, test, run

# Build everything (engine + production bins + benches + examples)
cargo build --release
cargo build --release --features kahler   # adds the kahler_tour example bin
cargo build --release --features halcyon  # adds the Halcyon worked examples

# Run benches
cargo run --release --bin bench_o1
cargo run --release --bin bench_ingest
cargo run --release --bin bench_tpch

# E2E against a running gigi-server
cd e2e && npm install && npm test

As of this README the engine ships with (counts dated to their last full run):

• `cargo test --no-default-features --lib` → 911 passed / 0 failed (2026-07-03 pre-deploy gate). The byte-identical no-feature build. The optionality contract: every feature flag is opt-in; the no-feature build is bit-identical to pre-upgrade GIGI on the paths it shares.
• `cargo test --features halcyon --lib --test-threads=1` → 965 passed / 0 failed (2026-06-28). Halcyon Parts I–IV on the substrate (LATTICE / GAUGE_FIELD / GIBBS_SAMPLE / E_FIELD / SYMPLECTIC_FLOW / PROJECT_GAUSS + the observable battery + the A2 bit-identity rows). Single-threaded because the gauge registry uses Arc<Mutex<…>> mutable accessors per D4.
• `cargo test --features "kahler imagine sharded transactions patterns causal_states wish halcyon" --lib --test-threads=1` → 1488 passed / 0 failed (2026-06-28). The full production feature surface. Adds the twelve Kähler layers, the IMAGINE / WALK extrapolation verbs with Marcella's 4.0 curvature ceiling, the sharded substrate, atomic sheaf commits, GGOG patterns, causal-states substrate, and the WISH BVP verb on top of Halcyon. The 2026-07-01→03 waves ride the per-suite gates in theory/halcyon/DEPLOY_2026-07-03_SIXTEEN_FEATS.md (INGEST family 39/0, spectral + topology 67/0, pathguard escape matrix 14/0 on Windows, lattice OBC 17/0, plus the no-feature groups).
• `cargo test --features halcyon --test halcyon_part_iv_gold --release` → 5 passed / 0 failed. The Part IV gold gate (acceptance arm + regression arm under release profile — per the III.8c profile-pinning).
• `cargo test --features halcyon --test halcyon_part_iv_a2_matrix --release` → 5 passed / 1 ignored. The A2 bit-identity matrix; the cross-OS row (Row 3) is honestly #[ignore]d with the 2 ULP envelope documented in HALCYON_PART_IV_GATES.md.

Plus the Python TDD math gates that ride alongside the Rust suites:

• IMAGINE / WALK extrapolation verbs — see theory/imagine/validation/ (T11 geodesic integrator, T12 halo partition invariance, T13 double-cover monodromy).
• Sharded substrate — see theory/poincare_to_sharding/validation/ (10 TDD gates, ~15s wall clock, three were red-then-green during development).
• Kähler / post-Kähler / brain-primitives validation — 15/15 + 30/30 + 26/26, see the catalogs under theory/.

Environment gates (fail-closed)

Two verb families touch the server's filesystem. Each is disabled until its root directory is set, and every path is confined to that root by the shared guard in src/pathguard.rs: a component-level screen rejects absolute, drive-prefixed, UNC, and .. forms before any filesystem access, then a canonical-to-canonical containment check refuses symlink and junction tunnels out of the root.

• `GIGI_INGEST_DIR` — gates every file-reading INGEST format (NPZ / CSV / JSONL). Unset ⇒ INGEST from server-side files errors engine-wide — the same posture as Postgres pg_read_server_files / MySQL secure_file_priv. Set ⇒ source paths in INGEST … FROM '<p>' resolve relative to the root. Production sets GIGI_INGEST_DIR = "/data/ingest" in fly.toml: the December harvest pipeline keeps its NPZ capability, bounded to the volume directory it already writes into.
• `GIGI_EMIT_DIR` — gates … EMIT CSV TO 'file.csv'. Unset ⇒ EMIT errors and names the knob; exported files land only inside the root. Production leaves it unset — HTTP consumers request the rows and save client-side.

GIGI_QUIET=1 mutes the first-contact banner gigi-stream prints when the engine goes ready (listening URL + three curl lines to try).

Two operational knobs live outside the fail-closed filesystem gates:

• `GIGI_DENSE_CEIL` — raises the dense eigensolver ceiling for SPECTRAL_GAUGE … FULL / BULK (the MODE MAGNETIC interior spectrum). Default 4096 vertices; an opt-in value is clamped to the safe band [4096, 8192] — raise-only, so it can never lower the floor or exceed 8192, because a V ≈ 8000 complex-Hermitian dense solve is ~2–3 GB peak RSS and will OOM a laptop. A FULL request above the ceiling returns a typed SparseUnavailable naming the memory cost and this knob; a BULK request above the ceiling routes to the sparse interior solver (Phase 2.1, live since 2026-07-18). A machine-safety knob, deliberately in the environment rather than the query.
• `GIGI_SKIP_BOOT_SNAPSHOT` — when set, boot finishes WAL replay and stays heap-only, skipping the post-replay DHOOM snapshot / mmap upgrade. The escape hatch for the boot-snapshot path; the 2026-07-16 durability fix (wide-numeric-bundle computed-field detection, once O(F³·N), now cached and capped) made it rarely necessary — high-field bundles that used to wedge the encoder now snapshot in seconds.

Usage by capability

6.1 GQL — verbs at a glance

-- Point query — O(1) via the GIGI hash
SECTION sensors AT (sensor_id='S-001');

-- Aggregate over a base-space cover — O(|r|)
INTEGRATE temp OVER sensors COVER ALL;

-- Curvature of the bundle
CURVATURE sensors;

-- Spectral connectivity (Fiedler value)
SPECTRAL sensors;

-- Local Laplacian eigenmodes in a fiber subspace
SPECTRAL corpus ON FIBER (f11, f12) MODES 5;

-- Holonomy: how much does the fiber rotate around a categorical loop?
HOLONOMY corpus ON FIBER (f11, f12) AROUND tense_label;

-- Parallel transport between two records — explicit SO(2) rotation matrix
TRANSPORT corpus FROM (token_str='walk') TO (token_str='walked')
  ON FIBER (f11, f12);

-- Betti numbers — sheaf cohomology
BETTI sensors;
BETTI sensors ORDER 1;  -- explicit β_k via the cell complex (Phase 1: k ∈ {0, 1})

-- Yang-Mills topology verbs (2026-06-28). Discrete Chern-Weil integration,
-- π_1 fundamental group, principal-bundle section-existence obstruction.
-- All five verbs answer end-to-end through /v1/gql against a declared lattice
-- + gauge field (verified on production 2026-06-28 late):
--   LATTICE smoke FROM CUBIC L=4 DIM=2 PERIODIC;
--   GAUGE_FIELD U_smoke ON LATTICE smoke GROUP SU(3) INIT IDENTITY;
--   CHERN_CLASS U_smoke ORDER 2;        → {"value": 0.0}
--   PONTRYAGIN U_smoke ORDER 1;         → {"value": -0.0}
--   BETTI smoke ORDER 2;                → {"value": 1.0}   (β_2(T²) = 1)
--   PI_1 smoke;                          → {"value": 2.0}   (π_1(T²) = ℤ², rank 2)
--   OBSTRUCTION U_smoke;                 → {"value": 0.0}
CHERN_CLASS gauge_bundle ORDER 2;       -- instanton number Q ∈ ℤ (Lüscher clover)
PONTRYAGIN gauge_bundle ORDER 1;        -- p_1 = 2·c_2 for SU(N)
PI_1 my_lattice;                         -- rank of π_1 (spanning tree + face relators)
OBSTRUCTION gauge_bundle;                -- principal-bundle section sector
SPECTRAL_GAUGE gauge_bundle ON FIBER (q0, q1, q2, q3);  -- fiber-weighted Laplacian gap

-- Bridge Trilogy verbs (2026-06-28). 4D cubic + NPZ ingest + SU(3) ingest.
-- The LATTICE → GAUGE_FIELD → CHERN_CLASS bridge is live end-to-end on
-- production (see smoke chain above): LATTICE declares the base, GAUGE_FIELD
-- declares the bundle, CHERN_CLASS reads the instanton sector.
LATTICE my_4d FROM CUBIC L=12 DIM=4 PERIODIC;
INGEST configs_bundle FROM 'harvest_L12_beta6.0_run1.npz' FORMAT NPZ;
GAUGE_FIELD U_4d ON LATTICE my_4d GROUP SU(3) INIT HAAR SEED 42;

-- L=24 OBC layer (2026-07-01). Open boundary along one axis (wrap edges +
-- boundary-crossing plaquettes omitted), one-step NPZ → gauge-field bundle,
-- per-config sector write-back, append-only schema evolution,
-- sector-stratified spectral gaps:
LATTICE l24 FROM CUBIC L=24 DIM=4 OBC AXIS 0;
INGEST su2_configs FROM 'raw_U_configs.npz' FORMAT NPZ KEY U
  AS GAUGE_FIELD GROUP SU(2) ON LATTICE l24;
ALTER BUNDLE su2_configs ADD BASE q_rounded INT;
CHERN_CLASS su2_configs ORDER 2 ON LATTICE l24 GROUP SU(2)
  PER config_id INTO_COLUMN q_rounded;
SPECTRAL_GAUGE su2_configs WHERE q_rounded = 0
  ON FIBER (q0, q1, q2, q3) GROUP SU(2);

-- Engine batch (2026-07-03). Evidence-grade error bars, schema
-- introspection, CSV in/out, per-field curvature decomposition, time as
-- a first-class type:
INTEGRATE runs MEASURE avg(plaquette) WITH JACKKNIFE ALONG sweep SKIP FIRST 500;
SHOW FIELDS ON sensors;                  -- one real row per field (field/kind/type/indexed)
EXPLAIN SECTION sensors AT sensor_id='S-001';    -- per-field κ + constant record_kappa
INGEST sensors FROM 'readings.csv' FORMAT CSV;   -- header row, inferred types; JSONL too (KEY <col> required)
COVER sensors ALL EMIT CSV TO 'sensors.csv';     -- fail-closed on GIGI_EMIT_DIR
CREATE BUNDLE events (id TEXT BASE, at TIMESTAMP FIBER);
COVER events WHERE at <= NOW;            -- ISO-8601 literals and NOW are timestamps

-- Millennium observables (2026-07-16/17). Each verb restages a documented
-- geometric signature as a gigi-native readout — evidence in the Davis
-- framework, NOT a proof of the Clay problem it echoes.
--   RIEMANN: a U(1) Hermitian magnetic Laplacian whose level spacing reads the
--   GUE class (measured r̃≈0.605) vs the real cos-weight GOE (≈0.527).
SPECTRAL_GAUGE erdos ON FIBER (theta) GROUP U(1) MODE MAGNETIC FULL LIMIT 8;
SPECTRAL_GAUGE erdos ON FIBER (theta) GROUP U(1) MODE MAGNETIC BULK 32 AROUND 0.0;
--   P vs NP: the raw signed-symmetric spectrum; n_negative / instability_fraction.
SPECTRAL hess ON FIBER (h) MODE MATRIX FULL;
--   Poincaré: an SU(2) loop; order_estimate reads the lens-space π_1 = Z/p class.
HOLONOMY U_lens AROUND CYCLE AXIS z AT (0, 1);
HOLONOMY U_lens AROUND CYCLE EDGES (0, 5, 9, 14);
GAUGE_FIELD theta GROUP U(1) INIT FLUX RANDOM SEED 20260716 ON LATTICE erdos;  -- seed a θ bundle

-- Marcella EXPLAIN family + OR patterns (2026-07-16).
EXPLAIN SECTION corpus AT id=1 VECTOR (v0..v383);   -- per-field κ + additive kappa_v
EXPLAIN SECTION corpus AT id IN (1, 2, 3);          -- grouped rows, one read-lock
DEFINE PATTERN spike AS amount=1 OR flag=2;         -- base-AND-(OR groups), COVER parity

-- Cognitive Geometry verbs (Branch VII)
CAPACITY corpus;    -- τ/K
HORIZON corpus;     -- τ/(K·ℝ“_c)
DEPTH corpus;       -- erasure-energy classifier I/II/III/IV
PERCEIVE corpus ROTATION (r00, r01, r10, r11) VECTOR (v0, v1) DIM 2;

-- Post-Kähler Phase 1 verbs (2026-07-25). Four geometry readouts gated on the
-- `post_kahler_phase1` feature; each ties exactly to
-- theory/post_kahler_directions/validation_tests.py. Ergonomic verb-first forms —
-- no ON clause defaults to every numeric fiber; GAP defaults to 2.
FISHER iris ON (petal_length, petal_width);            -- PK-2 Fisher metric g=diag(1/σ²,2/σ²) per fiber, from L4 Welford variance
PERSISTENCE iris ON (petal_length, petal_width) GAP 2;  -- PK-4 H₀ persistence (MST + elder rule) → honest cluster count
WASSERSTEIN iris ON petal_length BETWEEN species = 0 AND 2;  -- PK-3 exact 1D W₂ between two cohorts (monotone rearrangement)
REEB iris ON (petal_length, petal_width, sepal_length);      -- PK-1 standard contact form α=dz−y·dx + Reeb-field verification

-- Encrypted-at-rest fiber, gauge-preserving
CREATE BUNDLE finance FIBER (
  amount NUMERIC ENCRYPTED,
  account TEXT ENCRYPTED INDEXED
);

Two parser-wide behaviors ride under every verb (2026-07-03): parse errors name the offending token with near-context and a did-you-mean for a misspelled first verb, and input left over after a complete statement is refused with an explicit trailing-token error instead of being silently discarded. Statements that perform no work (unimplemented SHOW variants, COMPACT, …) return an explicit notice instead of a bare ok.

Complete grammar, status table, complexity per verb, and EMIT / wire format options live in GQL_REFERENCE.md and GQL_SPECIFICATION.md.

6.2 HTTP — the route catalog

The production deployment exposes a consumer-facing HTTP surface: /v1/gql (universal GQL passthrough), /v1/bundles/{name}/* for geometric reads (curvature, spectral gap, holonomy), /v1/bundles/{name}/brain/* for the twelve brain primitives, /v1/causal_states/commutator for the Davis (2026) update commutator, /v1/bundles/{name}/verify_invariant for the public deterministic invariant check, the Halcyon read routes (/v1/lattice/*, /v1/gauge_field/*, /v1/e_field/{name}, /v1/symplectic_flow/diagnostics/:run_id), and the Post-Kähler Phase 1 routes (/v1/bundles/{name}/fisher_metric, .../topology/persistence, .../ml/wasserstein, .../brain/reeb_flow — each the REST twin of its GQL verb), and the shape verbs /v1/bundles/{name}/texture (self-similarity exponent of one ordered field), /v1/bundles/{name}/precedence (which of two fields moves first, read from record order rather than any clock), and /v1/bundles/{name}/cadence (whether a timestamped event stream arrives steadily or in bursts, and whether the unevenness has memory). All three are also GQL verbs — TEXTURE b ON f ALONG o, PRECEDENCE b ON x, y ALONG o, CADENCE b ON t — returning a one-row envelope from the same kernels, so the two surfaces cannot disagree. User-facing guide: docs/SHAPE_VERBS.md. For the full route catalog hit GET /v1/openapi.json against any running gigi-stream instance — the OpenAPI document is the source of truth for shapes, parameters, and auth requirements.

6.3 Cognitive Geometry — builder-facing routing

Five verbs translating static geometric scalars into routing decisions the way a builder would phrase them: can the substrate hold this interpretation? (CAPACITY = τ/K, CGC Thm 8.1), how deep does coherent context extend? (HORIZON = τ/(K·ℝ“_c), Thm 8.6), what's the erasure energy of writing here? (DEPTH classifier I/II/III/IV, Thm 8.14), what does the substrate perceive this vector as, and how much should I trust the perception? (PERCEIVE, §8 step 4), and how trustworthy is the recent coherence regime? (LOCAL_HOLONOMY, COHERENCE_SIGNAL_SPEC §3). HTTP shapes under /v1/bundles/{name}/{capacity,horizon,depth,perceive,local_holonomy}.

6.4 Halcyon — lattice gauge theory on the substrate

Halcyon is SU(2) Yang-Mills on the buckyball lattice, running on GIGI as its substrate. The Parts I–IV sprint locked the verbs that take a ~600-line Python kernel and collapse it into a five-statement GQL block — the same block from the Quick Start, repeated here as the section's headline:

LATTICE buckyball FROM TRUNCATED_ICOSAHEDRON TOPOLOGY "S2";

GAUGE_FIELD U ON LATTICE buckyball GROUP SU(2) INIT IDENTITY;

GIBBS_SAMPLE U
  BETA 2.5 N_SWEEPS 200
  MEASURE_EVERY 1
  MEASURE (MEAN(PLAQUETTE), Q_SURROGATE)
  SEED 20260616;

E_FIELD E ON GAUGE_FIELD U INIT MAXWELL_BOLTZMANN BETA 2.5 SEED 20260617;

SYMPLECTIC_FLOW U FROM (U=U, E=E)
  BETA 2.5 DT 0.02 N_STEPS 1000
  PROJECT_GAUSS TRUE
  MEASURE_EVERY 20
  MEASURE (H_TOTAL, MEAN(PLAQUETTE), GAUSS_RESIDUAL_MAX, Q_SURROGATE)
  SEED 20260617;

Verb by verb. One-line description + spec link. Per-verb receipts (red-then-green commits, A2 row pins, fixture replays) live in the gates docs.

• LATTICE — declares a graph topology by (VERTICES, EDGES, FACES, TOPOLOGY) with the truncated-icosahedron shorthand. Storage: incidence table + Euler-characteristic precompute + face-cycle orientation table. Generalized HOLONOMY walks edge-list loops on a declared lattice. → HALCYON_PART_I_GATES.md Part I.
• GAUGE_FIELD — per-edge group-element store with group-erased storage (SU(2) only at launch; U(1) / Z_N are typed-empty arms). INIT IDENTITY and INIT HAAR_RANDOM SEED n both ship; declare → introspect → re-declare → bit-identical. → HALCYON_PART_I_GATES.md Part II.
• PLAQUETTE / Q_SURROGATE — observable battery. PLAQUETTE desugars to face holonomy via the Part I walker; three call shapes (PerFace / Mean / Sum). Q_SURROGATE is (1/2π) · Σ_f arccos(clamp(q0_f, −1, 1)). → HALCYON_PART_I_GATES.md Part III and the Q1/A1 math in HALCYON_TO_GIGI_REPLY_2026-06-17.md.
• GIBBS_SAMPLE — Kennedy-Pendleton heatbath sweep with the staple-sum kernel and a sqrt-rejection-on-x0 Haar fallback for ||staple|| · β < ε. Sequential edge order is bit-identity load-bearing. Reproduces Halcyon's <P>_canonical byte-for-byte at fixed seed within GIGI. → HALCYON_PART_III_GATES.md and HALCYON_PART_III_IMPLEMENTATION_LOG.md.
• E_FIELD — Lie-algebra sibling buffer parked next to a GAUGE_FIELD. (n_edges, 4) quaternion-packed with q0 = 0 enforced at every entry point. INIT MAXWELL_BOLTZMANN BETA β SEED s draws per-edge Gaussians with sigma = √(1/(β · 1.5)); the fourth normal is consumed-then-discarded so β-shifted runs share an identical RNG advance per edge (the A2 row 1 bit-identity contract). → HALCYON_PART_IV_GATES.md §IV.1.
• SYMPLECTIC_FLOW — second-order Kick-Drift-Kick leapfrog on (U, E). Drift uses the closed-form SU(2) Rodrigues exponential with a 4th-order Taylor fallback at θ < 1e-8. Kick uses the Wilson force F[e] = (−β/8) · staple_sum. PROJECT_GAUSS TRUE (default) projects the covariant Gauss residual back to the constraint surface every step. Kogut-Susskind Hamiltonian with g² = 4/β is load-bearing — the naive convention gives 65% drift over 200 steps; Kogut-Susskind gives < 1e-4. → HALCYON_PART_IV_GATES.md §IV.4–IV.6.
• PROJECT_GAUSS — knob struct exposing {tikhonov, cg_tol, cg_max_iter} over the unpreconditioned Hestenes-Stiefel CG projector. Production defaults are {1e-14, 1e-10, 200} (matches Halcyon Python). The spec-default 1e-12 lives behind explicit struct sugar. Buckyball cond(L_cov) ~ 16 needs no preconditioner; Jacobi is P1. → A1 / Q3 in HALCYON_TO_GIGI_REPLY_2026-06-17.md.

Embedded vs HTTP — the II.6c split, named here.

LATTICE, GAUGE_FIELD, PLAQUETTE, Q_SURROGATE, SHOW E_FIELD, SELECT H_TOTAL OF (U,E), SELECT GAUSS_RESIDUAL_MAX OF (U,E), and the GET /v1/symplectic_flow/diagnostics/:run_id LRU lookup all have HTTP routes — they're consumer-facing reads and ephemeral declares. They resolve on the production deployment with auth; embedded-only declarers return 404 on the same surface.

GIBBS_SAMPLE, SYMPLECTIC_FLOW, and E_FIELD declare are embedded-only by design. The reason isn't aesthetic — GIBBS_SAMPLE at β=2.5 on a 90-edge buckyball runs ~46 minutes wall-clock on production hardware doing O(10⁶) per-edge updates. Nobody runs that over JSON and waits for it. The route table absence is the enforcement; the soft-edge through /v1/gql is by design (any consumer routing a 46-minute mutation verb through HTTP self-deselects). Embedded GQL via PyO3 / CFFI is the canonical declarer / mutator surface for any consumer crossing a restart boundary.

Bit-identity contract. Six rows from HALCYON_TO_GIGI_REPLY_2026-06-17.md § A2:

Intra-binding strict; cross-binding (NumPy PCG64 mock vs Rust xorshift64*) impossible by design. CG iteration counts vary across β at fixed seed — that's a diagnostic, not a regression.

Where to read more.

Gates: HALCYON_PART_I_GATES.md, HALCYON_PART_III_GATES.md, HALCYON_PART_IV_GATES.md, HALCYON_PART_V_SNAPSHOT_GATES.md. Implementation logs (red-then-green commits, fixture SHAs): the *_IMPLEMENTATION_LOG.md siblings. Cross-team protocol: HALCYON_TO_GIGI_REPLY_2026-06-17.md. Yang-Mills mass-gap chapter (forward-tracking content target): GIGI Solves: The Clay Seven, Vol 4.

The Bridge Trilogy + Yang-Mills topology layer (2026-06-28). Three substrate items unblock the 4D SU(3) pipeline, then five verbs read topological invariants off the resulting bundles.

The trilogy itself — LATTICE … FROM CUBIC L=N DIM=K PERIODIC (n-D cubic primitive: L=12 D=4 gives 20736 vertices / 82944 directed links / 124416 plaquettes, matching Halcyon's December harvest dimensions), INGEST bundle FROM 'file.npz' FORMAT NPZ (real ingest executor via the npyz crate; SU(3) configs of shape (L, L, L, L, 9) complex flatten cleanly to per-link records), and GAUGE_FIELD … GROUP SU(3) INIT … (raw 3×3 complex storage = 144 B per link, Mezzadri 2007 Haar for INIT HAAR, conjugate-transpose inverse, 3×3 matmul compose, Re Tr(U)/3 plaquette reduction). Phase 1 scope is read-only ingest. Phase 2 (Cabibbo-Marinari heatbath, SU3EField tangent space, SU(3) Wilson force, symplectic flow) ships when Halcyon needs gigi to compute SU(3) configs in-house instead of ingesting them — currently they regenerate via lattice/gauge_heatbath_gpu.py on a GPU machine and INGEST the result. See HALCYON_BRIDGE_TRILOGY_2026-06-28_SHIPPED.md.

The topology verbs — SPECTRAL_GAUGE bundle ON FIBER (…) [GROUP …] returns λ₁ of the fiber-weighted Laplacian L_A (dense nalgebra::SymmetricEigen Phase 1 for bundles up to ~1000 vertices; Lanczos sparse + FULL k-eigenvalue mode is the named Phase 2 ship). CHERN_CLASS bundle ORDER 2 returns the discrete instanton number Q ∈ ℤ via Lüscher 1982 clover discretization — one integer per gauge configuration, classifying the topological sector for the mass-gap argument. PONTRYAGIN bundle ORDER 1 returns p₁ (= 2·c₂ for SU(N), Lüscher sign convention pinned). PI_1 lattice_name returns the rank of the fundamental group via BFS spanning tree + face-relator construction (Massey Ch IV §5). OBSTRUCTION bundle_name returns the principal-bundle section-existence class (= rounded c₂ for SU(N) on 4D, rounded c₁ for U(1) on 2D). BETTI bundle ORDER k extends BETTI to cell-complex β_k via integer-SNF on boundary maps. The TDD audit trail is preserved in git history (tests(X): RED … commits precede impl(X): GREEN … for each concept). See SPECTRAL_GAUGE_PHASE1_SHIPPED_2026-06-28.md and YANG_MILLS_TOPOLOGY_VERBS_SHIPPED_2026-06-28.md.

The L=24 OBC layer (2026-07-01). Four grammar extensions unblock Halcyon's SU(2) 4D L=24 β=2.3 open-boundary sectoral workflow; they compose into one Q-sector-by-Q-sector chain (declare → ingest → classify → stratify).

• LATTICE … FROM CUBIC L=N DIM=K OBC AXIS <k> opens the boundary along one axis: edges wrapping axis k and plaquettes crossing its boundary are omitted; the vertex set stays L^D. L=24 D=4 OBC AXIS 0 gives V = 331,776 (unchanged), E = 1,313,280, F = 1,949,184 — down from the periodic 1,327,104 / 1,990,656. Multi-axis OBC (PERIODIC AXES (…) OBC AXIS …) is deferred to Phase 2; OPEN (fully-open) cannot combine with OBC AXIS.
• INGEST <bundle> FROM '<file.npz>' FORMAT NPZ [KEY <member>] AS GAUGE_FIELD GROUP <g> ON LATTICE <l> turns a raw NPZ archive into a gauge-field bundle in one step. Axes decode as (config_id, mu, site_*, fiber); fiber columns take the canonical per-group names (q0..q3 SU(2), re_00..im_22 SU(3), theta U(1)); every record carries vertex_a / vertex_b base fields computed with the lattice's own column-major site numbering; records that would wrap across the OBC boundary are omitted, so the record set equals the lattice edge set by construction. KEY <member> selects one array out of a multi-array archive. f32 sources upconvert exactly to f64 (24-bit mantissa fits inside 53); unsupported dtypes error by name. Since 2026-07-03, server-side sources resolve relative to the fail-closed GIGI_INGEST_DIR (unset ⇒ disabled; prod pins /data/ingest — see the environment gates under Build, test, run).
• CHERN_CLASS <bundle> ORDER 2 [ON LATTICE <l>] [GROUP <g>] [PER <field>] [INTO_COLUMN <col>] reads the instanton sector per record group (PER config_id = one Q per configuration) and writes the rounded sector back into