fix(zettel_id_log): emit single hyphence header instead of stacked docs

Closes #212.

`AppendEntry` previously wrapped every entry in a fresh
`hyphence.TypedBlob` and emitted `Coder.EncodeTo` for it, so every
append re-wrote the `---\n! zettel_id_log-v1\n---\n` preamble. The
file ended up as stacked hyphence docs: 2 yin/yang entries from init
-> 2 type headers; N more appends -> N more headers.

The on-disk shape now mirrors the sibling `inventory_lists_log`:

  ---
  ! zettel_id_log-v1
  ---

  side = "yin"
  tai = "..."
  markl-id = "..."
  word-count = 6

  side = "yang"
  tai = "..."
  markl-id = "..."
  word-count = 6

A single header at the top of the file, then bodies appended below
with blank-line separation.

## Writer

`AppendEntry` stats the file after the `O_CREATE|O_APPEND|O_WRONLY`
open. Size 0 means a fresh file: emit the header preamble then the
body. Size > 0 means an existing log: emit a `\n` separator then the
body only. Callers (`genesis.go`, `add_zettel_ids.go`,
`migrate_zettel_ids.go`) don't need to know about the header --- the
first append into a fresh file lays it down.

The type-header line is `! <type-without-prefix>`. The
`TypeZettelIdLogVCurrent` constant carries the leading `!`
(e.g. `!zettel_id_log-v1`), so we `strings.TrimPrefix` to avoid
emitting `! !zettel_id_log-v1`.

`encodeEntryBody` calls `charlie_zil.V1Document.Encode` directly to
get the TOML key/value bytes without any surrounding hyphence
framing. Replaces the old per-entry `Coder.EncodeTo(&hyphence.TypedBlob)`
that pulled in the full header.

## Reader

`ReadAllEntries` keeps back-compat with the v14 / v15 stacked-doc
fixtures via a new line-driven `segmentBodies` helper:

- A `---` line toggles an `inHeader` state.
- Lines while `inHeader` (e.g. `! zettel_id_log-v1`) are discarded.
- Non-empty non-header lines accumulate into the current body.
- A blank line flushes the current body and starts the next.
- Opening a new header also flushes (so stacked-doc entries split
  at the inter-entry preamble).

Both shapes parse to the same body sequence with no per-shape branch.

## Verification

New BATS file `zz-tests_bats/current_version/zettel_id_log_format.bats`
asserts the on-disk contract:

  zettel_id_log_has_single_header_after_init           # 1 header after init
  zettel_id_log_has_single_header_after_add_zettel_ids # 1 header after init + add
  inventory_lists_log_has_single_header                # pins the working sibling

All three pass.

The existing `add_zettel_ids.bats` (5 tests) and `migrate_zettel_ids.bats`
(2 tests) also pass --- the new dual-shape reader handles both fresh
single-header logs and v14/v15 stacked-doc fixtures.

:clown:

Author: sfriedenberg-etsy

go/internal/delta/zettel_id_log/log.go

@@ -2,13 +2,15 @@ package zettel_id_log
 
 import (
 	"bufio"
+	"fmt"
+	"io"
 	"os"
 	"strings"
 
+	charlie_zil "code.linenisgreat.com/dodder/go/internal/charlie/zettel_id_log"
 	"code.linenisgreat.com/dodder/go/internal/bravo/ids"
 	"code.linenisgreat.com/dodder/go/lib/alfa/ohio"
 	"github.com/amarbel-llc/madder/go/pkgs/hyphence"
-	"github.com/amarbel-llc/purse-first/libs/dewey/alfa/pool"
 	"github.com/amarbel-llc/purse-first/libs/dewey/bravo/errors"
 	"github.com/amarbel-llc/purse-first/libs/dewey/delta/files"
 )
@@ -17,6 +19,16 @@ type Log struct {
 	Path string
 }
 
