feat: ADR-0036 Wave 2 (Python) — field.timestamp instant-by-default + @localTime

Port the TS reference (fa40542) to Python. field.timestamp is now an absolute
instant / timezone-aware BY DEFAULT; the rare naive / wall-clock case opts out
with the boolean @localTime attr. The @dbColumnType: timestamp_with_tz escape
hatch is retired — the legal @dbColumnType set shrinks to { uuid, jsonb }. The
canonical golden + shared persistence fixtures are TS-owned and unchanged; this
makes the Python port byte-match them.

Metamodel:
- db_constants.py: add FIELD_ATTR_LOCAL_TIME; drop DB_COLUMN_TYPE_TIMESTAMP_TZ
  from VALID_DB_COLUMN_TYPES (now [uuid, jsonb]); tombstone the retired constant.
- db_provider.py: register @localTime (boolean, NO allowed_values) on
  field.timestamp only; description sourced from the embedded spec_metamodel/db.json
  by apply_spec_descriptions (single-source). @dbColumnType allowed_values shrinks
  via VALID_DB_COLUMN_TYPES.
- spec_metamodel/db.json: re-copied from the TS-updated repo-root spec/metamodel/db.json
  (byte-identity gate) — new boolean @localTime on field.timestamp + slimmed
  @dbColumnType allowedValues/description.

Loader:
- validation_passes.py: drop timestamp_with_tz from the @dbColumnType legal
  pairing map (now uuid/jsonb→field.string only). A timestamp_with_tz value now
  fails Rule 1 (unrecognized value) → still ERR_BAD_ATTR_VALUE, so the shared
  error-dbcolumntype-illegal-pairing fixture stays green (trigger shifts from
  illegal-pairing to unknown-value).

Runtime (the core native-type flip):
- object_manager.py write codec: default field.timestamp → tz-aware datetime
  (UTC tzinfo → driver binds timestamptz); @localTime:true → naive datetime
  (no tzinfo → driver binds plain timestamp). Inverts the prior default. The
  normalization boundary (tests/integration/normalization.py) already keys
  tz-aware↔Z / naive↔no-Z off tzinfo, so it is unchanged.

Codegen/schema: Python is pure data-access (ADR-0015) — no DDL/schema emitter
and the Pydantic type map is datetime.datetime for both modes, so no codegen
column-type branch existed to flip.

Tests: registry-conformance byte-match green; spec_metamodel embed byte-match
green; full conformance (301) green incl. the shared illegal-pairing fixture;
test_field_uuid_dbcolumntype updated for the retirement + a new @localTime-ok
case. Native-type rule unit-verified (default aware / @localTime naive). The
persistence op:roundtrip (tsVal naive / tsTzVal tz-aware) needs pg8000 +
Testcontainers Postgres — CI-gated, not run locally. The 2 failing
test_cli_staleness_nudge tests are pre-existing (unrelated agent-docs message
wording), failing identically on the base branch.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GF9xLEQZaPus5Y6opk398n

Author: claude

server/python/src/metaobjects/loader/validation_passes.py

