docs(adr): ADR-0001 cross-language type binding; record FR-003 jsonb POJO + binding decisions

Establish spec/decisions/ ADR practice. ADR-0001: build-time, domain-sliced, FQN-keyed binding (OO=ServiceLoader registry, data-oriented=static imports), never runtime reflection. CLAUDE.md gets the durable rule + ADR pointer. FR-003 updated: jsonb = typed mutable POJOs (always-reserialize-on-update, ValueObject fallback); new binding-registry capability per ADR-0001.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: dmealing

CLAUDE.md

@@ -423,6 +423,10 @@ These are the load-bearing principles that have emerged through implementation.
 
 - **"Validated by spike" ≠ "right design".** A spike proves a technique works under a specific test. It doesn't prove it is the best production choice. Always ask "what's the UX cost?" alongside "does this work?"
 
+- **Bind metadata→native types at build time, never runtime reflection.** Resolving an object's native class/module from its FQN must happen in generated code (static imports for data-oriented ports; a domain-sliced, FQN-keyed registry for OO ports), not via `Class.forName`/`Type.GetType`/`importlib` — runtime reflection is impossible in TS and breaks under GraalVM native-image / .NET AOT. See [ADR-0001](spec/decisions/ADR-0001-cross-language-type-binding.md).
+
+- **Record significant cross-cutting decisions as ADRs.** Durable, cross-language/cross-feature architectural contracts live in `spec/decisions/` (Nygard format). Consult them before changing a cross-language contract; add a new ADR when you make one. Feature-level decisions stay in the FR spec; this file holds only the one-line rule + the pointer.
+
 ## Coding discipline (TS)
 
 - **Named constants for metamodel strings — always.** Type names, subtype names, reserved JSON keys, special attribute names, structural separators, and wildcards live in `packages/metadata/src/constants.ts` — import and use them. Gets you compile-time typo safety.

docs/superpowers/specs/2026-05-22-fr-003-omdb-persistence-schema-migration-projections-design.md

@@ -50,19 +50,19 @@ The required modules — `metadata`, `core`, `codegen-*`, `maven-plugin`, `core-
 ### 2. Spring-transaction-aware connection
 `ObjectConnectionDB(Connection)` already accepts an externally-owned connection. Ship (likely in `metaobjects-core-spring`) a thin adapter that wraps `DataSourceUtils.getConnection(dataSource)` and does **not** close the connection (Spring owns the lifecycle), so OMDB operations join the caller's active `@Transactional` scope — including `REQUIRES_NEW` and pessimistic boundaries. No second, out-of-transaction connection.
 
-### 3. jsonb fields modelled as value objects (opt-in)
-A jsonb column may be either opaque JSON **or** declare a nested MetaObject as its value type:
+### 3. jsonb fields modelled as typed value objects (opt-in)
+A jsonb column may be either opaque JSON **or** declare a nested MetaObject as its value type. When modelled, the value is a **code-generated, mutable, typed POJO** (the default — real objects, IDE/type-safe), with `ValueObject` (the dynamic Map container) as the **fallback** for intentionally-open/dynamic shapes:
 
 ```jsonc
 // opaque
 { "field.object": { "name": "rawConfig", "@dbColumn": "raw_config", "@dbType": "jsonb" }}
 
