fix(python): a view's currency reached the wire as a string; the TPH seam states the base-list obligation

Both found by running an adopter estate's Python port on the published rc6.

Currency. A table's field.currency column is BIGINT, which pg8000 hands back
as an int. A view's need not be: SUM over BIGINT is Postgres numeric, read
back as a Decimal, and a FastAPI route serializes a Decimal as a JSON string -
so a projection answered "totalRate": "100000" where the contract says
100000, while the entity routes beside it were right. ObjectManager's read
codec (_decode_read_value) now decodes an integral currency value to int
whatever the column type; a fractional one (an avg over minor units) has no
honest int and is returned as read. field.decimal keeps its Decimal.

TPH seam. The generated router returns whatever the consumer's repository
returns, and the natural repository - ObjectManager - reads a TPH base with
the base's columns only, which is the persistence contract in every port.
Wired together, GET /api/<base> lost every subtype field and nothing errored.
Not changing the runtime contract; the generated Protocol's docstring now
states that for subtype=None each row carries its own subtype's fields, and
how to get them. Generated output changes by that docstring only.

Verified: new runtime tests (5) + the seam test; Python codegen 585/0,
runtime 41/0, unit + query scenarios + return types 557/0. The estate's
Python port runs 43/43 on this build (42/43 on published rc6, the currency
scenario).

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

Author: dmealing

CHANGELOG.md

@@ -302,6 +302,26 @@ edit (two registered `description` strings) and was ruled a hold, as 1.0.4's was
   reference server and the Python in-memory seam ignored the filter and returned every row,
   and the TS reference server's allowlist gave the discriminator no operators.
 
+- **Python runtime: a `field.currency` read from a view answered as a JSON STRING, not
+  integer minor units.** A table's currency column is BIGINT, which the driver already hands
+  back as an `int`. A view's need not be: `SUM` over BIGINT is Postgres `numeric`, read back
+  as a `Decimal`, and a FastAPI route serializes a `Decimal` as a string — so
+  `GET /api/shipment_summaries` answered `"totalRate": "100000"` where the contract says
+  `100000`, while the entity routes beside it were right. The value's wire form depended on
+  the physical column type instead of the declared field. `ObjectManager`'s read codec now
+  decodes an integral currency value to `int` whatever the column type; a fractional one (an
+  `avg` over minor units) has no honest integer and is returned as read. Found by an adopter
+  estate's Python port once its read-only projection router existed (1.0.5's F22 fix).
+
+- **Python codegen: the generated TPH repository Protocol now states what the base
+  collection must return.** The router returns whatever the consumer's repository returns,
+  and the natural repository — `ObjectManager` — reads a TPH base with the base's columns
+  only (the persistence contract in every port). An adopter wiring one to the other served
+  `GET /api/<base>` with every subtype field missing and nothing erroring. The Protocol's
+  docstring now says that for `subtype=None` each row carries its OWN subtype's fields, and
+  how to get them. **Generated output changes (a docstring only)** — run `metaobjects gen`
+  to pick it up.
+
 - **Maven plugin: a relative `<sourceDir>` resolved against the shell's working directory,
   not the module.** The documented `<sourceDir>src/main/metaobjects</sourceDir>` therefore
   failed `SourceDir [src/main/metaobjects] does not exist` in any multi-module reactor build

server/python/src/metaobjects/codegen/generators/router_generator.py

