igniter-ledger 0.5.2

data/examples/intelligent_ledger/availability_deriver.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "time"
+require "date"
+
+module Igniter
+  module Store
+    module IntelligentLedger
+      # Pure computation: derives an AvailabilitySnapshot from base facts.
+      # No store dependency — all IO lives in AvailabilityLedger.
+      #
+      # Template format (value Hash):
+      #   { "weekly_schedule" => { "1" => [["09:00","17:00"]], "3" => [...], ... } }
+      #   Keys are wday strings ("0"=Sun … "6"=Sat); values are arrays of [start_time, end_time].
+      #
+      # Override/reservation value:
+      #   { "start" => <unix float>, "end" => <unix float>, "type" => "block"|"reserve"|"cancel",
+      #     "order_id" => "..." (optional) }
+      class AvailabilityDeriver
+        DERIVATION_NAME    = "availability_snapshot"
+        DERIVATION_VERSION = "1.0"
+
+        # Returns a value Hash suitable for storing as an AvailabilitySnapshotFact.
+        #
+        # base_facts:
+        #   :template            — Fact or nil (weekly schedule)
+        #   :overrides           — Array<Fact> (explicit time blocks)
+        #   :active_reservations — Array<Fact> (reserved order slots)
+        #
+        # horizon_start    — Date (inclusive, start of window)
+        # horizon_days     — Integer (number of days to expand)
+        # source_fact_ids  — Array<String> (all fact IDs that contributed)
+        # source_fact_refs — Array<Hash>   (structured refs: id/store/role; optional)
+        def derive(base_facts:, horizon_start:, horizon_days:, source_fact_ids:, source_fact_refs: nil)
+          template_value    = base_facts[:template]&.value || {}
+          override_facts    = base_facts[:overrides] || []
+          reservation_facts = base_facts[:active_reservations] || []
+
+          # 1. Expand template into intervals over the horizon window
+          available = expand_template(template_value, horizon_start, horizon_days)
+
+          # 2. Collect blocking intervals (overrides + reservations)
+          blocked = collect_blocked(override_facts, reservation_facts)
+
+          # 3. Subtract blocked from available
+          blocked.each { |b| available = subtract_interval(available, b) }
+
+          # 4. Compute total available seconds
+          available_seconds = available.sum { |s, e| e - s }
+
+          refs = (source_fact_refs || []).uniq { |r| r["id"] || r[:id] }
+
+          {
+            "available_slots"        => available.map { |s, e| { "start" => s, "end" => e } },
+            "blocked_intervals"      => blocked.map { |s, e| { "start" => s, "end" => e } },
+            "available_seconds"      => available_seconds.round,
+            "derived_from_fact_ids"  => source_fact_ids.uniq,
+            "derived_from_fact_refs" => refs,
+            "derivation"             => {
+              "name"    => DERIVATION_NAME,
+              "version" => DERIVATION_VERSION
+            },
+            "computed_at"            => Time.now.iso8601(3),
+            "horizon_start"          => horizon_start.iso8601,
+            "horizon_days"           => horizon_days
+          }
+        end
+
+        private
+
+        # Expands the weekly_schedule template into concrete [start_ts, end_ts] pairs
+        # over [horizon_start, horizon_start + horizon_days).
+        # Fact values have symbol keys (native extension normalises all keys to symbols).
+        def expand_template(template_value, horizon_start, horizon_days)
+          schedule = template_value[:weekly_schedule] || {}
+          intervals = []
+
+          horizon_days.times do |offset|
+            day = horizon_start + offset
+            wday_sym   = day.wday.to_s.to_sym
+            wday_slots = schedule[wday_sym] || []
+            wday_slots.each do |slot|
+              start_ts = day_time_to_unix(day, slot[0].to_s)
+              end_ts   = day_time_to_unix(day, slot[1].to_s)
+              intervals << [start_ts, end_ts] if end_ts > start_ts
+            end
+          end
+
+          intervals.sort_by(&:first)
+        end
+
+        # Gathers blocking intervals from override and reservation facts.
+        # Ignores facts whose type is "cancel" (cancellations restore availability).
+        def collect_blocked(override_facts, reservation_facts)
+          blocked = []
+
+          override_facts.each do |f|
+            v = f.value
+            next if v[:type].to_s == "cancel"
+            s = v[:start].to_f
+            e = v[:end].to_f
+            blocked << [s, e] if e > s
+          end
+
+          reservation_facts.each do |f|
+            v = f.value
+            next if v[:type].to_s == "cancel"
+            s = v[:start].to_f
+            e = v[:end].to_f
+            blocked << [s, e] if e > s
+          end
+
+          blocked.sort_by(&:first)
+        end
+
+        # Subtracts one [block_start, block_end] interval from a list of [start, end] pairs.
+        # Handles: no-overlap, full-containment, left-trim, right-trim, split.
+        def subtract_interval(intervals, block)
+          bs, be = block
+          result = []
+          intervals.each do |s, e|
+            if be <= s || bs >= e
+              # no overlap — keep as-is
+              result << [s, e]
+            elsif bs <= s && be >= e
+              # block fully covers slot — drop
+            elsif bs > s && be < e
+              # block splits slot — keep left and right fragments
+              result << [s, bs]
+              result << [be, e]
+            elsif bs <= s
+              # block trims left side
+              result << [be, e] if be < e
+            else
+              # block trims right side
+              result << [s, bs] if bs > s
+            end
+          end
+          result
+        end
+
+        # Converts a Date + "HH:MM" string to a Unix timestamp (Float).
+        def day_time_to_unix(date, time_str)
+          h, m = time_str.split(":").map(&:to_i)
+          Time.utc(date.year, date.month, date.day, h, m, 0).to_f
+        end
+      end
+    end
+  end
+end

