@everystack/model 0.3.0

package/README.md

@@ -0,0 +1,146 @@
+# @everystack/model
+
+Declare a table once — its columns, validation, authorization, and relations — and compile it to Postgres migrations, RLS policies, and handler config. One declaration, three targets, no drift between them.
+
+## Install
+
+```bash
+pnpm add @everystack/model
+```
+
+`zod` is an optional peer dependency, needed only when a field uses `.validate(...)`.
+
+## Declare a model
+
+```typescript
+import { defineModel, field, can, unique, index, check, foreignKey, sql } from '@everystack/model';
+import { z } from 'zod';
+
+export const Account = defineModel('accounts', {
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    email: field.text().notNull().unique(),
+    displayName: field.text().notNull(),
+    bio: field.text().nullable().validate(z.string().max(160)),
+    status: field.enum('account_status', ['active', 'suspended', 'closed']).notNull().default('active'),
+    createdAt: field.timestamptz().notNull().defaultNow(),
+  },
+  abilities: [
+    can('read'),                         // anyone can read
+    can('update', { owner: 'id' }),      // you can update your own row
+  ],
+});
+
+export const Note = defineModel('notes', {
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    accountId: field.uuid().notNull().references(() => Account, { onDelete: 'cascade' }),
+    title: field.text().notNull(),
+    createdAt: field.timestamptz().notNull().defaultNow(),
+  },
+  abilities: [
+    can('read', { owner: 'accountId' }),
+    can('create', { owner: 'accountId' }),
+    can('update', { owner: 'accountId' }),
+    can('delete', { owner: 'accountId' }),
+  ],
+  constraints: [
+    unique('accountId', 'title'),                  // composite unique
+    index('createdAt').where(sql`pinned = true`),  // partial index
+    check(sql`char_length(title) > 0`),            // table-level CHECK
+  ],
+});
+
+export const models = [Account, Note];
+```
+
+## Fields
+
+`field.*()` builds a column. The type is the Postgres type; the chained modifiers are the constraints.
+
+| Factory | Postgres type |
+|---------|---------------|
+| `field.uuid()` | `uuid` |
+| `field.text()` | `text` |
+| `field.varchar(n?)` | `character varying(n)` |
+| `field.integer()` | `integer` |
+| `field.bigint()` / `field.bigserial()` | `bigint` / `bigserial` |
+| `field.numeric(p?, s?)` | `numeric(p, s)` |
+| `field.boolean()` | `boolean` |
+| `field.timestamptz()` / `field.timestamp()` | `timestamp with[out] time zone` |
+| `field.date()` | `date` |
+| `field.jsonb()` | `jsonb` |
+| `field.enum('name', [...])` | a `CREATE TYPE … AS ENUM` (name is explicit, so `db:pull` round-trips it) |
+
+Modifiers: `.primaryKey()`, `.notNull()` / `.nullable()`, `.unique()`, `.default(value)` / `.defaultNow()` / `.defaultRandom()`, `.references(() => Other, { onDelete, onUpdate })`, `.private()` (never serialized), `.readonly()` (never accepted on write), `.validate(zodSchema)`, and `.renamedFrom('oldField')` (turns a drop+add into a data-preserving `RENAME COLUMN`).
+
+`.validate(...)` does double duty: the SQL-expressible refinements (`min`/`max`/`length`/range/enum) become a Postgres `CHECK` — the backstop for the SSR-direct write path that never runs app-layer Zod — while richer refinements stay app-layer only.
+
+## Constraints
+
+The table-level surface, composed in `constraints: [...]`, for what a column-scoped `field()` can't carry:
+
+- `unique('a', 'b')` — a composite unique constraint.
+- `index('a').unique().where(sql\`…\`)` — a standalone index, optionally unique and/or partial.
+- `check(sql\`a >= b\`)` — a multi-column CHECK.
+- `foreignKey(['a', 'b'], () => Other, ['x', 'y'], { onDelete })` — a composite foreign key.
+
+## Authorization
+
+`can(action, condition)` declares one rule (default-deny: no matching `can()` means denied). Conditions: `{ owner: 'column' }` (row owner, via the JWT `sub` claim by default — override with `userField`), `{ role: 'admin' }`, or a raw `{ sql: … }` escape hatch. These compile to RLS policies and grants.
+
+## Relations
+
+```typescript
+import { belongsTo, hasMany } from '@everystack/model';
+
+defineModel('notes', {
+  fields: { /* … */ },
+  relations: {
+    account: belongsTo(() => Account, 'accountId'),
+    comments: hasMany(() => Comment, 'noteId'),
+  },
+});
+```
+
+## Compile
+
+`@everystack/model` is the declaration surface; `@everystack/cli` is the compiler. With your `models` array:
+
+```bash
+everystack db:generate --stage dev   # diff models vs the live DB → one ordered migration (data + authz)
+everystack db:pull     --stage dev   # reverse an existing database into model source (the brownfield on-ramp)
+```
+
+`db:generate` is non-destructive by default — drops are held back as comments unless you pass `--allow-drops`. A faithful `db:pull` then `db:generate` is a no-op: the declaration and the database it built are the same thing.
+
+### Handler config
+
+`deriveHandlerConfig(models)` compiles the same Models into the authorization config `createHandler` consumes (exposed tables, hidden/protected columns, relations, row ownership) — so the HTTP handler and the database enforce the *same* declared rules, with no second source of truth.
+
+```typescript
+import { deriveHandlerConfig } from '@everystack/model';
+const handler = createHandler(db, schema, deriveHandlerConfig(models));
+```
+
+## Programmatic API (`@everystack/cli/model`)
+
+The same compiler the CLI uses is importable for your own CI and tests — point it at your live DB and assert the declaration and the database agree, or red-team the deployed authorization:
+
+```typescript
+import {
+  compileMigration, generateMigrationSql, introspectSchema, diffSchema,   // data layer
+  compileTableContract, introspectContract, diffContracts,                 // authz layer
+  buildOwnerProbeSql, evaluateOwnerProbe,                                   // owner-isolation red-team
+} from '@everystack/cli/model';
+```
+
+- **Data** — `introspectSchema(run)` reads the whole DB; `diffSchema(desired, current)` / `generateMigrationSql(models, current)` produce the structural delta. A green `db:generate` is this returning empty.
+- **Authz** — `compileTableContract(model)` is the declared RLS/grants; `introspectContract(run)` is what's live; `diffContracts(declared, live)` is the drift audit (`db:authz:diff`).
+- **Red-team** — `buildOwnerProbeSql` / `evaluateOwnerProbe` drive two JWT identities per owner-scoped table to catch IDOR (`db:authz:owner`).
+
+`run` is any `QueryRunner` — a function that executes SQL against your DB (e.g. wrapping an `everystack db:query` invoke or a direct connection). This is what the example app's dogfood test uses to prove its real Models round-trip against real Postgres.
+
+## License
+
+AGPL-3.0-only

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@everystack/model",
+  "version": "0.3.0",
+  "description": "Declare a table's schema, validation, and authorization once — compiled to migrations, RLS, and handler config",
+  "license": "AGPL-3.0-only",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "zod": "*"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/jest": "29.5.14",
+    "@types/node": "22.19.18",
+    "jest": "29.7.0",
+    "ts-jest": "29.4.9",
+    "typescript": "5.9.3",
+    "zod": "3.25.67"
+  },
+  "scripts": {
+    "test": "jest",
+    "build": "tsc --build",
+    "lint": "tsc --noEmit"
+  }
+}

