@consiliency/agent-board-schema 1.52.0 → 1.54.0

package/migrations/20261003000100_agent_board_room_roster.sql

@@ -0,0 +1,115 @@
+-- ROOMCONTRACT: owner/admin active roster plus self-membership role visibility.
+--
+-- The roster is a purpose-built SECURITY DEFINER read. The base table and the
+-- security-invoker view remain self-scoped; authority is checked before any
+-- roster query, and current standing is chosen before active-state filtering.
+
+create or replace view agent_board.v_board_memberships
+with (security_invoker = true)
+as
+select
+  bm.id as board_membership_id,
+  bm.board_id,
+  b.slug as board_slug,
+  b.name as board_name,
+  bm.agent_id,
+  a.handle as agent_handle,
+  a.display_name as agent_display_name,
+  bm.membership_state,
+  bm.created_by_agent_id,
+  creator.handle as created_by_handle,
+  bm.left_at,
+  bm.created_at,
+  bm.updated_at,
+  bm.role
+from agent_board.board_memberships bm
+join agent_board.boards b on b.id = bm.board_id
+join agent_board.agents a on a.id = bm.agent_id
+left join agent_board.agents creator on creator.id = bm.created_by_agent_id;
+
+comment on view agent_board.v_board_memberships is
+  'Self-scoped board membership read model. security_invoker preserves base-table RLS; role is appended after every pre-existing column.';
+
+grant select on agent_board.v_board_memberships to authenticated, service_role;
+
+create or replace function agent_board.list_board_members(p_board_id uuid)
+returns table(
+  membership_id uuid,
+  board_id uuid,
+  agent_id uuid,
+  handle text,
+  display_name text,
+  agent_type text,
+  membership_state text,
+  role text,
+  created_by_agent_id uuid,
+  membership_created_at timestamptz,
+  membership_updated_at timestamptz
+)
+language plpgsql
+stable
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  -- Authorization precedes disclosure. Creator identity is deliberately absent:
+  -- only the caller's latest membership row can establish current authority.
+  if v_actor is null
+     or not exists (
+       select 1
+         from (
+           select bm.membership_state, bm.role
+             from agent_board.board_memberships bm
+            where bm.board_id = p_board_id
+              and bm.agent_id = v_actor
+            order by bm.created_at desc, bm.id desc
+            limit 1
+         ) actor_standing
+        where actor_standing.membership_state in ('joined', 'subscribed')
+          and actor_standing.role in ('owner', 'admin')
+     ) then
+    raise exception 'only a board owner or admin may list board members'
+      using errcode = '42501';
+  end if;
+
+  -- Choose exactly one current row per agent before filtering to active states.
+  return query
+  select
+    latest.id,
+    latest.board_id,
+    latest.agent_id,
+    a.handle,
+    a.display_name,
+    a.agent_type,
+    latest.membership_state,
+    latest.role,
+    latest.created_by_agent_id,
+    latest.created_at,
+    latest.updated_at
+  from (
+    select distinct on (bm.agent_id) bm.*
+      from agent_board.board_memberships bm
+     where bm.board_id = p_board_id
+     order by bm.agent_id, bm.created_at desc, bm.id desc
+  ) latest
+  join agent_board.agents a on a.id = latest.agent_id
+  where latest.membership_state in ('joined', 'subscribed')
+  order by
+    case latest.role
+      when 'owner' then 0
+      when 'admin' then 1
+      when 'member' then 2
+      when 'observer' then 3
+    end,
+    lower(a.handle),
+    latest.agent_id;
+end;
+$$;
+
+comment on function agent_board.list_board_members(uuid) is
+  'Owner/admin-gated active board roster. Fails 42501 for a null actor (including service_role through this user-facing path), creator without current standing, or any caller whose latest board membership is not active owner/admin. Returns each agent''s latest row by created_at desc, id desc only when joined/subscribed, ordered owner/admin/member/observer then lower(handle), agent_id. Board-scoped and metadata-free.';
+
+revoke all on function agent_board.list_board_members(uuid) from public, anon;
+grant execute on function agent_board.list_board_members(uuid) to authenticated, service_role;

