@everystack/cli 0.4.82 → 0.4.83

package/src/cli/schema-fingerprint-v11.ts

@@ -0,0 +1,234 @@
+/**
+ * FROZEN v11 canonicalizer — the exact live-side hash the CLI produced under
+ * FINGERPRINT_VERSION 11, before serial-sequence grants narrowed to USAGE-only at v12.
+ *
+ * DO NOT EDIT this to track new behaviour. It exists for ONE purpose: `db:apply`'s
+ * fast-forward proof recomputes a `schema_log` row recorded at `fp_version = 11` against a
+ * CURRENT live read, and comparing an old-format hash against a current-format one reports a
+ * phantom mismatch. So the descent registry recomputes the LIVE side under the ROW's canon —
+ * this function — per the standing rule in `RETAINED_CANONS`.
+ *
+ * It is a SELF-CONTAINED copy of the v11 canonical form: the command fan and effective-privilege
+ * deadness are byte-identical to v12 (frozen here so a FUTURE canon change to the live authz form
+ * cannot silently move a recorded v11 hash), and the ONLY behavioural difference from v12 is the
+ * serial-sequence inheritance rule — pinned here to the v11 set `SELECT + UPDATE + USAGE`, which
+ * v12 narrowed to USAGE alone. It reuses only the stable leaf normalizers (deparse + structure)
+ * and the authz-contract privilege oracles, whose behaviour is equal across every version.
+ */
+
+import { createHash } from 'node:crypto';
+import type { PolicyContract, TableContract, SequenceGrantContract } from './authz-contract';
+import { holdsPrivilegeEffective, policyCommands } from './authz-contract';
+import type { SchemaSnapshot, TableSchema } from './schema-introspect';
+import { normalizeDefault, normalizeCheck, indexKey, nextvalSequence } from './schema-diff';
+import { stableStringify, schemaOf, type CanonicalizeOptions } from './schema-fingerprint';
+
+const PUBLIC_ROLE = 'public';
+
+const byKey = <T>(items: T[], key: (item: T) => string): T[] =>
+  [...items].sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+
+// --- v11 authz canonical form (frozen: the command fan, identical to v12) ---
+
+interface PolicyArm {
+  role: string;
+  command: string;
+  permissive: boolean;
+  using: string;
+  check: string;
+}
+
+function policyArms(p: PolicyContract): PolicyArm[] {
+  const roles = p.roles.includes(PUBLIC_ROLE) ? [PUBLIC_ROLE] : [...p.roles].sort();
+  const arms: PolicyArm[] = [];
+  for (const command of policyCommands(p)) {
+    const using = command === 'INSERT' ? '' : (p.using ?? '');
+    const check = command === 'SELECT' || command === 'DELETE' ? '' : ((p.check ?? p.using) ?? '');
+    for (const role of roles) arms.push({ role, command, permissive: p.permissive, using, check });
+  }
+  return arms;
+}
+
+function armKey(a: PolicyArm): string {
+  return `${a.role}|${JSON.stringify([a.command, a.permissive, a.using, a.check])}`;
+}
+
+function multiset(entries: string[]): Array<[string, number]> {
+  const counts = new Map<string, number>();
+  for (const e of entries) counts.set(e, (counts.get(e) ?? 0) + 1);
+  return [...counts.entries()].sort(([a], [b]) => (a < b ? -1 : 1));
+}
+
+function governedArm(governed: ReadonlySet<string>, role: string): boolean {
+  return governed.has(role) || role === PUBLIC_ROLE || (role.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'));
+}
+
+function armDead(t: TableContract, a: PolicyArm): boolean {
+  if (a.role === PUBLIC_ROLE || a.role.toUpperCase() === 'PUBLIC') {
+    const grantees = t.effectivePrivileges
+      ? Object.keys(t.effectivePrivileges)
+      : [...new Set([...Object.keys(t.grants), ...Object.keys(t.columnGrants ?? {})])];
+    return !grantees.some((r) => holdsPrivilegeEffective(t, r, a.command));
+  }
+  return !holdsPrivilegeEffective(t, a.role, a.command);
+}
+
+function armSubsumed(a: PolicyArm, alive: readonly PolicyArm[]): boolean {
+  if (!a.permissive || a.role === PUBLIC_ROLE || a.role.toUpperCase() === 'PUBLIC') return false;
+  return alive.some((o) =>
+    (o.role === PUBLIC_ROLE || o.role.toUpperCase() === 'PUBLIC')
+    && o.permissive && o.command === a.command && o.using === a.using && o.check === a.check);
+}
+
+function canonicalPolicyArms(contract: TableContract, governed?: ReadonlySet<string>): Array<[string, number]> {
+  const alive = contract.policies.flatMap(policyArms).filter((a) => !armDead(contract, a));
+  const kept = alive
+    .filter((a) => !armSubsumed(a, alive))
+    .filter((a) => (governed ? governedArm(governed, a.role) : true));
+  return multiset(kept.map(armKey));
+}
+
+function governedOnly<T>(map: Record<string, T> | undefined, governed: ReadonlySet<string> | undefined): Record<string, T> {
+  if (!map) return {};
+  if (!governed) return map;
+  return Object.fromEntries(
+    Object.entries(map).filter(([grantee]) => governed.has(grantee) || (grantee.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'))),
+  );
+}
+
+function canonicalAuthzV11(contract: TableContract, governed?: ReadonlySet<string>): Record<string, unknown> {
+  const grants = governedOnly(contract.grants, governed);
+  const columnGrants = governedOnly(contract.columnGrants, governed);
+  return {
+    table: contract.table,
+    rls: { enabled: contract.rls.enabled, forced: contract.rls.forced },
+    grants: Object.fromEntries(
+      Object.entries(grants).map(([role, privs]) => [role, [...(privs as string[])].sort()] as const).sort(([a], [b]) => (a < b ? -1 : 1)),
+    ),
+    ...(Object.keys(columnGrants).length > 0
+      ? {
+          columnGrants: Object.fromEntries(
+            Object.entries(columnGrants)
+              .map(([role, byPriv]) => [
+                role,
+                Object.fromEntries(
+                  Object.entries(byPriv as Record<string, string[]>).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: canonicalPolicyArms(contract, governed),
+  };
+}
+
+// --- v11 base-schema canonical form (identical to v12; frozen here for self-containment) ---
+
+function canonicalTableV11(table: TableSchema): Record<string, unknown> {
+  return {
+    table: table.table,
+    columns: byKey(
+      table.columns.map((c) => ({ name: c.name, type: c.type, notNull: c.notNull, default: normalizeDefault(c.default) })),
+      (c) => c.name,
+    ),
+    primaryKey: table.primaryKey,
+    uniques: byKey(table.uniques.map((u) => ({ columns: u.columns })), (u) => u.columns.join(',')),
+    checks: byKey(table.checks.map((c) => ({ expr: normalizeCheck(c.expr) })), (c) => c.expr),
+    foreignKeys: byKey(
+      table.foreignKeys.map((f) => ({
+        columns: f.columns, refTable: f.refTable, refColumns: f.refColumns,
+        ...(f.onDelete ? { onDelete: f.onDelete } : {}),
+        ...(f.onUpdate ? { onUpdate: f.onUpdate } : {}),
+      })),
+      (f) => stableStringify(f),
+    ),
+    indexes: [...new Set(table.indexes.map(indexKey))].sort(),
+  };
+}
+
+// --- v11 serial-sequence ACL slice (frozen: the derived set is SELECT + UPDATE + USAGE) ---
+
+/**
+ * The v11 inheritance rule: an INSERT-holder inherits SELECT + UPDATE + USAGE on the table's
+ * serial sequence. This is the ONLY line that differs from the live (v12) form, which derives
+ * USAGE alone. Pinned as a literal here so this frozen canon never tracks the live change.
+ */
+function inheritedSequenceGrantsV11(table: TableContract): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const [grantee, privileges] of Object.entries(table.grants)) {
+    if (privileges.includes('INSERT')) out[grantee] = ['SELECT', 'UPDATE', 'USAGE'];
+  }
+  return out;
+}
+
+function isGovernedGrantee(governed: ReadonlySet<string> | undefined, grantee: string): boolean {
+  if (!governed) return true;
+  return governed.has(grantee) || (grantee.toUpperCase() === 'PUBLIC' && governed.has('PUBLIC'));
+}
+
+function seqShape(grants: Record<string, string[]>, governed?: ReadonlySet<string>): string {
+  const kept = Object.entries(grants)
+    .filter(([grantee, privs]) => privs.length > 0 && isGovernedGrantee(governed, grantee))
+    .map(([grantee, privs]) => [grantee, [...privs].sort()] as const);
+  return stableStringify(Object.fromEntries(kept));
+}
+
+function canonicalSequenceAuthzV11(
+  tables: TableSchema[],
+  authzTables: TableContract[],
+  measured: SequenceGrantContract[] | undefined,
+  governed: ReadonlySet<string> | undefined,
+  keepTable: (name: string) => boolean,
+): Array<[string, string[]]> {
+  const snapshotByTable = new Map(tables.map((t) => [t.table, t]));
+  const measuredByTable = new Map<string, SequenceGrantContract[]>();
+  for (const s of measured ?? []) {
+    (measuredByTable.get(s.table) ?? measuredByTable.set(s.table, []).get(s.table)!).push(s);
+  }
+  const out: Array<[string, string[]]> = [];
+  for (const az of authzTables) {
+    if (!keepTable(az.table)) continue;
+    let shapes: string[];
+    if (measuredByTable.has(az.table)) {
+      shapes = measuredByTable.get(az.table)!.filter((s) => !s.identity).map((s) => seqShape(s.grants, governed));
+    } else {
+      const snap = snapshotByTable.get(az.table);
+      const serialCount = (snap?.columns ?? []).filter((c) => nextvalSequence(normalizeDefault(c.default)) != null).length;
+      if (serialCount === 0) continue;
+      const inherited = seqShape(inheritedSequenceGrantsV11(az), governed);
+      shapes = Array.from({ length: serialCount }, () => inherited);
+    }
+    if (shapes.length === 0) continue;
+    out.push([az.table, shapes.sort()]);
+  }
+  return out.sort(([a], [b]) => (a < b ? -1 : 1));
+}
+
+/** The frozen v11 live hash for (snapshot, authzTables, opts). */
+export function fingerprintV11(snapshot: SchemaSnapshot, authzTables: TableContract[], opts: CanonicalizeOptions = {}): string {
+  const inScope = opts.schemas ? new Set(opts.schemas) : null;
+  const keepTable = (name: string) => inScope === null || inScope.has(schemaOf(name));
+  const tables = snapshot.tables.filter((t) => keepTable(t.table));
+  const usedEnum = new Set<string>();
+  for (const t of tables) for (const c of t.columns) usedEnum.add(schemaOf(c.type) === 'public' ? c.type : c.type.slice(c.type.indexOf('.') + 1));
+  const sequences = byKey(
+    (snapshot.sequences ?? [])
+      .filter((s) => inScope === null || inScope.has(schemaOf(s.name)))
+      .map((s) => ({ name: s.name, as: s.as, ...(s.start != null ? { start: s.start } : {}), ...(s.increment != null ? { increment: s.increment } : {}) })),
+    (s) => String(s.name),
+  );
+  const sequenceAuthz = canonicalSequenceAuthzV11(tables, authzTables, opts.sequenceGrants, opts.governedRoles, keepTable);
+  const canonical = {
+    v: 11,
+    tables: byKey(tables.map(canonicalTableV11), (t) => String(t.table)),
+    enums: byKey(
+      (snapshot.enums ?? []).filter((e) => inScope === null || usedEnum.has(e.name)).map((e) => ({ name: e.name, values: e.values })),
+      (e) => e.name,
+    ),
+    authz: byKey(authzTables.filter((t) => keepTable(t.table)).map((t) => canonicalAuthzV11(t, opts.governedRoles)), (t) => String(t.table)),
+    ...(sequences.length ? { sequences } : {}),
+    ...(sequenceAuthz.length ? { sequenceAuthz } : {}),
+  };
+  return createHash('sha256').update(stableStringify(canonical)).digest('hex');
+}

package/src/cli/schema-fingerprint.ts

@@ -60,6 +60,7 @@ import { compileTableContract } from './authz-compile';
 import { governedRoleSet, inheritedSequenceGrants } from './authz-reconcile';
 import { normalizeDefault, normalizeCheck, indexKey, nextvalSequence } from './schema-diff';
 import { fingerprintV10 } from './schema-fingerprint-v10';
+import { fingerprintV11 } from './schema-fingerprint-v11';
 
 // v2: expression fields (defaults, checks, partial-index WHERE) normalize through
 // the diff's pg-deparse normalizers before hashing, so the model form and the live
@@ -130,7 +131,17 @@ import { fingerprintV10 } from './schema-fingerprint-v10';
 // plan or baseline minted under v10 refuses as a FORMAT CHANGE and must be re-minted (db:plan) or
 // re-baselined (db:reconcile --rebaseline) — no DDL, the fingerprint is a content address. The v10
 // canon is frozen in RETAINED_CANONS so a schema_log row recorded under it still descends.
-export const FINGERPRINT_VERSION = 11;
+// v12 — SERIAL-SEQUENCE grants narrowed to LEAST PRIVILEGE. The v11 A6 rule derived SELECT + UPDATE
+// + USAGE for every INSERT-holder, handing each one `setval` control of a surrogate key it never
+// needs; it widened a consumer's governed prod migrator by 28 UPDATE grants nobody asked for. The
+// derived set is now USAGE alone (exactly what `nextval` needs — see SEQUENCE_PRIVILEGES_FOR_INSERT),
+// so `canonicalSequenceAuthz`'s DERIVED shape moves for any serial table with a governed INSERT, and
+// the fingerprint with it. Same consequence as every bump: a plan or baseline minted under v11
+// refuses as a FORMAT CHANGE and must be re-minted — no DDL, the fingerprint is a content address.
+// On every deployed stage the next db:plan mints a REVOKE narrowing those sequence grants to USAGE
+// (the report classifies it as narrowing access). The v11 canon is frozen in schema-fingerprint-v11
+// and registered in RETAINED_CANONS so a schema_log row recorded under it still descends.
+export const FINGERPRINT_VERSION = 12;
 
 // ---------------------------------------------------------------------------
 // Canonical form.
@@ -489,11 +500,13 @@ export type CanonHasher = (
  * absent from this map is unrecomputable: `fingerprintLiveAtVersion` returns null and descent
  * SKIPS that row (fails closed), never guesses a hash.
  *
- * v11 is the FIRST bump, so v10 is the first retired entry: `fingerprintV10`, a self-contained
- * frozen copy of the v10 canonical form (no command fan, direct-grant deadness, no sequence ACLs).
+ * Retired entries: `fingerprintV10` (no command fan, direct-grant deadness, no sequence ACLs) and
+ * `fingerprintV11` (the command fan and sequence ACLs, but the pre-least-privilege derivation that
+ * gave an INSERT-holder SELECT + UPDATE + USAGE on its sequence).
  */
 export const RETAINED_CANONS: Readonly<Record<number, CanonHasher>> = {
   10: (snapshot, tables, opts) => fingerprintV10(snapshot, tables, opts),
+  11: (snapshot, tables, opts) => fingerprintV11(snapshot, tables, opts),
   [FINGERPRINT_VERSION]: (snapshot, tables, opts) => fingerprintState(snapshot, tables, opts).hash,
 };
 
@@ -527,7 +540,7 @@ export function fingerprintLiveAtVersion(
  * manifest (derived-introspect): triggers, domains, composite types, foreign
  * tables, partitioned tables, installed extensions — and identity columns, which
  * the models can now say and the builder now builds, but which the hash does not
- * yet cover (deferred past v11 by scope). Serial-sequence ACLs left this list at
+ * yet cover (deferred past v12 by scope). Serial-sequence ACLs left this list at
  * v11: they are fingerprinted now (see canonicalSequenceAuthz).
  */
 export const UNFINGERPRINTED_SQL = `
@@ -573,8 +586,9 @@ UNION ALL
 -- A14. A column's GENERATED … AS IDENTITY is READ, DECLARED and BUILT, but it is NOT hashed:
 -- the fingerprint's coverage is a version contract, and a property entering the hash inside a
 -- version makes two operators on different CLI builds disagree about the same database. v11
--- took the sequence ACLs and deliberately left this and the schema posture out; both stay
--- named here until a canon bump (a v12 candidate) carries them together. The gap is real and
+-- took the sequence ACLs and deliberately left this and the schema posture out (v12 narrowed
+-- the sequence derivation and carried neither); both stay named here until a later canon bump
+-- carries them together. The gap is real and
 -- narrow: an identity that is silently dropped or flipped ALWAYS to BY DEFAULT leaves the MATCH
 -- claim green. It is not silent on the write path — db:generate/db:plan diff it (the differ
 -- compares identity) — and the round-trip oracle's pg_dump comparison catches it.

package/src/cli/sql-statement.ts

@@ -0,0 +1,98 @@
+/**
+ * sql-statement — reading ONE generated statement, before anybody classifies it.
+ *
+ * Every classifier over db:generate's statement stream starts by answering the same question:
+ * which lines of this statement are SQL, and which are the `-- WARNING:` / `-- NOTICE:` prologue
+ * the emitter attached to it? The answer decides what a destructive check tests, which bucket a
+ * histogram counts, and what verb the plain change list prints. It was written out by hand eight
+ * times across plain-output.ts, state-apply.ts and edge-plan.ts — the same
+ * `split('\n').find((l) => l.trim() !== '' && !l.trim().startsWith('--'))`, with two different
+ * fallbacks and no shared name. Two classifiers that read a statement differently disagree about
+ * it before either one has decided anything, so the reading lives here, once.
+ *
+ * There are TWO readings, and which one a caller wants is a real decision:
+ *
+ *   statementBody      the WHOLE statement on one line. What you MATCH against. A generated
+ *                      statement is not single-line — the emitters format `ALTER TABLE`,
+ *                      `CREATE TRIGGER`, `GRANT` and every function body across lines — so a
+ *                      matcher that sees only line 1 sees a subject with no verb.
+ *   statementHead      the FIRST SQL line. What you PRINT when one line of an operator-facing
+ *                      preview is all there is room for.
+ *
+ * This module READS. It does not classify: what counts as destructive is state-apply's
+ * `classifyDestructive` (the single source the --confirm / snapshot / approver gate and
+ * plain-output's ⚠ line both run on), what counts as a histogram kind is state-apply's
+ * `KIND_MATCHERS`, and what a change is called in plain words is plain-output's `describeChange`.
+ * Those are three different questions on three different axes, deliberately not merged.
+ *
+ * Pure, and dependency-free on purpose — plain-output is a pure renderer and must stay one.
+ */
+
+/**
+ * The SQL lines of a statement: everything that is not blank and not a `--` comment,
+ * each still carrying its own leading whitespace.
+ *
+ * A statement's comment prologue is documentation the emitter wrote for the operator. It is
+ * never the verb, and a reader that stops at line 1 reports `-- WARNING: DROP IDENTITY …` as
+ * the change rather than the ALTER underneath it.
+ */
+export function statementBodyLines(statement: string): string[] {
+  return statement.split('\n').filter((l) => l.trim() !== '' && !l.trim().startsWith('--'));
+}
+
+/**
+ * The WHOLE statement as one line: comments and blank lines dropped, whitespace collapsed,
+ * CASE PRESERVED. This is the reading every MATCHER wants.
+ *
+ * Two failures it exists to stop, one in each direction.
+ *
+ * UNDER-reading, the dangerous one. A matcher anchored at `^` against the first line only sees
+ * `ALTER TABLE public.foo` for `ALTER TABLE public.foo\n  DROP COLUMN bar;` — the verb clause is
+ * on line 2. The plain change list matched nothing and printed `+` on a statement that REMOVES a
+ * column, and `revokeTarget` returned null for a `REVOKE` sitting under a `-- WARNING:` prologue,
+ * so a real privilege strip skipped the --confirm / snapshot / approver ceremony.
+ *
+ * OVER-reading, the other one. A matcher run against the RAW text reads the emitter's prose:
+ * `-- WARNING: this used to DROP TABLE …` ahead of an `ADD COLUMN` classified the addition as a
+ * drop. The comment is documentation, not DDL.
+ *
+ * Case is left exactly as the emitter wrote it. Callers whose matchers are upper-case uppercase
+ * the result themselves — the grantee `revokeTarget` returns out of this string is an identifier,
+ * and `"Odd-Role"` is not `"ODD-ROLE"`.
+ *
+ * The result is MATCHED against, never executed: a function body losing its own formatting here
+ * costs nothing, because the statement that runs is always the original string.
+ */
+export function statementBody(statement: string): string {
+  return statementBodyLines(statement).join(' ').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * The first SQL line, trimmed — the verb. Empty string when the statement is all comment.
+ *
+ * For callers that want ONE line of a statement, not the statement: the `!   <ddl>` previews in
+ * the plan summary. Anything that MATCHES wants {@link statementBody} instead — see the
+ * under-reading failure documented there. Callers that PRINT the head want
+ * {@link statementHeadOrSelf}, so a pure-comment statement still shows the operator something.
+ */
+export function statementHead(statement: string): string {
+  const [first] = statementBodyLines(statement);
+  return (first ?? '').trim();
+}
+
+/**
+ * The first SQL line, trimmed, falling back to the whole statement when there is none.
+ *
+ * For the paths that ECHO the statement at the operator (`!   <ddl>` in the plan summary):
+ * printing nothing for a statement that is all comment would silently drop a line the reader
+ * is counting.
+ */
+export function statementHeadOrSelf(statement: string): string {
+  const [first] = statementBodyLines(statement);
+  return (first ?? statement).trim();
+}
+
+/** Every line is blank or a comment — nothing executable inside. */
+export function isPureComment(statement: string): boolean {
+  return statementBodyLines(statement).length === 0;
+}

package/src/cli/state-apply.ts

@@ -27,16 +27,10 @@ import { generateMigrationSql, HELD_DROP_PREFIX } from './migration-generate';
 import type { SequenceDescriptor } from '@everystack/model';
 import { fingerprintLive, FINGERPRINT_VERSION } from './schema-fingerprint';
 import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply';
+import { isPureComment, statementBody, statementHead } from './sql-statement';
 
 const NOTICE_PREFIX = '-- NOTICE';
 
-/** Every line is a comment (or blank) — nothing executable inside. */
-function isPureComment(statement: string): boolean {
-  return statement
-    .split('\n')
-    .every((line) => line.trim() === '' || line.trim().startsWith('--'));
-}
-
 export interface ClassifiedStatements {
   /** Real DDL (possibly carrying leading -- WARNING lines) — what apply runs. */
   executable: string[];
@@ -105,11 +99,19 @@ export interface DestructiveBreakdown {
  * the same rule the reconciler already applies to grants: absence of knowledge means LEAVE IT
  * ALONE and say so, never "assume it is fine".
  */
+// TODO(PR-1b): classify on emitter kind, not rendered text — see the fast-follow item on the board.
 const ADDITIVE_MATCHERS: RegExp[] = [
   /^CREATE\s+(TABLE|POLICY|INDEX|UNIQUE\s+INDEX|SEQUENCE|EXTENSION|TYPE|SCHEMA)\b/,
   /^GRANT\b/,
   /^COMMENT\s+ON\b/,
-  /^ALTER\s+TABLE\s+[\s\S]+?\sADD\s+(COLUMN|CONSTRAINT|PRIMARY\s+KEY)\b/,
+  // ADD COLUMN alone. Its siblings `ADD CONSTRAINT` (FOREIGN KEY / CHECK / UNIQUE) and
+  // `ADD PRIMARY KEY` are deliberately NOT here: each one VALIDATES every row already in the
+  // table and then RESTRICTS every write after it. An FK add fails on orphan rows, a CHECK add
+  // fails on any violating row, a UNIQUE add fails on existing duplicates, and ADD PRIMARY KEY
+  // fails on duplicates or NULLs *and* silently makes every included column NOT NULL. Calling
+  // those additive tells the reviewer the plan is safe when it can abort the apply outright —
+  // the same false zero described above. They read as `unclassified`, like `SET NOT NULL`.
+  /^ALTER\s+TABLE\s+[\s\S]+?\sADD\s+COLUMN\b/,
   // Enabling/forcing RLS only ever RESTRICTS; it cannot widen access or lose a row.
   /^ALTER\s+TABLE\s+[\s\S]+?\s(ENABLE|FORCE)\s+ROW\s+LEVEL\s+SECURITY\b/,
   // Relaxing nullability and setting a default add capability; they remove nothing.
@@ -148,12 +150,16 @@ export interface StatementPartition {
   unclassified: string[];
 }
 
-/** The first non-comment line, upper-cased — WARNING prologues must not hide the verb. */
-function statementHead(statement: string): string {
-  return (statement.split('\n').find((l) => l.trim() !== '' && !l.trim().startsWith('--')) ?? '')
-    .trim()
-    .toUpperCase();
-}
+/**
+ * The first non-comment line, upper-cased — WARNING prologues must not hide the verb.
+ *
+ * The reading is shared with the plain change list (sql-statement.ts); the upper-casing is
+ * this module's own, because every matcher below is written in upper case. Note this is the
+ * FIRST-LINE reading, deliberately: `partitionStatements` and `statementKind` bucket a statement
+ * by the verb it opens with. What DESTROYS is a different question and uses {@link statementBody}
+ * — see `classifyDestructive`.
+ */
+const upperHead = (statement: string): string => statementHead(statement).toUpperCase();
 
 /**
  * Partition an executable stream into exactly one bucket per statement.
@@ -174,7 +180,7 @@ export function partitionStatements(
 
   for (const statement of executable) {
     if (destructive.has(statement)) continue;
-    const head = statementHead(statement);
+    const head = upperHead(statement);
     if (AUTHZ_REMOVAL_MATCHERS.some((re) => re.test(head))) authzRemovals.push(statement);
     else if (ADDITIVE_MATCHERS.some((re) => re.test(head))) additive.push(statement);
     else unclassified.push(statement);
@@ -182,12 +188,22 @@ export function partitionStatements(
   return { additive, drops, narrowings, strips, authzRemovals, unclassified };
 }
 
-/** `REVOKE … ON <table> FROM <grantee>;` → the grantee, or null when it is not a revoke. */
+/**
+ * `REVOKE … ON <table> FROM <grantee>;` → the grantee, or null when it is not a revoke.
+ *
+ * Read from {@link statementBody}, not the raw text. The regex is anchored at `^REVOKE`, and the
+ * emitter welds a `-- WARNING:` prologue onto statements it wants the operator to read — so the
+ * raw text of a revoke worth warning about starts with `--`, matched nothing, and returned null.
+ * Null here means "not a revoke", which UNDER-classifies a real privilege strip and skips the
+ * whole --confirm / snapshot / approver ceremony on it. That is the failure direction that
+ * matters: it removes a gate rather than adding one.
+ *
+ * Case is NOT touched. A quoted identifier can hold anything (`"Odd-Role"`, a reserved word,
+ * mixed case) and the grantee returned here is compared against the declared set, where
+ * `Odd-Role` and `ODD-ROLE` are two different roles.
+ */
 export function revokeTarget(statement: string): string | null {
-  // A quoted identifier can hold anything (`"Odd-Role"`, a reserved word, mixed case), and
-  // reading one as null would silently UNDER-classify a strip — the failure direction that
-  // matters, since it skips the ceremony rather than adding one.
-  const m = /^REVOKE\s+[\s\S]+?\sFROM\s+("[^"]*"|[A-Za-z_][A-Za-z0-9_$]*)\s*;?\s*$/i.exec(statement.trim());
+  const m = /^REVOKE\s+[\s\S]+?\sFROM\s+("[^"]*"|[A-Za-z_][A-Za-z0-9_$]*)\s*;?\s*$/i.exec(statementBody(statement));
   return m ? m[1].replace(/^"|"$/g, '') : null;
 }
 
@@ -199,10 +215,17 @@ export function classifyDestructive(
   const narrowings: string[] = [];
   const strips: string[] = [];
   for (const statement of executable) {
+    // Every matcher here reads the statement's BODY, never its raw text. The emitter's
+    // `-- WARNING:` prologue is prose written for the operator, and matching it both ways round
+    // was wrong: a comment that merely MENTIONS `DROP TABLE` ahead of an `ADD COLUMN` classified
+    // the addition as a drop, and a real `REVOKE` hiding under a prologue was not seen at all.
+    // The body preserves case, which these upper-case matchers rely on — the emitters write SQL
+    // keywords in upper case and nothing here lower-cases or upper-cases anything.
+    const body = statementBody(statement);
     // DROP IDENTITY is a drop: it takes the backing sequence and its counter with it, and a
     // counter is state no re-run reconstructs. The column's rows survive; its auto-value does not.
-    if (/\bDROP\s+(TABLE|COLUMN|TYPE|IDENTITY)\b/.test(statement)) drops.push(statement);
-    else if (/\bSET DATA TYPE\b/.test(statement) && /\bUSING\b/.test(statement)) narrowings.push(statement);
+    if (/\bDROP\s+(TABLE|COLUMN|TYPE|IDENTITY)\b/.test(body)) drops.push(statement);
+    else if (/\bSET DATA TYPE\b/.test(body) && /\bUSING\b/.test(body)) narrowings.push(statement);
     else if (opts.declaredGrantees) {
       // Only classified when the caller supplied the declared side — without it there is
       // no way to tell a strip from ordinary churn, and guessing would newly force
@@ -240,8 +263,7 @@ const KIND_MATCHERS: Array<[RegExp, string]> = [
 ];
 
 function statementKind(statement: string): string {
-  const first = statement.split('\n').find((l) => l.trim() !== '' && !l.trim().startsWith('--')) ?? '';
-  const s = first.trim().toUpperCase();
+  const s = upperHead(statement);
   for (const [re, kind] of KIND_MATCHERS) {
     if (re.test(s)) return kind;
   }

package/src/wire.ts

@@ -0,0 +1,30 @@
+/**
+ * @everystack/cli/wire — the Model-derived wire contract, as the ops Lambda reaches it.
+ *
+ * The definitions live in `@everystack/model/wire` (a neutral package, so the shapes have ONE
+ * home rather than a CLI copy and a server copy that agree by convention). This file is a pure
+ * re-export, and it exists for resolution, not for taste: `@everystack/server` does not declare
+ * `@everystack/model` — under pnpm's strict layout it therefore cannot resolve
+ * `@everystack/model/wire` from its own files. It CAN resolve `@everystack/cli/*` (an optional
+ * peer it already loads `@everystack/cli/apply` from), and the CLI depends on `@everystack/model`
+ * outright, so the constant reaches the server through here.
+ *
+ * That routing is also what makes the guard measure the RIGHT thing. The server reads
+ * MODEL_WIRE_CONTRACT from the `@everystack/cli` bundled into its Lambda; the operator's CLI reads
+ * it from its own install. Those are the two versions that can drift, which is precisely the skew
+ * the handshake exists to refuse — the same axis `APPLY_CONTRACT_VERSION` already rides.
+ */
+
+export { MODEL_WIRE_CONTRACT } from '@everystack/model/wire';
+export type {
+  ModelWireEnvelope,
+  DeclaredOwner,
+  AdopteeKind,
+  Adoptee,
+  ProvisionWirePayload,
+  OwnershipWirePayload,
+  DerivedKind,
+  DerivedAttachment,
+  DerivedDescriptor,
+  ReconcileWirePayload,
+} from '@everystack/model/wire';