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

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.

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

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.

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.

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.

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.

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

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.

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

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".

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

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

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.

• 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.

• docs/ — documentation portal
• docs/guide/ — user-facing guide
• docs/concepts/ — mental models and vocabulary
• docs/dev/ — architecture and package boundaries
• examples/ — runnable examples
• packages/ — package list and local package docs
• playgrounds/ — private/local-first experiments and history

• igniter-contracts
• igniter-extensions
• igniter-embed
• igniter-ledger
• igniter-ledger-client
• igniter-companion
• igniter-application
• igniter-web
• igniter-agents
• igniter-ai
• igniter-cluster
• igniter-hub
• igniter-mcp-adapter

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.