Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,15 +123,20 @@ parsed AST. Use it on any scroll you did not write before running it.

## Machine interface schemas

The four `--json` shapes are frozen under dated schemas (God Code
The `--json` shapes are frozen under dated schemas (God Code
releases by date, not by numbers):

```bash
godcode schema # list: check, run, explain, ledger-verify
godcode schema # list: check, run, explain, ledger-verify, receipt
godcode schema explain # print one schema as JSON
```

Schema IDs live under `https://getgodcode.com/schemas/2026-10/`. The
Schema IDs live under `https://getgodcode.com/schemas/2026-10/` for the
October shapes and `https://getgodcode.com/schemas/2026-11/` for the
receipt shape. A receipt records one sandboxed run with its source, so
anyone holding only the receipt file can replay it:
`godcode receipt record scroll.god`, then
`godcode receipt verify scroll.receipt.json` (see `docs/receipts.md`). The
full contract (commands, exit codes, stability promise) is in
`docs/machine-interfaces.md`. Required fields never change meaning;
additive fields may appear. A breaking change would ship under a new
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ All notable changes to the God Code engine are recorded here, that the generatio
## Unreleased

### Added
- **🕊️ Replayable receipts.** `godcode receipt record scroll.god` runs a scroll sandboxed and writes one JSON document holding the source, its fingerprint, the revealed lines, the outcome, the failure when the run failed, the discerned intents, and the permission manifest, sealed with the receipt's own fingerprint. `godcode receipt verify scroll.receipt.json` checks the seal first, so a doctored record is refused before any replay, then replays the recorded source sandboxed and compares the outcome, the revealed lines, and the failure code, exiting 0 only when every comparison matches. A failed run still records, so the failure itself can be replayed and checked. The shape is frozen under the dated schema `https://getgodcode.com/schemas/2026-11/receipt.json`, printed by `godcode schema receipt` and served by the `get_schema` bridge tool, and the schema list grows from four names to five. The honest limits are written into `docs/receipts.md`: receipts record sandboxed runs only and never touch a chain file, scrolls that read a changing value replay differently and verify says so, and scrolls importing from their own directory need that directory named again at verify time with `--import-dir`. New example `examples/receipt_demo.god` and new tests in `tests/test_receipts.py`.
- **🕊️ The MCP server.** `godcode mcp` serves God Code to any MCP client (Claude Code, Cursor, Codex, and the rest) over stdio, one JSON-RPC message per line, with protocol version negotiation and silence for notifications. It carries the eleven agent tools (`check`, `run`, `consult`, `intent`, `anchor_verify`, `ledger_verify`, `permissions`, `explain`, `get_schema`, plus new `format` and `list_scrolls`), and it holds one rule the plain bridge does not: runs through it are always sandboxed, so a client asking for an unsandboxed run still gets a sandboxed one, and the result says so. Tool work runs muted, so stdout carries exactly one protocol message per line and an engine notice can never break a client's parsing; the sandboxed tool path is muted the same way, which also heals the plain bridge. Documented in `docs/mcp.md`, `docs/agentics.md`, and repo `AGENTS.md`. New tests in `tests/test_mcp.py`; the tool-count tests now expect eleven tools.
- **🕊️ The October 2026 machine interfaces.** God Code's `--json` shapes are frozen under dated schemas, so an agent can parse every output without guessing. New `godcode explain scroll.god [--json]`: a static reading of any scroll that runs nothing, reporting the tongue, the rites and their declared intents, the declared names, the reveals, the seals (including `ANCHOR` seals on a chain), the summoned verbs, the `CONSULT` questions, the imports, and the permission manifest, in warm plain words for humans and one JSON document for agents. New `godcode ledger verify --json`: the covenant chain and anchor chain attestation as one JSON document. New `godcode schema [name]`: list or print the four dated schemas (`check`, `run`, `explain`, `ledger-verify`), shipped inside the installed package and resolvable through `importlib.resources`. The agent bridge gains two tools, `explain` and `get_schema` (nine tools in all). The full contract, exit codes, and the stability promise (additive fields may appear, required fields never change meaning, breaking changes ship under a new dated schema) live in `docs/machine-interfaces.md`. New tests in `tests/test_machine_interfaces.py`; repo `AGENTS.md` documents the read-before-you-run workflow.
- **🕊️ God Code speaks Igbo and Nigerian Pidgin.** The third and fourth tongues. A scroll that opens with `# tongue: ig` writes its keywords in Igbo (BIDO OKIKE for BEGIN CREATION, GOSI for REVEAL, Ọ BỤRỤ and MGBE AHỤ for IF and THEN, NWAA and JIDE for TRY and CATCH, and the rest), and one that opens with `# tongue: pg` (or the standard code `pcm`) writes them in Nigerian Pidgin (OYA KREASHON, TALK and BE for DECLARE and AS, SHOW for REVEAL, DEN for THEN, HOLD for CATCH, COMOT for ASCEND). Igbo words work with or without their dotted vowels (`DỊKA` and `DIKA` both speak), and Pidgin keeps the words it shares with English (IF, TRY, AND, RETURN). Two-word phrases now join whenever both words sit side by side on one line, even when one is an English keyword or a plain name, so `FINISH IF` closes an IF in Pidgin and `Ọ BỤRỤ` opens one in Igbo; Setswana and isiZulu closers behave exactly as before. The mappings live in `godcode/tongues.py`; the playground's lite engine knows both tongues (Igbo in its undotted spelling), the language server offers their completions, hover docs, and block snippets (hover now reads dotted words), and the VS Code extension paints their keywords and ships four starter snippets (`ndewo`, `oburu`, `howfar`, `ifden`). Documented in `docs/TONGUES.md` (both word tables and honest first-edition notes), `docs/LANGUAGE_REFERENCE.md` §1, repo `AGENTS.md`, the site landing card, and two new lessons on the learn page. New examples `examples/first_blessing_ig.god` and `examples/first_blessing_pg.god`, also offered as playground samples. 25 new tests in `tests/test_tongues_igbo_pidgin.py`; the VS Code snippet count in `tests/test_lsp_tongues.py` rises from 27 to 31
Expand Down
2 changes: 1 addition & 1 deletion docs/agentics.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ statically — nothing executes — and reports its tongue, rites and
their declared intents, declared names, reveals, seals, summoned
verbs, consults, imports, and permission manifest. The agent bridge
carries the same facts as the `explain` tool, and `get_schema` fetches
any of the four dated machine-interface schemas as parsed JSON.
any of the five dated machine-interface schemas as parsed JSON.
`godcode schema <name>` prints them from the CLI. The full machine
contract — commands, exit codes, and the stability promise — lives in
`docs/machine-interfaces.md`. Agents do not just run God Code.
Expand Down
17 changes: 12 additions & 5 deletions docs/machine-interfaces.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Machine interfaces: the contract for agents

God Code speaks JSON as fluently as it speaks in tongues. Four commands
emit one JSON document each on stdout, shaped by four dated schemas. An
agent parses every output without guessing: read the schema first, then
trust the shape.
emit one JSON document each on stdout, shaped by dated schemas, and a
fifth shape records a run for later replay. An agent parses every
output without guessing: read the schema first, then trust the shape.

## The four commands

Expand Down Expand Up @@ -37,23 +37,30 @@ warm plain words, for humans.
| 1 | diagnostics present, run failed, explain could not read the scroll, or a chain failed verification |
| 2 | usage error (argparse: bad flags, missing file argument) |

## The four schemas
## The five schemas

| Command | Schema |
|---------|--------|
| `check --json` | https://getgodcode.com/schemas/2026-10/check.json |
| `run --sandbox --json` | https://getgodcode.com/schemas/2026-10/run.json |
| `explain --json` | https://getgodcode.com/schemas/2026-10/explain.json |
| `ledger verify --json` | https://getgodcode.com/schemas/2026-10/ledger-verify.json |
| `receipt record` | https://getgodcode.com/schemas/2026-11/receipt.json |

God Code releases by date, not by numbers, so the machine interfaces
are dated, not versioned. Fetch any schema from the engine itself:

```bash
godcode schema # list the four schema names
godcode schema # list the five schema names
godcode schema explain # print the explain schema as JSON
godcode schema receipt # print the receipt schema as JSON
```

Receipts are documented in full in `docs/receipts.md`: a receipt
records one sandboxed run with its source, so anyone holding only the
receipt file can replay it with `godcode receipt verify` and confirm
the recorded result.

The same schemas ride the agent tools: `godcode tools --json` lists
eleven tools (`check`, `run`, `consult`, `intent`, `anchor_verify`,
`ledger_verify`, `permissions`, `explain`, `get_schema`, `format`,
Expand Down
99 changes: 99 additions & 0 deletions docs/receipts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
# Replayable receipts

A receipt is a checkable record of one sandboxed run. It answers the
question a funder, a reviewer, or a stranger on the internet would ask
about any God Code run: prove it happened, and prove this is what it
said.

## The idea in one paragraph

Record a run and you get a single JSON document holding the scroll's
source, the fingerprint of that source, the lines the run revealed,
whether it finished cleanly, the failure when it did not, the intents
it discerned, and the permission manifest it ran under. The document
also carries its own fingerprint, computed over everything else in it.
Hand the receipt to anyone. They run one command, the engine replays
the source in its sandbox, and the command says plainly whether the
replay matches the record. No trust in the person who handed it over
is required. The fingerprint is what makes that true: change one
revealed line after recording and the fingerprint no longer matches,
so verification stops before any replay and says the record was
changed.

## Commands

```bash
godcode receipt record scroll.god
godcode receipt record scroll.god my-receipt.json
godcode receipt verify scroll.receipt.json
godcode receipt verify scroll.receipt.json --json
```

`record` runs the scroll under the strict sandbox policy and writes
the receipt document. With no second argument it writes beside the
scroll, named after it: `scroll.god` becomes `scroll.receipt.json`.
With `--json` it also prints the receipt document on stdout. A failed
run still records, so the failure itself can be replayed and checked;
the human message says which failure code was recorded.

`verify` reads a receipt document and checks it in two steps. First
the seal: the source fingerprint must match the recorded source, and
the receipt fingerprint must match the rest of the document. Then the
replay: the recorded source runs again, sandboxed, and the outcome,
the revealed lines, and the failure code are compared with the
record. Exit 0 only when every comparison matches. With `--json` the
report is one JSON document with `verified`, `seal_intact`,
`replayed`, `differences`, and the full `replay`.

## What verify compares, and what it does not

Compared: the source fingerprint, the clean or failed outcome, the
revealed lines in order, and the failure code on a failed run. The
intents and the permission manifest are recorded for reading, not
compared, because discernment confidence is a reading of the run, not
its result.

Not compared, by design: how long the run took. Timing is not part of
a run's meaning.

## Honest limits

Receipts record sandboxed runs only. A sandboxed run writes nothing to
the host world, so a receipt never carries ledger blocks and never
touches a chain file. That is what makes a receipt safe to pass
around, and it is also the boundary of the claim.

Two kinds of scroll replay differently, and verify says so instead of
pretending otherwise:

- A scroll that reads a changing value, such as the clock or an
anchor timestamp, reveals a different line on replay. Verify
reports the revealed lines as differing.
- A scroll that imports a scroll from its own directory needs that
directory named again at verify time, with `--import-dir`. The
standard library scrolls are always available. Without the
directory, the replay fails on the import and verify reports the
failure code as differing.

## The shape

The receipt shape is frozen under the dated schema
`https://getgodcode.com/schemas/2026-11/receipt.json`, printed by
`godcode schema receipt`. Required fields never change meaning;
additive fields may appear, and a breaking change would ship under a
new dated schema, with this one staying published.

## A worked example

The repository carries `examples/receipt_demo.god`, a small harvest
count that fingerprints its own report:

```bash
godcode receipt record examples/receipt_demo.god
godcode receipt verify examples/receipt_demo.receipt.json
```

The second command prints that the receipt replays exactly as
recorded. Edit any revealed line in the receipt file and run verify
again: it stops at the fingerprint and says the record was changed
after it was recorded.
21 changes: 21 additions & 0 deletions examples/receipt_demo.god
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# A receipt you can check. The accountable agent in miniature.
# This scroll counts a small harvest, fingerprints its own report, and
# reveals the result. Record it, then hand only the receipt to anyone:
# godcode receipt record receipt_demo.god
# godcode receipt verify receipt_demo.receipt.json
# The second command replays the scroll sandboxed and confirms the
# recorded lines match exactly.
BEGIN CREATION
DECLARE INTENT "to count the harvest honestly and show the count" ON tally
DEFINE RITE tally(baskets)
DECLARE total AS SUM_OF(baskets)
REVEAL("baskets: " + STR(LEN(baskets)))
REVEAL("total: " + STR(total))
RETURN total
END RITE
DECLARE harvest AS [12, 7, 19, 7, 12, 4]
DECLARE counted AS tally(harvest)
DECLARE report AS "harvest total " + STR(counted)
REVEAL("fingerprint: " + SHA256(report))
REVEAL(report)
END CREATION
Loading