igniter 0.5.1 → 0.5.2

data/docs/dev/contract-persistence-target-plan.md

@@ -0,0 +1,426 @@
+# Contract Persistence Target Plan
+
+This document captures the accepted direction for persistence as a contract
+capability.
+
+It is a target plan, not a stable public API. Igniter is pre-v1, and the first
+implementation work stays app-local in the Companion showcase until repeated
+pressure justifies a package surface.
+
+## Core Claim
+
+Persistence should be a capability of contracts, not a hand-written store object
+that every application has to rebuild.
+
+A persisted contract should declare:
+
+- the durable shape it owns
+- the API it guarantees
+- the operations it can perform
+- the result and mutation semantics of those operations
+- the adapter or backend requirements underneath
+
+Backends are implementation detail:
+
+- memory
+- files
+- SQLite
+- Postgres
+- Mongo/document
+- Redis/KV
+- custom adapter classes
+
+## Target Surface
+
+The near-term Ruby shape should be readable and record-like:
+
+```ruby
+contract :Reminder do
+  persist key: :id, adapter: :sqlite
+
+  field :id
+  field :title
+  field :due
+  field :status, default: :open
+end
+```
+
+Commands can layer over the declared durable shape:
+
+```ruby
+contract :Reminder do
+  persist key: :id, adapter: :sqlite
+
+  field :id
+  field :title
+  field :due
+  field :status, default: :open
+
+  command :create do
+    validate :title, presence: true
+    append title: title, due: "today", status: :open
+  end
+
+  command :complete do
+    find id
+    update status: :done
+  end
+end
+```
+
+Generated or guaranteed API candidates:
+
+- `save`
+- `find`
+- `update`
+- `delete`
+- `all`
+- `clear`
+- named commands such as `create`, `complete`, `rotate`, `append_signal`
+
+## Graph Semantics
+
+The current Companion experiment uses a graph-facing form:
+
+- a command contract receives operation inputs and current state/read handle
+- the graph computes validation, result, and mutation intent
+- the boundary applies the mutation through the configured adapter
+- output includes receipt/action metadata
+
+This keeps side effects out of compute nodes while still making CRUD and signal
+logic inspectable as graph behavior.
+
+## Relation To Stores
+
+Existing store adapter docs describe execution snapshot stores:
+
+- save and fetch execution snapshots
+- resume pending executions
+- query executions by graph or correlation
+
+Contract persistence is different:
+
+- record/entity persistence
+- workflow/session persistence
+- credential-local pipeline state
+- transactional data emitted or consumed by contracts
+- signals/events that contracts reason over
+
+Both lines may share adapter infrastructure later, but they should not be
+collapsed conceptually.
+
+## Dynamic Authoring To Static Contracts
+
+Dynamic contract authoring is a sandbox path, not the durability boundary.
+Wizard/configurator flows may collect a type shape, preview generated manifests,
+and run local experiments, but accepted app behavior should materialize into
+static contracts before it becomes production shape.
+
+The intended flow is:
+
+1. User or agent drafts a shape dynamically.
+2. The system validates the manifest as record/history/relation/command
+   metadata.
+3. A materializer with explicit capabilities writes static contracts and app
+   bindings.
+4. Git/test/restart capabilities make the change reviewable and recoverable.
+
+This keeps future dynamic UX open while preserving the language path:
+`persist -> Store[T]`, `history -> History[T]`, and relation manifests over
+typed capabilities.
+
+The current Companion proof keeps this as a read-only graph contract:
+`WizardTypeSpec` persists sandbox-authored durable type specs as data,
+`WizardTypeSpecChange` keeps append-only spec lineage,
+`DurableTypeMaterializationContract` accepts the latest spec and returns the
+static record/history/relation plan plus required materializer capabilities,
+`StaticMaterializationParityContract` compares that plan with the static
+manifests and reports drift, and `WizardTypeSpecExportContract` projects dev
+exports with history or prod exports compressed to latest specs only. None of
+these contracts writes files or restarts the app.
+
+## Compatibility Ladder
+
+This plan must stay compatible with the larger `Store[T]` and `History[T]`
+direction. The relationship is a ladder, not competing APIs.
+
+### `persist`
+
+Ruby product surface for app ergonomics.
+
+Best for:
+
+- readable application code
+- fast POC/product iteration
+- hiding backend boilerplate
+- guaranteed app-facing API
+
+Main limit:
+
+- host-language DSL, not a typed persistence algebra by itself
+
+### `Store[T]`
+
+Typed storage capability behind record/entity persistence.
+
+Example future lowering:
+
+```ruby
+store :reminders, Store[Reminder], key: :id, backend: :relational
+```
+
+Adds:
+
+- typed storage manifest
+- adapter-independent API guarantee
+- graph-visible storage capability
+- future index, partition, placement, and verification metadata
+
+### `History[T]`
+
+Append-only temporal specialization.
+
+Examples:
+
+```ruby
+History[TrackerLog]
+History[ReminderEvent]
+History[CredentialReadinessSignal]
+```
+
+Adds:
+
+- immutable append semantics
+- time-range queries
+- replay and projection
+- auditability
+- causality and future bitemporal support
+
+Design rule: `persist` must be sugar that can lower to `Store[T]` for records
+and `History[T]` for events, logs, receipts, and signals.
+
+## Persistence Kinds
+
+### Record Contracts
+
+Examples:
+
+- reminder
+- tracker
+- countdown
+- installed capsule registry entry
+
+Primary API:
+
+- point read/write
+- list/query
+- validation
+- command-specific mutations
+
+### Workflow Contracts
+
+Examples:
+
+- daily routine session
+- onboarding setup state
+- hub install flow
+- agent run checkpoint
+
+Primary API:
+
+- append event
+- transition state
+- resume by id/token
+- emit receipt
+
+### Credential-Local Pipeline State
+
+Examples:
+
+- redacted OpenAI readiness
+- provider capability status
+- live-summary transcript reference
+
+Rules:
+
+- never copy raw secrets into graph outputs
+- expose redacted status facts
+- route work to the credential owner
+
+### Transactional Data And Signals
+
+Examples:
+
+- tracker logs
+- user action facts
+- reminder completion event
+- hub install receipt
+- runtime/provider signal
+
+Primary API:
+
+- append signal
+- query by subject/time/type
+- project into read model
+- feed derived contracts
+
+## Current Implementation Evidence
+
+Companion currently proves the first app-local version:
+
+- `Reminder` declares the target metadata shape with `persist`, `field`,
+  `index`, `scope`, and command metadata
+- `ContractRecordSet` turns that metadata into a generated record API
+- `DailyFocus` uses the same generated record API for date-keyed daily session
+  state
+- `Tracker` declares the same record metadata shape and uses the generated API
+- `Countdown` declares the same record metadata shape and uses the generated API
+- `TrackerLog` declares append-only metadata with `history` and `field`
+- `ContractHistory` turns that metadata into a generated history API
+- Companion persists tracker logs as a first-class top-level history and
+  projects them back into tracker read models for UI compatibility
+- `TrackerReadModelContract` derives dashboard facts from tracker records plus
+  tracker-log history
+- `CountdownReadModelContract` derives days-remaining facts from countdown
+  records for the dashboard
+- `CompanionAction` declares user/runtime receipts as append-only history
+- `ActivityFeedContract` derives dashboard activity facts from action history
+- `CompanionPersistence` collects generated record/history capabilities and
+  read-model projections behind the Store façade
+- `PersistenceReadinessContract` projects persistence registry diagnostics into
+  setup/readiness facts exposed by the app
+- `PersistenceManifestContract` projects registry capabilities and guaranteed
+  operations into a compact setup manifest
+- `ReminderContract` computes create/complete success and refusal
+- `CountdownContract` computes create success/refusal and mutation intent for a
+  user-facing countdown form
+- `TrackerLogContract` computes append-log success and refusal
+- command contracts return result plus normalized persistence operation intent
+- `CompanionStore` applies mutation at the state/backend boundary
+- smoke proves the metadata manifest plus success and refusal paths
+
+This validates the direction without committing a package API yet.
+
+The important split is intentional:
+
+- durable shape: `contract :Reminder do persist... field... end`
+- generated API: `all`, `find`, `save`, `update`, `delete`, `clear`, `scope`,
+  `command`
+- append-only shape: `contract :TrackerLog do history... field... end`
+- history API: `append`, `all`, `where`, `count`
+- projection: UI read models can compose `Store[Tracker]` plus
+  `History[TrackerLog]` through a derived contract
+- receipts: command/user/runtime outcomes can be modeled as `History[Action]`
+- activity feeds: receipt history can project into UI and audit summaries
+- behavior: graph command contracts compute validation, result, receipt, and
+  persistence operation intent
+- operation model: intents use `record_append`, `record_update`,
+  `history_append`, or `none`, plus a target capability
+- boundary: Store/app adapter applies the operation through the registry
+- diagnostics: `/setup/manifest` exposes records, histories, projections, and
+  command operation guarantees without promoting a public API yet
+- query metadata: app-local `index` and `scope` metadata are report-only and
+  preserve the path to typed `Store[T]` capabilities
+- scope execution: app-local generated record APIs may evaluate declared scopes
+  in memory for product pressure without implying database indexes or planners
+- command metadata: app-local generated record APIs may expose command metadata
+  for alignment checks while execution remains in graph command contracts
+
+The package-level design should preserve that split unless repeated Companion
+pressure shows that one surface can stay readable while expressing both.
+
+`TrackerLog` surfaced an important storage-shape distinction: Companion used to
+store logs nested under trackers, but the capability wants to reason over a
+first-class append-only stream. The POC now stores tracker logs top-level and
+projects them into tracker read models for the UI. That is a useful pressure
+signal for `History[T]`: history may project into records, but it should not be
+reduced to mutable record CRUD.
+
+The tracker slice now shows the intended composition: the tracker definition is
+record-like, while tracker observations are append-only. The dashboard can still
+render one tracker card with recent entries, but that card is a projection from
+two storage capabilities rather than a single procedural object.
+
+Daily focus adds a workflow/session-shaped record: it is not a catalog entity,
+but a date-keyed piece of daily state. This confirms `Store[T]` should cover
+small durable app/session records as well as obvious entities.
+
+This makes projections a first-class design concern: record/history capabilities
+own durable data, while derived contracts compute read models and summary facts
+for product surfaces.
+
+Action receipts are also history-shaped. They are not the same domain stream as
+tracker measurements, but they share append-only semantics and query needs:
+activity feeds, audit trails, command receipts, and later workflow replay.
+
+As with tracker logs, receipt history should feed projections rather than leak
+directly into UI code. `ActivityFeedContract` is the Companion proof that even
+small read models can stay graph-owned.
+
+As the app-local shapes repeat, Store should stop manually assembling them.
+`CompanionPersistence` is the current proof of a future registry/factory layer:
+contract manifests plus declarative app storage bindings produce capability
+objects and projection entry points.
+
+The registry also validates bindings: record bindings must point at contracts
+with `persist`, history bindings must point at contracts with `history`, and
+record structs must cover declared fields. This is app-local today, but it
+resembles the boundary guard a package-level persistence compiler should grow.
+
+Companion now also exposes one report-only relation manifest:
+`tracker_logs_by_tracker` names the edge `trackers.id -> tracker_logs.tracker_id`
+with `event_owner` semantics and `enforced: false`. Readiness validates endpoint
+kinds, join fields, projection presence, and the non-enforcement boundary. This
+keeps relations as typed manifest edges first, not ORM associations or database
+foreign keys. `TrackerReadModelContract` also declares the relation in its
+projection manifest inputs, proving the projection edge can be inspectable
+before a dedicated projection DSL exists. The same relation now produces
+per-relation diagnostic health reports through
+`PersistenceRelationHealthContract` for orphan history entries. Warnings are
+structured as relation/kind/endpoint/value payloads and can produce report-only
+review suggestions while keeping readiness `ready`; this is the `warn` phase,
+not relation enforcement or automatic repair. Companion exposes the projection
+directly at `/setup/relation-health` and as JSON at
+`/setup/relation-health.json`.
+
+`PersistenceReadinessContract` turns registry validation into a graph-owned
+diagnostic projection: readiness, counts by capability kind, and a compact
+summary. Companion now exposes that projection through `/setup` next to
+redacted credential status. That suggests package-level persistence should
+expose diagnostics as contracts, not only as thrown setup errors.
+
+Companion also now uses persisted facts to compute a graph-owned Today signal
+and quick action command intent. The UI renders that intent as a small
+executable form, but the decision remains in `DailyPlanContract`;
+`/today/quick-action` recomputes and executes the current command through the
+Store boundary. This is an app-local proof that product affordances can be graph
+outputs without depending on a whole snapshot or leaking Store internals.
+
+## Near-Term Plan
+
+1. Keep persisted-contract experiments app-local in Companion.
+2. Keep `ContractRecordSet` app-local until another entity repeats the same
+   useful CRUD shape.
+3. Keep `ContractHistory` app-local until another signal/log repeats the same
+   useful append-only shape.
+4. Add one more persisted shape only if it tests a new semantic category.
+5. Compare record contracts, command contracts returning mutation intent, and
+   event-log contracts plus projections.
+6. Promote a package experiment only after at least two Companion entities repeat
+   the same useful shape.
+
+## Non-Goals
+
+- no stable public API yet
+- no migration generator
+- no production database abstraction
+- no multi-backend guarantee beyond experiments
+- no implicit secret persistence
+- no igniter-lang syntax promotion
+- no automatic distributed placement
+
+## Related
+
+- [Store Adapters](../guide/store-adapters.md)
+- [Igniter Lang Foundation](../guide/igniter-lang-foundation.md)
+- [Application Showcase Portfolio](../guide/application-showcase-portfolio.md)

