ADR-010: Authority comes from roles, never from balances; RETIRED is terminal

Context

The earlier design let any holder of a single unit change a lot's lifecycle state, including to terminal states. In a lot held by many parties, that let a minority holder retire everyone else's goods. Status changes in agriculture are made by accountable institutions: a warehouse accepting delivery, an inspector condemning a lot, a registry cancelling a receipt.

Issue

Who may change a lot's status and metadata, and which status changes are irreversible?

Assumptions

• Lots commonly have many holders.
• Status changes correspond to acts of identifiable institutions.

Constraints

• No authority may derive from token balances.

Alternatives considered

Decision

setBatchStatus and setBatchMetadata require STATUS_ROLE. Status 255 (RETIRED) cannot be changed again; a retired lot cannot be minted, transferred or transformed, and can still be burned so that delivered or destroyed goods leave the supply.

Argument

Tying status to a role makes every change attributable to an institution through an event with a reason, which is what disputes and audits require. A terminal state gives integrators one invariant they can rely on.

Consequences

Positive

• A minority holder cannot touch the lot's state.
• RETIRED is a guarantee indexers and marketplaces can rely on.

Negative

• The role holder can retire lots held by others; this power must be disclosed to holders.

Obligations it creates

• Assign STATUS_ROLE to an accountable institution and document when it acts.
• Every change emits BatchStatusChanged with a reason.

Implementation and evidence

Related decisions

• ADR-006: Open codes instead of closed enumerations
• ADR-007: Lineage through an atomic transform operation
• ADR-012: Forced transfers bypass pause and eligibility but still run hooks