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
15 changes: 14 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,18 @@ godcode ledger verify # verify the covenant chain
- `DECLARE INTENT "words..." ON rite_name` names a rite's purpose; at
invocation the Spirit checks alignment and counsels gently on drift.
Drift can never fail a run.
- Contract clauses are the checkable half of that promise. Inside a rite
body, `REQUIRE expr` is weighed at entry (parameters bound, body not
yet run), `ENSURE expr` at exit (the body's declared names still in
scope, after `RETURN` too), and `NEVER expr` at both thresholds; in
this first form `NEVER` is weighed only at the thresholds, never
continuously. Clauses are declarations, not steps: the parser gathers
them into the rite's contract in written order, and one spoken outside
a rite body (or nested in a branch) is a parse error. A broken clause
FAILS the run with `CONTRACT_ERROR`, naming the rite, the clause, and
the values weighed. Run reports carry a `contracts` array
(`{rite, kind, text, passed}`) beside `intents`. Clause words are
English in every tongue for now; tongue equivalents are not yet vetted.
- `ASCEND` ends the run peacefully (not an error).
- An unbound name evaluates to a Symbol. It does not raise. `BREATHE LIFE INTO`
an undeclared name *does* raise at runtime.
Expand Down Expand Up @@ -97,13 +109,14 @@ godcode ledger verify # verify the covenant chain
| `LEXER_ERROR` | bad characters / unterminated string | check quotes on the reported line |
| `PARSE_ERROR` | grammar violation | missing BEGIN/END CREATION or block closer |
| `RUNTIME_ERROR` | failed while running | DECLARE names before use; re-read the line |
| `CONTRACT_ERROR` | a rite broke a REQUIRE / ENSURE / NEVER clause | mend the offering or the promise; see `contracts` in the report |
| `FILE_ERROR` | scroll unreadable | check the path |

## Agent workflow

generate → `explain --json` (on an unfamiliar scroll) → `check --json` →
fix from diagnostics → `run --sandbox --json` → inspect
`output`/`error`/`intents` → iterate. Never run untrusted scrolls without
`output`/`error`/`intents`/`contracts` → iterate. Never run untrusted scrolls without
`--sandbox`. Keep the human's production checklist (provider contracts,
real credentials, Bank of Botswana sandbox submission) out of the way.
Demo in sandbox mode.
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
- **🕊️ Contract clauses: `REQUIRE`, `ENSURE`, `NEVER`.** The checkable half of a rite's promise, beside `DECLARE INTENT`'s prose. A clause is a declaration written as a line of a rite body; the parser gathers the rite's clauses into its contract, in the order written, and they never execute as ordinary steps. At every invocation the clauses are weighed at the rite's thresholds: `REQUIRE` at the door, in the invocation frame with the parameters bound, before the body runs (a failure means the body does not run); `ENSURE` as the work ends, in the rite's own frame with the body's names still in scope, after `RETURN` as after a plain ending; `NEVER` at both doors, and in this first form only at the doors, never continuously while the body runs, which the docs and the spec say plainly. A broken clause is not counsel: the run fails with a new `ContractError` (machine code `CONTRACT_ERROR`) naming the rite, the clause as written, and the values it was weighed against, and a rite that breaks a clause has that invocation's intent record marked unaligned. Every clause weighed leaves a record in the run report's new additive `contracts` array (`{rite, kind, text, passed}`), in `run --json`, `run --sandbox --json`, the playground's run payload, and the agent bridge's run tool; the dated run schema gains the field additively, its required fields untouched. A clause spoken outside a rite body, or nested in a branch within one, is a gentle parse error. The sandbox weighs clauses exactly as the open run does, and `TRY`/`CATCH` at a call site may shelter a broken clause like any runtime failure. The clause words are English in every tongue for now; their tongue equivalents are the founder's to vet and are not yet spoken. `examples/intent_demo.god` gains a baking rite whose clauses all hold, and the `math` scroll's `FACTORIAL` now swears `REQUIRE n >= 0`. Documented in `docs/LANGUAGE_REFERENCE.md` §9, the spec's new covenant rules SX-40 to SX-45 in `docs/spec/syntax.md` (and the three words join the keyword inventory at LX-7), `docs/machine-interfaces.md`, and repo `AGENTS.md`. 27 new tests in `tests/test_intent_contracts.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
23 changes: 23 additions & 0 deletions docs/LANGUAGE_REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -354,6 +354,29 @@ REVEAL(word) # grace upon seeker
- Calling with the wrong number of arguments is an error.
- `RETURN` with no value returns `void`.

