GG Language Reference

Parent README: ../README.md

This reference covers the practical GG language surface used by Gnosis developers. For compiler implementation details, use ../src/betty/README.md, ../src/mod/README.md, and ../polyglot/README.md.

File Types

Extension	Purpose
`.gg`	Plain topology source. Use for executable graphs, examples, proof witnesses, and runtime fixtures.
`.test.gg`	Topology-shaped test suite. Use with the GG test runner and Gnosis testing adapters.
`.mgg`	Module-scoped GG source with imports, exports, and composition metadata.
`.gnarly`	GG-family source that can attach host-language implementation blocks to graph nodes.
`gnosis.mod`	Module manifest for package name, version, dependencies, exports, and effect contracts.

Core Shape

The common edge form is:

(input)-[:FORK]->(fast_path | safe_path)
(fast_path | safe_path)-[:FOLD { strategy: "linear" }]->(result)

Read it as:

input, fast_path, safe_path, and result are nodes.
FORK and FOLD are edge labels.
{ strategy: "linear" } is an edge property object.
fast_path | safe_path denotes a branch set.

GG is not an imperative language with hidden control flow. The topology is the control surface.

Nodes

A node names one unit of work or state in a topology.

Use stable, descriptive node names:

(load_profile)
(validate_capability)
(run_worker_lane)
(fold_response)

Avoid names that hide ownership or intent:

(data)
(thing)
(step1)

Node labels and properties depend on the parser/compiler surface being used. Check the closest owner README before adding a label that runtime code must interpret.

Edges

The edge label says what relationship the runtime or analyzer should enforce.

Edge	Use
`PROCESS`	Ordinary sequential work or a process step.
`FORK`	Split one upstream node into multiple independent branches.
`RACE`	Let branches compete, compare, or select a winner.
`FOLD`	Combine branch outputs into one downstream result.
`VENT`	Route failure, excess, rejection, or discharge out of the main path.
`SLIVER`	Represent a narrow shard, slice, or bounded subpath when supported by the owning compiler/runtime.

Examples:

(request)-[:PROCESS]->(parse)
(parse)-[:FORK]->(cache_lookup | compute)
(cache_lookup | compute)-[:RACE]->(selected_result)
(selected_result)-[:FOLD]->(response)
(compute)-[:VENT { reason: "timeout" }]->(fallback)

Properties

Properties are structured metadata on nodes or edges. Use them for runtime capabilities, strategy hints, theorem/provenance anchors, or compiler options only when the owning surface reads them.

(load_file)-[:PROCESS { requires: "fs.local" }]->(parse)
(draft | verify)-[:RACE { strategy: "first-valid" }]->(answer)

Common property families:

requires: host capability requirement, normalized by the capabilities layer.
strategy: fold/race/runtime selection hint.
theoremId: formal/provenance anchor when a surface explicitly supports it.
runtime, language, or file: polyglot and .gnarly execution metadata.

Do not add proof-looking properties as decoration. If a theorem id matters, it must correspond to a ledger or artifact surface.

Modules And Imports

Use plain .gg for standalone examples and simple topologies. Use .mgg and gnosis.mod when a graph must import, export, or compose with other graphs.

The module loader is documented in ../src/mod/README.md and Book 188. The host implementation owns:

format detection for .gg and .mgg
import/export parsing
filesystem and lockfile-backed resolution
optional Forge-registry fallback for declared bare specifiers
cycle detection
merged effect-contract summaries
AST merge/lowering
canonical merged-source rendering

Testing

Tests are also topologies. A .test.gg file should name the topology under test, the verification nodes, and the fold into a verdict.

Use:

../src/testing/README.md
../examples/README.md
Book 189 for the higher-level test framework walkthrough

TypeScript Bridge

gnode can compile a supported TypeScript orchestration subset into GG. The supported entrypoint shape is intentionally narrow:

top-level function entrypoints
const / let declarations
call expressions
await
Promise.all([...]) fork/join regions
explicit return

Loops, if / switch, try, and other statements inside the lifted entrypoint fail closed. Move those details into helper functions or author the topology directly in GG.

See ../gnode/README.md.

Formal Provenance

GG can point at formal artifacts, but GG source alone does not make a claim proved. Use these sources for proof-backed claims:

../FORMAL_LEDGER.md
../THEOREM_LEDGER.md
../lean/README.md
../tla/README.md
generated proof artifact reports at the repo root

When writing docs or code comments, state that a topology maps to, models, implements, or is backed by a named theorem. Do not use emphatic identity claims unless the proof is explicit.

Common Patterns

Parallel Work With A Fold

(input)-[:FORK]->(lane_a | lane_b | lane_c)
(lane_a | lane_b | lane_c)-[:FOLD { strategy: "merge" }]->(output)

Fast Path With Fallback

(request)-[:FORK]->(cache | compute)
(cache | compute)-[:RACE { strategy: "first-valid" }]->(answer)
(compute)-[:VENT { reason: "miss-or-timeout" }]->(fallback)

Capability-Gated Host Work

(read_config)-[:PROCESS { requires: "fs.local" }]->(parse_config)
(send_packet)-[:PROCESS { requires: "net.tcp.client" }]->(ack)

Test Verdict

(suite)-[:FORK]->(case_a | case_b)
(case_a | case_b)-[:FOLD { strategy: "all-pass" }]->(verdict)

forkjoin-ai/gnosis