Refactor Receipts

Refactor Receipts: the god-join plan from the graph critic, improved in two small steps - with a receipt after each one. Every step shows the smells found, the structure numbers, and the measured wall time, because "I made it better" is a claim and receipts are evidence.

source on github

a real captured run

REFACTOR RECEIPTS (five ingests -> report, 30ms per task)

  before: the god join
    wall 126ms | depth 3 | max fan-in 5 | tasks 7
    critic: god task (5 deps)

  step 1: stage the pairs
    wall 152ms | depth 4 | max fan-in 3 | tasks 9
    critic: no complaints

  step 2: report reads the stages
    wall 123ms | depth 3 | max fan-in 3 | tasks 8
    critic: no complaints

read the receipts honestly: step 1 removed the smell but COST 30ms
(the extra join level) - a receipt you'd never notice without the
measurement. step 2 pays it back by letting the report read the
stages directly. intermediate steps may cost; receipts price them,
and every step was still a shippable state.

source

# frozen_string_literal: true

# Refactor Receipts: the god-join plan from the graph critic, improved
# in two small steps - with a receipt after each one. Every step shows
# the smells found, the structure numbers, and the measured wall time,
# because "I made it better" is a claim and receipts are evidence.
#
#   bundle exec ruby examples/refactor_receipts.rb
#
# Runs offline; each task is 30ms of simulated IO.

require class="s">"bundler/setup"
require class="s">"agentic"

UNIT = 0.03

# Three versions of the same pipeline: five ingests feeding a report
SHAPES = {
  class="s">"before: the god join" => {
    class="s">"join" => %w[ingest_a ingest_b ingest_c ingest_d ingest_e],
    class="s">"report" => %w[join]
  },
  class="s">"step 1: stage the pairs" => {
    class="s">"join_ab" => %w[ingest_a ingest_b],
    class="s">"join_cde" => %w[ingest_c ingest_d ingest_e],
    class="s">"join" => %w[join_ab join_cde],
    class="s">"report" => %w[join]
  },
  class="s">"step 2: report reads the stages" => {
    class="s">"join_ab" => %w[ingest_a ingest_b],
    class="s">"join_cde" => %w[ingest_c ingest_d ingest_e],
    class="s">"report" => %w[join_ab join_cde]
  }
}.freeze

def build(deps)
  orchestrator = Agentic:class="y">:PlanOrchestrator.new(concurrency_limit: 4)
  names = (%w[ingest_a ingest_b ingest_c ingest_d ingest_e] + deps.keys).uniq
  tasks = names.to_h { |n| [n, Agentic:class="y">:Task.new(description: n, agent_spec: {class="s">"name" => n, class="s">"instructions" => class="s">"work"})] }
  names.each do |name|
    orchestrator.add_task(tasks[name], (deps[name] || []).map { |d| tasks.fetch(d) },
      agent: ->(_t) { sleep(UNIT) || class="y">:ok })
  end
  orchestrator
end

# The depth/fan-in walk this example used to hand-roll now ships as
# graph[:stats] - the critique is just thresholds over facts
def critique(graph)
  stats = graph[class="y">:stats]
  smells = []
  graph[class="y">:dependencies].each do |_id, deps|
    smells << class="s">"god task (#{deps.size} deps)" if deps.size >= 4
  end
  smells << class="s">"deep chain (#{stats[class="y">:max_depth]} levels)" if stats[class="y">:max_depth] >= 5
  [smells, stats[class="y">:max_depth], stats[class="y">:max_fan_in]]
end

puts class="s">"REFACTOR RECEIPTS (five ingests -> report, 30ms per task)"
puts

SHAPES.each do |label, deps|
  orchestrator = build(deps)
  smells, depth, fan_in = critique(orchestrator.graph)
  result = orchestrator.execute_plan

  puts class="s">"  #{label}"
  puts format(class="s">"    wall %3dms | depth %d | max fan-in %d | tasks %d",
    result.execution_time * 1000, depth, fan_in, orchestrator.graph[class="y">:tasks].size)
  if smells.empty?
    puts class="s">"    critic: no complaints"
  else
    smells.each { |smell| puts class="s">"    critic: #{smell}" }
  end
  puts
end

puts class="s">"read the receipts honestly: step 1 removed the smell but COST 30ms"
puts class="s">"(the extra join level) - a receipt you'd never notice without the"
puts class="s">"measurement. step 2 pays it back by letting the report read the"
puts class="s">"stages directly. intermediate steps may cost; receipts price them,"
puts class="s">"and every step was still a shippable state."