package/src/can.ts

@@ -0,0 +1,36 @@
+/**
+ * CanCan-shaped authorization rules. `can(action, condition)` declares one rule.
+ *
+ * Phase 0 consumes only the `owner` shape (→ the handler's `rowOwnership` IDOR
+ * backstop). The full set of condition shapes — `role`, `where`, `sql` — is
+ * stored verbatim now and compiled to RLS policies + grants in Phase 1
+ * (`compileAbilities`, the inverse of the contract suite's `humanizePredicate`).
+ *
+ * Default-deny is the model's contract: no matching `can()` means denied.
+ */
+
+/** CanCan verbs. `manage` is "all actions". */
+export type Action = 'read' | 'create' | 'update' | 'delete' | 'manage';
+
+export interface AbilityCondition {
+  /** Role-gated: policy `TO <role>` + grant. */
+  role?: string;
+  /** Row owner only: the column holding the owner id (`USING (<col> = auth.uid())`). */
+  owner?: string;
+  /** Field in the JWT claims holding the owner id. Default: `sub`. */
+  userField?: string;
+  /** Scalar/column predicate — a sql-tagged expression. Compiled in Phase 1. */
+  where?: unknown;
+  /** Escape hatch: a verbatim RLS predicate, preserved and diffed by normalized text. */
+  sql?: unknown;
+}
+
+export interface Ability {
+  action: Action;
+  condition: AbilityCondition;
+}
+
+/** Declare one authorization rule. */
+export function can(action: Action, condition: AbilityCondition = {}): Ability {
+  return { action, condition };
+}

