@bhooai/nexus-data 0.1.0

package/src/projects.ts

@@ -0,0 +1,185 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import type { Collection } from 'mongodb';
+import { connectionManager } from './connection/ConnectionManager.js';
+
+/** Shared database that stores one record per registered project. */
+export const PROJECT_INFO_DB = 'nexus_projects';
+
+const CONNECTION_NAME = 'project-info';
+const PROJECTS_COLLECTION = 'projects';
+
+/** A registered project's identity + runtime snapshot. */
+export interface ProjectInfo {
+  /** Canonical project name (package.json `name`). */
+  name: string;
+  /** Absolute path to the project root. */
+  path: string;
+  /** Per-project MongoDB database name (sanitized from `name`). */
+  dbName: string;
+  /** Redacted runtime snapshot (env, ports, paths, db). */
+  settings?: Record<string, unknown>;
+  /** Whether a backend instance is currently running. */
+  status?: 'running' | 'stopped';
+  /** App version when last seen running. */
+  version?: string;
+  startedAt?: string;
+  updatedAt?: string;
+}
+
+/**
+ * Derive a MongoDB-safe database name from a project name. Every project owns
+ * its own database (e.g. `sample-project` → `sample_project`).
+ */
+export function sanitizeDbName(name: string): string {
+  const clean = name
+    .toLowerCase()
+    .replace(/[^a-z0-9_]+/g, '_')
+    .replace(/_{2,}/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 63);
+  return clean || 'project';
+}
+
+/** Resolve the canonical project identity from a project root. */
+export async function resolveProjectInfo(root: string): Promise<ProjectInfo> {
+  let name = '';
+  try {
+    const pkg = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8')) as { name?: string };
+    name = pkg.name ?? '';
+  } catch { /* fall through to basename */ }
+  if (!name) name = root.split(/[\\/]/).filter(Boolean).pop() ?? 'project';
+  return { name, path: root, dbName: sanitizeDbName(name) };
+}
+
+/**
+ * Open the shared project-info database on a second connection. The main
+ * (default) connection keeps pointing at the per-project database.
+ */
+export function connectProjectInfo(uri: string, options: { autoIndex?: boolean } = {}): void {
+  connectionManager.connect(CONNECTION_NAME, uri, { name: PROJECT_INFO_DB, autoIndex: options.autoIndex });
+}
+
+/** The project-info `projects` collection (call `connectProjectInfo` first). */
+export function getProjectInfoCollection(): Promise<Collection<ProjectInfo>> {
+  return connectionManager.get(CONNECTION_NAME).db.then((db) => db.collection<ProjectInfo>(PROJECTS_COLLECTION));
+}
+
+let indexEnsured = false;
+async function ensureIndexes(): Promise<void> {
+  if (indexEnsured) return;
+  const coll = await getProjectInfoCollection();
+  await coll.createIndex({ name: 1 }, { unique: true });
+  indexEnsured = true;
+}
+
+/** Insert or update a project record in the shared project-info database. */
+export async function upsertProjectInfo(project: ProjectInfo): Promise<ProjectInfo> {
+  const coll = await getProjectInfoCollection();
+  await ensureIndexes();
+  const doc = { ...project, updatedAt: new Date().toISOString() };
+  await coll.updateOne({ name: project.name }, { $set: doc }, { upsert: true });
+  return doc;
+}
+
+/** List every registered project, alphabetical by name. */
+export async function listProjectInfo(): Promise<ProjectInfo[]> {
+  const coll = await getProjectInfoCollection();
+  await ensureIndexes();
+  return coll.find({}).sort({ name: 1 }).toArray();
+}
+
+/** Fetch a single project record by canonical name. */
+export async function getProjectInfo(name: string): Promise<ProjectInfo | null> {
+  const coll = await getProjectInfoCollection();
+  await ensureIndexes();
+  return coll.findOne({ name });
+}
+
+/** Delete a project record from the shared project-info database. */
+export async function deleteProjectInfo(name: string): Promise<boolean> {
+  const coll = await getProjectInfoCollection();
+  await ensureIndexes();
+  const r = await coll.deleteOne({ name });
+  return r.deletedCount > 0;
+}
+
+/** Drop a project's own database (the per-project one, NOT nexus_projects).
+ *  Uses the project-info connection's MongoClient to drop another db on the
+ *  same server — no second connection needed. */
+export async function dropProjectDatabase(dbName: string): Promise<boolean> {
+  const conn = connectionManager.get(CONNECTION_NAME);
+  await conn.db; // ensure the client has connected
+  return conn.client.db(dbName).dropDatabase();
+}
+
+/** Close the project-info connection (call during shutdown). */
+export async function closeProjectInfo(): Promise<void> {
+  if (connectionManager.has(CONNECTION_NAME)) await connectionManager.get(CONNECTION_NAME).close();
+}
+
+// ── cluster node registry (mirror of cluster.runtime.json in Mongo) ───────
+
+const CLUSTER_NODES_COLLECTION = 'cluster_nodes';
+
+/** One linked cluster node's registry record (mirrors cluster.runtime.json). */
+export interface ClusterNodeRecord {
+  /** Stable node id (e.g. `<host>-<role>`). */
+  id: string;
+  role: string;
+  tier: string;
+  version?: string;
+  baseUrl: string;
+  services?: Record<string, string>;
+  status: string;
+  enabled: boolean;
+  registeredAt: string;
+  lastSeenAt: string;
+  lastHealth?: unknown;
+  lastMetrics?: unknown;
+  updatedAt: string;
+}
+
+/** The cluster_nodes collection (call `connectProjectInfo` first). */
+export function getClusterNodesCollection(): Promise<Collection<ClusterNodeRecord>> {
+  return connectionManager.get(CONNECTION_NAME).db.then((db) => db.collection<ClusterNodeRecord>(CLUSTER_NODES_COLLECTION));
+}
+
+let clusterNodesIndexEnsured = false;
+
+/** Upsert a cluster node record by id (mirrors registry.save for one node). */
+export async function upsertClusterNode(node: ClusterNodeRecord): Promise<void> {
+  const coll = await getClusterNodesCollection();
+  if (!clusterNodesIndexEnsured) {
+    await coll.createIndex({ id: 1 }, { unique: true });
+    clusterNodesIndexEnsured = true;
+  }
+  await coll.updateOne({ id: node.id }, { $set: node }, { upsert: true });
+}
+
+/** Delete a cluster node record by id (mirrors registry.remove). */
+export async function deleteClusterNode(id: string): Promise<boolean> {
+  const coll = await getClusterNodesCollection();
+  const r = await coll.deleteOne({ id });
+  return r.deletedCount > 0;
+}
+
+/** List all cluster node records (mirrors registry.list). */
+export async function listClusterNodes(): Promise<ClusterNodeRecord[]> {
+  const coll = await getClusterNodesCollection();
+  return coll.find({}).sort({ role: 1, id: 1 }).toArray();
+}
+
+/** Replace all cluster node records (bulk sync — used after a full reload). */
+export async function syncClusterNodes(nodes: ClusterNodeRecord[]): Promise<void> {
+  const coll = await getClusterNodesCollection();
+  if (!clusterNodesIndexEnsured) {
+    await coll.createIndex({ id: 1 }, { unique: true });
+    clusterNodesIndexEnsured = true;
+  }
+  const ops = nodes.map((n) => ({ updateOne: { filter: { id: n.id }, update: { $set: n }, upsert: true } }));
+  if (ops.length) await coll.bulkWrite(ops as never);
+  // Remove records no longer in the registry.
+  const ids = nodes.map((n) => n.id);
+  await coll.deleteMany({ id: { $nin: ids } });
+}

