@fougere/adapter-sql 0.6.0-alpha.0 → 0.7.0-alpha.0

package/src/order.ts

@@ -0,0 +1,63 @@
+/**
+ * In what order a batch of tables is created — the one question that reads a `TableDef` and
+ * knows nothing above it: no entity, no axis, no schema.
+ */
+import type { ColumnDef, TableDef } from './table.js';
+
+export interface FkEdge {
+  table: TableDef;
+  column: ColumnDef;
+}
+
+export interface TableOrder {
+  /** Tables in dependency order — a `ref()` target always precedes its referrer. */
+  ordered: TableDef[];
+  /** FK columns whose target could not be ordered first — a cycle. Constrain after creation. */
+  deferred: FkEdge[];
+}
+
+/**
+ * Order a table set so a `ref()`'s target always exists before the table that points at it —
+ * required by every engine except SQLite, which resolves FK targets lazily and accepts any order
+ * (and has no `ALTER TABLE ADD CONSTRAINT` to close a cycle with — a caller on that dialect skips
+ * this function entirely).
+ */
+export function orderTables(tables: TableDef[]): TableOrder {
+  const byName = new Map(tables.map((table) => [table.name, table]));
+  const needs = new Map(
+    tables.map((table) => [
+      table.name,
+      new Set(
+        table.columns
+          .filter((c) => c.references && c.references.table !== table.name && byName.has(c.references.table))
+          .map((c) => c.references!.table),
+      ),
+    ]),
+  );
+
+  const ordered: TableDef[] = [];
+  const deferred: FkEdge[] = [];
+  const done = new Set<string>();
+
+  while (needs.size > 0) {
+    const ready = [...needs.keys()].find((name) => [...needs.get(name)!].every((dep) => done.has(dep)));
+    if (ready) {
+      ordered.push(byName.get(ready)!);
+      done.add(ready);
+      needs.delete(ready);
+      continue;
+    }
+    // Every table left waits on another table left — a cycle. Break it by
+    // deferring one edge: every column of the first remaining table that points
+    // at its first unmet dependency.
+    const [name, deps] = [...needs.entries()][0];
+    const dep = [...deps].find((d) => !done.has(d))!;
+    const table = byName.get(name)!;
+    for (const column of table.columns) {
+      if (column.references?.table === dep) deferred.push({ table, column });
+    }
+    deps.delete(dep);
+  }
+
+  return { ordered, deferred };
+}

package/src/query.ts

