form: one projection, one constructor, and comments that say what code does

Answers four keel threads on bcfa3f6.

## the acrobatics

Taking a patch, splitting it into dotted keys, and rebuilding it against an
empty snapshot. Six sites did this to add one key. Patches compose with Merge:

	form.Merge(dress, form.Build(form.Snapshot{}, add, nil))

Outfit layering was the same shape at a larger scale: N patches decomposed to
key maps, unioned, rebuilt. It is a fold of Merge.

That rewrite also removed a silent bug. Leaves() returned a fresh map, so
p.Leaves()[k] = v wrote to a temporary and was discarded. Five sites did it,
including the aria_id and cwd stamps on every birth patch.

## the duplication

	removed  Leaves, Keys, Removes, IsEmpty, Creates, creationsOnly,
	         sortStrings, and four near-identical recursive walkers
	kept     Entries, Entry, Build

Entries walks the patch once and yields (path, before, after). Keys, removals
and set values are filters over it. IsEmpty was an alias for IsIdentity;
Creates was Build with an empty base.

patch.go: 220 lines removed, 59 added.

## comments

Removed the inline justifications, the capitals used for emphasis, and every
reference to how the code used to be. The git history holds that.

Author: gluck

api/form/diff.go

@@ -90,7 +90,7 @@ func diffList(a, b []KeyedValue) Patch {
 			out.Delete = append(out.Delete, it)
 		}
 	}
-	// The window is computed over the sequence AS APPLY WILL SEE IT: after
+	// The window is computed over the sequence AS Apply will see IT: after
 	// creates are appended and deletes removed. Both directions are computed
 	// here because only here are both orders in hand.
 	fwdFrom := intermediate(a, bi, out.Create)
@@ -136,13 +136,11 @@ func keysOf(items []KeyedValue) []string {
 	return out
 }
 
-// windowFor is the PARTIAL WINDOW transforming from into to: the positions
-// where they disagree, widened by one neighbour either side as an anchor.
+// windowFor is the window transforming from into to: the positions where they
+// disagree, widened by one neighbour either side as an anchor.
 //
