@consiliency/agent-board-schema 1.28.0 → 1.38.0

package/migrations/20260917000100_agent_board_invite_no_downgrade.sql

@@ -0,0 +1,398 @@
+-- #317 — an invite must not weaken an active membership.
+--
+-- OBSERVED IN PRODUCTION. An agent that had been `joined` on a board since 2026-08-05 was
+-- found with no visible membership. The report inferred the row had been DELETED and that
+-- `v_board_memberships` filtered non-joined rows. Both inferences were wrong, and checking
+-- them is what found this defect:
+--
+--   * the row was never deleted -- `service_role` sees it, and NO shipped function contains a
+--     DELETE against board_memberships (verified across every pg_proc body);
+--   * `v_board_memberships` has no WHERE clause at all. The empty result came from RLS
+--     (`agent_id = current_agent_id()`), which shows a caller only its OWN rows in any state.
+--     So the query could not distinguish "no membership" from "not mine to see";
+--   * `board_membership_events` -- the audit table the report asked for -- already existed and
+--     answered it in one query:
+--
+--       2026-08-05 06:50:34  consent_link_redeem  -> joined
+--       2026-08-20 12:31:31  invite_offer         -> invited     <-- the event
+--
+-- THE DEFECT. `_upsert_board_membership_state` set `membership_state = p_membership_state`
+-- unconditionally, so inviting an agent who is ALREADY joined moves them back to `invited`.
+-- The agent stops receiving board delivery; neither side gets an error; the board just looks
+-- quiet. Absence of evidence renders identically to a negative result.
+--
+-- REPRODUCED before fixing, in a scratch database at this bundle:
+--
+--   1. after join   : joined
+--   2. after invite : invited        <-- DOWNGRADED
+--
+-- WHY THIS IS NOT #109, WHICH ALREADY GUARDS THIS FUNCTION. #109 was the sink acting on the
+-- WRONG ROW -- rejecting a pending request mutated the subject's ACTIVE membership -- and was
+-- fixed by letting a caller name the row it validated (`p_membership_id`). That guard is
+-- correct and untouched. This is the RIGHT row moved in the WRONG DIRECTION, which no
+-- selection rule can catch. Filed as one defect class, fixed as another.
+--
+-- THE RULE. `invited` and `requested` are OFFERS: they describe a membership that does not yet
+-- exist. Applying an offer to a membership that DOES exist (`joined`/`subscribed`) leaves the
+-- state alone -- the offer is already satisfied and the stronger standing wins.
+--
+-- A no-op rather than an exception, deliberately. Invite is idempotent by design (the
+-- MBCONSENT invite flow re-offers freely); raising here would break callers that succeed
+-- today, converting a silent demotion into a loud crash rather than into correct behaviour.
+--
+-- SCOPE, stated as what is actually asserted rather than as a claim about "all callers".
+-- The guard lives in the SHARED SINK, which is the only function that can MOVE AN EXISTING ROW
+-- between states -- so every caller that reaches the state through it (invite_board_member,
+-- join_board, request_join_board, resolve_board_request, update_board_membership, and
+-- leave_board by delegation) inherits it.
+--
+-- "MOVE AN EXISTING ROW", not "assigns membership_state", and the distinction is load-bearing
+-- rather than pedantic. An earlier draft of this sentence said the sink was the only function
+-- that ASSIGNS the column, and the catalog falsifies that: the seeding writers assign it in an
+-- INSERT COLUMN LIST -- `_redeem_unbounded_invite_for_agent` writes `preset_membership_state`
+-- that way (20260909000100:988-993), as do create_board and the two bootstrap paths. What they
+-- cannot do is move a row that already exists, which is what this defect is about and what the
+-- test actually asserts ("the ONLY writer that assigns membership_state IN A SET CLAUSE"). The
+-- test's label was right while this sentence was wrong; a review seat found the disagreement.
+--
+-- The claim is not asserted by reading this comment: agent_board_invite_no_downgrade.test.sql
+-- enumerates from pg_proc, over stripped_body so prose cannot satisfy it, and pins THREE
+-- separate containments, each verified by a mutation that made it fail by name:
+--
+--   * the set of functions that WRITE board_memberships is exactly six (a new writer is named);
+--   * of those six, exactly one assigns membership_state IN A SET CLAUSE -- six distinct writer
+--     spellings were
+--     each confirmed to fail it BY NAME: `UPDATE ... SET`, `INSERT ... ON CONFLICT DO UPDATE
+--     SET`, `MERGE INTO ... WHEN MATCHED THEN UPDATE SET`, an UNQUALIFIED `update
+--     board_memberships` resolved by search_path, a statement assembled inside a string literal
+--     and run by `EXECUTE`, and a `BEGIN ATOMIC` body (whose prosrc is empty);
+--   * no user TRIGGER on the table, which could assign NEW.membership_state without any
+--     function body naming it.
+--
+-- WHAT THOSE ASSERTIONS STILL DO NOT COVER, said plainly rather than left to be discovered:
+-- the scan is `nspname = 'agent_board'`, so a writer in another schema is outside it; and it is
+-- a regex over function source, so its completeness is the completeness of the pattern. The
+-- pattern is taken verbatim from agent_board_receipt_subject_gate.test.sql rather than written
+-- fresh, so the spellings that file already paid to learn are inherited instead of rediscovered.
+--
+-- THE FIRST DRAFT OF THAT CLASS ASSERTION WAS WRONG, and the way it was wrong is the point.
+-- It required `update agent_board.board_memberships`, so it named a class its predicate did not
+-- cover: FOUR separate decoys each left it fully green -- `insert ... on conflict ... do update
+-- set` (the shape the invite-link path actually uses), `merge into`, the unqualified spelling,
+-- and dynamic SQL inside a literal. Three of the four were found by the review board, not by
+-- the author, on a draft whose own header already claimed the class was closed.
+--
+-- THE SECOND DOOR, checked rather than assumed. `_redeem_unbounded_invite_for_agent` reaches an
+-- ACTIVE membership by that very ON CONFLICT DO UPDATE. Its SET list lifts `role` and
+-- `updated_at` only, so it cannot move the state -- and the test proves that behaviourally (a
+-- joined member redeems a `subscribed`-preset link and stays joined), not by citing this note.
+--
+-- UNTOUCHED TRANSITIONS, asserted positively in the test: joined <-> subscribed (a self-toggle
+-- must still work), active -> left/removed, and re-entry to joined from any non-active state
+-- (the ROLERESET #79 clamp still applies on that path). These are load-bearing, not decoration:
+-- a guard broadened to block every offer regardless of current state trips
+-- `board_memberships_state_left_at` on the re-invite path, and every mutating call in the test
+-- is wrapped in lives_ok for that reason. Measured both ways on this file: as a BARE call the
+-- transaction aborts and pgTAP prints ZERO `not ok` lines -- the failure is invisible, not
+-- loud -- while wrapped it runs every assertion and fails two of them BY NAME.
+--
+-- Stated without a count on purpose. An earlier version of this sentence carried one, and the
+-- review board caught it stale: the count had been re-denominated rather than re-measured when
+-- the file grew. A hand-maintained number describing a machine-derivable fact is rule 1's
+-- anti-pattern applied to prose, and it drifts the same way.
+
+CREATE OR REPLACE FUNCTION agent_board._upsert_board_membership_state(p_board_id uuid, p_agent_id uuid, p_membership_state text, p_created_by_agent_id uuid DEFAULT NULL::uuid, p_metadata jsonb DEFAULT '{}'::jsonb, p_membership_id uuid DEFAULT NULL::uuid, p_event_kind text DEFAULT NULL::text)
+ RETURNS agent_board.board_memberships
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_membership agent_board.board_memberships%rowtype;
+  v_metadata jsonb;
+  -- EC-MBROWID-3: currently-removed standing (R-LINK-7 set form), not a single row.
+  v_currently_removed boolean;
+  v_prior_state text;
+  -- #317: the resolved next membership_state, computed ONCE and then both written and compared.
+  -- An earlier draft wrote the guard as a CASE in the SET clause and RESTATED the same predicate
+  -- to decide whether to emit. The two agreed, and nothing asserted they must: dropping
+  -- `subscribed` from the emit copy alone re-created the false-ledger defect verbatim, and adding
+  -- `removed` to it alone silently dropped a real state change from an append-only ledger. Both
+  -- left the entire suite green. Deriving once removes the possibility rather than testing for it.
+  v_next_state text;
+  v_offer_noop boolean := false;
+begin
+  if p_membership_state not in ('requested', 'invited', 'joined', 'subscribed', 'left', 'removed') then
+    raise exception 'invalid board membership state' using errcode = '22023';
+  end if;
+
+  -- Metadata must be a JSON OBJECT. Previously a scalar/array was stored verbatim on insert and
+  -- concatenated on update; the reserved-key strip below iterates keys, so a non-object would raise
+  -- an opaque internal error. Fail explicitly instead. Reachable from the CLI `--metadata`, which
+  -- parses arbitrary JSON — this is a deliberate, declared behavior change for ALL mutator callers.
+  if jsonb_typeof(coalesce(p_metadata, '{}'::jsonb)) <> 'object' then
+    raise exception 'board membership metadata must be a JSON object' using errcode = '22023';
+  end if;
+
+  -- Reserved namespace: `ops_*` keys are operational state (the retention sweep's skip marker
+  -- `ops_retained_at`, read for board_memberships at 20260513000001:122) and must never be writable
+  -- by a caller whose own row they govern. Strip them from caller input; operational writers set
+  -- the column directly.
+  select coalesce(jsonb_object_agg(e.key, e.value), '{}'::jsonb)
+    into v_metadata
+    from jsonb_each(coalesce(p_metadata, '{}'::jsonb)) as e(key, value)
+   where e.key not like 'ops\_%';
+
+  -- EC-MBROWID-3 / R-LINK-7: currently-removed standing is the SET predicate
+  -- (exists removed AND no active), not a single total-ordered row. A higher-id
+  -- removed row can coexist with an active row; inferring "removed" from the
+  -- total-order winner alone would then try to activate the removed row and
+  -- collide with idx_agent_board_board_memberships_active_unique (23505).
+  -- Capture standing before the row lock so the predicate is independent of
+  -- which physical row the active-preferring SELECT below returns.
+  v_currently_removed :=
+    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')
+    );
+
+  -- Duplicate-aware ACTIVE-row selection (3a): prefer an active row when one
+  -- exists, then total-order by created_at desc, id desc. A pure total-order
+  -- can select a higher-id REMOVED row while an ACTIVE row still exists.
+  -- When v_currently_removed, no active row exists and the total-order pick is
+  -- non-active (re-entry clamp applies below).
+  -- When the caller names a row it has already validated AND LOCKED, act on THAT row. The
+  -- active-preferring pick below is right when the sink chooses for itself, but wrong when a
+  -- caller validated a specific one: rejecting a pending request would lock and mutate the
+  -- subject's ACTIVE membership instead, downgrading a real member (#109).
+  if p_membership_id is not null then
+    select *
+      into v_membership
+      from agent_board.board_memberships bm
+     where bm.id = p_membership_id
+       and bm.board_id = p_board_id
+       and bm.agent_id = p_agent_id
+     for update;
+
+    if v_membership.id is null then
+      raise exception 'membership row % not found for this subject', p_membership_id
+        using errcode = 'P0002';
+    end if;
+  else
+    select *
+      into v_membership
+      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
+     for update;
+  end if;
+
+  -- The PRIOR state, captured before the update below overwrites v_membership. The emitter
+  -- cannot see it, and without it a joined<->subscribed self-toggle is indistinguishable from
+  -- a fresh join.
+  v_prior_state := v_membership.membership_state;
+
+  if v_membership.id is null then
+    -- INSERT branch intentionally omits `role` so a no-prior-row entry takes the table default
+    -- (20260717000100:13-15). Do not write role here — an explicit write is wrong.
+    insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, left_at, metadata)
+    values (
+      p_board_id,
+      p_agent_id,
+      p_membership_state,
+      p_created_by_agent_id,
+      case when p_membership_state in ('left', 'removed') then now() else null end,
+      v_metadata
+    )
+    returning * into v_membership;
+  else
+    -- THE #317 RULE, in one place. `invited` and `requested` are OFFERS: they describe a
+    -- membership that does not yet exist. Applying one to a membership that DOES exist
+    -- (`joined`/`subscribed`) leaves the state alone -- the offer is already satisfied and the
+    -- stronger standing wins. Every other transition is untouched, including joined <-> subscribed,
+    -- active -> left/removed, and re-entry from any non-active state.
+    v_next_state := case
+                      when p_membership_state in ('invited', 'requested')
+                       and v_membership.membership_state in ('joined', 'subscribed')
+                        then v_membership.membership_state
+                      else p_membership_state
+                    end;
+
+    -- Suppressed iff the state did not move AND the caller asked for something else. The second
+    -- conjunct matters: join_board and update_board_membership both permit joined -> joined, which
+    -- also does not move the state but IS the caller getting what they asked for, and still emits.
+    v_offer_noop := v_next_state is not distinct from v_membership.membership_state
+                    and p_membership_state is distinct from v_next_state;
+
+    update agent_board.board_memberships bm
+       -- #317: AN INVITE MUST NOT WEAKEN AN ACTIVE MEMBERSHIP.
+       --
+       -- Reproduced on production and again in a scratch database: an agent JOINED since
+       -- 2026-08-05 was moved back to `invited` by a single invite_offer, because this UPDATE
+       -- set the requested state unconditionally. The row was never deleted -- it was
+       -- DOWNGRADED, and the agent silently lost board delivery while both sides saw a board
+       -- that merely looked quiet.
+       --
+       -- This is NOT #109 and the #109 guard does not cover it. #109 was the sink acting on the
+       -- WRONG ROW (an active row when a pending one had been validated), fixed by the
+       -- p_membership_id targeting above. This is the RIGHT row moved in the WRONG DIRECTION,
+       -- so it needs a direction rule, not a selection rule.
+       --
+       -- The rule: `invited` and `requested` are OFFERS -- they describe a membership that does
+       -- not yet exist. Applying an offer to one that DOES exist (`joined`/`subscribed`) leaves
+       -- the state alone: the offer is already satisfied and the stronger standing wins. Every
+       -- other transition is untouched, including joined <-> subscribed, active -> left/removed,
+       -- and re-entry from any non-active state.
+       --
+       -- A no-op rather than an exception, deliberately: invite is idempotent by design (the
+       -- MBCONSENT invite flow re-offers freely) and raising here would break callers that
+       -- succeed today.
+       --
+       -- "No-op" IS COLUMN-SCOPED, and saying so is the difference between a true claim and a
+       -- comfortable one. What a suppressed offer preserves is the AUTHORITY-BEARING state:
+       -- membership_state, left_at, and role. The row is still WRITTEN -- created_by_agent_id,
+       -- metadata and updated_at all follow the ordinary path below. That is pre-existing
+       -- behaviour this change does not alter: created_by_agent_id is audit provenance surfaced
+       -- as created_by_handle (20260507000000:85-87), not authority, and the metadata merge is
+       -- what every other caller gets. Making a suppressed offer skip the UPDATE entirely would
+       -- be defensible and is deliberately NOT done here -- it would change metadata semantics
+       -- for a path unrelated to the defect, in a fix meant to be narrow. Both the preserved
+       -- columns and the written ones are asserted, so the scope is a fact rather than a promise.
+       -- v_next_state, derived above. NOTE the deliberate asymmetry with the two CASEs below:
+       -- `role` and `left_at` still key off p_membership_state, the caller's REQUEST, and that is
+       -- correct rather than an oversight -- the #79 role clamp fires on ADMISSION to an active
+       -- state, and a suppressed offer admits nobody.
+       --
+       -- Stated precisely, because a first draft of this comment overclaimed and a mutation
+       -- refuted it: keying the clamp off v_next_state instead does NOT reset an ordinary owner,
+       -- because the clamp's second conjunct already requires the PRIOR state to be non-active
+       -- (or currently-removed standing to hold), and on a suppressed offer the prior state is
+       -- active by construction. The two spellings differ only in the `v_currently_removed`
+       -- corner, where the selected row is active while a removed duplicate exists. So the
+       -- asymmetry is worth keeping and worth explaining, but it is not the gaping hole the
+       -- draft claimed. The assertions below pin the ordinary case, which is what they cover.
+       set membership_state = v_next_state,
+           created_by_agent_id = coalesce(p_created_by_agent_id, bm.created_by_agent_id),
+           -- PRESERVE the first departure time. Restamping it would let the departing agent (or a
+           -- re-kicking owner) push its own row past the retention cutoff (20260513000001:121).
+           left_at = case
+                       when p_membership_state in ('left', 'removed') then
+                         case
+                           -- SAME terminal state re-asserted: preserve the FIRST departure time so a
+                           -- repeat call cannot push the retention cutoff forward.
+                           when v_membership.membership_state = p_membership_state
+                             then coalesce(v_membership.left_at, now())
+                           -- GENUINE transition (notably left -> removed, an owner barring
+                           -- invite-link re-entry for an already-departed agent) stamps NOW. R-LINK-7
+                           -- deliberately does not block voluntary 'left' (20260724000100:321-322),
+                           -- so this is the real kick moment; inheriting the earlier departure would
+                           -- both lose the audit answer and make the marker row retention-eligible
+                           -- prematurely.
+                           else now()
+                         end
+                       else null
+                     end,
+           -- ROLERESET (#79): clamp role to the table default on non-active -> active re-entry.
+           -- Hardcoded 'member' (column default at 20260717000100:13-15); do not read
+           -- information_schema at runtime. Active -> active preserves bm.role (including owner).
+           -- Unconditional — no service_role exemption.
+           -- MBROWID: origin is non-active when the selected row is non-active OR when
+           -- currently-removed standing holds (R-LINK-7 set form). With active-preferring
+           -- selection those agree; the set form is load-bearing against equal-created_at
+           -- removed+left duplicates where a single-row read would flip with id order.
+           role = case
+                    when p_membership_state in ('joined', 'subscribed')
+                     and (
+                       v_membership.membership_state not in ('joined', 'subscribed')
+                       or v_currently_removed
+                     )
+                    then 'member'
+                    else bm.role
+                  end,
+           metadata = coalesce(bm.metadata, '{}'::jsonb) || v_metadata,
+           updated_at = now()
+     where bm.id = v_membership.id
+     returning * into v_membership;
+  end if;
+
+  -- Emission is delegated so the sink and the four raw writers cannot drift apart.
+  -- The frozen mapping distinguishes a self-TOGGLE between two active states from a fresh
+  -- self-JOIN. Only the sink knows the prior state, so it names the kind; the emitter derives
+  -- everything security-critical regardless.
+  -- A caller-supplied kind wins; otherwise the sink's own derivation stands. Only the
+  -- DESCRIPTIVE field is delegated -- provenance is always derived from the session.
+  --
+  -- #317 -- NOTHING IS EMITTED WHEN NOTHING HAPPENED, and both of the obvious alternatives are
+  -- WORSE. Before the guard above, the argument and the resulting row could not differ, so the
+  -- question did not arise. The guard makes them differ on exactly one path, and that path then
+  -- has three options, two of which are defects:
+  --
+  --   * emit `p_membership_state` (what the first draft of this migration did): appends
+  --     `result_state = 'invited'` beside a row that says `joined`. `board_membership_events` is
+  --     append-only, so the false row can never be corrected -- and it is the table the #317
+  --     investigation itself read to establish what happened. The fix would have falsified its
+  --     own diagnostic. Caught by three review seats.
+  --
+  --   * emit `v_membership.membership_state` (what the SECOND draft did, "fixing" the above):
+  --     MINTS CONSENT OUT OF AN OFFER, which is strictly worse than a cosmetically wrong row.
+  --     `_membership_consent_present` -- the FROZEN MBCONSENT interface (IF-0-MBCONSENT-1) that
+  --     `update_board_membership` consults before admitting anyone -- treats
+  --     `operator-designated` + `result_state in ('joined','subscribed')` as an actual PLACEMENT,
+  --     i.e. as consent. An operator re-inviting a member whose ledger is silent would therefore
+  --     turn a mere OFFER into an admission grant. Measured, not reasoned:
+  --
+  --         consent BEFORE operator re-invite = false
+  --         consent AFTER  operator re-invite = true
+  --
+  --     That is the precise narrowing MBCONSENT shipped 20260806000100 to make -- "a bare operator
+  --     `invited` OFFER must be NEUTRAL" -- reopened from the other side. Delegating a kind cannot
+  --     avoid it either: the predicate keys on (provenance, result_state) ONLY, and provenance is
+  --     derived from the session and is not delegatable.
+  --
+  --   * emit nothing, which is what this does. `board_membership_events` records membership-state
+  --     events; a suppressed offer changed no state, so there is no event. A silent ledger reads
+  --     as `false` from the consent predicate, so this cannot mint anything, and it writes no row
+  --     that a later reader must distrust.
+  --
+  -- WHAT THIS GIVES UP, stated rather than left to be discovered: an invite that lands on an
+  -- already-active member is no longer visible in this ledger at all. That is a real loss of
+  -- audit for a real action. It is accepted because the only two ways to record it here are a
+  -- false statement about the row or a forged consent grant, and because the CALLER still sees
+  -- the outcome -- invite_board_member and update_board_membership both return the row, which
+  -- now reads `joined` rather than `invited`. If that action needs auditing, it needs a surface
+  -- that is not the consent ledger.
+  --
+  -- Emission is otherwise unchanged and still delegated, so the sink and the raw writers cannot
+  -- drift apart.
+  if not v_offer_noop then
+    perform agent_board._emit_membership_event(
+      p_board_id, p_agent_id, p_membership_state,
+      coalesce(p_event_kind, case
+        when v_prior_state in ('joined', 'subscribed')
+         and p_membership_state in ('joined', 'subscribed')
+         -- The states must actually DIFFER. join_board and update_board_membership both permit
+         -- joined->joined and subscribed->subscribed, and a write that changes nothing is not a
+         -- toggle of anything -- recording it as one permanently mislabels an append-only event.
+         and v_prior_state <> p_membership_state
+         and not agent_board._is_service_role()
+         and agent_board.current_agent_id() = p_agent_id
+        then 'consent_self_toggle'
+        else null
+      end));
+  end if;
+
+  return v_membership;
+end;
+$function$;

package/migrations/20260918000100_agent_board_signed_write_enforced_repoint.sql

@@ -0,0 +1,139 @@
+-- #310 — `signed_write_enforced` reports false for a system that IS enforcing.
+--
+-- THE DEFECT. `get_bundle_compatibility` reported `signed_write_enforced: false` on the canonical
+-- project while enforcement was intact. Reproduced on a FRESHLY BUILT database from this tree's
+-- bundle, so it is in the schema and not an artifact of one deployment.
+--
+-- The predicate encoded a model this project deliberately ABANDONED. It asked whether
+-- `authenticated` can EXECUTE four raw write RPCs, and reported enforcement only when it cannot.
+-- `20260718000800_agent_board_regrant_scoped_send.sql` re-granted EXECUTE on the eight send
+-- overloads on purpose -- its own header calls MBSESSION "the enforcement-switches-on point (the
+-- re-grant makes the authenticated live path real)". Enforcement moved from "authenticated cannot
+-- call it" to "the call gates INSIDE the function". The flag never moved with it.
+--
+-- WHY THAT IS WORTH A MIGRATION RATHER THAN A SHRUG. A health check that reports `false` for a
+-- system that is enforcing trains its readers to ignore it, which is worse than having no flag:
+-- the next real regression reads exactly the same. It also contradicted specs/operations.md.
+--
+-- THE INSTRUMENT WAS ALSO WRONG, independently of the model. `information_schema.
+-- role_routine_grants` shows DIRECT grants only, and only for roles the current user can see --
+-- the fail-open shape #302 corrected elsewhere. `has_function_privilege` resolves privileges
+-- inherited through role membership AND the PUBLIC default, which is the #118 class: a
+-- SECURITY DEFINER function recreated without restating its revoke is EXECUTE-able by PUBLIC,
+-- and a direct-grant read cannot see it. Every privilege question here now uses the resolver.
+--
+-- WHAT THE FLAG MEANS NOW, stated as exactly what it tests:
+--
+--   1. the signed gateway EXISTS (the anchor -- without it the second clause is vacuously true,
+--      because a schema with no signed_* functions trivially grants none of them);
+--   2. NO function named `signed\_%` is EXECUTE-able by `authenticated` or `anon`.
+--
+-- The `signed_%` set is read from pg_proc, NOT the four-name list the old predicate carried:
+-- there are SEVEN signed gateways, and a hand list that said four is precisely the failure
+-- CLAUDE.md rule 1 exists to stop. It iterates pg_proc ROWS rather than resolving names, because
+-- `to_regproc` returns NULL on an OVERLOADED name and the send family is overloaded -- a
+-- name-based check would silently skip exactly the functions most worth checking.
+--
+-- WHAT THIS FLAG DELIBERATELY DOES NOT TEST. "Cannot" would overstate it, so: what follows
+-- refutes a shipped prosrc SCAN, which is one alternative, not the whole class. A body-identity
+-- FINGERPRINT -- shipping expected (proname, proargtypes, hash(prosrc)) rows and comparing live
+-- pg_proc against them -- is immune to the comment objection, since a comment changes the hash
+-- and fails in the SAFE direction, and the repo already ships two checked-in catalog snapshots
+-- regenerated under `schema:after-migration --fix`. It is rejected as EXPENSIVE AND NOISY, not
+-- impossible: every migration touching a gated function would have to update the table in the
+-- same migration, and a comment-only edit would produce a false `false` -- an instrument that
+-- cries wolf, which is #310's own failure mode. The scan argument below stands on its own.
+-- "Every unsigned writer derives its actor from the session and gates" is a property of function
+-- BODIES. Testing it here would mean a shipped function scanning `prosrc` at runtime -- no
+-- shipped function does that today, and a raw scan is satisfied by a COMMENT, which is the
+-- #196/#199 class. The test-only strip helpers that make such a scan sound live in
+-- `agent_board_test`, and shipping a second copy into `agent_board` is the two-copies-drift
+-- failure #199 already names.
+--
+-- So that half is asserted in agent_board_signed_write_enforced.test.sql instead, over the CALL
+-- CLOSURE rather than direct bodies -- which is load-bearing: only 3 of the 7 unsigned
+-- counterparts name `_resolved_actor_agent_id` in their own body. The other four DELEGATE to
+-- `post_message`, so a direct body scan would report them ungated and be wrong.
+--
+-- CONSEQUENCE, stated with the qualifier that makes it TRUE. A new ungated writer that is the
+-- COUNTERPART OF A SIGNED GATEWAY turns the pgTAP class assertion red, not this flag. A new
+-- ungated writer with NO signed twin turns NEITHER red: every class-scoping predicate in that
+-- file bounds the class by `signed\_%` and derives the counterpart by stripping the prefix, so
+-- such a writer is outside the class by construction. Verified rather than reasoned -- an
+-- authenticated-executable SECURITY DEFINER writer deriving nothing from the session left the
+-- flag true and all 19 assertions green.
+--
+-- An earlier draft of this sentence, and of the COMMENT below, said "a new UNGATED writer"
+-- without the qualifier. The review board caught it. The unqualified form is this repo's most
+-- common defect -- a claim broader than its evidence -- and it was in the one statement of
+-- meaning that ships INSIDE the database and outlives this PR.
+--
+-- Closing it properly means an EFFECT-derived class ("every authenticated-executable function
+-- that writes a message/task/authority row") rather than a NAME-derived one. That shape already
+-- exists in this repo: agent_board_consent_gating.test.sql EC-4 derives its class from what a
+-- function REACHES, explicitly refusing an enumerated list. It is filed as a follow-up rather
+-- than done here, because it is a bigger class than #310's subject and deserves its own review.
+--
+-- CREATE OR REPLACE with the identical signature, so the existing ACL survives -- verified
+-- before writing this: `authenticated` and `service_role` hold EXECUTE, `anon` does not, and
+-- PUBLIC holds nothing. The grants are restated anyway and a COMMENT added, because a recreated
+-- SECURITY DEFINER function that does not restate them is the gate-bypass this repo has already
+-- shipped once. The executor set is pinned by assertion, not by this note.
+
+CREATE OR REPLACE FUNCTION agent_board.get_bundle_compatibility()
+ RETURNS jsonb
+ LANGUAGE sql
+ STABLE SECURITY DEFINER
+ SET search_path TO 'agent_board', 'pg_temp'
+AS $function$
+  select jsonb_build_object(
+    'schema_version', (select version from agent_board.schema_version limit 1),
+    'installed_bundle_version', (select package_version from agent_board.bundle_installation limit 1),
+    'installed_bundle_digest', (select bundle_digest from agent_board.bundle_installation limit 1),
+    'installed_schema_version', (select schema_version from agent_board.bundle_installation limit 1),
+    'source_commit', (select source_commit from agent_board.bundle_installation limit 1),
+    -- #310: enforcement means the SIGNED path stays operator-only, not that the unsigned path is
+    -- unreachable. See this migration's header for what this does and does not establish.
+    'signed_write_enforced', (
+      -- The anchor. A schema with no signed gateway grants none of them, which would make the
+      -- second clause vacuously true; requiring the gateway to exist is what stops "enforced"
+      -- from meaning "nothing to enforce".
+      exists (
+        select 1
+          from pg_catalog.pg_proc p
+          join pg_catalog.pg_namespace n on n.oid = p.pronamespace
+         where n.nspname = 'agent_board'
+           and p.proname = 'signed_send_direct_message'
+      )
+      and not exists (
+        -- Catalog-derived over pg_proc ROWS: covers all seven gateways and every overload of
+        -- each, and asks the privilege RESOLVER rather than reading a direct-grant view.
+        select 1
+          from pg_catalog.pg_proc p
+          join pg_catalog.pg_namespace n on n.oid = p.pronamespace
+         cross join (values ('authenticated'), ('anon')) as r(rolname)
+         where n.nspname = 'agent_board'
+           and p.proname like 'signed\_%'
+           and pg_catalog.has_function_privilege(r.rolname, p.oid, 'EXECUTE')
+      )
+    ),
+    -- Ready only once the materializer has recorded an install AND the schema
+    -- version handshake resolves.
+    'ready', (
+      (select version from agent_board.schema_version limit 1) is not null
+      and exists (select 1 from agent_board.bundle_installation)
+    ),
+    'checked_at', now()
+  );
+$function$;
+
+-- Restated rather than relied upon. CREATE OR REPLACE preserves the ACL, but this repo has
+-- already shipped a gate-bypass by recreating a SECURITY DEFINER function without restating its
+-- privileges, so the rule is to restate them in the same migration every time. `anon` is
+-- deliberately NOT granted: it did not hold EXECUTE before this migration and must not gain it.
+revoke all on function agent_board.get_bundle_compatibility() from public;
+grant execute on function agent_board.get_bundle_compatibility() to authenticated;
+grant execute on function agent_board.get_bundle_compatibility() to service_role;
+
+comment on function agent_board.get_bundle_compatibility() is
+  'Bundle/schema handshake for adopters. `signed_write_enforced` is TRUE iff the signed gateway exists AND no agent_board.signed_* function (all overloads, via has_function_privilege) is EXECUTE-able by authenticated or anon. GUIDANCE, not an assertion: read a FALSE together with installed_bundle_version from the same response -- below 1.37.0 it means the retired predicate, at or above it a real regression. That version is what the materializer RECORDED, which is evidence about intent rather than proof of which predicate body is live, so it is a decode hint and not a gate. It does NOT test that a writer derives its actor from the session and gates. That half is asserted in agent_board_signed_write_enforced.test.sql, and ONLY for the unsigned counterpart of a signed_* gateway -- a writer with no signed twin is outside both instruments. #310.';

package/migrations/20260919000100_agent_board_signed_write_model_key.sql

@@ -0,0 +1,107 @@
+-- SIGNEDWRITEMODEL (message-board#326) — a self-describing sibling for
+-- `signed_write_enforced` in the bundle/schema handshake.
+--
+-- THE PROBLEM. After #324 the flag has the right VALUE and the wrong NAME. It is
+-- called "signed write enforced" and it tests "the signed path is operator-only".
+-- Those are different propositions, and a boolean cannot say which one it means.
+-- The consequence is already written down in specs/operations.md: a reader must
+-- combine the flag with `installed_bundle_version` to know which MEANING they are
+-- looking at — below 1.37.0 it tests the model 20260718000800 abandoned, at or
+-- above it tests the current one. That works and it asks every reader to carry a
+-- version boundary in their head.
+--
+-- WHY NOT RENAME OR RETIRE, which is the strongest argument in this area.
+-- packages/agent-board-client/src/compatibility.ts recognises a health response
+-- with a runtime TYPE GUARD:
+--     "schema_version" in value && "signed_write_enforced" in value && "ready" in value
+-- Drop the key and every deployed client stops recognising a HEALTHY board's
+-- response as a health response at all. The other spelling of retirement — keep
+-- the key, pin it false/null forever — is a permanently-lying instrument, which is
+-- precisely the harm #310 names. Retirement loses both ways, which is why #324
+-- re-pointed rather than replaced, and why this migration ADDS.
+--
+-- WHY ADDING IS SAFE, and how far that claim goes. The guard requires those three
+-- keys to be PRESENT; it does not enumerate the payload. Checked rather than
+-- assumed: no consumer in this repository asserts an exhaustive key set over
+-- `get_bundle_compatibility()` — the pgTAP consumers read individual keys with
+-- `->>`, and the client reads named fields. A consumer OUTSIDE this repository
+-- that pins the whole object would still be broken by any added key, which is a
+-- property of adding keys and not of this one.
+--
+-- NOT PROPOSED: gating on it. A sound gate is constructible
+-- (`installed_bundle_version >= 1.37.0 AND flag true`) but semver strings need
+-- real comparison, and the recorded version is what the materializer WROTE, not
+-- necessarily what is APPLIED. That makes a good argument and a bad gate, so this
+-- ships as a decode hint like the boolean beside it.
+--
+-- FUTURE-PROOFING is the actual point. The next posture change adds a new VALUE
+-- here rather than silently re-pointing a boolean for a second time — which is
+-- exactly what #310 was.
+--
+-- CREATE OR REPLACE with the identical signature, so the existing ACL survives.
+-- The grants are restated anyway and the COMMENT rewritten, because a recreated
+-- SECURITY DEFINER function that does not restate them is the gate-bypass this
+-- repo has already shipped once (#118). `anon` is deliberately NOT granted.
+
+CREATE OR REPLACE FUNCTION agent_board.get_bundle_compatibility()
+ RETURNS jsonb
+ LANGUAGE sql
+ STABLE SECURITY DEFINER
+ SET search_path TO 'agent_board', 'pg_temp'
+AS $function$
+  select jsonb_build_object(
+    'schema_version', (select version from agent_board.schema_version limit 1),
+    'installed_bundle_version', (select package_version from agent_board.bundle_installation limit 1),
+    'installed_bundle_digest', (select bundle_digest from agent_board.bundle_installation limit 1),
+    'installed_schema_version', (select schema_version from agent_board.bundle_installation limit 1),
+    'source_commit', (select source_commit from agent_board.bundle_installation limit 1),
+    -- #326: which PROPOSITION the boolean below is answering, said out loud, so a
+    -- reader does not have to consult a version boundary to decode it. A constant
+    -- rather than a derivation: it names the model this bundle's predicate encodes,
+    -- which is a fact about the migration you are reading, not about the database.
+    'signed_write_model', 'operator-only-gateway',
+    -- #310: enforcement means the SIGNED path stays operator-only, not that the unsigned path is
+    -- unreachable. See 20260918000100's header for what this does and does not establish.
+    'signed_write_enforced', (
+      -- The anchor. A schema with no signed gateway grants none of them, which would make the
+      -- second clause vacuously true; requiring the gateway to exist is what stops "enforced"
+      -- from meaning "nothing to enforce".
+      exists (
+        select 1
+          from pg_catalog.pg_proc p
+          join pg_catalog.pg_namespace n on n.oid = p.pronamespace
+         where n.nspname = 'agent_board'
+           and p.proname = 'signed_send_direct_message'
+      )
+      and not exists (
+        -- Catalog-derived over pg_proc ROWS: covers all seven gateways and every overload of
+        -- each, and asks the privilege RESOLVER rather than reading a direct-grant view.
+        select 1
+          from pg_catalog.pg_proc p
+          join pg_catalog.pg_namespace n on n.oid = p.pronamespace
+         cross join (values ('authenticated'), ('anon')) as r(rolname)
+         where n.nspname = 'agent_board'
+           and p.proname like 'signed\_%'
+           and pg_catalog.has_function_privilege(r.rolname, p.oid, 'EXECUTE')
+      )
+    ),
+    -- Ready only once the materializer has recorded an install AND the schema
+    -- version handshake resolves.
+    'ready', (
+      (select version from agent_board.schema_version limit 1) is not null
+      and exists (select 1 from agent_board.bundle_installation)
+    ),
+    'checked_at', now()
+  );
+$function$;
+
+-- Restated rather than relied upon. CREATE OR REPLACE preserves the ACL, but this repo has
+-- already shipped a gate-bypass by recreating a SECURITY DEFINER function without restating its
+-- privileges, so the rule is to restate them in the same migration every time. `anon` is
+-- deliberately NOT granted: it did not hold EXECUTE before this migration and must not gain it.
+revoke all on function agent_board.get_bundle_compatibility() from public;
+grant execute on function agent_board.get_bundle_compatibility() to authenticated;
+grant execute on function agent_board.get_bundle_compatibility() to service_role;
+
+comment on function agent_board.get_bundle_compatibility() is
+  'Bundle/schema handshake for adopters. `signed_write_model` NAMES the proposition the boolean beside it answers -- `operator-only-gateway` means "the signed gateway exists and no agent_board.signed_* function (all overloads, via has_function_privilege) is EXECUTE-able by authenticated or anon". Read the pair: the model says WHAT is being tested, `signed_write_enforced` says whether it HOLDS. PRESENCE of this key implies the current meaning and needs no semver comparison. ABSENCE does NOT imply the retired one: the boolean changed meaning at bundle 1.37.0 and this key starts at 1.38.0, so on exactly 1.37.x the key is absent while a FALSE is a REAL regression. Absent means consult installed_bundle_version, not "nothing to see". Neither field is a gate. Neither tests that a writer derives its actor from the session and gates -- that half is asserted in agent_board_signed_write_enforced.test.sql, and ONLY for the unsigned counterpart of a signed_* gateway, so a writer with no signed twin is outside both instruments. #310, #326.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.28.0",
+  "version": "1.38.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",