Igniter

Igniter is a pre-v1 Ruby framework for building contracts-native applications, companions, and agent-aware systems.

At the center is a small contract graph kernel: validated inputs, computations, effects, outputs, diagnostics, and execution plans. Around that kernel Igniter is growing into a platform for:

  • embedding contract behavior into existing applications
  • observing and shadowing legacy services without changing production responses
  • storing immutable facts, histories, receipts, and replayable decisions
  • building companion apps beside existing systems of record
  • exposing operator surfaces, streams, MCP tools, and eventually cluster peers
  • giving AI agents evidence, receipts, and approval boundaries before authority

The short version:

Contracts
  -> Embed migration bridge
  -> Store / Ledger facts and receipts
  -> Ledger Client protocol boundary
  -> Companion typed Record/History facade
  -> Application + Web operator surfaces
  -> Agents / AI / Cluster / Hub runtime lanes

Status

Igniter is pre-v1. There is no backward-compatibility promise and no stable public API guarantee yet. That is intentional: weak shapes should still be replaced quickly while the better architecture is visible.

The project is now large enough to be treated as a framework/platform, but its surface is still being actively shaped by real application pressure. Current proofs are strongest in:

  • contract graph authoring and execution
  • host-local embedding and contractable shadowing
  • Store/Ledger facts, WAL, replay, changefeeds, compaction activity, and read-only protocol surfaces
  • application/web package structure and operator-oriented surfaces
  • early agents, AI, hub, and cluster package lanes

Use package READMEs, runnable examples, and track docs to evaluate current capability. Production-grade guarantees and compatibility policy belong after v1.

Platform Lanes

igniter-contracts

The kernel: DSL authoring, graph compilation, runtime execution, diagnostics, effects, and the core Contractable service protocol used inside contracts.

igniter-embed

The migration bridge for existing applications. It registers host-local contracts and wraps opaque services with contractable observation/shadowing:

legacy primary result
  -> returned unchanged
  -> optional candidate/shadow execution
  -> normalized comparison
  -> observation / divergence receipts

This is the safest first path for Rails and other host apps.

igniter-ledger

The Ledger substrate: immutable facts, Store[T] and History[T] experiments, causation, current/time-travel reads, access paths, WAL durability, changefeed, Ledger Open Protocol, LedgerServer, compaction lifecycle, and intelligent-ledger boundary proofs.

It is still a POC package, but it is no longer just "persistence research"; it is the event memory and receipt substrate for companion systems.

igniter-ledger-client

The protocol-first client boundary for Ledger users. It owns request/response envelopes, transports, errors, and future pooling/retry/backpressure policy without embedding the storage engine.

igniter-companion

Typed application-facing Record / History facade over igniter-ledger. It turns raw facts into ergonomic app objects while applying pressure back onto Store capabilities such as scopes, partitions, receipts, manifests, and typed storage semantics.

igniter-application

Contracts-native application runtime: app manifests, providers, services, credentials, agents, sessions, snapshots, boot/shutdown plans, and embedded host activation paths.

igniter-web

Operator and interaction surfaces: receipt/report views, event streams, dashboards, human approval gates, investigation workspaces, and app-local web mounts. It is not trying to replace a Rails admin UI.

igniter-agents and igniter-ai

Agent and AI runtime lanes: runs, turns, traces, serializable state, provider registration, and the promotion ladder from observe-only to human-approved authority.

igniter-cluster and igniter-hub

Distributed and sync lanes: capability-aware peers, ownership, leases, health, failover, admission/trust, and hub-style synchronization. These should emerge from real partitioned domains rather than "distributed everything".

igniter-mcp-adapter

Transport-facing MCP surface for exposing tools, protocol reads, and operator introspection.

Small Contract Example

require "igniter"

environment = Igniter.with

result = environment.run(inputs: { order_total: 100, country: "UA" }) do
  input :order_total
  input :country

  compute :vat_rate, depends_on: [:country] do |country:|
    country == "UA" ? 0.2 : 0.0
  end

  compute :gross_total, depends_on: %i[order_total vat_rate] do |order_total:, vat_rate:|
    order_total * (1 + vat_rate)
  end

  output :gross_total
end

result.output(:gross_total)
# => 120.0

Companion Direction

Igniter is being shaped by real application pressure such as Spark CRM:

Existing app remains the system of record
  -> Igniter Embed observes/shadows risky services
  -> Igniter Ledger records facts and receipts
  -> Ledger boundaries close semantic decisions
  -> Web/Agents explain, review, and recommend

This is the current strategic pattern: do not rewrite a production app into Igniter. Build an Igniter companion beside it, move event-heavy and explanation-heavy responsibilities behind explicit facts, receipts, boundaries, and approval gates.

What Is Not Promised Yet

  • Stable v1 API compatibility.
  • A production database adapter abstraction.
  • Remote mutating Store operations for compaction/prune/purge.
  • Cluster consensus or deployment guarantees.
  • AI authority without receipts, policies, replay, and human approval paths.

Repository Map

Package Docs

Working Principle

Igniter evolves through a tight loop:

real app pressure
  -> proof-local experiment
  -> receipt-backed package primitive
  -> protocol/read surface
  -> docs compression
  -> next pressure

That loop is why some docs live beside packages, some live in public guide/dev sections, and older long-form research is compressed into playgrounds/docs/ instead of being used as public onboarding.