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

package/scripts/lib/savepoint.rb

@@ -23,6 +23,36 @@ module Savepoint
   # (<id>--<slug>.md) is never sentineled; it is born complete.
   PLACEHOLDER_SENTINEL = "<!-- plastic:placeholder -->"
 
+  # --- Node-graph transition subject vocabulary (intent 335, spec D17) -------
+  #
+  # Owned HERE, not on NodeLedger, because test/savepoint_split_test.rb:57 pins
+  # savepoint.rb to loading no other project file: NodeLedger requires this
+  # file and reuses these three names rather than duplicating them, so the
+  # dependency runs one way only. Intent 334 (G1) mints node ids and must
+  # agree with NODE_SUBJECT_RE: it is the single seam for the node id shape.
+
+  # The literal subject token for an intent-scope transition line ("Intent
+  # needs_decision question=..."), as opposed to a node-scope line.
+  INTENT_SUBJECT = "Intent"
+
+  # A node id: one or two lowercase letters (the node's kind prefix, e.g. "n"
+  # for work, "v" for verify) followed by digits.
+  NODE_SUBJECT_RE = /\A[a-z]{1,2}\d+\z/.freeze
+
+  # True iff a raw savepoint ledger line's subject (field 2, split on
+  # /\s{2,}/) is a transition candidate: the literal Intent token or a node
+  # id. A stage line ("How  checklist.md created") or a Lock takeover audit
+  # line never matches, by construction (spec Acceptance Criteria: "no stage
+  # token this tree writes collides with Intent or with the node id
+  # pattern").
+  def self.transition_candidate?(line)
+    parts = line.to_s.split(/\s{2,}/)
+    return false unless parts.length >= 2
+
+    subject = parts[1]
+    subject == INTENT_SUBJECT || subject.match?(NODE_SUBJECT_RE)
+  end
+
   def self.intent_file(intent_dir)
     dir_name = File.basename(intent_dir)
     "#{intent_dir}/#{dir_name}.md"
@@ -57,22 +87,47 @@ module Savepoint
     File.exist?(path)
   end
 
-  # True iff actions/ holds AT LEAST ONE real action file: a non-empty *.md whose
-  # first line is not the placeholder sentinel. A `.gitkeep` (no .md extension)
-  # never counts, an empty *.md never counts, and a sentinel-only *.md never
-  # counts. Pure and side-effect-free so the gate stays unit-testable. Fail-open:
-  # a missing actions/ dir globs to nothing and returns false (the gate then
-  # reports it needs a real action file); it never raises.
-  def self.has_real_action?(intent_dir)
-    Dir.glob("#{intent_dir}/actions/*.md").any? do |f|
+  # True iff DIR_NAME (actions/ or nodes/) holds AT LEAST ONE real *.md file: non-empty,
+  # first line not the placeholder sentinel. A `.gitkeep` (no .md extension) never counts.
+  # Pure and side-effect-free; fail-open (a missing dir globs to nothing, never raises).
+  def self.has_real_files_in?(dir_name, intent_dir)
+    Dir.glob("#{intent_dir}/#{dir_name}/*.md").any? do |f|
       File.file?(f) && File.size(f) > 0 && stage_file_present?(f)
     end
   rescue StandardError
     false
   end
 
