@schemic/core 0.1.0-alpha.0

package/lib/driver-Dh5hLKHm.d.ts

@@ -0,0 +1,736 @@
+import * as jiti from 'jiti';
+import { S as SchemicConfig, C as ConnectionConfigBase } from './config-TIiKDd9t.js';
+import { Command } from 'commander';
+
+/**
+ * A resolved, per-CONNECTION config — the dialect-NEUTRAL shape every command operates on (one
+ * connection at a time). `params` are the driver-specific connection params (opaque to core; the
+ * driver's `connect` reads them). Built by resolving one entry of `config.connections`.
+ */
+interface ResolvedConfig {
+    /** Resolved connection name (e.g. `default`, or `tenants:abc` within a collection). */
+    connection: string;
+    /** The driver this connection uses (the package the CLI dynamically loads). */
+    driver: string;
+    /** Project root (the directory containing the config file). */
+    root: string;
+    /** Absolute schema path — a single `.ts` module, or a directory of them. */
+    schemaPath: string;
+    /** Whether `schemaPath` is a single file (vs a directory of schema modules). */
+    schemaIsFile: boolean;
+    /** Absolute migrations directory (per connection's schema). */
+    migrationsDir: string;
+    /** Absolute migration meta directory (the snapshot). */
+    metaDir: string;
+    /** Name of the table that records applied migrations. */
+    migrationsTable: string;
+    /** Driver-specific connection params (url/namespace/… or whatever the driver defines). Opaque to core. */
+    params: Record<string, unknown>;
+    /** Optional seed script (project-level). */
+    seed?: string;
+}
+/**
+ * A jiti instance for loading the project's TS/ESM modules. Caches are off so `--watch` re-reads
+ * edited schema files. (Bare deps like `@schemic/core` are native-imported, so registries stay shared.)
+ */
+declare function makeJiti(): jiti.Jiti;
+/** Find + load `schemic.config.ts` into the dialect-neutral {@link SchemicConfig}. */
+declare function loadProject(opts?: {
+    config?: string;
+    cwd?: string;
+}): Promise<{
+    config: SchemicConfig;
+    root: string;
+}>;
+/**
+ * Build the {@link ResolvedConfig} for one connection of the project. `ctx` carries the lazy
+ * cross-connection proxy + CLI `--arg`s (the CLI provides the real one; a static connection ignores
+ * it). A resolver returning a COLLECTION yields one ResolvedConfig per keyed entry.
+ *
+ * NOTE (WIP — multi-connection): the full resolution engine (lazy proxy DAG, `--connection`/`--all`
+ * addressing, collection fan-out) lives in `@schemic/cli`; this builder handles a single resolved
+ * connection config. See docs/MULTI-CONNECTION.md.
+ */
+declare function resolveConnectionConfig(config: SchemicConfig, connection: string, conn: ConnectionConfigBase, driver: string, root: string): ResolvedConfig;
+/**
+ * Load the project and resolve the DEFAULT connection to a {@link ResolvedConfig} — the single-
+ * connection convenience path. (Multi-connection addressing + resolver context are added by the CLI;
+ * here a static default connection is resolved with an empty context.)
+ */
+declare function loadConfig(opts?: {
+    config?: string;
+    cwd?: string;
+}): Promise<ResolvedConfig>;
+
+/**
+ * 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).
+ */
+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.
+ */
+interface PortableObject {
+    readonly kind: string;
+    readonly name: string;
+}
+/** A reference to another object in the schema graph — the unit of cross-kind dependency ordering. */
+interface Ref {
+    readonly kind: string;
+    readonly name: string;
+}
+
+/**
+ * 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.
+ */
+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 (PG `'x'` -> `'x'::text`, `a>0` ->
+     * `(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 `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;
+    /**
+     * Live connection -> all portable objects of THIS kind (the reverse direction). Introspection is
+     * often one `INFO`/`pg_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;
+}
+/** Per-kind presentation metadata (labels + output folder). All optional; core fills defaults. */
+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). */
+type ResolvedDisplay = Required<KindDisplay>;
+/** A kind's full spec: its `name`, its `build` (the driver's authoring entry), and its engine. */
+type KindSpec<Build extends (...args: never[]) => unknown, A extends Definable, P extends PortableObject> = {
+    name: string;
+    build: Build;
+} & KindEngine<A, P>;
+/**
+ * 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).
+ */
+declare class KindRegistry {
+    private readonly kinds;
+    /**
+     * 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;
+    /** The engine for `kind`, or undefined if no such kind is registered. */
+    engine(kind: string): KindEngine<any, any> | undefined;
+    /**
+     * 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;
+    /** Registered kind names, in registration order (== ordinal order). */
+    names(): string[];
+    /**
+     * 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;
+    /** [name, engine] pairs in registration order — the spine iterates these. */
+    entries(): [string, KindEngine<any, any>][];
+}
+
+/** A node in the dependency graph: identity + the edges/owner used to order it. */
+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).
+ */
+declare function orderObjects<T extends OrderNode>(nodes: T[], ordinalOf: (kind: string) => number): T[];
+/**
+ * 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.
+ */
+declare function lowerSchema(registry: KindRegistry, defs: Definable[]): PortableObject[];
+/**
+ * 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.
+ */
+interface KindSnapshot {
+    kinds: Record<string, PortableObject[]>;
+}
+/** Group a flat portable schema into a snapshot (by kind). */
+declare function snapshotKinds(schema: PortableObject[]): KindSnapshot;
+/** Flatten a snapshot back into a portable schema (the inverse of {@link snapshotKinds}). */
+declare function snapshotObjects(snap: KindSnapshot): PortableObject[];
+/** An up/down DDL program (each a list of statements). */
+interface KindPlan {
+    up: string[];
+    down: string[];
+}
+/**
+ * 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.
+ */
+declare function planKinds(registry: KindRegistry, prev: PortableObject[], next: PortableObject[]): KindPlan;
+/**
+ * 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.
+ */
+declare function buildKindDiff(registry: KindRegistry, prev: PortableObject[], next: PortableObject[]): Diff;
+/**
+ * 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}.
+ */
+declare function emitKinds(registry: KindRegistry, schema: PortableObject[]): string[];
+/**
+ * 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).
+ */
+declare function introspectKinds(registry: KindRegistry, conn: unknown): Promise<PortableObject[]>;
+
+/**
+ * One object's change, for display. `kind` is the object kind, `table` its owner (a table name,
+ * or the object's own name for db-level objects). `add` carries the new DDL; `remove` carries the
+ * `REMOVE` statement (`ddl`) plus the dropped object's prior DDL (`old`, for the unified patch);
+ * `change` pairs old↔new.
+ */
+type DiffItem = {
+    key: string;
+    table: string;
+    /** Dialect-defined object kind (e.g. "table"/"field"/"index") — opaque to the display. */
+    kind: string;
+    /** The source file this object lives in (or lived in, for a removal). Absent if unknown. */
+    file?: string;
+} & ({
+    op: "add";
+    ddl: string;
+} | {
+    op: "remove";
+    ddl: string;
+    old: string;
+} | {
+    op: "change";
+    before: string;
+    after: string;
+});
+interface Diff {
+    up: string[];
+    down: string[];
+    /** Structured per-object changes for the human display (word-level diff). */
+    items?: DiffItem[];
+    /** Every desired statement (the `next` schema), for the `--full` context view. */
+    full?: {
+        key: string;
+        table: string;
+        ddl: string;
+    }[];
+}
+/** `true` if the two snapshots define the same objects with identical DDL. */
+declare function isEmptyDiff(diff: Diff): boolean;
+/**
+ * Inline word-level diff of two statements: shared tokens dim, removed tokens red, added tokens
+ * green (LCS over space-separated tokens). So a changed field shows the whole statement with only
+ * the changed words highlighted.
+ */
+declare function tokenDiff(before: string, after: string): string;
+/** Render display items as a git-style file diff: each group headed by its source file path. */
+declare function formatItems(items: DiffItem[], inline?: boolean): string;
+/**
+ * A standard **unified diff** of the change, grouped one section per source file (git-style) — for
+ * piping through a diff viewer (git's pager / delta). Objects with no file fall back to a section
+ * headed by the object's bare name. Each object is a single-line DDL statement, so hunks are
+ * line-for-line.
+ */
+declare function formatPatch(diff: Diff): string;
+/** A human-readable view of a diff's forward (and optionally reverse) changes. */
+declare function formatDiff(diff: Diff, opts?: {
+    down?: boolean;
+    full?: boolean;
+    inline?: boolean;
+}): string;
+/**
+ * A per-kind breakdown of a set of changes, e.g. `1 Table, 2 Fields`. Counts each item by its
+ * structured `kind` and labels it from the registry's per-kind {@link KindRegistry.display} (singular
+ * when the count is one), so the summary is correct for every dialect — no DDL parsing.
+ */
+declare function summarizeKinds(registry: KindRegistry, items: readonly {
+    kind: string;
+}[]): string;
+
+/**
+ * The STORED snapshot (`_snapshot.json`): the canonical schema is portable objects grouped by kind
+ * (a {@link KindSnapshot}); DDL is derived generically via the kind registry (`buildKindDiff`/
+ * `emitKinds`). Diffed against the next `generate`. `files` maps each object's name to its
+ * project-root-relative source file (display-only; attached to diff items by the CLI). Pre-launch:
+ * the format is free to change, so there is no on-disk version migration — an unrecognized snapshot
+ * is treated as empty (regenerate via `schemic gen --baseline`).
+ */
+interface StoredSnapshot {
+    version: 3;
+    /** The driver that authored this snapshot ("surrealdb", "postgres", …). */
+    driver: string;
+    /** Portable objects grouped by kind. */
+    schema: KindSnapshot;
+    files?: Record<string, string>;
+}
+/** A migration file on disk. The filename is the source of truth — there's no journal. */
+interface Migration {
+    /** Filename without the `.surql` extension, e.g. `20260607153045_add_users`. */
+    tag: string;
+    /** Filename, e.g. `20260607153045_add_users.surql`. */
+    file: string;
+}
+/** The empty STORED snapshot — used as `prev` for a `--baseline` generate (diff against nothing). */
+declare const EMPTY_STORED: StoredSnapshot;
+/**
+ * Read the stored snapshot. Pre-launch: any snapshot that isn't the current `version: 3` shape (a
+ * pre-portable v1/v2, or absent) is treated as EMPTY — regenerate with `schemic gen --baseline`.
+ */
+declare function readSnapshot(metaDir: string): StoredSnapshot;
+declare function writeSnapshot(metaDir: string, snapshot: StoredSnapshot): void;
+/**
+ * All migration files in `migrationsDir`, in apply order. Filenames are timestamp-prefixed, so
+ * a plain ascending sort is chronological (and legacy `0001_` names sort before timestamped
+ * ones). The `meta/` directory and any file not ending in `ext` (the driver's migration extension)
+ * are ignored.
+ */
+declare function listMigrations(migrationsDir: string, ext?: string): Migration[];
+/** A sortable UTC timestamp prefix for a new migration, e.g. `20260607153045`. */
+declare function timestamp(date: Date): string;
+/** sha256 of a migration file's contents (drift detection / apply-time bookkeeping). */
+declare function checksum(content: string): string;
+/** Turn a free-form migration name into a filename-safe slug. */
+declare function slug(name: string): string;
+
+/**
+ * Per-kind object filter for `pull`/`diff`/`sync`/`generate`. Each kind is independently
+ * included (optionally name-restricted). `DEFINE ACCESS` is OPT-IN everywhere — excluded
+ * unless `--access` is given — so an introspection (which redacts access signing keys) can't
+ * silently rotate them. Table-scoped objects (fields/indexes/events) follow their table.
+ */
+interface Cat {
+    on: boolean;
+    /** When set, only these names of the kind are included. */
+    names?: Set<string>;
+}
+interface Filter {
+    tables: Cat;
+    functions: Cat;
+    events: Cat;
+    access: Cat;
+}
+/** Commander's parse of one `--kind [names]` / `--no-kind` flag: `undefined`/`true`/string/`false`. */
+type FlagValue = string | boolean | undefined;
+interface FilterOpts {
+    tables?: FlagValue;
+    functions?: FlagValue;
+    events?: FlagValue;
+    access?: FlagValue;
+}
+/** Build a {@link Filter} from CLI flags. Access is opt-in (`--access`); the rest default to on. */
+declare function parseFilter(o: FilterOpts): Filter;
+/** Attach the per-kind `--tables/--functions/--events/--access [names]` (+ `--no-*`) options. */
+declare function kindFlags(cmd: Command): Command;
+/** Whether a name passes a category gate (kind on + name allowed). Shared with the surreal filters. */
+declare const inCat: (c: Cat, name: string) => boolean;
+/**
+ * Whether a portable object passes the filter. A TOP-LEVEL object (no owner) is gated by its kind's
+ * category + name. An OWNED object (owner set — an index/event/constraint) FOLLOWS its owner table's
+ * inclusion; an `event` is ADDITIONALLY gated by the `events` category. (Fields are substrate nested
+ * in their table object, never standalone here.)
+ */
+declare function passesFilter(registry: KindRegistry, o: PortableObject, f: Filter): boolean;
+/** Keep only the portable objects that pass the filter (the {@link filterStructured} analog). */
+declare function filterKinds(registry: KindRegistry, objects: PortableObject[], f: Filter): PortableObject[];
+/**
+ * The stored snapshot to persist after a filtered `generate`: INCLUDED objects take their new state
+ * from `next`, EXCLUDED objects keep `prev`'s. Dedup by `kind:name` (an included `next` object wins).
+ * `files` overlays next on prev.
+ */
+declare function mergeStored(registry: KindRegistry, prev: StoredSnapshot, next: StoredSnapshot, f: Filter): StoredSnapshot;
+/**
+ * Restrict the `disk` objects to those that ALSO exist `live` (intersect by `kind:name`) AND pass the
+ * filter — for `baseline`. Hand-written schema not yet in the DB stays pending; what's really there is
+ * captured. Each field/index/event/constraint is its own object, so intersect-by-key handles them.
+ */
+declare function intersectKinds(registry: KindRegistry, disk: PortableObject[], live: PortableObject[], f: Filter): PortableObject[];
+
+/** One rendered object (table / function / access): its const statement + the imports it needs. */
+interface RenderedUnit {
+    kind: "table" | "function" | "access";
+    /** DB object name (drives the file path). */
+    name: string;
+    /** The exported const identifier (`User`, `math_add`, …). */
+    exportName: string;
+    /** The `export const … = define…(…);` statement source (no import lines). */
+    code: string;
+    /** The `import …` lines this unit needs. */
+    imports: string[];
+}
+/** Local-only content a merge would drop when mirroring the DB. */
+interface LocalOnly {
+    /** Per existing const: field keys present locally but absent from the DB object. */
+    fields: {
+        exportName: string;
+        fields: string[];
+    }[];
+    /** Whole consts present locally whose object the DB no longer has. */
+    objects: string[];
+}
+interface MergeResult {
+    content: string;
+    localOnly: LocalOnly;
+}
+/** Options governing what happens to local-only content. */
+interface MergeOptions {
+    /** Keep local-only fields (graft them back into the merged object). */
+    keepLocalFields: boolean;
+    /** Keep local-only consts (objects the DB no longer has). */
+    keepLocalObjects: boolean;
+}
+/** What pulling would do to one schema file. */
+interface PullFilePlan {
+    /** Path relative to the project root (for display). */
+    rel: string;
+    /** Absolute path on disk. */
+    abs: string;
+    /**
+     * `create` (new file), `update` (merged edits), `unchanged` (already matches the DB), or `delete`
+     * (a file that is purely local-only entities the DB doesn't have — removed when mirroring).
+     */
+    action: "create" | "update" | "unchanged" | "delete";
+    /** Current file contents (`""` for a new file). */
+    before: string;
+    /** Contents after the pull (the merged result). */
+    after: string;
+    /** Local-only content this file would drop when mirroring the DB. */
+    localOnly: LocalOnly;
+}
+/** A driver's introspection rendered into a per-file write plan (see a driver's `planPull`). */
+interface PullPlan {
+    files: PullFilePlan[];
+}
+/** Apply a plan: write created/updated files, delete local-only files. Returns the paths touched. */
+declare function applyPull(plan: PullPlan): string[];
+/**
+ * Merge `units` into `existingSrc`. Each unit replaces the matching `export const` in place (DB wins),
+ * preserving everything else in the file. New units are appended; needed imports are unioned in.
+ * Local-only fields/objects are reported, and kept or dropped per `opts`.
+ */
+declare function mergeUnits(existingSrc: string, units: RenderedUnit[], opts: MergeOptions): MergeResult;
+/**
+ * A compact colored line diff for previews. A new file renders as all-green additions; an edit
+ * renders removed (red `-`) / added (green `+`) lines with a little surrounding context (long
+ * unchanged runs collapse to `…`).
+ */
+declare function lineDiff(before: string, after: string): string;
+/**
+ * A git-style unified diff between two texts, headed by `label` as the file path — for piping to a
+ * diff viewer (delta / git's pager). Returns "" when there's no change.
+ */
+declare function unifiedDiff(before: string, after: string, label: string): string;
+/** Colored verb for a pull action (`new` / `update` / `delete` / `unchanged`). */
+declare function actionLabel(action: "create" | "update" | "unchanged" | "delete"): string;
+
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+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). */
+interface EmitOptions {
+    ifNotExists?: boolean;
+    overwrite?: boolean;
+}
+/** Options for {@link Driver.apply}. */
+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. */
+interface ConnectionOverrides {
+    url?: string;
+    namespace?: string;
+    database?: string;
+    username?: string;
+    password?: string;
+    authLevel?: string;
+}
+/** The direction a migration is applied in. */
+type MigrationDirection = "up" | "down";
+/** A migration's bookkeeping identity, recorded in the migrations-tracking table. */
+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.
+ */
+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).
+ */
+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.
+ */
+interface Driver<Conn = unknown, Tbl extends Authored = Authored, Def extends AuthoredDef = AuthoredDef> {
+    readonly name: string;
+    /** 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[]>;
+    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>;
+    readonly shadow?: ShadowCapability<Conn>;
+    /** Apply-time migration bookkeeping. Absent -> this driver can't run migrations (diff/gen still do). */
+    readonly migrations?: MigrationStore<Conn>;
+    /**
+     * 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;
+}
+/** Register a driver under its `name` (idempotent; last write wins). */
+declare function registerDriver(driver: Driver<unknown>): void;
+/** Look up a registered driver, or throw with the list of known names. */
+declare function getDriver(name: string): Driver<unknown>;
+/** All registered driver names (for help text / config validation). */
+declare function driverNames(): string[];
+
+export { registerDriver as $, type Authored as A, type PullPlan as B, type RenderedUnit as C, type Driver as D, unifiedDiff as E, type Filter as F, checksum as G, EMPTY_STORED as H, listMigrations as I, type Migration as J, readSnapshot as K, type LocalOnly as L, type MergeOptions as M, slug as N, timestamp as O, type PullFilePlan as P, writeSnapshot as Q, type ResolvedConfig as R, type StoredSnapshot as S, type ApplyOptions as T, type ConnectionOverrides as U, driverNames as V, type EmitOptions as W, getDriver as X, type MigrationDirection as Y, type MigrationRecord as Z, type MigrationStore as _, type AuthoredDef as a, type ShadowCapability as a0, type Statement as a1, buildKindDiff as a2, type Definable as a3, emitKinds as a4, introspectKinds as a5, type KindDisplay as a6, type KindEngine as a7, type KindPlan as a8, KindRegistry as a9, type KindSnapshot as aa, type KindSpec as ab, lowerSchema as ac, type OrderNode as ad, orderObjects as ae, type PortableObject as af, planKinds as ag, type Ref as ah, type ResolvedDisplay as ai, snapshotKinds as aj, snapshotObjects as ak, loadProject as b, type Diff as c, type DiffItem as d, formatItems as e, formatDiff as f, formatPatch as g, type FilterOpts as h, isEmptyDiff as i, filterKinds as j, inCat as k, loadConfig as l, makeJiti as m, intersectKinds as n, kindFlags as o, mergeStored as p, parseFilter as q, resolveConnectionConfig as r, summarizeKinds as s, tokenDiff as t, passesFilter as u, actionLabel as v, applyPull as w, lineDiff as x, type MergeResult as y, mergeUnits as z };