From 4da22a76354f63c7841cf02fc26446039647aa05 Mon Sep 17 00:00:00 2001 From: Wes Date: Wed, 5 Aug 2026 11:37:38 -0600 Subject: [PATCH] Document PMA fence and migration lock cost Define the last-binding behavior for shared definition coordinates and call out migration 0028's ACCESS EXCLUSIVE full-table rewrite before capability rollout. Co-authored-by: Carl Signed-off-by: Wes --- docs/nips/NIP-PMA.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/nips/NIP-PMA.md b/docs/nips/NIP-PMA.md index 1cc7f9770c..95c7c1b881 100644 --- a/docs/nips/NIP-PMA.md +++ b/docs/nips/NIP-PMA.md @@ -107,6 +107,26 @@ same definition coordinate; each immutable aggregate revision retains its exact bound recovery bytes while catalog browsing reads the latest active public projection. Browsing never requires decrypting kind `30179`. +The relay's ordinary-write fence for a `30175` definition coordinate follows +active aggregate bindings, not retained definition revision history. When the +last active agent bound to a definition is tombstoned, that coordinate is no +longer PMA-authoritative and an ordinary owner-authored NIP-33 write may become +the public head. `managed_agent_definition_heads` still retains the revision +floor; a later aggregate rebind advances from that retained revision rather than +adopting generic LWW history as an untracked revision. Deleted `30177` instance +coordinates remain fenced by their deleted aggregate head, so neither ordinary +writes nor legacy kind `5` deletion can bypass generation CAS. + +## Deployment note: migration 0028 + +`0028_private_managed_agent_foundation.sql` changes `events.search_tsv` by +dropping and re-adding the generated stored column, then rebuilding its GIN +index. PostgreSQL performs a full `events` table rewrite while holding an +`ACCESS EXCLUSIVE` lock. Operators MUST treat this as planned write downtime, +size the migration window from production table/index size, and complete the +migration before deploying binaries that advertise `nip-pma-aggregate-v1`. +Rolling application deployment does not make this DDL online. + ## Required deployment order 1. **Inert reservation:** codec and kind reservation while generic ingest still