@schemic/core 0.1.0-alpha.0

package/src/cli-kit/schema.ts

@@ -0,0 +1,186 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { Authored, AuthoredDef } from "@schemic/core";
+import { makeJiti } from "./config";
+
+/**
+ * The NEUTRAL view of a loaded table the engine reads — just `name` plus the `config.relation` flag
+ * used for ordering. A driver casts this to its own concrete table builder in `lower`. (The runtime
+ * object is the driver's real `TableDef`; the engine never names that type.)
+ */
+export interface AnyTable extends Authored {
+  readonly config: { readonly relation?: unknown };
+}
+
+/**
+ * Duck-typed `TableDef` check. We avoid `instanceof` on purpose: the user's schema and the
+ * CLI may end up with different module instances of `@schemic/core`, so we recognize a table
+ * by shape instead. (Structural access into `emitStatements` works regardless.)
+ */
+function isTableDef(v: unknown): v is AnyTable {
+  if (!v || typeof v !== "object") return false;
+  const t = v as Record<string, unknown>;
+  return (
+    typeof t.name === "string" &&
+    typeof t.fields === "object" &&
+    t.fields !== null &&
+    typeof t.config === "object" &&
+    t.config !== null &&
+    typeof t.record === "function"
+  );
+}
+
+/** Duck-typed standalone-def check (`defineEvent`/`defineFunction`) — see `isTableDef` on why not `instanceof`. */
+function isStandaloneDef(v: unknown): v is AuthoredDef {
+  if (!v || typeof v !== "object") return false;
+  const d = v as Record<string, unknown>;
+  return (
+    (d.kind === "event" || d.kind === "function" || d.kind === "access") &&
+    typeof d.name === "string"
+  );
+}
+
+function tsFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir).sort()) {
+    const p = join(dir, entry);
+    if (statSync(p).isDirectory()) out.push(...tsFiles(p));
+    else if (/\.(ts|mts|js|mjs)$/.test(entry) && !entry.endsWith(".d.ts"))
+      out.push(p);
+  }
+  return out;
+}
+
+/** The schema module file(s) for a path: the file itself, or every module under the directory. */
+function schemaFiles(path: string): string[] {
+  return statSync(path).isFile() ? [path] : tsFiles(path);
+}
+
+/** Import a schema module file and yield its exported tables/relations, paired with the file. */
+async function* tablesIn(
+  jiti: ReturnType<typeof makeJiti>,
+  file: string,
+): AsyncGenerator<AnyTable> {
+  const mod = (await jiti.import(file)) as Record<string, unknown>;
+  for (const value of Object.values(mod)) if (isTableDef(value)) yield value;
+}
+
+/**
+ * Load every schema object from `schemaPath` (a single `.ts` module, or a directory of them): the
+ * tables/relations (ordered normal-before-relation, then by name, for stable DDL) and the standalone
+ * defs (`defineEvent`/`defineFunction`). One pass over the files.
+ */
+export async function loadDefs(schemaPath: string): Promise<{
+  tables: AnyTable[];
+  defs: AuthoredDef[];
+  /** Absolute source file each table/def was loaded from (for `diff`'s file annotations). */
+  fileOf: Map<AnyTable | AuthoredDef, string>;
+}> {
+  if (!existsSync(schemaPath)) {
+    throw new Error(`Schema path not found: ${schemaPath}`);
+  }
+  const jiti = makeJiti();
+  const tables = new Map<string, AnyTable>();
+  const defs: AuthoredDef[] = [];
+  const fileOf = new Map<AnyTable | AuthoredDef, string>();
+  for (const file of schemaFiles(schemaPath)) {
+    const mod = (await jiti.import(file)) as Record<string, unknown>;
+    for (const value of Object.values(mod)) {
+      if (isTableDef(value)) {
+        tables.set(value.name, value); // last def of a name wins
+        fileOf.set(value, file);
+      } else if (isStandaloneDef(value)) {
+        defs.push(value);
+        fileOf.set(value, file);
+      }
+    }
+  }
+  const rank = (t: AnyTable) => (t.config.relation ? 1 : 0);
+  const sorted = [...tables.values()].sort(
+    (a, b) => rank(a) - rank(b) || a.name.localeCompare(b.name),
+  );
+  return { tables: sorted, defs, fileOf };
+}
+
+/** The tables/relations from `schemaPath` (standalone events excluded — see {@link loadDefs}). */
+export async function loadSchemas(schemaPath: string): Promise<AnyTable[]> {
+  return (await loadDefs(schemaPath)).tables;
+}
+
+/** A schema file's exported entities (tables/functions/accesses) and whether it holds ONLY those. */
+export interface LocalFileEntities {
+  /** Each schema entity by its export-const identifier + its DB name (table/function/access name). */
+  entities: { exportName: string; name: string; kind: "table" | "def" }[];
+  /** True when EVERY runtime export of the file is a schema entity (no helpers / other exports). */
+  pureSchema: boolean;
+}
+
+/**
+ * Scan each schema file for the tables/functions/accesses it exports (by export-const name), and
+ * whether the file is purely schema. `pull` uses this to find whole-entity local-only schema
+ * (entities the live DB doesn't have) and to decide whether a file is safe to delete when mirroring
+ * the DB. Standalone events are not whole entities (they attach to a table), so they don't count as
+ * entities — a file exporting one is therefore not `pureSchema` and won't be auto-deleted.
+ */
+export async function scanLocalEntities(
+  schemaPath: string,
+): Promise<Map<string, LocalFileEntities>> {
+  if (!existsSync(schemaPath)) return new Map();
+  const jiti = makeJiti();
+  const out = new Map<string, LocalFileEntities>();
+  for (const file of schemaFiles(schemaPath)) {
+    const exports = Object.entries(
+      (await jiti.import(file)) as Record<string, unknown>,
+    );
+    const entities: LocalFileEntities["entities"] = [];
+    for (const [exportName, value] of exports) {
+      if (isTableDef(value))
+        entities.push({ exportName, name: value.name, kind: "table" });
+      else if (
+        isStandaloneDef(value) &&
+        (value.kind === "function" || value.kind === "access")
+      )
+        entities.push({ exportName, name: value.name, kind: "def" });
+    }
+    if (entities.length)
+      out.set(file, {
+        entities,
+        pureSchema: entities.length === exports.length,
+      });
+  }
+  return out;
+}
+
+/** Map of table name → the file that defines it (for `pull`'s duplicate-definition check). */
+export async function existingTables(
+  schemaPath: string,
+): Promise<Map<string, string>> {
+  if (!existsSync(schemaPath)) return new Map();
+  const jiti = makeJiti();
+  const out = new Map<string, string>();
+  for (const file of schemaFiles(schemaPath)) {
+    for await (const t of tablesIn(jiti, file)) out.set(t.name, file);
+  }
+  return out;
+}
+
+/**
+ * Names defined in more than one place, mapped to the files that define them (a file repeats if it
+ * defines the same name twice). `loadSchemas` silently lets the last definition win, so this is how
+ * `doctor` surfaces the otherwise-invisible conflict.
+ */
+export async function duplicateTables(
+  schemaPath: string,
+): Promise<Map<string, string[]>> {
+  if (!existsSync(schemaPath)) return new Map();
+  const jiti = makeJiti();
+  const seen = new Map<string, string[]>();
+  for (const file of schemaFiles(schemaPath)) {
+    for await (const t of tablesIn(jiti, file)) {
+      const files = seen.get(t.name);
+      if (files) files.push(file);
+      else seen.set(t.name, [file]);
+    }
+  }
+  return new Map([...seen].filter(([, files]) => files.length > 1));
+}