@@ -937,7 +937,12 @@ def _render_tph_router(
         # Subtype-keyed repository Protocol (None == the polymorphic base).
         parts.append(f"class {repo_class}(Protocol):")
         parts.append('    """GENERATED — TPH seam. `subtype` is the @discriminatorValue, or None for')
-        parts.append('    the polymorphic base; the consumer scopes the single table accordingly."""')
+        parts.append('    the polymorphic base; the consumer scopes the single table accordingly.')
+        parts.append("")
+        parts.append("    For `subtype=None` the base collection is the discriminated union: each row")
+        parts.append("    carries its OWN subtype's fields, and `find_by_id(None, id)` likewise. The")
+        parts.append("    route returns what this returns. ObjectManager's base read projects only the")
+        parts.append("    base's columns, so read a base row through its own subtype entity.\"\"\"")
         parts.append("    def list(")
         parts.append("        self,")
         parts.append("        subtype: str | None,")

server/python/src/metaobjects/runtime/object_manager.py

@@ -903,10 +903,15 @@ def _int_value_map(field: MetaField) -> dict[Any, Any] | None:
 def _decode_read_value(field: MetaField, value: Any) -> Any:
     """Decode a stored value back to its authoring form on read.
 
-    The inverse of :func:`_coerce_write_value`'s int-backed-enum branch, and
-    today its only case: the column holds the member's integer, callers expect
-    the member SYMBOL. Every other field subtype is returned verbatim, keeping
-    ADR-0019's "runtime returns native in-process types" contract intact.
+    Two cases. The inverse of :func:`_coerce_write_value`'s int-backed-enum branch:
+    the column holds the member's integer, callers expect the member SYMBOL. And
+    ``field.currency``, whose native type is ``int`` minor units: a table column is
+    BIGINT and already reads back as an ``int``, but a VIEW column need not be —
+    ``SUM`` over BIGINT is Postgres ``numeric``, read back as a ``Decimal``, which a
+    FastAPI route then serializes as a JSON STRING. An integral ``Decimal`` is
+    decoded to ``int``; a fractional one (an ``avg`` over minor units) has no honest
+    ``int`` and is returned as read. Every other field subtype is returned verbatim,
+    keeping ADR-0019's "runtime returns native in-process types" contract intact.
 
     An int with no member RAISES. The database then holds a value the model says
     is impossible — a hand-written INSERT, or a member removed without a
@@ -918,6 +923,10 @@ def _decode_read_value(field: MetaField, value: Any) -> Any:
     """
     if value is None:
         return None
+    if field.sub_type == fc.FIELD_SUBTYPE_CURRENCY:
+        if isinstance(value, _decimal.Decimal) and value == value.to_integral_value():
+            return int(value)
+        return value
     if field.sub_type != fc.FIELD_SUBTYPE_ENUM:
         return value
     int_map = _int_value_map(field)

server/python/tests/codegen/test_tph_codegen.py

@@ -130,6 +130,18 @@ def test_base_router_polymorphic_plus_per_subtype(entities, index) -> None:
 # ---- filter allowlist: base folds in subtype-only filterable columns -------
 
 
+def test_base_seam_states_the_discriminated_union_obligation(entities, index) -> None:
+    # The router returns whatever the consumer's repository returns, and the natural
+    # repository — ObjectManager — reads a TPH BASE with the base's columns only (the
+    # persistence contract in every port). An adopter wiring one to the other served
+    # `GET /<base>` without any subtype field and nothing errored. The seam says so.
+    src = render_router(entities["Auth"], index)
+    assert src is not None
+    prose = " ".join(src.split())  # the docstring wraps; assert on its words
+    assert "each row carries its OWN subtype's fields" in prose
+    assert "ObjectManager's base read projects only the base's columns" in prose
+
+
 def test_base_allowlist_unions_subtype_fields(entities, index) -> None:
     src = render_filter_allowlist(entities["Auth"], index)
     assert src is not None

server/python/tests/runtime/test_object_manager_currency_read.py

@@ -0,0 +1,63 @@
+"""field.currency read decoding — the Python ObjectManager.
+
+Currency is integer minor units, natively and on the wire. A table column stores it as
+BIGINT, which pg8000 already hands back as an ``int``. A VIEW column need not: ``SUM`` over
+BIGINT is Postgres ``numeric``, which pg8000 hands back as a ``Decimal`` — and a ``Decimal``
+leaves a FastAPI route as the JSON STRING ``"100000"`` (Pydantic v2 serializes it that way),
+where the contract says the number ``100000``. So the value's wire form depended on the
+physical column type rather than on the declared field. The read codec now decodes an
+integral currency value to ``int`` whatever the column's type.
+"""
+from __future__ import annotations
+
+from decimal import Decimal
+
+from metaobjects.loader.meta_data_loader import MetaDataLoader
+from metaobjects.loader.sources import InMemoryStringSource
+from metaobjects.runtime.object_manager import _decode_read_value
+
+MODEL = """{"metadata.root": {"package": "acme", "children": [
+  {"object.entity": {"name": "Leg", "children": [
+    {"source.rdb": {"@table": "legs"}},
+    {"field.long": {"name": "id"}},
+    {"field.currency": {"name": "rate", "@currency": "USD"}},
+    {"field.decimal": {"name": "weight", "@precision": 10, "@scale": 2}},
+    {"identity.primary": {"name": "pk", "@fields": "id", "@generation": "increment"}}
+  ]}}
+]}}"""
+
+
+def _field(name: str):
+    result = MetaDataLoader().load([InMemoryStringSource(MODEL, "test.json")])
+    assert result.errors == []
+    leg = next(c for c in result.root.children() if c.name == "Leg")
+    return next(f for f in leg.fields() if f.name == name)
+
+
+def test_integral_decimal_currency_decodes_to_int_minor_units() -> None:
+    value = _decode_read_value(_field("rate"), Decimal("100000"))
+    assert value == 100000
+    assert type(value) is int
+
+
+def test_int_currency_is_unchanged() -> None:
+    value = _decode_read_value(_field("rate"), 1099)
+    assert value == 1099
+    assert type(value) is int
+
+
+def test_null_currency_stays_null() -> None:
+    assert _decode_read_value(_field("rate"), None) is None
+
+
+def test_fractional_decimal_currency_is_left_alone() -> None:
+    # An avg over minor units can be fractional; no int is honest, so the value is
+    # returned as read rather than silently rounded.
+    value = _decode_read_value(_field("rate"), Decimal("12.5"))
+    assert value == Decimal("12.5")
+
+
+def test_field_decimal_keeps_its_decimal() -> None:
+    value = _decode_read_value(_field("weight"), Decimal("12.50"))
+    assert value == Decimal("12.50")
+    assert type(value) is Decimal