@zalom/plastic 2.0.0-alpha.8 → 2.0.1

package/scripts/lib/meter_watch.rb

@@ -0,0 +1,185 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "time"
+require "fileutils"
+require "rbconfig"
+require_relative "atomic_write"
+
+# MeterWatch (intent 355, n5, D6): reads the owner's rate-limit cache on a
+# timer and writes one state file a session watches, instead of every session
+# parsing the cache and re-deriving the thresholds for itself. No model call
+# is spent on a tick that leaves the state unchanged.
+#
+# Everything is injected: home (holds config.yml and .cache/), the clock, the
+# cache path, and the renamer AtomicWrite uses. Nothing reads ENV, nothing
+# calls launchctl, and --install-timer (scripts/meter-watch) only ever writes
+# under the injected home.
+class MeterWatch
+  DEFAULT_REDUCE_AT = 55
+  DEFAULT_STOP_AT = 85
+  DEFAULT_WEEKLY_STOP_AT = 97
+  TICK_SECONDS = 20 * 60
+  STALE_AFTER_SECONDS = TICK_SECONDS * 2
+
+  def initialize(home:, cache_path: nil, config_path: nil, now: Time.now, renamer: File.method(:rename))
+    @home = home
+    @cache_path = cache_path || File.join(home, ".cache", "rate-limits.json")
+    @config_path = config_path || File.join(home, "config.yml")
+    @state_path = File.join(home, ".cache", "meter-state.json")
+    @now = now
+    @renamer = renamer
+    @reduce_at, @stop_at, @weekly_stop_at = load_thresholds
+  end
+
+  attr_reader :state_path
+
+  def tick
+    previous = read_state
+    state = compute_state(previous)
+    write_if_changed(previous, state)
+  end
+
+  private
+
+  def compute_state(previous)
+    return base_state("unavailable") unless File.file?(@cache_path)
+    return stopped?(previous) ? previous : base_state("stale") if stale?
+
+    cache = JSON.parse(File.read(@cache_path))
+    five_hour = cache["five_hour"]
+    seven_day = cache["seven_day"]
+    resets_at = cache["resets_at"]
+
+    # Resume compares `now` against the STOP's OWN resets_at (carried
+    # forward on `previous`, from the tick that first wrote "stop"), never
+    # the cache's current resets_at: the cache moves resets_at on to the
+    # NEXT window before five_hour/seven_day themselves drop, so comparing
+    # against the live value would never report resume (B4).
+    label = if stopped?(previous) && reset_passed?(previous["resets_at"])
+              "resume"
+            else
+              classify(five_hour, seven_day)
+            end
+
+    base_state(label, five_hour: five_hour, seven_day: seven_day, resets_at: resets_at)
+  rescue JSON::ParserError
+    base_state("unavailable")
+  end
+
+  def stopped?(previous)
+    previous && previous["state"] == "stop"
+  end
+
+  def classify(five_hour, seven_day)
+    return "stop" if five_hour.to_f >= @stop_at
+    return "stop" if seven_day.to_f >= @weekly_stop_at
+    return "reduce" if five_hour.to_f >= @reduce_at
+
+    "ok"
+  end
+
+  def stale?
+    File.mtime(@cache_path) < (@now - STALE_AFTER_SECONDS)
+  rescue Errno::ENOENT
+    true
+  end
+
+  def reset_passed?(resets_at)
+    at = parse_time(resets_at)
+    at && @now >= at
+  end
+
+  def parse_time(value)
+    return nil if value.nil? || value.to_s.empty?
+
+    text = value.to_s
+    text.match?(/\A\d+\z/) ? Time.at(text.to_i).utc : Time.iso8601(text)
+  rescue ArgumentError, TypeError
+    nil
+  end
+
+  def base_state(label, five_hour: nil, seven_day: nil, resets_at: nil)
+    {
+      "state" => label,
+      "five_hour" => five_hour,
+      "seven_day" => seven_day,
+      "resets_at" => resets_at,
+      "checked_at" => @now.getutc.iso8601,
+    }
+  end
+
+  def write_if_changed(previous, state)
+    return state if previous && previous["state"] == state["state"]
+
+    FileUtils.mkdir_p(File.dirname(@state_path))
+    AtomicWrite.write(@state_path, JSON.generate(state), renamer: @renamer)
+    state
+  end
+
+  def read_state
+    return nil unless File.file?(@state_path)
+
+    JSON.parse(File.read(@state_path))
+  rescue JSON::ParserError
+    nil
+  end
+
+  def load_thresholds
+    config = File.file?(@config_path) ? (YAML.safe_load(File.read(@config_path)) || {}) : {}
+    meter = config["meter"].is_a?(Hash) ? config["meter"] : {}
+    [
+      meter.fetch("reduce_at", DEFAULT_REDUCE_AT),
+      meter.fetch("stop_at", DEFAULT_STOP_AT),
+      meter.fetch("weekly_stop_at", DEFAULT_WEEKLY_STOP_AT),
+    ]
+  end
+
+  class << self
+    # Writes the LaunchAgent plist under an injectable home; never loads it
+    # with launchctl (scripts/meter-watch --install-timer calls this and
+    # nothing else). RunAtLoad primes the first tick; StartInterval repeats
+    # it every 20 minutes.
+    #
+    # `label:` and `arguments:` (intent 340a, G7b, n3, graph.md D9) let the
+    # delivery watch's own `runner watch --install-timer` reuse this one
+    # writer for its `com.plastic.delivery-watch.<id>` job instead of
+    # rendering plist XML a second time; their defaults reproduce today's
+    # meter-watch plist byte for byte (row 3.1).
+    def install_timer(home:, script_path:, ruby: RbConfig.ruby, interval: TICK_SECONDS,
+                       label: "com.plastic.meter-watch", arguments: nil)
+      agents_dir = File.join(home, "Library", "LaunchAgents")
+      FileUtils.mkdir_p(agents_dir)
+      plist_path = File.join(agents_dir, "#{label}.plist")
+      args = arguments || [ruby, script_path, "--home", home]
+      File.write(plist_path, plist(label, args, interval))
+      plist_path
+    end
+
+    private
+
+    def plist(label, arguments, interval)
+      args_xml = arguments.map { |a| "    <string>#{a}</string>" }.join("\n")
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+        <plist version="1.0">
+        <dict>
+          <key>Label</key>
+          <string>#{label}</string>
+          <key>ProgramArguments</key>
+          <array>
+        #{args_xml}
+          </array>
+          <key>StartInterval</key>
+          <integer>#{interval}</integer>
+          <key>RunAtLoad</key>
+          <true/>
+        </dict>
+        </plist>
+      XML
+    end
+  end
+end

