lecodes-sdk 0.19.0

package/src/server/auth/models.ts

@@ -0,0 +1,83 @@
+/**
+ * `auth.model.user({...})` / `auth.model.session()` — the ONLY place auth touches the schema
+ * (docs/backend-plan.md §3.4 / decision 10). Both return ordinary `model(...)`s: the developer registers
+ * them in `defineDb({ User, Session, … })` under exactly those keys (other models relate to them with
+ * `t.one("User")` / `t.one("Session")`), and `defineDb` adds `Session` itself when it isn't declared —
+ * a device session exists from the first request, before any login, so every project db has one.
+ *
+ * Provider identity columns (`googleId`, `appleId`) follow `app.json` `auth.providers`, which the
+ * compiler hands the server bundle through ./appConfig.ts (a module it replaces at compile time).
+ */
+
+import { t, type Field } from "../db/fields"
+import type { Fields, Model } from "../db/types"
+import { app, type AppConfig, type AuthProvider } from "./appConfig"
+
+export type { AppConfig, AuthProvider }
+
+const seam = globalThis as unknown as { __lecodesApp?: AppConfig }
+/** The project's `app.json` subset: the compiled-in module, else the test/tooling seam, else empty. */
+export const appConfig = (): AppConfig => (Object.keys(app).length ? app : seam.__lecodesApp ?? {})
+export const enabledProviders = (): AuthProvider[] => appConfig().auth?.providers ?? []
+
+/** The model name the auth runtime binds to. */
+export const AUTH_USER_MODEL = "User"
+export const AUTH_SESSION_MODEL = "Session"
+
+/** Marker on the two auth models (`model()` objects are otherwise plain). */
+export type AuthModelKind = "user" | "session"
+export type AuthModel<F extends Fields> = Model<F> & { readonly __auth: AuthModelKind }
+
+// ───────────────────────────── field sets ─────────────────────────────
+
+/** Built-in `User` fields (what `auth.user` is typed with). */
+export const userFields = () => ({
+  email:     t.string().optional().unique(),
+  name:      t.string().optional(),
+  avatar:    t.string().optional(),
+  /** Plain string column, `"user"` by default — `auth.requireUser({ role: "admin" })` is field equality. */
+  role:      t.string().default("user"),
+  createdAt: t.date().default("now"),
+})
+export type UserFields = ReturnType<typeof userFields>
+
+/** `<provider>Id` identity columns for the OAuth providers enabled in app.json. */
+const providerFields = (): Record<string, Field<any, any>> => {
+  const out: Record<string, Field<any, any>> = {}
+  for (const p of enabledProviders()) if (p !== "email") out[`${p}Id`] = t.string().optional().unique()
+  return out
+}
+
+/** Built-in `Session` fields. `user` is added by `defineDb` when a `User` model exists (schema-time, so a
+ *  db without an auth user model has sessions without a user column). */
+export const sessionFields = () => ({
+  /** sha256 of the bearer token the device holds — the token itself is never stored. */
+  tokenHash:    t.string().unique(),
+  createdAt:    t.date().default("now"),
+  lastSeenAt:   t.date().default("now"),
+  revoked:      t.bool().default(false),
+  // email-code sign-in state lives on the requesting session (no code table)
+  pendingEmail: t.string().optional(),
+  codeHash:     t.string().optional(),
+  codeExpires:  t.date().optional(),
+  codeAttempts: t.int().default(0),
+})
+export type SessionFields = ReturnType<typeof sessionFields> & { user: ReturnType<typeof sessionUserField> }
+export const sessionUserField = () => t.one(AUTH_USER_MODEL).optional().onDelete("cascade")
+
+// ───────────────────────────── factories ─────────────────────────────
+
+// Built inline (not via defineDb's `model()`) to keep this module import-free of defineDb, which imports us.
+const authModel = <F extends Fields>(kind: AuthModelKind, fields: F): AuthModel<F> =>
+  ({ fields, __model: true, __auth: kind }) as AuthModel<F>
+
+/** `auth.model.user({...extra})` — the built-in user (+ provider ids from app.json) plus the developer's fields. */
+export const authUserModel = <E extends Fields = {}>(extra?: E): AuthModel<UserFields & E> =>
+  authModel("user", { ...userFields(), ...providerFields(), ...(extra ?? {}) } as UserFields & E)
+
+/** `auth.model.session({...extra})` — declare it only to relate to sessions (`t.one("Session")`) or to add fields. */
+export const authSessionModel = <E extends Fields = {}>(extra?: E): AuthModel<SessionFields & E> =>
+  authModel("session", { ...sessionFields(), ...(extra ?? {}) } as unknown as SessionFields & E)
+
+export const isAuthModel = (m: unknown, kind?: AuthModelKind): m is AuthModel<any> =>
+  typeof m === "object" && m !== null && "__auth" in m && (kind === undefined || (m as AuthModel<any>).__auth === kind)

