Docs — GIGI · Davis Geometric

GQL · v2.2

Verbs, by family.

Geometric primitives, not relational — and confidence is not optional: every query returns it. Every verb below parses and executes in gigi-stream today. Families that parse but return 501 or a NOTICE (access control, triggers, prepared statements, backup, session variables) are catalogued in GQL_REFERENCE.md, whose status table is CI-enforced against a real engine.

How to read the chips GQL_REFERENCE.md v2.2 · src/bin/gigi_stream.rs

public read — allowed on POST /v1/public/gql (no auth, allowlisted bundles only): SHOW · HEALTH · DESCRIBE · SECTION AT · EXISTS · COVER · INTEGRATE · SELECT · CURVATURE · SPECTRAL at HEAD · next deploy — REEB · FISHER · WASSERSTEIN · PERSISTENCE ship at HEAD and land with the next deploy everything else runs through the authenticated POST /v1/gql

Family I · storage & writeDefine, insert, evolve.

BUNDLEDefines the fiber bundle (E, B, F, π) — keys on the base, values on the fiber. INDEX builds the field topology; RANGE n sets the curvature denominator.

BUNDLE sensors BASE (id NUMERIC) FIBER (city CATEGORICAL INDEX, temp NUMERIC RANGE 80, wind NUMERIC RANGE 30);

SECTIONInserts one record (a section σ at a base point). Response carries confidence, curvature, and the anomaly flag. UPSERT makes it insert-or-update; RETURNING echoes fields back.

SECTION sensors (id: 42, city: 'Moscow', temp: -31.9, wind: 2.2) RETURNING id, confidence, curvature;

SECTIONSBatch insert — one WAL flush, deferred field index, batch curvature update. With UPSERT: returns { inserted, updated }.

SECTIONS sensors (42, 'Moscow', -31.9, 2.2, 43, 'Moscow', -30.3, 1.8) UPSERT;

REDEFINEUpdate — at a point (AT) or over a cover (ON).

REDEFINE sensors AT id=42 SET (temp: -28.5);

RETRACTDelete — response includes the curvature delta the retraction caused.

RETRACT sensors ON city = 'TestCity';

GAUGE … TRANSFORMSchema migration as a gauge transformation — add, rename, drop fields. Curvature K is invariant under the transform.

GAUGE sensors TRANSFORM (ADD altitude NUMERIC RANGE 5000 DEFAULT 0, RENAME temp TO temperature);

LENSA view — a virtual bundle via morphism. Query it like any bundle; MATERIALIZE REFRESH n precomputes it.

LENS moscow_temps AS COVER sensors ON city = 'Moscow' PROJECT (date, temp, wind);

INGESTBulk import from NPZ, CSV, or JSONL files. CSV infers types from the data; JSONL requires KEY; numeric arrays become vector fibers. Auto-creates the bundle if absent.

INGEST docs FROM 'embeddings.jsonl' FORMAT JSONL KEY doc_id;

ATLASTransactions — an atomic chart transition. BEGIN / COMMIT / ROLLBACK / SAVEPOINT; bare BEGIN; is an accepted alias.

ATLAS BEGIN;  SECTION sensors (id: 9001, city: 'Test', temp: 0.0, wind: 0.0);  ATLAS COMMIT;

COLLAPSEDrops the bundle.

COLLAPSE sensors;

Family II · read & queryPoint, cover, integrate.

SECTION … ATpublic readO(1) point read — section evaluation σ(p). Every response includes confidence and curvature. Always.

SECTION sensors AT id=42 PROJECT (city, temp, wind);

EXISTS SECTIONpublic readBoolean existence check at a base point.

EXISTS SECTION sensors AT id=42;

COVERpublic readRange read — sheaf evaluation F(U). ON hits the field index (bitmap, O(|bucket|)); WHERE scans fiber values. RANK BY / FIRST / SKIP order and paginate; CONFIDENCE >= c filters by geometric trust.

COVER sensors ON city = 'Moscow' WHERE temp < -25 RANK BY temp DESC FIRST 5;