### Contract clauses: `REQUIRE`, `ENSURE`, `NEVER`

A rite may swear to its own behaviour with contract clauses, written as lines of its body:

```godcode
DEFINE RITE bake(loaves)
REQUIRE loaves > 0
ENSURE loaves IS 5
NEVER loaves < 0
REVEAL("the oven holds {loaves} loaves")
END RITE
```

Clauses are declarations, not steps. The parser gathers them into the rite's contract, in the order written, and they are weighed at the rite's thresholds every time it is invoked:

- **`REQUIRE expr`** is weighed at the door, in the invocation frame with the parameters bound, before the body runs. If it does not hold, the body does not run and the run fails.
- **`ENSURE expr`** is weighed as the work ends, after the body completes (by `RETURN` or by walking off its end), in the rite's own frame, where the names the body declared are still in scope. If it does not hold, the run fails; the work was done, but it does not stand.
- **`NEVER expr`** is weighed at both doors: the expression must be false as the rite begins and false again as it ends. In this first form `NEVER` is weighed only at the thresholds, not continuously while the body runs.

A broken clause is a broken promise, and it is not counsel: the run fails with a `CONTRACT_ERROR` naming the rite, the clause as written, and the values it was weighed against. If the body itself raises, or the run ascends out of the rite, the exit clauses are weighed no further. A clause spoken outside a rite body, or nested inside a branch within one, is a parse error. `TRY`/`CATCH` at a call site may shelter a broken clause, as it shelters any runtime failure.

Clauses are the checkable half of the promise that `DECLARE INTENT` speaks in prose (§16): the intent is discerned and drift is counseled, but a clause binds, and a rite that breaks one also has its invocation recorded as unaligned in the run's `intents` array. Every clause weighed leaves a record in the run report's `contracts` array: `{rite, kind, text, passed}`. The clause words are English in every tongue for now; their tongue equivalents are the founder's to vet and are not yet spoken. The law lives in the spec at SX-40 to SX-45.

## 10. Calling Things

When you call `NAME(args)`, the heavens are searched in this order:
Expand Down
12 changes: 8 additions & 4 deletions docs/machine-interfaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,14 @@ godcode ledger verify --json
`check --json` lexes and parses without running: `ok` plus a
`diagnostics` array (`line`, `col`, `code`, `severity`, `message`,
`hint`). `run --sandbox --json` runs inside the deny-by-default
sandbox and reports `output`, `seals`, `intents`, `permissions`, and
`error` (null on a clean run; `line`, `col`, `code`, `message`, and a
rite call `trace` on failure), with `stats` timing the run. `explain
--json` reads the scroll's static facts without running it: tongue,
sandbox and reports `output`, `seals`, `intents`, `contracts`,
`permissions`, and `error` (null on a clean run; `line`, `col`,
`code`, `message`, and a rite call `trace` on failure), with `stats`
timing the run. The `contracts` array is additive: one entry per
contract clause weighed at a rite's thresholds, each holding `rite`,
`kind`, `text`, and `passed`; a broken clause fails the run with
code `CONTRACT_ERROR`. `explain --json` reads the scroll's static
facts without running it: tongue,
rites and their declared intents, declared names, reveals, seals,
summoned verbs, consults, imports, and the permission manifest.
`ledger verify --json` attests the covenant chain and the anchor chain
Expand Down
2 changes: 1 addition & 1 deletion docs/spec/lexical.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ lexes as `REVEAL 1 NEWLINE REVEAL 2 EOF`. The language is line-oriented, and the

**LX-7.** The keywords are these, and only these:

