igniter 0.5.1 → 0.5.2

data/docs/research/contract-persistence-landing-zone.md

@@ -0,0 +1,126 @@
+# Contract Persistence Landing Zone
+
+Status date: 2026-04-29.
+Scope: research placement decision. Not a package commitment or public API.
+
+## Claim
+
+Contract persistence now deserves a named landing path, but not an immediate
+package split.
+
+The Companion proof is no longer just CRUD convenience. It shows a recursive
+system shape: contracts declare durable capabilities, inspect their own
+infrastructure, produce materializer review packets, lower approvals into
+history append intents, and expose audit read models for the process that may
+later materialize more contracts.
+
+That fractal signal is strong evidence for the direction. It is still extraction
+pressure, not an API-promotion trigger.
+
+## Decision
+
+Keep the next iteration app-local in Companion.
+
+When extraction starts, split by responsibility:
+
+- `igniter-extensions`: optional contract vocabulary and report-only
+  descriptors over `igniter-contracts`
+- `igniter-application`: host/runtime binding, adapters, setup/readiness
+  surfaces, explicit mutation boundaries, materializer review flows
+- future `igniter-persistence`: stable durable capability package after repeated
+  app pressure and a smaller adapter/manifest contract
+
+Do not create `igniter-data` yet. The name is too broad: it can mean dataflow,
+analytics, datasets, ETL, tables, events, or persistence. The sharper future
+name is `igniter-persistence`, because the capability is durable `Store[T]`,
+append-only `History[T]`, typed relations, commands, materialization, and audit.
+
+Do not put this in `igniter-contracts` now. The kernel should stay
+host-agnostic; persistence remains optional vocabulary and app-boundary
+behavior until the lowerings are clear.
+
+## Landing Map
+
+`igniter-extensions` owns:
+
+- `persist` / `history` as optional Ruby product sugar
+- future `Store[T]` / `History[T]` / `Relation[...]` descriptors
+- field/index/scope/command metadata descriptors
+- relation manifest shape
+- operation-intent metadata shape
+- report-only validation and diagnostics
+
+`igniter-application` owns:
+
+- capability registry/factory
+- app-local record/history bindings
+- adapter wiring and backend choice
+- explicit write boundary
+- setup/readiness/materializer surfaces
+- approval/attempt receipt persistence
+- application lifecycle around generated or materialized files
+
+Future `igniter-persistence` owns only after stabilization:
+
+- adapter contract
+- migration/change-plan contract
+- durable capability runtime APIs
+- relation enforcement policy
+- index/partition/placement metadata
+- cross-app persistence test kit
+
+## Maturity Ladder
+
+1. Companion app-local proof: current state.
+2. Companion internal stabilization: freeze manifest vocabulary, operation
+   algebra, relation semantics, approval lifecycle, and status packets.
+3. Split-shaped extraction without package promise: isolate extension-shaped and
+   application-shaped modules inside the app or example boundary.
+4. Optional shared packs: move descriptors to `igniter-extensions` and host
+   bindings to `igniter-application` only when another app/example repeats the
+   pressure.
+5. `igniter-persistence`: create only when adapter semantics, migrations,
+   relation policy, and Store/History lowerings have stable tests.
+6. `Igniter::Lang`: lower `persist` to `Store[T]`, `history` to `History[T]`,
+   and relation manifests to typed relation descriptors.
+
+## Next Slice
+
+Best next move:
+
+- keep Companion as the proving ground
+- stabilize a canonical manifest schema with `schema_version` and
+  `storage.shape`
+- keep `persist`/`history` aliases for current app-local compatibility
+- make operation algebra and relation metadata boring and explicit
+- keep materializer execution blocked behind human approval and audited
+  app-boundary writes
+- avoid SQL planners, migrations, FK generation, cascade semantics, and relation
+  enforcement until the descriptors stop moving
+
+Acceptance:
+
+- a new agent can read the manifest and know what is durable, append-only,
+  projected, related, command-driven, blocked, or approved
+- no setup/read endpoint mutates durable state
+- all mutation still flows through explicit command intent plus app boundary
+- all terms still lower cleanly to future `Store[T]` / `History[T]`
+
+## Handoff
+
+```text
+[Architect Supervisor / Codex]
+Track: docs/research/contract-persistence-landing-zone.md
+Status: persistence has a reserved landing path, not a new package yet.
+[D] Keep proof app-local in Companion for the next stabilization slice.
+[D] First extraction, when justified, is split: contract vocabulary to
+igniter-extensions; host/runtime/adapters/materializer boundary to
+igniter-application.
+[D] Reserve igniter-persistence as the future package name; avoid igniter-data.
+[R] Do not promote persistence DSL into igniter-contracts from this proof alone.
+[R] Treat fractality as a positive architecture signal, not a promotion trigger.
+[S] Preserve persist -> Store[T], history -> History[T], and typed relation
+lowerings.
+Next: stabilize manifest vocabulary, operation algebra, relation semantics, and
+approval/materializer lifecycle while staying app-local.
+```

