igniter 0.5.1 → 0.5.2

data/docs/research/wizard-type-spec-architecture.md

@@ -0,0 +1,293 @@
+# Wizard Type Spec Architecture
+
+Status: research response to
+[Wizard Type Spec Research Request](./wizard-type-spec-research-request.md).
+App-local direction only. Not accepted core API, package API, dynamic runtime
+execution, migration system, or Igniter Lang grammar.
+
+## Decision
+
+`WizardTypeSpec` should be modeled as a durable spec registry cell:
+
+```text
+WizardTypeSpec ~= Store[ContractSpec]
+WizardTypeSpecChange ~= History[ContractSpecChange]
+```
+
+The spec is data about a future or materialized contract shape. It is not
+runtime code.
+
+Static Ruby contracts remain the production execution shape. Wizard specs are
+the lineage, export, parity, and future materialization input.
+
+## Mental Model
+
+Use three layers:
+
+- Draft: wizard/configurator edits durable specs in a sandbox.
+- Materialization plan: graph contracts lower specs to static record, history,
+  relation, command, and capability requirements.
+- Static shape: explicit Ruby contracts execute in production and are checked
+  against the plan.
+
+This avoids the dangerous shortcut where a user-authored JSON spec becomes live
+runtime behavior.
+
+## Canonical Spec
+
+Minimum canonical form:
+
+```ruby
+{
+  schema_version: 1,
+  id: "article-comment",
+  name: :Article,
+  capability: :articles,
+  kind: :record,
+  storage: {
+    shape: :store,
+    key: :id,
+    adapter: :sqlite
+  },
+  fields: [
+    { name: :id, type: :string, required: true },
+    { name: :title, type: :string, required: true },
+    { name: :body, type: :string },
+    { name: :created_at, type: :datetime },
+    {
+      name: :status,
+      type: :enum,
+      values: %i[draft published archived],
+      default: :draft
+    }
+  ],
+  indexes: [
+    { name: :status, fields: [:status] }
+  ],
+  scopes: [
+    { name: :drafts, where: { status: :draft } },
+    { name: :published, where: { status: :published } }
+  ],
+  commands: [
+    {
+      name: :publish,
+      operation: :record_update,
+      changes: { status: :published }
+    }
+  ],
+  histories: [
+    {
+      name: :Comment,
+      capability: :comments,
+      storage: {
+        shape: :history,
+        key: :index,
+        adapter: :sqlite
+      },
+      fields: [
+        { name: :index, type: :integer },
+        { name: :article_id, type: :string },
+        { name: :body, type: :string },
+        { name: :created_at, type: :datetime }
+      ],
+      relation: {
+        name: :comments_by_article,
+        kind: :event_owner,
+        from: :articles,
+        to: :comments,
+        join: { id: :article_id },
+        cardinality: :one_to_many,
+        integrity: :validate_on_append,
+        consistency: :local,
+        enforced: false
+      }
+    }
+  ],
+  metadata: {
+    source: :wizard,
+    materialized: false
+  }
+}
+```
+
+Compatibility aliases are allowed during the app-local proof:
+
+- `persist` may lower to `storage: { shape: :store }`
+- `history` may lower to `storage: { shape: :history }`
+
+The canonical internal model should prefer `storage.shape` because it aligns
+with `Store[T]`, `History[T]`, and future specialized shapes.
+
+## Type Vocabulary
+
+Keep the first type vocabulary small:
+
+- `:string`
+- `:integer`
+- `:numeric`
+- `:boolean`
+- `:datetime`
+- `:date`
+- `:enum`
+- `:json`
+
+Do not add arbitrary Ruby classes to wizard specs yet. The bridge to Ruby
+classes belongs in materialization, not in the portable spec.
+
+## Change History
+
+`WizardTypeSpecChange` should capture lineage, not only audit:
+
+```ruby
+{
+  index: 12,
+  spec_id: "article-comment",
+  contract: "Article",
+  change_kind: :wizard_edit,
+  spec: { ...full_snapshot },
+  created_at: "2026-04-29",
+  actor: "user-or-agent",
+  reason: "add published scope"
+}
+```
+
+Use full snapshots first. Diffs can be added later as compression once repeated
+history pressure exists.
+
+## Export Rules
+
+Dev export:
+
+- includes latest specs
+- includes full spec history
+- includes materialization plan summaries
+- may include parity status and mismatches
+- is suitable for review, migration planning, and agent handoff
+
+Prod export:
+
+- includes latest specs only
+- strips history by default
+- strips actor/reason/debug metadata
+- includes no executable code
+- includes no write/git/restart capability
+- may include static materialization status so deploy checks can refuse drift
+
+## Materializer Boundary
+
+A materializer is a future capability, not current behavior.
+
+Allowed now:
+
+- read persisted specs
+- lower specs to materialization plans
+- compare plans with static manifests
+- export portable config
+- report required capabilities
+
+Still forbidden:
+
+- write files
+- run git
+- restart app processes
+- mutate core/package runtime
+- execute dynamic specs as code
+- run migrations
+- create DB indexes or foreign keys
+
+Future materializer capability should require explicit gates:
+
+- `write`
+- `test`
+- `git`
+- `restart`
+- optional `migration_plan`
+
+Parity must be clean before requesting any write/git/restart capability.
+
+## Migration Planning
+
+Spec history can become migration planning input, but not migration execution.
+
+Safe near-term uses:
+
+- detect added/removed/renamed fields
+- detect index/scope/command changes
+- detect relation shape changes
+- classify changes as additive, destructive, or ambiguous
+- emit review-only migration candidates
+
+Deferred:
+
+- automatic migrations
+- database schema changes
+- data backfills
+- destructive operations
+- runtime hot reload
+
+## Lang Lowering
+
+Future language interpretation:
+
+```text
+ContractSpec[Article]
+Store[ContractSpec]
+History[ContractSpecChange]
+MaterializationPlan[ContractSpec]
+ParityReport[MaterializationPlan, StaticManifest]
+```
+
+The important path:
+
+```text
+wizard JSON -> canonical ContractSpec -> Ruby static contracts
+            -> future Igniter::Lang syntax
+```
+
+Do not make Ruby reflection the canonical source. Ruby contracts can sync into
+the spec registry, but the portable form should stay host-neutral.
+
+## Promotion Criteria
+
+Do not promote yet.
+
+Promotion needs:
+
+- two or more real user-defined shapes
+- a stable canonical spec shape across edits
+- parity checks catching useful drift
+- dev/prod export proving different audiences
+- a materializer capability model accepted separately
+- no dynamic execution needed for product value
+
+## Smallest Next Experiment
+
+App-local only:
+
+1. Add `schema_version` and `storage.shape` to the seeded Article/Comment spec.
+2. Keep `persist`/`history` aliases for current manifest compatibility.
+3. Extend parity/export to surface `schema_version`.
+4. Add one smoke marker proving prod export strips history and dev export keeps
+   it.
+
+This tightens the canonical model without changing runtime behavior.
+
+## Handoff
+
+```text
+[Research / Codex]
+Track: docs/research/wizard-type-spec-architecture.md
+Status: research response delivered.
+[D] WizardTypeSpec is best modeled as Store[ContractSpec]; WizardTypeSpecChange
+is best modeled as History[ContractSpecChange].
+[D] Dynamic specs are durable lineage/config data, not executable runtime code.
+[R] Production execution stays static-contract-first until a separate
+materializer capability model is accepted.
+[R] Canonical specs should prefer host-neutral `storage.shape`; app-local
+`persist` and `history` remain compatibility sugar.
+[S] Companion already proves Article/Comment latest spec, spec history,
+materialization plan, parity, and dev/prod export.
+Next: add `schema_version` and `storage.shape` to the seeded spec and expose
+that through export/parity without runtime behavior changes.
+Block: no core/package promotion, no migrations, no dynamic execution.
+```

