@consiliency/agent-board-schema 1.28.0 → 1.38.0

package/src/deployment-drift.test.mjs

@@ -0,0 +1,301 @@
+// Tests for the deployment-drift DECISION.
+//
+// These call `evaluate()` from scripts/lib/drift-evaluate.mjs — the function the script
+// ships and uses. Nothing here reimplements the rule.
+//
+// That matters because the first version of this file did exactly that: it extracted two
+// leaf helpers and wrote the staleness rule locally, while the PR body claimed the tests
+// drove the shipped code. A three-seat review found the claim false and the real control
+// flow untested — including a path where a board with an unparseable timestamp was
+// reported `ok`.
+//
+// WHAT THE `OK` CASES ARE. An earlier version of this header claimed every "reports ok"
+// case below was a fail-open regression test. That was false, and it mattered: it dressed
+// up ordinary coverage as security coverage. There are two different kinds here, and they
+// are labelled:
+//   - FAIL-OPEN regression: the case returned `ok` in a previous version and must NOT.
+//     Those all assert UNKNOWN or DRIFT — see "UNKNOWN never collapses into OK" and
+//     "second-round fail-open regressions".
+//   - HAPPY-PATH / BOUNDARY / SKEW: the case must return OK, and the test exists so the
+//     check cannot be made trivially strict. A gate that fires on the normal state gets
+//     ignored, which is its own failure mode. These are the OK assertions at "the happy
+//     path is genuinely reachable", "does NOT flag a small, fresh gap", "tolerates a
+//     minute of clock skew", "pins the exact threshold boundary", and the behind-board
+//     case in "branches a mutation must not survive".
+//
+// The script itself — argv parsing, credential scrubbing, and the exit-code mapping this
+// whole PR exists for — is NOT exercised here. It is exercised as a subprocess in
+// deployment-drift-script.test.mjs, because none of it is reachable through `evaluate()`.
+import { describe, it, expect } from "vitest";
+import { evaluate, minorGap, pgTimestampToIso, OK, DRIFT, UNKNOWN } from "../../../scripts/lib/drift-evaluate.mjs";
+
+const NOW = new Date("2026-08-16T18:00:00Z").getTime();
+const BUMP = "2026-08-16T17:00:00Z";
+const base = (over = {}) => ({
+  merged: "1.35.0",
+  published: "1.35.0",
+  bumpIso: BUMP,
+  expectedSchemaVersion: 8,
+  expectedDigest: "f63027fa",
+  boards: [],
+  ...over,
+});
+const run = (facts, opts = {}) => evaluate(facts, { nowMs: NOW, ...opts });
+const board = (over = {}) => ({
+  ref: "b1",
+  running: "1.35.0",
+  schemaVersion: 8,
+  digest: "f63027fa",
+  installedAt: "2026-08-16 17:30:00+00",
+  ...over,
+});
+
+describe("the happy path is genuinely reachable", () => {
+  it("is OK when everything agrees", () => {
+    const r = run(base({ boards: [board()] }));
+    expect(r.status).toBe(OK);
+  });
+});
+
+// Each of these returned `ok` + exit 0 in the first version. That was the defect.
+describe("UNKNOWN never collapses into OK", () => {
+  it("npm unreachable is UNKNOWN, not current", () => {
+    expect(run(base({ published: null })).status).toBe(UNKNOWN);
+  });
+
+  it("an unreadable board is UNKNOWN, not current", () => {
+    expect(run(base({ boards: [{ ref: "b1", error: "HTTP 401" }] })).status).toBe(UNKNOWN);
+  });
+
+  it("a missing credential is UNKNOWN, not current", () => {
+    expect(run(base({ boards: [{ ref: "b1", error: "no SUPABASE_ACCESS_TOKEN" }] })).status).toBe(UNKNOWN);
+  });
+
+  it("an unparseable install timestamp is UNKNOWN — the specific bug a seat found", () => {
+    const r = run(base({ boards: [board({ installedAt: "not-a-date" })] }));
+    expect(r.status).toBe(UNKNOWN);
+    expect(r.findings.some((f) => /unparseable/.test(f.msg))).toBe(true);
+  });
+
+  it("a missing install timestamp is UNKNOWN", () => {
+    expect(run(base({ boards: [board({ installedAt: null })] })).status).toBe(UNKNOWN);
+  });
+
+  it("no bump date (shallow clone) is UNKNOWN for the board leg", () => {
+    expect(run(base({ bumpIso: null, boards: [board()] })).status).toBe(UNKNOWN);
+  });
+
+  it("a major-version difference is UNKNOWN, not OK", () => {
+    expect(run(base({ published: "2.0.0" })).status).toBe(UNKNOWN);
+  });
+
+  it("a malformed merged version is UNKNOWN and stops there", () => {
+    const r = run(base({ merged: "not-a-version" }));
+    expect(r.status).toBe(UNKNOWN);
+  });
+
+  it("a board record with no digest is UNKNOWN — cannot confirm same bytes", () => {
+    expect(run(base({ boards: [board({ digest: null })] })).status).toBe(UNKNOWN);
+  });
+});
+
+describe("real drift is DRIFT", () => {
+  it("flags more unpublished versions than the threshold", () => {
+    expect(run(base({ merged: "1.42.0" })).status).toBe(DRIFT);
+  });
+
+  it("does NOT flag a small, fresh gap — a check that cries wolf gets ignored", () => {
+    expect(run(base({ merged: "1.36.0" })).status).toBe(OK);
+  });
+
+  it("flags a small gap that has gone stale by age", () => {
+    const old = new Date("2026-08-01T17:00:00Z").toISOString();
+    expect(run(base({ merged: "1.36.0", bumpIso: old })).status).toBe(DRIFT);
+  });
+
+  it("flags a registry AHEAD of the checkout", () => {
+    expect(run(base({ merged: "1.28.0", published: "1.35.0" })).status).toBe(DRIFT);
+  });
+
+  it("flags a board with NO install record — absent is not up to date", () => {
+    expect(run(base({ boards: [{ ref: "b1", running: null }] })).status).toBe(DRIFT);
+  });
+
+  it("flags a board behind main", () => {
+    expect(run(base({ boards: [board({ running: "1.28.0" })] })).status).toBe(DRIFT);
+  });
+
+  it("flags a record installed before the version it claims existed", () => {
+    const r = run(base({ boards: [board({ installedAt: "2026-07-15 02:57:23+00" })] }));
+    expect(r.status).toBe(DRIFT);
+    expect(r.findings.some((f) => /stale/.test(f.msg))).toBe(true);
+  });
+
+  it("flags a record whose schema_version disagrees with the manifest", () => {
+    expect(run(base({ boards: [board({ schemaVersion: 7 })] })).status).toBe(DRIFT);
+  });
+
+  it("flags a record whose digest disagrees with the manifest — different bytes", () => {
+    expect(run(base({ boards: [board({ digest: "deadbeef" })] })).status).toBe(DRIFT);
+  });
+
+  it("tolerates a minute of clock skew rather than crying stale", () => {
+    expect(run(base({ boards: [board({ installedAt: "2026-08-16 16:59:30+00" })] })).status).toBe(OK);
+  });
+});
+
+describe("pgTimestampToIso", () => {
+  it("parses the Postgres two-digit offset that plain Date() rejects", () => {
+    expect(pgTimestampToIso("2026-07-15 02:57:23+00")).toBe("2026-07-15T02:57:23+00:00");
+    expect(Number.isNaN(new Date("2026-07-15T02:57:23+00").getTime())).toBe(true);
+  });
+  it("keeps fractional seconds", () => {
+    expect(pgTimestampToIso("2026-08-16 17:17:00.04088+00")).toBe("2026-08-16T17:17:00.04088+00:00");
+  });
+  it("assumes UTC for a naive timestamp", () => {
+    expect(pgTimestampToIso("2026-08-16 17:17:00")).toBe("2026-08-16T17:17:00Z");
+  });
+  it("returns null for unparseable input — unknown, never fresh", () => {
+    for (const v of ["not-a-date", null, undefined, ""]) expect(pgTimestampToIso(v)).toBeNull();
+  });
+});
+
+describe("minorGap", () => {
+  it("counts unpublished versions", () => expect(minorGap("1.35.0", "1.28.0")).toBe(7));
+  it("is zero when equal", () => expect(minorGap("1.35.0", "1.35.0")).toBe(0));
+  it("goes negative when the registry is ahead", () => expect(minorGap("1.28.0", "1.35.0")).toBe(-7));
+  it("refuses across a major", () => expect(minorGap("2.0.0", "1.35.0")).toBeNull());
+  it("returns null rather than guessing", () => expect(minorGap("nope", "1.35.0")).toBeNull());
+});
+
+// ---------------------------------------------------------------------------
+// Second-round findings. Every case below reported OK in the first rewrite.
+// ---------------------------------------------------------------------------
+describe("second-round fail-open regressions", () => {
+  it("an unpublished gap with an undeterminable bump date is UNKNOWN, not OK", () => {
+    expect(run(base({ merged: "1.36.0", bumpIso: null })).status).toBe(UNKNOWN);
+  });
+
+  it("a board behind main with an undeterminable bump date is UNKNOWN, not OK", () => {
+    expect(run(base({ bumpIso: null, boards: [board({ running: "1.34.0" })] })).status).toBe(UNKNOWN);
+  });
+
+  it("missing manifest expectations make the consistency leg UNKNOWN, not a silent skip", () => {
+    // Three seats reproduced this: a corrupt manifest disabled the digest and
+    // schema_version comparisons while still printing "record consistent".
+    const r = run(base({ expectedDigest: null, expectedSchemaVersion: null, boards: [board({ digest: "deadbeef" })] }));
+    expect(r.status).toBe(UNKNOWN);
+    expect(r.findings.some((f) => /record consistent/.test(f.msg))).toBe(false);
+  });
+
+  it("a board record with no schema_version is UNKNOWN", () => {
+    expect(run(base({ boards: [board({ schemaVersion: null })] })).status).toBe(UNKNOWN);
+  });
+
+  it("a malformed version does not parse as its numeric prefix", () => {
+    expect(minorGap("1.35.0garbage", "1.35.0")).toBeNull();
+    expect(run(base({ published: "1.35.0garbage" })).status).toBe(UNKNOWN);
+  });
+
+  it("a published PATCH ahead is drift, not agreement", () => {
+    // minor-only comparison called 1.35.1 equal to 1.35.0 while the registry was ahead
+    expect(run(base({ published: "1.35.1" })).status).toBe(DRIFT);
+  });
+
+  it("non-finite thresholds refuse to evaluate rather than passing everything", () => {
+    expect(run(base({ merged: "1.58.0" }), { maxVersions: NaN }).status).toBe(UNKNOWN);
+    expect(run(base({ merged: "1.58.0" }), { maxDays: NaN }).status).toBe(UNKNOWN);
+  });
+});
+
+describe("status accumulation — previously unpinned", () => {
+  it("DRIFT outranks UNKNOWN when both are present", () => {
+    // A RANK swap survived the first suite because no case mixed the two.
+    const r = run(base({ published: null, boards: [board({ running: "1.20.0" })] }));
+    expect(r.findings.some((f) => f.level === UNKNOWN)).toBe(true);
+    expect(r.findings.some((f) => f.level === DRIFT)).toBe(true);
+    expect(r.status).toBe(DRIFT);
+  });
+
+  it("pins the exact threshold boundary", () => {
+    expect(run(base({ merged: "1.38.0" })).status).toBe(OK); // gap 3 == maxVersions
+    expect(run(base({ merged: "1.39.0" })).status).toBe(DRIFT); // gap 4 > maxVersions
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Branches a mutation must not survive.
+//
+// Each of the four below was measured UNPINNED: the mutation named in its comment was
+// applied to drift-evaluate.mjs and all 38 tests stayed green. A green suite is not
+// evidence; these exist so that each mutation reds a named assertion.
+// ---------------------------------------------------------------------------
+describe("branches a mutation must not survive", () => {
+  // Mutation: delete the `add(UNKNOWN, ...)` for an unparseable bumpIso (:100-102).
+  // No board, and merged === published, so this finding is the ONLY non-OK source —
+  // without it the status is OK.
+  it("an unparseable bump timestamp is UNKNOWN even when every other leg agrees", () => {
+    const r = run(base({ bumpIso: "not-a-date", boards: [] }));
+    expect(r.status).toBe(UNKNOWN);
+    expect(r.findings.some((f) => f.level === UNKNOWN && /version-bump timestamp is unparseable/.test(f.msg))).toBe(true);
+  });
+
+  // Mutation: change the board-leg `add(UNKNOWN, ...)` for an incomparable version to OK.
+  it("a board across a MAJOR from merged is UNKNOWN, never OK", () => {
+    const r = run(base({ boards: [board({ running: "2.0.0" })] }));
+    expect(r.status).toBe(UNKNOWN);
+    expect(r.findings.some((f) => f.level === UNKNOWN && /running 2\.0\.0 is not comparable/.test(f.msg))).toBe(true);
+  });
+
+  // Mutation: drop the early `return` after the malformed-merged UNKNOWN (:96). The
+  // existing "a malformed merged version is UNKNOWN and stops there" asserts only the
+  // status, which the mutation preserves — so it asserted the label, not the stopping.
+  it("a malformed merged version STOPS evaluation — exactly one finding, nothing else runs", () => {
+    const r = run(base({ merged: "1.x.0", published: "1.35.0", boards: [board(), board({ ref: "b2", digest: "deadbeef" })] }));
+    expect(r.status).toBe(UNKNOWN);
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].msg).toMatch(/cannot compare anything/);
+  });
+
+  // Mutation: force the behind-board outcome to DRIFT unconditionally (:158 as numbered
+  // before this block was added). One version behind, bumped an hour ago, is inside
+  // release cadence and must not fire.
+  //
+  // Double duty: the ancient `installedAt` here pins the STATED LIMIT that a behind
+  // board's staleness check does not run (see the LIMIT comment in drift-evaluate.mjs).
+  // If that limit is ever closed, this assertion reds and must be rewritten deliberately
+  // rather than the limit being closed by accident.
+  // Mutation: delete the `gap < 0` branch, restoring the fall-through. Reproduced by a
+  // seat: a board running 1.36.0 against merged 1.35.0 with a MATCHING digest reported
+  // status ok, exit 0, and a message asserting the record was consistent. The publish leg
+  // has always called this same relation DRIFT; the board leg did not.
+  it("a board AHEAD of merged is DRIFT even when its digest and schema_version match", () => {
+    const r = run(base({ boards: [board({ running: "1.36.0" })] })); // digest/schemaVersion match
+    expect(r.status).toBe(DRIFT);
+    expect(r.findings.some((f) => f.level === DRIFT && /is running 1\.36\.0, which is AHEAD of merged/.test(f.msg))).toBe(true);
+    // The old fall-through produced this message while returning ok. Its presence would
+    // mean the ahead board was evaluated as though it were current.
+    expect(r.findings.some((f) => /record consistent/.test(f.msg))).toBe(false);
+  });
+
+  it("a board AHEAD with a MISMATCHED digest is DRIFT for being ahead, not for the bytes", () => {
+    // The symmetric case. A board ahead SHOULD disagree with a manifest describing merged,
+    // so the honest single finding is the ahead-ness; "different bytes" would be noise
+    // dressed as a second defect.
+    const r = run(base({ boards: [board({ running: "1.36.0", digest: "deadbeef", schemaVersion: 9 })] }));
+    expect(r.status).toBe(DRIFT);
+    expect(r.findings.some((f) => f.level === DRIFT && /AHEAD of merged/.test(f.msg))).toBe(true);
+    expect(r.findings.some((f) => /different bytes/.test(f.msg))).toBe(false);
+  });
+
+  it("a board a PATCH ahead is DRIFT too — the half-step sign is classified", () => {
+    // minorGap returns ±0.5 for a patch difference; -0.5 took the same fall-through.
+    expect(run(base({ boards: [board({ running: "1.35.1" })] })).status).toBe(DRIFT);
+  });
+
+  it("a board 1 behind and fresh is OK even with an ancient install timestamp", () => {
+    const r = run(base({ boards: [board({ running: "1.34.0", installedAt: "2020-01-01 00:00:00+00" })] }));
+    expect(r.status).toBe(OK);
+    expect(r.findings.some((f) => f.level === OK && /is 1 schema version\(s\) behind main/.test(f.msg))).toBe(true);
+  });
+});

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 forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 = 127)', () => {
+  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 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 = 137)', () => {
     expect(manifest.migrationCount).toBe(manifest.migrations.length);
