docs(adr): amend ADR-0007 per the #212 ruling — admission test + @ROLE shrink

ADR-0007 catalogued `source.event @topic @ROLE: publish`; ADR-0028 later ruled
that message topics are channels, not sources, "never in source.*". Both were
accepted and on the books, and nothing reconciled them. Read literally the later
decision foreclosed the earlier one's catalog entry. Nothing broke only because
`source.rdb` is the sole registered paradigm.

Resolved in favour of ADR-0028, and generalized. Amendment 1 removes `event` and
replaces the implicit admission rule with an explicit test: a source binds
ADDRESSABLE STATE AT REST — readable on demand by a declared key or address, not
merely observed as it flows past.

The second half of that test is the load-bearing part. #212 proposed a two-prong
AND (addressable AND drift-inspectable as a schema), and swept across all twelve
paradigms it fails in both directions: it would ADMIT a schema-registry-backed
Kafka topic and EXCLUDE source.memory, while wrongly maiming document ($jsonSchema
optional), keyValue (Redis has none), objectStore (CSV), timeSeries (Prometheus)
and graph. So drift-inspectability is demoted to a per-paradigm verify capability
and is explicitly NOT an admission criterion. Under the single prong only event's
flow kinds fall; get-by-id generalizes to get-by-declared-key/address, so
keyValue composite keys, objectStore paths and timeSeries series+time all
qualify, as do vector and search (both expose fetch-by-id — similarity is the
query path, not the only read). The escape clause is recorded as principled: a
stream becomes a source exactly when it is treated as addressable state, so a
compacted changelog read by key enters as an ordinary read-only-@kind source.
What stays out is only the flow itself.

Amendment 2 records that @ROLE is a designation mechanism, not a routing one.
The Consequences section promised codegen and runtime would "route by @ROLE
(primary = CRUD; index/cache/publish = derived)". No port ever built it: across
all five, every read of @ROLE is an equality test against primary — Java's OMDB
has zero role usage, and Kotlin's KotlinGenUtil and Python's write-through read
path are explicitly documented role-agnostic, finding the replica by @kind. So
the registered vocabulary shrinks to primary | replica, with index/cache/publish/
mirror reserved-not-registered (the ADR-0040 treatment) and a stated re-entry
bar: a role member enters the registry only when a shipping consumer dispatches
on it. Also recorded: replica is structurally required despite no consumer
reading the word, because @ROLE defaults to primary and the one-primary
invariant rejects two primaries — a second source must carry an explicit
non-primary role or the model fails to load.

Docs only. ADR-0035 §1 excludes reserved-but-unregistered vocabulary from the
compat surface, so this does not reset the quiet-period clock. The @ROLE registry
change itself rides the #210 consolidation batch; the eventing surface rides
FR-024 to 1.1.

Synced: ADR-0028's channel clause now cites the ratification; ADR-0018's
per-paradigm example no longer teaches a removed paradigm; the source-v2 design
doc strikes the event row, the CDC/outbox example and the four reserved roles;
FR-024 §7's channel row references a projection rather than a value, landing the
symmetry — queries return projections, commands take values, events emit
projections.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S3msoGxjRMwx94PhKSLDuE

Author: dmealing

docs/superpowers/specs/2026-05-23-source-v2-paradigm-subtypes-multisource-design.md

@@ -2,6 +2,13 @@
 
 - **Date:** 2026-05-23
 - **Status:** Design — plan-of-record. Authority for the `source` metatype going forward.