+// AppendEntry appends `entry` to the log on disk. The first call against
+// an empty (or nonexistent) file writes a single hyphence header
+// (`---\n! zettel_id_log-vN\n---\n`) followed by the entry body.
+// Subsequent calls append just a body, separated from prior content by a
+// blank line.
+//
+// Background: an earlier implementation wrapped every entry in a fresh
+// hyphence TypedBlob and emitted the full header per call, producing
+// stacked hyphence docs on disk (amarbel-llc/dodder#212). The reader
+// here keeps back-compat for those legacy files.
 func (l Log) AppendEntry(entry Entry) (err error) {
 	var file *os.File
 
@@ -31,19 +43,82 @@ func (l Log) AppendEntry(entry Entry) (err error) {
 
 	defer errors.DeferredCloser(&err, file)
 
-	typedBlob := &hyphence.TypedBlob[Entry]{
-		Type: ids.GetOrPanic(ids.TypeZettelIdLogVCurrent).TypeStruct.ToMadder(),
-		Blob: entry,
+	var stat os.FileInfo
+
+	if stat, err = file.Stat(); err != nil {
+		err = errors.Wrap(err)
+		return err
+	}
+
+	if stat.Size() == 0 {
+		// The type constant already carries a leading `!`
+		// (e.g. `!zettel_id_log-v1`). Hyphence's type-header line is
+		// `! <type-without-prefix>`, so strip the prefix before
+		// printing — otherwise we'd emit `! !zettel_id_log-v1`.
+		typeName := strings.TrimPrefix(
+			ids.TypeZettelIdLogVCurrent,
+			"!",
+		)
+
+		if _, err = fmt.Fprintf(
+			file,
+			"%s\n! %s\n%s\n\n",
+			hyphence.Boundary,
+			typeName,
+			hyphence.Boundary,
+		); err != nil {
+			err = errors.Wrap(err)
+			return err
+		}
+	} else {
+		// Blank-line separator between bodies.
+		if _, err = io.WriteString(file, "\n"); err != nil {
+			err = errors.Wrap(err)
+			return err
+		}
 	}
 
-	if _, err = Coder.EncodeTo(typedBlob, file); err != nil {
+	var body []byte
+
+	if body, err = encodeEntryBody(entry); err != nil {
+		err = errors.Wrap(err)
+		return err
+	}
+
+	if _, err = file.Write(body); err != nil {
 		err = errors.Wrap(err)
 		return err
 	}
 
 	return err
 }
 
+// encodeEntryBody returns the body-only encoding of an entry — the TOML
+// key/value block, with no surrounding hyphence boundaries or type
+// header. Mirrors what `charlie_zil.V1Document.Encode` returns directly.
+func encodeEntryBody(entry Entry) ([]byte, error) {
+	doc, err := charlie_zil.DecodeV1(nil)
+	if err != nil {
+		return nil, errors.Wrap(err)
+	}
+
+	switch v := entry.(type) {
+	case *V1:
+		*doc.Data() = *v
+	case V1:
+		*doc.Data() = v
+	default:
+		return nil, errors.Errorf("unsupported entry type %T", entry)
+	}
+
+	body, err := doc.Encode()
+	if err != nil {
+		return nil, errors.Wrap(err)
+	}
+
+	return body, nil
+}
+
 func (l Log) ReadAllEntries() (entries []Entry, err error) {
 	var file *os.File
 
@@ -59,64 +134,91 @@ func (l Log) ReadAllEntries() (entries []Entry, err error) {
 
 	defer errors.DeferredCloser(&err, file)
 
-	bufferedReader, repoolBufferedReader := pool.GetBufferedReader(file)
-	defer repoolBufferedReader()
+	bufferedReader := bufio.NewReader(file)
 
-	segments, err := segmentEntries(bufferedReader)
+	bodies, err := segmentBodies(bufferedReader)
 	if err != nil {
 		err = errors.Wrap(err)
 		return entries, err
 	}
 
-	for _, segment := range segments {
-		var typedBlob hyphence.TypedBlob[Entry]
-
-		stringReader, repoolStringReader := pool.GetStringReader(segment)
-		defer repoolStringReader()
-
-		if _, err = Coder.DecodeFrom(
-			&typedBlob,
-			stringReader,
-		); err != nil {
-			err = errors.Wrap(err)
-			return entries, err
+	for _, body := range bodies {
+		doc, err := charlie_zil.DecodeV1([]byte(body))
+		if err != nil {
+			return entries, errors.Wrap(err)
 		}
 
-		entries = append(entries, typedBlob.Blob)
+		v := *doc.Data()
+		entries = append(entries, v)
 	}
 
 	return entries, err
 }
 
-func segmentEntries(
-	reader *bufio.Reader,
-) (segments []string, err error) {
+// segmentBodies reads a zettel_id_log file and returns the entry bodies
+// (TOML key/value blocks) in order, ignoring any hyphence headers.
+//
+// Handles both the current single-header shape and the legacy stacked-
+// doc shape (amarbel-llc/dodder#212):
+//
+//   - Current shape: file starts with `---\n! zettel_id_log-v1\n---\n`,
+//     then bodies separated by blank lines.
+//   - Legacy shape: each body is preceded by its own `---\n! type\n---\n`
+//     preamble.
+//
+// In both cases, this function strips header preambles and groups
+// non-blank, non-header lines into bodies.
+func segmentBodies(reader *bufio.Reader) (bodies []string, err error) {
 	var current strings.Builder
-	boundaryCount := 0
+
+	flush := func() {
+		if current.Len() == 0 {
+			return
+		}
+		bodies = append(bodies, current.String())
+		current.Reset()
+	}
+
+	// State machine: skip header preambles (`---`...`---`) and collect
+	// body lines until a blank line or the next header.
+	inHeader := false
 
 	for line, errIter := range ohio.MakeLineSeqFromReader(reader) {
 		if errIter != nil {
 			err = errIter
-			return segments, err
+			return bodies, err
 		}
 
-		trimmed := strings.TrimSuffix(line, "\n")
+		trimmedRight := strings.TrimSuffix(line, "\n")
+
+		if trimmedRight == hyphence.Boundary {
+			if inHeader {
+				// Closing boundary of a header.
+				inHeader = false
+			} else {
+				// Opening boundary of a header — finalize any
+				// previous body first.
+				flush()
+				inHeader = true
+			}
+			continue
+		}
 
-		if trimmed == hyphence.Boundary {
-			boundaryCount++
+		if inHeader {
+			// Header content (e.g. `! zettel_id_log-v1`); ignore.
+			continue
+		}
 
-			if boundaryCount > 2 && boundaryCount%2 == 1 {
-				segments = append(segments, current.String())
-				current.Reset()
-			}
+		if trimmedRight == "" {
+			// Blank line — body separator in the new shape.
+			flush()
+			continue
 		}
 
 		current.WriteString(line)
 	}
 
-	if current.Len() > 0 {
-		segments = append(segments, current.String())
-	}
+	flush()
 
-	return segments, err
+	return bodies, err
 }

zz-tests_bats/current_version/zettel_id_log_format.bats

@@ -0,0 +1,139 @@
+#! /usr/bin/env bats
+
+setup() {
+	load "$(dirname "$BATS_TEST_FILE")/../lib/common.bash"
+
+	# for shellcheck SC2154
+	export output
+}
+
+teardown() {
+	chflags_nouchg
+}
+
+# bats file_tags=user_story:zettel_ids,format
+
+# The zettel_id_log is an append-only log of provider word-list mutations
+# (yin / yang inits and add-zettel-ids-* operations). The on-disk shape
+# should mirror the existing inventory_lists_log: exactly one hyphence
+# header at the top of the file (`---\n! <type>\n---\n`), then a blank
+# line, then one entry per line (or per record) appended below.
+#
+# The bug today is that go/internal/delta/zettel_id_log/log.go's
+# AppendEntry wraps each entry in a fresh hyphence.TypedBlob and emits
+# `Coder.EncodeTo` for it, so every append re-writes the type header.
+# The resulting file is stacked hyphence docs, not header + body. The
+# reader (segmentEntries in the same file) compensates by detecting
+# every odd boundary as a new entry, but the wire shape is wrong.
+#
+# These tests pin the *desired* shape: exactly one `! zettel_id_log-*`
+# line in the whole file regardless of entry count. They fail today and
+# pass when the writer is reshaped to "emit header on file creation,
+# then append bodies only" (or equivalent).
+#
+# Companion test: inventory_lists_log_has_single_header is the
+# inverse — it pins the working contract of the inventory log so we
+# notice if it ever drifts to the broken shape.
+
+function zettel_id_log_path {
+	echo "$PWD/.dodder/local/share/zettel_id_log"
+}
+
+function inventory_lists_log_path {
+	echo "$PWD/.dodder/local/share/inventory_lists_log"
+}
+
+function zettel_id_log_has_single_header_after_init { # @test
+	wd="$(mktemp -d)"
+	cd "$wd" || exit 1
+
+	run_dodder_init_disable_age
+
+	path="$(zettel_id_log_path)"
+	if [[ ! -f $path ]]; then
+		fail <<-EOM
+		expected zettel_id_log at $path
+
+		directory listing under .dodder/local/share/:
+		$(find .dodder/local/share -type f 2>&1 | sort)
+		EOM
+	fi
+
+	# Init writes a yin entry and a yang entry. The broken writer emits
+	# two full hyphence frames (two type headers). The desired shape has
+	# exactly one type header at the top of the file.
+	local header_count
+	# `grep -c` exits nonzero on zero matches; tolerate that so we can
+	# fail with a useful diagnostic instead of bailing here under set -e.
+	header_count="$(grep -c '^! zettel_id_log' "$path" || true)"
+
+	if [[ $header_count -ne 1 ]]; then
+		fail <<-EOM
+		zettel_id_log should have exactly 1 type-header line; got $header_count
+		path: $path
+		full content:
+		$(cat "$path")
+		EOM
+	fi
+}
+
+function zettel_id_log_has_single_header_after_add_zettel_ids { # @test
+	wd="$(mktemp -d)"
+	cd "$wd" || exit 1
+
+	run_dodder_init_disable_age
+
+	# Append a third entry so the bug (re-emitted header per append) is
+	# extra obvious: 3 entries -> 3 headers under the broken writer.
+	run bash -c 'echo -e "alpha\nbravo" | '"$DODDER_BIN"' add-zettel-ids-yin'
+	assert_success
+
+	path="$(zettel_id_log_path)"
+	local header_count
+	# `grep -c` exits nonzero on zero matches; tolerate that so we can
+	# fail with a useful diagnostic instead of bailing here under set -e.
+	header_count="$(grep -c '^! zettel_id_log' "$path" || true)"
+
+	if [[ $header_count -ne 1 ]]; then
+		fail <<-EOM
+		zettel_id_log should have exactly 1 type-header line after init + add-zettel-ids-yin; got $header_count
+		path: $path
+		full content:
+		$(cat "$path")
+		EOM
+	fi
+}
+
+function inventory_lists_log_has_single_header { # @test
+	# Inverse of the zettel_id_log tests: pin the inventory log's
+	# already-correct shape so we notice if it ever regresses to the
+	# stacked-doc format.
+	wd="$(mktemp -d)"
+	cd "$wd" || exit 1
+
+	run_dodder_init_disable_age
+
+	create_test_zettels
+
+	path="$(inventory_lists_log_path)"
+	if [[ ! -f $path ]]; then
+		fail <<-EOM
+		expected inventory_lists_log at $path
+
+		directory listing under .dodder/local/share/:
+		$(find .dodder/local/share -type f 2>&1 | sort)
+		EOM
+	fi
+
+	local header_count
+	header_count="$(grep -c '^! inventory_list' "$path")"
+
+	if [[ $header_count -ne 1 ]]; then
+		fail <<-EOM
+		inventory_lists_log should have exactly 1 type-header line; got $header_count
+		path: $path
+		full content:
+		$(cat "$path")
+		EOM
+	fi
+}