@zalom/plastic 2.0.0-alpha.18 → 2.0.0-alpha.19

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/installer_core.rb

@@ -373,6 +373,9 @@ class InstallerCore
       "scripts/lib/release_guard.rb" => "scripts/lib/release_guard.rb",
       "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
       "scripts/lib/savepoint.rb" => "scripts/lib/savepoint.rb",
+      "scripts/lib/guarded_append.rb" => "scripts/lib/guarded_append.rb",
+      "scripts/lib/node_ledger.rb" => "scripts/lib/node_ledger.rb",
+      "scripts/node-transition" => "scripts/node-transition",
       "scripts/lib/arm.rb" => "scripts/lib/arm.rb",
       "scripts/lib/lock.rb" => "scripts/lib/lock.rb",
       "scripts/plastic-lock" => "scripts/plastic-lock",
@@ -475,6 +478,35 @@ class InstallerCore
       # and need no entry here.
       "scripts/lib/dashboard_screen.rb" => "scripts/lib/dashboard_screen.rb",
       "scripts/hook-message-display" => "scripts/hook-message-display",
+      # Intent 334 (G1): the node file and graph.md library, plus its
+      # validator and CLI (327 D40/D41).
+      "scripts/lib/graph_edges.rb" => "scripts/lib/graph_edges.rb",
+      "scripts/lib/node_file.rb" => "scripts/lib/node_file.rb",
+      "scripts/lib/atomic_write.rb" => "scripts/lib/atomic_write.rb",
+      "scripts/lib/graph_file.rb" => "scripts/lib/graph_file.rb",
+      "scripts/lib/work_graph_validator.rb" => "scripts/lib/work_graph_validator.rb",
+      "scripts/validate-work-graph" => "scripts/validate-work-graph",
+      # Intent 335a: every id an intent has ever seen, so a deleted node's id
+      # is never reissued to a new node with the dead one's ledger history.
+      "scripts/lib/node_ids.rb" => "scripts/lib/node_ids.rb",
+      # Intent 339 (G6): the generated outcome.md library and its CLI.
+      "scripts/lib/outcome_report.rb" => "scripts/lib/outcome_report.rb",
+      "scripts/outcome-report" => "scripts/outcome-report",
+      # Intent 336 (G3): ReadySet, the one function that says what may run
+      # next, and its CLI. node-transition requires the lib as of n5;
+      # registered here (rather than waiting for n8's own CLI/doc unit) so
+      # test/install_sync_test.rb stays green across every intermediate unit.
+      "scripts/lib/ready_set.rb" => "scripts/lib/ready_set.rb",
+      "scripts/ready-set" => "scripts/ready-set",
+      # Intent 338 (G5): the node packet command - the trust-boundary wrapper,
+      # the five-block gatherer/assembler, and the CLI 340's runner calls.
+      "scripts/lib/packet_wrapper.rb" => "scripts/lib/packet_wrapper.rb",
+      "scripts/lib/node_packet.rb" => "scripts/lib/node_packet.rb",
+      "scripts/node-packet" => "scripts/node-packet",
+      # Intent 342 (G9): the backward shim that presents actions/*.md as a
+      # node graph for any legacy intent, so WorkGraphValidator can require
+      # it without going red on contact with install_sync_test.
+      "scripts/lib/action_graph_shim.rb" => "scripts/lib/action_graph_shim.rb",
     }
   end
 

package/scripts/lib/node_file.rb