-    expect(manifest.migrationCount).toBe(127);
+    expect(manifest.migrationCount).toBe(137);
     // 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,
@@ -141,6 +141,87 @@ describe('manifest integrity', () => {
       // MBCONSENT-B(iii) (#109/#110 + the gating race): validate and mutate the SAME
       // row. The sink gains an optional row identity and event kind.
       '20260810000100_agent_board_consent_locking.sql',
+      // RECEIPTSUBJECTGATE (#287): a read receipt is a MEMO of access, never a SOURCE of it --
+      // mark_read requires the NAMED agent to pass the thread-access predicate, closing the
+      // route by which service_role could mint an inherit-thread grant for a third party. The
+      // predicate is parameterized (_agent_can_access_thread) and the current-agent form
+      // recomposed from it, so the disjunct set has ONE definition. The receipt grandfather is
+      // deliberately preserved and documented, not removed.
+      '20260912000100_agent_board_receipt_subject_gate.sql',
+      // CLAIMSUBJECTGATE (#291): a claim is a LOCK, never a KEY -- acquire_claim requires the
+      // NAMED agent to pass the thread-access predicate before a thread-bound claim is written,
+      // closing the sibling of the #287 mint on agent_board.claims (and, through the thread
+      // disjunct of _current_agent_can_access_task, on task access). The permanence of a
+      // released or expired claim is RATIFIED here rather than fixed, in comment on function
+      // and in specs/security.md, so a future reader cannot mistake it for an oversight.
+      '20260914000100_agent_board_claim_subject_gate.sql',
+      // TASKTHREADLOCKORDER (#281 R1): one total order for (threads, tasks) -- threads BEFORE
+      // tasks -- in append_task_event (an explicit `threads ... for key share` hoisted above the
+      // existing `tasks ... for update`, with a recheck of the pre-read thread_id) and in
+      // _upsert_delivery_recipient (the OBSGATE thread stamp hoisted above the
+      // delivery_recipients insert, whose FK takes KEY SHARE on tasks). Definition-only.
+      '20260913000100_agent_board_task_thread_lock_order.sql',
+      // FEDSESSIONIDENTITYGATE (#246): a federated human is returned only to the identity that
+      // OWNS it. The owner uid is sha256(issuer || '|' || subject), a concatenation with no
+      // length prefix and no escaping, so two distinct principals can derive the same uid --
+      // and the return path checked only `active` and `kind = 'human'`, neither of which says
+      // the row belongs to the caller. Both return sites now require the agent's stored
+      // metadata.federation issuer AND subject to equal the caller's verified pair: the
+      // idempotent branch and the unique_violation race handler, which returned an existing
+      // row with no comparison either. A missing stamp is a refusal (coalesce(..., false)),
+      // not a pass. The ambiguous DERIVATION is deliberately unchanged -- that is a separate
+      // migration with an auth.users.email re-key -- because this gate defeats the collision
+      // with the encoding still in place.
+      '20260915000100_agent_board_fedsession_stored_identity_gate.sql',
+      // FEDIDENTITYSLUG (#246): the (issuer, subject) -> owner slug derivation becomes ONE
+      // injective serialization, and the ambiguous one is dropped rather than kept beside it.
+      // `issuer || '|' || subject` has no length prefix and no escaping, so the pair is not
+      // recoverable from the preimage and two principals can derive one slug -- and the slug
+      // is not a label, it is the auth.users key _ensure_agent_auth_user builds the email
+      // from. All five live derivation sites now call agent_board._federated_identity_slug,
+      // which length-prefixes each component. NOT definition-only: the migration also
+      // BACKFILLS every existing federated owner across all four surfaces that carry the
+      // slug -- auth.users.email, raw_user_meta_data.slug, auth.identities, and the human
+      // agent's handle -- because re-deriving without re-keying the email orphans the owner
+      // (the #244 resumption lookup misses and the non-null owner conjunct fails). The owner
+      // uuid is unchanged, so no FK and no live session moves.
+      '20260916000100_agent_board_federated_identity_injective_slug.sql',
+      // #317 INVITENODOWNGRADE. `_upsert_board_membership_state` is the sole sink that writes
+      // membership_state, and it wrote p_membership_state unconditionally -- so an invite (or a
+      // join request) landing on an agent who is already `joined`/`subscribed` REPLACED active
+      // standing with the weaker offer state. Reproduced on production. Distinct from #109, which
+      // was a wrong-ROW defect fixed by p_membership_id targeting; this is the right row moved in
+      // the wrong DIRECTION. `invited`/`requested` are offers, so applying one to an existing
+      // membership is now a no-op on membership_state (not an exception -- invite is idempotent by
+      // design and raising would break callers that succeed today). Every other transition,
+      // including re-invite after `removed`, is unchanged. The sink also now emits the RESULTING
+      // ROW's state rather than the requested argument: before the guard the two could not
+      // differ, and after it a no-op offer would otherwise append `invite_offer -> invited` to
+      // the append-only ledger beside a row that says `joined` -- the same discipline
+      // _redeem_unbounded_invite_for_agent already follows.
+      '20260917000100_agent_board_invite_no_downgrade.sql',
+      // #310 SIGNEDWRITEFLAG. `get_bundle_compatibility` reported
+      // `signed_write_enforced: false` on a system that IS enforcing, because the predicate
+      // still encoded the model 20260718000800 deliberately abandoned: it asked whether
+      // `authenticated` can EXECUTE four raw write RPCs. There are SEVEN signed gateways, not
+      // four, and the send family is OVERLOADED, so the old hand list was wrong twice over.
+      // The flag now reads pg_proc rows for `signed\_%` and asks `has_function_privilege`
+      // (which resolves inherited and PUBLIC-default grants that `role_routine_grants`
+      // structurally cannot see -- the #302 fail-open shape and the #118 recreate class).
+      // Definition-only: CREATE OR REPLACE with the identical signature, so the ACL survives;
+      // grants and a COMMENT are restated in the same migration anyway.
+      '20260918000100_agent_board_signed_write_enforced_repoint.sql',
+      // #326 SIGNEDWRITEMODEL. `signed_write_enforced` has the right VALUE and the wrong
+      // NAME: it is called "signed write enforced" and it tests "the signed path is
+      // operator-only". A boolean cannot say which proposition it means, so a reader had to
+      // combine it with `installed_bundle_version` and a 1.37.0 boundary to decode it. Adds a
+      // self-describing `signed_write_model` sibling ('operator-only-gateway'). ADDITIVE: the
+      // client's runtime type guard requires three keys to be PRESENT, so dropping or
+      // re-pointing the boolean was not available -- the first breaks every deployed client's
+      // recognition of a HEALTHY response, the second is the permanently-lying instrument #310
+      // names. Definition-only: CREATE OR REPLACE with the identical signature, grants and
+      // COMMENT restated in the same migration.
+      '20260919000100_agent_board_signed_write_model_key.sql',
     ]) {
       expect(names.has(f)).toBe(true);
     }