`BEGIN` `CREATION` `END` `DECLARE` `AS` `BREATHE` `LIFE` `INTO` `REVEAL` `PROPHESY` `ASCEND` `IF` `THEN` `ELSE` `ENDIF` `FOR` `IN` `ENDFOR` `WHILE` `DO` `ENDWHILE` `BREAK` `CONTINUE` `TRY` `CATCH` `ENDTRY` `DEFINE` `RITE` `INVOKE` `RETURN` `IMPORT` `IS` `NOT` `AND` `OR` `REFLECT` `BLESS` `ANOINT` `SEAL` `TESTIFY` `TRUE` `FALSE` `VOID`
`BEGIN` `CREATION` `END` `DECLARE` `AS` `BREATHE` `LIFE` `INTO` `REVEAL` `PROPHESY` `ASCEND` `IF` `THEN` `ELSE` `ENDIF` `FOR` `IN` `ENDFOR` `WHILE` `DO` `ENDWHILE` `BREAK` `CONTINUE` `TRY` `CATCH` `ENDTRY` `DEFINE` `RITE` `INVOKE` `RETURN` `IMPORT` `IS` `NOT` `AND` `OR` `REFLECT` `BLESS` `ANOINT` `SEAL` `TESTIFY` `REQUIRE` `ENSURE` `NEVER` `TRUE` `FALSE` `VOID`

Multi-word phrases like `BEGIN CREATION`, `END RITE`, and `BREATHE LIFE INTO` are separate keyword tokens at this layer. Joining them into phrases is the syntax layer's work. `TRUE`, `FALSE`, and `VOID` are keywords, so they work in any letter case.

Expand Down
14 changes: 14 additions & 0 deletions docs/spec/syntax.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,20 @@ parses to a `Program` holding one `CreationBlock`, which holds the `REVEAL`.

**SX-27.** A call names a rite directly: `name(args)` wherever a value is expected, or `INVOKE name(args)` as a statement. Arguments are comma-separated expressions; empty parentheses call with none. There are no method calls: a call's target is always a plain name.

## Covenants: contract clauses

**SX-40.** A rite body may carry contract clauses: `REQUIRE expr`, `ENSURE expr`, and `NEVER expr`. A clause is a declaration, not a step. The parser lifts every clause out of the body, in the order written, and gathers it into the rite's contract; clauses never execute as ordinary statements, and a clause written after a `RETURN` binds exactly as one written before it.

**SX-41.** A clause may only be spoken as a direct line of a rite body. At the top level of a creation, in a bare fragment, or nested inside a branch or loop within the rite, it is a parse error, answered gently with the way back.

**SX-42.** `REQUIRE` is weighed at the rite's door: the expression is evaluated in the rite's invocation frame, its parameters bound, before the body runs. If it does not hold, the body does not run and the run fails with a contract error naming the rite, the clause, and the values it was weighed against.

**SX-43.** `ENSURE` is weighed as the rite's work ends: after the body completes, whether by `RETURN` or by walking off its end, in the rite's own frame, where the names the body declared are still in scope. If it does not hold, the run fails with a contract error; the work was done, but it does not stand.

**SX-44.** `NEVER` is weighed at both doors: the expression must be false as the rite begins and false again as it ends; if it holds true at either threshold, the run fails with a contract error. In this first form `NEVER` is weighed only at the thresholds, not continuously while the body runs. The docs say so plainly, and so does this rule.

**SX-45.** Every clause weighed leaves a record. A run report carries a `contracts` array, one entry per weighing, holding the rite, the kind, the clause's text, and whether it passed; a broken clause reports the error code `CONTRACT_ERROR`. The sandbox weighs clauses exactly as the open run does. The clause words are English in every tongue for now; their tongue equivalents are the founder's to vet and are not yet spoken.

## Imports

