@ultimat3/entity 0.0.1

package/README.md

@@ -0,0 +1,69 @@
+# @ultimat3/entity 🗄️
+
+An entity is **a table + its domain type + its invariants**. The first of the eight
+primitives; repos, admin screens, cache tags and the manifest are all derived from
+one `entity()` call.
+
+```ts
+const posts = entity({
+  table: table('posts', { id: id(), orgId: orgId(), title: text(), ...money('price'),
+                          ...timestamps(), ...softDelete() }),
+  type: Post,
+  invariants: [invariant('title_not_empty', {
+    message: 'title must not be empty',
+    sql: 'char_length(title) > 0',
+    holds: (p) => p.title.length > 0,
+  })],
+});
+```
+
+## Blessed columns
+
+| Helper | Emits | Why it is the only way |
+|---|---|---|
+| `id()` | `uuid` pk, v7 default | time-ordered keys keep the pk index append-friendly |
+| `timestamps()` | `created_at`/`updated_at` `timestamptz` | UTC storage is not a per-table decision |
+| `money('price')` | `price_minor bigint` + `price_currency char(3)` | never a float, never one implied currency |
+| `tz()` | `text` + regex CHECK, `Intl`-validated | an offset is not a time zone |
+| `locale()`, `slug()` | `text` + CHECK | format is enforced by the database too |
+| `orgId()` | `uuid` + FK + index | its presence is what turns on tenancy |
+| `softDelete()` | `deleted_at timestamptz null` | its presence is what turns on soft delete |
+| `jsonb(parse)` | `jsonb` | a jsonb column without a parser is an untyped hole |
+
+Physical names are derived from the property key (`orgId` → `org_id`); write a name
+once or not at all.
+
+## Invariants run twice
+
+Written once, enforced in the app on every write **and** in Postgres as a CHECK or a
+unique index (`toSql()`). The database can never disagree with the code — a bulk
+import or a `psql` session hits the same rule.
+
+```sql
+ALTER TABLE "posts" ADD CONSTRAINT "posts_title_not_empty_check" CHECK (char_length(title) > 0);
+```
+
+## Repositories
+
+`Repo<T>` takes an explicit `tx` on every write so the transactional outbox can join
+the request's transaction. Pagination is **cursor-only**: `OFFSET` is wrong under
+concurrent writes because an insert before the offset shifts every later page, so a
+client silently skips and repeats rows. `memoryRepo()` is the default driver
+(tests, `x dev` before the first migration); Drizzle + Postgres is production.
+
+## Tenancy is a guard
+
+An entity with an `orgId` column can only be queried through a plan carrying an org
+predicate. Without one: `X_TENANCY_UNSCOPED`, at the seam, every time.
+
+## Errors
+
+`X_ENTITY_DUPLICATE` · `X_INVARIANT_VIOLATED` · `X_TENANCY_UNSCOPED` · `X_DB_DRIFT` ·
+`X_NOT_FOUND`
+
+## Boundaries
+
+Tier 2. Imports `@ultimat3/core` and `@ultimat3/schema` only. There is deliberately no
+`drizzle-orm` dependency: `ColumnDef`/`TableDef` are the narrow structural types this
+package consumes, so generated SQL stays readable and an agent can self-correct
+against it. `@ultimat3/cache` invalidates by the `entity:<name>` tag string.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ultimat3/entity",
+  "version": "0.0.1",
+  "description": "A table + its domain type + invariants the database also enforces",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/entity"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "^0.0.1",
+    "@ultimat3/schema": "^0.0.1"
+  }
+}

package/src/columns.ts

