@schemic/core 0.1.0-alpha.0

package/src/driver/portable-ir.ts

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

package/src/driver/portable.ts

@@ -0,0 +1,124 @@
+// The PORTABLE TYPE MODEL — the keystone of multi-DB support (see docs/MULTI-DB-SPIKE.md).
+//
+// Today the Struct-IR carries a field's type as a SurrealQL type-expression STRING
+// (`StructField.kind`, e.g. `option<int>`, `array<record<user>, 3>`). That string is a dialect leak:
+// equality and rendering both have to understand SurrealQL grammar. This module defines the
+// dialect-INDEPENDENT replacement — a structured type that every driver translates to/from.
+//
+// STATUS (Milestone 1): defined but NOT yet wired into `StructField`. Milestone 2 replaces
+// `kind: string` with `type: PortableType`, makes `inferField` (src/ddl.ts) produce it, and flips
+// diff equality to a structured deep-compare over the normalized IR. Until then this is the target
+// shape, kept in code so the Surreal driver's `emitType`/`parseType` can be built against it.
+
+/**
+ * The portable scalar set — the common denominator every driver maps to a concrete column type and
+ * back. A driver MAY reject scalars it cannot represent (and authoring can pin a richer DB-native
+ * type via `{ t: "native" }`). Names are lowercase and dialect-neutral.
+ */
+export type ScalarName =
+  | "any"
+  | "bool"
+  | "string"
+  | "int"
+  | "float"
+  | "decimal"
+  | "number" // a numeric whose int/float/decimal-ness is unconstrained
+  | "datetime"
+  | "duration"
+  | "uuid"
+  | "bytes"
+  | "null"; // the unit type of SQL NULL / Surreal `null` (distinct from `option`'s absence)
+
+/**
+ * A dialect-independent field type. Drivers translate this to their own type expression (`emitType`)
+ * and parse their introspection back into it (`parseType`). `option` and `nullable` are ORTHOGONAL
+ * and BOTH equality-relevant — see the note on `nullable` below; never collapse them.
+ */
+export type PortableType =
+  /** A primitive scalar. */
+  | { t: "scalar"; name: ScalarName }
+  /** A literal value type, e.g. the `'active'` in `'active' | 'archived'`. */
+  | { t: "literal"; value: string | number | boolean }
+  /**
+   * The field may be ABSENT / NONE (Surreal `option<T>`; SQL "column omitted / has a DEFAULT").
+   * Orthogonal to `nullable`.
+   */
+  | { t: "option"; inner: PortableType }
+  /**
+   * The field may be NULL (Surreal `T | null`; SQL `NULL` vs `NOT NULL`). Orthogonal to `option`:
+   * `option<T>`, `T | null`, and `option<T | null>` are THREE DISTINCT types. `normalize()` folds
+   * `nullable(option(X))` -> `option(nullable(X))` so `.optional().nullable()` ≡ `.nullish()`.
+   */
+  | { t: "nullable"; inner: PortableType }
+  /** An ordered, possibly length-bounded list. */
+  | { t: "array"; elem: PortableType; size?: number }
+  /** A set (distinct elements), possibly length-bounded. */
+  | { t: "set"; elem: PortableType; size?: number }
+  /** A discriminated/plain union. `normalize()` keeps `members` canonically sorted. */
+  | { t: "union"; members: PortableType[] }
+  /** A nested object/record literal. `flexible` allows undeclared keys (Surreal FLEXIBLE). */
+  | { t: "object"; fields: Record<string, PortableType>; flexible?: boolean }
+  /**
+   * A link to a row in one of `tables` (Surreal `record<a | b>`; SQL foreign key). The id-VALUE type
+   * is intentionally NOT modelled here — the DDL never encodes it; it lives App/Wire-side (TS-only).
+   */
+  | { t: "record"; tables: string[] }
+  /** A geometry type (Surreal-native; PostGIS or unsupported elsewhere). */
+  | { t: "geometry"; kind: GeometryKind }
+  /** The bottom type (no value). */
+  | { t: "never" }
+  /**
+   * An escape hatch for a DB-specific type with no portable meaning (PG `tsvector`, etc.). Carries
+   * the owning driver `db` so a schema authored for one DB can't silently typecheck against another.
+   * `params` carries the type's parameters for parameterized natives — `numeric(p,s)`, `varchar(n)`,
+   * `timestamp(p)` — so a driver round-trips `numeric(10,2)` exactly. Order matters; ignored when empty.
+   */
+  | { t: "native"; db: string; name: string; params?: (string | number)[] };
+
+export type GeometryKind =
+  | "feature"
+  | "point"
+  | "line"
+  | "polygon"
+  | "multipoint"
+  | "multiline"
+  | "multipolygon"
+  | "collection";
+
+// --- Constructors (ergonomic, and a single place to enforce the fold invariants) ----------------
+
+export const scalar = (name: ScalarName): PortableType => ({
+  t: "scalar",
+  name,
+});
+export const literal = (value: string | number | boolean): PortableType => ({
+  t: "literal",
+  value,
+});
+
+/** `option<T>` — but `option<any>` collapses to `any` (any already admits NONE), matching ddl.ts. */
+export const option = (inner: PortableType): PortableType =>
+  inner.t === "scalar" && inner.name === "any" ? inner : { t: "option", inner };
+
+/**
+ * `T | null` — with the fold rule `nullable(option(X))` -> `option(nullable(X))` so
+ * `.optional().nullable()` ≡ `.nullish()`, and `nullable(any)` collapses to `any`.
+ */
+export const nullable = (inner: PortableType): PortableType => {
+  if (inner.t === "scalar" && inner.name === "any") return inner;
+  if (inner.t === "option")
+    return { t: "option", inner: nullable(inner.inner) };
+  return { t: "nullable", inner };
+};
+
+export const array = (elem: PortableType, size?: number): PortableType => ({
+  t: "array",
+  elem,
+  ...(size !== undefined ? { size } : {}),
+});
+export const union = (members: PortableType[]): PortableType =>
+  members.length === 1 ? members[0] : { t: "union", members };
+export const record = (tables: string[]): PortableType => ({
+  t: "record",
+  tables,
+});

