@everystack/cli 0.4.81 → 0.4.83

package/src/cli/derived-source.ts

@@ -21,102 +21,25 @@
  */
 
 import { createHash } from 'node:crypto';
+import type { DerivedAttachment, DerivedDescriptor, DerivedKind as WireDerivedKind } from '@everystack/model/wire';
 
 /**
  * `'trigger'` and `'sql'` carry the extra fields the reconciler edges need (a trigger's
  * table for `DROP TRIGGER … ON`, a defineSql object's explicit drop).
+ *
+ * DEFINED IN `@everystack/model/wire` and re-exported here. `db:reconcile` ships these objects
+ * over the wire to a deployed stage's ops Lambda, so the shape is a versioned wire contract
+ * (MODEL_WIRE_CONTRACT), not a CLI-local convenience — one definition, imported by both sides,
+ * rather than a CLI copy and a server copy that happen to agree.
  */
-export type DerivedKind = 'function' | 'view' | 'materialized view' | 'trigger' | 'sql';
+export type DerivedKind = WireDerivedKind;
 
 /** A statement that belongs to an object: its index, comment, or grant. */
-export interface Attachment {
-  kind: 'index' | 'comment' | 'grant';
-  sql: string;
-}
+export type Attachment = DerivedAttachment;
 
-export interface SourceObject {
-  kind: DerivedKind;
-  /** Schema name, defaulted to `public` when unqualified. */
-  schema: string;
-  name: string;
-  /** `schema.name` — the reconciler's join key against the live catalog.
-   *  (Triggers: `schema.table.name` — compound identity, joined against pg_trigger.) */
-  identity: string;
-  /** The CREATE statement as authored (no trailing semicolon). */
-  sql: string;
-  /** Indexes / comments / grants targeting this object, in source order. */
-  attachments: Attachment[];
-  /** sha256 of the normalized CREATE + attachments — comment/whitespace edits do not change it. */
-  hash: string;
-  /**
-   * sha256 of the normalized CREATE + attachments EXCEPT plain (non-column-scoped) grants — the
-   * "would a rebuild be required" hash. Equal across an authz-only change (plain grants moved, body
-   * unchanged), so the reconciler can route that to a bare GRANT delta instead of a matview rebuild.
-   * Column-scoped grants stay IN (attacl not introspected → they must rebuild). `hash` stays the
-   * full/stable formula for provenance compat; this is the additional discriminator.
-   */
-  bodyHash: string;
-  /** Source file this object came from (descriptors: the declared-models marker). */
-  file: string;
-  /** Position in the concatenated source — a valid dependency order by convention. */
-  seq: number;
-  /**
-   * kind 'function' only: the declared owning role.
-   *
-   * A SECURITY DEFINER function executes with its OWNER's rights, so this is a privilege
-   * boundary. The applier enacts it by running the CREATE under `SET ROLE <owner>` rather
-   * than following it with `ALTER … OWNER TO`: measured on PG16, once ownership has moved the
-   * builder gets "must be owner of function" on the next `CREATE OR REPLACE`, so the
-   * alter-after form works exactly once and breaks every re-run.
-   */
-  owner?: string;
-  /**
-   * kind 'function' only: the declared `SET search_path`, or the sentinel `'unpinned'`.
-   *
-   * It is already inside `sql`, so this is NOT in the hash and changes no fingerprint. It rides
-   * structurally so the differ can compare the declared pin against the LIVE catalog directly
-   * rather than only against a recorded hash. Without that, `--baseline` records a declared pin
-   * the database does not have and every later check reports zero actions, forever: measured,
-   * and it is how a model came to claim `search_path=pg_catalog` about a database with none
-   * while every gate stayed green.
-   *
-   * `undefined` means NOT DECLARED — a parser-era db/sql object, or an invoker function with no
-   * pin. The comparison is skipped there; absent evidence is not evidence.
-   */
-  searchPath?: string[] | 'unpinned';
-  /** kind 'sql' only: the declared PostgreSQL object kind (`'aggregate'`, …). */
-  objectKind?: string;
-  /** kind 'sql' only: the explicit DROP for kinds whose drop isn't derivable from the name. */
-  drop?: string;
-  /** kind 'trigger' only: the (possibly schema-qualified) table/view the trigger rides. */
-  table?: string;
-  /**
-   * Views/matviews: every declared `dependsOn` ref as an identity (models AND derived),
-   * sorted. B4's dependency drift verifies it against the live catalog's actual edges —
-   * "declared, then verified". Absent on kinds whose live edges pg_depend can't see.
-   */
-  declaredDeps?: string[];
-  /**
-   * kind 'function' only: the relations this function's SIGNATURE names — a `setof(ref)`
-   * return, or an argument/return type spelled as a declared table, view or matview.
-   *
-   * Distinct from `dependsOn`, and the distinction is load-bearing for the from-scratch build.
-   * A body reference is a FORWARD reference the build can defer (`check_function_bodies = off`
-   * is exactly that escape), so a function whose body reads a not-yet-created table still
-   * creates. A SIGNATURE reference is not deferrable: PostgreSQL resolves the return and
-   * argument types when the function is created, so `RETURNS SETOF stats_view.x_row` needs
-   * that view to exist already. `db:build` runs functions ahead of state (an RLS policy's
-   * predicate must resolve the function it calls) and uses this to hold back the ones that
-   * cannot go first; the compiler also orders the function after them.
-   *
-   * RELATIONS only — tables, views, matviews. A signature naming a declared ENUM, domain or
-   * composite type has the same problem and is NOT covered here, so it still fails in the
-   * ahead-of-state pass. Absent/empty means "names no declared relation", never "is safe".
-   *
-   * Not in the hash — it is derived from `sql`, so carrying it moves no fingerprint.
-   */
-  signatureDeps?: string[];
-}
+/** The compiled derived-object descriptor — declared, field by field, in
+ *  `@everystack/model/wire` as `DerivedDescriptor`. */
+export type SourceObject = DerivedDescriptor;
 
 /** The provenance marker descriptor-compiled objects carry in `file` — the compiler
  *  ALWAYS declares authz (a private relation is declared-empty, not undeclared), so
@@ -207,9 +130,21 @@ export function lex(
         continue;
       }
       if (ch === "'") {
-        // E'...' / e'...' strings give backslash escape semantics.
+        // `E'...'` is PostgreSQL's backslash-escaping string literal — but the `E` only counts
+        // when it STANDS ALONE before the quote. Testing the single preceding character glued
+        // that rule onto the tail of any identifier or keyword ending in `e`, which in English
+        // is most of them: `date'2024-01-01'`, `store'x'`, `xe'y'`. A backslash inside such a
+        // literal then swallowed the closing quote, the lexer stayed "inside a string" past the
+        // real end, and `splitSqlStatements` stopped seeing the `;` boundaries after it — a
+        // multi-statement file counted as ONE, and db:exec/db:backfill sent the whole tail to
+        // the database as a single string. So require the character BEFORE the `E`/`e` to be a
+        // non-identifier character, or absent (the `E` starts the text).
+        // Mirrored in `packages/server/src/sql-lex.ts` — the deliberate fork, kept in step by hand.
         const prev = text[i - 1];
-        state = { in: 'single', escaped: prev === 'E' || prev === 'e' };
+        const beforePrev = text[i - 2];
+        const standaloneE = (prev === 'E' || prev === 'e')
+          && (beforePrev === undefined || !WORDISH.test(beforePrev));
+        state = { in: 'single', escaped: standaloneE };
         emit(ch, 'single', i); i++;
         continue;
       }

package/src/cli/edge-plan.ts

@@ -34,6 +34,7 @@ import { compileTableContract } from './authz-compile';
 import { carryUngovernedAuthz, inheritedSequenceGrants, type GrantExemption } from './authz-reconcile';
 import { BASELINE_FILE } from './authz-baseline';
 import { classifyGeneratedStatements, classifyDestructive, partitionStatements, renderStatementHistogram } from './state-apply';
+import { statementHead, statementHeadOrSelf } from './sql-statement';
 import { fingerprintLive, fingerprintState, fingerprintModels, governedRolesForModels, stableStringify, compareStoredFingerprint, formatChangedMessage, schemaOf, FINGERPRINT_VERSION, type Fingerprint } from './schema-fingerprint';
 import { compileDeclaredState } from './declared-diff';
 import { compileTableRenames, compileTableMoves, compileRenames } from './schema-compile';
@@ -127,6 +128,23 @@ export interface EdgePlan {
    * and verify raw, as they were minted).
    */
   governedRoles?: string[];
