@consiliency/agent-board-schema 1.23.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

@@ -488,6 +488,10 @@
     {
       "id": "20260904000100_agent_board_wake_recovery_surface",
       "sha256": "6349f705751104c5d60ec6602ea534e7c8b7de5c4c6ad2d84dbda680a5267848"
+    },
+    {
+      "id": "20260905000100_agent_board_consent_gating_reconcile",
+      "sha256": "d5328a0006ecd1ec940c4fde5bbb43acf29b0997eefbea557009f792868e298b"
     }
   ]
 }

package/migrations/20260905000100_agent_board_consent_gating_reconcile.sql

@@ -0,0 +1,151 @@
+-- Reconcile join_board onto its consent-gated definition (message-board#217).
+--
+-- WHY THIS EXISTS. Supabase keys supabase_migrations.schema_migrations on the
+-- 14-digit VERSION PREFIX alone, not the name. An adopter that independently
+-- authored a migration at 20260809000100 therefore has that version recorded
+-- under its own name, and the bundle's 20260809000100_agent_board_consent_gating
+-- is SKIPPED SILENTLY -- no error, because that file is three
+-- `create or replace function` statements. The database reaches schema_version 8
+-- while retaining pre-consent authorization semantics, and the deploy reports
+-- success. Found by Consiliency/consiliency-portal while adopting 1.22.0.
+--
+-- WHY join_board AND NOTHING ELSE. The skipped file redefines three functions,
+-- but two of them are superseded by LATER migrations that carry the consent
+-- gating forward: resolve_board_request by 20260819000100 and
+-- update_board_membership by 20260813000100. join_board has no later definition
+-- -- its newest is the skipped one -- so on an affected database it is still the
+-- pre-consent 20260803000100 body. That single function is the entire live gap.
+--
+-- WHY NOT RENUMBER THE ORIGINAL. Renumbering looks safe because the migration is
+-- idempotent, but idempotent is not order-independent. On a HEALTHY database the
+-- renumbered file would be the only unapplied migration, so it would run LAST --
+-- after 20260813000100 and 20260819000100 -- and re-apply the older
+-- resolve_board_request and update_board_membership bodies over the newer ones.
+-- That is a silent authorization ROLLBACK on every correctly-adopted database,
+-- including production. A forward-only migration cannot do that, because it runs
+-- last by construction and carries the newest definition of the only function it
+-- touches.
+--
+-- EFFECT. Healthy database: byte-identical body, a true no-op. Affected database:
+-- receives the consent gating it never got, with no `supabase migration repair`
+-- and no operator intervention. `create or replace` preserves the existing ACL
+-- and this migration adds no new grants, so the privilege surface is unchanged
+-- either way.
+
+create or replace function agent_board.join_board(p_board_id uuid, p_agent_id uuid, p_membership_state text DEFAULT 'joined'::text, p_created_by_agent_id uuid DEFAULT NULL::uuid, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, created_at timestamp with time zone, updated_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+as $$
+declare
+  v_board agent_board.boards%rowtype;
+  v_existing_state text;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  -- GATENULL (#58): only service_role may proceed with an unresolved actor.
+  if v_actor is null and not agent_board._is_service_role() then
+    raise exception 'current agent principal not resolved' using errcode = '42501';
+  end if;
+
+  if p_membership_state not in ('joined', 'subscribed') then
+    raise exception 'join_board only accepts joined or subscribed' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_agent_id) then
+    raise exception 'agent not found' using errcode = 'P0002';
+  end if;
+  if p_created_by_agent_id is not null and not exists (select 1 from agent_board.agents where id = p_created_by_agent_id) then
+    raise exception 'creator agent not found' using errcode = 'P0002';
+  end if;
+
+  select * into v_board from agent_board.boards where id = p_board_id and status = 'active';
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+
+  -- MBROWID (3a): prefer ACTIVE standing for joinability / idempotent-join. A bare
+  -- total-order can surface a high-id REMOVED row while a low-id JOINED row exists,
+  -- locking an active member out of their own private / invite_only board (P0002).
+  select bm.membership_state
+    into v_existing_state
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+   order by
+     case when bm.membership_state in ('joined', 'subscribed') then 0 else 1 end,
+     bm.created_at desc,
+     bm.id desc
+   limit 1;
+
+  -- #82: the CREATOR EXEMPTION IS REMOVED. Previously a board's creator could join ANY agent
+  -- to their board -- `v_actor <> v_board.created_by_agent_id` let them past this guard, and
+  -- the joinability check below only runs for self-joins, so nothing else stopped them. That
+  -- is the force-join hole. Creating a board does not entitle you to place other people in it.
+  --
+  -- Only the subject may join the subject. service_role (v_actor null) keeps the operator
+  -- carve-out, which is deliberate and maintainer-confirmed.
+  if v_actor is not null and v_actor <> p_agent_id then
+    raise exception 'board membership actor mismatch' using errcode = '42501';
+  end if;
+
+  -- NULLFIX (CR): v_existing_state is NULL when the caller has NO membership row, and the original
+  -- guard then evaluated to NULL — `not (false or false or NULL)` is NULL, not TRUE — so `if NULL
+  -- then` never fired and ANY resolvable actor self-joined ANY board, private ones included. That
+  -- (not the null-actor bypass) was the true root cause of the live "joined a private invite_only
+  -- board with no invite" finding, and it is reachable by an ACTIVE agent, which the GATENULL guard
+  -- above cannot touch. coalesce() makes the absent-row case FALSE so the raise fires.
+  --
+  -- MBROWID (3b): a 'removed' agent is excluded from self-joining even an OPEN board via the
+  -- R-LINK-7 SET predicate (exists removed AND no active), not a single latest-row state.
+  -- Total-ordering the latest-row read alone is insufficient: a removed+left pair with equal
+  -- created_at can surface 'left' as the total-order winner while standing is still removed
+  -- (mutator + grant_board_role already use set-based rules). The three defenses must agree.
+  if v_actor is not null
+     and v_actor = p_agent_id
+     and v_board.created_by_agent_id <> v_actor
+     and not (
+       not (
+         exists (
+           select 1 from agent_board.board_memberships bm
+            where bm.board_id = p_board_id
+              and bm.agent_id = p_agent_id
+              and bm.membership_state = 'removed'
+         ) and not exists (
+           select 1 from agent_board.board_memberships bm
+            where bm.board_id = p_board_id
+              and bm.agent_id = p_agent_id
+              and bm.membership_state in ('joined', 'subscribed')
+         )
+       )
+       and (
+         v_board.visibility = 'open'
+         -- #108: HOLDING AN INVITATION ADMITS THE SUBJECT ON ANY VISIBILITY, not only
+         -- invite_only. Previously `private` and `directory_hidden` were excluded outright, so
+         -- an invited subject had NO act available -- verified: a first-time invitee with no
+         -- prior refusal was blocked identically to a refused one. Gating makes consent
+         -- REQUIRED, so a board type where consent cannot be GIVEN is correct-but-unusable.
+         --
+         -- This is the narrowest widening that makes consent exercisable. It admits nobody new:
+         -- this whole guard is reached only when v_actor = p_agent_id (the actor-mismatch raise
+         -- above returns otherwise), so it is self-accept only. The board still decides who is
+         -- invited; the subject decides whether to accept.
+         or coalesce(v_existing_state, '') = 'invited'
+         or coalesce(v_existing_state, '') in ('joined', 'subscribed')
+       )
+     ) then
+    raise exception 'board is not joinable by this agent' using errcode = 'P0002';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    p_membership_state,
+    coalesce(p_created_by_agent_id, p_agent_id),
+    p_metadata
+  );
+
+  return query
+  select v_membership.id, v_membership.board_id, v_membership.agent_id, v_membership.membership_state, v_membership.created_at, v_membership.updated_at;
+end;
+$$;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Canonical, immutable, exact-pinnable agent_board schema bundle: ordered SQL migrations, digest + compatibility manifest, and deterministic materialize/plan/check tooling for adopters.",
   "repository": "https://github.com/Consiliency/message-board.git",
   "type": "module",

package/schema-manifest.json

@@ -2,7 +2,7 @@
   "schema": "agent_board_schema_manifest.v1",
   "interface": "IF-0-MBPLANE-BUNDLE-1",
   "package": "@consiliency/agent-board-schema",
-  "packageVersion": "1.23.0",
+  "packageVersion": "1.24.0",
   "schemaVersion": 8,
   "minClientVersion": "1.1.0",
   "source": {
@@ -46,8 +46,8 @@
       "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
     }
   ],