@@ -0,0 +1,255 @@
+// The blessed column helpers. There is exactly one way to store an id, a timestamp,
+// money, a locale and a time zone — the alternatives (float money, naive timestamps,
+// a single implied currency) are the bugs this file exists to make unreachable.
+import { uuid } from '@ultimat3/core';
+import { invariantViolated } from './errors';
+import type { ColumnDef, ColumnMap, IndexDef, TableDef } from './types';
+
+const snake = (value: string): string => value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+
+const reject = (column: string, rule: string, detail: string): never => {
+  throw invariantViolated(column, rule, detail);
+};
+
+interface ColumnOptions {
+  readonly name?: string;
+  readonly comment?: string;
+}
+
+const base = <T>(
+  kind: ColumnDef<T>['kind'],
+  parse: (value: unknown) => T,
+  overrides: Partial<ColumnDef<T>> = {},
+): ColumnDef<T> => ({
+  // '' means "derive from the property key in table()", so a column is declared once.
+  name: '',
+  kind,
+  notNull: true,
+  primaryKey: false,
+  unique: false,
+  index: false,
+  parse,
+  ...overrides,
+});
+
+const asString =
+  (label: string) =>
+  (value: unknown): string => {
+    if (typeof value === 'string') return value;
+    return reject(label, 'type', `expected a string, got ${typeof value}`);
+  };
+
+const asDate =
+  (label: string) =>
+  (value: unknown): Date => {
+    if (value instanceof Date) return value;
+    if (typeof value === 'string' || typeof value === 'number') {
+      const parsed = new Date(value);
+      if (!Number.isNaN(parsed.getTime())) return parsed;
+    }
+    return reject(label, 'type', `expected a Date or ISO-8601 string, got ${String(value)}`);
+  };
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+const asUuid =
+  (label: string) =>
+  (value: unknown): string => {
+    if (typeof value === 'string' && UUID.test(value)) return value;
+    return reject(label, 'format', `expected a uuid, got ${String(value)}`);
+  };
+
+/** uuid v7: time-ordered, so a primary key index stays append-friendly. */
+export const newId = (): string => uuid();
+
+export const id = (options: ColumnOptions = {}): ColumnDef<string> =>
+  base<string>('uuid', asUuid('id'), {
+    ...options,
+    name: options.name ?? 'id',
+    primaryKey: true,
+    default: { kind: 'generated', by: 'uuid-v7' },
+  });
+
+export const text = (options: ColumnOptions & { readonly check?: string } = {}) =>
+  base<string>('text', asString(options.name ?? 'text'), options);
+
+const asBoolean =
+  (label: string) =>
+  (value: unknown): boolean =>
+    typeof value === 'boolean'
+      ? value
+      : reject(label, 'type', `expected a boolean, got ${typeof value}`);
+
+const asInteger =
+  (label: string) =>
+  (value: unknown): number =>
+    typeof value === 'number' && Number.isSafeInteger(value)
+      ? value
+      : reject(label, 'type', `expected a safe integer, got ${String(value)}`);
+
+const asCurrency =
+  (label: string) =>
+  (value: unknown): string =>
+    typeof value === 'string' && /^[A-Z]{3}$/.test(value)
+      ? value
+      : reject(label, 'iso-4217', `expected a 3-letter ISO-4217 code, got ${String(value)}`);
+
+export const boolean = (options: ColumnOptions = {}): ColumnDef<boolean> =>
+  base<boolean>('boolean', asBoolean(options.name ?? 'boolean'), options);
+
+export const integer = (
+  options: ColumnOptions & { readonly check?: string } = {},
+): ColumnDef<number> => base<number>('integer', asInteger(options.name ?? 'integer'), options);
+
+/** UTC always. A `timestamp without time zone` column is not expressible here. */
+export const timestamps = (): {
+  readonly createdAt: ColumnDef<Date>;
+  readonly updatedAt: ColumnDef<Date>;
+} => ({
+  createdAt: base<Date>('timestamptz', asDate('createdAt'), {
+    name: 'created_at',
+    default: { kind: 'generated', by: 'now' },
+    index: true,
+  }),
+  updatedAt: base<Date>('timestamptz', asDate('updatedAt'), {
+    name: 'updated_at',
+    default: { kind: 'generated', by: 'now' },
+  }),
+});
+
+export type MoneyColumns<N extends string> = {
+  readonly [K in `${N}Minor`]: ColumnDef<bigint>;
+} & {
+  readonly [K in `${N}Currency`]: ColumnDef<string>;
+};
+
+const asMinorUnits =
+  (label: string) =>
+  (value: unknown): bigint => {
+    if (typeof value === 'bigint') return value;
+    if (typeof value === 'number') {
+      if (!Number.isInteger(value)) {
+        return reject(
+          label,
+          'money-minor-units',
+          `got the float ${value}; money is integer minor units — 12.34 EUR is 1234n, not 12.34`,
+        );
+      }
+      return BigInt(value);
+    }
+    if (typeof value === 'string' && /^-?\d+$/.test(value)) return BigInt(value);
+    return reject(label, 'money-minor-units', `expected integer minor units, got ${String(value)}`);
+  };
+
+/**
+ * Two columns, always: minor units as bigint and an ISO-4217 code. A single-currency
+ * assumption is a migration nobody wants to write later, and a float is a rounding
+ * bug nobody wants to debug.
+ */
+export const money = <N extends string>(name: N): MoneyColumns<N> =>
+  ({
+    [`${name}Minor`]: base<bigint>('bigint', asMinorUnits(`${name}Minor`), {
+      name: `${snake(name)}_minor`,
+    }),
+    [`${name}Currency`]: base<string>('char', asCurrency(`${name}Currency`), {
+      name: `${snake(name)}_currency`,
+      length: 3,
+      check: `${snake(name)}_currency ~ '^[A-Z]{3}$'`,
+    }),
+  }) as unknown as MoneyColumns<N>;
+
+/** IANA identifier, validated by `Intl` at write time and by a CHECK in the database. */
+export const tz = (options: ColumnOptions = {}): ColumnDef<string> => {
+  const label = options.name ?? 'tz';
+  return base<string>(
+    'text',
+    (value) => {
+      if (typeof value === 'string') {
+        try {
+          new Intl.DateTimeFormat('en', { timeZone: value }).format(0);
+          return value;
+        } catch {
+          return reject(label, 'iana-tz', `${value} is not an IANA time zone`);
+        }
+      }
+      return reject(label, 'iana-tz', `expected an IANA time zone, got ${typeof value}`);
+    },
+    { ...options, check: `${snake(label)} ~ '^[A-Za-z0-9_+/-]{3,64}$'` },
+  );
+};
+
+export const locale = (options: ColumnOptions = {}): ColumnDef<string> => {
+  const label = options.name ?? 'locale';
+  return base<string>('text', asString(label), {
+    ...options,
+    check: `${snake(label)} ~ '^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$'`,
+  });
+};
+
+export const slug = (options: ColumnOptions = {}): ColumnDef<string> => {
+  const label = options.name ?? 'slug';
+  return base<string>('text', asString(label), {
+    ...options,
+    unique: true,
+    check: `${snake(label)} ~ '^[a-z0-9]+(-[a-z0-9]+)*$'`,
+  });
+};
+
+/** Takes its own parser: a jsonb column without a schema is an untyped hole. */
+export const jsonb = <T>(parse: (value: unknown) => T, options: ColumnOptions = {}): ColumnDef<T> =>
+  base<T>('jsonb', parse, options);
+
+/** Presence of this column is what makes an entity soft-deletable — not a flag. */
+export const softDelete = (): { readonly deletedAt: ColumnDef<Date | null> } => ({
+  deletedAt: base<Date | null>(
+    'timestamptz',
+    (value) => (value === null || value === undefined ? null : asDate('deletedAt')(value)),
+    { name: 'deleted_at', notNull: false, index: true },
+  ),
+});
+
+/** Presence of this column is what makes an entity tenant-scoped. See tenancy.ts. */
+export const orgId = (options: ColumnOptions & { readonly table?: string } = {}) =>
+  base<string>('uuid', asUuid('orgId'), {
+    name: options.name ?? 'org_id',
+    index: true,
+    references: { table: options.table ?? 'orgs', column: 'id', onDelete: 'cascade' },
+  });
+
+export const nullable = <T>(column: ColumnDef<T>): ColumnDef<T | null> => ({
+  ...column,
+  notNull: false,
+  parse: (value) => (value === null || value === undefined ? null : column.parse(value)),
+});
+
+export const references = <T>(column: ColumnDef<T>, target: string, targetColumn = 'id') => ({
+  ...column,
+  index: true,
+  references: { table: target, column: targetColumn },
+});
+
+/**
+ * Composes columns into a table, filling every column name that was left to the
+ * property key (`orgId` -> `org_id`) so a physical name is written at most once.
+ */
+export const table = <C extends ColumnMap>(name: string, columns: C): TableDef<C> => {
+  const resolved: Record<string, ColumnDef<unknown>> = {};
+  const primaryKey: string[] = [];
+  const indexes: IndexDef[] = [];
+  for (const [property, column] of Object.entries(columns)) {
+    const physical = column.name === '' ? snake(property) : column.name;
+    resolved[property] = { ...column, name: physical };
+    if (column.primaryKey) primaryKey.push(physical);
+    if (column.unique) {
+      indexes.push({ name: `${name}_${physical}_key`, columns: [physical], unique: true });
+    } else if (column.index) {
+      indexes.push({ name: `${name}_${physical}_idx`, columns: [physical], unique: false });
+    }
+  }
+  return {
+    name,
+    columns: resolved as unknown as C,
+    primaryKey: primaryKey.length > 0 ? primaryKey : ['id'],
+    indexes,
+  };
+};