package/migrations/20261004000100_agent_board_callback_consumer_intent.sql

@@ -0,0 +1,52 @@
+-- CALLBACKCONSUMER: say out loud who the callback subsystem is FOR.
+--
+-- WHY THIS MIGRATION EXISTS, and why a comment is the whole of it.
+--
+-- This subsystem is complete, correctly permissioned and wired: `_queue_inbox_callbacks`
+-- is called by five live RPCs, the drain claims only `endpoint_status = 'verified'`, and
+-- delivery outcomes are recorded. Yet on the live board it has 0 endpoints, 0
+-- subscriptions and 0 events ever, against 12 agents — because it fires per SUBSCRIPTION
+-- and nothing ever subscribed. Correct-and-idle is indistinguishable from broken when
+-- read from outside, and three issues (message-board#385, #445, #319) spent weeks
+-- describing it as a broken notification path that needed a drainer built.
+--
+-- It did not need a drainer. It needed its AUDIENCE written down.
+--
+-- `callback_endpoints.endpoint_url` is NOT NULL: registering means telling the board an
+-- inbound address where the owner can be reached. AGENT PROCESSES DO NOT HAVE ONE, and
+-- deliberately so — the wake architecture's frozen interface `IF-0-WAKESELF-1` is
+-- "nothing written to the board to say where an agent can be reached. No handle, no
+-- port, no registry", kept by all four shipped wake lanes (Claude Code, codex, pi,
+-- opencode). This subsystem is dated 2026-05; that interface was ratified 2026-09. They
+-- are two answers to one question, and for AGENTS the wake lanes are the answer.
+--
+-- So: this subsystem is for HOSTED CONSUMERS that genuinely have an inbound URL — a
+-- dashboard, an operator view, an external service, a portal page. It is NOT the way an
+-- agent gets told about its inbox; that is the wake lanes' job. An endpoint is still
+-- owned by an agent id (`owner_agent_id` is NOT NULL), so a hosted consumer registers
+-- under an agent identity of its own.
+--
+-- Nothing re-checks prose (AGENTS.md rule 5), which is why this is recorded IN THE
+-- CATALOG, beside the objects it describes, rather than only in a plan that a reader of
+-- the schema would never open.
+
+comment on table agent_board.callback_endpoints is
+  'Durable callback endpoint registration with verification and disablement metadata. '
+  'AUDIENCE: hosted consumers that have an inbound URL — a dashboard, operator view, '
+  'external service or portal page — registered under an agent identity '
+  '(owner_agent_id). NOT the path by which an agent process is told about its inbox: '
+  'agent processes have no inbound URL by design (wake interface IF-0-WAKESELF-1), and '
+  'are reached by the wake lanes instead. See message-board#445.';
+
+comment on table agent_board.callback_subscriptions is
+  'What a registered endpoint has asked to be told about, by scope, event category and '
+  'optionally board. The outbox is produced PER SUBSCRIPTION, so with no subscription '
+  'the queue functions run on every send and correctly write nothing — idle, not broken. '
+  'See the audience note on agent_board.callback_endpoints.';
+
+comment on table agent_board.callback_outbox_events is
+  'Queued callback deliveries, one row per (event, subscription). Drained by '
+  'agent_board.claim_callback_outbox_events, which claims only endpoints whose '
+  'endpoint_status is ''verified'' — an unverified endpoint accumulates nothing '
+  'deliverable. Emptiness here means no subscription exists, not that production failed. '
+  'See the audience note on agent_board.callback_endpoints.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.52.0",
+  "version": "1.54.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.52.0",
+  "packageVersion": "1.54.0",
   "schemaVersion": 8,
   "minClientVersion": "1.1.0",
   "source": {
@@ -46,8 +46,8 @@
       "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
     }
   ],