package/src/query/Query.ts

@@ -0,0 +1,158 @@
+import type { DocumentInstance } from '../model/Document.js';
+import type { Model } from '../model/Model.js';
+
+type Op = 'find' | 'findOne';
+
+interface PopulatePath {
+  path: string;
+  select?: string;
+  match?: Record<string, unknown>;
+}
+
+/**
+ * Fluent, thenable query builder. Accumulates filter/projection/sort/limit/skip/
+ * populate options and compiles them to a mongo driver call on `then()` or
+ * `exec()`. Hydrates results into Document instances unless `lean()` is used.
+ */
+export class Query<T extends DocumentInstance> {
+  private filter: Record<string, unknown>;
+  private projection: Record<string, 0 | 1> | undefined;
+  private sortSpec: Record<string, 1 | -1> | undefined;
+  private limitVal = 0;
+  private skipVal = 0;
+  private populatePaths: PopulatePath[] = [];
+  private leanFlag = false;
+  private sessionRef?: { session: unknown };
+
+  constructor(
+    private model: Model<T>,
+    private op: Op,
+    filter: Record<string, unknown>,
+  ) {
+    this.filter = { ...filter };
+  }
+
+  // ── Filter helpers ─────────────────────────────────────────────────────
+  where(path: string, value: unknown): this { this.filter[path] = value; return this; }
+  gt(path: string, value: unknown): this { return this.op2(path, '$gt', value); }
+  gte(path: string, value: unknown): this { return this.op2(path, '$gte', value); }
+  lt(path: string, value: unknown): this { return this.op2(path, '$lt', value); }
+  lte(path: string, value: unknown): this { return this.op2(path, '$lte', value); }
+  in(path: string, values: unknown[]): this { return this.op2(path, '$in', values); }
+  nin(path: string, values: unknown[]): this { return this.op2(path, '$nin', values); }
+  ne(path: string, value: unknown): this { return this.op2(path, '$ne', value); }
+  exists(path: string, yes = true): this { return this.op2(path, '$exists', yes); }
+
+  private op2(path: string, op: string, value: unknown): this {
+    const current = this.filter[path];
+    if (current && typeof current === 'object' && !Array.isArray(current) && !(current instanceof Date)) {
+      (current as Record<string, unknown>)[op] = value;
+    } else {
+      this.filter[path] = { [op]: value };
+    }
+    return this;
+  }
+
+  // ── Shaping ────────────────────────────────────────────────────────────
+  sort(spec: string | Record<string, 1 | -1>): this {
+    if (typeof spec === 'string') {
+      this.sortSpec = {};
+      for (const part of spec.split(' ')) {
+        if (!part) continue;
+        const desc = part.startsWith('-');
+        this.sortSpec[desc ? part.slice(1) : part] = desc ? -1 : 1;
+      }
+    } else {
+      this.sortSpec = spec;
+    }
+    return this;
+  }
+
+  limit(n: number): this { this.limitVal = n; return this; }
+  skip(n: number): this { this.skipVal = n; return this; }
+
+  select(fields: string): this {
+    this.projection = {};
+    for (const part of fields.split(' ')) {
+      if (!part) continue;
+      const exclude = part.startsWith('-');
+      this.projection[exclude ? part.slice(1) : part] = exclude ? 0 : 1;
+    }
+    return this;
+  }
+
+  populate(path: string, opts: { select?: string; match?: Record<string, unknown> } = {}): this {
+    this.populatePaths.push({ path, select: opts.select, match: opts.match });
+    return this;
+  }
+
+  lean(): this { this.leanFlag = true; return this; }
+  session(session: unknown): this { this.sessionRef = { session }; return this; }
+
+  // ── Execution ──────────────────────────────────────────────────────────
+  async exec(): Promise<T[] | T | null> {
+    const schema = this.model.schema;
+    // pre('find') / pre('findOne') hooks receive the query's filter for mutation.
+    const hookCtx = { filter: this.filter, model: this.model, op: this.op };
+    await runFindHooks(schema.preHooks, this.op, hookCtx);
+    this.filter = hookCtx.filter;
+
+    const coll = await this.model.collection;
+    const options: Record<string, unknown> = {};
+    // Default projection: exclude fields flagged select:false unless caller set an explicit projection.
+    if (this.projection) {
+      options.projection = this.projection;
+    } else {
+      const excluded: Record<string, 0> = {};
+      let hasExcluded = false;
+      for (const [path, field] of schema.compiledPaths) {
+        if (field.select === false) { excluded[path] = 0; hasExcluded = true; }
+      }
+      if (hasExcluded) options.projection = excluded;
+    }
+    if (this.sessionRef) options.session = this.sessionRef.session;
+    if (this.sortSpec) options.sort = this.sortSpec;
+    if (this.limitVal) options.limit = this.limitVal;
+    if (this.skipVal) options.skip = this.skipVal;
+
+    if (this.op === 'find') {
+      const cursor = coll.find(this.filter, options);
+      const docs = await cursor.toArray();
+      let result: unknown[] = this.leanFlag ? docs : docs.map((d) => this.model.hydrate(d));
+      if (this.populatePaths.length && !this.leanFlag) {
+        const { populate } = await import('../populate/populate.js');
+        await populate(this.model.connection, result as DocumentInstance[], this.populatePaths);
+      }
+      await runFindHooks(schema.postHooks, 'find', { docs: result, ...hookCtx });
+      return result as T[];
+    } else {
+      const doc = await coll.findOne(this.filter, options);
+      if (!doc) return null;
+      const result = this.leanFlag ? doc : this.model.hydrate(doc);
+      if (this.populatePaths.length && !this.leanFlag) {
+        const { populate } = await import('../populate/populate.js');
+        await populate(this.model.connection, [result as DocumentInstance], this.populatePaths);
+      }
+      await runFindHooks(schema.postHooks, 'findOne', { doc: result, ...hookCtx });
+      return result as T;
+    }
+  }
+
+  // ── Thenable ───────────────────────────────────────────────────────────
+  then<TResult1 = T[] | T | null, TResult2 = never>(
+    onFulfilled?: (value: T[] | T | null) => TResult1 | PromiseLike<TResult1>,
+    onRejected?: (reason: unknown) => TResult2 | PromiseLike<TResult2>,
+  ): Promise<TResult1 | TResult2> {
+    return this.exec().then(onFulfilled, onRejected);
+  }
+}
+
+async function runFindHooks(
+  hooks: Map<string, Array<(ctx: unknown) => unknown | Promise<unknown>>>,
+  op: string,
+  ctx: unknown,
+): Promise<void> {
+  const list = hooks.get(op);
+  if (!list) return;
+  for (const fn of list) await fn.call(ctx, ctx);
+}