package/src/driver/sdk.ts

@@ -0,0 +1,66 @@
+// The NEUTRAL driver SDK — the public surface a driver package (@schemic/surrealdb, @schemic/postgres,
+// …) consumes from `@schemic/core/driver`. It re-exports ONLY dialect-free building blocks: the
+// Driver contract + registry, the portable IR types + constructors, and the config/diff types a
+// driver's ops reference. It deliberately does NOT re-export any concrete driver (that would drag a
+// dialect's whole tree into every consumer); the internal barrel (driver/index.ts) keeps those for
+// core-internal relative imports.
+
+// Types a driver's ops reference (Driver.connect/diff) — re-exported so a driver imports them from
+// the one SDK entry rather than reaching into core's cli/* internals.
+export type { ResolvedConfig } from "../cli-kit/config";
+export type { Diff, DiffItem } from "../cli-kit/diff";
+// Multi-connection: the primitive each driver wraps in its typed `<driver>Connection(...)` factory.
+export {
+  type ConnectionConfigBase,
+  type ConnectionEntry,
+  type ConnectionInput,
+  connectionEntry,
+  type ResolveContext,
+} from "../connection";
+export type {
+  ApplyOptions,
+  Authored,
+  AuthoredDef,
+  ConnectionOverrides,
+  Driver,
+  EmitOptions,
+  MigrationDirection,
+  MigrationRecord,
+  MigrationStore,
+  ShadowCapability,
+  Statement,
+} from "./driver";
+export { driverNames, getDriver, registerDriver } from "./driver";
+export type { GeometryKind, PortableType, ScalarName } from "./portable";
+export {
+  array,
+  literal,
+  nullable,
+  option,
+  record,
+  scalar,
+  union,
+} from "./portable";
+// The field SUBSTRATE every kind composes (the fixed-slot object types are retired — a driver owns
+// its own portable shapes; see ../kind).
+export type { PortableField, PortablePermissions } from "./portable-ir";
+// The KIND REGISTRY (core-v2) — what a driver builds its `registry`/`explode`/`introspectAll` against.
+export {
+  type Definable,
+  emitKinds,
+  introspectKinds,
+  type KindEngine,
+  type KindPlan,
+  KindRegistry,
+  type KindSnapshot,
+  type KindSpec,
+  lowerSchema,
+  type OrderNode,
+  orderObjects,
+  buildKindDiff,
+  planKinds,
+  type PortableObject,
+  type Ref,
+  snapshotKinds,
+  snapshotObjects,
+} from "../kind";

package/src/index.ts