package/scripts/lib/node_file.rb

@@ -0,0 +1,234 @@
+# 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`, and the optional research `report`) 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)
+    report, report_errors = normalize_report(fm["report"], kind)
+    errors.concat(report_errors)
+
+    {
+      ok: errors.empty?,
+      node: id.empty? ? nil : id,
+      kind: kind.empty? ? nil : kind,
+      files: files.is_a?(Array) ? files : nil,
+      budget: budget,
+      report: report,
+      body: body,
+      errors: errors,
+    }
+  end
+
+  def failure(errors)
+    { ok: false, node: nil, kind: nil, files: nil, budget: nil, report: nil, body: nil, errors: errors }
+  end
+
+  def normalize_report(raw, kind)
+    return [nil, []] if raw.nil?
+    return [nil, ["report: is allowed only on research nodes"]] unless kind == "research"
+    return [nil, ["report: must be a non-empty relative Markdown path under resources/"]] unless raw.is_a?(String)
+
+    path = raw
+    parts = path.split("/", -1)
+    valid = path == path.strip && parts.length >= 2 && parts.first == "resources" &&
+            parts.none? { |part| part.empty? || %w[. ..].include?(part) } &&
+            !path.include?("\\") && path.end_with?(".md")
+    return [nil, ["report: must be a relative .md path under resources/ with no traversal"]] unless valid
+
+    [path, []]
+  end
+  private_class_method :normalize_report
+
+  # <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
+  # (review 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 (from 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 (see: "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