@better-schemic/core 0.1.0-alpha.1

package/src/connection.ts

@@ -0,0 +1,120 @@
+// 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-only (erased): the resolved per-connection config a factory-embedded `client` opener receives.
+import type { ResolvedConfig } from "./cli-kit/config";
+
+type MaybePromise<T> = T | Promise<T>;
+
+/** Minimal Standard Schema v1 surface — what a connection's `args` schema must expose. */
+export interface StandardSchemaLike {
+  "~standard": {
+    validate(
+      value: unknown,
+    ): MaybePromise<
+      { value: unknown } | { issues: readonly { message: string }[] }
+    >;
+  };
+}
+
+/** 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;
+  /** Optional DISPLAY label for this config within a bulk (array) resolution — reporting/logs only. */
+  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>;
+  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<Client = unknown, Args = undefined> {
+  readonly __betterSchemic: "connection";
+  readonly driver: string;
+  resolve(ctx: ResolveContext, args?: Args): Promise<ConnectionConfigBase[]>;
+  /**
+   * Lazily open this connection's bound ORM CLIENT for a resolved config — embedded by the driver
+   * factory (with a lazy `import()` of its own client module, so authoring a config never pulls the
+   * engine). This is what powers the typed `config.connect(name)` on `defineConfig`'s return.
+   */
+  client?(config: ResolvedConfig): Promise<Client>;
+  /**
+   * Dialect-specific DISPLAY identity for a resolved config (bulk reporting / errors / logs) —
+   * e.g. surreal `ns/db`. Precedence: config `key` > this hook > positional `name[i]`.
+   */
+  label?(config: ResolvedConfig): string;
+  /** PHANTOM (never assigned) — anchors `Client`/`Args` so `config.connect` can infer them per entry. */
+  readonly __types?: { client: Client; args: Args };
+}
+
+/** Cross-driver erasure of the entry generics (like `AnyField`) — the shape neutral maps hold. */
+// biome-ignore lint/suspicious/noExplicitAny: cross-driver erasure of the per-entry client/args types.
+export type AnyConnectionEntry = ConnectionEntry<any, any>;
+
+/** A connection factory's input: a static config, or a resolver yielding one config or a keyed collection. */
+export type ConnectionInput<C extends ConnectionConfigBase, Args = undefined> =
+  | C
+  | ((ctx: ResolveContext, args: Args) => MaybePromise<C | C[]>);
+
+/**
+ * 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. `extras` carries the factory-embedded client opener (for
+ * `config.connect`) and the optional args schema.
+ */
+export function connectionEntry<
+  C extends ConnectionConfigBase,
+  Client = unknown,
+  Args = undefined,
+>(
+  driver: string,
+  input: ConnectionInput<C, Args>,
+  extras?: {
+    client?: (config: ResolvedConfig) => Promise<Client>;
+    label?: (config: ResolvedConfig) => string;
+  },
+): ConnectionEntry<Client, Args> {
+  return {
+    __betterSchemic: "connection",
+    driver,
+    ...(extras?.client ? { client: extras.client } : {}),
+    ...(extras?.label ? { label: extras.label } : {}),
+    async resolve(ctx, args) {
+      const out =
+        typeof input === "function" ? await input(ctx, args as Args) : 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 { __betterSchemic?: unknown }).__betterSchemic === "connection"
+  );
+}

package/src/driver/driver.ts