package/src/cli-kit/style.ts

@@ -0,0 +1,24 @@
+// Tiny ANSI styling, gated on a TTY and honoring NO_COLOR. No dependency.
+/** Whether colored output is enabled (a TTY and `NO_COLOR` unset). */
+export const colorEnabled = () =>
+  Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+const paint = (code: number, s: string) =>
+  colorEnabled() ? `\x1b[${code}m${s}\x1b[0m` : s;
+
+export const style = {
+  green: (s: string) => paint(32, s),
+  red: (s: string) => paint(31, s),
+  yellow: (s: string) => paint(33, s),
+  cyan: (s: string) => paint(36, s),
+  dim: (s: string) => paint(90, s),
+  bold: (s: string) => paint(1, s),
+};
+
+/** A green ✓ success line. */
+export const ok = (s: string) => `${style.green("✓")} ${s}`;
+/** A red ✗ failure line. */
+export const fail = (s: string) => `${style.red("✗")} ${s}`;
+
+/** Pluralize `n thing` / `n things`. */
+export const plural = (n: number, word: string) =>
+  `${n} ${word}${n === 1 ? "" : "s"}`;

package/src/config.ts

@@ -0,0 +1,51 @@
+/**
+ * Configuration for the `schemic` CLI — author it in `schemic.config.ts`.
+ *
+ * A project declares one or more named CONNECTIONS, each built by a per-driver factory
+ * (`<driver>Connection(...)` exported from `@schemic/<driver>`). Connection values are EXPLICIT —
+ * there is no env-var magic; read env yourself where you want it (`url: process.env.MY_URL`).
+ * See `@schemic/core` docs/MULTI-CONNECTION.md.
+ *
+ * ```ts
+ * import { defineConfig } from "@schemic/core/config";
+ * import { surrealConnection } from "@schemic/surrealdb";
+ *
+ * export default defineConfig({
+ *   connections: {
+ *     default: surrealConnection({
+ *       schema: "./database/schema",
+ *       url: "ws://localhost:8000",
+ *       namespace: "app",
+ *       database: "app",
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * For MULTIPLE databases (multi-tenant / heterogeneous / DB-per-user), add more named connections;
+ * a connection may be a resolver (incl. an array → a collection). See docs/MULTI-CONNECTION.md.
+ *
+ * NOTE: this file is dialect-NEUTRAL. Driver-specific connection shapes (SurrealDB's
+ * url/namespace/authLevel, its check-engine options, …) live in the driver package's
+ * `<driver>Connection` factory, not here.
+ */
+import type { ConnectionEntry } from "./connection";
+
+export interface SchemicConfig {
+  /** Named database connections — each produced by a per-driver `<driver>Connection(...)` factory. */
+  connections: Record<string, ConnectionEntry>;
+  /**
+   * With more than one connection, the connection a bare command targets (must name a single static
+   * connection). Absent + ambiguous → a live command errors asking for `--connection`.
+   */
+  defaultConnection?: string;
+  /** Table that records applied migrations (per connection). Default `_migrations`. */
+  migrationsTable?: string;
+  /** Optional seed script run by `schemic seed`. */
+  seed?: string;
+}
+
+/** Identity helper that types a `schemic.config.ts` default export. */
+export function defineConfig(config: SchemicConfig): SchemicConfig {
+  return config;
+}