package/src/schema/Schema.ts

@@ -0,0 +1,173 @@
+import { coerce, typeOf, type SchemaTypeToken } from './SchemaType.js';
+import { ValidationError } from '../../../nexus-core/src/index.js';
+import {
+  type CompiledField,
+  type FieldDefinition,
+  type IndexSpec,
+  type SchemaOptions,
+  type SchemaDefinition,
+} from './validators.js';
+
+export class NexusSchema<T = unknown> {
+  compiledPaths = new Map<string, CompiledField>();
+  indexes: IndexSpec[] = [];
+  options: SchemaOptions;
+  virtuals = new Map<string, { get?: () => unknown; set?: (v: unknown) => void }>();
+  preHooks = new Map<string, Array<(ctx: unknown) => unknown | Promise<unknown>>>();
+  postHooks = new Map<string, Array<(ctx: unknown) => unknown | Promise<unknown>>>();
+  methods: Record<string, (...args: unknown[]) => unknown> = {};
+  statics: Record<string, (...args: unknown[]) => unknown> = {};
+
+  constructor(definition: SchemaDefinition = {}, options: SchemaOptions = {}) {
+    this.options = { timestamps: false, versionKey: '__v', strict: true, ...options };
+    for (const [path, raw] of Object.entries(definition)) {
+      this.define(path, normalizeField(raw));
+    }
+    if (this.options.timestamps) {
+      const ts = this.options.timestamps === true ? { createdAt: 'createdAt', updatedAt: 'updatedAt' } : this.options.timestamps;
+      if (ts.createdAt && !this.compiledPaths.has(ts.createdAt)) {
+        this.define(ts.createdAt, { type: Date });
+      }
+      if (ts.updatedAt && !this.compiledPaths.has(ts.updatedAt)) {
+        this.define(ts.updatedAt, { type: Date });
+      }
+    }
+  }
+
+  define(path: string, def: FieldDefinition): void {
+    const token = resolveToken(def.type);
+    const validators = def.validate ? (Array.isArray(def.validate) ? def.validate : [def.validate]) : [];
+    const isRef = !!def.ref || !!def.refPath;
+    this.compiledPaths.set(path, {
+      token,
+      isRef,
+      ref: def.ref,
+      refPath: def.refPath,
+      required: def.required ?? false,
+      hasDefault: def.default !== undefined,
+      default: def.default,
+      enum: def.enum,
+      min: def.min,
+      max: def.max,
+      match: def.match,
+      validators,
+      select: def.select ?? true,
+      immutable: def.immutable ?? false,
+      transform: def.transform,
+      isEmbedded: false,
+    });
+    if (def.unique) {
+      this.indexes.push({ spec: { [path]: 1 }, options: { unique: true, sparse: def.sparse ?? false } });
+    } else if (def.index) {
+      const opts = typeof def.index === 'object' ? def.index : {};
+      this.indexes.push({ spec: { [path]: 1 }, options: opts });
+    }
+    if (def.expires) {
+      this.indexes.push({ spec: { [path]: 1 }, options: { expireAfterSeconds: def.expires } });
+    }
+  }
+
+  virtual(path: string, opts: { get?: () => unknown; set?: (v: unknown) => void } = {}): void {
+    this.virtuals.set(path, opts);
+  }
+
+  pre(event: string, fn: (ctx: unknown) => unknown | Promise<unknown>): void {
+    const list = this.preHooks.get(event) ?? [];
+    list.push(fn);
+    this.preHooks.set(event, list);
+  }
+
+  post(event: string, fn: (ctx: unknown) => unknown | Promise<unknown>): void {
+    const list = this.postHooks.get(event) ?? [];
+    list.push(fn);
+    this.postHooks.set(event, list);
+  }
+
+  method(name: string, fn: (...args: unknown[]) => unknown): void {
+    this.methods[name] = fn;
+  }
+
+  staticMethod(name: string, fn: (...args: unknown[]) => unknown): void {
+    this.statics[name] = fn;
+  }
+
+  /** Apply defaults for missing fields to a plain object. */
+  applyDefaults(doc: Record<string, unknown>): Record<string, unknown> {
+    for (const [path, field] of this.compiledPaths) {
+      if (doc[path] === undefined && field.hasDefault) {
+        doc[path] = typeof field.default === 'function' ? (field.default as () => unknown)() : field.default;
+      }
+    }
+    return doc;
+  }
+
+  /** Validate + coerce a document object; throws CoreValidationError on failure. */
+  validate(doc: Record<string, unknown>): void {
+    const errors: Array<{ path: string; message: string }> = [];
+    const strict = this.options.strict;
+
+    for (const [path, field] of this.compiledPaths) {
+      const value = doc[path];
+      const required = typeof field.required === 'function' ? field.required() : field.required;
+      if (value === undefined || value === null) {
+        if (required) errors.push({ path, message: `Path \`${path}\` is required.` });
+        continue;
+      }
+      let coerced: unknown;
+      try {
+        coerced = coerce(field.token, value);
+      } catch (e) {
+        errors.push({ path, message: (e as Error).message });
+        continue;
+      }
+      if (field.transform) coerced = field.transform(coerced);
+      if (field.enum && !field.enum.includes(coerced)) {
+        errors.push({ path, message: `\`${path}\` must be one of the enum values ${JSON.stringify(field.enum)}.` });
+      }
+      if (field.token === 'Number' && typeof coerced === 'number') {
+        if (field.min !== undefined && coerced < field.min) errors.push({ path, message: `\`${path}\` must be >= ${field.min}.` });
+        if (field.max !== undefined && coerced > field.max) errors.push({ path, message: `\`${path}\` must be <= ${field.max}.` });
+      }
+      if (field.token === 'String' && typeof coerced === 'string' && field.match && !field.match.test(coerced)) {
+        errors.push({ path, message: `\`${path}\` format is invalid.` });
+      }
+      for (const v of field.validators) {
+        if (!v.validator(coerced)) errors.push({ path, message: v.message });
+      }
+      doc[path] = coerced;
+    }
+
+    if (strict === true) {
+      for (const key of Object.keys(doc)) {
+        if (!this.compiledPaths.has(key) && !this.virtuals.has(key) && key !== '_id') {
+          delete doc[key];
+        }
+      }
+    } else if (strict === 'throw') {
+      for (const key of Object.keys(doc)) {
+        if (!this.compiledPaths.has(key) && !this.virtuals.has(key) && key !== '_id') {
+          errors.push({ path: key, message: `Path \`${key}\` is not in schema.` });
+        }
+      }
+    }
+
+    if (errors.length) {
+      throw new ValidationError(`Validation failed: ${errors.map((e) => e.message).join('; ')}`, errors);
+    }
+  }
+}
+
+function normalizeField(raw: unknown): FieldDefinition {
+  if (raw && typeof raw === 'object' && 'type' in (raw as Record<string, unknown>)) {
+    return raw as FieldDefinition;
+  }
+  return { type: raw };
+}
+
+function resolveToken(type: unknown): SchemaTypeToken {
+  if (Array.isArray(type)) return 'Array';
+  if (type instanceof NexusSchema) return 'Mixed';
+  if (typeof type === 'string') return type as SchemaTypeToken;
+  if (typeof type === 'function') return typeOf(type);
+  return 'Mixed';
+}

