@better-schemic/core 0.1.0-alpha.1

package/lib/driver-LVldBEhS.d.ts

@@ -0,0 +1,818 @@
+import { R as ResolvedConfig } from './config-BYh7WA4P.js';
+import { a as SecretRef, S as SecretProvider } from './secrets-BETi5p8g.js';
+import { Command } from 'commander';
+
+/**
+ * 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 (a cast suffix like `'x'::text`,
+     * added parens like `(a>0)`) or never introspects them (a COMMENT, an index) — so a faithful `emit` would phantom-diff a
+     * freshly-applied schema against `introspect`. Return `emit` MINUS those clauses: they stay create-time
+     * faithful in `emit`, but don't count as changes. `canonical(a) === canonical(b)` MUST mean "no
+     * migration needed". Affects ONLY classification; `emit`/`overwrite` (the DDL) are unaffected.
+     */
+    canonical?(portable: P): string;
+    /**
+     * Fine-grained DISPLAY items for a change of this object — so `better-schemic diff` shows per-SUB-OBJECT
+     * changes (a table decomposes into per-FIELD items: `field:user:name` changed), each carrying its
+     * owner `table` so the display GROUPS them hierarchically under it, instead of one coarse whole-object
+     * item. Called `(prev, next)`: a change diffs the two; `(undefined, next)` lists the object's
+     * sub-items as adds — the `--full` projection core uses for the full desired-state view. Default
+     * (omitted) = ONE whole-object item. DISPLAY ONLY — never affects up/down DDL (that is
+     * `emit`/`overwrite`); a structured driver reuses the per-field diff it already computes. Leave
+     * `DiffItem.file` unset (the caller attaches source linkage).
+     */
+    displayItems?(prev: P | undefined, next: P | undefined): DiffItem[];
+    /**
+     * Objects this one must be emitted AFTER — the cross-kind dependency edges (a field/index -> its
+     * table; an edge table -> its in/out tables; an event -> its table + any function it calls). Drives
+     * the topological sort in ./plan.ts. Omitted = no dependencies.
+     */
+    deps?(portable: P): Ref[];
+    /**
+     * The owning object to CLUSTER next to in the emitted order (an index's table) — readability only,
+     * never overrides {@link deps}. Omitted = a top-level object.
+     */
+    owner?(portable: P): Ref | undefined;
+    /**
+     * The STRUCTURAL container this object is nested within (an index's/field's table) — used for
+     * ADDRESSING and grouping (the CLI's dotted `parent.child`, e.g. `sc index info user.email_idx`) and
+     * distinct from {@link owner}, which is a DISPLAY choice (diff clustering). A kind may declare `parent`
+     * (it IS nested) while declining `owner` (it doesn't want per-parent diff clustering), or vice versa.
+     * The CLI resolves a nesting address as `parent ?? owner` (so a kind that only sets `owner` still
+     * addresses dotted). Omitted (and no `owner`) = a top-level object, addressed by its bare name.
+     */
+    parent?(portable: P): Ref | undefined;
+    /**
+     * Live connection -> all portable objects of THIS kind (the reverse direction). Introspection is
+     * often one `INFO`/catalog read yielding every kind at once; a driver backs all of its kinds'
+     * `introspect` with one shared (memoized) read and slices out this kind's objects. Omitted -> this
+     * kind isn't introspectable (diff/emit still work from authored state).
+     */
+    introspect?(conn: unknown): Promise<P[]>;
+    /**
+     * How this kind is PRESENTED — its human labels and the folder its objects render into. All optional
+     * with sensible defaults off the kind name (see {@link KindRegistry.display}), so a kind only declares
+     * what the defaults get wrong (e.g. `plural: "Indexes"`, or `folder: "access"`). DISPLAY ONLY.
+     */
+    display?: KindDisplay;
+    /**
+     * UNMANAGED by the migration pipeline: when `true`, objects of this kind are EXCLUDED from
+     * snapshot / diff / gen AND from the introspect-compare — so they never enter a migration file nor
+     * phantom-diff. For a kind whose lifecycle doesn't fit committed migrations: e.g. SurrealDB
+     * `DEFINE ACCESS`, which carries a secret the DB redacts on introspection (can't round-trip) and
+     * rotates on its own cadence. Such a kind is managed OUT-OF-BAND via the driver's own commands
+     * (`sc <kind> …`). `emit`/`lower` still work (a driver command may use them); only the automatic
+     * migration lifecycle skips it. Omitted/false = a normal, migration-managed kind.
+     *
+     * A PREDICATE form (`(portable) => boolean`) decides PER OBJECT — for a kind whose objects are
+     * managed only when they round-trip cleanly (e.g. SurrealDB access: key-free defs are manageable,
+     * key-bearing/redacted ones are not). The object is REQUIRED by
+     * {@link KindRegistry.isExcludedFromMigrations}; only a boolean `true` also skips introspection
+     * ({@link KindRegistry.skipsIntrospection}) — a predicate can't be decided there.
+     */
+    excludeFromMigrations?: boolean | ((portable: PortableObject) => boolean);
+}
+/** Per-kind presentation metadata (labels + output folder). All optional; core fills defaults. */
+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;
+    /**
+     * Is this PORTABLE OBJECT UNMANAGED by the migration pipeline (its engine set
+     * {@link KindEngine.excludeFromMigrations})? The snapshot/diff/emit spine skips such objects — see
+     * the flag's docs. The OBJECT is required: a per-object predicate can't be evaluated without it, and
+     * defaulting to "managed" would let a key-bearing object slip into a migration. An unregistered kind
+     * is treated as managed (false), so a stray object never gets silently dropped by a typo.
+     */
+    isExcludedFromMigrations(portable: PortableObject): boolean;
+    /**
+     * Whether `kind` is STATICALLY excluded from migrations (`excludeFromMigrations === true`), so even
+     * introspection skips it. A per-object PREDICATE can't be decided without an object: introspection
+     * runs for the kind, and the diff/snapshot/emit choke points filter by object afterwards.
+     */
+    skipsIntrospection(kind: string): boolean;
+    /**
+     * 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). Pass `registry` to DROP kinds/objects
+ * marked {@link KindEngine.excludeFromMigrations} (e.g. SurrealDB key-bearing access) so unmanaged,
+ * secret-bearing objects never enter a snapshot / migration. Omit it to snapshot every object
+ * unchanged.
+ */
+declare function snapshotKinds(schema: PortableObject[], registry?: KindRegistry): 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[];
+    /**
+     * Apply-time secret bindings: `$param` name -> a write-only {@link SecretRef} (e.g. `env("X")`).
+     * Populated by a driver whose DDL emits secret placeholders (SurrealDB `DEFINE ACCESS … KEY $param`).
+     * MODEL 1: stored in the migration so it replays without the live schema; the **value never appears
+     * here** — the apply layer resolves each ref through a `SecretProvider` and binds it (`db.query(ddl,
+     * resolved)`), so secrets stay out of the schema, snapshot, and migration files. Diff-excluded +
+     * snapshot-omitted, so a redacted secret never reads as drift.
+     */
+    bindings?: Record<string, SecretRef>;
+    /** 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. A statement may be pretty-printed multi-line, so every LINE gets
+ * its own `+`/`-` and the hunk counts count lines, not statements.
+ */
+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 `better-schemic gen --baseline`).
+ */
+interface StoredSnapshot {
+    version: 3;
+    /** The driver that authored this snapshot ("surrealdb"). */
+    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 `better-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>;
+    /**
+     * 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). */
+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). */
+    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>;
+    }>;
+}
+/**
+ * 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.
+ */
+interface CallableFunctions<Conn = unknown> {
+    invoke(conn: Conn, name: string, args: Record<string, unknown>): Promise<unknown>;
+}
+/** A declared argument for a {@link DriverCommand} — used for parsing + `--help`. */
+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. */
+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). */
+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. */
+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).
+ */
+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.
+ */
+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 /
+     * 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[]>;
+    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[];
+    /**
+     * 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;
+}
+/** 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 { intersectKinds as $, type Authored as A, type ResolvedDisplay as B, type CallableFunctions as C, type Driver as D, EMPTY_STORED as E, type Filter as F, type Statement as G, type StoredSnapshot as H, actionLabel as I, applyPull as J, KindRegistry as K, type LocalOnly as L, type MergeOptions as M, buildKindDiff as N, type OrderNode as O, type ParsedCommandArgs as P, checksum as Q, type Ref as R, type ShadowCapability as S, driverNames as T, emitKinds as U, filterKinds as V, formatDiff as W, formatItems as X, formatPatch as Y, getDriver as Z, inCat as _, type AuthoredDef as a, introspectKinds as a0, isEmptyDiff as a1, kindFlags as a2, lineDiff as a3, listMigrations as a4, lowerSchema as a5, mergeStored as a6, mergeUnits as a7, orderObjects as a8, parseFilter as a9, passesFilter as aa, planKinds as ab, readSnapshot as ac, registerDriver as ad, slug as ae, snapshotKinds as af, snapshotObjects as ag, summarizeKinds as ah, timestamp as ai, tokenDiff as aj, unifiedDiff as ak, writeSnapshot as al, type ApplyOptions as b, type CommandArgs as c, type CommandContext as d, type CommandIo as e, type ConnectionOverrides as f, type Definable as g, type Diff as h, type DiffItem as i, type DriverCommand as j, type EmitOptions as k, type FilterOpts as l, type KindDisplay as m, type KindEngine as n, type KindPlan as o, type KindSnapshot as p, type KindSpec as q, type MergeResult as r, type Migration as s, type MigrationDirection as t, type MigrationRecord as u, type MigrationStore as v, type PortableObject as w, type PullFilePlan as x, type PullPlan as y, type RenderedUnit as z };