package/src/server/auth/types.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared shapes of the auth layer (docs/backend-plan.md §3.4). Two sides meet through them:
+ *  - the BUNDLE side (`auth` global, ./global.ts) — what `*.server.ts` code calls;
+ *  - the HOST side (./host.ts) — sessions, email codes and OAuth binding, run by the runner with the
+ *    project's db handle and the platform's secrets. Installed on `globalThis.__lecodesAuth`.
+ */
+
+import type { RequestContext } from "../context"
+import type { AuthProvider } from "./models"
+
+/** The built-in user row — what `auth.user` is typed with (custom fields exist at runtime; select them via `db.user`). */
+export type AuthUser = {
+  id: number
+  email: string | null
+  name: string | null
+  avatar: string | null
+  role: string
+  createdAt: number
+}
+
+/** Per-request auth state, resolved by the host before the endpoint runs (`RequestContext.auth`). */
+export type AuthState = {
+  sessionId: number
+  userId: number | null
+  user: AuthUser | null
+  /** A token to hand back to the client in this response (a new guest session, or a rotation). */
+  issuedToken?: string
+}
+
+/** What an OAuth provider hands the runner after a successful web sign-in. */
+export type OAuthProfile = { sub: string, email?: string | null, emailVerified?: boolean, name?: string | null, avatar?: string | null }
+/** A credential a NATIVE provider SDK produced in the app (client plugin `OAuth.signIn`): an access token
+ *  (Yandex, VK ID) or an OpenID identity token (Google, Apple). Verified server-side, never trusted as-is. */
+export type OAuthCredential = { accessToken?: string, idToken?: string, name?: string | null, email?: string | null }
+
+/** Host operations the bundle's `auth` global forwards to (all request-scoped through `ctx`). */
+export type AuthOps = {
+  email: {
+    sendCode(ctx: RequestContext, email: string): Promise<void>
+    verify(ctx: RequestContext, email: string, code: string): Promise<AuthUser>
+  }
+  oauth: {
+    url(ctx: RequestContext, provider: Exclude<AuthProvider, "email">): Promise<string>
+    signIn(ctx: RequestContext, provider: Exclude<AuthProvider, "email">, credential: OAuthCredential): Promise<AuthUser>
+  }
+  signIn(ctx: RequestContext, userId: number): Promise<AuthUser>
+  signOut(ctx: RequestContext): Promise<void>
+  /** `db.session` filtered to the current user's sessions (or just this device's, when signed out). */
+  sessions(ctx: RequestContext): any
+}

package/src/server/channel.ts

