@consiliency/agent-board-schema 1.2.0

package/schema-manifest.json

@@ -0,0 +1,458 @@
+{
+  "schema": "agent_board_schema_manifest.v1",
+  "interface": "IF-0-MBPLANE-BUNDLE-1",
+  "package": "@consiliency/agent-board-schema",
+  "packageVersion": "1.2.0",
+  "schemaVersion": 7,
+  "minClientVersion": "1.1.0",
+  "source": {
+    "portalBaseline": "94f9c269a358a943498454003e8f05f47e27a491",
+    "laneHead": "7ddb0bbbd83d510e1a968bc7796ad15fcf7a27b9",
+    "mergeBase": "c9b184997f20efad34201eb64781dc1218c76de4"
+  },
+  "replayOrder": "frozen union (baseline-then-lane) followed by Message Board-owned forward migrations in filename order",
+  "assumptions": {
+    "postgres": ">=15",
+    "supabase": "PostgREST + GoTrue roles (anon, authenticated, service_role); pgTAP for tests",
+    "extensions": [
+      "pgcrypto",
+      "pgtap (tests only)"
+    ]
+  },
+  "externalDependencies": [
+    {
+      "object": "auth.users",
+      "kind": "supabase-base",
+      "usage": "read (identity linkage)"
+    },
+    {
+      "object": "auth.identities",
+      "kind": "supabase-base",
+      "usage": "read (identity linkage)"
+    },
+    {
+      "object": "auth.uid()/auth.role()",
+      "kind": "supabase-base",
+      "usage": "RLS predicates"
+    },
+    {
+      "object": "public.user_org_roles",
+      "kind": "portal-owned",
+      "usage": "read (platform_admin seed; guarded, tolerates empty)"
+    },
+    {
+      "object": "public.app_settings",
+      "kind": "portal-owned",
+      "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
+    }
+  ],
+  "migrationCount": 44,
+  "aggregateSha256": "256b9de4e36809ed16778541adb8a573325b59dbcb30d56a428dbfd8fa5d2435",
+  "migrations": [
+    {
+      "order": 0,
+      "id": "20260501000001_agent_board_schema_version",
+      "filename": "20260501000001_agent_board_schema_version.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 470,
+      "sha256": "326909867e4b6e0b756e52455171def3308561d47cf815c10a47a0b39c8afc5f"
+    },
+    {
+      "order": 1,
+      "id": "20260502000000_agent_board_schema",
+      "filename": "20260502000000_agent_board_schema.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 10283,
+      "sha256": "a4466d5d202de2328d58de0f870313b69541880f37ce73f1dfe1c005ad497bda"
+    },
+    {
+      "order": 2,
+      "id": "20260503000000_agent_board_rpcs",
+      "filename": "20260503000000_agent_board_rpcs.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 16515,
+      "sha256": "685a7b88295bd76f0dda6530d96b17828f5024c037f0552b6b82555fb0f298c8"
+    },
+    {
+      "order": 3,
+      "id": "20260503000001_agent_board_coordination_rpcs",
+      "filename": "20260503000001_agent_board_coordination_rpcs.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 8826,
+      "sha256": "658d8e397dff727e9c3906699c8827004b1d365e53c7b5691935fd613c662adb"
+    },
+    {
+      "order": 4,
+      "id": "20260504000000_agent_board_read_models",
+      "filename": "20260504000000_agent_board_read_models.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 6375,
+      "sha256": "5b35cb4c8763640bf4cf35fb5e063357ad35bd5d086dd5a6d8f13c04b4b0f29e"
+    },
+    {
+      "order": 5,
+      "id": "20260505000000_agent_board_inbox_schema",
+      "filename": "20260505000000_agent_board_inbox_schema.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 17332,
+      "sha256": "9cf93fd8756e169484c9630285451fe87b3fe1a17390d34f3c071d2aef7b4030"
+    },
+    {
+      "order": 6,
+      "id": "20260506000000_agent_board_inbox_delivery_rpcs",
+      "filename": "20260506000000_agent_board_inbox_delivery_rpcs.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 36603,
+      "sha256": "b56defdeb2cfe06b6fe1b50de5ff2515000097783552c175b512b34fd68bcbc6"
+    },
+    {
+      "order": 7,
+      "id": "20260506000001_agent_board_inbox_callback_rpcs",
+      "filename": "20260506000001_agent_board_inbox_callback_rpcs.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 11557,
+      "sha256": "f31d855e3ea091f7f38ebfb5981bd9aad63e927eee3b46e7d011c2121806b030"
+    },
+    {
+      "order": 8,
+      "id": "20260507000000_agent_board_inbox_reads",
+      "filename": "20260507000000_agent_board_inbox_reads.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 10949,
+      "sha256": "d9a11145ef49c7ee49b283c9fc71d230eb5d8e14ab76fa7a8da23519886af2d5"
+    },
+    {
+      "order": 9,
+      "id": "20260508000000_agent_board_callback_runtime",
+      "filename": "20260508000000_agent_board_callback_runtime.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 12760,
+      "sha256": "750848141ead5c1c8b58fc10f7b7b2d082055300ee28d8666bdcecea7db527ac"
+    },
+    {
+      "order": 10,
+      "id": "20260508000001_agent_board_inbox_service_role_reads",
+      "filename": "20260508000001_agent_board_inbox_service_role_reads.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 348,
+      "sha256": "85c2301902d5a49f6f226c9887ee5cf01a02f88b5c65925cb23cc3fb4c0a941e"
+    },
+    {
+      "order": 11,
+      "id": "20260510000000_agent_board_dblint_repairs",
+      "filename": "20260510000000_agent_board_dblint_repairs.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 14627,
+      "sha256": "4b862004b455d6569254638d3c5c07779b84b95ab8d70210d92a628dc3eb94c5"
+    },
+    {
+      "order": 12,
+      "id": "20260511000000_agent_board_auth_schema",
+      "filename": "20260511000000_agent_board_auth_schema.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 4611,
+      "sha256": "dba2128e74e25d009a8dc20052d3329fffee364e7b4c15c92ab22584b8f797a3"
+    },
+    {
+      "order": 13,
+      "id": "20260511000001_agent_board_auth_credentials",
+      "filename": "20260511000001_agent_board_auth_credentials.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 1885,
+      "sha256": "1f63c4d12fc34db76b7ceef17ee9c64ad09be9e13b9e02497477ec62aa14ebbc"
+    },
+    {
+      "order": 14,
+      "id": "20260512000000_agent_board_auth_provisioning_rpcs",
+      "filename": "20260512000000_agent_board_auth_provisioning_rpcs.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 17149,
+      "sha256": "4a72d9ac64446889a54293fb60bb3402da9dbd8bdb29027e7d5d15965e20af27"
+    },
+    {
+      "order": 15,
+      "id": "20260512000001_agent_board_auth_v1_rpcs",
+      "filename": "20260512000001_agent_board_auth_v1_rpcs.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 33511,
+      "sha256": "c1fdc772beac92f60010ca6d2e7ea95a81989d651f7cb279905770756dc47bda"
+    },
+    {
+      "order": 16,
+      "id": "20260512000002_agent_board_auth_v2_rpcs",
+      "filename": "20260512000002_agent_board_auth_v2_rpcs.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 43972,
+      "sha256": "c2df467ef49c6c30eea50d1a789e8816627a3b8f34a1172fdeb61b7d681031ae"
+    },
+    {
+      "order": 17,
+      "id": "20260512000003_agent_board_auth_rls",
+      "filename": "20260512000003_agent_board_auth_rls.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 15177,
+      "sha256": "d194a28482d8a7b00272e1b06a09fd125ec13f2906de86d2aab942671bc79294"
+    },
+    {
+      "order": 18,
+      "id": "20260513000000_agent_board_backup_ops",
+      "filename": "20260513000000_agent_board_backup_ops.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 1470,
+      "sha256": "1e9e5d1a6b6e2f6b83d9b5479e464cd0f91297c2a28ff71c54cabde656761142"
+    },
+    {
+      "order": 19,
+      "id": "20260513000001_agent_board_retention",
+      "filename": "20260513000001_agent_board_retention.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 5123,
+      "sha256": "7dd0ebd14eb97922d9c16fcf9c29815b0ab5c2bd7534c6f2de189d55e7d633ec"
+    },
+    {
+      "order": 20,
+      "id": "20260513000002_agent_board_monitoring_views",
+      "filename": "20260513000002_agent_board_monitoring_views.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 8790,
+      "sha256": "037b4d036a4526fd2b905e0a950698b8cbad5ad4a16e6fbea4cdab3b4147edc1"
+    },
+    {
+      "order": 21,
+      "id": "20260514000000_agent_board_auth_rls_id_qualification",
+      "filename": "20260514000000_agent_board_auth_rls_id_qualification.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 5490,
+      "sha256": "9d09d16f993cf504552e1736b867b4c6b2d5cad4ec9a99b512bf645fe83cfd76"
+    },
+    {
+      "order": 22,
+      "id": "20260515000000_agent_board_boardopt",
+      "filename": "20260515000000_agent_board_boardopt.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 17756,
+      "sha256": "99d82496dd9c791968cc7e129026e6af97da700302fa87e86b6a0e28513c7163"
+    },
+    {
+      "order": 23,
+      "id": "20260516000000_agent_board_callbackcap",
+      "filename": "20260516000000_agent_board_callbackcap.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 3725,
+      "sha256": "6f68ef098aaa6e2bd7e251d0ca9cd367cc593a4616a7b6acf51e3078394545fa"
+    },
+    {
+      "order": 24,
+      "id": "20260517000000_agent_board_addressing",
+      "filename": "20260517000000_agent_board_addressing.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 18997,
+      "sha256": "83ce21d332e9bc96a996b662848a2d02c508c8cdbd7ad8831feba83be0676a8b"
+    },
+    {
+      "order": 25,
+      "id": "20260628000000_agent_board_signing_store",
+      "filename": "20260628000000_agent_board_signing_store.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 9072,
+      "sha256": "889d73cd6c261a3ebde19c091db9bc71a1e5307f4f275cfd2a6871b509b16927"
+    },
+    {
+      "order": 26,
+      "id": "20260628000001_agent_board_signing_proof_rpcs",
+      "filename": "20260628000001_agent_board_signing_proof_rpcs.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 6663,
+      "sha256": "36571e459bf534dc5b79221ac3e3930840818b75cc3df21d744bd17eef548002"
+    },
+    {
+      "order": 27,
+      "id": "20260628000002_agent_board_signature_rls_reads",
+      "filename": "20260628000002_agent_board_signature_rls_reads.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 9776,
+      "sha256": "4172a46d85c1e1dcfb28e3398eed0aba73175cb9b3bfb3af712ec3eee9da2096"
+    },
+    {
+      "order": 28,
+      "id": "20260628000003_agent_board_signed_write_gateway",
+      "filename": "20260628000003_agent_board_signed_write_gateway.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 10728,
+      "sha256": "7cf2b5baf6520242b0d2a7f921dc4a54db8995b24c844d16ee67a79fe68d5903"
+    },
+    {
+      "order": 29,
+      "id": "20260628000004_agent_board_fleet_registry",
+      "filename": "20260628000004_agent_board_fleet_registry.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 19512,
+      "sha256": "8ee7a679d1c3355a28ff2ef61872651f43c172d391dd7c8e9b0d0e005def140a"
+    },
+    {
+      "order": 30,
+      "id": "20260628000005_agent_board_fleet_policy",
+      "filename": "20260628000005_agent_board_fleet_policy.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 19807,
+      "sha256": "b6e3603dc8b3911ee280a62f52bf578d76c8bb7932bc21f140f8852296512475"
+    },
+    {
+      "order": 31,
+      "id": "20260628000006_agent_board_fleet_read_models",
+      "filename": "20260628000006_agent_board_fleet_read_models.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 6626,
+      "sha256": "59c697536520d0e0650d7ca6cea25a97a7a2157b44623f9fcd7d56552809b6f4"
+    },
+    {
+      "order": 32,
+      "id": "20260629000100_agent_board_fleet_registry_repair",
+      "filename": "20260629000100_agent_board_fleet_registry_repair.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 19512,
+      "sha256": "8ee7a679d1c3355a28ff2ef61872651f43c172d391dd7c8e9b0d0e005def140a"
+    },
+    {
+      "order": 33,
+      "id": "20260629000101_agent_board_fleet_policy_refresh",
+      "filename": "20260629000101_agent_board_fleet_policy_refresh.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 19807,
+      "sha256": "b6e3603dc8b3911ee280a62f52bf578d76c8bb7932bc21f140f8852296512475"
+    },
+    {
+      "order": 34,
+      "id": "20260629000102_agent_board_fleet_read_models_refresh",
+      "filename": "20260629000102_agent_board_fleet_read_models_refresh.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 6626,
+      "sha256": "59c697536520d0e0650d7ca6cea25a97a7a2157b44623f9fcd7d56552809b6f4"
+    },
+    {
+      "order": 35,
+      "id": "20260630000100_agent_board_harness_kind_open_vocab",
+      "filename": "20260630000100_agent_board_harness_kind_open_vocab.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 566,
+      "sha256": "ed141128a5ec8b29a13ada55bae9582df8ba6226527c8afe32374cbbbda1cf6a"
+    },
+    {
+      "order": 36,
+      "id": "20260711000000_agent_board_provision_system_fail_closed",
+      "filename": "20260711000000_agent_board_provision_system_fail_closed.sql",
+      "origin": "baseline",
+      "sourceRef": "94f9c269a358a943498454003e8f05f47e27a491",
+      "bytes": 8308,
+      "sha256": "11b9b7d4617f190501ecee175f14335926d75500ffcedf0675275e6d2752b2e0"
+    },
+    {
+      "order": 37,
+      "id": "20260710000000_agent_board_authbound_boundary",
+      "filename": "20260710000000_agent_board_authbound_boundary.sql",
+      "origin": "lane",
+      "sourceRef": "7ddb0bbbd83d510e1a968bc7796ad15fcf7a27b9",
+      "bytes": 5061,
+      "sha256": "4656cabe7b0f4caec1cffe28ec5d84627fece85c1bc9d45092301c7bea3da2fe"
+    },
+    {
+      "order": 38,
+      "id": "20260710000100_agent_board_schema_version_rpc",
+      "filename": "20260710000100_agent_board_schema_version_rpc.sql",
+      "origin": "lane",
+      "sourceRef": "7ddb0bbbd83d510e1a968bc7796ad15fcf7a27b9",
+      "bytes": 415,
+      "sha256": "62d5d567c3b336607a6e65aaf8246b975a73e357db281924f466382f669a3286"
+    },
+    {
+      "order": 39,
+      "id": "20260710000400_agent_board_nonfleet_identity",
+      "filename": "20260710000400_agent_board_nonfleet_identity.sql",
+      "origin": "lane",
+      "sourceRef": "7ddb0bbbd83d510e1a968bc7796ad15fcf7a27b9",
+      "bytes": 5003,
+      "sha256": "6c37b4e00a6f13bc73e74276e7cc3864b2955ce7189a4602074511d6795a0873"
+    },
+    {
+      "order": 40,
+      "id": "20260710000401_agent_board_workload_providers",
+      "filename": "20260710000401_agent_board_workload_providers.sql",
+      "origin": "lane",
+      "sourceRef": "7ddb0bbbd83d510e1a968bc7796ad15fcf7a27b9",
+      "bytes": 2150,
+      "sha256": "b29afcdfb69d4fd765f10e49b18280f1ba4fb98c90cf02ab56ea6fc20e0f8bce"
+    },
+    {
+      "order": 41,
+      "id": "20260711000100_canary_signed_fleet_enforcement",
+      "filename": "20260711000100_canary_signed_fleet_enforcement.sql",
+      "origin": "lane",
+      "sourceRef": "7ddb0bbbd83d510e1a968bc7796ad15fcf7a27b9",
+      "bytes": 12649,
+      "sha256": "f56c6bb4a0e6bcdfbd2884d215c702f4cf374a374635b3180a958d08cdfa2607"
+    },
+    {
+      "order": 42,
+      "id": "20260712000000_agent_board_bundle_endpoint_compat",
+      "filename": "20260712000000_agent_board_bundle_endpoint_compat.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 4726,
+      "sha256": "ee4cccd78191f62ebac4c1c43c3fdcfe2b41debc6c2090f8bcadf701df84aa42"
+    },
+    {
+      "order": 43,
+      "id": "20260713000000_agent_board_rls_reassert_board_scoping",
+      "filename": "20260713000000_agent_board_rls_reassert_board_scoping.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 3464,
+      "sha256": "ba2c55bd11600d3dc86d54f02acd48ef4de711aaedce425e6bbfc85284a46c74"
+    }
+  ],
+  "excludedBridge": {
+    "id": "20260710000200_portal_htmltasking_taskbridge",
+    "filename": "20260710000200_portal_htmltasking_taskbridge.sql",
+    "origin": "portal-bridge",
+    "sourceRef": "7ddb0bbbd83d510e1a968bc7796ad15fcf7a27b9",
+    "bytes": 2598,
+    "sha256": "0dd8d76e8e1d2d3f215ec78eeb2e00ae4b3323f6459e3a71770d263a348c16ee",
+    "note": "Portal-owned bridge; reads agent_board.tasks; excluded from canonical union, remains adopter-side."
+  }
+}

