@consiliency/agent-board-schema 1.55.0 → 1.57.0

package/fixtures/already-applied.json

@@ -612,6 +612,14 @@
   {
    "id": "20261005000100_agent_board_enroll_token_single_use",
    "sha256": "317d7b41432b36a2e38cc64940838e173e425014e3e256a96d832202b250e82d"
+  },
+  {
+   "id": "20261006000100_agent_board_room_roster_active_first",
+   "sha256": "637480feeca07dbb2fe7a4624dc6d063d0c1f23e6ea3c3ee9a946ad43de4e34e"
+  },
+  {
+   "id": "20261007000100_agent_board_onboard_requests",
+   "sha256": "fbdbecfb1c78e2d1b16b37845a74082dcdf1241c61c0356b992e1e01baddc41c"
   }
  ]
 }

package/migrations/20261006000100_agent_board_room_roster_active_first.sql

@@ -0,0 +1,118 @@
+-- ROOMCONTRACT-ACTIVEFIRST (message-board#542): the owner/admin roster chooses current
+-- standing ACTIVE-FIRST, as every other acting membership reader does (MBROWID 3a).
+--
+-- THE DEFECT. 20261003000100 chose the caller's standing (authorization) and each
+-- member's inclusion (projection) from the LATEST board_memberships row alone:
+-- `order by created_at desc, id desc`. The active-membership unique index is PARTIAL
+-- (idx_agent_board_board_memberships_active_unique, WHERE membership_state in
+-- ('joined','subscribed')), so one active row can coexist with newer non-active rows
+-- (removed / left / requested / invited). MBROWID 3a (20260803000100) ruled that every
+-- reader acting on "current standing" prefers the active row when one exists; join_board,
+-- update_board_membership, _upsert_board_membership_state and
+-- list_board_pending_memberships all do. The roster did not, so an active owner or admin
+-- with a newer non-active row was refused with 42501 and omitted from every roster —
+-- while the rest of MB (and Portal's self view, which reduces active-first as MBROWID
+-- requires) treated them as active.
+--
+-- THE FIX. Both selection sites take the MBROWID 3a key, then the existing total order:
+--   order by case when membership_state in ('joined','subscribed') then 0 else 1 end,
+--            created_at desc, id desc
+-- Everything else is unchanged: signature, projection, STABLE, SECURITY DEFINER,
+-- search_path, the 42501 message, the result order, and the grants.
+--
+-- The class this belongs to is pinned from the catalog, not from this list:
+-- tests/agent_board_membership_current_row_class.test.sql derives every statement that
+-- picks ONE board_memberships row by recency and requires the active-first key, or a
+-- named exemption whose filter it asserts exactly. This migration fixes the only two
+-- sites that class found without the key; the exemptions are recorded there.
+--
+-- CREATE OR REPLACE keeps the ACL and the COMMENT, but both are restated below anyway:
+-- the COMMENT's text described latest-row semantics and must change, and the grants are
+-- restated so this file alone says what the function's posture is.
+
+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 current membership row can establish authority, and the
+  -- current row is the ACTIVE one when one exists (MBROWID 3a), else the latest.
+  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 case when bm.membership_state in ('joined', 'subscribed') then 0 else 1 end,
+                     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 (active-first, MBROWID 3a), then
+  -- keep only agents whose current row is active.
+  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,
+              case when bm.membership_state in ('joined', 'subscribed') then 0 else 1 end,
+              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 current board membership is not active owner/admin. The current row is chosen active-first (MBROWID 3a): case when membership_state in (joined, subscribed) then 0 else 1 end, created_at desc, id desc — so an active row outranks a newer removed/left/requested/invited row. Returns each agent''s current row 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/20261007000100_agent_board_onboard_requests.sql

@@ -0,0 +1,139 @@
+-- ONBOARD (v11) SL-2: the caller's own join requests (IF-0-ONBOARD-4) and a service-side
+-- invite label lookup for the consent page (IF-0-ONBOARD-11). Additive: two new read-only
+-- functions and one index. schema_version stays 8.
+--
+-- Sources read, each at its latest definition:
+--   * agent_board.current_agent_id()              -- 20260920000100 (the resolver
+--     request_join_board, 20260810000100, calls);
+--   * agent_board.board_membership_events         -- 20260806000100 (the append-only
+--     consent ledger; seq is the total order, created_at is wall-clock age);
+--   * agent_board.boards.join_request_ttl_days    -- 20260806000100;
+--   * the emitter _emit_membership_event          -- 20260807000100: a request made by the
+--     subject through request_join_board is `target-authored` / `requested`;
+--   * agent_board.board_invite_tokens             -- 20260724000100. invite_board_for_display
+--     checks only the frozen IF-0-ONBOARD-11 subset: not revoked, expires_at > now(), uses
+--     remaining. The redeem core (latest 20260909000100) refuses MORE -- a suspended or
+--     fleet-revoked creator, a lapsed ceiling, a removed agent, fleet-bounded invites -- so a
+--     code that displays a board can still fail to redeem.
+
+-- =============================================================================
+-- 1. list_my_board_requests() -- IF-0-ONBOARD-4
+-- =============================================================================
+-- WHICH REQUESTS. The ledger, never the membership row. A request is a (board, caller) with
+-- at least one event where agent_id is the caller, provenance = 'target-authored' and
+-- result_state = 'requested'. board_memberships.created_by_agent_id is NOT a source: the
+-- sink overwrites it on every later write (an approval names the approver), so it cannot say
+-- who asked.
+--
+-- IDENTITY. From the session only, by the resolver request_join_board uses. There is no
+-- parameter, and a null identity (service_role, anon, a revoked credential) returns nothing.
+--
+-- CURRENT STATE. The caller's membership row on that board, chosen active-first (MBROWID 3a,
+-- the key every current-standing reader uses), or 'none' when no row exists. A rejected request
+-- reads 'left' (REJECTSEM, #89: a refusal lands on the recoverable state).
+--
+-- EXPIRY. expires_at = the latest request event's created_at + the board's
+-- join_request_ttl_days. expired mirrors the consent predicates exactly
+-- (created_at < now() - ttl): an expired request no longer counts as consent. It is a property
+-- of the REQUEST and is reported whatever the membership's current state.
+create or replace function agent_board.list_my_board_requests()
+returns table(
+  board_id uuid,
+  board_name text,
+  board_slug text,
+  requested_at timestamptz,
+  membership_state text,
+  expires_at timestamptz,
+  expired boolean
+)
+language plpgsql
+stable
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  if v_actor is null then
+    return;
+  end if;
+
+  return query
+  select
+    b.id,
+    b.name,
+    b.slug,
+    req.created_at,
+    coalesce(cur.membership_state, 'none'),
+    req.created_at + make_interval(days => b.join_request_ttl_days),
+    req.created_at < now() - make_interval(days => b.join_request_ttl_days)
+  from (
+    -- The latest request event per board, by seq (the ledger's total order).
+    select distinct on (e.board_id) e.board_id, e.created_at
+      from agent_board.board_membership_events e
+     where e.agent_id = v_actor
+       and e.provenance = 'target-authored'
+       and e.result_state = 'requested'
+     order by e.board_id, e.seq desc
+  ) req
+  join agent_board.boards b on b.id = req.board_id
+  left join lateral (
+    select bm.membership_state
+      from agent_board.board_memberships bm
+     where bm.board_id = req.board_id
+       and bm.agent_id = v_actor
+     order by case when bm.membership_state in ('joined', 'subscribed') then 0 else 1 end,
+              bm.created_at desc, bm.id desc
+     limit 1
+  ) cur on true
+  order by req.created_at desc, b.id desc;
+end;
+$$;
+
+comment on function agent_board.list_my_board_requests() is
+  'IF-0-ONBOARD-4: the caller''s own join requests as they stand now. Source is the consent ledger (board_membership_events: agent_id = caller, provenance target-authored, result_state requested), never board_memberships.created_by_agent_id, which later writers overwrite. Identity is current_agent_id() only; there is no parameter and a null identity returns nothing, so service_role (no caller identity) is refused EXECUTE. Per board: id, name, slug, the latest request event''s time, the current membership state chosen active-first (MBROWID 3a) or none, expires_at = requested_at + join_request_ttl_days, and expired (the request no longer counts as consent). Requests made before the ledger existed carry only a board-authored backfill_neutral event and are not returned. No per-row history.';
+
+revoke all on function agent_board.list_my_board_requests() from public, anon, service_role;
+grant execute on function agent_board.list_my_board_requests() to authenticated;
+
+-- =============================================================================
+-- 2. invite_board_for_display(p_code_sha256) -- IF-0-ONBOARD-11
+-- =============================================================================
+-- The Portal's consent page shows which board an in-chat enrollment will join, and it holds
+-- only the digest (the code itself never leaves the agent). The digest is the lowercase hex
+-- sha256 of the code text; the argument is compared case-insensitively.
+--
+-- Only a code passing the IF-0-ONBOARD-11 subset resolves: not revoked, not expired, and uses
+-- remaining. This is narrower than the redeem core (see the header), so display is not a promise
+-- that redeem will succeed. Anything else -- including an unknown digest -- returns no row, one uniform
+-- answer. Codes are 256-bit, so the digest is not a practical oracle; EXECUTE is service_role
+-- only regardless, because the Portal calls it server-side.
+create index if not exists idx_agent_board_board_invite_tokens_code_sha256
+  on agent_board.board_invite_tokens (encode(extensions.digest(code, 'sha256'), 'hex'));
+
+create or replace function agent_board.invite_board_for_display(p_code_sha256 text)
+returns table(
+  board_id uuid,
+  board_name text,
+  board_slug text,
+  preset_role text
+)
+language sql
+stable
+security definer
+set search_path = agent_board, public
+as $$
+  select b.id, b.name, b.slug, t.preset_role
+    from agent_board.board_invite_tokens t
+    join agent_board.boards b on b.id = t.board_id
+   where encode(extensions.digest(t.code, 'sha256'), 'hex') = lower(p_code_sha256)
+     and t.revoked_at is null
+     and t.expires_at > now()
+     and (t.max_uses is null or t.uses_count < t.max_uses);
+$$;
+
+comment on function agent_board.invite_board_for_display(text) is
+  'IF-0-ONBOARD-11: resolves an invite code''s digest (lowercase hex sha256 of the code, compared case-insensitively) to (board_id, board_name, board_slug, preset_role) for display on the Portal consent page. Only a usable code resolves -- not revoked, expires_at > now(), and max_uses null or uses_count < max_uses (a subset of the redeem core''s checks, so a displayed board can still fail to redeem); revoked, expired, exhausted and unknown codes return no row. Read-only. EXECUTE is service_role only: the Portal calls it server-side.';
+
+revoke all on function agent_board.invite_board_for_display(text) from public, anon, authenticated;
+grant execute on function agent_board.invite_board_for_display(text) to service_role;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.55.0",
+  "version": "1.57.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.55.0",
+  "packageVersion": "1.57.0",
   "schemaVersion": 8,
   "minClientVersion": "1.1.0",
   "source": {
@@ -46,8 +46,8 @@
       "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
     }
   ],
-  "migrationCount": 153,
-  "aggregateSha256": "90e7cdfd7208e11b31f1699482c22b96f2ad0d797eb9490c85098491881e95dc",
+  "migrationCount": 155,
+  "aggregateSha256": "347357b36b5ee37fbde189e005993c40df1e63a2d9d247b53823761304ae127e",
   "migrations": [
     {
       "order": 0,
@@ -1425,6 +1425,24 @@
       "sourceRef": "message-board",
       "bytes": 55964,
       "sha256": "317d7b41432b36a2e38cc64940838e173e425014e3e256a96d832202b250e82d"
+    },
+    {
+      "order": 153,
+      "id": "20261006000100_agent_board_room_roster_active_first",
+      "filename": "20261006000100_agent_board_room_roster_active_first.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 5470,
+      "sha256": "637480feeca07dbb2fe7a4624dc6d063d0c1f23e6ea3c3ee9a946ad43de4e34e"
+    },
+    {
+      "order": 154,
+      "id": "20261007000100_agent_board_onboard_requests",
+      "filename": "20261007000100_agent_board_onboard_requests.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 7655,
+      "sha256": "fbdbecfb1c78e2d1b16b37845a74082dcdf1241c61c0356b992e1e01baddc41c"
     }
   ],
   "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 + one ROOMCONTRACT + one CALLBACKCONSUMER + one ENROLLTOKENSINGLEUSE 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 + 1 = 153)', () => {
+  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 + one ENROLLTOKENSINGLEUSE + one ROOMCONTRACT-ACTIVEFIRST + one ONBOARD 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 + 1 + 1 + 1 = 155)', () => {
     expect(manifest.migrationCount).toBe(manifest.migrations.length);
-    expect(manifest.migrationCount).toBe(153);
+    expect(manifest.migrationCount).toBe(155);
     // 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,
@@ -340,6 +340,12 @@ describe('manifest integrity', () => {
       '20261004000100_agent_board_callback_consumer_intent.sql',
       // ENROLLTOKENSINGLEUSE (#521): a verified Portal token binds to at most one key.
       '20261005000100_agent_board_enroll_token_single_use.sql',
+      // ROOMCONTRACT-ACTIVEFIRST (#542): list_board_members chooses current standing
+      // active-first (MBROWID 3a) at both its authorization and projection sites.
+      '20261006000100_agent_board_room_roster_active_first.sql',
+      // ONBOARD (v11): list_my_board_requests (IF-0-ONBOARD-4) and the service-only
+      // invite_board_for_display digest lookup (IF-0-ONBOARD-11).
+      '20261007000100_agent_board_onboard_requests.sql',
     ]) {
       expect(names.has(f)).toBe(true);
     }