@zalom/plastic 2.0.0-alpha.26 → 2.0.0-alpha.28

package/scripts/lib/project_validator.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "yaml"
 
 # ProjectValidator - the single source of truth for "is a project spawn
@@ -10,7 +11,7 @@ require "yaml"
 # missing the pieces a real project needs: project.yml, a root AGENTS.md.
 # The intent-26 spawn shipped exactly that shape and was caught only by a
 # much later, pull-only plastic-doctor sweep. This module lets
-# plastic-project-creating verify a spawn BEFORE announcing it as done,
+# `plastic project new` verify a spawn BEFORE announcing it as done,
 # mirroring how scripts/new-intent already runs IntentValidator before
 # announcing a new intent (validate-intent).
 #
@@ -52,7 +53,7 @@ module ProjectValidator
       errors << "registered project directory does not exist: #{project_path}"
     end
 
-    project_dir = File.join(plastic_home, "projects", slug)
+    project_dir = Plastic::StoreLayout.project_root(plastic_home, slug)
 
     # Invariant 3: project.yml exists AND parses as YAML.
     project_yml_path = File.join(project_dir, "project.yml")

package/scripts/lib/qmd_sync.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "yaml"
 require "json"
 
@@ -50,7 +51,7 @@ module QmdSync
   # to the directory's parent name when no registry match exists.
   def collection_name(store_dir, plastic_home:)
     store_dir = File.expand_path(store_dir)
-    global_store = File.expand_path(File.join(plastic_home, "store"))
+    global_store = File.expand_path(Plastic::StoreLayout.global_store(plastic_home))
     return "plastic-global" if store_dir == global_store
 
     if File.basename(store_dir) == "roadmaps"
@@ -69,7 +70,7 @@ module QmdSync
   def enumerate_stores(plastic_home:)
     stores = [{
       collection: "plastic-global",
-      dir: File.expand_path(File.join(plastic_home, "store")),
+      dir: File.expand_path(Plastic::StoreLayout.global_store(plastic_home)),
     }]
 
     projects = load_projects(plastic_home)
@@ -80,7 +81,7 @@ module QmdSync
       # Project stores live under ~/.plastic/projects/<slug>/store as the mirror;
       # registry `path` is the project code dir, so the tactical store is the
       # plastic_home projects mirror.
-      mirror_store = File.expand_path(File.join(plastic_home, "projects", slug.to_s, "store"))
+      mirror_store = File.expand_path(File.join(Plastic::StoreLayout.project_root(plastic_home, slug.to_s), "store"))
       dir = Dir.exist?(mirror_store) ? mirror_store : project_store
       stores << { collection: "plastic-#{slug}", dir: dir }
     end
@@ -245,13 +246,13 @@ module QmdSync
       path = info.is_a?(Hash) ? info["path"] : nil
       next unless path
       project_root = File.expand_path(path)
-      mirror = File.expand_path(File.join(plastic_home, "projects", slug.to_s, "store"))
+      mirror = File.expand_path(File.join(Plastic::StoreLayout.project_root(plastic_home, slug.to_s), "store"))
       return slug.to_s if store_dir == File.join(project_root, "store") || store_dir == mirror
     end
     # Fallback: <...>/projects/<slug>/store -> slug, else parent dir name.
-    parts = store_dir.split(File::SEPARATOR)
-    idx = parts.rindex("projects")
-    return parts[idx + 1] if idx && parts[idx + 1] && parts[idx + 2] == "store"
+    slug = Plastic::StoreLayout.locate(store_dir).last
+    return slug unless slug == Plastic::StoreLayout::GLOBAL
+
     File.basename(File.dirname(store_dir))
   end
 end