package/src/check.js

@@ -0,0 +1,23 @@
+// Posture check with stable machine-readable output and exit codes. Wraps plan()
+// and maps posture -> deterministic exit code for CI / adopter gating.
+
+import { plan } from './plan.js';
+
+export const EXIT = {
+  exact: 0,
+  behind: 10,
+  ahead: 11,
+  divergent: 12,
+  error: 13,
+};
+
+export function check(history) {
+  const p = plan(history);
+  return {
+    schema: 'agent_board_check.v1',
+    posture: p.posture,
+    exitCode: EXIT[p.posture] ?? EXIT.error,
+    counts: p.counts,
+    ahead: p.ahead,
+  };
+}

package/src/index.js

@@ -0,0 +1,50 @@
+// @consiliency/agent-board-schema — programmatic surface + shared helpers for
+// the deterministic materialize / plan / check tooling.
+//
+// Self-contained: resolves the bundle's own migrations + manifest relative to
+// this package, with no workspace dependency (packed-consumer safe).
+
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const PKG_ROOT = join(HERE, '..');
+export const MIGRATIONS_DIR = join(PKG_ROOT, 'migrations');
+
+export const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+
+export function loadManifest() {
+  return JSON.parse(readFileSync(join(PKG_ROOT, 'schema-manifest.json'), 'utf8'));
+}
+
+// The ordered, digest-verified bundle migrations (throws on immutable-byte drift
+// or a missing file — the same fail-closed guard used at build time).
+export function loadOrderedMigrations() {
+  const manifest = loadManifest();
+  const present = new Set(readdirSync(MIGRATIONS_DIR).filter((f) => f.endsWith('.sql')));
+  return manifest.migrations.map((m) => {
+    if (!present.has(m.filename)) {
+      throw new Error(`bundle corrupt: missing migration ${m.filename}`);
+    }
+    const bytes = readFileSync(join(MIGRATIONS_DIR, m.filename));
+    const digest = sha256(bytes);
+    if (digest !== m.sha256) {
+      throw new Error(`bundle corrupt: ${m.id} digest ${digest} != manifest ${m.sha256}`);
+    }
+    return { ...m, bytes, digest };
+  });
+}
+
+// Parse a supplied migration-history snapshot: an array of { id/version,
+// sha256? } (applied migrations), or a plain array of version-id strings.
+export function normalizeHistory(history) {
+  const rows = Array.isArray(history) ? history : history?.applied ?? [];
+  const map = new Map();
+  for (const r of rows) {
+    if (typeof r === 'string') map.set(r, null);
+    else map.set(r.id ?? r.version, r.sha256 ?? r.digest ?? null);
+  }
+  return map;
+}

