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

package/scripts/lib/runner_proposals.rb

@@ -0,0 +1,275 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "node_file"
+require_relative "node_ids"
+require_relative "graph_edges"
+require_relative "graph_file"
+require_relative "atomic_write"
+require_relative "ready_set"
+require_relative "node_ledger"
+require_relative "savepoint"
+require_relative "work_graph_validator"
+
+# RunnerProposals (intent 340, G7, n6): accepts or refuses what an executor
+# proposed in its return (327 D15, D28, D30). The runner mints every node id;
+# an executor never sees or picks one. A proposed node is scaffolded from its
+# kind's template, its id substituted everywhere the template hard-codes its
+# own placeholder (`n1`, `v1`, `d1`, `r1` - the frontmatter key, the H1, and
+# the failure-mode matrix heading), and appended to graph.md's ## Graph
+# section as a fresh, undispatched line - no ledger line at all, which reads
+# as "planned" by construction. A proposed edge is accepted only when both
+# endpoints exist (among the already-declared nodes or a node this very call
+# is minting), its head is not `running`, and the resulting graph stays
+# acyclic (D30); a refusal writes one ledger comment naming which of the
+# three failed.
+#
+# One call, one all-or-nothing write (D15's "nothing is partially written"):
+# every proposed node and edge is validated BEFORE anything touches disk. A
+# single rejected edge refuses the WHOLE call, leaving graph.md and nodes/
+# byte-identical to how #accept found them, and burning no minted id (an id
+# is only ever consumed once a node FILE actually exists; NodeIds.taken never
+# sees one this call abandoned).
+#
+# Pure and dependency-injected: the full validator re-run (327 D17's "a mid-
+# run scaffold is checked, not merely accepted"), the templates directory,
+# the clock and the rename call are all injectable keyword arguments with
+# real defaults, so a test never touches a real ~/.plastic install.
+module RunnerProposals
+  module_function
+
+  KIND_TEMPLATES = {
+    "work" => "node-work.md",
+    "verify" => "node-verify.md",
+    "decision" => "node-decision.md",
+    "research" => "node-research.md",
+  }.freeze
+
+  REVIEW_FIX_CAP = 2
+
+  # accept(context, proposer:, proposed_nodes:, proposed_edges:, now:,
+  # validator:, templates_dir:, renamer:) -> {ok:, minted:, validator:,
+  # errors:}. `proposer` names the node whose return carried these proposals
+  # - it is used only to attribute the refusal comment; the runner itself
+  # decides everything about the proposal's fate.
+  def accept(context, proposer:, proposed_nodes: [], proposed_edges: [], now: Time.now,
+             validator: WorkGraphValidator.method(:validate), templates_dir: nil,
+             renamer: File.method(:rename))
+    intent_dir = context.intent_dir
+    graph_path = File.join(intent_dir, "graph.md")
+    templates_root = templates_dir || File.join(context.plastic_home.to_s, "templates")
+
+    # v2 NEW-5/row 11.8: `ReadySet.load_graph` documents itself as never
+    # raising, but that guarantee is only as good as the parser underneath
+    # it - a `graph.md` carrying invalid UTF-8 bytes raises `ArgumentError`
+    # out of `GraphFile`'s own fence-line scan before `load_graph` ever gets
+    # a chance to catch it. M4 made this call reachable straight from
+    # `RunnerAbsorb#absorb`, so a `--return` carrying a proposal against a
+    # malformed graph used to die with a raw stack trace instead of a plain
+    # refusal.
+    loaded = safe_load_graph(intent_dir)
+    return refuse(intent_dir, proposer, "graph.md is unreadable: #{loaded[:errors].join('; ')}", now) if loaded[:unreadable]
+
+    declared = loaded[:edges].keys
+    status_map = NodeLedger.status_from_content(read_savepoint(intent_dir))
+
+    mint_pool = NodeIds.taken(intent_dir).dup
+    node_specs = []
+
+    Array(proposed_nodes).each do |raw|
+      spec = stringify(raw)
+      kind = spec["kind"].to_s
+      template_name = KIND_TEMPLATES[kind]
+      unless template_name
+        return refuse(intent_dir, proposer, "proposed node kind #{kind.inspect} has no template", now)
+      end
+
+      template_path = File.join(templates_root, template_name)
+      unless File.exist?(template_path)
+        return refuse(intent_dir, proposer, "missing template for kind #{kind.inspect} at #{template_path}", now)
+      end
+
+      id = NodeFile.mint_id(kind, mint_pool)
+      mint_pool << id
+      node_specs << {
+        id: id, kind: kind, template_path: template_path,
+        needs: Array(spec["needs"]).map(&:to_s),
+        files: spec["files"].nil? ? nil : Array(spec["files"]),
+        budget: spec["budget"],
+      }
+    end
+
+    trial_edges = loaded[:edges].dup
+    node_specs.each { |s| trial_edges[s[:id]] = s[:needs] }
+    known_ids = declared + node_specs.map { |s| s[:id] }
+
+    edge_specs = []
+    Array(proposed_edges).each do |raw|
+      e = stringify(raw)
+      from = e["from"].to_s
+      to = e["to"].to_s
+
+      unless known_ids.include?(from) && known_ids.include?(to)
+        return refuse(intent_dir, proposer,
+                       "edge #{from}->#{to} refused (endpoint_unknown): both ends must be a declared or proposed node", now)
+      end
+
+      if status_map.fetch(from, "planned") == "running"
+        return refuse(intent_dir, proposer,
+                       "edge #{from}->#{to} refused (head_running): #{from} is currently running", now)
+      end
+
+      trial = trial_edges.dup
+      trial[from] = (trial[from] || []) + [to]
+      if GraphEdges.cycle(trial)
+        return refuse(intent_dir, proposer,
+                       "edge #{from}->#{to} refused (would_cycle): would make the graph cyclic", now)
+      end
+
+      trial_edges = trial
+      edge_specs << { from: from, to: to }
+    end
+
+    trial_nodes = loaded[:nodes].merge(node_specs.to_h { |s| [s[:id], { kind: s[:kind] }] })
+    existing_fixes = review_fix_count(loaded[:edges], loaded[:nodes])
+    trial_fixes = review_fix_count(trial_edges, trial_nodes)
+    if trial_fixes > [existing_fixes, REVIEW_FIX_CAP].max
+      return refuse(intent_dir, proposer,
+                     "proposal refused (review_fix_cap): would make #{trial_fixes} review fixes, the cap is #{REVIEW_FIX_CAP}", now)
+    end
+
+    node_specs.each { |s| scaffold_node_file(intent_dir, s) }
+    if node_specs.any? || edge_specs.any?
+      append_to_graph(graph_path, node_specs: node_specs, edge_specs: edge_specs, renamer: renamer)
+    end
+
+    # v2 NEW-5/row 11.8: the accept itself already landed on disk by this
+    # point (327 D17's "a mid-run scaffold is checked" runs strictly AFTER
+    # the write) - a raising validator must report a broken verdict, never
+    # turn an already-successful accept into an uncaught exception.
+    { ok: true, minted: node_specs.map { |s| s[:id] }, validator: safe_validate(validator, intent_dir), errors: [] }
+  end
+
+  # --- review fixes (355 D4) -------------------------------------------------
+
+  # review_fix_count(edges, nodes) -> how many work nodes GraphEdges.review_fixes
+  # finds, a node's kind read from its declaration and, when that is missing,
+  # from its id's NodeFile::KIND_PREFIX (343 D6).
+  def review_fix_count(edges, nodes)
+    ids = (edges.keys + edges.values.flatten).uniq
+    kinds = ids.to_h { |id| [id, (nodes[id] || {})[:kind] || NodeFile::KIND_PREFIX.key(id.to_s[/\A[a-z]+/])] }
+    GraphEdges.review_fixes(edges, kinds).length
+  end
+
+  # --- node scaffolding --------------------------------------------------
+
+  # A template's own placeholder id ("n1", "v1", ...) is replaced only as a
+  # whole token, so minting past 9 (a proposed "n10") never mangles a
+  # coincidental substring match.
+  def substitute_id(text, old_id, new_id)
+    text.to_s.gsub(/(?<![A-Za-z0-9_-])#{Regexp.escape(old_id.to_s)}(?![A-Za-z0-9_-])/, new_id.to_s)
+  end
+
+  def scaffold_node_file(intent_dir, spec)
+    parsed_template = NodeFile.parse(spec[:template_path])
+    old_id = parsed_template[:node]
+    raw = File.read(spec[:template_path])
+    parts = raw.split("---", 3)
+    body = substitute_id(parts[2].to_s, old_id, spec[:id])
+
+    files = spec[:files].nil? ? parsed_template[:files] : spec[:files]
+    budget = spec[:budget].nil? ? parsed_template[:budget] : spec[:budget]
+
+    frontmatter = "---\nnode: #{spec[:id]}\nkind: #{spec[:kind]}\nfiles: [#{Array(files).join(', ')}]\nbudget: #{budget}\n---"
+    path = File.join(intent_dir, "nodes", "#{spec[:id]}.md")
+    FileUtils.mkdir_p(File.dirname(path))
+    File.write(path, "#{frontmatter}#{body}")
+  end
+  private_class_method :scaffold_node_file
+
+  # --- graph.md editing ----------------------------------------------------
+
+  # Appends one "- <id> needs <targets>" line per minted node, then applies
+  # each accepted edge onto the line (existing or just-appended) whose id
+  # matches its `from`, through GraphFile's own public section helpers
+  # (section_bounds, section_body, replace_or_append_section - none of them
+  # private_class_method'd) so this stays a plain text edit, never a second
+  # bespoke parser.
+  def append_to_graph(graph_path, node_specs:, edge_specs:, renamer:)
+    content = File.read(graph_path)
+    bounds = GraphFile.section_bounds(content, "## Graph")
+    return unless bounds
+
+    body = GraphFile.section_body(content, "## Graph").to_s
+    lines = body.split("\n")
+
+    node_specs.each do |s|
+      rendered = s[:needs].empty? ? "nothing" : s[:needs].join(" ")
+      lines << "- #{s[:id]} needs #{rendered}"
+    end
+
+    edge_specs.each do |e|
+      idx = lines.index { |l| l.strip.match?(/\A-\s*#{Regexp.escape(e[:from])}\s+needs\b/) }
+      next unless idx
+
+      stripped = lines[idx].strip
+      m = stripped.match(/\A-\s*(\S+)\s+needs\s+(.*)\z/)
+      targets = m[2].to_s.strip.split(/\s+/)
+      targets = [] if targets == ["nothing"]
+      targets << e[:to] unless targets.include?(e[:to])
+      lines[idx] = "- #{e[:from]} needs #{targets.empty? ? 'nothing' : targets.join(' ')}"
+    end
+
+    new_body = lines.join("\n")
+    new_content = GraphFile.replace_or_append_section(content, "## Graph", new_body)
+    AtomicWrite.write(graph_path, new_content, renamer: renamer)
+  end
+  private_class_method :append_to_graph
+
+  # --- refusal -------------------------------------------------------------
+
+  # One ledger comment (a plain milestone-style line through Savepoint's own
+  # public append primitive, never a state transition - a refused proposal
+  # changes nothing about the proposer's own status) naming which of the
+  # three checks failed. Dedup'd by (stage, text) like every other such line,
+  # so an identical refusal repeated verbatim across retries writes once.
+  def refuse(intent_dir, proposer, reason, now)
+    Savepoint.append_savepoint_line(intent_dir, "Proposal", "#{proposer}: #{reason}", now)
+    { ok: false, minted: [], validator: nil, errors: [reason] }
+  end
+  private_class_method :refuse
+
+  # --- guarded re-entries into graph.md (v2 NEW-5/row 11.8) -------------------
+
+  # `unreadable: true` marks the ONE case a raise actually happened -
+  # distinct from `ReadySet.load_graph`'s own ordinary `ok: false` (a
+  # cyclic graph, a missing node file, ...), which callers here already
+  # tolerate and must keep tolerating unchanged.
+  def safe_load_graph(intent_dir)
+    ReadySet.load_graph(intent_dir)
+  rescue StandardError => e
+    { ok: false, edges: {}, nodes: {}, errors: ["graph.md could not be read: #{e.message}"], unreadable: true }
+  end
+  private_class_method :safe_load_graph
+
+  def safe_validate(validator, intent_dir)
+    validator.call(intent_dir)
+  rescue StandardError => e
+    { ok: false, missing: [], errors: ["graph.md could not be validated: #{e.message}"] }
+  end
+  private_class_method :safe_validate
+
+  # --- internals -------------------------------------------------------------
+
+  def stringify(hash)
+    (hash || {}).each_with_object({}) { |(k, v), memo| memo[k.to_s] = v }
+  end
+  private_class_method :stringify
+
+  def read_savepoint(intent_dir)
+    path = File.join(intent_dir.to_s, "savepoint.md")
+    File.exist?(path) ? File.read(path) : ""
+  end
+  private_class_method :read_savepoint
+end

package/scripts/lib/runner_rewind.rb

@@ -0,0 +1,201 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "node_ledger"
+require_relative "ready_set"
+require_relative "node_file"
+require_relative "node_ids"
+require_relative "graph_file"
+require_relative "atomic_write"
+require_relative "runner_core"
+require_relative "worktree"
+require_relative "node_worktree"
+
+# RunnerRewind (intent 340, G7, n6): resets the intent branch to a node's own
+# recorded commit, marks every downstream node superseded (its evidence no
+# longer stands once the code it was built on is gone), and respins the
+# rewound node itself the same way RunnerAnswer's hard-cap path does - never
+# a plain `planned` line, because `failed_verification_count` is counted per
+# subject id over the WHOLE ledger and never resets; only a brand new id
+# starts clean.
+#
+# Internal, confirm-gated (327 D15's rewind clause): `confirm:` must be
+# explicitly true, and the whole intent must be quiescent (no `running` node
+# anywhere) before a branch reset is safe to make - resetting the branch
+# under a live executor's own worktree would move the base it is building on
+# out from under it.
+#
+# Pure and dependency-injected: every git call goes through an injected
+# `runner:` (default Worktree::ShellRunner), always `-C <path>`, never cwd;
+# the clock and the rename call are injectable the same way every other
+# runner_* module here already is.
+module RunnerRewind
+  module_function
+
+  def rewind(context, node:, confirm:, now: Time.now, ledger: NodeLedger,
+             runner: Worktree::ShellRunner.new, renamer: File.method(:rename),
+             worktree: NodeWorktree)
+    node = node.to_s
+    return refusal("confirm_required") unless confirm
+
+    intent_dir = context.intent_dir
+    # M9: a second, unguarded re-parse of graph.md - RunnerCore.context's
+    # own first read is already safe, but this fresh read is not.
+    loaded = RunnerCore.safe_load_graph(intent_dir)
+    return refusal("invalid_graph", detail: Array(loaded[:errors]).join("; ")) unless loaded[:ok]
+
+    edges = loaded[:edges]
+    nodes_decl = loaded[:nodes]
+    before_content = read_savepoint(intent_dir)
+    entries = NodeLedger.entries_from_content(before_content)
+    status_map = NodeLedger.status_from_content(before_content)
+
+    return refusal("a_node_is_running") if status_map.value?("running")
+
+    commit = last_commit(entries, node)
+    return refusal("no_recorded_commit") if commit.nil? || commit.to_s.strip.empty?
+
+    return refusal("no_intent_worktree") if blank?(context.worktree)
+
+    reset = runner.run("-C", context.worktree, "reset", "--hard", commit)
+    return refusal("git_reset_failed", detail: reset.stderr.to_s.strip) unless reset.success?
+
+    downstream = downstream_of(node, edges)
+    downstream.each do |d|
+      ledger.append_transition(savepoint_path(intent_dir), subject: d, state: "superseded",
+                                fields: { by: node }, now: now)
+      # M5/D7: a rewind-superseded node's evidence no longer stands once the
+      # code it was built on is gone - its worktree releases here too.
+      worktree.release(context, node: d, state: "superseded", runner: runner)
+    end
+
+    succ_id = respin(intent_dir, node, nodes_decl, edges, ledger: ledger, now: now, renamer: renamer,
+                      context: context, worktree: worktree, runner: runner)
+
+    RunnerCore.render_status(context)
+
+    {
+      ok: true, reset_to: commit, superseded: downstream, respun_to: succ_id, errors: [],
+      newly_ready: newly_ready(intent_dir, before_content: before_content, before_nodes: nodes_decl,
+                                before_edges: edges),
+    }
+  end
+
+  # --- downstream: everything that, directly or transitively, needs the
+  # rewound node - the mirror of ReadySet.critical_paths' own successors map.
+
+  def downstream_of(node, edges)
+    successors = Hash.new { |h, k| h[k] = [] }
+    edges.each { |id, targets| (targets || []).each { |t| successors[t] << id } }
+
+    seen = []
+    stack = successors[node].dup
+    until stack.empty?
+      n = stack.pop
+      next if seen.include?(n)
+
+      seen << n
+      stack.concat(successors[n] || [])
+    end
+    seen.sort
+  end
+  private_class_method :downstream_of
+
+  def last_commit(entries, node)
+    last = entries.select { |e| !e[:torn] && e[:subject] == node && e[:state] == "done" }.last
+    last && (last[:fields] || {})["commit"]
+  end
+  private_class_method :last_commit
+
+  # --- the respin (327 D22, same shape as RunnerAnswer's hard-cap path) ------
+
+  def respin(intent_dir, node, nodes_decl, edges, ledger:, now:, renamer:,
+             context:, worktree: NodeWorktree, runner: Worktree::ShellRunner.new)
+    decl = nodes_decl[node] || {}
+    kind = decl[:kind]
+    node_path = ReadySet.find_node_path(intent_dir, node)
+    parsed = NodeFile.parse(node_path)
+
+    mint_pool = NodeIds.taken(intent_dir).dup
+    succ_id = NodeFile.mint_id(kind, mint_pool)
+
+    raw = File.read(node_path)
+    parts = raw.split("---", 3)
+    body = substitute_id(parts[2].to_s, node, succ_id)
+    files = parsed[:files] || decl[:files] || []
+    budget = parsed[:budget]
+
+    frontmatter = "---\nnode: #{succ_id}\nkind: #{kind}\nfiles: [#{Array(files).join(', ')}]\nbudget: #{budget}\n---"
+    succ_path = File.join(intent_dir, "nodes", "#{succ_id}.md")
+    FileUtils.mkdir_p(File.dirname(succ_path))
+    File.write(succ_path, "#{frontmatter}#{body}")
+
+    append_graph_line(File.join(intent_dir, "graph.md"), succ_id, edges[node] || [], renamer: renamer)
+
+    ledger.append_transition(savepoint_path(intent_dir), subject: node, state: "superseded",
+                              fields: { by: succ_id }, now: now)
+
+    # M5/D7: the rewound node's own worktree releases too, same as the
+    # downstream nodes above.
+    worktree.release(context, node: node, state: "superseded", runner: runner)
+
+    succ_id
+  end
+  private_class_method :respin
+
+  def append_graph_line(graph_path, id, needs, renamer:)
+    content = File.read(graph_path)
+    body = GraphFile.section_body(content, "## Graph").to_s
+    lines = body.split("\n")
+    rendered = needs.empty? ? "nothing" : needs.join(" ")
+    lines << "- #{id} needs #{rendered}"
+    new_body = lines.join("\n")
+    new_content = GraphFile.replace_or_append_section(content, "## Graph", new_body)
+    AtomicWrite.write(graph_path, new_content, renamer: renamer)
+  end
+  private_class_method :append_graph_line
+
+  def substitute_id(text, old_id, new_id)
+    text.to_s.gsub(/(?<![A-Za-z0-9_-])#{Regexp.escape(old_id.to_s)}(?![A-Za-z0-9_-])/, new_id.to_s)
+  end
+  private_class_method :substitute_id
+
+  def newly_ready(intent_dir, before_content:, before_nodes:, before_edges:)
+    after = RunnerCore.safe_load_graph(intent_dir)
+    return [] unless after[:ok]
+
+    after_content = read_savepoint(intent_dir)
+
+    after[:nodes].keys.select do |id|
+      was = before_nodes.key?(id) &&
+            ReadySet.ready?(content: before_content, subject: id, graph: { edges: before_edges },
+                             nodes: before_nodes)[:ready]
+      now_ready = ReadySet.ready?(content: after_content, subject: id, graph: { edges: after[:edges] },
+                                   nodes: after[:nodes])[:ready]
+      now_ready && !was
+    end.sort
+  end
+  private_class_method :newly_ready
+
+  def refusal(reason, detail: nil)
+    { ok: false, reason: reason, detail: detail, reset_to: nil, superseded: [], respun_to: nil, newly_ready: [] }
+  end
+  private_class_method :refusal
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+  private_class_method :blank?
+
+  def read_savepoint(intent_dir)
+    path = savepoint_path(intent_dir)
+    File.exist?(path) ? File.read(path) : ""
+  end
+  private_class_method :read_savepoint
+
+  def savepoint_path(intent_dir)
+    File.join(intent_dir.to_s, "savepoint.md")
+  end
+  private_class_method :savepoint_path
+end