@better-schemic/core 0.1.0-alpha.1

package/lib/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testing.ts"],"sourcesContent":["// A shared DRIVER CONFORMANCE suite — the runtime contract a `@better-schemic/<driver>` must satisfy, asserted\n// with `bun:test`. Each driver runs it against its own authoring surface:\n//\n//   import { describeDriverConformance } from \"@better-schemic/core/testing\";\n//   import { defineTable, s, surrealDriver } from \"@better-schemic/surrealdb\";\n//   describeDriverConformance({ name: \"surrealdb\", s, driver: surrealDriver, defineEntity: defineTable });\n//\n// WHY a test, not a type: the zod drop-in builders (`s.string()` = `new <D>Field(z.string())`) are\n// mechanically identical across drivers, but TypeScript has NO higher-kinded types, so a generic core\n// factory can't preserve each driver's field type (it collapses to the base, dropping `$`-methods).\n// Each driver therefore hand-authors its drop-ins, and \"`s` is a Zod SUPERSET\" is enforceable only at\n// runtime. This suite is that enforcement.\n//\n// It DUCK-TYPES fields (a field is \"something with a `.schema` that is a Zod type\") rather than using\n// `instanceof SFieldBase` — a driver may extend its own copy of the base, so identity checks are unsafe.\n\nimport { describe, expect, test } from \"bun:test\";\nimport { readdirSync, readFileSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport type * as z from \"zod\";\nimport { type Driver, driverNames, getDriver } from \"./driver/driver\";\nimport { emitKinds, type KindRegistry, lowerSchema } from \"./kind\";\n\n/**\n * The driver's authoring namespace (`s`) — a bag of field builders, some NESTED (e.g.\n * `s.iso.{date,time,datetime,duration}`). Intentionally loose: the suite duck-types fields and\n * enforces the real contract at RUNTIME, not via this type (see the header note), so a precise\n * \"function-or-nested-namespace\" shape would only fight the internal `s.<key>()` calls for no gain.\n */\n// biome-ignore lint/suspicious/noExplicitAny: a driver's `s` is dialect-specific + may nest; runtime-duck-typed.\ntype Authoring = Record<string, any>;\n\nexport interface DriverConformanceOptions {\n  /** The driver's registry name (e.g. `\"surrealdb\"`). */\n  name: string;\n  /** The driver's authoring namespace — the `s` each package exports. */\n  s: Authoring;\n  /** The driver under test (already registered by importing its package). */\n  driver: Driver<unknown>;\n  /**\n   * Authors the driver's primary fielded definable — a table, collection, node-type, … — from a name\n   * and a field shape. Used to lower a probe object through the pipeline. Drivers pass their own\n   * `define*` for this (e.g. `defineEntity: defineTable`); the suite stays shape-agnostic.\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: dialect-specific definable/shape types.\n  defineEntity: (name: string, shape: Record<string, any>) => any;\n}\n\n/**\n * The canonical zod DROP-IN set every driver's `s` MUST expose — the structural Zod builders that make\n * a `@better-schemic/<driver>` a drop-in for `z`. Each maps to the DB's natural representation (a driver may\n * also offer richer native aliases, e.g. `text`/`varchar` alongside `string`). `object`/`array` nest a\n * `literal` (present everywhere) so a missing `string` doesn't cascade into their tests.\n */\nconst DROP_INS: { key: string; build: (s: Authoring) => unknown }[] = [\n  { key: \"string\", build: (s) => s.string() },\n  { key: \"number\", build: (s) => s.number() },\n  { key: \"boolean\", build: (s) => s.boolean() },\n  { key: \"date\", build: (s) => s.date() },\n  { key: \"literal\", build: (s) => s.literal(\"a\") },\n  { key: \"enum\", build: (s) => s.enum([\"a\", \"b\"]) },\n  { key: \"object\", build: (s) => s.object({ inner: s.literal(\"a\") }) },\n  { key: \"array\", build: (s) => s.array(s.literal(\"a\")) },\n];\n\n/** Value pairs that prove a scalar drop-in really carries the right Zod schema (unambiguous scalars only). */\nconst SCALAR_CHECKS: { key: string; valid: unknown; invalid: unknown }[] = [\n  { key: \"string\", valid: \"hello\", invalid: 123 },\n  { key: \"number\", valid: 123, invalid: \"hello\" },\n  { key: \"boolean\", valid: true, invalid: \"hello\" },\n];\n\n/** Duck-typed: a field exposes a Zod `.schema`; a raw Zod type IS the schema. Throws if neither. */\nfunction toSchema(v: unknown): z.ZodType {\n  const field = v as { schema?: unknown } | null;\n  if (field && isZod(field.schema)) return field.schema as z.ZodType;\n  if (isZod(v)) return v as z.ZodType;\n  throw new Error(\"expected a field (with a `.schema` Zod type) or a Zod type\");\n}\n\nfunction isZod(v: unknown): boolean {\n  return !!v && typeof (v as { safeParse?: unknown }).safeParse === \"function\";\n}\n\n/** Is `v` a driver field (has a `.schema` that is a Zod type)? */\nfunction isField(v: unknown): boolean {\n  return isZod((v as { schema?: unknown } | null)?.schema);\n}\n\n/**\n * Assert a `@better-schemic/<driver>` conforms to the Better-schemic driver contract: the Driver is registered with\n * the IR pipeline + execution ops, and its `s` is a Zod-drop-in SUPERSET (the canonical drop-in set is\n * present, carries the right schemas, composes through wrappers, and lowers to the portable IR).\n */\nexport function describeDriverConformance(\n  opts: DriverConformanceOptions,\n): void {\n  const { name, s, driver, defineEntity } = opts;\n\n  describe(`driver conformance: ${name}`, () => {\n    describe(\"Driver contract\", () => {\n      test(\"is registered under its name\", () => {\n        expect(driverNames()).toContain(name);\n        expect(getDriver(name)).toBe(driver);\n        expect(driver.name).toBe(name);\n      });\n\n      test(\"exposes a kind registry + the schema/execution ops\", () => {\n        // Schema ops are generic over `registry`; the driver provides the fan-out + execution.\n        expect(driver.registry).toBeDefined();\n        expect(typeof driver.registry.entries).toBe(\"function\");\n        expect(driver.registry.names().length).toBeGreaterThan(0);\n        for (const op of [\n          \"explode\",\n          \"introspectAll\",\n          \"connect\",\n          \"apply\",\n          \"close\",\n        ] as const) {\n          expect(typeof driver[op]).toBe(\"function\");\n        }\n      });\n    });\n\n    describe(\"zod drop-in surface (s.* is a Zod superset)\", () => {\n      for (const { key, build } of DROP_INS) {\n        test(`s.${key}() exists and returns a field`, () => {\n          expect(typeof s[key]).toBe(\"function\");\n          const field = build(s);\n          expect(isField(field)).toBe(true);\n        });\n      }\n\n      for (const { key, valid, invalid } of SCALAR_CHECKS) {\n        test(`s.${key}() carries a \"${key}\" Zod schema`, () => {\n          const schema = toSchema(s[key]());\n          expect(schema.safeParse(valid).success).toBe(true);\n          expect(schema.safeParse(invalid).success).toBe(false);\n        });\n      }\n    });\n\n    describe(\"Zod-clean codecs + wrappers\", () => {\n      test(\"decode/encode delegate to the inner Zod schema\", () => {\n        const field = s.string() as {\n          decode: (v: unknown) => unknown;\n          encode: (v: unknown) => unknown;\n        };\n        expect(field.decode(\"hi\")).toBe(\"hi\");\n        expect(field.encode(\"hi\")).toBe(\"hi\");\n      });\n\n      test(\"wrappers preserve field-ness (optional/array compose)\", () => {\n        const field = s.string() as {\n          optional: () => unknown;\n          array: () => unknown;\n        };\n        expect(isField(field.optional())).toBe(true);\n        expect(isField(field.array())).toBe(true);\n      });\n    });\n\n    describe(\"lowering (drop-in fields → kind registry)\", () => {\n      test(\"an entity of drop-in fields explodes + lowers + emits, carrying every field\", () => {\n        const shape: Record<string, unknown> = {};\n        for (const { key, build } of DROP_INS) shape[`f_${key}`] = build(s);\n        const entity = defineEntity(\"better_schemic_conformance_probe\", shape);\n\n        // explode (authoring -> kinded definables) -> lowerSchema -> portable objects.\n        const portable = lowerSchema(\n          driver.registry,\n          driver.explode([entity], []),\n        );\n        // Kind-agnostic: the probe lowers to at least one object (its kind is the driver's own —\n        // `table`, `collection`, …); the per-field check below is what proves lowering is faithful.\n        expect(portable.length).toBeGreaterThan(0);\n\n        // The portable shape is the driver's own, but the emitted DDL is generic: every drop-in\n        // field name must appear in it (lowering + emit carried it through).\n        const ddl = emitKinds(driver.registry, portable).join(\"\\n\");\n        expect(ddl.length).toBeGreaterThan(0);\n        for (const { key } of DROP_INS) {\n          expect(ddl).toContain(`f_${key}`);\n        }\n      });\n    });\n  });\n}\n\n// --- Coverage reconcile -------------------------------------------------------------------------\n//\n// The shared, driver-AGNOSTIC guard that keeps a driver's `docs/COVERAGE.md` (prose discipline) honest\n// against reality — closing the \"done-vs-todo list silently drifts\" gap. A driver declares its coverage\n// as data (a KIND manifest + a FEATURE manifest) and this reconciles it against the LIVE facts: the\n// neutral `registry.names()`/`.entries()` enumeration (so the registered-kind side CAN'T drift from the\n// code) and the actual test titles (so a feature can't be marked done without a real test). The\n// ENFORCEMENT lives here, in ONE place — a driver supplies only its manifest, so a fix propagates to\n// every driver instead of drifting across three copies.\n//\n// DELIBERATELY NOT checked: \"every kind defines `canonical()`\". `KindEngine.canonical` is OPTIONAL by\n// contract (it defaults to `emit(portable).join(\"\\n\")`), so a kind whose `emit` already IS its canonical\n// form correctly omits it — requiring it here would false-fail a conformant driver. A driver that wants\n// the stricter \"all MY kinds define an explicit canonical\" invariant can assert it in a local test.\n\n/** Coverage status, mirroring the `docs/COVERAGE.md` checkbox: full round-trip / partial / not done. */\nexport type CoverageStatus = \"x\" | \"~\" | \" \";\n\n/** A registered KIND and the round-trip status it claims. */\nexport interface KindCoverage {\n  name: string;\n  status: CoverageStatus;\n  note?: string;\n}\n\n/** A finer-grained FEATURE within a kind, and (when done) the test that proves it. */\nexport interface FeatureCoverage {\n  key: string;\n  kind: string;\n  status: CoverageStatus;\n  /** A substring of the test title that exercises this feature — REQUIRED when status is `x`. */\n  coveredBy?: string;\n  note?: string;\n}\n\n/** The live inputs a reconcile runs against (the pure form — no `bun:test`, no filesystem). */\nexport interface CoverageReconcileInput {\n  registry: KindRegistry;\n  kinds: KindCoverage[];\n  features: FeatureCoverage[];\n  /** Concatenated source of the driver's `*.test.ts` — real test titles are extracted from it. */\n  testSrc: string;\n}\n\n/** One named check and the assertions it failed (empty = passed). */\nexport interface CoverageCheck {\n  name: string;\n  failures: string[];\n}\n\n/** The reconcile outcome: per-check breakdown + a flattened failure list for a single-assert test. */\nexport interface CoverageReconcileResult {\n  checks: CoverageCheck[];\n  failures: string[];\n}\n\n/**\n * Extract the titles of the REAL, non-skipped `test(...)`/`it(...)` calls from concatenated test source.\n * Matching against actual titles (rather than a raw `source.includes`) means a mention in a comment or an\n * unrelated string literal can't count as coverage, and a `.skip`/`.todo` test can't satisfy a done claim.\n */\nfunction extractTestTitles(src: string): string[] {\n  const re =\n    /\\b(?:test|it)(\\.[\\w.]+)?\\s*\\(\\s*([\"'`])((?:\\\\.|(?!\\2)[\\s\\S])*?)\\2/g;\n  const titles: string[] = [];\n  for (const m of src.matchAll(re)) {\n    const modifier = m[1] ?? \"\";\n    if (/\\.(?:skip|todo)\\b/.test(modifier)) continue;\n    titles.push(m[3]);\n  }\n  return titles;\n}\n\n/**\n * Reconcile a driver's declared coverage against the live registry + tests. PURE — returns a per-check\n * breakdown; {@link describeCoverageReconcile} is the `bun:test` shell around it. See the section header\n * for what is (and deliberately isn't) checked.\n */\nexport function reconcileCoverage(\n  input: CoverageReconcileInput,\n): CoverageReconcileResult {\n  const { registry, kinds, features, testSrc } = input;\n  const registered = new Set(registry.names());\n  const checks: CoverageCheck[] = [];\n\n  // 1. Registered kinds EXACTLY equal the manifest, both directions — the neutral registry is the LHS,\n  //    so registering a kind without listing it (or vice versa) fails by construction.\n  const declared = new Set(kinds.map((k) => k.name));\n  const kindsFailures: string[] = [];\n  for (const name of registered)\n    if (!declared.has(name))\n      kindsFailures.push(\n        `kind \"${name}\" is registered but missing from the manifest`,\n      );\n  for (const name of declared)\n    if (!registered.has(name))\n      kindsFailures.push(\n        `kind \"${name}\" is in the manifest but not registered`,\n      );\n  checks.push({\n    name: \"registered kinds match the manifest\",\n    failures: kindsFailures,\n  });\n\n  // 2. Every feature references a registered kind (referential integrity).\n  checks.push({\n    name: \"every feature maps to a registered kind\",\n    failures: features\n      .filter((f) => !registered.has(f.kind))\n      .map((f) => `feature \"${f.key}\" -> unknown kind \"${f.kind}\"`),\n  });\n\n  // 3. Every DONE feature names a covering test that actually exists.\n  const titles = extractTestTitles(testSrc);\n  const coverFailures: string[] = [];\n  for (const f of features) {\n    if (f.status !== \"x\") continue;\n    if (!f.coveredBy) {\n      coverFailures.push(\n        `feature \"${f.key}\" is [x] but declares no coveredBy test`,\n      );\n      continue;\n    }\n    if (!titles.some((t) => t.includes(f.coveredBy as string)))\n      coverFailures.push(\n        `feature \"${f.key}\" coveredBy \"${f.coveredBy}\" — no matching (non-skipped) test title`,\n      );\n  }\n  checks.push({\n    name: \"every [x] feature names a covering test\",\n    failures: coverFailures,\n  });\n\n  // 4. No duplicate feature keys / kind entries (hygiene — a dup silently hides one side).\n  checks.push({\n    name: \"no duplicate feature keys\",\n    failures: duplicates(\n      features.map((f) => f.key),\n      \"feature key\",\n    ),\n  });\n  checks.push({\n    name: \"no duplicate kind entries\",\n    failures: duplicates(\n      kinds.map((k) => k.name),\n      \"kind entry\",\n    ),\n  });\n\n  return { checks, failures: checks.flatMap((c) => c.failures) };\n}\n\n/** Names appearing more than once, as failure messages. */\nfunction duplicates(names: string[], label: string): string[] {\n  const seen = new Set<string>();\n  const dup: string[] = [];\n  for (const n of names) {\n    if (seen.has(n)) dup.push(`duplicate ${label} \"${n}\"`);\n    seen.add(n);\n  }\n  return dup;\n}\n\n/** Options for the `bun:test` reconcile shell. Supply `testDir` (read for you) OR a pre-read `testSrc`. */\nexport interface CoverageReconcileOptions {\n  /** Label for the describe block (typically the driver name). */\n  name?: string;\n  registry: KindRegistry;\n  kinds: KindCoverage[];\n  features: FeatureCoverage[];\n  /** The dir holding this driver's `*.test.ts`; the helper concatenates them to prove test coverage. */\n  testDir?: string;\n  /** Pre-read test source, if you'd rather gather it yourself (alternative to `testDir`). */\n  testSrc?: string;\n}\n\n/**\n * Register the coverage reconcile as a `bun:test` block — one named `test(...)` per check, so CI reads\n * granularly. A driver calls this from a single `*.test.ts` with its manifest + `testDir`:\n *\n *   import { describeCoverageReconcile } from \"@better-schemic/core/testing\";\n *   import { registry } from \"../src/kinds\";\n *   import { KIND_MANIFEST, FEATURE_MANIFEST } from \"./coverage-manifest\";\n *   describeCoverageReconcile({ name: \"sqlite\", registry, kinds: KIND_MANIFEST,\n *     features: FEATURE_MANIFEST, testDir: import.meta.dir });\n */\nexport function describeCoverageReconcile(\n  opts: CoverageReconcileOptions,\n): void {\n  const { name, registry, kinds, features } = opts;\n  const testSrc =\n    opts.testSrc ?? (opts.testDir ? readTestSrc(opts.testDir) : \"\");\n  describe(name ? `coverage reconcile: ${name}` : \"coverage reconcile\", () => {\n    for (const check of reconcileCoverage({\n      registry,\n      kinds,\n      features,\n      testSrc,\n    }).checks) {\n      test(check.name, () => {\n        expect(check.failures).toEqual([]);\n      });\n    }\n  });\n}\n\n/** Concatenate every `*.test.ts` in `dir` (the source the covering-test check scans). */\nfunction readTestSrc(dir: string): string {\n  return readdirSync(dir)\n    .filter((f) => f.endsWith(\".test.ts\"))\n    .map((f) => readFileSync(join(dir, f), \"utf8\"))\n    .join(\"\\n\");\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@better-schemic/core",
+  "version": "0.1.0-alpha.1",
+  "description": "The dialect-neutral engine for Better-schemic — Driver contract, portable schema IR, and the migration/diff/snapshot engine.",
+  "license": "MIT",
+  "author": "Vertio Solutions",
+  "homepage": "https://github.com/NONSTANDARDCODE/better-schemic",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NONSTANDARDCODE/better-schemic.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "module": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "lib",
+    "src",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      }
+    },
+    "./config": {
+      "bun": "./src/config.ts",
+      "import": {
+        "types": "./lib/config.d.ts",
+        "default": "./lib/config.js"
+      }
+    },
+    "./driver": {
+      "bun": "./src/driver/sdk.ts",
+      "import": {
+        "types": "./lib/driver.d.ts",
+        "default": "./lib/driver.js"
+      }
+    },
+    "./authoring": {
+      "bun": "./src/authoring.ts",
+      "import": {
+        "types": "./lib/authoring.d.ts",
+        "default": "./lib/authoring.js"
+      }
+    },
+    "./testing": {
+      "bun": "./src/testing.ts",
+      "import": {
+        "types": "./lib/testing.d.ts",
+        "default": "./lib/testing.js"
+      }
+    },
+    "./query": {
+      "bun": "./src/query.ts",
+      "import": {
+        "types": "./lib/query.d.ts",
+        "default": "./lib/query.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepack": "bun run build",
+    "test": "bun test",
+    "test:unit": "bun test test/unit",
+    "test:live": "bun test test/live",
+    "test:e2e": "bun test test/e2e",
+    "test:types": "bun run ../../scripts/type-perf.ts packages/core",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write ."
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "jiti": "^2.4.2",
+    "magicast": "^0.5.3"
+  },
+  "peerDependencies": {
+    "surrealdb": "^2.0.3",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@ark/attest": "0.56.3",
+    "@biomejs/biome": "^2.3.11",
+    "@types/bun": "latest",
+    "surrealdb": "^2.0.3",
+    "tsup": "^8",
+    "tsx": "^4.23.0",
+    "typescript": "^5",
+    "zod": "^4.3.5"
+  }
+}