@@ -0,0 +1,214 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+
+# NodeFile (intent 334, n3): one node file's YAML envelope (`node`, `kind`,
+# `files`, `budget`) over a Markdown body, plus the deterministic id minter
+# (327 D1r, D5r, D9r-D12r, D16r). The kind-prefix rule lives here, not in
+# GraphEdges, which stays loose about id grammar so a numeric roadmap id
+# parses the same way (D12r).
+#
+# Pure and side-effect-free: parse reads one file and returns a Result hash,
+# never raising across the boundary; mint_id takes the ids already present
+# and returns one past the highest of them. Reserving an id against a
+# concurrent minter is G7's problem, not a claim this module makes (D16r);
+# gathering the ids an intent has ever seen is NodeIds' job (335a), which is
+# why this module still requires nothing but yaml and date.
+module NodeFile
+  module_function
+
+  KIND_PREFIX = { "work" => "n", "verify" => "v", "decision" => "d", "research" => "r" }.freeze
+  VALID_KINDS = KIND_PREFIX.keys.freeze
+  FENCE_LINE_RE = /\A\s{0,3}(`{3,}|~{3,})/.freeze
+
+  # {ok:, node:, kind:, files:, budget:, body:, errors:}. `body` is the raw
+  # text after the frontmatter block, present even when `ok` is false and the
+  # body itself parsed fine, so a caller can still inspect sections on an
+  # envelope-invalid file. Every failure mode returns errors rather than
+  # raising: a missing file, absent or non-mapping frontmatter, or YAML that
+  # will not parse.
+  def parse(path)
+    return failure(["node file not found: #{path}"]) unless File.exist?(path)
+
+    content = File.read(path)
+    return failure(["missing YAML frontmatter"]) unless content.start_with?("---")
+
+    parts = content.split("---", 3)
+    return failure(["missing YAML frontmatter"]) if parts.length < 3
+
+    fm = begin
+      YAML.safe_load(parts[1], permitted_classes: [Date, Time])
+    rescue StandardError => e
+      return failure(["frontmatter is not valid YAML: #{e.message}"])
+    end
+    fm = {} if fm.nil?
+    return failure(["frontmatter must be a mapping, got #{fm.class}"]) unless fm.is_a?(Hash)
+
+    body = parts[2].to_s
+    errors = []
+
+    kind = fm["kind"].to_s
+    unless VALID_KINDS.include?(kind)
+      errors << "unknown kind: #{fm["kind"].inspect} (must be one of #{VALID_KINDS.join(', ')})"
+    end
+
+    id = fm["node"].to_s
+    errors << "missing node id (node:)" if id.empty?
+
+    if !id.empty?
+      basename = File.basename(path, ".md")
+      unless filename_matches_id?(basename, id)
+        errors << "node id #{id.inspect} does not match filename #{File.basename(path).inspect}"
+      end
+    end
+
+    if !id.empty? && VALID_KINDS.include?(kind)
+      expected_prefix = KIND_PREFIX[kind]
+      unless id.match?(/\A#{Regexp.escape(expected_prefix)}[1-9][0-9]*\z/)
+        errors << "node id #{id.inspect} does not match kind #{kind.inspect}'s prefix #{expected_prefix.inspect}"
+      end
+    end
+
+    errors << "depends_on: is not a valid envelope field (removed by 327 D41; edges belong in ## Graph)" if fm.key?("depends_on")
+    errors << "turns: is not a valid envelope field (removed by 327 D47)" if fm.key?("turns")
+
+    files = fm["files"]
+    if files.nil?
+      errors << "missing files:"
+    elsif !files.is_a?(Array)
+      errors << "files: must be a list, got #{files.class}"
+    end
+
+    budget, budget_errors = normalize_budget(fm["budget"])
+    errors.concat(budget_errors)
+
+    {
+      ok: errors.empty?,
+      node: id.empty? ? nil : id,
+      kind: kind.empty? ? nil : kind,
+      files: files.is_a?(Array) ? files : nil,
+      budget: budget,
+      body: body,
+      errors: errors,
+    }
+  end
+
+  def failure(errors)
+    { ok: false, node: nil, kind: nil, files: nil, budget: nil, body: nil, errors: errors }
+  end
+
+  # <id>.md or <id>--<slug>.md, exactly - a longer id's file (n11--x.md) must
+  # never satisfy a shorter id (n1), so the id is matched as the whole prefix
+  # up to end-of-string or the literal "--" separator, never as a substring
+  # (fold A9).
+  def filename_matches_id?(basename, id)
+    basename.match?(/\A#{Regexp.escape(id)}(--[A-Za-z0-9][A-Za-z0-9-]*)?\z/)
+  end
+
+  # budget: normalizes to a plain integer token ceiling. A bare integer and
+  # {tokens: N} both normalize to N; {turns: N} is the field 327 D47 removed
+  # and is a named error, never silently accepted (fold: report's example).
+  def normalize_budget(raw)
+    return [nil, []] if raw.nil?
+    return [raw, []] if raw.is_a?(Integer)
+
+    if raw.is_a?(Hash)
+      return [nil, ["budget: {turns:} was removed by 327 D47; use budget: <int> or {tokens: <int>}"]] if raw.key?("turns") || raw.key?(:turns)
+
+      tokens = raw["tokens"] || raw[:tokens]
+      return [tokens, []] if tokens.is_a?(Integer)
+
+      return [nil, ["budget: must normalize to an integer token count, got #{raw.inspect}"]]
+    end
+
+    [nil, ["budget: must be an integer or {tokens: <int>}, got #{raw.class}"]]
+  end
+
+  # Every [heading_line, body] pair in the body text, split on any heading
+  # line, fence-aware: a "#" line inside a fenced block never starts a new
+  # section (fold: "a node passes on a section it does not have").
+  def split_by_headings(text)
+    sections = []
+    heading = nil
+    body = +""
+    each_fence_line(text) do |line, fenced|
+      if !fenced && line.start_with?("#")
+        sections << [heading, body] if heading
+        heading = line.strip
+        body = +""
+      else
+        body << line
+      end
+    end
+    sections << [heading, body] if heading
+    sections
+  end
+
+  # Markdown table data rows (header + separator stripped) in text, fence-aware.
+  def table_rows(text)
+    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 { |l| l.split("|", -1).map(&:strip)[1..-2].to_a }
+  end
+
+  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
+
+  # One past the highest id ever seen for the kind: purely numeric, so ids
+  # never sort as strings ("n10" ranking above "n9"), and a gap in the
+  # sequence STAYS a gap.
+  #
+  # Node ids never recycle (335a, owner ruling 2026-09-09). Intent 335 keyed
+  # the work ledger in savepoint.md on node id, and deletion is not a
+  # transition, so nothing in the ledger says a node is gone. Reissuing a
+  # deleted node's id therefore hands the new node the dead one's whole
+  # history: its `done` line, its evidence, its holder, and the successors
+  # that line released. The failure is silent, which is the worst shape it
+  # could take, so the gap is a headstone rather than free space.
+  #
+  # `taken` may carry ids this kind's grammar rejects, because NodeIds
+  # over-reserves on purpose (335a D11); they are ignored without shifting
+  # the sequence.
+  def mint_id(kind, taken)
+    prefix = KIND_PREFIX[kind.to_s]
+    return nil unless prefix
+
+    used = taken.to_a.filter_map do |id|
+      m = id.to_s.match(/\A#{Regexp.escape(prefix)}([1-9][0-9]*)\z/)
+      m && m[1].to_i
+    end
+
+    "#{prefix}#{(used.max || 0) + 1}"
+  end
+end

package/scripts/lib/node_ids.rb

@@ -0,0 +1,99 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "node_file"
+require_relative "graph_file"
+require_relative "graph_edges"
+require_relative "node_ledger"
+# Savepoint::INTENT_SUBJECT is named directly below, so the require is direct
+# too: test/savepoint_split_test.rb:157 refuses a transitive one.
+require_relative "savepoint"
+
+# NodeIds (intent 335a): every node id one intent has EVER seen, gathered from
+# the three places an id can appear, so NodeFile.mint_id can mint one past the
+# highest and never reissue a deleted node's id.
+#
+# Why this exists as its own module rather than inside NodeFile: NodeFile is
+# 334's deliberately dependency-free envelope reader (yaml and date only), and
+# gathering needs the graph parsers and the ledger. It is not inside
+# WorkGraphValidator either, because that module reports errors and minting is
+# not validation.
+#
+# The rule this serves (335a D1, owner ruling 2026-09-09): a removed node still
+# reserves its id. Deletion is not a ledger transition, so a reissued id would
+# silently inherit the dead node's transition history, evidence included.
+module NodeIds
+  module_function
+
+  # Every id seen in `intent_dir`, sorted and deduplicated. Each of the three
+  # sources is guarded on its own (D5): an intent that has not started yet is
+  # the ordinary case, not an error.
+  #
+  # The result deliberately OVER-reserves (D11). An id that no kind's grammar
+  # matches costs nothing, because mint_id filters by prefix; a missed id costs
+  # a false history.
+  def taken(intent_dir)
+    return [] unless intent_dir && File.directory?(intent_dir)
+
+    (from_node_files(intent_dir) + from_graph(intent_dir) + from_ledger(intent_dir))
+      .reject { |id| id.nil? || id.empty? }
+      .uniq
+      .sort
+  end
+
+  # Both the filename's id AND the envelope's `node:` (D7). A file can disagree
+  # with its own name, and a file whose frontmatter will not parse yields no
+  # envelope id at all, which is exactly when the filename is the only thing
+  # standing between a corrupt node file and a reissued id.
+  #
+  # Plain glob (D8): a zero-byte or sentinel-marked node file still names a node
+  # whose id is taken. Savepoint.has_real_files_in?'s filter answers a different
+  # question (has this intent started) and is not reused here.
+  def from_node_files(intent_dir)
+    Dir.glob(File.join(intent_dir, "nodes", "*.md")).sort.flat_map do |path|
+      [id_from_filename(path), NodeFile.parse(path)[:node]]
+    end
+  end
+
+  # The id a node filename declares: the basename up to the "--" separator, so
+  # both shapes 334 D11r ratifies reserve - the bare `n2.md` and the slugged
+  # `n1--graph-edges.md` (D6). Taking the whole basename would reserve nothing
+  # for every slugged file in the store, which is the dominant shape.
+  def id_from_filename(path)
+    File.basename(path, ".md").split("--", 2).first.to_s
+  end
+
+  # Declared plus targeted, from the `## Graph` section only (D9). The gatherer
+  # inherits GraphEdges' looseness: it is not fence-aware, so an id inside a
+  # fenced example is gathered. That over-reserves, which is the safe direction.
+  #
+  # `## Status` is NOT read (D10): it is a projection rendered from the ledger
+  # and rewritten wholesale, so every id it can carry the ledger already carries.
+  def from_graph(intent_dir)
+    path = File.join(intent_dir, "graph.md")
+    return [] unless File.exist?(path)
+
+    section = GraphFile.section_body(File.read(path).scrub, "## Graph")
+    return [] unless section
+
+    GraphEdges.parse(section)[:nodes].to_a
+  end
+
+  # Subjects only, read through NodeLedger.entries, NEVER a token scan (D4).
+  # A node id can sit inside an ordinary milestone's free text and does today:
+  # intent 335's own ledger carries "ACTION_1 v2" inside a Review line, and 23
+  # such tokens exist across the live store. NodeLedger.entries already owns the
+  # two-space split and already keeps a torn line's subject, so this reuses that
+  # seam rather than making a third copy of it.
+  #
+  # The literal `Intent` subject is dropped: it is an intent-scope line, not a
+  # node, and no kind's grammar would match it anyway.
+  def from_ledger(intent_dir)
+    path = File.join(intent_dir, "savepoint.md")
+    return [] unless File.exist?(path)
+
+    NodeLedger.entries(path)
+              .map { |entry| entry[:subject] }
+              .reject { |subject| subject == Savepoint::INTENT_SUBJECT }
+  end
+end