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

package/scripts/lib/graph_file.rb

@@ -0,0 +1,246 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_edges"
+require_relative "atomic_write"
+
+# GraphFile (intent 334, n2): the four graph.md sections (## Goal,
+# ## Decisions, ## Graph, ## Status), the verify:-none directive, and the two
+# writers - write_status and append_decision. Both writers refuse a cyclic
+# graph and both go through AtomicWrite (fold D19r). Fence-aware everywhere a
+# heading is located, so a fenced example carrying a fake "## " line never
+# splits or ends a real section (fold A8's sibling concern, applied to
+# section boundaries rather than edge lines).
+module GraphFile
+  module_function
+
+  FENCE_LINE_RE = /\A\s{0,3}(`{3,}|~{3,})/.freeze
+  DIRECTIVE_RE = /\A-\s*verify:\s*none(?:\s+reason=(.*))?\z/i.freeze
+
+  # {ok:, goal:, decisions:, graph:, status:, verify:, errors:}. `graph` is
+  # GraphEdges.parse's own Result hash, over the Graph section text with any
+  # verify:-none directive line stripped first (fold A8). A missing ## Graph
+  # section, or one that declares no nodes, is an error naming which (fold
+  # A10).
+  def parse(path)
+    return failure(["graph file not found: #{path}"]) unless File.exist?(path)
+
+    content = File.read(path)
+    goal = section_body(content, "## Goal")
+    decisions = section_body(content, "## Decisions")
+    graph_section = section_body(content, "## Graph")
+    status = section_body(content, "## Status")
+
+    errors = []
+    if graph_section.nil?
+      errors << "missing ## Graph section"
+      return { ok: false, goal: goal, decisions: decisions, graph: nil, status: status, verify: nil, errors: errors }
+    end
+
+    directive, directive_errors, remaining = extract_verify_directive(graph_section)
+    errors.concat(directive_errors)
+
+    parsed_graph = GraphEdges.parse(strip_fenced_blocks(remaining))
+    errors.concat(parsed_graph[:errors])
+    errors << "## Graph declares no nodes" if parsed_graph[:nodes].empty?
+
+    { ok: errors.empty?, goal: goal, decisions: decisions, graph: parsed_graph, status: status, verify: directive, errors: errors }
+  end
+
+  def failure(errors)
+    { ok: false, goal: nil, decisions: nil, graph: nil, status: nil, verify: nil, errors: errors }
+  end
+
+  # Rows shaped {node:, state:, detail:} parsed back from the ## Status
+  # table (D8r's round-trip guarantee).
+  def status_rows(path)
+    parsed = parse(path)
+    rows_from_table(parsed[:status])
+  end
+
+  # Replace the whole ## Status section with rows, creating the section if
+  # absent. Refuses a cyclic graph (D8r); goes through AtomicWrite (D19r).
+  def write_status(path, rows, renamer: File.method(:rename))
+    guard = refuse_if_cyclic(path)
+    return guard if guard
+
+    content = File.read(path)
+    new_content = replace_or_append_section(content, "## Status", render_status_table(rows))
+    AtomicWrite.write(path, new_content, renamer: renamer)
+    { ok: true, errors: [] }
+  end
+
+  # Append one answered decision as a list item to ## Decisions (C26),
+  # leaving every other section byte-identical. Refuses a cyclic graph.
+  def append_decision(path, text, renamer: File.method(:rename))
+    guard = refuse_if_cyclic(path)
+    return guard if guard
+
+    content = File.read(path)
+    bounds = section_bounds(content, "## Decisions")
+    return { ok: false, errors: ["missing ## Decisions section"] } unless bounds
+
+    start_idx, end_idx = bounds
+    heading_line_end = line_end(content, start_idx)
+    body = content[heading_line_end...end_idx]
+    trimmed = body.rstrip
+    trailing = body[trimmed.length..]
+    new_body = trimmed.empty? ? "- #{text}#{trailing}" : "#{trimmed}\n- #{text}#{trailing}"
+    new_content = content[0...heading_line_end] + new_body + content[end_idx..]
+    AtomicWrite.write(path, new_content, renamer: renamer)
+    { ok: true, errors: [] }
+  end
+
+  def refuse_if_cyclic(path)
+    parsed = parse(path)
+    return { ok: false, errors: parsed[:errors] } if parsed[:graph].nil?
+
+    cyc = GraphEdges.cycle(parsed[:graph][:edges])
+    return { ok: false, errors: ["cyclic graph, refusing to write: #{cyc.join(' > ')}"] } if cyc
+
+    nil
+  end
+
+  # --- verify: none directive --------------------------------------------------
+
+  def extract_verify_directive(graph_section)
+    return [nil, [], graph_section] if graph_section.nil?
+
+    reason = nil
+    present = false
+    errors = []
+    remaining_lines = []
+
+    graph_section.each_line do |line|
+      stripped = line.strip
+      m = stripped.match(DIRECTIVE_RE)
+      if m
+        present = true
+        captured = m[1].to_s.strip
+        if captured.empty?
+          errors << "verify: none requires reason=<text>: #{stripped.inspect}"
+        else
+          reason = captured
+        end
+      else
+        remaining_lines << line
+      end
+    end
+
+    directive = present ? { reason: reason } : nil
+    [directive, errors, remaining_lines.join]
+  end
+
+  # D18: drop every fenced line from `text`, so a fenced example edge inside a
+  # hand-written graph.md or roadmap ## Graph section is never handed to
+  # GraphEdges as real edge text. Non-fenced lines pass through unchanged.
+  def strip_fenced_blocks(text)
+    lines = []
+    each_fence_line(text) { |line, fenced| lines << line unless fenced }
+    lines.join
+  end
+
+  # --- fence-aware section location ---------------------------------------------
+
+  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
+
+  # [start_of_heading_line, start_of_next_top_level_heading_or_EOF] byte
+  # offsets for the FIRST line, outside any fence, whose stripped text
+  # exactly equals heading_text. nil when no such line exists.
+  def section_bounds(content, heading_text)
+    offset = 0
+    heading_start = nil
+
+    each_fence_line(content) do |line, fenced|
+      if !fenced && heading_start.nil? && line.strip == heading_text
+        heading_start = offset
+      elsif !fenced && heading_start && offset > heading_start && line.match?(/\A##[^#]/)
+        return [heading_start, offset]
+      end
+      offset += line.length
+    end
+
+    heading_start ? [heading_start, offset] : nil
+  end
+
+  def section_body(content, heading_text)
+    bounds = section_bounds(content, heading_text)
+    return nil unless bounds
+
+    start_idx, end_idx = bounds
+    content[(line_end(content, start_idx))...end_idx].to_s
+  end
+
+  def line_end(content, start_idx)
+    idx = content.index("\n", start_idx)
+    idx ? idx + 1 : content.length
+  end
+
+  def replace_or_append_section(content, heading_text, body_text)
+    rendered_body = body_text.to_s
+    rendered_body += "\n" unless rendered_body.end_with?("\n")
+    section = "#{heading_text}\n#{rendered_body}"
+
+    bounds = section_bounds(content, heading_text)
+    if bounds
+      start_idx, end_idx = bounds
+      tail = content[end_idx..].to_s
+      section += "\n" unless tail.empty?
+      content[0...start_idx] + section + tail
+    else
+      head = content.dup
+      head += "\n" unless head.end_with?("\n")
+      head += "\n" unless head.end_with?("\n\n")
+      head + section
+    end
+  end
+
+  # --- table rendering and reading -----------------------------------------------
+
+  def render_status_table(rows)
+    lines = ["| Node | State | Detail |", "| --- | --- | --- |"]
+    rows.each { |r| lines << "| #{r[:node]} | #{r[:state]} | #{r[:detail]} |" }
+    "#{lines.join("\n")}\n"
+  end
+
+  def rows_from_table(text)
+    return [] if text.nil?
+
+    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 do |l|
+      cells = l.split("|", -1).map(&:strip)[1..-2].to_a
+      { node: cells[0], state: cells[1], detail: cells[2] }
+    end
+  end
+end

package/scripts/lib/graph_tree.rb

@@ -0,0 +1,98 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_edges"
+require_relative "ready_set"
+
+# GraphTree (intent 337, n2, folds 327a): draws any edge map ({id => [needs...]})
+# as an indented tree with box-drawing branches. A node may have any number
+# of children; a node several branches need (fan-out) is drawn once, at the
+# point where those branches join. A node that itself needs several things
+# (fan-in) can only occupy one position in the tree: it hangs under its
+# highest-batch need, ties broken by smallest id, with its other needs shown
+# as converging references at the join (row 2.14, folded at the 2026-09-10
+# plan review). Pure, plain text, no roadmap knowledge, so the same
+# renderer serves the roadmap file, the roadmap screens, and later the node
+# scope. Batch numbers (for placement) and the topological sort come from
+# ReadySet - the ONE sort (327 D1) - never a second local one here.
+module GraphTree
+  module_function
+
+  def render(edges:, labels:, marks:, width:)
+    edges = edges || {}
+    nodes = ReadySet.all_nodes(edges)
+
+    cyc = GraphEdges.cycle(edges)
+    if cyc
+      return { ok: false, text: nil, error: "cyclic graph, cannot render a tree: #{cyc.join(' > ')}", cycle: cyc }
+    end
+
+    if nodes.empty?
+      return { ok: true, text: "(no dependencies)\n", error: nil, cycle: nil }
+    end
+
+    batch_result = ReadySet.batches(edges)
+    batch_of = {}
+    batch_result[:batches].each_with_index { |layer, i| layer.each { |id| batch_of[id] = i + 1 } }
+
+    primary_parent = {}
+    converging = {}
+    nodes.each do |id|
+      needs = (edges[id] || []).uniq
+      next if needs.empty?
+
+      primary = needs.min_by { |n| [-(batch_of[n] || 0), n] }
+      primary_parent[id] = primary
+      others = needs - [primary]
+      converging[id] = others.sort unless others.empty?
+    end
+
+    children_of = Hash.new { |h, k| h[k] = [] }
+    primary_parent.each { |child, parent| children_of[parent] << child }
+    children_of.each_value { |list| list.sort! { |a, b| [batch_of[a] || 0, a] <=> [batch_of[b] || 0, b] } }
+
+    roots = nodes.select { |id| (edges[id] || []).empty? }.sort
+
+    labels ||= {}
+    marks ||= {}
+    critical = (marks[:critical_path] || []).to_a
+    ready = (marks[:ready] || []).to_a
+
+    lines = []
+    roots.each { |id| append_node(id, "", "", lines, children_of, labels, critical, ready, converging, width) }
+
+    { ok: true, text: "#{lines.join("\n")}\n", error: nil, cycle: nil }
+  end
+
+  # `ancestor_prefix` is the continuation string every ancestor above this
+  # node contributes ("│   " when that ancestor still has a later sibling
+  # to draw, "    " when it was the last child); `connector` is this node's
+  # own branch glyph off its parent ("├── " / "└── "), empty for a root.
+  def append_node(id, ancestor_prefix, connector, lines, children_of, labels, critical, ready, converging, width)
+    lines << render_line(ancestor_prefix + connector, id, labels, critical, ready, converging, width)
+
+    continuation = connector == "└── " ? "    " : (connector.empty? ? "" : "│   ")
+    child_ancestor_prefix = ancestor_prefix + continuation
+
+    children = children_of[id] || []
+    children.each_with_index do |child_id, i|
+      last = i == children.length - 1
+      child_connector = last ? "└── " : "├── "
+      append_node(child_id, child_ancestor_prefix, child_connector, lines, children_of, labels, critical, ready, converging, width)
+    end
+  end
+
+  def render_line(connector, id, labels, critical, ready, converging, width)
+    label = labels.fetch(id, id).to_s
+    text = critical.include?(id) ? "* #{label}" : label
+    text += " (also needs #{converging[id].join(', ')})" if converging[id]
+    text += " (ready)" if ready.include?(id)
+
+    available = width - connector.length
+    if available.positive? && text.length > available
+      text = available > 3 ? "#{text[0, available - 3]}..." : text[0, available]
+    end
+
+    "#{connector}#{text}"
+  end
+end

package/scripts/lib/guarded_append.rb

@@ -0,0 +1,155 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# GuardedAppend - the shared fail-closed write guard behind NodeLedger's transition
+# lines and RoadmapSavepoint's roadmap ledger (intent 335, spec "Approach").
+#
+# One module function, #call: opens `path` RDWR|APPEND|CREAT, takes a non-blocking
+# exclusive lock with a bounded number of retries, and under that ONE hold reads the
+# current content, yields it to the caller's block, and appends whatever the block
+# returns. A block returning nil is a refusal: nothing is written. Read, decide, and
+# append happen inside one lock hold on purpose (spec "Approach"): that is what makes
+# "is this subject already running" and "append running" atomic against a second
+# writer, which a check followed by a separate append could never be.
+#
+# Pure and dependency-injected: `flock:` and `sleeper:` are constructor-style test
+# seams (never an environment variable, never a global); this module reads no
+# environment variable and shells out to nothing.
+module GuardedAppend
+  # Raised when the lock could not be taken within `retries` attempts (real
+  # contention), or when flock itself is unsupported on this filesystem and
+  # `strict: true` (spec D12a). Nothing is written either way; the caller is told
+  # plainly that nothing landed and must retry.
+  class Unavailable < StandardError; end
+
+  module_function
+
+  # Five attempts, 20 ms apart: about 100 ms of wall time total (spec D12).
+  DEFAULT_RETRIES = 5
+  DEFAULT_BACKOFF = 0.02
+
+  # Default lock and sleep seams: a real flock call, a real sleep. Tests inject
+  # replacements to simulate contention, recovery, and a flock-less filesystem
+  # hermetically, with no need for a real flock-less mount or a slow test run.
+  DEFAULT_FLOCK = ->(handle, mode) { handle.flock(mode) }
+  private_constant :DEFAULT_FLOCK
+
+  DEFAULT_SLEEPER = ->(seconds) { sleep(seconds) }
+  private_constant :DEFAULT_SLEEPER
+
+  # Open `path` (creating it if absent, never truncating it), take an exclusive
+  # non-blocking lock with up to `retries` attempts (`backoff` seconds apart), and
+  # under that one hold read the file's current content, yield it to the block, and
+  # append what the block returns.
+  #
+  # Returns :written when a line was appended, :refused when the block returned nil
+  # (nothing written, spec: a refusal). Raises Unavailable, writing nothing, when the
+  # lock could not be taken within `retries` attempts.
+  #
+  # `strict:` decides what happens when flock itself raises a SystemCallError OTHER
+  # than contention (EWOULDBLOCK/EAGAIN) - a filesystem without flock support,
+  # distinct from real contention (spec D12a): strict (the default) raises
+  # Unavailable; non-strict proceeds unguarded, since a single O_APPEND write still
+  # lands whole there. The SystemCallError rescue wraps the flock call only (spec
+  # D12b); an Errno::ENOENT from File.open (a missing parent directory) propagates
+  # as itself, never read as Unavailable.
+  def call(path, retries: DEFAULT_RETRIES, backoff: DEFAULT_BACKOFF, strict: true,
+           flock: DEFAULT_FLOCK, sleeper: DEFAULT_SLEEPER, &block)
+    created = !File.exist?(path)
+    handle = File.open(path, File::RDWR | File::APPEND | File::CREAT, 0o644)
+    begin
+      status = take_lock(handle, retries: retries, backoff: backoff, flock: flock, sleeper: sleeper)
+
+      case status
+      when :contended
+        raise Unavailable, "could not take an exclusive lock on #{path} after #{retries} attempts"
+      when :unsupported
+        if strict
+          raise Unavailable, "flock is unsupported on #{path} and strict: true refuses to proceed unguarded"
+        end
+
+        write_line(handle, &block)
+      when :locked
+        begin
+          write_line(handle, &block)
+        ensure
+          unlock(handle, flock: flock)
+        end
+      end
+    ensure
+      handle.close
+    end
+  rescue Unavailable
+    remove_freshly_created_empty_file(path) if created
+    raise
+  end
+
+  # Attempt the lock up to `retries` times. Returns :locked, :unsupported (a
+  # non-contention SystemCallError from flock, decided once, never retried), or
+  # :contended (every attempt failed with EWOULDBLOCK/EAGAIN or a false return).
+  # Sleeps `backoff` seconds after EVERY contended attempt, including the last, so
+  # the total backoff budget is exactly `retries` sleeps (spec D12: "about 100 ms of
+  # wall time in total" = 5 attempts * 20 ms, not 4).
+  def take_lock(handle, retries:, backoff:, flock:, sleeper:)
+    status = :contended
+    retries.times do
+      status = try_flock(handle, flock)
+      return status unless status == :contended
+
+      sleeper.call(backoff)
+    end
+    status
+  end
+  private_class_method :take_lock
+
+  # One attempt at the non-blocking exclusive lock. File#flock RAISES (does not
+  # return false) for every errno except EWOULDBLOCK/EAGAIN on most platforms, so
+  # both the "returns false" and the "raises EWOULDBLOCK" shapes read as contention;
+  # any other SystemCallError means flock is not supported on this filesystem.
+  def try_flock(handle, flock)
+    result = flock.call(handle, File::LOCK_EX | File::LOCK_NB)
+    result == false ? :contended : :locked
+  rescue Errno::EWOULDBLOCK, Errno::EAGAIN
+    :contended
+  rescue SystemCallError
+    :unsupported
+  end
+  private_class_method :try_flock
+
+  # Read the current content, yield it to the block, and write what it returns. A
+  # block returning nil writes nothing and reports :refused. Before a real write, if
+  # the content is non-empty and does not end in a newline, a newline is written
+  # first (spec D9a): a crash that truncated the previous write must not glue the
+  # next transition onto its tail. The handle is opened O_APPEND, so every write
+  # lands at the current end of file regardless of the read's cursor position.
+  def write_line(handle, &block)
+    content = handle.read
+    line = block.call(content)
+    return :refused if line.nil?
+
+    prefix = !content.empty? && !content.end_with?("\n") ? "\n" : ""
+    handle.write("#{prefix}#{line}")
+    handle.flush
+    :written
+  end
+  private_class_method :write_line
+
+  def unlock(handle, flock:)
+    flock.call(handle, File::LOCK_UN)
+  rescue SystemCallError
+    nil
+  end
+  private_class_method :unlock
+
+  # Row 7.9 (post-execution review): a give-up (Unavailable) must not leave a zero-byte
+  # file behind that File::CREAT created for a target that did not exist before this
+  # call. Only ever removes a file this same call created (never a pre-existing file,
+  # spec matrix 1.11) and only when it is still empty (no write ever reached it on the
+  # give-up paths this rescues).
+  def remove_freshly_created_empty_file(path)
+    File.unlink(path) if File.exist?(path) && File.zero?(path)
+  rescue SystemCallError
+    nil
+  end
+  private_class_method :remove_freshly_created_empty_file
+end

package/scripts/lib/hook_registry.rb

@@ -34,6 +34,17 @@ module HookRegistry
           { "name" => "check-update", "status" => "" },
         ] },
       ],
+      # Intent 355, n2: the call budget guard. Not one of the edit-path
+      # gates intent 302 removed (those denied a write on content; this
+      # denies a call on a per-attempt COUNT, read from the session's own
+      # transcript, never from the tool's arguments) - see scripts/hook-
+      # call-budget. Claude only: CODEX_LIVE_STATE_EVENTS below does not
+      # carry PreToolUse, so codex_hooks_json never projects it.
+      "PreToolUse" => [
+        { "matcher" => "", "hooks" => [
+          { "name" => "call-budget", "status" => "" },
+        ] },
+      ],
       "PreCompact" => [
         { "matcher" => "", "hooks" => [
           { "name" => "savepoint", "status" => "Saving Plastic intent state..." },
@@ -54,6 +65,20 @@ module HookRegistry
           { "name" => "capture", "status" => "Capturing prompt into the session ledger..." },
         ] },
       ],
+      # This entry belongs to the Claude adapter half of Plastic's
+      # harness-agnostic-core / Claude-adapter split (intent 316a1, D3
+      # supersedes 316a's D6): MessageDisplay is not one of
+      # CODEX_LIVE_STATE_EVENTS, so codex_hooks_json (below) never picks it
+      # up; codex_hook_names stays exactly what it was (pinned by
+      # test/hook_registry_test.rb:82 and :110-111). Fires on every streamed
+      # chunk of every assistant message (D11); the launcher (hooks/message-
+      # display) decides with shell builtins and forks nothing on the common
+      # case, execing Ruby only for a candidate message.
+      "MessageDisplay" => [
+        { "matcher" => "", "hooks" => [
+          { "name" => "message-display", "status" => "" },
+        ] },
+      ],
     }
   end
 
@@ -61,8 +86,9 @@ module HookRegistry
   # the PostToolUse record hook collapses from Claude's multi-tool matcher onto
   # Codex's single apply_patch tool (181 F4: apply_patch is Codex's sole
   # file-mutation tool; tool_name always reports apply_patch), and the live-state
-  # events project through whole. Since intent 302 there is no PreToolUse group at
-  # all: the edit-path gates are gone on both harnesses. Command invokes the
+  # events project through whole. PreToolUse (intent 355, n2's call-budget guard,
+  # Claude only) is not one of CODEX_LIVE_STATE_EVENTS below, so Codex still
+  # carries no PreToolUse group of its own. Command invokes the
   # codex-hook dispatcher with the hook name. Guide-settled shape [guide Part 3]:
   # top-level {"hooks":{<Event>: [{"matcher","hooks":[{"type":"command","command",
   # "statusMessage"}]}]}}, identical to Claude's shape, string command. Single