igniter 0.5.0 → 0.5.2

data/docs/guide/core.md

@@ -0,0 +1,43 @@
+# Core
+
+This document currently describes the embedded/kernel role. In the target
+architecture, the clearer name for that role is `Embed`.
+
+Use this section when the thing you care about should still make sense in embedded mode with `require "igniter"`.
+
+## Core Means
+
+- contract DSL
+- graph model and compilation
+- runtime execution and invalidation
+- diagnostics, introspection, provenance-friendly observation
+- dataflow semantics such as branches, collections, async/deferred execution
+
+If a capability stops making sense without hosting, networking, or optional packs, it probably does not belong in core.
+
+## Current First Reads
+
+- [Guide](../guide/README.md)
+- [Guide: API And Runtime](../guide/api-and-runtime.md)
+- [Guide: Core Runtime Features](../guide/core-runtime-features.md)
+- [Dev: Embed Target Plan](../dev/embed-target-plan.md)
+- [Igniter Concepts](../concepts/igniter.md)
+- [Dev: Architecture](../dev/architecture.md)
+
+## Supporting Reference
+
+- [Guide: Core Runtime Features](../guide/core-runtime-features.md)
+
+## When To Leave Core
+
+- Move to [App](./app.md) when you need app runtime/profile concerns.
+- Move to [Cluster](./cluster.md) when you need networking, mesh, routing,
+  replication, or resilience.
+- Move to [`igniter-extensions`](../../packages/igniter-extensions/README.md)
+  when you need optional packs.
+
+Current design direction:
+
+- treat this layer as the canonical embedded/contracts-first operating mode
+- do not let it absorb application or cluster concerns by default
+- for the target model, follow the [Embed Target Plan](../dev/embed-target-plan.md)

data/docs/guide/credentials.md

@@ -0,0 +1,51 @@
+# Credentials
+
+Use credentials when an Igniter application needs secrets such as API keys but
+must still boot cleanly without them.
+
+## Current Shape
+
+Credentials live in `igniter-application` as app runtime configuration. The
+first supported source is an environment variable:
+
+```ruby
+environment = Igniter::Application.build_kernel
+                                  .credential(
+                                    :openai_api_key,
+                                    env: "OPENAI_API_KEY",
+                                    required: false
+                                  )
+                                  .then { |kernel| Igniter::Application::Environment.new(profile: kernel.finalize) }
+```
+
+Application code can ask whether live mode is available:
+
+```ruby
+if environment.credentials.configured?(:openai_api_key)
+  api_key = environment.credentials.fetch(:openai_api_key)
+else
+  # show setup state or run offline mode
+end
+```
+
+## Rules
+
+- Missing optional credentials should produce setup state, not a crash.
+- Missing required credentials raise `MissingCredentialError` when fetched.
+- `profile.to_h`, manifests, snapshots, reports, and logs must not include
+  secret values.
+- Smoke tests should stay offline and deterministic by default.
+- Live provider calls should be opt-in through configured credentials.
+
+## Ready-To-Go App Pattern
+
+For live LLM applications:
+
+- declare `:openai_api_key` against `OPENAI_API_KEY`
+- boot without the key
+- show a visible setup message when the key is missing
+- switch to live mode when the key exists
+- keep offline smoke paths independent from the live provider
+
+This keeps examples runnable for everyone while making real API usage one
+configuration step away.

data/docs/guide/deployment-modes.md

@@ -0,0 +1,63 @@
+# Deployment Modes
+
+Igniter has three current operating modes. The same contract can often move
+between them while the surrounding runtime grows.
+
+## 1. Embedded
+
+Use this when Igniter runs inside an existing host such as Rails, a job, a CLI,
+or a service.
+
+```ruby
+require "igniter"
+```
+
+Add optional packs explicitly through package entrypoints such as
+`igniter-extensions` or host integration through `igniter-embed`.
+
+Choose embedded mode when contracts are called directly and you do not need app
+hosting, web mounting, or distributed execution.
+
+## 2. Application
+
+Use this when Igniter becomes the local runtime shape of an app.
+
+Current package:
+
+```ruby
+require "igniter-application"
+```
+
+Use this mode for app profiles, providers, services, capsules, local lifecycle,
+transfer review, activation review, and app-owned session state.
+
+## 3. Cluster
+
+Use this when the network becomes part of execution.
+
+Current package:
+
+```ruby
+require "igniter-cluster"
+```
+
+Use this mode for capability routing, peer topology, placement, ownership,
+health, failover, remediation, and distributed diagnostics.
+
+## Web Is A Surface
+
+`igniter-web` can be used with application mode, but web rendering is not the
+same thing as app hosting. Keep screens, routes, components, and browser
+surfaces web-owned.
+
+## Pre-v1 Note
+
+Older entrypoint language belongs to private historical context unless a package
+README explicitly documents it as current.
+
+## See Also
+
+- [Getting Started](./getting-started.md)
+- [Configuration](./configuration.md)
+- [App](./app.md)
+- [Cluster](./cluster.md)

