igniter 0.4.3 → 0.5.0

data/docs/SERVER_V1.md

@@ -66,6 +66,9 @@ Igniter::Server.configure do |c|
   c.host = "0.0.0.0"          # bind address (default: "0.0.0.0")
   c.port = 4567                # TCP port (default: 4567)
   c.store = my_store           # execution store for distributed contracts
+  c.log_format = :text         # :text (default) or :json — structured JSON for Loki/ELK
+  c.drain_timeout = 30         # seconds to drain in-flight requests on SIGTERM (default: 30)
+  c.metrics_collector = Igniter::Metrics::Collector.new  # enable Prometheus metrics
   c.register "Name", MyClass   # register a contract
   c.contracts = {              # bulk registration
     "ContractA" => ContractA,
@@ -145,9 +148,90 @@ Returns `404` if the execution is not found in the configured store.
 
 ---
 
+### `GET /v1/live`
+
+Kubernetes **liveness** probe. Always returns `200 OK`. If this endpoint fails, the pod should be restarted.
+
+**Response:**
+```json
+{ "status": "alive", "pid": 12345 }
+```
+
+---
+
+### `GET /v1/ready`
+
+Kubernetes **readiness** probe. Returns `200` when the server can accept traffic, `503` when it cannot (no contracts registered or store unreachable).
+
+**Response (ready):**
+```json
+{ "status": "ready", "checks": { "store": "ok", "contracts": "ok" } }
+```
+
+**Response (not ready, 503):**
+```json
+{ "status": "not_ready", "checks": { "store": "ok", "contracts": "no_contracts_registered" } }
+```
+
+---
+
+### `GET /v1/metrics`
+
+Prometheus text format metrics (exposition format 0.0.4). Returns `501` if no `metrics_collector` is configured.
+
+**Content-Type:** `text/plain; version=0.0.4; charset=utf-8`
+
+**Metrics exposed:**
+
+| Metric | Type | Labels | Description |
+|--------|------|--------|-------------|
+| `igniter_executions_total` | counter | `graph`, `status` | Contract executions completed |
+| `igniter_execution_duration_seconds` | histogram | `graph` | Execution wall-clock duration |
+| `igniter_http_requests_total` | counter | `method`, `path`, `status` | HTTP requests received |
+| `igniter_http_request_duration_seconds` | histogram | `method`, `path`, `status` | HTTP request processing duration |
+| `igniter_pending_executions` | gauge | `graph` | Executions currently in pending state in the store |
+
+Dynamic path segments are collapsed to avoid high cardinality (e.g. `/v1/contracts/MyContract/execute` → `/v1/contracts/:name/execute`).
+
+**Enable metrics:**
+```ruby
+require "igniter/metrics"
+
+Igniter::Server.configure do |c|
+  c.metrics_collector = Igniter::Metrics::Collector.new
+end
+```
+
+---
+
+### `GET /v1/manifest`
+
+Returns a JSON description of this peer for use by the Igniter Mesh. See [MESH_V1.md](MESH_V1.md).
+
+**Response:**
+```json
+{
+  "peer_name":    "orders-node",
+  "capabilities": ["orders", "inventory"],
+  "contracts":    ["ProcessOrder"],
+  "url":          "http://0.0.0.0:4567"
+}
+```
+
+Configure `peer_name` and `peer_capabilities` on `Igniter::Server`:
+
+```ruby
+Igniter::Server.configure do |c|
+  c.peer_name         = "orders-node"
+  c.peer_capabilities = %i[orders inventory]
+end
+```
+
+---
+
 ### `GET /v1/health`
 
-Health check endpoint.
+General health check (human-readable, not a K8s probe).
 
 **Response:**
 ```json
@@ -212,6 +296,11 @@ an `Igniter::ResolutionError` is raised and propagates like any other node failu
 **Note:** `require "igniter/server"` is required to load `Igniter::Server::Client`.
 Without it, any contract with a `remote:` node will raise at resolution time.
 
+### Mesh routing (capability / pinned)
+
+The `remote:` keyword also supports two mesh routing modes via `capability:` and `pinned_to:`
+instead of a hard-coded `node:` URL. See [MESH_V1.md](MESH_V1.md) for the full reference.
+
 ---
 
 ## HTTP Client
@@ -268,6 +357,116 @@ not at the first HTTP call.
 
 ---
 
+## Kubernetes Deployment
+
+### Deployment manifest
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: igniter-server
+spec:
+  replicas: 3
+  template:
+    spec:
+      terminationGracePeriodSeconds: 60   # must be > drain_timeout
+      containers:
+        - name: igniter
+          image: my-org/igniter-app:latest
+          ports:
+            - containerPort: 4567
+          env:
+            - name: REDIS_URL
+              valueFrom:
+                secretKeyRef: { name: redis-secret, key: url }
+          livenessProbe:
+            httpGet: { path: /v1/live, port: 4567 }
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          readinessProbe:
+            httpGet: { path: /v1/ready, port: 4567 }
+            initialDelaySeconds: 3
+            periodSeconds: 5
+          lifecycle:
+            preStop:
+              exec:
+                command: ["/bin/sh", "-c", "sleep 5"]  # give k8s time to drain
+```
+
+### Server configuration for K8s
+
+```ruby
+require "igniter/server"
+require "igniter/metrics"
+
+Igniter::Server.configure do |c|
+  c.host         = "0.0.0.0"
+  c.port         = 4567
+  c.log_format   = :json          # structured logs → stdout → Loki/CloudWatch
+  c.drain_timeout = 30            # seconds, must be < terminationGracePeriodSeconds
+  c.metrics_collector = Igniter::Metrics::Collector.new
+  c.store        = Igniter::Runtime::Stores::RedisStore.new(
+    redis: Redis.new(url: ENV.fetch("REDIS_URL")),
+    namespace: "igniter:prod"
+  )
+  c.register "MyContract", MyContract
+end
+
+Igniter::Server.start
+```
+
+### Prometheus scraping (prometheus.yml)
+
+```yaml
+scrape_configs:
+  - job_name: igniter
+    static_configs:
+      - targets: ["igniter-service:4567"]
+    metrics_path: /v1/metrics
+```
+
+---
+
+## Structured Logging
+
+igniter-server logs every request and lifecycle event to `$stdout`.
+
+**Text format** (default, `:text`):
+```
+[2026-04-10T12:00:00Z] INFO igniter-server started host=0.0.0.0 port=4567 pid=1
+[2026-04-10T12:00:01Z] INFO POST /v1/contracts/MyContract/execute status=200
+[2026-04-10T12:00:02Z] INFO SIGTERM received — draining drain_timeout=30 pid=1
+```
+
+**JSON format** (`:json`) — one JSON object per line, compatible with Loki, ELK, CloudWatch Logs:
+```json
+{"time":"2026-04-10T12:00:00.123Z","level":"INFO","msg":"igniter-server started","host":"0.0.0.0","port":4567,"pid":1}
+{"time":"2026-04-10T12:00:01.456Z","level":"INFO","msg":"POST /v1/contracts/MyContract/execute","status":200}
+```
+
+Configure via:
+```ruby
+Igniter::Server.configure { |c| c.log_format = :json }
+```
+
+---
+
+## Graceful Shutdown
+
+On `SIGTERM`, the server:
+1. Stops accepting new connections
+2. Waits up to `drain_timeout` seconds for in-flight requests to complete
+3. Exits cleanly
+
+```ruby
+Igniter::Server.configure { |c| c.drain_timeout = 30 }
+```
+
+Set `terminationGracePeriodSeconds` in your Kubernetes Deployment to a value greater than `drain_timeout` (e.g. 60s) to give the server enough time to drain before the pod is force-killed.
+
+---
+
 ## Security
 
 igniter-server ships with no built-in authentication. For production deployments:

data/docs/SKILLS_V1.md

@@ -0,0 +1,213 @@
+# Igniter Skills — V1
+
+## Overview
+
+`Igniter::Skill` is a composable unit of agent capability — the bridge between
+atomic Tools and full autonomous Agents.
+
+| | Tool | Skill | Agent |
+|---|---|---|---|
+| **Purpose** | Single operation | Multi-step task | Long-running process |
+| **LLM inside** | No | Yes (own loop) | Yes (own loop + mailbox) |
+| **Discoverable** | ✓ | ✓ | — |
+| **Capability guard** | ✓ | ✓ | — |
+| **Registered in ToolRegistry** | ✓ | ✓ | — |
+| **Used in `tools` DSL** | ✓ | ✓ | — |
+| **Duration** | ms | s–min | unbounded |
+
+## Key Insight
+
+From the **parent agent's perspective**, a Skill looks identical to a Tool:
+it has a `name`, `description`, parameter schema, and a `call_with_capability_check!`
+interface. The parent LLM cannot tell the difference. This enables **hierarchical agents**
+where each level delegates to the next.
+
+```
+ChatExecutor (parent)
+  tools: [TimeTool, WeatherTool, ResearchSkill, WriteCodeSkill]
+                                      │
+                              ResearchSkill (sub-agent)
+                                tools: [SearchWebTool, ReadUrlTool]
+                                Runs own LLM + tool loop internally
+```
+
+## Defining a Skill
+
+```ruby
+class ResearchSkill < Igniter::Skill
+  # ── Discovery interface (same as Tool) ──
+  description "Research a topic by searching and synthesizing multiple sources"
+
+  param :topic, type: :string, required: true,
+                desc: "The subject to research"
+  param :depth, type: :string, required: false, default: "brief",
+                desc: "brief | detailed"
+
+  requires_capability :network
+
+  # ── Agentic implementation (LLM::Executor DSL) ──
+  provider :anthropic
+  model "claude-sonnet-4-6"
+  system_prompt "You are a research assistant. Be concise and accurate."
+
+  tools SearchWebTool, ReadUrlTool    # skill's own sub-tools
+  max_tool_iterations 8
+
+  def call(topic:, depth: "brief")
+    instruction = depth == "detailed" ? "comprehensive" : "concise 2-3 sentence"
+    complete("Research this and return a #{instruction} summary: #{topic}")
+  end
+end
+```
+
+## Hierarchy Example: ChatExecutor with Skills
+
+```ruby
+class ChatExecutor < Igniter::LLM::Executor
+  provider :ollama
+  model "llama3.1:8b"
+  capabilities :network, :storage     # controls which tools/skills may run
+
+  tools TimeTool,         # instant lookup, no LLM needed
+        WeatherTool,      # instant lookup, no LLM needed
+        SaveNoteTool,     # atomic storage write
+        GetNotesTool,     # atomic storage read
+        ResearchSkill,    # → triggers its own LLM loop when called
+        RemindMeSkill     # → triggers its own LLM loop when called
+
+  max_tool_iterations 6
+
+  def call(message:, conversation_history:, intent:)
+    ctx = build_context(conversation_history, intent)
+    complete(message, context: ctx)
+    # The auto loop transparently selects the right tool or skill per turn.
+    # When ResearchSkill is called, it runs its own sub-loop before returning.
+  end
+end
+```
+
+## Schema Generation
+
+Skills and Tools produce identical schema formats — providers cannot tell them apart.
+
+```ruby
+ResearchSkill.tool_name      # => "research_skill"
+ResearchSkill.to_schema      # => { name:, description:, parameters: {...} }
+ResearchSkill.to_schema(:anthropic)  # => { name:, description:, input_schema: {...} }
+ResearchSkill.to_schema(:openai)     # => { type: "function", function: {...} }
+```
+
+## ToolRegistry
+
+Skills register the same way as Tools:
+
+```ruby
+Igniter::ToolRegistry.register(
+  TimeTool, WeatherTool,    # tools
+  ResearchSkill,            # skill — registered exactly like a tool
+)
+
+Igniter::ToolRegistry.tools_for(capabilities: [:network])
+# => [WeatherTool, ResearchSkill]  (TimeTool has no cap requirement → always included)
+
+Igniter::ToolRegistry.schemas(:anthropic, capabilities: [:network, :storage])
+```
+
+## Capability Guard
+
+Same `call_with_capability_check!` interface as Tool. `CapabilityError` is the same class:
+
+```ruby
+Igniter::Skill::CapabilityError == Igniter::Tool::CapabilityError  # => true
+
+skill = ResearchSkill.new
+skill.call_with_capability_check!(allowed_capabilities: [], topic: "AI")
+# => raises Igniter::Tool::CapabilityError: "research_skill" requires [:network]
+```
+
+## Inheritance
+
+A Skill inherits BOTH the Discoverable DSL AND the LLM::Executor config:
+
+```ruby
+class BaseResearcher < Igniter::Skill
+  provider :anthropic
+  model "claude-sonnet-4-6"
+  requires_capability :network
+end
+
+class DeepResearchSkill < BaseResearcher
+  description "Exhaustive multi-source research with citations"
+  param :topic, type: :string, required: true, desc: "Topic"
+  max_tool_iterations 20
+  # inherits provider, model, requires_capability from BaseResearcher
+end
+```
+
+## Tool::Discoverable
+
+Both `Tool` and `Skill` include `Igniter::Tool::Discoverable`, which provides:
+
+| Method | Description |
+|--------|-------------|
+| `.description(text)` | Set LLM-facing description |
+| `.param(name, type:, ...)` | Declare a parameter |
+| `.requires_capability(*caps)` | Declare required capabilities |
+| `.tool_name` | Auto-derived snake_case name |
+| `.to_schema(provider)` | Generate LLM tool schema |
+| `.tool_params` | Array of declared params |
+| `.required_capabilities` | Array of required caps |
+| `#call_with_capability_check!(...)` | Guard + invoke `#call` |
+
+## When to Use Tool vs Skill vs Agent
+
+**Use a Tool when:**
+- Operation is atomic and deterministic
+- No LLM reasoning needed internally
+- Response comes back in milliseconds
+- Examples: `TimeTool`, `SaveNoteTool`, `WebhookTool`
+
+**Use a Skill when:**
+- Task requires multi-step reasoning or tool orchestration
+- Output benefits from LLM synthesis (not just data retrieval)
+- Task runs in seconds (not unbounded)
+- Parent agent should treat it as a single callable unit
+- Examples: `ResearchSkill`, `RemindMeSkill`, `WriteCodeSkill`, `TranslateDocumentSkill`
+
+**Use an Agent when:**
+- Long-running process with its own lifecycle (mailbox, supervisor)
+- Needs to handle events asynchronously
+- Maintains complex persistent state
+- Examples: monitoring agent, background indexer, event-driven workflow
+
+## Companion Example
+
+The Companion voice assistant uses both tools and skills:
+
+```
+ChatExecutor
+├── TimeTool        [tool]  → "what time is it?"
+├── WeatherTool     [tool]  → "weather in Moscow?"
+├── SaveNoteTool    [tool]  → persist a note
+├── GetNotesTool    [tool]  → recall a note
+├── ResearchSkill   [skill] → "explain how Raft consensus works"
+└── RemindMeSkill   [skill] → "remind me to call Alice tomorrow at 3pm"
+```
+
+Skills in Companion:
+- `ResearchSkill` — keyword search + LLM synthesis (uses `SaveNoteTool` to persist findings)
+- `RemindMeSkill` — NL parsing + structured save (uses `TimeTool` + `SaveNoteTool`)
+  When Consensus cluster is active, notes survive node failures automatically.
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `lib/igniter/skill.rb` | Skill base class |
+| `lib/igniter/tool/discoverable.rb` | Shared DSL (Tool + Skill) |
+| `lib/igniter/tool.rb` | Tool base class |
+| `lib/igniter/tool_registry.rb` | Registry for Tool + Skill |
+| `spec/igniter/skill_spec.rb` | 30+ examples |
+| `examples/companion/skills/research_skill.rb` | ResearchSkill demo |
+| `examples/companion/skills/remind_me_skill.rb` | RemindMeSkill demo |
+| `docs/TOOLS_V1.md` | Tool system docs |

data/docs/STORE_ADAPTERS.md

@@ -7,12 +7,17 @@ Igniter ships with reference execution stores for:
 - ActiveRecord-style persistence
 - Redis-style persistence
 
-All stores implement the same minimal protocol:
-
-- `save(snapshot)`
-- `fetch(execution_id)`
-- `delete(execution_id)`
-- `exist?(execution_id)`
+All stores implement the same protocol:
+
+| Method | Description |
+|--------|-------------|
+| `save(snapshot, correlation: nil, graph: nil)` | Persist a snapshot; build secondary indexes for query |
+| `fetch(execution_id)` | Load a snapshot by ID; raises on missing |
+| `delete(execution_id)` | Remove a snapshot and clean up indexes |
+| `exist?(execution_id)` | Check existence without raising |
+| `find_by_correlation(graph:, correlation:)` | Find execution_id by correlation hash |
+| `list_all(graph: nil)` | All execution_ids, optionally filtered by graph name |
+| `list_pending(graph: nil)` | Execution_ids that have at least one node in `:pending` state |
 
 ## Memory Store
 
@@ -75,22 +80,45 @@ Igniter.execution_store = Igniter::Runtime::Stores::ActiveRecordStore.new(
 
 ## Redis Store
 
-Expected client protocol:
+`RedisStore` maintains secondary indexes so it can answer all query API calls efficiently:
+
+| Key pattern | Redis type | Purpose |
+|-------------|-----------|---------|
+| `{ns}:{execution_id}` | String | Serialized snapshot JSON |
+| `{ns}:all` | Set | All execution IDs |
+| `{ns}:graph:{name}` | Set | Execution IDs for one graph |
+| `{ns}:corr:{graph}` | Hash | `JSON(sorted_correlation)` → execution_id |
 
-- `set(key, value)`
-- `get(key)`
-- `del(key)`
-- `exists?(key)`
+The client must support these Redis commands:
+`set`, `get`, `del`, `exists?`, `sadd`, `srem`, `smembers`, `hset`, `hget`.
 
-Example configuration:
+The standard [`redis` gem](https://github.com/redis/redis-rb) satisfies this interface.
 
 ```ruby
 redis = Redis.new(url: ENV.fetch("REDIS_URL"))
 
 Igniter.execution_store = Igniter::Runtime::Stores::RedisStore.new(
   redis: redis,
-  namespace: "igniter:executions"
+  namespace: "igniter:executions"   # optional, default shown
+)
+```
+
+**Query API:**
+
+```ruby
+store = Igniter::Runtime::Stores::RedisStore.new(redis: redis)
+
+# Find a pending execution by correlation
+execution_id = store.find_by_correlation(
+  graph: "OrderContract",
+  correlation: { order_id: "o-42" }
 )
+
+# List all executions for a graph
+ids = store.list_all(graph: "OrderContract")
+
+# List only pending executions (O(n) scan — acceptable for moderate volumes)
+pending_ids = store.list_pending(graph: "OrderContract")
 ```
 
 ## Worker Flow

data/docs/TEMPORAL_V1.md

@@ -0,0 +1,174 @@
+# Temporal Contracts — v1
+
+Temporal contracts make time an explicit, first-class input so that every execution is
+fully reproducible. By supplying the original timestamp you can replay any historical
+computation and get the identical result — even months later.
+
+## Quick Start
+
+```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 — as_of defaults to Time.now
+TaxRateContract.new(country: "UA").result.rate
+# => 0.22
+
+# Reproduce the 2024 rate exactly
+TaxRateContract.new(country: "UA", as_of: Time.new(2024, 1, 1)).result.rate
+# => 0.20
+```
+
+## How It Works
+
+Including `Igniter::Temporal` overrides `define` to inject one extra input before the
+user block runs:
+
+```ruby
+input :as_of, default: -> { Time.now }
+```
+
+The default is a Proc so it is called freshly at execution time — no stale timestamps
+if the contract class is reused across requests.
+
+`temporal_compute` is a DSL helper that behaves identically to `compute` but automatically
+appends `:as_of` to the `depends_on` list.
+
+## Module Inclusion
+
+```ruby
+class MyContract < Igniter::Contract
+  include Igniter::Temporal
+  # ...
+end
+
+MyContract.temporal?  # => true
+```
+
+Plain contracts without the mixin return `false` from `respond_to?(:temporal?)`.
+
+## `as_of` Input
+
+The injected input behaves like any other input:
+
+- **Default**: `-> { Time.now }` — evaluated at execution time.
+- **Override**: pass `as_of:` when constructing the contract.
+- **Type**: any `Time`-like object is accepted (no type constraint).
+
+```ruby
+# Explicit as_of
+contract = TaxRateContract.new(country: "UA", as_of: Time.new(2024, 6, 1))
+contract.result.rate  # => 0.20 (2024 rate)
+
+# Default as_of — Time.now
+contract = TaxRateContract.new(country: "UA")
+contract.result.rate  # => current rate
+```
+
+## `temporal_compute` DSL
+
+`temporal_compute` is equivalent to:
+
+```ruby
+compute :name, depends_on: [:original_deps..., :as_of], ...
+```
+
+The block receives `as_of:` as a keyword argument alongside the declared dependencies:
+
+```ruby
+temporal_compute :result, depends_on: [:amount, :country] do |amount:, country:, as_of:|
+  # as_of is available automatically
+  rate = RateTable.lookup(country: country, year: as_of.year)
+  amount * rate
+end
+```
+
+You can also mix `temporal_compute` with regular `compute` in the same contract —
+only the nodes that need time-awareness need to use `temporal_compute`.
+
+## Class-Based Executors
+
+For class-based compute nodes in temporal contracts, inherit from
+`Igniter::Temporal::Executor`. This signals intent and ensures `as_of:` is always
+passed as a keyword argument:
+
+```ruby
+class TaxRateExecutor < Igniter::Temporal::Executor
+  def call(country:, as_of:)
+    HISTORICAL_RATES.dig(country, as_of.year) || 0.0
+  end
+end
+
+class TaxRateContract < Igniter::Contract
+  include Igniter::Temporal
+
+  define do
+    input :country
+    temporal_compute :rate, depends_on: :country, call: TaxRateExecutor
+    output :rate
+  end
+end
+```
+
+`Igniter::Temporal::Executor` is a plain subclass of `Igniter::Executor` — it imposes
+no additional behaviour, it is purely documentary.
+
+## Reproducibility Pattern
+
+The key property of temporal contracts: given the same inputs **and** the same `as_of`,
+the output is always identical. Store the `as_of` alongside your results and you can
+replay any historical computation:
+
+```ruby
+# At billing time
+result     = InvoiceContract.new(customer_id: "c1").result
+as_of_used = result.states[:as_of].value   # the Time.now captured during execution
+invoice_id = persist(result, as_of: as_of_used)
+
+# Audit replay 6 months later
+audit = InvoiceContract.new(customer_id: "c1", as_of: as_of_used).result
+audit.total == result.total  # => true
+```
+
+## Combining with Other Extensions
+
+Temporal contracts compose with every other Igniter feature:
+
+```ruby
+require "igniter/temporal"
+require "igniter/extensions/content_addressing"
+
+class TaxCalculator < Igniter::Temporal::Executor
+  pure                          # content-addressed — same country+as_of → cached result
+  fingerprint "tax_v2"
+
+  def call(country:, as_of:)
+    HISTORICAL_RATES.dig(country, as_of.year) || 0.0
+  end
+end
+```
+
+When combined with [content addressing](CONTENT_ADDRESSING_V1.md), the `as_of` value
+is part of the content key, so the cache is invalidated automatically when time changes.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `lib/igniter/temporal.rb` | `Temporal` module, `ClassMethods#define`, `temporal_compute` DSL helper, `Temporal::Executor` base class |
+| `lib/igniter/runtime/input_validator.rb` | Proc defaults called at execution time (`apply_defaults`, `missing_value!`) |
+| `spec/igniter/temporal_spec.rb` | 13 examples |