@zalom/plastic 1.2.0 → 1.4.0

package/scripts/lib/restore_intent_v1.rb

@@ -0,0 +1,154 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_rebuild"
+require_relative "frontmatter_writer"
+
+# RestoreIntentV1 - pure graph math for restoring a completed intent's frontmatter
+# graph across a v1 prose revert (intent 193). No file IO, no git, no `system`.
+#
+# The rule this module carries: prose reverts to v1; the sources/chain graph is
+# APPEND-ONLY and is the UNION of the v1 snapshot and the current snapshot, never
+# a re-derivation from other intents' reciprocal edges (that would silently erase
+# legitimate I2-asymmetry edges doctor.rb never auto-fixes). Before the union is
+# written, every edge (from either snapshot) is target-resolved by reusing
+# GraphRebuild.resolve_ref verbatim, the same classifier rebuild-graph and
+# doctor.rb already share: a :dead edge (resolves to no id in any known store) is
+# dropped and reported; :same_store, :cross_store, and :unknown_store edges are
+# all kept (bias toward preserving an edge that might be real; only positive proof
+# of non-existence justifies a drop). The value WRITTEN for a kept edge is the
+# RESOLVED value GraphRebuild returns (classification[:id] for :same_store,
+# classification[:ref] for :cross_store), never the raw pre-resolution ref, so
+# this tool can never disagree with rebuild-graph/doctor about the canonical form
+# of an edge it just wrote (D14).
+module RestoreIntentV1
+  module_function
+
+  # PURE. Computes the desired sources/chain for a restore.
+  #
+  # Returns:
+  #   { sources: [...], chain: [...],
+  #     dropped:      [ { field: :sources|:chain, ref: "<id or store:id>" }, ... ],
+  #     unverified:   [ { field: :sources|:chain, ref: "<id or store:id>" }, ... ],
+  #     current_only: [ { field: :sources|:chain, ref: "<id or store:id>" }, ... ] }
+  #
+  # `current_only` names every edge present in the CURRENT snapshot but absent from
+  # the v1 snapshot (D3 transparency): an edge added by the very change being
+  # reverted, which the union now carries forward. Named explicitly regardless of
+  # its target-resolution outcome, so it is never a silent side effect.
+  def compute_graph(v1_sources:, v1_chain:, current_sources:, current_chain:,
+                     referer_store:, relocation_map:, store_index:)
+    sources_result = resolve_union(v1_sources, current_sources, :sources,
+                                    referer_store, relocation_map, store_index)
+    chain_result = resolve_union(v1_chain, current_chain, :chain,
+                                  referer_store, relocation_map, store_index)
+
+    {
+      sources: sources_result[:kept],
+      chain: chain_result[:kept],
+      dropped: sources_result[:dropped] + chain_result[:dropped],
+      unverified: sources_result[:unverified] + chain_result[:unverified],
+      current_only: current_only_edges(v1_sources, current_sources, :sources) +
+                    current_only_edges(v1_chain, current_chain, :chain),
+    }
+  end
+
+  # PURE. Union two edge arrays (deduped, order-preserving, first array's order
+  # wins for shared entries), then target-resolve each via GraphRebuild.resolve_ref.
+  # WRITES THE RESOLVED VALUE, not the raw union member: a redundant same-store
+  # prefix (e.g. "global:15" written by a "global" intent) collapses to the bare
+  # "15", and a relocated ref is repointed to its resolved "store:id" form, exactly
+  # matching what GraphRebuild.rebuild_store itself writes (res[:id] / res[:ref]).
+  # Resolution can make two distinct union members collapse to the same resolved
+  # value, so `kept` is de-duped again after resolution.
+  def resolve_union(v1_edges, current_edges, field, referer_store, relocation_map, store_index)
+    union = (Array(v1_edges).map(&:to_s) + Array(current_edges).map(&:to_s)).uniq
+    kept = []
+    dropped = []
+    unverified = []
+
+    union.each do |ref|
+      classification = GraphRebuild.resolve_ref(
+        ref, referer_store: referer_store, relocation_map: relocation_map, store_index: store_index
+      )
+      case classification[:status]
+      when :dead
+        dropped << { field: field, ref: ref }
+      when :unknown_store
+        kept << ref
+        unverified << { field: field, ref: ref }
+      when :same_store
+        kept << classification[:id]
+      when :cross_store
+        kept << classification[:ref]
+      end
+    end
+
+    { kept: kept.uniq, dropped: dropped, unverified: unverified }
+  end
+
+  # PURE. Every edge present in `current_edges` but absent from `v1_edges`
+  # (raw, before target resolution): the set the restore is about to carry
+  # forward that v1 itself never had.
+  def current_only_edges(v1_edges, current_edges, field)
+    v1_set = Array(v1_edges).map(&:to_s)
+    Array(current_edges).map(&:to_s).uniq.reject { |ref| v1_set.include?(ref) }
+                         .map { |ref| { field: field, ref: ref } }
+  end
+
+  # PURE. Reapply the computed graph onto v1's exact prose. Delegates entirely to
+  # FrontmatterWriter; this module never rewrites YAML itself.
+  def apply_graph(v1_content, desired_sources:, desired_chain:)
+    FrontmatterWriter.rewrite_arrays(v1_content, sources: desired_sources, chain: desired_chain)
+  end
+
+  # PURE. Render one revisions.md entry (intent 107's append-only, move-and-record
+  # convention). `n` is the next revision number for this intent's revisions.md.
+  # `files` names every file reverted to its v1 content in this restore.
+  def render_revision_entry(n, at:, timestamp:, files:, before_sources:, after_sources:,
+                             before_chain:, after_chain:, dropped:)
+    lines = []
+    lines << "## Revision v#{n} - #{timestamp}"
+    lines << "- Why: restore-to-v1 preserved the frontmatter graph across a completed-intent " \
+             "restore [rule: restored-to-v1]"
+    lines << "- Prior location: frontmatter - sources/chain; prose reverted to ref #{at}"
+    lines << "- Files reverted to v1: #{files.empty? ? "(none, already at v1)" : files.join(", ")}"
+    lines << "- Change: sources (before: #{before_sources.inspect} -> after: #{after_sources.inspect}); " \
+             "chain (before: #{before_chain.inspect} -> after: #{after_chain.inspect})"
+    unless dropped.empty?
+      lines << ""
+      dropped.each do |d|
+        lines << "  Dropped dead edge in #{d[:field]} -> #{d[:ref]}: target intent does not exist."
+      end
+    end
+    "#{lines.join("\n")}\n"
+  end
+
+  # PURE. Render the dry-run/apply human-readable report. `v1` and `current` are
+  # { sources:, chain: } snapshots shown alongside the resulting union so a
+  # reviewer can see all three shapes without recomputing anything by hand (spec
+  # acceptance criterion: dry-run prints the v1 graph, the current graph, and the
+  # resulting union, not only the union).
+  def render_report(base:, at:, prose_changes:, v1:, current:, graph:, apply:)
+    lines = []
+    lines << "restore-intent-v1: #{base} at #{at} (#{apply ? "APPLY" : "DRY RUN"})"
+    prose_changes.each { |f| lines << "  prose: revert #{f}" }
+    lines << "  v1 sources -> #{v1[:sources].inspect}"
+    lines << "  v1 chain -> #{v1[:chain].inspect}"
+    lines << "  current sources -> #{current[:sources].inspect}"
+    lines << "  current chain -> #{current[:chain].inspect}"
+    lines << "  union sources -> #{graph[:sources].inspect}"
+    lines << "  union chain -> #{graph[:chain].inspect}"
+    graph[:dropped].each do |d|
+      lines << "  DROPPED dead edge (#{d[:field]}): #{d[:ref]} - target intent does not exist"
+    end
+    graph[:unverified].each do |d|
+      lines << "  UNVERIFIED edge (#{d[:field]}): #{d[:ref]} - store unknown, kept"
+    end
+    graph[:current_only].each do |d|
+      lines << "  CURRENT-ONLY edge (#{d[:field]}): #{d[:ref]} - added by the change being " \
+               "reverted, now surviving the restore"
+    end
+    lines.join("\n")
+  end
+end