data/docs/guide/distributed-workflows.md

@@ -0,0 +1,21 @@
+# Distributed Workflows
+
+Use this page when a contract is no longer just in-process computation and must
+wait for or react to signals that may arrive later or on another node.
+
+## Current Mental Model
+
+Distributed workflow concerns belong above the embedded kernel:
+
+- the contract graph stays explicit
+- correlation keys matter more than process memory
+- waiting on external signals should be visible in workflow state
+- transport stays outside the workflow model
+
+## Current Reading Path
+
+- [Cluster](./cluster.md)
+- [Guide: Deployment Modes](./deployment-modes.md)
+
+Historical distributed-workflow references are private working material under
+`playgrounds/docs/`.

data/docs/guide/getting-started.md

@@ -0,0 +1,49 @@
+# Getting Started
+
+This is the shortest user-facing path into Igniter.
+
+## 1. Start With The Core Idea
+
+Read:
+
+- [Top-level README](../../README.md)
+- [Igniter Concepts](../concepts/igniter.md)
+- [Core](./core.md)
+
+## 2. Run Something Real
+
+Use:
+
+- [Examples](../../examples/README.md)
+- [Application Showcase Portfolio](./application-showcase-portfolio.md)
+- [Interactive App Structure](./interactive-app-structure.md)
+
+## 3. Pick The Runtime Shape
+
+- Stay in [Core](./core.md) if you only need embedded contracts and execution.
+- Move to [App](./app.md) if Igniter becomes the runtime of an app.
+- Move to [Cluster](./cluster.md) if execution becomes distributed.
+- Add [Extensions](../../packages/igniter-extensions/README.md) only when
+  optional capabilities are needed.
+
+Current architecture note:
+
+- Igniter is pre-v1 and does not promise backward compatibility yet
+- `Core` here really means the embedded/contracts-first operating mode
+- `App` builds on top of that embedded mode
+- `Cluster` builds on top of embedded/application runtime
+
+## 4. Scaffold When You Want The Standard Shape
+
+Read:
+
+- [CLI](./cli.md)
+- [Application Capsules](./application-capsules.md)
+
+Then try:
+
+```bash
+bin/igniter-stack new my_app
+bin/igniter-stack new my_hub --profile dashboard
+bin/igniter-stack new mesh_lab --profile cluster
+```

data/docs/guide/how-tos.md

@@ -0,0 +1,33 @@
+# How-Tos
+
+Use this index for task-oriented documentation rather than architecture-first
+reading.
+
+## Build An App
+
+- [App](./app.md)
+- [CLI](./cli.md)
+- [Application Showcase Portfolio](./application-showcase-portfolio.md)
+- [Interactive App Structure](./interactive-app-structure.md)
+
+## Build A Dashboard Or Human UI
+
+- [Application Showcase Portfolio](./application-showcase-portfolio.md)
+- [Interactive App Structure](./interactive-app-structure.md)
+- [`packages/igniter-web/README.md`](../../packages/igniter-web/README.md)
+
+## Add Rails Integration
+
+- [`packages/igniter-embed/README.md`](../../packages/igniter-embed/README.md)
+- [App](./app.md)
+- [Integrations](./integrations.md)
+
+## Move To Distributed Execution
+
+- [Cluster](./cluster.md)
+- [Distributed Workflows](./distributed-workflows.md)
+
+## Add Optional Capability Packs
+
+- [AI And Tool Surfaces](./ai-and-tools.md)
+- [`packages/igniter-extensions/README.md`](../../packages/igniter-extensions/README.md)

data/docs/guide/igniter-lang-foundation.md

