igniter 0.4.5 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71035dd880de5a8a81bcc14cd0bf1097dbbb03ec9c2a915e36ae821bb3e25d70
-  data.tar.gz: a6bb66b9f865230e09c21e5db140ecf3b6705a934b2a5172f3dd2d6198dd5371
+  metadata.gz: 72a53df8eec907ddc95b8ab3b17890be79b00acebc04a94a92b6426573829f35
+  data.tar.gz: 9facff923baee1ef67e72c194fdbf390f79b516dcf3377ebc69dc74222bc6603
 SHA512:
-  metadata.gz: 0d59ee3a5cab0e01e5f0bdae733eb991296be4ff0ef107b305e1795da1c0de2629a629dbeef18326ca606e142376542eb919470cd66ac1baee7db4210eeccd4c
-  data.tar.gz: 79d4cabcebcfa3b93cb9fd409c1f4173001125f59dde18bb79a21a8021f45877613de5023de0caf6a0400418bfe71541a61ec8a42125d9aab526ddc23be3c211
+  metadata.gz: 000ef1ec945e8d4e2ea392708326927be8f9e8d6f6293b537c5b26f4a37ac5c81d0dec3da4c4b0603f5e1e5d78949f558aaadbbb6e062bb8029d130bfd2e4256
+  data.tar.gz: d79723b7f2a0938fcd70af41af44d4d3057834c366195ae7201ef003e9d36818137e1c8483a2d8ee9c48c517b988a658576d1b604cff22a49a21b32fe96b4ca0

data/README.md

@@ -13,6 +13,10 @@ Igniter is a Ruby gem for expressing business logic as a validated dependency gr
 - runtime auditing, diagnostics reports, and reactive side effects
 - graph and runtime introspection (text, Mermaid)
 - ergonomic DSL helpers: `const`, `lookup`, `map`, `project`, `aggregate`, `guard`, `export`, `expose`, `effect`, `on_success`, `scope`, `namespace`
+- `Igniter::Application` — application scaffold with YAML config, autoloading, scheduler, and `igniter-server new` generator
+- capability-based security: declare executor resource requirements, enforce `Policy` at runtime
+- temporal contracts: reproducible historical execution via an explicit `as_of` time input
+- content-addressed computation: `pure` executors cached by input fingerprint across executions and processes
 
 ## Installation
 
@@ -69,6 +73,10 @@ contract.diagnostics_text     # compact execution summary
 - **Diagnostics**: compact text, Markdown, or structured reports for triage.
 - **Reactive**: subscribe declaratively to runtime events with `effect`, `on_success`, `on_failure`.
 - **Introspection**: render graphs as text or Mermaid; inspect runtime state.
+- **Capabilities**: executors declare what resources they need (`:network`, `:database`, …); `Policy` denies them at runtime.
+- **Temporal contracts**: inject `as_of` time input automatically; replay any historical computation with the original timestamp.
+- **Content addressing**: `pure` executors get a universal cache key — identical inputs return a cached result across executions, processes, and deployments.
+- **Incremental dataflow**: `mode: :incremental` on collection nodes — only added/changed items run, unchanged items reuse cached results, removed items are retracted. O(change) not O(total).
 
 ## Quick Start Recipes
 
@@ -363,6 +371,10 @@ Igniter::Server.start
 **CLI:**
 
 ```bash
+# Generate a new application scaffold
+igniter-server new my_app
+
+# Start a server directly
 igniter-server start --port 4568 --require ./contracts.rb
 ```
 
@@ -448,6 +460,199 @@ end
 
 See [`examples/llm/research_agent.rb`](examples/llm/research_agent.rb), [`examples/llm/tool_use.rb`](examples/llm/tool_use.rb), and [`docs/LLM_V1.md`](docs/LLM_V1.md).
 
