forgo.cloud
Sign in
Repo workspace

forkjoin-ai/gnosis

Gnosis, x-gnosis, and x-gql — consumer stack

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

Gnosis, x-gnosis, and x-gql — consumer stack

These three packages show up together across workers, MCP tools, and research apps. This note maps roles and dependency direction so imports stay intentional.

Roles

Package Responsibility Typical import surface
@a0n/gnosis Graph-first language and runtime: .gg topologies, Betty compiler, scheduling mesh, CRDT/QDoc, math and physics helpers. Subpath imports are only those listed in package.json → exports (for example @a0n/gnosis/math, @a0n/gnosis/daylight-topology, @a0n/gnosis/simultaneity). Prefer the package exports over deep ../../open-source/gnosis/src/... paths.
@a0n/x-gnosis Edge and HTTP-facing adapters: fetch/Worker handlers, knotchain thin client (KnotchainWorkerAdapter), static resolution helpers under edge, nginx-style server surfaces where applicable. import { ... } from '@a0n/x-gnosis/edge' (and other documented subpaths). Builds on gnosis for executing topology from fabric.
@a0n/x-gql GraphQL layer over .gg: schema generation, Apollo / GraphQL Yoga wiring, OpenAPI/Postman export. import { ... } from '@a0n/x-gql' and ./server, ./generate as in package exports. Uses gnosis for compilation and x-gnosis where server/edge glue is needed.

Dependency direction

@a0n/x-gql  ──►  @a0n/gnosis
           ╲
            ──►  @a0n/x-gnosis   ──►  @a0n/gnosis

Workers and apps usually declare @a0n/gnosis whenever they import gnosis subpaths directly, and @a0n/x-gnosis when they use edge/knotchain helpers, even if another dependency pulls them in transitively.

TypeScript consumers

Gnosis typechecks with open-source/gnosis/tsconfig.typecheck.json (Bundler resolution for ergonomic imports). It does not enable noUncheckedIndexedAccess or exactOptionalPropertyTypes. If an app turns those on and typechecks gnosis .ts sources as part of the app program (path aliases into src), the compiler may report errors that gnosis’s own gate does not. Fixes: depend on published types only, relax those flags for the app, or contribute narrow fixes upstream in gnosis.

CI / a0 quality

The full pnpm test suite under open-source/gnosis is large. The Nx target gnosis:test runs test:quality-surface (scheduling-mesh self-test via gnode) so a0 quality exercises real signal without pulling the entire gnode test matrix.

Opt-in mesh + RTL-SDR + mesh-local-mcp gate (wrapper tests, rtlsdr-mock-sim Vitest including subprocess CLI integration, monster-mesh refusal smokes, then mesh-local-mcp Vitest): pnpm run a0 -- run gnosis:test:mesh-rtlsdr (same as pnpm --dir open-source/gnosis run mesh:smoke:local-gates). Use when touching rtlsdr-mock-sim/, bin/rtlsdr-mock-sim.js, or mesh-local-mcp/.

Hardware → replay: with a USB dongle and rtl_sdr installed, pnpm --dir open-source/gnosis run rtlsdr:hardware-loop captures IQ, writes a JSON sidecar with tuner metadata, and runs replay (see rtlsdr-mock-sim/README.md). Optional Vitest tier: RUN_RTLSDR_HARDWARE_TESTS=1 (see Tests section there).

FPGA / register-transfer (verifylog)

Not RTL-SDR: this is VHDL / SystemVerilog for bounded mesh policy slices.

  • Artifacts and layout: ../verifylog/README.md.
  • Emitter + golden tests: ../rtl-bridge/README.md.
  • Roadmap / exit criteria: ../ROADMAP-FPGA.md.
  • Optional GHDL gate: pnpm run a0 -- run gnosis:validate:rtl-sim (set GNOSIS_RTL_TOOLS=1 and install ghdl; otherwise the script no-ops successfully).
  • Optional SymbiYosys: pnpm run a0 -- run gnosis:validate:rtl-formal with GNOSIS_RTL_FORMAL=1 and sby in PATH.

Parent: README.md