forgo.cloud
Sign in
Repo workspace

forkjoin-ai/gnosis

GG Developer Guide

docs/GG_DEVELOPER_GUIDE.md
forkjoin-ai/gnosis
Repo overview Open in workbench

GG Developer Guide

Parent README: ../README.md

This guide is the developer entrypoint for using GG in Gnosis. It is intentionally practical: write a graph, run it, test it, import modules, and know which surface owns the next step.

What GG Is

GG names the graph language used by Gnosis. A .gg file describes executable work as nodes and directed edges. The same graph shape is consumed by the parser, analyzer, verifier, runtime, test framework, module loader, polyglot extractors, and formal ledger tooling.

Use GG when you want to make workflow structure explicit:

  • split work into branches with FORK
  • choose or compare branches with RACE
  • combine branch outputs with FOLD
  • isolate or discharge failure paths with VENT
  • mark ordinary sequential work with process-style edges
  • keep runtime capability and proof provenance attached to the graph

If you prefer to start from TypeScript, use gnode. It extracts a supported TypeScript orchestration subset into GG and runs the same admission path.

First Run

From the monorepo root:

GNODE_FORCE_TSX=1 pnpm --dir open-source/gnosis run monster:echo
GNODE_FORCE_TSX=1 pnpm --dir open-source/gnosis run monster:fib20

GNODE_FORCE_TSX=1 is the reliable first-run path for a shared monorepo checkout because it bypasses the prewarmed Gnosis bridge bundle. After the bundle has been refreshed for the exact workspace dependency graph, you can drop the flag to measure the faster bundled path.

Then inspect the smallest authoring examples:

For TypeScript-first usage:

pnpm --dir open-source/gnosis run gnode -- run ./path/to/app.ts

Use gnode when you want the TypeScript bridge to expose the compiled schedule before you author GG directly.

Developer Path

Read these in order:

  1. GG_LANGUAGE_REFERENCE.md: syntax, nodes, edges, labels, imports, and common topology shapes.
  2. GG_CLI_REFERENCE.md: gnosis, gnode, monster, lint, analyze, verify, build, run, test, and module commands.
  3. GG_MODULES_AND_EXTENSIONS.md: .gg / .mgg modules, public package exports, extension points, and editor/tooling integrations.
  4. GG_SURFACE_MAP.md: all GG-facing source, runtime, example, formal, package, and cross-site surfaces.

Use the ebooks as deeper background after the implementation docs:

What To Use When

Goal Primary surface
Learn GG syntax GG_LANGUAGE_REFERENCE.md, ../examples/README.md
Run TypeScript through Gnosis ../gnode/README.md
Execute extracted graphs ../polyglot/README.md, monster
Test topologies ../src/testing/README.md, Book 189
Compose modules ../src/mod/README.md, Book 188
Use package APIs GG_MODULES_AND_EXTENSIONS.md
Add runtime behavior ../src/runtime/README.md, ../runtime/README.md
Add language/framework extraction ../polyglot/src/README.md
Need proof provenance ../FORMAL_LEDGER.md, ../THEOREM_LEDGER.md
Publish or inspect the public site ../aeon.toml, https://gnosis.forgo.cloud/

Rules For GG Docs

  • Keep runnable commands behind sovereign repo entrypoints.
  • Treat analyze as report-only; executable paths must pass universe admission.
  • Do not claim a proof unless the formal ledger, Lean, TLA+, or generated artifact path is named.
  • Prefer current source and package exports over older ebook prose when they disagree.
  • Label experimental or cross-site integrations instead of presenting them as the first-run path.

Current Scope

This repository has thousands of GG-family files and many public exports. The developer docs do not try to inline every implementation detail. They provide a stable navigation spine so a developer can find the owning module, command, or extension point before editing or importing it.