data/examples/intelligent_ledger/availability_ledger.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require_relative "availability_deriver"
+
+module Igniter
+  module Store
+    module IntelligentLedger
+      # Store-backed orchestrator for the AvailabilitySnapshot derivation.
+      #
+      # Reads base facts from an IgniterStore, invokes AvailabilityDeriver,
+      # then persists the snapshot fact and a derivation receipt.
+      #
+      # Store layout:
+      #   :availability_templates  — key: technician_id
+      #   :availability_overrides  — key: "technician_id/override_id"
+      #   :order_events            — key: order_id (value has "type": "reserved"/"cancelled")
+      #   :availability_snapshots  — key: "technician_id/horizon_bucket"
+      #   :derivation_receipts     — key: snapshot_fact_id
+      class AvailabilityLedger
+        PRODUCER = { "system" => "availability_ledger", "version" => AvailabilityDeriver::DERIVATION_VERSION }.freeze
+
+        def initialize(store:)
+          @store   = store
+          @deriver = AvailabilityDeriver.new
+        end
+
+        # Writes a template fact for a technician.
+        # weekly_schedule: { "1" => [["09:00","17:00"]], ... }
+        def write_template(technician_id:, weekly_schedule:)
+          @store.write(
+            store: :availability_templates,
+            key:   technician_id.to_s,
+            value: { "weekly_schedule" => weekly_schedule }
+          )
+        end
+
+        # Writes an override fact (block a specific interval).
+        # type: "block" (default) or "cancel"
+        def write_override(technician_id:, override_id:, start_time:, end_time:, type: "block")
+          @store.write(
+            store: :availability_overrides,
+            key:   "#{technician_id}/#{override_id}",
+            value: {
+              "technician_id" => technician_id.to_s,
+              "start"         => start_time.to_f,
+              "end"           => end_time.to_f,
+              "type"          => type
+            }
+          )
+        end
+
+        # Writes an order event fact.
+        # type: "reserved" or "cancelled"
+        def write_order_event(order_id:, technician_id:, start_time:, end_time:, type: "reserved")
+          @store.write(
+            store: :order_events,
+            key:   order_id.to_s,
+            value: {
+              "order_id"      => order_id.to_s,
+              "technician_id" => technician_id.to_s,
+              "start"         => start_time.to_f,
+              "end"           => end_time.to_f,
+              "type"          => type
+            }
+          )
+        end
+
+        # Derives and persists an availability snapshot for a technician over a horizon window.
+        #
+        # horizon_start — Date (inclusive)
+        # horizon_days  — Integer (window length)
+        #
+        # Returns { snapshot_fact:, receipt_fact: }.
+        def compute_snapshot(technician_id:, horizon_start:, horizon_days:)
+          tid = technician_id.to_s
+
+          # --- gather base facts ---
+          template_fact = @store.history(store: :availability_templates, key: tid).last
+
+          override_facts = @store.history(store: :availability_overrides).select do |f|
+            f.key.start_with?("#{tid}/")
+          end
+
+          order_facts = @store.history(store: :order_events).select do |f|
+            f.value[:technician_id].to_s == tid
+          end
+
+          # Active reservations = latest event per order_id where type != "cancelled"
+          active_reservations = active_order_facts(order_facts)
+
+          # Collect source fact IDs and structured refs (id + store + role).
+          source_ids  = []
+          source_refs = []
+
+          if template_fact
+            source_ids  << template_fact.id
+            source_refs << { "id" => template_fact.id, "store" => "availability_templates",
+                             "role" => "template", "key" => template_fact.key }
+          end
+
+          override_facts.each do |f|
+            source_ids  << f.id
+            source_refs << { "id" => f.id, "store" => "availability_overrides",
+                             "role" => "override", "key" => f.key }
+          end
+
+          order_facts.each do |f|
+            source_ids  << f.id
+            source_refs << { "id" => f.id, "store" => "order_events",
+                             "role" => "order_event", "key" => f.key }
+          end
+
+          base_facts = {
+            template:            template_fact,
+            overrides:           override_facts,
+            active_reservations: active_reservations
+          }
+
+          # --- derive ---
+          snapshot_value = @deriver.derive(
+            base_facts:       base_facts,
+            horizon_start:    horizon_start,
+            horizon_days:     horizon_days,
+            source_fact_ids:  source_ids,
+            source_fact_refs: source_refs
+          )
+
+          # --- persist snapshot ---
+          bucket = "#{horizon_start.iso8601}/#{horizon_days}d"
+          snapshot_fact = @store.write(
+            store:    :availability_snapshots,
+            key:      "#{tid}/#{bucket}",
+            value:    snapshot_value,
+            producer: PRODUCER,
+            derivation: snapshot_derivation_metadata(snapshot_value)
+          )
+
+          # --- persist receipt ---
+          receipt_value = {
+            "snapshot_fact_id"   => snapshot_fact.id,
+            "technician_id"      => tid,
+            "horizon_start"      => horizon_start.iso8601,
+            "horizon_days"       => horizon_days,
+            "derivation_name"    => AvailabilityDeriver::DERIVATION_NAME,
+            "derivation_version" => AvailabilityDeriver::DERIVATION_VERSION,
+            "source_fact_ids"    => source_ids.uniq,
+            "source_fact_refs"   => source_refs.uniq { |r| r["id"] },
+            "derived_at"         => Time.now.iso8601(3)
+          }
+
+          receipt_fact = @store.write(
+            store:    :derivation_receipts,
+            key:      snapshot_fact.id,
+            value:    receipt_value,
+            producer: PRODUCER
+          )
+
+          { snapshot_fact: snapshot_fact, receipt_fact: receipt_fact }
+        end
+
+        # Reads the latest snapshot Fact for a technician/horizon combination.
+        # Returns nil if none exists.
+        def read_snapshot(technician_id:, horizon_start:, horizon_days:)
+          bucket = "#{horizon_start.iso8601}/#{horizon_days}d"
+          @store.history(store: :availability_snapshots, key: "#{technician_id}/#{bucket}").last
+        end
+
+        # Reads the derivation receipt Fact for a given snapshot_fact_id.
+        def read_receipt(snapshot_fact_id)
+          @store.history(store: :derivation_receipts, key: snapshot_fact_id).last
+        end
+
+        private
+
+        # From a list of order event facts, return only the facts that represent
+        # the latest state per order_id and are NOT cancelled.
+        def active_order_facts(order_facts)
+          by_order = order_facts.group_by { |f| f.key }
+          by_order.filter_map do |_order_id, facts|
+            latest = facts.max_by(&:transaction_time)
+            latest if latest&.value&.fetch(:type, nil).to_s != "cancelled"
+          end
+        end
+
+        def snapshot_derivation_metadata(snapshot_value)
+          raw = snapshot_value.fetch("derivation")
+          {
+            name:             raw.fetch("name"),
+            version:          raw.fetch("version"),
+            source_fact_ids:  snapshot_value.fetch("derived_from_fact_ids"),
+            source_fact_refs: snapshot_value.fetch("derived_from_fact_refs", [])
+          }
+        end
+      end
+    end
+  end
+end