data/docs/research/contract-persistence-organic-model.md

@@ -0,0 +1,279 @@
+# Contract Persistence: Organic Model
+
+Status date: 2026-04-30.
+Scope: Architecture recommendations for organic contract-native persistence.
+Not a public API promise, package API, or execution plan.
+
+## Current State (Honest Snapshot)
+
+What the Companion proof has validated:
+
+```
+persist → Store[T]            ✓ manifest descriptor
+history → History[T]           ✓ manifest descriptor
+field/index/scope/command      ✓ DSL metadata
+storage_plan (R1)              ✓ report-only lowering candidates
+command → mutation intent      ✓ graph returns, store applies
+materializer lifecycle         ✓ review-only, no execution
+```
+
+What is **not** yet part of the graph:
+
+- `field` — manifest metadata only, not a graph node
+- Store reads — happen **outside** the contract, inside `CompanionStore`
+- Store writes — intent hash interpreted by the store layer
+- Adapter — runtime injection, not compile-time configuration
+
+The graph knows about storage intent — but does not participate in storage.
+That is a sound starting point, but not yet organic.
+
+## What "Organic" Means in Igniter
+
+ORM approach: **storage first**
+
+```
+Table → Model class → Query methods → Business logic
+```
+
+Igniter organic persistence: **semantics first**
+
+```
+Contract (rules + shapes) → Storage plan → Adapter lowering → Physical storage
+```
+
+Core principles:
+
+1. **The contract IS the schema.** `persist :reminders do field :title end` is
+   the schema definition. No separate migration file.
+2. **Store[T] is a graph node**, not DSL metadata. The compiler validates it;
+   the runtime resolves it.
+3. **Reads are graph dependencies.** `store_read :reminder, by: :id` is
+   resolved by the runtime with TTL cache and coalescing — the same as
+   `compute`.
+4. **Writes are typed outputs.** `store_write :reminder, target: :reminders` is
+   executed by the runtime at the app boundary, with Saga compensation.
+5. **Adapter is a runtime plugin.** The contract declares what to store; the
+   adapter declares how.
+
+## Model: Store[T] and History[T] as First-Class Graph Nodes
+
+### New Node Types in the Graph Model
+
+```ruby
+# lib/igniter/model/ — new NodeTypes:
+# StoreNode      — like ComputeNode, but resolved by the adapter
+# HistoryNode    — append-only variant of StoreNode
+# StoreReadNode  — adapter resolution (like compute, with cache_ttl/coalesce)
+# StoreWriteNode — side effect at app boundary (like effect, with compensate)
+```
+
+### DSL (target shape)
+
+```ruby
+class ReminderContract < Igniter::Contract
+  define do
+    # Store[T] declaration — both schema and graph node
+    persist :reminders, key: :id, adapter: :sqlite do
+      field :id,     type: Types::UUID,  default: -> { SecureRandom.uuid }
+      field :title,  type: Types::String
+      field :status, type: Types::Enum[:open, :closed], default: :open
+      index :status
+      scope :open, where: { status: :open }
+    end
+
+    # History — append-only, no update/delete semantics
+    history :reminder_logs, partition_key: :reminder_id do
+      field :reminder_id, type: Types::UUID
+      field :action,      type: Types::Symbol
+      field :occurred_at, type: Types::DateTime, default: -> { Time.now }
+    end
+
+    # --- Inputs ---
+    input :reminder_id
+
+    # store_read resolved by runtime — lazy node like compute
+    store_read :reminder, from: :reminders, by: :id, using: :reminder_id,
+               cache_ttl: 60, coalesce: true
+
+    # Business logic stays in compute — storage-unaware
+    compute :updated_reminder, depends_on: [:reminder], call: CompleteReminderTransition
+
+    # store_write — typed side effect at app boundary
+    store_write :saved_reminder, from: :updated_reminder, target: :reminders
+
+    # store_append — for histories
+    store_append :log_entry, from: :updated_reminder, target: :reminder_logs
+
+    output :saved_reminder
+  end
+end
+```
+
+### What This Provides
+
+| Aspect | ORM | Igniter Organic |
+|--------|-----|-----------------|
+| Schema | Separate migration file | `persist do field ... end` IS the schema |
+| Reads | `Model.where(...)` outside business logic | `store_read` — graph dependency with cache/coalesce |
+| Writes | `model.save!` imperatively | `store_write` — typed output with Saga |
+| Validation | callbacks/validations in model | type system on fields + graph compiler |
+| Relations | belongs_to/has_many | `relation` — typed compiler-validated graph edge |
+| Adapter | ActiveRecord + database.yml | runtime plugin declared in contract |
+| Migration | `rails generate migration` | diff between `Store[T].version(n)` and `Store[T].version(n+1)` |
+
+## Relations as Graph Edges
+
+Relations are currently manifest metadata with `enforcement: :report_only`.
+In the organic model they are typed edges the **compiler validates**:
+
+```ruby
+relation :logs_by_reminder,
+  from: Store[:reminders],
+  to:   History[:reminder_logs],
+  join: { id: :reminder_id },
+  cardinality: :one_to_many
+
+# In a projection — the relation becomes a graph input
+project :reminder_detail,
+  using: :logs_by_reminder,
+  depends_on: [:reminder]
+```
+
+The compiler checks that `id` in `reminders` and `reminder_id` in
+`reminder_logs` have compatible types. This is compile-time type-checking of
+relations — something no ORM provides.
+
+## Migration as a First-Class Contract
+
+The current `WizardTypeSpecMigrationPlanContract` is already close to this.
+Target model:
+
+```ruby
+class ReminderContract::Migration < Igniter::Contract
+  define do
+    # Store[T] is itself versioned — it keeps a history of spec changes
+    input :previous_schema, from: Store[ReminderContract].version(:previous)
+    input :current_schema,  from: Store[ReminderContract].version(:current)
+
+    compute :schema_diff,    depends_on: %i[previous_schema current_schema], call: StoreSchemaDiff
+    compute :migration_plan, depends_on: [:schema_diff], call: MigrationPlanBuilder
+
+    output :migration_plan  # report-only, never self-executing
+  end
+end
+```
+
+Key insight: **schema versioning IS a History[ContractSpecChange]**, which
+Companion already has (`WizardTypeSpecChange`). Schema change history is stored
+with the same mechanisms as business event history. That is the organic shape.
+
+## Adapter as a Runtime Plugin
+
+```ruby
+# Adapter declared in the contract — compile-time decision
+class ReminderContract < Igniter::Contract
+  adapter :sqlite, database: "companion.db"   # development
+  # adapter :postgres, url: ENV["DATABASE_URL"]  # production
+  # adapter :memory                               # tests
+
+  define do
+    persist :reminders do ... end
+  end
+end
+
+# In tests:
+ReminderContract.execute(
+  { reminder_id: "123" },
+  adapter: :memory  # override per execution
+)
+```
+
+Minimal adapter interface:
+
+```ruby
+module Igniter::Persistence::Adapter
+  def read(store_key, query)           # → Record or nil
+  def write(store_key, record)         # → persisted Record
+  def append(history_key, event)       # → appended Event
+  def query(store_key, scope, params)  # → Array<Record>
+end
+```
+
+## The Core Distinction from ORM
+
+In an ORM the **unit of storage is an object** (User, Post, Comment). Business
+logic is scattered across callbacks, concerns, and service objects.
+
+In Igniter organic persistence the **unit of storage is a contract**. The
+contract declares:
+
+- what it stores (`persist`, `history`)
+- how to read (`store_read`)
+- how to mutate (`store_write`, `store_append`)
+- how data relates (`relation`)
+- what the adapter needs to lower the schema (`field`, `index`, `scope`)
+
+The runtime handles everything else: lazy resolution, cache, invalidation, Saga
+compensation, audit trail. Business logic stays in `compute` — isolated,
+testable, storage-unaware.
+
+## What to Preserve from the Current Design
+
+| Current | Status |
+|---------|--------|
+| `persist → Store[T]` / `history → History[T]` | Keep — correct semantics |
+| Command intent → app boundary | Keep — correct boundary pattern |
+| Storage plan sketch (R1) | Keep as compile-time artifact |
+| Report-only materializer lifecycle | Keep — execution must be explicit |
+| Manifest + glossary health | Keep as guardrail |
+| `WizardTypeSpec + History[ContractSpecChange]` | Keep — this IS schema versioning |
+
+## Phased Path (on top of existing roadmap)
+
+```
+R1 (done)  Storage plan sketch — report-only
+R2 (done)  Storage migration plan — report-only
+R2a        field → type system — fields participate in type validation
+R2b        store_read as compute-like graph node (lazy, cache_ttl, coalesce)
+R3         store_write / store_append as typed effect output with Saga
+R4         Adapter interface + memory adapter for tests
+R5         Migration as diff Store[T].v(n) → Store[T].v(n+1)
+R6         Materializer dry run → executable materializer
+R7         Extraction: descriptors → igniter-extensions,
+           adapters/materializer → igniter-application,
+           reserve igniter-persistence
+```
+
+## Conclusion
+
+The Companion proof has the right architecture. The boundary "graph computes
+intent, store applies it" is correct. The manifest, storage plan, and glossary
+health are the right infrastructure.
+
+The move to organic persistence is: make `Store[T]` and `History[T]`
+**first-class graph nodes**, not just DSL metadata. Then `store_read` is
+resolved by the runtime with the same cache/coalesce as compute nodes,
+`store_write` executes as a typed effect with Saga, and relations are
+compiler-validated. That is persistence as part of the contract, not an ORM
+on top of it.
+
+## Handoff
+
+```text
+[Architect Supervisor / Codex]
+Track: docs/research/contract-persistence-organic-model.md
+Status: architectural recommendations for organic contract-native persistence.
+[D] Store[T] and History[T] should become first-class graph node types.
+[D] store_read should be a lazy graph node resolved by the runtime adapter.
+[D] store_write/store_append should be typed effect outputs with Saga support.
+[D] Relations should be compiler-validated typed graph edges.
+[D] Fields should participate in Igniter's type system.
+[D] Adapter should be declared in the contract, overridable per execution.
+[D] Schema versioning IS History[ContractSpecChange] — already present in Companion.
+[R] Do not add ORM-style query methods or model callbacks to this path.
+[R] Keep the "graph computes intent, store applies" boundary.
+[S] Development track is captured in
+docs/research/contract-persistence-development-track.md.
+[S] Next best slice: R2a — connect field declarations to report-only type
+validation before core graph-node changes.
+```

