@everystack/cli 0.3.31 → 0.4.0

package/src/cli/model-render.ts

@@ -16,6 +16,7 @@
  */
 
 import type { SchemaSnapshot, TableSchema, ColumnSchema, CheckConstraint } from './schema-introspect.js';
+import type { DerivedRenderResult } from './derived-render.js';
 import { normalizeDefault, normalizeCheck } from './schema-diff.js';
 
 /**
@@ -59,6 +60,47 @@ export function checkToValidate(expr: string): { column: string; zod: string } |
 export interface RenderOptions {
   /** Only pull tables in this Postgres schema (others are framework-managed). Default: `public`. */
   schema?: string;
+  /**
+   * The read-model scaffold. Default `'commented'`: every model carries the authz decision
+   * as a commented stanza (same guidance as the db:check gate — the model fails the gate
+   * until it is authored). A preset name (`'public-read'`) stamps that stanza uncommented
+   * into every rendered model — an explicit, one-shot, operator-invoked choice that lands
+   * as reviewable code. Grants are authored, never inherited; there is no runtime default.
+   */
+  abilities?: string;
+  /** The rendered derived layer (B5) — rides the barrel: block after the models,
+   *  sequences/derived arrays on the module wrapper, symbols on the import header. */
+  derived?: DerivedRenderResult;
+}
+
+/**
+ * The `--abilities` presets db:pull can stamp. Deliberately few: `public-read` is the
+ * dominant brownfield shape (public reference data, admin-managed). Anything else is a
+ * per-model edit — the decision belongs in the file, not in a flag grammar.
+ */
+export const ABILITY_PRESETS: Record<string, string> = {
+  'public-read': `abilities: [can('read'), can('manage', { role: 'admin' })],`,
+};
+
+/**
+ * The scaffold stanza for one model: the commented decision surface (guide text says the
+ * same thing the db:check gate failure says — one voice, two doorways), or a preset
+ * stamped uncommented. An unknown preset throws — grants are authored, never guessed.
+ */
+function abilitiesStanza(mode: string): string {
+  if (mode === 'commented') {
+    return [
+      '  // Declare the read model — db:check fails this model until its authz is authored:',
+      `  // abilities: [can('read')],                          // public data`,
+      `  // abilities: [can('read', { owner: '<column>' })],   // rows owned by a user`,
+      '  // private: true,                                     // not part of the data API',
+    ].join('\n');
+  }
+  const preset = ABILITY_PRESETS[mode];
+  if (!preset) {
+    throw new Error(`Unknown --abilities preset '${mode}' — known: ${Object.keys(ABILITY_PRESETS).join(', ')} (or omit the flag for the commented scaffold).`);
+  }
+  return `  ${preset}`;
 }
 
 /** `format_type` → the `field.*()` factory that produces it (the non-parameterized types). */
@@ -210,8 +252,11 @@ function renderField(table: TableSchema, col: ColumnSchema, known: Set<string>,
 
   if (col.default != null && !serial) {
     const d = renderDefault(col.default);
-    if (d) expr += d;
-    else comment += ` // TODO: unmapped default ${col.default}`;
+    // No builder maps it → declare it verbatim with the escape hatch. RAW, not the
+    // normalized form — stripping a trailing cast here could change semantics
+    // (`'7 days'::interval`); the diff normalizes both sides for comparison instead.
+    // Drift closed by construction: pull output converges instead of shedding a TODO.
+    expr += d ?? `.defaultSql(sql\`${col.default}\`)`;
   }
 
   const validate = validates.get(col.name);
@@ -236,8 +281,14 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
     items.push(`check(sql\`${normalizeCheck(ck.expr)}\`)`);
   }
   for (const ix of table.indexes) {
-    let s = `index(${ix.columns.map((c) => tsLiteral(toCamelCase(c))).join(', ')})`;
+    // Plain entries render as field keys; canonical-text entries (expressions, DESC,
+    // opclass) render as raw sql`` args — the same form the builder declares (Brick E).
+    const entry = (c: string): string =>
+      /^[a-z_][a-z0-9_$]*$/i.test(c) ? tsLiteral(toCamelCase(c)) : `sql\`${c}\``;
+    let s = `index(${ix.columns.map(entry).join(', ')})`;
+    if (ix.using) s += `.using(${tsLiteral(ix.using)})`;
     if (ix.unique) s += '.unique()';
+    if (ix.include?.length) s += `.include(${ix.include.map((c) => tsLiteral(toCamelCase(c))).join(', ')})`;
     if (ix.where) s += `.where(sql\`${normalizeCheck(ix.where)}\`)`;
     items.push(s);
   }
