phronomy 0.6.0 → 0.7.1

data/scripts/check_private_enforcement.rb

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# check_private_enforcement.rb
+#
+# Verifies that every instance method annotated @api private in lib/ is
+# actually non-public at the Ruby level (i.e., NOT in Module#public_instance_methods).
+#
+# Class methods (def self.xxx) are excluded from this check because their
+# visibility is managed separately on the singleton class and rarely causes
+# accidental public exposure to consumers.
+#
+# Usage (run from the phronomy/ repository root):
+#   bundle exec ruby scripts/check_private_enforcement.rb
+#
+# Exit codes:
+#   0 — all @api private instance methods are non-public (or have no Ruby def)
+#   1 — one or more @api private instance methods are exposed as public
+
+require "bundler/setup"
+require_relative "../lib/phronomy"
+
+lib_dir = File.expand_path("../lib", __dir__)
+
+unless File.directory?(lib_dir)
+  warn "ERROR: lib directory not found at #{lib_dir}"
+  exit 1
+end
+
+# Step 1: Collect instance methods annotated @api private via static analysis.
+api_private_entries = []
+
+Dir.glob(File.join(lib_dir, "**", "*.rb")).sort.each do |file|
+  lines = File.readlines(file)
+
+  lines.each_with_index do |line, i|
+    next unless line.match?(/^\s*#\s*@api\s+private\s*$/)
+
+    # Advance past any further comment or blank lines to reach the def.
+    j = i + 1
+    j += 1 while j < lines.size && lines[j].match?(/^\s*(#|$)/)
+    next unless j < lines.size
+
+    # Skip class-level methods — they live on the singleton class, not as
+    # public instance methods accessible to consumers.
+    next if lines[j].match?(/def\s+self\./)
+
+    # Match both plain def and "private def".
+    m = lines[j].match(/^\s*(?:private\s+)?def\s+(\w+[!?=]?)/)
+    next unless m
+
+    rel_path = file.sub("#{lib_dir}/../", "")
+    api_private_entries << {name: m[1].to_sym, file: rel_path, line: j + 1}
+  end
+end
+
+if api_private_entries.empty?
+  puts "No @api private instance methods found."
+  exit 0
+end
+
+# Step 2: Build a map of publicly exposed instance methods across all
+# Phronomy-namespaced modules/classes (own methods only, no inheritance).
+all_phronomy_modules = ObjectSpace.each_object(Module).select do |mod|
+  mod.name&.start_with?("Phronomy")
+end
+
+public_exposure_map = {}
+all_phronomy_modules.each do |mod|
+  mod.public_instance_methods(false).each do |meth|
+    (public_exposure_map[meth] ||= []) << mod.name
+  end
+end
+
+# Step 3: Report violations — @api private methods that are still public.
+errors = []
+
+api_private_entries.each do |entry|
+  exposing_modules = public_exposure_map[entry[:name]]
+  next unless exposing_modules
+
+  errors << "#{entry[:file]}:#{entry[:line]}  def #{entry[:name]}" \
+            "  (annotated @api private but public in: #{exposing_modules.join(", ")})"
+end
+
+if errors.empty?
+  puts "OK: all #{api_private_entries.size} @api private instance methods are non-public."
+  exit 0
+else
+  warn "ERROR: #{errors.size} @api private instance method(s) are exposed as public:"
+  errors.each { |e| warn "  #{e}" }
+  exit 1
+end

data/scripts/check_readme_runnable.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# scripts/check_readme_runnable.rb
+#
+# Extracts ```ruby runnable blocks from README.md and executes each in an
+# isolated subprocess with a fake LLM stub to catch API drift.
+#
+# Any block that raises NoMethodError / ArgumentError / NameError causes a
+# non-zero exit, failing the CI step.
+#
+# Usage (from the phronomy/ root):
+#   bundle exec ruby scripts/check_readme_runnable.rb
+
+require "tempfile"
+require "open3"
+
+REPO_ROOT = File.expand_path("..", __dir__)
+README_PATH = File.join(REPO_ROOT, "README.md")
+
+# Injected before every runnable block.
+# Uses the Gemfile of this project so subprocesses can load phronomy.
+PREAMBLE = <<~RUBY
+  # frozen_string_literal: true
+  # --- CI preamble: stub LLM calls so no real network requests are made ---
+  ENV["BUNDLE_GEMFILE"] ||= "#{File.join(REPO_ROOT, "Gemfile")}"
+  require "bundler/setup"
+  require "phronomy"
+
+  # Patch invoke methods to return canned responses instead of calling the LLM.
+  module Phronomy
+    module Agent
+      class Base
+        def invoke(input = nil, **)
+          {output: "ci-stub-output", messages: []}
+        end
+      end
+
+      class Runner
+        def invoke(input = nil, **)
+          {output: "ci-stub-output", agent: nil, messages: []}
+        end
+      end
+    end
+
+    module Chain
+      class LLMChain
+        def invoke(vars = {})
+          "ci-stub-chain"
+        end
+      end
+    end
+  end
+  # --- end CI preamble ---
+
+RUBY
+
+readme = File.read(README_PATH)
+
+# Match opening fence with 'runnable' annotation: ```ruby runnable
+blocks = readme.scan(/^```ruby runnable\n(.*?)^```/m).map.with_index(1) { |(code), i| [i, code] }
+
+if blocks.empty?
+  puts "No 'ruby runnable' blocks found in README.md."
+  exit 0
+end
+
+puts "Checking #{blocks.size} runnable Ruby block(s) in README.md..."
+
+failures = []
+
+blocks.each do |index, code|
+  Tempfile.create(["readme_runnable_#{index}", ".rb"]) do |f|
+    f.write(PREAMBLE)
+    f.write(code)
+    f.flush
+
+    out, err, status = Open3.capture3(RbConfig.ruby, f.path)
+    combined = (out + err).gsub(f.path, "block ##{index}")
+
+    if status.success?
+      puts "  OK   block ##{index}"
+    else
+      failures << index
+      puts "  FAIL block ##{index}"
+      # Print at most 15 lines of output to keep CI logs readable.
+      puts combined.lines.first(15).join
+    end
+  end
+end
+
+puts
+if failures.empty?
+  puts "All #{blocks.size} runnable block(s) passed."
+  exit 0
+else
+  puts "#{failures.size} block(s) failed: #{failures.join(", ")}"
+  exit 1
+end

data/scripts/run_mutation.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# scripts/run_mutation.sh — Run mutation tests on core Phronomy domain classes.
+#
+# Usage:
+#   bash scripts/run_mutation.sh [SUBJECT_PATTERN]
+#
+# SUBJECT_PATTERN (optional): restrict to a specific subject, e.g. "Phronomy::WorkflowContext"
+# When omitted, all subjects listed in .mutant.yml are tested.
+#
+# Requires mutant-rspec (in Gemfile development group):
+#   gem "mutant-rspec", "~> 0.15.1"
+#
+# Target: mutation score >= 80% for each listed subject.
+# Baseline scores (as of initial run):
+#   Phronomy::WorkflowContext  84.85%
+#   Phronomy::Tool::Base       55.74%
+#
+# Note: mutation testing is slow (~1-5 min per subject). Run locally or via
+# the nightly-mutation GitHub Actions workflow.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+if ! bundle exec mutant --version &>/dev/null; then
+  echo "ERROR: mutant is not available. Run: bundle install"
+  exit 1
+fi
+
+SUBJECT="${1:-}"
+
+echo "=== Phronomy Mutation Test ==="
+echo "Date: $(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+echo "Ruby: $(ruby --version)"
+echo "Mutant: $(bundle exec mutant --version 2>&1 | grep -v warning | head -1)"
+echo ""
+
+if [[ -n "$SUBJECT" ]]; then
+  echo "Subject: $SUBJECT"
+  echo ""
+  bundle exec mutant run -- "$SUBJECT"
+else
+  echo "Subjects: all (see .mutant.yml)"
+  echo ""
+  bundle exec mutant run
+fi

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-21 00:00:00.000000000 Z
+date: 2026-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -17,6 +17,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -24,6 +27,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -31,6 +37,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -38,6 +47,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: state_machines
   requirement: !ruby/object:Gem::Requirement
@@ -60,16 +72,40 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".mutant.yml"
 - ".yardopts"
 - CHANGELOG.md
+- CONTRIBUTING.md
 - README.md
+- RELEASE_CHECKLIST.md
 - Rakefile
+- SECURITY.md
+- benchmark/baseline.json
+- benchmark/bench_agent_invoke.rb
+- benchmark/bench_context_assembler.rb
+- benchmark/bench_regression.rb
+- benchmark/bench_token_estimator.rb
+- benchmark/bench_tool_schema.rb
+- benchmark/bench_vector_store.rb
+- benchmark/bench_workflow.rb
+- benchmark/run_all.rb
+- docs/decisions/001-rubyllm-as-provider-layer.md
+- docs/decisions/002-workflow-context-immutability.md
+- docs/decisions/003-event-loop-singleton.md
+- docs/decisions/004-invoke-timeout-is-not-cancellation.md
+- docs/decisions/005-static-knowledge-class-level-cache.md
+- docs/decisions/006-no-built-in-guardrails.md
+- docs/decisions/007-mcp-is-beta-stability.md
+- docs/decisions/008-orchestrator-uses-os-threads.md
+- docs/decisions/009-state-store-abstraction.md
+- docs/decisions/010-cooperative-first-concurrency.md
 - lib/phronomy.rb
 - lib/phronomy/agent.rb
 - lib/phronomy/agent/base.rb
 - lib/phronomy/agent/before_completion_context.rb
 - lib/phronomy/agent/checkpoint.rb
 - lib/phronomy/agent/concerns/before_completion.rb
+- lib/phronomy/agent/concerns/error_translation.rb
 - lib/phronomy/agent/concerns/guardrailable.rb
 - lib/phronomy/agent/concerns/retryable.rb
 - lib/phronomy/agent/concerns/suspendable.rb
@@ -82,6 +118,11 @@ files:
 - lib/phronomy/agent/shared_state.rb
 - lib/phronomy/agent/suspend_signal.rb
 - lib/phronomy/agent/team_coordinator.rb
+- lib/phronomy/async_queue.rb
+- lib/phronomy/blocking_adapter_pool.rb
+- lib/phronomy/cancellation_scope.rb
+- lib/phronomy/cancellation_token.rb
+- lib/phronomy/concurrency_gate.rb
 - lib/phronomy/configuration.rb
 - lib/phronomy/context.rb
 - lib/phronomy/context/assembler.rb
@@ -91,6 +132,8 @@ files:
 - lib/phronomy/context/token_estimator.rb
 - lib/phronomy/context/trigger_context.rb
 - lib/phronomy/context/trim_context.rb
+- lib/phronomy/deadline.rb
+- lib/phronomy/diagnostics.rb
 - lib/phronomy/embeddings.rb
 - lib/phronomy/embeddings/base.rb
 - lib/phronomy/embeddings/ruby_llm_embeddings.rb
@@ -114,16 +157,22 @@ files:
 - lib/phronomy/guardrail/base.rb
 - lib/phronomy/guardrail/input_guardrail.rb
 - lib/phronomy/guardrail/output_guardrail.rb
+- lib/phronomy/guardrail/prompt_injection_guardrail.rb
+- lib/phronomy/invocation_context.rb
 - lib/phronomy/knowledge_source.rb
 - lib/phronomy/knowledge_source/base.rb
 - lib/phronomy/knowledge_source/entity_knowledge.rb
 - lib/phronomy/knowledge_source/rag_knowledge.rb
 - lib/phronomy/knowledge_source/static_knowledge.rb
+- lib/phronomy/llm_adapter.rb
+- lib/phronomy/llm_adapter/base.rb
+- lib/phronomy/llm_adapter/ruby_llm.rb
 - lib/phronomy/loader.rb
 - lib/phronomy/loader/base.rb
 - lib/phronomy/loader/csv_loader.rb
 - lib/phronomy/loader/markdown_loader.rb
 - lib/phronomy/loader/plain_text_loader.rb
+- lib/phronomy/metrics.rb
 - lib/phronomy/output_parser.rb
 - lib/phronomy/output_parser/base.rb
 - lib/phronomy/output_parser/json_parser.rb
@@ -131,21 +180,48 @@ files:
 - lib/phronomy/prompt_template.rb
 - lib/phronomy/ruby_llm_patches.rb
 - lib/phronomy/runnable.rb
+- lib/phronomy/runtime.rb
+- lib/phronomy/runtime/deterministic_scheduler.rb
+- lib/phronomy/runtime/fake_scheduler.rb
+- lib/phronomy/runtime/gate_registry.rb
+- lib/phronomy/runtime/pool_registry.rb
+- lib/phronomy/runtime/runtime_metrics.rb
+- lib/phronomy/runtime/scheduler.rb
+- lib/phronomy/runtime/scheduler_timer_adapter.rb
+- lib/phronomy/runtime/task_registry.rb
+- lib/phronomy/runtime/thread_scheduler.rb
+- lib/phronomy/runtime/timer_queue.rb
+- lib/phronomy/runtime/timer_service.rb
 - lib/phronomy/splitter.rb
 - lib/phronomy/splitter/base.rb
 - lib/phronomy/splitter/fixed_size_splitter.rb
 - lib/phronomy/splitter/recursive_splitter.rb
+- lib/phronomy/state_store/base.rb
+- lib/phronomy/state_store/in_memory.rb
+- lib/phronomy/task.rb
+- lib/phronomy/task/backend.rb
+- lib/phronomy/task/fiber_backend.rb
+- lib/phronomy/task/immediate_backend.rb
+- lib/phronomy/task/thread_backend.rb
+- lib/phronomy/task_group.rb
+- lib/phronomy/testing.rb
+- lib/phronomy/testing/fake_clock.rb
+- lib/phronomy/testing/fake_scheduler.rb
+- lib/phronomy/testing/scheduler_helpers.rb
 - lib/phronomy/token_usage.rb
 - lib/phronomy/tool.rb
 - lib/phronomy/tool/agent_tool.rb
 - lib/phronomy/tool/base.rb
 - lib/phronomy/tool/mcp_tool.rb
+- lib/phronomy/tool/scope_policy.rb
+- lib/phronomy/tool_executor.rb
 - lib/phronomy/tracing.rb
 - lib/phronomy/tracing/base.rb
 - lib/phronomy/tracing/langfuse_tracer.rb
 - lib/phronomy/tracing/null_tracer.rb
 - lib/phronomy/tracing/open_telemetry_tracer.rb
 - lib/phronomy/vector_store.rb
+- lib/phronomy/vector_store/async_backend.rb
 - lib/phronomy/vector_store/base.rb
 - lib/phronomy/vector_store/in_memory.rb
 - lib/phronomy/vector_store/pgvector.rb
@@ -154,7 +230,12 @@ files:
 - lib/phronomy/workflow.rb
 - lib/phronomy/workflow_context.rb
 - lib/phronomy/workflow_runner.rb
+- scripts/api_snapshot.rb
+- scripts/check_api_annotations.rb
+- scripts/check_private_enforcement.rb
 - scripts/check_readme_ruby.rb
+- scripts/check_readme_runnable.rb
+- scripts/run_mutation.sh
 - sig/phronomy.rbs
 homepage: https://github.com/Raizo-TCS/phronomy
 licenses: