@better-schemic/core 0.1.0-alpha.1

package/src/kind/plan.ts

@@ -0,0 +1,412 @@
+// The GENERIC migration spine over a {@link KindRegistry} — core's kind-blind orchestration. It
+// classifies each portable object as add/change/remove, ORDERS them across kinds by a dependency
+// graph, and emits up/down DDL + the display {@link Diff}. It never names a kind: every kind-specific
+// decision is delegated to that kind's {@link KindEngine}.
+//
+// The spine works on PORTABLE objects (both sides already lowered), exactly like the fixed-slot
+// `Driver.diff(prev, next)`: the stored snapshot IS portable, and the authoring side is lowered once
+// via {@link lowerSchema}. So `prev` is a snapshot, `next` is `lowerSchema(registry, defs)`.
+//
+// Cross-kind ordering is the load-bearing part (docs/kind-registry.md §7.1). THREE layers:
+//   1. dependency GRAPH + topological sort  -> CORRECTNESS (an object emits after everything it deps on)
+//   2. kind ORDINAL (registration order)     -> stable TIE-BREAK among independent objects (layering)
+//   3. OWNER clustering                       -> READABILITY (an index right after its table)
+// A per-kind ordinal ALONE is wrong: a table's event can call a function, so the function must emit
+// BEFORE the table — a function-before-table the graph handles and an ordinal cannot. Drops reverse it.
+
+// NOTE: `Diff`/`DiffItem` are a type-only import (erased at compile — no runtime cli->kind coupling),
+// the same arrangement as ./driver/portable-diff.ts.
+import type { Diff, DiffItem } from "../cli-kit/diff";
+import type {
+  Definable,
+  KindEngine,
+  KindRegistry,
+  PortableObject,
+  Ref,
+} from "./registry";
+
+const refKey = (r: Ref) => `${r.kind}:${r.name}`;
+
+/** A node in the dependency graph: identity + the edges/owner used to order it. */
+export interface OrderNode {
+  readonly kind: string;
+  readonly name: string;
+  /** Objects this node must come AFTER (only intra-set refs constrain; external refs are ignored). */
+  readonly deps: Ref[];
+  /** Owning object to cluster next to (readability tie-break only; never overrides `deps`). */
+  readonly owner?: Ref;
+}
+
+/**
+ * Kahn's topological sort with two presentation tweaks among the nodes whose deps are all satisfied:
+ * prefer one OWNED by the currently-open cluster (so a table's children follow it), then lowest
+ * (kind-ordinal, then name). Correctness (deps) always wins — an owned/low-ordinal node can't jump a
+ * dependency. A genuine cycle throws (a named error). Refs to nodes outside `nodes` are ignored (an
+ * object may depend on something untouched by this diff — it already exists / isn't changing).
+ */
+export function orderObjects<T extends OrderNode>(
+  nodes: T[],
+  ordinalOf: (kind: string) => number,
+): T[] {
+  const byKey = new Map(nodes.map((n) => [refKey(n), n]));
+  const indeg = new Map<string, number>(nodes.map((n) => [refKey(n), 0]));
+  const dependents = new Map<string, string[]>();
+  for (const n of nodes)
+    for (const d of n.deps) {
+      if (!byKey.has(refKey(d))) continue; // external dep -> not a constraint within this set
+      indeg.set(refKey(n), (indeg.get(refKey(n)) ?? 0) + 1);
+      const list = dependents.get(refKey(d)) ?? [];
+      list.push(refKey(n));
+      dependents.set(refKey(d), list);
+    }
+
+  const out: T[] = [];
+  const done = new Set<string>();
+  let group: string | undefined; // the last unowned node emitted == the open cluster
+  while (out.length < nodes.length) {
+    const ready = nodes.filter(
+      (n) => !done.has(refKey(n)) && indeg.get(refKey(n)) === 0,
+    );
+    if (ready.length === 0)
+      throw new Error(
+        `dependency cycle among: ${nodes
+          .filter((n) => !done.has(refKey(n)))
+          .map(refKey)
+          .join(", ")}`,
+      );
+    ready.sort((a, b) => {
+      const ao = a.owner && refKey(a.owner) === group ? 0 : 1; // prefer the open cluster
+      const bo = b.owner && refKey(b.owner) === group ? 0 : 1;
+      return (
+        ao - bo ||
+        ordinalOf(a.kind) - ordinalOf(b.kind) ||
+        refKey(a).localeCompare(refKey(b))
+      );
+    });
+    const next = ready[0];
+    out.push(next);
+    done.add(refKey(next));
+    if (!next.owner) group = refKey(next); // a top-level object opens a new cluster
+    for (const dep of dependents.get(refKey(next)) ?? [])
+      indeg.set(dep, (indeg.get(dep) ?? 1) - 1);
+  }
+  return out;
+}
+
+// --- lowering + snapshot ------------------------------------------------------------------------
+
+/**
+ * Author -> portable: lower each definable through its kind's engine (skipping unregistered kinds).
+ * The single place authoring becomes portable; everything downstream (diff/emit/snapshot) is portable.
+ */
+export function lowerSchema(
+  registry: KindRegistry,
+  defs: Definable[],
+): PortableObject[] {
+  const out: PortableObject[] = [];
+  for (const d of defs) {
+    const engine = registry.engine(d.kind);
+    if (engine) out.push(engine.lower(d));
+  }
+  return out;
+}
+
+/**
+ * The registry SNAPSHOT — portable objects grouped by kind. The open, generic replacement for
+ * `PortableDb`'s fixed slots; serializes as plain JSON (it is plain data). Pre-launch: the format is
+ * free to change, no version migration.
+ */
+export interface KindSnapshot {
+  kinds: Record<string, PortableObject[]>;
+}
+
+/**
+ * Group a flat portable schema into a snapshot (by kind). Pass `registry` to DROP kinds/objects
+ * marked {@link KindEngine.excludeFromMigrations} (e.g. SurrealDB key-bearing access) so unmanaged,
+ * secret-bearing objects never enter a snapshot / migration. Omit it to snapshot every object
+ * unchanged.
+ */
+export function snapshotKinds(
+  schema: PortableObject[],
+  registry?: KindRegistry,
+): KindSnapshot {
+  const kinds: Record<string, PortableObject[]> = {};
+  for (const o of schema) {
+    if (registry?.isExcludedFromMigrations(o)) continue;
+    const bucket = kinds[o.kind] ?? [];
+    bucket.push(o);
+    kinds[o.kind] = bucket;
+  }
+  return { kinds };
+}
+
+/** Flatten a snapshot back into a portable schema (the inverse of {@link snapshotKinds}). */
+export function snapshotObjects(snap: KindSnapshot): PortableObject[] {
+  return Object.values(snap.kinds).flat();
+}
+
+// --- diff / plan --------------------------------------------------------------------------------
+
+/** One classified object change, carrying its ordering metadata + the portable sides for DDL. */
+interface Change extends OrderNode {
+  readonly op: "add" | "change" | "remove";
+  readonly prev?: PortableObject;
+  readonly next?: PortableObject;
+}
+
+/** An up/down DDL program (each a list of statements). */
+export interface KindPlan {
+  up: string[];
+  down: string[];
+}
+
+/** The canonical change-detection key for an object — the kind's `canonical`, else its emitted DDL. */
+const canonicalOf = (engine: KindEngine, p: PortableObject): string =>
+  engine.canonical?.(p) ?? engine.emit(p).join("\n");
+
+const orderNodeOf = (
+  engine: KindEngine,
+  portable: PortableObject,
+): OrderNode => ({
+  kind: portable.kind,
+  name: portable.name,
+  deps: engine.deps?.(portable) ?? [],
+  owner: engine.owner?.(portable),
+});
+
+/** Display identity: `kind:owner:name` (owner blank for a top-level object) + the display owner. */
+const itemKey = (n: OrderNode) => `${n.kind}:${n.owner?.name ?? ""}:${n.name}`;
+const itemTable = (n: OrderNode) => n.owner?.name ?? n.name;
+
+const byKey = (schema: PortableObject[]) =>
+  new Map(schema.map((o) => [refKey(o), o]));
+
+/**
+ * Classify both sides into ordered add/change/remove sets — the shared core of plan + diff. A `change`
+ * is two objects of the same key whose emitted DDL differs (same test as the fixed-slot engine). Each
+ * class is topologically ordered parent-first; the caller reverses one class for drops/inversion.
+ */
+function orderedChanges(
+  registry: KindRegistry,
+  prev: PortableObject[],
+  next: PortableObject[],
+): { nonRemoves: Change[]; removes: Change[] } {
+  const prevByKey = byKey(prev);
+  const nextByKey = byKey(next);
+  const changes: Change[] = [];
+  for (const k of new Set([...prevByKey.keys(), ...nextByKey.keys()])) {
+    const p = prevByKey.get(k);
+    const n = nextByKey.get(k);
+    const portable = n ?? p;
+    if (!portable) continue;
+    // Migration-unmanaged kinds/objects (e.g. key-bearing access) never diff — they're reconciled
+    // out-of-band by driver commands, so they must not appear in gen/migrate/diff-live output.
+    // Central choke point (a per-object predicate is fed the object that would be emitted).
+    if (registry.isExcludedFromMigrations(portable)) continue;
+    const engine = registry.engine(portable.kind);
+    if (!engine) continue;
+    const node = orderNodeOf(engine, portable);
+    if (p && !n) changes.push({ op: "remove", prev: p, ...node });
+    else if (!p && n) changes.push({ op: "add", next: n, ...node });
+    else if (p && n && canonicalOf(engine, p) !== canonicalOf(engine, n))
+      changes.push({ op: "change", prev: p, next: n, ...node });
+  }
+  const ord = (kind: string) => registry.ordinal(kind);
+  return {
+    nonRemoves: orderObjects(
+      changes.filter((c) => c.op !== "remove"),
+      ord,
+    ),
+    removes: orderObjects(
+      changes.filter((c) => c.op === "remove"),
+      ord,
+    ),
+  };
+}
+
+const overwriteUp = (
+  engine: KindEngine,
+  a: PortableObject,
+  b: PortableObject,
+): string[] =>
+  engine.overwrite?.(a, b) ?? [...engine.remove(a), ...engine.emit(b)];
+
+/**
+ * Diff two portable schema states into an executable up/down program, generically over the registry.
+ *
+ * `up` runs creates/changes parent-first (the dependency graph) then drops child-first; `down` is the
+ * mirror: recreate drops parent-first, then undo creates/changes child-first. We invert PER OBJECT (not
+ * by reversing the flat DDL list) so a kind's multi-line block — a table emitted with its fields —
+ * keeps its internal order in both directions.
+ */
+export function planKinds(
+  registry: KindRegistry,
+  prev: PortableObject[],
+  next: PortableObject[],
+): KindPlan {
+  const { nonRemoves, removes } = orderedChanges(registry, prev, next);
+  const up: string[] = [];
+  const down: string[] = [];
+  for (const c of nonRemoves) {
+    const e = registry.engine(c.kind);
+    if (!e) continue;
+    if (c.op === "add" && c.next) up.push(...e.emit(c.next));
+    else if (c.op === "change" && c.prev && c.next)
+      up.push(...overwriteUp(e, c.prev, c.next));
+  }
+  for (const c of [...removes].reverse()) {
+    const e = registry.engine(c.kind); // drops child-first
+    if (e && c.prev) up.push(...e.remove(c.prev));
+  }
+  for (const c of removes) {
+    const e = registry.engine(c.kind); // recreate dropped objects parent-first
+    if (e && c.prev) down.push(...e.emit(c.prev));
+  }
+  for (const c of [...nonRemoves].reverse()) {
+    const e = registry.engine(c.kind); // undo creates/changes child-first
+    if (!e) continue;
+    if (c.op === "add" && c.next) down.push(...e.remove(c.next));
+    else if (c.op === "change" && c.prev && c.next)
+      down.push(...overwriteUp(e, c.next, c.prev));
+  }
+  return { up, down };
+}
+
+/**
+ * Display items for a change set, in up order (creates/changes parent-first, drops child-first). A kind
+ * with `displayItems` decomposes into FINE-grained sub-items (per-field, each carrying its `table` so
+ * the display groups them under it); otherwise it falls back to ONE whole-object item.
+ */
+function diffItems(
+  registry: KindRegistry,
+  nonRemoves: Change[],
+  removes: Change[],
+): DiffItem[] {
+  const items: DiffItem[] = [];
+  const push = (c: Change) => {
+    const e = registry.engine(c.kind);
+    if (!e) return;
+    if (e.displayItems) {
+      items.push(...e.displayItems(c.prev, c.next));
+      return;
+    }
+    const base = { key: itemKey(c), table: itemTable(c), kind: c.kind };
+    if (c.op === "add" && c.next)
+      items.push({ ...base, op: "add", ddl: e.emit(c.next).join("\n") });
+    else if (c.op === "remove" && c.prev)
+      items.push({
+        ...base,
+        op: "remove",
+        ddl: e.remove(c.prev).join("\n"),
+        old: e.emit(c.prev).join("\n"),
+      });
+    else if (c.op === "change" && c.prev && c.next)
+      items.push({
+        ...base,
+        op: "change",
+        before: e.emit(c.prev).join("\n"),
+        after: e.emit(c.next).join("\n"),
+      });
+  };
+  for (const c of nonRemoves) push(c);
+  for (const c of [...removes].reverse()) push(c);
+  return items;
+}
+
+/**
+ * The full {@link Diff} the CLI + migration model consume — up/down DDL + per-object display items +
+ * the whole desired schema (`full`, for `--full`). This is what a driver's `Driver.diff` returns once
+ * its kinds are on the registry (the generic counterpart of the fixed-slot `buildDiff`). Source-file
+ * linkage on the items is attached by the caller (the snapshot's `files` map), so `file` is left unset.
+ */
+export function buildKindDiff(
+  registry: KindRegistry,
+  prev: PortableObject[],
+  next: PortableObject[],
+): Diff {
+  const { nonRemoves, removes } = orderedChanges(registry, prev, next);
+  const { up, down } = planKinds(registry, prev, next);
+  // `full` mirrors the items' granularity: a kind with `displayItems` projects its object as per-
+  // sub-object adds (displayItems(undefined, portable)); otherwise one whole-object entry.
+  const full = orderedSchema(registry, next).flatMap(
+    ({ engine, portable, node }) => {
+      if (engine.displayItems)
+        return engine.displayItems(undefined, portable).map((it) => ({
+          key: it.key,
+          table: it.table,
+          ddl: it.op === "add" ? it.ddl : "",
+        }));
+      return [
+        {
+          key: itemKey(node),
+          table: itemTable(node),
+          ddl: engine.emit(portable).join("\n"),
+        },
+      ];
+    },
+  );
+  return { up, down, items: diffItems(registry, nonRemoves, removes), full };
+}
+
+/** Lower-already portable schema, topologically ordered, paired with each object's engine + node. */
+function orderedSchema(
+  registry: KindRegistry,
+  schema: PortableObject[],
+): { engine: KindEngine; portable: PortableObject; node: OrderNode }[] {
+  const items = schema.flatMap((portable) => {
+    const engine = registry.engine(portable.kind);
+    return engine
+      ? [{ engine, portable, node: orderNodeOf(engine, portable) }]
+      : [];
+  });
+  const pos = new Map(
+    orderObjects(
+      items.map((i) => i.node),
+      (k) => registry.ordinal(k),
+    ).map((n, i) => [itemKey(n), i]),
+  );
+  return items.sort(
+    (a, b) => (pos.get(itemKey(a.node)) ?? 0) - (pos.get(itemKey(b.node)) ?? 0),
+  );
+}
+
+/**
+ * Fresh-apply DDL for a portable schema: every object created, ordered across kinds by the graph.
+ * (The `up` of a diff from an empty state.) Lower authoring first via {@link lowerSchema}.
+ */
+export function emitKinds(
+  registry: KindRegistry,
+  schema: PortableObject[],
+): string[] {
+  // Skip migration-unmanaged kinds/objects (e.g. key-bearing access) — they're applied out-of-band
+  // by driver commands.
+  const managed = schema.filter(
+    (o) => !registry.isExcludedFromMigrations(o),
+  );
+  return orderedSchema(registry, managed).flatMap(({ engine, portable }) =>
+    engine.emit(portable),
+  );
+}
+
+/**
+ * Reverse direction, fanned out across kinds: introspect every introspectable kind off one live
+ * connection and flatten into portable objects. The RESOLUTION of "per-kind vs one driver read":
+ * the contract is per-kind ({@link KindEngine.introspect}), but a driver backs all of its kinds with
+ * ONE shared (memoized) read of `conn` and slices out each kind's objects — so the fan-out here costs
+ * a single round-trip, not N. A kind without `introspect` contributes nothing (not introspectable).
+ */
+export async function introspectKinds(
+  registry: KindRegistry,
+  conn: unknown,
+): Promise<PortableObject[]> {
+  const out: PortableObject[] = [];
+  for (const [kind, engine] of registry.entries()) {
+    if (!engine.introspect) continue;
+    // Skip STATICALLY migration-unmanaged kinds so the live side never phantom-diffs against a
+    // schema that (by design) excludes them. A per-object predicate can't be evaluated without the
+    // object — introspection still runs, and the diff choke point filters by object afterwards.
+    if (registry.skipsIntrospection(kind)) continue;
+    out.push(...(await engine.introspect(conn)));
+  }
+  return out;
+}