@@ -0,0 +1,413 @@
+// The DRIVER interface — the dialect seam (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>`, and core
+// never sees the 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";
+import type { SecretProvider, SecretRef } from "../secrets";
+
+/**
+ * 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>;
+  /**
+   * Apply-time secret bindings for this statement's `$param` placeholders — `param` name ->
+   * a write-only {@link SecretRef}. Collected into {@link Diff.bindings}; the value never lives here
+   * (resolved at apply through a `SecretProvider`). See {@link Diff.bindings}.
+   */
+  bindings?: Record<string, SecretRef>;
+}
+
+/** 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). */
+  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> }>;
+}
+
+/**
+ * User-defined DB functions — the `.call` side of the query layer's (B) surface (DB functions as code).
+ * `invoke` calls a defined function by name with already-encoded args and returns the function's RAW
+ * result (the driver extracts it from its own response shape — surreal `RETURN fn::name($a)` yields the
+ * value; a row-returning call yields a row set). The caller decodes that raw value through the
+ * function's `.returns(R)` schema via `callFunction` in `@better-schemic/core/query`. A defined function still
+ * emits/migrates via the schema engine regardless; this capability only adds INVOCATION.
+ */
+export interface CallableFunctions<Conn = unknown> {
+  invoke(
+    conn: Conn,
+    name: string,
+    args: Record<string, unknown>,
+  ): Promise<unknown>;
+}
+
+// --- driver-contributed CLI commands -----------------------------------------------------------
+// A driver may contribute dialect-specific commands invoked as `sc <kind> <verb> [args]` (e.g. surreal
+// `sc access rotate <name>`). CORE provides only the general
+// mechanism: it discovers `driver.commands`, registers each, parses argv against `args`, resolves the
+// connection, and dispatches to `run` with a {@link CommandContext}. The DRIVER owns the dialect logic
+// and the meaning of each kind/verb/arg — core never names one. Depth is fixed at kind/verb.
+
+/** A declared argument for a {@link DriverCommand} — used for parsing + `--help`. */
+export interface CommandArgs {
+  /**
+   * Positional args, in order. Core collects ALL positional tokens into a list (incl. raw `key=value`)
+   * and the driver interprets + validates arity; mark the last `variadic` for "one or more".
+   */
+  positionals?: readonly {
+    name: string;
+    required?: boolean;
+    variadic?: boolean;
+    help?: string;
+  }[];
+  /** Named flags. `value: true` takes a value (`--user U`); otherwise it's a boolean (`--dry-run`). */
+  flags?: readonly {
+    name: string;
+    value?: boolean;
+    required?: boolean;
+    help?: string;
+  }[];
+}
+
+/** argv parsed against a command's {@link CommandArgs}: positional tokens (driver-interpreted) + flags. */
+export interface ParsedCommandArgs {
+  /** Every positional token in order (incl. raw `key=value`); the driver interprets them. */
+  positionals: string[];
+  /** Flags: a value-flag -> its string, a boolean flag -> `true`, an absent flag -> `undefined`. */
+  flags: Record<string, string | boolean | undefined>;
+}
+
+/** Output + input helpers core hands a command (so a driver never touches stdio directly). */
+export interface CommandIo {
+  ok(message: string): void;
+  fail(message: string): void;
+  info(message: string): void;
+  /** Prompt for a line of input (`hidden` masks it) — for a sensitive value not passed inline (no shell-history leak). */
+  prompt(question: string, opts?: { hidden?: boolean }): Promise<string>;
+}
+
+/** The context core hands a {@link DriverCommand.run}: a connected db + the resolved config + io + secrets. */
+export interface CommandContext<Conn = unknown> {
+  conn: Conn;
+  config: ResolvedConfig;
+  io: CommandIo;
+  /** The configured secret provider (default reads `process.env`) for resolving {@link SecretRef}s. */
+  secrets: SecretProvider;
+}
+
+/**
+ * A driver-contributed CLI command — `sc <kind> <verb> [args]`. Core dispatches; the driver owns the
+ * dialect logic in {@link run}. The driver validates positional arity itself (core only collects them).
+ */
+export interface DriverCommand<Conn = unknown> {
+  /** Kind namespace — `sc <kind> …` (e.g. `"access"`, `"table"`). */
+  kind: string;
+  /** Verb under the kind — `sc <kind> <verb>` (e.g. `"rotate"`, `"check"`, `"find"`). */
+  verb: string;
+  /** One-line help shown in the command listing. */
+  summary: string;
+  /** Declared args for parsing + `--help`. */
+  args?: CommandArgs;
+  run(ctx: CommandContext<Conn>, args: ParsedCommandArgs): 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 /
+   * the system 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[];
+  /**
+   * Dialect-specific CLI commands invoked as `sc <kind> <verb> [args]` — e.g. surreal `access rotate`.
+   * Core discovers + dispatches them generically (see {@link DriverCommand});
+   * it never names a kind/verb. Absent -> this driver contributes no extra commands.
+   */
+  readonly commands?: readonly DriverCommand<Conn>[];
+  /**
+   * 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[]>;
+  /**
+   * User-defined DB functions ((B) of the query layer) — invoke a defined function + decode the result.
+   * Absent -> no `.call()` surface on this driver (the function still emits/migrates). See
+   * {@link CallableFunctions}.
+   */
+  readonly callable?: CallableFunctions<Conn>;
+  /**
+   * The dialect-specific files `better-schemic init` scaffolds, keyed by project-relative path: a
+   * connections-only `better-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 -> `better-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 -> `better-schemic new` is unavailable for this driver.
+   */
+  scaffoldEntity?(kind: string, name: string): string;
+}
+
+// --- Registry -----------------------------------------------------------------------------------
+
+// Shared across every loaded copy of `@better-schemic/core` so the registry is process-global — the CLI run
+// via `bunx` resolves its own core, while a driver loaded from the user's project resolves the
+// project's core; without sharing, the driver self-registers in one Map and the CLI reads an empty
+// one. Keyed by a REGISTERED symbol (`Symbol.for`) — same key in every instance, but no string-keyed
+// `globalThis` pollution and namespaced so it can't collide.
+const REGISTRY_KEY = Symbol.for("@better-schemic/core.driverRegistry");
+const REGISTRY: Map<string, Driver<unknown>> = ((
+  globalThis as Record<symbol, Map<string, Driver<unknown>> | undefined>
+)[REGISTRY_KEY] ??= 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";

package/src/driver/portable-ir.ts

@@ -0,0 +1,51 @@
+// The portable FIELD SUBSTRATE — the dialect-independent field model the kind registry builds on.
+//
+// core-v2 (the kind-registry flip) retired the fixed-slot `PortableDb` (tables/functions/accesses/
+// natives) + the per-slot object types (`PortableTable`/`PortableEvent`/…): a schema is now a flat
+// `PortableObject[]` of OPEN kinds (see ../kind), each driver owning its own portable shape. What
+// stays in core is the SUBSTRATE every kind composes — a field's structured {@link PortableType} +
+// its clauses — so a table kind nests `PortableField`s and the
+// cross-driver field model + Zod drop-in keep working.
+//
+// Field/permission CLAUSES (default/value/assert/index spec/…) are carried verbatim as dialect
+// expression strings: they don't port across dialects, so a foreign driver honors the ones it can and
+// surfaces the rest as a documented capability gap. Only the keystone (the TYPE) is fully portable.
+
+import type { PortableType } from "./portable";
+
+/** CRUD permissions — each a boolean (FULL/NONE) or a dialect WHERE-expression string (carried verbatim). */
+export interface PortablePermissions {
+  select?: boolean | string;
+  create?: boolean | string;
+  update?: boolean | string;
+  delete?: boolean | string;
+}
+
+/** A field in the portable substrate: a structured {@link PortableType} + its dialect clauses (verbatim). */
+export interface PortableField {
+  name: string;
+  type: PortableType;
+  flexible?: boolean;
+  readonly?: boolean;
+  default?: string;
+  default_always?: boolean;
+  value?: string;
+  computed?: string;
+  assert?: string;
+  /**
+   * A field-level CHECK constraint (dialect boolean expression, carried verbatim). DISTINCT from
+   * `assert`: that is Surreal's `ASSERT`; this is the SQL `CHECK` a SQL driver emits. A
+   * driver maps whichever of the two it supports and surfaces the other as a capability gap.
+   */
+  check?: string;
+  comment?: string;
+  /** Referential action(s) on a foreign reference. A driver honors the actions it supports. */
+  reference?: { on_delete?: string; on_update?: string };
+  /**
+   * Auto-generated identity column — `GENERATED ALWAYS`/`BY DEFAULT AS IDENTITY`; a `serial`/
+   * auto-increment column maps here too. Absent → an ordinary column. Drivers without identity ignore it.
+   */
+  identity?: "always" | "by-default";
+  permissions?: PortablePermissions;
+  table: string;
+}