package/src/materialize.js

@@ -0,0 +1,73 @@
+// Deterministic materializer — the ONLY adopter path. Writes the bundle's
+// original, digest-verified migration IDs + exact bytes into an adopter's
+// supabase/migrations workspace, carrying a provenance marker the adopter CI
+// recognizes. Refuses to overwrite manual edits. Never touches DB history.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadManifest, loadOrderedMigrations } from './index.js';
+
+const MARKER_PREFIX = '-- @agent-board-schema:materialized';
+
+function markerLine(version, id, sha) {
+  return `${MARKER_PREFIX} ${version} ${id} ${sha}`;
+}
+
+// Strip a leading materialize marker line (if present) to recover original bytes.
+function stripMarker(text) {
+  if (text.startsWith(MARKER_PREFIX)) {
+    const nl = text.indexOf('\n');
+    return nl === -1 ? '' : text.slice(nl + 1);
+  }
+  return text;
+}
+
+export function materialize(targetDir, { dryRun = false } = {}) {
+  const manifest = loadManifest();
+  const migrations = loadOrderedMigrations();
+  mkdirSync(targetDir, { recursive: true });
+
+  const written = [];
+  for (const m of migrations) {
+    const dest = join(targetDir, m.filename);
+    const originalText = m.bytes.toString('utf8');
+    const content = `${markerLine(manifest.packageVersion, m.id, m.sha256)}\n${originalText}`;
+
+    if (existsSync(dest)) {
+      const existing = readFileSync(dest, 'utf8');
+      const existingOriginal = stripMarker(existing);
+      if (existingOriginal !== originalText) {
+        throw new Error(
+          `refusing to overwrite manual difference in ${m.filename}: adopter bytes diverge from the pinned bundle. Resolve via a forward corrective migration upstream, never by editing here.`,
+        );
+      }
+      written.push({ id: m.id, filename: m.filename, action: 'unchanged' });
+      continue;
+    }
+    if (!dryRun) writeFileSync(dest, content);
+    written.push({ id: m.id, filename: m.filename, action: dryRun ? 'would-write' : 'written' });
+  }
+
+  const receipt = {
+    schema: 'agent_board_materialize_receipt.v1',
+    package: manifest.package,
+    packageVersion: manifest.packageVersion,
+    schemaVersion: manifest.schemaVersion,
+    bundleAggregateDigest: manifest.aggregateSha256,
+    source: manifest.source,
+    orderedIds: migrations.map((m) => m.id),
+    perFile: migrations.map((m) => ({ id: m.id, sha256: m.sha256 })),
+    target: targetDir,
+    // NOTE: after applying these to the database the adopter MUST call
+    // agent_board.record_bundle_installation(packageVersion, bundleAggregateDigest,
+    // schemaVersion, sourceCommit, receiptId) so the compatibility RPC reports live.
+    recordInstallationRpc: 'agent_board.record_bundle_installation',
+  };
+  if (!dryRun) {
+    writeFileSync(
+      join(targetDir, '.agent-board-schema-materialize-receipt.json'),
+      JSON.stringify(receipt, null, 2) + '\n',
+    );
+  }
+  return { written, receipt };
+}

