@consiliency/agent-board-schema 1.23.0 → 1.25.0

package/migrations/20260907000100_agent_board_signed_authority_provenance.sql

@@ -0,0 +1,243 @@
+-- #247 — signed provenance for the authority-granting writes.
+--
+-- WHAT THIS CLOSES. `grant_board_role` and `set_board_authority_ceiling` are the two
+-- authority-granting writes in the bundle, and neither could carry signing provenance in
+-- any form. The client's `attachSigningMetadata` merges its evidence into `p_metadata`,
+-- and neither function declares that parameter (verified against their NEWEST definitions,
+-- 20260802000100 and 20260901000110 — not their first). Adding them to the client's signed
+-- set would have attached an undeclared argument: a PostgREST signature mismatch, not a
+-- silent no-op. So closing this is a schema change, not a client-list change.
+--
+-- MECHANISM (ratified 2026-08-12). These two get dedicated `signed_*` wrappers that call
+-- `_record_signed_write_evidence` and write a real, queryable `signature_evidence` row —
+-- the same mechanism as the five existing message/task signed writes, whose shape they
+-- follow rather than inventing a new one. The alternative (`p_metadata.signed_write` on
+-- the written row) records only that a client CLAIMED to sign; for "who granted this role,
+-- and can we prove it", only an evidence row answers the question.
+--
+-- PROVENANCE IS DERIVED, NEVER ASSERTED. `_signed_write_actor_id` takes the actor from the
+-- gateway's verified decision and raises `actor_mismatch` (42501) when a payload names a
+-- different principal. That resolved actor — not `p_payload ->> 'p_grantor_agent_id'` — is
+-- what the wrapper passes to the inner function AND what the evidence row names, because
+-- the newest `_record_signed_write_evidence` (20260710000000) reads its actor solely from
+-- `p_gateway_decision ->> 'agent_id'`. An evidence row recording the caller-supplied
+-- grantor would be worse than no evidence row, because it looks like proof.
+--
+-- WHY set_board_authority_ceiling GAINS A PARAMETER. Its owner gate reads
+-- `current_agent_id()` and nothing else, so it can only ever succeed for an authenticated
+-- session. The `signed_*` layer is service_role-only BY DESIGN: 20260812000100 (#118)
+-- revoked `_record_signed_write_evidence` from `authenticated` precisely because it mints
+-- attestation rows from caller-supplied fields, so granting a `signed_*` wrapper to
+-- `authenticated` would reopen that forge hole. A service_role-only wrapper therefore
+-- cannot satisfy a `current_agent_id()`-only gate, and the bundle's existing delegation
+-- mechanism is `_resolved_actor_agent_id` — exactly the shape `grant_board_role` already
+-- has. Hence the new `p_actor_agent_id`.
+--
+-- D4 — THIS CHANGES NO UNSIGNED CALL. `p_actor_agent_id` defaults to null, and when it is
+-- null the setter takes the pre-#247 path verbatim (`v_actor := current_agent_id()`), for
+-- EVERY role. The resolver engages only when a caller supplies the argument. Under
+-- `authenticated` the resolver additionally requires the supplied id to equal
+-- `current_agent_id()` (42501 otherwise), so the new parameter cannot be used to act as
+-- someone else. `create or replace` cannot add a parameter — it would leave a 2-arg and a
+-- 3-arg overload live simultaneously and make a named-argument PostgREST call ambiguous —
+-- so the setter is DROPped and recreated, with its `revoke`, its `grant` and its `comment`
+-- restated in this same migration (a DROP discards the ACL and the COMMENT, and a
+-- recreated SECURITY DEFINER function grants EXECUTE to PUBLIC by default).
+--
+-- EVIDENCE SHAPE. An authority write has no canonical source row to point at: the
+-- `signature_evidence` source columns are message / task_event / artifact /
+-- delivery_recipient. `source_kind = 'external'` is the constraint's existing shape for
+-- "no internal source row, identified by a ref", and 20260718000300 already records
+-- signed-write preflight evidence that way. The ref is synthesized SERVER-side from the
+-- resolved actor and the board and FORCED over any caller-supplied value — a caller ref is
+-- an assertion, a derived one is evidence. No table DDL is required.
+
+-- 1. set_board_authority_ceiling — delegable actor, so a service_role gateway can carry a
+--    signed grant on an owner's behalf. Everything else is verbatim from 20260901000110.
+drop function if exists agent_board.set_board_authority_ceiling(uuid, text);
+
+create or replace function agent_board.set_board_authority_ceiling(
+  p_board_id uuid,
+  p_max_grantable_role text,
+  p_actor_agent_id uuid default null
+)
+returns table(
+  ceiling_board_id uuid,
+  ceiling_max_grantable_role text
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid;
+begin
+  if p_max_grantable_role not in ('owner', 'admin', 'member', 'observer') then
+    raise exception 'max_grantable_role must be one of owner/admin/member/observer' using errcode = '22023';
+  end if;
+
+  -- Same board-keyed advisory lock every ceiling READER for authorization takes.
+  -- Held to commit, it makes the insert of a first ceiling row serialize against a
+  -- concurrent authorization that would otherwise observe the pre-insert ABSENCE and
+  -- pass as default-owner. Taken before the owner gate so the gate and the write are
+  -- one critical section.
+  perform agent_board._lock_board_authority_ceiling(p_board_id);
+
+  -- #247. Actor resolution, NOT a widening of the gate. With p_actor_agent_id omitted this
+  -- is the pre-#247 expression for every role, so no existing caller changes behaviour
+  -- (D4). When it IS supplied, _resolved_actor_agent_id binds it: service_role takes the
+  -- argument (this is the signed_* gateway path, where the argument is the gateway-VERIFIED
+  -- signer, never a raw caller claim), while authenticated still resolves to
+  -- current_agent_id() and raises 42501 if the supplied id differs. The owner gate below is
+  -- untouched and remains the only thing that authorizes the write.
+  if p_actor_agent_id is null then
+    v_actor := agent_board.current_agent_id();
+  else
+    v_actor := agent_board._resolved_actor_agent_id(p_actor_agent_id, 'p_actor_agent_id');
+  end if;
+
+  if v_actor is null
+     or not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = p_board_id
+          and bm.agent_id = v_actor
+          and bm.role = 'owner'
+          and bm.membership_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'only a board owner may set the board authority ceiling' using errcode = '42501';
+  end if;
+
+  insert into agent_board.board_authority_ceilings(board_id, max_grantable_role)
+  values (p_board_id, p_max_grantable_role)
+  on conflict (board_id) do update
+    set max_grantable_role = excluded.max_grantable_role,
+        updated_at = now();
+
+  return query
+  select p_board_id, p_max_grantable_role;
+end;
+$$;
+
+comment on function agent_board.set_board_authority_ceiling(uuid, text, uuid) is
+  'Owner-gated setter for a board''s authority ceiling: takes the board-keyed _lock_board_authority_ceiling advisory lock, then upserts board_authority_ceilings only when the resolved actor is an owner of the board (else raises 42501). The actor is current_agent_id() when p_actor_agent_id is omitted — the pre-#247 behaviour for every role — and _resolved_actor_agent_id(p_actor_agent_id) when it is supplied, which lets the service_role-only signed_set_board_authority_ceiling gateway act for the gateway-verified signer while still forcing an authenticated caller to match current_agent_id(). Leaves _grant_within_ceiling semantics unchanged.';
+
+revoke all on function agent_board.set_board_authority_ceiling(uuid, text, uuid) from public, anon;
+grant execute on function agent_board.set_board_authority_ceiling(uuid, text, uuid) to authenticated, service_role;
+
+-- 2. signed_grant_board_role — evidence-recording wrapper over the live grant chokepoint.
+create or replace function agent_board.signed_grant_board_role(
+  p_payload jsonb,
+  p_gateway_decision jsonb
+)
+returns table(
+  board_id uuid,
+  agent_id uuid,
+  role text,
+  signature_evidence_id uuid,
+  verification_status text,
+  updated_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_row record;
+  v_actor uuid;
+  v_evidence_id uuid;
+  v_board uuid := (p_payload ->> 'p_board_id')::uuid;
+  v_grantee uuid := (p_payload ->> 'p_agent_id')::uuid;
+begin
+  -- The grantor is the gateway-verified signer. _signed_write_actor_id raises 42501 when
+  -- the gateway names no actor, and raises actor_mismatch when the payload names a
+  -- DIFFERENT one -- so a payload p_grantor_agent_id can never become the grantor. This
+  -- value is what grant_board_role binds (through its own _resolved_actor_agent_id) and
+  -- what the evidence row names; they cannot diverge.
+  v_actor := agent_board._signed_write_actor_id(p_payload, p_gateway_decision, 'p_grantor_agent_id');
+
+  select *
+    into v_row
+    from agent_board.grant_board_role(
+      v_board,
+      v_grantee,
+      p_payload ->> 'p_grantee_role',
+      v_actor
+    );
+
+  v_evidence_id := agent_board._record_signed_write_evidence(
+    'external',
+    null,
+    'grant_board_role',
+    p_payload,
+    p_gateway_decision || jsonb_build_object(
+      'external_evidence_ref',
+      'board-authority:grant_board_role:' || v_board::text || ':' || v_grantee::text
+    )
+  );
+
+  return query
+  select v_row.board_id, v_row.agent_id, v_row.role, v_evidence_id,
+         coalesce(p_gateway_decision ->> 'verification_status', 'unsigned'), v_row.updated_at;
+end;
+$$;
+
+comment on function agent_board.signed_grant_board_role(jsonb, jsonb) is
+  '#247 signed-write gateway wrapper for grant_board_role. Resolves the grantor with _signed_write_actor_id (gateway actor required; a payload p_grantor_agent_id that differs raises actor_mismatch 42501), passes THAT principal to grant_board_role so the bound grantor and the recorded one cannot diverge, and records a signature_evidence row via _record_signed_write_evidence with source_kind=external and a server-derived external_evidence_ref naming the board and grantee. Adds no authority: grant_board_role''s membership, ceiling and TOCTOU gates are untouched. service_role only, like every other signed_* wrapper (#118).';
+
+-- 3. signed_set_board_authority_ceiling — evidence-recording wrapper over the ceiling setter.
+create or replace function agent_board.signed_set_board_authority_ceiling(
+  p_payload jsonb,
+  p_gateway_decision jsonb
+)
+returns table(
+  ceiling_board_id uuid,
+  ceiling_max_grantable_role text,
+  signature_evidence_id uuid,
+  verification_status text
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_row record;
+  v_actor uuid;
+  v_evidence_id uuid;
+  v_board uuid := (p_payload ->> 'p_board_id')::uuid;
+begin
+  v_actor := agent_board._signed_write_actor_id(p_payload, p_gateway_decision, 'p_actor_agent_id');
+
+  select *
+    into v_row
+    from agent_board.set_board_authority_ceiling(
+      v_board,
+      p_payload ->> 'p_max_grantable_role',
+      v_actor
+    );
+
+  v_evidence_id := agent_board._record_signed_write_evidence(
+    'external',
+    null,
+    'set_board_authority_ceiling',
+    p_payload,
+    p_gateway_decision || jsonb_build_object(
+      'external_evidence_ref',
+      'board-authority:set_board_authority_ceiling:' || v_board::text || ':' || v_actor::text
+    )
+  );
+
+  return query
+  select v_row.ceiling_board_id, v_row.ceiling_max_grantable_role, v_evidence_id,
+         coalesce(p_gateway_decision ->> 'verification_status', 'unsigned');
+end;
+$$;
+
+comment on function agent_board.signed_set_board_authority_ceiling(jsonb, jsonb) is
+  '#247 signed-write gateway wrapper for set_board_authority_ceiling. Resolves the actor with _signed_write_actor_id (gateway actor required; a differing payload p_actor_agent_id raises actor_mismatch 42501) and passes it as p_actor_agent_id, so the owner gate authorizes the SAME principal the evidence row names. Records a signature_evidence row via _record_signed_write_evidence with source_kind=external and a server-derived external_evidence_ref. Adds no authority: the owner gate still rejects any actor that is not an active board owner. service_role only, like every other signed_* wrapper (#118).';
+
+revoke all on function agent_board.signed_grant_board_role(jsonb, jsonb) from public, anon, authenticated;
+revoke all on function agent_board.signed_set_board_authority_ceiling(jsonb, jsonb) from public, anon, authenticated;
+
+grant execute on function agent_board.signed_grant_board_role(jsonb, jsonb) to service_role;
+grant execute on function agent_board.signed_set_board_authority_ceiling(jsonb, jsonb) to service_role;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.23.0",
+  "version": "1.25.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.25.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": 125,
+  "aggregateSha256": "0ce03fcc8b0ae0113e9b6de2c8e8bc346cf735a86fcca0221ffc8103d604969f",
   "migrations": [
     {
       "order": 0,
@@ -1146,6 +1146,33 @@
       "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"
+    },
+    {
+      "order": 123,
+      "id": "20260906000100_agent_board_enroll_resumption",
+      "filename": "20260906000100_agent_board_enroll_resumption.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 41571,
+      "sha256": "2aafad9df5da006039268d9559311f85fba634b6ec44d06a2f55fe3deedb09d8"
+    },
+    {
+      "order": 124,
+      "id": "20260907000100_agent_board_signed_authority_provenance",
+      "filename": "20260907000100_agent_board_signed_authority_provenance.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 12633,
+      "sha256": "21111e289e0bb70ac3236f5422476c0c51d0bca5a815c11dd4e48b6932cf7c6b"
     }
   ],
   "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,
   };
 }