AGENTS.md

Cursor Cloud specific instructions

This repository (@a0n/gnosis) is a sub-package of a larger monorepo. The following notes apply to Cloud Agent development sessions.

Workspace context

• This checkout is the open-source/gnosis slice of the forkjoin-ai monorepo. Workspace dependencies (@a0n/aeon, @a0n/bitwise, etc.) are stubbed under .workspace-stubs/ for development.
• The Rust monster binary cannot be built in isolation (depends on ../../gnot from the parent monorepo). The TypeScript path (bin/gnode.js via tsx) is the primary dev surface.

Running tests

# Run a single test file
./bin/monster test src/__tests__/compiler.test.ts

# Run multiple test files
./bin/monster test src/__tests__/engine.test.ts src/__tests__/compiler.test.ts

The test runner goes through bin/monster → bin/gnode.js → gnode/bridge-driver.ts (via tsx). Each test case goes through Universe admission (formal theorem checks) before the actual test assertion runs.

Running the CLI / executing programs

# Run a TypeScript fixture through gnode
./bin/monster run ./gnode/benchmarks/echo.ts --input-json '{"name":"world"}' --export app

# Run fib(20) example
./bin/monster run ./gnode/benchmarks/fib.ts --input-json '{"n":20}' --export app

The bin/gnosis.js CLI (lint, analyze, verify) requires dist/cli.js or a full monorepo import graph. In this isolated checkout, use ./bin/monster run for TypeScript execution.

TypeScript type-checking

pnpm exec tsc -p tsconfig.typecheck.json --noEmit

Expected: some errors from cross-monorepo references (../../aeon/..., @a0n/bitwise/knotchain-fabric, etc.). Core source files typecheck cleanly.

Key gotchas

1. esbuild link: After pnpm install, esbuild's platform binary may need manual linking: ln -sf .pnpm/esbuild@0.28.0/node_modules/esbuild node_modules/esbuild
2. Betti WASM warning: Running code via ./bin/monster run shows a "TypeScript preflight failed" warning from the gnosis-betti-wasm stub — this is expected and does not block execution.
3. Universe admission: The test runner enforces formal topology checks (universe kernel). Tests that modify topology shapes may need to satisfy conservation laws (fork/fold balance).
4. Workspace stubs: The .workspace-stubs/ directory provides minimal implementations of monorepo packages. If tests fail with "does not provide an export named X", the relevant stub needs updating.