package/src/schema/SchemaType.ts

@@ -0,0 +1,80 @@
+import { ObjectId, Decimal128, Binary } from 'mongodb';
+
+/** Primitive type tokens understood by the ODM. */
+export type SchemaTypeToken =
+  | 'String'
+  | 'Number'
+  | 'Boolean'
+  | 'Date'
+  | 'Buffer'
+  | 'ObjectId'
+  | 'Decimal128'
+  | 'Mixed'
+  | 'Array'
+  | 'Map';
+
+/** Map a JS constructor to a type token. */
+export function typeOf(ctor: unknown): SchemaTypeToken {
+  switch (ctor) {
+    case String: return 'String';
+    case Number: return 'Number';
+    case Boolean: return 'Boolean';
+    case Date: return 'Date';
+    case Buffer: return 'Buffer';
+    case ObjectId: return 'ObjectId';
+    case Decimal128: return 'Decimal128';
+    case Binary: return 'Buffer';
+    case Object: return 'Mixed';
+    case Array: return 'Array';
+    case Map: return 'Map';
+    default: return 'Mixed';
+  }
+}
+
+/** Coerce a value to the target type, throwing on impossible coercion. */
+export function coerce(token: SchemaTypeToken, value: unknown): unknown {
+  if (value === undefined || value === null) return value;
+  switch (token) {
+    case 'String':
+      if (typeof value === 'string') return value;
+      if (typeof value === 'number' || typeof value === 'boolean' || value instanceof Date) return String(value);
+      if (value instanceof ObjectId) return value.toHexString();
+      throw new TypeError(`Cannot coerce ${typeof value} to String`);
+    case 'Number': {
+      const n = Number(value);
+      if (Number.isNaN(n)) throw new TypeError(`Cannot coerce ${JSON.stringify(value)} to Number`);
+      return n;
+    }
+    case 'Boolean':
+      if (typeof value === 'boolean') return value;
+      if (value === 'true' || value === 1 || value === '1') return true;
+      if (value === 'false' || value === 0 || value === '0') return false;
+      throw new TypeError(`Cannot coerce ${JSON.stringify(value)} to Boolean`);
+    case 'Date': {
+      if (value instanceof Date) return value;
+      const d = new Date(value as string);
+      if (Number.isNaN(d.getTime())) throw new TypeError(`Cannot coerce ${JSON.stringify(value)} to Date`);
+      return d;
+    }
+    case 'Buffer':
+      if (Buffer.isBuffer(value)) return value;
+      if (typeof value === 'string') return Buffer.from(value, 'utf8');
+      throw new TypeError('Cannot coerce value to Buffer');
+    case 'ObjectId':
+      if (value instanceof ObjectId) return value;
+      if (typeof value === 'string' && /^[0-9a-fA-F]{24}$/.test(value)) return new ObjectId(value);
+      throw new TypeError(`Cannot coerce ${JSON.stringify(value)} to ObjectId`);
+    case 'Decimal128':
+      if (value instanceof Decimal128) return value;
+      if (typeof value === 'string' || typeof value === 'number') return Decimal128.fromString(String(value));
+      throw new TypeError('Cannot coerce value to Decimal128');
+    case 'Mixed':
+    case 'Array':
+    case 'Map':
+      return value;
+    default:
+      return value;
+  }
+}
+
+export { ObjectId, Decimal128 };