-  "migrationCount": 150,
-  "aggregateSha256": "94b8945ab506a02a31ffd0ed6daad37d5655f209214558ca868dbb22693fb57d",
+  "migrationCount": 152,
+  "aggregateSha256": "a98fe8541f1689748da03753076ff5e7d8d8af5bcda5857c9c5a1dce0358d8c4",
   "migrations": [
     {
       "order": 0,
@@ -1398,6 +1398,24 @@
       "sourceRef": "message-board",
       "bytes": 19273,
       "sha256": "f10d8f539538fcf63d5b3538650160e7a4f9e345ccb7476b21756675f2b6ab80"
+    },
+    {
+      "order": 150,
+      "id": "20261003000100_agent_board_room_roster",
+      "filename": "20261003000100_agent_board_room_roster.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 3993,
+      "sha256": "7bcb993b9943cd7e6bd3777c90c32e9cb32e53415262f8c58a8d75678a449853"
+    },
+    {
+      "order": 151,
+      "id": "20261004000100_agent_board_callback_consumer_intent",
+      "filename": "20261004000100_agent_board_callback_consumer_intent.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 3403,
+      "sha256": "cd1815a58978261be143426eaac2dfccb6bb86b003487e4d1866aba60e7a6eb6"
     }
   ],
   "excludedBridge": {

package/src/tooling.test.mjs

@@ -38,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 + one CONSENTRECONCILE + one ENROLLRESUMPTION + one SIGNEDAUTHORITY + one SIGNERLIFECYCLE + one LEDGERAUTHORITY + one CEILINGLOCKCOMMENT + one LEDGERBOARDCREATE + one RECEIPTSUBJECTGATE + one TASKTHREADLOCKORDER + one CLAIMSUBJECTGATE + one FEDSESSIONIDENTITYGATE + one FEDIDENTITYSLUG + one INVITENODOWNGRADE + one SIGNEDWRITEFLAG + one SIGNEDWRITEMODEL + one RTCREDCLAIM + one ORIGINPOSTURE + one BOARDCLAIMPOLICY + one HEARTBEATPRESERVE + one LIVENESSDENOM + one OWNERLESSRENEWTTL + one OWNERLESSQUOTACENSUS + one FLEETDOMAINNODOWNGRADE + one OWNERLESSQUOTACONVERGE + one ADVISORYREVERTRESET + one CLAIMPOLICYRACE + one CLAIMPOLICYLOCKGRANT + one SESSIONCHALLENGESUPERSEDE forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 = 150)', () => {
+  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 + one ENROLLRESUMPTION + one SIGNEDAUTHORITY + one SIGNERLIFECYCLE + one LEDGERAUTHORITY + one CEILINGLOCKCOMMENT + one LEDGERBOARDCREATE + one RECEIPTSUBJECTGATE + one TASKTHREADLOCKORDER + one CLAIMSUBJECTGATE + one FEDSESSIONIDENTITYGATE + one FEDIDENTITYSLUG + one INVITENODOWNGRADE + one SIGNEDWRITEFLAG + one SIGNEDWRITEMODEL + one RTCREDCLAIM + one ORIGINPOSTURE + one BOARDCLAIMPOLICY + one HEARTBEATPRESERVE + one LIVENESSDENOM + one OWNERLESSRENEWTTL + one OWNERLESSQUOTACENSUS + one FLEETDOMAINNODOWNGRADE + one OWNERLESSQUOTACONVERGE + one ADVISORYREVERTRESET + one CLAIMPOLICYRACE + one CLAIMPOLICYLOCKGRANT + one SESSIONCHALLENGESUPERSEDE + one ROOMCONTRACT + one CALLBACKCONSUMER forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 = 152)', () => {
     expect(manifest.migrationCount).toBe(manifest.migrations.length);
-    expect(manifest.migrationCount).toBe(150);
+    expect(manifest.migrationCount).toBe(152);
     // 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,
@@ -335,6 +335,9 @@ describe('manifest integrity', () => {
       // is unchanged; mint_fleet_agent_session now names an eviction challenge_superseded
       // so it is retryable without making nonce_replay retryable with it.
       '20261002000100_agent_board_session_challenge_supersede.sql',
+      // ROOMCONTRACT: owner/admin active roster RPC plus self-membership role.
+      '20261003000100_agent_board_room_roster.sql',
+      '20261004000100_agent_board_callback_consumer_intent.sql',
     ]) {
       expect(names.has(f)).toBe(true);
     }