feat(pipeline): ingest revises the existing page instead of clobbering it (#103)

fix(wiki): give the preamble its own field instead of overloading heading=="" (#103)

Round 3 review: verified structurally that the preamble is no longer in the sections slice or the idx map, so it cannot collide with a degenerate `## ` heading. Flip-tested by reverting to the heading=="" model and confirming TestMerge_DegenerateEmptyHeadingDoesNotCollideWithPreamble goes red. Adversarial pass (multiple degenerate headings, frontmatter-only page, unicode around the ## boundary, 3x self-merge idempotency with preamble+degenerate) all held. CI green on 09aeaa9 (run 7820).

Co-authored-by: Mathias <mthbqv@gmail.com>

ingestion/internal/wiki/merge.go

@@ -29,12 +29,16 @@ type section struct {
 }
 
 // Merge combines two Page values with the same path.
-// Frontmatter is taken from a. Sections are merged by strategy:
-// bullet sections union unique lines, append sections concatenate,
-// all others keep a's version. Sections in b not present in a are appended.
+// Frontmatter is taken from a. The preamble (content before the first ##
+// heading) is taken from a — same "on-disk wins" default every unlisted
+// named section gets, kept as a separate field rather than a section with
+// an empty heading so it can never collide with one (see parseSections).
+// Sections are merged by strategy: bullet sections union unique lines,
+// append sections concatenate, all others keep a's version. Sections in b
+// not present in a are appended.
 func Merge(a, b Page) Page {
-	fmA, secsA := parseSections(a.Content)
-	_, secsB := parseSections(b.Content)
+	fmA, preambleA, secsA := parseSections(a.Content)
+	_, _, secsB := parseSections(b.Content)
 
 	idx := make(map[string]int, len(secsA))
 	for i, s := range secsA {
@@ -53,14 +57,24 @@ func Merge(a, b Page) Page {
 		case bulletSections[sB.heading]:
 			secsA[i].content = mergeBullets(sA.content, sB.content)
 		case appendSections[sB.heading]:
-			secsA[i].content = strings.TrimRight(sA.content, "\n") + "\n\n" + strings.TrimLeft(sB.content, "\n")
+			secsA[i].content = appendNew(sA.content, sB.content)
 		}
 	}
 
-	return Page{Path: a.Path, Content: rebuildContent(fmA, secsA)}
+	return Page{Path: a.Path, Content: rebuildContent(fmA, preambleA, secsA)}
 }
 
-func parseSections(markdown string) (frontmatter string, sections []section) {
+// parseSections splits markdown into its frontmatter, its preamble (content
+// before the first `## ` heading), and its `## `-headed sections.
+//
+// The preamble is returned separately rather than as a section with an
+// empty heading — a section keyed by heading=="" would collide with a
+// literal degenerate `## ` (marker, no title text; strings.TrimPrefix also
+// yields ""), which is a distinct, addressable section a page can genuinely
+// have, not the same thing as "no heading yet." Two entries sharing one key
+// in Merge's idx map means one of them silently loses lookup visibility —
+// found in review as real, reproducible data loss, not a hypothetical.
+func parseSections(markdown string) (frontmatter, preamble string, sections []section) {
 	lines := strings.Split(markdown, "\n")
 	i := 0
 
@@ -78,6 +92,22 @@ func parseSections(markdown string) (frontmatter string, sections []section) {
 		frontmatter = fmt.Sprintf("---\n%s\n---\n", strings.Join(fmLines, "\n"))
 	}
 
+	// Everything before the first `## ` heading — an intro paragraph, or, if
+	// the page has no headings at all, the entire body — is ordinary content,
+	// not something this parser is entitled to drop (hyperguild#103 review:
+	// dropping it meant Merge, one caller up, would silently replace the
+	// whole on-disk body with the fresh extraction whenever a page didn't
+	// follow the ## convention — exactly the class of bug this file exists
+	// to prevent).
+	var preambleLines []string
+	for ; i < len(lines); i++ {
+		if strings.HasPrefix(lines[i], "## ") {
+			break
+		}
+		preambleLines = append(preambleLines, lines[i])
+	}
+	preamble = strings.Join(preambleLines, "\n")
+
 	var cur *section
 	for ; i < len(lines); i++ {
 		line := lines[i]
@@ -96,24 +126,85 @@ func parseSections(markdown string) (frontmatter string, sections []section) {
 	return
 }
 
-func rebuildContent(frontmatter string, sections []section) string {
+// rebuildContent serialises sections back into a page.
+//
+// Each section body is normalised to exactly one trailing newline and no
+// leading blank line. Without that, a section keeps whatever blank lines it was
+// parsed with and this function adds its own, so every merge pass grows the page
+// by a blank line — invisible in a diff viewer, fatal to byte-stability. Compile-on-ingest
+// merges on every run, so "merging changes nothing when nothing changed" has to
+// hold at the byte level, not just the content level.
+func rebuildContent(frontmatter, preamble string, sections []section) string {
 	var sb strings.Builder
 	sb.WriteString(frontmatter)
+	if body := strings.Trim(preamble, "\n"); body != "" {
+		fmt.Fprintf(&sb, "\n%s\n", body)
+	}
 	for _, sec := range sections {
-		fmt.Fprintf(&sb, "\n## %s\n\n%s", sec.heading, sec.content)
+		body := strings.Trim(sec.content, "\n")
+		fmt.Fprintf(&sb, "\n## %s\n\n%s\n", sec.heading, body)
 	}
 	return sb.String()
 }
 
+// canonicalLine collapses a line to its comparison key: internal whitespace
+// runs (a re-extraction's bullet spacing, tabs vs spaces, trailing spaces)
+// must not make the same logical line look new. strings.Fields already
+// trims and splits on any whitespace run, so joining it back with single
+// spaces is exactly "same words, same order, whitespace-insensitive."
+func canonicalLine(line string) string {
+	return strings.Join(strings.Fields(line), " ")
+}
+
+// appendNew concatenates the lines of b that a does not already carry.
+//
+// Append sections used to concatenate wholesale, which is correct exactly once.
+// Compile-on-ingest merges a freshly extracted page into the one already on
+// disk, so an unchanged source re-ingested would grow "Open Questions" and
+// "Updates" on every run until the page is unreadable — and the drift guard
+// that would otherwise catch it (hashing the source body) does not exist yet,
+// so idempotency has to hold here rather than upstream.
+//
+// Line-level rather than block-level: the common case is a re-ingest carrying
+// one genuinely new line alongside several it already has. A block-level
+// "skip if identical" would duplicate the old lines every time that happened.
+//
+// The cost is that a line repeated verbatim on purpose collapses to one. For
+// these sections — questions, updates, evolving notes — a repeat is noise
+// rather than signal, and the failure is conservative: the page stops growing
+// instead of growing wrongly.
+func appendNew(a, b string) string {
+	seen := make(map[string]bool)
+	for _, line := range strings.Split(a, "\n") {
+		if c := canonicalLine(line); c != "" {
+			seen[c] = true
+		}
+	}
+
+	var add []string
+	for _, line := range strings.Split(b, "\n") {
+		c := canonicalLine(line)
+		if c == "" || seen[c] {
+			continue
+		}
+		seen[c] = true
+		add = append(add, line)
+	}
+	if len(add) == 0 {
+		return a // nothing new — leave the section byte-identical
+	}
+	return strings.TrimRight(a, "\n") + "\n\n" + strings.Join(add, "\n") + "\n"
+}
+
 func mergeBullets(a, b string) string {
 	seen := make(map[string]bool)
 	var lines []string
 	for _, line := range strings.Split(a+b, "\n") {
-		trimmed := strings.TrimSpace(line)
-		if trimmed == "" || seen[trimmed] {
+		c := canonicalLine(line)
+		if c == "" || seen[c] {
 			continue
 		}
-		seen[trimmed] = true
+		seen[c] = true
 		lines = append(lines, line)
 	}
 	return strings.Join(lines, "\n") + "\n"