@zalom/plastic 2.0.0-alpha.2 → 2.0.0-alpha.20

package/scripts/lib/node_file.rb

@@ -0,0 +1,214 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+
+# NodeFile (intent 334, n3): one node file's YAML envelope (`node`, `kind`,
+# `files`, `budget`) over a Markdown body, plus the deterministic id minter
+# (327 D1r, D5r, D9r-D12r, D16r). The kind-prefix rule lives here, not in
+# GraphEdges, which stays loose about id grammar so a numeric roadmap id
+# parses the same way (D12r).
+#
+# Pure and side-effect-free: parse reads one file and returns a Result hash,
+# never raising across the boundary; mint_id takes the ids already present
+# and returns one past the highest of them. Reserving an id against a
+# concurrent minter is G7's problem, not a claim this module makes (D16r);
+# gathering the ids an intent has ever seen is NodeIds' job (335a), which is
+# why this module still requires nothing but yaml and date.
+module NodeFile
+  module_function
+
+  KIND_PREFIX = { "work" => "n", "verify" => "v", "decision" => "d", "research" => "r" }.freeze
+  VALID_KINDS = KIND_PREFIX.keys.freeze
+  FENCE_LINE_RE = /\A\s{0,3}(`{3,}|~{3,})/.freeze
+
+  # {ok:, node:, kind:, files:, budget:, body:, errors:}. `body` is the raw
+  # text after the frontmatter block, present even when `ok` is false and the
+  # body itself parsed fine, so a caller can still inspect sections on an
+  # envelope-invalid file. Every failure mode returns errors rather than
+  # raising: a missing file, absent or non-mapping frontmatter, or YAML that
+  # will not parse.
+  def parse(path)
+    return failure(["node file not found: #{path}"]) unless File.exist?(path)
+
+    content = File.read(path)
+    return failure(["missing YAML frontmatter"]) unless content.start_with?("---")
+
+    parts = content.split("---", 3)
+    return failure(["missing YAML frontmatter"]) if parts.length < 3
+
+    fm = begin
+      YAML.safe_load(parts[1], permitted_classes: [Date, Time])
+    rescue StandardError => e
+      return failure(["frontmatter is not valid YAML: #{e.message}"])
+    end
+    fm = {} if fm.nil?
+    return failure(["frontmatter must be a mapping, got #{fm.class}"]) unless fm.is_a?(Hash)
+
+    body = parts[2].to_s
+    errors = []
+
+    kind = fm["kind"].to_s
+    unless VALID_KINDS.include?(kind)
+      errors << "unknown kind: #{fm["kind"].inspect} (must be one of #{VALID_KINDS.join(', ')})"
+    end
+
+    id = fm["node"].to_s
+    errors << "missing node id (node:)" if id.empty?
+
+    if !id.empty?
+      basename = File.basename(path, ".md")
+      unless filename_matches_id?(basename, id)
+        errors << "node id #{id.inspect} does not match filename #{File.basename(path).inspect}"
+      end
+    end
+
+    if !id.empty? && VALID_KINDS.include?(kind)
+      expected_prefix = KIND_PREFIX[kind]
+      unless id.match?(/\A#{Regexp.escape(expected_prefix)}[1-9][0-9]*\z/)
+        errors << "node id #{id.inspect} does not match kind #{kind.inspect}'s prefix #{expected_prefix.inspect}"
+      end
+    end
+
+    errors << "depends_on: is not a valid envelope field (removed by 327 D41; edges belong in ## Graph)" if fm.key?("depends_on")
+    errors << "turns: is not a valid envelope field (removed by 327 D47)" if fm.key?("turns")
+
+    files = fm["files"]
+    if files.nil?
+      errors << "missing files:"
+    elsif !files.is_a?(Array)
+      errors << "files: must be a list, got #{files.class}"
+    end
+
+    budget, budget_errors = normalize_budget(fm["budget"])
+    errors.concat(budget_errors)
+
+    {
+      ok: errors.empty?,
+      node: id.empty? ? nil : id,
+      kind: kind.empty? ? nil : kind,
+      files: files.is_a?(Array) ? files : nil,
+      budget: budget,
+      body: body,
+      errors: errors,
+    }
+  end
+
+  def failure(errors)
+    { ok: false, node: nil, kind: nil, files: nil, budget: nil, body: nil, errors: errors }
+  end
+
+  # <id>.md or <id>--<slug>.md, exactly - a longer id's file (n11--x.md) must
+  # never satisfy a shorter id (n1), so the id is matched as the whole prefix
+  # up to end-of-string or the literal "--" separator, never as a substring
+  # (fold A9).
+  def filename_matches_id?(basename, id)
+    basename.match?(/\A#{Regexp.escape(id)}(--[A-Za-z0-9][A-Za-z0-9-]*)?\z/)
+  end
+
+  # budget: normalizes to a plain integer token ceiling. A bare integer and
+  # {tokens: N} both normalize to N; {turns: N} is the field 327 D47 removed
+  # and is a named error, never silently accepted (fold: report's example).
+  def normalize_budget(raw)
+    return [nil, []] if raw.nil?
+    return [raw, []] if raw.is_a?(Integer)
+
+    if raw.is_a?(Hash)
+      return [nil, ["budget: {turns:} was removed by 327 D47; use budget: <int> or {tokens: <int>}"]] if raw.key?("turns") || raw.key?(:turns)
+
+      tokens = raw["tokens"] || raw[:tokens]
+      return [tokens, []] if tokens.is_a?(Integer)
+
+      return [nil, ["budget: must normalize to an integer token count, got #{raw.inspect}"]]
+    end
+
+    [nil, ["budget: must be an integer or {tokens: <int>}, got #{raw.class}"]]
+  end
+
+  # Every [heading_line, body] pair in the body text, split on any heading
+  # line, fence-aware: a "#" line inside a fenced block never starts a new
+  # section (fold: "a node passes on a section it does not have").
+  def split_by_headings(text)
+    sections = []
+    heading = nil
+    body = +""
+    each_fence_line(text) do |line, fenced|
+      if !fenced && line.start_with?("#")
+        sections << [heading, body] if heading
+        heading = line.strip
+        body = +""
+      else
+        body << line
+      end
+    end
+    sections << [heading, body] if heading
+    sections
+  end
+
+  # Markdown table data rows (header + separator stripped) in text, fence-aware.
+  def table_rows(text)
+    lines = []
+    each_fence_line(text) do |line, fenced|
+      next if fenced
+
+      stripped = line.strip
+      lines << stripped if stripped.start_with?("|")
+    end
+    sep_idx = lines.index { |l| l.match?(/\A\|[\s:|-]+\|?\z/) }
+    return [] unless sep_idx
+
+    lines[(sep_idx + 1)..].map { |l| l.split("|", -1).map(&:strip)[1..-2].to_a }
+  end
+
+  def each_fence_line(text)
+    return enum_for(:each_fence_line, text) unless block_given?
+
+    marker = nil
+    text.to_s.each_line do |line|
+      if marker
+        yield line, true
+        m = line.match(FENCE_LINE_RE)
+        next unless m && m[1][0] == marker[0] && m[1].length >= marker[1]
+        next unless line.sub(FENCE_LINE_RE, "").strip.empty?
+
+        marker = nil
+      else
+        m = line.match(FENCE_LINE_RE)
+        if m
+          marker = [m[1][0], m[1].length]
+          yield line, true
+        else
+          yield line, false
+        end
+      end
+    end
+  end
+
+  # One past the highest id ever seen for the kind: purely numeric, so ids
+  # never sort as strings ("n10" ranking above "n9"), and a gap in the
+  # sequence STAYS a gap.
+  #
+  # Node ids never recycle (335a, owner ruling 2026-09-09). Intent 335 keyed
+  # the work ledger in savepoint.md on node id, and deletion is not a
+  # transition, so nothing in the ledger says a node is gone. Reissuing a
+  # deleted node's id therefore hands the new node the dead one's whole
+  # history: its `done` line, its evidence, its holder, and the successors
+  # that line released. The failure is silent, which is the worst shape it
+  # could take, so the gap is a headstone rather than free space.
+  #
+  # `taken` may carry ids this kind's grammar rejects, because NodeIds
+  # over-reserves on purpose (335a D11); they are ignored without shifting
+  # the sequence.
+  def mint_id(kind, taken)
+    prefix = KIND_PREFIX[kind.to_s]
+    return nil unless prefix
+
+    used = taken.to_a.filter_map do |id|
+      m = id.to_s.match(/\A#{Regexp.escape(prefix)}([1-9][0-9]*)\z/)
+      m && m[1].to_i
+    end
+
+    "#{prefix}#{(used.max || 0) + 1}"
+  end
+end

package/scripts/lib/node_ids.rb

@@ -0,0 +1,99 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "node_file"
+require_relative "graph_file"
+require_relative "graph_edges"
+require_relative "node_ledger"
+# Savepoint::INTENT_SUBJECT is named directly below, so the require is direct
+# too: test/savepoint_split_test.rb:157 refuses a transitive one.
+require_relative "savepoint"
+
+# NodeIds (intent 335a): every node id one intent has EVER seen, gathered from
+# the three places an id can appear, so NodeFile.mint_id can mint one past the
+# highest and never reissue a deleted node's id.
+#
+# Why this exists as its own module rather than inside NodeFile: NodeFile is
+# 334's deliberately dependency-free envelope reader (yaml and date only), and
+# gathering needs the graph parsers and the ledger. It is not inside
+# WorkGraphValidator either, because that module reports errors and minting is
+# not validation.
+#
+# The rule this serves (335a D1, owner ruling 2026-09-09): a removed node still
+# reserves its id. Deletion is not a ledger transition, so a reissued id would
+# silently inherit the dead node's transition history, evidence included.
+module NodeIds
+  module_function
+
+  # Every id seen in `intent_dir`, sorted and deduplicated. Each of the three
+  # sources is guarded on its own (D5): an intent that has not started yet is
+  # the ordinary case, not an error.
+  #
+  # The result deliberately OVER-reserves (D11). An id that no kind's grammar
+  # matches costs nothing, because mint_id filters by prefix; a missed id costs
+  # a false history.
+  def taken(intent_dir)
+    return [] unless intent_dir && File.directory?(intent_dir)
+
+    (from_node_files(intent_dir) + from_graph(intent_dir) + from_ledger(intent_dir))
+      .reject { |id| id.nil? || id.empty? }
+      .uniq
+      .sort
+  end
+
+  # Both the filename's id AND the envelope's `node:` (D7). A file can disagree
+  # with its own name, and a file whose frontmatter will not parse yields no
+  # envelope id at all, which is exactly when the filename is the only thing
+  # standing between a corrupt node file and a reissued id.
+  #
+  # Plain glob (D8): a zero-byte or sentinel-marked node file still names a node
+  # whose id is taken. Savepoint.has_real_files_in?'s filter answers a different
+  # question (has this intent started) and is not reused here.
+  def from_node_files(intent_dir)
+    Dir.glob(File.join(intent_dir, "nodes", "*.md")).sort.flat_map do |path|
+      [id_from_filename(path), NodeFile.parse(path)[:node]]
+    end
+  end
+
+  # The id a node filename declares: the basename up to the "--" separator, so
+  # both shapes 334 D11r ratifies reserve - the bare `n2.md` and the slugged
+  # `n1--graph-edges.md` (D6). Taking the whole basename would reserve nothing
+  # for every slugged file in the store, which is the dominant shape.
+  def id_from_filename(path)
+    File.basename(path, ".md").split("--", 2).first.to_s
+  end
+
+  # Declared plus targeted, from the `## Graph` section only (D9). The gatherer
+  # inherits GraphEdges' looseness: it is not fence-aware, so an id inside a
+  # fenced example is gathered. That over-reserves, which is the safe direction.
+  #
+  # `## Status` is NOT read (D10): it is a projection rendered from the ledger
+  # and rewritten wholesale, so every id it can carry the ledger already carries.
+  def from_graph(intent_dir)
+    path = File.join(intent_dir, "graph.md")
+    return [] unless File.exist?(path)
+
+    section = GraphFile.section_body(File.read(path).scrub, "## Graph")
+    return [] unless section
+
+    GraphEdges.parse(section)[:nodes].to_a
+  end
+
+  # Subjects only, read through NodeLedger.entries, NEVER a token scan (D4).
+  # A node id can sit inside an ordinary milestone's free text and does today:
+  # intent 335's own ledger carries "ACTION_1 v2" inside a Review line, and 23
+  # such tokens exist across the live store. NodeLedger.entries already owns the
+  # two-space split and already keeps a torn line's subject, so this reuses that
+  # seam rather than making a third copy of it.
+  #
+  # The literal `Intent` subject is dropped: it is an intent-scope line, not a
+  # node, and no kind's grammar would match it anyway.
+  def from_ledger(intent_dir)
+    path = File.join(intent_dir, "savepoint.md")
+    return [] unless File.exist?(path)
+
+    NodeLedger.entries(path)
+              .map { |entry| entry[:subject] }
+              .reject { |subject| subject == Savepoint::INTENT_SUBJECT }
+  end
+end

package/scripts/lib/node_ledger.rb

@@ -0,0 +1,377 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "strscan"
+require_relative "savepoint"
+require_relative "guarded_append"
+
+# NodeLedger - the node and intent transition line (intent 335, G2). Owns the
+# line's byte-exact format, the closed state vocabulary, the required fields per
+# state, the parser, torn-line and unattributed-line detection, status as the
+# last line per subject in file order, and the guarded transition append that
+# skips dedup entirely (spec D11).
+#
+# Per spec D17 the subject vocabulary (`Savepoint::INTENT_SUBJECT`,
+# `Savepoint::NODE_SUBJECT_RE`, `Savepoint.transition_candidate?`) lives on
+# Savepoint, not here: this file requires savepoint.rb and reuses them, the
+# dependency running one way only (test/savepoint_split_test.rb:57 pins
+# savepoint.rb to loading no other project file).
+#
+# Pure and dependency-injected: every path and clock is an argument, `guard:` is
+# an injectable seam for the transition append, and this module reads no
+# environment variable.
+module NodeLedger
+  module_function
+
+  # Ten states, closed (spec D1). "ready" is computed and never written.
+  STATES = %w[
+    planned running done failed_verification needs_decision blocked deferred
+    superseded abandoned reclaimed
+  ].freeze
+
+  # A written state's RESOLVED state for the ready function 336 builds on top of
+  # this ledger (spec D2): every state resolves to itself except `reclaimed`,
+  # which resolves to `planned` ("a reclaimed node is planned again").
+  RESOLUTION = { "reclaimed" => "planned" }.freeze
+
+  # Required fields per state (spec D4), refused by #append_transition and read
+  # as torn by #torn? when absent. `done`'s evidence requirement (gates= plus at
+  # least one of commit=/verdict=) is asymmetric, so it is not representable as
+  # a flat list; DONE_EVIDENCE_FIELDS below carries the "at least one of" half.
+  REQUIRED_FIELDS = {
+    "planned" => [],
+    "running" => %w[holder expires packet model],
+    "done" => %w[gates],
+    "failed_verification" => %w[gates reason],
+    "needs_decision" => %w[question],
+    "blocked" => %w[reason],
+    "deferred" => %w[reason],
+    "superseded" => %w[by],
+    "abandoned" => %w[reason],
+    "reclaimed" => %w[holder expired],
+  }.freeze
+
+  # `done` requires gates= plus at least one of these (spec D7). `model=` is
+  # deliberately absent from every required-fields list except `running` (spec
+  # D6) and is accepted, never required, everywhere else - no separate table
+  # entry is needed for that: an unlisted field is never required.
+  DONE_EVIDENCE_FIELDS = %w[commit verdict].freeze
+
+  # Canonical field render order (spec D8's "stable declared order", matrix
+  # 2.6): every key named in REQUIRED_FIELDS or DONE_EVIDENCE_FIELDS, plus
+  # `model` (accepted on any state). A field outside this list still renders,
+  # sorted after these, so an unrecognized key is never silently dropped.
+  FIELD_ORDER = %w[holder expires packet model gates commit verdict reason question by expired].freeze
+
+  SEPARATOR = "  "
+
+  # The field key character class, shared by the emitter (#render_fields, below) and
+  # the parser (FIELD_TOKEN_RE, further down): a key outside this class is a key the
+  # parser can never read back as a pair, so it must never be emitted (post-execution
+  # review row 7.7). One source of truth for the char class keeps the two families
+  # from drifting the way they did before this row's fix.
+  FIELD_KEY_CHARS = "[a-z_]+"
+  FIELD_KEY_RE = /\A#{FIELD_KEY_CHARS}\z/.freeze
+
+  # timestamp<SEP>subject<SEP>state field=value... (comment). Two-space
+  # separators keep the line a three-field line under both `split(/\s{2,}/)`
+  # and every reader's own `SAVEPOINT_RE` (spec "Line shape"). Raises
+  # ArgumentError, writing nothing, for an unknown state or a missing required
+  # field (D4/D9): the caller of #append_transition relies on this check
+  # running BEFORE the file is ever touched.
+  def transition_line(subject:, state:, fields: {}, comment: nil, now: Time.now)
+    state = state.to_s
+    raise ArgumentError, "unknown transition state: #{state.inspect}" unless STATES.include?(state)
+
+    missing = missing_fields(state, fields)
+    raise ArgumentError, "state #{state} requires #{missing.join(', ')}" if missing.any?
+
+    timestamp = now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+    rest = ([state] + render_fields(fields)).join(" ")
+    rest = "#{rest} (#{normalize_value(comment)})" if comment && !comment.to_s.strip.empty?
+    "#{timestamp}#{SEPARATOR}#{subject}#{SEPARATOR}#{rest}\n"
+  end
+
+  # Collapse every run of two-or-more WHITESPACE characters in `text` to one
+  # (spec "Line shape": "collapses every whitespace run inside a field value
+  # to a single space"), so a caller-supplied value or comment can never
+  # reintroduce a two-or-more run the line's own separators rely on being
+  # unique to field boundaries. A tab or a newline is refused outright (raises
+  # ArgumentError) rather than collapsed: silently eating either would hide a
+  # value that could otherwise tear a ledger line. Post-execution review row
+  # 7.6: a bare `/ {2,}/` collapsed only literal spaces, so a carriage return,
+  # vertical tab or form feed beside a space still reached field 3 as a
+  # two-whitespace run that `split(/\s{2,}/)` reads as four fields while
+  # SAVEPOINT_RE reads as three - `\s{2,}` is what the acceptance criterion
+  # ("no run of two or more whitespace characters ever reaches field 3")
+  # actually requires.
+  def normalize_value(text)
+    value = text.to_s
+    raise ArgumentError, "value must not contain a tab or a newline: #{value.inspect}" if value =~ /[\t\n]/
+
+    value.gsub(/\s{2,}/, " ")
+  end
+
+  # A required-field D4 check independent of vocabulary validity: given a state
+  # (assumed valid) and a fields hash, the list of required field names still
+  # missing. `done`'s "at least one of commit=/verdict=" half renders as the
+  # literal string "commit or verdict" when both are absent.
+  def missing_fields(state, fields)
+    normalized = stringify_keys(fields)
+    required = REQUIRED_FIELDS.fetch(state.to_s, [])
+    missing = required.reject { |key| present?(normalized[key]) }
+    if state.to_s == "done" && DONE_EVIDENCE_FIELDS.none? { |key| present?(normalized[key]) }
+      missing += ["commit or verdict"]
+    end
+    missing
+  end
+
+  def present?(value)
+    !(value.nil? || value.to_s.strip.empty?)
+  end
+  private_class_method :present?
+
+  def stringify_keys(fields)
+    (fields || {}).each_with_object({}) { |(k, v), memo| memo[k.to_s] = v }
+  end
+  private_class_method :stringify_keys
+
+  def render_fields(fields)
+    normalized = stringify_keys(fields)
+    unreadable = normalized.keys.reject { |key| key.match?(FIELD_KEY_RE) }
+    if unreadable.any?
+      raise ArgumentError, "field key(s) the parser cannot read back: #{unreadable.join(', ')}"
+    end
+
+    known = FIELD_ORDER.select { |key| normalized.key?(key) }
+    extra = (normalized.keys - FIELD_ORDER).sort
+    (known + extra).map { |key| "#{key}=#{render_value(normalized[key])}" }
+  end
+  private_class_method :render_fields
+
+  def render_value(value)
+    text = normalize_value(value)
+    return text if bare_safe?(text)
+
+    escaped = text.gsub("\\") { "\\\\" }.gsub('"') { "\\\"" }
+    "\"#{escaped}\""
+  end
+  private_class_method :render_value
+
+  def bare_safe?(text)
+    !text.empty? && !text.match?(/[\s"\\]/)
+  end
+  private_class_method :bare_safe?
+
+  # --- Parsing ---------------------------------------------------------------
+
+  # timestamp<2sp>subject<2sp>rest, mirroring intent_screen.rb's SAVEPOINT_RE
+  # (the same three-field contract every reader in the tree already assumes).
+  TRANSITION_LINE_RE = /\A(\S+)#{SEPARATOR}(\S+)#{SEPARATOR}(.+?)\s*\z/.freeze
+  private_constant :TRANSITION_LINE_RE
+
+  FIELD_TOKEN_RE = /(#{FIELD_KEY_CHARS})=("(?:[^"\\]|\\.)*"|[^\s"]+)/.freeze
+  private_constant :FIELD_TOKEN_RE
+
+  # Parse one raw ledger line into {timestamp:, subject:, state:, fields:,
+  # comment:, raw:}, or nil when it does not even split into the three fields
+  # every transition line has. `#scrub`s the line first (mirrors
+  # SessionLedger.parse_checklist_line) so a stray non-UTF-8 byte anywhere in
+  # the ledger never raises out of the parser and takes down every reader
+  # (matrix 2.44); it only ever affects that one line's parsed text.
+  def parse_transition_line(line)
+    raw = line.to_s.chomp.scrub
+    m = TRANSITION_LINE_RE.match(raw)
+    return nil unless m
+
+    timestamp, subject, rest = m.captures
+    state, remainder = rest.split(/\s+/, 2)
+    fields, comment = scan_fields(remainder.to_s)
+    { timestamp: timestamp, subject: subject, state: state, fields: fields, comment: comment, raw: raw }
+  end
+
+  # Scan `rest` (everything after the state token) for `key=value` pairs, quote-
+  # and-escape aware, greedily from the start; the first token that is not a
+  # pair, and everything after it, is the trailing comment (spec D8), with one
+  # layer of wrapping parens stripped when present (the shape #transition_line
+  # itself always emits). Returns [fields_hash, comment_or_nil].
+  def scan_fields(rest)
+    scanner = StringScanner.new(rest)
+    fields = {}
+    loop do
+      scanner.skip(/\s+/)
+      break if scanner.eos?
+
+      start_pos = scanner.pos
+      if scanner.scan(FIELD_TOKEN_RE)
+        fields[scanner[1]] = unquote(scanner[2])
+      else
+        scanner.pos = start_pos
+        break
+      end
+    end
+    tail = scanner.rest.to_s.strip
+    comment = tail.empty? ? nil : tail.sub(/\A\((.*)\)\z/m, '\1')
+    [fields, comment]
+  end
+  private_class_method :scan_fields
+
+  def unquote(raw)
+    return raw unless raw.start_with?('"')
+
+    raw[1..-2].gsub(/\\(.)/) { Regexp.last_match(1) }
+  end
+  private_class_method :unquote
+
+  # A transition line is torn (spec D9) when it does not parse into the three
+  # fields at all, when its state token is outside STATES, or when its state is
+  # in STATES but a field REQUIRED_FIELDS demands is missing. The second half
+  # matters more than the first: a crash-truncated write usually keeps a valid
+  # state token and loses the tail (`n1  running holder=auto-ce5`), which is
+  # the realistic torn line, not a truncated state token.
+  def torn?(line)
+    parsed = parse_transition_line(line)
+    return true unless parsed
+    return true unless parsed[:state] && STATES.include?(parsed[:state])
+
+    missing_fields(parsed[:state], parsed[:fields]).any?
+  end
+
+  def torn_reason(parsed)
+    return "does not parse as timestamp  subject  state ..." unless parsed && parsed[:state]
+    return "unknown state #{parsed[:state].inspect}" unless STATES.include?(parsed[:state])
+
+    "missing required field(s): #{missing_fields(parsed[:state], parsed[:fields]).join(', ')}"
+  end
+  private_class_method :torn_reason
+
+  # A transition line is attributed (spec D10) iff it carries a non-blank
+  # `holder=` field. Unattributed and torn are independent: a line can be
+  # unattributed and otherwise well formed at the same time.
+  def attributed?(parsed)
+    return false unless parsed
+
+    present?((parsed[:fields] || {})["holder"])
+  end
+
+  def resolved_state(state)
+    RESOLUTION.fetch(state.to_s, state.to_s)
+  end
+
+  # --- Reading the ledger ------------------------------------------------------
+
+  # Every transition candidate line in `path`, in file order, each annotated
+  # with its parse, torn-ness, and attribution. Non-candidate lines (a stage
+  # line, a Lock takeover line) are excluded entirely: they are never a
+  # transition and are never reported as torn by this module (spec Acceptance
+  # Criteria; Savepoint's own phantom detector covers the stage family).
+  # `#scrub`s the whole file up front (matrix 2.44) so one bad byte anywhere
+  # never raises out of this reader.
+  def entries(path)
+    return [] unless path && File.exist?(path)
+
+    entries_from_content(File.read(path))
+  end
+
+  # Same as #entries, but over an in-memory string rather than a path (post-
+  # execution review row 7.1/7.2): the readiness decision `node-transition`
+  # makes for `running` must be evaluated against the exact content
+  # GuardedAppend read under its lock hold, never a re-read of the path (which
+  # could observe a different file than the one the guard is holding closed
+  # against other writers, and reintroduces the check-then-append gap this row
+  # exists to close).
+  def entries_from_content(content)
+    content.to_s.scrub.each_line.filter_map do |raw|
+      line = raw.chomp
+      next nil if line.strip.empty?
+      next nil unless Savepoint.transition_candidate?(line)
+
+      parsed = parse_transition_line(line)
+      torn = torn?(line)
+      {
+        raw: line,
+        timestamp: parsed && parsed[:timestamp],
+        subject: parsed ? parsed[:subject] : line.split(/\s{2,}/)[1],
+        state: parsed && parsed[:state],
+        fields: parsed ? parsed[:fields] : {},
+        comment: parsed && parsed[:comment],
+        torn: torn,
+        attributed: parsed ? attributed?(parsed) : false,
+      }
+    end
+  end
+
+  # Status per subject: the last NON-TORN line for that subject in FILE order
+  # (never by timestamp, spec Acceptance Criteria), resolved (spec D2). An
+  # unattributed-but-well-formed line still counts for status (D10: status
+  # shows it; only the readiness check ignores it).
+  def status(path)
+    status_from_content(path && File.exist?(path) ? File.read(path) : "")
+  end
+
+  # Content-based counterpart to #status (see #entries_from_content).
+  def status_from_content(content)
+    entries_from_content(content).each_with_object({}) do |entry, memo|
+      next if entry[:torn]
+
+      memo[entry[:subject]] = resolved_state(entry[:state])
+    end
+  end
+
+  # A subject with no line at all reads as "planned" (spec D1's implicit
+  # starting state), never raises.
+  def status_for(path, subject)
+    status(path).fetch(subject.to_s, "planned")
+  end
+
+  # Content-based counterpart to #status_for (see #entries_from_content).
+  def status_for_content(content, subject)
+    status_from_content(content).fetch(subject.to_s, "planned")
+  end
+
+  # The last (file-order) non-torn `running` entry for `subject`, or nil. Used
+  # by the reclaim precondition (S3) to find the `expires=` this subject's live
+  # dispatch carries.
+  def last_running(path, subject)
+    entries(path).select { |e| !e[:torn] && e[:subject] == subject.to_s && e[:state] == "running" }.last
+  end
+
+  # Torn and unattributed lines, each paired with a reason (spec C2/C5's
+  # reader): [{line:, reason:}, ...]. A clean or absent ledger returns []. A
+  # torn line is reported once, as torn; a well-formed unattributed line is
+  # reported once, as unattributed - the two categories never conflate.
+  def anomalies(path)
+    entries(path).filter_map do |entry|
+      if entry[:torn]
+        { line: entry[:raw], reason: "torn: #{torn_reason(parse_transition_line(entry[:raw]))}" }
+      elsif !entry[:attributed]
+        { line: entry[:raw], reason: "unattributed (no holder=)" }
+      end
+    end
+  end
+
+  # --- Writing -----------------------------------------------------------------
+
+  # Refuse an unknown state or a missing required field BEFORE touching the
+  # file (spec C20), then append through `guard` (default GuardedAppend,
+  # strict), skipping dedup entirely (spec D11: transition lines never consult
+  # savepoint_recorded_pairs). Returns whatever `guard.call` returns
+  # (:written or :refused); propagates GuardedAppend::Unavailable rather than
+  # swallowing it (a caller must never believe a line landed when it did not).
+  #
+  # `precondition:` (post-execution review rows 7.1-7.3) is an optional
+  # callable evaluated INSIDE the guard's lock hold, against the exact
+  # `content` the guard just read - never a value captured before the call.
+  # When it returns falsy, the block returns nil (GuardedAppend's own
+  # refusal contract) and nothing is written; the caller sees :refused,
+  # distinguishable from :written, and must not believe the line landed. This
+  # is what makes "is the subject still ready" and "append running" atomic
+  # against a second writer: a check followed by a separate append never is.
+  def append_transition(path, subject:, state:, fields: {}, comment: nil, now: Time.now, guard: GuardedAppend,
+                         precondition: nil)
+    line = transition_line(subject: subject, state: state, fields: fields, comment: comment, now: now)
+    guard.call(path, strict: true) do |content|
+      precondition && !precondition.call(content) ? nil : line
+    end
+  end
+end