@everystack/cli 0.4.99 → 0.4.100

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.100] - 2026-10-16
+
+### Added
+
+- check() takes an explicit constraint name; db:pull keeps a live name
+
+### Fixed
+
+- db:apply runs a rename-only plan
+
+### Documentation
+
+- a check folded into .validate() takes the field check name
+
 ## [0.4.99] - 2026-10-14
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.99",
+  "version": "0.4.100",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -145,7 +145,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.4.21"
+    "@everystack/model": "0.4.22"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.4.0",

package/src/cli/apply-execute.ts

@@ -73,6 +73,7 @@ import {
 import { validationPendingReason, pendingValidationsAreSafe } from './apply-refusals';
 import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply';
 import { checkPlanPrecondition, planHash, defaultAclHash, type EdgePlan } from './edge-plan';
+import { renameEdgeVerdict } from './catalog-rename';
 import type { DescentLedgerRow, LedgerRead } from './git-descent';
 
 /**
@@ -477,7 +478,20 @@ export async function executeApplyPlan(
   }
 
   if (live === plan.toFingerprint) {
-    return { status: 'already-applied', liveFingerprint: live };
+    // The hash is blind to a catalog rename (a check is keyed by predicate, an index or key by
+    // content), so a plan of renames alone has from == to == live whether or not it ran. Only
+    // then do the names decide, read from the same snapshot as the lock. Not landed: fall
+    // through, and every gate below runs. Half landed, or in a shape the plan never predicted:
+    // stale. Everything else is today's idempotent re-apply.
+    const verdict = plan.fromFingerprint === plan.toFingerprint
+      ? renameEdgeVerdict(plan.statements, before)
+      : { verdict: 'not-renames' as const };
+    if (verdict.verdict === 'stale') {
+      const reason = `this plan is stale: ${verdict.reason}. Re-mint with db:plan.`;
+      await recordRefusal(runner, plan, live, 'rename edge', reason, options);
+      return { status: 'refused', liveFingerprint: live, reason };
+    }
+    if (verdict.verdict !== 'unsettled') return { status: 'already-applied', liveFingerprint: live };
   }
   const pre = checkPlanPrecondition(plan, live);
   if (!pre.ok) {

package/src/cli/catalog-rename.ts

@@ -0,0 +1,115 @@
+/**
+ * catalog-rename — the catalog-only renames the planner emits, their parser, and the verdict
+ * db:apply reads from them.
+ *
+ * A rename of a check, a foreign key or an index changes no fingerprint: a check is hashed by its
+ * predicate and an index or key by its content. So a plan whose ONLY change is such a rename has
+ * from == to == live, and the endpoint cannot tell a rename that ran from one that did not. The
+ * live names can. The renderer and the parser live side by side here so they cannot drift; the
+ * parser accepts exactly what the renderer writes and nothing else.
+ */
+
+import type { SchemaSnapshot } from './schema-introspect';
+import { isPureComment } from './sql-statement';
+
+/** The same quoting schema-diff uses for every identifier it emits. */
+const quote = (name: string): string => `"${name}"`;
+
+/** `public.orders` → `public.`; an unqualified table carries no qualifier. */
+const schemaPrefix = (table: string): string => (table.includes('.') ? `${table.split('.')[0]}.` : '');
+
+export interface RenameChange {
+  /** Schema-qualified, as the snapshot spells it (`public.orders`). */
+  table: string;
+  from: string;
+  to: string;
+}
+
+/** `ALTER TABLE … RENAME CONSTRAINT` — catalog-only and instant; the constraint keeps its identity. */
+export function renderConstraintRename(change: RenameChange): string {
+  return `ALTER TABLE ${change.table} RENAME CONSTRAINT ${quote(change.from)} TO ${quote(change.to)};`;
+}
+
+/** `ALTER INDEX … RENAME TO` — no rebuild. The schema qualifies the OLD name only. */
+export function renderIndexRename(change: RenameChange): string {
+  return `ALTER INDEX ${schemaPrefix(change.table)}${quote(change.from)} RENAME TO ${quote(change.to)};`;
+}
+
+export type CatalogRename =
+  | { kind: 'constraint'; table: string; from: string; to: string }
+  /** ALTER INDEX names no table — an index name is unique within its schema, so the schema is the scope. */
+  | { kind: 'index'; schema: string; from: string; to: string };
+
+const IDENT = '"([^"]*)"';
+const CONSTRAINT_RE = new RegExp(`^ALTER TABLE (\\S+) RENAME CONSTRAINT ${IDENT} TO ${IDENT};$`);
+const INDEX_RE = new RegExp(`^ALTER INDEX (?:([^\\s."]+)\\.)?${IDENT} RENAME TO ${IDENT};$`);
+
+/** The rename a statement is, if it is exactly one the renderers above produce; otherwise null. */
+export function parseCatalogRename(sql: string): CatalogRename | null {
+  const c = CONSTRAINT_RE.exec(sql);
+  if (c) return { kind: 'constraint', table: c[1], from: c[2], to: c[3] };
+  const i = INDEX_RE.exec(sql);
+  // An unqualified ALTER INDEX resolves through search_path; the renderer only writes one for an
+  // unqualified table, which the snapshot spells as `public`.
+  if (i) return { kind: 'index', schema: i[1] ?? 'public', from: i[2], to: i[3] };
+  return null;
+}
+
+export type RenameEdgeVerdict =
+  /** Empty, or some statement is not a recognized rename — the names have nothing to say. */
+  | { verdict: 'not-renames' }
+  /** Every rename already landed: `to` present, `from` absent. */
+  | { verdict: 'settled' }
+  /** No rename has landed: `from` present, `to` absent. The edge still has to run. */
+  | { verdict: 'unsettled' }
+  /** Anything else — the plan describes neither the database before it nor after it. */
+  | { verdict: 'stale'; reason: string };
+
+/**
+ * Where each rename in the edge stands in the BEFORE snapshot (the one the lock was computed
+ * from). Only an edge made entirely of recognized renames gets a verdict other than
+ * `not-renames`; one rename in an odd state, or a mix of landed and not, makes the plan stale.
+ */
+export function renameEdgeVerdict(statements: readonly string[], before: SchemaSnapshot): RenameEdgeVerdict {
+  // A comment is never run, and the planner writes them beside real changes (an inert
+  // renamedFrom notice, a held drop). They must not hide a rename edge from the names.
+  const real = statements.filter((sql) => !isPureComment(sql));
+  if (real.length === 0) return { verdict: 'not-renames' };
+  const renames: CatalogRename[] = [];
+  for (const sql of real) {
+    const rename = parseCatalogRename(sql);
+    if (!rename) return { verdict: 'not-renames' };
+    renames.push(rename);
+  }
+
+  const settled: string[] = [];
+  const unsettled: string[] = [];
+  for (const rename of renames) {
+    let present: Set<string>;
+    let where: string;
+    if (rename.kind === 'constraint') {
+      const table = before.tables.find((t) => t.table === rename.table);
+      if (!table) return { verdict: 'stale', reason: `table ${rename.table} does not exist` };
+      present = new Set([...table.checks, ...table.foreignKeys, ...table.uniques].map((c) => c.name));
+      where = `on ${rename.table}`;
+    } else {
+      present = new Set(before.tables
+        .filter((t) => t.table.startsWith(`${rename.schema}.`))
+        .flatMap((t) => t.indexes.map((ix) => ix.name)));
+      where = `in schema ${rename.schema}`;
+    }
+    const hasFrom = present.has(rename.from);
+    const hasTo = present.has(rename.to);
+    const label = `"${rename.from}" → "${rename.to}"`;
+    if (hasTo && !hasFrom) settled.push(label);
+    else if (hasFrom && !hasTo) unsettled.push(label);
+    else if (hasFrom && hasTo) return { verdict: 'stale', reason: `both "${rename.from}" and "${rename.to}" exist ${where}` };
+    else return { verdict: 'stale', reason: `neither "${rename.from}" nor "${rename.to}" exists ${where}` };
+  }
+  if (unsettled.length === 0) return { verdict: 'settled' };
+  if (settled.length === 0) return { verdict: 'unsettled' };
+  return {
+    verdict: 'stale',
+    reason: `some of its renames are already applied (${settled.join(', ')}) and some are not (${unsettled.join(', ')})`,
+  };
+}

package/src/cli/model-render.ts

@@ -24,7 +24,7 @@ import { generatedIndexName, generatedForeignKeyName } from './schema-compile';
 // The soft-delete RULE itself — one boolean combination, shared with `defineModel`'s refusal.
 // Only the FACT EXTRACTION is duplicated here (this renderer holds text, not descriptors);
 // the rule is not, so the two surfaces cannot drift on when a declaration is required.
-import { needsSoftDeleteDeclaration, privilegesGrantDelete } from '@everystack/model';
+import { needsSoftDeleteDeclaration, privilegesGrantDelete, positionalCheckName } from '@everystack/model';
 
 /**
  * Reverse a CHECK predicate back into the `.validate(z…)` that produced it — the inverse of
@@ -599,8 +599,18 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
   for (const u of table.uniques) {
     if (u.columns.length > 1) items.push(`unique(${u.columns.map((c) => tsLiteral(toCamelCase(c))).join(', ')})`);
   }
+  // R9 — a check keeps the name the database has. Said only when it is NOT the positional name
+  // the compiler would give it: position counts only the checks rendered bare, exactly as the
+  // compiler counts only unnamed ones, so every pulled check compiles back to its live name.
+  let position = 0;
   for (const ck of checks) {
-    items.push(`check(sql\`${normalizeCheck(ck.expr)}\`)`);
+    const predicate = `sql\`${normalizeCheck(ck.expr)}\``;
+    if (ck.name === positionalCheckName(bareName(table.table), position)) {
+      items.push(`check(${predicate})`);
+      position++;
+    } else {
+      items.push(`check(${predicate}, { name: ${tsLiteral(ck.name)} })`);
+    }
   }
   for (const ix of table.indexes) {
     // Plain entries render as field keys; canonical-text entries (expressions, DESC,
@@ -655,9 +665,15 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
   const validates = new Map<string, string>();
   const columnNames = new Set(table.columns.map((c) => c.name));
   const tableChecks: CheckConstraint[] = [];
+  // A `.validate()` compiles to a CHECK named `<table>_<column>_check`. When a DIFFERENT live
+  // check already holds that name, folding this one into the field would give the model two
+  // constraints under one name, so it stays a table-level check and keeps its own.
+  const liveCheckNames = new Set(table.checks.map((ck) => ck.name));
   for (const ck of table.checks) {
     const v = checkToValidate(ck.expr);
-    if (v && columnNames.has(v.column) && !validates.has(v.column)) validates.set(v.column, v.zod);
+    const fieldCheckName = v ? `${bareName(table.table)}_${v.column}_check` : '';
+    const nameFree = ck.name === fieldCheckName || !liveCheckNames.has(fieldCheckName);
+    if (v && columnNames.has(v.column) && !validates.has(v.column) && nameFree) validates.set(v.column, v.zod);
     else tableChecks.push(ck);
   }
 

package/src/cli/schema-compile.ts

@@ -20,6 +20,7 @@
  */
 
 import type { ModelDescriptor, FieldSpec, SequenceDescriptor } from '@everystack/model';
+import { positionalCheckName } from '@everystack/model';
 import type { TableSchema, EnumType, SequenceSchema, UniqueConstraint, CheckConstraint, IndexSchema, ForeignKey } from './schema-introspect';
 import { nextvalSequence, identityClause, type RenameMap } from './schema-diff';
 import { normalizeDeparsedExpr } from './deparse-normal';
@@ -59,6 +60,13 @@ export function modelConstraintSpecs(model: ModelDescriptor): { uniques: UniqueC
   const indexes: IndexSchema[] = [];
   let checkIndex = 0;
   const usedIndexNames = new Set<string>();
+  // A field's `.validate()` CHECK is named `<table>_<column>_check`; a declared table check may
+  // not take that name, or CREATE TABLE fails with two constraints under one name.
+  const fieldCheckNames = new Map<string, string>();
+  for (const [key, field] of Object.entries(model.fields)) {
+    const col = toSnakeCase(key);
+    if (fieldCheckPredicate(col, field.spec)) fieldCheckNames.set(`${model.table}_${col}_check`, key);
+  }
   for (const con of model.constraints) {
     if (con.kind === 'unique') {
       const cols = con.columns.map(toSnakeCase);
@@ -67,7 +75,20 @@ export function modelConstraintSpecs(model: ModelDescriptor): { uniques: UniqueC
       // Normalized like the live producer (schema-introspect): a model that transcribes a
       // pulled predicate must compare equal to the database it came from, whichever of the
       // two equivalent deparse spellings each side happens to hold. See deparse-normal.ts.
-      checks.push({ name: `${model.table}_check_${checkIndex++}`, expr: normalizeDeparsedExpr(con.predicate) });
+      //
+      // A DECLARED name is used verbatim and takes no position, so naming one check never
+      // renames its unnamed siblings; defineModel already refused duplicates and collisions
+      // with a positional name.
+      if (con.name !== undefined && fieldCheckNames.has(con.name)) {
+        throw new Error(
+          `model '${model.table}': check(sql\`${con.predicate}\`) is named '${con.name}', the name of the CHECK that field '${fieldCheckNames.get(con.name)}'.validate() compiles to. Choose another name.`,
+        );
+      }
+      checks.push({
+        name: con.name ?? positionalCheckName(model.table, checkIndex++),
+        expr: normalizeDeparsedExpr(con.predicate),
+        ...(con.name !== undefined ? { nameDeclared: true } : {}),
+      });
     } else if (con.kind === 'index') {
       // Plain entries are field keys → snake_cased; raw sql`` entries (expressions,
       // DESC, opclass) pass verbatim — they are already SQL (Brick E).

package/src/cli/schema-diff.ts

@@ -33,6 +33,7 @@ import type {
   IndexSchema,
   SequenceSchema,
 } from './schema-introspect';
+import { renderConstraintRename, renderIndexRename } from './catalog-rename';
 
 // ---------------------------------------------------------------------------
 // The change set.
@@ -849,8 +850,12 @@ export function foreignKeyContentKey(
  * same predicate is the same check no matter what it's called, so a pulled check (whose DB
  * name we didn't choose) re-generates clean. A changed predicate drops the old (by its real
  * name) and adds the new.
+ *
+ * R9, the CHECK half of B3/A8: a predicate match whose DECLARED name disagrees with the live
+ * one is the same check under another name — `RENAME CONSTRAINT`, catalog-only, no re-scan.
+ * An undeclared (positional) name never renames the database.
  */
-function diffChecks(d: TableSchema, c: TableSchema, dropConstraints: SchemaChange[], addConstraints: SchemaChange[]): void {
+function diffChecks(d: TableSchema, c: TableSchema, dropConstraints: SchemaChange[], addConstraints: SchemaChange[], renames: SchemaChange[]): void {
   const desiredByPred = new Map(d.checks.map((ck) => [normalizeCheck(ck.expr), ck]));
   const currentByPred = new Map(c.checks.map((ck) => [normalizeCheck(ck.expr), ck]));
   // Paren-blind lookup, diagnostic only (see diffIndexes): a compound CHECK churns for the
@@ -860,7 +865,11 @@ function diffChecks(d: TableSchema, c: TableSchema, dropConstraints: SchemaChang
     if (!desiredByPred.has(pred)) dropConstraints.push({ kind: 'dropConstraint', table: d.table, name: ck.name });
   }
   for (const [pred, ck] of desiredByPred) {
-    if (currentByPred.has(pred)) continue;
+    const live = currentByPred.get(pred);
+    if (live) {
+      if (ck.nameDeclared && live.name !== ck.name) renames.push({ kind: 'renameConstraint', table: d.table, from: live.name, to: ck.name });
+      continue;
+    }
     const twin = currentByParenBlind.get(stripAllParens(ck.expr));
     // Annotate only a twin that is itself being dropped (no exact desired match) — a real churn.
     const churning = twin && !desiredByPred.has(normalizeCheck(twin.expr));
@@ -921,7 +930,7 @@ function diffConstraints(d: TableSchema, c: TableSchema, dropConstraints: Schema
     for (const cur of bucket) dropConstraints.push({ kind: 'dropConstraint', table: d.table, name: cur.name });
   }
 
-  diffChecks(d, c, dropConstraints, addConstraints);
+  diffChecks(d, c, dropConstraints, addConstraints, renames);
 
   // Primary key: a first-time add is safe; any other change needs the existing
   // constraint's name to drop it (which the snapshot discards), so it is surfaced.
@@ -1170,18 +1179,17 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string | string[] {
     }
     case 'renameConstraint':
       // Catalog-only and instant — the constraint and its backing index keep their identity.
-      return `ALTER TABLE ${change.table} RENAME CONSTRAINT ${quote(change.from)} TO ${quote(change.to)};`;
+      // Rendered beside its parser: db:apply reads this exact text back (catalog-rename).
+      return renderConstraintRename(change);
     case 'redefineIndex': {
       // Same statement as a removal; a DIFFERENT decision, which is why it is a different kind.
       const schema = change.table.includes('.') ? `${change.table.split('.')[0]}.` : '';
       return `DROP INDEX ${schema}${quote(change.name)};`;
     }
-    case 'renameIndex': {
-      // Non-destructive and instant — a catalog rename, no rebuild. The schema qualifier comes
-      // from the table; ALTER INDEX takes it on the OLD name only.
-      const schema = change.table.includes('.') ? `${change.table.split('.')[0]}.` : '';
-      return `ALTER INDEX ${schema}${quote(change.from)} RENAME TO ${quote(change.to)};`;
-    }
+    case 'renameIndex':
+      // Non-destructive and instant — a catalog rename, no rebuild. Rendered beside its parser:
+      // db:apply reads this exact text back (catalog-rename).
+      return renderIndexRename(change);
     case 'enumValuesChanged':
       return `-- NOTICE: enum ${quote(change.name)} values changed ([${change.from.join(', ')}] → [${change.to.join(', ')}]) in a way Postgres can't apply in place (a removal, reorder, or rename). ADD VALUE only appends; reshaping an enum needs a manual type swap (create new type, ALTER COLUMN ... TYPE using a cast, drop old).`;
     case 'createSequence':

package/src/cli/schema-introspect.ts

@@ -88,6 +88,8 @@ export interface CheckConstraint {
   name: string;
   /** The predicate text, as `pg_get_constraintdef` deparses it. */
   expr: string;
+  /** The name was DECLARED (`check(sql, { name })`), not positional — same rule as {@link IndexSchema.nameDeclared}. */
+  nameDeclared?: boolean;
 }
 
 /** A standalone index (NOT one backing a PK or UNIQUE constraint — those are excluded). */