data/examples/intelligent_ledger/ledger_boundary.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+
+module Igniter
+  module Store
+    module IntelligentLedger
+      # A closed semantic boundary over facts for a technician availability day.
+      #
+      # Lifecycle: open -> closed -> settled -> compacted
+      #
+      # Once closed, result_hash and output_fact_id are immutable. Settlement
+      # materialises useful long-lived memory (summary, metrics, receipt) before
+      # compaction. Compaction requires settlement first, then marks internal
+      # detail as purged while preserving output and result_hash.
+      class LedgerBoundary
+        POLICY_NAME  = "technician_day"
+        RULE_VERSION = "1.0"
+
+        attr_reader :boundary_key, :subject, :status, :result_hash,
+                    :source_fact_ids, :source_fact_refs,
+                    :output_fact_id, :output_value,
+                    :receipt_fact_id, :detail_status, :closed_at,
+                    :compacted_at, :compaction_receipt_id,
+                    :settlement_status, :settlement_receipt_id
+
+        def initialize(subject:, rule_version: RULE_VERSION)
+          @subject       = subject.freeze
+          @rule_version  = rule_version
+          @boundary_key  = build_boundary_key
+          @status        = :open
+          @detail_status = :full
+          @source_fact_ids       = [].freeze
+          @source_fact_refs      = [].freeze
+          @output_fact_id        = nil
+          @output_value          = nil
+          @receipt_fact_id       = nil
+          @result_hash           = nil
+          @closed_at             = nil
+          @compacted_at          = nil
+          @compaction_receipt_id = nil
+          @settlement_status     = :unsettled
+          @settlement_receipt_id = nil
+        end
+
+        def id = @boundary_key
+
+        def open?      = @status == :open
+        def closed?    = @status == :closed || @status == :compacted
+        def compacted? = @status == :compacted
+        def settled?   = @settlement_status == :settled
+
+        # Transitions open -> closed.
+        # output_fact, receipt_fact, result_hash are immutable after this point.
+        # source_fact_refs — structured refs (id/store/role); optional, defaults to [].
+        #   Refs are normalized to string keys for consistency across store round-trips.
+        def close!(output_fact:, receipt_fact:, source_fact_ids:, source_fact_refs: [])
+          raise "boundary already closed" unless @status == :open
+
+          @output_fact_id  = output_fact.id
+          @output_value    = output_fact.value
+          @receipt_fact_id = receipt_fact.id
+          @source_fact_ids = source_fact_ids.uniq.freeze
+          @source_fact_refs = source_fact_refs
+            .map { |r| r.transform_keys(&:to_s) }
+            .uniq { |r| r["id"] }
+            .freeze
+          @result_hash     = compute_result_hash(@output_value, @source_fact_ids)
+          @status          = :closed
+          @closed_at       = Time.now
+        end
+
+        # Transitions settlement_status: :unsettled -> :settled.
+        # Boundary must be closed first. settlement_receipt_id is immutable after this.
+        def settle!(settlement_receipt_id:)
+          raise "boundary must be closed before settlement" unless @status == :closed
+          raise "boundary already settled"                  if @settlement_status == :settled
+
+          @settlement_receipt_id = settlement_receipt_id
+          @settlement_status     = :settled
+        end
+
+        # Transitions closed -> compacted.
+        # Requires settlement first. Internal detail is marked purged;
+        # output, result_hash, and settlement outputs remain intact.
+        def compact!(compaction_receipt_id:)
+          raise "boundary must be closed before compaction"   unless @status == :closed
+          raise "boundary must be settled before compaction"  unless @settlement_status == :settled
+
+          @compaction_receipt_id = compaction_receipt_id
+          @detail_status         = :purged
+          @status                = :compacted
+          @compacted_at          = Time.now
+        end
+
+        # Returns a class-level deterministic key without instantiating a full boundary.
+        def self.key_for(company_id:, technician_id:, date:, rule_version: RULE_VERSION)
+          "#{POLICY_NAME}/company=#{company_id}/technician=#{technician_id}/date=#{date}/version=#{rule_version}"
+        end
+
+        # Rebuilds a LedgerBoundary from persisted store data after a process restart.
+        #
+        # boundary_record      — value hash from :ledger_boundaries (symbol keys from store)
+        # output_value         — value hash recovered from :availability_snapshots, or nil
+        # settlement_receipt_id — fact ID from :ledger_settlement_receipts, nil if unsettled
+        # compaction_receipt_id — fact ID from :ledger_cleanup_receipts, nil if not compacted
+        # compacted_at          — parsed Time from cleanup receipt, nil if not compacted
+        #
+        # Status is authoritative from receipt evidence: if compaction_receipt_id is present
+        # the status is :compacted regardless of what the boundary record says, because the
+        # boundary record in :ledger_boundaries is written at close time and never updated.
+        def self.from_persisted(boundary_record:, output_value: nil,
+                                settlement_receipt_id: nil,
+                                compaction_receipt_id: nil,
+                                compacted_at: nil)
+          obj = allocate
+          obj.__send__(:restore_from_record!,
+                       boundary_record:       boundary_record,
+                       output_value:          output_value,
+                       settlement_receipt_id: settlement_receipt_id,
+                       compaction_receipt_id: compaction_receipt_id,
+                       compacted_at:          compacted_at)
+          obj
+        end
+
+        private
+
+        def restore_from_record!(boundary_record:, output_value:,
+                                 settlement_receipt_id:, compaction_receipt_id:, compacted_at:)
+          @boundary_key = boundary_record[:boundary_key]
+          @rule_version = boundary_record[:rule_version] || RULE_VERSION
+          @subject      = boundary_record[:subject].freeze
+
+          # Status: cleanup receipt evidence overrides the stored boundary status
+          # (boundary record is written at close time and never updated on compact)
+          @status       = compaction_receipt_id ? :compacted : :closed
+          @detail_status = compaction_receipt_id ? :purged : (boundary_record[:detail_status]&.to_sym || :full)
+
+          @output_fact_id  = boundary_record[:output_fact_id]
+          @output_value    = output_value
+          @receipt_fact_id = boundary_record[:receipt_fact_id]
+          @result_hash     = boundary_record[:result_hash]
+          @source_fact_ids  = Array(boundary_record[:source_fact_ids]).freeze
+          @source_fact_refs = Array(boundary_record[:source_fact_refs] || [])
+            .map { |r| r.transform_keys(&:to_s) }
+            .freeze
+
+          @closed_at             = parse_time_safe(boundary_record[:closed_at])
+          @compacted_at          = compacted_at
+          @compaction_receipt_id = compaction_receipt_id
+
+          @settlement_status     = settlement_receipt_id ? :settled : :unsettled
+          @settlement_receipt_id = settlement_receipt_id
+        end
+
+        def parse_time_safe(val)
+          val ? Time.parse(val.to_s) : nil
+        rescue ArgumentError, TypeError
+          nil
+        end
+
+        def build_boundary_key
+          s = @subject
+          self.class.key_for(
+            company_id:    s[:company_id],
+            technician_id: s[:technician_id],
+            date:          s[:date],
+            rule_version:  @rule_version
+          )
+        end
+
+        def compute_result_hash(output_value, source_fact_ids)
+          content = output_value.to_s + source_fact_ids.sort.join(",") + @rule_version
+          Digest::SHA256.hexdigest(content)
+        end
+      end
+    end
+  end
+end