package/scripts/lib/reference_archive.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "sqlite"
+
+module Plastic
+  module ReferenceArchive
+    NAME = "references.db"
+    SCHEMA = <<~SQL
+      CREATE TABLE IF NOT EXISTS sqlar(name TEXT PRIMARY KEY, mode INT, mtime INT, sz INT, data BLOB, intent_id TEXT, sha256 TEXT);
+    SQL
+    INTENT_ID = %r{/([^/-]+)--[^/]+/}
+    SKIPPED = %r{(\A|/)(\.git|\.tmp)/|\.DS_Store\z|\.lock\z}
+
+    def self.path(home)
+      File.join(home, NAME)
+    end
+
+    def self.files(home)
+      Dir.glob("{store,projects,stores}/**/*", File::FNM_DOTMATCH, base: home)
+        .select { |file| File.file?(File.join(home, file)) && File.extname(file) != ".md" && !file.match?(SKIPPED) }.sort
+    end
+
+    def self.build(home)
+      known = Sqlite.call(path(home), "#{SCHEMA}SELECT name, mtime, sz FROM sqlar;").to_h { |row| [row["name"], row.values_at("mtime", "sz")] }
+      changed = files(home).reject { |file| known[file] == stamp(File.join(home, file)) }
+      Sqlite.call(path(home), ["BEGIN;", *changed.map { |file| insert(home, file) }, "COMMIT;"].join("\n"))
+      changed.size
+    end
+
+    def self.stamp(source)
+      stat = File.stat(source)
+      [stat.mtime.to_i, stat.size]
+    end
+
+    def self.insert(home, file)
+      source = File.join(home, file)
+      stat = File.stat(source)
+      id = file[INTENT_ID, 1]
+      read = "readfile(#{Sqlite.quote(source)})"
+      "INSERT OR REPLACE INTO sqlar VALUES(#{Sqlite.quote(file)}, #{stat.mode}, #{stat.mtime.to_i}, length(#{read}), " \
+        "sqlar_compress(#{read}), #{id ? Sqlite.quote(id) : "NULL"}, #{Sqlite.quote(Digest::SHA256.file(source).hexdigest)});"
+    end
+  end
+end

package/scripts/lib/release_guard.rb

@@ -52,6 +52,8 @@ module ReleaseGuard
   # to the stable channel. Pure function, no ENV reads, shared by
   # scripts/release-check and the test suite so the channel rule has exactly
   # one implementation (intent 347).
+  CHANNELS = {"alpha" => "alpha", "beta" => "beta", "main" => "latest"}.freeze
+
   def self.dist_tag(version)
     suffix = version[/-(.+)\z/, 1]
     return "latest" if suffix.nil?

package/scripts/lib/report_screen.rb

@@ -8,6 +8,7 @@
 # out. Dependency injection for anything reaching outside the fixture: the
 # clock is passed as `now:`, git tag reading as `tag_reader:`, and the ANSI
 # renderer path as `renderer_path:` (D2).
+require_relative "store_layout"
 require "time"
 require "json"
 require "date"
@@ -805,14 +806,14 @@ def self.matching_action_heading(intent_dir, label)
   # (<home>/projects/<slug>/store/<id--slug>); nil otherwise (a global-store
   # intent, a project with no `flow:` key, or malformed YAML). Pure: no git,
   # no shell-out, just the one file this intent's own layout already reads.
-  PROJECT_LAYOUT_RE = %r{\A(.*)/projects/([^/]+)/store/[^/]+\z}.freeze
+  PROJECT_LAYOUT_RE = %r{\A(.*)/(?:projects|stores)/([^/]+)/store/[^/]+\z}.freeze
 
   def self.flow_base(intent_dir)
     m = intent_dir.to_s.match(PROJECT_LAYOUT_RE)
     return nil unless m
 
     home, slug = m[1], m[2]
-    path = File.join(home, "projects", slug, "project.yml")
+    path = File.join(Plastic::StoreLayout.project_root(home, slug), "project.yml")
     return nil unless File.exist?(path)
 
     require "yaml"
@@ -1480,7 +1481,7 @@ def self.matching_action_heading(intent_dir, label)
 
   # D5: "global" is <home> itself; any other slug is <home>/projects/<slug>.
   def self.store_for_slug(home, slug)
-    slug == "global" ? home : File.join(home, "projects", slug)
+    slug == "global" ? home : Plastic::StoreLayout.project_root(home, slug)
   end
 
   # D4: the newest valid day directory that is not in the future, when

package/scripts/lib/rlm/corpus.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RLM
+  class Corpus
+    def initialize(search)
+      @search = search
+    end
+
+    def call(terms, limit)
+      @search.call(terms, limit)
+    end
+  end
+end

