@consiliency/agent-board-schema 1.22.0 → 1.24.0

package/src/index.js

@@ -39,6 +39,26 @@ export function loadOrderedMigrations() {
 
 // Parse a supplied migration-history snapshot: an array of { id/version,
 // sha256? } (applied migrations), or a plain array of version-id strings.
+// Collisions this bundle can HEAL, and the migration that heals each one.
+//
+// A version collision is a PERMANENT fact about a database: Supabase's
+// schema_migrations has `version` as its primary key, so an adopter's row at a
+// bundle migration's version never disappears. Reporting `collision` on the
+// mere presence of that row would therefore fail a fully-remediated database
+// FOREVER, and an adopter forced to ignore exit 14 also stops seeing genuine
+// `behind` and `divergent` states -- strictly worse than the problem it warns
+// about. So a collision whose remediating migration is applied is reported as
+// remediated and does not drive the posture.
+//
+// This map is a DECLARATION, not an enumeration: nothing in the catalog can
+// derive "which migration heals which", so it is stated here and asserted in
+// the tests -- both ids must exist in the bundle, and the healer must actually
+// restate the skipped migration's function body.
+export const COLLISION_REMEDIATIONS = Object.freeze({
+  '20260809000100_agent_board_consent_gating':
+    '20260905000100_agent_board_consent_gating_reconcile',
+});
+
 export function normalizeHistory(history) {
   const rows = Array.isArray(history) ? history : history?.applied ?? [];
   const map = new Map();

package/src/plan.js

@@ -4,7 +4,7 @@
 // history entries the adopter has that the bundle does not (ahead). Never
 // touches the database.
 
-import { loadOrderedMigrations, normalizeHistory } from './index.js';
+import { COLLISION_REMEDIATIONS, loadOrderedMigrations, normalizeHistory } from './index.js';
 
 export function plan(history) {
   const migrations = loadOrderedMigrations();
@@ -21,6 +21,75 @@ export function plan(history) {
 
   const ahead = [...applied.keys()].filter((id) => !bundleIds.has(id));
 
+  // VERSION COLLISIONS (message-board#217). Supabase keys
+  // supabase_migrations.schema_migrations on the 14-digit VERSION PREFIX alone,
+  // not the name. So an adopter who independently authored a migration at the
+  // same version has that version recorded under THEIR name, and the bundle's
+  // migration is skipped silently -- no error, and schema_version still reports
+  // the bundle's number, so the deploy looks successful.
+  //
+  // Such a database already shows up here as one `pending` plus one `ahead`, but
+  // that pair reads like a malformed history file rather than a skipped
+  // migration, and the natural reading ("we applied it, the tool just cannot see
+  // the digest") is the wrong one. Naming the collision explicitly is the
+  // difference between a puzzle and an instruction.
+  const versionOf = (id) => String(id).split('_')[0];
+  const aheadByVersion = new Map();
+  for (const id of ahead) {
+    const v = versionOf(id);
+    if (!aheadByVersion.has(v)) aheadByVersion.set(v, []);
+    aheadByVersion.get(v).push(id);
+  }
+  const allCollisions = perId
+    .filter((r) => r.action === 'pending')
+    .flatMap((r) => (aheadByVersion.get(versionOf(r.id)) ?? [])
+      // An ahead id with no NAME carries no evidence: it cannot be distinguished
+      // from the bundle's own migration at that version. Two shapes reach here --
+      // a bare version (normalizeHistory accepts plain version strings) and
+      // `<version>_` from a row whose `name` is NULL, which schema_migrations
+      // permits and the documented psql recipe renders exactly that way. A
+      // substring test for '_' admits the second and invents a collision from a
+      // legitimate history. Require an actual name.
+      .filter((recordedAs) => String(recordedAs).slice(versionOf(recordedAs).length + 1).length > 0)
+      .map((recordedAs) => ({
+        version: versionOf(r.id),
+        expected: r.id,
+        recordedAs,
+        remediatedBy: COLLISION_REMEDIATIONS[r.id] ?? null,
+      })));
+
+  // A collision is LIVE only while its healer is unapplied. Once healed the row
+  // remains in schema_migrations forever, but the DDL is present, so the
+  // database is correct and must be allowed to report a clean posture.
+  // The healer must be applied AND not divergent. A divergent digest means the
+  // database applied SOMETHING under that id which is not what this bundle ships,
+  // so nothing here can claim the skipped DDL was restored -- and claiming it
+  // would be the same false-success the collision detector exists to prevent.
+  // An UNKNOWN digest is not divergence: histories without digests are a
+  // supported shape, and demanding one would strand those adopters in the same
+  // permanent red this design just removed.
+  const healerDivergent = new Map(
+    perId.filter((r) => r.action === 'applied-divergent').map((r) => [r.id, true]),
+  );
+  const remediates = (c) =>
+    c.remediatedBy != null && applied.has(c.remediatedBy) && !healerDivergent.has(c.remediatedBy);
+  const collisions = allCollisions.filter((c) => !remediates(c));
+  const collisionsRemediated = allCollisions.filter(remediates);
+
+  // A remediated collision must stop affecting the posture ENTIRELY, not merely
+  // stop being called a collision. Both halves of the pair are permanent: the
+  // bundle's migration can never be applied on that database (its version is
+  // taken) so it would count `pending` forever, and the adopter's row can never
+  // be removed so it would count `ahead` forever. Left in, they gate the healed
+  // database at `behind`/10 in perpetuity -- a different permanent red than the
+  // one just fixed, which is why "not collision" was too weak a claim to make.
+  const remediatedExpected = new Set(collisionsRemediated.map((c) => c.expected));
+  const remediatedRecordedAs = new Set(collisionsRemediated.map((c) => c.recordedAs));
+  for (const r of perId) {
+    if (remediatedExpected.has(r.id) && r.action === 'pending') r.action = 'collision-remediated';
+  }
+  const effectiveAhead = ahead.filter((id) => !remediatedRecordedAs.has(id));
+
   const counts = perId.reduce((acc, r) => {
     acc[r.action] = (acc[r.action] || 0) + 1;
     return acc;
@@ -29,16 +98,21 @@ export function plan(history) {
   const divergent = perId.filter((r) => r.action === 'applied-divergent').length;
   const pending = perId.filter((r) => r.action === 'pending').length;
   let posture;
-  if (divergent > 0) posture = 'divergent';
-  else if (ahead.length > 0 && pending === 0) posture = 'ahead';
+  // Collision outranks every other posture: it is the only one where the
+  // database is silently missing bundle DDL while reporting success.
+  if (collisions.length > 0) posture = 'collision';
+  else if (divergent > 0) posture = 'divergent';
+  else if (effectiveAhead.length > 0 && pending === 0) posture = 'ahead';
   else if (pending > 0) posture = 'behind';
   else posture = 'exact';
 
   return {
     schema: 'agent_board_plan.v1',
     posture,
-    counts: { ...counts, ahead: ahead.length },
-    ahead,
+    counts: { ...counts, ahead: effectiveAhead.length, collision: collisions.length, collisionRemediated: collisionsRemediated.length },
+    ahead: effectiveAhead,
+    collisions,
+    collisionsRemediated,
     perId,
   };
 }

package/src/tooling.test.mjs

@@ -5,7 +5,8 @@ import { join } from 'node:path';
 import { loadManifest, loadOrderedMigrations, sha256 } from './index.js';
 import { materialize } from './materialize.js';
 import { plan } from './plan.js';
-import { check, EXIT } from './check.js';
+import { check, EXIT, POSTURE_ACTIONS } from './check.js';
+import { COLLISION_REMEDIATIONS } from './index.js';
 
 const manifest = loadManifest();
 const ordered = loadOrderedMigrations();
@@ -37,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 forward migrations (migrationCount = prior 112 + 1 = 113)', () => {
+  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 forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 + 1 = 123)', () => {
     expect(manifest.migrationCount).toBe(manifest.migrations.length);
-    expect(manifest.migrationCount).toBe(113);
+    expect(manifest.migrationCount).toBe(123);
     // 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,
@@ -199,7 +200,239 @@ describe('plan / check postures + exit codes (SemVer contract)', () => {
     expect(check({ applied }).exitCode).toBe(11);
   });
   it('exit-code map is a frozen SemVer surface', () => {
-    expect(EXIT).toEqual({ exact: 0, behind: 10, ahead: 11, divergent: 12, error: 13 });
+    expect(EXIT).toEqual({ exact: 0, behind: 10, ahead: 11, divergent: 12, error: 13, collision: 14 });
+  });
+
+  // VERSION COLLISION (message-board#217). Supabase keys schema_migrations on the
+  // 14-digit version prefix alone, so an adopter migration authored at a bundle
+  // migration's version makes the bundle's file skip SILENTLY -- no error, and
+  // schema_version still reports the bundle's number. The reported case is real:
+  // consiliency-portal recorded 20260809000100 as reconcile_panel_schema_drift.
+  // The adopter's own migration occupies the bundle's version, so the bundle's
+  // file was skipped. Two DISTINCT states matter, and conflating them is the
+  // defect a review seat caught: the collision ROW is permanent (Supabase keys
+  // schema_migrations on version, which is its primary key), so reporting on the
+  // row alone would fail a fully-healed database forever -- and an adopter forced
+  // to ignore exit 14 stops seeing genuine behind/divergent states too.
+  const portalHistory = (opts = {}) => ({
+    applied: [
+      ...ordered
+        .filter((m) => m.id !== '20260809000100_agent_board_consent_gating')
+        .filter((m) => opts.healed || m.id !== '20260905000100_agent_board_consent_gating_reconcile')
+        .map((m) => ({ id: m.id, sha256: m.sha256 })),
+      { id: '20260809000100_reconcile_panel_schema_drift', sha256: 'aa' },
+    ],
+  });
+
+  it('collision when an adopter migration occupies a bundle version and is unhealed', () => {
+    const c = check(portalHistory());
+    expect(c.posture).toBe('collision');
+    expect(c.exitCode).toBe(14);
+  });
+
+  it('collision names BOTH sides, so the report is an instruction not a puzzle', () => {
+    expect(plan(portalHistory()).collisions).toEqual([
+      {
+        version: '20260809000100',
+        expected: '20260809000100_agent_board_consent_gating',
+        recordedAs: '20260809000100_reconcile_panel_schema_drift',
+        remediatedBy: '20260905000100_agent_board_consent_gating_reconcile',
+      },
+    ]);
+  });
+
+  it('collision outranks behind — "behind" invites re-applying, which is the no-op that leaves the DB wrong', () => {
+    const p = plan(portalHistory());
+    expect(p.perId.filter((r) => r.action === 'pending').map((r) => r.id)).toContain(
+      '20260809000100_agent_board_consent_gating',
+    );
+    expect(p.posture).toBe('collision');
+  });
+
+  it('a HEALED database reports exact/0 — not merely "not collision"', () => {
+    // Asserting "not collision / not 14" was too weak and a review seat broke it:
+    // both halves of a remediated pair are PERMANENT (the bundle migration can
+    // never be applied on that database because its version is taken, and the
+    // adopter's row can never be removed), so leaving them in the counts gated
+    // the healed database at behind/10 forever — a different permanent red than
+    // the one being fixed. The claim is exact/0, so that is what is asserted.
+    const p = plan(portalHistory({ healed: true }));
+    expect(p.collisions).toEqual([]);
+    expect(p.collisionsRemediated.map((c) => c.expected)).toEqual([
+      '20260809000100_agent_board_consent_gating',
+    ]);
+    expect(p.counts.pending ?? 0).toBe(0);
+    expect(p.ahead).toEqual([]);
+    expect(p.posture).toBe('exact');
+    expect(check(portalHistory({ healed: true })).exitCode).toBe(0);
+  });
+
+  it('a NULL migration name is indeterminate, not a collision', () => {
+    // schema_migrations.name is nullable, and the documented psql recipe renders
+    // such a row as `<version>_`. A substring test for '_' called that a named
+    // row and invented a collision from a legitimate history.
+    const applied = [
+      ...ordered
+        .filter((m) => m.id !== '20260809000100_agent_board_consent_gating')
+        .map((m) => ({ id: m.id, sha256: m.sha256 })),
+      { id: '20260809000100_', sha256: 'aa' },
+    ];
+    const p = plan({ applied });
+    expect(p.collisions).toEqual([]);
+    expect(check({ applied }).exitCode).toBe(10); // behind, which is true: the DDL is absent
+  });
+
+  it('a DIVERGENT healer does not remediate — it is not the migration we shipped', () => {
+    // The database applied something under the healer's id that is not this
+    // bundle's bytes, so nothing here can claim the skipped DDL was restored.
+    // Posture already goes divergent, but reporting the collision as REMEDIATED
+    // would be the same false-success the detector exists to prevent.
+    const healer = '20260905000100_agent_board_consent_gating_reconcile';
+    const applied = [
+      ...ordered
+        .filter((m) => m.id !== '20260809000100_agent_board_consent_gating')
+        .map((m) => ({ id: m.id, sha256: m.id === healer ? 'deadbeef' : m.sha256 })),
+      { id: '20260809000100_reconcile_panel_schema_drift', sha256: 'aa' },
+    ];
+    const p = plan({ applied });
+    expect(p.collisionsRemediated).toEqual([]);
+    expect(p.collisions).toHaveLength(1);
+    expect(p.posture).toBe('collision');
+  });
+
+  it('an UNKNOWN healer digest still remediates — digest-less histories are supported', () => {
+    // normalizeHistory accepts entries without a digest. Requiring one would
+    // strand those adopters in the permanent red this design removes.
+    const applied = [
+      ...ordered.filter((m) => m.id !== '20260809000100_agent_board_consent_gating').map((m) => m.id),
+      '20260809000100_reconcile_panel_schema_drift',
+    ];
+    const p = plan({ applied });
+    expect(p.collisionsRemediated).toHaveLength(1);
+    expect(p.collisions).toEqual([]);
+  });
+
+  it('the healer being present is what clears it — not merely being declared', () => {
+    // Same declaration, healer unapplied: still live. Without this the previous
+    // test would pass on a map lookup rather than on the database's actual state.
+    expect(plan(portalHistory()).collisionsRemediated).toEqual([]);
+    expect(plan(portalHistory()).collisions).toHaveLength(1);
+  });
+
+  it('a bare-version history is indeterminate, not 123 collisions', () => {
+    // normalizeHistory accepts plain version strings. Such an entry carries no
+    // name, so it cannot be told apart from the bundle's own migration at that
+    // version — reporting it as a collision turns a supported input shape into a
+    // wall of false positives.
+    const p = plan({ applied: ordered.map((m) => m.id.split('_')[0]) });
+    expect(p.collisions).toEqual([]);
+  });
+
+  it('an unrelated adopter migration is NOT a collision, even with a bundle migration pending', () => {
+    // The history MUST have something pending as well as something ahead. A first
+    // draft of this test used an exact history plus one extra entry, and a mutation
+    // that reported every ahead entry as a collision SURVIVED it: with nothing
+    // pending there is no cross-product to over-report, so the assertion passed
+    // while checking nothing. A negative assertion driven by a clean input proves
+    // nothing (CLAUDE.md rule 2).
+    const applied = [
+      ...ordered
+        .filter((m) => m.id !== '20260809000100_agent_board_consent_gating')
+        .map((m) => ({ id: m.id, sha256: m.sha256 })),
+      { id: '99999999999999_extra', sha256: 'ff' },
+    ];
+    const p = plan({ applied });
+    expect(p.perId.some((r) => r.action === 'pending')).toBe(true); // the input is not clean
+    expect(p.ahead).toContain('99999999999999_extra');
+    expect(p.collisions).toEqual([]);
+    expect(p.posture).toBe('behind');
+  });
+});
+
+// OPERATOR GUIDANCE. Checks EXIT and POSTURE_ACTIONS agree with each other.
+//
+// This is NOT the completeness guard, and an earlier version of this comment
+// claimed it was. EXIT is a SECOND hand list, not the catalog: a posture added to
+// plan() without an EXIT entry passes everything here, falls through check()'s
+// `EXIT[p.posture] ?? EXIT.error` to exit 13, and prints no action. The real
+// catalog is the set of values plan() assigns, and scripts/check-posture-consumers.mjs
+// reads it from there -- and also holds the live-drift consumer to using
+// POSTURE_ACTIONS, which no test in this package can see. That script runs in
+// `schema:verify`. What follows is the in-package half: the two tables stay
+// consistent, and the collision action never tells an operator to re-apply.
+describe('every posture has operator guidance', () => {
+  const postures = Object.keys(EXIT).filter((k) => k !== 'error');
+
+  it('EXIT and POSTURE_ACTIONS cover the same postures', () => {
+    expect(Object.keys(POSTURE_ACTIONS).sort()).toEqual(postures.sort());
+  });
+
+  it('every non-exact posture has a non-empty action', () => {
+    for (const posture of postures) {
+      if (posture === 'exact') {
+        expect(POSTURE_ACTIONS.exact).toBeNull(); // nothing to do is not a missing action
+        continue;
+      }
+      expect(typeof POSTURE_ACTIONS[posture]).toBe('string');
+      expect(POSTURE_ACTIONS[posture].length).toBeGreaterThan(20);
+    }
+  });
+
+  it("the collision action does NOT tell an operator to re-apply", () => {
+    // Re-applying is the no-op that leaves the database wrong: the version is taken.
+    expect(POSTURE_ACTIONS.collision).toMatch(/no-op|not simply re-apply|Do NOT/i);
+  });
+});
+
+// COLLISION REMEDIATION (message-board#217). The reconcile migration's whole
+// no-op-on-a-healthy-database property rests on its join_board body being
+// byte-identical to the one in the migration an affected database skipped. The
+// PR asserted that in prose and nothing checked it -- the exact shape this repo
+// keeps getting caught by. The digest tests freeze each file's bytes, which is
+// not the same claim: two files can both be frozen and still differ.
+describe('collision remediation is real, not merely declared', () => {
+  const read = (id) =>
+    readFileSync(new URL(`../migrations/${id}.sql`, import.meta.url), 'utf8');
+  const joinBoardBlock = (sql) => {
+    const start = sql.search(/create or replace function agent_board\.join_board\b/i);
+    const rest = sql.slice(start + 10);
+    const next = rest.search(/create or replace function agent_board\./i);
+    return (next === -1 ? rest : rest.slice(0, next)).trimEnd();
+  };
+
+  it('every declared remediation names migrations that exist in the bundle', () => {
+    const ids = new Set(ordered.map((m) => m.id));
+    for (const [skipped, healer] of Object.entries(COLLISION_REMEDIATIONS)) {
+      expect(ids.has(skipped)).toBe(true);
+      expect(ids.has(healer)).toBe(true);
+      // The healer must come LATER, or it cannot run after the skip.
+      expect(healer > skipped).toBe(true);
+    }
+  });
+
+  it('the healer restates the skipped function BYTE-IDENTICALLY, so a healthy DB is a true no-op', () => {
+    const skipped = joinBoardBlock(read('20260809000100_agent_board_consent_gating'));
+    const healer = joinBoardBlock(read('20260905000100_agent_board_consent_gating_reconcile'));
+    expect(healer.length).toBeGreaterThan(1000);
+    expect(healer).toBe(skipped);
+  });
+
+  it('the healer touches ONLY the stale function, so it cannot clobber a later definition', () => {
+    // resolve_board_request and update_board_membership are superseded by
+    // 20260819000100 and 20260813000100. Restating them here would re-apply the
+    // older bodies over the newer ones on every healthy database.
+    const sql = read('20260905000100_agent_board_consent_gating_reconcile');
+    const defined = [...sql.matchAll(/create or replace function agent_board\.(\w+)/gi)].map((m) => m[1]);
+    expect(defined).toEqual(['join_board']);
+  });
+
+  it('the healer adds no grant, revoke or comment — create-or-replace preserves the ACL', () => {
+    const sql = read('20260905000100_agent_board_consent_gating_reconcile')
+      .split('\n').filter((l) => !l.trimStart().startsWith('--')).join('\n');
+    expect(sql).not.toMatch(/\bgrant\b/i);
+    expect(sql).not.toMatch(/\brevoke\b/i);
+    expect(sql).not.toMatch(/comment\s+on/i);
+    expect(sql).not.toMatch(/drop\s+function/i);
   });
 });