package/src/constraints.ts

@@ -0,0 +1,90 @@
+/**
+ * Table-level constraint builders — the surface for what a column-scoped `field()`
+ * can't express: a composite `unique(...)` and a multi-column `check(...)`. They are
+ * composed in a `constraints: [...]` array on `defineModel`, the same builder idiom as
+ * `field`/`can`, so the Model reads as intent rather than config.
+ *
+ * Columns are named by their **field keys** (camelCase, as the model is written); the
+ * compiler snake_cases them to SQL identifiers — symmetric with `.references()`. A
+ * `check(...)` takes raw `sql\`…\`` because a predicate is, by nature, SQL.
+ *
+ * (Indexes join this surface in a later increment; the union is open for it.)
+ */
+
+import type { RawSql } from './raw-sql';
+import type { ReferentialAction } from './field';
+
+export type TableConstraint =
+  /** `UNIQUE (a, b)` over two or more field keys — the composite the field builder can't carry. */
+  | { kind: 'unique'; columns: string[] }
+  /** `CHECK (<predicate>)` — a raw SQL predicate, typically spanning columns. */
+  | { kind: 'check'; predicate: string }
+  /** A standalone index — `CREATE [UNIQUE] INDEX … (cols) [WHERE <predicate>]`. */
+  | { kind: 'index'; columns: string[]; isUnique: boolean; predicate?: string }
+  /**
+   * A multi-column `FOREIGN KEY (a, b) REFERENCES other (x, y)` — the composite a column-scoped
+   * `.references()` can't carry. Local field keys, a model thunk for the target, and the target's
+   * field keys; optional `onDelete`/`onUpdate` referential actions.
+   */
+  | { kind: 'foreignKey'; columns: string[]; references: () => unknown; refColumns: string[]; onDelete?: ReferentialAction; onUpdate?: ReferentialAction };
+
+/** A composite unique constraint over the given field keys: `unique('authorId', 'slug')`. */
+export function unique(...columns: string[]): TableConstraint {
+  return { kind: 'unique', columns };
+}
+
+/** A table CHECK from a raw predicate: `check(sql\`published_at >= created_at\`)`. */
+export function check(predicate: RawSql): TableConstraint {
+  return { kind: 'check', predicate: predicate.sql };
+}
+
+/**
+ * A composite foreign key — the multi-column analog of `.references()`, which only a table-level
+ * surface can express: `foreignKey(['orgId', 'teamId'], () => Team, ['orgId', 'teamId'])`. The
+ * target columns are explicit (a composite FK references a composite key, not just the PK), and
+ * the referential actions ride here the same way they ride on `.references()`.
+ */
+export function foreignKey(
+  columns: string[],
+  references: () => unknown,
+  refColumns: string[],
+  opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction },
+): TableConstraint {
+  return {
+    kind: 'foreignKey',
+    columns,
+    references,
+    refColumns,
+    ...(opts?.onDelete ? { onDelete: opts.onDelete } : {}),
+    ...(opts?.onUpdate ? { onUpdate: opts.onUpdate } : {}),
+  };
+}
+
+/**
+ * A standalone index over the given field keys, chainable: `index('authorId')`,
+ * `index('authorId').unique()`, `index('slug').where(sql\`deleted_at IS NULL\`)` (partial).
+ * Indexes that merely back a primary key or unique constraint are NOT declared here — those
+ * come from `.primaryKey()` / `.unique()` / the `unique(...)` constraint.
+ */
+export class IndexBuilder {
+  readonly kind = 'index' as const;
+  isUnique = false;
+  predicate?: string;
+  constructor(readonly columns: string[]) {}
+
+  /** Make it a UNIQUE index. */
+  unique(): this {
+    this.isUnique = true;
+    return this;
+  }
+
+  /** A partial-index predicate: `index('slug').where(sql\`deleted_at IS NULL\`)`. */
+  where(predicate: RawSql): this {
+    this.predicate = predicate.sql;
+    return this;
+  }
+}
+
+export function index(...columns: string[]): IndexBuilder {
+  return new IndexBuilder(columns);
+}