+### 12. Igniter::Application
+
+Package contracts, executors, scheduler, and server config into a single coherent entry point:
+
+```bash
+# Scaffold a new application
+igniter-server new my_app
+cd my_app && bundle install && bin/start
+```
+
+```ruby
+require "igniter/application"
+
+class MyApp < Igniter::Application
+  config_file "application.yml"       # optional YAML base config
+
+  configure do |c|
+    c.port  = ENV.fetch("PORT", 4567).to_i
+    c.store = Igniter::Runtime::Stores::MemoryStore.new
+  end
+
+  executors_path "executors/"         # eager-require all executors
+  contracts_path "contracts/"         # eager-require all contracts
+
+  register "OrderContract", OrderContract
+
+  schedule :cleanup, every: "1h" do
+    puts "[cleanup] #{Time.now.strftime("%H:%M")}"
+  end
+
+  schedule :report, every: "1d", at: "09:00" do
+    DailyReportContract.new.resolve_all(date: Date.today)
+  end
+end
+
+MyApp.start       # blocking built-in HTTP server
+# or
+MyApp.rack_app    # Rack app for Puma / Unicorn
+```
+
+**`application.yml`** — base config loaded before the `configure` block (block always wins):
+
+```yaml
+server:
+  port: 4567
+  host: "0.0.0.0"
+  log_format: json    # text (default) or json
+  drain_timeout: 30
+```
+
+**Scheduler interval formats:** `30` (seconds), `"30s"`, `"5m"`, `"2h"`, `"1d"`, `{ hours: 1, minutes: 30 }`
+
+See [`docs/APPLICATION_V1.md`](docs/APPLICATION_V1.md) for the full reference and companion app example.
+
+### 13. Capability-Based Security
+
+Declare what external resources an executor needs, then deny specific capabilities at the
+policy level — without touching the executors themselves:
+
+```ruby
+require "igniter/capabilities"
+
+class DbLookup < Igniter::Executor
+  capabilities :database
+
+  def call(id:)
+    DB.find(id)
+  end
+end
+
+class PureCalc < Igniter::Executor
+  pure  # shorthand for capabilities(:pure)
+
+  def call(x:, y:) = x + y
+end
+
+# Inspect the graph's surface area before deploying
+MyContract.compiled_graph.required_capabilities
+# => { fetch: [:database], total: [:pure] }
+
+# Enforce policy at boot time
+Igniter::Capabilities.policy = Igniter::Capabilities::Policy.new(denied: [:database])
+
+MyContract.new(id: 1).resolve_all
+# => CapabilityViolationError: Node 'fetch' uses denied capabilities: database
+```
+
+See [`docs/CAPABILITIES_V1.md`](docs/CAPABILITIES_V1.md).
+
+### 14. Temporal Contracts
+
+Make time an explicit input so every execution is fully reproducible:
+
+```ruby
+require "igniter/temporal"
+
+class TaxRateContract < Igniter::Contract
+  include Igniter::Temporal
+
+  define do
+    input :country
+    # `as_of` is injected automatically (default: Time.now)
+
+    temporal_compute :rate, depends_on: :country do |country:, as_of:|
+      HISTORICAL_RATES.dig(country, as_of.year) || 0.0
+    end
+
+    output :rate
+  end
+end
+
+# Current rate
+TaxRateContract.new(country: "UA").result.rate
+# => 0.22
+
+# Reproduce the exact 2024 result
+TaxRateContract.new(country: "UA", as_of: Time.new(2024, 1, 1)).result.rate
+# => 0.20
+```
+
+See [`docs/TEMPORAL_V1.md`](docs/TEMPORAL_V1.md).
+
+### 15. Content-Addressed Computation
+
+`pure` executors are cached by a fingerprint of their logic + inputs. Identical computation
+is never repeated — within an execution, across executions, or across processes:
+
+```ruby
+require "igniter/extensions/content_addressing"
+
+class TaxCalculator < Igniter::Executor
+  pure
+  fingerprint "tax_calc_v1"   # bump to invalidate the cache when logic changes
+
+  def call(country:, amount:)
+    TAX_RATES[country] * amount
+  end
+end
+
+# First execution — computes and caches
+InvoiceContract.new(country: "UA", amount: 1000).result.tax  # computed
+
+# Second execution — served from cache; TaxCalculator is never called
+InvoiceContract.new(country: "UA", amount: 1000).result.tax  # cache hit
+
+# Distributed cache (Redis) — shared across all nodes
+Igniter::ContentAddressing.cache = RedisContentCache.new(Redis.new)
+```
+
+See [`docs/CONTENT_ADDRESSING_V1.md`](docs/CONTENT_ADDRESSING_V1.md).
+
+### 16. Incremental Dataflow — O(change) Collection Processing
+
+`mode: :incremental` on a collection node makes the runtime diff the input array on
+every `resolve_all`. Only added/changed items have their child contract re-run;
+unchanged items reuse the cached result; removed items are retracted automatically.
+
+```ruby
+require "igniter/extensions/dataflow"
+
+class SensorPipeline < Igniter::Contract
+  define do
+    input :readings, type: :array
+
+    collection :processed,
+               with: :readings,
+               each: SensorAnalysis,
+               key:  :sensor_id,
+               mode: :incremental,
+               window: { last: 1000 }   # bounded memory
+
+    output :processed
+  end
+end
+
+pipeline = SensorPipeline.new(readings: initial_batch)
+pipeline.resolve_all  # all N items run once
+
+# Push only the delta — no full-array replacement needed
+pipeline.feed_diff(:readings,
+  add:    [{ sensor_id: "new-1", value: 10 }],
+  update: [{ sensor_id: "tmp-2", value: 90 }],
+  remove: ["hum-1"]
+)
+pipeline.resolve_all  # only 2 child contracts run (new-1 + tmp-2)
+
+diff = pipeline.collection_diff(:processed)
+diff.processed_count  # => 2
+diff.unchanged.size   # => N - 2
+```
+
+See [`docs/DATAFLOW_V1.md`](docs/DATAFLOW_V1.md).
+
 ## Examples
 
 | Example | Run | Shows |