package/src/authoring.ts

@@ -0,0 +1,360 @@
+// The NEUTRAL, dialect-agnostic AUTHORING BASE (docs/AUTHORING-SPLIT.md — "base builder in core").
+// Each driver package builds its `s.*` on this: `class <D>Field extends SFieldBase<S, Flags, <D>Meta>`
+// adds the dialect's native authoring (`$`-methods) and its `$<driver>(type, codec)` escape hatch for
+// types not representable on the wire; the base provides the Zod codec, the Zod wrappers, the full
+// `z.*` passthrough, and the `rebuild`/`blank` seam that carries native metadata through a chain.
+//
+// It references NOTHING dialect-specific — it's generic over the per-dialect native-metadata slot `N`.
+// It is also Zod-CLEAN: app-side behaviour delegates to the inner Zod schema (`z.decode`/`z.encode`/
+// the wrappers) via Zod's public API, with side-channel metadata kept on WeakMaps — never patching
+// Zod internals.
+
+import * as z from "zod";
+
+// `SFieldBase` is INVARIANT in its native-metadata slot `N` (the protected `rebuild(native: N)` makes
+// N contravariant while `native`/`blank` make it covariant). So a dialect field — `SField` with
+// `N = SurrealMeta` — is NOT assignable to a fixed `N = unknown`, which would make `AnyField` reject
+// real dialect fields (e.g. `.or(s.int())`). At THIS cross-dialect boundary `N` is honestly "any
+// dialect's metadata": erase it to `any` (bivariant) so every driver's field is an `AnyField`. The
+// concrete `N` is preserved everywhere it matters — each driver's own field type keeps `N = <D>Meta`.
+
+/** Any field of ANY dialect — the base type the helpers + wrappers accept. */
+// biome-ignore lint/suspicious/noExplicitAny: cross-dialect erasure of the invariant native slot N.
+export type AnyField = SFieldBase<z.ZodType, string, any>;
+
+/** The Zod schema a field (or a raw Zod schema) carries. */
+export type SchemaOf<F> =
+  // biome-ignore lint/suspicious/noExplicitAny: match a field of any dialect (N is invariant).
+  F extends SFieldBase<infer S, string, any>
+    ? S
+    : F extends z.ZodType
+      ? F
+      : never;
+
+/** The `Flags` channel a field carries (driver `$`-methods brand it; widens to `string` for `Shape`). */
+export type FlagsOf<F> =
+  // biome-ignore lint/suspicious/noExplicitAny: match a field of any dialect (N is invariant).
+  F extends SFieldBase<z.ZodType, infer Fl, any> ? Fl : never;
+
+/** The schema one wrapper down — what `unwrap()` returns. */
+export 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;
+
+/**
+ * Maps an object schema (built via a driver's `s.object`) to its original field shape, so nested
+ * fields keep their authoring metadata through generation. Kept on the schema, not the field, so it
+ * composes through `array()`/`optional()`/nesting.
+ */
+export const objectFieldsRegistry = new WeakMap<
+  z.ZodType,
+  Record<string, AnyField>
+>();
+
+/**
+ * The PORTABLE, dialect-agnostic field base. 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). Each dialect subclasses it to
+ * add native authoring (`$`-methods) and re-type the wrappers so a chain stays its own field type.
+ */
+export abstract class SFieldBase<
+  S extends z.ZodType = z.ZodType,
+  Flags extends string = never,
+  N = unknown,
+> {
+  constructor(
+    readonly schema: S,
+    readonly native: N,
+  ) {}
+
+  /**
+   * Standard Schema interface (https://standardschema.dev), forwarded from the wrapped Zod schema so a
+   * Better-schemic field IS a drop-in Standard Schema — it slots straight into any consumer (tRPC, TanStack
+   * Form/Router, …) without unwrapping. `validate` runs the DECODE direction (wire -> app), matching
+   * `decode`/`parse`. We wrap Zod by composition (not subclassing), so this getter is what carries the
+   * `~standard` contract across the wrapper; without it only `field.schema` would be compliant.
+   */
+  get ["~standard"](): S["~standard"] {
+    return this.schema["~standard"];
+  }
+
+  /** 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;
+
+  // --- Field-level codec (raw, on `this.schema`): `decode` reads (wire -> app), `encode` writes
+  // (app -> wire). Create-shaping is a table concept, so these are NOT create-shaped. ---
+  /** Decode a DB value to its app type (wire -> app). */
+  decode(value: unknown): z.output<S> {
+    return z.decode(this.schema, value as never);
+  }
+  /** Encode an app value to its DB wire type (app -> wire). */
+  encode(value: z.output<S>): z.input<S> {
+    return z.encode(this.schema, value);
+  }
+  decodeAsync(value: unknown): Promise<z.output<S>> {
+    return z.decodeAsync(this.schema, value as never);
+  }
+  encodeAsync(value: z.output<S>): Promise<z.input<S>> {
+    return z.encodeAsync(this.schema, value);
+  }
+  safeDecode(value: unknown) {
+    return z.safeDecode(this.schema, value as never);
+  }
+  safeEncode(value: z.output<S>) {
+    return z.safeEncode(this.schema, value);
+  }
+  safeDecodeAsync(value: unknown) {
+    return z.safeDecodeAsync(this.schema, value as never);
+  }
+  safeEncodeAsync(value: z.output<S>) {
+    return z.safeEncodeAsync(this.schema, value);
+  }
+  // Deprecated Zod-style aliases — `parse` runs the DECODE direction (wire -> app).
+  /** @deprecated `parse` decodes a value (wire -> app). Use {@link decode}. */
+  parse(value: unknown): z.output<S> {
+    return this.decode(value);
+  }
+  /** @deprecated Use {@link safeDecode}. */
+  safeParse(value: unknown) {
+    return this.safeDecode(value);
+  }
+  /** @deprecated Use {@link decodeAsync}. */
+  parseAsync(value: unknown): Promise<z.output<S>> {
+    return this.decodeAsync(value);
+  }
+  /** @deprecated Use {@link safeDecodeAsync}. */
+  safeParseAsync(value: unknown) {
+    return this.safeDecodeAsync(value);
+  }
+  /** Zod's `.spa` alias for {@link safeParseAsync} (drop-in). */
+  spa(value: unknown) {
+    return this.safeParseAsync(value);
+  }
+
+  // --- Zod reflection + interop (drop-in for `z.*`), delegated to the inner schema ---
+  /** Does this field accept `undefined`? (Zod reflection.) */
+  isOptional(): boolean {
+    return this.schema.isOptional();
+  }
+  /** Does this field accept `null`? (Zod reflection.) */
+  isNullable(): boolean {
+    return this.schema.isNullable();
+  }
+  /** Read back the description set via {@link describe} / {@link meta}. */
+  get description(): string | undefined {
+    return this.schema.description;
+  }
+  /** JSON Schema for this field's wire shape (delegates to `z.toJSONSchema`). */
+  toJSONSchema() {
+    return z.toJSONSchema(this.schema);
+  }
+  /** Register the wrapped schema in a Zod registry for metadata interop; returns the field. */
+  register(...args: Parameters<S["register"]>): this {
+    Reflect.apply(this.schema.register, this.schema, args);
+    return this;
+  }
+
+  // Zod wrappers — delegate to the inner schema, carry native metadata + flags forward.
+  optional(): SFieldBase<z.ZodOptional<S>, Flags, N> {
+    return this.rebuild(this.schema.optional(), this.native);
+  }
+  nullable(): SFieldBase<z.ZodNullable<S>, Flags, N> {
+    return this.rebuild(this.schema.nullable(), this.native);
+  }
+  default(value: z.input<S>): SFieldBase<z.ZodDefault<S>, Flags, N> {
+    return this.rebuild(this.schema.default(value as never), this.native);
+  }
+  /** Zod prefault: fill an absent value with `value`, then validate it (unlike `.default`). */
+  prefault(value: z.input<S>): SFieldBase<z.ZodPrefault<S>, Flags, N> {
+    return this.rebuild(z.prefault(this.schema, value as never), this.native);
+  }
+  /** Zod catch: fall back to `value` when parsing fails. */
+  catch(value: z.output<S>): SFieldBase<z.ZodCatch<S>, Flags, N> {
+    return this.rebuild(this.schema.catch(value as never), this.native);
+  }
+  array(): SFieldBase<z.ZodArray<S>, Flags, N> {
+    return this.rebuild(z.array(this.schema), this.native);
+  }
+  nullish(): SFieldBase<z.ZodOptional<z.ZodNullable<S>>, Flags, N> {
+    return this.rebuild(this.schema.nullish(), this.native);
+  }
+  /** Zod `.nonoptional()` — require a value (strips an `.optional()`). */
+  nonoptional(): SFieldBase<z.ZodNonOptional<S>, Flags, N> {
+    return this.rebuild(this.schema.nonoptional(), this.native);
+  }
+  /** Zod `.exactOptional()` — optional that rejects an explicit `undefined`. */
+  exactOptional(): SFieldBase<z.ZodExactOptional<S>, Flags, N> {
+    return this.rebuild(this.schema.exactOptional(), this.native);
+  }
+  /** Zod union — `a.or(b)` accepts either. Mirrors Zod's `.or()`. */
+  or<F extends AnyField | z.ZodType>(
+    other: F,
+  ): SFieldBase<z.ZodUnion<[S, SchemaOf<F>]>, never, N> {
+    return this.rebuild<z.ZodUnion<[S, SchemaOf<F>]>, never>(
+      z.union([this.schema, toZod(other)]) as z.ZodUnion<[S, SchemaOf<F>]>,
+      this.blank(),
+    );
+  }
+  /** Zod intersection — `a.and(b)`. Mirrors Zod's `.and()`. */
+  and<F extends AnyField | z.ZodType>(
+    other: F,
+  ): SFieldBase<z.ZodIntersection<S, SchemaOf<F>>, never, N> {
+    return this.rebuild<z.ZodIntersection<S, SchemaOf<F>>, never>(
+      z.intersection(this.schema, toZod(other) as SchemaOf<F>),
+      this.blank(),
+    );
+  }
+
+  // --- Native Zod passthrough (drop-in for `z.*`): app-side validation / transform / metadata,
+  // delegated to the inner schema. The dialect-DDL side stays under the driver's `$`-methods. ---
+  refine(
+    check: (arg: z.output<S>) => unknown,
+    params?: string | z.core.$ZodCustomParams,
+  ): this {
+    return this.rebuild(
+      this.schema.refine(check, params) as S,
+      this.native,
+    ) as unknown as this;
+  }
+  superRefine(
+    refinement: (
+      arg: z.output<S>,
+      ctx: z.core.$RefinementCtx<z.output<S>>,
+    ) => void,
+  ): this {
+    return this.rebuild(
+      this.schema.superRefine(refinement) as S,
+      this.native,
+    ) as unknown as this;
+  }
+  check(
+    ...checks: (z.core.CheckFn<z.output<S>> | z.core.$ZodCheck<z.output<S>>)[]
+  ): this {
+    return this.rebuild(
+      this.schema.check(...checks) as S,
+      this.native,
+    ) as unknown as this;
+  }
+  overwrite(fn: (x: z.output<S>) => z.output<S>): this {
+    return this.rebuild(
+      this.schema.overwrite(fn) as S,
+      this.native,
+    ) as unknown as this;
+  }
+  brand<B extends PropertyKey = PropertyKey>(value?: B): this {
+    return this.rebuild(
+      this.schema.brand(value) as unknown as S,
+      this.native,
+    ) as unknown as this;
+  }
+  /** Zod's app-side metadata (JSON-schema/docs) — distinct from a driver's `$comment()`. */
+  describe(description: string): this {
+    return this.rebuild(
+      this.schema.describe(description) as S,
+      this.native,
+    ) as unknown as this;
+  }
+  meta(data: z.core.GlobalMeta): this {
+    return this.rebuild(
+      this.schema.meta(data) as S,
+      this.native,
+    ) as unknown as this;
+  }
+  /** Zod's app-side readonly (TS-immutable output) — distinct from a driver's `$readonly()`. */
+  readonly(): SFieldBase<z.ZodReadonly<S>, Flags, N> {
+    return this.rebuild(this.schema.readonly(), this.native);
+  }
+  /** 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
+  > {
+    return this.rebuild(this.schema.transform(fn), this.native);
+  }
+  /** 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> {
+    return this.rebuild(
+      this.schema.pipe(target) as z.ZodPipe<S, T>,
+      this.native,
+    );
+  }
+  /** Peel one wrapper (optional/nullable/default/prefault/catch/readonly/array) off the field. */
+  unwrap(): SFieldBase<InnerOf<S>, Flags, N> {
+    const def = this.schema._zod.def as {
+      innerType?: z.ZodType;
+      element?: z.ZodType;
+    };
+    const inner = def.innerType ?? def.element ?? this.schema;
+    return this.rebuild(inner, this.native) as unknown as SFieldBase<
+      InnerOf<S>,
+      Flags,
+      N
+    >;
+  }
+
+  /** Object-only: allow arbitrary extra keys — `FLEXIBLE` in DDL. Mirrors Zod's `.loose()`. */
+  loose(): this {
+    return this.objectMode("loose");
+  }
+  /** Object-only: reject unknown keys — the default. Mirrors Zod's `.strict()`. */
+  strict(): this {
+    return this.objectMode("strict");
+  }
+  /** Alias for {@link loose} — a `FLEXIBLE` object accepting arbitrary keys. */
+  flexible(): this {
+    return this.loose();
+  }
+  private objectMode(mode: "loose" | "strict"): this {
+    const obj = this.schema as unknown as {
+      loose?: () => z.ZodType;
+      strict?: () => z.ZodType;
+    };
+    if (typeof obj.loose !== "function" || typeof obj.strict !== "function") {
+      return this; // not an object schema — no-op
+    }
+    const next = (mode === "loose"
+      ? obj.loose()
+      : obj.strict()) as unknown as S;
+    // Carry the nested-field registry forward so DDL/create-shaping still see the subfields.
+    const fields = objectFieldsRegistry.get(this.schema);
+    if (fields) objectFieldsRegistry.set(next, fields);
+    return this.rebuild(next, this.native) as unknown as this;
+  }
+}
+
+/** Unwrap a field to its Zod schema (raw Zod schemas pass through). */
+export const toZod = (v: AnyField | z.ZodType): z.ZodType =>
+  v instanceof SFieldBase ? v.schema : v;
+
+// Secret-ref authoring helpers (env/secret) live here on the SIDE-EFFECT-FREE authoring subpath, so a
+// driver's authoring index can re-export them without dragging the engine. (Also on the main index.)
+export {
+  env,
+  isSecretRef,
+  type SecretProvider,
+  type SecretRef,
+  secret,
+} from "./secrets";