package/src/plan.js

@@ -0,0 +1,44 @@
+// Read-only per-ID plan against a supplied migration-history snapshot. Reports,
+// for every bundle migration, whether it is already applied (exact), applied
+// with a divergent digest, applied with an unknown digest, or pending — plus any
+// history entries the adopter has that the bundle does not (ahead). Never
+// touches the database.
+
+import { loadOrderedMigrations, normalizeHistory } from './index.js';
+
+export function plan(history) {
+  const migrations = loadOrderedMigrations();
+  const applied = normalizeHistory(history);
+  const bundleIds = new Set(migrations.map((m) => m.id));
+
+  const perId = migrations.map((m) => {
+    if (!applied.has(m.id)) return { id: m.id, action: 'pending' };
+    const appliedSha = applied.get(m.id);
+    if (appliedSha == null) return { id: m.id, action: 'applied-unknown-digest' };
+    if (appliedSha === m.sha256) return { id: m.id, action: 'applied-exact' };
+    return { id: m.id, action: 'applied-divergent', appliedSha256: appliedSha, bundleSha256: m.sha256 };
+  });
+
+  const ahead = [...applied.keys()].filter((id) => !bundleIds.has(id));
+
+  const counts = perId.reduce((acc, r) => {
+    acc[r.action] = (acc[r.action] || 0) + 1;
+    return acc;
+  }, {});
+
+  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';
+  else if (pending > 0) posture = 'behind';
+  else posture = 'exact';
+
+  return {
+    schema: 'agent_board_plan.v1',
+    posture,
+    counts: { ...counts, ahead: ahead.length },
+    ahead,
+    perId,
+  };
+}