data/docs/research/wizard-type-spec-research-request.md

@@ -0,0 +1,134 @@
+# Wizard Type Spec Research Request
+
+Status date: 2026-04-29.
+From: `[Architect Supervisor / Codex]`.
+To: Research.
+Track: `wizard-type-spec-lineage-materialization`.
+
+## Claim
+
+`WizardTypeSpec` may be more than a wizard draft store. It may be the durable
+lineage layer for user-defined contract shapes, static contract synchronization,
+portable config export, and future migration planning.
+
+## Current App-Local Proof
+
+Companion now proves this shape without core/runtime promotion:
+
+- `WizardTypeSpec`: persisted latest dynamic spec
+  - `id`
+  - `contract`
+  - `spec`, `type: :json`
+- `WizardTypeSpecChange`: append-only spec lineage
+  - static sync/backfill events
+  - full spec snapshots for migration analysis
+- `DurableTypeMaterializationContract`: read-only lowering from latest spec to
+  static record/history/relation materialization plan
+- `StaticMaterializationParityContract`: read-only parity check between the plan
+  and current static manifests
+- `WizardTypeSpecExportContract`: portable config projection
+  - dev export keeps history
+  - prod export compresses to latest-only specs
+
+The current example is `Article` + `Comment`:
+
+- latest spec lives in `wizard_type_specs`
+- history lives in `wizard_type_spec_changes`
+- static contracts still exist as normal Ruby contracts
+- materialization plan and parity are inspectable through setup endpoints
+- no dynamic spec is executed as runtime code
+- no write/git/restart capability is granted
+
+## Decision Pressure
+
+Static contracts can sync their own specs into `WizardTypeSpec`. That creates a
+shared representation for:
+
+- wizard-authored drafts
+- static contract manifests
+- materialization plans
+- drift/parity reports
+- migration candidates
+- portable config snapshots
+
+This suggests `WizardTypeSpec` may become the neutral durable shape registry,
+while static contracts remain the production execution shape.
+
+## Research Questions
+
+1. Should `WizardTypeSpec` be modeled as `Store[ContractSpec]` in the future
+   language layer?
+2. Should `WizardTypeSpecChange` be modeled as `History[ContractSpecChange]`,
+   or as a specialized migration/lineage history?
+3. What is the correct canonical form of `spec` so it can round-trip between:
+   wizard JSON, static Ruby contracts, and future `Igniter::Lang` syntax?
+4. What belongs in dev export versus prod export?
+5. Can spec history become the foundation for migration planning without
+   implying automatic DB migrations too early?
+6. How should static contracts sync their specs: at boot, via explicit command,
+   via materializer agent, or via build-time report?
+7. What invariants should parity check before any future write/git/restart
+   materializer capability is allowed?
+
+## Guardrails
+
+- Keep this app-local for now.
+- Do not promote `WizardTypeSpec`, `persist`, `history`, relation declarations,
+  or materialization contracts into core from this proof alone.
+- Dynamic authoring remains sandbox-only.
+- Static contracts remain the production materialized shape.
+- Spec export is data/config, not executable code.
+- Prod export may compress history away; dev export may preserve lineage.
+- Relation enforcement remains false.
+- No cascade semantics, automatic migrations, DB planners, or runtime dynamic
+  code execution yet.
+
+## Requested Research Output
+
+Please analyze whether this should become a first-class architecture concept and
+return:
+
+- a recommended mental model for `WizardTypeSpec`
+- the relation to `Store[T]`, `History[T]`, and future migration planning
+- the minimum canonical spec shape
+- dev/prod export rules
+- materializer capability boundaries
+- reasons this should not be promoted yet
+- the smallest next reversible app-local experiment
+
+## Research Response
+
+Accepted response:
+
+- [Wizard Type Spec Architecture](./wizard-type-spec-architecture.md)
+
+Summary:
+
+- `WizardTypeSpec` is best modeled as `Store[ContractSpec]`.
+- `WizardTypeSpecChange` is best modeled as `History[ContractSpecChange]`.
+- Dynamic specs are durable lineage/config data, not executable runtime code.
+- Static contracts remain the production materialized shape.
+- The smallest next experiment is to add `schema_version` and
+  `storage.shape` to the seeded Article/Comment spec while preserving current
+  `persist`/`history` compatibility.
+
+## Handoff
+
+```text
+[Architect Supervisor / Codex]
+Track: wizard-type-spec-lineage-materialization
+Status: Companion app-local proof now has persisted latest specs, append-only
+spec lineage, read-only materialization plans, parity checks, and dev/prod
+portable exports.
+[D] Dynamic specs are durable data, not executable runtime code.
+[D] Production behavior still materializes into static contracts.
+[R] Preserve path to Store[ContractSpec] and History[ContractSpecChange].
+[R] Do not infer automatic migrations or DB planning yet.
+[S] Article/Comment proves wizard-shaped specs can round-trip into static
+contract manifests with parity.
+[Q] Is WizardTypeSpec the neutral lineage/migration registry for future
+user-defined contract shapes?
+Next: Research should define the canonical spec model and materializer
+capability boundary.
+Block: none.
+```

data/docs/store/README.md

@@ -0,0 +1,7 @@
+# docs/store/
+
+Cross-package convergence audits and inter-agent protocol records for the Store subsystem.
+
+| File | Description |
+|------|-------------|
+| [convergence-audit.md](convergence-audit.md) | Inter-agent compact handoff — pressure progression log (command → effect → relation → projection/schema-graph metadata) |