package/src/entity.ts

@@ -0,0 +1,120 @@
+// `entity()` is the first primitive: a table, its domain type, and the invariants
+// that hold for every row. Everything downstream (repo, admin UI, cache tags, the
+// manifest) is derived from this one declaration.
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { invariantViolated } from './errors';
+import { assertInvariants, type Invariant, invariantsToSql } from './invariants';
+import { type EntityDescription, registerEntity } from './registry';
+import { isOrgScoped } from './tenancy';
+import type { ColumnMap, TableDef } from './types';
+
+export type EntitySchema<T> = StandardSchemaV1<unknown, T>;
+
+export interface EntityInit<T, C extends ColumnMap> {
+  /** Defaults to the table name. Must be unique across the app. */
+  readonly name?: string;
+  readonly table: TableDef<C>;
+  readonly type: EntitySchema<T>;
+  readonly invariants?: readonly Invariant<T>[];
+  /** Extra cache tags this entity participates in, beyond its own. */
+  readonly tags?: readonly string[];
+  /** Defaults to the presence of a `deletedAt` column. */
+  readonly softDelete?: boolean;
+}
+
+export interface Entity<T, C extends ColumnMap = ColumnMap> {
+  readonly name: string;
+  readonly table: TableDef<C>;
+  readonly type: EntitySchema<T>;
+  readonly invariants: readonly Invariant<T>[];
+  readonly tags: readonly string[];
+  /** `entity:<name>`. `@ultimat3/cache` invalidates by this string. */
+  readonly cacheTag: string;
+  readonly softDelete: boolean;
+  readonly orgScoped: boolean;
+  /** `entity:<name>:<id>` — row-level invalidation for live queries. */
+  tagFor(id: string): string;
+  /** Validates an unknown value into the domain type. Throws on failure. */
+  parse(value: unknown): T;
+  /** Runs every invariant. Called by the repository on insert and update. */
+  assert(row: T): void;
+  /** The CHECK/UNIQUE statements the migration emits for this entity. */
+  migration(): string;
+  describe(): EntityDescription;
+}
+
+interface LooseResult<T> {
+  readonly value?: T;
+  readonly issues?: readonly { readonly message: string }[] | undefined;
+}
+
+const parseWith = <T>(schema: EntitySchema<T>, name: string, value: unknown): T => {
+  const result = schema['~standard'].validate(value);
+  if (result instanceof Promise) {
+    throw invariantViolated(name, 'schema', 'entity types must validate synchronously');
+  }
+  const outcome = result as LooseResult<T>;
+  if (outcome.issues !== undefined && outcome.issues.length > 0) {
+    throw invariantViolated(name, 'schema', outcome.issues.map((i) => i.message).join('; '));
+  }
+  return outcome.value as T;
+};
+
+export const entity = <T, C extends ColumnMap>(init: EntityInit<T, C>): Entity<T, C> => {
+  const name = init.name ?? init.table.name;
+  const invariants = init.invariants ?? [];
+  const softDelete = init.softDelete ?? Object.hasOwn(init.table.columns, 'deletedAt');
+  const orgScoped = isOrgScoped(init.table);
+  const cacheTag = `entity:${name}`;
+
+  const describe = (): EntityDescription => ({
+    name,
+    table: init.table.name,
+    primaryKey: init.table.primaryKey,
+    columns: Object.entries(init.table.columns).map(([property, column]) => ({
+      property,
+      column: column.name,
+      kind: column.kind,
+      notNull: column.notNull,
+      primaryKey: column.primaryKey,
+      unique: column.unique,
+      hasDefault: column.default !== undefined,
+      check: column.check ?? null,
+      references:
+        column.references === undefined
+          ? null
+          : `${column.references.table}.${column.references.column}`,
+    })),
+    invariants: invariants.map((inv) => ({
+      name: inv.name,
+      kind: inv.kind,
+      message: inv.message,
+      sql: inv.sql,
+      where: inv.where ?? null,
+    })),
+    indexes: init.table.indexes.map((index) => index.name),
+    tags: [cacheTag, ...(init.tags ?? [])],
+    cacheTag,
+    softDelete,
+    orgScoped,
+  });
+
+  const built: Entity<T, C> = {
+    name,
+    table: init.table,
+    type: init.type,
+    invariants,
+    tags: [cacheTag, ...(init.tags ?? [])],
+    cacheTag,
+    softDelete,
+    orgScoped,
+    tagFor: (id) => `${cacheTag}:${id}`,
+    parse: (value) => parseWith(init.type, name, value),
+    assert: (row) => assertInvariants(name, invariants, row),
+    migration: () => invariantsToSql(init.table.name, invariants),
+    describe,
+  };
+
+  registerEntity({ name, tableName: init.table.name, describe });
+  return built;
+};