INTEGRATEpublic readAggregation as a fiber integral ∫ h dσ — avg / sum / count / min / max / stddev / variance, with per-group K and confidence in the response. FILTER (WHERE …) works on any aggregate.

INTEGRATE sensors OVER city MEASURE avg(temp) AS avg_t, count(*) HAVING avg_t < 0;

INTEGRATE … WITH JACKKNIFEAutocorrelation-honest error bars on avg() — mean ± corrected err, naive err, blocked-jackknife cross-check, τ_int, n_eff. ALONG defines chain order; SKIP FIRST n is the thermalization cut.

INTEGRATE chain MEASURE avg(plaquette) WITH JACKKNIFE ALONG sweep SKIP FIRST 500;

PULLBACKJoin — the pullback bundle f*E₂, O(|left|). PRESERVE LEFT is the left join; chains and self-joins (via AS) compose.

PULLBACK readings ALONG sensor_id ONTO sensors PRESERVE LEFT;

SHOW · DESCRIBEpublic readCatalog and schema — SHOW BUNDLES lists name, records, base geometry, K, confidence, storage; DESCRIBE adds per-field curvature; SHOW FIELDS ON gives one row per field.

SHOW BUNDLES;  DESCRIBE sensors;  SHOW FIELDS ON sensors;

EXPLAINThe geometric query plan for any statement. Wrapped around a point read, it returns the per-field decomposition of the record's κ — loudest field first, with classical z for cross-checking.

EXPLAIN SECTION stations AT station_id='st-042';

TRANSLATE SQLThe SQL → GQL compiler. Any SQL becomes GQL; not all GQL can go back.

TRANSLATE SQL "SELECT city, AVG(temp) FROM sensors WHERE region='EU' GROUP BY city";

Family III · geometryCurvature, transport, holonomy.

CURVATUREpublic readLocal data variability K — global, per-field, per-group, or scoped to a cover.

CURVATURE sensors ON temp BY city;

CONFIDENCEQuery trust 1/(1+K) — global or cover-specific.

CONFIDENCE sensors ON city = 'Moscow';

RICCIOllivier-Ricci curvature κ(x, y) between two record indices, plus the 1-Wasserstein distance between their neighborhoods. κ > 0: closer than typical; κ < 0: farther.

RICCI sensors BETWEEN 0 AND 1;

HOLONOMYGlobal loop consistency — per-group centroids and transport angles, plus a summary row with the total deficit δφ. ≈ 0 means a flat connection; ≈ 2π a maximally twisted fiber.

HOLONOMY corpus ON FIBER (f11, f12) AROUND tense_label;

HOLONOMY … NEARLocal holonomy in a proximity neighbourhood — { local_holonomy_angle, neighbourhood_size }. O(|N_r|) instead of O(N); METRIC cosine reads WITHIN r as minimum similarity 1 − r.

HOLONOMY corpus NEAR (f11=1.0, f12=0.0) WITHIN 0.3 ON FIBER (f11, f12) AROUND tense_label;

TRANSPORTParallel transport between two records — the rotation angle, the 2×2 SO(2) matrix, and raw displacements per fiber dimension.

TRANSPORT corpus FROM (token_str='walk') TO (token_str='walked') ON FIBER (f4, f11, f12);

GAUGE … VSGauge-invariance test across two bundles — both holonomies, their difference, and gauge_invariant: true when |δφ₁ − δφ₂| < π/10.

GAUGE corpus_en VS corpus_fr ON FIBER (f11, f12) AROUND tense_label;

GEODESICShortest path on the bundle between two points, under the bundle's own metric.

GEODESIC sensors FROM city='Moscow' TO city='Singapore';

PREDICTCurvature-ranked forecasting, with an optional train/test split on the base.

PREDICT sensors ON temp BY city TRAIN BEFORE date=20240901 TEST AFTER date=20240901;

Family IV · spectral, topology & informationThe spectrum is the topology.

SPECTRALpublic readIndex connectivity — λ₁, components, diameter, mixing time. FULL returns the whole eigenvalue spectrum.