-  "migrationCount": 122,
-  "aggregateSha256": "5bfa883d1264a31811a723ed8bd05b54227ae50c9266544d94830e8b3cdccfbf",
+  "migrationCount": 123,
+  "aggregateSha256": "f268991d3da80351c547d94249c48a5069a66267c3c1eaf580193bb47a89ff74",
   "migrations": [
     {
       "order": 0,
@@ -1146,6 +1146,15 @@
       "sourceRef": "message-board",
       "bytes": 10795,
       "sha256": "6349f705751104c5d60ec6602ea534e7c8b7de5c4c6ad2d84dbda680a5267848"
+    },
+    {
+      "order": 122,
+      "id": "20260905000100_agent_board_consent_gating_reconcile",
+      "filename": "20260905000100_agent_board_consent_gating_reconcile.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 8152,
+      "sha256": "d5328a0006ecd1ec940c4fde5bbb43acf29b0997eefbea557009f792868e298b"
     }
   ],
   "excludedBridge": {

package/src/check.js

@@ -9,8 +9,29 @@ export const EXIT = {
   ahead: 11,
   divergent: 12,
   error: 13,
+  // 14, not a reuse of `behind`: a collision previously reported as behind, and
+  // "behind" invites the fix of applying again -- which is exactly the no-op
+  // that leaves the database wrong. See message-board#217.
+  collision: 14,
 };
 
+// Operator guidance per posture. It lives HERE, next to the posture definition,
+// because the live-drift tool selected its message with a ternary over two named
+// postures and an else -- so a `collision` printed "the deployment has migrations
+// the bundle does not know about", which is the exact misdiagnosis this posture
+// exists to prevent. A completeness test over EXIT keeps a new posture from ever
+// again arriving without an action.
+export const POSTURE_ACTIONS = Object.freeze({
+  exact: null, // nothing to do
+  behind:
+    'migrations in the bundle are NOT applied to this deployment (or were applied without being recorded). Reconcile before assuming the board is current.',
+  ahead: 'the deployment has migrations the bundle does not know about.',
+  divergent:
+    'an applied migration digest does NOT match the bundle — the deployment ran different bytes. Investigate before applying anything further.',
+  collision:
+    'a bundle migration was SKIPPED because its version is already recorded under a different name. The deployment is missing that DDL while reporting the bundle\'s schema version. Do NOT simply re-apply: the version is taken, so applying again is a no-op. See the collisions list for the expected and recorded ids, and message-board#217.',
+});
+
 export function check(history) {
   const p = plan(history);
   return {
@@ -19,5 +40,7 @@ export function check(history) {
     exitCode: EXIT[p.posture] ?? EXIT.error,
     counts: p.counts,
     ahead: p.ahead,
+    collisions: p.collisions,
+    collisionsRemediated: p.collisionsRemediated,
   };
 }

package/src/index.js

@@ -39,6 +39,26 @@ export function loadOrderedMigrations() {
 
 // Parse a supplied migration-history snapshot: an array of { id/version,
 // sha256? } (applied migrations), or a plain array of version-id strings.
+// Collisions this bundle can HEAL, and the migration that heals each one.
+//
+// A version collision is a PERMANENT fact about a database: Supabase's
+// schema_migrations has `version` as its primary key, so an adopter's row at a
+// bundle migration's version never disappears. Reporting `collision` on the
+// mere presence of that row would therefore fail a fully-remediated database
+// FOREVER, and an adopter forced to ignore exit 14 also stops seeing genuine
+// `behind` and `divergent` states -- strictly worse than the problem it warns
+// about. So a collision whose remediating migration is applied is reported as
+// remediated and does not drive the posture.
+//
+// This map is a DECLARATION, not an enumeration: nothing in the catalog can
+// derive "which migration heals which", so it is stated here and asserted in
+// the tests -- both ids must exist in the bundle, and the healer must actually
+// restate the skipped migration's function body.
+export const COLLISION_REMEDIATIONS = Object.freeze({
+  '20260809000100_agent_board_consent_gating':
+    '20260905000100_agent_board_consent_gating_reconcile',
+});
+
 export function normalizeHistory(history) {
   const rows = Array.isArray(history) ? history : history?.applied ?? [];
   const map = new Map();

package/src/plan.js

@@ -4,7 +4,7 @@
 // history entries the adopter has that the bundle does not (ahead). Never
 // touches the database.
 
-import { loadOrderedMigrations, normalizeHistory } from './index.js';
+import { COLLISION_REMEDIATIONS, loadOrderedMigrations, normalizeHistory } from './index.js';
 
 export function plan(history) {
   const migrations = loadOrderedMigrations();
@@ -21,6 +21,75 @@ export function plan(history) {
 
   const ahead = [...applied.keys()].filter((id) => !bundleIds.has(id));
 
+  // VERSION COLLISIONS (message-board#217). Supabase keys
+  // supabase_migrations.schema_migrations on the 14-digit VERSION PREFIX alone,
+  // not the name. So an adopter who independently authored a migration at the
+  // same version has that version recorded under THEIR 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.
+  //
+  // Such a database already shows up here as one `pending` plus one `ahead`, but
+  // that pair reads like a malformed history file rather than a skipped
+  // migration, and the natural reading ("we applied it, the tool just cannot see
+  // the digest") is the wrong one. Naming the collision explicitly is the
+  // difference between a puzzle and an instruction.
+  const versionOf = (id) => String(id).split('_')[0];
+  const aheadByVersion = new Map();
+  for (const id of ahead) {
+    const v = versionOf(id);
+    if (!aheadByVersion.has(v)) aheadByVersion.set(v, []);
+    aheadByVersion.get(v).push(id);
+  }
+  const allCollisions = perId
+    .filter((r) => r.action === 'pending')
+    .flatMap((r) => (aheadByVersion.get(versionOf(r.id)) ?? [])
+      // An ahead id with no NAME carries no evidence: it cannot be distinguished
+      // from the bundle's own migration at that version. Two shapes reach here --
+      // a bare version (normalizeHistory accepts plain version strings) and
+      // `<version>_` from a row whose `name` is NULL, which schema_migrations
+      // permits and the documented psql recipe renders exactly that way. A
+      // substring test for '_' admits the second and invents a collision from a
+      // legitimate history. Require an actual name.
+      .filter((recordedAs) => String(recordedAs).slice(versionOf(recordedAs).length + 1).length > 0)
+      .map((recordedAs) => ({
+        version: versionOf(r.id),
+        expected: r.id,
+        recordedAs,
+        remediatedBy: COLLISION_REMEDIATIONS[r.id] ?? null,
+      })));
+
+  // A collision is LIVE only while its healer is unapplied. Once healed the row
+  // remains in schema_migrations forever, but the DDL is present, so the
+  // database is correct and must be allowed to report a clean posture.
+  // The healer must be applied AND not divergent. A divergent digest means the
+  // database applied SOMETHING under that id which is not what this bundle ships,
+  // so nothing here can claim the skipped DDL was restored -- and claiming it
+  // would be the same false-success the collision detector exists to prevent.
+  // An UNKNOWN digest is not divergence: histories without digests are a
+  // supported shape, and demanding one would strand those adopters in the same
+  // permanent red this design just removed.
+  const healerDivergent = new Map(
+    perId.filter((r) => r.action === 'applied-divergent').map((r) => [r.id, true]),
+  );
+  const remediates = (c) =>
+    c.remediatedBy != null && applied.has(c.remediatedBy) && !healerDivergent.has(c.remediatedBy);
+  const collisions = allCollisions.filter((c) => !remediates(c));
+  const collisionsRemediated = allCollisions.filter(remediates);
+
+  // A remediated collision must stop affecting the posture ENTIRELY, not merely
+  // stop being called a collision. Both halves of the pair are permanent: the
+  // bundle's migration can never be applied on that database (its version is
+  // taken) so it would count `pending` forever, and the adopter's row can never
+  // be removed so it would count `ahead` forever. Left in, they gate the healed
+  // database at `behind`/10 in perpetuity -- a different permanent red than the
+  // one just fixed, which is why "not collision" was too weak a claim to make.
+  const remediatedExpected = new Set(collisionsRemediated.map((c) => c.expected));
+  const remediatedRecordedAs = new Set(collisionsRemediated.map((c) => c.recordedAs));
+  for (const r of perId) {
+    if (remediatedExpected.has(r.id) && r.action === 'pending') r.action = 'collision-remediated';
+  }
+  const effectiveAhead = ahead.filter((id) => !remediatedRecordedAs.has(id));
+
   const counts = perId.reduce((acc, r) => {
     acc[r.action] = (acc[r.action] || 0) + 1;
     return acc;
@@ -29,16 +98,21 @@ export function plan(history) {
   const divergent = perId.filter((r) => r.action === 'applied-divergent').length;
   const pending = perId.filter((r) => r.action === 'pending').length;
   let posture;
-  if (divergent > 0) posture = 'divergent';
-  else if (ahead.length > 0 && pending === 0) posture = 'ahead';
+  // Collision outranks every other posture: it is the only one where the
+  // database is silently missing bundle DDL while reporting success.
+  if (collisions.length > 0) posture = 'collision';
+  else if (divergent > 0) posture = 'divergent';
+  else if (effectiveAhead.length > 0 && pending === 0) posture = 'ahead';
   else if (pending > 0) posture = 'behind';
   else posture = 'exact';
 
   return {
     schema: 'agent_board_plan.v1',
     posture,
-    counts: { ...counts, ahead: ahead.length },
-    ahead,
+    counts: { ...counts, ahead: effectiveAhead.length, collision: collisions.length, collisionRemediated: collisionsRemediated.length },
+    ahead: effectiveAhead,
+    collisions,
+    collisionsRemediated,
     perId,
   };
 }

package/src/tooling.test.mjs

@@ -5,7 +5,8 @@ import { join } from 'node:path';
 import { loadManifest, loadOrderedMigrations, sha256 } from './index.js';
 import { materialize } from './materialize.js';
 import { plan } from './plan.js';
-import { check, EXIT } from './check.js';
+import { check, EXIT, POSTURE_ACTIONS } from './check.js';
+import { COLLISION_REMEDIATIONS } from './index.js';
 
 const manifest = loadManifest();
 const ordered = loadOrderedMigrations();
@@ -37,9 +38,9 @@ describe('manifest integrity', () => {
     expect(manifest.schemaVersion).toBe(8);
     expect(manifest.minClientVersion).toMatch(/^\d+\.\d+\.\d+$/);
   });
-  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI + one FEDSESSION + one FEDSESSION-AUTOJOIN + one GATENULL + one MEMBSTATE + one AGENTSDIR + one LEAVEIDEM + one ROLERESET + one MBROWID + one MBHYGIENE + one MBCONSENT-A + one MBCONSENT-B(a) + one MBCONSENT-B(i) + one MBCONSENT-B(ii) + one MBCONSENT-B(iii) + one MBHARDEN-#97 + one MBHARDEN-#118 + one INVITEPOLICY + one OBSGATE + one OBSGATE-2 + one OBSGATE-3 + one OBSGATE-4 + one FLEETMACHINERLS + one RESOLVENOOP + one ROOMDELEG-LANEB + one CLAIMKEY + two MINTHARDEN + one FLEETMACHINEHIJACK + one CLAIMGATE-SHADOW + one CLAIMGATE-ENFORCE + one FLEETMACHINEREACTIVATION + one DELEGCAPCEILING + one FLEETMACHINERECLAIM + one DELEGSOLEWRITER + one FLEETDOMAINRECLAIM + five ATOMICFLEETONBOARDING (onboarding + ceiling-lock + revocation-evidence + fedsession-gate + fedsession-lock-order) + one OUTBOXWAKE + one ENROLLLOCKORDER + one FEDPROVIDERABSENCE + one WAKERECOVERY forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 = 122)', () => {
+  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI + one FEDSESSION + one FEDSESSION-AUTOJOIN + one GATENULL + one MEMBSTATE + one AGENTSDIR + one LEAVEIDEM + one ROLERESET + one MBROWID + one MBHYGIENE + one MBCONSENT-A + one MBCONSENT-B(a) + one MBCONSENT-B(i) + one MBCONSENT-B(ii) + one MBCONSENT-B(iii) + one MBHARDEN-#97 + one MBHARDEN-#118 + one INVITEPOLICY + one OBSGATE + one OBSGATE-2 + one OBSGATE-3 + one OBSGATE-4 + one FLEETMACHINERLS + one RESOLVENOOP + one ROOMDELEG-LANEB + one CLAIMKEY + two MINTHARDEN + one FLEETMACHINEHIJACK + one CLAIMGATE-SHADOW + one CLAIMGATE-ENFORCE + one FLEETMACHINEREACTIVATION + one DELEGCAPCEILING + one FLEETMACHINERECLAIM + one DELEGSOLEWRITER + one FLEETDOMAINRECLAIM + five ATOMICFLEETONBOARDING (onboarding + ceiling-lock + revocation-evidence + fedsession-gate + fedsession-lock-order) + one OUTBOXWAKE + one ENROLLLOCKORDER + one FEDPROVIDERABSENCE + one WAKERECOVERY + one CONSENTRECONCILE forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 + 1 = 123)', () => {
     expect(manifest.migrationCount).toBe(manifest.migrations.length);
-    expect(manifest.migrationCount).toBe(122);
+    expect(manifest.migrationCount).toBe(123);
     // MBSESSION switched enforcement on (scoped-send re-grant): the client-visible
     // schema version bumped to 8. MBDELEG tightens delegation and MBFED adds only
     // enrollment-only additive surface (identity_providers registry, enrollment audit,
@@ -199,7 +200,239 @@ describe('plan / check postures + exit codes (SemVer contract)', () => {
     expect(check({ applied }).exitCode).toBe(11);
   });
   it('exit-code map is a frozen SemVer surface', () => {
-    expect(EXIT).toEqual({ exact: 0, behind: 10, ahead: 11, divergent: 12, error: 13 });
+    expect(EXIT).toEqual({ exact: 0, behind: 10, ahead: 11, divergent: 12, error: 13, collision: 14 });
+  });
+
+  // VERSION COLLISION (message-board#217). Supabase keys schema_migrations on the
+  // 14-digit version prefix alone, so an adopter migration authored at a bundle
+  // migration's version makes the bundle's file skip SILENTLY -- no error, and
+  // schema_version still reports the bundle's number. The reported case is real:
+  // consiliency-portal recorded 20260809000100 as reconcile_panel_schema_drift.
+  // The adopter's own migration occupies the bundle's version, so the bundle's
+  // file was skipped. Two DISTINCT states matter, and conflating them is the
+  // defect a review seat caught: the collision ROW is permanent (Supabase keys
+  // schema_migrations on version, which is its primary key), so reporting on the
+  // row alone would fail a fully-healed database forever -- and an adopter forced
+  // to ignore exit 14 stops seeing genuine behind/divergent states too.
+  const portalHistory = (opts = {}) => ({
+    applied: [
+      ...ordered
+        .filter((m) => m.id !== '20260809000100_agent_board_consent_gating')
+        .filter((m) => opts.healed || m.id !== '20260905000100_agent_board_consent_gating_reconcile')
+        .map((m) => ({ id: m.id, sha256: m.sha256 })),
+      { id: '20260809000100_reconcile_panel_schema_drift', sha256: 'aa' },
+    ],
+  });
+
+  it('collision when an adopter migration occupies a bundle version and is unhealed', () => {
+    const c = check(portalHistory());
+    expect(c.posture).toBe('collision');
+    expect(c.exitCode).toBe(14);
+  });
+
+  it('collision names BOTH sides, so the report is an instruction not a puzzle', () => {
+    expect(plan(portalHistory()).collisions).toEqual([
+      {
+        version: '20260809000100',
+        expected: '20260809000100_agent_board_consent_gating',
+        recordedAs: '20260809000100_reconcile_panel_schema_drift',
+        remediatedBy: '20260905000100_agent_board_consent_gating_reconcile',
+      },
+    ]);
+  });
+
+  it('collision outranks behind — "behind" invites re-applying, which is the no-op that leaves the DB wrong', () => {
+    const p = plan(portalHistory());
+    expect(p.perId.filter((r) => r.action === 'pending').map((r) => r.id)).toContain(
+      '20260809000100_agent_board_consent_gating',
+    );
+    expect(p.posture).toBe('collision');
+  });
+
+  it('a HEALED database reports exact/0 — not merely "not collision"', () => {
+    // Asserting "not collision / not 14" was too weak and a review seat broke it:
+    // both halves of a remediated pair are PERMANENT (the bundle migration can
+    // never be applied on that database because its version is taken, and the
+    // adopter's row can never be removed), so leaving them in the counts gated
+    // the healed database at behind/10 forever — a different permanent red than
+    // the one being fixed. The claim is exact/0, so that is what is asserted.
+    const p = plan(portalHistory({ healed: true }));
+    expect(p.collisions).toEqual([]);
+    expect(p.collisionsRemediated.map((c) => c.expected)).toEqual([
+      '20260809000100_agent_board_consent_gating',
+    ]);
+    expect(p.counts.pending ?? 0).toBe(0);
+    expect(p.ahead).toEqual([]);
+    expect(p.posture).toBe('exact');
+    expect(check(portalHistory({ healed: true })).exitCode).toBe(0);
+  });
+
+  it('a NULL migration name is indeterminate, not a collision', () => {
+    // schema_migrations.name is nullable, and the documented psql recipe renders
+    // such a row as `<version>_`. A substring test for '_' called that a named
+    // row and invented a collision from a legitimate history.
+    const applied = [
+      ...ordered
+        .filter((m) => m.id !== '20260809000100_agent_board_consent_gating')
+        .map((m) => ({ id: m.id, sha256: m.sha256 })),
+      { id: '20260809000100_', sha256: 'aa' },
+    ];
+    const p = plan({ applied });
+    expect(p.collisions).toEqual([]);
+    expect(check({ applied }).exitCode).toBe(10); // behind, which is true: the DDL is absent
+  });
+
+  it('a DIVERGENT healer does not remediate — it is not the migration we shipped', () => {
+    // The database applied something under the healer's id that is not this
+    // bundle's bytes, so nothing here can claim the skipped DDL was restored.
+    // Posture already goes divergent, but reporting the collision as REMEDIATED
+    // would be the same false-success the detector exists to prevent.
+    const healer = '20260905000100_agent_board_consent_gating_reconcile';
+    const applied = [
+      ...ordered
+        .filter((m) => m.id !== '20260809000100_agent_board_consent_gating')
+        .map((m) => ({ id: m.id, sha256: m.id === healer ? 'deadbeef' : m.sha256 })),
+      { id: '20260809000100_reconcile_panel_schema_drift', sha256: 'aa' },
+    ];
+    const p = plan({ applied });
+    expect(p.collisionsRemediated).toEqual([]);
+    expect(p.collisions).toHaveLength(1);
+    expect(p.posture).toBe('collision');
+  });
+
+  it('an UNKNOWN healer digest still remediates — digest-less histories are supported', () => {
+    // normalizeHistory accepts entries without a digest. Requiring one would
+    // strand those adopters in the permanent red this design removes.
+    const applied = [
+      ...ordered.filter((m) => m.id !== '20260809000100_agent_board_consent_gating').map((m) => m.id),
+      '20260809000100_reconcile_panel_schema_drift',
+    ];
+    const p = plan({ applied });
+    expect(p.collisionsRemediated).toHaveLength(1);
+    expect(p.collisions).toEqual([]);
+  });
+
+  it('the healer being present is what clears it — not merely being declared', () => {
+    // Same declaration, healer unapplied: still live. Without this the previous
+    // test would pass on a map lookup rather than on the database's actual state.
+    expect(plan(portalHistory()).collisionsRemediated).toEqual([]);
+    expect(plan(portalHistory()).collisions).toHaveLength(1);
+  });
+
+  it('a bare-version history is indeterminate, not 123 collisions', () => {
+    // normalizeHistory accepts plain version strings. Such an entry carries no
+    // name, so it cannot be told apart from the bundle's own migration at that
+    // version — reporting it as a collision turns a supported input shape into a
+    // wall of false positives.
+    const p = plan({ applied: ordered.map((m) => m.id.split('_')[0]) });
+    expect(p.collisions).toEqual([]);
+  });
+
+  it('an unrelated adopter migration is NOT a collision, even with a bundle migration pending', () => {
+    // The history MUST have something pending as well as something ahead. A first
+    // draft of this test used an exact history plus one extra entry, and a mutation
+    // that reported every ahead entry as a collision SURVIVED it: with nothing
+    // pending there is no cross-product to over-report, so the assertion passed
+    // while checking nothing. A negative assertion driven by a clean input proves
+    // nothing (CLAUDE.md rule 2).
+    const applied = [
+      ...ordered
+        .filter((m) => m.id !== '20260809000100_agent_board_consent_gating')
+        .map((m) => ({ id: m.id, sha256: m.sha256 })),
+      { id: '99999999999999_extra', sha256: 'ff' },
+    ];
+    const p = plan({ applied });
+    expect(p.perId.some((r) => r.action === 'pending')).toBe(true); // the input is not clean
+    expect(p.ahead).toContain('99999999999999_extra');
+    expect(p.collisions).toEqual([]);
+    expect(p.posture).toBe('behind');
+  });
+});
+
+// OPERATOR GUIDANCE. Checks EXIT and POSTURE_ACTIONS agree with each other.
+//
+// This is NOT the completeness guard, and an earlier version of this comment
+// claimed it was. EXIT is a SECOND hand list, not the catalog: a posture added to
+// plan() without an EXIT entry passes everything here, falls through check()'s
+// `EXIT[p.posture] ?? EXIT.error` to exit 13, and prints no action. The real
+// catalog is the set of values plan() assigns, and scripts/check-posture-consumers.mjs
+// reads it from there -- and also holds the live-drift consumer to using
+// POSTURE_ACTIONS, which no test in this package can see. That script runs in
+// `schema:verify`. What follows is the in-package half: the two tables stay
+// consistent, and the collision action never tells an operator to re-apply.
+describe('every posture has operator guidance', () => {
+  const postures = Object.keys(EXIT).filter((k) => k !== 'error');
+
+  it('EXIT and POSTURE_ACTIONS cover the same postures', () => {
+    expect(Object.keys(POSTURE_ACTIONS).sort()).toEqual(postures.sort());
+  });
+
+  it('every non-exact posture has a non-empty action', () => {
+    for (const posture of postures) {
+      if (posture === 'exact') {
+        expect(POSTURE_ACTIONS.exact).toBeNull(); // nothing to do is not a missing action
+        continue;
+      }
+      expect(typeof POSTURE_ACTIONS[posture]).toBe('string');
+      expect(POSTURE_ACTIONS[posture].length).toBeGreaterThan(20);
+    }
+  });
+
+  it("the collision action does NOT tell an operator to re-apply", () => {
+    // Re-applying is the no-op that leaves the database wrong: the version is taken.
+    expect(POSTURE_ACTIONS.collision).toMatch(/no-op|not simply re-apply|Do NOT/i);
+  });
+});
+
+// COLLISION REMEDIATION (message-board#217). The reconcile migration's whole
+// no-op-on-a-healthy-database property rests on its join_board body being
+// byte-identical to the one in the migration an affected database skipped. The
+// PR asserted that in prose and nothing checked it -- the exact shape this repo
+// keeps getting caught by. The digest tests freeze each file's bytes, which is
+// not the same claim: two files can both be frozen and still differ.
+describe('collision remediation is real, not merely declared', () => {
+  const read = (id) =>
+    readFileSync(new URL(`../migrations/${id}.sql`, import.meta.url), 'utf8');
+  const joinBoardBlock = (sql) => {
+    const start = sql.search(/create or replace function agent_board\.join_board\b/i);
+    const rest = sql.slice(start + 10);
+    const next = rest.search(/create or replace function agent_board\./i);
+    return (next === -1 ? rest : rest.slice(0, next)).trimEnd();
+  };
+
+  it('every declared remediation names migrations that exist in the bundle', () => {
+    const ids = new Set(ordered.map((m) => m.id));
+    for (const [skipped, healer] of Object.entries(COLLISION_REMEDIATIONS)) {
+      expect(ids.has(skipped)).toBe(true);
+      expect(ids.has(healer)).toBe(true);
+      // The healer must come LATER, or it cannot run after the skip.
+      expect(healer > skipped).toBe(true);
+    }
+  });
+
+  it('the healer restates the skipped function BYTE-IDENTICALLY, so a healthy DB is a true no-op', () => {
+    const skipped = joinBoardBlock(read('20260809000100_agent_board_consent_gating'));
+    const healer = joinBoardBlock(read('20260905000100_agent_board_consent_gating_reconcile'));
+    expect(healer.length).toBeGreaterThan(1000);
+    expect(healer).toBe(skipped);
+  });
+
+  it('the healer touches ONLY the stale function, so it cannot clobber a later definition', () => {
+    // resolve_board_request and update_board_membership are superseded by
+    // 20260819000100 and 20260813000100. Restating them here would re-apply the
+    // older bodies over the newer ones on every healthy database.
+    const sql = read('20260905000100_agent_board_consent_gating_reconcile');
+    const defined = [...sql.matchAll(/create or replace function agent_board\.(\w+)/gi)].map((m) => m[1]);
+    expect(defined).toEqual(['join_board']);
+  });
+
+  it('the healer adds no grant, revoke or comment — create-or-replace preserves the ACL', () => {
+    const sql = read('20260905000100_agent_board_consent_gating_reconcile')
+      .split('\n').filter((l) => !l.trimStart().startsWith('--')).join('\n');
+    expect(sql).not.toMatch(/\bgrant\b/i);
+    expect(sql).not.toMatch(/\brevoke\b/i);
+    expect(sql).not.toMatch(/comment\s+on/i);
+    expect(sql).not.toMatch(/drop\s+function/i);
   });
 });