FR-036 Pin 1 (@required string ⇒ non-empty) is over-applied to object.value in the Python port — TS excludes it, and the @min:0 opt-out is clamped shut

[dmealing]

Summary

FR-036 Pin 1 — "a @required non-array string is non-empty" — is applied to every object.* in the Python port, including object.value. FR-036 was designed for the wire tier (object.entity POST/PATCH), and the TypeScript reference port excludes object.value by construction. The result is exactly the cross-port divergence FR-036 existed to remove — plus a Python-internal self-contradiction, and a vocabulary regression that leaves "required to be provided, may be empty" inexpressible.

Surfaced by a downstream Python adopter upgrading 0.15.x → 0.19.0: in-process prompt-payload object.value models (template-slot carriers, never an HTTP input, never persisted) began raising ValidationError on legitimately-empty slots, breaking 62 unit tests and a production code path. Their metadata is correct as documented — see §4.

---

1. The scope bug

server/python/src/metaobjects/codegen/generators/entity_model.py (Pin 1) keys only on subtype/array/required — there is no object-kind gate:

# FR-036 Pin 1 — a @required non-array string is non-empty: reject null / "" but
# ACCEPT whitespace-only. Emit an implicit min_length of 1, keeping the stricter
# floor if a validator.length @min already set one.
if (
 field.sub_type == fc.FIELD_SUBTYPE_STRING
 and not field_is_array(field)
 and field.attrs().get(fc.FIELD_ATTR_REQUIRED) is True
):
 existing_min = kwargs.get("min_length")
 kwargs["min_length"] = max(1, existing_min) if isinstance(existing_min, int) else 1

The default Python suite runs entity_model() over every object.* (server/python/src/metaobjects/cli.py), so object.value gets the constraint.

Four independent reasons this is out of designed scope:

1. The FR-036 spec is entirely wire-tier. Its enforcement matrix is POST/PATCH-over-HTTP and its emitter section names entity DTOs. The strings object.value and payload appear nowhere in it.
2. The conformance corpus models only object.entity (fixtures/validation-conformance/meta.json) — so nothing locks the object.value behavior either way.
3. The TS reference port excludes it explicitly — server/typescript/packages/codegen-ts/src/generators/api-model.ts:348:

   return obj.subType !== OBJECT_SUBTYPE_VALUE && !isTphSubtype(obj);

   object.value gets a plain interface with zero runtime validation. TS and Python therefore validate identical metadata differently.
4. ADR-0028 defines object.value as a constructed shape — "values are never populated — they are constructed" — i.e. explicitly not a wire-input tier.

Python also contradicts itself. For the same object.value, the entity generator emits Field(min_length=1) while payload_vo_generator.py emits no constraints at all — two generated classes for one VO, disagreeing:

# <name>_prompt_payload.py (payload VO generator)
goal: str
# <Name>Payload.py (entity_model generator)
goal: str = Field(min_length=1)

Repro

# meta.yaml
metadata:
 package: app
 children:
 - object.value:
 name: Slots
 children:
 - field.string: {name: goal, required: true}

metaobjects gen ./meta --out ./out --generators entity

Observed (0.19.0): goal: str = Field(min_length=1) → Slots(goal="") raises ValidationError.
Expected: an object.value is not a wire input; TS emits no constraint for the same metadata.

---

2. Vocabulary regression — the opt-out is clamped shut

@required is documented as presence; Pin 1 redefined it as non-empty; and the natural escape hatch is deliberately foreclosed. validator.length @min: 0 on a required string cannot suppress the floor:

• Python: kwargs["min_length"] = max(1, existing_min) (above)
• TS mirror: codegen-ts/src/templates/zod-validators.ts — comments that an explicit @min: 0 "can't suppress it"

So "must be provided, but may be the empty string" is now inexpressible: dropping @required flips the generated type to T | None = None, losing presence typing entirely. Note non-emptiness already had a home — validator.length @min: 1 maps to exactly min_length=1. Pin 1 duplicated an expressible constraint into @required while removing the ability to not say it.