data/docs/research/contract-persistence-organic-model.ru.md

@@ -0,0 +1,277 @@
+# Contract Persistence: Органическая модель
+
+Дата: 2026-04-29.
+Область: Архитектурные рекомендации по органическому persistence, нативному для контрактов.
+Не является публичным API, пакетным API или планом выполнения.
+
+## Текущее состояние (честный срез)
+
+Что доказано в Companion:
+
+```
+persist → Store[T]            ✓ manifest descriptor
+history → History[T]           ✓ manifest descriptor
+field/index/scope/command      ✓ DSL-метаданные
+storage_plan (R1)              ✓ report-only lowering candidates
+command → mutation intent      ✓ граф возвращает, store применяет
+materializer lifecycle         ✓ review-only, без execution
+```
+
+Что **не** является частью графа сейчас:
+
+- `field` — только метаданные манифеста, не узел графа
+- Store reads — происходят **снаружи** контракта, в `CompanionStore`
+- Store writes — intent hash, интерпретируемый store-ом
+- Adapter — runtime injection, не compile-time конфигурация
+
+Граф знает о намерении хранить — но не является участником хранения.
+Это хорошая отправная точка, но ещё не "organic".
+
+## Что значит "organic" в контексте Igniter
+
+ORM-подход: **storage first**
+
+```
+Table → Model class → Query methods → Business logic
+```
+
+Igniter organic persistence: **semantics first**
+
+```
+Contract (rules + shapes) → Storage plan → Adapter lowering → Physical storage
+```
+
+Ключевые принципы:
+
+1. **Контракт IS схема.** `persist :reminders do field :title end` — это и
+   есть определение данных. Никакой отдельной миграционной схемы.
+2. **Store[T] — узел графа**, а не DSL-метадата. Компилятор валидирует,
+   runtime резолвит.
+3. **Чтение — граф-зависимость.** `store_read :reminder, by: :id` резолвится
+   runtime-ом с TTL cache и coalescing — так же как `compute`.
+4. **Запись — типизированный output.** `store_write :reminder,
+   target: :reminders` выполняется runtime-ом на app boundary, с Saga
+   компенсацией.
+5. **Adapter — runtime plugin.** Контракт объявляет что хранить; adapter
+   говорит как.
+
+## Модель: Store[T] и History[T] как узлы первого класса
+
+### Новые типы узлов в модели графа
+
+```ruby
+# lib/igniter/model/ — новые NodeType:
+# StoreNode       — аналог ComputeNode, но резолвится adapter-ом
+# HistoryNode     — append-only вариант StoreNode
+# StoreReadNode   — разрешение через adapter (как compute, с cache_ttl/coalesce)
+# StoreWriteNode  — side effect на app boundary (как effect, с compensate)
+```
+
+### DSL (целевая форма)
+
+```ruby
+class ReminderContract < Igniter::Contract
+  define do
+    # Объявление Store[T] — это и схема, и узел графа
+    persist :reminders, key: :id, adapter: :sqlite do
+      field :id,     type: Types::UUID,  default: -> { SecureRandom.uuid }
+      field :title,  type: Types::String
+      field :status, type: Types::Enum[:open, :closed], default: :open
+      index :status
+      scope :open, where: { status: :open }
+    end
+
+    # История — append-only, без update/delete семантики
+    history :reminder_logs, partition_key: :reminder_id do
+      field :reminder_id, type: Types::UUID
+      field :action,      type: Types::Symbol
+      field :occurred_at, type: Types::DateTime, default: -> { Time.now }
+    end
+
+    # --- Входы ---
+    input :reminder_id
+
+    # store_read резолвится runtime-ом — lazy node как compute
+    store_read :reminder, from: :reminders, by: :id, using: :reminder_id,
+               cache_ttl: 60, coalesce: true
+
+    # Бизнес-логика остаётся в compute — без зависимости от хранилища
+    compute :updated_reminder, depends_on: [:reminder], call: CompleteReminderTransition
+
+    # store_write — типизированный side effect на app boundary
+    store_write :saved_reminder, from: :updated_reminder, target: :reminders
+
+    # store_append — для историй
+    store_append :log_entry, from: :updated_reminder, target: :reminder_logs
+
+    output :saved_reminder
+  end
+end
+```
+
+### Что это даёт
+
+| Аспект | ORM | Igniter Organic |
+|--------|-----|-----------------|
+| Схема | Отдельный migration file | `persist do field ... end` IS схема |
+| Чтение | `Model.where(...)` вне бизнес-логики | `store_read` — граф-зависимость с cache/coalesce |
+| Запись | `model.save!` императивно | `store_write` — типизированный output с Saga |
+| Валидация | callbacks/validations в модели | type system на field + граф-компилятор |
+| Отношения | belongs_to/has_many | `relation` — граф-ребро, валидируемое компилятором |
+| Адаптер | ActiveRecord + database.yml | runtime plugin, объявлен в контракте |
+| Миграция | `rails generate migration` | diff между `Store[T].version(n)` и `Store[T].version(n+1)` |
+
+## Relations как граф-рёбра
+
+Сейчас relations — manifest metadata с `enforcement: :report_only`. В
+органической модели — это типизированные рёбра, которые **компилятор
+валидирует**:
+
+```ruby
+relation :logs_by_reminder,
+  from: Store[:reminders],
+  to:   History[:reminder_logs],
+  join: { id: :reminder_id },
+  cardinality: :one_to_many
+
+# В проекции — relation становится граф-входом
+project :reminder_detail,
+  using: :logs_by_reminder,
+  depends_on: [:reminder]
+```
+
+Компилятор проверяет, что `id` в `reminders` и `reminder_id` в
+`reminder_logs` имеют совместимые типы. Это compile-time type-checking
+отношений — чего нет ни в каком ORM.
+
+## Migration как первоклассный контракт
+
+Текущий `WizardTypeSpecMigrationPlanContract` уже близок к этому. Целевая
+модель:
+
+```ruby
+class ReminderContract::Migration < Igniter::Contract
+  define do
+    # Store[T] сам является версионированным — хранит историю spec-изменений
+    input :previous_schema, from: Store[ReminderContract].version(:previous)
+    input :current_schema,  from: Store[ReminderContract].version(:current)
+
+    compute :schema_diff,    depends_on: %i[previous_schema current_schema], call: StoreSchemaDiff
+    compute :migration_plan, depends_on: [:schema_diff], call: MigrationPlanBuilder
+
+    output :migration_plan  # report-only, не выполняется
+  end
+end
+```
+
+Ключевая идея: **версионирование схемы — это History[ContractSpecChange]**,
+что уже есть в Companion (`WizardTypeSpecChange`). История изменений схемы
+хранится теми же механизмами, что и история бизнес-событий. Это и есть
+органичная форма.
+
+## Adapter как runtime plugin
+
+```ruby
+# Адаптер объявлен в контракте — compile-time decision
+class ReminderContract < Igniter::Contract
+  adapter :sqlite, database: "companion.db"    # для development
+  # adapter :postgres, url: ENV["DATABASE_URL"] # для production
+  # adapter :memory                              # для тестов
+
+  define do
+    persist :reminders do ... end
+  end
+end
+
+# В тестах:
+ReminderContract.execute(
+  { reminder_id: "123" },
+  adapter: :memory  # override per execution
+)
+```
+
+Минимальный интерфейс адаптера:
+
+```ruby
+module Igniter::Persistence::Adapter
+  def read(store_key, query)           # → Record или nil
+  def write(store_key, record)         # → persisted Record
+  def append(history_key, event)       # → appended Event
+  def query(store_key, scope, params)  # → Array<Record>
+end
+```
+
+## Ключевое отличие от ORM: граф как единица хранения
+
+В ORM **единица хранения — объект** (User, Post, Comment). Бизнес-логика
+разбросана по callbacks, concerns, service objects.
+
+В Igniter organic persistence **единица хранения — контракт**. Контракт
+объявляет:
+
+- что он хранит (`persist`, `history`)
+- как получить (`store_read`)
+- как изменить (`store_write`, `store_append`)
+- как данные связаны (`relation`)
+- как выглядит схема для адаптера (`field`, `index`, `scope`)
+
+Runtime делает всё остальное: lazy resolution, cache, invalidation, Saga
+компенсация, audit trail. Бизнес-логика остаётся в `compute` — изолированная,
+тестируемая, без зависимости от хранилища.
+
+## Что сохранить из текущего дизайна
+
+| Текущее | Статус |
+|---------|--------|
+| `persist → Store[T]` / `history → History[T]` | Сохранить — правильная семантика |
+| Command intent → app boundary | Сохранить — правильный паттерн |
+| Storage plan sketch (R1) | Сохранить как compile-time artifact |
+| Report-only materializer lifecycle | Сохранить — execution должен быть явным |
+| Manifest + glossary health | Сохранить как guardrail |
+| `WizardTypeSpec + History[ContractSpecChange]` | Сохранить — это и есть версионирование схемы |
+
+## Фазированный путь (поверх текущего roadmap)
+
+```
+R1 (done)  Storage plan sketch — report-only
+R2a        field → type system — поля участвуют в Type validation
+R2b        store_read как compute-like граф-узел (lazy, cache_ttl, coalesce)
+R3         store_write / store_append как typed effect output с Saga
+R4         Adapter interface + memory adapter для тестов
+R5         Migration как diff Store[T].v(n) → Store[T].v(n+1)
+R6         Materializer dry run → executable materializer
+R7         Extraction: descriptors → igniter-extensions,
+           adapters/materializer → igniter-application,
+           reserve igniter-persistence
+```
+
+## Вывод
+
+Companion — правильное доказательство модели. Граница "граф вычисляет
+намерение, store применяет" — **правильная**. Манифест, storage plan и
+glossary health — правильная инфраструктура.
+
+Шаг к "organic" — сделать `Store[T]` и `History[T]` **первоклассными узлами
+графа**, а не просто DSL-метаданными. Тогда `store_read` резолвится
+runtime-ом с тем же cache/coalesce что и вычисления, `store_write`
+выполняется как typed effect с Saga, а relations валидируются компилятором.
+Это и есть persistence как часть контракта, а не ORM поверх него.
+
+## Handoff
+
+```text
+[Architect Supervisor / Codex]
+Track: docs/research/contract-persistence-organic-model.ru.md
+Canonical: docs/research/contract-persistence-organic-model.md
+Status: архитектурные рекомендации по органическому persistence.
+[D] Store[T] и History[T] должны стать первоклассными типами узлов графа.
+[D] store_read — lazy граф-узел, резолвируемый runtime adapter-ом.
+[D] store_write/store_append — typed effect outputs с поддержкой Saga.
+[D] Relations — типизированные граф-рёбра, валидируемые компилятором.
+[D] Fields должны участвовать в type system Igniter.
+[D] Adapter объявлен в контракте, переопределяется per-execution.
+[D] Версионирование схемы IS History[ContractSpecChange] — уже есть в Companion.
+[R] Не добавлять ORM-style query methods или model callbacks.
+[R] Сохранять границу "граф вычисляет намерение, store применяет".
+[S] Следующий лучший срез: R2a — подключение field к type system.
+```