package/src/connection.ts

@@ -0,0 +1,78 @@
+// The neutral MULTI-CONNECTION contract (design: docs/MULTI-CONNECTION.md). A project's config maps
+// names to CONNECTIONS; each is produced by a per-driver `<driver>Connection(...)` factory that wraps
+// {@link connectionEntry} with its own typed connection shape. Everything here is dialect-free — the
+// CLI reads only these neutral fields; driver-specific connection params ride on the driver's own
+// config type. The resolution engine (lazy DAG, fan-out, addressing) lives in the CLI layer.
+
+type MaybePromise<T> = T | Promise<T>;
+
+/** The dialect-neutral fields the orchestration reads off every connection config. */
+export interface ConnectionConfigBase {
+  /** Schema dir (the desired state + its migration files/snapshot). Shared dir = shared schema. */
+  schema: string;
+  /** Address within a COLLECTION (array-returning resolver) — `<name>:<key>`. Required on array entries. */
+  key?: string;
+  /** Migrations dir override; defaults relative to `schema`. */
+  migrations?: string;
+}
+
+/** A live, queryable handle to ANOTHER (already-resolved) connection, for use inside a resolver. */
+export interface ResolvedConnectionHandle {
+  query<T = unknown>(sql: string, vars?: Record<string, unknown>): Promise<T[]>;
+}
+
+/**
+ * What a connection RESOLVER receives. `connections` is a LAZY proxy of the other connections —
+ * touching one resolves + connects it on demand (so the dependency graph falls out of access; cycles
+ * error). `args` are CLI `--arg k=v` values (so a resolver can yield a SUBSET without resolving all).
+ */
+export interface ResolveContext {
+  connections: Record<string, ResolvedConnectionHandle>;
+  args: Record<string, string>;
+  env: NodeJS.ProcessEnv;
+}
+
+/**
+ * The opaque, branded output of a `<driver>Connection(...)` factory — the only thing `defineConfig`'s
+ * `connections` map accepts. Never hand-authored. `driver` is the package the CLI dynamically loads;
+ * `resolve` always normalizes to an ARRAY (a single connection -> one element, a collection -> many).
+ */
+export interface ConnectionEntry {
+  readonly __schemic: "connection";
+  readonly driver: string;
+  resolve(ctx: ResolveContext): Promise<ConnectionConfigBase[]>;
+}
+
+/** A connection factory's input: a static config, or a resolver yielding one config or a keyed collection. */
+export type ConnectionInput<C extends ConnectionConfigBase> =
+  | C
+  | ((ctx: ResolveContext) => MaybePromise<C | (C & { key: string })[]>);
+
+/**
+ * Build a {@link ConnectionEntry} from a driver tag + a static config or resolver — the primitive each
+ * driver package wraps in its typed `<driver>Connection(...)` factory (which fixes `C` to the driver's
+ * own connection shape and overloads the array form to require `key`). Returns a branded entry whose
+ * `resolve` always yields an array.
+ */
+export function connectionEntry<C extends ConnectionConfigBase>(
+  driver: string,
+  input: ConnectionInput<C>,
+): ConnectionEntry {
+  return {
+    __schemic: "connection",
+    driver,
+    async resolve(ctx) {
+      const out = typeof input === "function" ? await input(ctx) : input;
+      return Array.isArray(out) ? out : [out];
+    },
+  };
+}
+
+/** Type guard: is a `connections` map value a real factory output (vs a stray object)? */
+export function isConnectionEntry(v: unknown): v is ConnectionEntry {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    (v as { __schemic?: unknown }).__schemic === "connection"
+  );
+}

