feat(metamodel)!: @readonly becomes the @mutability enum (#338)

FR-037 R1. `@readOnly` (boolean) is retired across 18 registry entries and
replaced by `@mutability: readWrite | writeOnce | readOnly` on field.base,
registered by the CORE field provider. A legacy `@readOnly` fails a strict load
with ERR_UNKNOWN_ATTR; there is no deprecation shim under ADR-0023.

WHY AN ENUM, not a second boolean: readOnly and writeOnce are mutually
exclusive modes of ONE axis — who may write, and when. One enum makes the
illegal pair unrepresentable and gives inheritance a total order
(readWrite < writeOnce < readOnly), so "may only tighten" is an INDEX
comparison over the declaration order rather than a lookup table. A test pins
that ordering, because reordering the array would silently invert the rule.

Five rules, all five ports, each with a cross-port fixture or per-port unit test:

  ERR_MUTABILITY_AUTOSET_CONFLICT (new) — @autoset with writeOnce or readOnly.
    @autoset already says the SERVER supplies the value; @mutability says who
    may write it. The boolean era left readOnly x @autoset REPRESENTABLE but
    unvalidated — the enum closes both arms with one rule. Proven live in all
    four ports by sabotaging the fixture and watching each go red.
  ERR_MUTABILITY_DOWNGRADE (new) — replaces ERR_READONLY_DOWNGRADE, renamed
    because the rule now spans three modes and a READONLY name would misdescribe
    a writeOnce -> readWrite loosening.
  ERR_READONLY_ASSIGNED_PRIMARY — KEEPS its name. The condition really is
    readOnly-specific, and the asymmetry is the enum's whole justification:
    `writeOnce` on an assigned primary key is LEGAL and is in fact the natural
    declaration for one — a thing the boolean vocabulary could not say at all.
  WARN_MUTABILITY_VALUE_OBJECT (new) — replaces WARN_READONLY_VALUE_OBJECT.
  WARN_MUTABILITY_READONLY_HOST (new) — writeOnce on a projection / read-only
    @kind. Benign: inert, not wrong, and a projection may inherit it.

writeOnce leaves the UPDATE shape and ONLY the update shape, through each
port's existing excluded-settable-set seam (the one @autoset:onCreate already
uses): TS updateSchemaFields + the combined zod walk, Python _emit_patch_lines,
Java SpringDtoGenerator.settableFields (vanilla AND the TPH overload — stated
twice deliberately, per the 0.19.4 lesson that TPH is a separate code path),
Kotlin patchSettableFields, C# SetAfterSaveBehavior(Ignore).

D1 VERIFIED, not assumed: a presented writeOnce key on PATCH is STRIPPED, not
400'd. The emitted <Entity>UpdateSchema is a plain z.object() (never .strict()),
Zod drops unknown keys, and mountUpdateRoute safeParses that same schema — the
TPH discriminator is additionally hand-stripped after parse, the same
convention. Rejecting would break our own shipped client: the generated edit
form submits EVERY registered field (0.19.2 switched the resolver to
UpdateSchema on edit rather than diff-and-omit), so 400-on-present would fail
every save on every generated edit form for an entity carrying one.

That verification exposed a PRE-EXISTING doc defect, now corrected:
docs/features/generated-mutations.md PATCH-3 has claimed "at the HTTP tier an
unknown or non-settable key is a 400", which is false today for the
non-settable case and has been.

And a real CROSS-PORT DIVERGENCE, now closed: Python's <Entity>Patch INCLUDED
@readonly fields — `_emit_patch_lines` skipped only the PK and derived fields,
while TS excluded readOnly from UpdateSchema. Nobody hit it because @readonly
has zero adopter uses; it would have bitten the first one.

C# splits the two modes exactly where they differ. Both get
SetAfterSaveBehavior(Ignore) (they share the UPDATE half); only `readOnly` gets
a private setter. `writeOnce` keeps a PUBLIC setter deliberately — the caller
must supply it on insert, and a private setter there would make the mode
useless. So neither signal alone distinguishes the modes; only the pair does,
and the test asserts the pair.

The accessor lives on the field node in every port (MetaField.getMutability /
.Mutability, fieldMutability, field_mutability) and is RESOLVING per ADR-0039,
so a mode inherited through `extends` is honoured — an own-only read would
report readWrite for a field whose abstract parent declared readOnly and emit a
setter for a column nothing may write. Python's naming inversion is called out
at the call site (`attr()` is own-only there; `get_meta_attr()` resolves).

