government

commit b16190dee4ae781544f8119bec44f00f5224c810

tree

parent:
18e20f574cf1ffbd092fda0b63e7b07430be77dc

nmyk <nick@nmyk.io>

2026-11-14T18:09:01-05:00

add lisp comments as x509 user notice

diff --git a/DESIGN.md b/DESIGN.md
index ecfe9de98df81e1159695f16128b67f60c45f031..6af8829a7a5aa3365a19bfed49e2865c65a21b95 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -426,7 +426,7 @@
 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 that begins on the next line, or to the form it trails on the same line. Test annotations (`;=>`, `;=!`) are never notes.
+- **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.
 - **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.
diff --git a/ast/tree.go b/ast/tree.go
index 61bfe7459a7f9777d6fa8e8bf78458eb82b19c55..cdb6465e4ff5a0353e7702394f7a8ea50a5dba6b 100644
--- a/ast/tree.go
+++ b/ast/tree.go
@@ -17,6 +17,9 @@ 	ID       uint64
 	NS       Namespace
 	Text     string
 	Children []*Node
+	// Note is the source comment describing this node, if any. It travels
+	// in the certs as a policy qualifier and never affects evaluation.
+	Note string
 }
 
 // Tree is a whole program. Its forms are the children of the policy tree's
@@ -33,11 +36,12 @@ func (n *Node) IsList() bool {
 	return n.NS == NSBuiltin && n.Text == ListNode
 }
 
