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

package/scripts/lib/runner_sweep.rb

@@ -0,0 +1,231 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "time"
+require "fileutils"
+require_relative "worktree"
+require_relative "lock"
+require_relative "node_ledger"
+require_relative "ready_set"
+require_relative "savepoint"
+
+# RunnerSweep (intent 340, G7, n2): the first thing every `step` does. Two
+# separately callable entry points - #abort_if_merging and #reclaim - plus
+# #run, which composes them for a caller that has no absorb step to interleave.
+# `step` (a later node) calls #abort_if_merging, runs absorb, then calls
+# #reclaim itself, so a reclaimed node's just-landed work from absorb is never
+# thrown away by a stale read (matrix row 2.20).
+#
+# #abort_if_merging refuses the whole step when the intent worktree already
+# has a merge in progress (`MERGE_HEAD` resolves): dispatching on top of a
+# half-finished merge would hand the next node a diff full of someone else's
+# conflict markers. Nothing is written when this fires - not the ledger, not
+# graph.md, not even the delivery lease heartbeat (row 2.2, row 2.16: the
+# heartbeat runs strictly after the abort check).
+#
+# #reclaim walks every node whose CURRENT status (the ledger's own resolution,
+# never a raw scan) is `running`, skipping anything named in `skip:` (the
+# nodes this step already absorbed, row 2.19) or already terminal (a `done`
+# node is never touched, row 2.12 - it simply never shows up as `running`).
+# An expired lease with no commits on the node's own branch newer than its
+# expiry is reclaimed outright. An expired lease whose branch DOES carry
+# newer commits is extended instead, up to twice per attempt (row 2.7); the
+# extension is never a ledger transition (`running` cannot re-enter `running`
+# under the transition layer), so it is one line appended to
+# packets/<node>--a<N>.extensions, `N` derived from the ledger's own attempt
+# count (row 2.18), never trusted from the caller. A third expiry reclaims
+# regardless of new commits.
+#
+# Pure and dependency-injected: every git call goes through an injected
+# `runner:` (default Worktree::ShellRunner), never cwd; the delivery-lease
+# heartbeat goes through an injected `heartbeat:` (default Lock.heartbeat) so
+# ordering (row 2.16) is provable without a real lock file. No eval, no
+# ENV/global-constant seam.
+module RunnerSweep
+  module_function
+
+  # D-ish: at most two extensions per attempt (row 2.7); the third expiry
+  # reclaims regardless of new commits.
+  MAX_EXTENSIONS_PER_ATTEMPT = 2
+
+  # abort_if_merging(context, runner:) -> {ok:, error:, recovery_command:}.
+  # `context.worktree` is nil for a global-store-only intent (no git repo to
+  # merge into); that case is always ok - there is nothing to abort.
+  def abort_if_merging(context, runner: Worktree::ShellRunner.new)
+    worktree = context&.worktree
+    return { ok: true, error: nil, recovery_command: nil } if blank?(worktree)
+
+    res = runner.run("-C", worktree, "rev-parse", "-q", "--verify", "MERGE_HEAD")
+    return { ok: true, error: nil, recovery_command: nil } unless res.success?
+
+    recovery_command = "git -C #{worktree} merge --abort"
+    warn "runner: a merge is already in progress in #{worktree}; run `#{recovery_command}` " \
+         "before the next step can dispatch"
+    { ok: false, error: "a merge is in progress in #{worktree}", recovery_command: recovery_command }
+  end
+
+  # reclaim(context, runner:, skip:, now:) -> {reclaimed: [{node:, holder:,
+  # expired:}], extended: [{node:, head:, time:}]}. Reads the ledger fresh on
+  # every call (no cache), which is what makes calling it AFTER absorb (row
+  # 2.20) actually see absorb's own just-landed work rather than a stale
+  # snapshot taken before it.
+  def reclaim(context, runner: Worktree::ShellRunner.new, skip: [], now: Time.now)
+    intent_dir = context.intent_dir
+    content = savepoint_content(intent_dir)
+    entries = NodeLedger.entries_from_content(content)
+    status_map = NodeLedger.status_from_content(content)
+    skip_set = Array(skip).map(&:to_s)
+
+    reclaimed = []
+    extended = []
+
+    status_map.each do |subject, state|
+      next unless state == "running"
+      next unless subject.match?(Savepoint::NODE_SUBJECT_RE)
+      next if skip_set.include?(subject)
+
+      last = entries.select { |e| !e[:torn] && e[:subject] == subject && e[:state] == "running" }.last
+      next unless last
+
+      fields = last[:fields] || {}
+      expires_raw = fields["expires"]
+      expires_at = parse_time(expires_raw)
+      next unless expires_at
+      next if now < expires_at # row 2.5: an unexpired lease is left alone
+
+      holder = fields["holder"]
+      branch = node_branch(context, subject)
+      head_sha, head_time = branch_head(runner, context.worktree, branch)
+      has_new_commits = head_time && head_time > expires_at
+
+      if has_new_commits
+        attempt = current_attempt(entries, subject)
+        count = extension_count(intent_dir, subject, attempt)
+        if count < MAX_EXTENSIONS_PER_ATTEMPT
+          record_extension(intent_dir, subject, attempt, head_sha, now)
+          extended << { node: subject, head: head_sha, time: now.utc.iso8601 }
+          next
+        end
+        # row 2.7: the cap is spent - fall through and reclaim anyway.
+      end
+
+      NodeLedger.append_transition(
+        savepoint_path(intent_dir),
+        subject: subject,
+        state: "reclaimed",
+        fields: { holder: holder, expired: expires_raw },
+        now: now
+      )
+      reclaimed << { node: subject, holder: holder, expired: expires_raw }
+    end
+
+    { reclaimed: reclaimed, extended: extended }
+  end
+
+  # run(context, runner:, skip:, now:, heartbeat:) -> the composed report a
+  # caller with no absorb step to interleave uses directly. Order is fixed on
+  # purpose (row 2.2, row 2.16): abort check, THEN the lease heartbeat, THEN
+  # reclaim - never the reverse, and never a write of any kind before the
+  # abort check has cleared.
+  def run(context, runner: Worktree::ShellRunner.new, skip: [], now: Time.now, heartbeat: Lock.method(:heartbeat))
+    abort_result = abort_if_merging(context, runner: runner)
+    unless abort_result[:ok]
+      return {
+        ok: false, aborted: true, error: abort_result[:error],
+        recovery_command: abort_result[:recovery_command], reclaimed: [], extended: [],
+      }
+    end
+
+    session = context&.session
+    heartbeat.call(context.intent_dir, session: session, now: now) unless blank?(session)
+
+    result = reclaim(context, runner: runner, skip: skip, now: now)
+    {
+      ok: true, aborted: false, error: nil, recovery_command: nil,
+      reclaimed: result[:reclaimed], extended: result[:extended],
+    }
+  end
+
+  # --- internals ---------------------------------------------------------------
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+  private_class_method :blank?
+
+  def savepoint_path(intent_dir)
+    File.join(intent_dir.to_s, "savepoint.md")
+  end
+  private_class_method :savepoint_path
+
+  def savepoint_content(intent_dir)
+    path = savepoint_path(intent_dir)
+    File.exist?(path) ? File.read(path) : ""
+  end
+  private_class_method :savepoint_content
+
+  # The node's own worktree branch (n3's naming: `plastic/<id>--<slug>--<node>`),
+  # derived from the intent id/slug alone - never through NodeWorktree, which
+  # this node does not depend on.
+  def node_branch(context, node)
+    "plastic/#{context.intent_id}--#{context.intent_slug}--#{node}"
+  end
+  private_class_method :node_branch
+
+  # [head_sha, committer_time] for `branch` in `worktree`'s repo, or [nil, nil]
+  # when the worktree is gone, the branch does not exist, or anything else
+  # about the git call fails (row 2.13: never raise).
+  def branch_head(runner, worktree, branch)
+    return [nil, nil] if blank?(worktree) || blank?(branch)
+
+    res = runner.run("-C", worktree, "log", "-1", "--format=%H%x1f%cI", branch)
+    return [nil, nil] unless res.success?
+
+    sha, iso = res.stdout.to_s.strip.split("\x1f")
+    [sha, parse_time(iso)]
+  rescue StandardError
+    [nil, nil]
+  end
+  private_class_method :branch_head
+
+  def parse_time(raw)
+    return nil if blank?(raw)
+
+    Time.iso8601(raw.to_s)
+  rescue ArgumentError
+    nil
+  end
+  private_class_method :parse_time
+
+  # Row 2.18: the attempt number comes from the ledger's own count of
+  # `running` lines since the subject's last terminal line - the exact same
+  # arithmetic NodePacket uses to name that attempt's packet file, so the
+  # extensions file for a `running` line always matches the packet it extends.
+  def current_attempt(entries, subject)
+    ReadySet.attempts_count(entries, subject)
+  end
+  private_class_method :current_attempt
+
+  def extensions_path(intent_dir, node, attempt)
+    File.join(intent_dir.to_s, "packets", "#{node}--a#{attempt}.extensions")
+  end
+  private_class_method :extensions_path
+
+  # Row 2.8: counted from the attempt-scoped file alone, so a prior attempt's
+  # extensions never count against a fresh dispatch.
+  def extension_count(intent_dir, node, attempt)
+    path = extensions_path(intent_dir, node, attempt)
+    return 0 unless File.exist?(path)
+
+    File.read(path).each_line.count { |l| !l.strip.empty? }
+  end
+  private_class_method :extension_count
+
+  # Row 2.9: the observed head sha and the time, one line, append-only.
+  def record_extension(intent_dir, node, attempt, head_sha, now)
+    path = extensions_path(intent_dir, node, attempt)
+    FileUtils.mkdir_p(File.dirname(path))
+    File.open(path, "a") { |f| f.write("#{now.utc.iso8601}  head=#{head_sha}\n") }
+  end
+  private_class_method :record_extension
+end

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]]