@consiliency/agent-board-schema

Canonical, immutable, exact-pinnable agent_board schema bundle. Message Board owns the schema bytes, ordering, compatibility rules, and the deterministic adopter tooling; adopters (e.g. the Portal Supabase project) pin an exact release and materialize it — they do not author agent_board DDL.

What's in the bundle

• migrations/ — the ordered, immutable SQL union (frozen baseline + lane migrations + the Message Board-owned endpoint compatibility migration).
• schema-manifest.json — package version, agent_board.schema_version, ordered migration IDs, per-file SHA-256, aggregate digest, source refs + merge base, minimum client version, PostgreSQL/Supabase assumptions, and external dependencies.
• provenance.json — per-file origin/source-ref/digest for every migration + test.
• tests/ — the pgTAP suite + tests/fixtures/ (adopter-base + test/operator prerequisites).
• fixtures/ — plan/check history snapshots.

Adopter CLI (the only supported path)

# Write the exact pinned migrations into an adopter workspace (original IDs,
# exact bytes, provenance marker, receipt). Refuses to overwrite manual edits.
agent-board-schema materialize --target <adopter>/supabase/migrations

# Read-only posture against a supplied migration-history snapshot.
agent-board-schema plan  --history history.json
agent-board-schema check --history history.json     # exit 0 exact / 10 behind / 11 ahead / 12 divergent / 14 collision

# Self-contained smoke: byte-exact + idempotent materialize.
agent-board-schema materialize --check-smoke

agent-board-schema manifest    # print the compatibility manifest
agent-board-schema version

Version collisions — build history.json from real rows, not from versions

Supabase keys supabase_migrations.schema_migrations on the 14-digit version prefix alone, not the name. If you have independently authored a migration at a version this bundle also uses, your database has that version recorded under your 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.

This is not hypothetical. It happened at 20260809000100, where an adopter's reconcile_panel_schema_drift occupied the version used by agent_board_consent_gating (message-board#217). 50 of this bundle's migrations share the 000100 suffix, so if you also mint fixed-suffix timestamps the odds are far above random.

Build the history from version and name, so check can see it. Let Postgres do the encoding — a shell pipeline breaks on a name containing : or a quote, and an empty result set produces a file that will not parse:

psql "$DATABASE_URL" -At -c \
  "select coalesce(json_agg(json_build_object('id', version || '_' || coalesce(name, ''))), '[]'::json)
     from supabase_migrations.schema_migrations" \
  | sed 's/^/{"applied":/; s/$/}/' > history.json

agent-board-schema check --history history.json

A history built from versions alone cannot detect this — matching on the version prefix is precisely the check that reports success on an affected database.

check exits 14 and names both sides:

collision @20260809000100:
  expected    20260809000100_agent_board_consent_gating
  recorded as 20260809000100_reconcile_panel_schema_drift

Exit 14 is deliberately not behind (10). "Behind" invites the fix of applying again, which is the no-op that leaves the database wrong.

Single-version discriminator, if you only want to check the known case:

select name from supabase_migrations.schema_migrations where version = '20260809000100';
-- agent_board_consent_gating -> healthy
-- anything else              -> this database skipped the bundle migration

Remediation. From bundle version 1.24.0 you do not need one: 20260905000100_agent_board_consent_gating_reconcile re-applies the only function left stale by that skip (join_board — the other two are superseded by later migrations that carry the gating forward). It is byte-identical on a healthy database and self-healing on an affected one, with no supabase migration repair.

A healed database stops reporting collision, even though the row is permanent. schema_migrations keys on version, its primary key, so the adopter's row at a collided version can never be removed. check therefore reports on whether the remediating migration is applied, not on whether the row exists — otherwise a database that had done everything right would gate red forever, and an adopter trained to ignore exit 14 would stop seeing genuine behind and divergent states too. A remediated collision is reported under collisionsRemediated and both halves of the pair are removed from the counts, so a healed database reports exact / exit 0. Removing them is the whole point: the bundle's migration can never be applied there (its version is taken) and your row can never be removed, so left in they would report behind forever — a different permanent red than the one being fixed.

A row whose name is NULL is treated as indeterminate, not as a collision: it carries no name to tell apart from the bundle's own migration at that version. The same applies to a history built from bare version strings.

For a collision at any other version there is no declared healer, so check keeps reporting it and the fix is a migration repair on your side.

After applying the materialized migrations, the adopter records the install so the authenticated compatibility RPC reports live:

select agent_board.record_bundle_installation(
  '<packageVersion>', '<bundleDigest>', <schemaVersion>, '<sourceCommit>', '<receiptId>'
);
select agent_board.get_bundle_compatibility();  -- authenticated health, no secrets

Rules

• Released migration bytes are immutable. Corrections are forward-only new migrations with new IDs and tests — never edits to shipped SQL.
• SemVer covers SQL, manifest schema, and the materialize/plan/check command/argument/output/exit-code contracts.
• Materialization never mutates database history directly; the adopter operator applies it via the Supabase CLI.