@@ -0,0 +1,133 @@
+# Igniter Lang Foundation
+
+Igniter Lang is currently an additive contracts-facing foundation, not a
+separate production language runtime.
+
+Use it when you want a small reference surface for:
+
+- loading the Lang namespace with `require "igniter/lang"`
+- compiling and executing through the current contracts runtime
+- attaching definition-time descriptors such as `History`, `BiHistory`,
+  `OLAPPoint`, and `Forecast`
+- inspecting a read-only `VerificationReport`
+- seeing declared metadata in a report-only `MetadataManifest`
+
+## Quick Start
+
+Run the compact example:
+
+```bash
+ruby examples/contracts/lang_foundation.rb
+```
+
+For the accepted evaluator proof path, see
+[Getting Started](./getting-started.md).
+
+Minimal usage:
+
+```ruby
+require "igniter/lang"
+
+backend = Igniter::Lang.ruby_backend
+history_type = Igniter::Lang::History[Numeric]
+
+compiled = backend.compile do
+  input :price_history, type: history_type
+
+  compute :latest_price,
+          depends_on: [:price_history],
+          return_type: Numeric,
+          deadline: 50,
+          wcet: 20 do |price_history:|
+    price_history.fetch(:latest)
+  end
+
+  output :latest_price
+end
+
+result = backend.execute(compiled, inputs: { price_history: { latest: 120.0 } })
+report = backend.verify(compiled)
+
+result.output(:latest_price)
+report.metadata_manifest.to_h
+```
+
+## Ruby Backend Wrapper
+
+`Igniter::Lang.ruby_backend` returns `Igniter::Lang::Backends::Ruby`, a thin
+wrapper over the existing `Igniter::Contracts` compile, execute, diagnose, and
+verify surfaces.
+
+It does not introduce a new compiler, runtime, scheduler, parser, or AST. The
+compiled artifact is still a contracts artifact, and execution behavior stays
+the same as ordinary contracts execution.
+
+## Descriptors
+
+Descriptors are immutable definition-time metadata objects:
+
+```ruby
+Igniter::Lang::History[Numeric]
+Igniter::Lang::BiHistory[String]
+Igniter::Lang::OLAPPoint[Numeric, { region: String }]
+Igniter::Lang::Forecast[Float]
+```
+
+They can be attached to operation metadata, usually with `type:`. Today they are
+inspectable declarations. They are not physical unit checks, storage adapters,
+OLAP runtime handlers, temporal rules, or inferred type enforcement.
+
+## Verification Reports
+
+`backend.verify(...)` returns a read-only `Igniter::Lang::VerificationReport`.
+`ok?` follows current compilation findings only.
+
+The report exposes:
+
+- `descriptors`
+- `findings`
+- `metadata_manifest`
+- `to_h`
+
+## Metadata Manifest
+
+`Igniter::Lang::MetadataManifest` reports metadata that was already declared on
+operations:
+
+- `type:` descriptors
+- `return_type:`
+- `deadline:`
+- `wcet:`
+
+Manifest data is declared, not enforced. Requirement-like entries include
+`enforced: false`, and manifest semantics include:
+
+```ruby
+{
+  report_only: true,
+  runtime_enforced: false
+}
+```
+
+This means `return_type`, `deadline`, and `wcet` are visible in reports, but
+they do not create runtime checks, warnings, findings, deadline monitoring, or
+execution-result changes.
+
+## Deferred
+
+These remain future/research phases:
+
+- standalone grammar, parser, AST, and `.il` files
+- Rust backend and certified exports
+- store DSL or Lang metadata builder
+- contract persistence lowering to `Store[T]` / `History[T]`
+- OLAP, time-machine, and temporal-rule runtime behavior
+- physical unit algebra enforcement
+- invariant metadata integration
+- deadline/WCET runtime monitoring, warnings, or findings
+
+## Related
+
+- [Getting Started](./getting-started.md)
+- [Contract Class DSL](./contract-class-dsl.md)
+- [Contract Persistence Target Plan](../dev/contract-persistence-target-plan.md)

data/docs/guide/integrations.md