@@ -0,0 +1,56 @@
+/**
+ * Server side of channels (docs/backend-plan.md §3.3): typed pub/sub, server → client only.
+ *
+ *   type ChatEvents = { message: { from: string; text: string }; typing: { from: string } }
+ *   export const chat = channel<ChatEvents>({ onJoin: room => { auth.requireUser() } })
+ *   chat.publish(room, "message", { from, text })
+ *
+ * A channel's identity is its export (`<path>#<name>`), assigned by the runtime when the bundle is
+ * loaded (`loadServerModules`); `publish` before that is an error. Delivery goes through the
+ * `globalThis.__lecodesPublish` seam the runner installs (same reason as ./context.ts: the bundle
+ * carries its own SDK copy).
+ */
+
+export type ChannelEvents = Record<string, unknown>
+
+export type ChannelOptions = {
+  /** Called when a client subscribes to `topic`; throw (e.g. `ApiError(403)`) to refuse. */
+  onJoin?: (topic: string) => void | Promise<void>
+}
+
+export interface Channel<E extends ChannelEvents> {
+  /** @internal set by the runtime: `<path>#<export>` */
+  __id: string | null
+  /** @internal */
+  readonly __channel: true
+  readonly options: ChannelOptions
+  /** Deliver `event` with `payload` to every subscriber of `topic` (at-most-once). */
+  publish<K extends keyof E & string>(topic: string, event: K, payload: E[K]): void
+}
+
+type Publisher = (channelId: string, topic: string, event: string, payload: unknown) => void
+const seam = globalThis as unknown as { __lecodesPublish?: Publisher }
+
+/** Host hook (runner / test harness): where `publish` delivers to. */
+export const setChannelPublisher = (publisher: Publisher | null) => {
+  if (publisher) seam.__lecodesPublish = publisher
+  else delete seam.__lecodesPublish
+}
+
+export const channel = <E extends ChannelEvents>(options: ChannelOptions = {}): Channel<E> => {
+  const ch: Channel<E> = {
+    __id: null,
+    __channel: true,
+    options,
+    publish(topic, event, payload) {
+      if (!ch.__id) throw new Error("channel.publish: the channel is not registered — export it from a *.server.ts file")
+      const publish = seam.__lecodesPublish
+      if (!publish) throw new Error("channel.publish: no host publisher installed")
+      publish(ch.__id, topic, event, payload)
+    },
+  }
+  return ch
+}
+
+export const isChannel = (v: unknown): v is Channel<any> =>
+  typeof v === "object" && v !== null && (v as Channel<any>).__channel === true

package/src/server/context.ts

@@ -0,0 +1,36 @@
+/**
+ * Request context for server code. The runner keeps the current request in an AsyncLocalStorage
+ * and exposes it through `globalThis.__lecodesRequest` — a *global* seam on purpose: the compiled
+ * server bundle carries its own copy of this module (chisel bundles the SDK in), so the host can't
+ * hand it a value by import. `request` reads through that seam; outside a request (module load,
+ * timers after the response) every member is undefined.
+ */
+
+export type RequestContext = {
+  /** Endpoint id `<path>#<export>` (or the channel id for `onJoin`). */
+  id: string
+  headers: Record<string, string>
+  ip?: string
+  /** Bearer session token as sent by the client transport (raw; auth resolves it). */
+  sessionToken?: string
+  /** Set by the auth runtime after resolving the token — read via `auth.*`, not here. */
+  auth?: unknown
+}
+
+type Provider = () => RequestContext | undefined
+const seam = globalThis as unknown as { __lecodesRequest?: Provider }
+
+/** Host hook (runner / test harness): install the current-request provider. */
+export const setRequestProvider = (provider: Provider | null) => {
+  if (provider) seam.__lecodesRequest = provider
+  else delete seam.__lecodesRequest
+}
+/** @internal */
+export const currentRequest = (): RequestContext | undefined => seam.__lecodesRequest?.()
+
+/** The current request (server global). Undefined members outside a request. */
+export const request = {
+  get id(): string | undefined { return currentRequest()?.id },
+  get headers(): Record<string, string> { return currentRequest()?.headers ?? {} },
+  get ip(): string | undefined { return currentRequest()?.ip },
+}

package/src/server/db/defineDb.ts