@@ -5,12 +5,7 @@ export interface QueryEvent {
   /** Which storage ran it — a process may open several (`sources:`). */
   storage: string;
   sql: string;
-  /**
-   * How MANY parameters, never their values.
-   *
-   * They are user data nobody chose to expose — the rule the call log states for a body.
-   * The count is what a reader needs anyway: it is how you see an `IN (?, ?, ?)` grow.
-   */
+  /** How MANY parameters, never their values. */
   parameters: number;
   /** Rounded to three decimals: a sub-microsecond statement reports 17 digits otherwise. */
   ms: number;
@@ -22,17 +17,7 @@ export type QuerySink = (event: QueryEvent) => void;
 
 const sinks: QuerySink[] = [];
 
-/**
- * Be told about every statement this process runs, and get the unsubscription back.
- *
- * A subscription and not an option, for one reason that decides it: Kysely takes its `log`
- * at CONSTRUCTION, and the storage is built during the boot — before any extension's
- * `up(app)` runs. So the only way to subscribe afterwards is for the log to be installed
- * from the start and route to whoever is listening.
- *
- * The same shape core states for `onLog` and observability for `onSpan`. Costs nothing when
- * nobody listens: `logQueries` returns on an empty list before touching the event.
- */
+/** Be told about every statement this process runs, and get the unsubscription back. */
 export function onQuery(sink: QuerySink): () => void {
   sinks.push(sink);
 

package/src/setup.ts

@@ -1,12 +1,4 @@
-/**
- * Storage setup — the shape every engine answers, and no driver at all.
- *
- * Fougere has no business choosing a driver (`pg`, `mysql2`, `tedious`, `better-sqlite3`,
- * a D1 binding), so the caller builds the Kysely dialect and hands it over — no dynamic
- * import, no optional dependency. This file therefore reaches for nothing: it is what a
- * runtime with no filesystem imports. The one driver this package does own lives behind
- * `@fougere/adapter-sql/sqlite`.
- */
+/** Storage setup — the shape every engine answers, and no driver at all. */
 import { Kysely, sql, type Dialect as KyselyDialect } from 'kysely';
 import type { Source, SourceView } from '@fougere/core';
 import { createStorageFactory, type StorageFactoryOptions } from './crud.js';
@@ -19,57 +11,29 @@ import type { SqlSink } from './ddl.js';
 export interface SetupOptions {
   /** Override naming for specific entities (e.g. better-auth wants singular table names). */
   storageFactoryOptions?: StorageFactoryOptions;
-  /**
-   * What to call this storage when a query is reported.
-   *
-   * A process may open several (`sources:`), and a module-level sink sees them all — without
-   * a name, two statements from two databases read as one stream. Defaults to what
-   * distinguishes them anyway: the engine here, the file path for SQLite.
-   */
+  /** What to call this storage when a query is reported. */
   name?: string;
 }
 
-/**
- * A `Source` realized by SQL — and the three members that are SQL's, not the routing's.
- *
- * `dialect`, `db` and `sink` are to a source what `Kysely` is to `SqlStorage.client`: what
- * this adapter is MADE OF, reached by narrowing. Nothing that routes entities across
- * sources reads them.
- */
+/** A `Source` realized by SQL — and the three members that are SQL's, not the routing's. */
 export interface SqlSource extends Source {
   dialect: DialectName;
   storageFactory: ReturnType<typeof createStorageFactory>;
   /** Runs raw statements — what `autoMigrate` writes through. */
   sink: SqlSink;
   /**
-   * The Kysely instance, for what precedes any entity: `migrate(app, setup)` writes the
-   * schema through it, and a script may need it before a container exists.
-   *
-   * It is not the way to reach data from inside an app — that is the injected `Storage`,
-   * whose `client` gives the same handle while keeping the scope of its entity.
+   * The Kysely instance, for what precedes any entity: `migrate(app, setup)` writes the schema
+   * through it, and a script may need it before a container exists.
    */
   db: Kysely<any>;
-  /**
-   * Run `fn` inside one transaction of this engine, with a storage factory bound to it.
-   *
-   * The transaction belongs to the engine, so obtaining one is a gesture on the engine and
-   * nowhere else. Nothing new is handed back: `Transaction<DB> extends Kysely<DB>` and
-   * `SqlStorage` takes a `Kysely<any>`, so the SAME storage is rebuilt over the substituted
-   * connection — which is why a frame needs no support in this package.
-   */
+  /** Run `fn` inside one transaction of this engine, with a storage factory bound to it. */
   transacted<R>(fn: (storageFactory: ReturnType<typeof createStorageFactory>) => Promise<R>): Promise<R>;
 }
 
 /** The name this shape answered to before it was one realization among several. */
 export type Setup = SqlSource;
 
-/**
- * The migration of what lives in ONE sql source, carrying its own dialect.
- *
- * It was the router's gesture, which had to know how SQL migrates — and did not pass the
- * dialect, so every source was migrated as sqlite, the documented Postgres case included.
- * A source knows its own engine, so the gesture is its own.
- */
+/** The migration of what lives in ONE sql source, carrying its own dialect. */
 function migrating(db: Kysely<any>, dialect: DialectName, opts: SetupOptions) {
   return async (view: SourceView): Promise<void> => {
     await migrate(view as never, db, {

package/src/sqlite.ts

@@ -1,12 +1,4 @@
-/**
- * SQLite on a file — the convention a first run meets, and the only driver this package owns.
- *
- * It sits behind its own subpath because `better-sqlite3` is a NATIVE module and `node:fs`
- * is a builtin: a bundler cannot prune a module that imports them, so re-exporting this
- * from the index made the whole adapter unreachable from a runtime that has neither. Same
- * cut as `@fougere/transport-http/receive`, and for the same reason — share the projection,
- * never the plumbing.
- */
+/** SQLite on a file — the convention a first run meets, and the only driver this package owns. */
 import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { Kysely, SqliteDialect } from 'kysely';
@@ -51,14 +43,7 @@ export function setupSqlite(opts: SqliteSetupOptions = {}): SqliteSetup {
   };
 }
 
-/**
- * `source: 'sql'` — answered HERE and not in the driver-free index, because answering a
- * name means building a driver, and this is the one this package owns.
- *
- * The refusal is `refuseUnresolvable` moved: it lived in `@fougere/defaults`, which happened
- * to import the driver, so a second adapter had nowhere to say it exists. A dialect this
- * package cannot build from a name is refused here, where the reason is true.
- */
+/** `source. */
 Sources.register('sql', (conf: SourceConfig): Source => {
   const dialect = conf.dialect as string | undefined;
   if (dialect !== undefined && dialect !== 'sqlite') {

package/src/step.ts

@@ -1,15 +1,4 @@
-/**
- * The half `delta()` refuses — realised from an intention that was written down.
- *
- * `diff.ts` states its own guarantee: additive only, because "a rename is not even
- * detectable from a diff (it reads as a drop plus an add)". That still holds, and this
- * file does not weaken it. What changed is upstream: a frozen step (`fougere freeze`)
- * carries a rename because a human declared it at the moment they made it. The intention
- * exists now, so it can be realised — and only what the step actually says.
- *
- * A drop and a rename both touch live data, so this is the only place either can come
- * from: never introspection, never a guess.
- */
+/** The half `delta()` refuses — realised from an intention that was written down. */
 import { sql, type Kysely } from 'kysely';
 import type { Change as ShapeChange, SetDiff } from '@fougere/schema';
 import { dequal } from 'dequal';
@@ -42,25 +31,11 @@ export interface Plan {
 export interface PlanOptions {
   /** Entity key → table name. Same resolver `desiredTables` takes. */
   tableName?: (name: string) => string;
-  /**
-   * What the database actually holds, from `actualState`. Given, a change already
-   * realised is skipped.
-   *
-   * Idempotence by OBSERVATION and not by bookkeeping — the same choice `delta` makes.
-   * A ledger of applied steps would be a second record of a fact the columns already
-   * carry, and the two would disagree the day someone renamed a column by hand.
-   */
+  /** What the database actually holds, from `actualState`. */
   actual?: SchemaState;
 }
 
-/**
- * Collapse a chain of steps into one, following each field through its renames.
- *
- * A step judges itself on two names — old gone, new here — so an intermediate rename is
- * unrecognisable once its target has been renamed again: both names are absent and it is
- * proposed forever. Composing the chain first asks the question about the name the field
- * ENDS on, which is the only one the tables can answer.
- */
+/** Collapse a chain of steps into one, following each field through its renames. */
 export function collapseChain(steps: readonly SetDiff[]): SetDiff {
   const entities: SetDiff['entities'] = {};
   const added: string[] = [];
@@ -70,9 +45,9 @@ export function collapseChain(steps: readonly SetDiff[]): SetDiff {
     added.push(...step.entitiesAdded);
     removed.push(...step.entitiesRemoved);
     for (const [entity, answer] of Object.entries(step.entities)) {
-      const held = (entities[entity] ??= { changes: [], ambiguous: [] });
-      held.ambiguous.push(...answer.ambiguous);
-      for (const change of answer.changes) compose(held.changes, change);
+      const entry = (entities[entity] ??= { changes: [], ambiguous: [] });
+      entry.ambiguous.push(...answer.ambiguous);
+      for (const change of answer.changes) compose(entry.changes, change);
     }
   }
 
@@ -80,9 +55,8 @@ export function collapseChain(steps: readonly SetDiff[]): SetDiff {
 }
 
 /**
- * Add one change to what the chain has said so far, rewriting rather than appending when
- * it continues a field already moved. A rename back to its origin cancels: the tables
- * never held the name in between, so there is nothing for them to do.
+ * Add one change to what the chain has said so far, rewriting rather than appending when it
+ * continues a field already moved.
  */
 function compose(held: ShapeChange[], change: ShapeChange): void {
   if (change.kind === 'renamed') {
@@ -113,11 +87,7 @@ function compose(held: ShapeChange[], change: ShapeChange): void {
   held.push({ ...change, field: origin.from });
 }
 
-/**
- * Turn a frozen step into what the tables must do, and what nobody may decide for you.
- *
- * Pure, like `delta` — the comparison is one thing, running it is another.
- */
+/** Turn a frozen step into what the tables must do, and what nobody may decide for you. */
 export function planStep(step: SetDiff, tables: TableDef[], options: PlanOptions = {}): Plan {
   const resolve = options.tableName ?? toTableName;
   const actual = options.actual;
@@ -191,7 +161,7 @@ function realise(
 
     case 'reshaped':
       // A tightened bound is a CHECK, and altering one on a live table is engine-specific
-      // AND may be refused by rows already stored. The judge still enforces it at the door.
+      // AND may be refused by rows already stored. The validator still enforces it at the door.
       return {
         entity,
         field: change.field,
@@ -203,13 +173,7 @@ function realise(
   }
 }
 
-/**
- * An axis other than shape moved. Only some of it is a fact about the table.
- *
- * `boundary` never is — it says who may read or write, which no column holds. `lifecycle`
- * is one only through the DEFAULT clause. `role` is one three times over, and two of those
- * are constraints a live table may already contradict.
- */
+/** An axis other than shape moved. */
 function restated(entity: string, change: Extract<ShapeChange, { kind: 'restated' }>): { change?: StepChange } | Refusal {
   const refuse = (reason: string): Refusal => ({ entity, field: change.field, reason });
 
@@ -246,13 +210,7 @@ function literalOf(rules: { create?: unknown } | undefined): unknown {
 
 const show = (value: unknown): string => (value === undefined ? 'none' : JSON.stringify(value));
 
-/**
- * Has the table already moved? Read off the columns themselves.
- *
- * A rename whose old name is gone and whose new one is there has happened; a drop whose
- * column is absent has happened. Unknown state (no introspection given) answers no, so a
- * plan built without it proposes everything the step says.
- */
+/** Has the table already moved? Read off the columns themselves. */
 function done(change: StepChange, columns: Set<string> | undefined): boolean {
   if (!columns) return false;
   return change.kind === 'renameColumn'

package/src/table.ts

@@ -1,18 +1,8 @@
 import { Lifecycle, Role } from '@fougere/schema';
-/**
- * Entity → table description, with no SQL in sight.
- *
- * This is the neutral middle term: one projection reads the entity's axes and
- * produces a `TableDef`; a `Dialect` turns that into SQL. Neither half knows the
- * other — the dialect never mentions a field. Adding a dialect touches only the
- * second half.
- *
- * `ColumnDef.stated` is the one member the axes did not produce. It names one engine's
- * column type, so dropping it leaves every column describable.
- */
-import { Anatomy, FieldGroup, Unique, fieldsOf, lowerFirst, schemaOf, type Field, type SchemaView, type SchemaOrCard } from '@fougere/schema';
+/** Entity → table description, with no SQL in sight. */
+import { Shapes, lowerFirst, type Field, type SchemaView } from '@fougere/schema';
 import { boundsOf, type ShapeBounds } from './check.js';
-import type { SqlField } from './fields.js';
+import { sqlEntries, type SqlField } from './fields.js';
 
 /** The shape keywords a dialect needs to choose a column type. */
 export interface ColumnShape {
@@ -62,11 +52,7 @@ export interface TableDef {
   columns: ColumnDef[];
   /** PK column names when the key is composite — empty for a simple key. */
   compositePrimary: string[];
-  /**
-   * Column groups unique together, from `entity(fields, { unique: [...] })`.
-   * A single-field group is left to the column's own `unique` — this is the
-   * table-level form, for facts no column can hold alone.
-   */
+  /** Column groups unique together, from `entity(fields, { unique: [...] })`. */
   uniqueGroups: string[][];
 }
 
@@ -83,11 +69,7 @@ function isStored(field: Field): boolean {
   return !Role.of(field).isCollection;
 }
 
-/**
- * The target's primary key column. A live thunk (an in-process entity) answers
- * for real; a relation reconstructed from a lone `Card` (without a `Bundle`) has lost it to a
- * name stand-in with no `getFields` — the convention there is to assume `id`.
- */
+/** The target's primary key column. */
 function primaryColumnOf(target: Partial<SchemaView>): string {
   if (typeof target.getFields !== 'function') return 'id';
   for (const [name, field] of Object.entries(target.getFields())) {
@@ -96,28 +78,11 @@ function primaryColumnOf(target: Partial<SchemaView>): string {
   return 'id'; // declared no primary() field — defensive, shouldn't happen
 }
 
-/**
- * The FK target for a `ref()` field: the table it points at plus its PK column.
- *
- * `tableNameOf` is an identity map — built once per app generation pass, see
- * {@link toTables} — from a LIVE entity class to the table name already resolved
- * for it. Reusing that name (instead of re-deriving one from the class name) is
- * what keeps a custom `tableName` resolver honest: `demos/schema-ecommerce`
- * names `Category`'s table `"categories"` (an irregular plural its resolver
- * special-cases) — re-deriving from `Category.name` through the DEFAULT
- * convention would silently produce `"categorys"` instead.
- *
- * A miss (the target isn't part of this batch — a cross-frond target, or a live
- * class the app substituted for one a package hardcoded — e.g.
- * `@fougere/auth-better`'s `AuthSession` always points at its own default
- * `AuthUser`, never at whatever `opts.user` the app actually registered) falls
- * back to deriving the name from the class — correct when that class follows
- * the default convention, wrong if the app ALSO overrides `tableName` for it.
- */
+/** The FK target for a `ref()` field. */
 function referenceFor(
   field: Field,
   resolve: (name: string) => string,
-  tableNameOf?: Map<SchemaOrCard, string>,
+  tableNameOf?: Map<SchemaView, string>,
   hosted?: HostedNames,
 ): ColumnReference | undefined {
   const relation = Role.of(field).relation;
@@ -156,14 +121,14 @@ function toColumn(
   fieldName: string,
   field: Field,
   resolve: (name: string) => string,
-  tableNameOf?: Map<SchemaOrCard, string>,
+  tableNameOf?: Map<SchemaView, string>,
   hosted?: HostedNames,
   stated?: SqlField,
 ): ColumnDef {
   // The column type comes from the `shape` axis alone. `anatomy` strips the
   // nullable union so a nullable integer stays an integer instead of falling
   // through to text.
-  const { base, nullable } = Anatomy.of(field.shape);
+  const { base, nullable } = Shapes.of(field.shape);
   const lifecycle = Lifecycle.of(field);
   const column: ColumnDef = {
     field: fieldName,
@@ -180,8 +145,7 @@ function toColumn(
   // redundant constraint on every engine. So would indexing what `unique` constrains.
   // Only a constraint of ONE becomes a column constraint; a group of several is a table
   // constraint, emitted once from `uniqueGroups` rather than once per member column.
-  const soleUnique = FieldGroup.on(field, Unique).some((group) => group.members.length <= 1);
-  if (soleUnique && !column.primary) column.unique = true;
+  if (Role.of(field).isUnique && !column.primary) column.unique = true;
   if (Role.of(field).isIndexed && !column.primary && !column.unique) column.index = true;
   const references = referenceFor(field, resolve, tableNameOf, hosted);
   if (references) column.references = references;
@@ -194,7 +158,7 @@ export interface RelationResolve {
   /** Same resolver used for every entity's own table (default or a custom `tableName`). */
   resolve: (name: string) => string;
   /** Live entity class → its already-resolved table name, reused instead of re-derived. */
-  tableNameOf?: Map<SchemaOrCard, string>;
+  tableNameOf?: Map<SchemaView, string>;
   /** Which entities this batch holds and which live in another source — decided by NAME. */
   hosted?: HostedNames;
 }
@@ -207,46 +171,29 @@ export interface HostedNames {
   elsewhere: ReadonlySet<string>;
 }
 
-/**
- * Describe one entity as a table — the single reader of the axes.
- *
- * Takes the entity as a live class or as a card. Read ONCE into `fields`: `fieldsOf`
- * reconstructs a descriptor on each call, so re-reading per loop would rebuild the schema
- * as many times as this function iterates.
- *
- * A lone card has no live relation targets, so a `ref()` falls back to the conventions
- * `referenceFor`/`primaryColumnOf` already document (name-derived table, `id` as the key).
- * Pass a descriptor through `Bundle.toSchemas` first when the FKs matter — it resolves the
- * targets, and its output is the live-class case again.
- */
-export function toTable(tableName: string, entity: SchemaOrCard, relations?: RelationResolve): TableDef {
+/** Describe one entity as a table — the single reader of the axes. */
+export function toTable(tableName: string, schema: SchemaView, relations?: RelationResolve): TableDef {
   const resolve = relations?.resolve ?? toTableName;
-  const fields = fieldsOf(entity);
+  const fields = schema.getFields();
   // Read off the entity, since that is where it is declared and addressed by field key.
-  const stated = schemaOf(entity).getAdapters()?.sql;
+  const configuration = schema.getAdapters().sql;
+  // Judged HERE and not at `entity()`: this runs at boot, after every import, so the
+  // format is always loaded. A validator registered with `schema` would depend on which
+  // module was imported first.
+  sqlEntries.assert(configuration, `${schema.name}.adapters.sql`);
   const columns: ColumnDef[] = [];
   for (const [fieldName, field] of Object.entries(fields)) {
     if (!isStored(field)) continue;
-    columns.push(toColumn(fieldName, field, resolve, relations?.tableNameOf, relations?.hosted, stated?.[fieldName]));
+    columns.push(toColumn(fieldName, field, resolve, relations?.tableNameOf, relations?.hosted, configuration?.[fieldName]));
   }
   const primaries = columns.filter((column) => column.primary).map((column) => column.name);
   const stored = new Set(columns.map((column) => column.name));
-  // Read off the fields, not off `getUnique()`: a card has no entity-level declaration to
-  // offer, and the members carry the same fact either way. One reader for both forms.
-  //
-  // Declared in field names, realized in column names — and a group that names a field the
-  // storage does not keep is not enforceable, so it is dropped here rather than emitted
-  // against a column that will not exist.
-  const groups = new Map<string, string[]>();
-  for (const [fieldName, field] of Object.entries(fields)) {
-    for (const group of FieldGroup.on(field, Unique)) {
-      const members = group.resolvedOn(fieldName).members.map(toSnakeCase);
-      if (members.length > 1 && members.every((column) => stored.has(column))) {
-        groups.set(members.join(' '), members);
-      }
-    }
-  }
-  const uniqueGroups = [...groups.values()];
+  // Declared in field names, realized in column names — and a group naming a field the
+  // storage does not keep is not enforceable, so it is dropped rather than emitted against
+  // a column that will not exist.
+  const uniqueGroups = (schema.getUnique() ?? [])
+    .map((group) => group.map(toSnakeCase))
+    .filter((members) => members.every((column) => stored.has(column)));
 
   return {
     name: tableName,
@@ -257,12 +204,8 @@ export function toTable(tableName: string, entity: SchemaOrCard, relations?: Rel
 }
 
 /**
- * Is this column part of a key? MySQL and SQL Server refuse an unbounded text
- * column in a primary key or an index, so the dialect needs to know.
- *
- * `unique` and `index` count, and until they could be declared nothing did but the
- * primary key — the comment above already said "or an index" while the code answered
- * for the key alone, because no vocabulary word produced one to answer for.
+ * Is this column part of a key? MySQL and SQL Server refuse an unbounded text column in a primary
+ * key or an index, so the dialect needs to know.
  */
 export function isKeyed(table: TableDef, column: ColumnDef): boolean {
   return column.primary
@@ -280,8 +223,8 @@ export function toTableName(name: string): string {
 
 export interface EntityEntry {
   name: string;
-  /** A live class in-process, a card from a frond whose class never crossed. */
-  entityClass: SchemaOrCard;
+  /** A live class in-process, or one rebuilt from the card of a frond that never crossed. */
+  entityClass: SchemaView;
 }
 
 export interface FrondLike {
@@ -292,43 +235,25 @@ export interface FrondLike {
 export interface AppLike {
   fronds: FrondLike[];
   /** Auth runtime entities are migrated alongside scanned fronds when present. */
-  auth?: { entities: Record<string, SchemaOrCard> };
-  /**
-   * Entities this app hosts in ANOTHER source — named so a miss can be read.
-   *
-   * Without it every miss looked alike, so a `ref()` fell back to a derived table name
-   * and the constraint was emitted against a table that might not exist. Absent means
-   * one source, where a miss can only be a mistake.
-   */
+  auth?: { entities: Record<string, SchemaView> };
+  /** Entities this app hosts in ANOTHER source — named so a miss can be read. */
   elsewhere?: string[];
 }
 
-/**
- * A schema says whether it holds rows; this adapter decides what to emit for it.
- *
- * A root always did. A derivation describes ANOTHER's rows — `Post.pick('id','title')` is
- * a shape, and one dropped under `entities/` used to get a table of its own: measured on a
- * real app, where a projection of an archived entity created a duplicate in the OTHER
- * database. `.anchor()` is what says otherwise, and it is the entity's own word, never a
- * key of the app's config: a frond stays mountable without its host knowing.
- */
+/** A schema says whether it holds rows; this adapter decides what to emit for it. */
 function verdictOn(entry: EntityEntry): 'table' | 'answer' {
-  const schema = schemaOf(entry.entityClass);
+  const { entityClass } = entry;
 
-  return !schema.derivation || schema.anchored ? 'table' : 'answer';
+  return !entityClass.derivation || entityClass.anchored ? 'table' : 'answer';
 }
 
-/**
- * Every entity this app hosts, once each. The same class reaches here under one
- * registration name from two lists — a frond's `entities/` and the auth runtime's map —
- * and two entries for one name are two CREATE TABLE for one table.
- */
+/** Every entity this app hosts, once each. */
 function collectEntities(app: AppLike): EntityEntry[] {
   const entries: EntityEntry[] = [];
-  const held = new Set<string>();
+  const seen = new Set<string>();
   const hold = (entry: EntityEntry) => {
-    if (held.has(lowerFirst(entry.name))) return;
-    held.add(lowerFirst(entry.name));
+    if (seen.has(lowerFirst(entry.name))) return;
+    seen.add(lowerFirst(entry.name));
     entries.push(entry);
   };
 
@@ -345,14 +270,12 @@ function collectEntities(app: AppLike): EntityEntry[] {
 }
 
 /**
- * Every entity an app hosts, as FK-aware tables — the shared middle step behind
- * `generateSQL` (a from-scratch create pass) and `desiredTables` (the diff's
- * target state). Builds the identity map once (see `referenceFor`'s doc) so a
- * `ref()` target reuses the SAME resolved name as the entity's own table.
+ * Every entity an app hosts, as FK-aware tables — the shared middle step behind `generateSQL` (a
+ * from-scratch create pass) and `desiredTables` (the diff's target state).
  */
 export function toTables(app: AppLike, resolve: (name: string) => string): TableDef[] {
   const entries = collectEntities(app);
-  const tableNameOf = new Map<SchemaOrCard, string>(entries.map((entry) => [entry.entityClass, resolve(entry.name)]));
+  const tableNameOf = new Map<SchemaView, string>(entries.map((entry) => [entry.entityClass, resolve(entry.name)]));
   const hosted = app.elsewhere
     ? { here: new Set(entries.map((entry) => lowerFirst(entry.name))), elsewhere: new Set(app.elsewhere.map(lowerFirst)) }
     : undefined;
@@ -360,69 +283,3 @@ export function toTables(app: AppLike, resolve: (name: string) => string): Table
 }
 
 // ─── Ordering — a referenced table before its referrer ─────────────────────
-
-export interface FkEdge {
-  table: TableDef;
-  column: ColumnDef;
-}
-
-export interface TableOrder {
-  /** Tables in dependency order — a `ref()` target always precedes its referrer. */
-  ordered: TableDef[];
-  /** FK columns whose target could not be ordered first — a cycle. Constrain after creation. */
-  deferred: FkEdge[];
-}
-
-/**
- * Order a table set so a `ref()`'s target always exists before the table that
- * points at it — required by every engine except SQLite, which resolves FK
- * targets lazily and accepts any order (and has no `ALTER TABLE ADD CONSTRAINT`
- * to close a cycle with — a caller on that dialect skips this function entirely).
- *
- * A cycle (`Post → Author → Post`, legal in the model — role.ts's relation
- * thunk exists precisely so two entities can reference each other) has no such
- * order: the loop is broken by deferring ONE of its edges per remaining cycle —
- * that FK is added after every table exists, instead of inline. A self-reference
- * (`parentId: ref(() => Category)`) is not a cycle here: a table may always
- * reference its own not-yet-populated rows inline, standard support across
- * every engine — so it's excluded from the dependency graph entirely.
- */
-export function orderTables(tables: TableDef[]): TableOrder {
-  const byName = new Map(tables.map((table) => [table.name, table]));
-  const needs = new Map(
-    tables.map((table) => [
-      table.name,
-      new Set(
-        table.columns
-          .filter((c) => c.references && c.references.table !== table.name && byName.has(c.references.table))
-          .map((c) => c.references!.table),
-      ),
-    ]),
-  );
-
-  const ordered: TableDef[] = [];
-  const deferred: FkEdge[] = [];
-  const done = new Set<string>();
-
-  while (needs.size > 0) {
-    const ready = [...needs.keys()].find((name) => [...needs.get(name)!].every((dep) => done.has(dep)));
-    if (ready) {
-      ordered.push(byName.get(ready)!);
-      done.add(ready);
-      needs.delete(ready);
-      continue;
-    }
-    // Every table left waits on another table left — a cycle. Break it by
-    // deferring one edge: every column of the first remaining table that points
-    // at its first unmet dependency.
-    const [name, deps] = [...needs.entries()][0];
-    const dep = [...deps].find((d) => !done.has(d))!;
-    const table = byName.get(name)!;
-    for (const column of table.columns) {
-      if (column.references?.table === dep) deferred.push({ table, column });
-    }
-    deps.delete(dep);
-  }
-
-  return { ordered, deferred };
-}