+  # True iff the intent has at least one real action file, whether delivered as
+  # legacy actions/*.md or as a node graph's nodes/*.md (intent 334, G1, D10r):
+  # an intent delivered as nodes is exactly as real as one delivered as
+  # actions, so doctor and the exec-stage gate never report a backfill gap on
+  # a fully delivered node-graph intent. Checks actions/ first (the common
+  # path today), falling through to nodes/ only when actions/ has nothing.
+  def self.has_real_action?(intent_dir)
+    has_real_files_in?("actions", intent_dir) || has_real_files_in?("nodes", intent_dir)
+  rescue StandardError
+    false
+  end
+
+  # Intent 336 (G3, D13): a real graph.md is 327 D41's replacement for
+  # plan.md/checklist.md on the common path, so a node-shaped intent is
+  # judged on graph.md and nodes/ alone, whether or not spec.md is real - the
+  # graph IS the spec under D41. Checked using only this file's own
+  # primitives (stage_file_present?, has_real_files_in?), because
+  # test/savepoint_split_test.rb pins this file to loading no other project
+  # file and no YAML: GraphFile/NodeFile/ReadySet are never required here. An
+  # intent with no real graph.md (or a sentinel-placeholder one,
+  # stage_file_present? already reads that as absent) derives exactly what it
+  # derived before this intent.
   def self.derive_stage(intent_dir)
     return "done" if stage_file_present?("#{intent_dir}/outcome.md")
+
+    if stage_file_present?("#{intent_dir}/graph.md")
+      return "exec" if has_real_files_in?("nodes", intent_dir)
+      return "how"
+    end
+
     if stage_file_present?("#{intent_dir}/plan.md") &&
        has_real_action?(intent_dir) &&
        stage_file_present?("#{intent_dir}/checklist.md")
@@ -87,19 +142,49 @@ module Savepoint
     files = []
     ifile = File.basename(intent_file(intent_dir))
     files << ifile if File.exist?("#{intent_dir}/#{ifile}")
-    ["spec.md", "plan.md", "checklist.md", "outcome.md"].each do |f|
+    ["spec.md", "graph.md", "plan.md", "checklist.md", "outcome.md"].each do |f|
       files << f if stage_file_present?("#{intent_dir}/#{f}")
     end
-    files << "actions/" if has_real_action?(intent_dir)
+    # Name the directory that actually exists (fold B3): a nodes-only intent
+    # must never claim the literal "actions/" artifact it does not have.
+    # Checks actions/ first, matching D15r's read order.
+    if has_real_files_in?("actions", intent_dir)
+      files << "actions/"
+    elsif has_real_files_in?("nodes", intent_dir)
+      files << "nodes/"
+    end
     files
   end
 
   def self.missing_for_stage(stage, intent_dir = nil)
     ifile = intent_dir ? File.basename(intent_file(intent_dir)) : "intent.md"
+    # A How-stage intent that already started a nodes/ directory is named
+    # accordingly, so the next-step hint never tells a node-graph intent to
+    # go make an actions/ directory it will never use (fold B3). Mirrors
+    # has_real_files_in?'s actions-first order and its real-file requirement
+    # (post-execution review, non-blocking 4): an intent carrying real files
+    # in both directories, or a real actions/ file beside an empty or
+    # .gitkeep-only nodes/, is named actions/, never nodes/.
+    action_label = if intent_dir && has_real_files_in?("actions", intent_dir)
+      "actions/"
+    elsif intent_dir && has_real_files_in?("nodes", intent_dir)
+      "nodes/"
+    else
+      "actions/"
+    end
     case stage
     when "what" then [ifile]
     when "why" then ["spec.md"]
-    when "how" then ["plan.md", "actions/", "checklist.md"]
+    when "how"
+      # A node-shaped How intent (a real graph.md already) is named after its
+      # own two artifacts, never the three D41 removed from its path (fold
+      # B3, extended by 336 D13): checked via stage_file_present? alone, the
+      # same primitive derive_stage itself uses.
+      if intent_dir && stage_file_present?("#{intent_dir}/graph.md")
+        ["graph.md", "nodes/"]
+      else
+        ["plan.md", action_label, "checklist.md"]
+      end
     when "exec" then ["outcome.md"]
     else []
     end
@@ -213,6 +298,32 @@ module Savepoint
     append_savepoint_line(intent_dir, "Exec", "started", now)
   end
 