package/src/errors.ts

@@ -0,0 +1,73 @@
+// The entity layer's stable error codes. Each factory produces the exact command
+// that fixes the situation — `X_DB_DRIFT` is the flagship: it names the table, the
+// column and the generator invocation.
+import { UltimateError } from '@ultimat3/core';
+
+export const ENTITY_ERROR_CODES = [
+  'X_ENTITY_DUPLICATE',
+  'X_INVARIANT_VIOLATED',
+  'X_TENANCY_UNSCOPED',
+  'X_DB_DRIFT',
+  'X_NOT_FOUND',
+] as const;
+
+export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
+
+export const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>> = {
+  X_ENTITY_DUPLICATE: 'two entities claim the same name',
+  X_INVARIANT_VIOLATED: 'a domain invariant rejected this row',
+  X_TENANCY_UNSCOPED: 'a tenant-scoped query has no org predicate',
+  X_DB_DRIFT: 'schema differs from migrations',
+  X_NOT_FOUND: 'no row for that id',
+};
+
+export class EntityError extends UltimateError {
+  constructor(init: { code: EntityErrorCode; cause: string; fix: string }) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+      docs: `https://ultimate.dev/errors/${init.code}`,
+    });
+    this.name = 'EntityError';
+  }
+}
+
+export const entityDuplicate = (name: string, existingTable: string): EntityError =>
+  new EntityError({
+    code: 'X_ENTITY_DUPLICATE',
+    cause: `entity "${name}" is already registered for table "${existingTable}"`,
+    fix: `x entities list --json   # then rename one of the two entity({ name }) declarations`,
+  });
+
+export const invariantViolated = (
+  entityName: string,
+  invariantName: string,
+  message: string,
+): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.${invariantName}: ${message}`,
+    fix: `x entity explain ${entityName} --json   # shows the invariant and its SQL CHECK`,
+  });
+
+export const tenancyUnscoped = (entityName: string, operation: string): EntityError =>
+  new EntityError({
+    code: 'X_TENANCY_UNSCOPED',
+    cause: `${entityName}.${operation}() was built without an org predicate but the entity has an orgId column`,
+    fix: `pass { orgId } to ${entityName}.${operation}(), or wrap the plan with orgScoped(entity, orgId, plan)`,
+  });
+
+export const dbDrift = (tableName: string, columnName: string): EntityError =>
+  new EntityError({
+    code: 'X_DB_DRIFT',
+    cause: `table "${tableName}" has column "${columnName}" not present in any migration`,
+    fix: `x db gen "add ${columnName}"`,
+  });
+
+export const notFound = (entityName: string, id: string): EntityError =>
+  new EntityError({
+    code: 'X_NOT_FOUND',
+    cause: `${entityName} ${id} does not exist (or is soft-deleted)`,
+    fix: `x db query "select id from ${entityName} limit 5" --json   # confirm the id you expect`,
+  });