SPECTRAL sensors FULL;

SPECTRAL … ON FIBER … MODESThe k smallest non-zero eigenvalues (with inverse participation ratios) of the fiber-space Laplacian — near-zero eigenvalues count the semantic clusters.

SPECTRAL corpus ON FIBER (f11, f12) MODES 3;

BETTITopological invariants β₀ (components), β₁ (independent loops), β₂ (enclosed voids). β₁ > 0 means non-contractible loops in the data topology.

BETTI sensors;

CONSISTENCYČech H¹ diagnostic — h1 = 0 is consistent. REPAIR attempts cocycle resolution.

CONSISTENCY sensors REPAIR;

ENTROPYShannon entropy of the bundle — global, per-field, or per-group.

ENTROPY sensors ON temp BY city;

DIVERGENCEGaussian KL (both directions) + Jensen-Shannon between two bundles, per shared numeric field — O(1) per query after the stats cache warms. VS is an accepted alias for FROM … TO.

DIVERGENCE FROM sensor_das TO sensor_sonar;

FREEENERGYHelmholtz free energy F = −τ log Z at temperature τ. The syntax is AT τ — the parser rejects the older TOLERANCE spelling.

FREEENERGY sensors AT 0.5;

HEALTHpublic readThe full geometric diagnostic for one bundle, in one call.

HEALTH sensors;

PROFILEThe whole geometric data profile — per-field K, confidence, entropy; global scalar curvature, spectral gap, Betti numbers; storage geometry; top outliers with z-scores.

PROFILE sensors;

Family V · post-KählerAt HEAD, landing next.

REEBat HEAD · next deployThe standard contact structure α = dz − y·dx on three chosen numeric fibers and its Reeb field R = ∂_z — verifying α(R)=1, ι_R dα=0, and non-degeneracy on the bundle's own points. Exactly three fields, read as (x, y, z).

REEB cloud ON (x, y, z);

FISHERat HEAD · next deployThe Fisher information metric on the data's statistical manifold. No ON clause → every numeric fiber.

FISHER demo ON (age, income);

WASSERSTEINat HEAD · next deployThe earth-mover distance between one field's distribution in two cohorts, as one scalar — exact 1D W₂ via monotone rearrangement.

WASSERSTEIN pop ON income BETWEEN cohort = 0 AND 1;

PERSISTENCEat HEAD · next deployPersistent homology — cluster births and deaths at every scale. No ON clause → every numeric fiber; GAP factor must be > 1 (default 2).

PERSISTENCE cloud ON (x, y) GAP 3;

Family VI · brain / Friston · cognitive geometryCapacity, horizon, depth.

CAPACITYDavis capacity C = τ/K — how many distinct interpretations the system can hold at this curvature level. τ defaults to 1.0.

CAPACITY sensors TOLERANCE 2.5;

HORIZONHolonomy horizon s_max = τ/(K·ℓ_c) — maximum coherent context depth. ℓ_c is estimated from the spectral gap (ℓ_c ≈ 1/√λ₁); returns Inf when K ≈ 0.

HORIZON sensors TOLERANCE 3.0;

DEPTHEncoding depth as a scalar — 1.0 Tangent (easily erased) · 2.0 Connection (skill-level) · 3.0 Metric (resists argument) · 4.0 Topological (irrecoverable).

DEPTH sensors;

/brain/*The 12 brain primitives — SAMPLE · DREAM · FORECAST · RECONSTRUCT · INPAINT · PREDICT · SELF-MONITOR · ATTEND · FOCUS · EPISODIC · SEMANTIC · EXPLAIN — are REST verbs, not GQL keywords. They ride the Friston master equation on the Kähler bundle at POST /v1/bundles/{name}/brain/*.

curl -X POST http://localhost:3142/v1/bundles/sensors/brain/sudoku \
  -H "Content-Type: application/json" -d '{ … }'
# also: /brain/sample_transport · /brain/confidence_with_explain · /brain/attend · /brain/dream …

The language, and the wire.

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