package/scripts/lib/rlm/probe.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "corpus"
+
+module RLM
+  class Probe
+    STOP_WORDS = %w[a an and are as at be by do does for from how in is it of on or that the this to was what when where which who why with].freeze
+    DEFAULT_LIMIT = 10
+
+    def initialize(corpus, limit: DEFAULT_LIMIT)
+      @corpus = corpus
+      @limit = limit
+    end
+
+    def call(question)
+      hits = terms(question).flat_map { |term| @corpus.call([term], @limit) }
+      hits.group_by { |row| row["id"] }.values
+        .map { |rows| rows.first.merge("score" => rows.size) }
+        .sort_by.with_index { |row, index| [-row["score"], index] }
+        .first(@limit)
+    end
+
+    private
+
+    def terms(question)
+      question.downcase.scan(/[[:alnum:]]+/).uniq - STOP_WORDS
+    end
+  end
+end

package/scripts/lib/rlm/query.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "probe"
+
+module RLM
+  class Query
+    DEFAULT_LIMIT = 3
+
+    def initialize(probe, judge: nil, limit: DEFAULT_LIMIT)
+      @probe = probe
+      @judge = judge
+      @limit = limit
+    end
+
+    def call(question)
+      rows = @probe.call(question)
+      return rows unless @judge && rows.size > @limit
+
+      @judge.call(question, rows)
+    end
+  end
+end

package/scripts/lib/roadmap_queue.rb

@@ -411,8 +411,8 @@ class RoadmapQueue
   # --- scope + payload -----------------------------------------------------------
 
   def scope_label
-    m = @roadmaps_dir.to_s.match(%r{/projects/([^/]+)/roadmaps/?\z})
-    m ? "project:#{m[1]}" : "global"
+    m = @roadmaps_dir.to_s.match(%r{/(?:projects|stores)/([^/]+)/roadmaps/?\z})
+    (m && m[1] != "global") ? "project:#{m[1]}" : "global"
   end
 
   def payload(mode:, state:, roadmap:, frontier_wave:, dispatchable:, in_flight:, blocked:, tie:, tie_candidates:)

package/scripts/lib/roadmap_savepoint.rb

@@ -224,7 +224,7 @@ module RoadmapSavepoint
 
   # The tier root is the parent of `roadmaps/` (a live roadmap's grandparent, or, for one
   # already moved to `roadmaps/archived/`, its great-grandparent); INDEX.md is that root's
-  # sibling file, matching the layout `plastic-roadmap`'s file-format doc defines.
+  # sibling file, matching the layout docs/help/roadmaps.md defines.
   def index_path_for(roadmap_path)
     dir = File.dirname(roadmap_path)
     dir = File.dirname(dir) if File.basename(dir) == "archived"

package/scripts/lib/runner_absorb.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "yaml"
 require "date"
 require "time"
@@ -59,7 +60,7 @@ module RunnerAbsorb
   # to plain strings), this cap is purely about line length.
   FINDING_CAP = 200
 
-  PROJECT_LAYOUT_RE = %r{\A(.*)/projects/([^/]+)/store/[^/]+\z}.freeze
+  PROJECT_LAYOUT_RE = %r{\A(.*)/(?:projects|stores)/([^/]+)/store/[^/]+\z}.freeze
 
   # absorb(context, node:, return_path:) -> a result hash describing the one
   # transition it wrote (or attempted to write). Never raises across its own
@@ -100,6 +101,7 @@ module RunnerAbsorb
     node_decl = ((context.graph || {})[:nodes] || {})[node] || {}
     kind = node_decl[:kind]
     declared_files = normalize_files(node_decl[:files])
+    report_path = declared_report_path(intent_dir, node)
 
     # v2 NEW-2: a `graph.md` that failed to parse, or a node whose kind
     # cannot be resolved from it, refuses right here - before ANY check
@@ -143,6 +145,11 @@ module RunnerAbsorb
       return fail_check(savepoint_path, context, node, "node_mismatch", checks_ran, holder, extra_fields, now, ledger)
     end
 