package/src/index.ts

@@ -0,0 +1,79 @@
+// The public surface of @ultimat3/entity. Explicit, never `export *`.
+
+export type { MoneyColumns } from './columns';
+export {
+  boolean,
+  id,
+  integer,
+  jsonb,
+  locale,
+  money,
+  newId,
+  nullable,
+  orgId,
+  references,
+  slug,
+  softDelete,
+  table,
+  text,
+  timestamps,
+  tz,
+} from './columns';
+export type { Entity, EntityInit, EntitySchema } from './entity';
+export { entity } from './entity';
+export type { EntityErrorCode } from './errors';
+export {
+  dbDrift,
+  ENTITY_ERROR_CODES,
+  ENTITY_ERROR_TITLES,
+  EntityError,
+  entityDuplicate,
+  invariantViolated,
+  notFound,
+  tenancyUnscoped,
+} from './errors';
+export type { CheckInit, Invariant, InvariantKind, UniqueInit } from './invariants';
+export {
+  assertInvariants,
+  constraintName,
+  invariant,
+  invariantsToSql,
+  toSql,
+  unique,
+} from './invariants';
+export type {
+  ColumnDescription,
+  EntityDescription,
+  InvariantDescription,
+  RegistryEntry,
+} from './registry';
+export {
+  clearRegistry,
+  describeEntities,
+  entityNames,
+  getEntity,
+  registerEntity,
+} from './registry';
+export type { FindManyArgs, Page, Repo, RepoOptions, Transactor, Tx } from './repo';
+export { decodeCursor, encodeCursor, memoryRepo, memoryTransactor } from './repo';
+export type { Operator, Predicate, QueryPlan, SortDirection } from './tenancy';
+export {
+  assertScoped,
+  describePlan,
+  emptyPlan,
+  hasOrgPredicate,
+  isOrgScoped,
+  ORG_COLUMN,
+  orgScoped,
+} from './tenancy';
+export type {
+  ColumnDef,
+  ColumnDefault,
+  ColumnKind,
+  ColumnMap,
+  IndexDef,
+  ReferenceDef,
+  RowOf,
+  TableDef,
+} from './types';
+export { columnNames, hasColumn } from './types';