-// ToTree turns a parsed program into a tree, numbering nodes 1, 2, 3, ... in
-// pre-order (a list before its elements, elements left to right). Because
-// ids are given in reading order, sorting siblings by id recovers argument
-// order, which certificates do not preserve.
-func ToTree(program []sexpr.Value) (*Tree, error) {
+// Build turns a program, as datums from sexpr.ReadProgram, into a tree,
+// numbering nodes 1, 2, 3, ... in pre-order (a list before its elements,
+// elements left to right). Because ids are given in reading order, sorting
+// siblings by id recovers argument order, which certificates do not
+// preserve. Each datum becomes exactly one node and passes its note on.
+func Build(program []*sexpr.Datum) (*Tree, error) {
 	b := &builder{}
 	t := &Tree{}
 	for _, form := range program {
@@ -50,17 +54,35 @@ 	}
 	return t, nil
 }
 
+// ToTree is Build for a program that exists only as values, with no source
+// and so no notes.
+func ToTree(program []sexpr.Value) (*Tree, error) {
+	return Build(sexpr.DatumsOf(program))
+}
+
 type builder struct {
 	lastID uint64
 }
 
-func (b *builder) node(v sexpr.Value) (*Node, error) {
+func (b *builder) node(d *sexpr.Datum) (*Node, error) {
 	b.lastID++
-	n := &Node{ID: b.lastID}
-	switch v := v.(type) {
-	case *sexpr.Pair:
+	n := &Node{ID: b.lastID, Note: d.Note}
+	if d.Dot {
+		n.NS, n.Text = NSBuiltin, Dot
+		return n, nil
+	}
+	if d.IsList() {
 		n.NS, n.Text = NSBuiltin, ListNode
-		return n, b.elements(n, v)
+		for _, e := range d.Elems {
+			child, err := b.node(e)
+			if err != nil {
+				return nil, err
+			}
+			n.Children = append(n.Children, child)
+		}
+		return n, nil
+	}
+	switch v := d.Value.(type) {
 	case sexpr.Symbol:
 		n.NS, n.Text = NSSymbol, string(v)
 		if isReservedSymbol(n.Text) {
@@ -90,35 +112,6 @@ 			return nil, err
 		}
 	}
 	return n, nil
-}
-
-// elements makes each element of the list p a child of n. An improper
-// tail becomes a "." child followed by the tail, mirroring the source text
-// (a b . c).
-func (b *builder) elements(n *Node, p *sexpr.Pair) error {
-	var rest sexpr.Value = p
-	for {
-		switch r := rest.(type) {
-		case *sexpr.Pair:
-			child, err := b.node(r.Car)
-			if err != nil {
-				return err
-			}
-			n.Children = append(n.Children, child)
-			rest = r.Cdr
-			continue
-		case sexpr.Empty:
-			return nil
-		}
-		b.lastID++
-		n.Children = append(n.Children, &Node{ID: b.lastID, NS: NSBuiltin, Text: Dot})
-		tail, err := b.node(rest)
-		if err != nil {
-			return err
-		}
-		n.Children = append(n.Children, tail)
-		return nil
-	}
 }
 
 // isReservedSymbol reports whether a source symbol names a builtin. The
diff --git a/ast/tree_test.go b/ast/tree_test.go
index 91812066cf4f057122e296b89f96818f255cac1f..23205569790d6bf80ffe1aa314121d9b4cd91a0f 100644
--- a/ast/tree_test.go
+++ b/ast/tree_test.go
@@ -238,3 +238,66 @@ type fakeFunction struct{ sexpr.FunctionBase }
 
 func (fakeFunction) Builtin() bool { return false }
 func (fakeFunction) Name() string  { return "" }
+
+func TestBuildCarriesNotes(t *testing.T) {
+	src := "; squares\n(define sq (lambda (x)\n  ; the work\n  (* x x)))"
+	datums, err := sexpr.ReadProgram(src)
+	if err != nil {
+		t.Fatal(err)
+	}
+	tree, err := Build(datums)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// (#1 define#2 sq#3 (#4 lambda#5 (#6 x#7) (#8 *#9 x#10 x#11)))
+	lambda := tree.Forms[0].Children[2]
+	if tree.Forms[0].Note != "squares" || lambda.Children[2].Note != "the work" || lambda.Note != "" {
+		t.Errorf("notes: form %q, (* x x) %q, lambda %q", tree.Forms[0].Note, lambda.Children[2].Note, lambda.Note)
+	}
+	if lambda.Children[2].ID != 8 {
+		t.Errorf("(* x x) is node %d, want 8", lambda.Children[2].ID)
+	}
+}
+
+// TestBuildMatchesToTree checks that building from source and from the
+// values it reads as give the same tree, notes aside. A difference would
+// mean the reader splits some list differently from DatumOf.
+func TestBuildMatchesToTree(t *testing.T) {
+	sources := []string{`'(1 . (2 . (3 . ())))`, `'(a . 'b)`, `'(a b . c)`, `(f () T F "s" 1.5 -2)`, `'''x`}
+	files, _ := filepath.Glob("../testdata/*.gov.lisp")
+	examples, _ := filepath.Glob("../examples/*.gov.lisp")
+	for _, f := range append(files, examples...) {
+		src, err := os.ReadFile(f)
+		if err != nil {
+			t.Fatal(err)
+		}
+		sources = append(sources, string(src))
+	}
+	for _, src := range sources {
+		datums, err := sexpr.ReadProgram(src)
+		if err != nil {
+			t.Fatal(err)
+		}
+		fromSource, err := Build(datums)
+		if err != nil {
+			t.Fatal(err)
+		}
+		var clear func(n *Node)
+		clear = func(n *Node) {
+			n.Note = ""
+			for _, c := range n.Children {
+				clear(c)
+			}
+		}
+		for _, f := range fromSource.Forms {
+			clear(f)
+		}
+		fromValues, err := ToTree(mustRead(t, src))
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !reflect.DeepEqual(fromSource, fromValues) {
+			t.Errorf("%.40q: the tree from source differs from the tree from its values", src)
+		}
+	}
+}
diff --git a/ast/unlayer.go b/ast/unlayer.go
index 6b9d9fc4543f0a54931a07716996d74e51693eda..9836c2c18443898a92e25a4595eb968cc530c416 100644
--- a/ast/unlayer.go
+++ b/ast/unlayer.go
@@ -87,7 +87,7 @@ 	if out, ok := u.built[in]; ok {
 		return out, nil
 	}
 	d := u.depth[in]
-	out := &Node{ID: in.ID, NS: in.NS, Text: in.Text}
+	out := &Node{ID: in.ID, NS: in.NS, Text: in.Text, Note: in.Note}
 	// Ids are unique across the program, so two real nodes with one id
 	// means two different OIDs claim the same place in argument order.
 	if other, ok := u.byID[in.ID]; ok {
diff --git a/cmd/government/inspect.go b/cmd/government/inspect.go
index cdf9968159407b5dfbd966800904c9d0ecbdd9b7..26571950732b0eb9aa50cb97aa5254b714c9b140 100644
--- a/cmd/government/inspect.go
+++ b/cmd/government/inspect.go
@@ -58,6 +58,6 @@ 	if err != nil {
 		fmt.Fprintf(stderr, "%s: %v\n", path, err)
 		return exitInvalid
 	}
-	fmt.Fprint(stdout, gov2lisp.Decompile(p.Forms))
+	fmt.Fprint(stdout, gov2lisp.DecompileTree(p.Tree))
 	return exitOK
 }
diff --git a/cmd/government/inspect_test.go b/cmd/government/inspect_test.go
index 31e5db5279573ed545365925930d272cf9d4ac9e..b36289daf384faabdf5da410b631811be5fee896 100644
--- a/cmd/government/inspect_test.go
+++ b/cmd/government/inspect_test.go
@@ -21,7 +21,7 @@
 func TestDecompileCommand(t *testing.T) {
 	gov := compileTo(t, t.TempDir(), "sq", sqSource)
 	code, stdout, stderr := runCmd("decompile", gov)
-	if code != exitOK || stdout != "(define sq (lambda (x) (* x x)))\n(sq 12)\n" {
+	if code != exitOK || stdout != "; sq.gov.lisp: the square of a number.\n(define sq (lambda (x) (* x x)))\n(sq 12)\n" {
 		t.Errorf("exit %d, stdout %q, stderr %s", code, stdout, stderr)
 	}
 }
diff --git a/gov2lisp/gov2lisp.go b/gov2lisp/gov2lisp.go
index e4f88a182691e363f89ed49fc17206a3c14a5a1c..b43d7c521f88684f20dfdcca9ab636c76c898faa 100644
--- a/gov2lisp/gov2lisp.go
+++ b/gov2lisp/gov2lisp.go
@@ -4,13 +4,13 @@
 import (
 	"strings"
 
+	"government/ast"
 	"government/sexpr"
 )
 
 // Decompile prints one top-level form per line. The output is source in
-// normal form: the printer's spelling, so 'x comes back as (quote x),
-// 3.10 as 3.1, and comments are gone until notes carry them (Phase 7).
-// Reading it gives exactly the forms that were decoded.
+// normal form: the printer's spelling, so 'x comes back as (quote x) and
+// 3.10 as 3.1. Reading it gives exactly the forms that were decoded.
 func Decompile(forms []sexpr.Value) string {
 	var b strings.Builder
 	for _, f := range forms {
@@ -19,3 +19,75 @@ 		b.WriteByte('\n')
 	}
 	return b.String()
 }
+
+// DecompileTree is Decompile that also restores notes as comments. Each
+// note goes on the lines just before its node, so reading the output
+// attaches it to the same node again. A form with no notes inside it stays
+// on one line; a list with a noted element inside is broken across lines,
+// one element per line, so the comment has a line of its own.
+func DecompileTree(t *ast.Tree) string {
+	var b strings.Builder
+	for _, f := range t.Forms {
+		writeNote(&b, f.Note, "")
+		writeNode(&b, f, "")
+		b.WriteByte('\n')
+	}
+	return b.String()
+}
+
+func writeNode(b *strings.Builder, n *ast.Node, indent string) {
+	if !n.IsList() || !hasNotesInside(n) {
+		b.WriteString(compact(n))
+		return
+	}
+	inner := indent + "  "
+	b.WriteByte('(')
+	for i, c := range n.Children {
+		if i > 0 || c.Note != "" {
+			b.WriteString("\n" + inner)
+		}
+		if c.Note != "" {
+			writeNote(b, c.Note, inner)
+		}
+		writeNode(b, c, inner)
+	}
+	b.WriteByte(')')
+}
+
+// writeNote writes a note as comment lines, each ending in a newline and
+// the indent the node will start at.
+func writeNote(b *strings.Builder, note, indent string) {
+	if note == "" {
+		return
+	}
+	for _, line := range strings.Split(note, "\n") {
+		if line == "" {
+			b.WriteString(";\n" + indent)
+		} else {
+			b.WriteString("; " + line + "\n" + indent)
+		}
+	}
+}
+
+func hasNotesInside(n *ast.Node) bool {
+	for _, c := range n.Children {
+		if c.Note != "" || hasNotesInside(c) {
+			return true
+		}
+	}
+	return false
+}
+
+// compact prints a node on one line, as the printer would print its value.
+func compact(n *ast.Node) string {
+	if n.IsList() {
+		forms, _, err := ast.FromTree(&ast.Tree{Forms: []*ast.Node{n}})
+		if err == nil {
+			return sexpr.Print(forms[0])
+		}
+	}
+	if n.NS == ast.NSString {
+		return sexpr.Print(sexpr.String(n.Text))
+	}
+	return n.Text
+}
diff --git a/gov2lisp/gov2lisp_test.go b/gov2lisp/gov2lisp_test.go
index 64e2c1a5d63b954b37578c59162b977eaf32e8bc..cc93670eb57f2b03461b2658d8aae078eb7bd824 100644
--- a/gov2lisp/gov2lisp_test.go
+++ b/gov2lisp/gov2lisp_test.go
@@ -4,18 +4,34 @@ import (
 	"os"
 	"path/filepath"
 	"reflect"
+	"strings"
 	"testing"
 	"time"
 
+	"government/ast"
 	"government/lisp2gov"
 	"government/program"
 	"government/sexpr"
 )
 
-// TestRoundTrip compiles each testdata file, decodes the .gov and
-// decompiles it. The text must equal the source in normal form, and read
-// back to the source's forms. A bug anywhere between reading the source
-// and printing the decoded program shows up here, in either direction.
+func decompiled(t *testing.T, src string) string {
+	t.Helper()
+	data, err := lisp2gov.Compile(src, lisp2gov.Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	p, err := program.Load(data, program.Options{At: time.Now()})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return DecompileTree(p.Tree)
+}
+
+// TestRoundTrip compiles each program, decodes the .gov and decompiles it.
+// The text must read back to the source's forms with the source's notes,
+// and compiling it again must give the same text: a bug anywhere between
+// reading the source and printing the decoded program shows up here, in
+// either direction.
 func TestRoundTrip(t *testing.T) {
 	files, _ := filepath.Glob("../testdata/*.gov.lisp")
 	examples, _ := filepath.Glob("../examples/*.gov.lisp")
@@ -28,35 +44,78 @@ 		src, err := os.ReadFile(file)
 		if err != nil {
 			t.Fatal(err)
 		}
-		want, err := sexpr.ReadAll(string(src))
+		wantForms, wantNotes, err := readWithNotes(string(src))
 		if err != nil {
 			t.Fatal(err)
 		}
-		data, err := lisp2gov.Compile(string(src), lisp2gov.Options{})
+		text := decompiled(t, string(src))
+		gotForms, gotNotes, err := readWithNotes(text)
 		if err != nil {
-			t.Fatal(err)
+			t.Errorf("%s: decompiled text does not read: %v", file, err)
+			continue
+		}
+		if !reflect.DeepEqual(gotForms, wantForms) {
+			t.Errorf("%s: decompiled text reads as different forms", file)
 		}
-		p, err := program.Load(data, program.Options{At: time.Now()})
-		if err != nil {
-			t.Fatalf("%s: %v", file, err)
+		if !reflect.DeepEqual(gotNotes, wantNotes) {
+			t.Errorf("%s: notes differ:\n got  %q\n want %q", file, gotNotes, wantNotes)
 		}
-		got := Decompile(p.Forms)
-		if normal := Decompile(want); got != normal {
-			t.Errorf("%s: decompiled text differs from the source in normal form", file)
+		if again := decompiled(t, text); again != text {
+			t.Errorf("%s: decompiling twice gives different text", file)
 		}
-		back, err := sexpr.ReadAll(got)
-		if err != nil {
-			t.Errorf("%s: decompiled text does not read: %v", file, err)
-			continue
+	}
+}
+
+// readWithNotes reads src as values, plus the note of each node, by id.
+func readWithNotes(src string) ([]sexpr.Value, map[uint64]string, error) {
+	datums, err := sexpr.ReadProgram(src)
+	if err != nil {
+		return nil, nil, err
+	}
+	tree, err := ast.Build(datums)
+	if err != nil {
+		return nil, nil, err
+	}
+	notes := map[uint64]string{}
+	var walk func(n *ast.Node)
+	walk = func(n *ast.Node) {
+		if n.Note != "" {
+			notes[n.ID] = n.Note
 		}
-		if !reflect.DeepEqual(back, want) {
-			t.Errorf("%s: decompiled text reads as different forms", file)
+		for _, c := range n.Children {
+			walk(c)
 		}
 	}
+	for _, f := range tree.Forms {
+		walk(f)
+	}
+	forms := make([]sexpr.Value, len(datums))
+	for i, d := range datums {
+		forms[i] = d.Value
+	}
+	return forms, notes, nil
+}
+
+func TestLongNoteSurvives(t *testing.T) {
+	// 450 characters: three user notices in the cert, one comment again.
+	long := strings.Repeat("The quick brown fox jumps. ", 17)[:450]
+	text := decompiled(t, "; "+long+"\n(+ 1 2)\n")
+	if text != "; "+long+"\n(+ 1 2)\n" {
+		t.Errorf("got %q", text)
+	}
+}
+
+func TestNotesInsideForms(t *testing.T) {
+	src := "(define area\n  ; width times height\n  (lambda (w h)\n    (* w ; the width\n       h)))\n"
+	text := decompiled(t, src)
+	want := "(define\n  area\n  ; width times height\n  (lambda\n    (w h)\n    (*\n      ; the width\n      w\n      h)))\n"
+	if text != want {
+		t.Errorf("got\n%s\nwant\n%s", text, want)
+	}
 }
 
 func TestDecompileNormalForm(t *testing.T) {
-	forms, _ := sexpr.ReadAll("'x   ( + 1    3.10 )\n; gone\n\"a\\tb\"")
+	forms, _ := sexpr.ReadAll("'x   ( + 1    3.10 )\n\"a\\tb\"")
 	if got, want := Decompile(forms), "(quote x)\n(+ 1 3.1)\n\"a\\tb\"\n"; got != want {
 		t.Errorf("got %q, want %q", got, want)
 	}
diff --git a/lisp2gov/cert.go b/lisp2gov/cert.go
index def76b0c3d305f2cc81832fceb48d9d444d96eca..d2ea25f5db075992b6c4d2067681b5d1cd7ee0ad 100644
--- a/lisp2gov/cert.go
+++ b/lisp2gov/cert.go
@@ -48,7 +48,7 @@
 // newCert makes the cert at depth i, issued by parent. Every cert but the
 // last is a CA, because each one signs the next; the last one signs
 // nothing.
-func newCert(seed [32]byte, program string, i int, last bool, policies []x509.OID, mappings []x509.PolicyMapping, parent signer) (signer, error) {
+func newCert(seed [32]byte, program string, i int, last bool, policies []policyInfo, mappings []x509.PolicyMapping, parent signer) (signer, error) {
 	key := keyForDepth(seed, i)
 	pub := key.Public().(ed25519.PublicKey)
 	tmpl := &x509.Certificate{
@@ -70,11 +70,7 @@ 		// only for certs 1..n-1), so any here would be silently dead.
 		return signer{}, fmt.Errorf("cert %d is the last one and cannot carry mappings", i)
 	}
 	if len(policies) > 0 {
-		infos := make([]policyInfo, len(policies))
-		for j, p := range policies {
-			infos[j] = policyInfo{id: p}
-		}
-		ext, err := certificatePoliciesExtension(infos)
+		ext, err := certificatePoliciesExtension(policies)
 		if err != nil {
 			return signer{}, err
 		}
diff --git a/lisp2gov/compile.go b/lisp2gov/compile.go
index a867d52f3550ec0f51a69bfbbe3dfb73eeb5b96e..97128c767a5fd1d39e6862b32f4bc4acd149ecc5 100644
--- a/lisp2gov/compile.go
+++ b/lisp2gov/compile.go
@@ -52,11 +52,11 @@ // top-level forms; certs 2..n list only anyPolicy, so every node below
 // depth 1 exists in the policy tree only because a mapping in the cert
 // above names it.
 func compileCerts(src string, opts Options) ([]*x509.Certificate, error) {
-	forms, err := sexpr.ReadAll(src)
+	datums, err := sexpr.ReadProgram(src)
 	if err != nil {
 		return nil, err
 	}
-	tree, err := ast.ToTree(forms)
+	tree, err := ast.Build(datums)
 	if err != nil {
 		return nil, err
 	}
@@ -73,16 +73,9 @@ 	}
 	certs := []*x509.Certificate{prev.cert}
 	n := layers.Depth()
 	for i := 1; i <= n; i++ {
-		policies := []x509.OID{anyPolicy}
-		if i == 1 {
-			policies = nil
-			for _, node := range layers.Nodes[0] {
-				oid, err := node.OID()
-				if err != nil {
-					return nil, err
-				}
-				policies = append(policies, oid)
-			}
+		policies, err := policiesFor(i, layers.Nodes[i-1])
+		if err != nil {
+			return nil, err
 		}
 		mappings, err := mappingsFor(layers.Edges[i-1])
 		if err != nil {
@@ -96,6 +89,30 @@ 		certs = append(certs, next.cert)
 		prev = next
 	}
 	return certs, nil
+}
+
+// policiesFor lists what cert i asserts. Cert 1 names every top-level
+// node. Certs 2..n assert anyPolicy, which creates their nodes, and also
+// name each node with a note: a node anyPolicy creates gets no qualifiers,
+// but RFC 9618 handles named policies (step d.1) before anyPolicy (d.2),
+// which skips a policy that already has a node, so the named entry and its
+// note are the ones that stick.
+func policiesFor(i int, nodes []*ast.Node) ([]policyInfo, error) {
+	var policies []policyInfo
+	if i > 1 {
+		policies = append(policies, policyInfo{id: anyPolicy})
+	}
+	for _, n := range nodes {
+		if i > 1 && n.Note == "" {
+			continue
+		}
+		oid, err := n.OID()
+		if err != nil {
+			return nil, err
+		}
+		policies = append(policies, policyInfo{id: oid, note: n.Note})
+	}
+	return policies, nil
 }
 
 // header is the text above the first PEM block: nothing, or with
diff --git a/lisp2gov/extensions.go b/lisp2gov/extensions.go
index 468560595e4679ab59fef3594015681846da569b..7eb7f7b5c1497f3c71f7a99b7c406e67523837b5 100644
--- a/lisp2gov/extensions.go
+++ b/lisp2gov/extensions.go
@@ -27,32 +27,67 @@ 	}
 	return oid
 }
 
-// policyInfo is one entry of certificatePolicies. Phase 7 adds user-notice
-// qualifiers here to carry notes, which is why this extension is built by
-// hand: x509.Certificate.Policies holds bare OIDs and has no room for them.
+// policyInfo is one entry of certificatePolicies: a node's OID and, if the
+// node has one, its note. x509.Certificate.Policies holds bare OIDs, with
+// no room for a note, which is why this extension is built by hand.
 type policyInfo struct {
-	id x509.OID
+	id   x509.OID
+	note string
 }
 
+// idQtUnotice is the user-notice qualifier, a policy qualifier holding text
+// meant for a person reading the cert.
+var idQtUnotice = mustOID("1.3.6.1.5.5.7.2.2")
+
+// maxNoticeText is RFC 5280's limit on a user notice's explicitText, in
+// characters. A longer note is split across several user notices, which a
+// reader joins back in order.
+const maxNoticeText = 200
+
 // certificatePoliciesExtension encodes
 //
 //	certificatePolicies ::= SEQUENCE SIZE (1..MAX) OF PolicyInformation
 //	PolicyInformation ::= SEQUENCE {
 //	     policyIdentifier   CertPolicyId,
 //	     policyQualifiers   SEQUENCE SIZE (1..MAX) OF PolicyQualifierInfo OPTIONAL }
+//	PolicyQualifierInfo ::= SEQUENCE {
+//	     policyQualifierId  id-qt-unotice,
+//	     qualifier          UserNotice }
+//	UserNotice ::= SEQUENCE { explicitText UTF8String }
 //
 // It is not critical, as Go and most CAs write it: a verifier that does not
 // do policy processing can still check the signatures, and one that does
-// will also need the critical policyMappings.
+// will also need the critical policyMappings. Qualifiers never affect
+// policy processing: RFC 5280 only carries them along, so notes cannot
+// change what a program does.
 func certificatePoliciesExtension(policies []policyInfo) (pkix.Extension, error) {
 	if len(policies) == 0 {
 		return pkix.Extension{}, errors.New("certificatePolicies needs at least one policy")
 	}
 	entries := make([][]byte, len(policies))
 	for i, p := range policies {
-		entries[i] = der.Sequence(der.OID(p.id))
+		if p.note == "" {
+			entries[i] = der.Sequence(der.OID(p.id))
+			continue
+		}
+		var qualifiers [][]byte
+		for _, chunk := range splitNote(p.note) {
+			qualifiers = append(qualifiers, der.Sequence(der.OID(idQtUnotice), der.Sequence(der.UTF8String(chunk))))
+		}
+		entries[i] = der.Sequence(der.OID(p.id), der.Sequence(qualifiers...))
 	}
 	return pkix.Extension{Id: oidCertificatePolicies, Value: der.Sequence(entries...)}, nil
+}
+
+// splitNote cuts a note into pieces of at most maxNoticeText characters.
+func splitNote(note string) []string {
+	runes := []rune(note)
+	var chunks []string
+	for len(runes) > maxNoticeText {
+		chunks = append(chunks, string(runes[:maxNoticeText]))
+		runes = runes[maxNoticeText:]
+	}
+	return append(chunks, string(runes))
 }
 
 // policyMappingsExtension encodes
diff --git a/lisp2gov/extensions_test.go b/lisp2gov/extensions_test.go
index 7b8f31f533ee25679d07a498b5e3069e8437a030..9fe0c1de97af579f3fd8d23f9a315d31ef1f359a 100644
--- a/lisp2gov/extensions_test.go
+++ b/lisp2gov/extensions_test.go
@@ -128,7 +128,7 @@ 	want, err := asn1.Marshal([]policyInformation{{asn1.ObjectIdentifier{1, 2, 3}}, {asn1.ObjectIdentifier{2, 5, 29, 32, 0}}})
 	if err != nil {
 		t.Fatal(err)
 	}
-	ext, err := certificatePoliciesExtension([]policyInfo{{mustOID("1.2.3")}, {anyPolicy}})
+	ext, err := certificatePoliciesExtension([]policyInfo{{id: mustOID("1.2.3")}, {id: anyPolicy}})
 	if err != nil {
 		t.Fatal(err)
 	}
diff --git a/policy/draw.go b/policy/draw.go
index 64934752029d2130a647ff3c8efd57fae9abac55..2e537ffe9f062e44344a43853c9b3c0ec24e36df 100644
--- a/policy/draw.go
+++ b/policy/draw.go
@@ -21,7 +21,8 @@ //
 // A trailing ' marks a copy the validator made, which carries an atom down
 // to the bottom; a chain of copies is one line giving the depths it spans.
 // A node with several parents is drawn in full under the first and named
-// again, without its children, under the others.
+// again, without its children, under the others. A note follows its node's
+// OID after a ";", with its line breaks shown as " / ".
 func (g *Graph) Draw() string {
 	type line struct {
 		depth       int
@@ -50,6 +51,9 @@ 				where = fmt.Sprintf("copy, depths %d-%d", n.Depth, last.Depth)
 			}
 			lines = append(lines, line{n.Depth, prefix + branch + label, where})
 			return
+		}
+		if n.Note != "" {
+			where += "  ; " + strings.ReplaceAll(n.Note, "\n", " / ")
 		}
 		lines = append(lines, line{n.Depth, prefix + branch + label, where})
 		children := slices.Clone(n.Children)
diff --git a/policy/draw_test.go b/policy/draw_test.go
index a042e05fcf519b6503c79a1d750a103c8115ea20..f66b09b8b09d90efaaa9453f19043d261d3cb6cb 100644
--- a/policy/draw_test.go
+++ b/policy/draw_test.go
@@ -51,3 +51,10 @@ 	if n := strings.Count(got, "\n"); n != 11 {
 		t.Errorf("%d lines, want 11:\n%s", n, got)
 	}
 }
+
+func TestDrawShowsNotes(t *testing.T) {
+	got := compiledGraph(t, "; the sum\n(+ 1\n  ; two\n  ; lines\n  2)").Draw()
+	if !strings.Contains(got, "GOV.0.1.1  ; the sum") || !strings.Contains(got, "GOV.2.4.50  ; two / lines") {
+		t.Errorf("notes missing:\n%s", got)
+	}
+}
diff --git a/policy/graph.go b/policy/graph.go
index 3c3e92128cf296cc13d3f138a5fe4536b6eb50bc..feee6a7ceb5d72a1a83a6ca6c01c927f0b809946 100644
--- a/policy/graph.go
+++ b/policy/graph.go
@@ -36,6 +36,9 @@ 	// Expected is the expected_policy_set: the policies the next cert may
 	// assert under this node. It is the node's own policy unless a mapping
 	// replaces it.
 	Expected []x509.OID
+	// Note is the user-notice text the cert attached to this policy, if
+	// it named the policy itself. Nodes made by anyPolicy have none.
+	Note string
 }
 
 func (n *Node) expects(p x509.OID) bool {
@@ -113,6 +116,10 @@ 	// and (f): with explicit policy required, an empty graph is a failure.
 	if !hasExtension(c, oidCertificatePolicies) {
 		return errorf(ErrPolicy, "cert %d has no certificatePolicies, so no policy holds past depth %d", i, i-1)
 	}
+	notes, err := notesIn(c)
+	if err != nil {
+		return errorf(ErrPolicy, "cert %d: %v", i, err)
+	}
 	parents := g.Levels[i-1]
 	var level []*Node
 	byPolicy := map[string]*Node{}
@@ -162,6 +169,7 @@ 		if len(from) > 0 {
 			if err := add(p, from); err != nil {
 				return err
 			}
+			byPolicy[key(p)].Note = notes[key(p)]
 		}
 	}
 
diff --git a/policy/layers.go b/policy/layers.go
index b0af1c232956022acd1223a3a82feb7b332e5f80..ca41e172d34e105f8482df3edb43f7595bb1eab8 100644
--- a/policy/layers.go
+++ b/policy/layers.go
@@ -20,7 +20,7 @@ 			ns, id, text, err := ast.DecodeOID(gn.Policy)
 			if err != nil {
 				return ast.Layers{}, fmt.Errorf("depth %d: %w", d, err)
 			}
-			an := &ast.Node{ID: id, NS: ns, Text: text}
+			an := &ast.Node{ID: id, NS: ns, Text: text, Note: gn.Note}
 			decoded[gn] = an
 			l.Nodes[d-1] = append(l.Nodes[d-1], an)
 		}
diff --git a/policy/notes.go b/policy/notes.go
new file mode 100644
index 0000000000000000000000000000000000000000..15ddb5cb304455ef14ddcd8c4e67b1aa98f4f149
--- /dev/null
+++ b/policy/notes.go
@@ -0,0 +1,96 @@
+package policy
+
+import (
+	"crypto/x509"
+	"encoding/asn1"
+	"errors"
+	"fmt"
+	"strings"
+	"unicode/utf16"
+)
+
+var idQtUnotice = asn1.ObjectIdentifier{1, 3, 6, 1, 5, 5, 7, 2, 2}
+
+// policyInformation is one entry of certificatePolicies. The identifier is
+// kept raw: encoding/asn1 holds OID arcs in an int, and the GOV root's
+// 123-bit arc does not fit, so x509.OID decodes it instead.
+type policyInformation struct {
+	ID         asn1.RawValue
+	Qualifiers []policyQualifierInfo `asn1:"optional"`
+}
+
+type policyQualifierInfo struct {
+	ID        asn1.ObjectIdentifier
+	Qualifier asn1.RawValue
+}
+
+// notesIn reads the user-notice text attached to each policy in a cert,
+// keyed like byPolicy. Go parses certificatePolicies into bare OIDs and
+// drops the qualifiers, so this reads the extension's bytes itself. Other
+// qualifier kinds (CPS pointers) are skipped, as RFC 5280 allows.
+func notesIn(c *x509.Certificate) (map[string]string, error) {
+	var raw []byte
+	for _, ext := range c.Extensions {
+		if ext.Id.Equal(oidCertificatePolicies) {
+			raw = ext.Value
+		}
+	}
+	if raw == nil {
+		return nil, nil
+	}
+	var infos []policyInformation
+	if rest, err := asn1.Unmarshal(raw, &infos); err != nil || len(rest) > 0 {
+		return nil, fmt.Errorf("certificatePolicies does not parse: %v", err)
+	}
+	notes := map[string]string{}
+	for _, info := range infos {
+		var id x509.OID
+		if err := id.UnmarshalBinary(info.ID.Bytes); err != nil {
+			return nil, err
+		}
+		var text strings.Builder
+		for _, q := range info.Qualifiers {
+			if !q.ID.Equal(idQtUnotice) {
+				continue
+			}
+			t, err := explicitText(q.Qualifier.FullBytes)
+			if err != nil {
+				return nil, err
+			}
+			text.WriteString(t)
+		}
+		if text.Len() > 0 {
+			notes[key(id)] = text.String()
+		}
+	}
+	return notes, nil
+}
+
+// explicitText reads a UserNotice ::= SEQUENCE { noticeRef OPTIONAL,
+// explicitText OPTIONAL }. The two optional fields have different types, so
+// it reads the elements and takes the one that is a string.
+func explicitText(userNotice []byte) (string, error) {
+	var elems []asn1.RawValue
+	if rest, err := asn1.Unmarshal(userNotice, &elems); err != nil || len(rest) > 0 {
+		return "", errors.New("a user notice does not parse")
+	}
+	for _, e := range elems {
+		if e.Class != asn1.ClassUniversal {
+			continue
+		}
+		switch e.Tag {
+		case asn1.TagUTF8String, asn1.TagIA5String, 26: // 26 is VisibleString
+			return string(e.Bytes), nil
+		case asn1.TagBMPString:
+			if len(e.Bytes)%2 != 0 {
+				return "", errors.New("a BMPString has an odd length")
+			}
+			units := make([]uint16, len(e.Bytes)/2)
+			for i := range units {
+				units[i] = uint16(e.Bytes[2*i])<<8 | uint16(e.Bytes[2*i+1])
+			}
+			return string(utf16.Decode(units)), nil
+		}
+	}
+	return "", nil
+}
diff --git a/program/program.go b/program/program.go
index 532d9803f578650b31784d39b8a6102839325543..8ff29e8925b79e0191ba1f12e9b2ad8b3c61ad9f 100644
--- a/program/program.go
+++ b/program/program.go
@@ -10,6 +10,7 @@ import (
 	"crypto/x509"
 	"fmt"
 	"io"
+	"strings"
 	"time"
 
 	"government/ast"
@@ -41,11 +42,14 @@ type Program struct {
 	Forms []sexpr.Value
 	// Certs is the chain in depth order, anchor first.
 	Certs []*x509.Certificate
+	// Tree is the decoded program, with its notes.
+	Tree *ast.Tree
 	// Nodes is how many AST nodes the program has. A node shared by
 	// several parents counts once; the validator's copies do not count.
 	Nodes   int
 	origins ast.Origins
 	depth   map[*ast.Node]int
+	parent  map[*ast.Node]*ast.Node
 }
 
 // Depth is how many certificates hold the program, not counting the
@@ -75,19 +79,23 @@ 	forms, origins, err := ast.FromTree(tree)
 	if err != nil {
 		return nil, &Error{ErrDecode, err.Error()}
 	}
-	p := &Program{Forms: forms, Certs: certs, origins: origins, depth: map[*ast.Node]int{}}
-	var walk func(n *ast.Node, d int)
-	walk = func(n *ast.Node, d int) {
+	p := &Program{Forms: forms, Certs: certs, Tree: tree, origins: origins,
+		depth: map[*ast.Node]int{}, parent: map[*ast.Node]*ast.Node{}}
+	var walk func(n, parent *ast.Node, d int)
+	walk = func(n, parent *ast.Node, d int) {
 		if _, seen := p.depth[n]; seen {
 			return
 		}
 		p.depth[n] = d
+		if parent != nil {
+			p.parent[n] = parent
+		}
 		for _, c := range n.Children {
-			walk(c, d+1)
+			walk(c, n, d+1)
 		}
 	}
 	for _, f := range tree.Forms {
-		walk(f, 1)
+		walk(f, nil, 1)
 	}
 	p.Nodes = len(p.depth)
 	return p, nil
@@ -95,21 +103,33 @@ }
 
 // Locate names where an evaluation error happened: the OID of the
 // innermost list being evaluated and its depth, which is the cert that
-// holds it. A .gov program has no line numbers; this is its equivalent.
+// holds it, plus the note of the innermost noted node around it. A .gov
+// program has no line numbers; this is its equivalent.
 func (p *Program) Locate(err error) string {
-	e, ok := err.(*eval.Error)
-	if !ok {
+	n := p.node(err)
+	if n == nil {
 		return ""
 	}
-	pair, ok := e.Expr.(*sexpr.Pair)
+	where := fmt.Sprintf("%s (depth %d)", n, p.depth[n])
+	for m := n; m != nil; m = p.parent[m] {
+		if m.Note != "" {
+			where += fmt.Sprintf(" (note: %q)", strings.ReplaceAll(m.Note, "\n", " "))
+			break
+		}
+	}
+	return where
+}
+
+func (p *Program) node(err error) *ast.Node {
+	e, ok := err.(*eval.Error)
 	if !ok {
-		return ""
+		return nil
 	}
-	n, ok := p.origins[pair]
+	pair, ok := e.Expr.(*sexpr.Pair)
 	if !ok {
-		return ""
+		return nil
 	}
-	return fmt.Sprintf("%s (depth %d)", n, p.depth[n])
+	return p.origins[pair]
 }
 
 // Run evaluates the forms in order, printing the value of each one that is
diff --git a/program/program_test.go b/program/program_test.go
index a96c09d6dc1441f53f6e52af39326952ca3c8df4..93f62995b22eb48486c8cf47b12da39bb06820fa 100644
--- a/program/program_test.go
+++ b/program/program_test.go
@@ -75,3 +75,18 @@ func hasCode(err error, code string) bool {
 	var e *ratify.Error
 	return errors.As(err, &e) && e.Code == code
 }
+
+func TestErrorsNameTheirNote(t *testing.T) {
+	src := "; compute the total\n(define total (lambda (xs)\n  (+ (car xs) z)))\n(total '(1))"
+	p := load(t, src)
+	err := p.Run(&bytes.Buffer{})
+	got := p.Describe(err)
+	if !strings.HasSuffix(got, `(note: "compute the total")`) {
+		t.Errorf("got %s", got)
+	}
+	// The innermost noted node wins.
+	p = load(t, "; outer\n(define f (lambda ()\n  ; inner\n  (+ 1 z)))\n(f)")
+	if got := p.Describe(p.Run(&bytes.Buffer{})); !strings.HasSuffix(got, `(note: "inner")`) {
+		t.Errorf("got %s", got)
+	}
+}
diff --git a/sexpr/datum.go b/sexpr/datum.go
new file mode 100644
index 0000000000000000000000000000000000000000..788dbdc8e7167312a57483cda5e3827b9736e5ab
--- /dev/null
+++ b/sexpr/datum.go
@@ -0,0 +1,67 @@
+package sexpr
+
+// Datum is one piece of source as the reader saw it: the value it reads
+// as, where it is, and the comment that describes it. The datums of a
+// program form a tree with one datum per node of the program tree, so a
+// comment attached to a datum lands on exactly that node, with nothing to
+// count or keep in step.
+type Datum struct {
+	Value      Value
+	Start, End Pos
+	// Elems are a non-empty list's elements, in order. If the list ends in
+	// a dotted pair, the last two are the "." (a datum with Dot set) and
+	// the tail. A tail that is itself a list is not dotted at all: the
+	// reader reads (a . (b c)) as (a b c), so its elements join this list.
+	Elems []*Datum
+	Dot   bool
+	Note  string
+}
+
+// IsList reports whether the datum is a non-empty list, the kind with
+// elements. () is an atom.
+func (d *Datum) IsList() bool {
+	_, ok := d.Value.(*Pair)
+	return ok && !d.Dot
+}
+
+// DatumOf builds the datum tree for a value that did not come from source,
+// with no positions or notes. A list is split exactly as the reader splits
+// it, so the reader's datums for some text and DatumOf of the value it
+// reads as have the same shape.
+func DatumOf(v Value) *Datum {
+	d := &Datum{Value: v}
+	p, ok := v.(*Pair)
+	if !ok {
+		return d
+	}
+	var rest Value = p
+	for {
+		pair, ok := rest.(*Pair)
+		if !ok {
+			break
+		}
+		d.Elems = append(d.Elems, DatumOf(pair.Car))
+		rest = pair.Cdr
+	}
+	if _, ok := rest.(Empty); !ok {
+		d.Elems = append(d.Elems, &Datum{Value: Symbol("."), Dot: true}, DatumOf(rest))
+	}
+	return d
+}
+
+// DatumsOf is DatumOf for every form of a program.
+func DatumsOf(program []Value) []*Datum {
+	ds := make([]*Datum, len(program))
+	for i, v := range program {
+		ds[i] = DatumOf(v)
+	}
+	return ds
+}
+
+// walk visits d and every datum inside it, a list before its elements.
+func (d *Datum) walk(visit func(*Datum)) {
+	visit(d)
+	for _, e := range d.Elems {
+		e.walk(visit)
+	}
+}
diff --git a/sexpr/notes.go b/sexpr/notes.go
new file mode 100644
index 0000000000000000000000000000000000000000..2ccf0a59184e11800133adc90e3d85fe3536d8bd
--- /dev/null
+++ b/sexpr/notes.go
@@ -0,0 +1,85 @@
+package sexpr
+
+import "strings"
+
+// ReadProgram reads every top-level form of src and attaches each comment
+// to the datum it describes, as that datum's Note.
+//
+// A comment that follows code on the same line describes that code: the
+// last datum to end before it, taking the outermost when several end at
+// the same place, as a list and its last element do. Any other comment
+// describes the next datum to start after it. Several comments on the same
+// datum are joined with newlines, in order. Every comment is a note: the
+// test runner's ";=>" and ";=!" annotations mean nothing to the language.
+func ReadProgram(src string) ([]*Datum, error) {
+	r := NewReader(src)
+	var forms []*Datum
+	for {
+		d, err := r.ReadDatum()
+		if err != nil {
+			return nil, err
+		}
+		if d == nil {
+			break
+		}
+		forms = append(forms, d)
+	}
+
+	// Every datum that is part of the program, in reading order. Only these
+	// can take a note, so a "." or parentheses that a dotted tail merged
+	// away never take one by mistake.
+	var all []*Datum
+	for _, f := range forms {
+		f.walk(func(d *Datum) { all = append(all, d) })
+	}
+	for _, c := range r.comments {
+		d := trailed(all, c.Pos)
+		if d == nil {
+			d = following(all, c.Pos)
+		}
+		if d == nil {
+			continue
+		}
+		text := noteText(c.Text)
+		if d.Note != "" {
+			text = d.Note + "\n" + text
+		}
+		d.Note = text
+	}
+	return forms, nil
+}
+
+// noteText drops the comment markers and the one space after them, so
+// ";; total" and "; total" are both the note "total".
+func noteText(text string) string {
+	text = strings.TrimLeft(text, ";")
+	text = strings.TrimPrefix(text, " ")
+	return strings.TrimRight(text, " \t\r")
+}
+
+// trailed is the datum a comment at pos follows on the same line, or nil.
+// all is in reading order, so the first datum to reach the latest end is
+// the outermost one ending there.
+func trailed(all []*Datum, pos Pos) *Datum {
+	var best *Datum
+	for _, d := range all {
+		if d.End.Line != pos.Line || d.End.Col > pos.Col {
+			continue
+		}
+		if best == nil || d.End.Col > best.End.Col {
+			best = d
+		}
+	}
+	return best
+}
+
+// following is the first datum that starts after pos, or nil: the
+// outermost datum starting there, since a list comes before its elements.
+func following(all []*Datum, pos Pos) *Datum {
+	for _, d := range all {
+		if d.Start.Line > pos.Line || (d.Start.Line == pos.Line && d.Start.Col > pos.Col) {
+			return d
+		}
+	}
+	return nil
+}
diff --git a/sexpr/notes_test.go b/sexpr/notes_test.go
new file mode 100644
index 0000000000000000000000000000000000000000..115fe176043d18b6c758e8fd33b03ffcaec170c2
--- /dev/null
+++ b/sexpr/notes_test.go
@@ -0,0 +1,128 @@
+package sexpr
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// notesOf reads src and lists its notes by each datum's position in
+// reading order, counted from 0.
+func notesOf(t *testing.T, src string) map[int]string {
+	t.Helper()
+	forms, err := ReadProgram(src)
+	if err != nil {
+		t.Fatal(err)
+	}
+	notes := map[int]string{}
+	i := 0
+	for _, f := range forms {
+		f.walk(func(d *Datum) {
+			if d.Note != "" {
+				notes[i] = d.Note
+			}
+			i++
+		})
+	}
+	return notes
+}
+
+func TestNotes(t *testing.T) {
+	tests := []struct {
+		name string
+		src  string
+		want map[int]string
+	}{
+		{"leading comment", "; the answer\n42", map[int]string{0: "the answer"}},
+		{"trailing comment", "42 ; the answer\n7", map[int]string{0: "the answer"}},
+		// (+ 1 2): list 0, + 1, 1 2, 2 3. The list and the 2 end at the
+		// same place; the comment describes the whole list.
+		{"trailing a list", "(+ 1 2) ; sum\n", map[int]string{0: "sum"}},
+		{"inside a list", "(+ 1 ; one\n   2)", map[int]string{2: "one"}},
+		{"leading, nested", "(f\n  ; the argument\n  x)", map[int]string{2: "the argument"}},
+		{"a block of comments", ";; first\n;\n; third\n1", map[int]string{0: "first\n\nthird"}},
+		// (+ 1 1) is datums 0-3, (car 1) is 4-6.
+		{"test annotations are notes too", "(+ 1 1) ;=> 2\n(car 1) ;=! pair", map[int]string{0: "=> 2", 4: "=! pair"}},
+		// 'x reads as (quote x): list 0, quote 1, x 2.
+		{"quoted datum", "; data\n'x", map[int]string{0: "data"}},
+		// '(a . b) is (quote (a . b)): list 0, quote 1, list 2, a 3, . 4,
+		// b 5.
+		{"dotted tail", "'(a .\n ; tail\n b)", map[int]string{5: "tail"}},
+		// '(a . (b c)) is (quote (a b c)): the merged-away parentheses
+		// leave no datum, so the comment goes to b, datum 4.
+		{"merged dotted tail", "'(a .\n ; rest\n (b c))", map[int]string{4: "rest"}},
+		{"nothing follows", "1\n; dangling", map[int]string{}},
+		{"two forms", "; one\n1\n; two\n2", map[int]string{0: "one", 1: "two"}},
+	}
+	for _, tt := range tests {
+		if got := notesOf(t, tt.src); !reflect.DeepEqual(got, tt.want) {
+			t.Errorf("%s: %q gives %v, want %v", tt.name, tt.src, got, tt.want)
+		}
+	}
+}
+
+// shape prints a datum tree without positions or notes, to compare the
+// reader's datums with DatumOf's.
+func shape(d *Datum) string {
+	if d.Dot {
+		return "."
+	}
+	if len(d.Elems) == 0 {
+		return Print(d.Value)
+	}
+	parts := make([]string, len(d.Elems))
+	for i, e := range d.Elems {
+		parts[i] = shape(e)
+	}
+	return "[" + strings.Join(parts, " ") + "]"
+}
+
+func TestReaderDatumsMatchDatumOf(t *testing.T) {
+	for _, src := range []string{
+		"(+ 1 (* 2 3))", "'x", "''x", "'(1 . (2 . (3 . ())))", "'(a . 'b)", "'(a . b)",
+		`(f () T F "s" 1.5 -2)`, "'(a b . c)", "((lambda (x) x) 1)",
+	} {
+		forms, err := ReadProgram(src)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for _, f := range forms {
+			if got, want := shape(f), shape(DatumOf(f.Value)); got != want {
+				t.Errorf("%s: reader gives %s, DatumOf gives %s", src, got, want)
+			}
+		}
+	}
+}
+
+func TestDatumPositions(t *testing.T) {
+	forms, err := ReadProgram("(define f\n  '(a . \"s\"))")
+	if err != nil {
+		t.Fatal(err)
+	}
+	d := forms[0]
+	quoted := d.Elems[2]
+	checks := []struct {
+		name       string
+		d          *Datum
+		start, end Pos
+	}{
+		{"outer list", d, Pos{1, 1}, Pos{2, 14}},
+		{"define", d.Elems[0], Pos{1, 2}, Pos{1, 8}},
+		{"quoted list", quoted, Pos{2, 3}, Pos{2, 13}},
+		{"quote mark", quoted.Elems[0], Pos{2, 3}, Pos{2, 4}},
+		{"dot", quoted.Elems[1].Elems[1], Pos{2, 7}, Pos{2, 8}},
+	}
+	for _, c := range checks {
+		if c.d.Start != c.start || c.d.End != c.end {
+			t.Errorf("%s: %v-%v, want %v-%v", c.name, c.d.Start, c.d.End, c.start, c.end)
+		}
+	}
+}
+
+func TestLongNoteKeepsItsText(t *testing.T) {
+	long := strings.Repeat("abcdefghij ", 45)
+	got := notesOf(t, "; "+long+"\n1")
+	if got[0] != strings.TrimRight(long, " ") {
+		t.Errorf("note changed: %q", got[0])
+	}
+}
diff --git a/sexpr/reader.go b/sexpr/reader.go
index 6743ed0c2e447ed76fdb614ea2c592cdee8a939e..b59b996589180f2b04fa87f075195c08f0eac094 100644
--- a/sexpr/reader.go
+++ b/sexpr/reader.go
@@ -21,6 +21,7 @@ 	lex       *Lexer
 	peeked    *Token
 	positions map[*Pair]Pos
 	comments  []Token
+	lastEnd   Pos
 }
 
 func NewReader(src string) *Reader {
@@ -67,27 +68,41 @@ }
 
 // ReadWithPos is Read that also returns where the form starts.
 func (r *Reader) ReadWithPos() (Value, Pos, error) {
+	d, err := r.ReadDatum()
+	if err != nil || d == nil {
+		return nil, Pos{}, err
+	}
+	return d.Value, d.Start, nil
+}
+
+// ReadDatum returns the next top-level form as a datum, or nil at end of
+// input. Notes are not attached yet: a comment may describe a datum read
+// later, so ReadProgram attaches them once everything is read.
+func (r *Reader) ReadDatum() (*Datum, error) {
 	t, err := r.peek()
 	if err != nil {
-		return nil, Pos{}, err
+		return nil, err
 	}
 	if t.Kind == TokEOF {
-		return nil, Pos{}, nil
+		return nil, nil
 	}
-	v, err := r.datum()
-	return v, t.Pos, err
+	return r.datum()
 }
 
-func (r *Reader) datum() (Value, error) {
+func (r *Reader) datum() (*Datum, error) {
 	t, err := r.next()
 	if err != nil {
 		return nil, err
 	}
 	switch t.Kind {
 	case TokAtom:
-		return parseAtom(t)
+		v, err := parseAtom(t)
+		if err != nil {
+			return nil, err
+		}
+		return &Datum{Value: v, Start: t.Pos, End: t.End}, nil
 	case TokString:
-		return String(t.Text), nil
+		return &Datum{Value: String(t.Text), Start: t.Pos, End: t.End}, nil
 	case TokQuote:
 		next, err := r.peek()
 		if err != nil {
@@ -96,17 +111,23 @@ 		}
 		if next.Kind == TokEOF || next.Kind == TokRParen {
 			return nil, &SyntaxError{Pos: t.Pos, Msg: "' must be followed by a value", Incomplete: next.Kind == TokEOF}
 		}
-		v, err := r.datum()
+		inner, err := r.datum()
 		if err != nil {
 			return nil, err
 		}
-		return r.record(List(Symbol("quote"), v), t.Pos), nil
+		// 'x is (quote x): a list whose first element is the quote mark.
+		quote := &Datum{Value: Symbol("quote"), Start: t.Pos, End: t.End}
+		d := &Datum{Value: List(quote.Value, inner.Value), Start: t.Pos, End: inner.End, Elems: []*Datum{quote, inner}}
+		r.record(d)
+		return d, nil
 	case TokLParen:
-		v, err := r.list(t.Pos)
+		d, err := r.list(t.Pos)
 		if err != nil {
 			return nil, err
 		}
-		return r.record(v, t.Pos), nil
+		d.Start, d.End = t.Pos, r.lastEnd
+		r.record(d)
+		return d, nil
 	case TokRParen:
 		return nil, &SyntaxError{Pos: t.Pos, Msg: "unexpected )"}
 	case TokDot:
@@ -118,8 +139,8 @@
 // list parses the rest of a list after its "(". Errors about a missing ")"
 // point at the "(" that opened the list, which is where the mistake usually
 // is.
-func (r *Reader) list(open Pos) (Value, error) {
-	var items []Value
+func (r *Reader) list(open Pos) (*Datum, error) {
+	var items []*Datum
 	for {
 		t, err := r.peek()
 		if err != nil {
@@ -130,32 +151,58 @@ 		case TokEOF:
 			return nil, &SyntaxError{Pos: open, Msg: "unterminated list", Incomplete: true}
 		case TokRParen:
 			r.next()
-			return List(items...), nil
+			return listDatum(items, nil, nil), nil
 		case TokDot:
 			if len(items) == 0 {
 				return nil, &SyntaxError{Pos: t.Pos, Msg: "a dotted pair needs a value before ."}
 			}
 			r.next()
-			return r.dottedTail(t.Pos, open, items)
+			dot := &Datum{Value: Symbol("."), Start: t.Pos, End: t.End, Dot: true}
+			return r.dottedTail(dot, open, items)
 		}
-		v, err := r.datum()
+		d, err := r.datum()
 		if err != nil {
 			return nil, err
 		}
-		items = append(items, v)
+		items = append(items, d)
 	}
 }
 
+// listDatum builds the datum for a list of items with an optional dotted
+// tail. A tail that is a list, or (), is no dotted pair: its elements just
+// continue this list, so they become this datum's elements too, and the
+// "." and the tail's own parentheses leave no datum behind.
+func listDatum(items []*Datum, dot, tail *Datum) *Datum {
+	d := &Datum{Elems: items}
+	values := make([]Value, len(items))
+	for i, item := range items {
+		values[i] = item.Value
+	}
+	if tail == nil {
+		d.Value = List(values...)
+		return d
+	}
+	d.Value = ListWithTail(tail.Value, values...)
+	switch tail.Value.(type) {
+	case *Pair:
+		d.Elems = append(d.Elems, tail.Elems...)
+	case Empty:
+	default:
+		d.Elems = append(d.Elems, dot, tail)
+	}
+	return d
+}
+
 // dottedTail parses the single value after "." and the ")" that must follow
 // it: a pair has exactly one cdr.
-func (r *Reader) dottedTail(dot, open Pos, items []Value) (Value, error) {
+func (r *Reader) dottedTail(dot *Datum, open Pos, items []*Datum) (*Datum, error) {
 	t, err := r.peek()
 	if err != nil {
 		return nil, err
 	}
 	switch t.Kind {
 	case TokRParen, TokEOF:
-		return nil, &SyntaxError{Pos: dot, Msg: "expected a value after .", Incomplete: t.Kind == TokEOF}
+		return nil, &SyntaxError{Pos: dot.Start, Msg: "expected a value after .", Incomplete: t.Kind == TokEOF}
 	case TokDot:
 		return nil, &SyntaxError{Pos: t.Pos, Msg: "only one . is allowed in a list"}
 	}
@@ -169,7 +216,7 @@ 		return nil, err
 	}
 	switch t.Kind {
 	case TokRParen:
-		return ListWithTail(tail, items...), nil
+		return listDatum(items, dot, tail), nil
 	case TokEOF:
 		return nil, &SyntaxError{Pos: open, Msg: "unterminated list", Incomplete: true}
 	case TokDot:
@@ -178,11 +225,11 @@ 	}
 	return nil, &SyntaxError{Pos: t.Pos, Msg: "expected ) after the value following ."}
 }
 
-func (r *Reader) record(v Value, pos Pos) Value {
-	if p, ok := v.(*Pair); ok {
-		r.positions[p] = pos
+// record remembers where a list starts, so errors can point at it.
+func (r *Reader) record(d *Datum) {
+	if p, ok := d.Value.(*Pair); ok {
+		r.positions[p] = d.Start
 	}
-	return v
 }
 
 // next and peek give the reader one token of lookahead, which is all this
@@ -191,8 +238,17 @@ func (r *Reader) next() (Token, error) {
 	if r.peeked != nil {
 		t := *r.peeked
 		r.peeked = nil
+		r.lastEnd = t.End
 		return t, nil
 	}
+	t, err := r.fetch()
+	if err == nil {
+		r.lastEnd = t.End
+	}
+	return t, err
+}
+
+func (r *Reader) fetch() (Token, error) {
 	for {
 		t, err := r.lex.Next()
 		if err != nil || t.Kind != TokComment {
@@ -204,7 +260,7 @@ }
 
 func (r *Reader) peek() (Token, error) {
 	if r.peeked == nil {
-		t, err := r.next()
+		t, err := r.fetch()
 		if err != nil {
 			return Token{}, err
 		}
diff --git a/sexpr/token.go b/sexpr/token.go
index 48e5f21260f5c2243243ad8cc21bd69071441d71..88fb8640f4f8b4b205e36ac8b9b4052cbb8ca806 100644
--- a/sexpr/token.go
+++ b/sexpr/token.go
@@ -61,6 +61,8 @@ type Token struct {
 	Kind TokenKind
 	Text string
 	Pos  Pos
+	// End is the position just after the token's last character.
+	End Pos
 }
 
 type SyntaxError struct {
@@ -116,6 +118,7 @@ 	t, err := l.next()
 	if err != nil {
 		l.err = err
 	}
+	t.End = l.pos
 	return t, err
 }