package/src/derive.ts

@@ -0,0 +1,130 @@
+/**
+ * `deriveHandlerConfig` — compile a set of models down to the per-table slice of
+ * the API handler's options blob.
+ *
+ * This is the Phase-0 payoff: today the example hand-authors `exposedTables`,
+ * `hiddenColumns`, `protectedFields`, `rowOwnership`, `softDelete`, `relations`,
+ * and `hooks` as a scattered literal kept in sync with the schema by hand. Those
+ * are all *views of the model*, so they derive from it — no drift.
+ *
+ * Scope boundary: only the PER-TABLE surface derives here. App/handler-level
+ * options (`auth`, `pgSettings`, `rpc`, `basePath`, `audit`, `maxLimit`,
+ * `naming`, `hideSchemaErrors`) are not per-model and stay explicit at the
+ * `createHandler` call.
+ */
+
+import type { ModelDescriptor } from './model';
+import type { ModelHooks } from './model';
+
+/** The handler's RelationConfig shape, mirrored structurally (no @everystack/api dep). */
+export interface RelationConfig {
+  table: string;
+  from: string;
+  to: string;
+  many?: boolean;
+}
+
+export interface DerivedHandlerConfig {
+  exposedTables: string[];
+  hiddenColumns: Record<string, string[]>;
+  protectedFields: Record<string, string[]>;
+  rowOwnership: Record<string, { column: string; userField: string }>;
+  softDelete: { tables: string[] };
+  relations: Record<string, Record<string, RelationConfig>>;
+  hooks: Record<string, ModelHooks>;
+}
+
+/** Conventional soft-delete column — matches the handler's default. */
+const SOFT_DELETE_COLUMN = 'deletedAt';
+/** Conventional JWT claim holding the owner id. */
+const DEFAULT_USER_FIELD = 'sub';
+
+/** A model's primary key for relation resolution (single-PK default; falls back to `id`). */
+function primaryKeyOf(model: ModelDescriptor): string {
+  return model.primaryKey[0] ?? 'id';
+}
+
+export function deriveHandlerConfig(models: ModelDescriptor[]): DerivedHandlerConfig {
+  const exposedTables: string[] = [];
+  const hiddenColumns: Record<string, string[]> = {};
+  const protectedFields: Record<string, string[]> = {};
+  const rowOwnership: Record<string, { column: string; userField: string }> = {};
+  const softDeleteTables: string[] = [];
+  const relations: Record<string, Record<string, RelationConfig>> = {};
+  const hooks: Record<string, ModelHooks> = {};
+
+  for (const model of models) {
+    const { table } = model;
+    exposedTables.push(table);
+
+    // .private() → hiddenColumns (omit the key entirely when there are none, so
+    // the derived blob matches a hand-written `{}` exactly).
+    const privateCols = fieldsWhere(model, (f) => f.spec.isPrivate);
+    if (privateCols.length) hiddenColumns[table] = privateCols;
+
+    // .readonly() → protectedFields (mass-assignment guard).
+    const readonlyCols = fieldsWhere(model, (f) => f.spec.isReadonly);
+    if (readonlyCols.length) protectedFields[table] = readonlyCols;
+
+    // The first owner-shaped ability → the handler's rowOwnership IDOR backstop.
+    // (RLS, compiled from the same ability in Phase 1, is the primary enforcement;
+    // this is the HTTP-path guard. A model's owner abilities share one column.)
+    const ownerAbility = model.abilities.find((a) => a.condition.owner);
+    if (ownerAbility) {
+      rowOwnership[table] = {
+        column: ownerAbility.condition.owner!,
+        userField: ownerAbility.condition.userField ?? DEFAULT_USER_FIELD,
+      };
+    }
+
+    // Convention: a `deletedAt` field opts the table into soft-delete.
+    if (SOFT_DELETE_COLUMN in model.fields) softDeleteTables.push(table);
+
+    if (model.hooks) hooks[table] = model.hooks;
+
+    const relationNames = Object.keys(model.relations);
+    if (relationNames.length) {
+      const resolved: Record<string, RelationConfig> = {};
+      for (const name of relationNames) {
+        const rel = model.relations[name];
+        const target = rel.target();
+        if (rel.kind === 'belongsTo') {
+          // this.<column> → target.<pk>
+          resolved[name] = {
+            table: target.table,
+            from: rel.column,
+            to: rel.references ?? primaryKeyOf(target),
+          };
+        } else {
+          // this.<pk> → target.<column>
+          resolved[name] = {
+            table: target.table,
+            from: rel.references ?? primaryKeyOf(model),
+            to: rel.column,
+            many: true,
+          };
+        }
+      }
+      relations[table] = resolved;
+    }
+  }
+
+  return {
+    exposedTables,
+    hiddenColumns,
+    protectedFields,
+    rowOwnership,
+    softDelete: { tables: softDeleteTables },
+    relations,
+    hooks,
+  };
+}
+
+function fieldsWhere(
+  model: ModelDescriptor,
+  pred: (f: ModelDescriptor['fields'][string]) => boolean,
+): string[] {
+  return Object.entries(model.fields)
+    .filter(([, f]) => pred(f))
+    .map(([name]) => name);
+}

