parent:
d7a5838ae78830c0ba1161fee24dacb9d87725d7
nmyk <nick@nmyk.io>
2026-11-14T15:03:55-05:00
add OID <-> govlisp symbol mapping
diff --git a/ast/builtin.go b/ast/builtin.go
new file mode 100644
index 0000000000000000000000000000000000000000..a74bd00b1e9a2c10574be15f86d8b78e02726539
--- /dev/null
+++ b/ast/builtin.go
@@ -0,0 +1,70 @@
+package ast
+
+// Names for the builtins that have no source spelling as a symbol. The
+// reader turns "()", "T" and "F" into values and handles "." itself, so none
+// of these can collide with a user symbol.
+const (
+ ListNode = "(...)"
+ Dot = "."
+ True = "T"
+ False = "F"
+ Empty = "()"
+)
+
+// builtinCodes is the table from DESIGN.md. A code is permanent once
+// published: changing one would change the meaning of every .gov file
+// already compiled, so new builtins only ever take a free code.
+var builtinCodes = []struct {
+ code uint64
+ name string
+}{
+ {1, ListNode},
+ {2, Dot},
+ {3, True},
+ {4, False},
+ {5, Empty},
+
+ {10, "quote"},
+ {11, "if"},
+ {12, "define"},
+ {13, "lambda"},
+ {14, "and"},
+ {15, "or"},
+
+ {20, "not"},
+ {21, "+"},
+ {22, "-"},
+ {23, "*"},
+ {24, "/"},
+ {25, "<"},
+ {26, ">"},
+ {27, "<="},
+ {28, ">="},
+ {29, "=="},
+ {30, "!="},
+ {31, "cons"},
+ {32, "car"},
+ {33, "cdr"},
+ {34, "strlen"},
+ {35, "strcat"},
+ {36, "str?"},
+}
+
+var (
+ codeByName = map[string]uint64{}
+ nameByCode = map[uint64]string{}
+)
+
+func init() {
+ for _, b := range builtinCodes {
+ codeByName[b.name] = b.code
+ nameByCode[b.code] = b.name
+ }
+}
+
+// IsBuiltin reports whether name is in namespace 0. A symbol with this name
+// is always encoded as the builtin, which is why programs cannot rebind one.
+func IsBuiltin(name string) bool {
+ _, ok := codeByName[name]
+ return ok
+}
diff --git a/ast/doc.go b/ast/doc.go
new file mode 100644
index 0000000000000000000000000000000000000000..355f97fde82a877865d7d881a56493ffecefcdda
--- /dev/null
+++ b/ast/doc.go
@@ -0,0 +1,4 @@
+// Package ast is the program tree that certificates carry: how each node is
+// named by an OID, how a tree is numbered, and how it is cut into one layer
+// per certificate.
+package ast
diff --git a/ast/oid.go b/ast/oid.go
new file mode 100644
index 0000000000000000000000000000000000000000..9d5c42c9a38beb932e9e94be5b79ba8d92d7477d
--- /dev/null
+++ b/ast/oid.go
@@ -0,0 +1,221 @@
+package ast
+
+import (
+ "crypto/x509"
+ "errors"
+ "fmt"
+ "strings"
+ "unicode/utf8"
+
+ "government/sexpr"
+)
+
+// Root is the arc every node OID starts with.
+const Root = "2.25.9665536045854453410170579537759926404"
+
+// Namespace is an OID's first arc after Root. It says how to read the
+// payload, so the same text can be a symbol, a number or a string.
+type Namespace uint64
+
+const (
+ NSBuiltin Namespace = iota
+ NSSymbol
+ NSInt
+ NSFloat
+ NSString
+)
+
+var nsNames = []string{"builtin", "symbol", "integer", "float", "string"}
+
+func (ns Namespace) String() string {
+ if ns < Namespace(len(nsNames)) {
+ return nsNames[ns]
+ }
+ return fmt.Sprintf("namespace %d", uint64(ns))
+}
+
+// rootBytes is Root in DER. Encoding appends arcs to it and decoding strips
+// it, working on bytes because x509.OID has no way to read its arcs back
+// and Root is too large for OIDFromInts.
+var rootBytes = func() []byte {
+ oid, err := x509.ParseOID(Root)
+ if err != nil {
+ panic(err)
+ }
+ b, err := oid.MarshalBinary()
+ if err != nil {
+ panic(err)
+ }
+ return b
+}()
+
+// EncodeOID builds the OID Root.ns.id.payload. For a builtin, text is its
+// name and the payload is its code; otherwise the payload is text's code
+// points.
+func EncodeOID(ns Namespace, id uint64, text string) (x509.OID, error) {
+ if id == 0 {
+ return x509.OID{}, errors.New("node id must be positive")
+ }
+ var payload []uint64
+ if ns == NSBuiltin {
+ code, ok := codeByName[text]
+ if !ok {
+ return x509.OID{}, fmt.Errorf("%q is not a builtin", text)
+ }
+ payload = []uint64{code}
+ } else {
+ if !utf8.ValidString(text) {
+ return x509.OID{}, fmt.Errorf("%s %q is not valid UTF-8", ns, text)
+ }
+ if err := checkPayload(ns, text); err != nil {
+ return x509.OID{}, err
+ }
+ for _, r := range text {
+ payload = append(payload, uint64(r))
+ }
+ }
+
+ b := append([]byte{}, rootBytes...)
+ b = appendArc(b, uint64(ns))
+ b = appendArc(b, id)
+ for _, arc := range payload {
+ b = appendArc(b, arc)
+ }
+ var oid x509.OID
+ if err := oid.UnmarshalBinary(b); err != nil {
+ return x509.OID{}, err
+ }
+ return oid, nil
+}
+
+// DecodeOID is EncodeOID's inverse. Its input comes from an untrusted
+// certificate, so every rule EncodeOID follows is checked again here.
+func DecodeOID(oid x509.OID) (ns Namespace, id uint64, text string, err error) {
+ b, err := oid.MarshalBinary()
+ if err != nil {
+ return 0, 0, "", err
+ }
+ // An arc's last byte is below 0x80, so a byte prefix match ends on an
+ // arc boundary.
+ rest, ok := strings.CutPrefix(string(b), string(rootBytes))
+ if !ok {
+ return 0, 0, "", fmt.Errorf("OID %s is not under %s", oid, Root)
+ }
+ arcs, err := readArcs([]byte(rest))
+ if err != nil {
+ return 0, 0, "", fmt.Errorf("OID %s: %w", oid, err)
+ }
+ if len(arcs) < 2 {
+ return 0, 0, "", fmt.Errorf("OID %s has no node id", oid)
+ }
+ ns, id, payload := Namespace(arcs[0]), arcs[1], arcs[2:]
+ if ns > NSString {
+ return 0, 0, "", fmt.Errorf("OID %s: unknown %s", oid, ns)
+ }
+ if id == 0 {
+ return 0, 0, "", fmt.Errorf("OID %s: node id must be positive", oid)
+ }
+
+ if ns == NSBuiltin {
+ if len(payload) != 1 {
+ return 0, 0, "", fmt.Errorf("OID %s: a builtin has exactly one payload arc, got %d", oid, len(payload))
+ }
+ name, ok := nameByCode[payload[0]]
+ if !ok {
+ return 0, 0, "", fmt.Errorf("OID %s: unknown builtin code %d", oid, payload[0])
+ }
+ return ns, id, name, nil
+ }
+
+ var sb strings.Builder
+ for _, arc := range payload {
+ // ValidRune rejects both surrogates and values past U+10FFFF.
+ if arc > utf8.MaxRune || !utf8.ValidRune(rune(arc)) {
+ return 0, 0, "", fmt.Errorf("OID %s: arc %d is not a Unicode code point", oid, arc)
+ }
+ sb.WriteRune(rune(arc))
+ }
+ text = sb.String()
+ if err := checkPayload(ns, text); err != nil {
+ return 0, 0, "", fmt.Errorf("OID %s: %w", oid, err)
+ }
+ return ns, id, text, nil
+}
+
+// checkPayload applies the reader's grammar, so a text decodes as a symbol
+// or number exactly when the same text in source would read as one.
+func checkPayload(ns Namespace, text string) error {
+ switch ns {
+ case NSSymbol:
+ if text == "" {
+ return errors.New("empty symbol")
+ }
+ if IsBuiltin(text) {
+ return fmt.Errorf("symbol %q is a builtin name", text)
+ }
+ if _, isNumber, _ := sexpr.ParseNumber(text); isNumber {
+ return fmt.Errorf("symbol %q reads as a number", text)
+ }
+ case NSInt:
+ v, _, err := sexpr.ParseNumber(text)
+ if err != nil {
+ return err
+ }
+ if _, ok := v.(sexpr.Int); !ok {
+ return fmt.Errorf("%q is not an integer", text)
+ }
+ case NSFloat:
+ v, _, err := sexpr.ParseNumber(text)
+ if err != nil {
+ return err
+ }
+ if _, ok := v.(sexpr.Float); !ok {
+ return fmt.Errorf("%q is not a float", text)
+ }
+ case NSString:
+ default:
+ return fmt.Errorf("unknown %s", ns)
+ }
+ return nil
+}
+
+// appendArc writes arc in base 128, high digits first, with the top bit set
+// on every byte but the last. This is how DER encodes each OID arc.
+func appendArc(b []byte, arc uint64) []byte {
+ var digits [10]byte
+ i := len(digits)
+ for {
+ i--
+ digits[i] = byte(arc & 0x7f)
+ arc >>= 7
+ if arc == 0 {
+ break
+ }
+ }
+ for j := i; j < len(digits)-1; j++ {
+ digits[j] |= 0x80
+ }
+ return append(b, digits[i:]...)
+}
+
+func readArcs(b []byte) ([]uint64, error) {
+ var arcs []uint64
+ for len(b) > 0 {
+ var arc uint64
+ for i := 0; ; i++ {
+ if i == len(b) {
+ return nil, errors.New("truncated arc")
+ }
+ if arc > (1<<64-1)>>7 {
+ return nil, errors.New("arc does not fit in 64 bits")
+ }
+ arc = arc<<7 | uint64(b[i]&0x7f)
+ if b[i]&0x80 == 0 {
+ b = b[i+1:]
+ break
+ }
+ }
+ arcs = append(arcs, arc)
+ }
+ return arcs, nil
+}
diff --git a/ast/oid_test.go b/ast/oid_test.go
new file mode 100644
index 0000000000000000000000000000000000000000..acedb1f6119fe2ea245c4d7298c26e1cb639f489
--- /dev/null
+++ b/ast/oid_test.go
@@ -0,0 +1,140 @@
+package ast
+
+import (
+ "crypto/x509"
+ "strings"
+ "testing"
+)
+
+func gov(s string) string { return strings.Replace(s, "GOV", Root, 1) }
+
+func mustParse(t *testing.T, s string) x509.OID {
+ t.Helper()
+ oid, err := x509.ParseOID(gov(s))
+ if err != nil {
+ t.Fatalf("ParseOID(%s): %v", s, err)
+ }
+ return oid
+}
+
+func TestNamespaceTable(t *testing.T) {
+ tests := []struct {
+ ns Namespace
+ id uint64
+ text string
+ oid string
+ }{
+ {NSBuiltin, 7, "+", "GOV.0.7.21"},
+ {NSSymbol, 8, "foo", "GOV.1.8.102.111.111"},
+ {NSInt, 9, "-42", "GOV.2.9.45.52.50"},
+ {NSFloat, 10, "3.14", "GOV.3.10.51.46.49.52"},
+ {NSString, 11, "hi", "GOV.4.11.104.105"},
+ {NSString, 12, "", "GOV.4.12"},
+ {NSBuiltin, 13, ListNode, "GOV.0.13.1"},
+ {NSBuiltin, 14, Empty, "GOV.0.14.5"},
+ {NSSymbol, 15, "😀", "GOV.1.15.128512"},
+ {NSSymbol, 1 << 40, "x", "GOV.1.1099511627776.120"},
+ }
+ for _, tt := range tests {
+ oid, err := EncodeOID(tt.ns, tt.id, tt.text)
+ if err != nil {
+ t.Errorf("EncodeOID(%s, %d, %q): %v", tt.ns, tt.id, tt.text, err)
+ continue
+ }
+ if got, want := oid.String(), gov(tt.oid); got != want {
+ t.Errorf("EncodeOID(%s, %d, %q) = %s, want %s", tt.ns, tt.id, tt.text, got, tt.oid)
+ }
+ ns, id, text, err := DecodeOID(mustParse(t, tt.oid))
+ if err != nil {
+ t.Errorf("DecodeOID(%s): %v", tt.oid, err)
+ continue
+ }
+ if ns != tt.ns || id != tt.id || text != tt.text {
+ t.Errorf("DecodeOID(%s) = %s, %d, %q", tt.oid, ns, id, text)
+ }
+ }
+}
+
+func TestEncodeRejects(t *testing.T) {
+ tests := []struct {
+ ns Namespace
+ id uint64
+ text string
+ want string
+ }{
+ {NSSymbol, 0, "x", "positive"},
+ {NSBuiltin, 1, "foo", "not a builtin"},
+ {NSSymbol, 1, "", "empty symbol"},
+ {NSSymbol, 1, "+", "builtin name"},
+ {NSSymbol, 1, "T", "builtin name"},
+ {NSSymbol, 1, "12", "reads as a number"},
+ {NSSymbol, 1, "1.", "reads as a number"},
+ {NSInt, 1, "007", "malformed"},
+ {NSInt, 1, "1.5", "not an integer"},
+ {NSInt, 1, "9223372036854775808", "64 bits"},
+ {NSFloat, 1, "1.", "malformed"},
+ {NSFloat, 1, "1e5", "malformed"},
+ {NSFloat, 1, "42", "not a float"},
+ {NSFloat, 1, "1.0e999", "out of range"},
+ {NSString, 1, "\xff", "UTF-8"},
+ {5, 1, "x", "unknown namespace 5"},
+ }
+ for _, tt := range tests {
+ _, err := EncodeOID(tt.ns, tt.id, tt.text)
+ if err == nil || !strings.Contains(err.Error(), tt.want) {
+ t.Errorf("EncodeOID(%s, %d, %q) error = %v, want %q", tt.ns, tt.id, tt.text, err, tt.want)
+ }
+ }
+}
+
+func TestDecodeRejects(t *testing.T) {
+ tests := []struct {
+ oid string
+ want string
+ }{
+ {"2.5.29.32.0", "not under"},
+ {"2.25.96655360458544534101705795377599264041.1.1.120", "not under"}, // Root's arc with a digit added
+ {"GOV", "no node id"},
+ {"GOV.1", "no node id"},
+ {"GOV.5.1.120", "unknown namespace 5"},
+ {"GOV.1.0.120", "positive"},
+ {"GOV.0.1", "exactly one payload arc, got 0"},
+ {"GOV.0.1.21.21", "exactly one payload arc, got 2"},
+ {"GOV.0.1.6", "unknown builtin code 6"},
+ {"GOV.4.1.55296", "not a Unicode code point"}, // U+D800, a surrogate
+ {"GOV.4.1.1114112", "not a Unicode code point"}, // one past U+10FFFF
+ {"GOV.1.1", "empty symbol"},
+ {"GOV.1.1.49.46", "reads as a number"}, // "1."
+ {"GOV.3.1.49.46", "malformed"},
+ {"GOV.1.18446744073709551616.120", "64 bits"},
+ }
+ for _, tt := range tests {
+ _, _, _, err := DecodeOID(mustParse(t, tt.oid))
+ if err == nil || !strings.Contains(err.Error(), tt.want) {
+ t.Errorf("DecodeOID(%s) error = %v, want %q", tt.oid, err, tt.want)
+ }
+ }
+}
+
+func TestBuiltinCodesArePinned(t *testing.T) {
+ // Published codes must never change; this list is a second copy of the
+ // DESIGN.md table so an accidental edit to builtinCodes fails here.
+ want := map[string]uint64{
+ ListNode: 1, Dot: 2, True: 3, False: 4, Empty: 5,
+ "quote": 10, "if": 11, "define": 12, "lambda": 13, "and": 14, "or": 15,
+ "not": 20, "+": 21, "-": 22, "*": 23, "/": 24, "<": 25, ">": 26,
+ "<=": 27, ">=": 28, "==": 29, "!=": 30, "cons": 31, "car": 32,
+ "cdr": 33, "strlen": 34, "strcat": 35, "str?": 36,
+ }
+ if len(builtinCodes) != len(want) {
+ t.Errorf("%d builtins, want %d", len(builtinCodes), len(want))
+ }
+ for _, b := range builtinCodes {
+ if want[b.name] != b.code {
+ t.Errorf("%s has code %d, want %d", b.name, b.code, want[b.name])
+ }
+ }
+ if len(nameByCode) != len(builtinCodes) {
+ t.Error("two builtins share a code")
+ }
+}
diff --git a/ast/reserved_test.go b/ast/reserved_test.go
new file mode 100644
index 0000000000000000000000000000000000000000..8b8db2874b0d828cd0804ea90105c251162a5f65
--- /dev/null
+++ b/ast/reserved_test.go
@@ -0,0 +1,24 @@
+package ast
+
+import (
+ "slices"
+ "testing"
+
+ "government/eval"
+)
+
+func TestBuiltinsMatchEvaluator(t *testing.T) {
+ // The structural names are values in source (or reader syntax), not
+ // symbols, so the evaluator never sees them as names.
+ structural := []string{ListNode, Dot, True, False, Empty}
+ var named []string
+ for _, b := range builtinCodes {
+ if !slices.Contains(structural, b.name) {
+ named = append(named, b.name)
+ }
+ }
+ slices.Sort(named)
+ if reserved := eval.ReservedNames(); !slices.Equal(named, reserved) {
+ t.Errorf("builtin codes name %v\nevaluator reserves %v", named, reserved)
+ }
+}
diff --git a/eval/closure.go b/eval/closure.go
index 9cf8d3722c6a0f0f05b338bf2a8e32b788a50dd2..d70b4fd54ca6c0cd11c46a8cbab8b3afd06a99e8 100644
--- a/eval/closure.go
+++ b/eval/closure.go
@@ -1,6 +1,10 @@
package eval
-import "government/sexpr"
+import (
+ "sort"
+
+ "government/sexpr"
+)
// Closure is a lambda's code paired with the environment it was created
// in. Calling it extends that environment, never the caller's, which is
@@ -130,3 +134,18 @@ return true
}
return builtinNames[name]
}
+
+// ReservedNames lists the names isReserved accepts. The ast package checks
+// its builtin code table against this list, so the evaluator and the OID
+// encoding cannot disagree about which names are builtins.
+func ReservedNames() []string {
+ names := make([]string, 0, len(specialForms)+len(builtins))
+ for name := range specialForms {
+ names = append(names, string(name))
+ }
+ for _, b := range builtins {
+ names = append(names, b.name)
+ }
+ sort.Strings(names)
+ return names
+}
diff --git a/sexpr/reader.go b/sexpr/reader.go
index 093c5001ea972e0f6f89ce91eca65ec601b644cf..6743ed0c2e447ed76fdb614ea2c592cdee8a939e 100644
--- a/sexpr/reader.go
+++ b/sexpr/reader.go
@@ -222,26 +222,42 @@ numberLike = regexp.MustCompile(`^[-+]?\.?[0-9]`)
)
func parseAtom(t Token) (Value, error) {
- s := t.Text
- switch {
- case s == "T":
+ switch t.Text {
+ case "T":
return T, nil
- case s == "F":
+ case "F":
return F, nil
+ }
+ v, ok, err := ParseNumber(t.Text)
+ if err != nil {
+ return nil, &SyntaxError{Pos: t.Pos, Msg: err.Error()}
+ }
+ if ok {
+ return v, nil
+ }
+ return Symbol(t.Text), nil
+}
+
+// ParseNumber reads s as a number literal. ok is false when s does not start
+// like a number, so it is a symbol. The OID decoder uses this too, so a
+// payload is a valid integer, float or symbol exactly when the same text is
+// in source.
+func ParseNumber(s string) (v Value, ok bool, err error) {
+ switch {
case intPattern.MatchString(s):
n, err := strconv.ParseInt(s, 10, 64)
if err != nil {
- return nil, &SyntaxError{Pos: t.Pos, Msg: fmt.Sprintf("integer %s does not fit in 64 bits", s)}
+ return nil, true, fmt.Errorf("integer %s does not fit in 64 bits", s)
}
- return Int(n), nil
+ return Int(n), true, nil
case floatPattern.MatchString(s):
f, err := strconv.ParseFloat(s, 64)
if err != nil || math.IsInf(f, 0) {
- return nil, &SyntaxError{Pos: t.Pos, Msg: fmt.Sprintf("float %s is out of range", s)}
+ return nil, true, fmt.Errorf("float %s is out of range", s)
}
- return Float(f), nil
+ return Float(f), true, nil
case numberLike.MatchString(s):
- return nil, &SyntaxError{Pos: t.Pos, Msg: fmt.Sprintf("malformed number %s", s)}
+ return nil, true, fmt.Errorf("malformed number %s", s)
}
- return Symbol(s), nil
+ return nil, false, nil
}