package/scripts/lib/roadmap_queue.rb

@@ -112,7 +112,7 @@ class RoadmapQueue
 
   def parse_roadmap(path)
     text = File.read(path)
-    { slug: File.basename(path, ".md"), path: path, waves: parse_waves(section_body(text, "Waves")) }
+    { slug: File.basename(path, ".md"), path: path, waves: parse_waves(RoadmapSavepoint.grouping_section_body(text, path: path)) }
   end
 
   def parse_waves(waves_body)

package/scripts/lib/roadmap_savepoint.rb

@@ -21,12 +21,20 @@ require "fileutils"
 module RoadmapSavepoint
   module_function
 
-  EVENTS = %w[created dispatched parked merged release handoff closed added reordered wave].freeze
+  EVENTS = %w[created dispatched parked merged release handoff closed added reordered wave batch].freeze
+
+  # Raised by grouping_section_body when a roadmap has neither '## Batches' (canonical, owner
+  # ruling 145) nor '## Waves' (legacy) as its top-level grouping heading (intent 196): a
+  # malformed roadmap must fail loudly, never silently parse as zero entries.
+  class MissingGroupingHeading < StandardError; end
+
+  # Canonical first, legacy fallback second. A roadmap file has exactly one of these, never both.
+  GROUPING_HEADINGS = %w[Batches Waves].freeze
 
   # Keyword -> event classification for `rebuild`, checked top to bottom, first match wins.
   # Kept small and deterministic (action 1). Order matters: more specific/rarer words are