@@ -0,0 +1,145 @@
+/**
+ * @schemic/core — the dialect-neutral engine for Schemic.
+ *
+ * The Driver contract + the portable schema IR + the neutral migration/diff/snapshot/CLI-support
+ * engine. NO database dialect and NO authoring surface (`s.*`/`defineTable`) live here — those ship
+ * in driver packages (`@schemic/surrealdb`, `@schemic/postgres`). `@schemic/cli` and the drivers all
+ * build on the surface re-exported below.
+ */
+
+// --- neutral config ---------------------------------------------------------------------------
+export {
+  loadConfig,
+  loadProject,
+  makeJiti,
+  type ResolvedConfig,
+  resolveConnectionConfig,
+} from "./cli-kit/config";
+// --- neutral diff display ---------------------------------------------------------------------
+export {
+  type Diff,
+  type DiffItem,
+  formatDiff,
+  formatItems,
+  formatPatch,
+  isEmptyDiff,
+  summarizeKinds,
+  tokenDiff,
+} from "./cli-kit/diff";
+// --- neutral filtering ------------------------------------------------------------------------
+export {
+  type Filter,
+  type FilterOpts,
+  filterKinds,
+  inCat,
+  intersectKinds,
+  kindFlags,
+  mergeStored,
+  parseFilter,
+  passesFilter,
+} from "./cli-kit/filter";
+// --- pull plan + magicast merge (neutral codegen support) -------------------------------------
+export {
+  actionLabel,
+  applyPull,
+  type LocalOnly,
+  lineDiff,
+  type MergeOptions,
+  type MergeResult,
+  mergeUnits,
+  type PullFilePlan,
+  type PullPlan,
+  type RenderedUnit,
+  unifiedDiff,
+} from "./cli-kit/merge";
+// --- snapshot + migration metadata ------------------------------------------------------------
+export {
+  checksum,
+  EMPTY_STORED,
+  listMigrations,
+  type Migration,
+  readSnapshot,
+  type StoredSnapshot,
+  slug,
+  timestamp,
+  writeSnapshot,
+} from "./cli-kit/meta";
+// --- pager + style ----------------------------------------------------------------------------
+export { pipeThroughPager, resolvePager } from "./cli-kit/pager";
+// --- jiti schema loader (loads a project's authored schema files agnostically) ----------------
+export {
+  type AnyTable,
+  duplicateTables,
+  existingTables,
+  loadDefs,
+  loadSchemas,
+  scanLocalEntities,
+} from "./cli-kit/schema";
+export { colorEnabled, fail, ok, plural, style } from "./cli-kit/style";
+// --- multi-connection contract (docs/MULTI-CONNECTION.md) -------------------------------------
+export {
+  type ConnectionConfigBase,
+  type ConnectionEntry,
+  type ConnectionInput,
+  connectionEntry,
+  isConnectionEntry,
+  type ResolveContext,
+  type ResolvedConnectionHandle,
+} from "./connection";
+// --- driver contract + registry ---------------------------------------------------------------
+export {
+  type ApplyOptions,
+  type Authored,
+  type AuthoredDef,
+  type ConnectionOverrides,
+  type Driver,
+  driverNames,
+  type EmitOptions,
+  getDriver,
+  type MigrationDirection,
+  type MigrationRecord,
+  type MigrationStore,
+  registerDriver,
+  type ShadowCapability,
+  type Statement,
+} from "./driver/driver";
+// --- portable schema IR -----------------------------------------------------------------------
+export {
+  array,
+  literal,
+  nullable,
+  option,
+  type PortableType,
+  record,
+  type ScalarName,
+  scalar,
+  union,
+} from "./driver/portable";
+// (the Statement-level portable-diff is retired — superseded by the kind registry's
+// planKinds/buildKindDiff in ./kind/plan.ts.)
+export type {
+  PortableField,
+  PortablePermissions,
+} from "./driver/portable-ir";
+// --- kind registry (core-v2) — generic, open object kinds (docs/kind-registry.md) -------------
+export {
+  buildKindDiff,
+  type Definable,
+  emitKinds,
+  introspectKinds,
+  type KindDisplay,
+  type KindEngine,
+  type KindPlan,
+  KindRegistry,
+  type KindSnapshot,
+  type KindSpec,
+  lowerSchema,
+  type OrderNode,
+  orderObjects,
+  type PortableObject,
+  planKinds,
+  type Ref,
+  type ResolvedDisplay,
+  snapshotKinds,
+  snapshotObjects,
+} from "./kind";

package/src/kind/index.ts

@@ -0,0 +1,28 @@
+// The KIND REGISTRY subsystem (core-v2) — the generic, open replacement for the fixed object-kind
+// slots. See ./registry.ts (the primitive + per-driver registry) and ./plan.ts (the kind-blind
+// migration spine + cross-kind dependency ordering). Additive: the fixed-slot `Driver`/`PortableDb`
+// path is untouched while kinds migrate onto this one (docs/kind-registry.md §8).
+
+export {
+  buildKindDiff,
+  emitKinds,
+  introspectKinds,
+  type KindPlan,
+  type KindSnapshot,
+  lowerSchema,
+  type OrderNode,
+  orderObjects,
+  planKinds,
+  snapshotKinds,
+  snapshotObjects,
+} from "./plan";
+export {
+  type Definable,
+  type KindDisplay,
+  type KindEngine,
+  KindRegistry,
+  type KindSpec,
+  type PortableObject,
+  type Ref,
+  type ResolvedDisplay,
+} from "./registry";