Aside on the whitespace rule. Pin 1 rejects "" but accepts " ". That isn't a semantic — a meaningful-content rule would trim, a presence rule would accept "". The spec states the origin plainly: "Matches TS, the reference impl." It's the shadow of z.string().min(1). Reasonable as a cross-port consistency ruling for the wire tier; the problem is that it silently redefined an attribute documented as presence, everywhere.

---

3. The documentation item was never executed

FR-036 §A5 explicitly ordered: "Reconcile the registry text: field @required says 'NOT NULL', validator.required says 'null/empty' — align both to the pinned non-empty semantic."

This did not happen. As shipped in v0.19.0:

• spec/metamodel/field.json:13 — "When true, the field is NOT NULL. Equivalent to attaching a validator.required child."
• server/typescript/packages/metadata/src/core/field/field-definition.embedded.ts:45 — same text
• validator-definition.embedded.ts:38-39 — "Fails when the value is null/empty (NOT NULL)" / "A field must be present (NOT NULL)" (internally contradictory, pre-existing)
• The metaobjects-authoring skill never defines the non-empty semantic

The new meaning exists in prose only in the CHANGELOG breaking banner. An adopter reading the vocabulary today — post-change — would still author required: true to mean "must be present," which is precisely what happened.

---

4. Latent: the entity READ model also carries the constraint

In Python the constraint lands on the entity base/read model too, so reading an existing DB row containing "" throws at model construction. TS's Zod equivalent is insert/update-only. Not the reported breakage, but the same over-application one tier down — worth gating in the same pass.

---

Proposed fixes

1. Scope fix (patch). Gate Pin 1 to object.entity (exclude OBJECT_SUBTYPE_VALUE) in entity_model.py. Restores FR-036's designed scope, TS parity, ADR-0028 purity, and Python-internal coherence. Add an object.value case to fixtures/validation-conformance/ so it stays locked.
2. Restore expressibility (additive). Honor an explicit validator.length @min: 0 on a required string as the opt-out — remove the max(1, …) clamp in Python and TS. An author writing @min: 0 is unambiguously saying "empty allowed," so this needs no further breaking change. (A full revert of Pin 1 to presence-only would be semantically cleaner but is a second breaking change against conformance-locked behavior — not proposed here.)
3. Execute A5 (mandatory either way). Update spec/metamodel/field.json, field-definition.embedded.ts, validator-definition.embedded.ts, and the authoring skill to state: strings under @required reject "" (whitespace accepted), arrays do not, the entity-vs-value scope, and the opt-out.
4. Consider gating the read-model path (§4) in the same change.

Environment