+    report_reason = report_contract_violation(kind, report_path, parsed)
+    if report_reason
+      return fail_check(savepoint_path, context, node, report_reason, checks_ran, holder, extra_fields, now, ledger)
+    end
+
     append_findings(intent_dir, node, parsed.findings, now: now)
 
     proposal_result = nil
@@ -267,6 +274,14 @@ module RunnerAbsorb
     end
 
     commit_value = merge_commit || parsed.commit
+    if report_path
+      report_result = persist_report(intent_dir, report_path, parsed.report)
+      unless report_result[:ok]
+        return finish.call(fail_check(savepoint_path, context, node, report_result[:reason], gates.split("+") + ["report"],
+                                      holder, extra_fields, now, ledger))
+      end
+      gates = "#{gates}+report"
+    end
     fields = { gates: gates, commit: commit_value, holder: holder, suite: suite_value }.merge(extra_fields)
     result = write_transition(savepoint_path, context, node, "done", fields, now: now, ledger: ledger)
 
@@ -420,6 +435,48 @@ module RunnerAbsorb
   end
   private_class_method :normalize_scope_path
 
+  # --- research report -------------------------------------------------------
+
+  def declared_report_path(intent_dir, node)
+    path = ReadySet.find_node_path(intent_dir, node)
+    return nil unless path
+
+    parsed = NodeFile.parse(path)
+    parsed[:ok] ? parsed[:report] : nil
+  end
+  private_class_method :declared_report_path
+
+  def report_contract_violation(kind, declared, parsed)
+    return "report_not_declared" if parsed.report && declared.nil?
+    return nil unless parsed.status == "done"
+    return "report_missing" if declared && parsed.report.to_s.strip.empty?
+    return "report_not_research" if parsed.report && kind.to_s != "research"
+
+    nil
+  end
+  private_class_method :report_contract_violation
+
+  def persist_report(intent_dir, relative_path, content)
+    resources_root = File.expand_path(File.join(intent_dir, "resources"))
+    target = File.expand_path(File.join(intent_dir, relative_path.to_s))
+    unless target.start_with?("#{resources_root}/") && target.end_with?(".md")
+      return { ok: false, reason: "report_path_invalid" }
+    end
+
+    if File.exist?(target)
+      return { ok: true, path: target } if File.binread(target) == content.to_s
+
+      return { ok: false, reason: "report_conflict" }
+    end
+
+    FileUtils.mkdir_p(File.dirname(target))
+    AtomicWrite.write(target, content.to_s)
+    { ok: true, path: target }
+  rescue StandardError
+    { ok: false, reason: "report_write_failed" }
+  end
+  private_class_method :persist_report
+
   # --- named tests -----------------------------------------------------------
 
   # Row 4.19/minor 1: read the node's own failure-mode matrix table, take
@@ -619,7 +676,7 @@ module RunnerAbsorb
     return nil unless m
 
     home, slug = m[1], m[2]
-    path = File.join(home, "projects", slug, "project.yml")
+    path = File.join(Plastic::StoreLayout.project_root(home, slug), "project.yml")
     return nil unless File.exist?(path)
 
     data = begin

package/scripts/lib/runner_dispatch.rb

@@ -37,7 +37,7 @@ module RunnerDispatch
   RETURN_CONTRACT = <<~TEXT.freeze
     RETURN CONTRACT: reply with exactly one YAML document as your final
     message, nothing else around it. Keys: node, status, commit, summary,
-    findings, proposed_nodes, proposed_edges, question, reason. status is one
+    findings, report, proposed_nodes, proposed_edges, question, reason. status is one
     of done, failed_verification, needs_decision, blocked. done requires
     commit; needs_decision requires question; failed_verification and
     blocked require reason. Anything that does not parse under this closed
@@ -47,7 +47,7 @@ module RunnerDispatch
   HARD_CAP_RE = /\Ais at its dispatch cap \((\d+)\/(\d+)\)\z/.freeze
 
   # D8 (355, n6): the agent every dispatched, non-decision node names - a
-  # role, never a harness (matrix 6.5), and never `plastic-advisor`, which
+  # role, never a harness (matrix 6.5), and never a consultation advisor, which
   # stays a deliberate, never-auto-dispatched consultation agent.
   SPAWN_AGENT = "plastic-executor"
 