-  # checked before the broader "wave" fallback so an incidental "wave" mention in an otherwise
-  # classifiable line never shadows its real event.
+  # checked before the broader "wave"/"batch" fallbacks so an incidental "wave" or "batch"
+  # mention in an otherwise classifiable line never shadows its real event.
   KEYWORD_TABLE = [
     [/\bclosed\b/i, "closed"],
     [/\bhanded off\b|\bhandoff\b/i, "handoff"],
@@ -38,6 +46,7 @@ module RoadmapSavepoint
     [/\badded\b|\badds\b/i, "added"],
     [/\bcreated\b/i, "created"],
     [/\bwave\b/i, "wave"],
+    [/\bbatch(?:es)?\b/i, "batch"],
   ].freeze
 
   # --- append -----------------------------------------------------------------
@@ -88,15 +97,16 @@ module RoadmapSavepoint
   # --- rebuild ------------------------------------------------------------------
 
   # Reconstruct the paired ledger deterministically from the roadmap file's `## Log` (never the
-  # roadmap `.md`, which is read-only here), cross-checked against `## Waves` and the tier's
-  # INDEX so every `delivered` wave entry has a `merged` line. Every timestamp comes from an
-  # on-disk source (the Log, or INDEX `## Completed`); an entry with no recoverable timestamp is
-  # not emitted (D4, never invented). Overwrites the ledger (the one operation allowed to rewrite
-  # it, matching `Bridge.rebuild_savepoint`). Returns the number of lines written.
+  # roadmap `.md`, which is read-only here), cross-checked against the roadmap's grouping
+  # section (`## Batches`, or legacy `## Waves`) and the tier's INDEX so every `delivered` wave
+  # entry has a `merged` line. Every timestamp comes from an on-disk source (the Log, or INDEX
+  # `## Completed`); an entry with no recoverable timestamp is not emitted (D4, never invented).
+  # Overwrites the ledger (the one operation allowed to rewrite it, matching
+  # `Bridge.rebuild_savepoint`). Returns the number of lines written.
   def rebuild(roadmap_path)
     text = File.read(roadmap_path)
     log_lines = classify_log(section_body(text, "Log"))
-    delivered_ids = delivered_wave_ids(section_body(text, "Waves"))
+    delivered_ids = delivered_wave_ids(grouping_section_body(text, path: roadmap_path))
     backfilled = backfill_merged_lines(log_lines, delivered_ids, roadmap_path)
 
     lines = dedup_pairs(log_lines + backfilled)
@@ -139,7 +149,8 @@ module RoadmapSavepoint
 
   WAVE_ENTRY = /\A-\s*\[([ xX])\]\s+(\S+)\s+.+—\s*(\S+)\s*\z/.freeze
 
-  # Intent ids of every `[x] ... — delivered` entry in the `## Waves` body.
+  # Intent ids of every `[x] ... — delivered` entry in the roadmap's grouping section body
+  # (`## Batches`, or legacy `## Waves`).
   def delivered_wave_ids(waves_body)
     waves_body.each_line.filter_map do |line|
       m = line.strip.match(WAVE_ENTRY)
@@ -198,6 +209,23 @@ module RoadmapSavepoint
   end
   private_class_method :section_body
 