package/tests/agent_board_atomic_fleet_onboarding.test.sql

@@ -110,12 +110,21 @@
 --     demonstrated silenced that way (#198). They are presence claims, so a
 --     comment can only make a MISSING construct look present -- the same
 --     fail-open direction, on weaker claims;
---   * the two catalog CLASS assertions at the end. The serialization one decides
---     serialized/UNSERIALIZED with `strpos(p.prosrc, '_lock_board_authority_ceiling')`
---     over RAW prosrc, so a reader that DROPS the lock while keeping a comment
---     naming it still prints "serialized" -- the dangerous direction. The
---     surface-set predicates that pick the second class's member functions are raw
---     for the same reason.
+--   * the ONE remaining deliberate raw read, added by message-board#277: the
+--     KNOWN-STALE record for set_board_authority_ceiling's inline every-reader
+--     claim. Its evidence IS a comment, so a stripped body cannot see it by
+--     construction. It is a PRESENCE claim, so the fail-open direction is "a
+--     comment makes a missing thing look present" -- which is exactly what it is
+--     asserting, deliberately.
+--
+-- CORRECTED BY message-board#277, because this paragraph was itself an example of
+-- the defect #277 fixes -- prose claiming what the code no longer does. It used to
+-- say the catalog CLASS assertions at the end decide serialized/UNSERIALIZED with
+-- `strpos(p.prosrc, …)` over RAW prosrc. They do not, and had not since #196/#199:
+-- the serialization state and the surface-set predicates all read
+-- agent_board_test.stripped_body(), and one surface predicate reads
+-- stripped_body(oid, true) because its marker is a string literal. Verified against
+-- the statements themselves, not against this list.
 -- All of it is inside exact-set or presence assertions that #196 Bucket A
 -- deliberately excluded; it belongs to the follow-up that closes Buckets B and C,
 -- together with the nesting hole in the strip described above.
@@ -123,7 +132,7 @@ create extension if not exists pgtap with schema extensions;
 set search_path = extensions, public, agent_board;
 
 begin;
-select plan(54);
+select plan(58);
 
 -- ---------------------------------------------------------------------------
 -- The stripped-body reader every positional assertion below uses is
@@ -491,33 +500,54 @@ select ok(
   'the ceiling setter holds the same lock before its owner gate and upsert [BACKSTOP: tests/isolation/specs/ceiling_setter_lock_before_upsert.spec]'
 );
 
+-- THE CEILING CLASSES, DERIVED ONCE (message-board#277). Both sides of this lock
+-- -- who READS the ceiling for authorization, and who WRITES it -- are needed by
+-- four assertions below, one of which compares them to the lock helper's own
+-- COMMENT. Written out four times they would be four things that can drift; the
+-- drift would show up as one of them failing, but only after someone read four
+-- copies to work out which was right. So the predicates live here, once.
+--
+-- CALL SHAPE for the serialization state, not strpos on a bare name: that is the
+-- dangerous direction -- a reader that DROPS the lock but keeps a variable named
+-- after it would still print "serialized".
+-- SCHEMA-QUALIFIED, because a bare-name anchor proves call SYNTAX, not callee
+-- IDENTITY: `\m_lock_board_authority_ceiling\s*\(` also matches
+-- `zz_other._lock_board_authority_ceiling(...)` (measured true). Every live call
+-- site in agent_board is `agent_board.`-qualified, so requiring the qualification
+-- costs nothing today and is fail-CLOSED if someone later writes an unqualified
+-- call (it reads as NOT calling). Overload count is pinned separately, so schema +
+-- name is the identity.
+--
+-- The WRITE predicate names the DML verb and the relation together rather than
+-- "mentions board_authority_ceilings", so _grant_within_ceiling -- which reads the
+-- table and is the reason the read class exists at all -- is not miscounted as a
+-- writer. It sees only STATIC SQL in the function's own body: a write built into an
+-- `execute` string is a literal and is stripped away, and a write performed by a
+-- TRIGGER or by a callee belongs to that object, not to this one. Same blindness
+-- the positional claims above carry and for the same reason; stated here so the
+-- class is not read as "every write to this table", which it is not.
+create temp table _ceiling_class as
+select 'agent_board.' || regexp_replace(p.oid::regprocedure::text, '^([^(]*\.)?', '') as ident,
+       p.proname::text as name,   -- text, not `name`: array_agg(name) has no is(name[], text[]) overload
+       (strpos(lower(agent_board_test.stripped_body(p.oid)), '_grant_within_ceiling') > 0) as is_reader,
+       (agent_board_test.stripped_body(p.oid) ~*
+          '(insert\s+into|update|delete\s+from|merge\s+into)\s+(only\s+)?(agent_board\.)?board_authority_ceilings\M') as is_writer,
+       (agent_board_test.stripped_body(p.oid) ~* '\magent_board\._lock_board_authority_ceiling\s*\(') as serialized
+  from pg_proc p
+  join pg_namespace n on n.oid = p.pronamespace
+ where n.nspname = 'agent_board';
+
 -- CLASS (catalog-derived, EC-4 form). Every agent_board function that reads the
 -- ceiling for authorization, enumerated from pg_proc — never from a list written
 -- here — each carrying its serialization state POSITIVELY. A new reader changes
 -- the array and NAMES ITSELF in the diff; a reader that is serialized without
--- being declared here also fails. The three UNSERIALIZED entries are the
--- knowingly-unfixed remainder of the class recorded in 20260901000110's header:
--- they carry the same absence race and are out of #186's scope.
+-- being declared here also fails. The two UNSERIALIZED entries are what remains of
+-- the knowingly-unfixed set recorded in 20260901000110's header (it recorded three;
+-- #276 retired one): they carry the same absence race and are out of #186's scope.
 select is( -- pgtap-allow-raise-checked: catalog read only; the RPC names below are string literals in the expected array, never invoked
-  (select array_agg(entry order by entry) from (
-     select 'agent_board.' || regexp_replace(p.oid::regprocedure::text, '^([^(]*\.)?', '') || ' => ' ||
-            -- CALL SHAPE, not strpos on a bare name: this is the dangerous
-            -- direction -- a reader that DROPS the lock but keeps a variable named
-            -- after it would still print "serialized".
-      -- SCHEMA-QUALIFIED, because a bare-name anchor proves call SYNTAX, not callee
-      -- IDENTITY: `\m_lock_board_authority_ceiling\s*\(` also matches
-      -- `zz_other._lock_board_authority_ceiling(...)` (measured true). Every live call
-      -- site in agent_board is `agent_board.`-qualified, so requiring the
-      -- qualification costs nothing today and is fail-CLOSED if someone later writes
-      -- an unqualified call (it reads as NOT calling). Overload count is pinned
-      -- separately, so schema + name is the identity.
-            case when agent_board_test.stripped_body(p.oid) ~* '\magent_board\._lock_board_authority_ceiling\s*\('
-                 then 'serialized' else 'UNSERIALIZED' end as entry
-       from pg_proc p
-       join pg_namespace n on n.oid = p.pronamespace
-      where n.nspname = 'agent_board'
-        and strpos(lower(agent_board_test.stripped_body(p.oid)), '_grant_within_ceiling') > 0
-   ) readers),
+  (select array_agg(ident || ' => ' || case when serialized then 'serialized' else 'UNSERIALIZED' end
+            order by ident || ' => ' || case when serialized then 'serialized' else 'UNSERIALIZED' end)
+     from _ceiling_class where is_reader),
   array[
     'agent_board._redeem_unbounded_invite_for_agent(text,uuid) => UNSERIALIZED',
     'agent_board.create_invite_link(uuid,text,text,integer,timestamp with time zone,uuid,jsonb) => UNSERIALIZED',
@@ -532,6 +562,91 @@ select is( -- pgtap-allow-raise-checked: catalog read only; the RPC names below
   'every ceiling-authorization reader in pg_proc is declared with its serialization state'
 );
 
+-- CLASS (catalog-derived, message-board#277). The WRITE side of the same lock,
+-- declared the same way. The helper's COMMENT makes a claim about writers as well
+-- as readers, and until now only ONE writer was checked -- by name, in the
+-- lock-before-upsert assertion above. A second writer could appear with no lock at
+-- all and nothing here would notice; the comment would still say every writer takes
+-- it. Now it names itself.
+select is( -- pgtap-allow-raise-checked: catalog read only; the RPC name below is a string literal in the expected array, never invoked
+  (select array_agg(ident || ' => ' || case when serialized then 'serialized' else 'UNSERIALIZED' end
+            order by ident || ' => ' || case when serialized then 'serialized' else 'UNSERIALIZED' end)
+     from _ceiling_class where is_writer),
+  array[
+    'agent_board.set_board_authority_ceiling(uuid,text,uuid) => serialized'
+  ]::text[],
+  'every function that WRITES board_authority_ceilings is declared with its serialization state'
+);
+
+-- The COMMENT on the lock helper is the most discoverable statement of intent about
+-- it -- it is attached to the lock itself -- and until #277 it claimed a property
+-- that the reader class above ACTIVELY REFUTED: "every RPC that writes the ceiling
+-- and every RPC that reads it for authorization takes this FIRST". Two of the four
+-- readers do not take it at all. Correcting the sentence would have fixed today and
+-- left the same rot mechanism in place: prose three files away from the assertion
+-- that knows the answer.
+--
+-- So the COMMENT now carries the two lists in a fixed machine-readable form and this
+-- assertion compares them, name for name and state for state, to the SAME
+-- catalog-derived classes the two assertions above declare. A reader or writer added,
+-- removed, or moved between serialized and UNSERIALIZED fails here as well, and the
+-- failure prints the disagreeing lists side by side.
+--
+-- FAIL-CLOSED ON A MANGLED BLOCK: an absent or malformed block makes substring()
+-- return NULL, which is coalesced to a sentinel that no catalog list can equal --
+-- never to the empty list, which is a real and different answer ('(none)').
+-- Deleting the block is therefore a failure, not a silent pass. Mutation-verified in
+-- all three directions (state flipped, name dropped, block deleted).
+select is(
+  (select array[
+     coalesce(string_agg(name, ', ' order by name) filter (where is_writer and serialized), '(none)'),
+     coalesce(string_agg(name, ', ' order by name) filter (where is_writer and not serialized), '(none)'),
+     coalesce(string_agg(name, ', ' order by name) filter (where is_reader and serialized), '(none)'),
+     coalesce(string_agg(name, ', ' order by name) filter (where is_reader and not serialized), '(none)')
+   ] from _ceiling_class),
+  (select array[
+     coalesce(substring(c from 'WRITERS\[serialized: ([^]]*)\]'), '(NO WRITERS BLOCK IN THE COMMENT)'),
+     coalesce(substring(c from 'WRITERS\[serialized: [^]]*\]\[UNSERIALIZED: ([^]]*)\]'), '(NO WRITERS UNSERIALIZED BLOCK IN THE COMMENT)'),
+     coalesce(substring(c from 'READERS\[serialized: ([^]]*)\]'), '(NO READERS BLOCK IN THE COMMENT)'),
+     coalesce(substring(c from 'READERS\[serialized: [^]]*\]\[UNSERIALIZED: ([^]]*)\]'), '(NO READERS UNSERIALIZED BLOCK IN THE COMMENT)')
+   ] from (select obj_description('agent_board._lock_board_authority_ceiling(uuid)'::regprocedure, 'pg_proc') as c) d),
+  'the ceiling lock COMMENT names exactly the catalog-derived writers and readers, with the same serialization state'
+);
+
+-- The COMMENT lists BARE NAMES (onboard_federated_fleet_agent alone has 23
+-- parameters; a signature list would be unreadable and would rot on any signature
+-- change). A bare name is an identity only while no two members of these classes
+-- share one -- otherwise the comparison above would accept the wrong overload's
+-- state. Catalog-derived, so a colliding overload fails here and prints its name.
+select is(
+  (select array_agg(name order by name) from (
+     select name from _ceiling_class where is_reader or is_writer group by name having count(*) > 1
+   ) dupes),
+  null::text[],
+  'no two ceiling readers/writers share a bare name, so the COMMENT may identify them by name'
+);
+
+-- KNOWN STALE, RECORDED POSITIVELY (message-board#277). The same overclaim the
+-- helper's COMMENT carried is ALSO an inline comment inside
+-- set_board_authority_ceiling's live body: "Same board-keyed advisory lock every
+-- ceiling READER for authorization takes." It is false in the same way and for the
+-- same two readers. It is NOT corrected in #277 because correcting prose inside a
+-- body means recreating a SECURITY DEFINER function -- a much wider blast radius
+-- than a `comment on function`, and a decision to take deliberately rather than to
+-- smuggle into a comment fix.
+--
+-- Asserted POSITIVELY rather than left as a note in a PR body (CLAUDE.md rule 1: an
+-- exemption states its claim, never relies on absence). WHEN YOU FIX IT: this
+-- assertion fails and names itself -- delete it, and re-derive the COMMENT's blocks
+-- from the catalog while you are there. Raw prosrc on purpose: the evidence IS a
+-- comment, so the stripped body cannot see it (presence claim, not positional).
+select ok(
+  (select p.prosrc from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board' and p.proname = 'set_board_authority_ceiling')
+    like '%Same board-keyed advisory lock every ceiling READER for authorization takes%',
+  'KNOWN STALE (#277): set_board_authority_ceiling still carries the refuted every-reader claim inline -- pinned here so fixing it cannot go unnoticed'
+);
+
 -- CLASS (catalog-derived). Every function that touches this migration set's own
 -- surface — the bounded-invite table, the human revocation registry, the fleet
 -- revocation ledger, or the ceiling lock — with its exact non-owner EXECUTE