@everystack/cli 0.4.44 → 0.4.45

package/src/cli/schema-fingerprint.ts

@@ -46,6 +46,7 @@
  */
 
 import { createHash } from 'node:crypto';
+import { canonicalAuthz } from './authz-canonical.js';
 import type { ModelDescriptor, SequenceDescriptor } from '@everystack/model';
 import type { SchemaSnapshot, TableSchema } from './schema-introspect.js';
 import type { AuthzContract, TableContract } from './authz-contract.js';
@@ -62,7 +63,17 @@ import { normalizeDefault, normalizeCheck } from './schema-diff.js';
 // STANDALONE SEQUENCES enter the canonical form (declared via defineSequence,
 // introspected from pg_sequence minus serial-owned) — a coverage expansion; the
 // `sequences` key appears only when any exist, so sequence-free states hash unchanged.
-export const FINGERPRINT_VERSION = 3;
+// v4: the AUTHZ canonical form became the reconciler's equivalence relation instead of a
+// name-keyed transcript of the catalog. Policy NAMES leave the hash (a brownfield database
+// names its policies whatever its previous migration tool named them, so hashing the name made
+// a policy carrying the declared authorization read as a different state); policies expand
+// across their roles as a MULTISET (so one policy TO a,b hashes equal to two identical ones TO
+// a and TO b, and duplicates never collapse); PUBLIC stays a single sentinel and is never
+// enumerated; and grants are filtered to the GOVERNED grantees, because the reconciler leaves
+// an ungoverned migrator/ETL role alone and a hash that counts it can never converge.
+// Together these restore the identity the format exists for: fingerprints match exactly when
+// db:generate is a no-op.
+export const FINGERPRINT_VERSION = 4;
 
 // ---------------------------------------------------------------------------
 // Canonical form.
@@ -115,40 +126,18 @@ function canonicalTable(table: TableSchema): Record<string, unknown> {
   };
 }
 