@@ -42,7 +42,6 @@
 )
 from ..meta.persistence.db.db_constants import (
     DB_COLUMN_TYPE_JSONB,
-    DB_COLUMN_TYPE_TIMESTAMP_TZ,
     DB_COLUMN_TYPE_UUID,
     FIELD_ATTR_DB_COLUMN_TYPE,
     VALID_DB_COLUMN_TYPES,
@@ -662,25 +661,27 @@ def _validate_field_defaults(root: MetaData, errors: list[MetaError]) -> None:
 # Own-only validation of the @dbColumnType physical column-type attribute,
 # mirroring the field.enum @values precedent. Two rules, both → ERR_BAD_ATTR_VALUE:
 #
-#   1. The value must be one of the closed set uuid|jsonb|timestamp_with_tz.
+#   1. The value must be one of the closed set uuid|jsonb.
 #      (@dbColumnType is registered as a bare string attr — no allowed_values — so
 #      this pass is the SOLE enforcer of the closed set: an unknown value fires
 #      exactly one ERR_BAD_ATTR_VALUE, matching TS/Java/C#.)
 #   2. The (logical subtype × value) pairing must be legal:
-#        uuid              → field.string
-#        jsonb             → field.string
-#        timestamp_with_tz → field.timestamp
+#        uuid  → field.string
+#        jsonb → field.string
+#
+# ADR-0036 Wave 2: timestamp_with_tz is RETIRED — timezone-awareness moved to
+# field.timestamp (instant by default) + @localTime (the naive opt-out), so it is
+# no longer a legal @dbColumnType value or pairing.
 #
 # Own-only: only @dbColumnType declared on THIS node is validated (a physical
 # attr is never inherited via extends:). Cross-port: TS/C#/Java run the identical
 # own-only check.
 
-# value → the field subtype it is legal on (Phase 1: three surviving values).
+# value → the field subtype it is legal on (uuid/jsonb on field.string).
 # uuid_array / text_array are REMOVED — derive from field.uuid/field.string + isArray.
 _DB_COLUMN_TYPE_REQUIRED_SUBTYPE: dict[str, str] = {
     DB_COLUMN_TYPE_UUID: FIELD_SUBTYPE_STRING,
     DB_COLUMN_TYPE_JSONB: FIELD_SUBTYPE_STRING,
-    DB_COLUMN_TYPE_TIMESTAMP_TZ: FIELD_SUBTYPE_TIMESTAMP,
 }
 
 

server/python/src/metaobjects/meta/persistence/db/db_constants.py

@@ -18,9 +18,17 @@
 # ---------------------------------------------------------------------------
 
 # Physical DB column-type override on a field (@dbColumnType). Closed value set:
-# DB_COLUMN_TYPE_UUID / DB_COLUMN_TYPE_JSONB / DB_COLUMN_TYPE_TIMESTAMP_TZ.
+# DB_COLUMN_TYPE_UUID / DB_COLUMN_TYPE_JSONB.
 FIELD_ATTR_DB_COLUMN_TYPE = "dbColumnType"
 
+# ADR-0036 Wave 2: @localTime — a boolean flag on field.timestamp marking the rare
+# naive / wall-clock case. When true the column is Postgres `timestamp without time
+# zone`; absent/false (the default) is an absolute instant → `timestamptz`. This
+# replaces the retired @dbColumnType: timestamp_with_tz escape hatch — timezone-
+# awareness now lives in the logical field type (instant-by-default) + this opt-out,
+# not in a physical column-type string.
+FIELD_ATTR_LOCAL_TIME = "localTime"
+
 # @db.indexed — boolean DB-domain attr on every field subtype. Suppresses the
 # @filterable-without-index warning by declaring an explicit index intent.
 # Mirrors TS persistence/db/db-constants.ts FIELD_ATTR_DB_INDEXED.
@@ -30,8 +38,12 @@
 DB_COLUMN_TYPE_UUID = "uuid"
 # @dbColumnType: jsonb — genuinely-open JSON column (legal on field.string).
 DB_COLUMN_TYPE_JSONB = "jsonb"
-# @dbColumnType: timestamp_with_tz — timestamp with time zone (legal on field.timestamp).
-DB_COLUMN_TYPE_TIMESTAMP_TZ = "timestamp_with_tz"
+
+# ADR-0036 Wave 2 removal: timestamp_with_tz is no longer a valid @dbColumnType
+# value. field.timestamp is instant / tz-aware BY DEFAULT and @localTime opts into
+# the naive wall-clock case — timezone-awareness moved out of @dbColumnType. The
+# constant is kept as a tombstone so any straggling caller gets a clear NameError.
+# DB_COLUMN_TYPE_TIMESTAMP_TZ = "timestamp_with_tz"  # REMOVED — use @localTime opt-out
 
 # Phase 1 removal: uuid_array / text_array are no longer valid @dbColumnType values.
 # Derive native uuid[]/text[] from field.uuid/field.string + isArray=true instead.
@@ -40,11 +52,11 @@
 # DB_COLUMN_TYPE_UUID_ARRAY = "uuid_array"  # REMOVED — use field.uuid isArray:true
 # DB_COLUMN_TYPE_TEXT_ARRAY = "text_array"  # REMOVED — use field.string isArray:true
 
-# The closed set of legal @dbColumnType values (Phase 1: uuid | jsonb | timestamp_with_tz).
+# The closed set of legal @dbColumnType values. ADR-0036 Wave 2 retires
+# timestamp_with_tz — the legal set is now just { uuid, jsonb }, both on field.string.
 VALID_DB_COLUMN_TYPES = (
     DB_COLUMN_TYPE_UUID,
     DB_COLUMN_TYPE_JSONB,
-    DB_COLUMN_TYPE_TIMESTAMP_TZ,
 )
 
 # ---------------------------------------------------------------------------

server/python/src/metaobjects/meta/persistence/db/db_provider.py

@@ -16,7 +16,7 @@
 """
 from __future__ import annotations
 
-from ...core.attr.attr_constants import ATTR_SUBTYPE_STRING
+from ...core.attr.attr_constants import ATTR_SUBTYPE_BOOLEAN, ATTR_SUBTYPE_STRING
 from ...core.field import field_constants as fc
 from ...core.identity.identity_constants import (
     IDENTITY_SUBTYPE_REFERENCE,
@@ -27,6 +27,7 @@
 from ....shared.base_types import TYPE_FIELD, TYPE_IDENTITY
 from .db_constants import (
     FIELD_ATTR_DB_COLUMN_TYPE,
+    FIELD_ATTR_LOCAL_TIME,
     IDENTITY_REFERENCE_ATTR_CONSTRAINT_NAME,
     IDENTITY_SECONDARY_ATTR_ORDERS,
     IDENTITY_SECONDARY_ATTR_WHERE,
@@ -46,21 +47,30 @@
 _COLUMN_SCHEMA = AttrSchema(name=fc.FIELD_ATTR_COLUMN, value_type=ATTR_SUBTYPE_STRING, required=False)
 
 # @dbColumnType — physical column-type override on a field. Carries the closed
-# value-set (uuid | jsonb | timestamp_with_tz) PURELY so it surfaces in the
-# registry manifest (ADR-0036 Wave 1, decision 5 — closed-value-set conformance
-# gate). Its REAL constraint is the (subtype × value) pairing enforced by the
-# loader's _validate_db_column_type pass, which emits the single ERR_BAD_ATTR_VALUE
-# for both an unrecognized value and an illegal pairing; that pass is the sole
-# enforcer, so @dbColumnType is EXEMPT from the generic flat allowed_values
-# membership check (Check 3 in validation_passes) to avoid double-reporting —
-# matching the TS reference.
+# value-set (uuid | jsonb) PURELY so it surfaces in the registry manifest (ADR-0036
+# Wave 1, decision 5 — closed-value-set conformance gate). Its REAL constraint is
+# the (subtype × value) pairing enforced by the loader's _validate_db_column_type
+# pass, which emits the single ERR_BAD_ATTR_VALUE for both an unrecognized value and
+# an illegal pairing; that pass is the sole enforcer, so @dbColumnType is EXEMPT from
+# the generic flat allowed_values membership check (Check 3 in validation_passes) to
+# avoid double-reporting — matching the TS reference.
 _DB_COLUMN_TYPE_SCHEMA = AttrSchema(
     name=FIELD_ATTR_DB_COLUMN_TYPE,
     value_type=ATTR_SUBTYPE_STRING,
     required=False,
     allowed_values=VALID_DB_COLUMN_TYPES,
 )
 
+# @localTime — boolean opt-out into a naive / wall-clock timestamp (ADR-0036 Wave
+# 2). Registered on field.timestamp only; the description is sourced from the
+# embedded spec/metamodel/db.json by apply_spec_descriptions (single-source). NO
+# allowed_values — it's an open boolean, not a closed-enum attr.
+_LOCAL_TIME_SCHEMA = AttrSchema(
+    name=FIELD_ATTR_LOCAL_TIME,
+    value_type=ATTR_SUBTYPE_BOOLEAN,
+    required=False,
+)
+
 # DB-domain physical attrs EXTENDING identity subtypes — RDB index / FK-constraint
 # concerns, NOT core identity. Mirrors spec/metamodel/db.json's identity extends and
 # the TS/Java/C# db providers. Descriptions are byte-identical to the canonical.
@@ -129,6 +139,13 @@ def _register(registry: TypeRegistry) -> None:
             sub_type,
             attributes=[_COLUMN_SCHEMA, _DB_COLUMN_TYPE_SCHEMA],
         )
+    # ADR-0036 Wave 2: @localTime is a field.timestamp-only opt-out (instant by
+    # default → naive). Registered on the timestamp subtype only.
+    registry.extend(
+        TYPE_FIELD,
+        fc.FIELD_SUBTYPE_TIMESTAMP,
+        attributes=[_LOCAL_TIME_SCHEMA],
+    )
     registry.extend(
         TYPE_IDENTITY,
         IDENTITY_SUBTYPE_SECONDARY,

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

@@ -674,16 +674,17 @@ def _coerce_write_value(field: MetaField, value: Any) -> Any:
         return value if isinstance(value, _uuid.UUID) else _uuid.UUID(str(value))
 
     # temporal: parse the authoring string to the native type, with tz-awareness
-    # driven by the field (TIMESTAMP → naive, TIMESTAMPTZ → aware) so the driver
-    # binds the correct physical type.
+    # driven by the field so the driver binds the correct physical type. ADR-0036
+    # Wave 2: field.timestamp is instant / tz-aware BY DEFAULT (→ timestamptz); the
+    # rare naive wall-clock case opts out with @localTime:true (→ plain timestamp).
     if sub == fc.FIELD_SUBTYPE_DATE:
         return value if isinstance(value, _dt.date) else _dt.date.fromisoformat(str(value))
     if sub == fc.FIELD_SUBTYPE_TIME:
         return value if isinstance(value, _dt.time) else _dt.time.fromisoformat(str(value))
     if sub == fc.FIELD_SUBTYPE_TIMESTAMP:
         if isinstance(value, _dt.datetime):
             return value
-        is_tz = col_type == dbc.DB_COLUMN_TYPE_TIMESTAMP_TZ
+        is_tz = field.attr(dbc.FIELD_ATTR_LOCAL_TIME) is not True
         return _parse_datetime(str(value), tz_aware=is_tz)
 
     # field.object (jsonb storage): a dict/list passes through — pg8000 binds it

server/python/src/metaobjects/spec_metamodel/db.json

@@ -7,7 +7,14 @@
       "children": [
         { "type": "attr", "subType": "string", "name": "column", "min": 0, "max": 1, "description": "Physical column name for this field on an rdb source. Defaults to the field name via columnNamingStrategy." },
         { "type": "attr", "subType": "boolean", "name": "db.indexed", "min": 0, "max": 1, "description": "When true, suppress the @filterable-without-index Loader warning (the field is indexed by other means)." },
-        { "type": "attr", "subType": "string", "name": "dbColumnType", "min": 0, "max": 1, "allowedValues": ["uuid", "jsonb", "timestamp_with_tz"], "description": "Physical DB column-type override (ADR-0013 escape hatch). Legal values are uuid | jsonb | timestamp_with_tz, each legal only on a specific logical field subtype (uuid/jsonb on field.string, timestamp_with_tz on field.timestamp). The logical field type and its native binding are unchanged. Native SQL arrays (uuid[]/text[]) are NOT declared here — they are derived from a field subtype + isArray (ADR-0036 Wave 1)." }
+        { "type": "attr", "subType": "string", "name": "dbColumnType", "min": 0, "max": 1, "allowedValues": ["uuid", "jsonb"], "description": "Physical DB column-type override (ADR-0013 escape hatch). Legal values are uuid | jsonb, both on field.string (uuid = native Postgres uuid column over a string-typed field; jsonb = genuinely-open JSON column). The logical field type and its native binding are unchanged. Native SQL arrays (uuid[]/text[]) are NOT declared here — they are derived from a field subtype + isArray (ADR-0036 Wave 1). The retired timestamp_with_tz value is gone — timezone-awareness lives in field.timestamp (instant by default) + @localTime (the naive opt-out), per ADR-0036 Wave 2." }
+      ]
+    },
+    {
+      "type": "field",
+      "subType": "timestamp",
+      "children": [
+        { "type": "attr", "subType": "boolean", "name": "localTime", "min": 0, "max": 1, "description": "When true, the timestamp is a naive wall-clock value with no timezone (Postgres `timestamp without time zone`); absent/false (the default) = an absolute instant (`timestamptz`). ADR-0036 Wave 2 — replaces the retired @dbColumnType: timestamp_with_tz escape hatch." }
       ]
     },
     {

server/python/tests/unit/test_field_uuid_dbcolumntype.py

@@ -90,11 +90,23 @@ def test_dbcolumntype_jsonb_on_string_ok() -> None:
     assert codes == []
 
 
-def test_dbcolumntype_timestamptz_on_timestamp_ok() -> None:
+def test_dbcolumntype_timestamptz_retired_on_timestamp_error() -> None:
+    # ADR-0036 Wave 2: @dbColumnType:timestamp_with_tz is RETIRED — it is no longer
+    # a recognized value, so even on field.timestamp it is now ERR_BAD_ATTR_VALUE
+    # (unknown value). Timezone-awareness moved to @localTime (instant by default).
     codes, _ = _load(_entity(
         {"field.long": {"name": "id"}},
         {"field.timestamp": {"name": "at", "@dbColumnType": "timestamp_with_tz"}},
     ))
+    assert codes == ["ERR_BAD_ATTR_VALUE"]
+
+
+def test_local_time_attr_on_timestamp_ok() -> None:
+    # ADR-0036 Wave 2: @localTime is a valid boolean opt-out on field.timestamp.
+    codes, _ = _load(_entity(
+        {"field.long": {"name": "id"}},
+        {"field.timestamp": {"name": "at", "@localTime": True}},
+    ))
     assert codes == []
 
 
@@ -104,6 +116,7 @@ def test_dbcolumntype_timestamptz_on_timestamp_ok() -> None:
 
 
 def test_dbcolumntype_timestamptz_on_string_illegal() -> None:
+    # ADR-0036 Wave 2: timestamp_with_tz is retired → unknown value on any subtype.
     codes, _ = _load(_entity(
         {"field.long": {"name": "id"}},
         {"field.string": {"name": "at", "@dbColumnType": "timestamp_with_tz"}},
@@ -185,13 +198,14 @@ def test_dbcolumntype_uuid_array_error_message_names_valid_set() -> None:
         result = MetaDataLoader.from_directory(tmpdir, providers=[core_provider])
         assert len(result.errors) == 1
         msg = result.errors[0].message
-        # The "allowed:" section must list only the three surviving legal values.
+        # The "allowed:" section must list only the two surviving legal values
+        # (ADR-0036 Wave 2 retired timestamp_with_tz → { uuid, jsonb }).
         allowed_idx = msg.index("allowed:")
         allowed_section = msg[allowed_idx:]
         assert "uuid" in allowed_section
         assert "jsonb" in allowed_section
-        assert "timestamp_with_tz" in allowed_section
-        # uuid_array and text_array must NOT appear in the allowed section.
+        # timestamp_with_tz (retired), uuid_array, text_array must NOT appear.
+        assert "timestamp_with_tz" not in allowed_section
         assert "uuid_array" not in allowed_section
         assert "text_array" not in allowed_section