@@ -261,7 +312,7 @@ function renderConstraintsBlock(table: TableSchema, checks: CheckConstraint[], k
 }
 
 /** One `export const X = defineModel(...)` block for a table. */
-export function renderModelBlock(table: TableSchema, known: Set<string>, enums: Map<string, string[]> = new Map()): string {
+export function renderModelBlock(table: TableSchema, known: Set<string>, enums: Map<string, string[]> = new Map(), abilities = 'commented'): string {
   // A CHECK that reverses to a single field's .validate() is rendered on the field (ergonomic);
   // the rest stay table-level check(). Both round-trip — this only chooses the nicer form.
   const validates = new Map<string, string>();
@@ -275,23 +326,52 @@ export function renderModelBlock(table: TableSchema, known: Set<string>, enums:
 
   const fields = table.columns.map((c) => renderField(table, c, known, enums, validates)).join('\n');
   const constraints = renderConstraintsBlock(table, tableChecks, known);
+  // The authz decision renders FIRST — before fields — because it is the first thing a
+  // reviewer must resolve about a model (and where the field-report consumer's codemod
+  // put it, proving the position is mechanical-edit-friendly).
+  const stanza = abilitiesStanza(abilities);
 
-  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n  fields: {\n${fields}\n  },${constraints}\n});`;
+  return `export const ${modelVarName(table.table)} = defineModel('${bareName(table.table)}', {\n${stanza}\n  fields: {\n${fields}\n  },${constraints}\n});`;
 }
 
 /** The `import` lines a rendered body needs — only what it actually uses, so the file reads clean. */
-function importHeader(body: string): string {
+function importHeader(body: string, extra: string[] = []): string {
   const symbols = ['defineModel', 'field'];
+  // `can` only when a stanza is stamped UNCOMMENTED (line starts with spaces, not `//`) —
+  // the commented scaffold must not leave an unused import behind.
+  if (/^\s*abilities: \[can\(/m.test(body)) symbols.push('can');
   if (/\bunique\(/.test(body)) symbols.push('unique');
   if (/\bcheck\(/.test(body)) symbols.push('check');
   if (/\bindex\(/.test(body)) symbols.push('index');
   if (/\bforeignKey\(/.test(body)) symbols.push('foreignKey');
+  if (/\bdefineModule\(/.test(body)) symbols.push('defineModule');
   if (/\bsql`/.test(body)) symbols.push('sql');
+  for (const s of extra) if (!symbols.includes(s)) symbols.push(s);
   const imports = [`import { ${symbols.join(', ')} } from '@everystack/model';`];
   if (/\.validate\(/.test(body)) imports.push(`import { z } from 'zod';`);
   return imports.join('\n');
 }
 
+/** The barrel's module wrapper: models always; sequences/derived when the pull found any (B5). */
+function moduleFooter(modelNames: string[], derived?: DerivedRenderResult, multiline = false): string {
+  const models = multiline
+    ? `export const models = [\n${modelNames.map((n) => `  ${n},`).join('\n')}\n];`
+    : `export const models = [${modelNames.join(', ')}];`;
+  const parts = [models];
+  const keys = ['models'];
+  if (derived?.sequenceNames.length) {
+    parts.push(`export const sequences = [${derived.sequenceNames.join(', ')}];`);
+    keys.push('sequences');
+  }
+  if (derived?.names.length) {
+    parts.push(`export const derived = [${derived.names.join(', ')}];`);
+    keys.push('derived');
+  }
+  parts.push(`export const appModule = defineModule({ ${keys.join(', ')} });`);
+  parts.push(`export const modules = [appModule];`);
+  return parts.join('\n\n');
+}
+
 /**
  * Render a whole snapshot as a single Models module: the import, one block per table (scoped
  * to `opts.schema`), and the `models` array the rest of the framework consumes. The tables
@@ -303,11 +383,16 @@ export function renderModelSource(snapshot: SchemaSnapshot, opts: RenderOptions
   const known = new Set(tables.map((t) => bareName(t.table)));
   const enums = new Map((snapshot.enums ?? []).map((e) => [e.name, e.values]));
 
-  const blocks = tables.map((t) => renderModelBlock(t, known, enums));
-  const body = blocks.join('\n\n');
+  const blocks = tables.map((t) => renderModelBlock(t, known, enums, opts.abilities ?? 'commented'));
+  // The derived layer (B5): sequences + views/matviews/functions, after the models they
+  // reference, before the module wrapper that composes all three.
+  if (opts.derived?.block) blocks.push(opts.derived.block);
+
+  // Module composition is the norm: the pulled barrel exports `modules` alongside `models`,
+  // so a fresh brownfield project lands on the same shape the framework composes.
+  const footer = moduleFooter(tables.map((t) => modelVarName(t.table)), opts.derived);
 
-  const header = importHeader(body);
-  const footer = `export const models = [${tables.map((t) => modelVarName(t.table)).join(', ')}];`;
+  const header = importHeader([...blocks, footer].join('\n\n'), opts.derived?.imports ?? []);
 
   return [header, ...blocks, footer].join('\n\n') + '\n';
 }
@@ -349,7 +434,7 @@ export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions =
   const enums = new Map((snapshot.enums ?? []).map((e) => [e.name, e.values]));
 
   const files: RenderedModelFile[] = tables.map((t) => {
-    const block = renderModelBlock(t, known, enums);
+    const block = renderModelBlock(t, known, enums, opts.abilities ?? 'commented');
     const crossImports = referencedTables(t, known).map(
       (target) => `import { ${modelVarName(target)} } from './${bareName(target).replace(/_/g, '-')}';`,
     );
@@ -357,11 +442,19 @@ export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions =
     return { file: modelFileName(t.table), source: `${header}\n\n${block}\n` };
   });
 
+  // The index carries the module wrapper (composition is the norm) and the derived layer
+  // (B5 — it references the model variables the index imports); model files carry only
+  // their own model.
   const names = tables.map((t) => modelVarName(t.table));
+  const modelSymbols = ['defineModule', ...(opts.derived?.imports ?? [])];
   const index = [
-    names.map((n, i) => `import { ${n} } from './${bareName(tables[i].table).replace(/_/g, '-')}';`).join('\n'),
+    [
+      `import { ${modelSymbols.join(', ')} } from '@everystack/model';`,
+      ...names.map((n, i) => `import { ${n} } from './${bareName(tables[i].table).replace(/_/g, '-')}';`),
+    ].join('\n'),
     `export {\n${names.map((n) => `  ${n},`).join('\n')}\n};`,
-    `export const models = [\n${names.map((n) => `  ${n},`).join('\n')}\n];`,
+    ...(opts.derived?.block ? [opts.derived.block] : []),
+    moduleFooter(names, opts.derived, true),
   ].join('\n\n');
   files.push({ file: 'index.ts', source: index + '\n' });
 

package/src/cli/models-path.ts

@@ -1,7 +1,7 @@
 /**
  * models-path — where the Models barrel lives.
  *
- * One home for schema: `db/models/` (state) beside `db/sql/` (compute). The
+ * One home for schema: `db/models/` — state (tables) and compute (descriptors). The
  * CLI looks there first, falling back to the legacy top-level `models/` so
  * existing consumers keep working without a flag. An explicit `--models`
  * always wins. When neither home exists, the NEW home is returned so error

package/src/cli/pipeline-path.ts

@@ -1,7 +1,7 @@
 /**
  * pipeline-path — where the consumer's pipeline definition lives.
  *
- * Beside the schema homes (`db/models/`, `db/sql/`, `db/backfills/`), the
+ * Beside the schema homes (`db/models/`, `db/backfills/`), the
  * pipeline is authored at `db/pipeline.ts` (or `db/pipeline/index.ts`),
  * exporting a `pipeline` built with definePipeline. An explicit `--pipeline`
  * always wins; when neither home exists the primary is returned so error

package/src/cli/schema-compile.ts

@@ -19,12 +19,12 @@
  * Input is a `@everystack/model` ModelDescriptor (type-only — no runtime dep).
  */
 
-import type { ModelDescriptor, FieldSpec } from '@everystack/model';
-import type { TableSchema, EnumType, UniqueConstraint, CheckConstraint, IndexSchema, ForeignKey } from './schema-introspect.js';
-import type { RenameMap } from './schema-diff.js';
+import type { ModelDescriptor, FieldSpec, SequenceDescriptor } from '@everystack/model';
+import type { TableSchema, EnumType, SequenceSchema, UniqueConstraint, CheckConstraint, IndexSchema, ForeignKey } from './schema-introspect.js';
+import { nextvalSequence, type RenameMap } from './schema-diff.js';
 
 /** `authorId` -> `author_id`. SQL identifiers are snake_case. */
-function toSnakeCase(name: string): string {
+export function toSnakeCase(name: string): string {
   return name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
 }
 
@@ -48,20 +48,25 @@ export function modelConstraintSpecs(model: ModelDescriptor): { uniques: UniqueC
     } else if (con.kind === 'check') {
       checks.push({ name: `${model.table}_check_${checkIndex++}`, expr: con.predicate });
     } else if (con.kind === 'index') {
-      const cols = con.columns.map(toSnakeCase);
+      // Plain entries are field keys → snake_cased; raw sql`` entries (expressions,
+      // DESC, opclass) pass verbatim — they are already SQL (Brick E).
+      const cols = con.columns.map((c, i) => (con.rawPositions?.[i] ? c : toSnakeCase(c)));
       // Disambiguate multiple indexes over the same columns — e.g. a full index plus a
       // partial one (`familyId` and `familyId WHERE status='active'`): the name must be
       // unique within the table for CREATE to succeed. The diff matches indexes by content
-      // (columns + uniqueness + predicate), never by name, so the suffix never affects the
-      // round-trip. Declaration order is deterministic, so the name is stable across calls.
-      let name = `${model.table}_${cols.join('_')}_index`;
-      for (let n = 2; usedIndexNames.has(name); n++) name = `${model.table}_${cols.join('_')}_index_${n}`;
+      // (entries + uniqueness + predicate + method + INCLUDE), never by name, so the suffix
+      // never affects the round-trip. Raw entries sanitize to identifier-safe name parts.
+      const nameParts = cols.map((c) => c.replace(/\W+/g, '_').replace(/^_+|_+$/g, ''));
+      let name = `${model.table}_${nameParts.join('_')}_index`;
+      for (let n = 2; usedIndexNames.has(name); n++) name = `${model.table}_${nameParts.join('_')}_index_${n}`;
       usedIndexNames.add(name);
       indexes.push({
         name,
         columns: cols,
         unique: con.isUnique,
         ...(con.predicate ? { where: con.predicate } : {}),
+        ...(con.method ? { using: con.method } : {}),
+        ...(con.includeColumns?.length ? { include: con.includeColumns.map(toSnakeCase) } : {}),
       });
     }
   }
@@ -209,6 +214,7 @@ function defaultExpr(spec: FieldSpec): string | null {
   switch (spec.defaultKind) {
     case 'now': return 'now()';
     case 'random': return 'gen_random_uuid()';
+    case 'sql': return String(spec.default); // .defaultSql() — the author's SQL, verbatim
     case 'value':
       return spec.isArray && Array.isArray(spec.default) ? arrayLiteral(spec.default) : literal(spec.default);
     default: return null;
@@ -251,7 +257,12 @@ export function fieldColumnSql(sqlName: string, spec: FieldSpec, inlinePrimaryKe
   let s = `"${sqlName}" ${serial ?? pgType(spec)}`;
   if (inlinePrimaryKey) s += ' PRIMARY KEY';
   const def = serial ? null : defaultExpr(spec);
-  if (def) s += ` DEFAULT ${def}`;
+  // A `defaultSql` nextval draws from an EXISTING sequence, possibly owned by a table
+  // created later in the same migration — held out of the column line (compileMigration
+  // re-attaches it as a trailing SET DEFAULT). Never the serial shorthand: that would
+  // mint a NEW sequence and silently detach the column from the one it declared.
+  const heldSequenceDraw = spec.defaultKind === 'sql' && nextvalSequence(def) != null;
+  if (def && !heldSequenceDraw) s += ` DEFAULT ${def}`;
   if (spec.isNotNull) s += ' NOT NULL';
   return s;
 }
@@ -485,6 +496,26 @@ export function compileEnums(models: ModelDescriptor[]): EnumType[] {
   return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/**
+ * Standalone-sequence descriptors → the snapshot shape the diff and fingerprint consume.
+ * PostgreSQL's defaults (start/increment of 1) are omitted, so a declaration that omits
+ * them reaches the same canonical form a live default-configured sequence introspects to.
+ */
+export function compileSequences(sequences: readonly SequenceDescriptor[]): SequenceSchema[] {
+  return sequences
+    .map((s) => ({
+      name: s.name,
+      as: s.as,
+      ...(s.start != null && s.start !== 1 ? { start: s.start } : {}),
+      ...(s.increment != null && s.increment !== 1 ? { increment: s.increment } : {}),
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// The DDL renderer lives in schema-diff (emitOne needs it; this file already imports
+// schema-diff, so defining it there avoids a cycle) — re-exported here beside its compiler.
+export { sequenceCreateSql } from './schema-diff.js';
+
 /**
  * Foreign-key constraints for a model — its `.references()` fields and its table-level
  * `foreignKey(...)` constraints, via `modelForeignKeys` — as `ALTER TABLE` statements. These

package/src/cli/schema-diff.ts

@@ -30,6 +30,7 @@ import type {
   ColumnSchema,
   EnumType,
   IndexSchema,
+  SequenceSchema,
 } from './schema-introspect.js';
 
 // ---------------------------------------------------------------------------
@@ -79,10 +80,14 @@ export type SchemaChange =
   | { kind: 'dropType'; name: string }
   /** An enum value the DB has but the Model dropped/renamed — Postgres can't drop one in place (a notice). */
   | { kind: 'enumValuesChanged'; name: string; from: string[]; to: string[] }
-  /** A standalone index to create → `CREATE [UNIQUE] INDEX … [WHERE …]`. */
-  | { kind: 'createIndex'; table: string; name: string; columns: string[]; unique: boolean; where?: string }
+  /** A standalone index to create → `CREATE [UNIQUE] INDEX … [USING …] (…) [INCLUDE …] [WHERE …]`. */
+  | { kind: 'createIndex'; table: string; name: string; columns: string[]; unique: boolean; where?: string; using?: string; include?: string[] }
   /** A standalone index present in the DB but no longer declared → `DROP INDEX` (a removal — gated). */
-  | { kind: 'dropIndex'; table: string; name: string };
+  | { kind: 'dropIndex'; table: string; name: string }
+  /** A declared standalone sequence missing live → `CREATE SEQUENCE`, before any table. */
+  | { kind: 'createSequence'; sequence: SequenceSchema }
+  /** A declared sequence whose live properties differ — a NOTICE, never a silent ALTER (it holds state). */
+  | { kind: 'sequenceDrift'; name: string; declared: SequenceSchema; live: SequenceSchema };
 
 /**
  * Rename intent, keyed like the snapshot's tables (`public.posts`) → { newColumn: oldColumn }.
@@ -131,9 +136,48 @@ export function normalizeDefault(expr: string | null): string | null {
   // `nextval('public.x_seq')` on another. public is always on the search_path — strip it.
   s = s.replace(/^nextval\('public\.([^']+)'/, "nextval('$1'");
 
+  // The deparser also casts the sequence literal (`nextval('x_seq'::regclass)`); an
+  // authored `defaultSql` may spell it bare. One canonical (castless) form for both —
+  // a normalization change, so FINGERPRINT_VERSION was bumped with it.
+  s = s.replace(/^nextval\('([^']+)'::regclass\)$/, "nextval('$1')");
+
   return s;
 }
 
+/**
+ * The sequence a `nextval` default draws from (schema qualification and the `::regclass`
+ * cast stripped), or null when the expression isn't a plain nextval. Drives two decisions:
+ * the `serial` shorthand fires ONLY for a column's own conventional `<table>_<col>_seq`
+ * (anything else would mint a NEW sequence), and a foreign-sequence default is held out
+ * of CREATE/ADD and re-attached as a trailing SET DEFAULT (its sequence may live on a
+ * table created later).
+ */
+export function nextvalSequence(expr: string | null): string | null {
+  if (expr == null) return null;
+  const m = expr.trim().match(/^nextval\('(?:[^'.]+\.)?([^'.]+)'(?:::regclass)?\)$/);
+  return m ? m[1] : null;
+}
+
+/** `public.contracts` / `contracts` → `contracts` (the bare table name for sequence conventions). */
+function bareTable(table: string): string {
+  return table.replace(/^[^.]+\./, '');
+}
+
+/** `CREATE SEQUENCE` DDL for a standalone sequence — emitted BEFORE any table, so a
+ *  column's `defaultSql(nextval(…))` can draw on it from the first CREATE. */
+export function sequenceCreateSql(seq: SequenceSchema): string {
+  let s = `CREATE SEQUENCE ${seq.name} AS ${seq.as}`;
+  if (seq.start != null) s += ` START WITH ${seq.start}`;
+  if (seq.increment != null) s += ` INCREMENT BY ${seq.increment}`;
+  return `${s};`;
+}
+
+/** True when a column's default draws a sequence that is NOT its own conventional one. */
+function isForeignSequenceDefault(table: string, col: ColumnSchema): boolean {
+  const seq = nextvalSequence(col.default);
+  return seq != null && seq !== `${bareTable(table)}_${col.name}_seq`;
+}
+
 // ---------------------------------------------------------------------------
 // Type-change classification — does the conversion need a USING cast and a warning?
 // ---------------------------------------------------------------------------
@@ -318,29 +362,76 @@ export function diffSchema(desired: SchemaSnapshot, current: SchemaSnapshot, ren
 
   const e = diffEnums(desired.enums ?? [], current.enums ?? []);
 
+  // Standalone sequences — existence-diffed, DECLARED-SCOPED (a live sequence the models
+  // never declared is invisible: it holds state, and undeclared ≠ ours to drop). A declared
+  // one missing live is a create, before any table (a defaultSql may draw on it from the
+  // first CREATE); live property drift is a NOTICE — never a silent ALTER on a counter.
+  const sequenceCreates: SchemaChange[] = [];
+  const sequenceNotices: SchemaChange[] = [];
+  const currentSeqs = new Map((current.sequences ?? []).map((s) => [s.name, s]));
+  for (const declared of desired.sequences ?? []) {
+    const liveSeq = currentSeqs.get(declared.name);
+    if (!liveSeq) {
+      sequenceCreates.push({ kind: 'createSequence', sequence: declared });
+    } else if (liveSeq.as !== declared.as || (liveSeq.increment ?? 1) !== (declared.increment ?? 1)) {
+      sequenceNotices.push({ kind: 'sequenceDrift', name: declared.name, declared, live: liveSeq });
+    }
+  }
+
+  // Foreign-sequence defaults are held out of CREATE/ADD by the emitters (the sequence
+  // may live on a table created later in the same batch) and re-attached here as
+  // SET DEFAULT changes ordered after every create and add.
+  const trailingDefaults: SchemaChange[] = [];
+  for (const c of creates) {
+    if (c.kind !== 'createTable') continue;
+    for (const col of c.schema.columns) {
+      if (isForeignSequenceDefault(c.table, col)) {
+        trailingDefaults.push({ kind: 'setDefault', table: c.table, column: col.name, expr: col.default! });
+      }
+    }
+  }
+  for (const c of addColumns) {
+    if (c.kind !== 'addColumn') continue;
+    if (isForeignSequenceDefault(c.table, c.column)) {
+      trailingDefaults.push({ kind: 'setDefault', table: c.table, column: c.column.name, expr: c.column.default! });
+    }
+  }
+
   // Enum types come first (a table or column may reference one); value adds before the
   // columns that use them. Table renames run before creates (a rename frees a name a
   // create may reuse) and before every per-table change (which all target the new name).
   // Column renames run before adds and alters for the same reason. Enum drops sit with
   // the other removals; notices are comments — emitted last, after the DDL.
   return [
-    ...e.creates, ...e.adds,
+    ...e.creates, ...e.adds, ...sequenceCreates,
     ...renameTables,
-    ...creates, ...renameColumns, ...addColumns, ...alters,
+    ...creates, ...renameColumns, ...addColumns, ...alters, ...trailingDefaults,
     ...dropConstraints, ...addConstraints, ...createIndexes,
     ...dropColumns, ...dropIndexes, ...dropTables,
-    ...e.drops, ...notices, ...e.notices,
+    ...e.drops, ...notices, ...e.notices, ...sequenceNotices,
   ];
 }
 
 /** A `createIndex` change from an index spec (the new-table path and the per-table diff share it). */
 function createIndexChange(table: string, ix: IndexSchema): SchemaChange {
-  return { kind: 'createIndex', table, name: ix.name, columns: ix.columns, unique: ix.unique, ...(ix.where ? { where: ix.where } : {}) };
+  return {
+    kind: 'createIndex', table, name: ix.name, columns: ix.columns, unique: ix.unique,
+    ...(ix.where ? { where: ix.where } : {}),
+    ...(ix.using ? { using: ix.using } : {}),
+    ...(ix.include?.length ? { include: ix.include } : {}),
+  };
 }
 
-/** An index's content identity — columns, uniqueness, and partial predicate, name-independent (like checks). */
+/**
+ * An index's content identity — key entries (expressions/direction/opclass are canonical
+ * text, normalized like checks), uniqueness, predicate, access method, and INCLUDE set:
+ * name-independent, and no longer blind to anything `CREATE INDEX` can say (Brick E —
+ * the consumer's 31 phantom drop/creates). Plain btree indexes key exactly as before
+ * plus a constant tail — both sides compute the same key, so nothing churns.
+ */
 function indexKey(ix: IndexSchema): string {
-  return `${ix.unique ? 'u' : ''}|${ix.columns.join(',')}|${normalizeCheck(ix.where ?? '')}`;
+  const entries = ix.columns.map((c) => normalizeCheck(c)).join(',');
+  return `${ix.unique ? 'u' : ''}|${entries}|${normalizeCheck(ix.where ?? '')}|${ix.using ?? 'btree'}|${(ix.include ?? []).join(',')}`;
 }
 
 /**
@@ -555,25 +646,31 @@ const enumLiteral = (value: string): string => `'${value.replace(/'/g, "''")}'`;
  * column), or null. CREATE/ADD COLUMN must use the shorthand — it creates the backing
  * sequence, which a bare `DEFAULT nextval(...)` would reference before it exists.
  */
-function serialSpelling(col: ColumnSchema): string | null {
-  if (col.default == null || !/^nextval\('[^']+'::regclass\)$/.test(col.default)) return null;
+function serialSpelling(col: ColumnSchema, table: string): string | null {
+  // ONLY the column's own conventional sequence is a serial declaration — the shorthand
+  // creates a sequence, so spelling it for a foreign `nextval` would mint a duplicate
+  // and silently detach the column from the sequence it declared.
+  const seq = nextvalSequence(col.default);
+  if (seq == null || seq !== `${bareTable(table)}_${col.name}_seq`) return null;
   if (col.type === 'integer') return 'serial';
   if (col.type === 'bigint') return 'bigserial';
   return null;
 }
 
 /** A column definition body (no leading indent): `"name" type [DEFAULT expr] [NOT NULL]`. */
-function columnSql(col: ColumnSchema): string {
-  const serial = serialSpelling(col);
+function columnSql(col: ColumnSchema, table: string): string {
+  const serial = serialSpelling(col, table);
   let s = `${quote(col.name)} ${serial ?? col.type}`;
-  if (!serial && col.default != null) s += ` DEFAULT ${col.default}`;
+  // A foreign-sequence default is held out — diffSchema appends the trailing SET DEFAULT
+  // (after every create), so the CREATE never references a sequence that doesn't exist yet.
+  if (!serial && col.default != null && !isForeignSequenceDefault(table, col)) s += ` DEFAULT ${col.default}`;
   if (col.notNull) s += ' NOT NULL';
   return s;
 }
 
 /** `CREATE TABLE` from the IR: columns + PK/unique/check inline; FKs are emitted separately. */
 function createTableSql(t: TableSchema): string {
-  const lines = t.columns.map((c) => `\t${columnSql(c)}`);
+  const lines = t.columns.map((c) => `\t${columnSql(c, t.table)}`);
   if (t.primaryKey.length) lines.push(`\tPRIMARY KEY (${colList(t.primaryKey)})`);
   for (const u of t.uniques) lines.push(`\tCONSTRAINT ${quote(u.name)} UNIQUE (${colList(u.columns)})`);
   for (const ck of t.checks) lines.push(`\tCONSTRAINT ${quote(ck.name)} CHECK ${wrapOnce(ck.expr)}`);
@@ -613,7 +710,7 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string {
     case 'dropTable':
       return `DROP TABLE ${change.table};`;
     case 'addColumn': {
-      const ddl = `ALTER TABLE ${change.table} ADD COLUMN ${columnSql(change.column)};`;
+      const ddl = `ALTER TABLE ${change.table} ADD COLUMN ${columnSql(change.column, change.table)};`;
       // Adding a NOT NULL column with no default fails on a table that already has rows.
       if (change.column.notNull && change.column.default == null) {
         return `-- WARNING: ADD COLUMN ${quote(change.column.name)} NOT NULL on ${change.table} has no default and FAILS if the table has rows; add a default or backfill first.\n${ddl}`;
@@ -674,8 +771,13 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string {
       return `DROP TYPE ${quote(change.name)};`;
     case 'createIndex': {
       const unique = change.unique ? 'UNIQUE ' : '';
+      const using = change.using ? ` USING ${change.using}` : '';
+      // A plain identifier entry quotes as before; a canonical-text entry (expression,
+      // DESC, opclass) passes verbatim — quoting the whole thing would mangle it.
+      const entry = (c: string): string => (/^[a-z_][a-z0-9_$]*$/i.test(c) ? quote(c) : c);
+      const include = change.include?.length ? ` INCLUDE (${colList(change.include)})` : '';
       const where = change.where ? ` WHERE ${change.where}` : '';
-      return `CREATE ${unique}INDEX ${quote(change.name)} ON ${change.table} (${colList(change.columns)})${where};`;
+      return `CREATE ${unique}INDEX ${quote(change.name)} ON ${change.table}${using} (${change.columns.map(entry).join(', ')})${include}${where};`;
     }
     case 'dropIndex': {
       const schema = change.table.includes('.') ? `${change.table.split('.')[0]}.` : '';
@@ -683,6 +785,10 @@ function emitOne(change: SchemaChange, opts: EmitOptions): string {
     }
     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':
+      return sequenceCreateSql(change.sequence);
+    case 'sequenceDrift':
+      return `-- NOTICE: sequence ${change.name} differs from its declaration (declared AS ${change.declared.as}${change.declared.increment != null ? ` INCREMENT ${change.declared.increment}` : ''}; live AS ${change.live.as}${change.live.increment != null ? ` INCREMENT ${change.live.increment}` : ''}). A sequence holds a counter — reshape it by hand (ALTER SEQUENCE) after deciding what the counter should be.`;
   }
 }
 

package/src/cli/schema-fingerprint.ts

@@ -39,23 +39,30 @@
  *    fingerprints. The version prefix plus the re-diff path keep that honest.
  *
  * Coverage is partial and SAYS SO: `UNFINGERPRINTED_SQL` enumerates what the
- * base fingerprint does not see (standalone sequences, triggers, domains,
- * composite types, foreign/partitioned tables, extensions) so partial
- * coverage reads as a report, never as "covered everything".
+ * base fingerprint does not see (triggers — drift-checked separately by the
+ * reconciler's provenance — domains, composite types, foreign/partitioned
+ * tables, extensions) so partial coverage reads as a report, never as
+ * "covered everything". Standalone sequences left this list in v3: covered.
  */
 
 import { createHash } from 'node:crypto';
-import type { ModelDescriptor } from '@everystack/model';
+import type { ModelDescriptor, SequenceDescriptor } from '@everystack/model';
 import type { SchemaSnapshot, TableSchema } from './schema-introspect.js';
 import type { AuthzContract, TableContract } from './authz-contract.js';
-import { compileTableSchema, compileEnums } from './schema-compile.js';
+import { compileTableSchema, compileEnums, compileSequences } from './schema-compile.js';
 import { compileTableContract } from './authz-compile.js';
 import { normalizeDefault, normalizeCheck } from './schema-diff.js';
 
 // 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
 // deparsed form agree — the identity `fingerprintModels === fingerprintLive` holds.
-export const FINGERPRINT_VERSION = 2;
+// v3: nextval defaults canonicalize to the castless form (`nextval('x_seq')`), so an
+// authored `defaultSql` and the deparser's `nextval('x_seq'::regclass)` hash equal
+// (canonical forms changed for every serial column's default → the bump). ALSO in v3:
+// STANDALONE SEQUENCES enter the canonical form (declared via defineSequence,
+// introspected from pg_sequence minus serial-owned) — a coverage expansion; the
+// `sequences` key appears only when any exist, so sequence-free states hash unchanged.
+export const FINGERPRINT_VERSION = 3;
 
 // ---------------------------------------------------------------------------
 // Canonical form.
@@ -149,12 +156,23 @@ export interface CanonicalState {
   tables: Array<Record<string, unknown>>;
   enums: Array<{ name: string; values: string[] }>;
   authz: Array<Record<string, unknown>>;
+  /** Standalone sequences — present ONLY when any exist, so a sequence-free state's
+   *  canonical form (and hash) is byte-identical to the pre-coverage form. */
+  sequences?: Array<Record<string, unknown>>;
 }
 
 export function canonicalizeState(
   snapshot: SchemaSnapshot,
   authzTables: TableContract[],
 ): CanonicalState {
+  const sequences = byKey(
+    (snapshot.sequences ?? []).map((s) => ({
+      name: s.name, as: s.as,
+      ...(s.start != null ? { start: s.start } : {}),
+      ...(s.increment != null ? { increment: s.increment } : {}),
+    })),
+    (s) => String(s.name),
+  );
   return {
     v: FINGERPRINT_VERSION,
     tables: byKey(snapshot.tables.map(canonicalTable), (t) => String(t.table)),
@@ -163,6 +181,7 @@ export function canonicalizeState(
       (e) => e.name,
     ),
     authz: byKey(authzTables.map(canonicalAuthzTable), (t) => String(t.table)),
+    ...(sequences.length ? { sequences } : {}),
   };
 }
 
@@ -184,11 +203,12 @@ export function fingerprintState(
 /** The DECLARED state: compile the models to the same canonical shape and hash it. */
 export function fingerprintModels(
   models: ModelDescriptor[],
-  opts: { schema?: string } = {},
+  opts: { schema?: string; sequences?: SequenceDescriptor[] } = {},
 ): Fingerprint {
   const snapshot: SchemaSnapshot = {
     tables: models.map((m) => compileTableSchema(m, opts)),
     enums: compileEnums(models),
+    ...(opts.sequences?.length ? { sequences: compileSequences(opts.sequences) } : {}),
   };
   const authzTables = models.map((m) => compileTableContract(m, opts));
   return fingerprintState(snapshot, authzTables);
@@ -210,17 +230,7 @@ export function fingerprintLive(snapshot: SchemaSnapshot, contract: AuthzContrac
  * types, foreign tables, partitioned tables, and installed extensions.
  */
 export const UNFINGERPRINTED_SQL = `
-SELECT 'sequence' AS kind, n.nspname || '.' || c.relname AS identity
-FROM pg_class c
-JOIN pg_namespace n ON n.oid = c.relnamespace
-WHERE c.relkind = 'S'
-  AND n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg_%'
-  AND NOT EXISTS (
-    SELECT 1 FROM pg_depend d
-    WHERE d.objid = c.oid AND d.deptype IN ('a', 'i') AND d.refobjsubid > 0
-  )
-UNION ALL
-SELECT 'trigger', n.nspname || '.' || c.relname || '.' || t.tgname
+SELECT 'trigger' AS kind, n.nspname || '.' || c.relname || '.' || t.tgname AS identity
 FROM pg_trigger t
 JOIN pg_class c ON c.oid = t.tgrelid
 JOIN pg_namespace n ON n.oid = c.relnamespace