@@ -0,0 +1,47 @@
+# Integrations
+
+Use this page for environment-specific surfaces that adapt Igniter into a host
+framework or UI/runtime package.
+
+## Current Integration Surfaces
+
+- `require "igniter/plugins/rails"` for Rails integration
+- `require "igniter-web"` for current human-authored web surfaces
+- schema-driven rendering remains a guide-level authoring direction, not a
+  current package entrypoint in this repository
+
+## Rails Integration
+
+Use `require "igniter/plugins/rails"` when Rails is the host application and
+Igniter is embedded inside it.
+
+That entrypoint is intentionally narrow:
+
+- it loads the embedded Igniter kernel plus Rails adapters
+- it does not silently pull application hosting, web rendering, or cluster
+  coordination
+- it is the canonical public surface; `require "igniter/rails"` is not
+
+Reach for it when you want controllers, jobs, or channels to call contracts
+without promoting the whole app into a larger Igniter hosting profile.
+
+## Practical Split
+
+Use:
+
+- runtime layers for execution/hosting concerns
+- extension packs for optional shared capabilities
+- integrations for framework or environment adaptation
+
+For Rails specifically:
+
+- embedded Rails usage stays in integrations
+- app/server/cluster remain separate runtime choices
+- crossing into those layers should be explicit in code and docs
+
+## Current Reading Path
+
+- [App](./app.md)
+- [`packages/igniter-embed/README.md`](../../packages/igniter-embed/README.md)
+- [`packages/igniter-web/README.md`](../../packages/igniter-web/README.md)
+- [`packages/igniter-extensions/README.md`](../../packages/igniter-extensions/README.md)

data/docs/guide/interactive-app-structure.md

@@ -0,0 +1,91 @@
+# Interactive App Structure
+
+Use this guide for small real applications that combine `igniter-application`
+and `igniter-web` without inventing a public framework API.
+
+This is a copyable convention, not a compatibility contract.
+
+## Current Examples
+
+- `examples/application/interactive_operator/`
+- `examples/application/operator_signal_inbox/`
+- `examples/application/lense/`
+- `examples/application/chronicle/`
+- `examples/application/scout/`
+- `examples/application/dispatch/`
+
+Run the richer showcases:
+
+```bash
+ruby examples/application/lense_poc.rb
+ruby examples/application/chronicle_poc.rb
+ruby examples/application/scout_poc.rb
+ruby examples/application/dispatch_poc.rb
+```
+
+Add `server` for manual browser review. Server mode is example scaffolding, not
+production server behavior.
+
+## App Shape
+
+- `app.rb` is the composition boundary.
+- `contracts/` owns deterministic business graphs.
+- `services/` owns loading, mutable state, commands, and snapshots.
+- `reports/` owns receipt/report artifacts when the workflow has evidence.
+- `web/` owns the mounted Arbre surface.
+- the launcher script owns smoke and optional server mode.
+
+Keep domain names, command results, snapshot fields, feedback codes, markers,
+routes, receipts, thresholds, and readiness rules local until repeated apps
+prove a package API is worth extracting.
+
+## Runtime Loop
+
+A serious one-process showcase should have:
+
+- app-local services that load inputs and own session state
+- one contracts-native graph for core analysis/readiness/payload
+- command routes that return app-local success/refusal results
+- deterministic action facts recorded at command boundaries
+- one detached snapshot shared by Web rendering, `/events`, and smoke
+- one receipt/report artifact when the workflow reaches a useful checkpoint
+- explicit mutation-boundary proof
+
+Do not imply hidden LLM calls, external connectors, schedulers, databases,
+auth, live transport, production hosting, or cluster placement in the first
+slice.
+
+## Web Surface
+
+Use one mounted web surface:
+
+- mount through `Igniter::Web.mount` and app-local `mount_web`
+- read state through `MountContext`
+- render from one app-owned snapshot
+- keep command routes in `app.rb`
+- expose stable app-local `data-` markers for smoke and manual review
+- keep `/events` on the same snapshot shape as the visible surface
+- add `/report` or `/receipt` only when the app owns a stable artifact
+
+Marker vocabulary is local. Do not extract a UI kit, marker DSL, route DSL, or
+`interactive_app` facade until repetition makes local readability worse.
+
+## Proof Checklist
+
+The smoke path should prove:
+
+- initial HTML render and top-level surface marker
+- one successful command path
+- one refusal path when the app has one
+- feedback marker and feedback code
+- domain counters/records through app-local `data-` markers
+- recent activity from the same snapshot
+- `/events` parity
+- receipt/report validity when present
+- no unintended fixture or target mutation
+
+Manual browser review should confirm the same seams through the printed local
+URL.
+
+For the showcase map, see
+[Application Showcase Portfolio](./application-showcase-portfolio.md).