test(api-contract): cross-port gate for jsonb open-bag parsed-value contract (#98) (#110)

New isolated `jsonb/` sub-corpus under fixtures/api-contract-conformance/
(peer of m2m/ and tph/): a single `Document` entity with a
`field.string @dbColumnType:jsonb` open bag. The scenario POSTs records whose
jsonb field holds a JSON object (and an object whose value is an array), reads
them back, and asserts the field is the parsed object/array — NOT a
JSON-encoded string. Locks in the API-boundary half of the #98 contract that
was only gated per-port before (the persistence corpus gates the runtime wire
form, not the generated DTO/validator accepting a posted object).

Wired + run green in BOTH lanes for:
  - TypeScript: hand-rolled reference (ObjectManager) + GENERATED routes
    (runGen → emitted Document.routes.ts) over Postgres testcontainers.
  - Python: hand-rolled reference (FastAPI + pg8000) over a Postgres
    testcontainer + GENERATED router (render_router) with an in-memory seam.

Real finding the gate surfaced (runtime-ts): ObjectManager.create rejected an
object written to a `field.string @dbColumnType:jsonb` open bag — the
write-path validator type-checked it as a string, contradicting the write-side
coercer (serializeJsonbColumns), which already expects an object and
JSON.stringifies it. The #98 fix had covered codegen (Zod `unknown`) and the
read-side coercer but missed the runtime write-path validator. Fixed minimally:
validator-runner skips the string type/length checks for an open-bag
jsonb-columned string field (required-ness still applies). The generated API
lane was already green; the runtime reference lane caught the gap.

Deferred (corpus is ready, follow-up tracked in #98): Java, Kotlin, C#. Their
api-contract harnesses bind the per-entity DTO shape statically (the JVM
generated harness reflects a fixed Author constructor arity + ships a
hand-written in-memory repo source; the C# generated lane is full-stack EF +
Kestrel), so adding the Document entity means a new reference server +
generated harness per port (mirroring their m2m/ and tph/ harnesses) rather
than a focused fixture edit. The sub-corpus is isolated, so those ports' runners
do not discover jsonb/ and stay green.


Claude-Session: https://claude.ai/code/session_01LuZWKnWzYGVnESijL7uuky

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: dmealing

fixtures/api-contract-conformance/jsonb/README.md

@@ -0,0 +1,78 @@
+# `api-contract-conformance/jsonb/` — jsonb open-bag parsed-value corpus
+
+Cross-port REST contract for the **`field.string @dbColumnType:jsonb` open
+JSON bag** at the API boundary. The field is a bare jsonb column that may hold
+*any* JSON value; the contract is that a client POSTs a JSON **object** to it
+and reads back the same **object** — never a JSON-encoded **string**
+(`"{\"k\":\"v\"}"`).
+
+This closes a real gap: the persistence-conformance corpus
+(`queries/asset-uuid-roundtrip.yaml`) gates the runtime/ORM **wire** form of a
+jsonb column, but nothing gated that each port's **generated DTO/validator +
+controller** accept a posted object and surface a parsed value over HTTP. Each
+port already carries the fix on `main` (TS `z.unknown()`, Python `Any`,
+Java `Object`, Kotlin `JsonElement`, C# `JsonDocument`); this corpus locks it
+in cross-port.
+
+The single `Document` entity (`acme::store`, `@table="documents"`) carries one
+open-bag field:
+
+| Field     | Type                              | Notes                       |
+|-----------|-----------------------------------|-----------------------------|
+| `id`      | `field.long`                      | `identity.primary @generation=increment` |
+| `title`   | `field.string`                    | `@required` + `@maxLength 200` |
+| `payload` | `field.string @dbColumnType=jsonb`| open JSON bag — parsed value over the wire |
+
+`source.rdb @table="documents"` → the URL segment is `/api/documents`
+(lowercased + pluralized), per the cross-port grammar.
+
+## Files
+
+```
+jsonb/
+├── README.md              # this file
+├── meta.json              # the Document entity
+├── seed.json              # 2 seed Documents (ids 1, 2), each with a jsonb object
+└── scenarios/
+    └── jsonb-open-bag-roundtrip.yaml
+```
+
+`seed.json` is applied fresh before the scenario; the runner advances the id
+sequence past `max(id)` so the next implicit-id POST lands at id 3 (then 4),
+mirroring the single-entity `create-201` contract.
+
+## Scenario
+
+`jsonb-open-bag-roundtrip.yaml` exercises both read and write of the open bag:
+
+| Request | What it pins |
+|---|---|
+| `r1` GET `/api/documents/1` | a **seeded** jsonb object reads back as an object |
+| `r2` POST `/api/documents` | the generated validator accepts a posted nested object; the create echo is an object |
+| `r3` GET `/api/documents/3` | the persisted value reads back as the same object |
+| `r4` POST `/api/documents` | jsonb holds any JSON — an object whose values include an **array** |
+| `r5` GET `/api/documents/4` | the array-bearing structure reads back parsed (never a string) |
+
+The `body.row` assertion deep-equals each listed key with **sorted-key**
+normalization (the corpus's existing canonical form), so the gate is
+object-vs-string and structure-preserving — it does not pin jsonb key order.
+A regressed port that returned `"{\"k\":\"v\"}"` (a string) instead of
+`{"k":"v"}` (an object) fails here.
+
+## Per-port wiring status
+
+Both lanes (hand-rolled reference server + the GENERATED routes/controller
+booted over HTTP) are wired and green for:
+
+- **TypeScript** — reference (`ObjectManager`) + generated (`runGen` →
+  emitted `Document.routes.ts` over Postgres testcontainer).
+- **Python** — reference (FastAPI + pg8000 over Postgres testcontainer) +
+  generated (`render_router` emitted router + in-memory seam).
+
+Deferred (corpus is ready; follow-up): **Java**, **Kotlin**, **C#**. Their
+api-contract harnesses bind the per-entity DTO shape statically (the JVM
+generated harness reflects a fixed `Author` constructor arity + ships a
+hand-written in-memory repo source; the C# generated lane is full-stack EF +
+Kestrel), so adding the `Document` entity means a new reference server +
+generated harness per port (mirroring their `m2m/` and `tph/` sub-corpus
+harnesses) rather than a focused fixture edit. Tracked in #98.

fixtures/api-contract-conformance/jsonb/meta.json

@@ -0,0 +1,17 @@
+{
+  "metadata.root": {
+    "package": "acme::store",
+    "children": [
+      { "object.entity": {
+        "name": "Document",
+        "children": [
+          { "source.rdb":       { "@table": "documents" } },
+          { "field.long":       { "name": "id", "@filterable": true, "@sortable": true } },
+          { "field.string":     { "name": "title", "@required": true, "@maxLength": 200, "@filterable": true, "@sortable": true } },
+          { "field.string":     { "name": "payload", "@dbColumnType": "jsonb" } },
+          { "identity.primary": { "name": "id", "@fields": "id", "@generation": "increment" } }
+        ]
+      }}
+    ]
+  }
+}

fixtures/api-contract-conformance/jsonb/scenarios/jsonb-open-bag-roundtrip.yaml

@@ -0,0 +1,79 @@
+name: jsonb-open-bag-roundtrip
+description: >
+  The `field.string @dbColumnType:jsonb` open-JSON-bag contract over HTTP: a
+  client POSTs a record whose jsonb field holds a JSON OBJECT and reads it back
+  as the same OBJECT — NOT a JSON-encoded string. This pins the API-boundary
+  half of the contract that the per-port fixes establish (TS `z.unknown()`,
+  Python `Any`, Java `Object`, Kotlin `JsonElement`, C# `JsonDocument`): the
+  generated DTO/validator must accept a posted object and the read path must
+  surface a parsed value, not a stringified `"{\"k\":\"v\"}"`.
+
+  Two seed rows (ids 1, 2) carry jsonb objects (read path); the next implicit-id
+  POST lands at id 3, the one after at id 4 (the seed runner advances the
+  sequence past max(id), mirroring the create-201 contract). Coverage:
+    - r1: GET a SEEDED row → jsonb object read back as an object.
+    - r2/r3: POST a nested object + GET it back → object on both write-echo and
+             persisted read.
+    - r4/r5: POST an object whose values include an ARRAY (jsonb holds any JSON)
+             + GET it back → structure preserved, parsed (never a string).
+requests:
+  - id: r1
+    method: GET
+    path: /api/documents/1
+    expect:
+      status: 200
+      body:
+        row:
+          id: 1
+          title: "alpha"
+          payload: { seeded: true, n: 1 }
+
+  - id: r2
+    method: POST
+    path: /api/documents
+    body:
+      title: "gamma"
+      payload: { k: "v", n: 1, nested: { deep: true }, list: [1, 2, 3] }
+    expect:
+      status: 201
+      body:
+        hasId: true
+        row:
+          title: "gamma"
+          payload: { k: "v", n: 1, nested: { deep: true }, list: [1, 2, 3] }
+
+  - id: r3
+    method: GET
+    path: /api/documents/3
+    expect:
+      status: 200
+      body:
+        row:
+          id: 3
+          title: "gamma"
+          payload: { k: "v", n: 1, nested: { deep: true }, list: [1, 2, 3] }
+
+  - id: r4
+    method: POST
+    path: /api/documents
+    body:
+      title: "delta"
+      payload: { items: [{ x: 1 }, { y: 2 }], flag: false }
+    expect:
+      status: 201
+      body:
+        hasId: true
+        row:
+          title: "delta"
+          payload: { items: [{ x: 1 }, { y: 2 }], flag: false }
+
+  - id: r5
+    method: GET
+    path: /api/documents/4
+    expect:
+      status: 200
+      body:
+        row:
+          id: 4
+          title: "delta"
+          payload: { items: [{ x: 1 }, { y: 2 }], flag: false }

fixtures/api-contract-conformance/jsonb/seed.json

@@ -0,0 +1,6 @@
+{
+  "rows": [
+    { "id": 1, "title": "alpha", "payload": { "seeded": true, "n": 1 } },
+    { "id": 2, "title": "beta",  "payload": { "k": "v" } }
+  ]
+}

server/python/tests/integration/api_contract_jsonb_server.py

@@ -0,0 +1,160 @@
+"""Hand-rolled reference FastAPI app for the ``Document`` entity from the
+``api-contract-conformance/jsonb/`` corpus.
+
+The contract under test is the ``field.string @dbColumnType:jsonb`` open bag:
+a posted JSON object must round-trip as an object (never a JSON-encoded
+string). Pared down from ``api_contract_server.py`` (the Author reference) —
+the jsonb scenario only POSTs + GETs by id, so this server implements just
+those verbs.
+
+Backend: pg8000 (pure-python DB-API; same driver as ``api_contract_server.py``).
+``payload`` is a bare ``JSONB`` column — the open bag holds any JSON value.
+pg8000 auto-decodes jsonb to a native Python object on read; on write the
+value is ``json.dumps``-serialized and bound with a ``::jsonb`` cast.
+"""
+from __future__ import annotations
+
+import json
+from contextlib import closing
+from typing import Any
+
+import pg8000.dbapi as pg8000
+from fastapi import FastAPI, Request, status
+from fastapi.responses import JSONResponse
+
+from .postgres_container import PostgresInfo
+
+
+class DocumentRepository:
+    """Direct-JDBC-equivalent repo against the test Postgres instance."""
+
+    def __init__(self, info: PostgresInfo) -> None:
+        self._info = info
+
+    def create_schema(self) -> None:
+        self._exec(
+            'CREATE TABLE IF NOT EXISTS "documents" ('
+            "    id BIGSERIAL PRIMARY KEY,"
+            "    title VARCHAR(200) NOT NULL,"
+            "    payload JSONB"
+            ")"
+        )
+
+    def truncate(self) -> None:
+        self._exec('TRUNCATE TABLE "documents" RESTART IDENTITY')
+
+    def apply_seed(self, rows: list[dict[str, Any]]) -> None:
+        """Insert seed rows with explicit ids, then bump the sequence so the
+        next implicit-id POST lands at max(id) + 1 (the GET-after-POST
+        contract relies on a deterministic id)."""
+        self.truncate()
+        with closing(self._connect()) as conn:
+            cur = conn.cursor()
+            try:
+                for r in rows:
+                    cur.execute(
+                        'INSERT INTO "documents" (id, title, payload) '
+                        "VALUES (%s, %s, %s::jsonb)",
+                        (int(r["id"]), r["title"], _dump_payload(r.get("payload"))),
+                    )
+                cur.execute(
+                    "SELECT setval(pg_get_serial_sequence('documents', 'id'), "
+                    "COALESCE((SELECT MAX(id) FROM documents), 1))"
+                )
+                conn.commit()
+            finally:
+                cur.close()
+
+    def find_by_id(self, ident: int) -> dict[str, Any] | None:
+        with closing(self._connect()) as conn:
+            cur = conn.cursor()
+            try:
+                cur.execute(
+                    'SELECT id, title, payload FROM "documents" WHERE id = %s',
+                    (int(ident),),
+                )
+                row = cur.fetchone()
+                return _row_to_dict(row) if row is not None else None
+            finally:
+                cur.close()
+
+    def create(self, dto: dict[str, Any]) -> dict[str, Any]:
+        with closing(self._connect()) as conn:
+            cur = conn.cursor()
+            try:
+                cur.execute(
+                    'INSERT INTO "documents" (title, payload) '
+                    "VALUES (%s, %s::jsonb) RETURNING id",
+                    (dto.get("title"), _dump_payload(dto.get("payload"))),
+                )
+                new_id = int(cur.fetchone()[0])
+                conn.commit()
+            finally:
+                cur.close()
+        created = self.find_by_id(new_id)
+        if created is None:
+            raise RuntimeError("create: row vanished between INSERT and SELECT")
+        return created
+
+    def _connect(self) -> Any:
+        return pg8000.connect(
+            host=self._info.host,
+            port=self._info.port,
+            user=self._info.user,
+            password=self._info.password,
+            database=self._info.database,
+        )
+
+    def _exec(self, sql: str) -> None:
+        with closing(self._connect()) as conn:
+            cur = conn.cursor()
+            try:
+                cur.execute(sql)
+                conn.commit()
+            finally:
+                cur.close()
+
+
+def make_jsonb_app(repo: DocumentRepository) -> FastAPI:
+    app = FastAPI()
+
+    @app.exception_handler(404)
+    async def _default_404(_req: Request, _exc: Any) -> JSONResponse:
+        return JSONResponse(status_code=404, content={"error": "not_found"})
+
+    @app.get("/api/documents/{document_id}")
+    def get_document(document_id: int) -> Any:
+        row = repo.find_by_id(document_id)
+        if row is None:
+            return JSONResponse(status_code=404, content={"error": "not_found"})
+        return row
+
+    @app.post("/api/documents", status_code=status.HTTP_201_CREATED)
+    def create_document(dto: dict[str, Any]) -> Any:
+        return repo.create(dto)
+
+    return app
+
+
+def _dump_payload(value: Any) -> Any:
+    """jsonb bind: a dict/list is ``json.dumps``-serialized for the ``::jsonb``
+    cast; ``None`` stays ``None`` (SQL NULL); a pre-serialized string passes
+    through."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    return json.dumps(value)
+
+
+def _row_to_dict(row: Any) -> dict[str, Any]:
+    ident, title, payload = row
+    # pg8000 auto-decodes jsonb → native Python object; if a driver returned raw
+    # text we'd parse it, but the open-bag contract is "parsed value", so a str
+    # that is JSON is decoded here defensively.
+    if isinstance(payload, str):
+        try:
+            payload = json.loads(payload)
+        except json.JSONDecodeError:
+            pass
+    return {"id": int(ident), "title": title, "payload": payload}