+  **Amended 2026-08-05** ([#212](https://github.com/metaobjectsdev/metaobjects/issues/212), ADR-0007
+  Amendments 1–2): the **`event` paradigm is removed** (a stream is a channel, not a source — a
+  `source.*` binds **addressable state at rest**; emission moves to the surface layer as
+  `api.eventing`/`operation.event`/`binding.messaging` with a payload→**projection** reference), and
+  **`@role`'s registered vocabulary shrinks to `primary | replica`** (`index`/`cache`/`publish`/`mirror`
+  become reserved-not-registered; no port ever built the anticipated role-routing). The rows below
+  marked ~~struck~~ are retained for provenance — read ADR-0007 for the governing contract.
 - **Decision record:** [ADR-0007](../../../spec/decisions/ADR-0007-source-v2-paradigm-subtypes-multisource.md) (the durable contract); this spec is the detailed design + migration + rollout.
 - **Supersedes:** FR-003 / Project E `source.dbTable` / `source.dbView`.
 - **Related:** [ADR-0006](../../../spec/decisions/ADR-0006-reserved-keywords-vs-inline-attributes.md) (reserved keywords vs `@`-attrs — resolved here for `source`), ADR-0002 (subtype behavior), ADR-0004 (per-subtype attr schemas).
@@ -13,7 +20,7 @@
 
 A `source` declares **where an object's data physically lives**. Rules:
 
-1. **Subtype = storage paradigm** (`rdb`, `document`, `event`, …). The paradigm selects the
+1. **Subtype = storage paradigm** (`rdb`, `document`, `search`, …). The paradigm selects the
    codegen/runtime driver, so it's the behavioral axis (ADR-0002). Each subtype owns its
    attribute vocabulary (ADR-0004).
 2. **`name` = logical name** (optional on sources), consistent with every node (ADR-0006).
@@ -31,7 +38,7 @@ A `source` declares **where an object's data physically lives**. Rules:
 |--|--|--|--|--|
 | **rdb** | Postgres, MySQL, SQLite, SQL Server, Oracle | `@table` | table* · view · materializedView · storedProc · tableFunction | `@schema`, `@refresh`(matview), `@params`(proc/fn) |
 | **document** | MongoDB, CouchDB, Cosmos, Firestore | `@collection` | collection* · view · gridFs | `@database`, `@viewOn`+`@pipeline`(view) |