package/src/invariants.ts

@@ -0,0 +1,96 @@
+// A domain invariant is written once and enforced twice: in the app on every write,
+// and in Postgres as a CHECK or UNIQUE constraint emitted into the migration. The
+// database can therefore never disagree with the code — a bulk import, a psql
+// session or a second service all hit the same rule.
+import { invariantViolated } from './errors';
+
+export type InvariantKind = 'check' | 'unique';
+
+export interface Invariant<T> {
+  /** Becomes the constraint name: `<table>_<name>_check`. Keep it snake_case. */
+  readonly name: string;
+  readonly kind: InvariantKind;
+  /** Safe to log and useful to an agent: says what was expected, not what leaked. */
+  readonly message: string;
+  /** SQL predicate for `check`, or the column list for `unique`. */
+  readonly sql: string;
+  readonly columns: readonly string[];
+  /** Partial-constraint predicate, e.g. `deleted_at is null`. */
+  readonly where?: string;
+  readonly holds: (row: T) => boolean;
+}
+
+export interface CheckInit<T> {
+  readonly message: string;
+  /** Postgres predicate over physical column names. */
+  readonly sql: string;
+  readonly holds: (row: T) => boolean;
+  readonly columns?: readonly string[];
+  readonly where?: string;
+}
+
+/** `invariant('price_positive', { sql: 'price_minor > 0', holds: (p) => p.priceMinor > 0n })` */
+export const invariant = <T>(name: string, init: CheckInit<T>): Invariant<T> => ({
+  name,
+  kind: 'check',
+  message: init.message,
+  sql: init.sql,
+  columns: init.columns ?? [],
+  ...(init.where === undefined ? {} : { where: init.where }),
+  holds: init.holds,
+});
+
+export interface UniqueInit<T> {
+  readonly message: string;
+  readonly columns: readonly string[];
+  /** In-app duplicate detection needs the store, so the app check defaults to true. */
+  readonly holds?: (row: T) => boolean;
+  readonly where?: string;
+}
+
+/**
+ * Uniqueness cannot be decided from a single row, so the app-side check is a no-op
+ * by default and the database is the authority. The unique index is still declared
+ * here so it lives next to the rule it implements.
+ */
+export const unique = <T>(name: string, init: UniqueInit<T>): Invariant<T> => ({
+  name,
+  kind: 'unique',
+  message: init.message,
+  sql: init.columns.join(', '),
+  columns: init.columns,
+  ...(init.where === undefined ? {} : { where: init.where }),
+  holds: init.holds ?? (() => true),
+});
+
+export const constraintName = (
+  table: string,
+  inv: { readonly name: string; readonly kind: InvariantKind },
+): string => `${table}_${inv.name}_${inv.kind === 'check' ? 'check' : 'key'}`;
+
+/** The DDL the migration emits. One statement, terminated, ready to diff. */
+export const toSql = <T>(table: string, inv: Invariant<T>): string => {
+  const name = constraintName(table, inv);
+  if (inv.kind === 'check') {
+    return `ALTER TABLE "${table}" ADD CONSTRAINT "${name}" CHECK (${inv.sql});`;
+  }
+  const where = inv.where === undefined ? '' : ` WHERE ${inv.where}`;
+  const columns = inv.columns.map((column) => `"${column}"`).join(', ');
+  return `CREATE UNIQUE INDEX "${name}" ON "${table}" (${columns})${where};`;
+};
+
+export const invariantsToSql = <T>(table: string, invariants: readonly Invariant<T>[]): string =>
+  invariants.map((inv) => toSql(table, inv)).join('\n');
+
+/** Runs on every write. Reports every violation at once so one round trip fixes all. */
+export const assertInvariants = <T>(
+  entityName: string,
+  invariants: readonly Invariant<T>[],
+  row: T,
+): void => {
+  const failed = invariants.filter((inv) => !inv.holds(row));
+  if (failed.length === 0) return;
+  const first = failed[0];
+  if (first === undefined) return;
+  throw invariantViolated(entityName, first.name, failed.map((inv) => inv.message).join('; '));
+};