data/docs/dev/current-runtime-snapshot.md

@@ -0,0 +1,73 @@
+# Current Runtime Snapshot
+
+This snapshot describes the current public package graph and proof surface.
+
+## Package Graph
+
+- `igniter-contracts`: canonical embedded kernel for contract declaration,
+  compilation, execution, diagnostics, class DSL, and the core Contractable
+  service protocol.
+- `igniter-extensions`: optional packs, operational tooling, domain behavior,
+  language packs such as observable piecewise decisions, numeric scaling, and
+  formulas, differential/shadow utilities, and MCP-facing tool semantics.
+- `igniter-embed`: host integration and registration layer for applications
+  that want Igniter contracts inside an existing runtime, including
+  migration/shadow wrappers over the core Contractable idea.
+- `igniter-application`: contracts-native local application runtime,
+  app-owned environment composition, transfer receipts, and installed-capsule
+  registries.
+- `igniter-ai`: provider-neutral AI execution, request/response envelopes,
+  fake/live/recorded provider modes, and response normalization.
+- `igniter-agents`: minimal agent definitions, runs, turns, traces, tool-call
+  evidence, single-turn assistant execution over `igniter-ai`, and
+  application-level agent DSL wiring.
+- `igniter-hub`: local capsule catalog discovery, transfer bundle metadata,
+  and app-facing install candidate summaries.
+- `igniter-web`: mounted web surfaces over explicit application snapshots.
+- `igniter-cluster`: distributed planning, routing, and mesh execution layer.
+- `igniter-mcp-adapter`: transport-facing adapter for MCP tool catalogs and
+  invocation.
+- `igniter-ledger`: experimental contract-native hot fact engine with immutable
+  facts, time-travel reads, causation, access paths, reactive invalidation,
+  retention/compaction, LedgerServer transport, and package-local docs/specs.
+- `igniter-durable-model`: experimental typed Record/History facade over
+  `igniter-ledger`, used to converge Companion app-local persistence manifests
+  with package-level Store/History facts without making persistence a core API.
+
+Planned rebuilds:
+
+- richer agent memory/context, handoff, human-gate, and contracts-first tool
+  execution semantics.
+- relation auto-wiring from app-local relation manifests into store-side
+  RelationRule remains active pressure, not accepted core semantics.
+
+## Public Proof
+
+Current proof starts from:
+
+- [Application Showcase Portfolio](../guide/application-showcase-portfolio.md)
+- [Igniter Lang Foundation](../guide/igniter-lang-foundation.md)
+- [Examples](../../examples/README.md)
+
+The flagship application set is Lense, Chronicle, Scout, Dispatch, and
+Companion.
+
+## Boundaries
+
+- Lang descriptors and metadata manifests are report-only unless a future
+  runtime semantics track explicitly accepts enforcement.
+- Showcase web surfaces are manual-review/example surfaces, not production
+  server behavior.
+- Legacy, expert, research, and agent-cycle documents are private working
+  material under `playgrounds/docs/`.
+- Public package APIs should graduate only from repeated, low-ceremony shapes
+  proven across examples.
+- `igniter-ledger` and `igniter-durable-model` are package-level pressure surfaces,
+  not umbrella/core guarantees. The Store server hosts durable facts and
+  projections; contract computation stays in the app.
+- Capsule transfer is now agent-aware at the declaration/evidence layer:
+  agents can be carried as capabilities, but transfer does not execute agents.
+- `igniter-hub` is local-only in the first slice. Companion can display and
+  install a local hub capsule through transfer, then record installed state via
+  the `igniter-application` registry, but there is no remote download,
+  signature, or trust policy yet.

