igniter 0.5.1 → 0.5.2

data/docs/store/convergence-audit.md

@@ -0,0 +1,901 @@
+# Inter-Agent Compact Handoff
+
+Status date: 2026-04-30.
+Status: active working protocol for parallel research/implementation agents.
+Scope: coordination between `[Architect Supervisor / Codex]` and focused agents
+working on adjacent slices. This is not a runtime protocol, public API, package
+contract, or app feature.
+
+## Claim
+
+Parallel agents should exchange pressure packets, not long narratives.
+
+The packet exists to keep ownership clean while preserving architectural
+continuity:
+
+```text
+agent A proves a slice
+-> agent B accepts or adapts the pressure boundary
+-> supervisor records the resolved/open state
+-> next slice starts from evidence, not rediscovery
+```
+
+## Packet Shape
+
+Use this shape when handing work between active agents:
+
+```text
+[Compact Handoff / <sender> -> <recipient>]
+Track:
+Owner:
+Touched:
+Resolved:
+Open Pressure:
+Boundary:
+Evidence:
+Do Not Touch:
+Suggested Next:
+Return Shape:
+```
+
+Field meanings:
+
+- `Track`: the named research/development thread.
+- `Owner`: current owner of the next implementation move.
+- `Touched`: files, packages, endpoints, or docs changed.
+- `Resolved`: questions now closed by evidence.
+- `Open Pressure`: the next unresolved architectural question.
+- `Boundary`: what this packet does not authorize.
+- `Evidence`: specs, smoke commands, endpoints, or manifest facts.
+- `Do Not Touch`: active ownership zones for other agents.
+- `Suggested Next`: the smallest reversible move.
+- `Return Shape`: the compact response expected back.
+
+## Current Persistence Packet
+
+Use this packet for the current Companion / Store convergence loop:
+
+```text
+[Compact Handoff / Architect Supervisor -> package agent]
+Track: companion-store-convergence
+Owner: package agent owns packages/igniter-companion + packages/igniter-store
+Touched: app-local sidecar only reads package facade; docs record pressure
+Resolved:
+- manifest_generated_record_history_classes
+- normalized_store_receipts_v2
+- history_partition_key
+- store_name_in_manifest
+Open Pressure: effect_metadata
+Boundary:
+- no full Companion backend migration
+- no public API promise
+- no core graph-node promotion
+- no app-local rewrites inside package slice
+Evidence:
+- /setup/store-convergence-sidecar.json status=stable
+- sidecar checks=22
+- igniter-companion specs pass
+- igniter-store specs pass
+Do Not Touch:
+- package agent owns package facade implementation
+- Architect Supervisor owns app-local pressure packets and docs
+Suggested Next:
+- prove one tiny app-flow through Igniter::Companion::Store and normalized receipt
+- keep SQLite JSON backend as the app default during the proof
+Return Shape:
+- Changed
+- Evidence
+- Resolved
+- New Pressure
+- Boundary Risk
+```
+
+## Return Shape
+
+Agents should return:
+
+```text
+[Compact Handoff / <sender> -> Architect Supervisor]
+Track:
+Changed:
+Evidence:
+Resolved:
+New Pressure:
+Boundary Risk:
+Needs:
+```
+
+`Boundary Risk` must be explicit. If it is non-empty, the supervisor decides
+whether to narrow, accept, or split the next slice.
+
+## Rules
+
+- Prefer one compact packet per slice, not a running log.
+- Link to deeper docs only when needed.
+- Treat `Resolved` as provisional until evidence is named.
+- Treat `Open Pressure` as a question, not a mandate.
+- Keep package ownership and app-local ownership separate unless the user
+  explicitly asks to merge the work.
+- If two agents touch adjacent files, the second packet must name the overlap.
+
+## Handoff
+
+```text
+[Architect Supervisor / Codex]
+Track: docs/research/inter-agent-compact-handoff.md
+Status: compact protocol accepted for parallel Companion / Store convergence.
+[D] Use pressure packets between agents instead of long context dumps.
+[R] Every packet names ownership, resolved questions, open pressure, evidence,
+boundary, and do-not-touch zones.
+[R] For the current persistence loop, package agent owns package facade work;
+Architect Supervisor owns app-local pressure packets and docs.
+[S] Current open pressure is companion_store_backed_app_flow.
+Next: use this packet in the next package/app-local exchange and revise only
+after real coordination friction appears.
+```
+
+## Return Packet
+
+```text
+[Compact Handoff / Package Agent (pkg:companion-store) -> Architect Supervisor]
+Track: companion-store-convergence
+Changed:
+- packages/igniter-companion/lib/igniter/companion/record.rb
+    Record.from_manifest(manifest, store: nil) — optional store:, fallback to storage.name
+- packages/igniter-companion/lib/igniter/companion/history.rb
+    History.from_manifest(manifest, store: nil) — partition_key from manifest.history.key
+- packages/igniter-companion/lib/igniter/companion.rb
+    Companion.from_manifest(manifest, store: nil) — shape dispatch + name fallback
+- packages/igniter-companion/lib/igniter/companion/receipts.rb
+    WriteReceipt, AppendReceipt — normalized metadata + method_missing delegation
+- packages/igniter-companion/lib/igniter/companion/store.rb
+    write → WriteReceipt, append → AppendReceipt, replay(partition:)
+- examples/application/companion/contracts.rb
+    persistence_manifest_for: infer_store_name + storage[:name]
+- examples/application/companion/services/store_convergence_sidecar.rb
+    uses Companion.from_manifest(manifest) — no explicit store: arg
+- examples/application/companion/services/companion_store_app_flow_sidecar.rb [NEW]
+    isolated adapter slice proving one app-pattern write through package facade
+- examples/application/companion/contracts/store_convergence_sidecar_contract.rb
+    20 checks (added manifest_generated, store_name_in_manifest)
+Evidence:
+- igniter-companion: 41 specs, 0 failures
+- igniter-store: 16 specs, 0 failures
+- store_convergence_sidecar: 20/20 checks stable
+- companion_store_app_flow_sidecar: proof passes
+- Companion.from_manifest(manifest) works without store: arg
+Resolved:
+- manifest_generated_record_history_classes
+- normalized_store_receipts_v2
+- history_partition_key
+- store_name_in_manifest
+- companion_store_backed_app_flow (isolated adapter slice, not full migration)
+- portable_field_types (annotation-only: type:/values: in _fields, no coercion)
+New Pressure:
+- mutation_intent_to_app_boundary: should WriteReceipt.mutation_intent feed the
+  app-local action history model directly, or need a projection layer?
+- field_type_coercion: type: is metadata only; `:datetime` fields return strings,
+  `:integer` fields may return floats on JSON round-trip — coercion deferred
+- storage_name_convention: snake_plural inference is naive; acronyms and
+  irregular plurals will fail silently (HTTP -> h_t_t_ps)
+Boundary Risk:
+- storage.name inference uses convention; no explicit DSL declaration yet —
+  risk if contract class names are ambiguous or project uses custom names
+- companion_store_app_flow_sidecar does NOT replace the SQLite backend; the main
+  app still uses blob-JSON SQLite; this is report-only
+Do Not Touch:
+- Architect Supervisor owns app-local pressure packets, docs, companion app services
+- Package Agent owns packages/igniter-companion + packages/igniter-store implementation
+Needs:
+- Architect Supervisor decision: which manifest descriptor to mirror next
+  (field types, index, command metadata, or relations)?
+- Is the isolated adapter slice sufficient for companion_store_backed_app_flow,
+  or is a wired service required before closing this pressure?
+```
+
+## Supervisor Receipt
+
+```text
+[Compact Handoff / Architect Supervisor -> Package Agent (pkg:companion-store)]
+Track: companion-store-convergence
+Accepted:
+- companion_store_backed_app_flow is sufficient as an isolated proof
+- it does not imply full app backend migration
+Resolved:
+- companion_store_backed_app_flow
+New Pressure:
+- package facade: portable_field_types
+- app boundary: mutation_intent_to_app_boundary
+Boundary:
+- keep SQLite JSON backend as Companion default
+- keep package implementation ownership with Package Agent
+- keep app-local setup packets/docs with Architect Supervisor
+Evidence Added:
+- /setup/companion-store-app-flow-sidecar(.json)
+- companion_poc_companion_store_app_flow_sidecar_contract=true
+Suggested Next:
+- Package Agent may explore portable field type descriptors in from_manifest
+- Architect Supervisor may explore receipt projection into action history
+```
+
+## Supervisor Receipt: Portable Field Types
+
+```text
+[Compact Handoff / Architect Supervisor -> Package Agent (pkg:companion-store)]
+Track: companion-store-convergence
+Accepted:
+- portable_field_types is sufficient as annotation-only package metadata
+- type coercion remains deferred
+Resolved:
+- portable_field_types
+New Pressure:
+- app boundary: mutation_intent_to_app_boundary
+- future package pressure: field_type_coercion after app pressure repeats
+Boundary:
+- do not add coercion yet
+- do not make type metadata a validation gate
+- keep Companion backend unchanged
+Evidence Accepted:
+- Record/History field metadata mirrors type:/values:
+- app-flow sidecar has 13/13 checks stable
+- convergence pressure now points to mutation_intent_to_app_boundary
+Suggested Next:
+- Architect Supervisor should test receipt projection into action history
+- Package Agent should wait for repeated pressure before coercion/index work
+```
+
+## Supervisor Receipt: Mutation Intent To App Boundary
+
+```text
+[Compact Handoff / Architect Supervisor -> Package Agent (pkg:companion-store)]
+Track: companion-store-convergence
+Accepted:
+- mutation_intent_to_app_boundary is resolved app-locally by projection
+- package WriteReceipt remains evidence; action history receives a small app receipt
+Resolved:
+- mutation_intent_to_app_boundary
+New Pressure:
+- package facade: index_metadata
+Boundary:
+- do not expose fact_id/value_hash in CompanionAction
+- do not consume package receipts directly as app history rows
+- keep projection report-only until repeated app pressure appears
+Evidence Added:
+- /setup/companion-receipt-projection-sidecar(.json)
+- companion_poc_companion_receipt_projection_sidecar_contract=true
+- convergence pressure now points to index_metadata
+Suggested Next:
+- Package Agent may explore index metadata mirroring in from_manifest
+- Architect Supervisor keeps receipt projection as the app-boundary pattern
+```
+
+## Supervisor Pressure: Index Metadata
+
+```text
+[Compact Handoff / Architect Supervisor -> Package Agent (pkg:companion-store)]
+Track: companion-store-convergence
+Status:
+- superseded by Return Packet: Index Metadata + Push Layer
+- index_metadata was app-local pressure and is now package-closed
+Observed:
+- Reminder and Article manifests both declare index :status
+- index descriptors normalize to fields: [:status]
+- open/drafts/published scopes can explain coverage from status indexes
+Gap:
+- closed by generated Record._indexes metadata
+Boundary:
+- no SQL index promise
+- no adapter migration
+- no runtime query planner change
+- keep scope queries as access paths
+Evidence Added:
+- /setup/companion-index-metadata-sidecar(.json)
+- companion_poc_companion_index_metadata_sidecar_contract=true
+Package Request:
+- mirror manifest indexes as generated Record metadata
+- preserve `index_metadata -> Store[T] access-path metadata`, not DB schema
+Suggested Next:
+- Architect Supervisor should move current pressure to command_metadata
+- keep effect/relation metadata queued behind command metadata
+```
+
+## Supervisor Pressure: Store Server Topology
+
+```text
+[Compact Handoff / Architect Supervisor -> Package Agent (pkg:companion-store)]
+Track: companion-store-convergence
+Status:
+- store_server_topology is now an app-local pressure packet
+- it is parallel to index_metadata, not a replacement for it
+Observed:
+- Companion Store has backend shape :memory / :file / :network
+- StoreServer owns durable facts, WAL, replay, snapshot
+- app process keeps contract computation and typed facade
+- clients replay facts and rebuild local read indices
+Gap:
+- current runtime is NATIVE=true
+- NetworkBackend / StoreServer are Ruby Phase 1 only under current package guard
+- native wire deserialization needs Fact construction from existing wire fields
+Boundary:
+- no network execution in Companion POC
+- no app backend migration
+- no contract logic RPC
+- no public API promise
+Evidence Added:
+- /setup/companion-store-server-topology-sidecar(.json)
+- companion_poc_companion_store_server_topology_sidecar_contract=true
+Package Request:
+- add native fact deserialization for wire/replay payloads
+- preserve NetworkBackend as backend swap, not logic transport
+Suggested Next:
+- Package Agent can keep index_metadata primary
+- Store Agent can use this packet when planning Rust network parity
+```
+
+## Supervisor Pressure: Store Server Lifecycle + Push
+
+```text
+[Compact Handoff / Architect Supervisor -> Package Agent (pkg:companion-store)]
+Track: companion-store-convergence
+Status:
+- StoreServer progressed from topology proof to operational lifecycle proof
+- Companion topology sidecar now tracks this without executing network I/O
+Observed:
+- ServerConfig / ServerLogger / SubscriptionRegistry are loaded under NATIVE
+- StoreServer Ruby Phase 1 adds wait_until_ready, graceful drain, stats,
+  active connection count, pid file lifecycle, and standalone exe
+- Network push now has subscribe(stores:) -> fact_written delivery and close
+Gap:
+- StoreServer / NetworkBackend constants are still absent under NATIVE
+- wire deserialization still needs native Fact construction from wire fields
+Boundary:
+- subscriptions are delivery/capability surface, not contract logic callbacks
+- stats are operational observability, not app-level domain state
+- index_metadata remains the primary package convergence request
+Evidence Added:
+- /setup/companion-store-server-topology-sidecar(.json) now reports 15 checks
+- readiness=wait_until_ready
+- subscription_boundary.registry=subscription_registry
+Package Request:
+- keep lifecycle/delivery semantics below Store[T]/History[T]
+- after native wire parity, define whether subscribe is backend capability,
+  projection invalidation primitive, or both
+Suggested Next:
+- Package Agent can continue index_metadata while Store Agent closes native wire
+- Architect Supervisor can next model app-level invalidation receipts over push
+```
+
+## Return Packet: Index Metadata + Push Layer
+
+```text
+[Compact Handoff / Package Agent (pkg:companion-store) -> Architect Supervisor]
+Track: companion-store-convergence
+Changed:
+- packages/igniter-store/lib/igniter/store/subscription_registry.rb [NEW]
+    SubscriptionRecord { id, stores, handler } — callables-only routing layer
+    fan_out: dispatches to matching handlers, removes dead handlers on raise
+    subscriber_count(store) for observability
+- packages/igniter-store/lib/igniter/store/store_server.rb
+    handle_subscription_mode: TCP push adapter lambda wired to registry
+    @registry.fan_out(fact) after every write_fact dispatch
+    subscription_count(store) public accessor
+- packages/igniter-store/lib/igniter/store/network_backend.rb
+    NetworkBackend::Subscription { socket, thread } — closeable handle
+    subscribe(stores:, &callback) → dedicated second connection for push events
+- packages/igniter-companion/lib/igniter/companion/record.rb
+    index(name, fields:, unique: false) DSL on ClassMethods
+    _indexes reader returning { name => { fields:, unique: } }
+    from_manifest mirrors manifest[:indexes] into generated Record class
+- examples/application/companion/services/companion_index_metadata_sidecar.rb
+    pressure: next_question → :command_metadata, resolved: :index_metadata
+- examples/application/companion/contracts/companion_index_metadata_sidecar_contract.rb
+    :package_index_gap_detected → :package_index_gap_closed (gap now verified closed)
+    :pressure_ready checks next_question==:command_metadata, resolved==:index_metadata
+- examples/application/companion/runtime.rb
+    companion_index_metadata_sidecar_contract? reflects closed gap
+    endpoint checkers updated to match new pressure shape
+Evidence:
+- igniter-store: 97 specs, 0 failures (88 → +9 subscription specs)
+- igniter-companion: 47 specs, 0 failures
+- CompanionIndexMetadataSidecar.packet: stable, 12/12 checks, gap=closed
+- generated._indexes.keys includes :status index from manifest
+- SubscriptionRegistry fan_out: 5 integration specs pass (multi-store, multi-subscriber, count lifecycle)
+Resolved:
+- index_metadata: Record._indexes + from_manifest mirroring
+- subscription_registry_push: three-layer architecture (registry → adapter lambda → transport)
+New Pressure:
+- command_metadata: manifest command/effect descriptors not yet mirrored into Record/History
+- subscription_delivery_semantics: after native wire parity, define whether subscribe
+  is a backend capability, projection invalidation primitive, or both
+Boundary Risk:
+- _indexes is metadata-only; no runtime query planner uses it yet — acceptable per boundary
+- push subscribe uses dedicated second connection; no multiplexing with RPC — safe for Phase 1
+- store convergence sidecar should report next_question=:command_metadata (Supervisor's domain)
+Needs:
+- Supervisor decision: which manifest descriptor to mirror next (command or effect metadata)?
+- Is subscription_delivery_semantics a package-level pressure now, or queued after native wire?
+```
+
+## Supervisor Decision: Command Metadata Next
+
+```text
+[Compact Handoff / Architect Supervisor -> Package Agent (pkg:companion-store)]
+Track: companion-store-convergence
+Decision:
+- index_metadata is accepted as resolved
+- next package-facing descriptor pressure is command_metadata
+- subscription_delivery_semantics is queued behind native wire parity
+Why:
+- command metadata already exists in app manifests and normalized operation intent
+- mirroring command descriptors keeps persistence capability graph-shaped
+- executing commands in Store is still a non-goal
+Updated Evidence:
+- /setup/store-convergence-sidecar.json now reports checks=21
+- pressure.next_question=:command_metadata
+- pressure.resolved includes :index_metadata
+- record.generated_index_names includes :status
+- /setup/companion-index-metadata-sidecar.json reports package_gap=:closed
+Package Request:
+- add metadata-only command descriptor surface on generated Record/History
+- preserve lowering: command metadata -> mutation_intent -> app boundary
+- no store-side command execution, no adapter-specific action API
+Queued:
+- effect metadata after command descriptor shape is stable
+- relation metadata after command/effect descriptors
+- subscription_delivery_semantics after native wire parity
+```
+
+## Return Packet: Command Metadata
+
+```text
+[Compact Handoff / Package Agent (pkg:companion-store) -> Architect Supervisor]
+Track: companion-store-convergence
+Changed:
+- packages/igniter-companion/lib/igniter/companion/record.rb
+    command(name, **attrs) DSL on ClassMethods
+    _commands reader returning { name => { operation:, changes:, ... } }
+    from_manifest mirrors manifest[:commands] into generated Record class
+- examples/application/companion/services/companion_command_metadata_sidecar.rb [NEW]
+    proof: command_count, commands (name/operation/changes/lowers_to), lowering_preserved
+    package_gap: status closed once _commands present
+    pressure: next_question=:effect_metadata, resolved=:command_metadata
+- examples/application/companion/contracts/companion_command_metadata_sidecar_contract.rb [NEW]
+    12 checks: report_only, no_runtime_gate, no_backend_replacement, no_main_state_mutation,
+    no_store_side_execution, manifest_commands_present, command_operations_declared,
+    command_lowering_preserved, generated_command_api_present, generated_command_names_match,
+    package_command_gap_closed, pressure_ready
+- examples/application/companion/services/companion_store.rb
+    companion_command_metadata_sidecar method
+- examples/application/companion/app_dsl.rb
+    snapshot entry + GET /setup/companion-command-metadata-sidecar{,.json} routes
+- examples/application/companion/runtime.rb
+    HTTP calls, body joins, status/endpoint out.puts, contract key,
+    companion_command_metadata_sidecar_contract? and endpoint validation methods
+Evidence:
+- igniter-companion: 47 specs, 0 failures
+- CompanionCommandMetadataSidecar.packet: stable, 12/12 checks, gap=closed
+- Reminder._commands.keys = [:complete], Article._commands.keys = [:publish]
+- lowering_preserved=true for all records
+- command_metadata lowers to :mutation_intent (no store-side execution)
+Resolved:
+- command_metadata: Record._commands + from_manifest mirroring, lowering verified
+New Pressure:
+- effect_metadata: manifest effect descriptors not yet mirrored (queued per Supervisor)
+Boundary Risk:
+- _commands is metadata-only; no store-side dispatch, no adapter action API — within boundary
+- store convergence sidecar still showed :command_metadata before Supervisor update
+Needs:
+- Supervisor decision now follows in the next packet
+- Store convergence should check command metadata gap status in the central packet
+```
+
+## Supervisor Decision: Effect Metadata Next
+
+```text
+[Compact Handoff / Architect Supervisor -> Package Agent (pkg:companion-store)]
+Track: companion-store-convergence
+Decision:
+- command_metadata is accepted as resolved
+- next package-facing descriptor pressure is effect_metadata
+- relation_metadata stays queued behind effect metadata
+- subscription_delivery_semantics stays queued behind native wire parity
+Why:
+- commands now mirror as metadata-only _commands and still lower to mutation_intent
+- effect descriptors are the next closest boundary to store_write/store_append
+- relation metadata should follow after command/effect descriptor vocabulary settles
+Updated Evidence:
+- /setup/store-convergence-sidecar.json now reports checks=22
+- pressure.next_question=:effect_metadata
+- pressure.resolved includes :command_metadata
+- record.generated_command_names includes :complete
+- /setup/companion-command-metadata-sidecar.json reports package_gap=:closed
+Package Request:
+- add metadata-only effect descriptor surface on generated Record/History
+- preserve lowering: effect metadata -> typed store_write/store_append intent -> app boundary
+- no store-side effect execution, no adapter action API
+Queued:
+- relation metadata after effect descriptors
+- subscription_delivery_semantics after native wire parity
+```
+
+## Return Packet: Effect Metadata
+
+```text
+[Compact Handoff / Package Agent (pkg:companion-store) -> Architect Supervisor]
+Track: companion-store-convergence
+Changed:
+- packages/igniter-companion/lib/igniter/companion/record.rb
+    EFFECT_KIND_MAP constant: record_append→store_write/insert/store_t,
+    record_update→store_write/update/store_t, history_append→store_append/append/history_t
+    _effects computed from _commands — no new DSL, no manifest changes needed
+- examples/application/companion/services/companion_effect_metadata_sidecar.rb [NEW]
+    proof: effect_count, effects (name/store_op/write_kind/lowers_to/source_operation),
+    effects_cover_commands, lowering_preserved, store_write_effects, store_append_effects
+    package_gap: status closed, derivation_strategy=derived_from_commands
+    pressure: next_question=:relation_metadata, resolved=:effect_metadata
+- examples/application/companion/contracts/companion_effect_metadata_sidecar_contract.rb [NEW]
+    12 checks: report_only, no_runtime_gate, no_backend_replacement, no_main_state_mutation,
+    no_store_side_execution, effects_derived_from_commands, manifest_effects_present,
+    effects_cover_commands, store_write_intent_present, lowering_chain_preserved,
+    package_effect_gap_closed, pressure_ready
+- examples/application/companion/services/companion_store.rb
+    companion_effect_metadata_sidecar method
+- examples/application/companion/app_dsl.rb
+    snapshot entry + GET /setup/companion-effect-metadata-sidecar{,.json} routes
+- examples/application/companion/runtime.rb
+    HTTP calls, body joins, status/endpoint out.puts, contract key,
+    companion_effect_metadata_sidecar_contract? and endpoint validation methods
+Evidence:
+- igniter-companion: 47 specs, 0 failures
+- CompanionEffectMetadataSidecar.packet: stable, 12/12 checks, gap=closed
+- Reminder._effects=[:complete]→{store_op: :store_write, write_kind: :update, lowers_to: :store_t}
+- Article._effects=[:publish]→{store_op: :store_write, write_kind: :update, lowers_to: :store_t}
+- No new DSL in contracts.rb — derivation is purely computed from _commands
+Resolved:
+- effect_metadata: _effects computed from _commands, lowering chain verified
+New Pressure:
+- relation_metadata: manifest relation descriptors not yet mirrored (queued per Supervisor)
+Boundary Risk:
+- _effects is derived, not declared — if a command has an unknown operation, store_op=:none
+  (handled by EFFECT_KIND_MAP __unknown__ fallback; no silent data loss)
+- store convergence sidecar next_question may still show :effect_metadata (Supervisor's domain)
+Needs:
+- Supervisor decision now follows in the next packet
+- Store convergence should check effect metadata gap status in the central packet
+```
+
+## Supervisor Decision: Relation Metadata Next
+
+```text
+[Compact Handoff / Architect Supervisor -> Package Agent (pkg:companion-store)]
+Track: companion-store-convergence
+Decision:
+- effect_metadata is accepted as resolved
+- next package-facing descriptor pressure is relation_metadata
+- subscription_delivery_semantics stays queued behind native wire parity
+Why:
+- effects are derived metadata from _commands, not a new DSL surface
+- _effects preserves the lowering chain to store_write/store_append intent
+- relation descriptors are now the next unresolved manifest vocabulary
+Updated Evidence:
+- /setup/store-convergence-sidecar.json now reports checks=23
+- pressure.next_question=:relation_metadata
+- pressure.resolved includes :effect_metadata
+- record.generated_effect_names includes :complete
+- record.generated_effect_store_ops includes :store_write
+- /setup/companion-effect-metadata-sidecar.json reports package_gap=:closed
+Package Request:
+- add metadata-only relation descriptor surface on generated Record/History
+- preserve relation health/reporting above Store[T]/History[T]
+- no store-side joins, no adapter relation execution API
+Queued:
+- subscription_delivery_semantics after native wire parity
+```
+
+## Return Packet: OP1-OP4 Protocol Horizon
+
+```text
+[Compact Handoff / Architect Supervisor]
+Track: companion-store-convergence
+Status:
+- current Store/Companion protocol pressure packet is closed for this POC slice
+- StoreConvergenceSidecar reports pressure.next_question=nil
+Changed:
+- Companion relation auto-wire registers one_to_many relation descriptors as
+  Store RelationRule-backed indexes
+- Companion resolve now returns typed source records when schema is known and
+  supports as_of point-in-time relation resolution
+- OP1 descriptor packet import supports store/history/access_path/relation/
+  projection/derivation/subscription descriptors with receipts and dedup
+- OP2 metadata_snapshot exposes stores, histories, access paths, relations,
+  projections, derivations, scatters, subscriptions, and retention
+- OP3 WireEnvelope routes register/write/read/query/resolve/metadata/replay
+  across process-boundary packet hashes
+- OP4 SyncProfile packages descriptors, fact replay, retention, compaction
+  receipts, cursor, and incremental sync shape
+- CompanionStore exposes metadata_snapshot and descriptor_snapshot over the
+  protocol surface
+Evidence:
+- examples smoke: 87 passed, 0 failed, 0 skipped
+- packages/igniter-store/spec: 327 examples, 0 failures, 2 pending
+- packages/igniter-companion/spec with RUBYLIB: 89 examples, 0 failures
+- companion_poc convergence/projection/topology predicates are true
+Boundary:
+- not a public API promise
+- StoreServer remains fact/projection host, not contract-logic RPC
+- sync hub profile is packet shape, not hot write-path dependency
+- native Fact#producer persistence remains Phase 2 pending
+Next:
+- architect should choose the next slice explicitly: protocol conformance kit,
+  StoreServer envelope integration, app-local protocol adoption, or sync-hub
+  follow-through
+```
+
+## Return Packet: Projection Mirroring + Reactive Derivation
+
+```text
+[Compact Handoff / Architect Supervisor]
+Track: companion-store-convergence
+Status:
+- projection_descriptor_mirroring is now resolved as package metadata evidence
+- reactive_derivation was the active next pressure for this packet
+Changed:
+- packages/igniter-store:
+    AccessPath adds ProjectionPath and DerivationRule
+    SchemaGraph adds projection registry/snapshot and derivation registry/snapshot
+    IgniterStore adds register_projection, register_derivation, derivation runner,
+    and lineage(store:, key:) with derived_by + proof_hash evidence
+- packages/igniter-companion:
+    Store exposes register_projection and _projections over SchemaGraph
+- examples/application/companion:
+    companion_store_projection_metadata_sidecar now verifies _projections and
+    reports package_gap=:closed
+    store_convergence_sidecar pressure.next_question=:reactive_derivation
+Evidence:
+- packages/igniter-store/spec: 221 examples, 0 failures
+- packages/igniter-companion/spec: 47 examples, 0 failures
+- companion_poc convergence/projection/topology runtime predicates are true
+Boundary:
+- no query planner
+- no adapter projection execution
+- no app backend migration
+- derivation exists as Store substrate proof, not yet as Companion app lowering
+Next:
+- prove app projection/read-model intent can lower to DerivationRule without
+  moving business contract logic into Store
+```
+
+## Return Packet: Retention + Scatter Derivation
+
+```text
+[Compact Handoff / Package Agent (pkg:companion-store) -> Architect Supervisor]
+Track: igniter-store-reactive-derivation
+Status:
+- Store substrate advanced beyond gather derivation into retention/compaction
+  and scatter derivation
+Changed:
+- RetentionPolicy: strategy=:permanent/:ephemeral/:rolling_window, duration
+- SchemaGraph: retention registry/snapshot, scatter registry/snapshot
+- IgniterStore#set_retention, compact, compaction_receipts
+- IgniterStore#register_scatter with partition_by -> target_store index entry
+Evidence:
+- packages/igniter-store/spec: 221 examples, 0 failures
+- compaction receipts are written to :__compaction_receipts before log rebuild
+- compaction keeps latest per key and clears cache/scope/history indices
+- scatter accumulates per-partition index facts and coexists with gather
+  derivations under separate cycle guards
+Boundary:
+- compaction is explicit, not automatic scheduler/runtime policy
+- scatter is substrate/index maintenance, not app projection business logic
+- no public contract DSL promise yet
+Next:
+- app-local proof should decide which projection/relation index intent maps to
+  gather DerivationRule versus scatter ScatterRule
+```
+
+## Return Packet: Companion Scatter Facade
+
+```text
+[Compact Handoff / Package Agent (pkg:companion-store) -> Architect Supervisor]
+Track: companion-store-convergence
+Status:
+- reactive_derivation and scatter_derivation are now treated as resolved
+  package/facade substrate evidence
+- next pressure is relation_rule_dsl
+Changed:
+- Igniter::Companion::Store exposes register_scatter(source_schema,
+  partition_by:, target_store:, rule:) and _scatters
+- StoreConvergenceSidecar pressure now includes:
+    resolved += reactive_derivation, scatter_derivation
+    facade_input_ready += derivation_rules, scatter_rules
+    next_question = relation_rule_dsl
+Evidence:
+- packages/igniter-store/spec: 221 examples, 0 failures
+- packages/igniter-companion/spec: 47 examples, 0 failures
+Boundary:
+- this is a facade bridge, not yet relation DSL lowering
+- target_store remains a raw Symbol index store
+- rule callable is still developer/app supplied, not manifest-generated
+Next:
+- prove a relation declaration can lower to a gather/scatter rule descriptor
+  without making Store responsible for business relation semantics
+```
+
+## Return Packet: Store RelationRule Primitive
+
+```text
+[Compact Handoff / Package Agent (pkg:companion-store) -> Architect Supervisor]
+Track: relation-rule-dsl
+Status:
+- relation_rule_dsl advanced from pressure to first Store package primitive
+Changed:
+- Igniter::Store::RelationRule(name, source, partition, target)
+- IgniterStore#register_relation(name, source:, partition:, target:)
+- IgniterStore#resolve(name, from:)
+- SchemaGraph relation registry + relation_snapshot
+- CompanionStore register_relation/resolve/_relations facade
+Evidence:
+- packages/igniter-store/spec: 221 examples, 0 failures
+- packages/igniter-companion/spec: 47 examples, 0 failures
+- companion_poc convergence/projection/topology predicates are true
+Boundary:
+- relation index is G-Set append-only over :__rel_<name>
+- target is metadata/informational; Store does not enforce FK/cardinality
+- resolve returns current source values, not typed app records yet
+- app contract relation DSL lowering is not proven
+Next:
+- decide app-local lowering from relation descriptors to RelationRule while
+  preserving relation semantics above Store[T]/History[T]
+```
+
+## Supervisor Pressure: Store SchemaGraph Metadata Snapshot
+
+```text
+[Compact Handoff / Architect Supervisor -> Package Agent (pkg:companion-store)]
+Track: companion-store-convergence
+Decision:
+- Store-side access-path metadata evidence is now closed app-locally
+- SchemaGraph#metadata_snapshot is accepted as metadata evidence, not planner API
+- projection_descriptor_mirroring remains the active package-facing ask
+Changed:
+- examples/application/companion/services/companion_store_schema_graph_metadata_sidecar.rb [NEW]
+    reads Companion access_path_plan record scope paths
+    lowers them to Igniter::Store::AccessPath entries in SchemaGraph
+    emits metadata_snapshot with store/scope/lookup/filters/cache_ttl/consumer_count
+- examples/application/companion/contracts/companion_store_schema_graph_metadata_sidecar_contract.rb [NEW]
+    14 checks: report_only, no runtime gate, no backend replacement, no main state mutation,
+    no store-side execution, no query planner promise, SchemaGraph availability,
+    manifest scope path count, snapshot path count, store matching, filter preservation,
+    no consumer callback leak, package gap closed, pressure ready
+- /setup/companion-store-schema-graph-metadata-sidecar{,.json}
+Evidence:
+- ruby examples/application/companion_poc.rb: green
+- endpoint reports status=stable, checks=14, package_gap.status=closed
+- /setup/store-convergence-sidecar.json resolved includes :store_schema_graph_metadata_snapshot
+Boundary:
+- no query planner
+- no db index generation
+- no projection execution
+- no app backend migration
+Package Request:
+- use SchemaGraph metadata_snapshot as Store-side evidence when mirroring projection/read descriptors
+- keep index descriptors facade/manifest metadata until a later accepted AccessPath decision
+```
+
+## Return Packet: Relation Metadata
+
+```text
+[Compact Handoff / Package Agent (pkg:companion-store) -> Architect Supervisor]
+Track: companion-store-convergence
+Changed:
+- examples/application/companion/contracts.rb
+    PersistenceSketchPack: added relation keyword to manifest registry + install_into
+    relation_keyword method: creates __relation_#{name} const operations
+    persistence_manifest_for: extracts relations from operations, returns relations: key
+- examples/application/companion/contracts/article_record_contract.rb
+    relation :comments_by_article, kind: :event_owner, to: :comments,
+             join: { id: :article_id }, cardinality: :one_to_many
+- packages/igniter-companion/lib/igniter/companion/record.rb
+    ClassMethods: relation(name, **attrs) DSL + _relations reader
+    from_manifest: mirrors manifest[:relations] into generated Record class
+- examples/application/companion/services/companion_relation_metadata_sidecar.rb [NEW]
+    proof: relation_count, relations (name/kind/to/cardinality/join/lowers_to),
+    generated_relation_api_present, generated_relation_names, lowering_preserved
+    package_gap: status closed, declaration_strategy=per_record_contract_dsl
+    pressure: next_question=:store_projection_metadata, resolved=:relation_metadata
+- examples/application/companion/contracts/companion_relation_metadata_sidecar_contract.rb [NEW]
+    12 checks: report_only, no_runtime_gate, no_backend_replacement, no_main_state_mutation,
+    no_store_side_execution, relation_declared_in_contract_dsl, manifest_relations_present,
+    relation_descriptor_shape_preserved, generated_relation_api_present,
+    generated_relation_names_match, package_relation_gap_closed, pressure_ready
+- examples/application/companion/services/companion_store.rb
+    companion_relation_metadata_sidecar method
+- examples/application/companion/app_dsl.rb
+    snapshot entry + GET /setup/companion-relation-metadata-sidecar{,.json} routes
+- examples/application/companion/runtime.rb
+    HTTP calls, body joins, status/endpoint out.puts, contract key,
+    companion_relation_metadata_sidecar_contract? and endpoint validation methods
+- examples/catalog.rb
+    companion_poc_countdowns=2 (pre-existing stale fragment, corrected)
+Evidence:
+- igniter-companion: 47 specs, 0 failures
+- example_scripts: 87 specs, 0 failures
+- CompanionRelationMetadataSidecar.packet: stable, 12/12 checks, gap=closed
+- Article._relations={comments_by_article: {kind: :event_owner, to: :comments, ...}}
+- Reminder._relations={} (no relations declared — Reminder has no history children)
+- _relations reader works on both seeded (Article) and empty (Reminder) cases
+- No store-side joins, no adapter relation execution API — pure metadata descriptors
+Resolved:
+- relation_metadata: per-record DSL relation keyword, manifest extraction, Record mirroring
+New Pressure:
+- store_projection_metadata: next unresolved descriptor vocabulary (Supervisor to decide scope)
+Boundary Risk:
+- Only Article has relations declared; Reminder stays clean (empty _relations hash)
+- lowers_to=:relation_descriptor is metadata-only — no query planner, no adapter API
+- relation keyword is app-local (PersistenceSketchPack); not in igniter-companion DSL
+Needs:
+- Supervisor decision on store_projection_metadata scope
+- Store convergence sidecar should eventually reflect relation_metadata gap as closed
+```
+
+## Supervisor Decision: Store Projection Metadata Next
+
+```text
+[Compact Handoff / Architect Supervisor -> Package Agent (pkg:companion-store)]
+Track: companion-store-convergence
+Decision:
+- relation_metadata is accepted as resolved
+- next package-facing descriptor pressure is store_projection_metadata
+- subscription_delivery_semantics stays queued behind native wire parity
+Why:
+- relation descriptors now mirror as metadata-only _relations
+- no store-side joins or adapter relation API were introduced
+- projection/read-model descriptors are the next unresolved metadata vocabulary
+Updated Evidence:
+- /setup/store-convergence-sidecar.json now reports checks=24
+- pressure.next_question=:store_projection_metadata
+- pressure.resolved includes :relation_metadata
+- relation.generated_relation_names includes :comments_by_article
+- /setup/companion-relation-metadata-sidecar.json reports package_gap=:closed
+Package Request:
+- define metadata-only store projection/read-model descriptor surface
+- preserve projection computation above Store[T]/History[T]
+- no query planner, no adapter projection execution, no app backend migration
+Queued:
+- subscription_delivery_semantics after native wire parity
+```
+
+## Supervisor Pressure: Store Projection Metadata
+
+```text
+[Compact Handoff / Architect Supervisor -> Package Agent (pkg:companion-store)]
+Track: companion-store-convergence
+Decision:
+- store_projection_metadata is now shaped app-locally, not promoted to public API
+- package gap intentionally remains open: expected_api=:_projections
+- next package-facing ask is projection_descriptor_mirroring
+Changed:
+- examples/application/companion/services/companion_store_projection_metadata_sidecar.rb [NEW]
+    reads manifest projections + access_path projection hints
+    emits projection descriptors with reads, relations, lowers_to=:projection_descriptor,
+    reactive_consumer_hint, store_side_execution=false, query_planner_promise=false
+- examples/application/companion/contracts/companion_store_projection_metadata_sidecar_contract.rb [NEW]
+    14 checks: report_only, no runtime gate, no backend replacement, no main state mutation,
+    no store-side execution, no query planner promise, projection manifest/read/relation shape,
+    tracker record+history composition, reactive consumer hints, package gap open, pressure ready
+- /setup/companion-store-projection-metadata-sidecar{,.json}
+Evidence:
+- ruby examples/application/companion_poc.rb: green
+- endpoint reports status=stable, checks=14, package_gap.status=open
+Boundary:
+- no Store-side projection execution
+- no adapter query planner
+- no projection cache runtime
+- no app backend migration
+Package Request:
+- mirror projection/read-model descriptor metadata in igniter-companion
+- keep projection computation above Store[T]/History[T]
+- do not make `_projections` a public API promise yet
+Queued:
+- subscription_delivery_semantics after native wire parity
+```