government

commit 25d85a34ec701b64fde8050571d39eaa9b8d1bbb

tree

parent:
27e33aecf4976d7646339e35c5fff6755a29497c

nmyk <nick@nmyk.io>

2026-11-14T23:52:36-05:00

rm design doc, add tech spec

diff --git a/DESIGN.md b/DESIGN.md
deleted file mode 100644
index fdd698e772983743a34a7ff3043e6e6315e00fa1..0000000000000000000000000000000000000000
--- a/DESIGN.md
+++ /dev/null
@@ -1,491 +0,0 @@
-# GOVERNMENT Language Design Document
-
-Nov 14, 2026
-
-## Overview
-
-GOVERNMENT is a minimal, lexically scoped Lisp whose programs are X.509 certificate chains. The interpreter validates the chain, computes the X.509 policy tree, and evaluates that tree as the program's AST.
-
-A `.gov` file is a real, standards-conformant certificate path: `openssl x509 -text` will happily print it, and every expression in the program is a certificate policy OID. Parentheses are policy mappings. Nesting depth is chain length.
-
-**Goals**
-
-- Use genuine RFC 5280 / RFC 9618 path-validation semantics, not a look-alike. A program that does not validate does not run.
-- Implement the minimal Lisp core from the brief: 5 atom types, pairs, closures, 4 special forms, 2 short-circuit forms, 17 builtin functions.
-- Reproducible builds: the same Lisp source always transpiles to byte-identical `.gov` output.
-- Human-readable tests: every language test is a plain Lisp file run through a Lisp-to-GOVERNMENT transpiler.
-
-**Non-goals (v1):** I/O, mutation, macros, string operations beyond length, append and type test, performance, and interoperability with the public Web PKI.
-
-**Pipeline**
-
-1. **Load:** decode the PEM blocks into certificates.
-2. **Ratify:** validate the path (name chaining, signatures, validity, CA constraints).
-3. **Policy processing:** build the valid policy tree per RFC 5280 §6.1.3–6.1.4 as updated by RFC 9618.
-4. **Decode:** turn the tree into an AST (skip the validator's copies, order children, decode OIDs into atoms).
-5. **Evaluate:** evaluate each top-level form in order.
-
-Terminology used in this doc: *GOV* is the language's root OID arc; *red tape* is the copies of a leaf that the validator itself generates, through `anyPolicy`, to keep every leaf at the same depth; *ratify* means "pass path validation".
-
-## Source format
-
-A `.gov` file is one UTF-8 text file of concatenated PEM `CERTIFICATE` blocks: a trust anchor and one certificate per tree depth. The compiler writes them anchor first, top-down; the interpreter accepts them in any order.
-
-- **The trust anchor** is the one self-signed certificate. It carries no policies.
-- **The certification path** is every other certificate. The certificate at depth *i* is issued by the one at depth *i−1* and carries every node at depth *i* of the tree. So *n* equals the program's AST depth.
-- **Order.** The interpreter recovers each certificate's depth from the certificates themselves: it starts at the anchor and follows issuer links down. Every link is pinned by a signature, so the order cannot be forged, and a shuffled file runs exactly like the ordered one. A file that is not one clean chain (no anchor, two certificates issued by the same parent, a missing depth, an unrelated certificate) is an error.
-- Text outside PEM blocks is ignored, as PEM allows. The compiler writes nothing there by default (the program's name is already in every subject as `O=`). With `--source` it writes the original Lisp source, indented so no line of it can start a PEM block. The source is opt-in because the certs alone are the program, and the source may hold comments or code the author does not want to publish.
-- Any non-`CERTIFICATE` PEM block is an error.
-- The compiler writes anchor first so that reading the file top to bottom reads the tree top to bottom (conventional PEM bundles are leaf-first). This is for human readers only.
-
-**Trust.** By default a program is self-ratified: the interpreter trusts the anchor inside the file, so validation checks internal consistency only. `government run --anchor gov-ca.pem prog.gov` additionally requires the anchor to match a given certificate, which gives code signing for free: only run programs ratified by your government.
-
-### Certificate profile
-
-| Field | Trust anchor | Cert *i* (1 ≤ i < n) | Cert *n* |
-| --- | --- | --- | --- |
-| Version | v3 | v3 | v3 |
-| Serial | 1 | i + 1 | n + 1 |
-| Signature | Ed25519 (author key) | Ed25519 (key of cert i−1) | Ed25519 (key of cert n−1) |
-| Subject | `CN=<author or GOVERNMENT Anchor>, O=<program>` | `CN=GOVERNMENT Depth i, O=<program>` | `CN=GOVERNMENT Depth n, O=<program>` |
-| subjectAltName | author email, if given | absent | absent |
-| Validity | `--not-before` to `--not-after` (default 2000-01-01 to 9999-12-31) | same | same |
-| basicConstraints (critical) | CA:TRUE | CA:TRUE | CA:FALSE |
-| keyUsage (critical) | keyCertSign, cRLSign | keyCertSign, cRLSign | digitalSignature |
-| certificatePolicies | absent | cert 1: the top-level node OIDs; certs 2..n−1: `anyPolicy` only, plus any node that carries notes | `anyPolicy` only, plus any node that carries notes |
-| policyMappings (critical) | absent | one entry per parent→child edge | must be absent |
-| SKI / AKI | present | present | present |
-
-Notes:
-
-- 9999-12-31 is RFC 5280's "no well-defined expiration" date. Effective dates, repeal, notes and authorship are covered in Civic features.
-- Ed25519 signatures are deterministic, so fixed keys plus fixed dates give byte-identical output.
-- Mappings in cert *n* are rejected because RFC 5280 never processes them (§6.1.4 runs only for certs 1..n−1); allowing them would hide transpiler bugs.
-- Any unrecognized critical extension is rejected, per RFC 5280.
-
-**Size.** A locally built prototype cert with 1 policy and 3 mappings was 525 bytes DER. Only cert 1 lists nodes; every other node costs just its incoming mapping, so expect roughly 350 bytes per depth plus about 50 bytes per node, before PEM's 4/3 base64 overhead.
-
-A program whose forms are all atoms has depth 1: its single cert is both cert 1 and cert n, and lists the top-level nodes.
-
-## The policy tree as AST
-
-The valid policy tree has exactly the shape of a Lisp AST once four quirks are designed around: uniform leaf depth, unordered children, per-OID (not per-node) mappings, and silent dropping.
-
-### How the tree is built
-
-RFC 5280 §6.1 builds the tree one certificate at a time:
-
-1. **Init:** the root is a single `anyPolicy` (`2.5.29.32.0`) node at depth 0, expecting `{anyPolicy}`.
-2. **Policies of cert i:** for each policy P in the cert, every depth *i−1* node whose `expected_policy_set` contains P gets a child P. If none matches, P attaches to a depth *i−1* `anyPolicy` node, which exists only at depth 0. So cert 1's policies become the root's children: the top-level forms.
-3. **anyPolicy in cert i** (RFC 9618 step d.2): for every policy that some depth-*i−1* node expects but that has no node at depth *i* yet, create that node, with every node that expects it as a parent. Certs 2..n assert only `anyPolicy`, so this one rule creates every node below depth 1: a mapped node's children, and, for a node with no mappings, a copy of itself.
-4. **Prune:** any node at depth *i−1* or less with no children is deleted, repeatedly.
-5. **Mappings of cert i:** for every depth-*i* node whose policy is an `issuerDomainPolicy`, its `expected_policy_set` becomes the set of mapped `subjectDomainPolicy` values. An unmapped node expects only itself, which is why step 3 copies it.
-
-RFC 9618 (2024) updates this: it replaces the tree with a `valid_policy_graph`, a DAG where a node may have several parents, to avoid exponential growth. When every node has one parent, the graph and the tree are the same structure.
-
-**Validation inputs:** `user-initial-policy-set = {anyPolicy}`, `initial-policy-mapping-inhibit = false`, `initial-explicit-policy = true`, `initial-any-policy-inhibit = false`. Explicit policy makes an empty tree a validation failure. `anyPolicy` must not be inhibited, because certs 2..n depend on it; for the same reason the `inhibitAnyPolicy` extension is rejected.
-
-### Constraints and design responses
-
-| # | Constraint from RFC 5280 / 9618 | Consequence for a Lisp AST | GOVERNMENT's response |
-| --- | --- | --- | --- |
-| 1 | Pruning deletes every leaf above depth n | `(+ 1 (* 2 3))` would lose `+` and `1` | **Red tape**: certs 2..n assert `anyPolicy`, so the validator copies every unmapped leaf down to depth n. Nothing is written for it |
-| 2 | A cert's policies are a set (no duplicates, no order) | `(+ 1 1)` cannot have two `1` children; argument order is lost | A **node-id arc** in every OID makes siblings distinct and gives their order |
-| 3 | Mappings key on the OID, not the node | Two equal-OID nodes at one depth would get identical children | Node ids are **unique across the whole program**, so every OID is unique |
-| 4 | An unmapped node expects only its own OID | A missing mapping silently drops a subtree: nodes below depth 1 exist only through mappings | A list node (code 1) must have at least one element, and the empty list is its own constant (code 5). **Strict check**: node ids must be exactly 1..N, so a lost subtree leaves a gap. Only losing the subtree with the highest ids goes unnoticed; signatures rule out tampering, so that case can only be a transpiler bug, which round-trip tests catch |
-| 5 | A policy matching no parent at depth ≥ 2 is silently dropped | An explicitly listed node (one carrying notes) with a wrong OID would vanish | **Strict check**: every explicitly asserted policy must appear in the final tree |
-| 6 | Mappings in cert n are never processed | Dead data | Rejected |
-| 7 | `anyPolicy` must not be mapped | — | Certs 2..n must assert `anyPolicy`; cert 1 must not (it would create an `anyPolicy` node under the root); it may never be mapped |
-| 8 | An empty tree fails explicit-policy validation | The empty program cannot exist | A program needs ≥ 1 top-level form |
-| 9 | One child OID mapped from several parents gets several parents (9618) or is duplicated (5280) | Shared subexpressions | The compiler **shares** identical lists at the same depth by default (`--no-share` keeps copies); the decoder and evaluator work on the DAG directly, never unfolding it |
-
-**Strict check.** Plain RFC processing forgives mistakes by deleting code. After policy processing, the interpreter also verifies that certs 2..n assert `anyPolicy` and cert 1 does not, that every explicitly asserted policy in cert *i* is a node at depth *i*, that every mapping in cert *i* produced an edge, and that the program's distinct node ids are exactly 1..N with no gaps. A failure is a ratification error naming the orphaned OID. This turns silent data loss into a compile-style error.
-
-**Denial-of-service guard.** Policy processing has caused real DoS bugs, e.g. Go's CVE-2026-32281 (inefficient policy validation, fixed in Go 1.25.9 / 1.26.2). The graph form keeps work linear in mappings, and the interpreter caps nodes (`--max-nodes`, default 1,000,000), checking the cap as each node is made rather than after. A cap on nodes is not a cap on time, so each cert's work is also kept linear in its level: parents are indexed by the policies they expect, nodes by policy for mappings, and pruning stops at the first level where nothing died. The worst case the cap allows is cheap to reach: every atom above the bottom is copied down once per cert, so a 400 KB file with 6,000 top-level atoms beside one 200-deep form asks for 1.2 million nodes. It is refused in under two seconds.
-
-**OpenSSL.** OpenSSL is not a full validator for GOVERNMENT. Since CVE-2023-0464 it refuses any policy tree over 1,000 nodes (`OPENSSL_POLICY_TREE_NODES_MAX`, fixed when OpenSSL is built), reporting it as a failed allocation in its policy check. It still builds RFC 5280's tree, which unfolds shared nodes, and every atom above the bottom is copied down once per cert, so a program's tree grows roughly as depth times width: a 31-deep `(+ 1 (+ 1 ...))` fits in 961 nodes, a 32-deep one needs 1,024, and six levels of shared doubling that are a few dozen graph nodes unfold past the limit. Even a flat `(+ 1 … 1000)` needs 1,002. Every test program and example fits. Past the limit, a program is still lawful to GOVERNMENT, whose graph budget is a million nodes; a stock OpenSSL just cannot check it. The limit holds through OpenSSL 4.1.0, and can only be changed when OpenSSL is built: `make oracle` builds one with `-DOPENSSL_POLICY_TREE_NODES_MAX=0` (`scripts/openssl-unlimited.sh`, cached outside the repository) and runs the oracle tests with it, and that build agrees with GOVERNMENT on every program over the limit too. Without the limit OpenSSL is open to CVE-2023-0464 again, so that build is only for checking programs you compiled yourself.
-
-## OID encoding
-
-Every node OID is `GOV.<namespace>.<node-id>.<payload…>`. For a builtin the payload is one arc, its fixed code from the builtin table. For every other node it is the Unicode code points of the node's text, one arc each (so ASCII `A` is arc 65).
-
-**Root arc.** `GOV = 2.25.9665536045854453410170579537759926404`. The `2.25` arc takes a UUID as an integer and needs no registration (ITU-T X.667); this one is UUID `074583b8-3bb7-4179-8669-827877697884`. Go's `x509.ParseOID` handles the 128-bit arc. Tools print `GOV` as shorthand.
-
-**Node id.** A positive integer, unique across the whole program, assigned in pre-order by the transpiler. Siblings are ordered by ascending id. Uniqueness is what makes constraints 2 and 3 above go away. Sharing renumbers ids so that every list a shared node belongs to still sorts in argument order (see Shared subexpressions).
-
-**Payload.** For symbols, numbers and strings: Unicode code points 0–0x10FFFF, excluding surrogates. ASCII is the common case. Verified locally: an arc of 128512 (😀) survives a create/parse round trip.
-
-### Namespaces
-
-| ns | Kind | Payload | Source | OID |
-| --- | --- | --- | --- | --- |
-| 0 | builtin | one arc, the builtin's code | `+` | `GOV.0.7.21` |
-| 1 | symbol | symbol name (non-empty) | `foo` | `GOV.1.8.102.111.111` |
-| 2 | integer | decimal text | `-42` | `GOV.2.9.45.52.50` |
-| 3 | float | decimal text | `3.14` | `GOV.3.10.51.46.49.52` |
-| 4 | string | the string's characters, unescaped (may be empty) | `"hi"` | `GOV.4.11.104.105` |
-
-Separating builtins (ns 0) from symbols (ns 1) means a user symbol can never shadow a builtin by accident: the transpiler maps the reserved names in the next section to ns 0, and everything else to ns 1.
-
-**Payload grammars**
-
-- Integer: `-?(0|[1-9][0-9]*)`, range of int64.
-- Float: `-?[0-9]+\.[0-9]+([eE][-+]?[0-9]+)?`. A dot is required; NaN and infinities are not literals.
-- Symbol: any non-empty code point sequence that is not a reserved name and does not parse as a number.
-
-**Why text for numbers.** It is uniform with strings and symbols, follows your ASCII-arc idea, round-trips floats exactly as written, and is readable in an `openssl` dump with a one-line decoder. The alternative (a sign arc plus a magnitude arc for integers, IEEE-754 bits for floats) is shorter but opaque.
-
-## Builtin symbol table
-
-There are 28 builtins, all in namespace 0. Package `builtin` holds this table; the OID encoding and the evaluator both read it, and the evaluator refuses to start if a builtin there has no implementation. Each has a fixed numeric code, which is its whole payload: one arc. `<id>` is the node's own id. Names are case-sensitive.
-
-Codes are grouped with room to grow: structure 1–2, constants 3–5, special forms 10–15, functions 20 and up. A code is permanent: it is never reused or renumbered, and a new builtin takes the next free code in its group.
-
-| Code | Name | Kind | OID | Arity / note |
-| --- | --- | --- | --- | --- |
-| 1 | `(…)` | structural | `GOV.0.<id>.1` | List node; its children are the elements; at least one |
-| 2 | `.` | structural | `GOV.0.<id>.2` | Dotted-pair marker inside a quoted list |
-| 3 | `T` | constant | `GOV.0.<id>.3` | Boolean true |
-| 4 | `F` | constant | `GOV.0.<id>.4` | Boolean false |
-| 5 | `()` | constant | `GOV.0.<id>.5` | The empty list |
-| 10 | `quote` | special form | `GOV.0.<id>.10` | 1 operand |
-| 11 | `if` | special form | `GOV.0.<id>.11` | 2 or 3 operands |
-| 12 | `define` | special form | `GOV.0.<id>.12` | 2 operands |
-| 13 | `lambda` | special form | `GOV.0.<id>.13` | params + 1 or more body forms |
-| 14 | `and` | short-circuit form | `GOV.0.<id>.14` | 0+ operands |
-| 15 | `or` | short-circuit form | `GOV.0.<id>.15` | 0+ operands |
-| 20 | `not` | function | `GOV.0.<id>.20` | 1 arg |
-| 21 | `+` | function | `GOV.0.<id>.21` | 0+ args |
-| 22 | `-` | function | `GOV.0.<id>.22` | 1+ args |
-| 23 | `*` | function | `GOV.0.<id>.23` | 0+ args |
-| 24 | `/` | function | `GOV.0.<id>.24` | 1+ args |
-| 25 | `<` | function | `GOV.0.<id>.25` | 2 args |
-| 26 | `>` | function | `GOV.0.<id>.26` | 2 args |
-| 27 | `<=` | function | `GOV.0.<id>.27` | 2 args |
-| 28 | `>=` | function | `GOV.0.<id>.28` | 2 args |
-| 29 | `==` | function | `GOV.0.<id>.29` | 2 args |
-| 30 | `!=` | function | `GOV.0.<id>.30` | 2 args |
-| 31 | `cons` | function | `GOV.0.<id>.31` | 2 args |
-| 32 | `car` | function | `GOV.0.<id>.32` | 1 arg |
-| 33 | `cdr` | function | `GOV.0.<id>.33` | 1 arg |
-| 34 | `strlen` | function | `GOV.0.<id>.34` | 1 arg |
-| 35 | `strcat` | function | `GOV.0.<id>.35` | 0+ args |
-| 36 | `str?` | function | `GOV.0.<id>.36` | 1 arg |
-
-A ns-0 OID whose code is not in this table, or that does not have exactly one payload arc, is a decode error. Adding a builtin later is backward compatible: it is a new code in the same namespace.
-
-Fixed codes keep every builtin OID to one payload arc (spelling names in ASCII took up to six), at the cost of `openssl` dumps no longer showing builtin names; `government tree` decodes them.
-
-A non-empty list is one list node whose children, in id order, are the list's elements, rather than separate open and close tokens. The tree already encodes nesting, so this needs no matching of parentheses, makes unbalanced lists impossible to encode, and keeps depth equal to nesting depth. Quote sugar (`'x`) has no node; the transpiler expands it to `(quote x)`.
-
-## Tree to AST decoding
-
-Decoding skips red tape (the validator's copies), sorts each node's children by id, and reads every OID as an atom or a list.
-
-**Rules**
-
-1. The root (`anyPolicy`) is the program. Its children, in id order, are the top-level forms.
-2. A child with the same OID as its parent is a copy made by the validator. The decoder skips it. A copy may only have a copy below it.
-3. A list node (code 1) is a list. Its other children, in id order, are its elements, and it must have at least one. The empty list is the constant `()` (code 5), an atom.
-4. Every other node is an atom. Its only child may be its copy.
-5. `.` may appear only as the second-to-last element of a list. It builds a dotted pair and is only meaningful under `quote`.
-6. Anything else is a decode error that names the offending OID and depth.
-
-### Worked example: `(+ 1 (* 2 3))`
-
-The AST is 3 deep, so the file holds an anchor plus 3 certs. Ids are given in pre-order. This is `government tree`'s output for it; a trailing `'` marks a copy the validator makes:
-
-```
-depth 0  anyPolicy
-depth 1  `-- (...)#1       GOV.0.1.1
-depth 2      |-- +#2       GOV.0.2.21
-depth 3      |   `-- +#2'  copy
-depth 2      |-- 1#3       GOV.2.3.49
-depth 3      |   `-- 1#3'  copy
-depth 2      `-- (...)#4   GOV.0.4.1
-depth 3          |-- *#5   GOV.0.5.23
-depth 3          |-- 2#6   GOV.2.6.50
-depth 3          `-- 3#7   GOV.2.7.51
-```
-
-| Cert | certificatePolicies | policyMappings |
-| --- | --- | --- |
-| 1 | `GOV.0.1.1` | `GOV.0.1.1 → GOV.0.2.21`, `→ GOV.2.3.49`, `→ GOV.0.4.1` |
-| 2 | `anyPolicy` | `GOV.0.4.1 → GOV.0.5.23`, `→ GOV.2.6.50`, `→ GOV.2.7.51` |
-| 3 | `anyPolicy` | none |
-
-Policy processing reproduces the tree above. Cert 1's policy attaches to the root. In cert 2, `anyPolicy` creates the three nodes #1 expects. In cert 3, it creates the three nodes #4 expects, and copies `+#2` and `1#3`, which expect only themselves. Nothing is pruned, because every branch reaches depth 3. Decoding skips the copies and yields `(+ 1 (* 2 3))`, which evaluates to `7`.
-
-This was checked with a prototype chain against two independent implementations, OpenSSL 3.0 and Go 1.24's `x509.Verify`: a shallow atom survives to the last cert only when the certs below it assert `anyPolicy`, mapping targets need not be listed, and inhibiting `anyPolicy` makes the chain fail.
-
-## Language semantics
-
-GOVERNMENT is a strict, lexically scoped, purely functional Lisp-1 with Scheme-style truthiness (only F is false) and immutable bindings.
-
-### Values
-
-| Type | Representation | Printed as |
-| --- | --- | --- |
-| Integer | int64; overflow is an error | `-42` |
-| Float | float64; NaN or infinity results are errors | `3.14`, `1.0` (always has a dot) |
-| String | immutable sequence of code points | `"hello"`, with `\"`, `\\`, `\n`, `\t` escaped |
-| Boolean | `T` or `F` | `T`, `F` |
-| Symbol | interned name | `foo` |
-| Pair | immutable (car, cdr) | `(1 2 3)`, `(1 . 2)` |
-| Empty list | unique value | `()` |
-| Function | closure or builtin | `#<lambda fact>`, `#<lambda>`, `#<builtin +>` |
-
-Lists are pairs ending in `()`.
-
-### Evaluation
-
-- Integers, floats, strings, `T`, `F` and `()` evaluate to themselves.
-- A symbol evaluates to its lexical binding; unbound is an error.
-- A builtin function name (`+`, `car`, …) evaluates to that function, so builtins are first-class: `(define add +)` works.
-- A special-form name in a non-head position is an error. `(define my-if if)` is rejected.
-- A non-empty list whose head is a special form follows that form's rule. Otherwise the head and then the arguments are evaluated left to right, and the head must be a function.
-- Tail calls (function bodies and `if` branches) are proper, so recursive loops run in constant Go stack.
-
-### Special forms
-
-- **Truthiness.** As in Scheme, `F` is the only false value. Everything else is true, including `0`, `0.0`, `""` and `()`.
-- **`(quote d)`** returns `d` as data, unevaluated. Atoms become their values. Builtin nodes become symbols of the same name (`'+` is the symbol `+`), except `T`/`F` (booleans) and `()` (lists).
-- **`(if c a b)`** evaluates `a` unless `c` is `F`, in which case it evaluates `b`. **`(if c a)`** returns `()` when `c` is `F`. Only the selected branch is evaluated.
-- **`(define name expr)`** is allowed at top level and at the start of a lambda body, before any expression. It returns the symbol `name`. When the value is a `lambda` written directly in the `define`, the closure takes `name` for printing and error messages (`#<lambda fact>`, `fact takes 1 argument, got 2`); binding it again later does not rename it. Scoping rules are below.
-- **`(lambda (p1 … pk) body…)`** creates a closure over the current environment. It takes a fixed number of parameters (no variadic lambdas), which must be distinct symbols. The body is zero or more `define`s followed by one or more expressions; the last expression's value is returned. Calling with the wrong number of arguments is an error.
-- **`(and x…)`** evaluates left to right and returns `F` at the first `F`; otherwise it returns the last value. `(and)` is `T`.
-- **`(or x…)`** evaluates left to right and returns the first value that is not `F`; otherwise `F`. `(or)` is `F`.
-- `and` and `or` are special forms, so they are not first-class.
-
-### Definitions and scope
-
-Definitions are sequential, like Scheme's `let*`: each `define` sees the definitions before it and itself, never the ones after it. So self-recursion works and mutual recursion does not.
-
-```lisp
-(lambda (x)
-  (define y (+ x 1))   ; sees x
-  (define z (+ y 1))   ; sees x, y
-  z)
-```
-
-- The environment is a chain of single, immutable bindings. Each `define` extends the chain; nothing is ever changed in place.
-- The new binding is visible inside its own `expr`, so `(define fact (lambda (n) … (fact …)))` works. Using it before it has a value, as in `(define x (+ x 1))`, is an error.
-- Any reference to a name defined later in the same scope is an unbound-symbol error, even from inside a lambda. That is what rules out mutual recursion.
-- The same rule applies at top level, so top-level functions cannot be mutually recursive either.
-- Defining a name twice in the same scope is an error (immutable bindings). As in Scheme, the `define`s at the start of a lambda body form their own scope inside the parameters' scope, so a `define` may shadow a parameter. A lambda parameter or an inner `define` may shadow an outer name.
-
-### Builtin functions
-
-- **Arithmetic.** `+` and `*` take 0+ args (`(+)` is 0, `(*)` is 1). `-` and `/` take 1+ (`(- x)` negates; `(/ x)` is `(/ 1 x)`). Int with int stays int; any float makes the result float. Integer `/` truncates toward zero. Division by zero is an error.
-- **Ordering.** `<` `>` `<=` `>=` take exactly two numbers (ints and floats mix).
-- **Equality.** `==` `!=` take any two values. Numbers compare numerically (`(== 1 1.0)` is `T`). Strings, symbols and booleans compare by value; pairs compare structurally. Comparing functions is an error.
-- **Boolean.** `not` takes one value of any type and returns T only for F.
-- **Strings.** `strlen` returns the number of code points as an integer. `strcat` takes 0+ strings and returns their concatenation (`(strcat)` is `""`). `str?` takes any value and returns `T` if it is a string, else `F`. Non-string arguments to `strlen` or `strcat` are errors.
-- **Lists.** `cons` takes any two values. `car` and `cdr` require a pair; `(car '())` is an error.
-
-### Program output and errors
-
-`government run` evaluates top-level forms in order and prints the value of each non-`define` form, one per line.
-
-A runtime error stops the program with exit code 1. Every error names its source location, which is an OID: `E-UNBOUND: no statute for symbol x at GOV.1.12.120 (depth 4)`. Ratification and decode errors use exit code 2.
-
-## Interpreter architecture
-
-The interpreter is a pure-Go module that needs Go 1.24 or later. The module root is `src/`, so the repository's top level holds only documents, `examples/`, `scripts/` and the Makefile, which runs every Go command in `src/`. The language packages use only the standard library: `crypto/x509` for parsing and signatures, with path and policy processing implemented here. The two commands add [cobra](https://github.com/spf13/cobra) for the CLI, and `govlisp`'s REPL adds [ergochat/readline](https://github.com/ergochat/readline).
-
-### Go facts verified locally (go1.24.7)
-
-- `x509.OID` and `x509.ParseOID` handle arcs beyond 64 bits, including the 128-bit `GOV` arc.
-- `Certificate.Policies` and `Certificate.PolicyMappings` are populated by `ParseCertificate`, and a critical policyMappings extension is not listed as unhandled.
-- **`CreateCertificate` does not emit `PolicyMappings` in 1.24.** It silently drops the field. The transpiler must DER-encode the extension itself and pass it through `ExtraExtensions`. A ~15-line hand encoder was enough in the prototype. The same is true of `policyConstraints`.
-- Ed25519 certificate signing is byte-for-byte deterministic.
-
-**Why not `x509.Verify`?** It builds its own paths (we need exactly the path in the file), it does not expose the policy tree, and it is built around system-root semantics. `CheckSignatureFrom` gives us signatures plus the parent's CA and keyCertSign checks.
-
-### Packages
-
-| Package | Responsibility |
-| --- | --- |
-| `cmd/government` | CLI |
-| `ratify` | PEM loading; path validation (§6.1.3 a–c, 6.1.4 k–n); critical-extension check |
-| `policy` | RFC 9618 policy graph; strict check; node budget |
-| `ast` | Graph to AST: skipping copies, ordering, OID decoding, structural errors |
-| `program` | The whole load path: ratify, policy graph, decode; maps runtime errors back to node OIDs |
-| `builtin` | The one table of builtins: name, OID code, kind and operand count, read by `ast` and `eval` |
-| `eval` | Values, environments, special forms, builtins, trampoline for tail calls |
-| `sexpr` | Lisp reader and printer, shared by the transpiler, decompiler and tests |
-| `lisp2gov` | Transpiler: s-expressions to `.gov` |
-| `gov2lisp` | Decompiler: AST back to Lisp text |
-
-### Ratification steps
-
-1. Parse every PEM block (an unreadable file is `E-MALFORMED`). Order the certs: the anchor is the only self-issued cert, every other cert's issuer must be the subject of exactly one cert in the file, and no two certs may share a parent (else `E-CHAIN`). The anchor must be self-signed. With `--anchor`, its public key must match the pinned one (else `E-FOREIGN`).
-2. For each cert at depth *i*: `CheckSignatureFrom(cert at depth i−1)` passes (else `E-TAMPERED`); the check time (`--at`, default now) is inside its validity (else `E-NOT-IN-FORCE` or `E-LAPSED`).
-3. Certs at depths 0..n−1 are CAs allowed to sign certs (basicConstraints CA:TRUE and keyCertSign); no cert but the anchor is self-issued, since that would change `policy_mapping` counting (else `E-CHAIN`).
-4. No unknown critical extensions; no `policyConstraints` or `inhibitAnyPolicy`, rejected in v1 to keep the counters trivial (else `E-CHAIN`).
-5. With `--crl`: verify each CRL and reject any path cert it revokes (`E-REPEALED`, `E-STALE-REPEALS`).
-6. Run policy processing with the inputs in "The policy tree as AST", then the strict check (else `E-POLICY`; a graph past the `--max-nodes` budget is `E-TOO-LARGE`).
-
-### CLI
-
-| Command | Does |
-| --- | --- |
-| `government run prog.gov` | Ratify, decode, evaluate, print results |
-| `government prog.gov` | Same as `government run prog.gov`, as with `python prog.py`. A command name always wins over a file of the same name, and an argument that is neither a file nor a `.gov` name is reported as an unknown command |
-| `government verify prog.gov` | Ratify and decode only; print the certificate of ratification; exit 0 if the program is lawful |
-| `government tree prog.gov` | Print the policy tree, with `GOV` abbreviated, payloads decoded and notes shown |
-| `government decompile prog.gov` | Print equivalent Lisp source, notes restored as comments |
-| `government compile prog.gov.lisp -o prog.gov` | Run the transpiler (`--key`, `--author`, `--seed`, `--not-before`, `--not-after`, `--name`, `--source`, `--no-comments`, `--no-share`) |
-| `government repeal prog.gov -o repeal.crl` | Write a CRL repealing the program (`--key` or `--seed`, `--reason`, `--at`, `--last-update`, `--next-update`; `--next-update` defaults to 9999-12-31, a permanent repeal) |
-
-Shared flags: `--at <RFC 3339 time or YYYY-MM-DD>`, `--anchor <cert or public key PEM>`, `--crl <file>` (repeatable), `--max-nodes <n>`.
-
-The CLI is built on [cobra](https://github.com/spf13/cobra), so flags follow GNU style: long flags take two dashes, `-o` is short for `--output`, flags may come before or after the file name, and `government <command> --help` lists a command's flags.
-
-GOVERNMENT's Lisp source files use the extension `.gov.lisp`. A second command, `govlisp`, runs Lisp source directly, with no certificates: `govlisp` alone is a REPL (multi-line forms, errors reported without ending the session; on a terminal, line editing and history via [ergochat/readline](https://github.com/ergochat/readline), kept in `~/.govlisp_history`, Tab completion of names in scope, and Ctrl-C to discard the form being typed), and `govlisp prog.gov.lisp` runs a file, printing each non-`define` value and reporting the first error at its source line and column.
-
-## Transpiler and test suite
-
-Every language test is a plain `.gov.lisp` file with expected results in comments; the runner transpiles it to `.gov` bytes and runs the full interpreter pipeline on them.
-
-### `lisp2gov` pipeline
-
-1. **Read** Lisp: integers, floats, strings (escapes `\"` `\\` `\n` `\t` `\u{…}`), symbols, `T`/`F`, `'x`, `;` comments (kept as notes), dotted pairs.
-2. **Classify**: reserved names go to ns 0, other symbols to ns 1, literals to ns 2–4. Expand `'x` to `(quote x)`. Attach each comment to its form.
-3. **Number** nodes in pre-order, starting at 1.
-4. **Share** (unless `--no-share`): merge identical lists at the same depth into one node with several parents, and renumber. See Shared subexpressions.
-5. **Layer**: compute n = max depth and each node's depth. No padding is written: `anyPolicy` makes the validator copy shallow leaves down.
-6. **Assign**: cert 1 lists the top-level nodes; certs 2..n list `anyPolicy`, plus any node that carries notes; each parent→child edge becomes a mapping in the parent's cert.
-7. **Sign**: take the author key (or the default seed), derive one Ed25519 key per depth, build the anchor and certs 1..n, and hand-encode certificatePolicies and policyMappings.
-8. **Emit** PEM, with the original source above the first block if `--source` is given.
-
-The same source and flags always give the same bytes.
-
-### Shared subexpressions
-
-RFC 5280's tree would have to duplicate a subexpression used in two places; RFC 9618's graph lets one node have several parents. So by default the compiler hash-conses: every subtree gets a number for its shape (node kinds, text and notes, recursively), and a list whose shape already appeared at the same depth becomes that earlier node, with one more parent. A shared node costs one mapping per parent, as before, but its own subtree is written once, so sharing never makes a program bigger. `(+ (* 1 E) (- E 0))` nested 20 deep is about a million nodes as a tree and 162 shared.
-
-Three rules keep the meaning intact:
-
-- **Only lists are shared.** An atom costs one mapping per parent either way, so sharing it saves nothing.
-- **Equal siblings stay apart.** A cert's policies are a set, so in `(+ (f) (f))` one shared `(f)` would lose an argument. The k-th of several equal siblings is shared only with other k-th copies.
-- **Argument order must survive.** Children sort by id in every parent, and two parents can disagree: `(a (g) (h))` and `(b (h) (g))` at one depth would need `(g)` both before and after `(h)`. Before sharing, the compiler checks that the node can follow its previous sibling without contradicting an order already required, and keeps a separate copy if not. Ids are then renumbered 1..N in an order every parent agrees with, ties going to the original pre-order id, so a program with nothing to share compiles to exactly the bytes it would without sharing.
-
-Notes are part of a subtree's shape, so no comment is lost. The decoder needs nothing new: `Unlayer` keeps a node with several parents as one node, and `FromTree` turns it into one value shared by several lists, so the program in memory is as small as the one in the certificates. Evaluation never mutates code, so it cannot tell the sharing apart from copies. A runtime error inside a shared node names that one node; the note `Locate` reports comes from the first parent that has one.
-
-### Test file format
-
-After a top-level form, `;=> value` asserts its printed value, and `;=! text` asserts an error whose message contains `text`. In test mode, an error ends only that form, so one file can hold many error cases.
-
-```lisp
-; src/internal/lisptest/testdata/scoping.gov.lisp  (lexical, not dynamic)
-(define x 1)
-(define f (lambda () x))
-(define g (lambda (x) (f)))
-(g 2)                 ;=> 1
-(define x 2)          ;=! immutable
-((lambda (x) (define y (+ x 1)) (define z (+ y 1)) z) 1)   ;=> 3
-((lambda () (define a (lambda () (b))) (define b (lambda () 1)) (a)))   ;=! unbound
-
-; src/internal/lisptest/testdata/truthiness.gov.lisp
-(and F (car '()))     ;=> F
-(or F 7)              ;=> 7
-(if 0 'true 'false)   ;=> true
-(if F 1)              ;=> ()
-(not 0)               ;=> F
-
-; src/internal/lisptest/testdata/strings.gov.lisp
-(strlen "héllo")        ;=> 5
-(strcat "gov" "ern" "ment")   ;=> "government"
-(str? "")             ;=> T
-(str? 'foo)           ;=> F
-```
-
-### Test categories
-
-| Category | Form | Checks |
-| --- | --- | --- |
-| Language | `src/internal/lisptest/testdata/*.gov.lisp`, listed by `lisptest.Files` | All semantics: arithmetic, comparisons, truthiness, `if`, `quote`, lists, `define`, closures, scoping, recursion, higher-order functions, strings and Unicode |
-| Shape stress | `src/stress_test.go`, generated | 200-deep nesting (201 certs), 1,000-argument calls, 1,000-element `quote`d lists, 1,000 top-level forms, all through the whole pipeline; `--max-nodes` exactly at and one below a program's graph size; a small file asking for a million-node graph, refused quickly. Shared subexpressions are in `src/lisp2gov/share_test.go` |
-| Round trip | Go test over every language test program | `gov2lisp(lisp2gov(src))` equals the normalized source, comments included |
-| Ratification | Go table test that mutates a valid chain | Flipped signature byte, reordered certs, dropped mapping, orphaned policy, mapping in cert n, `anyPolicy` missing from a cert 2..n or asserted in cert 1, a list node with no elements, unknown critical extension; each expects a specific error |
-| Civic | Go table test | Runs before, inside and after a `--not-before`/`--not-after` window; repeal of each depth; scheduled repeal; stale CRL; CRL signed by the wrong key; `--anchor` pin across a re-ratified version; notes over 200 characters; default-key warning |
-| Golden | `src/lisp2gov/testdata/golden.gov` and `golden.crl`, from `golden.gov.lisp` | Byte equality with every option fixed (seed, author, dates), so any change to the encoding fails, reported as the block and DER byte where it starts; the program uses every literal kind, a split note, a dotted pair and a shared node, and must also run. `go test ./lisp2gov -update`, run in `src/`, accepts a deliberate change |
-| External oracle (optional) | `src/lisp2gov/openssl_test.go`: `openssl verify -x509_strict -policy_check -explicit_policy -policy 2.5.29.32.0 -policy_print`, plus `-crl_check_all` with repeal CRLs | OpenSSL accepts every test program and example, shared and not, and reports the same top-level policies; it refuses each broken program (tampered, missing depth, foreign anchor, out of force) and each repealed one. Three known disagreements are pinned: scheduled repeals, a list issued after the check time, and OpenSSL's 1,000-node tree limit (see OpenSSL below). Skipped without OpenSSL; `$GOVERNMENT_OPENSSL` picks the binary, since macOS's `openssl` is LibreSSL. `make oracle` runs them with an OpenSSL built without its tree limit. Without `-policy 2.5.29.32.0` OpenSSL treats the acceptable set as empty |
-
-Ratification tests are Go rather than Lisp because a Lisp source cannot express a broken certificate.
-
-## Civic features
-
-Four X.509 features carry over into the language: effective dates, repeal by revocation, notes attached to clauses, and authorship. None of them changes evaluation; they decide whether a program may run, and what it says about itself.
-
-### Effective dates
-
-A program is in force only between its start and end dates.
-
-- `government compile --not-before 2027-01-01 --not-after 2027-12-31T00:00:00Z` sets `notBefore` and `notAfter` on every cert, named for the X.509 fields they fill. Each takes an RFC 3339 time or a date, meaning midnight UTC at its start. The defaults are 2000-01-01 and 9999-12-31 (no expiry).
-- The interpreter checks every cert's window at the check time (`--at`, default now). The program's window is the overlap of all of them.
-- Before the window: `E-NOT-IN-FORCE: takes effect 2027-01-01T00:00:00Z`. After it: `E-LAPSED: expired 2027-12-31T00:00:00Z`. Both exit with code 2.
-
-### Repeal (revocation)
-
-A signed certificate revocation list (CRL) can strike down a ratified program after it has shipped.
-
-- Revoking any cert of the chain breaks it, so revoking one cert repeals the whole program.
-- Per RFC 5280, a cert's revocation is published by its issuer. `government repeal` always revokes depth 1, so its CRL is signed by the anchor, with the author's own key: the author strikes down what they ratified.
-- `government repeal prog.gov --reason superseded -o repeal.crl` writes that CRL. It needs the program's signing key (see Authorship). The reason is any RFC 5280 CRLReason, e.g. `superseded` or `cessationOfOperation`.
-- The checker accepts a CRL from any cert of the chain, as RFC 5280 path validation does, so a hand-made CRL for depth *i*, signed by cert *i−1*, repeals the program too. Every CA cert therefore gets `cRLSign` as well as `keyCertSign`.
-- `government run --crl repeal.crl prog.gov` loads one or more CRL PEM blocks (the flag repeats; `verify`, `tree` and `decompile` take it too). For each CRL it checks that its issuer is a cert of this program (else `E-FOREIGN`), its signature (`RevocationList.CheckSignatureFrom`, else `E-TAMPERED`), and that the check time is not past `nextUpdate`. A check time before `thisUpdate` is allowed: each entry's revocation time already says when the repeal applies, so a newer list can still answer whether the program was in force at an earlier `--at`. OpenSSL disagrees: it refuses a list that is not yet valid.
-- A path cert listed with a revocation time at or before the check time fails: `E-REPEALED: depth 1 repealed 2027-03-01 (superseded)`.
-- A CRL past its `nextUpdate` is `E-STALE-REPEALS`. This is a deliberate GOVERNMENT rule: an outdated repeal list fails closed.
-- A future revocation time gives a scheduled repeal. RFC 5280 treats that field as when revocation occurred, so honoring a future time is a GOVERNMENT-specific reading, noted as such. OpenSSL ignores the time: a listed cert is revoked, so it refuses a scheduled repeal at once.
-- CRLs are always external files. A `.gov` file may still contain only certificates.
-
-### Notes
-
-Comments in the Lisp source travel inside the certs as notes on the clauses they describe, so a `.gov` file documents itself.
-
-- **Encoding.** Each policy entry may carry RFC 5280 user-notice qualifiers (`id-qt-unotice`, `1.3.6.1.5.5.7.2.2`) whose `explicitText` is a UTF8String. RFC 5280 caps `explicitText` at 200 characters, so a longer note is split across several qualifiers and joined back in order. A node below depth 1 is normally created through `anyPolicy` and would take its (empty) qualifiers, so a node with a note is also listed explicitly in its cert; the explicit entry wins, because RFC 9618 step d.1 runs before d.2, which skips policies already present.
-- **Attachment.** The transpiler attaches a `;` comment to the form it trails on the same line, or else to the next form that begins after it. Consecutive comments on one form are joined with line breaks. Every comment is a note: the test runner's `;=>` and `;=!` annotations are a convention of the test suite, not part of the language.
-- **Semantics.** Qualifiers do not affect policy processing or evaluation; RFC 5280 only carries them along.
-- **Opting out.** `government compile --no-comments` drops every comment, so the certs say nothing the code does not. Decompiling cannot bring them back. It cannot be combined with `--source`, whose copy of the source would keep them.
-- **Display.** `government tree` prints notes beside nodes. Errors print the note of the innermost noted node, e.g. `E-UNBOUND: no statute for symbol z … (note: "compute the total")`. `government decompile` restores notes as comments, so the round-trip test also covers comments.
-- **Go.** `x509.Certificate.Policies` holds OIDs only and has no qualifier support. The transpiler hand-encodes the whole certificatePolicies extension (as it already does for policyMappings), and the interpreter decodes qualifiers from the raw extension bytes.
-
-### Authorship
-
-A program is signed by its author's key, which records who ratified it and lets only that person amend or repeal it.
-
-- `government compile --key author.pem --author "Ada Lovelace <ada@example.com>"` takes an Ed25519 PKCS#8 key. The anchor is self-signed with it, with subject `CN=Ada Lovelace, O=<program>` and the email in subjectAltName.
-- The keys for certs 1..n are derived from the author key: seed for depth *i* = SHA-256(author seed ‖ "GOVERNMENT" ‖ i). Output stays byte-for-byte deterministic, and the key holder alone can rebuild the chain or sign repeals.
-- Any changed byte breaks a signature: `E-TAMPERED: clause at depth 2 fails signature check`. Amending a program means re-ratifying it.
-- `--anchor` pins a public key, not a whole cert. It accepts a cert or a public key PEM and compares SubjectPublicKeyInfo. A re-ratified program with new dates or text still matches its author's pin.
-- `government verify` prints a certificate of ratification: author, key fingerprint (SHA-256 of the SPKI), window in force, depth and node count.
-- Without `--key`, the default seed is public, so anyone can forge, amend or repeal. `verify` says so, naming the ratifier as `Public (Default Key)`.
-
-## Design decisions
-
-Every question raised in review is decided. The doc's sections above already reflect each decision.
-
-| Question | Decision | Affects |
-| --- | --- | --- |
-| What counts as true? | Scheme-style: only `F` is false | Semantics |
-| Number size? | 64 bits: int64 (overflow is an error) and float64 | Semantics |
-| What does a program output? | Value of every non-`define` top-level form | Semantics, tests |
-| Shared subexpressions? | Yes, by default (`--no-share` to keep copies); evaluated on the DAG without unfolding | Shared subexpressions |
-| `define` in lambda bodies? | Allowed at the start of the body; sequential, no mutual recursion | Semantics |
-| Who is trusted? | The file's own anchor (`--anchor` optional) | Source format |
-| Should programs expire? | Only when built with `--not-after` | Civic features |
-| Cert order in the file? | Written anchor first, top-down; read in any order | Source format |
-| OID root? | UUID arc under `2.25` | OID encoding |
-| v1 extras? | No variadic lambdas; `if` without else returns `()`; add `strlen`, `strcat`, `str?` | Semantics, builtin table |
-| Which X.509 extras? | Effective dates, repeal by CRL, notes, authorship | Civic features |
-| Padding? | Generated by the validator: certs 2..n assert `anyPolicy`, which copies unmapped leaves down. Verified against OpenSSL and Go | Policy tree, encoding |
-
-## Sources
-
-- [RFC 9618: Updates to X.509 Policy Validation](https://www.rfc-editor.org/rfc/rfc9618.html) (replaces the policy tree with a graph)
-- [Go `crypto/x509` documentation](https://pkg.go.dev/crypto/x509@go1.27.0)
-- [CVE-2026-32281: inefficient policy validation in Go crypto/x509](https://fieldguide.lutrasecurity.com/CVE-2026-32281)
-- RFC 5280 §6.1 (Certification Path Validation), as summarized via RFC 9618 and reference implementations
-- Local prototype against go1.24.7 (OID arcs, PolicyMappings marshaling, Ed25519 determinism)
diff --git a/SPEC.md b/SPEC.md
new file mode 100644
index 0000000000000000000000000000000000000000..63166ed9a54379dfac5eef5a19eb78e70a826893
--- /dev/null
+++ b/SPEC.md
@@ -0,0 +1,729 @@
+# GOVERNMENT Technical Specification
+
+This document specifies the GOVERNMENT file format and language as they are
+implemented. It gives what you need to write your own compiler: the source
+language, how source becomes a tree, how the tree becomes certificates, and the
+checks that the interpreter applies before it runs a program.
+
+Where this document says a thing "must" be true, the interpreter refuses a file
+in which it is not true. Where it describes "the reference compiler", it
+describes what `government compile` does in a place where a compiler has a free
+choice. A compiler that makes a different choice still makes valid programs.
+
+## Overview
+
+A program is a tree of expressions. Each node of the tree is one certificate
+policy OID. A `.gov` file holds a chain of X.509 certificates: a trust anchor,
+then one certificate for each depth of the tree. Certificate 1 lists the
+top-level forms as its policies. Each list node has a policy mapping to each of
+its elements, in the certificate at the list's depth.
+
+To run a program, the interpreter does these steps in order:
+
+1. **Load.** Read the PEM blocks as certificates.
+2. **Order.** Put the certificates in chain order, starting at the anchor.
+3. **Ratify.** Check signatures, CA constraints, extensions, validity dates and
+   CRLs.
+4. **Process policies.** Build the RFC 9618 valid policy graph from the chain.
+5. **Strict check.** Make sure that policy processing did not drop any part of
+   the program.
+6. **Decode.** Turn the graph into a tree of expressions.
+7. **Evaluate.** Evaluate the top-level forms in order.
+
+## Terms
+
+| Term      | Meaning                                                                                                                                               |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GovLisp   | The source language. Source files use the extension `.gov.lisp`.                                                                                      |
+| `GOV`     | The root OID arc, `2.25.9665536045854453410170579537759926404`.                                                                                       |
+| Node      | One expression of the program: a list or an atom. Each node has one OID.                                                                              |
+| List node | A node whose children are the elements of a non-empty list.                                                                                           |
+| Atom      | Any node that is not a list node.                                                                                                                     |
+| Depth     | A top-level form has depth 1. A list's elements have the list's depth plus 1. In the chain, the anchor has depth 0 and certificate *i* has depth *i*. |
+| *n*       | The depth of the deepest node. The chain has *n* certificates below the anchor.                                                                       |
+| Copy      | A node that the validator creates under an atom, with the atom's own OID, to carry the atom down to depth *n*. Decoding ignores copies.               |
+| Note      | A source comment, stored in a certificate as a user notice.                                                                                           |
+| Ratify    | Pass every check before evaluation. A program that ratifies is "lawful".                                                                              |
+| Repeal    | Revoke a program with a certificate revocation list (CRL).                                                                                            |
+
+## Source language
+
+GovLisp source is UTF-8 text. Invalid UTF-8 is a syntax error.
+
+### Tokens
+
+| Token      | Syntax                                                                                                   |
+| ---------- | -------------------------------------------------------------------------------------------------------- |
+| Whitespace | Any character for which Unicode `White_Space` is true. It separates tokens and is otherwise ignored.     |
+| `(` `)`    | List delimiters.                                                                                         |
+| `'`        | Quote. `'d` reads as `(quote d)`. A `'` must be followed by a datum.                                     |
+| String     | `"` to the next unescaped `"`. See Strings.                                                              |
+| Comment    | `;` to the end of the line.                                                                              |
+| Atom       | A run of characters up to the next delimiter. The delimiters are whitespace, `(`, `)`, `'`, `"` and `;`. |
+| Dot        | An atom that is exactly `.`. It is only valid inside a list.                                             |
+
+### Atoms
+
+The reader classifies each atom in this order:
+
+1. `T` is boolean true and `F` is boolean false.
+2. Text that matches `-?(0|[1-9][0-9]*)` is an integer. It must fit in a signed
+   64-bit integer.
+3. Text that matches `-?[0-9]+\.[0-9]+([eE][-+]?[0-9]+)?` is a float. It must be
+   finite as an IEEE 754 double. There must be digits on both sides of the dot.
+4. Any other text that matches `[-+]?\.?[0-9]` at its start is a malformed
+   number, which is a syntax error. So `+1`, `.5`, `1.` and `01` are errors.
+5. Everything else is a symbol. Symbols are case-sensitive.
+
+### Strings
+
+A string can hold any character except an unescaped `"` or `\`. It can span
+lines. These escapes are valid:
+
+| Escape  | Character                                                                                                       |
+| ------- | --------------------------------------------------------------------------------------------------------------- |
+| `\"`    | `"`                                                                                                             |
+| `\\`    | `\`                                                                                                             |
+| `\n`    | Line feed                                                                                                       |
+| `\t`    | Tab                                                                                                             |
+| `\u{X}` | The code point X, written as 1 to 6 hex digits. It must be a Unicode scalar value, so surrogates are not valid. |
+
+Any other escape is a syntax error.
+
+### Lists and dotted pairs
+
+`(a b c)` is a list. `()` is the empty list.
+
+`(a b . c)` is a dotted pair. A dotted list must have at least one datum before
+the `.`, exactly one datum after it, and only one `.`. If the datum after the
+`.` is a list, the result is one longer list: `(a . (b c))` reads as `(a b c)`,
+and `(a . ())` reads as `(a)`.
+
+### Comments and notes
+
+Each comment becomes a note on one datum. The note's text is the comment without
+its leading `;` characters, without one space after them, and without trailing
+spaces, tabs and carriage returns.
+
+The reader attaches each comment as follows:
+
+1. If one or more datums end on the comment's line before the comment, the
+   comment attaches to the one that ends last. If several end at that same
+   place, it attaches to the outermost.
+2. Otherwise, the comment attaches to the first datum, in pre-order, that starts
+   after the comment. This is the outermost datum that starts next.
+3. Otherwise, the comment is dropped.
+
+When several comments attach to one datum, their texts are joined in source
+order with a line feed between them.
+
+The reference compiler's `--no-comments` option drops every note.
+
+### Reserved names
+
+The names of the special forms and builtin functions are reserved: codes 10 and
+up in the builtin table (see OIDs). A reserved name cannot be defined or used as
+a lambda parameter. In source, a reserved name reads as a symbol, and the
+compiler gives it namespace 0.
+
+## The program tree
+
+The compiler turns each datum into one node:
+
+| Datum                               | Node                                                                           |
+| ----------------------------------- | ------------------------------------------------------------------------------ |
+| A non-empty list                    | A list node (builtin code 1). Its children are the list's elements, in order.  |
+| The empty list                      | The builtin constant `()` (code 5).                                            |
+| `T` and `F`                         | The builtin constants `T` (code 3) and `F` (code 4).                           |
+| A symbol with a reserved name       | The builtin with that name, in namespace 0.                                    |
+| Any other symbol                    | A symbol node, namespace 1.                                                    |
+| An integer                          | An integer node, namespace 2.                                                  |
+| A float                             | A float node, namespace 3.                                                     |
+| A string                            | A string node, namespace 4.                                                    |
+| `(a b . c)` where `c` is not a list | A list node with the children `a`, `b`, the dot builtin `.` (code 2), and `c`. |
+
+`'d` is the list `(quote d)`. It has no node of its own.
+
+A program must have at least one top-level form.
+
+### Node ids
+
+Every node has an id, a positive integer. In a program, the distinct nodes must
+have exactly the ids 1 to N, with no gaps and no repeats. The children of a
+node, and the top-level forms, are in ascending id order. So ids record argument
+order, which a set of policies cannot.
+
+The reference compiler gives ids in pre-order, starting at 1. In `(+ 1 (* 2 3))`
+the outer list is 1, `+` is 2, `1` is 3, the inner list is 4, `*` is 5, `2` is 6
+and `3` is 7.
+
+### Shared nodes
+
+One node can have more than one parent, because RFC 9618's policy graph allows
+this. Every parent of a shared node must be at the same depth. A shared node is
+one value in the decoded program, so a compiler can write a repeated
+subexpression once.
+
+Sharing must not change the program:
+
+- One node cannot be two children of the same parent, because a certificate's
+  policies are a set. In `(+ (f) (f))` the two `(f)` lists must stay two nodes.
+- The ids must give the correct order of children in every parent at once. If
+  `(a (g) (h))` and `(b (h) (g))` are at the same depth, `(g)` and `(h)` cannot
+  both be shared.
+
+The reference compiler shares by default, and `--no-share` turns sharing off. It
+shares only lists, never atoms. Two lists are equal if they have the same
+structure, the same atoms and the same notes. The k-th of several equal siblings
+is shared only with other k-th copies. Before it shares a list, the compiler
+checks that the order of children stays consistent, and keeps a separate list if
+it does not. Then it numbers the nodes 1 to N with a topological sort of the
+required orders, and breaks ties by pre-order id. So a program with nothing to
+share has the same ids, and the same bytes, with or without sharing.
+
+## OIDs
+
+Every node OID has the form:
+
+```
+GOV.<namespace>.<id>.<payload>
+```
+
+`GOV` is `2.25.9665536045854453410170579537759926404`, a UUID arc under `2.25`
+(ITU-T X.667). The UUID is `074583b8-3bb7-4179-8669-827877697884`. Tools print
+the prefix as `GOV`.
+
+### Namespaces
+
+| Namespace | Kind    | Payload                                             | Source | OID                    |
+| --------- | ------- | --------------------------------------------------- | ------ | ---------------------- |
+| 0         | Builtin | One arc: the builtin's code                         | `+`    | `GOV.0.7.21`           |
+| 1         | Symbol  | The name's code points, one arc each                | `foo`  | `GOV.1.8.102.111.111`  |
+| 2         | Integer | The decimal text's code points                      | `-42`  | `GOV.2.9.45.52.50`     |
+| 3         | Float   | The decimal text's code points                      | `3.14` | `GOV.3.10.51.46.49.52` |
+| 4         | String  | The string's code points, after escapes are decoded | `"hi"` | `GOV.4.11.104.105`     |
+
+Payload rules:
+
+- A code point arc must be a Unicode scalar value: 0 to 0x10FFFF, with no
+  surrogates.
+- A symbol payload must not be empty, must not be a builtin name, and must not
+  read as a number (rule 2, 3 or 4 of Atoms).
+- An integer payload must match the integer grammar and fit in 64 bits.
+- A float payload must match the float grammar and be finite.
+- A string payload can be empty. Then the OID ends with the id arc.
+
+The reference compiler writes integers in plain decimal, with no `-` on zero. It
+writes floats in the shortest form that reads back as the same double, always
+with a dot. Magnitudes below 1e-6 or at or above 1e21 use an exponent:
+`1.0e+21`, `1.5e-07`. The decoder accepts any text that matches the grammar.
+
+### Builtins
+
+Each builtin has a fixed code, which is its whole payload. A namespace 0 OID
+must have exactly one payload arc, and that arc must be a code in this table.
+
+| Code | Name     | Kind                          | Operands                              |
+| ---- | -------- | ----------------------------- | ------------------------------------- |
+| 1    | `(...)`  | Structure: list node          | At least 1 child                      |
+| 2    | `.`      | Structure: dotted pair marker |                                       |
+| 3    | `T`      | Constant                      |                                       |
+| 4    | `F`      | Constant                      |                                       |
+| 5    | `()`     | Constant                      |                                       |
+| 10   | `quote`  | Special form                  | 1                                     |
+| 11   | `if`     | Special form                  | 2 or 3                                |
+| 12   | `define` | Special form                  | 2                                     |
+| 13   | `lambda` | Special form                  | Parameters, then 1 or more body forms |
+| 14   | `and`    | Special form                  | 0 or more                             |
+| 15   | `or`     | Special form                  | 0 or more                             |
+| 20   | `not`    | Function                      | 1                                     |
+| 21   | `+`      | Function                      | 0 or more                             |
+| 22   | `-`      | Function                      | 1 or more                             |
+| 23   | `*`      | Function                      | 0 or more                             |
+| 24   | `/`      | Function                      | 1 or more                             |
+| 25   | `<`      | Function                      | 2                                     |
+| 26   | `>`      | Function                      | 2                                     |
+| 27   | `<=`     | Function                      | 2                                     |
+| 28   | `>=`     | Function                      | 2                                     |
+| 29   | `==`     | Function                      | 2                                     |
+| 30   | `!=`     | Function                      | 2                                     |
+| 31   | `cons`   | Function                      | 2                                     |
+| 32   | `car`    | Function                      | 1                                     |
+| 33   | `cdr`    | Function                      | 1                                     |
+| 34   | `strlen` | Function                      | 1                                     |
+| 35   | `strcat` | Function                      | 0 or more                             |
+| 36   | `str?`   | Function                      | 1                                     |
+
+## The `.gov` file
+
+A `.gov` file is text that holds PEM blocks.
+
+- Every block must be of type `CERTIFICATE`, with no PEM headers, and must parse
+  as a DER X.509 certificate.
+- Every line that starts with `-----BEGIN ` must start a block that can be read.
+- There must be at least 2 certificates: the anchor and certificate 1.
+- Text outside the blocks is ignored.
+- The certificates can be in any order. The reference compiler writes the anchor
+  first, then certificates 1 to *n*.
+
+With `--source`, the reference compiler writes the source above the first block.
+It indents every non-blank line by 4 spaces, keeps blank lines empty, and adds
+one blank line after the source. Because of the indent, no source line can start
+a PEM block.
+
+## Certificates
+
+### Profile
+
+All certificates are X.509 v3.
+
+| Field                       | Anchor (depth 0)                            | Certificate *i*, 1 ≤ *i* < *n*         | Certificate *n*                        |
+| --------------------------- | ------------------------------------------- | -------------------------------------- | -------------------------------------- |
+| Serial number               | 1                                           | *i*+1                                  | *n*+1                                  |
+| Issuer                      | Its own subject                             | Subject of certificate *i*−1           | Subject of certificate *n*−1           |
+| Subject                     | `CN=<author>, O=<program>`                  | `CN=GOVERNMENT Depth <i>, O=<program>` | `CN=GOVERNMENT Depth <n>, O=<program>` |
+| Signed by                   | Its own key                                 | The key of certificate *i*−1           | The key of certificate *n*−1           |
+| Validity                    | `notBefore` to `notAfter`                   | Same                                   | Same                                   |
+| basicConstraints (critical) | CA:TRUE                                     | CA:TRUE                                | CA:FALSE                               |
+| keyUsage (critical)         | keyCertSign, cRLSign                        | keyCertSign, cRLSign                   | digitalSignature                       |
+| subjectKeyIdentifier        | First 20 bytes of SHA-256 of the public key | Same                                   | Same                                   |
+| authorityKeyIdentifier      | Its own key identifier                      | The issuer's key identifier            | The issuer's key identifier            |
+| subjectAltName              | The author's email, if there is one         | Absent                                 | Absent                                 |
+| certificatePolicies         | Absent                                      | See Policies                           | See Policies                           |
+| policyMappings (critical)   | Absent                                      | See Mappings                           | Must be absent                         |
+
+If *n* is 1, certificate 1 is also certificate *n*: it is not a CA and has no
+mappings.
+
+Reference compiler values:
+
+- `<program>` is the `--name` option, or `program` by default.
+- `<author>` is the name from `--author`, or `GOVERNMENT Anchor` by default.
+  `--author` takes `Name <email>`, a name, or an email. With only an email, the
+  email is also the name.
+- The validity is the same on every certificate: `--not-before` and
+  `--not-after`, or 2000-01-01T00:00:00Z and 9999-12-31T23:59:59Z by default.
+  `notBefore` must be before `notAfter`.
+- The interpreter only needs each subject to be distinct. It does not read the
+  names.
+
+### Keys
+
+All signatures are Ed25519, and so are deterministic. One 32-byte seed makes
+every key:
+
+- The anchor's key is the Ed25519 key for the seed itself.
+- The key of certificate *i* is the Ed25519 key for SHA-256(seed ‖ `GOVERNMENT`
+  ‖ *i*), where `GOVERNMENT` is ASCII and *i* is the decimal digits of *i*, with
+  no separators.
+
+The seed comes from one of these:
+
+- `--key`: a PKCS#8 `PRIVATE KEY` PEM file for an Ed25519 key. The seed is that
+  key's seed.
+- `--seed`: 64 hex digits.
+- The default: SHA-256 of the ASCII text `GOVERNMENT`. This seed is public, so
+  anyone can make or repeal programs with it. `government verify` names this
+  ratifier as `Public (Default Key)`.
+
+The interpreter does not check how keys were made. It only checks the
+signatures.
+
+### Policies
+
+Each certificate lists the nodes at its depth as follows:
+
+- **Certificate 1** lists every node at depth 1, with that node's note if it has
+  one. It must not list `anyPolicy`.
+- **Certificates 2 to *n*** list `anyPolicy` (`2.5.29.32.0`), then each node at
+  that depth that has a note, with the note. They must list `anyPolicy`.
+
+Other nodes below depth 1 are not listed. The validator makes them from the
+mappings, because each certificate asserts `anyPolicy` (see Policy processing).
+A node that has a note is listed, because the listed entry gives the node its
+note.
+
+The extension is DER:
+
+```
+certificatePolicies ::= SEQUENCE OF PolicyInformation
+
+PolicyInformation ::= SEQUENCE {
+    policyIdentifier   OBJECT IDENTIFIER,
+    policyQualifiers   SEQUENCE OF PolicyQualifierInfo OPTIONAL }
+
+PolicyQualifierInfo ::= SEQUENCE {
+    policyQualifierId  OBJECT IDENTIFIER,  -- id-qt-unotice, 1.3.6.1.5.5.7.2.2
+    qualifier          UserNotice }
+
+UserNotice ::= SEQUENCE {
+    explicitText       UTF8String }
+```
+
+A node without a note has no `policyQualifiers`. RFC 5280 limits `explicitText`
+to 200 characters, so the reference compiler splits a longer note into chunks of
+200 code points, one qualifier per chunk, in order. The reference compiler does
+not mark the extension critical.
+
+To read a note, the interpreter joins, in order, the `explicitText` of every
+`id-qt-unotice` qualifier on the entry. It accepts UTF8String, IA5String,
+VisibleString and BMPString. It ignores `noticeRef` and other qualifiers.
+
+The reference compiler lists nodes in ascending id order. The interpreter does
+not care about the order.
+
+### Mappings
+
+Each edge from a list node at depth *i* to one of its children is one mapping in
+certificate *i*:
+
+```
+policyMappings ::= SEQUENCE OF SEQUENCE {
+    issuerDomainPolicy   OBJECT IDENTIFIER,  -- the list node
+    subjectDomainPolicy  OBJECT IDENTIFIER } -- the child
+```
+
+The reference compiler marks the extension critical, as RFC 5280 recommends.
+Neither side may be `anyPolicy`. Certificate *n* must not have mappings, because
+RFC 5280 never processes them. A certificate with no edges has no policyMappings
+extension.
+
+The reference compiler sorts mappings by the parent's id, then the child's id.
+
+### Size
+
+The certificates hold one policy entry for each top-level form and each node
+that has a note, and one mapping for each edge. A shared node costs one mapping
+for each parent, but its own subtree is written once.
+
+## Ratification
+
+The interpreter checks a file in this order. The first failure stops the program
+with exit code 2.
+
+1. **Load** the file as in The `.gov` file. Failure: `E-MALFORMED`.
+2. **Order** the certificates. Exactly one certificate must be self-issued: its
+   issuer name equals its subject name. That is the anchor. No two certificates
+   may have the same subject, and no two may have the same issuer. Starting at
+   the anchor, each next certificate is the one whose issuer is the current
+   subject. Every certificate must be on that path. Failure: `E-CHAIN`.
+3. **Pin.** With `--anchor`, the anchor's SubjectPublicKeyInfo must equal the
+   pinned one. `--anchor` takes a `PUBLIC KEY` PEM, a certificate, or a `.gov`
+   file, whose anchor is used. Failure: `E-FOREIGN`.
+4. **Signatures.** The anchor must verify with its own key, and each other
+   certificate with its issuer's key. The issuer must have basicConstraints
+   CA:TRUE and, if it has keyUsage, keyCertSign. Failure: `E-TAMPERED` for a bad
+   signature, `E-CHAIN` for a CA constraint.
+5. **Extensions.** No certificate may have an unknown critical extension, a
+   policyConstraints extension or an inhibitAnyPolicy extension, critical or
+   not. Failure: `E-CHAIN`.
+6. **Validity.** The program is in force from the latest `notBefore` to the
+   earliest `notAfter` of all the certificates, the anchor included. The check
+   time (`--at`, default now) must be in that window. Failure: `E-NOT-IN-FORCE`
+   before it, `E-LAPSED` after it or if the window is empty.
+7. **Repeals.** Each CRL from `--crl` is checked. See Repeal.
+8. **Policies.** Policy processing and the strict check must pass. Failure:
+   `E-POLICY`, or `E-TOO-LARGE` for a graph over the node budget.
+9. **Decode.** The graph must decode to a tree. Failure: `E-DECODE`.
+
+## Policy processing
+
+The interpreter runs RFC 5280 section 6.1 policy processing in the graph form of
+RFC 9618, on the path of certificates 1 to *n*. The anchor is the trust anchor,
+not part of the path. The inputs are fixed:
+
+| Input                          | Value         |
+| ------------------------------ | ------------- |
+| user-initial-policy-set        | {`anyPolicy`} |
+| initial-explicit-policy        | true          |
+| initial-policy-mapping-inhibit | false         |
+| initial-any-policy-inhibit     | false         |
+
+Because policyConstraints and inhibitAnyPolicy are refused, the RFC's three
+counters never reach 0, so they have no effect.
+
+The graph starts with one root node, `anyPolicy`, at depth 0, which expects
+{`anyPolicy`}. For each certificate *i*, from 1 to *n*:
+
+1. If the certificate has no certificatePolicies extension, processing fails.
+2. For each policy P in the certificate that is not `anyPolicy` (RFC 9618 step
+   d.1): make a node P at depth *i* under every depth *i*−1 node that expects P.
+   If no node expects P, make it under each `anyPolicy` node at depth *i*−1. If
+   there is none, drop P. A listed node gets the note from its entry.
+3. If the certificate lists `anyPolicy` (step d.2): for each policy that some
+   depth *i*−1 node expects and that has no node at depth *i* yet, make that
+   node, under every node that expects it.
+4. Prune: delete every node above depth *i* that has no children, until there
+   are none.
+5. If depth *i* has no nodes, processing fails.
+6. If *i* < *n*, apply the certificate's mappings: each node at depth *i* whose
+   policy is an issuerDomainPolicy now expects the set of subjectDomainPolicy
+   values mapped from it. A node with no mappings expects only its own policy. A
+   mapping with `anyPolicy` on either side fails processing.
+
+Each node expects either its mapped children or itself, so step 3 makes both the
+children of each list node and the copy of each atom. An atom at depth *d* gets
+a copy at each depth from *d*+1 to *n*, so pruning keeps it. A list node expects
+only its children, so it gets no copy.
+
+Policy processing failures are `E-POLICY`.
+
+### Node budget
+
+The graph may make at most `--max-nodes` nodes, 1,000,000 by default. Copies
+count. The root does not. The interpreter checks the budget each time it makes a
+node, so a small file cannot make it do a large amount of work. Past the budget:
+`E-TOO-LARGE`.
+
+## Strict check
+
+Plain policy processing drops a policy or a mapping that does not fit, without
+an error. The strict check makes each of those cases an error, `E-POLICY`:
+
+- Certificate 1 must not list `anyPolicy`. Certificates 2 to *n* must list it.
+- Certificate *n* must not have mappings.
+- Each policy that certificate *i* lists, other than `anyPolicy`, must be a node
+  at depth *i* in the final graph.
+- Each mapping in certificate *i*, for *i* < *n*, must be an edge in the final
+  graph: its issuerDomainPolicy must be a node at depth *i*, with a child that
+  is its subjectDomainPolicy.
+- Every node OID must be under `GOV` and must decode as in OIDs.
+- Two different OIDs must not have the same id. A copy has its atom's OID, so it
+  does not count.
+- The ids must be exactly 1 to N, where N is the largest id. A gap means that a
+  subtree was lost.
+
+## Decoding
+
+The interpreter turns the graph into a tree:
+
+1. The root's children, in id order, are the top-level forms. A top-level `.` is
+   an error.
+2. A child with the same OID as its parent is a copy. The decoder skips it. A
+   copy may only have copies below it.
+3. A list node's other children, in id order, are its elements. It must have at
+   least one.
+4. An atom must have no children other than its copy.
+5. `.` may only be the second-to-last element of a list with at least 3
+   elements. `(a . b)` decodes as a pair with car `a` and cdr `b`. If `b` is a
+   list, the result is the longer list, as in the reader.
+6. A node with several parents stays one node, and is one shared value in the
+   decoded program.
+
+A failure is `E-DECODE`, and names the OID and depth.
+
+## Worked example
+
+The program `(+ 1 (* 2 3))` has depth 3, so its file holds the anchor and 3
+certificates.
+
+| Certificate | certificatePolicies | policyMappings                                                                     |
+| ----------- | ------------------- | ---------------------------------------------------------------------------------- |
+| 1           | `GOV.0.1.1`         | `GOV.0.1.1` → `GOV.0.2.21`, `GOV.0.1.1` → `GOV.2.3.49`, `GOV.0.1.1` → `GOV.0.4.1`  |
+| 2           | `anyPolicy`         | `GOV.0.4.1` → `GOV.0.5.23`, `GOV.0.4.1` → `GOV.2.6.50`, `GOV.0.4.1` → `GOV.2.7.51` |
+| 3           | `anyPolicy`         | None                                                                               |
+
+Policy processing makes this graph. A `'` marks a copy:
+
+```
+depth 0  anyPolicy
+depth 1  `-- (...)#1       GOV.0.1.1
+depth 2      |-- +#2       GOV.0.2.21
+depth 3      |   `-- +#2'  copy
+depth 2      |-- 1#3       GOV.2.3.49
+depth 3      |   `-- 1#3'  copy
+depth 2      `-- (...)#4   GOV.0.4.1
+depth 3          |-- *#5   GOV.0.5.23
+depth 3          |-- 2#6   GOV.2.6.50
+depth 3          `-- 3#7   GOV.2.7.51
+```
+
+Certificate 1's policy attaches to the root. In certificate 2, `anyPolicy` makes
+the three nodes that #1 expects. In certificate 3, it makes the three nodes that
+#4 expects, and copies `+` and `1`, which expect only themselves. Nothing is
+pruned. Decoding skips the copies and gives `(+ 1 (* 2 3))`, which evaluates to
+`7`.
+
+## Repeal
+
+A repeal is an X.509 v2 CRL in a PEM block of type `X509 CRL`. CRLs are always
+separate files, given with `--crl`, which can be repeated. A CRL file can hold
+several blocks.
+
+The interpreter checks each CRL as follows:
+
+1. Its issuer name must be the subject of a certificate in the program. Failure:
+   `E-FOREIGN`.
+2. Its signature must verify with that certificate's key. Failure: `E-TAMPERED`.
+3. The check time must not be after its nextUpdate. Failure: `E-STALE-REPEALS`.
+4. If the issuer is at depth *d* < *n*, look for an entry with the serial number
+   of certificate *d*+1. If its revocation time is at or before the check time,
+   the program is repealed. Failure: `E-REPEALED`.
+
+Notes on these rules:
+
+- The interpreter does not compare the check time with thisUpdate. A newer CRL
+  can still answer whether a program was in force at an earlier time.
+- A revocation time after the check time is a scheduled repeal: the program runs
+  until that time. RFC 5280 does not give a future revocation time this meaning,
+  and OpenSSL does not.
+- A CRL from certificate *n* is checked, but it cannot revoke anything.
+
+The reference compiler's `government repeal` always revokes certificate 1, with
+a CRL signed by the anchor's key. The seed must make the anchor's public key.
+The CRL holds:
+
+| Field                  | Value                                                                       |
+| ---------------------- | --------------------------------------------------------------------------- |
+| thisUpdate             | `--last-update`, default now                                                |
+| nextUpdate             | `--next-update`, default 9999-12-31T23:59:59Z. It must be after thisUpdate. |
+| cRLNumber              | thisUpdate as Unix seconds                                                  |
+| authorityKeyIdentifier | The anchor's key identifier                                                 |
+| Entry                  | Serial number 2, revocation time `--at` (default now), reason `--reason`    |
+
+The reasons are the RFC 5280 CRLReason names: `unspecified`, `keyCompromise`,
+`cACompromise`, `affiliationChanged`, `superseded`, `cessationOfOperation`,
+`certificateHold`, `removeFromCRL`, `privilegeWithdrawn` and `aACompromise`.
+
+## Language semantics
+
+GovLisp is a strict, lexically scoped Lisp-1. All values are immutable.
+
+### Values
+
+| Type       | Range                             | Printed as                                         |
+| ---------- | --------------------------------- | -------------------------------------------------- |
+| Integer    | Signed 64 bits                    | `-42`                                              |
+| Float      | IEEE 754 double, always finite    | `3.25`, `1.0`, `1.0e+21`, as in OIDs               |
+| String     | A sequence of Unicode code points | `"a\"b"`, with `"`, `\`, line feed and tab escaped |
+| Boolean    | `T` or `F`                        | `T`, `F`                                           |
+| Symbol     | A name                            | `foo`                                              |
+| Pair       | A car and a cdr                   | `(1 2 3)`, `(1 . 2)`                               |
+| Empty list | One value                         | `()`                                               |
+| Function   | A closure or a builtin function   | `#<lambda sq>`, `#<lambda>`, `#<builtin +>`        |
+
+A list is a chain of pairs that ends in `()`. Only `F` is false. Every other
+value is true, including `0`, `0.0`, `""` and `()`.
+
+### Evaluation
+
+- Integers, floats, strings, `T`, `F` and `()` evaluate to themselves.
+- A symbol evaluates to its binding in the current scope. An unbound symbol is
+  `E-UNBOUND`.
+- A builtin function name evaluates to that function, so `(define add +)` works.
+- A special form name in any place other than the head of a list is
+  `E-SPECIAL-FORM`.
+- A list whose head is a special form follows the rule for that form. An
+  improper list is `E-SYNTAX`.
+- In any other list, the head and then the arguments are evaluated from left to
+  right, and the head's value is called. If it is not a function:
+  `E-NOT-A-FUNCTION`.
+- A call in tail position uses no extra stack. The tail positions are the last
+  expression of a lambda body, the branches of `if`, and the last operand of
+  `and` and `or`.
+
+### Special forms
+
+The wrong number of operands is `E-SYNTAX`.
+
+- `(quote d)` returns `d` without evaluating it. A builtin node becomes the
+  symbol with that name, so `'+` is the symbol `+`. `T`, `F` and `()` stay
+  constants.
+- `(if c a b)` evaluates `c`. If it is not `F`, it evaluates `a`, otherwise `b`.
+  `(if c a)` gives `()` when `c` is `F`.
+- `(define name expr)` binds `name` to the value of `expr` and returns the
+  symbol `name`. `name` must be a symbol that is not reserved. If `expr` is a
+  `lambda` written directly in the `define`, the closure takes `name` for
+  printing and errors.
+- `(lambda (p1 … pk) body…)` makes a closure over the current scope. The
+  parameters must be distinct symbols that are not reserved. `(lambda () …)`
+  takes none. The body is zero or more `define` forms, then one or more
+  expressions. The value of the last expression is the result. A call with a
+  different number of arguments than parameters is `E-ARITY`.
+- `(and x…)` evaluates from left to right and returns `F` at the first `F`.
+  Otherwise it returns the last value. `(and)` is `T`.
+- `(or x…)` evaluates from left to right and returns the first value that is not
+  `F`. Otherwise it returns `F`. `(or)` is `F`.
+
+### Definitions and scope
+
+- `define` is valid at the top level and at the start of a lambda body. Anywhere
+  else it is `E-SYNTAX`.
+- Definitions are sequential. Each `define` sees the definitions before it and
+  itself, and never the ones after it, even from inside a lambda. So a function
+  can call itself, but two functions cannot call each other.
+- A name used inside its own definition before the definition has a value, as in
+  `(define x (+ x 1))`, is `E-UNBOUND`.
+- A name can be defined only once in a scope. A second `define` is
+  `E-IMMUTABLE`.
+- The `define` forms at the start of a lambda body make a new scope inside the
+  parameters' scope. So they can shadow a parameter. A parameter or an inner
+  `define` can shadow an outer name.
+
+### Builtin functions
+
+A wrong number of arguments is `E-ARITY`. An argument of the wrong type is
+`E-TYPE`.
+
+| Function          | Result                                                                                              |
+| ----------------- | --------------------------------------------------------------------------------------------------- |
+| `+` `*`           | The sum or product. `(+)` is 0 and `(*)` is 1.                                                      |
+| `-` `/`           | The first argument minus, or divided by, each later one. `(- x)` is `-x`, and `(/ x)` is `(/ 1 x)`. |
+| `<` `>` `<=` `>=` | Compare two numbers.                                                                                |
+| `==` `!=`         | Compare any two values.                                                                             |
+| `not`             | `T` if the argument is `F`, otherwise `F`.                                                          |
+| `cons`            | A new pair of the two arguments.                                                                    |
+| `car` `cdr`       | The car or cdr of a pair. Any other argument, `()` included, is `E-TYPE`.                           |
+| `strlen`          | The number of code points in a string.                                                              |
+| `strcat`          | The strings joined in order. `(strcat)` is `""`.                                                    |
+| `str?`            | `T` if the argument is a string, otherwise `F`.                                                     |
+
+Arithmetic goes from left to right, one argument at a time. Two integers give an
+integer. If either is a float, the result is a float. Integer `/` truncates
+toward zero. Integer overflow, division by zero, and a float result that is not
+finite are `E-ARITH`.
+
+Comparisons can mix integers and floats, and compare them exactly. For `==` and
+`!=`, numbers compare by value, so `(== 1 1.0)` is `T`. Pairs compare by
+structure. Other values are equal only if they have the same type and value. A
+function in either argument is `E-TYPE`.
+
+### Output and errors
+
+The interpreter evaluates the top-level forms in order. It prints the value of
+each form that is not a `define`, one per line.
+
+A runtime error stops the program with exit code 1. The message gives the error
+code, the OID and depth of the node that failed, and the nearest note. For a
+shared node, the note comes from the first parent that has one.
+
+| Runtime error      | Cause                                                                |
+| ------------------ | -------------------------------------------------------------------- |
+| `E-UNBOUND`        | A symbol is not bound, or is used before its definition is complete. |
+| `E-SYNTAX`         | A special form or a call is malformed.                               |
+| `E-SPECIAL-FORM`   | A special form's name is used as a value.                            |
+| `E-NOT-A-FUNCTION` | The head of a call is not a function.                                |
+| `E-ARITY`          | A call has the wrong number of arguments.                            |
+| `E-TYPE`           | An argument has the wrong type.                                      |
+| `E-ARITH`          | Overflow, division by zero, or a float result that is not finite.    |
+| `E-IMMUTABLE`      | A name is defined twice in the same scope.                           |
+
+## Determinism
+
+The reference compiler gives the same `.gov` bytes for the same source and
+options. It does this with Ed25519, which signs deterministically, keys derived
+from one seed, fixed default dates and serial numbers, and a fixed order of ids,
+policies and mappings. A compiler that fixes all of these gets the same result.
+
+A repeal CRL is deterministic only when `--at` and `--last-update` are given,
+because both default to now.
+
+## References
+
+- [RFC 5280](https://www.rfc-editor.org/rfc/rfc5280.html), section 6.1:
+  certification path validation and policy processing.
+- [RFC 9618](https://www.rfc-editor.org/rfc/rfc9618.html): the policy graph that
+  replaces RFC 5280's policy tree.
+- [RFC 8410](https://www.rfc-editor.org/rfc/rfc8410.html): Ed25519 in X.509.
+- [ITU-T X.667](https://www.itu.int/rec/T-REC-X.667): UUID-based OIDs under
+  `2.25`.