data/docs/dev/data-ownership.md

@@ -0,0 +1,29 @@
+# Data Ownership
+
+Use this page when the question is not “which database?” but “who owns this
+state and at which layer?”
+
+## Current Heuristic
+
+- node-local state is normal
+- shared cluster state should be explicit and small
+- read models should be derived
+- external durable systems are deployment choices, not the architectural center
+
+## Layer View
+
+- core stays storage-agnostic
+- app/runtime defaults stay local-first
+- cluster owns replicated metadata and routing state
+- integrations or deployment profiles may add external storage systems
+
+## Ownership Questions
+
+Ask:
+
+1. Which node or layer owns this data?
+2. Is this local state, replicated metadata, or a read model?
+3. Does it really need shared consensus visibility?
+
+Historical persistence references are private working material under
+`playgrounds/docs/`.

data/docs/dev/document-rotation.md

@@ -0,0 +1,51 @@
+# Document Rotation
+
+Use public docs for the current product surface. Use `playgrounds/docs/` for
+full memory: research, expert reports, agent handoffs, old tracks, rejected
+options, and long-form history.
+
+## Public Stays Small
+
+Keep a document public only when it is one of these:
+
+- user-facing guide or how-to
+- package README or API reference
+- current architecture boundary or target plan
+- runnable example documentation
+- recent track summary needed by active contributors
+
+Everything else should be private until it is distilled into accepted public
+shape.
+
+## Track Rotation
+
+Public development tracks keep a short tail, not the whole conversation:
+
+- keep at most three recent active public track summaries
+- when a fourth track appears, move the oldest public track into
+  `playgrounds/docs/dev/tracks/`
+- keep agent comments, raw handoffs, and detailed cycle logs private by default
+- after a track closes, copy only the accepted result into stable public guide,
+  dev, example, or package docs
+
+The public git history remains the recent development trail. The private docs
+keep the full memory.
+
+## Promote And Demote
+
+Promote private material into public docs only after it becomes concrete:
+accepted behavior, public API, package boundary, user workflow, or verification
+surface.
+
+Demote public material when it becomes superseded, duplicated, too verbose for
+its purpose, internal-process oriented, or mostly useful as historical context.
+
+## Rotation Cadence
+
+Run rotation after major track closure, before release readiness passes, and
+whenever public docs start competing with each other. A rotation pass should:
+
+- update or remove public links
+- move private history under `playgrounds/docs/`
+- leave a compact public decision/result when the knowledge is still current
+- run markdown link checks and `git diff --check`