+  # Append a `Review` line: one per plan-review or post-execution-review verdict
+  # (intent 317, D5/D17). Same shape as every other line, through the shared
+  # append_savepoint_line primitive, so dedup and the timestamp format never
+  # drift from the one line-writer every other kind already uses.
+  def self.append_review_savepoint(intent_dir, text, now: Time.now)
+    append_savepoint_line(intent_dir, "Review", text, now)
+  end
+
+  # Append a `Commit` line: one per commit landing during Exec (intent 317,
+  # D5/D17). Same primitive as append_review_savepoint above.
+  def self.append_commit_savepoint(intent_dir, text, now: Time.now)
+    append_savepoint_line(intent_dir, "Commit", text, now)
+  end
+
+  # The day the Report kind (below) shipped. `doctor`'s intent_reports_printed_check reads
+  # this so it never re-litigates a ledger recorded before the kind existed (intent 331f, R6).
+  REPORT_KIND_SINCE = "2026-09-05"
+
+  # Append a `Report` line: one per report screen printed (intent 331f, D2/D3). Same primitive
+  # as append_review_savepoint/append_commit_savepoint above, so the line shape, dedup, and
+  # timestamp format never drift. `savepoint_milestone` maps FILENAMES only, so a Report line
+  # is never mistaken for a file-landing lifecycle line by construction.
+  def self.append_report_savepoint(intent_dir, text, now: Time.now)
+    append_savepoint_line(intent_dir, "Report", text, now)
+  end
+
   TERMINAL_DISPOSITIONS = %w[delivered abandoned].freeze
 
   # Append the terminal bookend `Done  delivered|abandoned`, written by the
@@ -232,6 +343,17 @@ module Savepoint
   # A Plastic 1.x ledger may carry a `Tier  <value>` line after the spec.md
   # milestone (removed in 2.0, intent 304); a rebuild drops it, and the phantom
   # detector ignores it, so a 1.x store reads clean.
+  #
+  # Every transition line (intent 335, spec D13) is preserved VERBATIM, in its
+  # original relative order, after the reconstructed stage skeleton. It is
+  # never dropped and never refused: a transition line's evidence fields
+  # (`holder=`, `expires=`, `gates=`, ...) have no file-mtime analog to
+  # reconstruct from, so refusing instead of preserving would make this method
+  # destroy the graph's only status on every intent that carries one. Relative
+  # order BETWEEN a stage line and a transition line is not preserved (safe:
+  # status is computed per subject, and the two families share no subject);
+  # relative order WITHIN the transition lines is preserved, which is what
+  # "last line per subject in file order" depends on.
   def self.rebuild_savepoint(intent_dir)
     ordered = [
       File.basename(intent_file(intent_dir)),
@@ -245,7 +367,18 @@ module Savepoint
       stamp = File.mtime(path).utc.iso8601
       ["#{stamp}  #{stage}  #{milestone}\n"]
     end
-    File.write(File.join(intent_dir, SAVEPOINT_FILE), lines.join)
+
+    savepoint_path = File.join(intent_dir, SAVEPOINT_FILE)
+    if File.exist?(savepoint_path)
+      # #scrub before scanning (post-execution review row 7.8), the same way
+      # NodeLedger.entries does (matrix 2.44): a stray non-UTF-8 byte anywhere
+      # in the ledger must not raise out of the one repair tool three doctor
+      # fix hints and maintenance-run --tool rebuild-savepoint point at.
+      transition_lines = File.read(savepoint_path).scrub.each_line.select { |raw| transition_candidate?(raw) }
+      lines += transition_lines.map { |raw| raw.end_with?("\n") ? raw : "#{raw}\n" }
+    end
+
+    File.write(savepoint_path, lines.join)
     lines.length
   end
 
@@ -294,6 +427,10 @@ module Savepoint
     File.read(path).each_line do |raw|
       line = raw.strip
       next if line.empty?
+      # A transition line (intent 335) is never a stage phantom candidate: its
+      # own repeated-line semantics (dedup-free by design, spec D11) are
+      # NodeLedger's concern, not this detector's.
+      next if transition_candidate?(line)
       parts = line.split(/\s{2,}/)
       next if parts.length < 3
       pair = [parts[1], parts[2]]