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

package/scripts/lib/runner_answer.rb

@@ -0,0 +1,206 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "node_ledger"
+require_relative "ready_set"
+require_relative "graph_file"
+require_relative "atomic_write"
+require_relative "node_file"
+require_relative "node_ids"
+require_relative "runner_core"
+require_relative "node_worktree"
+require_relative "worktree"
+
+# RunnerAnswer (intent 340, G7, n6): closes a decision node into graph.md's
+# ## Decisions (C26), or unparks a work node the runner parked at
+# `needs_decision` (327 D22). Both share one precondition - the target must
+# currently BE at `needs_decision` - and one shape of input: a non-empty
+# owner answer.
+#
+# A decision node writes its text into ## Decisions through
+# GraphFile.append_decision (temp-plus-rename, matrix row 6.7) and closes
+# with `done verdict=answered`. Any other kind unparks instead:
+# `READY_PRIOR_STATES` (ready_set.rb) accepts `planned` and
+# `failed_verification` back into dispatch, so below ReadySet::DEFAULT_CAPS'
+# HARD attempt backstop, writing `planned` is enough. At or above it, a
+# plain `planned` line changes nothing about `failed_verification_count`
+# (counted per subject over the WHOLE ledger, never reset) - only a brand
+# new subject id starts clean, so the node is superseded and a successor is
+# minted carrying its body, files and needs across.
+#
+# Pure and dependency-injected down to the clock and the rename call; every
+# test here drives a real tmpdir intent directory, never a real ~/.plastic
+# install.
+module RunnerAnswer
+  module_function
+
+  # v2 NEW-6: `blocked` is neither in `ReadySet::READY_PRIOR_STATES` nor in
+  # `ReadySet::TERMINAL_STATES` - a node the runner itself blocks (a broken
+  # `project.yml`, a core-integrity drift, an unresolvable graph) was
+  # unrecoverable forever, since `answer` refused everything but
+  # `needs_decision`. Both park an executor's own dispatch pending an owner
+  # decision; only the reason differs.
+  PARKED_STATES = %w[needs_decision blocked].freeze
+
+  def answer(context, node:, text:, now: Time.now, ledger: NodeLedger,
+             caps: ReadySet::DEFAULT_CAPS, renamer: File.method(:rename),
+             worktree: NodeWorktree, runner: Worktree::ShellRunner.new)
+    node = node.to_s
+    intent_dir = context.intent_dir
+    graph_path = File.join(intent_dir, "graph.md")
+
+    return refusal("empty_answer") if text.to_s.strip.empty?
+
+    # 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", errors: loaded[:errors]) unless loaded[:ok]
+
+    nodes_decl = loaded[:nodes]
+    edges = loaded[:edges]
+    before_content = read_savepoint(intent_dir)
+    entries = NodeLedger.entries_from_content(before_content)
+    current_state = NodeLedger.status_for_content(before_content, node)
+
+    # v2 NEW-6/row 11.10/11.11: parked is `needs_decision` OR `blocked` -
+    # anything else (planned, running, done, ...) is a healthy node with no
+    # evidence to release it on, and must stay refused exactly as before.
+    return refusal("not_parked") unless PARKED_STATES.include?(current_state)
+
+    kind = (nodes_decl[node] || {})[:kind]
+    respun_to = nil
+
+    if kind.to_s == "decision" && current_state == "needs_decision"
+      gf = GraphFile.append_decision(graph_path, text.to_s.strip, renamer: renamer)
+      return refusal("graph_write_failed", errors: gf[:errors]) unless gf[:ok]
+
+      # A `done` line's attribution (a non-blank `holder=`) is what
+      # ReadySet.ready? requires of a needs target before a successor may
+      # become ready (NodeLedger.attributed?): an unattributed done line
+      # closes the decision node's own status but never releases anything
+      # downstream, so the holder is the session driving this very answer.
+      fields = { gates: "answer", verdict: "answered" }
+      fields[:holder] = context.session unless blank?(context.session)
+      result = ledger.append_transition(savepoint_path(intent_dir), subject: node, state: "done",
+                                         fields: fields, now: now)
+      return refusal("append_failed") unless result == :written
+    else
+      cap = caps.fetch(kind.to_s) { caps["work"] }
+      attempts = ReadySet.attempts_count(entries, node)
+
+      if cap && attempts >= cap
+        respun_to = respin(intent_dir, node, nodes_decl, edges, ledger: ledger, now: now, renamer: renamer,
+                            holder: context.session, context: context, worktree: worktree, runner: runner)
+      else
+        fields = {}
+        fields[:holder] = context.session unless blank?(context.session)
+        result = ledger.append_transition(savepoint_path(intent_dir), subject: node, state: "planned",
+                                           fields: fields, now: now)
+        return refusal("append_failed") unless result == :written
+      end
+    end
+
+    RunnerCore.render_status(context)
+
+    {
+      ok: true, respun_to: respun_to, errors: [],
+      newly_ready: newly_ready(intent_dir, before_content: before_content, before_nodes: nodes_decl, before_edges: edges),
+    }
+  end
+
+  # --- the hard-cap respin (327 D22) ------------------------------------------
+
+  def respin(intent_dir, node, nodes_decl, edges, ledger:, now:, renamer:, holder: nil,
+             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)
+
+    fields = { by: succ_id }
+    fields[:holder] = holder unless blank?(holder)
+    ledger.append_transition(savepoint_path(intent_dir), subject: node, state: "superseded",
+                              fields: fields, now: now)
+
+    # M5/D7: a superseded node's evidence no longer needs to survive - its
+    # own worktree releases here, the same as `done`'s does in RunnerAbsorb.
+    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
+
+  # --- what became ready (C26) ------------------------------------------------
+
+  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, errors: [])
+    { ok: false, reason: reason, errors: errors, 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

package/scripts/lib/runner_core.rb

@@ -0,0 +1,194 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "arm"
+require_relative "lock"
+require_relative "worktree"
+require_relative "ready_set"
+require_relative "node_ledger"
+require_relative "graph_file"
+
+# RunnerCore (intent 340, G7, n1): the shared context every scripts/runner
+# verb needs, resolved once, plus the two read-only queries (status,
+# complete?) and the one write (render_status) this node ships. Session
+# resolution mirrors NodeTransition.resolve_owning_session
+# (scripts/node-transition) exactly, so `running`'s ownership rule and the
+# runner's own idea of "who holds this intent" never drift apart.
+#
+# Pure and dependency-injected: #context takes intent_dir:, home:, and
+# optional session:/env: overrides (the CLI passes the real
+# ENV["CLAUDE_CODE_SESSION_ID"] at its own boundary, the same place
+# node-transition's main reads it, never inside this library). It never
+# raises across its boundary: every field is resolved independently, so a
+# missing or malformed graph.md lands in `errors` and every other field
+# still resolves. #status and #complete? read the filesystem but write
+# nothing; #render_status is the one write, and it goes through
+# GraphFile.write_status, the existing atomic writer.
+module RunnerCore
+  module_function
+
+  Context = Struct.new(
+    :intent_dir, :intent_id, :intent_slug, :store, :plastic_home,
+    :session, :worktree, :worktree_branch, :graph, :errors,
+    keyword_init: true
+  )
+
+  def context(intent_dir:, home: Dir.home, session: nil, env: ENV["CLAUDE_CODE_SESSION_ID"])
+    dir = File.expand_path(intent_dir.to_s)
+    errors = []
+
+    intent_id = safe(errors, "intent id") { Arm.intent_id_for(dir) }
+    intent_slug = safe(errors, "intent slug") { Worktree.slug_from_dir(dir) }
+    store = safe(errors, "store") { Arm.store_for(dir) }
+
+    # Arm.home_for's own docstring says it returns the PARENT of `.plastic`
+    # (the OS home, honestly named `home_root` here) - everywhere else in the
+    # tree, including CoreIntegrity.check and RunnerProposals' templates_dir,
+    # `plastic_home` means the `.plastic` directory itself. Row 9.5: append
+    # it once, here, so every consumer of `context.plastic_home` sees the
+    # same directory `manifest.json` and `templates/` actually live in.
+    home_root = safe(errors, "plastic home") { Arm.home_for(dir, home: home) } || home
+    plastic_home = File.join(home_root, ".plastic")
+
+    resolved_session = safe(errors, "session") do
+      resolve_owning_session(dir, explicit: session, env_session: env, store: store, intent_id: intent_id)
+    end
+
+    # Arm.worktree_block's own `home:` parameter is the OS-home fallback
+    # `Arm.home_for` takes (it re-derives home_for internally), not the
+    # `.plastic` directory - pass it `home_root`, never `plastic_home`.
+    worktree_block = safe(errors, "worktree") { Arm.worktree_block(intent_dir: dir, home: home_root) } || {}
+
+    graph = safe(errors, "graph") { ReadySet.load_graph(dir) } ||
+            { ok: false, edges: {}, nodes: {}, errors: ["graph could not be resolved"] }
+    errors.concat(graph[:errors] || []) unless graph[:ok]
+
+    Context.new(
+      intent_dir: dir,
+      intent_id: intent_id,
+      intent_slug: intent_slug,
+      store: store,
+      plastic_home: plastic_home,
+      session: resolved_session,
+      worktree: worktree_block["code"],
+      worktree_branch: worktree_block["code_branch"],
+      graph: graph,
+      errors: errors
+    )
+  end
+
+  # Mirrors NodeTransition.resolve_owning_session (scripts/node-transition,
+  # intent 335 G2): an explicit session is authoritative and never falls
+  # through (an explicit non-owner is refused outright, never silently
+  # granted ownership through a fallback); without it, try env_session, then
+  # the derived `auto-` key, keeping the first candidate that actually HOLDS
+  # the lock.
+  def resolve_owning_session(intent_dir, explicit:, env_session:, store:, intent_id:)
+    if explicit && !explicit.to_s.strip.empty?
+      return Lock.holds?(intent_dir, session: explicit) ? explicit : nil
+    end
+
+    candidates = [env_session, Arm.derive_key(store, intent_id)].reject { |c| c.to_s.strip.empty? }
+    candidates.find { |c| Lock.holds?(intent_dir, session: c) }
+  end
+
+  # status(context) -> {id => {kind:, state:, ready:, blockers:,
+  # last_transition:}} for every node graph.md DECLARES, whether or not it
+  # has a ledger line yet (a node with no line reads as "planned", the
+  # ledger's own implicit starting state). Writes NOTHING: savepoint.md's
+  # content is read once and every node's readiness is evaluated against
+  # that one read, mirroring the way node-transition's own precondition
+  # never re-reads the file per node.
+  def status(context)
+    edges = (context.graph || {})[:edges] || {}
+    nodes = (context.graph || {})[:nodes] || {}
+    content = savepoint_content(context.intent_dir)
+    entries = NodeLedger.entries_from_content(content)
+
+    nodes.each_with_object({}) do |(id, decl), rows|
+      readiness = ReadySet.ready?(content: content, subject: id, graph: { edges: edges }, nodes: nodes)
+      last = entries.select { |e| !e[:torn] && e[:subject] == id }.last
+
+      rows[id] = {
+        kind: decl[:kind],
+        state: NodeLedger.status_for_content(content, id),
+        ready: readiness[:ready],
+        blockers: readiness[:blockers],
+        last_transition: last,
+      }
+    end
+  end
+
+  # complete?(context) -> true only when EVERY declared node resolves to a
+  # terminal state (done, superseded, abandoned). An empty declared-node set,
+  # or any node that is merely not-ready (blocked, needs_decision, deferred,
+  # or simply not yet attempted), is stalled, not complete - never shortcut
+  # to "the ready set is empty".
+  def complete?(context)
+    rows = status(context)
+    return false if rows.empty?
+
+    rows.values.all? { |v| ReadySet::TERMINAL_STATES.include?(v[:state]) }
+  end
+
+  # render_status(context) -> GraphFile.write_status's own {ok:, errors:}.
+  # One row per node graph.md declares, including a node with no ledger line
+  # (which renders "planned"); a graph.md with no ## Status section gets one
+  # created, never a raise - both guarantees come from GraphFile.write_status
+  # itself, this method only ever supplies the rows.
+  #
+  # M8: Detail carries the readiness BLOCKERS only for a node still in play;
+  # a TERMINAL node (done, superseded, abandoned) instead renders its own
+  # last transition's fields, so a `done` node reads its commit rather than
+  # the nonsense "n1 is done, not eligible to enter running" every later
+  # transition used to rewrite it to.
+  def render_status(context)
+    rows = status(context)
+    graph_rows = rows.map do |id, view|
+      { node: id, state: view[:state], detail: detail_for(view) }
+    end
+    GraphFile.write_status(File.join(context.intent_dir.to_s, "graph.md"), graph_rows)
+  end
+
+  def detail_for(view)
+    if ReadySet::TERMINAL_STATES.include?(view[:state])
+      transition_detail(view[:last_transition])
+    else
+      Array(view[:blockers]).join("; ")
+    end
+  end
+
+  def transition_detail(last_transition)
+    return "" unless last_transition
+
+    fields = last_transition[:fields] || {}
+    fields.map { |k, v| "#{k}=#{v}" }.join(" ")
+  end
+
+  def savepoint_content(intent_dir)
+    path = File.join(intent_dir.to_s, "savepoint.md")
+    File.exist?(path) ? File.read(path) : ""
+  end
+
+  def safe(errors, label)
+    yield
+  rescue StandardError => e
+    errors << "#{label}: #{e.message}"
+    nil
+  end
+
+  # safe_load_graph(intent_dir) -> ReadySet.load_graph's own result, or the
+  # same {ok: false, edges: {}, nodes: {}, errors: [...]} shape when the
+  # graph is not the well-formed UTF-8 ReadySet assumes (post-execution
+  # review M9). `step`, `answer` and `rewind` all re-read and re-parse
+  # graph.md fresh, after RunnerCore.context's own first, already-guarded
+  # read (`safe` above) - a raise from THAT second read crossed the
+  # runner's boundary as a raw stack trace. The one safe loader every such
+  # call site uses now, so a graph that goes bad between two reads refuses
+  # cleanly everywhere, not just here.
+  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}"] }
+  end
+end