@consiliency/agent-board-schema 1.23.0 → 1.25.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,18 @@
     {
       "id": "20260904000100_agent_board_wake_recovery_surface",
       "sha256": "6349f705751104c5d60ec6602ea534e7c8b7de5c4c6ad2d84dbda680a5267848"
+    },
+    {
+      "id": "20260905000100_agent_board_consent_gating_reconcile",
+      "sha256": "d5328a0006ecd1ec940c4fde5bbb43acf29b0997eefbea557009f792868e298b"
+    },
+    {
+      "id": "20260906000100_agent_board_enroll_resumption",
+      "sha256": "2aafad9df5da006039268d9559311f85fba634b6ec44d06a2f55fe3deedb09d8"
+    },
+    {
+      "id": "20260907000100_agent_board_signed_authority_provenance",
+      "sha256": "21111e289e0bb70ac3236f5422476c0c51d0bca5a815c11dd4e48b6932cf7c6b"
     }
   ]
 }

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;
+$$;