+  # The one shared fix point for the Batches/Waves grammar (intent 196). '## Batches' is
+  # canonical (owner ruling 145); '## Waves' is the legacy heading the three pre-ruling roadmaps
+  # still use and must keep parsing forever (145 also forbids renaming those files). Public,
+  # because roadmap_queue.rb calls it instead of holding its own copy of the heading string: that
+  # file already depends one-directionally on this module (require_relative "roadmap_savepoint",
+  # already calling `ledger_path_for`), so this is the smaller diff than a new shared module.
+  # Raises MissingGroupingHeading, naming the offending path, when neither heading is present.
+  def grouping_section_body(text, path: nil)
+    GROUPING_HEADINGS.each do |heading|
+      m = text.match(/^##\s+#{Regexp.escape(heading)}\s*$(.*?)(?=^##\s|\z)/m)
+      return m[1] if m
+    end
+    raise MissingGroupingHeading,
+          "#{path || '(unknown roadmap file)'}: found neither '## Batches' (canonical) nor " \
+          "'## Waves' (legacy) grouping heading"
+  end
+
   # Stable dedup on the `(event, detail)` pair, keeping the first occurrence in the given
   # (already chronological-then-backfill-appended) order.
   def dedup_pairs(lines)

package/scripts/lib/store_discovery.rb

@@ -0,0 +1,77 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "store_provisioning"
+
+# StoreDiscovery: the single source of truth for "what stores exist" (intent 189).
+#
+# Two failure modes must both be avoided: missing a real store (a live cross-store ref
+# into it gets classified dead and DELETED by rebuild-graph, the data-loss bug this module
+# fixes) and silently treating a registered-but-unprovisioned project as an empty store (a
+# different silent failure). So discovery is a SUPERSET: the global store (if it exists)
+# plus every `projects/<slug>/store` directory that exists on disk, UNIONED with every slug
+# registered in projects.yml. A registered slug with no store directory contributes no ids
+# and is reported separately in `missing`, never silently dropped.
+#
+# Reuses StoreProvisioning.load_projects (rescues to {} so a malformed projects.yml never
+# raises) instead of writing a third copy of that reader (a second copy already exists in
+# QmdSync, out of scope here).
+#
+# Pure filesystem, dependency-injected: `discover` takes `plastic_home` as its only
+# argument, performs no writes, no `system`/`spawn`, no network, no eval, no
+# ENV/global-constant reads.
+module StoreDiscovery
+  module_function
+
+  # Returns { stores: [ { key:, slug:, root:, store:, index: } ... ],
+  #           missing: [ { slug:, project_dir: } ... ] }.
+  #
+  # `stores` entries: `key` is "global" or "project:<slug>" (the store_index/referer_store
+  # key shape GraphRebuild and the doctor checks already use); `slug` is the bare token
+  # form used in a cross-store ref ("global", "knowdb", "ai-agents-resources"); `root` is
+  # the directory holding INDEX.md; `store` is the intents directory; `index` is the
+  # INDEX.md path. Sorted by slug (global first) for deterministic output.
+  #
+  # `missing` lists every projects.yml slug with no `store/` directory on disk: legal
+  # (plastic-store-provisioning exists for exactly this state), reported so callers never
+  # mistake it for a store with zero intents.
+  def discover(plastic_home)
+    stores = []
+    missing = []
+
+    global_store = File.join(plastic_home, "store")
+    if File.directory?(global_store)
+      stores << { key: "global", slug: "global", root: plastic_home,
+                  store: global_store, index: File.join(plastic_home, "INDEX.md") }
+    end
+
+    registered = StoreProvisioning.load_projects(plastic_home) # { slug => info }, {} on error/absence
+    projects_root = File.join(plastic_home, "projects")
+    on_disk = File.directory?(projects_root) ? Dir.children(projects_root).reject { |e| e.start_with?(".") } : []
+
+    all_slugs = (registered.keys + on_disk).uniq.sort
+
+    all_slugs.each do |slug|
+      root = File.join(projects_root, slug)
+      store_dir = File.join(root, "store")
+      if File.directory?(store_dir)
+        stores << { key: "project:#{slug}", slug: slug, root: root,
+                    store: store_dir, index: File.join(root, "INDEX.md") }
+      elsif registered.key?(slug)
+        missing << { slug: slug, project_dir: root }
+      end
+      # else: an on-disk directory with no store/ and no projects.yml entry (a junk dir,
+      # e.g. a stale path-as-slug from a past bug). Silently excluded, exactly as doctor's
+      # existing disk scan already does: it is neither a store nor a registered project.
+    end
+
+    { stores: stores, missing: missing }
+  end
+
+  # Convenience: just the known store SLUGS (the token form used in a cross-store ref),
+  # for IntentValidator's injected known-store check (ACTION_7). "global" is included
+  # when the global store exists.
+  def known_slugs(plastic_home)
+    discover(plastic_home)[:stores].map { |s| s[:slug] }
+  end
+end

package/scripts/lib/store_provisioning.rb

@@ -44,24 +44,33 @@ module StoreProvisioning
       }
     end
 
