@schemic/surrealdb 0.1.0-alpha.0

package/src/kinds/explode.ts

@@ -0,0 +1,201 @@
+// The driver-side EXPLODE (docs/kind-registry-contract.md §7, sanctioned by core-dev): SurrealDB
+// authors index/event/field-index INLINE on the table, so a single `TableDef` fans out into one TABLE
+// object + N INDEX + M EVENT objects (and the db-level FUNCTION/ACCESS objects ride alongside). We
+// flatten the whole schema into per-kind portable objects BEFORE lowering, so `KindEngine.lower` stays
+// a clean 1:1 and the contract needs no "explode hook". This is what `Driver.lower` will wrap around
+// `lowerSchema` at the eventual wholesale flip.
+//
+// It reuses the EXISTING canonical pipeline — `schemaStruct` (TableDef -> normalized Struct IR, with
+// standalone events attached + functions/accesses resolved) then `structuredSnapshot` (Struct ->
+// canonical `DEFINE` statements keyed kind:table:name) — so every emitted DDL string is byte-identical
+// to the fixed-slot `surrealDriver.diff` path.
+//
+// CROSS-KIND DEPS: an object that calls `fn::name` must emit AFTER that function (the function-before-
+// table case the ordinal alone gets wrong). We scan each object's rendered DDL for `fn::` references and
+// attach `deps -> {kind:"function", name}` — on a table (field VALUE/ASSERT/DEFAULT/PERMISSIONS + table
+// PERMISSIONS), an event (WHEN/THEN), an access (SIGNUP/SIGNIN/AUTHENTICATE), and a function (its body
+// calling another fn::). Edges to functions outside the diff are ignored by the spine, so over-reporting
+// is harmless. (SEARCH index -> analyzer edges land when the analyzer kind is registered.)
+
+import type { AnyTable, AuthoredDef, Ref } from "@schemic/core";
+import type { Surreal } from "surrealdb";
+import { schemaStruct } from "../cli/lower";
+import { normalizeDb } from "../cli/struct";
+import type {
+  DbStructured,
+  StructAccess,
+  StructAnalyzer,
+  StructFunction,
+  StructTable,
+} from "../cli/structure";
+import { introspectStructured, structuredSnapshot } from "../cli/structure";
+import type { DefineStatement } from "../ddl";
+import type { Shape, StandaloneDef, TableDef } from "../pure";
+import type { SurrealPortable } from "./portable";
+
+/** Match a `fn::name` reference (incl. namespaced `fn::a::b`), capturing the bare function name. */
+const FN_REF = /fn::([A-Za-z0-9_]+(?:::[A-Za-z0-9_]+)*)/g;
+
+/**
+ * The cross-kind dependency edges for one object: a `base` set (its table, for index/event) plus the
+ * `fn::` functions referenced in its DDL — deduped, and excluding `self` (a function's body referencing
+ * itself is recursion, not an ordering edge).
+ */
+function depsOf(ddls: string[], base: Ref[] = [], self?: string): Ref[] {
+  const seen = new Set(base.map((r) => `${r.kind}:${r.name}`));
+  const out: Ref[] = [...base];
+  for (const ddl of ddls) {
+    for (const m of ddl.matchAll(FN_REF)) {
+      const name = m[1];
+      if (name === self) continue;
+      const key = `function:${name}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ kind: "function", name });
+    }
+  }
+  return out;
+}
+
+/**
+ * The shared core: a NORMALIZED Struct IR -> per-kind portable objects. Renders each object's canonical
+ * `DEFINE` statement(s) via `structuredSnapshot`, then partitions: a {@link PTable} per table (head +
+ * nested fields), a {@link PIndex} per index, a {@link PEvent} per event, and the db-level
+ * {@link PFunction}/{@link PAccess} objects — each carrying its `fn::`/endpoint dependency edges. A
+ * table also carries its normalized {@link StructTable} and the opaque kinds their `native` struct, so
+ * `renderSchema` reconstructs `DbStructured` without re-parsing DDL. Both entry points
+ * ({@link explodeSchema} from authoring, {@link introspectAll} from a live DB) feed their normalized
+ * Struct here, so they produce byte-identical portable objects.
+ */
+export function fromStructured(db: DbStructured): SurrealPortable[] {
+  const stmts = Object.values(structuredSnapshot(db).statements);
+  const of = (kind: DefineStatement["kind"]) =>
+    stmts.filter((s) => s.kind === kind);
+
+  const out: SurrealPortable[] = [];
+
+  // Tables: head + nested fields. deps = RELATION in/out endpoints + fn:: from the head/fields.
+  const headByTable = new Map(of("table").map((s) => [s.name, s]));
+  const fieldsByTable = new Map<string, DefineStatement[]>();
+  for (const s of of("field")) {
+    const arr = fieldsByTable.get(s.table ?? "") ?? [];
+    arr.push(s);
+    fieldsByTable.set(s.table ?? "", arr);
+  }
+  for (const st of db.tables) {
+    const head = headByTable.get(st.name);
+    if (!head) continue; // a table always has a head; defensive only
+    const fields = fieldsByTable.get(st.name) ?? [];
+    const endpoints: Ref[] = [];
+    for (const t of st.kind.in ?? [])
+      endpoints.push({ kind: "table", name: t });
+    for (const t of st.kind.out ?? [])
+      endpoints.push({ kind: "table", name: t });
+    const deps = depsOf([head.ddl, ...fields.map((f) => f.ddl)], endpoints);
+    out.push({ kind: "table", name: st.name, head, fields, deps, struct: st });
+  }
+
+  for (const s of of("index")) {
+    // A FULLTEXT index depends on its analyzer (so the analyzer emits first); all indexes -> their table.
+    const deps: Ref[] = [{ kind: "table", name: s.table ?? "" }];
+    const ft = /FULLTEXT ANALYZER (\S+)/.exec(s.ddl);
+    if (ft) deps.push({ kind: "analyzer", name: ft[1] });
+    out.push({
+      kind: "index",
+      name: s.name,
+      table: s.table ?? "",
+      stmt: s,
+      deps,
+    });
+  }
+  for (const s of of("event"))
+    out.push({
+      kind: "event",
+      name: s.name,
+      table: s.table ?? "",
+      stmt: s,
+      deps: depsOf([s.ddl], [{ kind: "table", name: s.table ?? "" }]),
+    });
+  // The opaque kinds carry their structured `native` (matched by name) for renderSchema.
+  const fnByName = new Map(db.functions.map((f) => [f.name, f]));
+  const accByName = new Map(db.accesses.map((a) => [a.name, a]));
+  for (const s of of("function")) {
+    const native = fnByName.get(s.name);
+    if (native)
+      out.push({
+        kind: "function",
+        name: s.name,
+        stmt: s,
+        deps: depsOf([s.ddl], [], s.name),
+        native,
+      });
+  }
+  for (const s of of("access")) {
+    const native = accByName.get(s.name);
+    if (native)
+      out.push({
+        kind: "access",
+        name: s.name,
+        stmt: s,
+        deps: depsOf([s.ddl]),
+        native,
+      });
+  }
+  const anByName = new Map(db.analyzers.map((a) => [a.name, a]));
+  for (const s of of("analyzer")) {
+    const native = anByName.get(s.name);
+    if (native)
+      out.push({ kind: "analyzer", name: s.name, stmt: s, deps: [], native });
+  }
+
+  return out;
+}
+
+/** Reassemble `DbStructured` from per-kind portable objects — the inverse of {@link fromStructured},
+ *  for `renderSchema` TS codegen. Tables carry their full normalized struct; the opaque kinds their
+ *  `native`. (No DDL re-parsing: the structured data rides on the objects per flip-plan §6b.) */
+export function toStructured(objects: SurrealPortable[]): DbStructured {
+  const tables: StructTable[] = [];
+  const functions: StructFunction[] = [];
+  const accesses: StructAccess[] = [];
+  const analyzers: StructAnalyzer[] = [];
+  for (const o of objects) {
+    if (o.kind === "table") tables.push(o.struct);
+    else if (o.kind === "function") functions.push(o.native);
+    else if (o.kind === "access") accesses.push(o.native);
+    else if (o.kind === "analyzer") analyzers.push(o.native);
+  }
+  return { tables, functions, accesses, analyzers };
+}
+
+/**
+ * Authoring -> per-kind portable objects (what `Driver.lower` wraps around `lowerSchema`). Params mirror
+ * `buildSnapshot`'s public bound (`AnyTable`/`AuthoredDef`) and cast to the src `TableDef` the canonical
+ * pipeline reads. `schemaStruct` already normalizes (events attached, functions/accesses resolved).
+ */
+export function explodeSchema(
+  tables: AnyTable[],
+  defs: AuthoredDef[] = [],
+): SurrealPortable[] {
+  return fromStructured(
+    schemaStruct(
+      tables as unknown as TableDef<string, Shape>[],
+      defs as unknown as StandaloneDef[],
+    ),
+  );
+}
+
+/**
+ * The reverse path (flip-plan §4): a live connection -> per-kind portable objects, via ONE
+ * `INFO … STRUCTURE` read (`introspectStructured`) fanned across every kind. Normalized the same way as
+ * {@link decompose}/{@link explodeSchema} (`normalizeDb` → canonical `structuredSnapshot`), so an
+ * introspected schema canonicalizes IDENTICALLY to a lowered one — no introspect phantom-diffs. This is
+ * the COMPLETE introspection the flip needs: it returns objects for every registered kind that round-
+ * trips (table/index/event/function/access). `exclude` drops tables by name (e.g. the migrations table).
+ */
+export async function introspectAll(
+  conn: Surreal,
+  exclude?: Set<string>,
+): Promise<SurrealPortable[]> {
+  return fromStructured(normalizeDb(await introspectStructured(conn, exclude)));
+}

package/src/kinds/portable.ts

@@ -0,0 +1,116 @@
+// The PORTABLE objects for the SurrealDB kind registry (core-v2, docs/kind-registry-contract.md
+// slice 2). Each is a {@link PortableObject} (tagged `kind`/`name` for the generic spine) wrapping
+// the canonical {@link DefineStatement}(s) the legacy diff engine already produces — so a kind's
+// `emit`/`overwrite` reuse the SAME renderer + clause maps the fixed-slot `surrealDriver.diff` uses,
+// and parity is byte-exact by construction (see ./registry.ts).
+//
+// SurrealDB authors index/event INLINE on the table, but the contract models them as their OWN kinds
+// (deps/owner -> table). The driver-side EXPLODE (./explode.ts) fans a `TableDef` into one table object
+// + N index + M event objects BEFORE lowering, so `KindEngine.lower` stays a clean 1:1. Fields stay
+// NESTED in the table object (a table HAS fields — they are the shared substrate, not a kind), and the
+// table kind owns field-level diff inside its `overwrite`.
+
+import type { PortableObject, Ref } from "@schemic/core";
+import type {
+  StructAccess,
+  StructAnalyzer,
+  StructFunction,
+  StructTable,
+} from "../cli/structure";
+import type { DefineStatement } from "../ddl";
+
+/**
+ * A table's portable form: its `DEFINE TABLE` head + its `DEFINE FIELD` statements (nested). Indexes
+ * and events are EXCLUDED — they are their own kinds. `deps` carries the table's cross-kind edges
+ * (a RELATION's in/out endpoint tables), computed at explode time.
+ */
+export interface PTable extends PortableObject {
+  readonly kind: "table";
+  readonly name: string;
+  /** The `DEFINE TABLE` head statement (carries the table-level clause map for `ALTER TABLE`). */
+  readonly head: DefineStatement;
+  /** The nested `DEFINE FIELD` statements (each carries its clause map for `ALTER FIELD`). */
+  readonly fields: DefineStatement[];
+  /** Objects this table must be emitted AFTER — a RELATION's in/out tables. */
+  readonly deps: Ref[];
+  /**
+   * The NORMALIZED structured table (fields/indexes/events nested) — carried so `renderSchema` can
+   * reconstruct `DbStructured` for TS codegen WITHOUT re-parsing rendered DDL (the robust read of
+   * flip-plan §6b's "derive structured from your portable objects"; emit/diff still use head/fields).
+   */
+  readonly struct: StructTable;
+}
+
+/** An index's portable form: the `DEFINE INDEX` statement + its owning table. `deps` carries the table
+ *  and, for a FULLTEXT index, its analyzer (so the analyzer emits BEFORE the index). */
+export interface PIndex extends PortableObject {
+  readonly kind: "index";
+  readonly name: string;
+  readonly table: string;
+  readonly stmt: DefineStatement;
+  readonly deps: Ref[];
+}
+
+/** An event's portable form: the `DEFINE EVENT` statement + its owning table. `deps` carries any
+ *  `fn::` functions the WHEN/THEN call (so a called function emits BEFORE the event). */
+export interface PEvent extends PortableObject {
+  readonly kind: "event";
+  readonly name: string;
+  readonly table: string;
+  readonly stmt: DefineStatement;
+  readonly deps: Ref[];
+}
+
+/**
+ * A db-level function's portable form — OPAQUE (a neutral identity + its canonical `DEFINE FUNCTION`
+ * statement, round-tripped verbatim). `deps` carries any OTHER `fn::` functions its body calls.
+ */
+export interface PFunction extends PortableObject {
+  readonly kind: "function";
+  readonly name: string;
+  readonly stmt: DefineStatement;
+  readonly deps: Ref[];
+  /** The structured function (the opaque kind's `native` payload) — for `renderSchema` TS codegen. */
+  readonly native: StructFunction;
+}
+
+/**
+ * A db-level access/auth definition's portable form — OPAQUE. `deps` carries any `fn::` functions its
+ * SIGNUP/SIGNIN/AUTHENTICATE call (so those functions emit BEFORE the access).
+ */
+export interface PAccess extends PortableObject {
+  readonly kind: "access";
+  readonly name: string;
+  readonly stmt: DefineStatement;
+  readonly deps: Ref[];
+  /** The structured access (the opaque kind's `native` payload) — for `renderSchema` TS codegen. */
+  readonly native: StructAccess;
+}
+
+/**
+ * A db-level text-search analyzer's portable form — OPAQUE. A FULLTEXT index `deps` on it.
+ */
+export interface PAnalyzer extends PortableObject {
+  readonly kind: "analyzer";
+  readonly name: string;
+  readonly stmt: DefineStatement;
+  readonly deps: Ref[];
+  /** The structured analyzer (the opaque kind's `native` payload) — for `renderSchema` TS codegen. */
+  readonly native: StructAnalyzer;
+}
+
+/** Every portable object a SurrealDB schema lowers to. */
+export type SurrealPortable =
+  | PTable
+  | PIndex
+  | PEvent
+  | PFunction
+  | PAccess
+  | PAnalyzer;
+
+/**
+ * The authoring-side definables the explode produces. They ALREADY carry the normalized, canonical
+ * `DefineStatement`(s) (the explode runs `schemaStruct` + `structuredSnapshot` first), so each kind's
+ * `lower` is the identity — exactly the pattern core's `kind-registry.test.ts` uses.
+ */
+export type SurrealDefinable = SurrealPortable;

package/src/kinds/registry.ts

@@ -0,0 +1,177 @@
+// The SurrealDB KIND REGISTRY (core-v2, docs/kind-registry-contract.md): the per-driver registry +
+// the `table`/`index`/`event`/`function`/`access` engines. Core orchestrates generically over this registry
+// (lower -> diff -> order -> emit); each engine delegates to the EXISTING fixed-slot primitives, so the
+// generic path is byte-exact with `surrealDriver.diff`:
+//   - table.overwrite  -> `diffSnapshots` (the whole field + table-head ALTER engine, scoped to one table)
+//   - index            -> recreate (the spine's remove+emit default == legacy `changeUp` for an index)
+//   - event.overwrite  -> `overwriteStatement` (DEFINE EVENT OVERWRITE == legacy `changeUp` for an event)
+//
+// Registration ORDER is each kind's ordinal (the tie-break among independent objects): table (0) before
+// index (1) before event (2). index/event point `deps`+`owner` at their table, so the graph emits them
+// AFTER and clusters them next to it. Fields are NESTED in the table object (substrate, not a kind).
+//
+// NOTE (slice 2): the legacy `Driver.lower/emit/diff` path is UNTOUCHED and still production. This
+// registry is built + parity-tested ALONGSIDE it; the wholesale flip (routing `Driver` + the `s.*`
+// authoring `build` through here) lands once access/function/natives are migrated too.
+
+import {
+  type AnyTable,
+  type AuthoredDef,
+  type DiffItem,
+  type KindEngine,
+  KindRegistry,
+  lowerSchema,
+  type PortableObject,
+  type Ref,
+} from "@schemic/core";
+import { EMPTY_SNAPSHOT, type Snapshot } from "../cli/structure";
+import { diffSnapshots } from "../cli/surreal-diff";
+import type { DefineStatement } from "../ddl";
+import { overwriteStatement, removeStatement } from "../ddl";
+import { explodeSchema } from "./explode";
+import type {
+  PAccess,
+  PAnalyzer,
+  PEvent,
+  PFunction,
+  PIndex,
+  PTable,
+} from "./portable";
+
+/** Statement key matching the legacy engine's `keyOf` (`kind:table:name`). */
+const keyOf = (s: Pick<DefineStatement, "kind" | "name" | "table">) =>
+  `${s.kind}:${s.table ?? ""}:${s.name}`;
+
+/** A one-table {@link Snapshot} (head + its fields) for the legacy `diffSnapshots` to diff. */
+function snapOf(head: DefineStatement, fields: DefineStatement[]): Snapshot {
+  const statements: Snapshot["statements"] = {};
+  for (const s of [head, ...fields]) statements[keyOf(s)] = s;
+  return { version: 1, statements };
+}
+
+// --- table: structured, field-level diff inside `overwrite` -------------------------------------
+
+const tableEngine: KindEngine<PTable, PTable> = {
+  lower: (t) => t,
+  emit: (t) => [t.head.ddl, ...t.fields.map((f) => f.ddl)],
+  // REMOVE TABLE covers its fields (no orphan REMOVE FIELDs) — matches the legacy drop.
+  remove: (t) => [removeStatement(t.head)],
+  // The field + table-head delta IS the legacy engine: build both sides as one-table snapshots and
+  // take the up. The spine calls `overwrite(next, prev)` for the down, so this stays symmetric.
+  overwrite: (prev, next) =>
+    diffSnapshots(
+      snapOf(prev.head, prev.fields),
+      snapOf(next.head, next.fields),
+    ).up,
+  deps: (t) => t.deps,
+  // PER-FIELD display (Manuel's call): the table's diff items are its head + per-field statements
+  // (each carrying its `table` so the display groups under it) — exactly `diffSnapshots().items`.
+  // `full` uses displayItems(undefined, next) -> the per-field add items.
+  displayItems: (prev, next): DiffItem[] =>
+    diffSnapshots(
+      prev ? snapOf(prev.head, prev.fields) : EMPTY_SNAPSHOT,
+      next ? snapOf(next.head, next.fields) : EMPTY_SNAPSHOT,
+    ).items ?? [],
+};
+
+// --- index: own kind, owned by its table, recreated on change -----------------------------------
+
+const indexEngine: KindEngine<PIndex, PIndex> = {
+  lower: (i) => i,
+  emit: (i) => [i.stmt.ddl],
+  remove: (i) => [removeStatement(i.stmt)],
+  // No `overwrite` -> the spine recreates (remove + emit): `REMOVE INDEX … ; DEFINE INDEX …`,
+  // exactly the legacy `changeUp` for an index (ALTER INDEX can't change fields/kind).
+  // -> its table (owner) + a FULLTEXT index's analyzer (so the analyzer emits first).
+  deps: (i) => i.deps,
+  owner: (i) => ({ kind: "table", name: i.table }),
+};
+
+// --- event: own kind, owned by its table, OVERWRITE on change -----------------------------------
+
+const eventEngine: KindEngine<PEvent, PEvent> = {
+  lower: (e) => e,
+  emit: (e) => [e.stmt.ddl],
+  remove: (e) => [removeStatement(e.stmt)],
+  // DEFINE EVENT OVERWRITE in place — matches the legacy `changeUp`/`changeDown` for an event.
+  overwrite: (_prev, next) => [overwriteStatement(next.stmt.ddl)],
+  // -> its table (owner) + any `fn::` the WHEN/THEN call (so the function emits first).
+  deps: (e) => e.deps,
+  owner: (e) => ({ kind: "table", name: e.table }),
+};
+
+// --- function / access: db-level OPAQUE kinds, OVERWRITE on change -------------------------------
+
+const functionEngine: KindEngine<PFunction, PFunction> = {
+  lower: (f) => f,
+  emit: (f) => [f.stmt.ddl],
+  remove: (f) => [removeStatement(f.stmt)],
+  // DEFINE FUNCTION OVERWRITE in place — matches the legacy `changeUp`/`changeDown` for a function.
+  overwrite: (_prev, next) => [overwriteStatement(next.stmt.ddl)],
+  // Other `fn::` its body calls (db-level, no owner cluster).
+  deps: (f) => f.deps,
+};
+
+const accessEngine: KindEngine<PAccess, PAccess> = {
+  lower: (a) => a,
+  emit: (a) => [a.stmt.ddl],
+  remove: (a) => [removeStatement(a.stmt)],
+  // DEFINE ACCESS OVERWRITE in place — matches the legacy `changeUp`/`changeDown` for an access.
+  overwrite: (_prev, next) => [overwriteStatement(next.stmt.ddl)],
+  // Any `fn::` the SIGNUP/SIGNIN/AUTHENTICATE call (db-level, no owner cluster).
+  deps: (a) => a.deps,
+};
+
+// --- analyzer: db-level OPAQUE kind (a FULLTEXT index depends on it) -----------------------------
+
+const analyzerEngine: KindEngine<PAnalyzer, PAnalyzer> = {
+  lower: (a) => a,
+  emit: (a) => [a.stmt.ddl],
+  remove: (a) => [removeStatement(a.stmt)],
+  // DEFINE ANALYZER OVERWRITE in place.
+  overwrite: (_prev, next) => [overwriteStatement(next.stmt.ddl)],
+  deps: (a) => a.deps,
+};
+
+/**
+ * The SurrealDB driver's kind registry. Registration order == kind ordinal (the tie-break among
+ * objects with no dependency relation): table < index < event < function < access. Correctness is the
+ * dependency GRAPH (deps), not the ordinal — a `fn::`-called function still emits before its caller via
+ * the function `deps` regardless of its ordinal.
+ */
+export const surrealKinds = new KindRegistry();
+
+// `build` is the kind's authoring entry. At the wholesale flip these route the `s.*` authoring through
+// the registry; for the facade-test phase the explode produces portable objects directly, so the builds
+// are the identity (the registry only needs the engine behavior registered here).
+surrealKinds.define({ name: "table", build: (t: PTable) => t, ...tableEngine });
+surrealKinds.define({ name: "index", build: (i: PIndex) => i, ...indexEngine });
+surrealKinds.define({ name: "event", build: (e: PEvent) => e, ...eventEngine });
+surrealKinds.define({
+  name: "function",
+  build: (f: PFunction) => f,
+  ...functionEngine,
+});
+surrealKinds.define({
+  name: "access",
+  build: (a: PAccess) => a,
+  // The generic pluralizer would make "access" -> "Accesses"/"accesses"; SurrealQL's noun is
+  // invariant ("Access") and the dir is `access/`, so pin both.
+  display: { plural: "Access", folder: "access" },
+  ...accessEngine,
+});
+surrealKinds.define({
+  name: "analyzer",
+  build: (a: PAnalyzer) => a,
+  ...analyzerEngine,
+});
+
+/** Author -> portable via the registry: explode tables/defs into per-kind objects, then lower each. */
+export function lowerAll(
+  tables: AnyTable[],
+  defs: AuthoredDef[] = [],
+): PortableObject[] {
+  return lowerSchema(surrealKinds, explodeSchema(tables, defs));
+}
+
+export type { Ref };