feat(equipment): Asset.persistent_id write path + DoiMinter port + Stub adapter (slice F.1)

[xmap]

Summary

Closes the D-ASSIGN deferral from slice E.1 (PR #34). Adds the WRITE path for PIDINST v1.0 Property 1 at the Asset tier:

• Asset.persistent_id: PersistentIdentifier | None aggregate field (additive; default None; placed as LAST field per the verified field-ordering check)
• PersistentIdentifier frozen-dataclass VO with trim + 1-200 length invariant
• Closed PersistentIdentifierScheme StrEnum {DOI, HANDLE}, values matching PidinstIdentifierType byte-for-byte (no translation map at the serializer)
• AssetPersistentIdAssigned event (alphabetical position in __all__; grouped by domain-arm in the discriminated union per BC convention)
• assign_asset_persistent_id mutation slice (command + decider + handler + route + MCP tool)
• DoiMinter Protocol port at cora.equipment.ports.doi_minter
• StubDoiMinter adapter at cora.equipment.adapters.stub_doi_minter (ships in F.1, no DataCite credentials needed)
• Match/case serializer extension on _build_identifier with NO default arm (adding a third scheme member fires pyright as an unhandled-case error)
• Tach rows for cora.equipment.ports + cora.equipment.adapters

The production DataCite adapter (PUT /dois/{id} + HTTP Basic + 429 backoff + cassette tests) is deferred to F.2 behind facility-credential gating.

Why

Operators need a server-mint flow today so that downstream PIDINST serialization swaps from urn:uuid: to the assigned DOI as soon as the assign slice runs. Slice E.1 reserved the JSONB column and shipped the read closure; this slice closes the write side end-to-end on a Stub so the whole flow can be proven on the inert mint, then F.2 swaps the Stub for the production adapter once credentials land at the pilot facility.

Key locks

• Set-once domain invariant per F3.3 (DataCite Findable immutability): once Asset.persistent_id is set, no further assign / clear / reassign is accepted. Slice G owns withdraw via a separate timestamp facet.
• Server-mint posture per the non-determinism-injection principle: the route accepts (scheme, suffix | None) and the handler resolves the PersistentIdentifier from the DoiMinter port before invoking the pure decider, keeping the decider deterministic and trivially testable. ONE minter call site (the handler), not two (route + MCP tool).
• BC-tier wiring per the operation BC ControlPort precedent: wire_equipment(deps) stashes the StubDoiMinter on the equipment-deps namespace, NOT through the cross-BC Kernel dataclass.
• Error surface: 5 classes mapped uniformly. 400 InvalidPersistentIdentifierValueError, 404 AssetNotFoundError, 409 AssetPersistentIdAlreadyAssignedError + AssetPersistentIdAssignmentForbiddenError, 502 PersistentIdentifierMintError. PersistentIdentifierMintError lives at cora.equipment.ports.doi_minter next to the Protocol it documents, NOT in aggregates/asset/state.py, because it is an adapter-tier failure not a decider-raised genesis error.

Naming note

The slice directory was renamed from assign_persistent_id to assign_asset_persistent_id at implementation time per the test_slice_dir_carries_subject architecture fitness (sibling pattern: add_asset_owner, add_asset_alternate_identifier, add_asset_family, add_asset_port). The command class follows: AssignAssetPersistentId. The Pydantic wire models follow: AssignAssetPersistentIdRequest / AssignAssetPersistentIdResponse. The URL stays terse (/assets/{asset_id}/assign-persistent-identifier) because the URL path already carries the SUBJECT via /assets/.

Scale

40 files, 3943 insertions / 6 deletions. 118 slice tests + 16657 architecture-tier tests passing post-rebase.

Test plan

• Unit tests: VO + PBT + scheme + decider + decider-PBT + evolver + events + summary-projection + serializer + wire (10 files)
• Integration tests: route (full HTTP matrix incl. 502 mint-error path) + tool (MCP) + pidinst-view round-trip (3 files)
• Contract test: OpenAPI shape + 7-status documentation
• Architecture fitness: paired-PBT for new decider, decider-purity (no minter import), no-clear-no-reassign command, scheme byte-match, slice-subject, all pre-existing fitness green
• Pre-commit: ruff + ruff-format + pyright + tach + secrets + architecture-fitness all green

Follow-ups

• F.2 (production DataCite adapter; gated on facility credentials)
• Slice E.Fixture (parallel Fixture-tier PIDINST design memo; tracked at project_fixture_configuration_hash_followup)

Closes the D-ASSIGN deferral from slice E.1.

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
__init__.py
_asset_persistent_identifier_body.py
_pidinst_serializer.py
_pidinst_types.py
routes.py					327-328
tools.py
wire.py					216
apps/api/src/cora/equipment/adapters
stub_doi_minter.py
apps/api/src/cora/equipment/aggregates/asset
events.py
evolver.py
state.py
apps/api/src/cora/equipment/features/assign_asset_persistent_id
__init__.py
command.py
decider.py
handler.py
route.py
tool.py
apps/api/src/cora/equipment/ports
__init__.py
doi_minter.py
apps/api/src/cora/equipment/projections
asset.py					330
Project Total

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