• Python metaobjects 0.19.0; TS @metaobjectsdev/* 0.19.0; metamodelVersion 0.9.
• Introduced in 0.16.0 (FR-036). Adopters on object.value payloads see it the moment they regenerate.

[dmealing]

Partial fix shipped in PyPI metaobjects 0.19.1 (985920a8). Keeping this open — items 2 and 3 are still outstanding.

What landed

FR-036 Pin 1 is now tier-aware rather than gated on object kind. Pin 1 is emitted only on the wire models (<Name>Create / <Name>Patch) and never on the in-process read model. This fixes item 1 (in-process object.value no longer rejects an empty @required string) and, at zero marginal cost, item 4 (the entity read model carried it too). An object.value now also emits its own <Name>Create wire model, and create/patch reference <Ref>Create for value-object-typed fields.

Python-only. npm / NuGet stay 0.19.0; Maven Central stays 7.11.0. See CHANGELOG.md → PyPI [0.19.1].

Verified: full Python suite 1525 passed (2 unrelated pre-existing failures in test_cli_staleness_nudge.py, reproduce identically at the parent commit); validation-conformance 14/14; api-contract jsonb-value-object-patch r10 still 400s on a nested empty @required string.

Three corrections to the analysis above

Investigating this turned up places the report was off — worth recording so the remaining work is scoped correctly:

1. Proposed fix 1, as written, would have broken locked behavior. A bare object.value gate is not safe: in Python a single VO Pydantic model serves both tiers — entity Create/Patch models type their VO fields as the VO model and recurse at construction. Gating by object kind would have broken the Program D gate (jsonb-value-object-patch r10: nested label: "" -> 400, five ports, both lanes) and the Python validation-conformance lane, whose runner builds the read model. The fix had to split by tier, not by object kind.

2. "The TS reference port excludes object.value by construction" is misleading. TS excludes VOs from the entity/read API-model path, but it does apply Pin 1 to value objects at the wire tier via <Ref>InsertSchema, embedded in entity wire schemas (codegen-ts/src/templates/zod-validators.ts). TS and Python now agree because both apply Pin 1 on the wire tier only — not because TS omits it entirely.

3. The @min: 0 clamp is a five-port issue, not Python + TS. The max(1, …) clamp also exists in SpringDtoGenerator.java, KotlinEntityGenerator.kt, and EntityGenerator.cs. Removing it in only two ports would manufacture exactly the cross-port divergence FR-036 exists to prevent. Item 2 therefore needs an owner ruling plus a coordinated five-port change and a new corpus case (no @min: 0 fixture exists today) — which is why it is not in this patch.

Relatedly, Java/C#/Kotlin are not affected by the reported bug: their VO constraints are declarative annotations on records/POCOs with no validating constructor, evaluated only by explicit validator calls in generated controllers. new Marker("", 5) never throws in any of them.

Still open

• Item 2 — restore the validator.length @min: 0 opt-out. Needs a ruling + coordinated five-port change + corpus case (see correction 3).
• Item 3 (§A5) — reconcile the @required wording across spec/metamodel/field.json, the generated embedded definitions, validator-definition, and the authoring skill. This is arguably the root cause: the vocabulary still documents @required as plain "NOT NULL", which is why the metadata was authored as presence. It is its own atomic change because the descriptions are byte-matched by expected-registry.json across all five ports.
• Not adding a shared-corpus case for this. The wire tier is already locked by r10 (which transitively covers the new <Name>Create), and "in-process models do not enforce" is not expressible in four of the five ports — there is no artifact to run. Locked with Python port-local tests instead; a VO wire-artifact section in validation-conformance is a reasonable optional follow-up, since all five ports could honestly run that.

[dmealing]

Fully shipped. The remaining two items are live as of npm 0.19.1 · NuGet 0.19.1 · PyPI 0.19.2 · Maven Central 7.11.1 (released as a patch: the clamp silently discarded metadata the loader had already accepted, so this removes a defect rather than adding a feature — nothing could have depended on @min: 0 doing nothing).

• Item 2 — an explicit validator.length @min is now authoritative over the Pin 1 implicit floor, in all five ports (fa712a40). Locked by note-empty-allowed / note-missing in validation-conformance, alongside the existing name-empty case which proves the default still rejects "" when no @min is authored.
• Item 3 (§A5) — the @required vocabulary now matches shipped behavior (03690af8), atomically across all nine surfaces: both spec files, the committed C#/Python copies, the hand-maintained C# FieldSchema constant, the regenerated embedded definitions, expected-registry.json, the metamodel-docs fixtures, and the authoring skill — which had never defined the semantic at all.

Items 1 and 4 shipped earlier in PyPI 0.19.1. Closing.

Two things this surfaced, tracked separately so they are not lost:

• migrate --dialect d1: the sqlite table-rebuild's PRAGMA foreign_keys OFF is a no-op on remote D1, so any parent-table rebuild fails with FOREIGN KEY constraint failed #226 — the D1 table-rebuild PRAGMA foreign_keys no-op you flagged as "related but separate", filed with the code path (emit/d1.ts delegates to renderSqlite, and the D1 safety pass has no PRAGMA awareness).
• The CI lanes were running cherry-picked subsets, so a red test could sit on main under a green lane — which is how the §A5 gap and two unrelated red tests went unnoticed. Fixed in aaa2e2d6: the python and csharp lanes now run their full suites and a new ts-unit lane gates the previously-ungated per-package suites.

Thank you for the report — the analysis was detailed enough to verify directly against the code, and the three places it turned out to be off (the proposed fix would have broken the jsonb PATCH gate; TS does apply Pin 1 at the wire tier; the clamp is five-port, not two) were only findable because you cited exact files and lines.