@zalom/plastic 1.0.0-beta.2 → 1.0.0-beta.21

package/scripts/lib/link_suggestions.rb

@@ -0,0 +1,322 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# LinkSuggestions - support links decided by CONTEXT INFLUENCE (intent 91, D7), not
+# by shared files, shared symbols, or a topic-similarity score. A script cannot judge
+# whether one intent's context influenced another (that is reasoning over meaning), so
+# this helper does NOT grade. It only:
+#
+#   - gather:      DISCOVERY. Find candidate intents (via an injected candidate-finder)
+#                  and surface each candidate's `## Intent` + `## Context` as the
+#                  EVIDENCE an agent reads to judge influence.
+#   - record_edge: record a CONFIRMED `sources`/`chain` frontmatter edge AND append a
+#                  line to `link-decisions.md` (utc, target, edge, rating, reason).
+#                  Append-only, frontmatter block only, never a `## Links` line,
+#                  never a delete. A no-op without confirm: true.
+#   - drift:       flag any `## Links` wikilink with no matching frontmatter edge.
+#
+# Two systems frame this:
+#   - System for Brain: links are tiered by context influence (sources = foundational
+#     context that shaped creation; chain = the genuinely delivery-moving context, a
+#     HIGH bar; tags = loose theme grouping, not a link). The influence judgement is
+#     made by an agent, not here.
+#   - System for Work (Convention over Configuration): `## Links` is a derived view of
+#     `sources`/`chain`. This helper never authors a `## Links` line and never deletes.
+#
+# Design rules: all collaborators are injected via the constructor (the store dir, a
+# filesystem reader, AND a candidate-finder). No eval, no ENV / global config seam.
+# Reuses IntentValidator.parse_frontmatter; does NOT touch LinksProjection /
+# LinksSection / project-links / doctor.
+
+require "time"
+require_relative "intent_validator"
+
+class LinkSuggestions
+  # One discovery candidate plus the evidence an agent reads to judge influence.
+  Candidate = Struct.new(:id, :basename, :label, :intent, :context, keyword_init: true)
+
+  # A drift finding: a `## Links` ref with no matching `sources`/`chain` edge.
+  Drift = Struct.new(:ref, :detail, keyword_init: true)
+
+  RATINGS = %w[high medium low].freeze
+
+  # A minimal default filesystem reader. Injected so tests can substitute an
+  # in-memory map; the production path reads real files. No global state.
+  class DiskReader
+    def directory?(path)
+      File.directory?(path)
+    end
+
+    def children(path)
+      Dir.children(path)
+    end
+
+    def exist?(path)
+      File.exist?(path)
+    end
+
+    def read(path)
+      File.read(path)
+    end
+
+    def write(path, content)
+      File.write(path, content)
+    end
+  end
+
+  # Default candidate-finder: a cheap discovery net (NOT a grade) over the loaded
+  # nodes - candidates that share a non-project tag, share a `sources` parent/family,
+  # or sit at an adjacent id. The CLI may inject a QMD-backed finder instead. Either
+  # way this is DISCOVERY ONLY; influence is judged later by an agent.
+  class FamilyTagFinder
+    def call(subject_id, nodes)
+      subject = nodes[subject_id]
+      return [] unless subject
+
+      nodes.keys.select do |other_id|
+        next false if other_id == subject_id
+
+        other = nodes[other_id]
+        shares_tag?(subject, other) || shares_family?(subject, other) ||
+          adjacent_id?(subject_id, other_id)
+      end
+    end
+
+    private
+
+    def shares_tag?(subject, other)
+      !(link_tags(subject) & link_tags(other)).empty?
+    end
+
+    def link_tags(node)
+      node[:tags].reject { |t| t.start_with?("project-") }
+    end
+
+    def shares_family?(subject, other)
+      return true unless (subject[:sources] & other[:sources]).empty?
+
+      subject[:sources].include?(other[:id]) || other[:sources].include?(subject[:id])
+    end
+
+    # Adjacent ids (discovery hint only): equal non-numeric prefix with integers
+    # differing by 1 (9<->10, 99<->100, 90<->91), or a letter successor at the same
+    # depth (66a<->66b). This is NOT a grade; it only widens the candidate net.
+    def adjacent_id?(a, b)
+      return false if a == b || a.empty? || b.empty?
+
+      ma = a.match(/\A(.*?)(\d+)\z/)
+      mb = b.match(/\A(.*?)(\d+)\z/)
+      return (ma[2].to_i - mb[2].to_i).abs == 1 if ma && mb && ma[1] == mb[1]
+
+      return false unless a.length == b.length
+
+      a[0..-2] == b[0..-2] && a[-1].match?(/[a-z]/) && b[-1].match?(/[a-z]/) &&
+        (a[-1].succ == b[-1] || b[-1].succ == a[-1])
+    end
+  end
+
+  # store_dir - the directory holding `id--slug/` intent folders for ONE store.
+  # reader    - injected filesystem collaborator (DiskReader by default).
+  # finder    - injected candidate-finder responding to #call(subject_id, nodes).
+  def initialize(store_dir:, reader: DiskReader.new, finder: FamilyTagFinder.new)
+    @store_dir = store_dir
+    @reader = reader
+    @finder = finder
+  end
+
+  attr_reader :store_dir, :reader, :finder
+
+  # Load every intent in the store as a node Hash keyed by id:
+  #   { id => { id:, basename:, label:, path:, dir:, sources:[], chain:[], tags:[],
+  #             links_refs:[], intent:, context: } }
+  def load_nodes
+    nodes = {}
+    return nodes unless reader.directory?(store_dir)
+
+    reader.children(store_dir).reject { |e| e.start_with?(".") }.sort.each do |entry|
+      dir = File.join(store_dir, entry)
+      next unless reader.directory?(dir)
+
+      md = File.join(dir, "#{entry}.md")
+      next unless reader.exist?(md)
+
+      content = reader.read(md)
+      fm = IntentValidator.parse_frontmatter_text(content)
+      next unless fm.is_a?(Hash) && fm["id"]
+
+      id = fm["id"].to_s
+      body = IntentValidator.body_of(content)
+      nodes[id] = {
+        id: id,
+        basename: entry,
+        label: fm["intent"].to_s.strip,
+        path: md,
+        dir: dir,
+        sources: Array(fm["sources"]).map(&:to_s),
+        chain: Array(fm["chain"]).map(&:to_s),
+        tags: Array(fm["tags"]).map(&:to_s),
+        links_refs: links_refs(body),
+        intent: section_text(body, "Intent"),
+        context: section_text(body, "Context"),
+      }
+    end
+    nodes
+  end
+
+  # DISCOVERY. The candidate intents for `subject_id`, each carrying its Intent +
+  # Context as the evidence an agent reads to judge influence. No grading. Sorted by
+  # natural id order for stable output.
+  def gather(subject_id, nodes: load_nodes)
+    return [] unless nodes.key?(subject_id)
+
+    ids = finder.call(subject_id, nodes)
+    ids.uniq.sort_by { |id| natural_key(id) }.filter_map do |id|
+      node = nodes[id]
+      next unless node
+
+      Candidate.new(id: id, basename: node[:basename], label: node[:label],
+                    intent: node[:intent], context: node[:context])
+    end
+  end
+
+  # Record a single CONFIRMED edge from `subject_id` to `target_id`:
+  #   1. append `target_id` to the subject's frontmatter `sources` or `chain`;
+  #   2. append a line to `link-decisions.md` in the subject dir capturing
+  #      {utc, target, edge, rating, reason}.
+  # Append-only, frontmatter block only. NEVER writes a `## Links` line, NEVER
+  # deletes. A no-op (returns false) without confirm: true, so a default run mutates
+  # nothing. Returns true when it wrote, false when it declined or the edge existed.
+  def record_edge(subject_id, target_id, edge:, rating: nil, reason: nil,
+                  confirm: false, now: Time.now, nodes: load_nodes)
+    return false unless confirm
+    return false unless %i[sources chain].include?(edge)
+
+    subject = nodes[subject_id]
+    return false unless subject
+    return false if subject[edge].include?(target_id)
+
+    content = reader.read(subject[:path])
+    updated = add_frontmatter_ref(content, edge.to_s, target_id)
+    return false if updated == content
+
+    reader.write(subject[:path], updated)
+    append_decision(subject, target_id, edge, rating, reason, now)
+    true
+  end
+
+  # DRIFT. The `## Links` refs on `subject_id` with no matching `sources`/`chain`
+  # frontmatter edge behind them. Fence-skipping is honored so a `[[id]]` inside an
+  # example code block is not flagged.
+  def drift(subject_id, nodes: load_nodes)
+    subject = nodes[subject_id]
+    return [] unless subject
+
+    edges = (subject[:sources] + subject[:chain]).map { |r| bare_ref(r) }
+    subject[:links_refs].reject { |r| edges.include?(bare_ref(r)) }.map do |ref|
+      Drift.new(ref: ref,
+                detail: "`## Links` references #{ref} with no sources/chain edge behind it")
+    end
+  end
+
+  private
+
+  # Append one decision line to `link-decisions.md` in the subject's dir, creating the
+  # ledger with a header when absent. Append-only; never rewrites prior lines.
+  def append_decision(subject, target_id, edge, rating, reason, now)
+    ledger = File.join(subject[:dir], "link-decisions.md")
+    stamp = now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+    line = "#{stamp} | #{target_id} | #{edge} | #{rating || "-"} | #{reason || "-"}"
+
+    if reader.exist?(ledger)
+      existing = reader.read(ledger)
+      reader.write(ledger, existing.rstrip + "\n" + line + "\n")
+    else
+      header = "# Link decisions (intent 91 D6): utc | target | edge | rating | reason\n\n"
+      reader.write(ledger, header + line + "\n")
+    end
+  end
+
+  # Natural sort key for ids so 2 sorts before 10 and 14a groups with 14.
+  def natural_key(id)
+    id.scan(/\d+|[a-z]+/).map { |part| part.match?(/\d/) ? [0, part.to_i, ""] : [1, 0, part] }
+  end
+
+  # Strip a `store:` prefix from a ref so a cross-store and same-store form compare.
+  def bare_ref(ref)
+    ref.to_s.include?(":") ? ref.to_s.split(":", 2).last : ref.to_s
+  end
+
+  # Extract bare-id wikilink refs from a body's `## Links` section. Matches
+  # `[[<id>--<slug>|...]]` and `[[<store>:<id>--<slug>|...]]`, yielding the bare id.
+  # Reads only the Links section so example fences elsewhere are not scanned.
+  def links_refs(body)
+    section = section_text(body, "Links")
+    return [] if section.empty?
+
+    section.scan(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/).filter_map do |match|
+      t = bare_ref(match.first.strip)
+      id = t.split("--", 2).first
+      id unless id.nil? || id.empty?
+    end.uniq
+  end
+
+  # The text under the first `## <heading>` heading, up to the next `## ` heading. A
+  # deliberately small reader since we only need the section content. Fence lines are
+  # skipped so a `## Links` (or any heading) inside an example block is ignored.
+  def section_text(body, heading)
+    lines = body.to_s.lines
+    out = []
+    capture = false
+    in_fence = false
+    lines.each do |line|
+      stripped = line.strip
+      if stripped.start_with?("```")
+        in_fence = !in_fence
+        next
+      end
+      next if in_fence
+
+      if stripped == "## #{heading}"
+        capture = true
+        next
+      end
+      break if capture && stripped.start_with?("## ")
+
+      out << line if capture
+    end
+    out.join.strip
+  end
+
+  # Append a ref to a frontmatter array (`sources` or `chain`), creating the key if
+  # absent. Touches ONLY the frontmatter block; the body (including `## Links`) is
+  # left byte-identical. Inline-flow arrays (`key: ["a", "b"]`) are extended in place;
+  # an absent key is inserted before the closing `---`. Never deletes.
+  def add_frontmatter_ref(content, key, ref)
+    return content unless content.start_with?("---")
+
+    parts = content.split("---", 3)
+    return content if parts.length < 3
+
+    fm = parts[1]
+    line_re = /^#{Regexp.escape(key)}:\s*(.*)$/
+    if fm =~ line_re
+      current = Regexp.last_match(1).strip
+      new_line = extend_flow_array(key, current, ref)
+      fm = fm.sub(line_re, new_line)
+    else
+      fm = fm.rstrip + "\n#{key}: [\"#{ref}\"]\n"
+    end
+    "---#{fm}---#{parts[2]}"
+  end
+
+  def extend_flow_array(key, current, ref)
+    if current.empty? || current == "[]"
+      %(#{key}: ["#{ref}"])
+    elsif current.start_with?("[") && current.end_with?("]")
+      inner = current[1..-2].strip
+      inner.empty? ? %(#{key}: ["#{ref}"]) : %(#{key}: [#{inner}, "#{ref}"])
+    else
+      %(#{key}: ["#{ref}"])
+    end
+  end
+end

package/scripts/lib/links_projection.rb

@@ -0,0 +1,160 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# LinksProjection — pure logic that projects one intent's sources/chain graph into
+# the canonical I5 `## Links` section text (intent 72). Mirrors the pure-module
+# style of GraphRebuild: module-function helpers, no file IO, no eval, no
+# ENV/global state. The IO shell (scripts/project-links) and doctor build the
+# cross-store resolver and feed it here.
+#
+# Pinned canonical projection (the human's format call):
+#   1. ORDERING (load-bearing): ALL sources first, in frontmatter order, THEN all
+#      chain, in frontmatter order. Sources can NEVER appear at the end. No group
+#      headings, no per-entry source/chain tags: the ordering carries the meaning.
+#   2. ENTRY SHAPE: one list item `- [[<id>--<slug>|<target's full intent: text>]]`,
+#      where the wikilink TARGET is the target intent's resolvable `id--slug` file
+#      basename (so it clicks through in Obsidian) and the LABEL is the target's
+#      full `intent:` frontmatter text, whitespace-trimmed.
+#   3. CROSS-STORE: a cross-store target renders
+#      `- [[<store>:<id>--<slug>|<target's full intent: text>]]`.
+#   4. RESOLVER MISS: a ref that resolves to no intent raises UnresolvedRef. No
+#      bare-id, slug-less, or guessed link is ever emitted.
+#   5. EMPTY-STATE: empty sources AND chain yields the heading plus a single
+#      explanatory comment.
+module LinksProjection
+  module_function
+
+  HEADING = "## Links"
+  EMPTY_COMMENT = "<!-- No sources or chain; this intent has no graph edges to project. -->"
+
+  # Raised when a sources/chain ref resolves to no intent. Carries the offending
+  # ref so the IO shell can report it per-intent and skip the write.
+  class UnresolvedRef < StandardError
+    attr_reader :ref
+
+    def initialize(ref)
+      @ref = ref
+      super("unresolved sources/chain ref: #{ref.inspect}")
+    end
+  end
+
+  # PURE. Build the canonical `## Links` section text for one intent.
+  #
+  #   sources — array of id / `store:id` ref strings, in frontmatter order
+  #   chain   — array of id / `store:id` ref strings, in frontmatter order
+  #   resolve — a callable (`->(ref) { ... }`) mapping ONE ref to a Hash like
+  #             { target: "<id>--<slug>",            label: "<full intent: text>" } or
+  #             { target: "<store>:<id>--<slug>",    label: "<full intent: text>" }.
+  #             Returning nil (or a Hash lacking :target) signals no target and
+  #             raises UnresolvedRef. Keeping resolution injected keeps this module
+  #             pure and hermetically testable with in-memory maps.
+  #
+  # Returns the full section text: the `## Links` heading line, one entry line per
+  # ref (sources first, then chain), and a single trailing newline. The empty case
+  # returns the heading + the empty-state comment + a single trailing newline.
+  def section(sources:, chain:, resolve:)
+    src = Array(sources).map(&:to_s)
+    chn = Array(chain).map(&:to_s)
+
+    # Resolve EVERY ref to its { target:, label: } first, then dedup by the RESOLVED
+    # target (not the raw ref string). This is load-bearing: the same intent may be
+    # referenced as a bare id in one group and as `store:id` in another (or via a
+    # relocation), which dedups identically only AFTER resolution. Sources win
+    # (formative edge), and frontmatter order is preserved within each group.
+    seen = {}
+    rendered = []
+    src.each { |ref| add_entry(ref, resolve, seen, rendered) }
+    chn.each { |ref| add_entry(ref, resolve, seen, rendered) }
+
+    return empty_section if rendered.empty?
+
+    (["#{HEADING}\n"] + rendered.map { |line| "#{line}\n" }).join
+  end
+
+  # PURE. The canonical empty-state section: heading + the single comment line.
+  def empty_section
+    "#{HEADING}\n#{EMPTY_COMMENT}\n"
+  end
+
+  # Resolve `ref`, render its entry, and append it to `rendered` UNLESS its resolved
+  # target was already emitted (dedup by resolved target, first-seen wins so sources
+  # precede chain). Mutates `seen` and `rendered`. Raises UnresolvedRef on a miss.
+  def add_entry(ref, resolve, seen, rendered)
+    target, label = resolve_entry(ref, resolve)
+    return if seen.key?(target)
+
+    seen[target] = true
+    rendered << "- [[#{target}|#{label}]]"
+  end
+
+  # PURE. Resolve one ref to [target, label]. Raises UnresolvedRef when the
+  # resolver returns nothing usable.
+  def resolve_entry(ref, resolve)
+    resolved = resolve.call(ref)
+    target = resolved.is_a?(Hash) ? resolved[:target] || resolved["target"] : nil
+    raise UnresolvedRef, ref if target.nil? || target.to_s.strip.empty?
+
+    label = (resolved[:label] || resolved["label"]).to_s.strip
+    [target.to_s, label]
+  end
+
+  # PURE. Render one entry line `- [[<target>|<label>]]` from a single ref. Kept for
+  # callers/tests that render one entry; #section uses add_entry for dedup.
+  def entry(ref, resolve)
+    target, label = resolve_entry(ref, resolve)
+    "- [[#{target}|#{label}]]"
+  end
+
+  # PURE. Resolve ONE sources/chain ref to its `{ target:, label: }` projection,
+  # given the in-memory cross-store maps. This is the single resolver definition
+  # shared by the IO shell (scripts/project-links) and the doctor check, so the two
+  # can never diverge.
+  #
+  #   ref            — "40" (same-store bare id) or "knowdb:1" (cross-store)
+  #   referer_store  — store_key of the intent carrying the ref ("global" / "project:<slug>")
+  #   relocation_map — from GraphRebuild.build_relocation_map (spans all stores)
+  #   store_index    — { store_key => [bare ids present] } (spans all stores)
+  #   node_index     — { store_key => { id => { basename:, label: } } } (spans all stores)
+  #
+  # Returns { target:, label: } (target is `<id>--<slug>` for a same-store id, or
+  # `<slug>:<id>--<slug>` for a cross-store one), or nil when the ref resolves to no
+  # live intent (which makes #section / #entry raise UnresolvedRef).
+  #
+  # Uses GraphRebuild.resolve_ref so a relocation always wins over a coincidentally
+  # reused id (the `global:24` impostor hazard), exactly as the frontmatter rebuild
+  # and the cross-store doctor check do.
+  def resolve_ref_projection(ref, referer_store:, relocation_map:, store_index:, node_index:)
+    require_relative "graph_rebuild"
+
+    res = GraphRebuild.resolve_ref(ref, referer_store: referer_store,
+                                        relocation_map: relocation_map,
+                                        store_index: store_index)
+    case res[:status]
+    when :same_store
+      node = (node_index[referer_store] || {})[res[:id]]
+      return nil if node.nil?
+
+      { target: node[:basename], label: node[:label] }
+    when :cross_store
+      slug, bare = res[:ref].split(":", 2)
+      target_key = canonical_store_key(slug, store_index)
+      node = (node_index[target_key] || {})[bare]
+      return nil if node.nil?
+
+      { target: "#{slug}:#{node[:basename]}", label: node[:label] }
+    else # :dead
+      nil
+    end
+  end
+
+  # Map a ref store slug ("global", "knowdb", "plastic") to a node_index/store_index
+  # key ("global", "project:knowdb", "project:plastic"). Mirrors
+  # GraphRebuild.canonical_store_key's intent for the node_index keyspace.
+  def canonical_store_key(slug, store_index)
+    return "global" if slug == "global"
+    return slug if (store_index || {}).key?(slug)
+
+    projected = "project:#{slug}"
+    (store_index || {}).key?(projected) ? projected : slug
+  end
+end

package/scripts/lib/links_section.rb

@@ -0,0 +1,207 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "intent_validator"
+
+# LinksSection — pure, minimal, style-preserving rewrite of ONLY the `## Links`
+# section of an intent file's content string (intent 72). Mirrors the discipline of
+# FrontmatterWriter: pure (no file IO, no eval, no global/ENV state), and returns
+# the original content UNCHANGED when nothing changed (idempotency).
+#
+# `## Links` is canonically the LAST sanctioned section
+# (IntentValidator::SANCTIONED_SECTIONS = Intent, Context, Outcome, Insights,
+# Links), and real intents put it last. So a file with an existing `## Links` has
+# its section replaced in place (from the heading to the next top-level `## `
+# heading or EOF), and a file WITHOUT a `## Links` gets one appended at end-of-body,
+# separated by exactly one blank line, preserving the body's trailing-newline shape.
+#
+# FENCE AWARENESS (intent 72 corruption fix): a `## Links` heading INSIDE a fenced
+# code block (``` or ~~~, possibly with an info string like ```markdown) is part of
+# an EXAMPLE, not a real section. All section scanning here IGNORES headings inside
+# fences and only ever targets the REAL `## Links` section (outside any fence). The
+# section end is the next `## ` heading that is ALSO outside a fence, so a replace
+# never consumes or unbalances a code fence. If more than one REAL `## Links`
+# heading exists, #rewrite raises AmbiguousLinks rather than guess.
+#
+# Frontmatter is NEVER touched: the leading `---`...`---` block is preserved
+# byte-for-byte and only the body is rebuilt.
+module LinksSection
+  module_function
+
+  HEADING = "## Links"
+
+  # A fence delimiter: ``` or ~~~ (any length >= 3), optional leading whitespace,
+  # optional info string (e.g. ```markdown). Mirrors CommonMark fenced-code rules
+  # closely enough for intent bodies.
+  FENCE_RE = /\A\s*(`{3,}|~{3,})/
+
+  # Raised when a body has more than one REAL `## Links` heading outside any fence;
+  # the tool must fail loud rather than guess which one to rewrite.
+  class AmbiguousLinks < StandardError
+    def initialize(count)
+      super("found #{count} real `## Links` headings outside code fences; refusing to guess")
+    end
+  end
+
+  # PURE. Replace (or insert) the REAL `## Links` section in `content` with
+  # `section_text` (the canonical block from LinksProjection.section, which begins
+  # with the `## Links` heading line and ends with a single trailing newline).
+  # Returns the new content, or the original when nothing changed. Raises
+  # AmbiguousLinks when more than one real `## Links` heading exists.
+  def rewrite(content, section_text)
+    return content unless content.is_a?(String)
+
+    fm, body = split_frontmatter(content)
+    new_body = rewrite_body(body, section_text)
+    updated = "#{fm}#{new_body}"
+    updated == content ? content : updated
+  end
+
+  # Split content into [frontmatter_with_delimiters, body]. When there is no
+  # frontmatter block, the frontmatter part is "" and the whole content is the
+  # body. The frontmatter part is preserved byte-for-byte by the caller.
+  def split_frontmatter(content)
+    return ["", content] unless content.start_with?("---")
+
+    parts = content.split("---", 3)
+    return ["", content] if parts.length < 3
+
+    ["---#{parts[1]}---", parts[2]]
+  end
+
+  # Rewrite ONLY the REAL `## Links` section within the body text.
+  def rewrite_body(body, section_text)
+    bounds = links_bounds(body)
+    if bounds
+      replace_section(body, section_text, bounds)
+    else
+      insert_section(body, section_text)
+    end
+  end
+
+  # PURE. Locate the REAL `## Links` section (fence-aware). Returns
+  # [start_index, end_index] line indices into body.lines, where start_index is the
+  # `## Links` heading line and end_index is the index of the next out-of-fence
+  # `## ` heading (or lines.length at EOF). Returns nil when there is no real
+  # `## Links` heading. Raises AmbiguousLinks when more than one exists.
+  def links_bounds(body)
+    lines = body.to_s.lines
+    starts = real_links_heading_indices(lines)
+    return nil if starts.empty?
+    raise AmbiguousLinks, starts.length if starts.length > 1
+
+    start = starts.first
+    stop = next_out_of_fence_heading(lines, start + 1)
+    [start, stop]
+  end
+
+  # PURE. Indices of every `## Links` heading line that is OUTSIDE any code fence.
+  # Accepts a body String or an Array of lines.
+  def real_links_heading_indices(body_or_lines)
+    lines = body_or_lines.is_a?(Array) ? body_or_lines : body_or_lines.to_s.lines
+    indices = []
+    in_fence = false
+    fence_marker = nil
+    lines.each_with_index do |line, i|
+      if (m = fence_open_close(line, in_fence, fence_marker))
+        in_fence = m[:in_fence]
+        fence_marker = m[:marker]
+        next
+      end
+      indices << i if !in_fence && line.rstrip == HEADING
+    end
+    indices
+  end
+
+  # PURE. Index of the first `## ` heading at or after `from` that is OUTSIDE any
+  # code fence. Returns lines.length when none (EOF). Fence state is recomputed
+  # from the top so nested example fences after the real heading are respected.
+  def next_out_of_fence_heading(lines, from)
+    in_fence = false
+    fence_marker = nil
+    lines.each_with_index do |line, i|
+      if (m = fence_open_close(line, in_fence, fence_marker))
+        in_fence = m[:in_fence]
+        fence_marker = m[:marker]
+        next
+      end
+      return i if i >= from && !in_fence && line.start_with?("## ")
+    end
+    lines.length
+  end
+
+  # PURE. Given the current fence state, decide whether `line` is a fence delimiter
+  # and return the new state, or nil when the line is not a fence delimiter.
+  # An opening fence records its marker family (` or ~); a closing fence must use a
+  # marker of the SAME family and carry no info string.
+  def fence_open_close(line, in_fence, fence_marker)
+    m = line.match(FENCE_RE)
+    return nil unless m
+
+    marker = m[1]
+    family = marker[0] # "`" or "~"
+    if in_fence
+      # A closing fence uses the same family, length >= the opener, no info string.
+      rest = line.sub(FENCE_RE, "").strip
+      if family == fence_marker && rest.empty?
+        { in_fence: false, marker: nil }
+      else
+        # A delimiter of the OTHER family (or an info-string line) inside a fence is
+        # literal content, not a fence event.
+        nil
+      end
+    else
+      { in_fence: true, marker: family }
+    end
+  end
+
+  # True iff the body has a REAL (out-of-fence) `## Links` heading. Used by callers
+  # to classify regenerate-vs-add without re-deriving fence state.
+  def links_heading?(body)
+    !real_links_heading_indices(body.to_s.lines).empty?
+  end
+
+  # Replace the REAL `## Links` section (the [start, stop] line bounds) with
+  # `section_text`, preserving everything before the heading and after the section
+  # byte-for-byte (including any fenced example that lives BEFORE the real section).
+  def replace_section(body, section_text, bounds)
+    lines = body.lines
+    start, stop = bounds
+    before = lines[0...start].join
+    tail = (lines[stop..] || [])
+
+    # `section_text` already ends with exactly one newline. When there is trailing
+    # content (another section follows), separate the block from it with one blank
+    # line; otherwise the section ends the body.
+    block = tail.empty? ? section_text : "#{section_text}\n"
+    "#{before}#{block}#{tail.join}"
+  end
+
+  # Append a `## Links` section at end-of-body, after the last existing section,
+  # separated by exactly one blank line, preserving the body's trailing newline.
+  def insert_section(body, section_text)
+    trimmed = body.to_s.sub(/\s+\z/, "")
+    if trimmed.empty?
+      # An empty body (no sections) just becomes the section.
+      section_text
+    else
+      "#{trimmed}\n\n#{section_text}"
+    end
+  end
+
+  # PURE. Extract the REAL `## Links` section text (fence-aware), normalized to the
+  # canonical block shape the projection emits: heading line + entry lines + a
+  # single trailing newline. Returns "" when there is no real section. Shared by
+  # the IO shell's audit and the doctor drift check so all three agree on the
+  # location. Raises AmbiguousLinks when more than one real heading exists.
+  def extract_section(body)
+    bounds = links_bounds(body)
+    return "" if bounds.nil?
+
+    start, stop = bounds
+    lines = body.to_s.lines
+    section = lines[(start + 1)...stop].join.sub(/\n+\z/, "\n")
+    section = "" if section.strip.empty?
+    "#{HEADING}\n#{section}"
+  end
+end