package/src/kind/registry.ts

@@ -0,0 +1,270 @@
+// The KIND REGISTRY — core-v2's generic, open replacement for the fixed object-kind slots.
+//
+// Today `PortableDb` hard-codes the object kinds a schema may contain (`tables`/`functions`/
+// `accesses`/`natives`) and the Driver's whole-DB methods switch on those slots. The kind registry
+// turns the slots into a REGISTRY a driver populates: each driver registers KINDS, and every kind
+// brings (a) its OWN authoring builder — any shape/chain it likes, fully typed — and (b) its engine
+// behavior (`lower`/`emit`/`remove`/`overwrite`/`deps`/`owner`/`introspect`) over THAT kind's objects.
+// Core orchestrates generically over the registry (see ./plan.ts) and never names a kind.
+//
+// What stays in core is the field/type VOCABULARY (`SFieldBase`, the Zod-drop-in `s.*`, `PortableType`,
+// codecs) — the substrate every kind builds on. Fields/types are NOT a kind: a table HAS fields, a
+// function's args ARE fields, an index REFERENCES fields. See docs/kind-registry.md.
+//
+// The registry is PER-DRIVER, not a module global: a driver builds one `KindRegistry` and registers
+// its kinds into it.
+
+/**
+ * An authored definable, tagged with the KIND that owns it. Core dispatches on `kind` alone — every
+ * other field is the kind's own business, handed straight to {@link KindEngine.lower}. This is the
+ * neutral upper bound for a kind's authoring-object type (a driver's concrete `TableDef`/`FnDef` is a
+ * structural subtype).
+ */
+export interface Definable {
+  readonly kind: string;
+  readonly name: string;
+}
+
+/**
+ * A kind's PORTABLE object — the dialect-independent data shape core stores + diffs. A kind chooses
+ * how structured this is: a table's portable form carries fields/indexes (so core can field-level
+ * diff it); an opaque kind (function/access) carries a neutral identity + a `native` payload it
+ * round-trips. Either way it is tagged with `kind`/`name` for cross-kind dispatch + ordering.
+ */
+export interface PortableObject {
+  readonly kind: string;
+  readonly name: string;
+}
+
+/** A reference to another object in the schema graph — the unit of cross-kind dependency ordering. */
+export interface Ref {
+  readonly kind: string;
+  readonly name: string;
+}
+
+// `DiffItem` is a type-only import (erased at compile) — the display contract the `displayItems` hook
+// produces; no runtime cli->kind coupling, same arrangement as ./plan.ts.
+import type { DiffItem } from "../cli-kit/diff";
+
+/**
+ * What core needs to orchestrate ONE kind generically — it never inspects the specifics. The
+ * change-vocabulary (`emit`/`remove`/`overwrite`) mirrors the Driver contract's, so a kind's behavior
+ * is parity-checkable against the fixed-slot engine. `A` is the kind's authoring object, `P` its
+ * portable object; both are opaque to core beyond the {@link Definable}/{@link PortableObject} bounds.
+ */
+export interface KindEngine<
+  A extends Definable = Definable,
+  P extends PortableObject = PortableObject,
+> {
+  /** Authoring object -> this kind's portable object (normalized; both lowerings must converge here). */
+  lower(authored: A): P;
+  /** CREATE DDL for one portable object (a fresh apply / migration `up` for an added object). */
+  emit(portable: P): string[];
+  /** DROP DDL for one portable object (`up` for a removed object, `down` for an added one). */
+  remove(portable: P): string[];
+  /**
+   * In-place CHANGE DDL taking `prev` to `next` (the dialect's ALTER/OVERWRITE). The spine calls
+   * `overwrite(next, prev)` to roll a change back. A kind with no in-place form recreates: implement
+   * as `[...remove(prev), ...emit(next)]`. Default (omitted) = recreate via emit(next).
+   */
+  overwrite?(prev: P, next: P): string[];
+  /**
+   * The CANONICAL change-detection key: the spine treats prev/next of the same object as a CHANGE iff
+   * their `canonical` differs. Default (omitted) = `emit(portable).join("\n")` — so a kind whose `emit`
+   * is already its canonical form needs nothing. Override when `emit` is FAITHFUL but some clauses must
+   * be EXCLUDED from equality — because the DB rewrites them on read (a cast suffix like `'x'::text`,
+   * added parens like `(a>0)`) or never introspects them (a COMMENT, an index) — so a faithful `emit` would phantom-diff a
+   * freshly-applied schema against `introspect`. Return `emit` MINUS those clauses: they stay create-time
+   * faithful in `emit`, but don't count as changes. `canonical(a) === canonical(b)` MUST mean "no
+   * migration needed". Affects ONLY classification; `emit`/`overwrite` (the DDL) are unaffected.
+   */
+  canonical?(portable: P): string;
+  /**
+   * Fine-grained DISPLAY items for a change of this object — so `better-schemic diff` shows per-SUB-OBJECT
+   * changes (a table decomposes into per-FIELD items: `field:user:name` changed), each carrying its
+   * owner `table` so the display GROUPS them hierarchically under it, instead of one coarse whole-object
+   * item. Called `(prev, next)`: a change diffs the two; `(undefined, next)` lists the object's
+   * sub-items as adds — the `--full` projection core uses for the full desired-state view. Default
+   * (omitted) = ONE whole-object item. DISPLAY ONLY — never affects up/down DDL (that is
+   * `emit`/`overwrite`); a structured driver reuses the per-field diff it already computes. Leave
+   * `DiffItem.file` unset (the caller attaches source linkage).
+   */
+  displayItems?(prev: P | undefined, next: P | undefined): DiffItem[];
+  /**
+   * Objects this one must be emitted AFTER — the cross-kind dependency edges (a field/index -> its
+   * table; an edge table -> its in/out tables; an event -> its table + any function it calls). Drives
+   * the topological sort in ./plan.ts. Omitted = no dependencies.
+   */
+  deps?(portable: P): Ref[];
+  /**
+   * The owning object to CLUSTER next to in the emitted order (an index's table) — readability only,
+   * never overrides {@link deps}. Omitted = a top-level object.
+   */
+  owner?(portable: P): Ref | undefined;
+  /**
+   * The STRUCTURAL container this object is nested within (an index's/field's table) — used for
+   * ADDRESSING and grouping (the CLI's dotted `parent.child`, e.g. `sc index info user.email_idx`) and
+   * distinct from {@link owner}, which is a DISPLAY choice (diff clustering). A kind may declare `parent`
+   * (it IS nested) while declining `owner` (it doesn't want per-parent diff clustering), or vice versa.
+   * The CLI resolves a nesting address as `parent ?? owner` (so a kind that only sets `owner` still
+   * addresses dotted). Omitted (and no `owner`) = a top-level object, addressed by its bare name.
+   */
+  parent?(portable: P): Ref | undefined;
+  /**
+   * Live connection -> all portable objects of THIS kind (the reverse direction). Introspection is
+   * often one `INFO`/catalog read yielding every kind at once; a driver backs all of its kinds'
+   * `introspect` with one shared (memoized) read and slices out this kind's objects. Omitted -> this
+   * kind isn't introspectable (diff/emit still work from authored state).
+   */
+  introspect?(conn: unknown): Promise<P[]>;
+  /**
+   * How this kind is PRESENTED — its human labels and the folder its objects render into. All optional
+   * with sensible defaults off the kind name (see {@link KindRegistry.display}), so a kind only declares
+   * what the defaults get wrong (e.g. `plural: "Indexes"`, or `folder: "access"`). DISPLAY ONLY.
+   */
+  display?: KindDisplay;
+  /**
+   * UNMANAGED by the migration pipeline: when `true`, objects of this kind are EXCLUDED from
+   * snapshot / diff / gen AND from the introspect-compare — so they never enter a migration file nor
+   * phantom-diff. For a kind whose lifecycle doesn't fit committed migrations: e.g. SurrealDB
+   * `DEFINE ACCESS`, which carries a secret the DB redacts on introspection (can't round-trip) and
+   * rotates on its own cadence. Such a kind is managed OUT-OF-BAND via the driver's own commands
+   * (`sc <kind> …`). `emit`/`lower` still work (a driver command may use them); only the automatic
+   * migration lifecycle skips it. Omitted/false = a normal, migration-managed kind.
+   *
+   * A PREDICATE form (`(portable) => boolean`) decides PER OBJECT — for a kind whose objects are
+   * managed only when they round-trip cleanly (e.g. SurrealDB access: key-free defs are manageable,
+   * key-bearing/redacted ones are not). The object is REQUIRED by
+   * {@link KindRegistry.isExcludedFromMigrations}; only a boolean `true` also skips introspection
+   * ({@link KindRegistry.skipsIntrospection}) — a predicate can't be decided there.
+   */
+  excludeFromMigrations?: boolean | ((portable: PortableObject) => boolean);
+}
+
+/** Per-kind presentation metadata (labels + output folder). All optional; core fills defaults. */
+export interface KindDisplay {
+  /** Title-Case singular, e.g. `"Table"`, `"Field"`. Default: the kind name, capitalized. */
+  label?: string;
+  /** Title-Case plural, e.g. `"Tables"`, `"Indexes"`. Default: the English plural of `label`. */
+  plural?: string;
+  /** The directory this kind's objects render into. Default: the lowercase slug of `plural`. */
+  folder?: string;
+}
+
+/** A kind's resolved presentation — every field filled (the shape {@link KindRegistry.display} returns). */
+export type ResolvedDisplay = Required<KindDisplay>;
+
+/** A kind's full spec: its `name`, its `build` (the driver's authoring entry), and its engine. */
+export type KindSpec<
+  Build extends (...args: never[]) => unknown,
+  A extends Definable,
+  P extends PortableObject,
+> = { name: string; build: Build } & KindEngine<A, P>;
+
+/** `"table"` -> `"Table"`. */
+function capitalize(s: string): string {
+  return s ? s[0].toUpperCase() + s.slice(1) : s;
+}
+
+/** A plain English pluralizer for kind labels: `Index` -> `Indexes`, `Policy` -> `Policies`. */
+function pluralize(s: string): string {
+  if (/[^aeiou]y$/i.test(s)) return `${s.slice(0, -1)}ies`;
+  if (/(s|x|z|ch|sh)$/i.test(s)) return `${s}es`;
+  return `${s}s`;
+}
+
+/** `"Tables"` -> `"tables"`; collapses non-alphanumerics to single dashes (a filesystem-safe folder). */
+function slugify(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * A driver's set of registered kinds + the generic behavior the spine reads off them. Built once per
+ * driver; `define` registers a kind and returns the driver's OWN `build` function UNCHANGED — so the
+ * driver writes `export const defineTable = registry.define({ name: "table", build, ...engine })` and
+ * keeps full type-safety + DX (TS preserves a generic `build`'s parameters across the passthrough).
+ */
+export class KindRegistry {
+  // Heterogeneous kinds erase at the engine seam (engine ops are structural); the AUTHORING side
+  // keeps full types via `define`'s `Build` passthrough.
+  // biome-ignore lint/suspicious/noExplicitAny: the engine seam is intentionally type-erased.
+  private readonly kinds = new Map<string, KindEngine<any, any>>();
+
+  /**
+   * Register a KIND. `build` is the driver's own authoring entry — ANY shape/chain — and its type
+   * flows through unchanged (type-safety + DX are the driver's to design). The engine fns give core
+   * the generic behavior. Registration ORDER is the kind's ordinal (the stable tie-break among
+   * independent objects in {@link orderObjects}), so register coarse-to-fine (table before index).
+   */
+  define<
+    Build extends (...args: never[]) => unknown,
+    A extends Definable,
+    P extends PortableObject,
+  >(spec: KindSpec<Build, A, P>): Build {
+    this.kinds.set(spec.name, spec);
+    return spec.build;
+  }
+
+  /** The engine for `kind`, or undefined if no such kind is registered. */
+  // biome-ignore lint/suspicious/noExplicitAny: the engine erases at this seam (see `kinds`).
+  engine(kind: string): KindEngine<any, any> | undefined {
+    return this.kinds.get(kind);
+  }
+
+  /**
+   * Is this PORTABLE OBJECT UNMANAGED by the migration pipeline (its engine set
+   * {@link KindEngine.excludeFromMigrations})? The snapshot/diff/emit spine skips such objects — see
+   * the flag's docs. The OBJECT is required: a per-object predicate can't be evaluated without it, and
+   * defaulting to "managed" would let a key-bearing object slip into a migration. An unregistered kind
+   * is treated as managed (false), so a stray object never gets silently dropped by a typo.
+   */
+  isExcludedFromMigrations(portable: PortableObject): boolean {
+    const flag = this.kinds.get(portable.kind)?.excludeFromMigrations;
+    return typeof flag === "function" ? flag(portable) : flag === true;
+  }
+
+  /**
+   * Whether `kind` is STATICALLY excluded from migrations (`excludeFromMigrations === true`), so even
+   * introspection skips it. A per-object PREDICATE can't be decided without an object: introspection
+   * runs for the kind, and the diff/snapshot/emit choke points filter by object afterwards.
+   */
+  skipsIntrospection(kind: string): boolean {
+    return this.kinds.get(kind)?.excludeFromMigrations === true;
+  }
+
+  /**
+   * A kind's resolved presentation — `label`/`plural`/`folder`, with defaults derived from the kind
+   * name for whatever the driver left unset. Works for unregistered display sub-kinds too (e.g. the
+   * `"field"` items a table's `displayItems` emits) — they just get the name-derived defaults.
+   */
+  display(kind: string): ResolvedDisplay {
+    const d = this.kinds.get(kind)?.display ?? {};
+    const label = d.label ?? capitalize(kind);
+    const plural = d.plural ?? pluralize(label);
+    return { label, plural, folder: d.folder ?? slugify(plural) };
+  }
+
+  /** Registered kind names, in registration order (== ordinal order). */
+  names(): string[] {
+    return [...this.kinds.keys()];
+  }
+
+  /**
+   * A kind's ORDINAL = its registration index. Used ONLY as a tie-break among objects with no
+   * dependency relation, so independent objects come out stably layered (readability); it never
+   * overrides the dependency graph. An unknown kind sorts last.
+   */
+  ordinal(kind: string): number {
+    const i = this.names().indexOf(kind);
+    return i === -1 ? Number.MAX_SAFE_INTEGER : i;
+  }
+
+  /** [name, engine] pairs in registration order — the spine iterates these. */
+  // biome-ignore lint/suspicious/noExplicitAny: the engine erases at this seam (see `kinds`).
+  entries(): [string, KindEngine<any, any>][] {
+    return [...this.kinds.entries()];
+  }
+}