metaobjects 0.10.0__tar.gz → 0.11.1__tar.gz

{metaobjects-0.10.0 → metaobjects-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaobjects
-Version: 0.10.0
+Version: 0.11.1
 Summary: Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port.
 Project-URL: Homepage, https://metaobjects.dev
 Project-URL: Repository, https://github.com/metaobjectsdev/metaobjects

{metaobjects-0.10.0 → metaobjects-0.11.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.10.0"
+version = "0.11.1"
 description = "Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port."
 readme = "README.md"
 requires-python = ">=3.11"

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/agent_context/_content/skills/metaobjects-authoring/SKILL.md

@@ -165,6 +165,26 @@ Reuse a constraint set across entities with an abstract `field.enum` + `extends`
 { "field.object": { "name": "address", "@objectRef": "Address", "@storage": "flattened" } }
 ```
 
+**Arrays of value objects** — set `isArray: true` with `@storage: jsonb`. The whole
+array lives in **one** jsonb column (a JSON array), never a native `jsonb[]`. The
+generated Postgres column is typed `.$type<VO[]>()` and the Zod schema is
+`z.array(<VO>InsertSchema)`:
+
+```json
+{ "field.object": { "name": "triples", "@objectRef": "Triple",
+    "@storage": "jsonb", "isArray": true } }
+```
+
+**Opaque jsonb (no value object)** — when the payload has no fixed shape (freeform
+config, passthrough metadata, an open-keyed map), do NOT use `field.object` (it
+requires `@objectRef`, and a partial VO would let the generated Zod strip unknown
+keys → data loss). Model it as a `field.string` with the physical-type override
+`@dbColumnType: jsonb` — the logical type stays string-bound, the column is jsonb:
+
+```json
+{ "field.string": { "name": "metadata", "@dbColumnType": "jsonb" } }
+```
+
 ## YAML sigil-free authoring + the coercion footgun
 
 In YAML, write the fused `type.subType` key with a **map body**, bare reserved
@@ -194,7 +214,7 @@ The `[]` key-suffix declares an array field: `field.long[]: weekIds` lowers to
 | Subtype | Purpose | Key attrs |
 |---|---|---|
 | `identity.primary` | the PK field(s) | `@fields`, `@generation` |
-| `identity.secondary` | a unique secondary index | `@fields` |
+| `identity.secondary` | a unique secondary index | `@fields` (or `@expr` for a functional index) |
 | `identity.reference` | an inbound FK from this entity to another | `@fields`, `@references`, `@enforce` |
 
 `@generation` on a primary controls value generation (e.g. `increment`).
@@ -205,9 +225,27 @@ reference for navigation/typing/codegen only. Referential actions
 (`@onDelete`/`@onUpdate`) are NOT on `identity.reference` — they live on the
 `relationship.*` node (see Relationships below).
 
+`@references` resolves cross-package by **fully-qualified name**
+(`@references: "shared::billing::Account"`), the same rule as `extends`; a bare
+name resolves within the current package. The FK target must be an entity with a
+single-column primary key (the FK points at that PK); a target with a composite
+PK needs the explicit dotted form `@references: "pkg::Target.fieldA,fieldB"`.
+
+**A dangling reference fails the load (0.11.0+).** An unresolved
+`identity.reference.@references` raises `ERR_INVALID_REFERENCE` and an unresolved
+`relationship.@objectRef` raises `ERR_INVALID_RELATIONSHIP` — the target entity must
+exist (previously such references loaded silently). So every `@references` /
+`@objectRef` you author must name a real entity.
+
+A `identity.secondary` can index an **expression** instead of plain columns: use
+`@expr` (e.g. `"lower(email)"`) in place of `@fields`, optionally with `@using` (the
+index method — `gin` / `gist` / `hash`; default `btree`) and `@where` (a partial-index
+predicate).
+
 ```json
 { "identity.primary":   { "name": "id", "@fields": ["id"], "@generation": "increment" } }
 { "identity.secondary": { "name": "byEmail", "@fields": ["email"] } }
+{ "identity.secondary": { "name": "byEmailCI", "@expr": "lower(email)" } }
 { "identity.reference": { "name": "fkAuthor", "@fields": ["authorId"], "@references": "Author", "@enforce": true } }
 ```
 
@@ -229,6 +267,39 @@ the two halves of one FK.
     "@cardinality": "many", "@onDelete": "cascade" } }
 ```
 
+**Adoption footgun — pin BOTH actions.** `@onDelete` and `@onUpdate` each default to
+`cascade` when omitted, but a plain SQL foreign key is `NO ACTION` on both. If you're
+adopting an existing database (matching metadata to a live schema), omitting these
+makes the metadata declare `CASCADE` where the DB has `NO ACTION` — a perpetual
+`verify --db` drift. Pin **both** explicitly to the DB's real behavior:
+
+```json
+{ "relationship.composition": { "name": "author", "@objectRef": "User",
+    "@cardinality": "one", "@onDelete": "no-action", "@onUpdate": "no-action" } }
+```
+
+## Validators — cross-field rules
+
+Entity-scoped `validator.*` children declare invariants that reference sibling fields
+**by name** (the same name-reference pattern as `identity.*`). The backend derives the
+enforcement (a CHECK constraint / cross-field assertion) — no raw expression is stored.
+
+| Subtype | Rule | Key attrs |
+|---|---|---|
+| `validator.comparison` | two fields stand in a relational order (`@left @op @right`) | `@left`, `@op` (`gt`/`gte`/`lt`/`lte`/`ne`/`eq`), `@right` |
+| `validator.requiredWhen` | `@field` is required when `@when` equals `@equals` | `@field`, `@when`, `@equals` |
+| `validator.presentIff` | `@field` is present **iff** `@when` equals `@equals` (biconditional) | `@field`, `@when`, `@equals` |
+| `validator.atLeastOne` | at least one of `@fields` (2+) is present | `@fields` |
+
+```json
+{ "validator.comparison":   { "name": "hpInRange", "@left": "currentHp", "@op": "lte", "@right": "maxHp" } }
+{ "validator.requiredWhen": { "name": "reasonIfRejected", "@field": "rejectReason", "@when": "status", "@equals": "rejected" } }
+{ "validator.presentIff":   { "name": "usedAtWhenUsed", "@field": "usedAt", "@when": "isUsed", "@equals": "true" } }
+{ "validator.atLeastOne":   { "name": "emailOrPhone", "@fields": ["email", "phone"] } }
+```
+
+These are children of `object.entity`, alongside its fields and identities.
+
 ## Sources — `source.rdb` + `@kind`
 
 `source.rdb` declares where an entity's data lives. Read-only-ness derives from

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/agent_context/_content/skills/metaobjects-codegen/references/typescript.md

@@ -41,6 +41,11 @@ export default defineConfig({
   dialect: "postgres",                 // "postgres" | "sqlite" | "d1" (D1 is TS-only)
   apiPrefix: "/api",                   // flows to routes AND client fetch URLs
   columnNamingStrategy: "snake_case",  // "snake_case" (default) | "literal" | "kebab-case"
+  timestampMode: "string",             // "string" (default, ISO-8601 wire contract) | "date" (Drizzle native Date)
+  pluralizeCollections: true,          // default; table VARS auto-pluralize (AgentConfig → agentConfigs)
+  collectionNameOverrides: {           // per-entity escape hatch for names the rule gets wrong
+    AuditLog: "auditLog", LlmTierConfig: "llmTierConfig",
+  },
   generators: [
     entityFile(), queriesFile(), routesFile(), barrel(),
     formFile(), tanstackQuery(), tanstackGrid(),
@@ -48,6 +53,13 @@ export default defineConfig({
 });
 ```
 
+Naming + timestamp knobs are **codegen config**, not metadata attributes — a
+collection variable name and a Drizzle column mode are per-port rendering choices
+with no meaning to the other language ports, so they carry no cross-port
+conformance cost. `collectionNameOverrides` wins over `pluralizeCollections` and is
+applied consistently to the table declaration, every FK reference, the `relations()`
+block, and the inferred types.
+
 A second file, `.metaobjects/config.json`, holds static project state parseable by
 non-TS tooling; `meta init` scaffolds both plus the `metaobjects/` source dir.
 
@@ -133,3 +145,21 @@ Deterministic per dialect: `field.string` + `@maxLength` → `varchar(N)`,
 (Postgres) + `gen_random_uuid()`, `field.enum` → `varchar` + `CHECK`. Override a
 field's physical column name with `@column` on the field; the DB schema name lives
 on `source.rdb` via `@schema`.
+
+### Value-object jsonb columns
+
+A `field.object` with `@storage: jsonb` (or the default `subdocument`) becomes a
+single typed jsonb column — the referenced value-object's TS type is carried onto
+the Drizzle column via `.$type<>()`, and its Zod schema is the VO's `InsertSchema`:
+
+```ts
+// field.object @objectRef=LlmConfig @storage=jsonb
+llmConfigJson: jsonb("llm_config_json").$type<LlmConfig>(),
+// field.object @objectRef=Triple @storage=jsonb isArray=true
+triples: jsonb("triples").$type<Triple[]>(),   // one jsonb column, NOT a native jsonb[]
+```
+
+The VO type, its Zod `InsertSchema`, and this `.$type<>()` all import the VO from
+the same module (layout/package/`extStyle`-aware resolution). An opaque jsonb column
+(`field.string @dbColumnType: jsonb`) gets no `.$type<>()` — it stays `unknown`,
+which is the correct shape for freeform payloads with no fixed VO.

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/agent_context/_content/skills/metaobjects-prompts/SKILL.md

@@ -123,6 +123,47 @@ For the `xml`-format example above with payload `{ displayName: "Ada", postCount
 bytes. You render the prompt, call your LLM client (provider-agnostic — codegen
 emits no provider-side schema), then parse the response.
 
+## Conditional content: data and flags, never branched prose
+
+When a prompt's wording varies along some dimension — audience, tier, mode,
+locale, entitlement, a domain variant — do NOT branch the prose in code and
+concatenate strings. Branching prompt text in a service is the anti-pattern this
+pillar exists to remove: it scatters the same distinction across call sites, each
+re-encoded and free to drift, and none of it snapshot-tested. The variation
+belongs in exactly two places, with a third for the rare genuine divergence:
+
+- **Vocabulary as payload data.** The words and values that differ become typed
+  payload fields, pre-computed once from the varying dimension — a noun, a label,
+  a set of verbs (a list), an example. The template stays single and references
+  `{{term}}` / `{{#items}}…{{/items}}`. The prose *structure* is identical across
+  variants; only the data differs, so there is nothing to branch.
+- **Presence as boolean flags.** When a whole block exists-or-not for a variant,
+  gate it with a section flag the payload sets: `{{#showBlock}}…{{/showBlock}}`.
+  Reserve flags for entire blocks — never mid-sentence word swaps, which are
+  vocabulary.
+- **Variant text only when prose truly diverges.** If a section's wording — not
+  just its vocabulary — genuinely differs, select a per-variant text through the
+  provider seam (a `@textRef` variant, or an included partial) so the shared
+  prose still lives in one place. Expect to need this rarely.
+
+A single resolver maps the varying dimension to that payload (the flags + the
+vocabulary), so the distinction is defined ONCE and every template that depends
+on it stays consistent.
+
+```
+// WRONG — prose branched and concatenated in a service:
+if (tier.isPremium()) sb.append("Your plan includes priority support.");
+else                  sb.append("Upgrade any time for priority support.");
+```
+```mustache
+{{! RIGHT — text in the template; the variant is data + a flag }}
+{{supportLine}}
+{{#isPremium}}(Priority queue enabled.){{/isPremium}}
+```
+
+This stays deterministic and golden-testable per variant: render the template
+against each value of the dimension and snapshot every variant.
+
 ## `verify` fails the build on prompt-drift
 
 For every template, the verify step resolves the text, parses each `{{...}}`

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/agent_context/_content/skills/metaobjects-verify/references/migration.md

@@ -66,7 +66,40 @@ A clean run is silent; a failure names the drifted table/column. Bias toward
 trusting the tool — a drift failure almost always means the metadata changed and the
 DB didn't follow.
 
+## Index modeling (Postgres)
+
+Secondary indexes carry physical-shape attributes contributed by the db provider
+(they live on `identity.secondary`, not core):
+
+- `@orders` — per-key sort direction, positional to `@fields` (`["asc", "desc"]`).
+  Omit for all-ascending; drives `DESC`-ordered index keys (e.g. a recency index).
+- `@where` — a partial-index predicate (raw SQL, e.g. `"delivered_at IS NULL"`),
+  emitted as `WHERE (<pred>)`. The index then covers only matching rows.
+
+```json
+{ "identity.secondary": { "@fields": ["userId", "createdAt"],
+    "@orders": ["asc", "desc"], "@where": "archived_at IS NULL" } }
+```
+
+## Adopting an existing database (non-destructive)
+
+`meta verify --db` / `meta migrate` can reach **zero drift** against a hand-built
+schema without a rewrite:
+
+- **`meta migrate --from-db`** reverse-engineers a baseline from the live DB so the
+  first diff is empty.
+- **Auto schema-scope** — the diff manages only the schemas the metadata *declares*
+  (via `source.rdb @schema`); tables in undeclared schemas belong to another owner
+  and are left untouched. This is what lets several apps share one database, each
+  owning its own schema, with a clean per-owner `verify --db` and no manual ignore
+  lists. A downstream app that extends the toolkit's DB declares its own `@schema`,
+  models only its tables, and runs its own migrate/verify against that scope.
+- **`identity.reference @constraintName`** pins a foreign-key constraint name so the
+  metadata can match an existing DB's naming convention without a destructive
+  rename.
+
 ## Not yet shipped
 
-Triggers, generated columns, partial/exclusion/check constraints, MySQL, and data
+Triggers, generated columns, exclusion + CHECK constraints, MySQL, and data
 migrations (column-type changes needing data transformation error out with a hint).
+(Partial + descending **indexes** *are* supported — see Index modeling above.)

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/codegen/extract_delegate_emitter.py

@@ -47,7 +47,7 @@ def ref_vo(field: MetaData, root: MetaData) -> MetaData | None:
     """The ``@objectRef`` target VO for a nested-object field, or ``None`` when
     unresolvable. Matches first on the full ref, then the trailing simple-name
     segment (mirrors the runtime ``_resolve_object_ref`` short-name fallback)."""
-    ref = field.attr(fc.FIELD_ATTR_OBJECT_REF)
+    ref = field.attrs().get(fc.FIELD_ATTR_OBJECT_REF)
     if not isinstance(ref, str) or not ref:
         return None
     direct = _find_object(root, ref)

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/codegen/extract_schema_emitter.py

@@ -53,7 +53,7 @@ def _field_spec_literal(field: MetaData, owner: MetaData) -> str:
 
     if field.sub_type == fc.FIELD_SUBTYPE_ENUM:
         values_lit = fm.string_list_literal(fm.enum_values(field))
-        alias_lit = fm.properties_map_literal(field.attr(fc.FIELD_ATTR_ENUM_ALIAS))
+        alias_lit = fm.properties_map_literal(field.attrs().get(fc.FIELD_ATTR_ENUM_ALIAS))
         # FR-011: resolve the three new enum args (field → object.value → "strip" for
         # normalize). Keep the back-compat 4-arg form when nothing is set; otherwise
         # emit the 7-arg form (..., coerce_default, normalize, default_value).

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/codegen/fr010_field_mapping.py

@@ -34,12 +34,12 @@ def fields(vo: MetaData) -> list[MetaData]:
 def is_array(field: MetaData) -> bool:
     """Array-ness from either form: the node property (programmatic build) or the
     ``@isArray`` attr (how metadata loads from JSON)."""
-    return bool(field.is_array) or field.attr(KEY_IS_ARRAY) is True
+    return bool(field.is_array) or field.attrs().get(KEY_IS_ARRAY) is True
 
 
 def is_required(field: MetaData) -> bool:
     """``@required`` — accepts a bool ``True`` or the string ``"true"``."""
-    v = field.attr(fc.FIELD_ATTR_REQUIRED)
+    v = field.attrs().get(fc.FIELD_ATTR_REQUIRED)
     if v is True:
         return True
     return isinstance(v, str) and v.lower() == "true"
@@ -49,7 +49,7 @@ def xml_text(field: MetaData) -> bool:
     """``@xmlText`` — the XML text-content extract marker (accepts a bool ``True`` or the
     string ``"true"``). When set, codegen bakes a ``FieldSpec.text_content_field(...)``.
     Mirrors the TS ``xmlText(field)`` helper."""
-    v = field.attr(TEMPLATE_ATTR_XML_TEXT)
+    v = field.attrs().get(TEMPLATE_ATTR_XML_TEXT)
     if v is True:
         return True
     return isinstance(v, str) and v.lower() == "true"
@@ -57,7 +57,7 @@ def xml_text(field: MetaData) -> bool:
 
 def enum_values(field: MetaData) -> list[str]:
     """The string members of an enum field's ``@values`` attr (empty when absent)."""
-    v = field.attr(fc.FIELD_ATTR_VALUES)
+    v = field.attrs().get(fc.FIELD_ATTR_VALUES)
     if isinstance(v, (list, tuple)):
         return [str(x) for x in v]
     return []

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/codegen/generators/entity_model.py

@@ -57,7 +57,7 @@ def _validator_constraints(field: MetaField) -> dict[str, object]:
     # String length: validator.length @min/@max + field @maxLength (max wins per field attr).
     min_len = _first_attr(field, vc.VALIDATOR_SUBTYPE_LENGTH, vc.VALIDATOR_ATTR_MIN)
     max_len = _first_attr(field, vc.VALIDATOR_SUBTYPE_LENGTH, vc.VALIDATOR_ATTR_MAX)
-    field_max = field.attr(fc.FIELD_ATTR_MAX_LENGTH)
+    field_max = field.attrs().get(fc.FIELD_ATTR_MAX_LENGTH)
     if _is_int(field_max):
         max_len = field_max
     if min_len is not None:
@@ -109,15 +109,18 @@ def _field_line(field: MetaField, imports: set[str], config: GenConfig) -> tuple
         pt = py_type_for(field)
         imports.update(pt.imports)
         type_expr = pt.expr
-    if field.sub_type == fc.FIELD_SUBTYPE_OBJECT:
-        ref = field.attr(fc.FIELD_ATTR_OBJECT_REF)
+    if field.sub_type in (fc.FIELD_SUBTYPE_OBJECT, fc.FIELD_SUBTYPE_MAP):
+        # A field.object (-> VO) and a field.map with @objectRef (-> dict[str, VO])
+        # both reference a value-object by name; import it so the annotation
+        # py_type_for emitted resolves.
+        ref = field.attrs().get(fc.FIELD_ATTR_OBJECT_REF)
         if ref:
             # @objectRef is FQN-expanded at load time; the generated VOs live
             # flat in one package, so import by the bare class name.
             ref_name = str(ref).split("::")[-1]
             imports.add(f"from .{ref_name} import {ref_name}")
-    required = field.attr(fc.FIELD_ATTR_REQUIRED) is True
-    default_raw = field.attr(fc.FIELD_ATTR_DEFAULT)
+    required = field.attrs().get(fc.FIELD_ATTR_REQUIRED) is True
+    default_raw = field.attrs().get(fc.FIELD_ATTR_DEFAULT)
     has_default = default_raw is not None
     enum_type_name = type_name if shared is not None else None
 

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/codegen/generators/filter_allowlist_generator.py

@@ -117,7 +117,7 @@ def _is_filterable(field: MetaField) -> bool:
     matching the Java/Kotlin/C# tolerance for either YAML-bool or raw-string
     value forms.
     """
-    raw = field.attr(fc.FIELD_ATTR_FILTERABLE)
+    raw = field.attrs().get(fc.FIELD_ATTR_FILTERABLE)
     if raw is True:
         return True
     if isinstance(raw, str):

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/codegen/generators/m2m_codegen.py

@@ -96,7 +96,7 @@ def _column_of(field: MetaField | None, fallback: str) -> str:
     ``@column`` overrides)."""
     if field is None:
         return fallback
-    col = field.attr(fc.FIELD_ATTR_COLUMN)
+    col = field.attrs().get(fc.FIELD_ATTR_COLUMN)
     return col if isinstance(col, str) and col else field.name
 
 

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/codegen/generators/payload_vo_generator.py

@@ -172,7 +172,7 @@ def is_field_required(field: MetaField) -> bool:
     additionally treat the string ``"true"`` as required. The payload type's optionality
     and the extractor mapper's None-guarding are kept in lockstep by sharing THIS
     predicate, so do not "reconcile" it with the runtime predicate."""
-    return field.attr(fc.FIELD_ATTR_REQUIRED) is True
+    return field.attrs().get(fc.FIELD_ATTR_REQUIRED) is True
 
 
 def _resolve_object_field_type(
@@ -186,7 +186,7 @@ def _resolve_object_field_type(
     (array). The target VO is scheduled for in-file emission (per-file dedupe, same
     mechanism as ``origin.collection``). Falls back to the bare type-map form when the
     ``@objectRef`` can't be resolved (defensive — loader validation gates it first)."""
-    ref = field.attr(fc.FIELD_ATTR_OBJECT_REF)
+    ref = field.attrs().get(fc.FIELD_ATTR_OBJECT_REF)
     if not isinstance(ref, str) or not ref:
         return _fallback_type(field)
     target = _resolve_object_by_short_or_fqn(root, ref)

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/codegen/generators/render_helper_generator.py

@@ -114,7 +114,7 @@ def _derive_payload_field_tree(
         if f.type != TYPE_FIELD or not isinstance(f, MetaField):
             continue
         if f.sub_type == fc.FIELD_SUBTYPE_OBJECT:
-            ref = f.attr(fc.FIELD_ATTR_OBJECT_REF)
+            ref = f.attrs().get(fc.FIELD_ATTR_OBJECT_REF)
             if isinstance(ref, str) and ref:
                 target = _resolve_nested_object_ref(root, ref)
                 if target is not None and target.sub_type == OBJECT_SUBTYPE_VALUE:

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/codegen/output_format_spec_emitter.py

@@ -34,7 +34,7 @@ def _prompt_style_enum(template: MetaData) -> str:
 
 
 def _opt_string_attr(field: MetaData, attr_name: str) -> str:
-    v = field.attr(attr_name)
+    v = field.attrs().get(attr_name)
     return fm.py_string_literal(v) if isinstance(v, str) else "None"
 
 
@@ -54,7 +54,7 @@ def _prompt_field_literal(field: MetaData) -> str:
 
     if field.sub_type == fc.FIELD_SUBTYPE_ENUM:
         values_lit = fm.string_list_literal(fm.enum_values(field))
-        enum_doc_lit = fm.properties_map_literal(field.attr(fc.FIELD_ATTR_ENUM_DOC))
+        enum_doc_lit = fm.properties_map_literal(field.attrs().get(fc.FIELD_ATTR_ENUM_DOC))
         return (
             f'PromptField("{name}", FieldKind.ENUM, {req}, array={array}, '
             f"enum_values={values_lit}, enum_doc={enum_doc_lit}, "

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/codegen/type_map.py

@@ -35,7 +35,7 @@ _SCALAR: dict[str, PyType] = {
 def field_is_array(field: MetaField) -> bool:
     """Array-ness from either form: the node property (programmatic build) or the
     `@isArray` attr (how metadata loads from JSON — the conformance-fixture form)."""
-    return field.is_array or field.attr(KEY_IS_ARRAY) is True
+    return field.is_array or field.attrs().get(KEY_IS_ARRAY) is True
 
 
 def _py_str_literal(value: str) -> str:
@@ -65,8 +65,22 @@ def py_type_for(field: MetaField) -> PyType:
     constrained, Pydantic runtime-validated) rather than bare ``str``; an enum array
     becomes ``list[Literal[...]]``. An enum WITHOUT declared values falls back to
     ``str``."""
+    if field.sub_type == fc.FIELD_SUBTYPE_MAP:
+        # field.map → dict[str, V]. Keys are always strings; V is a value-object
+        # (@objectRef → bare class name) or a scalar (@valueType, defaulting to
+        # str). A map is stored as a single jsonb/object column and is NEVER
+        # wrapped in list[...] (isArray does not apply), so return directly.
+        ref = field.attrs().get(fc.FIELD_ATTR_OBJECT_REF)
+        if ref:
+            # @objectRef is expanded to a package-qualified FQN at load time; the
+            # emitted VOs live flat in one generated package, so type by the bare
+            # class name (mirrors the field.object branch below).
+            return PyType(f"dict[str, {str(ref).split('::')[-1]}]")
+        value_type = field.attrs().get(fc.FIELD_ATTR_VALUE_TYPE)
+        value = _SCALAR.get(str(value_type), PyType("str")) if value_type else PyType("str")
+        return PyType(f"dict[str, {value.expr}]", value.imports)
     if field.sub_type == fc.FIELD_SUBTYPE_OBJECT:
-        ref = field.attr(fc.FIELD_ATTR_OBJECT_REF)
+        ref = field.attrs().get(fc.FIELD_ATTR_OBJECT_REF)
         # @objectRef is expanded to a package-qualified FQN at load time
         # (e.g. ``app::pkg::Thing``); the emitted VOs all live flat in one
         # generated package, so type by the bare class name.

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/core_types.py

@@ -26,6 +26,7 @@ from .meta.core.field.field_constants import (
     FIELD_ATTR_SCALE,
     FIELD_ATTR_STORAGE,
     FIELD_ATTR_UNIQUE,
+    FIELD_ATTR_VALUE_TYPE,
     FIELD_ATTR_VALUES,
     FIELD_SUBTYPE_ENUM,
     STORAGE_VALUES,
@@ -107,6 +108,7 @@ from .meta.presentation.view.view_constants import (
 )
 from .provider import Provider
 from .registry import AttrSchema, ChildRule, NodeFactory, TypeDefinition, TypeRegistry
+from .validation_types import ReferenceDescriptor
 from .shared.base_types import (
     SUBTYPE_BASE,
     SUBTYPE_ROOT,
@@ -149,6 +151,7 @@ def _register_subtypes(
     factory: NodeFactory,
     child_rules: list[ChildRule] | None = None,
     attrs: list[AttrSchema] | None = None,
+    references: list[ReferenceDescriptor] | None = None,
 ) -> None:
     """Register one TypeDefinition per subtype. Centralises loop boilerplate only —
     all type knowledge (subtypes tuple, node class, child rules) stays with the caller."""
@@ -160,6 +163,7 @@ def _register_subtypes(
                 factory=factory,
                 child_rules=list(child_rules) if child_rules else [],
                 attrs=list(attrs) if attrs else [],
+                references=list(references) if references else [],
             )
         )
 
@@ -332,6 +336,18 @@ for _def in core_provider._defs:  # noqa: SLF001 (provider build-time enrichment
         )
         break
 
+# field.map carries the @valueType attr (scalar value subtype) IN ADDITION to the
+# common field attrs (@objectRef is already common). The bulk loop registered
+# field.map with the common attrs; append @valueType to that definition (mirrors
+# TS, where field.map's attr set = commonFieldAttrs + @valueType + @objectRef).
+# The exactly-one-of @valueType/@objectRef rule is enforced by validation_passes.
+for _def in core_provider._defs:  # noqa: SLF001 (provider build-time enrichment)
+    if _def.type == TYPE_FIELD and _def.sub_type == fc.FIELD_SUBTYPE_MAP:
+        _def.attrs.append(
+            AttrSchema(name=FIELD_ATTR_VALUE_TYPE, value_type=ATTR_SUBTYPE_STRING, required=False)
+        )
+        break
+
 # field.enum — dedicated registration with required @values attr.
 # Inherits every common field attr (column / required / unique / default /
 # maxLength / filterable / sortable / etc.) so the D2 type-coercion guard
@@ -390,6 +406,12 @@ core_provider.add(
             ),
         ],
         child_rules=[ChildRule(TYPE_ATTR, "*")],
+        # max_occurs/default_name are hardcoded here (matching the values in
+        # spec_metamodel/identity.json, which this port does NOT yet read). Sourcing them from
+        # that JSON — true single-source-of-truth across all ports — is the config-driven-
+        # validation work tracked in issue #51.
+        max_occurs=1,
+        default_name="primary",
     )
 )
 
@@ -420,6 +442,10 @@ core_provider.add(
             AttrSchema(name=IDENTITY_REFERENCE_ATTR_ENFORCE, value_type=ATTR_SUBTYPE_BOOLEAN, required=False),
         ],
         child_rules=[ChildRule(TYPE_ATTR, "*")],
+        # @references is a cross-reference to a real object (FK target) — the loader's
+        # registry-derived validation resolves it; "Entity.field" resolves the entity head.
+        references=[ReferenceDescriptor(
+            IDENTITY_REFERENCE_ATTR_REFERENCES, TYPE_OBJECT, None, True, "ERR_INVALID_REFERENCE")],
     )
 )
 
@@ -460,6 +486,10 @@ _register_subtypes(
     factory=MetaRelationship,
     child_rules=[ChildRule(TYPE_ATTR, "*")],
     attrs=_RELATIONSHIP_ATTRS,
+    # @objectRef is a cross-reference to a real object (the relationship target); the
+    # loader's registry-derived validation resolves it (dangling target = load error).
+    references=[ReferenceDescriptor(
+        RELATIONSHIP_ATTR_OBJECT_REF, TYPE_OBJECT, None, False, "ERR_INVALID_RELATIONSHIP")],
 )
 
 # source.* — base (no attrs) + rdb (paradigm subtype with @table/@kind/@role/@schema).
@@ -628,6 +658,26 @@ _VALIDATOR_ATTRS_BY_SUBTYPE: dict[str, list[AttrSchema]] = {
     ],
     vc.VALIDATOR_SUBTYPE_NUMERIC: list(_VALIDATOR_MIN_MAX_ATTRS),
     vc.VALIDATOR_SUBTYPE_ARRAY: list(_VALIDATOR_MIN_MAX_ATTRS),
+    # Cross-field validators — entity-scoped, reference sibling fields by name.
+    vc.VALIDATOR_SUBTYPE_COMPARISON: [
+        AttrSchema(name=vc.VALIDATOR_ATTR_LEFT, value_type=ATTR_SUBTYPE_STRING, required=True),
+        AttrSchema(name=vc.VALIDATOR_ATTR_OP, value_type=ATTR_SUBTYPE_STRING, required=True,
+                   allowed_values=("gt", "gte", "lt", "lte", "ne", "eq")),
+        AttrSchema(name=vc.VALIDATOR_ATTR_RIGHT, value_type=ATTR_SUBTYPE_STRING, required=True),
+    ],
+    vc.VALIDATOR_SUBTYPE_REQUIRED_WHEN: [
+        AttrSchema(name=vc.VALIDATOR_ATTR_FIELD, value_type=ATTR_SUBTYPE_STRING, required=True),
+        AttrSchema(name=vc.VALIDATOR_ATTR_WHEN, value_type=ATTR_SUBTYPE_STRING, required=True),
+        AttrSchema(name=vc.VALIDATOR_ATTR_EQUALS, value_type=ATTR_SUBTYPE_STRING, required=True),
+    ],
+    vc.VALIDATOR_SUBTYPE_PRESENT_IFF: [
+        AttrSchema(name=vc.VALIDATOR_ATTR_FIELD, value_type=ATTR_SUBTYPE_STRING, required=True),
+        AttrSchema(name=vc.VALIDATOR_ATTR_WHEN, value_type=ATTR_SUBTYPE_STRING, required=True),
+        AttrSchema(name=vc.VALIDATOR_ATTR_EQUALS, value_type=ATTR_SUBTYPE_STRING, required=True),
+    ],
+    vc.VALIDATOR_SUBTYPE_AT_LEAST_ONE: [
+        AttrSchema(name=vc.VALIDATOR_ATTR_FIELDS, value_type=ATTR_SUBTYPE_STRING, required=True, is_array=True),
+    ],
 }
 for _sub, _attrs in _VALIDATOR_ATTRS_BY_SUBTYPE.items():
     core_provider.add(

{metaobjects-0.10.0 → metaobjects-0.11.1}/src/metaobjects/errors.py

@@ -23,6 +23,8 @@ class ErrorCode(str, Enum):
     # Vocabulary-only here until FR-024 Phase E (the Python loader does not
     # enforce these yet); the enum tracks the shared corpus codes.
     ERR_IDENTITY_NAME_REQUIRED = "ERR_IDENTITY_NAME_REQUIRED"
+    # A type.subType declared with maxOccurs (e.g. identity.primary) appears more than allowed under one parent.
+    ERR_TOO_MANY_OCCURRENCES = "ERR_TOO_MANY_OCCURRENCES"
     ERR_PROJECTION_IDENTITY_NOT_EXTENDED = "ERR_PROJECTION_IDENTITY_NOT_EXTENDED"
     ERR_IDENTITY_KEY_MISMATCH = "ERR_IDENTITY_KEY_MISMATCH"
     # FR-024 (ADR-0028): a source.* on an object.projection has a writable
@@ -76,6 +78,9 @@ class ErrorCode(str, Enum):
     # references / sourceRefField-not-matching / M:N-attr-on-1:N). The symmetric-
     # on-hetero + symmetric+sourceRefField rules emit ERR_BAD_ATTR_VALUE instead.
     ERR_INVALID_RELATIONSHIP = "ERR_INVALID_RELATIONSHIP"
+    # identity.reference @references names an FK target object that does not resolve
+    # to any object in the loaded tree (a dangling cross-reference between metadata).
+    ERR_INVALID_REFERENCE = "ERR_INVALID_REFERENCE"
     ERR_BAD_ATTR_FILTER = "ERR_BAD_ATTR_FILTER"
     # Reserved structural body key authored as an @-attr (source-v2 / ADR-0007).
     ERR_RESERVED_ATTR = "ERR_RESERVED_ATTR"