package/src/schema/validators.ts

@@ -0,0 +1,88 @@
+import { coerce, typeOf, type SchemaTypeToken } from './SchemaType.js';
+
+export interface FieldValidator {
+  validator: (value: unknown) => boolean;
+  message: string;
+}
+
+export interface FieldDefinition {
+  /** A JS constructor, an array `[Constructor]`, a nested Schema, or a type token. */
+  type: unknown;
+  required?: boolean | (() => boolean);
+  default?: unknown | (() => unknown);
+  enum?: unknown[];
+  min?: number;
+  max?: number;
+  match?: RegExp;
+  validate?: FieldValidator | FieldValidator[];
+  ref?: string; // model name for population
+  refPath?: string; // dynamic ref field
+  select?: boolean; // exclude from queries by default when false
+  immutable?: boolean;
+  expires?: number; // TTL index seconds
+  index?: boolean | Record<string, unknown>;
+  unique?: boolean;
+  sparse?: boolean;
+  transform?: (value: unknown) => unknown;
+}
+
+export interface CompiledField {
+  token: SchemaTypeToken;
+  isRef: boolean;
+  ref?: string;
+  refPath?: string;
+  required: boolean | (() => boolean);
+  hasDefault: boolean;
+  default: unknown | (() => unknown);
+  enum?: unknown[];
+  min?: number;
+  max?: number;
+  match?: RegExp;
+  validators: FieldValidator[];
+  select: boolean;
+  immutable: boolean;
+  transform?: (value: unknown) => unknown;
+  isEmbedded: boolean;
+  embeddedSchema?: Schema;
+}
+
+export interface IndexSpec {
+  spec: Record<string, 1 | -1>;
+  options: Record<string, unknown>;
+}
+
+/** A field-validation error with a path. */
+export interface FieldError {
+  path: string;
+  message: string;
+}
+
+/** Self-referencing type for embedded schemas. */
+export interface Schema {
+  compiledPaths: Map<string, CompiledField>;
+  indexes: IndexSpec[];
+  options: SchemaOptions;
+  virtuals: Map<string, { get?: () => unknown; set?: (v: unknown) => void }>;
+  preHooks: Map<string, Array<(ctx: unknown) => unknown | Promise<unknown>>>;
+  postHooks: Map<string, Array<(ctx: unknown) => unknown | Promise<unknown>>>;
+  methods: Record<string, (...args: unknown[]) => unknown>;
+  statics: Record<string, (...args: unknown[]) => unknown>;
+  define(path: string, def: FieldDefinition): void;
+  virtual(path: string, opts?: { get?: () => unknown; set?: (v: unknown) => void }): void;
+  pre(event: string, fn: (ctx: unknown) => unknown | Promise<unknown>): void;
+  post(event: string, fn: (ctx: unknown) => unknown | Promise<unknown>): void;
+  method(name: string, fn: (...args: unknown[]) => unknown): void;
+  staticMethod(name: string, fn: (...args: unknown[]) => unknown): void;
+}
+
+export interface SchemaOptions {
+  timestamps?: boolean | { createdAt?: string; updatedAt?: string };
+  collection?: string;
+  discriminatorKey?: string;
+  versionKey?: string | false;
+  strict?: boolean | 'throw';
+}
+
+export interface SchemaDefinition {
+  [path: string]: FieldDefinition | unknown;
+}