@@ -0,0 +1,237 @@
+/**
+ * `model({...})` + `defineDb({ User, Post })` — the schema registry and the typed db handle.
+ *
+ * Runtime responsibilities: validate relation names, resolve `t.many()` back-fields, emit the `.marci`
+ * schema text (`db.$schema`), and turn collection calls into lazy `Op`s over a `MarciTransport`
+ * (`marcidb-embedded` handle, HTTP client, or a test fake). The transport is either passed to
+ * `defineDb(models, { transport })` or provided by the host through `setDbTransport()` — user code
+ * never sees a connection string.
+ */
+
+import type { Field, FieldDef, ScalarKind } from "./fields"
+import { AUTH_SESSION_MODEL, AUTH_USER_MODEL, authSessionModel, isAuthModel, sessionUserField } from "../auth/models"
+import { createQueryLayer, type FieldDesc, type MarciOp, type MarciTransport, type ModelsMeta } from "./marci/query"
+import type { AuthBinding, Db, Fields, Model, Schema, ValidateRefs } from "./types"
+
+export const model = <F extends Fields>(fields: F): Model<F> => ({ fields, __model: true })
+
+// ───────────────────────────── transport ─────────────────────────────
+
+// A GLOBAL seam (not a module variable): the compiled server bundle carries its own copy of this
+// module, so the host's `setDbTransport` and the bundle's `defineDb` only meet through globalThis.
+const seam = globalThis as unknown as { __lecodesDbTransport?: MarciTransport, __lecodesDbs?: Db<any>[] }
+/** Host hook: the runner/dev-server installs the project's transport before loading user code. */
+export const setDbTransport = (transport: MarciTransport | null) => {
+  if (transport) seam.__lecodesDbTransport = transport
+  else delete seam.__lecodesDbTransport
+}
+/**
+ * Every `defineDb` call registers its handle here so the host finds the schema whether or not the
+ * project exports `db` (`const db = defineDb(...)` used only inside endpoints is the common case).
+ * The host reads and clears the list after evaluating a bundle (`loadServerModules`).
+ */
+export const takeRegisteredDbs = (): Db<any>[] => {
+  const dbs = seam.__lecodesDbs ?? []
+  seam.__lecodesDbs = []
+  return dbs
+}
+
+const opOf = (o: unknown): MarciOp => {
+  const op = (o as { __op?: MarciOp })?.__op
+  if (!op) throw new Error("db.$transaction: every item must be a db.<model>.<method>(...) call")
+  return op
+}
+
+/** A reference to a previous operation's result inside `$transaction` (resolved server-side): `ref("0.id")`. */
+export const ref = (path: string): any => ({ $ref: path })
+
+// ───────────────────────────── metadata ─────────────────────────────
+
+type ModelMeta = {
+  name: string
+  fields: Record<string, FieldDef>
+  idKeys: string[]
+  /** id is a single uuid key we generate on insert. */
+  uuidId: boolean
+}
+
+const isRel = (d: FieldDef) => d.kind === "one" || d.kind === "many" || d.kind === "list"
+
+const buildMeta = (models: Record<string, Model>): Record<string, ModelMeta> => {
+  const metas: Record<string, ModelMeta> = {}
+  for (const [name, m] of Object.entries(models)) {
+    if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) throw new Error(`defineDb: model name "${name}" must be PascalCase`)
+    const fields: Record<string, FieldDef> = {}
+    for (const [key, f] of Object.entries(m.fields as Fields)) fields[key] = { ...(f as Field<any, any>).def }
+    if (fields.id && !fields.id.isId) fields.id.isId = true
+    const idKeys = Object.keys(fields).filter(k => fields[k].isId)
+    const uuidId = idKeys.length === 1 && idKeys[0] === "id" && fields.id.scalar === "uuid"
+    metas[name] = { name, fields, idKeys, uuidId }
+  }
+  // relations: targets must exist; `many` needs a back field
+  for (const meta of Object.values(metas)) {
+    for (const [key, d] of Object.entries(meta.fields)) {
+      if (!isRel(d)) continue
+      const target = metas[d.model!]
+      if (!target) throw new Error(`defineDb: ${meta.name}.${key} references unknown model "${d.model}"`)
+      if (d.kind !== "many") continue
+      if (d.back) {
+        const back = target.fields[d.back]
+        if (!back || back.kind !== "one" || back.model !== meta.name)
+          throw new Error(`defineDb: ${meta.name}.${key}: "${d.model}.${d.back}" is not a t.one("${meta.name}") field`)
+        continue
+      }
+      const candidates = Object.entries(target.fields).filter(([, f]) => f.kind === "one" && f.model === meta.name).map(([k]) => k)
+      if (candidates.length !== 1)
+        throw new Error(
+          `defineDb: ${meta.name}.${key}: cannot infer the back field on ${d.model} ` +
+          (candidates.length ? `(candidates: ${candidates.join(", ")}) — pass it: t.many("${d.model}", "<field>")`
+                             : `— add a t.one("${meta.name}") field to ${d.model}`))
+      d.back = candidates[0]
+    }
+  }
+  return metas
+}
+
+// ───────────────────────────── .marci emitter ─────────────────────────────
+
+const SCALAR: Record<Exclude<ScalarKind, "">, string> = {
+  string: "String", int: "Int", float: "Double", bool: "Bool", date: "DateTime", uuid: "Byte[16]",
+}
+const cap = (s: string) => s.charAt(0).toUpperCase() + s.slice(1)
+const ON_DELETE = { cascade: "Cascade", setNull: "SetNull", restrict: "Restrict" } as const
+
+const literal = (v: unknown, d: FieldDef): string => {
+  if (d.scalar === "date" && v === "now") return "now()"
+  if (Array.isArray(v)) return `[${v.map(x => literal(x, { ...d, array: false })).join(", ")}]`
+  if (typeof v === "string") return d.kind === "enum" ? v : JSON.stringify(v)
+  return String(v)
+}
+
+const emitField = (owner: string, key: string, d: FieldDef, extra: string[]): string => {
+  let type: string
+  const attrs: string[] = []
+  switch (d.kind) {
+    case "scalar":
+      type = d.vector ? `Float[${d.vector.size}]` : SCALAR[d.scalar as Exclude<ScalarKind, "">]
+      if (d.scalar === "uuid") attrs.push("@format(uuid)")
+      break
+    case "json": type = "Json"; break
+    case "enum": {
+      const name = `${owner}${cap(key)}`
+      extra.push(`enum ${name} {\n${d.values!.map(v => `    ${v}`).join("\n")}\n}`)
+      type = name; break
+    }
+    case "struct": {
+      const name = `${owner}${cap(key)}`
+      const inner: string[] = []
+      for (const [k, f] of Object.entries(d.fields!)) inner.push(emitField(name, k, (f as Field<any, any>).def, extra))
+      extra.push(`struct ${name} {\n${inner.join("\n")}\n}`)
+      type = name; break
+    }
+    case "one": type = d.model!; break
+    case "many": type = `${d.model}[]`; attrs.push(`@bind(${d.model}.${d.back})`); break
+    case "list": type = `${d.model}[]`; attrs.push("@list"); break
+  }
+  if (d.array && d.kind !== "many" && d.kind !== "list") type += "[]"
+  if (d.optional) type += "?"
+  if (d.isId) attrs.unshift("@id")
+  if (d.unique) attrs.push("@unique")
+  if (d.index) attrs.push("@index")
+  if (d.hasDefault) attrs.push(`@default(${literal(d.default, d)})`)
+  if (d.onDelete) attrs.push(`@onDelete(${ON_DELETE[d.onDelete]})`)
+  if (d.fulltext) attrs.push(`@fulltext(${d.fulltext})`)
+  if (d.vector) attrs.push(`@vector(${d.vector.metric})`)
+  return `    ${key.padEnd(12)} ${type}${attrs.length ? " " + attrs.join(" ") : ""}`
+}
+
+export const toMarci = (metas: Record<string, ModelMeta>): string => {
+  const out: string[] = []
+  const extra: string[] = []
+  for (const meta of Object.values(metas)) {
+    const lines = Object.entries(meta.fields).map(([k, d]) => emitField(meta.name, k, d, extra))
+    out.push(`model ${meta.name} {\n${lines.join("\n")}\n}`)
+  }
+  return [...out, ...extra].join("\n\n") + "\n"
+}
+
+// ───────────────────────────── queries ─────────────────────────────
+
+/**
+ * The model metadata marcidb's query layer reads (`MODELS` in a generated client): field descriptors per
+ * model — `key` / `body` scalars, `one` / `many` relations with their target. Structs are pseudo-models
+ * (`User.info`) so an empty nested select fills with the struct's own scalars, as marcidb does.
+ */
+const modelsMeta = (metas: Record<string, ModelMeta>): ModelsMeta => {
+  const out: Record<string, FieldDesc[]> = {}
+  const describe = (name: string, fields: Record<string, FieldDef>, implicitId: boolean) => {
+    const descs: FieldDesc[] = implicitId ? [{ n: "id", k: "key" }] : []
+    for (const [key, d] of Object.entries(fields)) {
+      if (isRel(d)) descs.push({ n: key, k: d.kind === "one" ? "one" : "many", m: d.model! })
+      else if (d.kind === "struct") {
+        const sub = `${name}.${key}`
+        const inner: Record<string, FieldDef> = {}
+        for (const [ik, f] of Object.entries(d.fields!)) inner[ik] = (f as Field<any, any>).def
+        describe(sub, inner, false)
+        descs.push({ n: key, k: "one", m: sub })
+      }
+      else descs.push({ n: key, k: d.isId ? "key" : "body" })
+    }
+    out[name] = descs
+  }
+  for (const meta of Object.values(metas)) describe(meta.name, meta.fields, meta.idKeys.length === 0)
+  return out
+}
+
+const uncap = (s: string) => s.charAt(0).toLowerCase() + s.slice(1)
+
+export type DefineDbOptions = { transport?: MarciTransport }
+
+/**
+ * The schema registry: model name = key (`db.user` ← `User`). Relation strings are checked against the
+ * keys both at the type level (`ValidateRefs`) and at runtime.
+ */
+/**
+ * The auth models (docs/backend-plan.md §3.4): `auth.model.user()` must be registered as `User`,
+ * `auth.model.session()` as `Session`; `Session` is added when the project doesn't declare it (a device
+ * session exists before any login), and gets its `user` column exactly when a `User` model exists.
+ */
+const withAuthModels = (models: Record<string, Model>): { models: Record<string, Model>, auth: AuthBinding } => {
+  for (const [name, m] of Object.entries(models)) {
+    if (isAuthModel(m, "user") && name !== AUTH_USER_MODEL) throw new Error(`defineDb: auth.model.user() must be registered as "${AUTH_USER_MODEL}" (got "${name}")`)
+    if (isAuthModel(m, "session") && name !== AUTH_SESSION_MODEL) throw new Error(`defineDb: auth.model.session() must be registered as "${AUTH_SESSION_MODEL}" (got "${name}")`)
+  }
+  // A plain `model()` named User is just a model (no auth binding); only auth.model.user() binds.
+  const user = isAuthModel(models[AUTH_USER_MODEL], "user") ? models[AUTH_USER_MODEL] : null
+  let session = models[AUTH_SESSION_MODEL]
+  if (session && !isAuthModel(session, "session")) throw new Error(`defineDb: "${AUTH_SESSION_MODEL}" is reserved for auth.model.session()`)
+  if (!session) session = authSessionModel()
+  if (user && !("user" in session.fields)) session = { ...session, fields: { ...session.fields, user: sessionUserField() } }
+  return { models: { ...models, [AUTH_SESSION_MODEL]: session }, auth: { user: user ? AUTH_USER_MODEL : null, session: AUTH_SESSION_MODEL } }
+}
+
+export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>, options: DefineDbOptions = {}): Db<S> => {
+  const { models, auth } = withAuthModels(declared as Record<string, Model>)
+  const metas = buildMeta(models)
+  const transport = () => {
+    const t = options.transport ?? seam.__lecodesDbTransport
+    if (!t) throw new Error("db: no transport — the host must call setDbTransport() before user code runs")
+    return t
+  }
+  // marcidb's own query builder over our metadata; the transport is the only host-specific piece
+  const { collection } = createQueryLayer({
+    models: modelsMeta(metas),
+    run: op => transport().exec(op),
+    // a single uuid key is generated client-side so `insert` needs no id (the .marci says @format(uuid))
+    prepareInsert: (name, data) => (metas[name].uuidId && data?.id == null ? { ...data, id: crypto.randomUUID() } : data),
+  })
+  const db: Record<string, unknown> = {
+    $schema: toMarci(metas),
+    $models: models,
+    $auth: auth,
+    $transaction: async (ops: unknown[]) => transport().batch(ops.map(opOf)),
+  }
+  for (const name of Object.keys(metas)) db[uncap(name)] = collection(name)
+  ;(seam.__lecodesDbs ??= []).push(db as Db<any>)
+  return db as Db<S>
+}