Fixtures: six field-readonly-* renamed to field-mutability-* and migrated;
three ADDED for writeOnce, which had no corpus coverage at all — and coverage
here is the whole story, because a peer scan of three adopter estates (826/8/75
metadata files, 14,860 field nodes) found ZERO uses of @readonly by two
independent methods with controls firing. So the corpus is the only thing that
exercises these modes, and ERR_MUTABILITY_AUTOSET_CONFLICT has no existing
instance anywhere to migrate — it is purely forward-looking. The coverage
ratchet fired on the rename and was regenerated only after confirming the diff
is exactly 13x readOnly->mutability plus U2's -1 subtype: no coverage lost.

Output equivalence pinned in TS and C#: an explicit @mutability: "readWrite"
emits byte-identically to declaring nothing.

Green: TS build + typecheck clean, 5939 tests 0 fail · C# four Passed! lines,
0 error CS, conformance 955 · Python 1723 · Java metadata 1461 /
codegen-spring 292 / codegen-kotlin 202 / render 316, BUILD SUCCESS,
ConformanceTest 576 · check-metamodel-version.mjs exit 0 (0.10 covers it) ·
ci-local.sh --only gates PASSED.

Still to land for FR-037 R1: the api-contract-conformance writeOnce scenario
(both lanes, every port, vanilla AND TPH).

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

Author: dmealing

agent-context/skills/metaobjects-audit/references/capability-checklist.md