-// modelled — value is a (list/map of) ValueObject(s)
+// modelled — value is a generated typed POJO (list/map per cardinality)
 { "field.object": { "name": "dispositions", "@dbColumn": "dispositions",
     "@dbType": "jsonb", "@objectRef": "Disposition", "@isArray": true, "@keyedBy": "subjectId" }}
 ```
 
-`PostgresDriver` gains a jsonb column type + a Jackson-backed value converter that reads the field's referenced MetaObject to (de)serialize `ValueObject` ⇄ jsonb. Cardinality via `@isArray` (List) and optional `@keyedBy` (Map). This shares one modelling path with projections (below).
+`PostgresDriver` gains a jsonb column type + a Jackson-backed converter that resolves the field's referenced MetaObject to its **bound Java class** (via the binding registry, §8 / ADR-0001) and (de)serializes the typed POJO ⇄ jsonb; cardinality via `@isArray` (`List<T>`) and optional `@keyedBy` (`Map<K,T>`); `ValueObject` when no class is bound. **Mutability matters:** these objects are read-modify-write (e.g. `realm.getMechanics().setX(…)`), not read-only DTOs — so generated jsonb value types are **mutable POJOs**, not immutable records. Because in-place mutation leaves the parent's field reference unchanged (so OMDB's dirty-field check can't detect it), **jsonb fields are always (re)serialized on `updateObject`** (deep-compare is a later optimization). This shares one modelling path with projections (below).
 
 ### 4. Metadata-driven schema migration (decoupled `meta migrate`)
 Extend `MetaClassDBValidatorService` + drivers from *create-if-missing* to a **diff-and-converge** engine: add tables/columns/indexes/FKs/sequences/views and additive ALTERs (widen type, add nullable/defaulted column). Surface it through a cross-language-aligned verb set, **not** as boot-time auto-apply:
@@ -78,11 +78,14 @@ A consuming app adopts its existing schema as the baseline; metadata must reprod
 A projection is `object.value`/`object.entity` + `source.dbView`, with fields carrying `origin.passthrough` (cross-entity ref) or `origin.aggregate` (`count`/`sum`/`avg`/`min`/`max` via dotted `@via`/`@of`). OMDB already creates views from `ViewDef` and verifies read mappings; add the **origin→`CREATE VIEW` SQL deriver** so view SQL is generated when expressible, falling back to explicit `dbViewSQL` only when it is not. Projection results materialize as `ValueObject`s (the same container used for opaque/value-object reads), so consumers can blend projected DB data with app-side values.
 
 ### 6. Codegen templates
-Mustache templates/generators (build-time, via the maven-plugin) for: entity base classes (POJO mapped via `PojoMetaObject`, no business logic), per-entity SQL-name constants (`Tables`/`Columns` — keep residual native SQL rename-safe + drift-checkable), projection value-object classes, and an OMDB-backed repository base (CRUD via `Expression`/`QueryOptions`; advanced queries via `dbViewSQL`/`executeQuery`). Generated artifacts carry no business logic; consumers extend them.
+Mustache templates/generators (build-time, via the maven-plugin) for: entity base classes (POJO mapped via `PojoMetaObject`, no business logic), per-entity SQL-name constants (`Tables`/`Columns` — keep residual native SQL rename-safe + drift-checkable), **typed mutable jsonb value-object POJOs** (§3), projection value-object classes, an OMDB-backed repository base (CRUD via `Expression`/`QueryOptions`; advanced queries via `dbViewSQL`/`executeQuery`), and **one `MetaDataTypeProvider` per generated package that registers its `FQN → class` bindings** (§8 / ADR-0001), `ServiceLoader`-discovered. Generated artifacts carry no business logic; consumers extend them.
 
 ### 7. Conformance fixtures
 Extend the existing `source-*`/`origin-*` corpus to cover the new vocabulary surfaced here (`@generation`, `@previousName`, jsonb value-object fields, projection origin→view derivation at the **metamodel** level). A full migration-output conformance corpus (byte-identical SQL across languages) is flagged **future** (consistent with the C# design); v1 asserts vocabulary + loader/serializer parity and diff *determinism* per language.
 
+### 8. Metadata→Java-class binding registry (per ADR-0001)
+OMDB instantiates **typed objects** — entities, jsonb value-objects (§3), and projection results — by resolving a MetaObject's FQN to its concrete Java class. Per **[ADR-0001](../../../spec/decisions/ADR-0001-cross-language-type-binding.md)**, this is a **build-time, domain-sliced, FQN-keyed registry — never runtime reflection** (`Class.forName` is AOT/native-image-hostile; the cross-language contract forbids it). Java realization: codegen emits **one `MetaDataTypeProvider` per generated package** that registers its `FQN → Class` bindings; `ServiceLoader` discovers and merges them across packages/jars (the same mechanism core already uses for its 8 type providers). OMDB consults the merged registry to pick the class for `newInstance()`/jsonb deserialization, falling back to `ValueObject` when no class is bound. This FR builds the **runtime registry contract** (the registry API + OMDB consulting it, tested with hand-registered bindings); the codegen that *emits* the per-package providers ships with the codegen templates (§6). The deferred metadata overlay (`@object` FQN map) is replaced by this generated, compile-checked registration — and never reappears as a hand-maintained file.
+
 ## Versioning & compatibility
 
 `6.x → 7.0.0`, by SemVer (and OSGi semantic versioning, since the project ships bundles): a major bump is mandated by **breaking public-API changes**, regardless of how much additive work rides along.

spec/decisions/ADR-0001-cross-language-type-binding.md

@@ -0,0 +1,57 @@
+# ADR-0001 — Cross-language metadata→native-type binding
+
+**Status:** Accepted — 2026-05-22
+**Applies to:** all language ports (TS, Java, Python, C#)
+**Related:** the OMDB persistence work (`docs/superpowers/specs/2026-05-22-fr-003-*`); `spec/metamodel.md`; `spec/conformance-tests.md`
+
+## Context
+
+Metadata is **language-agnostic**: an object is identified by a fully-qualified name (FQN) like `myapp::commerce::Program`. At runtime and/or codegen time, each language must bind that FQN to its native representation — the generated class to instantiate (OO ports), or the generated module/schema to use (data-oriented ports). The question is *how*, in a way that is consistent across languages, survives modern toolchains, and doesn't pollute the metadata.
+
+Three naive approaches fail:
+
+- **Runtime reflection by name** (`Class.forName` / `Type.GetType` / `importlib`): impossible in TS/JS (no runtime "class from string" reflection), and increasingly broken in Java/C# by **GraalVM native image** and **.NET Native AOT / trimming**, which remove reflection at build time. The industry is actively moving *away* from this (Spring AOT generates reflection-free hints; `System.Text.Json` requires source generators and lets you disable reflection entirely).
+- **A single global registry**: doesn't scale — codegen runs **per package/domain/target**, often into separate artifacts/jars; one monolithic registry can't be assembled from independently-generated slices.
+- **A hand-maintained (or generated-JSON) metadata overlay** mapping FQN→class: drifts from the code, pollutes the language-agnostic metadata with per-language class paths, and is only validated at runtime.
+
+Industry precedent (cross-language schema tools): **Protobuf** uses a `TypeRegistry` keyed by FQN/type-URL, populated by **generated code in each `.proto`'s output that self-registers** (`proto.RegisterType`, etc.). **gRPC** emits **per-service** registration that composes at startup. **Jackson** prefers explicit `@JsonSubTypes` over reflection scanning. **class-transformer** (TS) requires explicit discriminator maps because TS has no reflection. **SQLAlchemy** centers a `registry` construct that declarative and imperative mapping both populate.
+
+## Decision
+
+**Resolve the binding at build/codegen time, in generated code — never via runtime reflection.** The binding is keyed by the canonical metadata FQN and is **domain-sliced and composable** (each codegen unit contributes its own bindings; the runtime aggregates them). The realization is idiomatic per language paradigm:
+
+| Paradigm | Realization | Discovery / composition |
+|---|---|---|
+| **Data-oriented** (TS) | generated **static imports** (convention: namespace→file path) + lookup by name in the loaded metadata tree; **no registry object** (codegen emits plain types + schemas, not OO classes) | barrel re-export; the metadata tree *is* the runtime registry |
+| **OO** (Java / C# / Python) | generated, **domain-sliced registration** into an **FQN-keyed runtime registry** (typed objects are instantiated, so build-time static imports alone can't provide runtime polymorphic instantiation) | **Java:** one `MetaDataTypeProvider` **per generated package**, auto-discovered + merged via `ServiceLoader`. **C#:** source-generated registration per assembly via a module initializer (AOT-safe). **Python:** per-package registration at import / entry-points. |
+
+The **durable contract** (conformance-describable) is: *the binding key is the metadata FQN, it is established in generated code at build time, and it is composable across independently-generated slices.* The **realization is idiomatic** per language (matching the project's "durable contract identical; runtime surface idiomatic" rule).
+
+The language-agnostic metadata holds **no** native class paths. Any one-off divergence from convention is expressed as an inline `@object` attribute on a single MetaObject — never a whole overlay file.
+
+## Consequences
+
+**Positive**
+- Compile/type-checked in TS/Java/C# (rename a class → the generated registration won't compile); import-checked in Python. Drift caught at build, not runtime.
+- **AOT / native-image safe** (no runtime reflection-by-name).
+- **Domain-sliced & composable** — multi-package/multi-jar codegen each contributes a registration unit; the runtime composes them (Java `ServiceLoader` is purpose-built for exactly this; it already loads core's type providers).
+- Metadata stays language-agnostic; no driftable overlay.
+- Matches what the TS port already ships (this ADR validates and generalizes existing behavior, it does not re-architect it).
+
+**Negative / costs**
+- OO ports emit one small registration unit per codegen slice (a generated artifact). This is folded into the per-target codegen output already produced, and is the same model protobuf/gRPC use, so the cost is minimal and idiomatic.
+- The runtime needs a registry abstraction + a discovery hook per language (a one-time investment per port).
+
+## Alternatives considered (rejected)
+1. **Runtime reflection / convention-by-name** — impossible in TS; AOT/native-image-hostile in Java/C#. Rejected as a *universal* mechanism (it remains available only as a per-language optimization where reflection is acceptable).
+2. **Single global registry** — can't be assembled from independently-generated package slices.
+3. **Generated/maintained metadata overlay (FQN→class JSON)** — driftable, runtime-only checking, pollutes language-agnostic metadata.
+
+## Realization status
+- **TS** — shipped (data-oriented: static imports + metadata-tree lookup; no registry object needed).
+- **Java** — in the OMDB persistence work: per-package `MetaDataTypeProvider` registry via `ServiceLoader`, consulted by ObjectManagerDB to instantiate entities and typed jsonb value-objects.
+- **C#** — future runtime work: source-generated registration per assembly.
+- **Python** — post-H3.
+
+## Conformance note
+Runtime instantiation APIs are out of byte-identical conformance scope (per `spec/conformance-tests.md` — runtime surface is idiomatic). What is conformance-relevant is the **key**: the canonical FQN form (`pkg::Name`) used as the registry key, which the loader/serializer corpus already pins.

spec/decisions/README.md

@@ -0,0 +1,21 @@
+# Architecture Decision Records (ADRs)
+
+This directory records **significant, cross-cutting architectural decisions** for the MetaObjects standard — the durable "why" that outlives any single feature spec.
+
+## What goes here vs. elsewhere
+
+| Doc type | Location | Scope |
+|---|---|---|
+| **ADR** | `spec/decisions/` *(here)* | Durable, **cross-cutting, target-agnostic** contracts that bind multiple language ports (e.g. how metadata→native types are bound; the conformance model; persistence-engine choice). |
+| Feature design (FR spec) | `docs/superpowers/specs/` | A single feature's design, language- or area-scoped. |
+| Implementation plan | `docs/superpowers/plans/` | Task-by-task execution of a feature. |
+| Conventions / pointers | `CLAUDE.md` | Lean, always-loaded context: durable one-liners + pointers here. |
+
+## When to write an ADR
+Write one when a decision is **cross-cutting** (affects more than one language port or more than one feature) and **durable** (future work must respect it). Examples: a metamodel binding contract, the wire-format guarantee, "migrations decoupled from the runtime." Do **not** write ADRs for feature-level or easily-reversible choices — those live in the FR spec.
+
+## Format
+[Michael Nygard's ADR format](https://github.com/joelparkerhenderson/architecture-decision-record): **Context → Decision → Consequences → Status**, plus *Alternatives considered* and *Realization status* where useful. One decision per file. Status is `Proposed` | `Accepted` | `Superseded by ADR-NNNN`. Numbered sequentially; never renumber (supersede instead).
+
+## Index
+- [ADR-0001 — Cross-language metadata→native-type binding](ADR-0001-cross-language-type-binding.md) — *Accepted*