data/examples/store_poc.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "igniter-ledger"
+
+store = Igniter::Store.memory
+
+invalidations = []
+store.register_path(
+  Igniter::Store.access_path(
+    store: :reminders,
+    lookup: :primary_key,
+    scope: nil,
+    filters: nil,
+    cache_ttl: 60,
+    consumers: [->(store_name, key) { invalidations << [store_name, key] }]
+  )
+)
+
+t_before = Process.clock_gettime(Process::CLOCK_REALTIME)
+first = store.write(store: :reminders, key: "r1", value: { title: "Buy milk", status: :open })
+sleep 0.01
+t_mid = Process.clock_gettime(Process::CLOCK_REALTIME)
+second = store.write(store: :reminders, key: "r1", value: { title: "Buy milk", status: :closed })
+
+store.append(history: :reminder_logs, event: { reminder_id: "r1", action: :created, at: t_before })
+store.append(history: :reminder_logs, event: { reminder_id: "r1", action: :closed, at: Time.now.to_f })
+
+wal_path = File.join(Dir.tmpdir, "igniter_ledger_package_poc_#{Process.pid}.jsonl")
+begin
+  file_store = Igniter::Store.open(wal_path)
+  file_store.write(store: :tasks, key: "t1", value: { title: "Package POC", done: false })
+  file_store.write(store: :tasks, key: "t1", value: { title: "Package POC", done: true })
+  replayed = Igniter::Store.open(wal_path)
+
+  puts "access_paths=#{store.schema_graph.paths_for(:reminders).length}"
+  puts "chain_intact=#{second.causation == first.id}"
+  puts "current_status=#{store.read(store: :reminders, key: "r1").fetch(:status)}"
+  puts "status_at_mid=#{store.time_travel(store: :reminders, key: "r1", at: t_mid).fetch(:status)}"
+  puts "invalidations=#{invalidations.inspect}"
+  puts "history_count=#{store.history(store: :reminder_logs).length}"
+  puts "wal_replay_done=#{replayed.read(store: :tasks, key: "t1").fetch(:done)}"
+ensure
+  File.delete(wal_path) if File.exist?(wal_path)
+end