@@ -50,8 +50,11 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
 - **`field.map`** (`@valueType`) — hunt ad-hoc open-keyed key/value bags stuffed into a jsonb
   column by hand.
 - **Common field attrs** — `@column` (hand column-name mapping), `@default` (hand default
-  assignment), `@required` (hand presence checks), `@unique` (hand uniqueness), `@readOnly`
-  (hand write-guards), `@filterable` / `@sortable` (hand filter/sort allowlists),
+  assignment), `@required` (hand presence checks), `@unique` (hand uniqueness),
+  `@mutability` (hand write-guards: `readOnly` for a column the DB/replication owns,
+  `writeOnce` for one set at create and never changed — hunt hand-written
+  "cannot be modified after creation" checks), `@filterable` / `@sortable`
+  (hand filter/sort allowlists),
   `@dbColumnType` (hand native-type override), `@example` / `@instruction` (hand prompt
   hints), `@xmlText` (hand XML-text mapping). The `@db.indexed` attr suppresses the
   *`@filterable`-without-index* Loader warning (you assert the column is indexed by other

docs/features/generated-mutations.md

@@ -32,10 +32,21 @@ but the semantics are one contract — call them **PATCH-1..7** (FR-035):
   *omitted* field is left alone. This is JSON-Merge-Patch present-key semantics
   with `null` meaning *set null*, not *delete*.
 - **PATCH-3 (settable set).** Never settable: the primary key, the TPH
-  discriminator, `@readOnly` fields, `origin.*`-derived fields. `@autoSet:onUpdate`
-  columns are stamped server-side regardless of the caller; `@autoSet:onCreate`
-  columns are not patch-settable. At the HTTP tier an unknown or non-settable key
-  is a `400 {"error":"validation"}`.
+  discriminator, `@mutability: "readOnly"` fields, `@mutability: "writeOnce"` fields
+  (settable on POST, frozen thereafter), `origin.*`-derived fields.
+  `@autoSet:onUpdate` columns are stamped server-side regardless of the caller;
+  `@autoSet:onCreate` columns are not patch-settable.
+  **A non-settable key present in a PATCH body is STRIPPED, not rejected.** The
+  generated `<Entity>UpdateSchema` is a plain `z.object()` (never `.strict()`) that
+  simply omits every non-settable field, and Zod drops unknown keys — so
+  `safeParse` succeeds and the key never reaches the `SET`. The TPH discriminator
+  is additionally deleted by hand after parse, the same convention. A malformed
+  *value* on a settable key is still `400 {"error":"validation"}`.
+  This matters for `writeOnce` specifically: the generated edit form submits EVERY
+  registered field (`handleSubmit` passes all values, and 0.19.2 switched the
+  resolver to `UpdateSchema` on edit rather than diff-and-omit), so rejecting a
+  present-but-frozen key would fail every save on every generated edit form for an
+  entity carrying one.
 - **PATCH-4 (validation).** Assigned values run the same per-field validation and
   the same write codec as `create`.
 - **PATCH-5 (empty patch).** Zero assignments is a no-op — the current row is read

fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-audit/references/capability-checklist.md

@@ -50,8 +50,11 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
 - **`field.map`** (`@valueType`) — hunt ad-hoc open-keyed key/value bags stuffed into a jsonb
   column by hand.
 - **Common field attrs** — `@column` (hand column-name mapping), `@default` (hand default
-  assignment), `@required` (hand presence checks), `@unique` (hand uniqueness), `@readOnly`
-  (hand write-guards), `@filterable` / `@sortable` (hand filter/sort allowlists),
+  assignment), `@required` (hand presence checks), `@unique` (hand uniqueness),
+  `@mutability` (hand write-guards: `readOnly` for a column the DB/replication owns,
+  `writeOnce` for one set at create and never changed — hunt hand-written
+  "cannot be modified after creation" checks), `@filterable` / `@sortable`
+  (hand filter/sort allowlists),
   `@dbColumnType` (hand native-type override), `@example` / `@instruction` (hand prompt
   hints), `@xmlText` (hand XML-text mapping). The `@db.indexed` attr suppresses the
   *`@filterable`-without-index* Loader warning (you assert the column is indexed by other

fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-audit/references/capability-checklist.md

@@ -50,8 +50,11 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
 - **`field.map`** (`@valueType`) — hunt ad-hoc open-keyed key/value bags stuffed into a jsonb
   column by hand.
 - **Common field attrs** — `@column` (hand column-name mapping), `@default` (hand default
-  assignment), `@required` (hand presence checks), `@unique` (hand uniqueness), `@readOnly`
-  (hand write-guards), `@filterable` / `@sortable` (hand filter/sort allowlists),
+  assignment), `@required` (hand presence checks), `@unique` (hand uniqueness),
+  `@mutability` (hand write-guards: `readOnly` for a column the DB/replication owns,
+  `writeOnce` for one set at create and never changed — hunt hand-written
+  "cannot be modified after creation" checks), `@filterable` / `@sortable`
+  (hand filter/sort allowlists),
   `@dbColumnType` (hand native-type override), `@example` / `@instruction` (hand prompt
   hints), `@xmlText` (hand XML-text mapping). The `@db.indexed` attr suppresses the
   *`@filterable`-without-index* Loader warning (you assert the column is indexed by other

fixtures/agent-context-conformance/python/expected/.claude/skills/metaobjects-audit/references/capability-checklist.md

@@ -50,8 +50,11 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
 - **`field.map`** (`@valueType`) — hunt ad-hoc open-keyed key/value bags stuffed into a jsonb
   column by hand.
 - **Common field attrs** — `@column` (hand column-name mapping), `@default` (hand default
-  assignment), `@required` (hand presence checks), `@unique` (hand uniqueness), `@readOnly`
-  (hand write-guards), `@filterable` / `@sortable` (hand filter/sort allowlists),
+  assignment), `@required` (hand presence checks), `@unique` (hand uniqueness),
+  `@mutability` (hand write-guards: `readOnly` for a column the DB/replication owns,
+  `writeOnce` for one set at create and never changed — hunt hand-written
+  "cannot be modified after creation" checks), `@filterable` / `@sortable`
+  (hand filter/sort allowlists),
   `@dbColumnType` (hand native-type override), `@example` / `@instruction` (hand prompt
   hints), `@xmlText` (hand XML-text mapping). The `@db.indexed` attr suppresses the
   *`@filterable`-without-index* Loader warning (you assert the column is indexed by other

fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/skills/metaobjects-audit/references/capability-checklist.md

@@ -50,8 +50,11 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
 - **`field.map`** (`@valueType`) — hunt ad-hoc open-keyed key/value bags stuffed into a jsonb
   column by hand.
 - **Common field attrs** — `@column` (hand column-name mapping), `@default` (hand default
-  assignment), `@required` (hand presence checks), `@unique` (hand uniqueness), `@readOnly`
-  (hand write-guards), `@filterable` / `@sortable` (hand filter/sort allowlists),
+  assignment), `@required` (hand presence checks), `@unique` (hand uniqueness),
+  `@mutability` (hand write-guards: `readOnly` for a column the DB/replication owns,
+  `writeOnce` for one set at create and never changed — hunt hand-written
+  "cannot be modified after creation" checks), `@filterable` / `@sortable`
+  (hand filter/sort allowlists),
   `@dbColumnType` (hand native-type override), `@example` / `@instruction` (hand prompt
   hints), `@xmlText` (hand XML-text mapping). The `@db.indexed` attr suppresses the
   *`@filterable`-without-index* Loader warning (you assert the column is indexed by other

fixtures/agent-context-conformance/ts-requirements/expected/.claude/skills/metaobjects-audit/references/capability-checklist.md

@@ -50,8 +50,11 @@ classify it (using the classification scheme in `SKILL.md`) and route the cutove
 - **`field.map`** (`@valueType`) — hunt ad-hoc open-keyed key/value bags stuffed into a jsonb
   column by hand.
 - **Common field attrs** — `@column` (hand column-name mapping), `@default` (hand default
-  assignment), `@required` (hand presence checks), `@unique` (hand uniqueness), `@readOnly`
-  (hand write-guards), `@filterable` / `@sortable` (hand filter/sort allowlists),
+  assignment), `@required` (hand presence checks), `@unique` (hand uniqueness),
+  `@mutability` (hand write-guards: `readOnly` for a column the DB/replication owns,
+  `writeOnce` for one set at create and never changed — hunt hand-written
+  "cannot be modified after creation" checks), `@filterable` / `@sortable`
+  (hand filter/sort allowlists),
   `@dbColumnType` (hand native-type override), `@example` / `@instruction` (hand prompt
   hints), `@xmlText` (hand XML-text mapping). The `@db.indexed` attr suppresses the
   *`@filterable`-without-index* Loader warning (you assert the column is indexed by other

fixtures/conformance/ERROR-CODES.json

@@ -57,8 +57,9 @@
     "ERR_SOURCE_UNRESOLVED": "Phase-1 metadata-source-resolution: a path source declared in .metaobjects/config.json does not exist on disk.",
     "ERR_PHYSICAL_NAME_KIND_MISMATCH": "FR-016 / ADR-0018: a source.rdb declares a kind-aware physical-name alias (@view/@materializedView/@proc/@function) that does not match its @kind. The legacy @table-for-non-table case warns rather than errors.",
     "ERR_PHYSICAL_NAME_MULTIPLE": "FR-016 / ADR-0018: a source.rdb declares two or more kind-aware physical-name aliases at once (e.g. both @table and @view). Exactly one is permitted.",
-    "ERR_READONLY_ASSIGNED_PRIMARY": "FR-013: a field with @readOnly: true is the target of an identity.primary with @generation: \"assigned\". The application has no path to populate the identity value (no setter; not generated; not defaulted).",
-    "ERR_READONLY_DOWNGRADE": "FR-013: a concrete entity declares @readOnly: false on a field whose extends-chain parent declares @readOnly: true. Read-only-ness can only be upgraded, never downgraded.",
+    "ERR_MUTABILITY_AUTOSET_CONFLICT": "FR-037 R1: a field declares @autoSet together with @mutability \"writeOnce\" or \"readOnly\". @autoSet already means the SERVER supplies the value; @mutability says who may write it. The pair states two contradictory things about one column. The boolean era left readOnly x @autoSet representable but UNVALIDATED; the enum cut closes both arms with one rule.",
+    "ERR_MUTABILITY_DOWNGRADE": "FR-037 R1: a subtype LOOSENS an inherited @mutability mode. A subtype may only tighten (readWrite < writeOnce < readOnly), never loosen. Replaces ERR_READONLY_DOWNGRADE, which was renamed because the rule now spans three modes and a code named READONLY would misdescribe a writeOnce -> readWrite loosening.",
+    "ERR_READONLY_ASSIGNED_PRIMARY": "FR-037 R1: a field with @mutability: \"readOnly\" is the target of an identity.primary with @generation: \"assigned\". The application has no path to populate the identity value (no setter; not generated; not defaulted). KEEPS its readOnly-specific name because the condition is readOnly-specific: @mutability: \"writeOnce\" on an assigned primary key is LEGAL, and indeed the natural declaration for one.",
     "ERR_PARAMETER_REF_UNRESOLVED": "FR-015: source.rdb @parameterRef names an object that does not exist in the loaded model.",
     "ERR_PARAMETER_REF_NOT_VALUE_OBJECT": "FR-015: source.rdb @parameterRef references an object.entity instead of object.value. Input shapes are value-objects by definition (no identity).",
     "ERR_PARAMETER_REF_ON_NON_CALLABLE_KIND": "FR-015: source.rdb @parameterRef is set with @kind: \"table\" / \"view\" / \"materializedView\". These kinds do not accept parameters; only \"storedProc\" / \"tableFunction\" do.",

fixtures/conformance/error-field-mutability-autoset-conflict/expected-errors.json

@@ -0,0 +1,15 @@
+{
+  "errors": [
+    {
+      "code": "ERR_MUTABILITY_AUTOSET_CONFLICT",
+      "source": {
+        "format": "json",
+        "files": [
+          "meta.demo.json"
+        ],
+        "jsonPath": "$['metadata.root'].children[0]['object.entity'].children[2]['field.timestamp']"
+      }
+    }
+  ],
+  "warnings": []
+}

fixtures/conformance/error-field-mutability-autoset-conflict/input/meta.demo.json

@@ -0,0 +1,37 @@
+{
+  "metadata.root": {
+    "package": "demo",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Customer",
+          "children": [
+            {
+              "source.rdb": {
+                "@table": "customers"
+              }
+            },
+            {
+              "field.long": {
+                "name": "id"
+              }
+            },
+            {
+              "field.timestamp": {
+                "name": "createdAt",
+                "@autoSet": "onCreate",
+                "@mutability": "readOnly"
+              }
+            },
+            {
+              "identity.primary": {
+                "name": "id",
+                "@fields": "id"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}