package/src/registry.ts

@@ -0,0 +1,70 @@
+// The entity registry. Every `entity()` call registers here, which is what makes
+// `x.manifest.json`, the admin dashboard generator and the migration emitter able to
+// see the whole domain without importing it — and what makes a duplicate name a
+// build error rather than a silent last-one-wins.
+import { entityDuplicate } from './errors';
+
+export interface ColumnDescription {
+  readonly property: string;
+  readonly column: string;
+  readonly kind: string;
+  readonly notNull: boolean;
+  readonly primaryKey: boolean;
+  readonly unique: boolean;
+  readonly hasDefault: boolean;
+  readonly check: string | null;
+  readonly references: string | null;
+}
+
+export interface InvariantDescription {
+  readonly name: string;
+  readonly kind: 'check' | 'unique';
+  readonly message: string;
+  readonly sql: string;
+  readonly where: string | null;
+}
+
+export interface EntityDescription {
+  readonly name: string;
+  readonly table: string;
+  readonly primaryKey: readonly string[];
+  readonly columns: readonly ColumnDescription[];
+  readonly invariants: readonly InvariantDescription[];
+  readonly indexes: readonly string[];
+  readonly tags: readonly string[];
+  readonly cacheTag: string;
+  readonly softDelete: boolean;
+  readonly orgScoped: boolean;
+}
+
+export interface RegistryEntry {
+  readonly name: string;
+  readonly tableName: string;
+  describe(): EntityDescription;
+}
+
+const entities = new Map<string, RegistryEntry>();
+
+export const registerEntity = <E extends RegistryEntry>(entry: E): E => {
+  const existing = entities.get(entry.name);
+  if (existing !== undefined && existing !== entry) {
+    throw entityDuplicate(entry.name, existing.tableName);
+  }
+  entities.set(entry.name, entry);
+  return entry;
+};
+
+export const getEntity = (name: string): RegistryEntry | undefined => entities.get(name);
+
+export const entityNames = (): readonly string[] => [...entities.keys()].sort();
+
+/** Deterministic order: the manifest is a build artefact and must diff cleanly. */
+export const describeEntities = (): readonly EntityDescription[] =>
+  entityNames().map((name) => {
+    const entry = entities.get(name);
+    if (entry === undefined) throw entityDuplicate(name, 'unknown');
+    return entry.describe();
+  });
+
+/** Test seam. Production code never unregisters an entity. */
+export const clearRegistry = (): void => entities.clear();

package/src/tenancy.ts