-// The scan is linear, so moving one item a long way marks every key it passed
-// as moved -- those keys really are in different positions relative to the
-// survivors, and a scan cannot know which single move explains it. A known and
-// accepted approximation.
+// The scan is linear, so moving one item far marks every key it passed as
+// moved. A known approximation.
 func windowFor(from, to []string) *Order {
 	if len(from) != len(to) {
 		return nil

api/form/environment.go

@@ -54,5 +54,5 @@ func EnvironmentPatch() Patch {
 	if set == nil {
 		return Patch{}
 	}
-	return Creates(set)
+	return Build(Snapshot{}, set, nil)
 }

api/form/fold_test.go

@@ -47,7 +47,7 @@ func oldRenderLoop(s Snapshot, patches []Patch, tmpls *template.Template) ([]str
 func foldCorpus(t *testing.T) [][]Patch {
 	t.Helper()
 	set := func(kv ...string) Patch {
-		p := Creates(map[string]json.RawMessage{})
+		p := Build(Snapshot{}, map[string]json.RawMessage{}, nil)
 		for i := 0; i+1 < len(kv); i += 2 {
 			b, err := json.Marshal(kv[i+1])
 			if err != nil {
@@ -174,8 +174,8 @@ func TestFoldRenderSeesTheBoardBeforeEachPatch(t *testing.T) {
 	tmpls := orderSensitiveTemplates(t)
 	board := FromMap(map[string]json.RawMessage{"mantra": json.RawMessage(`"first"`)})
 	patches := []Patch{
-		Creates(map[string]json.RawMessage{"mantra": json.RawMessage(`"second"`)}),
-		Creates(map[string]json.RawMessage{"mantra": json.RawMessage(`"third"`)}),
+		Build(Snapshot{}, map[string]json.RawMessage{"mantra": json.RawMessage(`"second"`)}, nil),
+		Build(Snapshot{}, map[string]json.RawMessage{"mantra": json.RawMessage(`"third"`)}, nil),
 	}
 	var bodies []string
 	final := FoldRender(board, patches, tmpls,

api/form/form.go

@@ -12,7 +12,6 @@ import (
 // Snapshot is a structural view of an aria's board: a JSON object whose
 // members are the keys, nested where the keys nest.
 //
-// It was a FLAT map of dotted strings to opaque JSON, which made a dot a
 // convention nothing enforced and made every value below the first level
 // unreachable: changing one field of a 6.5KB credo rewrote the credo. The
 // dots address a tree now, and a patch reaches any node of it.
@@ -21,7 +20,6 @@ type Snapshot struct {
 }
 
 // Path is a key resolved to its segments. Dots address the tree; a segment
-// may itself contain a dot where the key was written that way, so a path is
 // resolved AGAINST a snapshot rather than parsed in isolation.
 type Path []string
 
@@ -51,11 +49,8 @@ func (s Snapshot) Root() Value {
 // FromValue wraps a root object as a snapshot.
 func FromValue(v Value) Snapshot { return Snapshot{root: v} }
 
-// Get returns the raw value at key and whether it was present.
-//
-// The key is resolved segment by segment, LONGEST MATCH FIRST at every level,
+// The key is resolved segment by segment, Longest match first at every level,
 // so a key whose own name contains a dot resolves to itself rather than to a
-// path that does not exist. That is what makes `skills.howto` and
 // `skills.howto.md` both addressable.
 func (s Snapshot) Get(key string) (json.RawMessage, bool) {
 	v, ok := s.resolve(key)
@@ -187,11 +182,15 @@ func (s Snapshot) Apply(p Patch) Snapshot {
 	return Snapshot{root: next}
 }
 
-// Additive keeps only what p would actually change on s. A patch that removes
-// is not additive, so removals are dropped and what remains is re-diffed
-// against s: whatever is left is genuinely new or genuinely different.
+// Additive keeps only what p would add to s. Removals are dropped.
 func Additive(s Snapshot, p Patch) Patch {
-	return s.Apply(p.creationsOnly()).Diff(s)
+	set := map[string]json.RawMessage{}
+	for _, e := range p.Entries() {
+		if !e.IsRemoval() {
+			set[e.Key] = e.New
+		}
+	}
+	return Build(s, set, nil)
 }
 
 // SetPath returns a snapshot with key set to v, creating intermediate objects.
@@ -287,7 +286,6 @@ func decodeRawObject(v Value) (map[string]json.RawMessage, bool) {
 // MarshalJSON emits the nested object: what the form channel holds on disk.
 func (s Snapshot) MarshalJSON() ([]byte, error) { return s.Root().Raw(), nil }
 
-// UnmarshalJSON reads the nested object. A FLAT board written before the tree
 // -- dotted keys at the top level -- is nested on read, so an old store opens
 // without a rewrite.
 func (s *Snapshot) UnmarshalJSON(data []byte) error {
@@ -330,8 +328,8 @@ func (e Entry) NewString() string { return decodeStringOrRaw(e.New) }
 // OldString is the entry's old value as a string, or "".
 func (e Entry) OldString() string { return decodeStringOrRaw(e.Old) }
 
-// PatchEntries flattens a patch to one entry per changed LEAF, against the
-// board as it stood before.
+// PatchEntries is the patch's entries resolved against the board it applies
+// to, so an entry that changes an existing key carries the value it replaces.
 func PatchEntries(p Patch, prev Snapshot) []Entry {
 	next := prev.Apply(p)
 	before := map[string]json.RawMessage{}

api/form/form_test.go

@@ -51,7 +51,7 @@ func TestDiff_NoChange(t *testing.T) {
 		"model": raw(t, "claude-opus-4-6"),
 	})
 	p := next.Diff(prev)
-	assert.True(t, p.IsEmpty(), "identical snapshots produce empty patch")
+	assert.True(t, p.IsIdentity(), "identical snapshots produce empty patch")
 }
 
 func TestDiff_AddSetRemove(t *testing.T) {

api/form/incantation_test.go

@@ -40,14 +40,14 @@ func TestStudyIncantationReadsEveryEvent(t *testing.T) {
 	if got.OnStudy != "watch it" || got.OnUpdate != "it moved" || got.OnDrop != "look away" {
 		t.Fatalf("all three events should carry their phrase, got %+v", got)
 	}
-	if got.IsEmpty() {
+	if got.IsIdentity() {
 		t.Fatal("a populated incantation reports itself empty")
 	}
 }
 
 func TestStudyIncantationAbsentIsSilentAndEmpty(t *testing.T) {
 	out := captureWarnings(t, func() {
-		if got := ReadStudyIncantation(Snapshot{}); !got.IsEmpty() {
+		if got := ReadStudyIncantation(Snapshot{}); !got.IsIdentity() {
 			t.Fatalf("no key should read as no incantation, got %+v", got)
 		}
 	})
@@ -85,7 +85,7 @@ func TestStudyIncantationWrongShapeIsRefusedWholesale(t *testing.T) {
 			out := captureWarnings(t, func() {
 				got = ReadStudyIncantation(boardWith(t, StudyIncantationKey, tc.raw))
 			})
-			if !got.IsEmpty() {
+			if !got.IsIdentity() {
 				t.Fatalf("a %s must not parse as an incantation: %+v", tc.name, got)
 			}
 			if !strings.Contains(out, tc.kind) {
@@ -104,7 +104,7 @@ func TestStudyIncantationNamesUnknownKeys(t *testing.T) {
 	board := boardWith(t, StudyIncantationKey, `{"onstudied":"watch it"}`)
 	var got StudyIncantation
 	out := captureWarnings(t, func() { got = ReadStudyIncantation(board) })
-	if !got.IsEmpty() {
+	if !got.IsIdentity() {
 		t.Fatalf("an unknown field must not become a phrase: %+v", got)
 	}
 	if !strings.Contains(out, "onstudied") || !strings.Contains(out, "onstudy") {
@@ -125,7 +125,7 @@ func TestForkIncantationWrongShapeIsRefused(t *testing.T) {
 	out := captureWarnings(t, func() {
 		got = ReadForkIncantation(boardWith(t, ForkIncantationKey, `["a","b"]`))
 	})
-	if !got.IsEmpty() {
+	if !got.IsIdentity() {
 		t.Fatalf("an array must not parse: %+v", got)
 	}
 	if !strings.Contains(out, "array") {
@@ -137,7 +137,7 @@ func TestForkIncantationWrongShapeIsRefused(t *testing.T) {
 // says less than nothing: it tells the model there was something to say.
 func TestIncantationTrimsAndDropsBlank(t *testing.T) {
 	s := ReadStudyIncantation(boardWith(t, StudyIncantationKey, `{"onstudy":"   "}`))
-	if !s.IsEmpty() {
+	if !s.IsIdentity() {
 		t.Fatalf("a blank phrase must be no phrase: %+v", s)
 	}
 	f := ReadForkIncantation(boardWith(t, ForkIncantationKey, `"  branched  "`))

api/form/legacy_test.go

@@ -15,7 +15,7 @@ func TestLegacyFlatPatchStillApplies(t *testing.T) {
 	raw := []byte(`{"set":{"system.model":"claude-opus-5","mantra":"hello","skills.howto":{"a":1}},"remove":["stale"]}`)
 	var p form.Patch
 	require.NoError(t, json.Unmarshal(raw, &p))
-	require.False(t, p.IsEmpty(), "a flat patch decoded to Identity: history would vanish")
+	require.False(t, p.IsIdentity(), "a flat patch decoded to Identity: history would vanish")
 
 	base := form.FromMap(map[string]json.RawMessage{"stale": json.RawMessage(`"x"`)})
 	got := base.Apply(p)