fix(models): retired labels are refused by value on every write path; the primary-key refusal names its fix (panel F4, F5, F8)

[0x054]

Part of #623 (panel fix round for PR #636; #625 and #627's files)

F4: a retired label on a plain Enum is now refused

Before this change, the guard only checked values that were a str. A field typed as a plain class Status(Enum): CANCELED = "canceled" holds the member after validation, and that member is not a str. So Order(status=Status.CANCELED) and order.status = Status.CANCELED wrote the retired label without any error.

Now one helper, written_retired_label, compares the value that would actually be written: member.value for any enum member, or the raw string. The construction validator and the class-level __setattr__ both use it. The __setattr__ is still installed only when validate_assignment is off. The guard stays per-field, and Model gets no __setattr__ of its own. Hydration still bypasses the guard (I-2).

Tests in tests/test_retired_labels.py:

• test_a_plain_enum_refuses_the_retired_label_on_construction[False|True]
• test_a_plain_enum_refuses_the_retired_label_on_assignment[False|True]
• test_a_hydrated_plain_enum_retired_row_changes_another_field_and_saves, which runs on both backends with both validate_assignment settings

F5: the retired primary-key refusal names its fix

The refusal now reads:

Author.id: a primary key cannot be retired; drop `retired=True`. To remove the key, change the primary key first: see the Migrations docs § Changing a primary key

The migrations guide's list of refusals now gives the fix for this case too, as it does for the others. Test: tests/test_retired_columns.py::test_retiring_a_primary_key_is_refused_naming_the_fix pins the full text.

F8: update() refuses a retired enum label

Before this change, Model.where(...).update(status=Status.CANCELED) wrote the retired label to every matching row.

Now the literal SETs for both keyword update(status=...) and the recipe form update(lambda o: {"status": ...}) go through refuse_retired_label_write (in metaclass.py) before anything is compiled. It uses the same by-value comparison as F4 and raises the same retired_enum_label ValidationError. Column copies and arithmetic are not literals, so they are not checked: an enum column cannot be an arithmetic target.

Test: test_update_refuses_the_retired_label_and_writes_nothing. It covers keyword and recipe × StrEnum and plain Enum × sqlite and postgres, for both the member and the raw string. It also checks that the row is unchanged and that a later update() without the label still works.

Verify (on 8c4cd01)

uv run maturin develop                                  -> exit 0
cargo check --all-targets                               -> exit 0
uv run pytest -v tests/test_ir_vectors_contract.py      -> exit 0, 14 passed
uv run pytest --db-backends=sqlite,postgres tests/test_retired_labels.py tests/test_retired_columns.py tests/test_schema_enum_annotations.py tests/test_enum_cold_hydration.py tests/test_generate_enum_removal.py tests/test_generate_retired.py tests/test_hydration.py tests/test_docs_examples.py tests/test_docs_migrations.py
                                                        -> exit 0, 438 passed
uv run prek run --all-files                             -> exit 0

Outside Files owned

None. The changed files are src/ferro/metaclass.py, src/ferro/query/wire.py, tests/test_retired_labels.py, tests/test_retired_columns.py and the one retirement sentence in docs/pages/guide/schema/migrations.md. models.py and ir/compiler.py are unchanged.

• Issue status: Retired columns: Field(retired=True) leaves the model, stays in the snapshot nullable, generates DROP NOT NULL (#619) #625 and Retired labels: __ferro_retired_labels__ keeps the member and refuses the write (#619) #627 stay closed; this PR is part of Spec: Pinch migration needs — typed baseline refusal, retired columns and labels, expand-only allow_ahead, migrate new --replace, defaults in drift (#618–#622) #623 and closes nothing.

🤖 Generated with Claude Code

https://claude.ai/code/session_014ERLk8yFhJy7rdDyU7rGdR

[0x054]

Scoped re-review: F4, F5, F8

Reviewed the fix diff c9e3f61..8c4cd01.

• F4: ADDRESSED. src/ferro/metaclass.py:111 written_retired_label compares the value that would be written: member.value for any Enum, otherwise the raw value. That catches a StrEnum member, a plain Enum member and a raw string. Both guards use it: _label_guard (:158) and _guarded_setattr (:168). The labels checked are always the field's own enum's (retired_labels[field_name]; in update(), _enum_fields[column]), so a different enum's retired label on another field cannot refuse a write. Hydration still runs neither guard (I-2). test_a_hydrated_plain_enum_retired_row_changes_another_field_and_saves pins hydrate-then-save for a plain Enum.
• F5: ADDRESSED. src/ferro/metaclass.py:76 names the fix ("drop retired=True. To remove the key, change the primary key first: see the Migrations docs § Changing a primary key"). It agrees with docs/pages/guide/schema/migrations.md:226, which links to §399. A test pins the text.
• F8: ADDRESSED. src/ferro/query/wire.py:558 _guarded_literal_assignment covers every literal SET: keyword update() (:596) and the recipe form (:827). The non-literal recipe values (column copy, arithmetic, now, .merge()) do not write a label literal. save() is untouched, so writing back an unchanged hydrated label still works.
• models.py and ir/compiler.py are untouched. No new findings.

Merge preview with origin/feat/pinch-migration-needs (36670c4): the merge is clean, cargo check --all-targets exits 0, and the merge was aborted afterwards.

Verify block on 8c4cd01:

• uv run maturin develop: exit 0
• cargo check --all-targets: exit 0
• pytest tests/test_ir_vectors_contract.py: exit 0 (14 passed)
• pytest --db-backends=sqlite,postgres on the nine listed files: exit 0 (438 passed)
• uv run prek run --all-files: exit 0