Architecture decision records

This section captures the durable architectural decisions behind Pina’s public model, safety posture, and verification strategy.

ADR format and naming

ADR	Status	Decision
ADR 0001	Accepted	Keep discriminator bytes as the first field inside typed layouts.
ADR 0002	Accepted	Keep zero-copy for fixed-size Pod layouts, but only behind explicit validation.
ADR 0003	Accepted	Keep runtime borrow guards alive for the full typed loader lifetime.
ADR 0004	Accepted	Preserve `no_std` / no-allocator constraints for on-chain code paths.
ADR 0005	Accepted	Keep SPL token support optional and feature-gated.
ADR 0006	Accepted	Treat CI as layered verification, not a single all-purpose test lane.
ADR 0007	Proposed	Make migrations a generated, on-demand, versioned ABI compatibility boundary.
ADR 0008	Proposed	Reserve a migration instruction, add client migrate-first flow, and support adopting migrations on already-launched programs.
ADR 0009	Accepted	Give `pina_abi` its own release line, pin a committed `abiVersion` to it, reset the document to stored facts, and publish generated JSON Schemas.
ADR 0010	Accepted	Bound the entrypoint account array per program and keep pinocchio as a library; ADR 0011 proposes revisiting its rejection of a dispatcher.
ADR 0011	Proposed	Dispatch on the SIMD-0321 instruction-data pointer before reading accounts, parse only the routed instruction’s accounts, and re-verify stored-bump PDAs with `sha256`.
ADR 0012	Accepted	Judge instruction account slots on wire facts only; `defaultValue` and `pda` client hints never block a version.

Use these ADRs when you need to answer questions like:

why Pina uses discriminator-first layouts instead of external headers
when zero-copy is allowed, and where the safety boundaries are
why typed account loaders must be guard-backed instead of returning bare references
why no_std and allocator constraints are treated as architecture, not implementation detail
why token helpers are optional instead of always-on
why Miri, compile-fail tests, feature matrices, and compute-unit checks all exist at once
why the ABI document’s abiVersion is a committed value pinned to pina_abi’s own release line instead of counting format revisions
why a changed PDA or known-address hint on an instruction account never blocks a published version