data/docs/dev/embed-target-plan.md

@@ -0,0 +1,51 @@
+# Embed Target Plan
+
+`Embed` is the contracts-first operating mode. It is the foundation for
+`Application` and `Cluster`, not a side feature.
+
+## Owns
+
+- contract DSL and class DSL consumption
+- graph model, compilation, validation, and local execution
+- finalized profiles, explicit packs, and diagnostics hooks
+- host-local registry/discovery, graph cache, reload integration, and named
+  execution for embedded hosts
+
+Typical hosts: Rails apps, jobs, scripts, CLIs, services, and local automation.
+
+## Does Not Own
+
+- application boot lifecycle
+- server/container runtime
+- scheduler orchestration
+- stack composition
+- network routing
+- consensus, replication, or distributed placement
+
+Those belong to `Application` and `Cluster`.
+
+## Package Rule
+
+The embedded package story is:
+
+- `igniter-contracts` for executable graph semantics
+- `igniter-extensions` for optional packs over that kernel
+- no required dependency on app, stack, cluster, Rails, or legacy core
+
+`require "igniter"` may stay as a convenience umbrella, but architecture should
+remain explicit: contracts kernel, packs, profile, environment.
+
+## Authoring Rule
+
+Two authoring forms are equal before any host layer exists:
+
+- block DSL for generated and low-level kernel usage
+- class DSL for human-edited contracts in apps, Rails projects, and examples
+
+`Embed` must consume those forms. It must not redefine the contract language.
+
+## Success
+
+Embed is successful when an existing host can run contracts with explicit packs,
+diagnostics, and local runtime behavior without adopting application hosting,
+stack orchestration, cluster semantics, or legacy/core assumptions.