-function canonicalAuthzTable(contract: TableContract): Record<string, unknown> {
-  return {
-    table: contract.table,
-    rls: { enabled: contract.rls.enabled, forced: contract.rls.forced },
-    grants: Object.fromEntries(
-      Object.entries(contract.grants)
-        .map(([role, privs]) => [role, [...privs].sort()] as const)
-        .sort(([a], [b]) => (a < b ? -1 : 1)),
-    ),
-    ...(contract.columnGrants && Object.keys(contract.columnGrants).length > 0
-      ? {
-          columnGrants: Object.fromEntries(
-            Object.entries(contract.columnGrants)
-              .map(([role, byPriv]) => [
-                role,
-                Object.fromEntries(
-                  Object.entries(byPriv)
-                    .map(([priv, cols]) => [priv, [...cols].sort()] as const)
-                    .sort(([a], [b]) => (a < b ? -1 : 1)),
-                ),
-              ] as const)
-              .sort(([a], [b]) => (a < b ? -1 : 1)),
-          ),
-        }
-      : {}),
-    policies: byKey(
-      contract.policies.map((p) => ({
-        name: p.name, command: p.command, roles: [...p.roles].sort(),
-        permissive: p.permissive, using: p.using, check: p.check,
-      })),
-      (p) => p.name,
-    ),
-    // The handler-side columns exposure block is NOT a database fact — excluded.
-  };
+/**
+ * The authorization slice of the canonical form.
+ *
+ * Delegates to `authz-canonical`, which the reconciler and the differ read too. Keeping a
+ * private copy here is what let the fingerprint drift out of step with the reconciler and
+ * report permanent drift on a database that had nothing to reconcile.
+ */
+function canonicalAuthzTable(
+  contract: TableContract,
+  governed?: ReadonlySet<string>,
+): Record<string, unknown> {
+  return canonicalAuthz(contract, governed);
 }
 
 export interface CanonicalState {
@@ -171,6 +160,17 @@ export interface CanonicalizeOptions {
   /** Restrict the state to these schemas — the content address of ONE schema (e.g. a
    *  schema-scoped artifact) instead of the whole database. Omitted = every schema. */
   schemas?: string[];
+  /**
+   * The grantees the models govern. PASS THIS WHENEVER HASHING A LIVE CONTRACT.
+   *
+   * The reconciler leaves an ungoverned grantee alone by design, so a live grant to a
+   * migrator or ETL role is never reconciled. A hash that counts it describes a state the
+   * models can never reach: the operator gets "nothing to do" from the plan and "you have
+   * drifted" from the gate, with no action in between that resolves it. Omitted means "hash
+   * every grantee", which is correct only for a contract compiled FROM the models, where
+   * every grantee is governed by construction.
+   */
+  governedRoles?: ReadonlySet<string>;
 }
 
 export function canonicalizeState(
@@ -208,7 +208,10 @@ export function canonicalizeState(
         .map((e) => ({ name: e.name, values: e.values })),
       (e) => e.name,
     ),
-    authz: byKey(authzTables.filter((t) => keepTable(t.table)).map(canonicalAuthzTable), (t) => String(t.table)),
+    authz: byKey(
+      authzTables.filter((t) => keepTable(t.table)).map((t) => canonicalAuthzTable(t, opts.governedRoles)),
+      (t) => String(t.table),
+    ),
     ...(sequences.length ? { sequences } : {}),
   };
 }
@@ -305,3 +308,52 @@ export interface UnfingerprintedObject {
 export function mapUnfingerprintedRows(rows: Array<{ kind: unknown; identity: unknown }>): UnfingerprintedObject[] {
   return rows.map((r) => ({ kind: String(r.kind), identity: String(r.identity) }));
 }
+
+
+// ---------------------------------------------------------------------------
+// Comparing a STORED fingerprint against live reality.
+// ---------------------------------------------------------------------------
+
+/**
+ * A fingerprint as recorded in an artifact — a plan, a baseline, an export stamp.
+ *
+ * `v` is the format it was computed under. It must be stored ALONGSIDE the hash, not merely
+ * mixed into it: a hash alone cannot say why it differs, and the difference between "you have
+ * drifted" and "the format changed" is the difference between an operator hunting a phantom
+ * change and an operator running one re-baseline.
+ */
+export interface StoredFingerprint {
+  hash: string;
+  /** The FINGERPRINT_VERSION in force when the hash was computed. Absent = pre-v4 artifact. */
+  v?: number;
+}
+
+export type FingerprintComparison =
+  | { kind: 'match' }
+  | { kind: 'drift' }
+  | { kind: 'format-changed'; stored: number | 'unstamped'; current: number };
+
+/**
+ * Compare a stored fingerprint to one computed now.
+ *
+ * A raw hash compare across formats reports DRIFT, which is a lie — the state may be
+ * untouched while the way we describe it changed. Every hash comparison that spans an artifact
+ * boundary must come through here so a format change reads as a format change.
+ */
+export function compareStoredFingerprint(
+  stored: StoredFingerprint,
+  currentHash: string,
+  currentVersion: number = FINGERPRINT_VERSION,
+): FingerprintComparison {
+  if (stored.v !== currentVersion) {
+    return { kind: 'format-changed', stored: stored.v ?? 'unstamped', current: currentVersion };
+  }
+  return stored.hash === currentHash ? { kind: 'match' } : { kind: 'drift' };
+}
+
+/** The operator-facing sentence for a format change. Names the fix, never the phantom drift. */
+export function formatChangedMessage(c: Extract<FingerprintComparison, { kind: 'format-changed' }>): string {
+  return `fingerprint format changed (recorded v${c.stored}, current v${c.current}) — this is NOT drift. `
+    + 'The artifact predates the current canonical form, so its hash cannot be compared. '
+    + 'Re-mint the plan (db:plan) or re-baseline the stage (db:reconcile --rebaseline); no DDL is involved.';
+}