@schemic/surrealdb 0.1.0-alpha.0

package/lib/index.d.ts

@@ -0,0 +1,1231 @@
+import { Driver } from '@schemic/core';
+import { BoundQuery, Table, RecordIdValue, RecordId, Bound, RecordIdRange, Uuid, DateTime, Duration, Decimal, FileRef, Geometry, Surreal } from 'surrealdb';
+export { BoundQuery } from 'surrealdb';
+import { z } from 'zod';
+import { ConnectionConfigBase, ConnectionEntry, ResolveContext } from '@schemic/core/driver';
+
+/**
+ * The "pure" approach: a field is a stock Zod schema + SurrealQL DDL metadata.
+ * The JS<->DB mapping rides on Zod's two native channels via codecs:
+ *   - encoded side (`z.input`)  = DB wire type
+ *   - decoded side (`z.output`) = app type
+ * `z.decode` reads from the DB, `z.encode` writes to it.
+ */
+/**
+ * Maps a Surreal-native schema (datetime codec, recordId) to its SurrealQL type.
+ * Kept on the schema — not the field — so it composes through array()/optional()/nesting.
+ */
+declare const surrealTypeRegistry: WeakMap<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, string>;
+/**
+ * Maps an object schema built via `s.object` to its original SField shape, so
+ * nested fields keep their DDL metadata ($default/$assert/...) during generation.
+ */
+declare const objectFieldsRegistry: WeakMap<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, Record<string, AnyField>>;
+/**
+ * Per-table/field row-level permissions. A `PermOp` is one access operation; `Perm` is
+ * the rule for one op — `true` (FULL) / `false` (NONE) / a `BoundQuery` (a `WHERE` expr) /
+ * `` `same as X` `` to reuse another op's resolved rule. A `TablePermissions` is a blanket
+ * rule, a shared `WHERE`, or per-op rules. Fields have NO `delete` op (verified against
+ * the DB), so they use `FieldPerm` / `FieldPermissions`.
+ */
+type PermOp = "select" | "create" | "update" | "delete";
+type Perm = boolean | BoundQuery | `same as ${PermOp}`;
+type TablePermissions = boolean | BoundQuery | Partial<Record<PermOp, Perm>>;
+type FieldPerm = boolean | BoundQuery | "same as select" | "same as create" | "same as update";
+type FieldPermissions = boolean | BoundQuery | Partial<Record<"select" | "create" | "update", FieldPerm>>;
+/** SurrealQL DDL metadata — the `$`-prefixed field options. */
+interface SurrealMeta {
+    default?: BoundQuery;
+    defaultAlways?: boolean;
+    value?: BoundQuery;
+    /** `COMPUTED <expr>` — a derived, read-only column (computed on read; never written). */
+    computed?: BoundQuery;
+    /**
+     * `ASSERT` fragments that AND-combine into one clause. Computed checks (format
+     * builders, `$`-constraints, `.$assert()`-derived) are plain strings; a custom
+     * `.$assert(surql\`…\`)` is a `BoundQuery` (inlined during DDL generation).
+     */
+    asserts?: (string | BoundQuery)[];
+    readonly?: boolean;
+    comment?: string;
+    /** Field-level `PERMISSIONS` (no `delete` op). Omitted ops default to FULL in
+     * SurrealDB — the table is the gate; set an op `false` to lock it. See `.$permissions()`. */
+    permissions?: FieldPermissions;
+    /** DB-managed, client-hidden: still emits DEFINE FIELD (+ PERMISSIONS NONE) but is
+     * excluded from the public app/create/update surface. See `.$internal()` / `.system`. */
+    internal?: boolean;
+    /** Single-field index: `.index()` (normal) / `.unique()` (uniqueness). Emits a `DEFINE
+     * INDEX <table>_<field>_idx ON TABLE <table> FIELDS <field> [UNIQUE]`. */
+    index?: {
+        unique?: boolean;
+    };
+    /** `REFERENCE [ON DELETE …]` on a record-link field. See `.reference()`. */
+    reference?: true | {
+        onDelete?: "reject" | "cascade" | "ignore" | "unset" | BoundQuery;
+    };
+}
+/**
+ * Reverse of {@link formatAssert}: recover a format name from a baked `string::is_<fmt>($value)`
+ * assert. Used by `pull` to restore `s.<format>()` instead of `s.string().$assert(...)`. Returns
+ * undefined for any other assert — including one that combines a format with extra text — so only an
+ * exact, single-format assert reverses (a user's own assert is never swallowed).
+ */
+declare function formatForAssert(assert: string): string | undefined;
+/** The schema one wrapper down — what `unwrap()` returns. */
+type InnerOf<S extends z.ZodType> = S extends z.ZodOptional<infer I extends z.ZodType> ? I : S extends z.ZodNullable<infer I extends z.ZodType> ? I : S extends z.ZodDefault<infer I extends z.ZodType> ? I : S extends z.ZodPrefault<infer I extends z.ZodType> ? I : S extends z.ZodCatch<infer I extends z.ZodType> ? I : S extends z.ZodReadonly<infer I extends z.ZodType> ? I : S extends z.ZodArray<infer I extends z.ZodType> ? I : S;
+/**
+ * A Zod schema paired with SurrealQL DDL metadata. `Flags` tracks input traits
+ * used by `Create<>`/`Update<>`: `"create"` (DB-filled -> optional on create) and
+ * `"readonly"` (excluded from updates). It only appears in method return types, so
+ * `SField` is covariant in it.
+ */
+/**
+ * The PORTABLE, dialect-agnostic field base (extraction phase B — see docs/AUTHORING-SPLIT.md).
+ * Holds the Zod schema, an opaque per-dialect `native` metadata slot, the field-level codecs, and
+ * the App-land Zod wrappers (which carry `native` forward via the `rebuild` hook so a chain keeps
+ * its concrete dialect type). It references NOTHING SurrealDB-specific. Each dialect subclasses it
+ * (see {@link SField} for SurrealDB) to add native authoring (`$`-methods) and re-type the wrappers.
+ */
+declare abstract class SFieldBase<S extends z.ZodType = z.ZodType, Flags extends string = never, N = unknown> {
+    readonly schema: S;
+    readonly native: N;
+    constructor(schema: S, native: N);
+    /** Rebuild a sibling field of the SAME dialect with a new schema/flags. Each dialect overrides it. */
+    protected abstract rebuild<S2 extends z.ZodType, F2 extends string>(schema: S2, native: N): SFieldBase<S2, F2, N>;
+    /** A fresh, empty native-metadata bag (for wrappers like `or`/`and` that reset it). */
+    protected abstract blank(): N;
+    /** Decode a DB value to its app type (wire -> app). */
+    decode(value: unknown): z.output<S>;
+    /** Encode an app value to its DB wire type (app -> wire). */
+    encode(value: z.output<S>): z.input<S>;
+    decodeAsync(value: unknown): Promise<z.output<S>>;
+    encodeAsync(value: z.output<S>): Promise<z.input<S>>;
+    safeDecode(value: unknown): z.ZodSafeParseResult<z.core.output<S>>;
+    safeEncode(value: z.output<S>): z.ZodSafeParseResult<z.core.input<S>>;
+    safeDecodeAsync(value: unknown): Promise<z.ZodSafeParseResult<z.core.output<S>>>;
+    safeEncodeAsync(value: z.output<S>): Promise<z.ZodSafeParseResult<z.core.input<S>>>;
+    /** @deprecated `parse` decodes a value (wire -> app). Use {@link SField.decode | decode}. */
+    parse(value: unknown): z.output<S>;
+    /** @deprecated Use {@link SField.safeDecode | safeDecode}. */
+    safeParse(value: unknown): z.ZodSafeParseResult<z.core.output<S>>;
+    /** @deprecated Use {@link SField.decodeAsync | decodeAsync}. */
+    parseAsync(value: unknown): Promise<z.output<S>>;
+    /** @deprecated Use {@link SField.safeDecodeAsync | safeDecodeAsync}. */
+    safeParseAsync(value: unknown): Promise<z.ZodSafeParseResult<z.core.output<S>>>;
+    optional(): SFieldBase<z.ZodOptional<S>, Flags, N>;
+    nullable(): SFieldBase<z.ZodNullable<S>, Flags, N>;
+    default(value: z.input<S>): SFieldBase<z.ZodDefault<S>, Flags, N>;
+    /** Zod prefault: fill an absent value with `value`, then validate it (unlike `.default`). */
+    prefault(value: z.input<S>): SFieldBase<z.ZodPrefault<S>, Flags, N>;
+    /** Zod catch: fall back to `value` when parsing fails. */
+    catch(value: z.output<S>): SFieldBase<z.ZodCatch<S>, Flags, N>;
+    array(): SFieldBase<z.ZodArray<S>, Flags, N>;
+    nullish(): SFieldBase<z.ZodOptional<z.ZodNullable<S>>, Flags, N>;
+    /** Zod union — `a.or(b)` accepts either; SurrealQL `<a> | <b>`. Mirrors Zod's `.or()`. */
+    or<F extends AnyField | z.ZodType>(other: F): SFieldBase<z.ZodUnion<[S, SchemaOf<F>]>, never, N>;
+    /** Zod intersection — `a.and(b)`; merges object fields in DDL. Mirrors Zod's `.and()`. */
+    and<F extends AnyField | z.ZodType>(other: F): SFieldBase<z.ZodIntersection<S, SchemaOf<F>>, never, N>;
+    refine(check: (arg: z.output<S>) => unknown, params?: string | z.core.$ZodCustomParams): this;
+    superRefine(refinement: (arg: z.output<S>, ctx: z.core.$RefinementCtx<z.output<S>>) => void): this;
+    check(...checks: (z.core.CheckFn<z.output<S>> | z.core.$ZodCheck<z.output<S>>)[]): this;
+    overwrite(fn: (x: z.output<S>) => z.output<S>): this;
+    brand<B extends PropertyKey = PropertyKey>(value?: B): this;
+    /** Zod's app-side metadata (JSON-schema/docs) — distinct from `$comment()` (SurrealDB COMMENT). */
+    describe(description: string): this;
+    meta(data: z.core.GlobalMeta): this;
+    /** Zod's app-side readonly (TS-immutable output) — distinct from `$readonly()` (SurrealDB READONLY). */
+    readonly(): SFieldBase<z.ZodReadonly<S>, Flags, N>;
+    /** Zod transform — changes the decoded `App<>` value; the stored (wire) type is unchanged. */
+    transform<NewOut>(fn: (arg: z.output<S>, ctx: z.core.$RefinementCtx<z.output<S>>) => NewOut): SFieldBase<z.ZodPipe<S, z.ZodTransform<Awaited<NewOut>, z.output<S>>>, Flags, N>;
+    /** Zod pipe — feed this field's output into `target`; the stored (wire) type stays `this`. */
+    pipe<T extends z.core.$ZodType<unknown, z.output<S>>>(target: T): SFieldBase<z.ZodPipe<S, T>, Flags, N>;
+    /** Peel one wrapper (optional/nullable/default/prefault/catch/readonly/array) off the field. */
+    unwrap(): SFieldBase<InnerOf<S>, Flags, N>;
+    /** Object-only: allow arbitrary extra keys — `FLEXIBLE` in DDL. Mirrors Zod's `.loose()`. */
+    loose(): this;
+    /** Object-only: reject unknown keys — non-`FLEXIBLE` (the default). Mirrors Zod's `.strict()`. */
+    strict(): this;
+    /** Alias for {@link loose} — a `FLEXIBLE` object accepting arbitrary keys. */
+    flexible(): this;
+    private objectMode;
+}
+/**
+ * The SurrealDB field — the dialect extension of {@link SFieldBase}. Adds SurrealDB-native authoring
+ * (the `$`-methods over `SurrealMeta`: DEFAULT/VALUE/ASSERT/PERMISSIONS/REFERENCE/…) and re-types the
+ * inherited portable Zod wrappers so a chain stays a `SField`. `s.*` produces these. In the package
+ * split this class moves to `@schemic/surrealdb` (see docs/AUTHORING-SPLIT.md).
+ */
+declare class SField<S extends z.ZodType = z.ZodType, Flags extends string = never> extends SFieldBase<S, Flags, SurrealMeta> {
+    constructor(schema: S, surreal?: SurrealMeta);
+    /** The SurrealDB-native field metadata (DEFAULT/VALUE/ASSERT/PERMISSIONS/…). */
+    get surreal(): SurrealMeta;
+    protected rebuild<S2 extends z.ZodType, F2 extends string>(schema: S2, native: SurrealMeta): SField<S2, F2>;
+    protected blank(): SurrealMeta;
+    optional(): SField<z.ZodOptional<S>, Flags>;
+    nullable(): SField<z.ZodNullable<S>, Flags>;
+    default(value: z.input<S>): SField<z.ZodDefault<S>, Flags>;
+    prefault(value: z.input<S>): SField<z.ZodPrefault<S>, Flags>;
+    catch(value: z.output<S>): SField<z.ZodCatch<S>, Flags>;
+    array(): SField<z.ZodArray<S>, Flags>;
+    nullish(): SField<z.ZodOptional<z.ZodNullable<S>>, Flags>;
+    or<F extends AnyField | z.ZodType>(other: F): SField<z.ZodUnion<[S, SchemaOf<F>]>>;
+    and<F extends AnyField | z.ZodType>(other: F): SField<z.ZodIntersection<S, SchemaOf<F>>>;
+    readonly(): SField<z.ZodReadonly<S>, Flags>;
+    transform<NewOut>(fn: (arg: z.output<S>, ctx: z.core.$RefinementCtx<z.output<S>>) => NewOut): SField<z.ZodPipe<S, z.ZodTransform<Awaited<NewOut>, z.output<S>>>, Flags>;
+    pipe<T extends z.core.$ZodType<unknown, z.output<S>>>(target: T): SField<z.ZodPipe<S, T>, Flags>;
+    unwrap(): SField<InnerOf<S>, Flags>;
+    $default(value: z.output<S> | BoundQuery): SField<S, Flags | "create">;
+    $defaultAlways(value: z.output<S> | BoundQuery): SField<S, Flags | "create">;
+    /**
+     * Set a DB-side `VALUE` clause. Whether the field is create-OPTIONAL depends on
+     * whether the expression consumes the client input (`$value`), which can't be
+     * inferred — so it's explicit via the `optional` option:
+     *   - `time::now()` ignores input -> `{ optional: true }` (create-optional)
+     *   - `string::lowercase($value)` requires input -> default (create-required)
+     * Optionality is purely type-level (the option drives the `"create"` flag that
+     * `Create<>`/`encode()` read); it does not touch the app type or DB nullability.
+     * There is no separate update option — every field is already optional in `Update<>`.
+     */
+    $value<O extends boolean = false>(expr: BoundQuery, opts?: {
+        optional?: O;
+    }): SField<S, O extends true ? Flags | "create" : Flags>;
+    /**
+     * `COMPUTED <expr>` — a derived, read-only column computed from other fields. Never written, so
+     * it's create-OPTIONAL: `s.string().$computed(surql\`string::concat(first, " ", last)\`)`.
+     */
+    $computed(expr: BoundQuery): SField<S, Flags | "create">;
+    /**
+     * Add an `ASSERT` fragment (fragments AND-combine into one clause):
+     *   - `.$assert(surql\`…\`)` pushes a custom expression (inlined during DDL generation).
+     *   - `.$assert()` (no args) derives fragments from the field's existing Zod checks
+     *     (formats, string length/regex, number bounds) — best-effort; unknowns are skipped.
+     */
+    $assert(expr?: BoundQuery): SField<S, Flags>;
+    /** Min length (string) / minimum value (number). */
+    $min(n: number): SField<S, Flags>;
+    /** Max length (string) / maximum value (number). */
+    $max(n: number): SField<S, Flags>;
+    /** Exact length (string). */
+    $length(n: number): SField<S, Flags>;
+    /** Pattern match (string). */
+    $regex(re: RegExp): SField<S, Flags>;
+    /** Greater than (number). */
+    $gt(n: number): SField<S, Flags>;
+    /** Greater than or equal (number). */
+    $gte(n: number): SField<S, Flags>;
+    /** Less than (number). */
+    $lt(n: number): SField<S, Flags>;
+    /** Less than or equal (number). */
+    $lte(n: number): SField<S, Flags>;
+    /** The underlying Zod schema's `def.type` ("string" / "number" / …). */
+    private get schemaType();
+    /** Append ASSERT fragments, returning a new field (same type param + flags). */
+    private pushAsserts;
+    /** Apply a concrete-subtype Zod check (`min`/`max`/`length`/`regex`/`gt`/…) and push its
+     * matching DB fragment, returning a new field carrying the refined schema. */
+    private constrain;
+    /** Set field-level `PERMISSIONS` (no `delete` op). Omitted ops default to FULL. */
+    $permissions(spec: FieldPermissions): SField<S, Flags>;
+    $readonly(readonly?: boolean): SField<S, Flags | "readonly">;
+    $comment(comment: string): SField<S, Flags>;
+    /** Index this field — `DEFINE INDEX <table>_<field>_idx ON TABLE <table> FIELDS <field>`. */
+    index(): SField<S, Flags>;
+    /** Index this field with a uniqueness constraint (`… FIELDS <field> UNIQUE`). */
+    unique(): SField<S, Flags>;
+    /**
+     * Mark a record-link field as a `REFERENCE` so the DB tracks back-links. `onDelete` sets the
+     * `ON DELETE` action — `"reject" | "cascade" | "ignore" | "unset"`, or a `surql` expression
+     * (emitted as `ON DELETE THEN …`). Omit it for a bare `REFERENCE`.
+     */
+    reference(opts?: {
+        onDelete?: "reject" | "cascade" | "ignore" | "unset" | BoundQuery;
+    }): SField<S, Flags>;
+    /**
+     * Teach @schemic/core how to store this value in SurrealDB: give the **wire type** as an `s.*`
+     * field (its SurrealQL DDL type and Zod schema are derived from it) plus a codec
+     * (`encode`: app -> wire, `decode`: wire -> app). This turns an otherwise-unmappable field
+     * (e.g. `s.custom`/`s.instanceof`) into a real table field and clears the no-mapping brand;
+     * `s.input<>` then reports the wire type. Omit the codec for an identity mapping (the app
+     * value is stored as-is). `$`-prefixed to avoid clashing with Zod.
+     */
+    $surreal<WF extends AnyField | z.ZodType, A = z.output<S>>(wire: WF, codec?: {
+        encode: (app: A) => z.output<SchemaOf<WF>>;
+        decode: (wire: z.output<SchemaOf<WF>>) => A;
+    }): SField<z.ZodCodec<SchemaOf<WF>, S>, Exclude<Flags, NoDdl>>;
+    /**
+     * Mark the field DB-managed and client-hidden. It still emits its `DEFINE FIELD`
+     * (so SCHEMAFULL writes from a record-access SIGNUP block succeed) plus
+     * `PERMISSIONS NONE`, but is excluded from the public app/create/update surface.
+     * Reach internal fields via the `.system` view (server/system code).
+     */
+    $internal(): SField<S, Flags | "internal">;
+}
+/** A flag-agnostic SField, for internal storage where flags don't matter. */
+type AnyField = SField<z.ZodType, string>;
+type GeometryKind = "point" | "line" | "polygon" | "multipoint" | "multiline" | "multipolygon" | "collection";
+/** A `record<…>` field: table restriction (+ optional id-value type) and construction helpers. */
+declare class RecordIdField<T extends string, V extends RecordIdValue = RecordIdValue> extends SField<z.ZodType<RecordId<T, V>, RecordId<T, V>>> {
+    readonly tables: T[];
+    readonly valueType?: z.ZodType<V> | undefined;
+    constructor(tables: T[], valueType?: z.ZodType<V> | undefined, surreal?: SurrealMeta, schemaOverride?: z.ZodType<RecordId<T, V>, RecordId<T, V>>);
+    protected rebuild<S2 extends z.ZodType, F2 extends string>(schema: S2, native: SurrealMeta): SField<S2, F2>;
+    /** Restrict the id value's type — reflected as `RecordId<T, V>` and validated at runtime. */
+    type<V2 extends RecordIdValue>(schema: z.ZodType<V2>): RecordIdField<T, V2>;
+    /** Build a RecordId. Single-table: `for(id)`; multi-table: `for(table, id)`. */
+    for(idOrTable: V | T, id?: V): RecordId<T, V>;
+    /** A record-id range for queries (default: inclusive start .. exclusive end). */
+    range(from?: V | Bound<V>, to?: V | Bound<V>): RecordIdRange<T, V>;
+}
+/**
+ * Internal `Flags` brand for a field with no SurrealQL mapping. It rides the `Flags` channel,
+ * so it survives every wrapper (`.optional()`/`.array()`/…); `defineTable`/`defineRelation`
+ * reject a branded field at compile time, and `.$surreal(...)` clears it. (Runtime `inferField`
+ * is the backstop for nested/dynamic shapes.)
+ */
+type NoDdl = "~no-ddl";
+type ZodsOf<T extends readonly (AnyField | z.ZodType)[]> = {
+    -readonly [K in keyof T]: SchemaOf<T[K]>;
+};
+type Shape = Record<string, AnyField | z.ZodType>;
+type SchemaOf<F> = F extends SField<infer S, infer _> ? S : F extends z.ZodType ? F : never;
+type FlagsOf<F> = F extends SField<z.ZodType, infer Fl> ? Fl : never;
+/**
+ * Whether a field carries the `"internal"` flag (set by `.$internal()`). The
+ * `string extends FlagsOf<F>` guard short-circuits the broad `Shape` case (where
+ * flags widen to `string`, and `"internal" extends string` would wrongly be true),
+ * so `ZShape<Shape>` keeps every key for shape-agnostic refs like `TableDef<string, Shape>`.
+ */
+type IsInternal<F> = string extends FlagsOf<F> ? false : "internal" extends FlagsOf<F> ? true : false;
+/** The public zshape — internal fields are excluded (see `ZShapeAll` for the system view). */
+type ZShape<S extends Shape> = {
+    [K in keyof S as IsInternal<S[K]> extends true ? never : K]: SchemaOf<S[K]>;
+};
+/** Every field's zshape, including internal ones — backs the `.system` view. */
+type ZShapeAll<S extends Shape> = {
+    [K in keyof S]: SchemaOf<S[K]>;
+};
+/**
+ * The schema type returned by `s.object`: a plain `z.ZodObject` carrying its original
+ * `Shape` via a type-only `~szShape` brand. The brand is optional, so the runtime cast
+ * (`z.object(...) as SZObject<S>`) is sound and the brand is invisible to `z.input`/
+ * `z.output`/`App`/`Wire` — nested fields stay REQUIRED on the decoded side. It exists
+ * solely so `ShapeOf`/`CreateValue` can recover the nested shape for the create surface.
+ */
+type SZObject<S extends Shape> = z.ZodObject<ZShape<S>> & {
+    readonly "~szShape"?: S;
+};
+type ToField<F> = F extends SField<infer Sc, infer Fl> ? SField<Sc, Fl> : SField<SchemaOf<F>>;
+type Fields<S extends Shape> = {
+    [K in keyof S]: ToField<S[K]>;
+};
+type Unwrap<F> = F extends SField<z.ZodOptional<infer Inner extends z.ZodType>, infer Fl> ? SField<Inner, Fl> : F;
+type PartialShape<S extends Shape> = {
+    [K in keyof S]: SField<z.ZodOptional<SchemaOf<S[K]>>, FlagsOf<S[K]>>;
+};
+type RequiredShape<S extends Shape> = {
+    [K in keyof S]: Unwrap<Fields<S>[K]>;
+};
+interface TableConfig {
+    schemafull: boolean;
+    /** Table `TYPE`: `normal` (default) or `any` (holds both records and graph edges). */
+    type?: "normal" | "any";
+    drop?: boolean;
+    comment?: string;
+    /** Table-level `PERMISSIONS`. Omitted ops default to NONE in SurrealDB. See `.permissions()`. */
+    permissions?: TablePermissions;
+    relation?: {
+        from: string[];
+        to: string[];
+        enforced?: boolean;
+    };
+    /** Composite (multi-field) indexes. See `.index(name, fields, opts)`. */
+    indexes?: TableIndex[];
+    /** Row-change events. See `.event(name, { when?, then })`. */
+    events?: TableEvent[];
+    /** `CHANGEFEED <dur> [INCLUDE ORIGINAL]`. See `.changefeed(dur, opts?)`. */
+    changefeed?: {
+        expiry: string;
+        includeOriginal?: boolean;
+    };
+    /**
+     * A pre-computed (materialized) VIEW — `AS <SELECT …>`. When set, the table is computed from the
+     * query (forced `TYPE ANY SCHEMALESS`, no authored fields). See {@link defineView}.
+     */
+    view?: Expr;
+}
+/** A table index definition (single- or multi-field, or a row-count index). */
+interface TableIndex {
+    name: string;
+    fields: string[];
+    unique?: boolean;
+    /** A materialized row-count index (`DEFINE INDEX … COUNT`, no fields). */
+    count?: boolean;
+    /** `COMMENT <string>` on the index. */
+    comment?: string;
+    /**
+     * A special index spec appended after `FIELDS` — a vector (`HNSW …`/`DISKANN …`) or full-text
+     * (`FULLTEXT ANALYZER …`) index. Built from the `.index()` opts; minimal form (SurrealDB
+     * materializes the rest), so it round-trips against the introspected, canonicalized spec.
+     */
+    spec?: string;
+}
+/** Options for a HNSW vector index (`.index(name, [field], { hnsw: {…} })`). */
+interface HnswOptions {
+    dimension: number;
+    dist?: "euclidean" | "cosine" | "manhattan" | "minkowski" | "hamming";
+    type?: "f64" | "f32" | "i64" | "i32" | "i16";
+    efc?: number;
+    m?: number;
+}
+/** Options for a DISKANN vector index (`.index(name, [field], { diskann: {…} })`). */
+interface DiskannOptions {
+    dimension: number;
+    dist?: "euclidean" | "cosine" | "manhattan";
+    type?: "f64" | "f32" | "i64" | "i32" | "i16";
+    degree?: number;
+    l_build?: number;
+    alpha?: number;
+}
+/** Options for a FULL-TEXT search index (`.index(name, [field], { fulltext: {…} })`). Needs a
+ *  `defineAnalyzer` of the same name. `bm25: [k1, b]` tunes scoring; `true` uses the defaults. */
+interface FulltextOptions {
+    analyzer: string;
+    bm25?: boolean | [number, number];
+    highlights?: boolean;
+}
+/** A SurrealQL expression: a `surql\`…\`` bound query (bindings inlined) or a raw string. */
+type Expr = BoundQuery | string;
+/**
+ * A table event: `DEFINE EVENT <name> ON TABLE <table> [WHEN <when>] THEN <then>`. The event
+ * body sees `$before`/`$after`/`$event`/`$value`. `then` may be one expression or several
+ * (run in order). Author expressions with `surql\`…\`` (bindings inline) or a raw string.
+ */
+interface TableEvent {
+    name: string;
+    when?: Expr;
+    then: Expr | Expr[];
+}
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type AppOf<F> = z.output<SchemaOf<F>>;
+type InputOptional<F> = undefined extends z.input<SchemaOf<F>> ? true : false;
+/**
+ * Recover the nested `Shape` of an `s.object` schema (`never` if the schema isn't one).
+ * Identity-preserving wrappers (optional/default/readonly/nullable) are peeled first, then
+ * the `~szShape` brand is read. The inner `NS extends Shape ? NS : never` drops the
+ * `| undefined` that inferring from an optional property can introduce, so the result is the
+ * clean shape — or `never` for any non-object schema.
+ */
+type ShapeOf<Sc> = Sc extends z.ZodOptional<infer I> ? ShapeOf<I> : Sc extends z.ZodDefault<infer I> ? ShapeOf<I> : Sc extends z.ZodReadonly<infer I> ? ShapeOf<I> : Sc extends z.ZodNullable<infer I> ? ShapeOf<I> : Sc extends {
+    "~szShape"?: infer NS;
+} ? NS extends Shape ? NS : never : never;
+/**
+ * The element `Shape` of an `s.object(...).array()` field (`never` otherwise). Peels the
+ * same identity-preserving wrappers off the array, then reads the element's `~szShape`.
+ */
+type ArrayShapeOf<Sc> = Sc extends z.ZodOptional<infer I> ? ArrayShapeOf<I> : Sc extends z.ZodDefault<infer I> ? ArrayShapeOf<I> : Sc extends z.ZodReadonly<infer I> ? ArrayShapeOf<I> : Sc extends z.ZodNullable<infer I> ? ArrayShapeOf<I> : Sc extends z.ZodArray<infer E> ? ShapeOf<E> : never;
+/**
+ * The create-input VALUE type for a field. A nested `s.object` recurses into its own
+ * `CreateShape` (so nested `$default`/`"create"` fields become optional too); an array of
+ * `s.object` becomes that nested create-shape's array; everything else is the plain app
+ * type (`AppOf`). `[X] extends [never]` guards each branch because `never extends Shape` is
+ * vacuously true and would otherwise wrongly match the object branch for scalar fields.
+ */
+type CreateValue<F, Sc = SchemaOf<F>> = [ShapeOf<Sc>] extends [never] ? [ArrayShapeOf<Sc>] extends [never] ? AppOf<F> : ArrayShapeOf<Sc> extends infer ENS extends Shape ? CreateShape<ENS>[] : AppOf<F> : ShapeOf<Sc> extends infer NS extends Shape ? CreateShape<NS> : AppOf<F>;
+type CreateOptional<S extends Shape, K extends keyof S> = K extends "id" ? true : "create" extends FlagsOf<S[K]> ? true : InputOptional<S[K]>;
+type CreateShape<S extends Shape> = Prettify<{
+    [K in keyof S as IsInternal<S[K]> extends true ? never : CreateOptional<S, K> extends true ? never : K]: CreateValue<S[K]>;
+} & {
+    [K in keyof S as IsInternal<S[K]> extends true ? never : CreateOptional<S, K> extends true ? K : never]?: CreateValue<S[K]>;
+}>;
+type CreateShapeAll<S extends Shape> = Prettify<{
+    [K in keyof S as CreateOptional<S, K> extends true ? never : K]: CreateValue<S[K]>;
+} & {
+    [K in keyof S as CreateOptional<S, K> extends true ? K : never]?: CreateValue<S[K]>;
+}>;
+type UpdateExcluded<S extends Shape, K extends keyof S> = K extends "id" ? true : "readonly" extends FlagsOf<S[K]> ? true : false;
+/**
+ * The update-input VALUE type for a field — a DEEP partial, since `MERGE` recursively
+ * deep-merges nested objects (so any subset of nested keys is a valid patch). A nested
+ * `s.object` recurses into its own `UpdateShape` (every nested field optional); an array
+ * of `s.object` becomes that update-shape's array; everything else is the plain app type
+ * (`AppOf`). The `[X] extends [never]` guards mirror `CreateValue` (so scalar fields don't
+ * wrongly match the object branch via `never extends Shape`).
+ */
+type UpdateValue<F, Sc = SchemaOf<F>> = [ShapeOf<Sc>] extends [never] ? [ArrayShapeOf<Sc>] extends [never] ? AppOf<F> : ArrayShapeOf<Sc> extends infer ENS extends Shape ? UpdateShape<ENS>[] : AppOf<F> : ShapeOf<Sc> extends infer NS extends Shape ? UpdateShape<NS> : AppOf<F>;
+type UpdateShape<S extends Shape> = Prettify<{
+    [K in keyof S as IsInternal<S[K]> extends true ? never : UpdateExcluded<S, K> extends true ? never : K]?: UpdateValue<S[K]>;
+}>;
+type UpdateShapeAll<S extends Shape> = Prettify<{
+    [K in keyof S as UpdateExcluded<S, K> extends true ? never : K]?: UpdateValue<S[K]>;
+}>;
+/** A Zod-style non-throwing result: `{ success: true; data }` | `{ success: false; error }`
+ * (mirrors `z.safeEncode`/`z.safeDecode`). */
+type SafeResult<T> = z.ZodSafeParseResult<T>;
+/** The wire payload `encode`/`safeEncode` build: the provided keys' wire (`z.input`) types. Only
+ * the supplied keys are present at runtime, hence `Partial`. */
+type MakeWire<S extends Shape> = Partial<z.input<z.ZodObject<ZShape<S>>>>;
+/** Same, over ALL fields — the `.system` view includes `$internal()` ones. */
+type MakeWireAll<S extends Shape> = Partial<z.input<z.ZodObject<ZShapeAll<S>>>>;
+/** A table (or relation) definition: shape + DDL config, with chainable builders. */
+declare class TableDef<Name extends string, S extends Shape> {
+    readonly name: Name;
+    readonly fields: Fields<S>;
+    readonly config: TableConfig;
+    /** Zod object over the inner schemas — drives validation, encode/decode, types. */
+    readonly object: z.ZodObject<ZShape<S>>;
+    constructor(name: Name, fields: Fields<S>, config?: TableConfig);
+    get kind(): "table" | "relation";
+    /**
+     * A SurrealDB `Table` instance for this table — for direct SDK calls that take a table reference,
+     * e.g. `db.select(User.table)`. (For a record id, chain `User.record().for(id)`.)
+     */
+    get table(): Table<Name>;
+    /** DB wire row -> app object. */
+    decode(row: unknown): z.output<z.ZodObject<ZShape<S>>>;
+    /** DB wire row -> app object (async — for async refinements). */
+    decodeAsync(row: unknown): Promise<z.output<z.ZodObject<ZShape<S>>>>;
+    safeDecode(row: unknown): z.ZodSafeParseResult<z.core.$InferObjectOutput<ZShape<S>, {}>>;
+    safeDecodeAsync(row: unknown): Promise<z.ZodSafeParseResult<z.core.$InferObjectOutput<ZShape<S>, {}>>>;
+    /** @deprecated `parse` decodes a DB row (wire -> app). Use {@link TableDef.decode | decode}. */
+    parse(row: unknown): z.output<z.ZodObject<ZShape<S>>>;
+    /** @deprecated Use {@link TableDef.safeDecode | safeDecode} (or {@link TableDef.safeEncode | safeEncode} to validate an app object). */
+    safeParse(row: unknown): z.ZodSafeParseResult<z.core.$InferObjectOutput<ZShape<S>, {}>>;
+    /** @deprecated Use {@link TableDef.decodeAsync | decodeAsync}. */
+    parseAsync(row: unknown): Promise<z.output<z.ZodObject<ZShape<S>>>>;
+    /** @deprecated Use {@link TableDef.safeDecodeAsync | safeDecodeAsync}. */
+    safeParseAsync(row: unknown): Promise<z.ZodSafeParseResult<z.core.$InferObjectOutput<ZShape<S>, {}>>>;
+    /**
+     * Build a wire payload for `CREATE` (DB-filled fields optional). Validates+encodes each
+     * provided field — so this VALIDATES and THROWS the aggregated `z.ZodError` on invalid
+     * input. Use `safeEncode` for the non-throwing form.
+     */
+    encode(input: CreateShape<S>): MakeWire<S>;
+    /**
+     * Build a wire payload for `UPDATE`/`MERGE` (a partial patch; excludes id/readonly).
+     * VALIDATES and THROWS on invalid input; use `safeEncodePartial` for the non-throwing form.
+     */
+    encodePartial(input: UpdateShape<S>): MakeWire<S>;
+    /**
+     * Non-throwing `encode`: validates+encodes the provided keys and returns a Zod-style
+     * `{ success: true; data }` | `{ success: false; error }`. All field errors are
+     * aggregated (with correct paths) into a single `z.ZodError`.
+     */
+    safeEncode(input: CreateShape<S>): SafeResult<MakeWire<S>>;
+    /** Non-throwing `encodePartial` (see `safeEncode`). */
+    safeEncodePartial(input: UpdateShape<S>): SafeResult<MakeWire<S>>;
+    /** Async `encode` (awaits async refinements per leaf); throws the aggregated error. */
+    encodeAsync(input: CreateShape<S>): Promise<MakeWire<S>>;
+    /** Async `encodePartial`; throws the aggregated error. */
+    encodePartialAsync(input: UpdateShape<S>): Promise<MakeWire<S>>;
+    /** Non-throwing async `encode` (see `safeEncode`). */
+    safeEncodeAsync(input: CreateShape<S>): Promise<SafeResult<MakeWire<S>>>;
+    /** Non-throwing async `encodePartial`. */
+    safeEncodePartialAsync(input: UpdateShape<S>): Promise<SafeResult<MakeWire<S>>>;
+    /**
+     * The server/system view: the same table over ALL fields, including `$internal()`
+     * ones the public surface hides. Use it in trusted server code that must read or
+     * write internal fields (e.g. a `passhash`).
+     */
+    get system(): SystemView<Name, S>;
+    private withConfig;
+    schemafull(): TableDef<Name, S>;
+    schemaless(): TableDef<Name, S>;
+    /** `TYPE ANY` — the table may hold both normal records and graph edges. */
+    typeAny(): TableDef<Name, S>;
+    drop(drop?: boolean): TableDef<Name, S>;
+    comment(comment: string): TableDef<Name, S>;
+    /** Set table-level `PERMISSIONS` (folded into the single `DEFINE TABLE` head). */
+    permissions(spec: TablePermissions): TableDef<Name, S>;
+    /** `CHANGEFEED <dur> [INCLUDE ORIGINAL]` — track row changes for `SHOW CHANGES`. */
+    changefeed(expiry: string, opts?: {
+        includeOriginal?: boolean;
+    }): TableDef<Name, S>;
+    /**
+     * Add a composite index: `DEFINE INDEX <name> ON TABLE <table> FIELDS <fields> [UNIQUE]`, or a
+     * materialized row-count index with `{ count: true }` (no fields → `DEFINE INDEX <name> … COUNT`).
+     */
+    index(name: string, fields: (keyof S & string)[], opts?: {
+        unique?: boolean;
+        count?: boolean;
+        comment?: string;
+        /** A HNSW vector index over the field. */
+        hnsw?: HnswOptions;
+        /** A DISKANN vector index over the field. */
+        diskann?: DiskannOptions;
+        /** A full-text search index — needs a `defineAnalyzer` of `analyzer`'s name. */
+        fulltext?: FulltextOptions;
+    }): TableDef<Name, S>;
+    /**
+     * Add a row-change event: `DEFINE EVENT <name> ON TABLE <table> [WHEN <when>] THEN <then>`.
+     * The body sees `$before`/`$after`/`$event`/`$value`; author with `surql\`…\`` or a raw string.
+     */
+    event(name: string, spec: {
+        when?: Expr;
+        then: Expr | Expr[];
+    }): TableDef<Name, S>;
+    extend<E extends Shape>(ext: E): TableDef<Name, Omit<S, keyof E> & E>;
+    pick<K extends keyof S>(...keys: K[]): TableDef<Name, Pick<S, K>>;
+    omit<K extends keyof S>(...keys: K[]): TableDef<Name, Omit<S, K>>;
+    partial(): TableDef<Name, PartialShape<S>>;
+    required(): TableDef<Name, RequiredShape<S>>;
+    /** Derive a `record<name>` link to this table (carrying its id value type). */
+    record(): S extends {
+        id: RecordIdField<Name, infer V>;
+    } ? RecordIdField<Name, V> : RecordIdField<Name>;
+}
+/**
+ * The server/system view of a table (`TableDef.system`): the same data methods typed
+ * over ALL fields, including `$internal()` ones the public `TableDef` hides. Its
+ * `.object` validates/encodes/decodes the full shape, and `encode`/`encodePartial` accept
+ * internal fields. Exposed for trusted server code; never hand it to a browser client.
+ */
+declare class SystemView<Name extends string, S extends Shape> {
+    readonly fields: Record<string, AnyField>;
+    /** Zod object over ALL fields (internal included). */
+    readonly object: z.ZodObject<ZShapeAll<S>>;
+    constructor(fields: Record<string, AnyField>);
+    /** DB wire row -> app object (internal fields kept). */
+    decode(row: unknown): z.output<z.ZodObject<ZShapeAll<S>>>;
+    /** DB wire row -> app object (async; internal fields kept). */
+    decodeAsync(row: unknown): Promise<z.output<z.ZodObject<ZShapeAll<S>>>>;
+    safeDecode(row: unknown): z.ZodSafeParseResult<z.core.$InferObjectOutput<ZShapeAll<S>, {}>>;
+    safeDecodeAsync(row: unknown): Promise<z.ZodSafeParseResult<z.core.$InferObjectOutput<ZShapeAll<S>, {}>>>;
+    /** @deprecated `parse` decodes a DB row (wire -> app). Use {@link SystemView.decode | decode}. */
+    parse(row: unknown): z.output<z.ZodObject<ZShapeAll<S>>>;
+    /** @deprecated Use {@link SystemView.safeDecode | safeDecode}. */
+    safeParse(row: unknown): z.ZodSafeParseResult<z.core.$InferObjectOutput<ZShapeAll<S>, {}>>;
+    /** @deprecated Use {@link SystemView.decodeAsync | decodeAsync}. */
+    parseAsync(row: unknown): Promise<z.output<z.ZodObject<ZShapeAll<S>>>>;
+    /** @deprecated Use {@link SystemView.safeDecodeAsync | safeDecodeAsync}. */
+    safeParseAsync(row: unknown): Promise<z.ZodSafeParseResult<z.core.$InferObjectOutput<ZShapeAll<S>, {}>>>;
+    /**
+     * Build a `CREATE` payload allowed to set internal fields. VALIDATES and THROWS the
+     * aggregated `z.ZodError` on invalid input; use `safeEncode` for the non-throwing form.
+     */
+    encode(input: CreateShapeAll<S>): MakeWireAll<S>;
+    /**
+     * Build an `UPDATE`/`MERGE` payload allowed to set internal fields. VALIDATES and THROWS
+     * on invalid input; use `safeEncodePartial` for the non-throwing form.
+     */
+    encodePartial(input: UpdateShapeAll<S>): MakeWireAll<S>;
+    /** Non-throwing `encode` over ALL fields (see `TableDef.safeEncode`). */
+    safeEncode(input: CreateShapeAll<S>): SafeResult<MakeWireAll<S>>;
+    /** Non-throwing `encodePartial` over ALL fields. */
+    safeEncodePartial(input: UpdateShapeAll<S>): SafeResult<MakeWireAll<S>>;
+    /** Async `encode` over ALL fields; throws the aggregated error. */
+    encodeAsync(input: CreateShapeAll<S>): Promise<MakeWireAll<S>>;
+    /** Async `encodePartial` over ALL fields; throws the aggregated error. */
+    encodePartialAsync(input: UpdateShapeAll<S>): Promise<MakeWireAll<S>>;
+    /** Non-throwing async `encode` over ALL fields. */
+    safeEncodeAsync(input: CreateShapeAll<S>): Promise<SafeResult<MakeWireAll<S>>>;
+    /** Non-throwing async `encodePartial` over ALL fields. */
+    safeEncodePartialAsync(input: UpdateShapeAll<S>): Promise<SafeResult<MakeWireAll<S>>>;
+}
+type IdValue<Id> = Id extends RecordIdField<string, infer V> ? V : Id extends SField<infer Sc, infer _> ? z.output<Sc> extends RecordIdValue ? z.output<Sc> : RecordIdValue : Id extends z.ZodType ? z.output<Id> extends RecordIdValue ? z.output<Id> : RecordIdValue : RecordIdValue;
+type WithSmartId<Name extends string, S extends Shape> = Omit<S, "id"> & {
+    id: RecordIdField<Name, "id" extends keyof S ? IdValue<S["id"]> : RecordIdValue>;
+};
+/**
+ * Define a normal table (schemafull by default). The shape may be a plain object, or a callback
+ * `(self) => ({...})` that receives a `record<thisTable>` field — use it for self-referential
+ * links: `manager: self.optional()`. Type-safe with no repeated table name: `self`'s type comes
+ * from the `name` arg, not from `typeof <theConst>`, so it sidesteps the self-in-its-own-
+ * initializer cycle (TS 7022) that would otherwise widen the whole table to `any`.
+ */
+/**
+ * Reject a shape field carrying the `NoDdl` brand (no SurrealQL mapping) at compile time: the
+ * offending key resolves to an error string, so the shape literal won't type-check. Give such a
+ * field `.$surreal(type, codec)` to make it storable, or drop it.
+ */
+type RejectNoDdl<S extends Shape> = {
+    [K in keyof S]: string extends FlagsOf<S[K]> ? S[K] : NoDdl extends FlagsOf<S[K]> ? "no SurrealQL mapping for this field — give it `.$surreal(type, codec)` or remove it" : S[K];
+};
+type IdOutput<Id> = Id extends RecordIdField<string, infer V> ? V : Id extends SField<infer Sc, infer _> ? z.output<Sc> : Id extends z.ZodType ? z.output<Id> : never;
+/** Compile-time guard: an explicit `id` field must have a valid `RecordIdValue` value type — a
+ *  `s.symbol()`/`s.boolean()` id (not a valid id value) is rejected rather than silently widened. */
+type RejectBadId<S extends Shape> = "id" extends keyof S ? [IdOutput<S["id"]>] extends [RecordIdValue] ? unknown : {
+    id: "the `id` field's value must be a valid RecordId value type (string | number | bigint | uuid | array | object) — e.g. s.string(), s.int(), s.uuid()";
+} : unknown;
+declare function defineTable<Name extends string, S extends Shape>(name: Name, shape: (S & RejectNoDdl<S> & RejectBadId<S>) | ((self: RecordIdField<Name>) => S)): TableDef<Name, WithSmartId<Name, S>>;
+type AnyTable = TableDef<string, any>;
+type TableRef = AnyTable | readonly AnyTable[];
+type NamesOf<T> = T extends TableDef<infer N extends string, infer _> ? N : T extends readonly (infer E)[] ? E extends TableDef<infer N extends string, infer _> ? N : never : never;
+/** A relation's full shape: the edge fields plus the `in`/`out` record endpoints. */
+type RelationShape<Name extends string, S extends Shape, In extends string, Out extends string> = Omit<WithSmartId<Name, S>, "in" | "out"> & {
+    in: RecordIdField<In>;
+    out: RecordIdField<Out>;
+};
+/**
+ * A graph relation (edge table). It's a usable `TableDef` immediately — endpoints are OPTIONAL
+ * (`TYPE RELATION` with no `FROM`/`TO` restricts nothing) — and `.from(X)` / `.to(Y)` narrow the
+ * `in` / `out` record types. Both return a new `RelationDef` (immutable), chainable in any order.
+ */
+declare class RelationDef<Name extends string, S extends Shape, In extends string = string, Out extends string = string> extends TableDef<Name, RelationShape<Name, S, In, Out>> {
+    private readonly edge;
+    private readonly fromNames;
+    private readonly toNames;
+    private readonly isEnforced;
+    constructor(name: Name, edge: S, fromNames?: string[], toNames?: string[], isEnforced?: boolean);
+    /** Restrict the source endpoint(s) (`in`). */
+    from<F extends TableRef>(ref: F): RelationDef<Name, S, NamesOf<F>, Out>;
+    /** Restrict the target endpoint(s) (`out`). */
+    to<T extends TableRef>(ref: T): RelationDef<Name, S, In, NamesOf<T>>;
+    /** Require both endpoints to exist on RELATE (`TYPE RELATION … ENFORCED`). */
+    enforced(): RelationDef<Name, S, In, Out>;
+}
+/**
+ * Define a graph relation (edge table). Endpoints are optional — the result is a usable table
+ * right away; chain `.from(X).to(Y)` to restrict the `in`/`out` records.
+ */
+declare function defineRelation<Name extends string, S extends Shape = {}>(name: Name, fields?: S & RejectNoDdl<S>): RelationDef<Name, S>;
+/**
+ * Define a pre-computed (materialized) VIEW table — `DEFINE TABLE <name> TYPE ANY SCHEMALESS AS
+ * <query>`. Its rows are computed from the SELECT (SurrealDB keeps them in sync as the source tables
+ * change), so a view has NO authored fields/id. Chain `.permissions()` / `.comment()` / `.changefeed()`
+ * as on any table:
+ *
+ * ```ts
+ * export const Adults = defineView("adults", surql`SELECT name, age FROM person WHERE age >= 18`);
+ * ```
+ */
+declare function defineView<Name extends string>(name: Name, query: Expr): TableDef<Name, {}>;
+/**
+ * A standalone `DEFINE EVENT`, declared apart from its table (vs the inline `TableDef.event(…)`).
+ * Export one per event when you want each event as its own named symbol. It compiles to the same
+ * statement as the inline form — `pull` regenerates events inline, so the two are interchangeable.
+ */
+declare class EventDef {
+    /** Owning table name. */
+    readonly table: string;
+    readonly name: string;
+    readonly when: Expr | undefined;
+    readonly then: Expr | Expr[];
+    readonly kind: "event";
+    constructor(
+    /** Owning table name. */
+    table: string, name: string, when: Expr | undefined, then: Expr | Expr[]);
+}
+/**
+ * Declare a row-change event on `table` as a standalone, exportable object:
+ * `export const reverify = defineEvent(User, "reverify", { when, then })`. Pass the `TableDef`
+ * (preferred — no name repetition) or a table name string. See {@link TableDef.event} for the
+ * inline, chainable form.
+ */
+declare function defineEvent(table: TableDef<string, Shape> | string, name: string, spec: {
+    when?: Expr;
+    then: Expr | Expr[];
+}): EventDef;
+interface FunctionConfig {
+    /** Return type (an s schema, inferred to a SurrealQL type — like a field). */
+    returns?: AnyField;
+    /** Function body: a `surql\`…\`` block (or raw string). Required to emit. */
+    body?: Expr;
+    /** `PERMISSIONS FULL` (true) / `NONE` (false) / a `surql` condition. */
+    permissions?: boolean | Expr;
+    comment?: string;
+}
+/**
+ * A custom function — `DEFINE FUNCTION fn::<name>(<args>) [-> <returns>] { <body> }`. Built with a
+ * chainable, immutable API (like {@link TableDef}): `defineFunction(name, args).returns(…).body(…)`.
+ * Args and the return type are s schemas (inferred to SurrealQL types, same as table fields).
+ */
+declare class FunctionDef {
+    readonly name: string;
+    /** Ordered named args, each an s schema. */
+    readonly args: Record<string, AnyField>;
+    readonly config: FunctionConfig;
+    readonly kind: "function";
+    constructor(name: string, 
+    /** Ordered named args, each an s schema. */
+    args: Record<string, AnyField>, config?: FunctionConfig);
+    private withConfig;
+    /** Declare the return type (an s schema). */
+    returns(type: AnyField): FunctionDef;
+    /** The function body — a `surql\`…\`` block (braces optional) or a raw string. */
+    body(body: Expr): FunctionDef;
+    /** `PERMISSIONS`: `FULL` (true, the default), `NONE` (false), or a `surql` condition. */
+    permissions(p: boolean | Expr): FunctionDef;
+    comment(comment: string): FunctionDef;
+}
+/**
+ * Declare a custom function as a standalone, exportable object:
+ * `export const greet = defineFunction("greet", { name: s.string() }).returns(s.string()).body(surql\`…\`)`.
+ * Emitted as `DEFINE FUNCTION fn::greet(...)`. Args are s schemas (inferred to SurrealQL types).
+ */
+declare function defineFunction(name: string, args?: Shape): FunctionDef;
+/** The access type + its type-specific config. `RECORD` (default) / `JWT` / `BEARER`. */
+type AccessKind = {
+    type: "record";
+} | {
+    type: "jwt";
+    alg?: string;
+    key?: string;
+    url?: string;
+} | {
+    type: "bearer";
+    subject: "record" | "user";
+};
+/** Token/session/grant lifetimes, e.g. `{ token: "1h", session: "12h", grant: "30d" }`. */
+interface AccessDuration {
+    grant?: string;
+    token?: string;
+    session?: string;
+}
+interface AccessConfig {
+    /** `ON DATABASE` (default) or `ON NAMESPACE`. */
+    on: "database" | "namespace";
+    kind: AccessKind;
+    /** RECORD-only: SIGNUP/SIGNIN/AUTHENTICATE blocks. */
+    signup?: Expr;
+    signin?: Expr;
+    authenticate?: Expr;
+    duration?: AccessDuration;
+}
+/**
+ * An access definition — `DEFINE ACCESS <name> ON DATABASE TYPE …`. Chainable like {@link TableDef}.
+ * Pick a type with `.record()` (default; SIGNUP/SIGNIN), `.jwt({ alg, key } | { url })` (validate
+ * external tokens), or `.bearer({ for })` (API-key grants). The RECORD bodies are `surql\`…\`` blocks
+ * (braces optional). NOTE: SurrealDB redacts signing keys in introspection, so `pull` can't recover
+ * them — see the CLI (`--access` is opt-in for that reason).
+ */
+declare class AccessDef {
+    readonly name: string;
+    readonly config: AccessConfig;
+    readonly kind: "access";
+    constructor(name: string, config?: AccessConfig);
+    private withConfig;
+    /** `TYPE RECORD` (the default) — end users sign up / sign in directly. */
+    record(): AccessDef;
+    /** `TYPE JWT` — validate tokens from an external issuer: `{ alg, key }` (symmetric/PEM) or `{ url }` (JWKS). */
+    jwt(opts: {
+        alg?: string;
+        key?: string;
+        url?: string;
+    }): AccessDef;
+    /** `TYPE BEARER FOR USER|RECORD` — bearer-token / API-key grants. */
+    bearer(opts: {
+        for: "record" | "user";
+    }): AccessDef;
+    onNamespace(): AccessDef;
+    onDatabase(): AccessDef;
+    /** `SIGNUP { … }` (RECORD) — a `surql\`…\`` block (braces optional) run on sign-up. */
+    signup(body: Expr): AccessDef;
+    /** `SIGNIN { … }` (RECORD) — a `surql\`…\`` block run on sign-in. */
+    signin(body: Expr): AccessDef;
+    /** `AUTHENTICATE { … }` — a `surql\`…\`` block run on each authenticated request. */
+    authenticate(body: Expr): AccessDef;
+    /** Token/session/grant lifetimes (`DURATION FOR TOKEN …, FOR SESSION …, FOR GRANT …`). */
+    duration(d: AccessDuration): AccessDef;
+}
+/**
+ * Declare an access definition: `export const account = defineAccess("account").record()
+ * .signup(surql\`…\`).signin(surql\`…\`).duration({ token: "1h", session: "12h" })`. See {@link AccessDef}
+ * for `.jwt(…)` / `.bearer(…)`.
+ */
+declare function defineAccess(name: string): AccessDef;
+/** A text-search `DEFINE ANALYZER`'s config: an ordered tokenizer + filter pipeline. */
+interface AnalyzerConfig {
+    /** `TOKENIZERS …` — e.g. `["blank", "class", "camel", "punct"]` (at least one). */
+    tokenizers: string[];
+    /** `FILTERS …` — e.g. `["lowercase", "ascii", "snowball(english)", "ngram(1,3)"]`. */
+    filters?: string[];
+}
+/**
+ * A text-search analyzer (`DEFINE ANALYZER`), referenced by a `FULLTEXT` index. Declared standalone:
+ * `export const english = defineAnalyzer("english", { tokenizers: ["blank"], filters: ["lowercase", "snowball(english)"] })`.
+ */
+declare class AnalyzerDef {
+    readonly name: string;
+    readonly config: AnalyzerConfig;
+    readonly kind: "analyzer";
+    constructor(name: string, config: AnalyzerConfig);
+}
+/** Declare a text-search analyzer. See {@link AnalyzerConfig}; reference it from a `fulltext` index. */
+declare function defineAnalyzer(name: string, config: AnalyzerConfig): AnalyzerDef;
+/** A schema object declared apart from a table (collected by the CLI loader and emitted on its own). */
+type StandaloneDef = EventDef | FunctionDef | AccessDef | AnalyzerDef;
+/**
+ * The underlying Zod schema of any s value: a field (`SField`), a table/relation def
+ * (anything carrying an `.object`), or a raw Zod type.
+ */
+type ZodOf<T> = T extends {
+    object: infer O;
+} ? O extends z.ZodType ? O : never : SchemaOf<T>;
+/** The app-facing type (what your code reads). Same as `s.output` / Zod's `infer`. */
+type App<T> = z.output<ZodOf<T>>;
+/** The DB wire type (what crosses the wire). Same as `s.input`. */
+type Wire<T> = z.input<ZodOf<T>>;
+/** Field constructors — the authoring surface. */
+declare const s: {
+    string: () => SField<z.ZodString, never>;
+    number: () => SField<z.ZodNumber, never>;
+    boolean: () => SField<z.ZodBoolean, never>;
+    email: () => SField<z.ZodEmail, never>;
+    url: (params?: Parameters<typeof z.url>[0]) => SField<z.ZodURL, never>;
+    /** Surreal native `uuid`: a `string` app-side, stored as a `Uuid` (no ASSERT — native type). */
+    uuid: () => SField<z.ZodCodec<z.ZodCustom<Uuid, Uuid>, z.ZodUUID>, never>;
+    guid: (params?: Parameters<typeof z.guid>[0]) => SField<z.ZodGUID, never>;
+    nanoid: (params?: Parameters<typeof z.nanoid>[0]) => SField<z.ZodNanoID, never>;
+    cuid: (params?: Parameters<typeof z.cuid>[0]) => SField<z.ZodCUID, never>;
+    cuid2: (params?: Parameters<typeof z.cuid2>[0]) => SField<z.ZodCUID2, never>;
+    ulid: (params?: Parameters<typeof z.ulid>[0]) => SField<z.ZodULID, never>;
+    xid: (params?: Parameters<typeof z.xid>[0]) => SField<z.ZodXID, never>;
+    ksuid: (params?: Parameters<typeof z.ksuid>[0]) => SField<z.ZodKSUID, never>;
+    ipv4: (params?: Parameters<typeof z.ipv4>[0]) => SField<z.ZodIPv4, never>;
+    ipv6: (params?: Parameters<typeof z.ipv6>[0]) => SField<z.ZodIPv6, never>;
+    cidrv4: (params?: Parameters<typeof z.cidrv4>[0]) => SField<z.ZodCIDRv4, never>;
+    cidrv6: (params?: Parameters<typeof z.cidrv6>[0]) => SField<z.ZodCIDRv6, never>;
+    base64: (params?: Parameters<typeof z.base64>[0]) => SField<z.ZodBase64, never>;
+    base64url: (params?: Parameters<typeof z.base64url>[0]) => SField<z.ZodBase64URL, never>;
+    e164: (params?: Parameters<typeof z.e164>[0]) => SField<z.ZodE164, never>;
+    jwt: (params?: Parameters<typeof z.jwt>[0]) => SField<z.ZodJWT, never>;
+    emoji: (params?: Parameters<typeof z.emoji>[0]) => SField<z.ZodEmoji, never>;
+    alpha: () => SField<z.ZodString, never>;
+    alphanum: () => SField<z.ZodString, never>;
+    ascii: () => SField<z.ZodString, never>;
+    numeric: () => SField<z.ZodString, never>;
+    semver: () => SField<z.ZodString, never>;
+    hexadecimal: () => SField<z.ZodString, never>;
+    latitude: () => SField<z.ZodString, never>;
+    longitude: () => SField<z.ZodString, never>;
+    ip: () => SField<z.ZodString, never>;
+    domain: () => SField<z.ZodString, never>;
+    int: (params?: Parameters<typeof z.int>[0]) => SField<z.ZodInt, never>;
+    float: (params?: Parameters<typeof z.float64>[0]) => SField<z.ZodFloat64, never>;
+    int32: (params?: Parameters<typeof z.int32>[0]) => SField<z.ZodInt32, never>;
+    uint32: (params?: Parameters<typeof z.uint32>[0]) => SField<z.ZodUInt32, never>;
+    bigint: (params?: Parameters<typeof z.bigint>[0]) => SField<z.ZodBigInt, never>;
+    datetime: () => SField<z.ZodCodec<z.ZodCustom<DateTime, DateTime>, z.ZodDate>, never>;
+    /** Alias of `datetime` (Surreal stores a `datetime`; there is no plain date). */
+    date: () => SField<z.ZodCodec<z.ZodCustom<DateTime, DateTime>, z.ZodDate>, never>;
+    /** Surreal `duration` (a `Duration` instance). */
+    duration: () => SField<z.ZodType<Duration, Duration, z.core.$ZodTypeInternals<Duration, Duration>>, never>;
+    /** Surreal `decimal` (a `Decimal` instance — arbitrary precision). */
+    decimal: () => SField<z.ZodType<Decimal, Decimal, z.core.$ZodTypeInternals<Decimal, Decimal>>, never>;
+    /** Surreal `bytes` (a `Uint8Array`). */
+    bytes: () => SField<z.ZodCodec<z.ZodUnion<readonly [z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<ArrayBuffer, ArrayBuffer>]>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>, never>;
+    /** Surreal `file` (a `FileRef`). */
+    file: () => SField<z.ZodType<FileRef, FileRef, z.core.$ZodTypeInternals<FileRef, FileRef>>, never>;
+    /** Surreal `geometry` (a `Geometry`), optionally narrowed to a kind. */
+    geometry: (kind?: GeometryKind) => SField<z.ZodType<Geometry, Geometry, z.core.$ZodTypeInternals<Geometry, Geometry>>, never>;
+    /**
+     * A `record<…>` link. Pass a table name, the imported `TableDef`/`RelationDef`, or an array for a
+     * multi-table union — `s.recordId(User)`, `s.recordId([User, Service])` — so a table's name is
+     * only ever written in its own definition. (For a single-table link `User.record()` is preferred:
+     * it also carries the id value type; `User.record().or(Post.record())` composes a union.)
+     *
+     * Called with NO argument — `s.recordId()` — it emits a bare `record` (a link to ANY table), since a
+     * record id's table is optional in SurrealDB.
+     */
+    recordId: <T extends string | AnyTable = string>(table?: T | readonly T[]) => RecordIdField<T extends string ? T : NamesOf<T>>;
+    /**
+     * A nested object whose fields keep their surreal metadata + native types. The returned
+     * schema TYPE carries the original shape `S` via the `~szShape` brand (type-only — runtime
+     * is unchanged) so `CreateValue`/`ShapeOf` can recover the nested fields' create-flags
+     * (e.g. a nested `$default`) and make them create-optional. The brand survives every
+     * `$`-method and Zod wrapper (`.optional()`/`.array()`/`.$default()`), which all reuse
+     * `this.schema`.
+     */
+    object: <S extends Shape>(shape: S) => SField<SZObject<S>>;
+    /** An array of `element`. `opts.max` -> sized `array<T, N>` (N is the MAX length). */
+    array: <F extends AnyField | z.ZodType>(element: F, opts?: {
+        max?: number;
+    }) => SField<z.ZodArray<SchemaOf<F>>>;
+    /** A literal value type. */
+    literal: <const T extends string | number | boolean | bigint>(value: T) => SField<z.ZodLiteral<T>, never>;
+    /** A string enum. */
+    enum: <const T extends readonly [string, ...string[]]>(values: T) => SField<z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>, never>;
+    /** A union of fields/schemas. */
+    union: <const T extends readonly [AnyField | z.ZodType, ...(AnyField | z.ZodType)[]]>(options: T) => SField<z.ZodUnion<ZodsOf<T>>>;
+    /** A fixed-length tuple of fields/schemas. */
+    tuple: <const T extends readonly [AnyField | z.ZodType, ...(AnyField | z.ZodType)[]]>(items: T) => SField<z.ZodTuple<ZodsOf<T>>>;
+    /** An open-keyed record `record<key, value>` -> SurrealQL `object` with a `.*` value field. */
+    record: <K extends z.core.$ZodRecordKey, V extends AnyField | z.ZodType>(key: K, value: V) => SField<z.ZodRecord<K, SchemaOf<V>>>;
+    /** A `Map<key, value>` -> SurrealQL `object` with a `.*` value field. */
+    map: <K extends AnyField | z.ZodType, V extends AnyField | z.ZodType>(key: K, value: V) => SField<z.ZodMap<SchemaOf<K>, SchemaOf<V>>>;
+    /** A `Set<element>` -> SurrealQL `set<element>`. `opts.max` -> sized `set<T, N>` (MAX). */
+    set: <V extends AnyField | z.ZodType>(element: V, opts?: {
+        max?: number;
+    }) => SField<z.ZodSet<SchemaOf<V>>>;
+    /** The intersection of two schemas (object fields are merged in DDL). */
+    intersection: <A extends AnyField | z.ZodType, B extends AnyField | z.ZodType>(a: A, b: B) => SField<z.ZodIntersection<SchemaOf<A>, SchemaOf<B>>>;
+    /** A lazily-resolved schema/field (for recursive types). */
+    lazy: <V extends AnyField | z.ZodType>(getter: () => V) => SField<z.ZodLazy<SchemaOf<V>>>;
+    /** A native TS enum — string or numeric (numeric reverse-mappings are filtered out). */
+    nativeEnum: <const T extends Record<string, string | number>>(entries: T) => SField<z.ZodEnum<T>, never>;
+    /** A discriminated union of object schemas/fields -> DDL `object`. */
+    discriminatedUnion: <Disc extends string, const T extends readonly [AnyField | z.ZodType, ...(AnyField | z.ZodType)[]]>(discriminator: Disc, options: T) => SField<z.ZodDiscriminatedUnion<ZodsOf<T>, Disc>>;
+    /** Wrap a field/schema as optional (constructor form of `.optional()`). */
+    optional: <F extends AnyField | z.ZodType>(field: F) => SField<z.ZodOptional<SchemaOf<F>>, FlagsOf<F>>;
+    /** Wrap a field/schema as nullable (constructor form of `.nullable()`). */
+    nullable: <F extends AnyField | z.ZodType>(field: F) => SField<z.ZodNullable<SchemaOf<F>>, FlagsOf<F>>;
+    /** Optional **and** nullable — Zod's `nullish`. */
+    nullish: <F extends AnyField | z.ZodType>(field: F) => SField<z.ZodNullable<z.ZodOptional<SchemaOf<F>>>, FlagsOf<F>>;
+    /**
+     * Zod-style coercion. Each maps to the **same** SurrealQL type as its non-coerced builder —
+     * coercion only loosens the app/input side; the DB/wire type is unchanged.
+     */
+    coerce: {
+        string: () => SField<z.ZodCoercedString<unknown>, never>;
+        number: () => SField<z.ZodCoercedNumber<unknown>, never>;
+        boolean: () => SField<z.ZodCoercedBoolean<unknown>, never>;
+        bigint: () => SField<z.ZodCoercedBigInt<unknown>, never>;
+        date: () => SField<z.ZodCodec<z.ZodCustom<DateTime, DateTime>, z.ZodCoercedDate<unknown>>, never>;
+    };
+    any: () => SField<z.ZodAny, never>;
+    unknown: () => SField<z.ZodUnknown, never>;
+    null: () => SField<z.ZodNull, never>;
+    symbol: () => SField<z.ZodSymbol, "~no-ddl">;
+    undefined: () => SField<z.ZodUndefined, "~no-ddl">;
+    void: () => SField<z.ZodVoid, "~no-ddl">;
+    never: () => SField<z.ZodNever, "~no-ddl">;
+    nan: () => SField<z.ZodNaN, "~no-ddl">;
+    custom: <T>(check?: (val: unknown) => boolean) => SField<z.ZodCustom<T, T>, "~no-ddl">;
+    instanceof: <T extends Parameters<typeof z.instanceof>[0]>(cls: T) => SField<z.ZodCustom<InstanceType<T>, InstanceType<T>>, "~no-ddl">;
+    promise: <F extends AnyField | z.ZodType>(schema: F) => SField<z.ZodPromise<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>, "~no-ddl">;
+    /** Zod's function factory (not a schema/field — present for drop-in `z.*` parity). */
+    function: (params?: {
+        input: z.core.$ZodFunctionArgs;
+        output: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    } | undefined) => z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+};
+/**
+ * Zod-style inference helpers, exposed on `s` (a type-only namespace merged with the `s`
+ * value — the same trick Zod uses for `z.infer`). They accept fields, table/relation defs,
+ * and raw schemas alike:
+ *   - `s.infer<T>` / `s.output<T>` / `s.TypeOf<T>` -> the decoded **app** type (== `App<T>`)
+ *   - `s.input<T>`                                   -> the **wire/DB** type (== `Wire<T>`)
+ */
+declare namespace s {
+    type infer<T> = z.output<ZodOf<T>>;
+    type output<T> = z.output<ZodOf<T>>;
+    type input<T> = z.input<ZodOf<T>>;
+    type TypeOf<T> = z.output<ZodOf<T>>;
+    /** Any s field — the `z.ZodTypeAny` analogue, for typing generic schemas. */
+    type Field = AnyField;
+}
+/** The typed input for creating a record (DB-filled fields optional). */
+type Create<T> = T extends TableDef<string, infer S> ? CreateShape<S> : never;
+/** The typed input for updating a record (partial; excludes id and readonly fields). */
+type Update<T> = T extends TableDef<string, infer S> ? UpdateShape<S> : never;
+
+declare const surrealDriver: Driver<Surreal, TableDef<string, Shape>, StandaloneDef>;
+
+/** Which level to authenticate at — mirrors `surreal sql --auth-level`. */
+type AuthLevel = "root" | "namespace" | "database";
+/** A SurrealDB connection's params (the surreal-specific half of a `surrealConnection` config). */
+interface SurrealZodConnection {
+    /** Endpoint, e.g. `ws://localhost:8000` or `http://localhost:8000`. */
+    url: string;
+    /** Target namespace. */
+    namespace: string;
+    /** Target database. */
+    database: string;
+    /** Auth username. */
+    username?: string;
+    /** Auth password. */
+    password?: string;
+    /**
+     * Level to sign in at: `root` (default), `namespace`, or `database`. Determines the
+     * signin payload — `namespace`/`database` scope the credentials to that ns/db.
+     */
+    authLevel?: AuthLevel;
+}
+/** An allow/deny list for a single capability — mirrors `@surrealdb/node`. */
+interface CapabilityList {
+    allow?: boolean | string[];
+    deny?: boolean | string[];
+}
+/** Capabilities for the embedded check engine — mirrors `@surrealdb/node`'s `capabilities` option. */
+interface EmbeddedCapabilities {
+    scripting?: boolean;
+    guest_access?: boolean;
+    live_query_notifications?: boolean;
+    functions?: boolean | string[] | CapabilityList;
+    network_targets?: boolean | string[] | CapabilityList;
+    experimental?: boolean | string[] | CapabilityList;
+}
+/**
+ * Run `schemic check`'s replay on an EMBEDDED in-process SurrealDB via the optional `@surrealdb/node`
+ * package (install it yourself — `npm i -D @surrealdb/node`). Options pass through to
+ * `createNodeEngines`; `backend`/`path` choose the storage. No external server, your data untouched.
+ */
+interface SurrealZodCheckEmbedded {
+    /** Storage backend. `memory` (default) is throwaway in-RAM; the others persist to `path`. */
+    backend?: "memory" | "surrealkv" | "surrealkv+versioned" | "rocksdb";
+    /** Filesystem path for the persistent backends (ignored for `memory`). */
+    path?: string;
+    /** Capabilities for the instance. Default: all allowed, so asserts/defaults/functions work. */
+    capabilities?: boolean | EmbeddedCapabilities;
+    /** SurrealDB strict mode. */
+    strict?: boolean;
+    /** Query timeout. */
+    query_timeout?: number;
+    /** Transaction timeout. */
+    transaction_timeout?: number;
+}
+/** `schemic check` options (lives on a SurrealDB connection's config; rides into `params.check`). */
+interface SurrealZodCheck {
+    /**
+     * Engine for the migration replay:
+     *  - `"auto"` (default) — if the `surreal` CLI is on PATH, spin up an ephemeral in-memory instance
+     *    (your EXACT SurrealDB version, no external server, your data untouched); otherwise fall back to
+     *    the `check.db` server.
+     *  - `"binary"` — require the local `surreal` CLI (error if it's missing).
+     *  - `"remote"` — always use the `check.db` server (throwaway scratch databases on it).
+     *  - an embedded object (`{ backend, capabilities, … }`) — run in-process via the optional
+     *    `@surrealdb/node` package. See {@link SurrealZodCheckEmbedded}.
+     */
+    engine?: "auto" | "binary" | "remote" | SurrealZodCheckEmbedded;
+    /** Path to the `surreal` CLI for the `auto`/`binary` engines. Default: `surreal` on PATH. */
+    binary?: string;
+    /**
+     * Connection used for the `remote` engine, merged field-by-field over the connection's own params.
+     * The replay spins up throwaway scratch databases and drops them — it NEVER reads or writes your real
+     * database — but it DOES reach the server. Point this at a local/scratch SurrealDB so `schemic check`
+     * never touches production. Falls back to the connection params for any field you omit.
+     */
+    db?: Partial<SurrealZodConnection>;
+}
+/**
+ * The SurrealDB-specific bag carried in `ResolvedConfig.params`: the connection params plus the optional
+ * `check` replay config. `connect`/`introspect`/`checkReplay` read `config.params as SurrealParams`.
+ */
+interface SurrealParams extends SurrealZodConnection {
+    /** `schemic check` overrides — e.g. a dedicated connection for its migration replay. */
+    check?: SurrealZodCheck;
+}
+
+/**
+ * A SurrealDB connection's config: the dialect-neutral base (`schema`, optional `key`/`migrations`)
+ * plus the SurrealDB-specific connection params and the optional `check` replay config. Read env
+ * yourself in a resolver if you need it — there is no implicit `SURREAL_*` magic. The resolution engine
+ * strips the neutral base; the surreal half (url/namespace/…/check) lands in `ResolvedConfig.params`.
+ */
+interface SurrealConnectionConfig extends ConnectionConfigBase, SurrealZodConnection {
+    /** `schemic check` overrides — e.g. a dedicated scratch connection for the migration replay. */
+    check?: SurrealZodCheck;
+}
+/**
+ * Build a SurrealDB {@link ConnectionEntry} for a config's `connections` map. Three forms:
+ * a single static config, a resolver returning one config, or a resolver returning a keyed
+ * COLLECTION (one connection per entry — `key` is then required and addressable as `<name>:<key>`).
+ */
+declare function surrealConnection(config: SurrealConnectionConfig): ConnectionEntry;
+declare function surrealConnection(resolve: (ctx: ResolveContext) => SurrealConnectionConfig | Promise<SurrealConnectionConfig>): ConnectionEntry;
+declare function surrealConnection(resolve: (ctx: ResolveContext) => (SurrealConnectionConfig & {
+    key: string;
+})[] | Promise<(SurrealConnectionConfig & {
+    key: string;
+})[]>): ConnectionEntry;
+
+/** Inline a BoundQuery's bindings into a literal SurrealQL string for DDL use. Exported so the
+ *  Struct-IR lowering (`fromTableDef`) renders DEFAULT/VALUE/COMPUTED/permission exprs identically. */
+declare function inline(query: BoundQuery): string;
+/**
+ * The bare AND-joined `ASSERT` expression (no `ASSERT ` keyword): inline any `BoundQuery` entries
+ * (custom `surql` asserts), keep strings (computed checks) as-is, dedupe while preserving order,
+ * and AND-join. Each fragment is already a complete boolean expr. Returns "" when there are none.
+ * Exported so the Struct-IR lowering (`fromTableDef`) can populate `StructField.assert` (the bare
+ * expr) while the DDL emitter prepends the `ASSERT ` keyword via {@link renderAsserts}.
+ */
+declare function assertExpr(asserts: SurrealMeta["asserts"]): string;
+/**
+ * The SurrealQL type of a field plus any nested fields it expands into:
+ * object subfields (`path.key`) and array/record element fields (`path.*`).
+ * Exported (with {@link inferField}) so the Struct-IR lowering walks the SAME child tree the
+ * emitter does — so the two can't disagree on type strings or dotted field paths.
+ */
+interface FieldInfo {
+    type: string;
+    flexible: boolean;
+    children: {
+        suffix: string;
+        info: FieldInfo;
+        surreal?: SurrealMeta;
+    }[];
+}
+/** Infer a field's SurrealQL type + nested structure from a Zod schema. Exported so the Struct-IR
+ *  lowering (`fromTableDef`) and the emitter share one source of truth for type strings + paths. */
+declare function inferField(schema: z.ZodType, seen?: Set<z.ZodType>): FieldInfo;
+/** DDL generation options. `exists: "overwrite"` -> OVERWRITE; "ignore" -> IF NOT EXISTS. */
+type DefineOptions = {
+    exists?: "overwrite" | "ignore";
+};
+/**
+ * One generated DDL statement, tied to the schema object it defines. `kind` is the object
+ * kind; `name` identifies it within its scope (a table name, or a field path like
+ * `settings.theme` / `tags.*`, already escaped as it appears in the DDL); `table` is the
+ * owning table for fields. Used by the CLI's migration diff to add/change/remove objects
+ * individually. `emitTable`/`emitField` are the string-joined views of these.
+ */
+interface DefineStatement {
+    kind: "table" | "field" | "index" | "event" | "function" | "access" | "analyzer";
+    name: string;
+    table?: string;
+    ddl: string;
+    /**
+     * Rendered clause fragments keyed by clause name (`TYPE`, `DEFAULT`, `ASSERT`, …) — only on
+     * `field`/`table` statements. Each value is the exact fragment used in the DDL, which is also
+     * the `ALTER … <set>` form, so the migration engine can compute a clause-level delta without
+     * parsing SurrealQL. Absent on older snapshots (those changes fall back to `OVERWRITE`).
+     */
+    clauses?: Record<string, string>;
+}
+/** The SurrealQL type of a field schema (e.g. `string`, `option<int>`, `record<user>`). */
+declare function fieldType(field: SField): string;
+/** Inline a single event clause (`when`/one `then`): a `BoundQuery` is inlined, a string passes
+ *  through. Exported so the Struct-IR lowering renders event/permission exprs identically. */
+declare function eventClause(e: Expr): string;
+/** A `{ … }` block body — wraps a bare statement list in braces; a `surql\`{ … }\`` passes through.
+ *  Exported so the Struct-IR lowering renders function/access blocks to match INFO's `{ … }` form. */
+declare function braceBody(e: Expr): string;
+/** The `DefineStatement` for a standalone def — `defineEvent`/`defineFunction`/`defineAccess`/`defineAnalyzer`. */
+declare function emitDefStatement(def: StandaloneDef, opts?: DefineOptions): DefineStatement;
+/** Structured `DEFINE FIELD` statements for a field (and its nested subfields). */
+declare function emitFieldStatements(name: string, table: string, field: SField, opts?: DefineOptions): DefineStatement[];
+/** `DEFINE FIELD ...` for a field (and any nested object/array/record subfields). */
+declare function emitField(name: string, table: string, field: SField, opts?: DefineOptions): string;
+/** Structured statements for a table: its `DEFINE TABLE` head, then one per (nested) field. */
+declare function emitStatements(t: TableDef<string, Shape>, opts?: DefineOptions): DefineStatement[];
+/** `DEFINE TABLE ...` plus a `DEFINE FIELD` per field. */
+declare function emitTable(t: TableDef<string, Shape>, opts?: DefineOptions): string;
+/** The `REMOVE ...` statement that drops the object a `DefineStatement` defines. */
+declare function removeStatement(s: Pick<DefineStatement, "kind" | "name" | "table">): string;
+/** Inject `OVERWRITE` into a plain `DEFINE <kind> …` statement (idempotent re-definition). */
+declare function overwriteStatement(ddl: string): string;
+/**
+ * Emit an `ALTER FIELD` that turns the `prev` clause set into `next` — re-set changed/added
+ * clauses, `DROP` removed ones (a true delta). Returns `null` (the caller should fall back to
+ * `DEFINE … OVERWRITE`) when the delta touches a clause `ALTER FIELD` can't express (`COMPUTED`),
+ * or when clause data is unavailable (e.g. an older snapshot without `clauses`).
+ */
+declare function alterField(table: string, path: string, prev: Record<string, string> | undefined, next: Record<string, string> | undefined): string | null;
+/**
+ * Emit an `ALTER TABLE` that turns the `prev` clause set into `next`. Returns `null` (caller falls
+ * back to `DEFINE … OVERWRITE`) when the delta touches a clause `ALTER TABLE` can't express
+ * (`TYPE` NORMAL/RELATION/ANY, or the `DROP` flag), or when clause data is unavailable.
+ */
+declare function alterTable(name: string, prev: Record<string, string> | undefined, next: Record<string, string> | undefined): string | null;
+
+/**
+ * @schemic/surrealdb — author SurrealDB schemas with Zod, and the SurrealDB driver.
+ *
+ * Define tables/relations with `s.*` (a drop-in for `z.*`), generate SurrealQL DDL, and map JS <-> DB
+ * across Zod's two channels via codecs (`decode`/`encode`). Importing this package registers the
+ * SurrealDB driver with `@schemic/core` (so the CLI's `getDriver("surrealdb")` resolves).
+ */
+
+/**
+ * Author SurrealQL expressions — the `s.*` authoring API takes these `BoundQuery` values everywhere a
+ * dynamic expression is allowed (`$default`/`$value`/`$computed`/`$assert`, `reference({ onDelete })`,
+ * event `when`/`then`, function bodies, permissions). A thin GENERIC wrapper over the SDK's tag so a
+ * direct SDK query can also carry its RESULT type — one tuple entry per statement:
+ * `db.query(surql<[string[]]>\`RETURN ['a', 'b', 'c']\`)`. Plain `surql\`…\`` (no type arg) is unchanged.
+ * Provided here (typed) so you stay on a single import, decoupled from the SDK version.
+ */
+declare function surql<R extends unknown[] = unknown[]>(strings: TemplateStringsArray, ...values: unknown[]): BoundQuery<R>;
+
+export { AccessDef, type AnalyzerConfig, AnalyzerDef, type App, type AuthLevel, type CapabilityList, type Create, type DefineOptions, type DefineStatement, type DiskannOptions, type EmbeddedCapabilities, EventDef, type Expr, type FieldInfo, type FulltextOptions, FunctionDef, type HnswOptions, RecordIdField, RelationDef, SField, type Shape, type StandaloneDef, type SurrealConnectionConfig, type SurrealMeta, type SurrealParams, type SurrealZodCheck, type SurrealZodCheckEmbedded, type SurrealZodConnection, SystemView, type TableConfig, TableDef, type TableEvent, type TableIndex, type Update, type Wire, alterField, alterTable, assertExpr, braceBody, defineAccess, defineAnalyzer, defineEvent, defineFunction, defineRelation, defineTable, defineView, emitDefStatement, emitField, emitFieldStatements, emitStatements, emitTable, eventClause, fieldType, formatForAssert, inferField, inline, objectFieldsRegistry, overwriteStatement, removeStatement, s, surql, surrealConnection, surrealDriver, surrealTypeRegistry };