+  /**
+   * Every grantee the models declared AT MINT, sorted — the discriminator that separates a revoke
+   * that is ordinary churn from one that is a STRIP (a revoke against a role no model grants to,
+   * so nothing can put the access back).
+   *
+   * Pinned onto the plan for the same reason `governedRoles` is: the answer must be the one the
+   * mint used, not the one the checkout happens to hold later. db:apply can run long after
+   * db:plan — across a rebase, or a hotfix to the models — and a receipt that re-reads the models
+   * at apply time marks its ⚠ lines against a declared side the plan was never verified under.
+   * The plan's own destructive breakdown reads it here too, so what db:plan prints and what
+   * db:apply prints come from one snapshot rather than two readings of a moving tree.
+   *
+   * Absent means a plan minted before this field existed: both readers degrade to their prior
+   * behaviour (the summary shows no strips; the receipt re-reads the checkout's models) rather
+   * than failing — nothing is DECIDED from this field, every gate that acts on a strip ran at mint.
+   */
+  declaredGrantees?: string[];
   /** The models-only fingerprint — context for the strong claim. Equals `to` when nothing is unmodeled. */
   declaredFingerprint: string;
   /** The edge, in db:generate's statement grammar (no held drops — mint refuses them). */
@@ -390,6 +408,23 @@ export function governedLiveFingerprint(
  * state. Pure: introspection in, plan out. Throws when the edge would hold
  * drops back — a plan must be complete to have a reachable endpoint.
  */
+/**
+ * Every grantee the models declare — the discriminator for a STRIP (a revoke against a role no
+ * model grants to has nothing to restore it from, so it carries a dropped column's ceremony).
+ *
+ * Exported because the PLAN REPORT has to mark exactly the statements the --confirm gate counts.
+ * Two copies of this loop would eventually disagree, and the direction it would disagree in is
+ * the bad one: a report calling a strip ordinary churn while the gate calls it destructive.
+ */
+export function declaredGranteesOf(models: ModelDescriptor[], opts: { schema?: string } = {}): Set<string> {
+  const grantees = new Set<string>();
+  for (const t of models.map((m) => compileTableContract(m, { schema: opts.schema }))) {
+    for (const g of Object.keys(t.grants)) grantees.add(g);
+    for (const g of Object.keys(t.columnGrants ?? {})) grantees.add(g);
+  }
+  return grantees;
+}
+
 export function mintEdgePlan(
   models: ModelDescriptor[],
   snapshot: SchemaSnapshot,
@@ -418,11 +453,7 @@ export function mintEdgePlan(
   // The grantees the models actually declare — the discriminator for a STRIP (a revoke
   // against a role no model grants to has nothing to restore it from, so it carries the
   // same ceremony as a dropped column).
-  const declaredGrantees = new Set<string>();
-  for (const t of models.map((m) => compileTableContract(m, { schema: opts.schema }))) {
-    for (const g of Object.keys(t.grants)) declaredGrantees.add(g);
-    for (const g of Object.keys(t.columnGrants ?? {})) declaredGrantees.add(g);
-  }
+  const declaredGrantees = declaredGranteesOf(models, { schema: opts.schema });
   const breakdown = partitionStatements(classified.executable, { declaredGrantees });
   const destructive = breakdown.drops.length + breakdown.narrowings.length + breakdown.strips.length;
 
@@ -444,6 +475,10 @@ export function mintEdgePlan(
     defaultAclHash: defaultAclHash(contract),
     declaredFingerprint: fingerprintModels(models, { schema: opts.schema }).hash,
     governedRoles: [...governedRoles].sort(),
+    // Pinned, not re-derived later: the receipt after the apply and the breakdown in this plan's
+    // own summary both read the declared side from HERE, so neither can drift onto a checkout
+    // whose models moved between mint and apply.
+    declaredGrantees: [...declaredGrantees].sort(),
     statements,
     executable: classified.executable.length,
     destructive,
@@ -487,7 +522,7 @@ export function tablesLeftWithoutARead(statements: readonly string[], live?: Aut
   const touched = new Set<string>();
 
   for (const statement of statements) {
-    const head = (statement.split('\n').find((l) => l.trim() !== '' && !l.trim().startsWith('--')) ?? '').trim();
+    const head = statementHead(statement);
     let m = /^DROP\s+POLICY\s+(?:IF\s+EXISTS\s+)?(\S+)\s+ON\s+(\S+?);?$/i.exec(head);
     if (m) {
       touched.add(m[2]);
@@ -627,20 +662,48 @@ export function buildPlanSummary(plan: EdgePlan, opts: { carriedBy?: string[] }
   // The shape first — a four-digit edge is reviewable as a histogram, not a wall.
   const histogram = renderStatementHistogram(classifyGeneratedStatements(plan.statements).executable);
   if (histogram) lines.push(`shape: ${histogram}`);
+  // The declared side comes off the PLAN, never off the checkout — this is the same set the mint
+  // counted `destructive` with, so every bucket below agrees with what the plan already says about
+  // itself. Both classifiers in this function read it: they partition the SAME statement stream,
+  // and handing the set to one but not the other makes the two halves of one summary disagree.
+  // Absent on a pre-field plan: every reading falls back to the old one exactly, because
+  // best-effort marking never blocks the operator.
+  const declaredOpt = plan.declaredGrantees
+    ? { declaredGrantees: new Set(plan.declaredGrantees) }
+    : {};
+  const declared = plan.declaredGrantees !== undefined;
   if (plan.destructive > 0) {
-    const { drops, narrowings } = classifyDestructive(classifyGeneratedStatements(plan.statements).executable);
+    // Without the declared side the strip bucket is empty by construction (classifyDestructive
+    // will not guess), and a strips-only plan printed `N DESTRUCTIVE — 0 drop(s), 0 narrowing type
+    // change(s)` with the statement itself missing from the list under it.
+    const { drops, narrowings, strips } = classifyDestructive(
+      classifyGeneratedStatements(plan.statements).executable,
+      declaredOpt,
+    );
+    const stripClause = declared ? `, ${strips.length} authorization strip(s)` : '';
     lines.push(
-      `! ${plan.destructive} DESTRUCTIVE statement(s) — ${drops.length} drop(s), ${narrowings.length} narrowing type change(s). Data loss carried explicitly; the apply is gated (--confirm + snapshot, approver set when declared):`,
+      `! ${plan.destructive} DESTRUCTIVE statement(s) — ${drops.length} drop(s), ${narrowings.length} narrowing type change(s)${stripClause}. Data loss carried explicitly; the apply is gated (--confirm + snapshot, approver set when declared):`,
     );
-    for (const statement of [...drops, ...narrowings]) {
-      const ddl = statement.split('\n').find((l) => l.trim() !== '' && !l.trim().startsWith('--')) ?? statement;
-      lines.push(`!   ${ddl.trim()}`);
+    for (const statement of [...drops, ...narrowings, ...strips]) {
+      lines.push(`!   ${statementHeadOrSelf(statement)}`);
     }
   }
   // Authorization removed loses no row, so it is not gated — but it decides who can SEE the
   // rows, and a plan that drops a table's only read policy leaves that table returning nothing.
   // 11 tables went dark in a real adoption plan that printed "0 notice(s)".
-  const { authzRemovals, unclassified } = partitionStatements(classifyGeneratedStatements(plan.statements).executable);
+  //
+  // Same declared side as the destructive breakdown above, and for the same reason. partitionStatements
+  // gives each statement exactly one bucket, consulting the data-loss buckets FIRST — so with the set
+  // in hand a strip lands in `strips` and is kept out of `authzRemovals`. Without it the strip is
+  // unrecognisable as such and falls through to `authzRemovals`, which is where it belongs on a
+  // pre-field plan: that is the only bucket that can hold it, and a revoke nobody can grade still
+  // has to be seen. Passing it to the classifier above but not here printed the strip TWICE — once
+  // under DESTRUCTIVE and again in the REMOVE-authorization count — and that count then disagreed
+  // with the plan's own `classification`, which the mint computed with the declared side.
+  const { authzRemovals, unclassified } = partitionStatements(
+    classifyGeneratedStatements(plan.statements).executable,
+    declaredOpt,
+  );
   // Prefer what the mint resolved against live. Recomputing here would have only the statement
   // text and would re-introduce the false positives the mint-time answer exists to avoid.
   const dark = plan.dark ?? tablesLeftWithoutARead(plan.statements);
@@ -653,8 +716,7 @@ export function buildPlanSummary(plan: EdgePlan, opts: { carriedBy?: string[] }
   if (unclassified.length > 0) {
     lines.push(`! ${unclassified.length} statement(s) could NOT be classified — read them before applying. They are not counted as additive:`);
     for (const statement of unclassified) {
-      const ddl = statement.split('\n').find((l) => l.trim() !== '' && !l.trim().startsWith('--')) ?? statement;
-      lines.push(`!   ${ddl.trim()}`);
+      lines.push(`!   ${statementHeadOrSelf(statement)}`);
     }
   }
   if (plan.unmodeled.length > 0) {

package/src/cli/index.ts

@@ -351,9 +351,9 @@ Usage:
   everystack db:seed           [--stage <name>]  Seed database on deployed Lambda (dev only)
   everystack db:reset          [--stage <name>]  Drop all schemas + re-run migrations (dev only)
   everystack db:psql           --stage <name>  Interactive ADMIN psql (IAM-gated; resolves the admin URL in-process)
-  everystack db:psql           [--stage <name>] -c <command>  Run one query via Lambda (works for private RDS)
+  everystack db:psql           [--stage <name>] -c <command>  Run one query via Lambda (read-only). Runs as the SELECT-only 'reader' role when the stage has one (db:provision --with-reader + QUERY_DATABASE_URL wired to dbPlugin's queryDatabaseUrl); WITHOUT one it runs on the OPERATOR connection, fenced only by a read-only transaction — see docs/cli.md
   everystack db:doctor         [--stage <name>] [--direct | --database-url <api> [--admin-database-url <ops>]]  Check the DB is least-privilege + RLS-subject (api vs operator connection). No flag = ops-Lambda venue (auto-falls to direct via the stage secrets if the handler has no dbPlugin). --direct = probe both connections from the stage's DATABASE_URL + ADMIN_DATABASE_URL secrets; --database-url = explicit local venue (a lone URL is probed as both)
-  everystack db:provision      --stage <name> [--direct | --database-url <url>] [--rotation-pairs]  Create the least-privilege role chain (idempotent). --rotation-pairs creates A/B pairs for live rotation
+  everystack db:provision      --stage <name> [--direct | --database-url <url>] [--rotation-pairs] [--with-reader]  Create the least-privilege role chain (idempotent). --rotation-pairs creates A/B pairs for live rotation. --with-reader adds the SELECT-only 'reader' login db:query runs as, grants it read on the declared schemas, and writes QUERY_DATABASE_URL (opt-in once, then kept converged on every re-provision)
   everystack db:provision      --rotate --stage <name> [--slot api|ops|both] [--grace 60]  Rotate credentials live (A/B role swap, no deploy, no downtime)
   everystack db:snapshot       [--stage <name>] [--instance <id>]  Take a physical RDS snapshot (instant DR point; RDS only — use db:backup for portable logical backups)
   everystack db:snapshots      [--stage <name>] [--instance <id>]  List manual RDS snapshots for the instance
@@ -364,17 +364,17 @@ Usage:
   everystack db:export         --schema <name> [--stage <name> | --database-url <url> [--out <file.dump>]] [--models <barrel>]  Schema-scoped pg_dump artifact, stamped with the DECLARED schema fingerprint (the canonical-sync export; db:swap gates on that stamp). --stage dumps the stage's private DB via the ops Lambda → S3; --database-url (explicit flag, never the env) dumps a reachable DB to a local .dump + .meta.json — the build-locally → publish → swap on-ramp
   everystack db:swap           --schema <name> --from <artifact.dump | artifact-id> [--stage <name> --direct | --database-url <url>] --confirm [--fingerprint <hash>] [--snapshot physical|logical|none] [--snapshot-ref <id>] [--rebuild-derived] [--dump-build <file.json>]  Land a schema artifact atomically: fingerprint gate → pre-flight refusals → CONFIRMED snapshot → restore into <schema>_incoming (COPY-safe rewrite) → build the paired derived layer → one txn (drop+rename+recreate app→schema FKs, re-apply authz + schema USAGE) → assertions → drop retiring. Refresh-free; app.* untouched; the derived layer is never absent. DESTRUCTIVE. The venue is EXPLICIT — DATABASE_URL in the env is refused, and --stage requires --direct (a multi-GB restore exceeds the ops-Lambda 900s clock). The rollback point defaults to a PHYSICAL RDS snapshot on a stage that exposes databaseInstanceId (no locks, no pg_dump contending with the restore) and a WAITED logical db:backup otherwise; a bare --database-url refuses without --snapshot-ref <id> or --snapshot none. docs/schema-swap.md
   everystack db:generate       [--stage <name> | --database-url <url>] [--name <label>] [--models db/models/index.ts] [--schema-out db/schema.generated.ts] [--allow-drops] [--apply] [--dry-run]  Diff models vs the live DB → next migration file, or with --apply execute it directly (one transaction, schema_log recorded, verified by re-diff — no drizzle folder needed; direct connection only; DROPs held back unless --allow-drops). --dry-run prints the edge and writes NOTHING (no migration, no journal entry, no schema refresh) — the preview verb; db:diff computes a models-vs-models edge with no database at all. The resolved --schema-out is recorded in the migration journal: later flag-less runs reuse it (flag > recorded > default), a differing flag updates the record and says so
-  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities live|public-read]  Introspect the live DB → render field() Models — THE on-ramp for an existing database: commit what it renders, then db:plan --stage <s>. EMPTY plan = adopted as it is (that commit declares the database; every later db:apply descends from it). NON-EMPTY plan = the hardening edge: review it, db:apply --plan <f> --stage <s> — no commit declares the database yet, so the reviewed plan is the ORIGIN. Render from the stage, never from a local restore of a dump. --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored). **--abilities live is the brownfield mode**: derive each model's authz from the grants and policies the database ALREADY has, and write the foreign-grantee baseline (db/authz-baseline.json) — this is what you want when adopting an existing schema. --abilities public-read stamps the common stanza (public read, admin write) uncommented — greenfield only, since on an existing database it declares public read of every table. Both are explicit generated code, never a runtime default. --govern-roles <r1,r2> (with --abilities live) transcribes the named FOREIGN roles' grants into privileges — the models then OWN them, so a fresh build recreates them; required for migration deletion when the migrations created grants to an ops/connection role. Explicit only (a re-pull must not silently govern), complete-or-refuse (a listed role holding a column-scoped grant fails the pull before anything is written). --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review; add --suggest-keys to probe the LIVE rows for functionally-unique columns (one scan per matview) and surface each as a commented .primaryKey() suggestion. docs/derived-objects.md#flipping-a-matview-to-a-materialized-table---matviews-as-tables
+  everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts | dir>] [--abilities live|public-read]  Introspect the live DB → render field() Models — THE on-ramp for an existing database: commit what it renders, then db:plan --stage <s>. EMPTY plan = adopted as it is (that commit declares the database; every later db:apply descends from it). NON-EMPTY plan = the hardening edge: review it, db:apply --plan <f> --stage <s> — no commit declares the database yet, so the reviewed plan is the ORIGIN. Render from the stage, never from a local restore of a dump. --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. --derived-out <dir> (anything not ending in .ts) splits that module by kind and schema instead — views.ts, functions-<schema>.ts, triggers.ts, index.ts barrel — for a real schema whose derived layer is otherwise one unreviewable file; refuses loudly, before writing anything, if the split files would import each other. Every model scaffolds its authz decision as comments (db:check fails until authored). **--abilities live is the brownfield mode**: derive each model's authz from the grants and policies the database ALREADY has, and write the foreign-grantee baseline (db/authz-baseline.json) — this is what you want when adopting an existing schema. --abilities public-read stamps the common stanza (public read, admin write) uncommented — greenfield only, since on an existing database it declares public read of every table. Both are explicit generated code, never a runtime default. --govern-roles <r1,r2> (with --abilities live) transcribes the named FOREIGN roles' grants into privileges — the models then OWN them, so a fresh build recreates them; required for migration deletion when the migrations created grants to an ops/connection role. Explicit only (a re-pull must not silently govern), complete-or-refuse (a listed role holding a column-scoped grant fails the pull before anything is written). --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review; add --suggest-keys to probe the LIVE rows for functionally-unique columns (one scan per matview) and surface each as a commented .primaryKey() suggestion. docs/derived-objects.md#flipping-a-matview-to-a-materialized-table---matviews-as-tables
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
   everystack db:fingerprint    [--stage <name> | --database-url <url>] [--models <barrel>] [--json]  Content-address the live base schema (tables+constraints+authz) and compare against the models — MATCH/MISMATCH (exit 1), plus the unfingerprinted-objects report
-  everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--only a,b] [--json]  Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (atomic — DDL + provenance in one transaction) and records provenance + schema_log; --apply --stage runs credential-free in the ops Lambda (no admin URL on the deployer, the db:apply twin), --apply --database-url runs direct. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive. --only <schema.name,…> restricts the run to the named objects (surgical); with --rebuild it FORCES those to rebuild from source even when the hashes show no diff — the recovery exit when a mistaken --rebaseline left a self-consistent-but-wrong provenance row (the dependency cascade rebuilds their live dependents).
+  everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--rebaseline] [--overwrite-drift] [--only a,b] [--json]  ADVANCED — you do not run this for a deploy: db:apply runs it for you (after a plan, and alone when given no --plan), and db:check runs its checkout-side gates. It is fully supported, not deprecated — scripts and CI jobs calling it directly keep working unchanged. Reach for it yourself for a surgical fix (--only <schema.name> rebuilds one object without minting a plan), an adoption move (--baseline / --rebaseline), or a hand-edit overwrite (--overwrite-drift). Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (atomic — DDL + provenance in one transaction) and records provenance + schema_log; --apply --stage runs credential-free in the ops Lambda (no admin URL on the deployer, the db:apply twin), --apply --database-url runs direct. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive. --only <schema.name,…> restricts the run to the named objects (surgical); with --rebuild it FORCES those to rebuild from source even when the hashes show no diff — the recovery exit when a mistaken --rebaseline left a self-consistent-but-wrong provenance row (the dependency cascade rebuilds their live dependents).
   everystack db:refresh        [--stage <name> | --database-url <url> | --direct] [--only a,b] [--verify-nonempty] [--list]  Refresh the declared materialized views in dependency order, credential-free. --stage runs the whole refresh in the ops Lambda on the operator connection (no URL on the operator's machine — the data-lane twin of the reconcile lane); --database-url refreshes over a local connection (dev); --stage <name> --direct resolves the stage's operator connection from its ops Lambda (credential never on argv) and refreshes CLI-side on an UNBOUNDED clock, for a matview set that exceeds the ops-Lambda 900s limit; --only refreshes a named subset (full identity or bare name); --verify-nonempty gates on populated-but-zero-rows matviews (the dark-panel check — a scoped EXISTS on just what was refreshed, so a promotion script gets the gate with no read authority) and FAILS naming any empty; --list previews the order without connecting. Plain REFRESH (ACCESS EXCLUSIVE); fail-fast, idempotent to re-run.
   everystack db:sync           [--database-url <url>] [--models <barrel>] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against the declared descriptors, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
   everystack db:diff           --from-models <barrel> [--to-models db/models/index.ts] [--allow-drops] [--check] [--json]  The state edge between two declared states, NO database: the SQL db:generate would produce, computed purely — CI plan previews (--check exits 1 on a non-empty edge) and computed rollbacks (swap the flags)
-  everystack db:plan           [--stage <name> [--direct] | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only; plans are ephemeral, never committed. VENUES: --stage runs via the ops Lambda, which reads TWICE and refuses on disagreement — agreement there is a DETECTOR, not a verification. --stage --direct resolves the stage's operator connection from its IAM-gated ops Lambda, holds it in memory only, and reads ONCE over one session: the lane for a fingerprint you intend to trust, with the credential never on argv. --database-url is the local-dev venue (same read guarantee, but against a deployed stage it puts a privileged DSN on the command line)
-  everystack db:apply          --plan <file.plan.json> [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--snapshot-ref <ref>] [--attest-lineage-lost <sha>]  Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule — it protects MERGED work: a commit on any ref that declares the live state and is not an ancestor of HEAD refuses by name, escaped git-natively by fetch + merge/rebase + re-plan; --attest-lineage-lost <sha> waives it ONLY for a declaring commit proven gone from every ref. When NO commit on ANY ref declares the live state — a database everystack never wrote, or one hand-edited since its last apply — the rule has nothing to protect: over a full, current clone that is PROVEN DRIFT, the reviewed plan is the ORIGIN, it applies with a loud warning, and the origin is recorded in schema_log so every later apply descends from it. A shallow, partial, or behind-remote clone, or a models tree that will not compile, is UNVERIFIABLE and refuses with a fetch/prune runbook), and for DESTRUCTIVE plans require --confirm always + a confirmed rollback point + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there
+  everystack db:plan           [--stage <name> [--direct] | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -] [--verbose]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only; plans are ephemeral, never committed. VENUES: --stage runs via the ops Lambda, which reads TWICE and refuses on disagreement — agreement there is a DETECTOR, not a verification. --stage --direct resolves the stage's operator connection from its IAM-gated ops Lambda, holds it in memory only, and reads ONCE over one session: the lane for a fingerprint you intend to trust, with the credential never on argv. --database-url is the local-dev venue (same read guarantee, but against a deployed stage it puts a privileged DSN on the command line) DEFAULT OUTPUT is the plain change list: '+' something is now true, '-' something is no longer true, and a '⚠ DESTRUCTIVE' line of its own when real data can be lost. Nothing else. --verbose restores the full internal report (edge summary, kind histogram, adoption and ownership reports, plan ref)
+  everystack db:apply          [--plan <file.plan.json>] [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--state-only] [--snapshot-ref <ref>] [--attest-lineage-lost <sha>] [--verbose]  THE deploy verb — it does the WHOLE job: the reviewed plan (tables, columns, grants), then ALWAYS the functions, views, matviews and triggers, against the same target, reported as one receipt. With NO --plan it does the catch-up alone (this is what replaces running db:reconcile --apply by hand). --state-only skips the catch-up for the narrow case that wants the tables alone. If the plan lands and the catch-up then fails, the exit is non-zero and the message says the table/column changes are committed and safe and gives the rerun, which retries only the catch-up. Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule — it protects MERGED work: a commit on any ref that declares the live state and is not an ancestor of HEAD refuses by name, escaped git-natively by fetch + merge/rebase + re-plan; --attest-lineage-lost <sha> waives it ONLY for a declaring commit proven gone from every ref. When NO commit on ANY ref declares the live state — a database everystack never wrote, or one hand-edited since its last apply — the rule has nothing to protect: over a full, current clone that is PROVEN DRIFT, the reviewed plan is the ORIGIN, it applies with a loud warning, and the origin is recorded in schema_log so every later apply descends from it. A shallow, partial, or behind-remote clone, or a models tree that will not compile, is UNVERIFIABLE and refuses with a fetch/prune runbook), and for DESTRUCTIVE plans require --confirm always + a confirmed rollback point + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there DEFAULT OUTPUT is the receipt: the same change lines back, then 'Applied N changes.'. --verbose restores the endpoint and plan-ref line
   everystack db:build          --database-url <url> [--models <barrel>]  Build a database FROM the models and KEEP it — the fresh-database bootstrap a deleted migration folder is replaced BY. Runs the same compose db:check proves buildability with (extensions -> schemas -> contract roles -> declared functions -> state -> derived layer), against a real target, then reports MATCH. Venue is EXPLICIT: --database-url only, never the ambient environment, because this writes a whole schema. REFUSES a database that already holds objects — evolving an existing one is db:sync (dev) or db:plan -> db:apply (a stage). Contract roles are created NOLOGIN if absent, and roles are cluster-level
-  everystack db:check          [--models <barrel>] [--schema-out <file.ts>] [--database-url <url>] [--json]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, descriptors compile), every exposed RLS-enabled table must declare a read path (no force-RLS-with-no-read landmine that goes dark on the superuser drop), and generated artifacts must MATCH regeneration byte-for-byte; with a scratch PostgreSQL it builds the state from scratch on an ephemeral database (created + dropped) and requires fingerprint MATCH. Exit 1 on any failure; never touches a real target
+  everystack db:check          [--models <barrel>] [--schema-out <file.ts>] [--database-url <url>] [--json] [--verbose]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, descriptors compile), every exposed RLS-enabled table must declare a read path (no force-RLS-with-no-read landmine that goes dark on the superuser drop), and generated artifacts must MATCH regeneration byte-for-byte; with a scratch PostgreSQL it builds the state from scratch on an ephemeral database (created + dropped) and requires fingerprint MATCH. Exit 1 on any failure; never touches a real target DEFAULT OUTPUT is ONE line: 'Up to date.' or 'N changes pending. Run db:plan to review.'. --verbose restores every finding and the from-scratch build report
   everystack db:approvers      --stage <name> [--set "cto,arn:..."] [--remove]  Declare who can DESTROY: the stage's destructive-approver set (SSM parameter, admin-writable). Destructive db:apply runs are then identity-verified (STS) against it; --set '' disables destructive applies; --remove returns the stage to ceremony-only
   everystack db:backfill       [--database-url <url>] [--dir db/backfills] [--apply] [--mark-applied <file.sql>] [--json]  One-shot data jobs in their own lane: plan shows applied (by CONTENT identity — renames/comment edits are no-ops) / pending (in order, unbounded-pass advisories) / blocked (a name that already ran in a different form — one-shot jobs are immutable). --apply runs each pending job as its own transaction, recorded in everystack.backfill_log (a failure rolls back alone, is recorded, stops the run); --mark-applied records without running. Never runs as a schema side effect; direct connection required
   everystack db:exec           <file.sql> [--stage <name> | --database-url <url>] [--schemas a,b] [--confirm]  Credential-free write SQL — the psql-piped-file replacement (or pipe SQL on stdin). Runs the whole file as ONE transaction, DML-only enforced SEMANTICALLY: a catalog digest before vs after rejects ANY schema change (however caused — a function, a DO block, dynamic SQL) by rolling the txn back. Schema changes go through db:apply / db:reconcile. Every run is recorded crash-truthfully in everystack.exec_log (intent before, per-statement rows-affected after). --stage runs in the ops Lambda (operator holds no URL); prod-tier writes require --confirm; --database-url is local-direct (--schemas scopes the digest, default public)

package/src/cli/model-wire-lane.ts

@@ -0,0 +1,143 @@
+/**
+ * The Model-derived wire-contract PREFLIGHT — the CLI half of the handshake.
+ *
+ * `db:provision`, `db:converge-ownership` and `db:reconcile --apply --stage` all compute a payload
+ * from the Models barrel and hand it to a deployed stage's ops Lambda, which acts on it against a
+ * real database: it reassigns object ownership, or creates and replaces derived objects. The CLI
+ * doing the computing and the `@everystack/cli` bundled into that Lambda are separate installs on
+ * independent release trains, so their idea of those shapes can drift.
+ *
+ * The SERVER gate is the authority (never trust a client's claim about itself). This preflight
+ * covers the half the server structurally cannot: a stage deployed BEFORE the guard existed has no
+ * code to refuse with. Its `_health` still answers — it simply omits `modelContract` — so ABSENCE
+ * is the older-stage signal and refuses exactly as hard as a mismatch.
+ *
+ * TWO functions, and the split matters when you go to test them:
+ *
+ *   `checkStageModelContract` is PURE — a `_health` answer in, a verdict and its phrasing out. No
+ *   connection, no I/O, no exit. Every rule about what counts as skew is decided here, so it can
+ *   be exercised by passing it plain objects.
+ *
+ *   `modelContractPreflight` is the ORCHESTRATION around it, and it is not pure: it invokes
+ *   `_health` over the wire, prints, and calls `process.exit(1)` on a refusal. It exists so the
+ *   commands do not each hand-roll that sequence and drift into three wordings for one skew.
+ *
+ * Sibling of `checkStageApplyContract` in apply-lane.ts, which decides the same question for
+ * db:apply's separate `APPLY_CONTRACT_VERSION`. (That command still orchestrates its own preflight
+ * inline; consolidating the two is deliberately NOT done here — the apply contract's machinery is
+ * left untouched on this branch.) The two numbers are never compared to each other.
+ */
+
+import { MODEL_WIRE_CONTRACT } from '../wire';
+import { invokeAction } from './aws';
+import { step, fail, info } from './output';
+
+/**
+ * Does the deployed stage speak THIS CLI's Model-derived wire contract?
+ *
+ * `health` is the raw `_health` answer. `verb` is the command about to dispatch, so the refusal
+ * names the thing the operator actually typed.
+ *
+ * Exact equality, never `>=`: a bump means the payload keys or a field's meaning changed, so an
+ * off-by-any peer must refuse rather than guess. A false refusal costs one redeploy; a false
+ * accept risks wrong ownership or a wrong derived object on a real database.
+ */
+export function checkStageModelContract(
+  health: unknown,
+  verb: string,
+): { ok: true } | { ok: false; reason: string } {
+  const advertised = (health as { modelContract?: unknown } | null | undefined)?.modelContract;
+  if (typeof advertised === 'number' && advertised === MODEL_WIRE_CONTRACT) return { ok: true };
+
+  if (advertised === undefined) {
+    return {
+      ok: false,
+      reason:
+        `the deployed stage does not advertise a Model-derived wire contract — its ops Lambda `
+        + `predates this handshake, so it would accept the ${verb} payload this CLI builds `
+        + `(model-wire v${MODEL_WIRE_CONTRACT}) without checking that it understands its shape. `
+        + `Deploy the stage first so its server matches this CLI; nothing was sent.`,
+    };
+  }
+
+  return {
+    ok: false,
+    reason:
+      `the deployed stage speaks model-wire contract v${String(advertised)} but this CLI speaks `
+      + `v${MODEL_WIRE_CONTRACT} — the CLI and the stage disagree about the shape of the `
+      + `Model-derived payload ${verb} sends. Deploy the stage (or align the CLI) so they match; `
+      + `nothing was sent.`,
+  };
+}
+
+/** A wire-contract refusal, raised instead of printed when the caller asked for `onRefusal: 'throw'`. */
+export class ModelContractError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ModelContractError';
+  }
+}
+
+/**
+ * The orchestration around that decision, shared by every command that dispatches a Model-derived
+ * payload to a stage: read `_health`, judge it, and exit on a refusal. One implementation and one
+ * wording, so `db:provision` and `db:reconcile` cannot drift into saying different things about
+ * the same skew.
+ *
+ * Returns a MEMOIZED runner. `db:provision` dispatches twice to the same stage (credentials, then
+ * `db:converge-ownership`), and one handshake covers both — but each dispatch still asks, so the
+ * guarantee is per-dispatch rather than a fact an earlier line has to remember to establish.
+ *
+ * An UNREACHABLE `_health` is deliberately NOT a refusal. A stage with no ops Lambda at all throws
+ * here, and that is a different failure with a much better message waiting further down (for
+ * `db:provision` it is also the path the ADMIN_DATABASE_URL auto-fallback exists for). Absence of
+ * evidence is not evidence of skew. A stage that ANSWERS and names no contract IS evidence, and
+ * refuses.
+ *
+ * `directCommand` is the venue that crosses no wire — the CLI resolves the stage's operator
+ * connection itself and runs the work locally — so a refused operator is left with somewhere to go.
+ * `directHint` carries whatever is true of that venue for THIS command only; sharing one runner
+ * must not cost a caller the specific thing its own operator needed to read.
+ *
+ * `onRefusal` decides WHO renders the refusal, and the answer belongs to the CALLER, because
+ * only the caller knows whether anything has been written yet. A call site that runs BEFORE any
+ * write — which is every original one — wants printing and exiting: the refusal already says the
+ * stage and the CLI disagree, that nothing was sent, and where the `--direct` venue is. That is
+ * `'exit'`. A call site that runs AFTER a write — `db:apply`'s
+ * function/view catch-up, once the table and column changes have committed — needs one specific
+ * sentence first: your changes are safe, here is what to rerun. A `process.exit` from in here
+ * would end the process before that could be said, so that caller asks for `'throw'`.
+ *
+ * Note the shape: the CALLER passes it. A callee that hardcodes one of the two answers on behalf
+ * of callers with opposite post-conditions is the bug this parameter exists to prevent.
+ */
+export function modelContractPreflight(opts: {
+  region: string;
+  fn: string;
+  directCommand: string;
+  /** Command-specific detail about `--direct`, appended to the hint. Omit for the generic line. */
+  directHint?: string;
+  /** REQUIRED. `'exit'` prints and exits. `'throw'` hands the caller a `ModelContractError`. */
+  onRefusal: 'exit' | 'throw';
+}): (verb: string) => Promise<void> {
+  let verified = false;
+  return async (verb: string): Promise<void> => {
+    if (verified) return;
+    step("Verifying the deployed stage speaks this CLI's Model-derived wire contract...");
+    const health = await invokeAction(opts.region, opts.fn, '_health', {}).catch(() => null);
+    if (health === null) return;
+    const verdict = checkStageModelContract(health, verb);
+    if (!verdict.ok) {
+      // One wording for both exits — a thrown refusal and a printed one must never drift.
+      const directLine =
+        `The --direct venue crosses no wire (the CLI resolves the stage's operator connection `
+        + `internally and runs the work itself): ${opts.directCommand}`
+        + (opts.directHint ? ` — ${opts.directHint}` : '');
+      if (opts.onRefusal === 'throw') throw new ModelContractError(`${verdict.reason} ${directLine}`);
+      fail(`REFUSED: ${verdict.reason}`);
+      info(directLine);
+      process.exit(1);
+    }
+    verified = true;
+  };
+}

package/src/cli/output.ts

@@ -47,3 +47,15 @@ function say(line: string): void {
   if (stdoutReserved) console.error(line);
   else console.log(line);
 }
+
+/**
+ * A line printed EXACTLY as given \u2014 no marker, no indent of ours.
+ *
+ * The default reports (plain-output.ts) own their own shape: a header, a blank line, indented
+ * change lines, a verdict. `info` would prepend two spaces to every one of them and turn a
+ * designed block into a ragged one. Everything else about `say` still applies, so `--out -`
+ * keeps moving the report off stdout.
+ */
+export function line(text: string): void {
+  say(text);
+}