@@ -0,0 +1,86 @@
+// Multi-tenancy is a guard, not a convention. An entity with an `orgId` column can
+// only be queried through a plan that carries an org predicate; building one without
+// it throws `X_TENANCY_UNSCOPED` at the seam instead of leaking another tenant's rows.
+import { tenancyUnscoped } from './errors';
+import type { TableDef } from './types';
+
+export type Operator =
+  | 'eq'
+  | 'neq'
+  | 'in'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'like'
+  | 'is-null'
+  | 'is-not-null';
+
+export interface Predicate {
+  readonly column: string;
+  readonly op: Operator;
+  readonly value?: unknown;
+}
+
+export type SortDirection = 'asc' | 'desc';
+
+export interface QueryPlan {
+  readonly entity: string;
+  readonly where: readonly Predicate[];
+  readonly orderBy: readonly { readonly column: string; readonly direction: SortDirection }[];
+  readonly limit: number;
+  readonly cursor?: string;
+}
+
+export const ORG_COLUMN = 'orgId';
+
+/** True when the table declares an `orgId` column — presence is the switch. */
+export const isOrgScoped = (table: TableDef): boolean => Object.hasOwn(table.columns, ORG_COLUMN);
+
+export const emptyPlan = (entity: string, limit = 50): QueryPlan => ({
+  entity,
+  where: [],
+  orderBy: [],
+  limit,
+});
+
+export const hasOrgPredicate = (plan: QueryPlan): boolean =>
+  plan.where.some((predicate) => predicate.column === ORG_COLUMN);
+
+/** Adds the org predicate exactly once; calling it twice is not an error. */
+export const orgScoped = (plan: QueryPlan, orgId: string): QueryPlan =>
+  hasOrgPredicate(plan)
+    ? plan
+    : { ...plan, where: [...plan.where, { column: ORG_COLUMN, op: 'eq', value: orgId }] };
+
+/**
+ * Called by every repository operation. Runtime here, and a build-time check in
+ * `x verify` that no query for a tenant-scoped entity is constructed without it.
+ */
+export const assertScoped = (
+  entityName: string,
+  table: TableDef,
+  operation: string,
+  plan: QueryPlan,
+): void => {
+  if (!isOrgScoped(table)) return;
+  if (hasOrgPredicate(plan)) return;
+  throw tenancyUnscoped(entityName, operation);
+};
+
+/** Debug/`x db explain` rendering. Values stay out: a plan is safe to log. */
+export const describePlan = (plan: QueryPlan): string => {
+  const where = plan.where
+    .map((predicate) => `${predicate.column} ${predicate.op} ?`)
+    .join(' and ');
+  const order = plan.orderBy.map((entry) => `${entry.column} ${entry.direction}`).join(', ');
+  return [
+    `from ${plan.entity}`,
+    where === '' ? null : `where ${where}`,
+    order === '' ? null : `order by ${order}`,
+    `limit ${plan.limit}`,
+    plan.cursor === undefined ? null : 'after cursor',
+  ]
+    .filter((part): part is string => part !== null)
+    .join(' ');
+};

package/src/types.ts

@@ -0,0 +1,77 @@
+// The narrow structural types this package consumes. Drizzle is the production
+// backing for `TableDef`/`ColumnDef` (see README), but declaring the shape we use
+// instead of depending on the ORM keeps the generated SQL readable and keeps this
+// package free of a dependency an agent would have to learn to read.
+
+/** Postgres types the blessed column helpers emit. No `float` for money, ever. */
+export type ColumnKind =
+  | 'uuid'
+  | 'text'
+  | 'char'
+  | 'boolean'
+  | 'integer'
+  | 'bigint'
+  | 'numeric'
+  | 'timestamptz'
+  | 'date'
+  | 'jsonb';
+
+export type ColumnDefault =
+  | { readonly kind: 'sql'; readonly expression: string }
+  | { readonly kind: 'value'; readonly value: string | number | boolean | null }
+  | { readonly kind: 'generated'; readonly by: 'uuid-v7' | 'now' };
+
+export interface ReferenceDef {
+  readonly table: string;
+  readonly column: string;
+  readonly onDelete?: 'cascade' | 'restrict' | 'set null';
+}
+
+export interface ColumnDef<T> {
+  /** snake_case physical name; the property key is the camelCase domain name. */
+  readonly name: string;
+  readonly kind: ColumnKind;
+  readonly notNull: boolean;
+  readonly primaryKey: boolean;
+  readonly unique: boolean;
+  readonly length?: number;
+  readonly default?: ColumnDefault;
+  /** SQL expression emitted as a CHECK next to the column. */
+  readonly check?: string;
+  readonly references?: ReferenceDef;
+  readonly index: boolean;
+  readonly comment?: string;
+  /**
+   * Runtime guard AND the carrier of the column's TypeScript type. Every write goes
+   * through it, which is how `money()` can refuse a float instead of rounding it.
+   */
+  readonly parse: (value: unknown) => T;
+}
+
+export type ColumnMap = Readonly<Record<string, ColumnDef<unknown>>>;
+
+export interface IndexDef {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+  /** Partial index predicate — soft-deleted rows are excluded with this. */
+  readonly where?: string;
+}
+
+export interface TableDef<C extends ColumnMap = ColumnMap> {
+  readonly name: string;
+  readonly columns: C;
+  readonly primaryKey: readonly string[];
+  readonly indexes: readonly IndexDef[];
+}
+
+/** The row type a table describes, derived from its columns' parse signatures. */
+export type RowOf<C extends ColumnMap> = {
+  readonly [K in keyof C]: C[K] extends ColumnDef<infer T> ? T : never;
+};
+
+export const columnNames = (table: TableDef): readonly string[] =>
+  Object.values(table.columns).map((column) => column.name);
+
+export const hasColumn = (table: TableDef, property: string): boolean =>
+  Object.hasOwn(table.columns, property);