package/src/driver/driver.ts

@@ -0,0 +1,300 @@
+// The DRIVER interface — the dialect seam for multi-DB support (see docs/MULTI-DB-SPIKE.md).
+//
+// Everything dialect-specific lives behind a `Driver`: lowering authoring to the Struct-IR, emitting
+// DDL, introspecting a live DB, normalizing to a canonical form, and executing. Everything ABOVE the
+// driver (the diff algorithm, the magicast TS-merge, the migration model, the CLI shell) stays
+// dialect-free and calls these ops.
+//
+// The connection type is a driver-private parameter `Conn`: the orchestration treats it opaquely and
+// only ever hands it back to the SAME driver. So the Surreal driver is `Driver<Surreal>`, a future
+// Postgres driver is `Driver<PgClient>`, and core never sees either concrete type. The AUTHORING
+// types (`Tbl`/`Def`) are driver-private the same way — opaque to core beyond the neutral
+// `Authored`/`AuthoredDef` bounds — so the neutral engine never names a dialect's concrete builder
+// (`TableDef`/`StandaloneDef`).
+
+import type { ResolvedConfig } from "../cli-kit/config";
+import type { Diff } from "../cli-kit/diff";
+import type { Filter } from "../cli-kit/filter";
+import type { PullPlan } from "../cli-kit/merge";
+import type { Definable, KindRegistry, PortableObject } from "../kind";
+
+/**
+ * The dialect-NEUTRAL authoring contract — the only structure the orchestration reads off an
+ * authored object (everything else is opaque and handed straight to {@link Driver.explode}). A table
+ * contributes just its `name`; this is the upper bound for a driver's table-authoring type. The
+ * Surreal `TableDef` is a structural subtype, as is any future dialect's table builder.
+ */
+export interface Authored {
+  readonly name: string;
+}
+
+/**
+ * The neutral contract for a standalone (non-table) authored object — an event/function/access. It
+ * adds a `kind` discriminant and, for objects owned by a table (e.g. an event), the owner `table`
+ * name (so the snapshot can file-link a child object under its parent). The Surreal `StandaloneDef`
+ * union is a structural subtype.
+ */
+export interface AuthoredDef extends Authored {
+  readonly kind: string;
+  readonly table?: string;
+}
+
+/**
+ * A single emitted DDL statement, structured: object identity (`kind`/`name`/`table`) + the dialect
+ * `ddl` string, plus an optional clause map (each value an `ALTER … <set>` form) for dialects that
+ * diff clause-level. `kind` is a dialect-defined string the orchestration treats opaquely — the
+ * SurrealDB `DefineStatement` (with its fixed kind union) is a structural subtype of this.
+ */
+export interface Statement {
+  kind: string;
+  name: string;
+  table?: string;
+  ddl: string;
+  clauses?: Record<string, string>;
+}
+
+/** Options for {@link Driver.emit} — mirrors the existing `DefineOptions` (e.g. IF NOT EXISTS). */
+export interface EmitOptions {
+  ifNotExists?: boolean;
+  overwrite?: boolean;
+}
+
+/** Options for {@link Driver.apply}. */
+export interface ApplyOptions {
+  /**
+   * Run the whole batch atomically. `migrate` wraps up/down + `_migrations` bookkeeping in one
+   * transaction; a driver that can't MUST surface that (the migration model degrades to best-effort).
+   */
+  transactional?: boolean;
+}
+
+/** Per-connection overrides (url/namespace/credentials) — superset across dialects. */
+export interface ConnectionOverrides {
+  url?: string;
+  namespace?: string;
+  database?: string;
+  username?: string;
+  password?: string;
+  authLevel?: string;
+}
+
+/** The direction a migration is applied in. */
+export type MigrationDirection = "up" | "down";
+
+/** A migration's bookkeeping identity, recorded in the migrations-tracking table. */
+export interface MigrationRecord {
+  tag: string;
+  file: string;
+  /** sha of the migration file at apply time (drift detection). */
+  checksum: string;
+}
+
+/**
+ * The apply-time, dialect-specific half of the migration runner. The orchestration (which
+ * migrations are pending, ordering, the lock-then-loop) stays driver-neutral in cli/migrate.ts;
+ * this capability owns the SQL: the tracking table, the applied-records, the advisory lock, and the
+ * atomic apply+record. A driver WITHOUT it can't run migrations (diff/gen still work). `Conn` is the
+ * driver's own connection type.
+ */
+export interface MigrationStore<Conn = unknown> {
+  /** This dialect's migration-file extension, e.g. `".surql"` (SurrealDB) or `".sql"` (Postgres). */
+  readonly extension: string;
+  /** Render a diff as this dialect's migration-file body (e.g. SurrealQL `IF $direction` up/down). */
+  render(tag: string, diff: Diff): string;
+  /** Ensure the migrations-tracking table exists. */
+  ensure(conn: Conn, table: string): Promise<void>;
+  /** Applied migrations: tag -> checksum recorded at apply time. */
+  applied(conn: Conn, table: string): Promise<Map<string, string>>;
+  /**
+   * Apply one migration's `up`/`down` PROGRAM plus its bookkeeping write atomically: on `up` record
+   * the migration, on `down` erase it — so the record is written iff the DDL actually applied.
+   */
+  apply(
+    conn: Conn,
+    table: string,
+    m: {
+      content: string;
+      direction: MigrationDirection;
+      record: MigrationRecord;
+    },
+  ): Promise<void>;
+  /** Record a migration as applied WITHOUT running its DDL (baseline of an existing DB). */
+  record(conn: Conn, table: string, record: MigrationRecord): Promise<void>;
+  /** Drop all applied records (baseline-squash reconcile). */
+  clear(conn: Conn, table: string): Promise<void>;
+  /** Take an advisory lock so two runs can't race — throws if already held. */
+  lock(conn: Conn, table: string): Promise<void>;
+  /** Release the advisory lock (idempotent). */
+  unlock(conn: Conn, table: string): Promise<void>;
+}
+
+/**
+ * An OPTIONAL throwaway-instance capability for round-trip canonicalization and `sz check`'s
+ * migration replay. Absent -> `check`/replay-verification is degraded/unavailable (diff/apply still
+ * work, since a kind's `lower`/`introspectAll` already canonicalize).
+ */
+export interface ShadowCapability<Conn> {
+  /** Apply `ddl` to a fresh scratch DB, introspect it back to portable objects, then drop it. */
+  roundTrip(
+    conn: Conn,
+    config: ResolvedConfig,
+    ddl: string,
+  ): Promise<PortableObject[]>;
+  /** Spin up a fully-isolated ephemeral instance (for migration replay). Caller must `stop()`. */
+  ephemeral?(): Promise<{ conn: Conn; stop: () => Promise<void> }>;
+}
+
+/**
+ * A database dialect, expressed as a SET OF KINDS (core-v2). The driver registers its object kinds on
+ * `registry`; core orchestrates schema ops GENERICALLY over it (`lowerSchema`/`buildKindDiff`/
+ * `emitKinds`/`orderObjects`) — it never names a kind. The driver owns only what isn't generic: the
+ * authoring -> kinded `explode`, a single-read `introspectAll`, the connection lifecycle, and the
+ * dialect-specific command capabilities. The field/type substrate (`PortableType`/`s.*`) stays core.
+ * See docs/kind-registry-flip-plan.md.
+ */
+export interface Driver<
+  Conn = unknown,
+  Tbl extends Authored = Authored,
+  Def extends AuthoredDef = AuthoredDef,
+> {
+  readonly name: string;
+
+  // --- kind registry (the schema engine) -----------------------------------------------------
+  /** This driver's registered KINDS. Core runs lower/diff/emit/order generically over it. */
+  readonly registry: KindRegistry;
+  /**
+   * Authoring (loaded `defineTable`/standalone defs) -> kinded {@link Definable}s. The driver-side
+   * fan-out: one inline-authored table explodes into `[table, ...index, ...event/constraint]`, each
+   * tagged with its `kind`. Core then lowers via `lowerSchema(registry, explode(...))` — so
+   * `KindEngine.lower` stays 1:1 and the contract needs no explode hook.
+   */
+  explode(tables: Tbl[], defs: Def[]): Definable[];
+  /**
+   * Live connection -> ALL portable objects, fanned across kinds from ONE read (INFO STRUCTURE /
+   * pg_catalog). Must canonicalize IDENTICALLY to lowering (a clean apply round-trips to a zero diff)
+   * and be COMPLETE (return every diffable kind, else presence-phantom-diffs). `exclude` skips tables
+   * by name.
+   */
+  introspectAll(conn: Conn, exclude?: Set<string>): Promise<PortableObject[]>;
+
+  // --- execution -----------------------------------------------------------------------------
+  connect(config: ResolvedConfig, over?: ConnectionOverrides): Promise<Conn>;
+  apply(conn: Conn, statements: string[], opts?: ApplyOptions): Promise<void>;
+  /** Tear down a connection opened by {@link connect} (the orchestration owns the lifecycle). */
+  close(conn: Conn): Promise<void>;
+
+  // --- optional capabilities -----------------------------------------------------------------
+  readonly shadow?: ShadowCapability<Conn>;
+  /** Apply-time migration bookkeeping. Absent -> this driver can't run migrations (diff/gen still do). */
+  readonly migrations?: MigrationStore<Conn>;
+
+  // --- optional COMMAND capabilities ---------------------------------------------------------
+  // The dialect-agnostic CLI routes each schema-syncing command through one of these. A driver that
+  // omits a capability makes that command unavailable on it — the CLI never hardcodes `if surreal`.
+
+  /**
+   * Diff the LIVE database against the loaded schema into executable up/down DDL. Owns every
+   * dialect-specific normalization and apply-time fixup (Surreal: a shadow-DB round-trip to cancel
+   * formatting noise, the redacted-access-key swap, and the implicit-wildcard OVERWRITE re-mark), so
+   * the result is safe to apply as-is. Backs `diff --live`, `push`, and the baseline reconcile.
+   */
+  diffLive?(conn: Conn, config: ResolvedConfig, filter: Filter): Promise<Diff>;
+  /** Reduce a live diff (from {@link diffLive}) to the statements `push` applies; `prune: false` keeps removals. */
+  syncPlan?(diff: Diff, prune?: boolean): string[];
+  /**
+   * Render portable objects to per-file source in THIS dialect's `s.*` syntax, filtered — the codegen
+   * behind the offline `diff --ts` and `pull`. Takes `PortableObject[]` (this driver's own portable
+   * shape): `diff --ts` renders the SNAPSHOT side (stored portable) and the DESIRED side
+   * (`lowerSchema(explode(...))`) at MATCHING fidelity so an in-sync schema yields identical files;
+   * `pull` renders the introspected DB. The driver re-derives its structured form from the portable
+   * objects (parsing its own DDL where needed — docs/kind-registry-flip-plan.md §6b). `single` (a file
+   * key) folds everything into one module; otherwise `fileFor` maps each object to its own file.
+   */
+  renderSchema?(
+    objects: PortableObject[],
+    filter: Filter,
+    fileFor: (kind: string, name: string) => string,
+    single?: string,
+  ): Map<string, string>;
+  /**
+   * The two sides of `diff --ts --live` rendered to per-file source: the live DB (`current`) and the
+   * declared schema (`desired`), both normalized through the dialect so an unchanged schema yields
+   * identical files.
+   */
+  diffTsLive?(
+    conn: Conn,
+    config: ResolvedConfig,
+    filter: Filter,
+    fileFor: (kind: string, name: string) => string,
+    single?: string,
+  ): Promise<{ current: Map<string, string>; desired: Map<string, string> }>;
+  /**
+   * Replay every migration into a throwaway engine and diff the result against the schema (`check`).
+   * Owns ephemeral-engine selection + setup; `log` receives progress lines. Needs a {@link shadow}-
+   * class capability. An empty diff means the migrations reproduce the schema.
+   */
+  checkReplay?(
+    config: ResolvedConfig,
+    over: ConnectionOverrides,
+    filter: Filter,
+    log: (msg: string) => void,
+  ): Promise<Diff>;
+  /** Introspect the live DB and plan schema-file codegen (`pull`); writing is the neutral `applyPull`. */
+  planPull?(
+    conn: Conn,
+    config: ResolvedConfig,
+    opts: { filter: Filter; keepLocal?: boolean },
+  ): Promise<PullPlan>;
+  /** A human-readable server identity for `doctor` (e.g. "SurrealDB 3.1.3"); throws if unreachable. */
+  serverInfo?(conn: Conn): Promise<string>;
+  /**
+   * Run a raw READ query and return rows — for connection RESOLVERS (a multi-connection resolver's
+   * `ctx.connections.<name>.query(...)`) and `seed`. The `sql` is this dialect's query language; the
+   * orchestration treats the rows opaquely. Absent -> a resolver can't read from this connection.
+   */
+  query?<T = unknown>(
+    conn: Conn,
+    sql: string,
+    vars?: Record<string, unknown>,
+  ): Promise<T[]>;
+  /**
+   * The dialect-specific files `schemic init` scaffolds, keyed by project-relative path: a
+   * connections-only `schemic.config.ts` (using this driver's `<driver>Connection` factory), a sample
+   * schema module in this dialect's `s.*`, a seed stub, a `.env.example`, … The CLI writes them
+   * verbatim (never overwriting) alongside the dialect-neutral migration snapshot it records itself.
+   * Absent -> `schemic init` can't scaffold a project for this driver.
+   */
+  initScaffold?(): Record<string, string>;
+  /**
+   * Scaffold a NEW entity file's contents — the starter `s.*` / `define*` module for an object of
+   * `kind` named `name` (e.g. `("table", "user")` -> a `defineTable("user", { … })` module in this
+   * dialect's authoring). Returns the file text; the CLI writes it under the kind's
+   * {@link KindRegistry.display} folder. THROW for a kind this driver can't author (the CLI surfaces
+   * the message). Absent -> `schemic new` is unavailable for this driver.
+   */
+  scaffoldEntity?(kind: string, name: string): string;
+}
+
+// --- Registry -----------------------------------------------------------------------------------
+
+const REGISTRY = new Map<string, Driver<unknown>>();
+
+/** Register a driver under its `name` (idempotent; last write wins). */
+export function registerDriver(driver: Driver<unknown>): void {
+  REGISTRY.set(driver.name, driver);
+}
+
+/** Look up a registered driver, or throw with the list of known names. */
+export function getDriver(name: string): Driver<unknown> {
+  const d = REGISTRY.get(name);
+  if (!d) {
+    const known = [...REGISTRY.keys()].join(", ") || "(none registered)";
+    throw new Error(`Unknown database driver "${name}". Registered: ${known}.`);
+  }
+  return d;
+}
+
+/** All registered driver names (for help text / config validation). */
+export function driverNames(): string[] {
+  return [...REGISTRY.keys()];
+}

package/src/driver/index.ts

@@ -0,0 +1,31 @@
+// The driver layer — the multi-DB seam (see docs/MULTI-DB-SPIKE.md).
+
+export type {
+  ApplyOptions,
+  Authored,
+  AuthoredDef,
+  ConnectionOverrides,
+  Driver,
+  EmitOptions,
+  MigrationDirection,
+  MigrationRecord,
+  MigrationStore,
+  ShadowCapability,
+  Statement,
+} from "./driver";
+export { driverNames, getDriver, registerDriver } from "./driver";
+export type {
+  GeometryKind,
+  PortableType,
+  ScalarName,
+} from "./portable";
+export {
+  array,
+  literal,
+  nullable,
+  option,
+  record,
+  scalar,
+  union,
+} from "./portable";
+export type { PortableField, PortablePermissions } from "./portable-ir";