@@ -465,6 +670,8 @@ See [`examples/llm/research_agent.rb`](examples/llm/research_agent.rb), [`exampl
 | `server/node1.rb` + `node2.rb` | run both, then curl | Two-node igniter-server with `remote:` DSL |
 | `llm/research_agent.rb` | `ruby examples/llm/research_agent.rb` | Multi-step LLM pipeline with Ollama |
 | `llm/tool_use.rb` | `ruby examples/llm/tool_use.rb` | LLM tool declarations, chained LLM nodes, `Context` |
+| `companion/demo.rb` | `ruby examples/companion/demo.rb` | End-to-end voice AI pipeline using `Igniter::Application` |
+| `dataflow.rb` | `ruby examples/dataflow.rb` | Incremental sensor pipeline: `mode: :incremental`, `feed_diff`, sliding window |
 
 ## Design Docs
 
@@ -478,6 +685,11 @@ See [`examples/llm/research_agent.rb`](examples/llm/research_agent.rb), [`exampl
 - [Store Adapters](docs/STORE_ADAPTERS.md)
 - [igniter-server v1](docs/SERVER_V1.md)
 - [LLM Integration v1](docs/LLM_V1.md)
+- [Application scaffold v1](docs/APPLICATION_V1.md)
+- [Capabilities v1](docs/CAPABILITIES_V1.md)
+- [Temporal Contracts v1](docs/TEMPORAL_V1.md)
+- [Content Addressing v1](docs/CONTENT_ADDRESSING_V1.md)
+- [Incremental Dataflow v1](docs/DATAFLOW_V1.md)
 - [Concepts and Principles](docs/IGNITER_CONCEPTS.md)
 
 ## Development
@@ -500,7 +712,12 @@ Current feature baseline:
 - igniter-server: TCP server, Rack adapter, CLI, `remote:` DSL
 - LLM compute nodes: Ollama, Anthropic, OpenAI providers
 - Rails integration: Railtie, ActiveJob, ActionCable, webhook controller mixin
+- `Igniter::Application`: YAML config, autoloading, scheduler, generator (`igniter-server new`)
 - auditing, diagnostics, reactive subscriptions, graph introspection
+- capability-based security: `capabilities`, `pure`, `Policy`, `CapabilityViolationError`
+- temporal contracts: `include Igniter::Temporal`, `temporal_compute`, `as_of` input, historical reproduction
+- content-addressed computation: `pure`, `fingerprint`, universal `ContentKey`, pluggable `ContentCache`
+- incremental dataflow: `mode: :incremental`, `window:`, `feed_diff`, `collection_diff`, `DiffState`, `IncrementalCollectionResult`
 
 ## License
 

data/docs/APPLICATION_V1.md

@@ -0,0 +1,253 @@
+# Igniter::Application v1
+
+`Igniter::Application` is an optional base class that packages contracts, executors, YAML config, a background scheduler, and server startup into a single coherent entry point. It replaces the raw `Igniter::Server.configure` boilerplate and provides a conventional project layout.
+
+---
+
+## Quick Start
+
+### 1. Generate a scaffold
+
+```bash
+igniter-server new my_app
+cd my_app
+bundle install
+bin/start
+```
+
+This creates:
+
+```
+my_app/
+├── application.rb       ← Application class (entry point)
+├── application.yml      ← base config (port, log_format, etc.)
+├── Gemfile
+├── config.ru            ← Rack entry point for Puma / Unicorn
+├── bin/start            ← convenience start script
+├── contracts/           ← put Contract subclasses here
+└── executors/           ← put Executor subclasses here
+```
+
+### 2. Define your Application
+
+```ruby
+# application.rb
+require "igniter"
+require "igniter/server"
+require "igniter/application"
+
+Dir[File.join(__dir__, "executors/**/*.rb")].sort.each { |f| require f }
+Dir[File.join(__dir__, "contracts/**/*.rb")].sort.each { |f| require f }
+
+class MyApp < Igniter::Application
+  config_file File.join(__dir__, "application.yml")   # optional
+
+  configure do |c|
+    c.port  = ENV.fetch("PORT", 4567).to_i
+    c.store = Igniter::Runtime::Stores::MemoryStore.new
+  end
+
+  register "OrderContract",   OrderContract
+  register "InvoiceContract", InvoiceContract
+
+  schedule :cleanup, every: "1h" do
+    puts "[cleanup] #{Time.now.strftime("%H:%M")}"
+  end
+
+  schedule :daily_report, every: "1d", at: "09:00" do
+    DailyReportContract.new.resolve_all(date: Date.today)
+  end
+end
+
+MyApp.start if $PROGRAM_NAME == __FILE__
+```
+
+### 3. Run
+
+```bash
+# Built-in HTTP server (blocking)
+ruby application.rb
+
+# Rack / Puma
+bundle exec puma config.ru
+```
+
+---
+
+## DSL Reference
+
+### `config_file(path)`
+
+Load a YAML file as the base configuration. Applied **before** the `configure` block — values in the block always win.
+
+```ruby
+config_file File.join(__dir__, "application.yml")
+```
+
+### `configure { |c| ... }`
+
+Block receives an `AppConfig` instance. May be called multiple times; blocks are applied in order.
+
+```ruby
+configure do |c|
+  c.host              = "0.0.0.0"
+  c.port              = 4567
+  c.log_format        = :json          # :text (default) or :json
+  c.drain_timeout     = 30             # seconds for SIGTERM drain
+  c.store             = my_store       # any store adapter
+  c.metrics_collector = Igniter::Metrics::Collector.new
+end
+```
+
+### `executors_path(path)` / `contracts_path(path)`
+
+Eagerly require all `.rb` files under the given directory on startup.
+
+```ruby
+executors_path "executors/"
+contracts_path "contracts/"
+```
+
+### `register(name, contract_class)`
+
+Register a contract for HTTP dispatch.
+
+```ruby
+register "OrderContract", OrderContract
+```
+
+### `schedule(name, every:, at: nil) { ... }`
+
+Define a recurring background job. Starts automatically with `start` / `rack_app`.
+
+```ruby
+schedule :heartbeat, every: "30s" do
+  HealthCheckContract.new.resolve_all
+end
+
+schedule :daily_report, every: "1d", at: "09:00" do
+  DailyReportContract.new.resolve_all(date: Date.today)
+end
+```
+
+**Interval formats:**
+
+| Format | Meaning |
+|--------|---------|
+| `30` | 30 seconds (Integer) |
+| `"30s"` | 30 seconds |
+| `"5m"` | 5 minutes |
+| `"2h"` | 2 hours |
+| `"1d"` | 1 day |
+| `{ hours: 1, minutes: 30 }` | 90 minutes |
+
+`at: "HH:MM"` delays the first run until the next occurrence of that wall-clock time, then repeats with `every:`.
+
+---
+
+## application.yml Reference
+
+```yaml
+server:
+  port: 4567
+  host: "0.0.0.0"
+  log_format: text      # "text" (default) or "json"
+  drain_timeout: 30     # seconds for graceful SIGTERM shutdown
+```
+
+Keys under `server:` map 1-to-1 to `AppConfig` attributes. Values from YAML are applied first; the `configure` block runs afterwards and overrides anything.
+
+ENV variables are not expanded in YAML — read them in the `configure` block:
+
+```ruby
+configure do |c|
+  c.port = ENV.fetch("PORT", 4567).to_i
+end
+```
+
+---
+
+## Lifecycle
+
+### `MyApp.start`
+
+Builds the config, registers contracts, starts background jobs, then starts the built-in pure-Ruby HTTP server (blocking). Registers `at_exit` to stop the scheduler.
+
+### `MyApp.rack_app`
+
+Same as `start` but returns a Rack-compatible application instead of blocking. Use with Puma, Unicorn, or any Rack server:
+
+```ruby
+# config.ru
+require_relative "application"
+run MyApp.rack_app
+```
+
+```bash
+bundle exec puma config.ru -p 4567
+```
+
+### `MyApp.config`
+
+Returns the `AppConfig` instance (populated after the first call to `start` or `rack_app`).
+
+---
+
+## Build Order
+
+1. YAML file loaded → values applied to `AppConfig`
+2. `executors_path` / `contracts_path` directories required
+3. `configure` blocks run in declaration order (override YAML)
+4. `Server::Config` built from `AppConfig`
+5. Contracts registered on the server registry
+6. Scheduler started (one thread per job)
+
+---
+
+## Subclass Isolation
+
+Each `Igniter::Application` subclass gets its own isolated set of registered contracts, scheduled jobs, and configure blocks via the `inherited` hook. Subclasses do not share state:
+
+```ruby
+class AppA < Igniter::Application
+  register "ContractA", ContractA
+end
+
+class AppB < Igniter::Application
+  register "ContractB", ContractB
+end
+# AppA and AppB have completely independent registries
+```
+
+---
+
+## Companion App Example
+
+`examples/companion/` is a full production-style application built with `Igniter::Application`. It implements a distributed voice AI assistant pipeline:
+
+```
+ESP32 microphone → ASR → Intent → Chat (LLM) → TTS → ESP32 speaker
+```
+
+**Single-process demo (mock executors, no hardware):**
+
+```bash
+ruby examples/companion/demo.rb
+```
+
+**Orchestrator node (HP t740, real Ollama):**
+
+```bash
+# Requires: ollama serve (llama3.1:8b pulled)
+bundle exec ruby examples/companion/application.rb
+```
+
+**See also:** [`examples/companion/README.md`](../examples/companion/README.md)
+
+---
+
+## Integration with igniter-server
+
+`Igniter::Application` is a thin wrapper around `Igniter::Server`. The underlying `Server::Config` and `HttpServer` are the same — you can still use `Igniter::Server.configure` directly when you don't need the Application scaffold.
+
+The two approaches are compatible in the same process: `Igniter::Application#start` calls `Igniter::Server::HttpServer.new(config).start` internally.