data/exe/igniter-ledger-server

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# igniter-ledger-server — standalone LedgerServer process
+#
+# Usage:
+#   igniter-ledger-server [options]
+#
+# Examples:
+#   igniter-ledger-server
+#   igniter-ledger-server --port 7400 --backend memory
+#   igniter-ledger-server --backend file --path /var/lib/igniter/store.wal --pid-file /run/igniter-ledger.pid
+#   igniter-ledger-server --host 0.0.0.0 --port 7400 --log-level debug
+
+require "optparse"
+require_relative "../lib/igniter-ledger"
+
+opts        = {}
+cf_opts     = {}
+cf_thresholds = {}
+
+parser = OptionParser.new do |o|
+  o.banner = "Usage: igniter-ledger-server [options]"
+  o.separator ""
+  o.separator "Network:"
+  o.on("--host HOST", "Bind host         (default: 127.0.0.1)") { |v| opts[:host] = v }
+  o.on("--port PORT", Integer, "Bind port         (default: 7400)") { |v| opts[:port] = v }
+  o.on("--transport TYPE", "tcp or unix       (default: tcp)") { |v| opts[:transport] = v.to_sym }
+
+  o.separator ""
+  o.separator "Storage:"
+  o.on("--backend BACKEND",              "memory or file    (default: memory)") { |v| opts[:backend] = v.to_sym }
+  o.on("--path PATH",                    "WAL file path     (required for --backend file)") { |v| opts[:path] = v }
+
+  o.separator ""
+  o.separator "Operations:"
+  o.on("--log-level LEVEL",             "debug|info|warn|error (default: info)")        { |v| opts[:log_level] = v.to_sym }
+  o.on("--pid-file PATH",               "Write PID to file on startup")                 { |v| opts[:pid_file] = v }
+  o.on("--drain-timeout SECS", Integer, "Graceful shutdown drain timeout (default: 5)") { |v| opts[:drain_timeout] = v }
+
+  o.separator ""
+  o.separator "Protocol API (envelope dispatch):"
+  o.on("--http-port PORT", Integer, "HTTP adapter port  (default: disabled)") { |v| opts[:http_port] = v }
+  o.on("--tcp-port PORT",  Integer, "TCP adapter port   (default: disabled)") { |v| opts[:tcp_port]  = v }
+
+  o.separator ""
+  o.separator "Changefeed:"
+  o.on("--changefeed-max-size N",               Integer, "Event ring size           (default: 1000)")   { |v| cf_opts[:max_size] = v }
+  o.on("--changefeed-subscriber-queue-size N",  Integer, "Per-subscriber queue size (default: 100)")    { |v| cf_opts[:subscriber_queue_size] = v }
+  o.on("--changefeed-overflow POLICY",                   "drop_oldest|drop_newest  (default: drop_oldest)") { |v| cf_opts[:overflow] = v.to_sym }
+  o.on("--changefeed-close-policy POLICY",               "drain|discard            (default: drain)") { |v| cf_opts[:close_policy] = v.to_sym }
+  o.on("--changefeed-diagnostic-ring-size N", Integer, "Diagnostic ring size      (default: 100)") { |v| cf_opts[:diagnostic_ring_size] = v }
+  o.on("--changefeed-alert-total-queued N", Integer, "Alert: total_queued >= N") { |v| cf_thresholds[:total_queued] = v }
+  o.on("--changefeed-alert-overflow-dropped-total N", Integer, "Alert: overflow_dropped_total >= N") { |v| cf_thresholds[:overflow_dropped_total] = v }
+  o.on("--changefeed-alert-failed-total N", Integer, "Alert: failed_total >= N") { |v| cf_thresholds[:failed_total] = v }
+  o.on("--changefeed-alert-queue-pressure-ratio FLOAT", Float, "Alert: queue_pressure_ratio >= FLOAT") { |v| cf_thresholds[:queue_pressure_ratio] = v }
+
+  o.separator ""
+  o.on("-h", "--help", "Show this help and exit") do
+    puts o
+    exit 0
+  end
+  o.on("-v", "--version", "Show version and exit") do
+    version = begin
+      require "igniter/version"
+      Igniter::VERSION
+    rescue LoadError
+      begin
+        require_relative "../../../lib/igniter/version"
+        Igniter::VERSION
+      rescue LoadError
+        Gem.loaded_specs["igniter-ledger"]&.version&.to_s || "unknown"
+      end
+    end
+    puts "igniter-ledger #{version}"
+    exit 0
+  end
+end
+
+begin
+  parser.parse!
+rescue OptionParser::InvalidOption, OptionParser::InvalidArgument => e
+  warn "Error: #{e.message}"
+  warn parser
+  exit 1
+end
+
+# Validate --backend file requires --path
+if opts[:backend] == :file && opts[:path].nil?
+  warn "Error: --backend file requires --path PATH"
+  exit 1
+end
+
+http_port = opts.delete(:http_port)
+tcp_port  = opts.delete(:tcp_port)
+
+cf_opts[:alert_thresholds] = cf_thresholds unless cf_thresholds.empty?
+opts[:changefeed] = cf_opts unless cf_opts.empty?
+
+config = Igniter::Ledger::ServerConfig.new(**opts)
+
+$stdout.sync = true
+$stderr.sync = true
+
+server = Igniter::Ledger::LedgerServer.new(config: config)
+if http_port || tcp_port
+  server.start_with_adapters(http_port: http_port, tcp_port: tcp_port)
+else
+  server.start_foreground
+end