package/src/server/db/fields.ts

@@ -0,0 +1,132 @@
+/**
+ * `t` — field builders for `model({...})`. Each builder returns an immutable `Field` carrying a runtime
+ * `FieldDef` (what `.marci` is emitted from) and two phantom type parameters: the TS value type and a
+ * `FieldMeta` record (kind / optional / default / …) that `defineDb`'s type layer projects into row,
+ * insert, update, select and where types. Chained modifiers return a NEW field (builders are never
+ * mutated), so `const s = t.string(); { a: s, b: s.optional() }` behaves as expected.
+ */
+
+import type { JsonValue } from "./marci/query"
+
+export type ScalarKind = "string" | "int" | "float" | "bool" | "date" | "uuid" | ""
+export type FieldKind = "scalar" | "json" | "enum" | "struct" | "one" | "many" | "list"
+export type OnDelete = "cascade" | "setNull" | "restrict"
+
+/** Phantom metadata — the type-level twin of `FieldDef`. */
+export type FieldMeta = {
+  kind: FieldKind
+  scalar: ScalarKind
+  optional: boolean
+  hasDefault: boolean
+  array: boolean
+  isId: boolean
+  /** Related model name for one/many/list; "" otherwise. */
+  model: string
+}
+
+type DefaultMeta = { kind: "scalar", scalar: "", optional: false, hasDefault: false, array: false, isId: false, model: "" }
+export type Meta<O extends Partial<FieldMeta>> = { [P in keyof FieldMeta]: P extends keyof O ? O[P] : DefaultMeta[P] }
+type SetMeta<M extends FieldMeta, K extends keyof FieldMeta, V> = { [P in keyof FieldMeta]: P extends K ? V : M[P] }
+
+/** Runtime field definition — everything the `.marci` emitter and the runtime need. */
+export type FieldDef = {
+  kind: FieldKind
+  scalar?: ScalarKind
+  optional: boolean
+  unique: boolean
+  index: boolean
+  hasDefault: boolean
+  default?: unknown
+  array: boolean
+  isId: boolean
+  onDelete?: OnDelete
+  fulltext?: "multi" | "english" | "russian"
+  vector?: { size: number, metric: "cosine" | "euclidean" }
+  /** enum */
+  values?: readonly string[]
+  /** struct */
+  fields?: Record<string, Field<any, any>>
+  /** one / many / list */
+  model?: string
+  /** many: the field on the related model that holds the reference (`@bind`); resolved by defineDb when omitted. */
+  back?: string
+}
+
+type DefaultOf<T, M extends FieldMeta> =
+  M["scalar"] extends "date" ? "now" | number : M["array"] extends true ? T[] : T
+
+export interface Field<T, M extends FieldMeta = FieldMeta> {
+  /** phantom (type-level only — never set at runtime) */ readonly __t?: T
+  /** phantom (type-level only — never set at runtime) */ readonly __m?: M
+  readonly def: FieldDef
+  /** Nullable column (`String?`). */
+  optional(): Field<T, SetMeta<M, "optional", true>>
+  /** `@unique` (on a relation: one-to-one). */
+  unique(): Field<T, M>
+  /** `@index` — used by `$where`, `$order`, aggregations. */
+  index(): Field<T, M>
+  /** `@default(...)`; `"now"` on `t.date()` → `now()`. Makes the field optional on insert. */
+  default(value: DefaultOf<T, M>): Field<T, SetMeta<M, "hasDefault", true>>
+  /** Primitive list (`String[]`). */
+  array(): Field<T, SetMeta<M, "array", true>>
+  /** `@id` — primary key (several → composite). A field literally named `id` is the key implicitly. */
+  id(): Field<T, SetMeta<M, "isId", true>>
+  /** Referential policy for `t.one()` (defaults: required → restrict, optional → setNull). */
+  onDelete(policy: OnDelete): Field<T, M>
+  /** `@fulltext(...)` module index on a string field; query with `$search`. */
+  fulltext(lang?: "multi" | "english" | "russian"): Field<T, M>
+  /** `Float[n] @vector(metric)` — nearest-neighbour index; query with `$near`. */
+  vector(size: number, metric?: "cosine" | "euclidean"): Field<T, M>
+}
+
+const create = <T, M extends FieldMeta>(def: FieldDef): Field<T, M> => {
+  const next = (patch: Partial<FieldDef>) => create<any, any>({ ...def, ...patch })
+  return {
+    def,
+    optional: () => next({ optional: true }),
+    unique: () => next({ unique: true }),
+    index: () => next({ index: true }),
+    default: (value: unknown) => next({ hasDefault: true, default: value }),
+    array: () => next({ array: true }),
+    id: () => next({ isId: true }),
+    onDelete: (policy) => next({ onDelete: policy }),
+    fulltext: (lang = "multi") => next({ fulltext: lang }),
+    vector: (size, metric = "cosine") => next({ vector: { size, metric } }),
+  } as Field<T, M>
+}
+
+const base = (kind: FieldKind, extra: Partial<FieldDef> = {}): FieldDef => ({
+  kind, optional: false, unique: false, index: false, hasDefault: false, array: false, isId: false, ...extra,
+})
+
+const scalar = <T, K extends ScalarKind>(scalar: K) =>
+  create<T, Meta<{ kind: "scalar", scalar: K }>>(base("scalar", { scalar }))
+
+export const t = {
+  string: () => scalar<string, "string">("string"),
+  /** 64-bit signed integer. */
+  int:    () => scalar<number, "int">("int"),
+  /** 64-bit float. */
+  float:  () => scalar<number, "float">("float"),
+  bool:   () => scalar<boolean, "bool">("bool"),
+  /** Epoch milliseconds — reads and writes as `number`. */
+  date:   () => scalar<number, "date">("date"),
+  /** UUID string (16 bytes in storage). On an `id` field the runtime generates it on insert. */
+  uuid:   () => scalar<string, "uuid">("uuid"),
+  /** Any JSON value; `J` is TS-only (marcidb stores it schemaless). Filter by dot-path in `$where`. */
+  json:   <J = JsonValue>() => create<J, Meta<{ kind: "json" }>>(base("json")),
+  /** String enum: `t.enum("draft", "published")`. */
+  enum:   <const V extends readonly [string, ...string[]]>(...values: V) =>
+            create<V[number], Meta<{ kind: "enum" }>>(base("enum", { values })),
+  /** Owned nested object (marcidb `struct`): created/updated with the parent, no id of its own. */
+  struct: <F extends Record<string, Field<any, any>>>(fields: F) =>
+            create<F, Meta<{ kind: "struct" }>>(base("struct", { fields })),
+  /** Reference to one row of `model` (by id). Required unless `.optional()`. */
+  one:    <N extends string>(model: N) => create<never, Meta<{ kind: "one", model: N }>>(base("one", { model })),
+  /** Reverse side of a `t.one()` on `model` (the field is inferred when unambiguous). Read-only list. */
+  many:   <N extends string>(model: N, backField?: string) =>
+            create<never, Meta<{ kind: "many", model: N }>>(base("many", { model, back: backField })),
+  /** Ordered relation list stored inline (`@list`) — hand-arranged collections, duplicates allowed. */
+  list:   <N extends string>(model: N) => create<never, Meta<{ kind: "list", model: N }>>(base("list", { model })),
+}
+export type T = typeof t