@consiliency/agent-board-schema 1.22.0 → 1.24.0

package/README.md

@@ -26,7 +26,7 @@ agent-board-schema materialize --target <adopter>/supabase/migrations
 
 # Read-only posture against a supplied migration-history snapshot.
 agent-board-schema plan  --history history.json
-agent-board-schema check --history history.json     # exit 0 exact / 10 behind / 11 ahead / 12 divergent
+agent-board-schema check --history history.json     # exit 0 exact / 10 behind / 11 ahead / 12 divergent / 14 collision
 
 # Self-contained smoke: byte-exact + idempotent materialize.
 agent-board-schema materialize --check-smoke
@@ -35,6 +35,80 @@ agent-board-schema manifest    # print the compatibility manifest
 agent-board-schema version
 ```
 
+## Version collisions — build `history.json` from real rows, not from versions
+
+**Supabase keys `supabase_migrations.schema_migrations` on the 14-digit version
+prefix alone, not the name.** If you have independently authored a migration at a
+version this bundle also uses, your database has that version recorded under *your*
+name and the bundle's migration is **skipped silently** — no error, and
+`schema_version` still reports the bundle's number, so the deploy looks successful.
+
+This is not hypothetical. It happened at `20260809000100`, where an adopter's
+`reconcile_panel_schema_drift` occupied the version used by
+`agent_board_consent_gating` (message-board#217). 50 of this bundle's migrations share
+the `000100` suffix, so if you also mint fixed-suffix timestamps the odds are far
+above random.
+
+**Build the history from version *and* name**, so `check` can see it. Let Postgres
+do the encoding — a shell pipeline breaks on a name containing `:` or a quote, and
+an empty result set produces a file that will not parse:
+
+```bash
+psql "$DATABASE_URL" -At -c \
+  "select coalesce(json_agg(json_build_object('id', version || '_' || coalesce(name, ''))), '[]'::json)
+     from supabase_migrations.schema_migrations" \
+  | sed 's/^/{"applied":/; s/$/}/' > history.json
+
+agent-board-schema check --history history.json
+```
+
+A history built from **versions alone** cannot detect this — matching on the version
+prefix is precisely the check that reports success on an affected database.
+
+`check` exits **14** and names both sides:
+
+```
+collision @20260809000100:
+  expected    20260809000100_agent_board_consent_gating
+  recorded as 20260809000100_reconcile_panel_schema_drift
+```
+
+Exit 14 is deliberately not `behind` (10). "Behind" invites the fix of applying
+again, which is the no-op that leaves the database wrong.
+
+**Single-version discriminator**, if you only want to check the known case:
+
+```sql
+select name from supabase_migrations.schema_migrations where version = '20260809000100';
+-- agent_board_consent_gating -> healthy
+-- anything else              -> this database skipped the bundle migration
+```
+
+**Remediation.** From bundle version 1.24.0 you do not need one:
+`20260905000100_agent_board_consent_gating_reconcile` re-applies the only function
+left stale by that skip (`join_board` — the other two are superseded by later
+migrations that carry the gating forward). It is byte-identical on a healthy
+database and self-healing on an affected one, with no `supabase migration repair`.
+
+**A healed database stops reporting `collision`, even though the row is permanent.**
+`schema_migrations` keys on `version`, its primary key, so the adopter's row at a
+collided version can never be removed. `check` therefore reports on whether the
+*remediating migration is applied*, not on whether the row exists — otherwise a
+database that had done everything right would gate red forever, and an adopter
+trained to ignore exit 14 would stop seeing genuine `behind` and `divergent`
+states too. A remediated collision is reported under `collisionsRemediated` and both halves of
+the pair are removed from the counts, so a healed database reports **`exact` / exit
+0**. Removing them is the whole point: the bundle's migration can never be applied
+there (its version is taken) and your row can never be removed, so left in they would
+report `behind` forever — a different permanent red than the one being fixed.
+
+A row whose `name` is NULL is treated as **indeterminate**, not as a collision: it
+carries no name to tell apart from the bundle's own migration at that version. The
+same applies to a history built from bare version strings.
+
+For a collision at any *other* version there is no declared healer, so `check`
+keeps reporting it and the fix is a `migration repair` on your side.
+
 After applying the materialized migrations, the adopter records the install so the
 authenticated compatibility RPC reports live:
 

package/fixtures/already-applied.json

@@ -452,6 +452,46 @@
     {
       "id": "20260831000100_agent_board_fleet_domain_reclaim",
       "sha256": "8d24ec4d682969a5d9339aec0573fad65ee95993dce2f8dca214906549b5ebe8"
+    },
+    {
+      "id": "20260901000100_agent_board_atomic_fleet_onboarding",
+      "sha256": "4cf07673b7c7da4ee13550e71d2bfe606b4b9c56971169e1ef61ac0d545ac6ef"
+    },
+    {
+      "id": "20260901000110_agent_board_fleet_onboarding_ceiling_lock",
+      "sha256": "310a32931562be6b4ad323b5e2926ebe459d6cd31bd6f601c7b862f354b5ce58"
+    },
+    {
+      "id": "20260901000120_agent_board_human_revocation_evidence_completeness",
+      "sha256": "e8ccb3605fb6dfa4e8dfbefbbb4328179a61aec00616c1abef27d6a09c2a913e"
+    },
+    {
+      "id": "20260901000130_agent_board_fedsession_human_revocation_gate",
+      "sha256": "f76d78973b87cc66c54ca0af4754358221ede19c8e0644df81a08e65dab0e89b"
+    },
+    {
+      "id": "20260901000140_agent_board_fedsession_board_owner_lock_order",
+      "sha256": "2388528532e974ab27c35337f9b00263056c1b16d973b7b3a0cf8cebb7724cc4"
+    },
+    {
+      "id": "20260902000100_agent_board_outbox_wake_ordering",
+      "sha256": "d3557acc29bf146862920fe903c3ac2e9e0e0317f3ca2134c5bb0835620fd2da"
+    },
+    {
+      "id": "20260903000100_agent_board_enroll_identity_board_owner_lock_order",
+      "sha256": "f8dc4ae6c5c6ea56183258402ab283cd424929b8e637984a59cf6ecd0685f681"
+    },
+    {
+      "id": "20260903000200_agent_board_fedsession_provider_absence_gate",
+      "sha256": "79c581011be386d0efd97db723d3aa07947ad7b996667878ed1387cdd106b000"
+    },
+    {
+      "id": "20260904000100_agent_board_wake_recovery_surface",
+      "sha256": "6349f705751104c5d60ec6602ea534e7c8b7de5c4c6ad2d84dbda680a5267848"
+    },
+    {
+      "id": "20260905000100_agent_board_consent_gating_reconcile",
+      "sha256": "d5328a0006ecd1ec940c4fde5bbb43acf29b0997eefbea557009f792868e298b"
     }
   ]
 }