feat(equipment): Asset.model_id binding + cross-BC subset invariant (closes Lock 6 + Lock 9)

[xmap]

Summary

Closes the Lock 6 + Lock 9 deferral from the Model design memo via the locked Stage 1 design (project_asset_model_binding_design.md). Purely additive on the Asset BC: one optional field, one optional event payload key, one nullable projection column, no new slices, no new event types.

Asset gains optional model_id: UUID | None = None set ONCE at register_asset time (per Lock A; rebind via decommission + re-register, no bind_asset_to_model slice in v1).

Cross-BC subset invariant Model.declared_families ⊆ Asset.family_ids enforced at add_asset_family when the Asset has a bound Model. At register_asset the bind is permissive (load to verify Model exists, but no subset assertion at genesis because Asset.family_ids starts empty; subset would be vacuous). NOT enforced at remove_asset_family per Lock B (eventual-consistency posture). No cascade-validation when Model.add_model_family fires (Lock C); no refusal of Deprecated-Model binding (Lock D, Family-deprecation posture extended).

Commits (2)

1. a22ef3b64 Implementation: 2 slice mods (register_asset + add_asset_family) + AssetModelMismatchError class + 1 Atlas migration + projection update + 28 test files. ~2200 LOC.
2. b7a3d614e Gate-review P1 fixes: idempotency-key + model_id contract test + AssetModelMismatch → AssetModelMismatchError rename (drift-catcher visibility) + revert 5 phantom Method.needs.families docstring renames.

Verification

• Stage 3 gate review (7-axis: architecture / test-coverage / cross-BC-consistency baseline + standards-alignment specialist + security + migration-safety + design-memo-conformance): 0 P0, 3 P1 all resolved in commit 2.
• 3625 Asset + Model + architecture tests pass, 0 failures. ruff clean, pyright 0/0/0, tach clean.
• Atlas migration 20260602110000_add_asset_summary_model.sql is forward-only ADD COLUMN + partial index WHERE model_id IS NOT NULL.
• AssetModelMismatchError correctly visible to both fitness gates (_error_class_names + _bc_error_classes); drift catcher will fire on future regressions.
• The idempotency-key + model_id collision case explicitly tested at the contract tier.

Design-memo conformance

All 9 Locks (A through I) honored:

• A: model_id set-once at register; no bind_asset_to_model slice
• B: subset at add_asset_family; permissive at register_asset; NOT at remove_asset_family
• C: no Model-side cascade
• D: Deprecated-Model NOT refused
• E: AssetModelMismatchError carries both sets verbatim; 409 via cannot_transition_cls
• F: forward-only ADD COLUMN + partial index; no event upcasting
• G: omit-when-None for model_id key (mirrors Asset.drawing precedent)
• H: gate review = baseline + standards-alignment (this PR)
• I: single-stream-write; no append_streams

All Anti-hooks respected (no append_streams, no validate at remove_asset_family, no cascade, no bind_asset_to_model slice, no frozenset[UUID] for model_id, no in-state subset invariant, no Deprecated-Model refusal).

Deferred (tracked as Watch items in the design memo)

• bind_asset_to_model slice (Option C) — fires on first re-cataloging operator request
• Model-side cascade reaction — fires if pilot ops report stale Asset bindings
• ModelDeprecatedForNewAsset soft refusal — revisit at pilot operator surface
• PIDINST DOI mint slice — now sibling-unblocked by this commit (the other side, Asset.alternate_identifiers, is the parallel slice)

Test plan

• Local pytest: 3625 Asset + Model + architecture tests pass
• Local ruff + pyright clean across the changed tree
• Local pre-commit hooks pass on both commits
• Atlas migration syntactically validated (forward-only ADD COLUMN + partial index)
• Stage 3 gate review (7-axis) executed; all P1 findings resolved
• CI run on push (this PR)
• Manual smoke test of POST /assets with model_id + POST /assets/{id}/families subset gate

Note on main CI

Main has been CI-red for several commits due to a pre-existing conduct_procedure Operation BC test bug (unrelated to this PR; admin-merged at #17 with the same scope-isolation reasoning). This PR inherits that failure. The 2 failing tests are NOT in our diff and the rest of CI is green.

Co-Authored-By: Claude Opus 4.7 noreply@anthropic.com

🤖 Generated with Claude Code

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
apps/api/src/cora/equipment/aggregates/asset
events.py
evolver.py
state.py
apps/api/src/cora/equipment/features/add_asset_family
handler.py
apps/api/src/cora/equipment/features/register_asset
command.py
decider.py
handler.py
route.py
tool.py
apps/api/src/cora/equipment/projections
asset.py
Project Total

This report was generated by python-coverage-comment-action