@avelonjs/orm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Yannelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# @avelonjs/orm
+
+`@avelonjs/orm` is Scrivener, Avelon's model layer. It builds serializable `QueryIR` and never imports a database vendor. Reach for this package when application code needs models, fluent queries, ward injection, relation loads, casts, timestamps, soft deletes, or lifecycle hooks.
+
+## Installation
+
+```sh
+bun add @avelonjs/orm
+```
+
+## Basic Usage
+
+```ts
+import { Model } from '@avelonjs/orm'
+import { defineConfig } from '@avelonjs/core'
+import type { DatabaseDriver } from '@avelonjs/core'
+
+export function boot(database: DatabaseDriver) {
+  defineConfig({
+    name: 'app',
+    drivers: { database },
+  })
+}
+
+export class Post extends Model {
+  static override table = 'posts'
+  static override fillable = ['title', 'body', 'user_id']
+  static override casts = { published_at: 'datetime' } as const
+  static override timestamps = true
+  static override softDeletes = true
+
+  declare id: string
+  declare title: string
+  declare body: string
+  declare user_id: string
+  declare published_at: Date | null
+
+  author() {
+    return this.belongsTo(User, 'user_id')
+  }
+
+  static published() {
+    return this.query().whereNotNull('published_at')
+  }
+}
+
+export class User extends Model {
+  static override table = 'users'
+  static override fillable = ['email', 'name']
+}
+
+export async function latestPublished() {
+  return Post.published().with('author').latest('published_at').paginate(15)
+}
+```
+
+## Query Builder
+
+The builder accumulates predicates, ordering, limits, relations, and wards, then emits `QueryIR` for the configured database driver. `where('age', 20)` equals `where('age', '=', 20)`. `orWhere` wraps the accumulated predicates in an `or` node. `paginate` uses count mode for the total.
+
+## Models
+
+Models declare a table, fillable attributes, optional casts, timestamps, and soft deletes. Use `declare` for attributes so hydration is not overwritten by emitted class fields. `findOrFail` raises `NotFound`. `forActor` injects the actor's ward. `Scrivener.unwarded(Post).query()` skips ward injection and is restricted by Bailiff to errands and seeds.
+
+## Lifecycle Hooks
+
+Writes dispatch `ModelLifecycle` on the same event bus as application events. A `creating` listener that returns `false` (or calls `stopPropagation`) aborts the insert.
+
+```ts
+import { Events, defineListener } from '@avelonjs/core'
+import { ModelLifecycle } from '@avelonjs/orm'
+
+Events.listen(
+  ModelLifecycle,
+  defineListener({
+    handle: (event) => {
+      if (event.hook === 'creating' && event.modelName === 'Post') return false
+    },
+  }),
+)
+```
+
+## Method Reference
+
+| Method                        | Signature                                                                          | Description                                        |
+| ----------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `query`                       | `(table: string, driver?: DatabaseDriver) => QueryBuilder`                         | Starts a fluent builder for a table.               |
+| `QueryBuilder.select`         | `(...columns: string[]) => this`                                                   | Sets the projection.                               |
+| `QueryBuilder.where`          | `(column: string, opOrValue: CompareOp \| unknown, value?: unknown) => this`       | Adds a comparison predicate.                       |
+| `QueryBuilder.wherePredicate` | `(predicate: Predicate) => this`                                                   | Adds an arbitrary predicate.                       |
+| `QueryBuilder.whereNull`      | `(column: string) => this`                                                         | Constrains a column to be null.                    |
+| `QueryBuilder.whereNotNull`   | `(column: string) => this`                                                         | Constrains a column to be non-null.                |
+| `QueryBuilder.whereIn`        | `(column: string, values: readonly unknown[]) => this`                             | Constrains a column to a list.                     |
+| `QueryBuilder.orWhere`        | `(column: string, opOrValue: CompareOp \| unknown, value?: unknown) => this`       | ORs a comparison with accumulated predicates.      |
+| `QueryBuilder.orderBy`        | `(column: string, direction?: 'asc' \| 'desc', nulls?: 'first' \| 'last') => this` | Orders results.                                    |
+| `QueryBuilder.latest`         | `(column?: string) => this`                                                        | Orders descending by a timestamp column.           |
+| `QueryBuilder.limit`          | `(count: number) => this`                                                          | Limits rows.                                       |
+| `QueryBuilder.offset`         | `(count: number) => this`                                                          | Offsets rows.                                      |
+| `QueryBuilder.with`           | `(relation: string \| RelationLoad) => this`                                       | Eager-loads a relation method or descriptor.       |
+| `QueryBuilder.ward`           | `(predicate: WardInput) => this`                                                   | Injects a ward predicate.                          |
+| `QueryBuilder.unwarded`       | `() => this`                                                                       | Skips registered ward injection.                   |
+| `QueryBuilder.withTrashed`    | `() => this`                                                                       | Includes soft-deleted rows.                        |
+| `QueryBuilder.toIR`           | `(mode?: QueryIR['mode']) => QueryIR`                                              | Builds serializable IR.                            |
+| `QueryBuilder.get`            | `() => Promise<readonly TModel[]>`                                                 | Executes a select and hydrates models.             |
+| `QueryBuilder.first`          | `() => Promise<TModel \| null>`                                                    | Returns the first hydrated model.                  |
+| `QueryBuilder.count`          | `() => Promise<number>`                                                            | Executes a count.                                  |
+| `QueryBuilder.paginate`       | `(perPage: number, page?: number) => Promise<Page<TModel>>`                        | Counts and selects one page.                       |
+| `QueryBuilder.insert`         | `(values: Row \| Row[], returning?: string[] \| '*') => Promise<QueryResult>`      | Inserts rows.                                      |
+| `QueryBuilder.update`         | `(values: Row, returning?: string[] \| '*') => Promise<QueryResult>`               | Updates matching rows.                             |
+| `QueryBuilder.delete`         | `(returning?: string[] \| '*') => Promise<QueryResult>`                            | Deletes or soft-deletes matching rows.             |
+| `Model.query`                 | `(driver?) => QueryBuilder`                                                        | Starts a warded query for the model.               |
+| `Model.find`                  | `(id: string \| number) => Promise<TModel \| null>`                                | Finds by primary key.                              |
+| `Model.findOrFail`            | `(id: string \| number) => Promise<TModel>`                                        | Finds by primary key or throws `NotFound`.         |
+| `Model.create`                | `(values: Row) => Promise<TModel>`                                                 | Mass-assigns fillable attributes and saves.        |
+| `Model.forActor`              | `(actor: GateActor) => QueryBuilder`                                               | Starts a query warded for an actor.                |
+| `Model.withTrashed`           | `() => QueryBuilder`                                                               | Starts a query that includes soft-deleted rows.    |
+| `Model.fill`                  | `(values: Row, raw?: boolean) => this`                                             | Copies fillable attributes onto the instance.      |
+| `Model.save`                  | `(driver?) => Promise<this>`                                                       | Persists the instance and fires lifecycle hooks.   |
+| `Model.update`                | `(values: Row) => Promise<this>`                                                   | Fills and saves.                                   |
+| `Model.delete`                | `(driver?) => Promise<void>`                                                       | Deletes or soft-deletes the instance.              |
+| `Model.restore`               | `(driver?) => Promise<this>`                                                       | Clears `deleted_at` on a soft-deleted instance.    |
+| `Model.belongsTo`             | `(related, foreignKey, ownerKey?) => RelationLoad`                                 | Builds a belongsTo descriptor.                     |
+| `Model.hasOne`                | `(related, foreignKey, localKey?) => RelationLoad`                                 | Builds a hasOne descriptor.                        |
+| `Model.hasMany`               | `(related, foreignKey, localKey?) => RelationLoad`                                 | Builds a hasMany descriptor.                       |
+| `Scrivener.unwarded`          | `(model) => { query: () => QueryBuilder }`                                         | Starts an unwarded query.                          |
+| `ModelLifecycle`              | `class ModelLifecycle extends Event`                                               | Hook name, model name, and instance for observers. |
+| `ModelHook`                   | `type`                                                                             | `'creating' \| 'created' \| 'updating' \| 'updated' \| 'saving' \| 'saved' \| 'deleting' \| 'deleted' \| 'restored'` |
+| `Page`                        | `interface Page<TModel>`                                                           | `data`, `total`, `perPage`, `page`, and `lastPage` from `paginate`. |
+
+## Testing
+
+Point `defineConfig` at `FakeDatabase` from `@avelonjs/conformance` and assert on `toIR()` output or hydrated models.
+
+```ts
+import { defineConfig } from '@avelonjs/core'
+import { FakeDatabase } from '@avelonjs/conformance'
+import { Model } from '@avelonjs/orm'
+
+defineConfig({ name: 'test', drivers: { database: new FakeDatabase() } })
+
+export class User extends Model {
+  static override table = 'assay_users'
+  static override fillable = ['id', 'email', 'name', 'age', 'nickname']
+}
+
+await User.create({
+  id: 'u1',
+  email: 'one@example.test',
+  name: 'One',
+  age: 20,
+  nickname: null,
+})
+```

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@avelonjs/orm",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Model layer and QueryIR builder for Avelon applications.",
+  "license": "MIT",
+  "author": "Ryan Yannelli <ryanyannelli@gmail.com>",
+  "homepage": "https://github.com/yannelli/avelon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yannelli/avelon.git",
+    "directory": "packages/orm"
+  },
+  "bugs": {
+    "url": "https://github.com/yannelli/avelon/issues"
+  },
+  "keywords": [
+    "avelon",
+    "typescript",
+    "orm",
+    "query-ir"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@avelonjs/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@avelonjs/conformance": "workspace:*",
+    "@types/bun": "1.3.14",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export {
+  Model,
+  ModelLifecycle,
+  QueryBuilder,
+  query,
+  Scrivener,
+  type ModelHook,
+  type Page,
+} from './model'

package/src/model.ts

@@ -0,0 +1,655 @@
+import {
+  DB,
+  Event,
+  Events,
+  Gate,
+  Invalid,
+  NotFound,
+  injectWard,
+  resolveWard,
+  type CompareOp,
+  type DatabaseDriver,
+  type DatabaseTransaction,
+  type GateActor,
+  type OrderTerm,
+  type Predicate,
+  type QueryIR,
+  type QueryResult,
+  type RelationLoad,
+  type WardInput,
+} from '@avelonjs/core'
+
+type Row = Record<string, unknown>
+type CastKind = 'datetime' | 'json' | 'number' | 'boolean'
+
+/** Lifecycle hooks dispatched on the shared event bus. */
+export type ModelHook =
+  | 'creating'
+  | 'created'
+  | 'updating'
+  | 'updated'
+  | 'saving'
+  | 'saved'
+  | 'deleting'
+  | 'deleted'
+  | 'restored'
+
+/** Event fired for every model lifecycle hook so observers are ordinary listeners. */
+export class ModelLifecycle extends Event {
+  constructor(
+    readonly modelName: string,
+    readonly hook: ModelHook,
+    readonly model: Model,
+  ) {
+    super()
+  }
+}
+
+/** Page of hydrated models returned by `paginate`. */
+export interface Page<TModel> {
+  data: readonly TModel[]
+  total: number
+  perPage: number
+  page: number
+  lastPage: number
+}
+
+type ModelClass = typeof Model & { new (): Model }
+
+function ctorOf(model: Model): ModelClass {
+  return model.constructor as ModelClass
+}
+
+function tableOf(modelClass: ModelClass): string {
+  return modelClass.table
+}
+
+function keyOf(modelClass: ModelClass): string {
+  return modelClass.key
+}
+
+function asRecord(model: Model): Row {
+  return model as unknown as Row
+}
+
+function read(model: Model, column: string): unknown {
+  return asRecord(model)[column]
+}
+
+function write(model: Model, column: string, value: unknown): void {
+  asRecord(model)[column] = value
+}
+
+function castIn(kind: CastKind | undefined, value: unknown): unknown {
+  if (kind === undefined || value === null || value === undefined) return value
+  switch (kind) {
+    case 'datetime':
+      return value instanceof Date ? value : new Date(String(value))
+    case 'json':
+      return typeof value === 'string' ? (JSON.parse(value) as unknown) : value
+    case 'number':
+      return typeof value === 'number' ? value : Number(value)
+    case 'boolean':
+      return Boolean(value)
+  }
+}
+
+function castOut(kind: CastKind | undefined, value: unknown): unknown {
+  if (kind === undefined || value === null || value === undefined) return value
+  switch (kind) {
+    case 'datetime':
+      return value instanceof Date ? value.toISOString() : value
+    case 'json':
+      return typeof value === 'string' ? value : JSON.stringify(value)
+    case 'number':
+    case 'boolean':
+      return value
+  }
+}
+
+function fillableKeys(modelClass: ModelClass, values: Row, raw: boolean): string[] {
+  if (raw) return Object.keys(values)
+  return modelClass.fillable.filter((key) => Object.hasOwn(values, key))
+}
+
+async function fire(model: Model, hook: ModelHook): Promise<boolean> {
+  const event = new ModelLifecycle(ctorOf(model).name, hook, model)
+  await Events.dispatch(event)
+  return !event.isPropagationStopped()
+}
+
+/** Fluent query builder that emits portable `QueryIR` and hydrates models. */
+export class QueryBuilder<TModel extends Model = Model> {
+  readonly #model: ModelClass
+  readonly #driver: DatabaseDriver | DatabaseTransaction
+  #select: string[] | '*' = '*'
+  #where: Predicate[] = []
+  #order: OrderTerm[] = []
+  #relations: RelationLoad[] = []
+  #limit: number | undefined
+  #offset: number | undefined
+  #ward: WardInput | undefined
+  #unwarded = false
+  #withTrashed = false
+  #actor: GateActor | undefined
+
+  constructor(
+    model: ModelClass,
+    driver: DatabaseDriver | DatabaseTransaction = DB.driver,
+    options: { unwarded?: boolean; withTrashed?: boolean; actor?: GateActor } = {},
+  ) {
+    this.#model = model
+    this.#driver = driver
+    this.#unwarded = options.unwarded ?? false
+    this.#withTrashed = options.withTrashed ?? false
+    this.#actor = options.actor
+  }
+
+  /** Starts an unwarded builder. Restricted by Bailiff to errands and seeds. */
+  unwarded(): this {
+    this.#unwarded = true
+    return this
+  }
+
+  /** Includes soft-deleted rows. */
+  withTrashed(): this {
+    this.#withTrashed = true
+    return this
+  }
+
+  /** Restricts the projection. */
+  select(...columns: string[]): this {
+    this.#select = columns.length === 0 ? '*' : columns
+    return this
+  }
+
+  /**
+   * Adds a comparison predicate.
+   *
+   * `where('age', 20)` equals `where('age', '=', 20)`.
+   */
+  where(column: string, opOrValue: CompareOp | unknown, value?: unknown): this {
+    if (value === undefined) {
+      this.#where.push({ kind: 'compare', column, op: '=', value: opOrValue })
+    } else {
+      this.#where.push({
+        kind: 'compare',
+        column,
+        op: opOrValue as CompareOp,
+        value,
+      })
+    }
+    return this
+  }
+
+  /** Adds a raw predicate object. */
+  wherePredicate(predicate: Predicate): this {
+    this.#where.push(predicate)
+    return this
+  }
+
+  /** Constrains a column to be null. */
+  whereNull(column: string): this {
+    this.#where.push({ kind: 'null', column, negated: false })
+    return this
+  }
+
+  /** Constrains a column to be non-null. */
+  whereNotNull(column: string): this {
+    this.#where.push({ kind: 'null', column, negated: true })
+    return this
+  }
+
+  /** Constrains a column to a list of values. */
+  whereIn(column: string, values: readonly unknown[]): this {
+    this.#where.push({ kind: 'in', column, values: [...values], negated: false })
+    return this
+  }
+
+  /** ORs a comparison with the predicates accumulated so far. */
+  orWhere(column: string, opOrValue: CompareOp | unknown, value?: unknown): this {
+    const next: Predicate =
+      value === undefined
+        ? { kind: 'compare', column, op: '=', value: opOrValue }
+        : { kind: 'compare', column, op: opOrValue as CompareOp, value }
+    if (this.#where.length === 0) {
+      this.#where.push(next)
+      return this
+    }
+    const previous = this.#where.splice(0, this.#where.length)
+    this.#where.push({
+      kind: 'or',
+      predicates: [
+        previous.length === 1 ? (previous[0] as Predicate) : { kind: 'and', predicates: previous },
+        next,
+      ],
+    })
+    return this
+  }
+
+  /** Orders the result. */
+  orderBy(column: string, direction: 'asc' | 'desc' = 'asc', nulls?: 'first' | 'last'): this {
+    this.#order.push(nulls === undefined ? { column, direction } : { column, direction, nulls })
+    return this
+  }
+
+  /** Newest-first helper for timestamp columns. */
+  latest(column = 'created_at'): this {
+    return this.orderBy(column, 'desc')
+  }
+
+  /** Limits the result count. */
+  limit(count: number): this {
+    this.#limit = count
+    return this
+  }
+
+  /** Offsets the result window. */
+  offset(count: number): this {
+    this.#offset = count
+    return this
+  }
+
+  /** Eager-loads a relation name declared on the model, or a fully resolved descriptor. */
+  with(relation: string | RelationLoad): this {
+    this.#relations.push(typeof relation === 'string' ? this.#resolveRelation(relation) : relation)
+    return this
+  }
+
+  /** Applies a ward predicate for row scoping. */
+  ward(predicate: WardInput): this {
+    this.#ward = predicate
+    return this
+  }
+
+  /** Builds the serializable query IR without executing it. */
+  toIR(mode: QueryIR['mode'] = 'select'): QueryIR {
+    const where = [...this.#where]
+    if (this.#model.softDeletes && !this.#withTrashed) {
+      where.push({ kind: 'null', column: 'deleted_at', negated: false })
+    }
+    const base: QueryIR = {
+      table: tableOf(this.#model),
+      mode,
+      select: mode === 'count' ? [] : this.#select,
+      where,
+      relations: mode === 'select' ? this.#relations : [],
+      order: mode === 'count' ? [] : this.#order,
+      ...(this.#limit !== undefined && mode !== 'count' ? { limit: this.#limit } : {}),
+      ...(this.#offset !== undefined && mode !== 'count' ? { offset: this.#offset } : {}),
+    }
+    if (this.#unwarded) return this.#ward === undefined ? base : injectWard(base, this.#ward)
+    const resolved = this.#resolvedWard()
+    if (resolved === undefined && this.#ward === undefined) return base
+    return injectWard(base, this.#ward ?? resolved ?? true)
+  }
+
+  /** Executes a select and hydrates models. */
+  async get(): Promise<readonly TModel[]> {
+    const result = await this.#driver.execute<Row>(this.toIR('select'))
+    return result.rows.map((row) => hydrate(this.#model, row) as TModel)
+  }
+
+  /** Executes a select and returns the first model or null. */
+  async first(): Promise<TModel | null> {
+    const rows = await this.limit(1).get()
+    return rows[0] ?? null
+  }
+
+  /** Executes a count query. */
+  async count(): Promise<number> {
+    const result = await this.#driver.execute(this.toIR('count'))
+    return result.count ?? 0
+  }
+
+  /** Paginates using count plus a limited select. */
+  async paginate(perPage: number, page = 1): Promise<Page<TModel>> {
+    if (!Number.isInteger(perPage) || perPage < 1 || !Number.isInteger(page) || page < 1) {
+      throw new Invalid('Pagination requires positive integer perPage and page.', {
+        metadata: { fields: { page: ['perPage and page must be positive integers.'] } },
+      })
+    }
+    const total = await this.count()
+    const data = await this.offset((page - 1) * perPage)
+      .limit(perPage)
+      .get()
+    return {
+      data,
+      total,
+      perPage,
+      page,
+      lastPage: Math.max(1, Math.ceil(total / perPage)),
+    }
+  }
+
+  /** Inserts one or more rows. */
+  async insert(values: Row | Row[], returning?: string[] | '*'): Promise<QueryResult<Row>> {
+    return this.#driver.execute<Row>({
+      table: tableOf(this.#model),
+      mode: 'insert',
+      select: [],
+      where: [],
+      relations: [],
+      order: [],
+      values,
+      returning,
+    })
+  }
+
+  /** Updates matching rows. */
+  async update(values: Row, returning?: string[] | '*'): Promise<QueryResult<Row>> {
+    return this.#driver.execute<Row>({
+      ...this.toIR('update'),
+      mode: 'update',
+      select: [],
+      values,
+      returning,
+    })
+  }
+
+  /** Deletes matching rows, soft-deleting when the model enables it. */
+  async delete(returning?: string[] | '*'): Promise<QueryResult<Row>> {
+    if (this.#model.softDeletes) {
+      return this.update({ deleted_at: new Date().toISOString() }, returning)
+    }
+    return this.#driver.execute<Row>({
+      ...this.toIR('delete'),
+      mode: 'delete',
+      select: [],
+      returning,
+    })
+  }
+
+  #resolvedWard(): WardInput | undefined {
+    try {
+      return resolveWard(
+        this.#model,
+        'read',
+        this.#actor === undefined ? Gate.actor() : this.#actor,
+      )
+    } catch {
+      return this.#model.ward?.(this.#actor === undefined ? Gate.actor() : this.#actor)
+    }
+  }
+
+  #resolveRelation(path: string): RelationLoad {
+    if (path.includes('.')) {
+      throw new Invalid('Nested with() paths need RelationLoad.relations.', {
+        metadata: { fields: { with: [`${path} is nested; pass a RelationLoad with relations.`] } },
+      })
+    }
+    if (path.length === 0) {
+      throw new Invalid('Relation name is required.', {
+        metadata: { fields: { with: ['Relation name is required.'] } },
+      })
+    }
+    const instance = new this.#model()
+    const method = Reflect.get(instance, path)
+    if (typeof method !== 'function') {
+      throw new Invalid(`Unknown relation ${path} on ${this.#model.name}.`, {
+        metadata: { fields: { with: [`${this.#model.name} has no ${path}() relation.`] } },
+      })
+    }
+    const descriptor = method.call(instance) as RelationLoad
+    return { ...descriptor, relation: path }
+  }
+}
+
+function hydrate(modelClass: ModelClass, row: Row): Model {
+  const model = new modelClass()
+  for (const [column, value] of Object.entries(row)) {
+    write(model, column, castIn(modelClass.casts[column], value))
+  }
+  model.exists = true
+  return model
+}
+
+function serialize(model: Model, keys: readonly string[]): Row {
+  const modelClass = ctorOf(model)
+  const values: Row = {}
+  for (const key of keys) {
+    values[key] = castOut(modelClass.casts[key], read(model, key))
+  }
+  return values
+}
+
+/** Base Scrivener model. Subclasses use `declare` for attributes, never emitted fields. */
+export class Model {
+  /** Database table name. */
+  static table = ''
+  /** Primary key column. */
+  static key = 'id'
+  /** Mass-assignable attributes. */
+  static fillable: readonly string[] = []
+  /** Attribute casts applied on hydrate and persist. */
+  static casts: Readonly<Record<string, CastKind>> = {}
+  /** When true, `created_at` and `updated_at` are maintained. */
+  static timestamps = false
+  /** When true, `delete()` writes `deleted_at` instead of removing the row. */
+  static softDeletes = false
+  /** Optional ward factory used when no `defineWard` registration exists. */
+  static ward?: (actor: GateActor) => WardInput
+
+  /** Whether this instance has been persisted. */
+  exists = false
+
+  /** Starts a query for this model. */
+  static query<T extends typeof Model>(
+    this: T,
+    driver?: DatabaseDriver | DatabaseTransaction,
+  ): QueryBuilder<InstanceType<T>> {
+    return new QueryBuilder(this as ModelClass, driver ?? DB.driver)
+  }
+
+  /** Includes soft-deleted rows. */
+  static withTrashed<T extends typeof Model>(this: T): QueryBuilder<InstanceType<T>> {
+    return this.query().withTrashed()
+  }
+
+  /** Applies the model ward for the supplied actor. */
+  static forActor<T extends typeof Model>(
+    this: T,
+    actor: GateActor,
+    driver?: DatabaseDriver | DatabaseTransaction,
+  ): QueryBuilder<InstanceType<T>> {
+    return new QueryBuilder(this as ModelClass, driver ?? DB.driver, { actor })
+  }
+
+  /** Finds a row by primary key or returns null. */
+  static async find<T extends typeof Model>(
+    this: T,
+    id: string | number,
+    driver?: DatabaseDriver | DatabaseTransaction,
+  ): Promise<InstanceType<T> | null> {
+    return this.query(driver).where(this.key, id).first()
+  }
+
+  /** Finds a row by primary key or throws `NotFound`. */
+  static async findOrFail<T extends typeof Model>(
+    this: T,
+    id: string | number,
+    driver?: DatabaseDriver | DatabaseTransaction,
+  ): Promise<InstanceType<T>> {
+    const model = await this.find(id, driver)
+    if (model === null) {
+      throw new NotFound(`${this.name} was not found.`, {
+        metadata: { resource: this.table || this.name, identifier: id },
+      })
+    }
+    return model
+  }
+
+  /** Mass-assigns fillable attributes, persists, and returns the hydrated model. */
+  static async create<T extends typeof Model>(
+    this: T,
+    values: Row,
+    driver?: DatabaseDriver | DatabaseTransaction,
+  ): Promise<InstanceType<T>> {
+    const model = new this() as InstanceType<T>
+    model.fill(values)
+    await model.save(driver)
+    return model
+  }
+
+  /** Copies fillable attributes onto the instance. */
+  fill(values: Row, raw = false): this {
+    const modelClass = ctorOf(this)
+    for (const key of fillableKeys(modelClass, values, raw)) {
+      const value = values[key]
+      write(this, key, castIn(modelClass.casts[key], value))
+    }
+    return this
+  }
+
+  /** Persists the instance, firing lifecycle hooks. */
+  async save(driver?: DatabaseDriver | DatabaseTransaction): Promise<this> {
+    const modelClass = ctorOf(this)
+    const saving = await fire(this, 'saving')
+    if (!saving) return this
+    if (!this.exists) {
+      if (!(await fire(this, 'creating'))) return this
+      if (modelClass.timestamps) {
+        const now = new Date().toISOString()
+        if (read(this, 'created_at') === undefined) write(this, 'created_at', now)
+        write(this, 'updated_at', now)
+      }
+      const keys = persistKeys(this)
+      const result = await modelClass.query(driver).insert(serialize(this, keys), '*')
+      const row = result.rows[0]
+      if (row !== undefined) {
+        for (const [column, value] of Object.entries(row)) {
+          write(this, column, castIn(modelClass.casts[column], value))
+        }
+      }
+      this.exists = true
+      await fire(this, 'created')
+    } else {
+      if (!(await fire(this, 'updating'))) return this
+      if (modelClass.timestamps) write(this, 'updated_at', new Date().toISOString())
+      const keys = persistKeys(this)
+      const id = read(this, keyOf(modelClass))
+      await modelClass.query(driver).where(keyOf(modelClass), id).update(serialize(this, keys))
+      await fire(this, 'updated')
+    }
+    await fire(this, 'saved')
+    return this
+  }
+
+  /** Mass-assigns fillable attributes and persists. */
+  async update(values: Row, driver?: DatabaseDriver | DatabaseTransaction): Promise<this> {
+    this.fill(values)
+    return this.save(driver)
+  }
+
+  /** Deletes the instance, soft-deleting when enabled. */
+  async delete(driver?: DatabaseDriver | DatabaseTransaction): Promise<void> {
+    if (!(await fire(this, 'deleting'))) return
+    const modelClass = ctorOf(this)
+    const id = read(this, keyOf(modelClass))
+    await modelClass.query(driver).where(keyOf(modelClass), id).delete()
+    this.exists = false
+    await fire(this, 'deleted')
+  }
+
+  /** Restores a soft-deleted instance. */
+  async restore(driver?: DatabaseDriver | DatabaseTransaction): Promise<this> {
+    const modelClass = ctorOf(this)
+    write(this, 'deleted_at', null)
+    const id = read(this, keyOf(modelClass))
+    await modelClass.withTrashed().where(keyOf(modelClass), id).update({ deleted_at: null })
+    this.exists = true
+    await fire(this, 'restored')
+    return this
+  }
+
+  /** Declares a belongsTo relation for eager loading. */
+  belongsTo(
+    related: ModelClass,
+    foreignKey: string,
+    ownerKey = 'id',
+    relation = related.name.replace(/^[A-Z]/, (letter) => letter.toLowerCase()),
+  ): RelationLoad {
+    return {
+      relation,
+      kind: 'belongsTo',
+      table: related.table,
+      localKey: foreignKey,
+      foreignKey: ownerKey,
+      select: '*',
+      where: null,
+      order: [],
+      relations: [],
+    }
+  }
+
+  /** Declares a hasOne relation for eager loading. */
+  hasOne(related: ModelClass, foreignKey: string, localKey = 'id'): RelationLoad {
+    return {
+      relation: related.name.replace(/^[A-Z]/, (letter) => letter.toLowerCase()),
+      kind: 'hasOne',
+      table: related.table,
+      localKey,
+      foreignKey,
+      select: '*',
+      where: null,
+      order: [],
+      relations: [],
+    }
+  }
+
+  /** Declares a hasMany relation for eager loading. */
+  hasMany(related: ModelClass, foreignKey: string, localKey = 'id'): RelationLoad {
+    return {
+      relation: related.name.replace(/^[A-Z]/, (letter) => letter.toLowerCase()),
+      kind: 'hasMany',
+      table: related.table,
+      localKey,
+      foreignKey,
+      select: '*',
+      where: null,
+      order: [],
+      relations: [],
+    }
+  }
+}
+
+function persistKeys(model: Model): string[] {
+  const modelClass = ctorOf(model)
+  const keys = new Set<string>([...modelClass.fillable])
+  keys.add(keyOf(modelClass))
+  if (modelClass.timestamps) {
+    keys.add('created_at')
+    keys.add('updated_at')
+  }
+  if (modelClass.softDeletes) keys.add('deleted_at')
+  for (const key of Object.keys(asRecord(model))) {
+    if (typeof asRecord(model)[key] !== 'function' && key !== 'exists') keys.add(key)
+  }
+  return [...keys].filter((key) => read(model, key) !== undefined)
+}
+
+/** Starts a query against a table using an anonymous model class. */
+export function query<TRow extends Row = Row>(
+  table: string,
+  driver?: DatabaseDriver | DatabaseTransaction,
+): QueryBuilder {
+  class Anonymous extends Model {
+    static override table = table
+    static override fillable: readonly string[] = []
+  }
+  Object.defineProperty(Anonymous, 'name', { value: table })
+  return new QueryBuilder(Anonymous, driver ?? DB.driver) as QueryBuilder<Model & TRow>
+}
+
+/** Scrivener entry for operations that Bailiff later restricts by directory. */
+export const Scrivener = {
+  /** Returns an unwarded query for a model. Allowed only in errands and seeds. */
+  unwarded<T extends typeof Model>(model: T): { query: () => QueryBuilder<InstanceType<T>> } {
+    return {
+      query: () =>
+        new QueryBuilder(model as ModelClass, DB.driver, { unwarded: true }) as QueryBuilder<
+          InstanceType<T>
+        >,
+    }
+  },
+}