chore(drift): point stale comments and the RPC-missing hint at the v2 probe migration

docs/branch-review-records/e4f69008ad6f53bc51fceeff12fe8d1116722ca31f4c53c56bc0b1a611cf5e53.record.md

@@ -0,0 +1 @@
+| 2026-08-18 | claude/drift-probe-comment-pointers | 71dea17b3574e4d9bfba8c5770497c8b01ecb6ad | follow-up to #2058: stale comment pointers + RPC-missing hint name the v2 probe migration; doc bullet wording, PR #2090 | self-review: comment/doc-only, no SQL/manifest/test change | vitest drift-detection + migration-history-guards 25 passed; docs:check-links 1838 resolve; prettier unchanged |

docs/database-drift-detection.md

@@ -44,9 +44,11 @@ storage bucket rows + storage.objects policies.
 - **Column ordinal drift** — live tables grew via `ALTER TABLE ADD COLUMN`;
   columns compare sorted by name, not `attnum`.
 - **ACL append order** — aclitem arrays are sorted.
-- **Duplicate migration-history versions** — history is _not_ compared at all;
-  the check compares actual object state (history presence proved unreliable:
-  see `20260703030000` below).
+- **Duplicate migration-history versions** — history _presence_ is not compared;
+  the object categories compare actual object state (history presence proved
+  unreliable: see `20260703030000` below). The one thing the check now reads
+  from history is the no-statements fingerprint ("Migration-history probe"
+  below), and that is compared live-vs-allowlist, never manifest-vs-live.
 - **Platform-provisioned extensions** (pg_net, pgsodium, pgmq, …) — extra live
   extensions are informational; missing schema.sql-declared ones fail.
 - **Legacy index names** — `alias` allowlist entries assert the live database

scripts/check-drift.ts

@@ -14,9 +14,10 @@ loadEnvConfig(process.cwd());
  * it was generated from, so a stale manifest fails fast here (and offline in
  * tests/drift-detection.test.ts) instead of producing phantom drift.
  *
- * Live side: public.schema_drift_snapshot() (migration
- * 20260706200000_schema_drift_snapshot.sql), a service-role-only RPC returning
- * the same normalized inventory the manifest holds.
+ * Live side: public.schema_drift_snapshot() (v1 migration
+ * 20260706200000_schema_drift_snapshot.sql, v2 20260818090000 — see
+ * HISTORY_PROBE_MIGRATION below), a service-role-only RPC returning the same
+ * normalized inventory the manifest holds.
  *
  * Known, documented divergence is carried in supabase/drift-allowlist.json —
  * every entry needs a reason and is reported as a warning, never silently
@@ -372,7 +373,7 @@ async function main() {
     if (/could not find the function|schema cache|PGRST202/i.test(message)) {
       throw new Error(
         `schema_drift_snapshot() is not available on the live project. Apply migration ` +
-          `20260706200000_schema_drift_snapshot.sql through the normal linked migration workflow first. (${message})`,
+          `${HISTORY_PROBE_MIGRATION} (or at least the v1 20260706200000_schema_drift_snapshot.sql) through the normal linked migration workflow first. (${message})`,
       );
     }
     throw new Error(`schema_drift_snapshot RPC failed: ${message}`);

scripts/generate-drift-manifest.ts

@@ -13,7 +13,10 @@ import { fileURLToPath } from "node:url";
  *
  * Requires Docker. Never touches the live project. Run this whenever
  * supabase/schema.sql changes — the manifest embeds schema.sql's sha256 and
- * both check:drift and tests/supabase-schema.test.ts fail while it is stale.
+ * both check:drift and tests/drift-detection.test.ts fail while it is stale.
+ * The replay has no supabase_migrations schema, so the manifest's
+ * migration_history is always empty with probe 'no_history_table' — that
+ * category is compared live-vs-allowlist, never against this manifest.
  *
  * Flags:
  *   --keep        leave the container running (for inspection / DR rehearsal)