**SX-28.** `IMPORT "path"` names a scroll in quotes. Anything but a quoted string is rejected where it stands.
Expand Down
17 changes: 16 additions & 1 deletion examples/intent_demo.god
Original file line number Diff line number Diff line change
@@ -1,7 +1,14 @@
# Intent demo — DECLARE INTENT names a rite's purpose in plain words.
# When the rite is invoked, the Spirit discerns whether its words still
# walk in the declared intent: alignment is blessed, drift is counseled.
# Nothing here can fail the run; the Spirit counsels, it does not condemn.
# Nothing in the intent layer can fail the run; the Spirit counsels, it
# does not condemn.
#
# Beneath the intent sits its checkable half: the contract clauses
# (REQUIRE, ENSURE, NEVER) inside morning_baking. Where the Spirit
# counsels, a clause binds: REQUIRE is weighed before the body runs,
# ENSURE after it, NEVER at both doors. Break one and the run fails.
# In this scroll every clause holds.
BEGIN CREATION
DECLARE INTENT "bring peace to the household" ON evening_blessing
DECLARE INTENT "bring peace to the household" ON war_drum
Expand All @@ -15,6 +22,14 @@ BEGIN CREATION
REVEAL(tally)
END RITE

DEFINE RITE morning_baking(loaves)
REQUIRE loaves > 0
ENSURE loaves IS 10
NEVER loaves < 0
REVEAL("the oven holds {loaves} loaves")
END RITE

INVOKE evening_blessing()
INVOKE war_drum()
INVOKE morning_baking(10)
END CREATION
11 changes: 10 additions & 1 deletion godcode/agentics.py
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,11 @@
"The scroll parsed but stumbled while running. DECLARE every "
"name before use and re-read the reported line."
),
"CONTRACT_ERROR": (
"A rite broke one of its contract clauses (REQUIRE, ENSURE, or "
"NEVER). Either the offering did not meet the promise, or the "
"promise was sworn too tightly. Mend one of them."
),
"FILE_ERROR": "Check the path. The scroll must exist and be readable.",
}

Expand Down Expand Up @@ -148,7 +153,8 @@ def check_payload(file: str, ok: bool, diagnostics: list[dict]) -> dict:
def run_payload(file: str, ok: bool, output: list[str],
seals: list[dict], error: dict | None, ms: int,
intents: list[dict] | None = None,
permissions: dict | None = None) -> dict:
permissions: dict | None = None,
contracts: list[dict] | None = None) -> dict:
return {
"tool": TOOL_NAME,
"command": "run",
Expand All @@ -157,6 +163,7 @@ def run_payload(file: str, ok: bool, output: list[str],
"output": output,
"seals": seals,
"intents": intents if intents is not None else [],
"contracts": contracts if contracts is not None else [],
"permissions": permissions if permissions is not None else {},
"error": error,
"stats": {"ms": ms},
Expand Down Expand Up @@ -247,8 +254,10 @@ def cmd_run_json(args) -> int:
output = buf.getvalue().splitlines()
seals = _new_seals(interp, seals_before)
intents = list(getattr(interp, "intent_checks", []) or [])
contracts = list(getattr(interp, "contract_checks", []) or [])
manifest = getattr(interp, "manifest", None)
emit(run_payload(args.file, error is None, output, seals, error, ms,
intents=intents,
contracts=contracts,
permissions=manifest.to_json() if manifest else {}))
return 0 if error is None else 1
16 changes: 16 additions & 0 deletions godcode/ast.py
Original file line number Diff line number Diff line change
Expand Up @@ -183,11 +183,27 @@ class TryStmt:
col: int = 1


@dataclass
class ContractClause:
"""REQUIRE / ENSURE / NEVER expr: one checkable promise of a rite.

Clauses are declarations inside a rite body, collected by the parser
into ``DefineRite.contract``. They never execute as ordinary
statements: REQUIRE and NEVER are weighed at the rite's entry,
ENSURE and NEVER again at its exit.
"""
kind: str # "REQUIRE" | "ENSURE" | "NEVER"
expr: Expr
line: int = 1
col: int = 1


@dataclass
class DefineRite:
name: str
params: list = field(default_factory=list) # list[str]
body: list = field(default_factory=list)
contract: list = field(default_factory=list) # list[ContractClause]
line: int = 1
col: int = 1

Expand Down
Loading