+    index_template = File.join(package_root, "templates", "index.md")
+    project_template = File.join(package_root, "templates", "project.yml")
+
+    missing = []
+    missing << "templates/index.md" unless File.exist?(index_template)
+    missing << "templates/project.yml" unless File.exist?(project_template)
+
+    unless missing.empty?
+      return {
+        ok: false,
+        error: "cannot provision project '#{slug}': missing required " \
+               "template(s) #{missing.join(", ")} under #{package_root}/templates. " \
+               "This means the installer did not ship these templates to " \
+               "package_root/templates: check InstallerCore#core_files registers " \
+               "every templates/* file, then re-run the Plastic installer (or " \
+               "'plastic update') so package_root has current templates.",
+      }
+    end
+
     project_dir = File.join(plastic_home, "projects", slug)
     store_dir = File.join(project_dir, "store")
     FileUtils.mkdir_p(store_dir)
 
     created = []
     created << write_if_missing(File.join(store_dir, ".gitkeep"), "")
-
-    index_template = File.join(package_root, "templates", "index.md")
-    if File.exist?(index_template)
-      created << write_if_missing(File.join(project_dir, "INDEX.md"),
-                                  File.read(index_template))
-    end
-
-    project_template = File.join(package_root, "templates", "project.yml")
-    if File.exist?(project_template)
-      created << write_if_missing(File.join(project_dir, "project.yml"),
-                                  File.read(project_template))
-    end
+    created << write_if_missing(File.join(project_dir, "INDEX.md"), File.read(index_template))
+    created << write_if_missing(File.join(project_dir, "project.yml"), File.read(project_template))
 
     { ok: true, store_dir: store_dir, created: created.compact }
   end

package/scripts/new-intent

@@ -29,6 +29,7 @@ require_relative "lib/intent_validator"
 require_relative "lib/graph_rebuild"
 require_relative "lib/links_projection"
 require_relative "lib/links_section"
+require_relative "lib/store_discovery"
 
 # --- Explicit flag parsing (no eval, no global injection) ------------------
 
@@ -162,17 +163,12 @@ def store_context(store)
   end
 end
 
-# The in-scope stores under `plastic_home`, each { key:, store: }. Mirrors
-# project-links/RebuildGraph#stores so cross-store resolution spans the family.
+# The in-scope stores under `plastic_home`, each { key:, store: }. Delegates to
+# StoreDiscovery, the single source of truth also used by project-links, rebuild-graph,
+# and doctor.rb (intent 189), so cross-store resolution spans EVERY real store, not a
+# hardcoded few.
 def family_stores(plastic_home)
-  list = []
-  global_store = File.join(plastic_home, "store")
-  list << { key: "global", store: global_store } if File.directory?(global_store)
-  %w[plastic knowdb].each do |slug|
-    store = File.join(plastic_home, "projects", slug, "store")
-    list << { key: "project:#{slug}", store: store } if File.directory?(store)
-  end
-  list
+  StoreDiscovery.discover(plastic_home)[:stores].map { |s| { key: s[:key], store: s[:store] } }
 end
 
 # Build the cross-store maps the LinksProjection resolver needs:
@@ -353,8 +349,10 @@ def main(argv)
   # fire adds nothing.
   Bridge.append_savepoint(intent_dir, intent_file)
 
-  # 7. Self-validate (frontmatter + sanctioned sections).
-  result = IntentValidator.validate(intent_dir)
+  # 7. Self-validate (frontmatter + sanctioned sections), including that every
+  # sources/chain cross-store token names a real store (intent 189 D3).
+  known_stores = StoreDiscovery.known_slugs(plastic_home)
+  result = IntentValidator.validate(intent_dir, known_stores: known_stores)
   unless result[:ok]
     warn "new-intent: scaffolded intent is NOT born complete:"
     result[:missing].each { |f| warn "  missing field: #{f}" }