-| **event** | Kafka, Pulsar, Kinesis | `@topic` | topic* · stream · eventStore · changelog | `@keySchema`, `@valueSchema`, `@partitions`, `@compaction`, `@consumerGroup` |
+| ~~**event**~~ **REMOVED (#212)** | ~~Kafka, Pulsar, Kinesis~~ | ~~`@topic`~~ | ~~topic* · stream · eventStore · changelog~~ | A stream is a *channel*, not a source. Emission belongs to the surface layer (`binding.messaging` on an `operation.event`, payload → projection). A compacted changelog / event store read **by key** re-enters as an ordinary read-only-`@kind` paradigm source under the escape clause — it is addressable state at rest. |
 | **keyValue** | DynamoDB, Redis, etcd | `@table` / `@namespace` | table* · keyspace | `@partitionKey`, `@sortKey`, `@gsi`, `@ttl` |
 | **wideColumn** | Cassandra, ScyllaDB, Bigtable | `@table` | table* | `@keyspace`, `@partitionKey`, `@clusteringKey`, `@columnFamily` |
 | **graph** | Neo4j, Neptune, ArangoDB | `@label` / `@edge` | node* · relationship | `@from`, `@to` (relationship) |
@@ -79,7 +86,7 @@ The same per-subtype principle, one level down — a field's address *within* a
 | paradigm | field physical attr | notes |
 |--|--|--|
 | rdb / wideColumn / objectStore | `@column` | renames the old `@dbColumn` |
-| document / event / search / vector | `@field` | dotted path allowed (`name.first`) |
+| document / search / vector | `@field` | dotted path allowed (`name.first`) |
 | graph | `@property` | |
 | keyValue | `@attribute` | |
 | timeSeries | `@column` / `@tag` | Influx tag vs field distinction |
@@ -101,7 +108,8 @@ An object may declare multiple `source` children:
 { "object.entity": { "name": "Product", "children": [
   { "source.rdb":      { "@table": "products", "@schema": "catalog" } },     // primary (default), table
   { "source.search":   { "@index": "products_idx", "@role": "index" } },     // maintained on write
-  { "source.event":    { "@topic": "product.changed", "@role": "publish" } },// CDC / outbox
+  // REMOVED (#212): `source.event @role: publish` — a CDC/outbox topic is emission, not
+  // population. The outbox TABLE is an ordinary rdb source; the topic hop is a binding.
   { "source.keyValue": { "@namespace": "product:", "@role": "cache", "@ttl": 300 } }
   /* …fields… */
 ]}}
@@ -111,10 +119,15 @@ An object may declare multiple `source` children:
 |--|--|--|
 | `primary`* | system of record (may be read-only for a projection) | CRUD / canonical read |
 | `replica` | read copy (read replica, matview) | read routing |
-| `index` | search/vector index derived from primary | search queries; maintained on write |
-| `cache` | read-/write-through cache | cache get/set |
-| `publish` | event/stream sink (CDC, outbox, event-sourcing) | emit-on-write |
-| `mirror` | dual-write (migration) | parallel write |
+| ~~`index`~~ **RESERVED (#212)** | ~~search/vector index derived from primary~~ | Not registered — no consumer dispatches on it |
+| ~~`cache`~~ **RESERVED (#212)** | ~~read-/write-through cache~~ | Not registered — no consumer dispatches on it |
+| ~~`publish`~~ **RESERVED, not registered (#212)** | ~~event/stream sink (CDC, outbox, event-sourcing)~~ | Emission is a surface concern; see ADR-0007 Amendment 2. `index`/`cache`/`mirror` are likewise reserved-not-registered — no consumer in any port dispatches on them. |
+| ~~`mirror`~~ **RESERVED (#212)** | ~~dual-write (migration)~~ | Not registered — no consumer dispatches on it |
+
+**Registered vocabulary is `primary | replica` only** (ADR-0007 Amendment 2). The struck rows are
+reserved: documented here, not in the registry, re-entering only when a shipping consumer
+dispatches on them. The example above is therefore illustrative of the *paradigm* axis; its
+`@role: index` / `@role: cache` values are not currently loadable.
 
 **Validation:** exactly one `primary` per object (`ERR_SOURCE_NO_PRIMARY` / `ERR_SOURCE_MULTIPLE_PRIMARY`). Single-source objects need no `@role` (defaults to `primary`).
 

docs/superpowers/specs/2026-06-12-fr-024-entity-surfaces-projections-design.md

@@ -232,7 +232,7 @@ errors when it is **provably all-to-one** (every hop explicitly declares
 | `rdb @kind:table` | **entity** only | own, required |
 | `rdb @kind:view` / `materializedView` | **projection** (standalone) or **entity** (multi-source, read role) | borrowed / own |
 | `rdb @kind:storedProc` / `tableFunction` | result shape = **projection** (today spelled entity — migration candidate, §10); args = **value** via `@parameterRef` (shipped) | optional — result sets are often keyless |
-| *(future)* message topic / queue | **nobody** — a topic is a *channel*, not a population location; it belongs to the surface layer as `binding.messaging` on an operation referencing a value (AsyncAPI's model: channels reference message schemas) | n/a |
+| *(future)* message topic / queue | **nobody** — a topic is a *channel*, not a population location; it belongs to the surface layer as `binding.messaging` on an operation referencing a **projection** (AsyncAPI's model: channels reference message schemas). Ratified 2026-08-05 (#212 / ADR-0007 Amendment 1): an emitted event's shape is system-produced derived output, so the CQRS symmetry is *queries return projections, commands take values, **events emit projections***. A topic that is treated as addressable state (compacted changelog / event store read by key) re-enters as an ordinary read-only-`@kind` paradigm source. | n/a |
 | no source | **value** (embedded / payload / args) or **projection** (wire-only contract shape) | value: never; projection: optional |
 
 **Assembly modes.** Whether origins are *required* depends on the source:

spec/decisions/ADR-0007-source-v2-paradigm-subtypes-multisource.md

@@ -1,6 +1,9 @@
 # ADR-0007 — Source metatype v2: storage-paradigm subtypes, logical names, multi-source, per-subtype physical addresses
 
-**Status:** Accepted (proposed 2026-05-23; shipped in all five ports)
+**Status:** Accepted (proposed 2026-05-23; shipped in all five ports). **Amended 2026-08-05**
+([#212](https://github.com/metaobjectsdev/metaobjects/issues/212)) — see Amendments 1 and 2:
+`event` is removed from the paradigm catalog and replaced by an explicit admission test
+("addressable state at rest"), and `@role`'s registered vocabulary shrinks to `primary | replica`.
 
 **Supersedes:** the `source.dbTable` / `source.dbView` vocabulary introduced for FR-003
 (Project E, "Source-aware entities + projections"). Builds on ADR-0002 (subtype behavior on
@@ -35,19 +38,22 @@ treats the dialect/provider as runtime config and metadata as backend-agnostic.
 
 **Source v2** restructures the `source` metatype along four rules:
 
-1. **Subtype = storage paradigm**, not object kind: `source.{rdb, document, event, keyValue,
+1. **Subtype = storage paradigm**, not object kind: `source.{rdb, document, keyValue,
    wideColumn, graph, search, vector, timeSeries, objectStore, api, memory}`. The paradigm is the
    real behavioral axis (it selects the codegen/runtime driver — JOOQ/SQLAlchemy vs a document
-   ODM vs a Kafka client), so it belongs on the subtype per ADR-0002. Each paradigm owns its
+   ODM vs a search client), so it belongs on the subtype per ADR-0002. Each paradigm owns its
    attribute vocabulary per ADR-0004.
 
+   **Amended 2026-08-05 (#212): `event` is removed from the catalog** — see
+   *Amendment 1* below for the admission test that governs which paradigms belong here at all.
+
 2. **`name` = logical name (optional); physical address = a per-subtype idiomatic attribute**,
    at **both** the source and field level (ADR-0006-compliant; the physical name is never `@name`):
 
-   | level | rdb | document | event | graph | … |
+   | level | rdb | document | graph | search | … |
    |---|---|---|---|---|---|
-   | source physical | `@table` | `@collection` | `@topic` | `@label`/`@edge` | per paradigm |
-   | field physical | `@column` | `@field` | `@field` | `@property` | per paradigm |
+   | source physical | `@table` | `@collection` | `@label`/`@edge` | `@index` | per paradigm |
+   | field physical | `@column` | `@field` | `@property` | `@field` | per paradigm |
 
    `@dbColumn` is renamed **`@column`**. When a physical attr is omitted it is derived from the
    logical `name` via the naming strategy (today's column-naming behavior, generalized). Because
@@ -61,24 +67,96 @@ treats the dialect/provider as runtime config and metadata as backend-agnostic.
    the dominant noun.
 
 4. **Multi-source via `@role`.** An object may declare **N `source` children**; each carries
-   `@role` (default `primary`): `primary` (system of record; may be read-only for a projection),
-   `replica`, `index`, `cache`, `publish`, `mirror`. **Exactly one `primary`** per object. The
-   primary drives CRUD/canonical reads; secondaries drive derived behavior (index maintenance,
-   cache, event emission). Single-source objects are unchanged: one source, role defaults to
-   `primary`.
+   `@role` (default `primary`). **Exactly one `primary`** per object; the primary is the system of
+   record and drives CRUD/canonical reads. Single-source objects are unchanged: one source, role
+   defaults to `primary`.
+
+   **Amended 2026-08-05 (#212 sub-decision): the registered vocabulary is `primary | replica`** —
+   see *Amendment 2* below.
+
+## Amendment 1 (2026-08-05, #212) — the admission test: addressable state at rest
+
+ADR-0028 subsequently ruled that "message topics/queues are *channels*, not sources — they live at
+the surface layer as `binding.*` on operations, never in `source.*`", which contradicted this ADR's
+`source.event @topic @role: publish` catalog entry. Both were on the books. Resolved in favour of
+ADR-0028, and generalized into the test that governs the whole catalog:
+
+> A `source.*` binds an object to **addressable state at rest** — a place where a current value of
+> an instance can be read on demand by a declared key or address, not merely observed as it flows
+> past. **Drift-inspectability is NOT an admission criterion.** It follows per paradigm from
+> whatever schema authority the backend exposes (`information_schema`, index mapping, schema
+> registry, parquet footer) and may be absent entirely; it is a `verify` capability.
+
+The second sentence is load-bearing. A two-prong test requiring both addressability *and* a
+drift-inspectable schema fails in both directions: it would **admit** a schema-registry-backed Kafka
+topic (Confluent exposes key/value schemas) and **exclude** `source.memory` (nothing exists to drift
+against), while wrongly maiming `document` (`$jsonSchema` optional), `keyValue` (Redis has none),
+`objectStore` (parquet yes, CSV no), `timeSeries` (Timescale yes, Prometheus no) and `graph`.
+
+Under the single-prong test only **`event`'s flow kinds (topic / stream)** fall. "Get-by-id"
+generalizes to "get-by-declared-key/address", so composite keys (`keyValue`), paths
+(`objectStore`) and series+time (`timeSeries`) all qualify; `vector` and `search` qualify too, since
+both expose fetch-by-id (similarity is the *query* path, not the only read).
+
+**Escape clause — principled, not ad hoc:** *a stream becomes a source exactly when it is treated as
+addressable state.* A compacted changelog or event store read by key (KTable-style) enters as an
+ordinary read-only-`@kind` paradigm source. What stays out is only the **flow** itself; modeling a
+flow as storage is the category error. Windowed/stateful stream aggregation stays out
+**permanently** — it violates the determinism contract that a derivation is a pure function of the
+*current* entity graph, and is stream *processing*, not projection.
+
+**Where emission goes instead:** the surface layer (`api.eventing` / `operation.event` /
+`binding.messaging`, per ADR-0030), with the event's payload referencing an `object.projection`.
+This lands the symmetry — **queries return projections, commands take values, events emit
+projections** — and the projection concept still does all the shape work; only the exposure is a
+channel binding rather than a source.
+
+## Amendment 2 (2026-08-05, #212 sub-decision) — `@role` is a designation, not a routing mechanism
+
+The Consequences below say codegen and runtime "route by `@role` (primary = CRUD; index/cache/publish
+= derived)". **No port ever built that dispatch.** Across all five, every read of `@role` is an
+equality test against `primary`: Java's OMDB has zero role usage, and Kotlin's `KotlinGenUtil` and
+Python's write-through read path are explicitly documented *role-agnostic* — they find the replica
+view by read-only `@kind`. The consumed information content is one bit.
+
+Accordingly:
+
+- **Registered vocabulary shrinks to `primary | replica`.** `index`, `cache`, `publish` and `mirror`
+  are **reserved — documented here, NOT registered**, the same treatment ADR-0040 gave
+  `index.fulltext` / `index.vector` / `index.spatial`. (`publish` is additionally dead on doctrine:
+  emission is a surface concern per Amendment 1.)
+- **Re-entry bar:** *a role member enters the registry only when a shipping consumer dispatches on
+  it.* Registration did not summon the routing feature over the project's life; reserving costs a
+  future adopter one paragraph, and re-entry post-1.0 is additive whereas removal would be a 2.0
+  event.
+- **`replica` is structurally required**, despite no consumer reading the word: `@role` defaults to
+  `primary` when omitted and the one-primary invariant rejects two primaries, so a *second* source
+  must carry an explicit non-primary role or the model fails to load. The enum cannot shrink below
+  two members without redesigning the default.
+- **`@role` is not derivable** (so it survives ADR-0037 as a step-3 configuration attribute):
+  primacy is a tie-breaking *designation*, and `table(primary)` + `table(replica)` — two
+  same-writability sources — is legal and becomes inexpressible under any "the writable one is
+  primary" derivation.
+
+For consumer-meaningless author annotations about a source's purpose, the chartered home is the
+registered `attr.properties` bag (ADR-0023), not members of a byte-checked enum whose presence
+implies behavior that does not exist.
 
 ## Consequences
 
 - **Cross-language migration** (TS / C# / Java / Python): the loader subtype set changes
   (`dbTable`/`dbView` → `rdb` + `@kind`), `@name` → `@table`, `@dbColumn` → `@column`, and
   `@role` + multi-source validation (exactly one primary) are added.
 - **Codegen/runtime** stop dispatching read-only off the *subtype* and instead off **`@kind`**,
-  and stop assuming one source — they **route by `@role`** (primary = CRUD; index/cache/publish =
-  derived). Degrades gracefully: no secondaries ⇒ today's behavior.
+  and stop assuming one source — they select the primary by `@role` and everything else by
+  `@kind`. Degrades gracefully: no secondaries ⇒ today's behavior. *(As shipped, `@role` selects
+  only the primary; the "route by `@role`" routing this originally anticipated was never built —
+  see Amendment 2.)*
 - **Conformance corpus** migrates every `source.*` fixture; this also resolves the ADR-0006
   `source.@name` violation (the physical name moves to the non-reserved `@table`).
 - **Scope is staged.** Only `source.rdb` is implemented now (it covers everything FR-003 does);
-  the other ten paradigms are a validated roadmap, each built when a backend lands.
+  the other paradigms are a validated roadmap, each built when a backend lands — subject to the
+  Amendment 1 admission test.
 - **Back-compat:** `dbTable`/`dbView` documents stop loading. Intended — they are migrated in the
   shared corpus, and `source` is pre-1.0.
 

spec/decisions/ADR-0018-per-kind-physical-name-attrs.md

@@ -7,7 +7,7 @@
 
 ## Context
 
-ADR-0007 introduced the source-v2 paradigm and established the rule that the physical-address attribute is *per-paradigm-idiomatic*: `@table` for `source.rdb`, `@collection` for `source.document`, `@topic` for `source.event`, `@label`/`@edge` for `source.graph`. The Alternatives Considered section rejected a single generic `@locator` / `@map` attribute on the grounds that paradigms have genuinely different vocabularies and a multi-sourced field needs paradigm-specific addresses (`@column` for the rdb side, `@field` for the document side, simultaneously).
+ADR-0007 introduced the source-v2 paradigm and established the rule that the physical-address attribute is *per-paradigm-idiomatic*: `@table` for `source.rdb`, `@collection` for `source.document`, `@index` for `source.search`, `@label`/`@edge` for `source.graph`. The Alternatives Considered section rejected a single generic `@locator` / `@map` attribute on the grounds that paradigms have genuinely different vocabularies and a multi-sourced field needs paradigm-specific addresses (`@column` for the rdb side, `@field` for the document side, simultaneously).
 
 That per-paradigm principle is correct and is preserved here.
 

spec/decisions/ADR-0028-object-taxonomy-projection-value-purity.md

@@ -33,6 +33,11 @@ semantic lie.
    or by embedding; embedded VO storage belongs to the owning entity's field).
    Message topics/queues are *channels*, not sources — they live at the surface
    layer as `binding.*` on operations (AsyncAPI's model), never in `source.*`.
+   *(Ratified over ADR-0007's conflicting `source.event` catalog entry on
+   2026-08-05, [#212](https://github.com/metaobjectsdev/metaobjects/issues/212);
+   ADR-0007 Amendment 1 removes `event` and generalizes this into the admission
+   test — a source binds **addressable state at rest**, and a stream becomes a
+   source exactly when it is treated as addressable state.)*
 4. **Derived means read-only, at two levels:** any field carrying `origin.*` is
    derived and therefore read-only wherever it lives (on entities: excluded from
    INSERT/UPDATE, write codecs, and create/update inputs); a projection is wholly