TracePass passport lifecycle (irreversible actions)

WARNING: Every action here changes what the public sees or is a legal act, some irreversible. archive permanently removes the public QR code (it 404s forever). record_registration records the economic operator's registration in the production EU DPP Registry and locks the passport's operator and facility identifiers. place_on_market submits a registration to an EN 18222 registry API. The assistant MUST confirm with the user before each call. Use suspend (reversible — public QR shows 'suspended') as the safe alternative to archive when a change might need to be undone; a passport placed on the market cannot be suspended, because it must stay public.

EU DPP REGISTRY: the economic operator registers a battery passport itself, on the EU DPP Registry website under its own EU Login. TracePass prepares what the operator submits (prepare_registry_upi / prepare_registry_upload_file in tracepass_passports) and records what the operator reports; it never submits to the Registry and never verifies the registration. The Registry's acceptance environment is for testing and has no legal effect (record_acceptance_test in tracepass_passports); only a registration in the production environment counts, and that is what record_registration records. The EU DPP Registry does not accept registrations through place_on_market. record_registration and undo_registration need a paid plan, and a connected app (OAuth) must act for an admin or owner.

Actions (pass via action, with args):

• record_registration — args: { id, placedOnMarketAt? (YYYY-MM-DD), registrationId? (≤200 chars) }. WRITE, battery passports only, published only. Records that the operator has registered this passport in the PRODUCTION EU DPP Registry, as the operator states it: TracePass does not check it with the Registry. Confirm with the user first, and only after the operator has registered on the Registry website. Effects: the passport is marked placed on the market (placeOnMarketStatus "placed", registrationMode "website"), the operator and facility party identifiers are locked (409 operator_locked on a later change), the backup copy is queued and the passport.placed_on_market webhook fires. placedOnMarketAt defaults to today; it may not be in the future or before the passport was first published. registrationId: the identifier the Registry gave, if any. Returns { passport }. Refusals: 400 Validation failed | invalid_date | date_in_future | date_before_publication | registration_id_too_long; 404; 409 not_a_battery | not_published | already_registered. A mistaken record can be undone with undo_registration. Counts 1 write.

• undo_registration — args: { id, environment: production|acceptance }. WRITE. Undoes a mistaken record. production: removes a registration recorded with record_registration (one made through place_on_market is not undone here), so the passport is no longer marked placed and its operator identifiers unlock; a webhook already delivered is not recalled. acceptance: removes the recorded acceptance test. It changes nothing in the Registry itself. Confirm with the user first. Returns { passport }. 404; 409 nothing_to_undo. Counts 1 write.

• place_on_market — args: { id }. WRITE, battery passports only, published only. Submits a registration to the EN 18222 registry API configured in the account's registry access settings. This is NOT the way into the EU DPP Registry, which does not accept it: for the EU DPP Registry use prepare_registry_upi / prepare_registry_upload_file and then record_registration. A legal act for the economic operator — confirm with the user first. ASYNCHRONOUS: answers 202 { passport, passportId, status: "placing", dppId } and the registry call follows in the background; read the passport (get) to follow placeOnMarketStatus: placing → placed (placedOnMarketAt, registrationId) or rejected (registrationRejectionReason). To retry a rejected passport, fix the cause and call place_on_market again. Refusals are 409 with a code: not_a_battery | not_published | already_placed (placing or placed) | operator_id_missing (no economic-operator identifier on the account) | registry_not_configured (an admin sets registry access in the dashboard) | registry_host_not_allowed (TracePass does not send registrations to the configured registry address; check the registry URL), registry_not_ready (findings[] lists what stands in the way — run registry_readiness for the structured findings). After placement the passport's party operatorIdentifier / facilityIdentifier are locked (409 operator_locked on a change). Counts 1 write.

• suspend — args: { id }. Reversible — public QR shows 'suspended'. Refused with 409 passport_placed_on_market once the passport is placed on the market or its registration is under way.

• suspend_by_serial — args: { serial, gtin? }. Same as suspend, addressed by your serial. 409 ambiguous_serial if the serial isn't unique in your account — pass gtin.

• archive — args: { id, reason? (recycled|never_placed|duplicate_or_error) }. never_placed is refused (409 reason_contradicts_placement) on a passport placed on the market. IRREVERSIBLE and destructive — confirm with the user first. The public QR permanently 404s. reason is REQUIRED for battery passports (400 reason_required / invalid_reason without a valid one): recycled, never_placed (never placed on the market or put into service), or duplicate_or_error (a duplicate or erroneous record); for other categories it is optional. A passport marked for deletion cannot be archived (409).

• archive_by_serial — args: { serial, gtin?, reason? }. IRREVERSIBLE and destructive, addressed by your serial — confirm first. Same reason rule as archive. 409 ambiguous_serial if the serial isn't unique — pass gtin.

• archive_product — args: { id }. Archives a PRODUCT (not a passport). Reversible — this soft-archives the product from the catalogue. Blocked (409) while any non-archived passport still references it — archive those passports first. Not deletion.