package/src/field.ts

@@ -0,0 +1,193 @@
+/**
+ * The field descriptor — Layer 1 of the Model, in its Phase-0 form.
+ *
+ * Today a `field()` records *intent*: the Postgres type and the exposure /
+ * constraint modifiers the handler-config derivation needs (`.private()`,
+ * `.readonly()`, primary key, references). It does NOT yet generate DDL or Zod —
+ * that is the Zod⊗Postgres bridge (Phase 4), which enriches THIS SAME builder
+ * surface without changing how a model is written. A model authored now keeps
+ * working when the bridge lands.
+ *
+ * See docs/plans/v3-model-implementation.md (Phase 0) and v3-model-api.md.
+ */
+
+export type FieldType =
+  | 'text'
+  | 'uuid'
+  | 'bigint'
+  | 'bigserial'
+  | 'integer'
+  | 'boolean'
+  | 'timestamptz'
+  | 'timestamp'
+  | 'date'
+  | 'numeric'
+  | 'varchar'
+  | 'jsonb'
+  | 'enum';
+
+export type DefaultKind = 'value' | 'now' | 'random';
+
+/** A foreign-key referential action (`ON DELETE` / `ON UPDATE`). `'no action'` is the default. */
+export type ReferentialAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';
+
+/** The flattened state a {@link FieldBuilder} accumulates. Read by the derivation. */
+export interface FieldSpec {
+  type: FieldType;
+  /** The Postgres type name for an `enum` field (`CREATE TYPE <name> AS ENUM …`). Always explicit. */
+  enumName?: string;
+  /** Allowed values for `enum` fields, in declaration order (the enum's value order). */
+  enumValues?: readonly string[];
+  /** `numeric(precision, scale)` — total digits and digits after the decimal point. */
+  precision?: number;
+  scale?: number;
+  /** `varchar(length)` — maximum character length. */
+  length?: number;
+  isPrimaryKey: boolean;
+  isNotNull: boolean;
+  isUnique: boolean;
+  /** `.private()` — never serialized into API responses (→ `hiddenColumns`). */
+  isPrivate: boolean;
+  /** `.readonly()` — never accepted on write (→ `protectedFields`). */
+  isReadonly: boolean;
+  /** `.references(() => Other)` — FK target, a model thunk. Used by relation/ownership work. */
+  references?: () => unknown;
+  /** `ON DELETE` action for the FK. Omitted (or `'no action'`) is the Postgres default. */
+  onDelete?: ReferentialAction;
+  /** `ON UPDATE` action for the FK. Omitted (or `'no action'`) is the Postgres default. */
+  onUpdate?: ReferentialAction;
+  default?: unknown;
+  defaultKind?: DefaultKind;
+  /** A Zod schema, stored verbatim. Consumed by the field bridge (Phase 4); inert today. */
+  validation?: unknown;
+  /**
+   * `.renamedFrom('oldField')` — a one-shot migration hint. When the diff sees the old
+   * column still present and this (new) column absent, it emits `RENAME COLUMN` instead
+   * of a data-losing drop+add. Rename intent cannot be recovered from two snapshots, so
+   * it is declared here. The marker goes inert once the rename is applied (the new name
+   * is present) and can be removed — the diff says so when it sees a satisfied one.
+   */
+  renamedFrom?: string;
+}
+
+/**
+ * Fluent, mutable builder. Every modifier returns `this` so declarations chain:
+ * `field.text().notNull().private()`. The accumulated {@link FieldSpec} is read
+ * off `.spec` by the derivation.
+ */
+export class FieldBuilder {
+  readonly spec: FieldSpec;
+
+  constructor(type: FieldType, extra?: Pick<FieldSpec, 'enumName' | 'enumValues' | 'precision' | 'scale' | 'length'>) {
+    this.spec = {
+      type,
+      enumName: extra?.enumName,
+      enumValues: extra?.enumValues,
+      precision: extra?.precision,
+      scale: extra?.scale,
+      length: extra?.length,
+      isPrimaryKey: false,
+      isNotNull: false,
+      isUnique: false,
+      isPrivate: false,
+      isReadonly: false,
+    };
+  }
+
+  primaryKey(): this {
+    this.spec.isPrimaryKey = true;
+    this.spec.isNotNull = true;
+    return this;
+  }
+
+  notNull(): this {
+    this.spec.isNotNull = true;
+    return this;
+  }
+
+  nullable(): this {
+    this.spec.isNotNull = false;
+    return this;
+  }
+
+  unique(): this {
+    this.spec.isUnique = true;
+    return this;
+  }
+
+  /** Hide from every API response. Compiles to the handler's `hiddenColumns`. */
+  private(): this {
+    this.spec.isPrivate = true;
+    return this;
+  }
+
+  /** Reject on write (mass-assignment guard). Compiles to the handler's `protectedFields`. */
+  readonly(): this {
+    this.spec.isReadonly = true;
+    return this;
+  }
+
+  /**
+   * Declare a foreign key. The target is a model thunk (forward-reference safe). Optional
+   * `onDelete`/`onUpdate` referential actions are column-scoped, so they live here, not on
+   * the table — `field.uuid().references(() => User, { onDelete: 'cascade' })`.
+   */
+  references(target: () => unknown, opts?: { onDelete?: ReferentialAction; onUpdate?: ReferentialAction }): this {
+    this.spec.references = target;
+    if (opts?.onDelete) this.spec.onDelete = opts.onDelete;
+    if (opts?.onUpdate) this.spec.onUpdate = opts.onUpdate;
+    return this;
+  }
+
+  default(value: unknown): this {
+    this.spec.default = value;
+    this.spec.defaultKind = 'value';
+    return this;
+  }
+
+  defaultNow(): this {
+    this.spec.defaultKind = 'now';
+    return this;
+  }
+
+  defaultRandom(): this {
+    this.spec.defaultKind = 'random';
+    return this;
+  }
+
+  /** Attach a Zod schema. Stored now, compiled to CHECK + runtime validation in Phase 4. */
+  validate(schema: unknown): this {
+    this.spec.validation = schema;
+    return this;
+  }
+
+  /**
+   * Mark this field as the rename of a former one (`oldField` is the previous *field*
+   * name, snake_cased to its column by the generator). A one-shot hint the schema diff
+   * reads to emit `RENAME COLUMN` instead of drop+add, preserving the column's data.
+   */
+  renamedFrom(oldField: string): this {
+    this.spec.renamedFrom = oldField;
+    return this;
+  }
+}
+
+/** The field factory. `field.text()`, `field.uuid()`, `field.enum('status', [...])`, … */
+export const field = {
+  text: (): FieldBuilder => new FieldBuilder('text'),
+  uuid: (): FieldBuilder => new FieldBuilder('uuid'),
+  bigint: (): FieldBuilder => new FieldBuilder('bigint'),
+  bigserial: (): FieldBuilder => new FieldBuilder('bigserial'),
+  integer: (): FieldBuilder => new FieldBuilder('integer'),
+  boolean: (): FieldBuilder => new FieldBuilder('boolean'),
+  timestamptz: (): FieldBuilder => new FieldBuilder('timestamptz'),
+  timestamp: (): FieldBuilder => new FieldBuilder('timestamp'),
+  date: (): FieldBuilder => new FieldBuilder('date'),
+  /** `numeric(precision, scale)` — both optional; `numeric()` is unbounded. */
+  numeric: (precision?: number, scale?: number): FieldBuilder => new FieldBuilder('numeric', { precision, scale }),
+  /** `varchar(length)` — length optional; `varchar()` is unbounded `character varying`. */
+  varchar: (length?: number): FieldBuilder => new FieldBuilder('varchar', { length }),
+  jsonb: (): FieldBuilder => new FieldBuilder('jsonb'),
+  /** A Postgres enum. The `name` is the `CREATE TYPE` name and is always explicit, so `db:pull` round-trips it. */
+  enum: (name: string, values: readonly string[]): FieldBuilder => new FieldBuilder('enum', { enumName: name, enumValues: values }),
+} as const;

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @everystack/model — declare a table once; compile it to migrations, RLS, and
+ * handler config. See docs/plans/v3-model-architecture.md.
+ *
+ * Phase 0 ships the declaration surface (`defineModel`, `field`, `can`,
+ * `belongsTo`/`hasMany`) and the first compile target: handler-config derivation.
+ */
+
+export { field, FieldBuilder } from './field';
+export type { FieldSpec, FieldType, DefaultKind, ReferentialAction } from './field';
+
+export { unique, check, index, foreignKey, IndexBuilder } from './constraints';
+export type { TableConstraint } from './constraints';
+
+export { sql } from './raw-sql';
+export type { RawSql } from './raw-sql';
+
+export { can } from './can';
+export type { Ability, AbilityCondition, Action } from './can';
+
+export { belongsTo, hasMany } from './relations';
+export type { Relation } from './relations';
+
+export { defineModel } from './model';
+export type { ModelDescriptor, ModelDefinition, ModelHooks } from './model';
+
+export { deriveHandlerConfig } from './derive';
+export type { DerivedHandlerConfig, RelationConfig } from './derive';