@@ -56,8 +56,8 @@ module RunnerDispatch
   # (NodeInput.test_command_block, n4), and the call cap (n2) - fenced so a
   # session pastes it straight into the Agent tool (327 D42: the runner
   # itself never spawns).
-  def spawn_block(model:, input:, test_command:, call_cap:, agent: SPAWN_AGENT)
-    lines = ["agent: #{agent}", "model: #{model}", "input: #{input}", test_command,
+  def spawn_block(model:, input:, test_command:, call_cap:, effort: AgentModels::DEFAULT_EFFORT, agent: SPAWN_AGENT)
+    lines = ["agent: #{agent}", "model: #{model}", "effort: #{effort}", "input: #{input}", test_command,
              NodeInput.call_cap_sentence(call_cap)]
     (["```"] + lines + ["```"]).join("\n")
   end
@@ -220,7 +220,8 @@ module RunnerDispatch
     savepoint_path = File.join(intent_dir.to_s, "savepoint.md")
 
     holder = context.session
-    model = RunnerPolicy.model_for(kind, config: config)
+    model = RunnerPolicy.model_for(kind, config: config, harness: harness)
+    effort = RunnerPolicy.effort_for(kind, config: config, harness: harness)
     expires = RunnerPolicy.lease_expires(kind, now: now)
     calls_cap = RunnerPolicy.call_cap(kind, config: config)
 
@@ -267,7 +268,7 @@ module RunnerDispatch
     # Row 1.19/1.20/D21: harness= rides alongside model= on every `running`
     # line, resolved once by the caller through HarnessAdapter and threaded
     # straight through here - never re-resolved, never a literal.
-    fields = { holder: holder, expires: expires, input: build_result[:sha], model: model, harness: harness,
+    fields = { holder: holder, expires: expires, input: build_result[:sha], model: model, effort: effort, harness: harness,
                calls: calls_cap }
 
     result = begin
@@ -287,11 +288,13 @@ module RunnerDispatch
     end
 
     test_command = NodeInput.test_command_block(intent_dir: intent_dir, files: (nodes_decl[node] || {})[:files])
-    spawn = spawn_block(model: model, input: build_result[:path], test_command: test_command, call_cap: calls_cap)
+    spawn = spawn_block(model: model, effort: effort, input: build_result[:path], test_command: test_command,
+                        call_cap: calls_cap)
 
     {
       ok: true,
-      entry: { node: node, kind: kind.to_s, role: role_for(kind), model: model, worktree: provisioned[:path],
+      entry: { node: node, kind: kind.to_s, role: role_for(kind), model: model, effort: effort,
+                worktree: provisioned[:path],
                 input: build_result[:path], spawn: spawn },
     }
   end
@@ -507,6 +510,7 @@ module RunnerDispatch
       "return_contract" => RETURN_CONTRACT,
       "dispatch" => dispatched.map do |d|
         { "node" => d[:node], "kind" => d[:kind], "role" => d[:role], "model" => d[:model],
+          "effort" => d[:effort],
           "worktree" => d[:worktree], "input" => d[:input] }
       end,
       "spawn" => dispatched.map { |d| d[:spawn] }

package/scripts/lib/runner_policy.rb

@@ -35,7 +35,7 @@ module RunnerPolicy
   # resolves through AgentModels::TIER_DEFAULTS, the one place
   # `plastic-executor`'s shipped tier is already declared (post-execution
   # review minor 4), rather than a second, independently-drifting literal
-  # here. `plastic-advisor` carries no lifecycle-stage entry in
+  # here. `plastic-primary-advisor` carries no lifecycle-stage entry in
   # TIER_DEFAULTS at all (it is a consultation agent, never auto-dispatched
   # - see agent_models.rb's own docstring), so its default stays the one
   # literal this table cannot source from anywhere else.
@@ -43,7 +43,7 @@ module RunnerPolicy
   DEFAULT_ADVISOR_MODEL = "opus"
 
   EXECUTOR_CONFIG_KEY = "plastic-executor"
-  ADVISOR_CONFIG_KEY = "plastic-advisor"
+  ADVISOR_CONFIG_KEY = "plastic-primary-advisor"
 
   # {model_role:, worktree:, retry_cap:, diff_rule:, lease_minutes:} per kind
   # (327 D12). `decision` carries no retry cap or lease: it is never
@@ -69,24 +69,42 @@ module RunnerPolicy
   # verify resolves the advisor model, and a config with no override falls
   # back to the shipped default rather than an empty string (`running`
   # requires a non-blank `model=`).
-  def model_for(kind, config: {})
-    policy_for(kind)[:model_role] == :advisor ? advisor_model(config: config) : executor_model(config: config)
+  def model_for(kind, config: {}, harness: "claude-code")
+    alias_or_id = policy_for(kind)[:model_role] == :advisor ? advisor_model(config: config, harness: harness) :
+                                                              executor_model(config: config, harness: harness)
+    codex_harness?(harness) ? (AgentModels.codex_model_for(alias_or_id) || alias_or_id) : alias_or_id
   end
 
-  def executor_model(config: {})
-    resolve_model(config, EXECUTOR_CONFIG_KEY, DEFAULT_EXECUTOR_MODEL)
+  def executor_model(config: {}, harness: "claude-code")
+    resolve_model(config, EXECUTOR_CONFIG_KEY, DEFAULT_EXECUTOR_MODEL, harness)
   end
 
-  def advisor_model(config: {})
-    resolve_model(config, ADVISOR_CONFIG_KEY, DEFAULT_ADVISOR_MODEL)
+  def advisor_model(config: {}, harness: "claude-code")
+    resolve_model(config, ADVISOR_CONFIG_KEY, DEFAULT_ADVISOR_MODEL, harness)
   end
 
-  def resolve_model(config, key, shipped_default)
-    value = AgentModels.models_section(config)[key]
+  def effort_for(kind, config: {}, harness: "claude-code")
+    key = policy_for(kind)[:model_role] == :advisor ? ADVISOR_CONFIG_KEY : EXECUTOR_CONFIG_KEY
+    value = AgentModels.efforts_section(config, harness_name(harness))[key]
+    present?(value) ? value : AgentModels::DEFAULT_EFFORT
+  end
+
+  def resolve_model(config, key, shipped_default, harness)
+    value = AgentModels.models_section(config, harness: harness_name(harness))[key]
     present?(value) ? value : shipped_default
   end
   private_class_method :resolve_model
 
+  def harness_name(harness)
+    codex_harness?(harness) ? "codex" : "claude"
+  end
+  private_class_method :harness_name
+
+  def codex_harness?(harness)
+    harness.to_s == "codex"
+  end
+  private_class_method :codex_harness?
+
   def present?(value)
     !(value.nil? || value.to_s.strip.empty?)
   end

package/scripts/lib/search_index.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "sqlite"
+
+module Plastic
+  module SearchIndex
+    NAME = "knowledge_graph.db"
+    SCHEMA = <<~SQL
+      CREATE TABLE doc(id INTEGER PRIMARY KEY, path TEXT, sz INT, data BLOB, hash TEXT);
+      CREATE VIEW doc_v AS SELECT id AS rowid, CAST(sqlar_uncompress(data, sz) AS TEXT) AS body FROM doc;
+      CREATE VIRTUAL TABLE ft USING fts5(body, content='doc_v', content_rowid='rowid');
+    SQL
+    FINISH = "INSERT INTO ft(ft) VALUES('rebuild'); INSERT INTO ft(ft) VALUES('optimize'); VACUUM;"
+
+    def self.path(home)
+      File.join(home, NAME)
+    end
+
+    def self.files(home)
+      Dir.glob("{store,projects,stores}/**/*.md", File::FNM_DOTMATCH, base: home).reject { |file| file.include?("/.git/") }.sort
+    end
+
+    def self.build(home)
+      files = files(home)
+      draft = "#{path(home)}.tmp"
+      FileUtils.rm_f(draft)
+      Sqlite.call(draft, [SCHEMA, "BEGIN;", *files.map { |file| insert(home, file) }, "COMMIT;", FINISH].join("\n"))
+      File.rename(draft, path(home))
+      files.size
+    ensure
+      FileUtils.rm_f(draft.to_s)
+    end
+
+    def self.insert(home, file)
+      source = quote(File.join(home, file))
+      "INSERT INTO doc(path, sz, data, hash) VALUES(#{quote(file)}, length(readfile(#{source})), " \
+        "sqlar_compress(readfile(#{source})), lower(hex(sha3(readfile(#{source}), 256))));"
+    end
+
+    def self.search(home, terms, limit:, prefix: "")
+      phrases = terms.map { |term| %("#{term.delete('"')}") }.join(" ")
+      Sqlite.call(path(home), <<~SQL, readonly: true)
+        SELECT doc.id AS id, doc.path AS path, snippet(ft, 0, '[', ']', ' ... ', 12) AS excerpt
+        FROM ft JOIN doc ON doc.id = ft.rowid
+        WHERE ft MATCH #{quote(phrases)} AND doc.path LIKE #{quote("#{prefix}%")}
+        ORDER BY rank LIMIT #{Integer(limit)};
+      SQL
+    end
+
+    def self.quote(text)
+      Sqlite.quote(text)
+    end
+  end
+end

package/scripts/lib/session_git.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require "yaml"
 require_relative "worktree"
 require_relative "scaffold_intent"
@@ -160,7 +161,7 @@ module SessionGit
   def read_project_flow(slug, plastic_home)
     return nil if slug == "global"
 
-    project_yml = File.join(plastic_home, "projects", slug, "project.yml")
+    project_yml = File.join(Plastic::StoreLayout.project_root(plastic_home, slug), "project.yml")
     return nil unless File.exist?(project_yml)
 
     data = begin
@@ -196,7 +197,7 @@ module SessionGit
     resolver ||= lambda { |short_session|
       ActiveDelivery.resolve_by_short_session(
         global_store: store,
-        project_roots: ActiveDelivery.project_roots(File.dirname(store)),
+        project_roots: ActiveDelivery.project_roots(Plastic::StoreLayout.locate(store).first),
         short_session: short_session
       )
     }
@@ -333,7 +334,7 @@ module SessionGit
   # a detached HEAD. Both modes now share exactly one check of each.
   def commit!(cwd:, summary:, day:, session:, plastic_home:, store: nil,
               runner: Worktree::ShellRunner.new, gh_runner: GhRunner.new)
-    effective_store = store || File.join(plastic_home, "store")
+    effective_store = store || Plastic::StoreLayout.global_store(plastic_home)
     repo = resolve_repo(cwd, runner: runner)
     return note("no repo") if repo.nil?
 

package/scripts/lib/sqlite.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Plastic
+  module Sqlite
+    Error = Class.new(StandardError)
+
+    def self.quote(text)
+      "'#{text.gsub("'", "''")}'"
+    end
+
+    def self.call(path, sql, readonly: false)
+      flags = readonly ? ["-readonly"] : []
+      out, err, status = Open3.capture3("sqlite3", "-json", *flags, path, stdin_data: sql)
+      raise Error, err.strip unless status.success?
+
+      out.strip.empty? ? [] : JSON.parse(out)
+    end
+  end
+end

package/scripts/lib/store_discovery.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require_relative "store_layout"
 require_relative "store_provisioning"
 
 # StoreDiscovery: the single source of truth for "what stores exist" (intent 189).
@@ -39,20 +40,20 @@ module StoreDiscovery
     stores = []
     missing = []
 
-    global_store = File.join(plastic_home, "store")
+    global_store = Plastic::StoreLayout.global_store(plastic_home)
     if File.directory?(global_store)
-      stores << { key: "global", slug: "global", root: plastic_home,
-                  store: global_store, index: File.join(plastic_home, "INDEX.md") }
+      global_root = Plastic::StoreLayout.global_root(plastic_home)
+      stores << { key: "global", slug: "global", root: global_root,
+                  store: global_store, index: File.join(global_root, "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?(".") } : []
+    on_disk = Plastic::StoreLayout.project_slugs(plastic_home)
 
     all_slugs = (registered.keys + on_disk).uniq.sort
 
     all_slugs.each do |slug|
-      root = File.join(projects_root, slug)
+      root = Plastic::StoreLayout.project_root(plastic_home, slug)
       store_dir = File.join(root, "store")
       if File.directory?(store_dir)
         stores << { key: "project:#{slug}", slug: slug, root: root,