equipped 5.2.9 → 5.3.0-alpha.0

package/CHANGELOG.md

@@ -2,6 +2,94 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [5.3.0-alpha.0](https://github.com/kevinand11/equipped/compare/v5.2.9...v5.3.0-alpha.0) (2026-06-16)
+
+
+### ⚠ BREAKING CHANGES
+
+* **orm:** `Where`, `WhereOp`, `WhereGroupOp`, `QueryGroup`,
+`WhereFactory`, and `FilterOp` are removed from the public API.
+Use `Filter`, `FilterGroup`, and `FilterFactory` from `filter.ts`.
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+* **orm:** EventAudit class and all types exported from
+src/audit/ are removed. Migrate to EventLog via
+EventLog.from(repo).build().handler(name, def).
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+* bump version to 6.0.0 for breaking-change lockdown
+* **orm:** delete Adapter.from builder; finalize class-based narrowing
+
+### Features
+
+* computed fields ([d1abd3e](https://github.com/kevinand11/equipped/commit/d1abd3ead8614490a5ca7c0b129e5ab4f59ede78))
+* configurable ([01e3b32](https://github.com/kevinand11/equipped/commit/01e3b329fc5c828324b1e1d826d57c85b550805f))
+* fields and schema fields ([e67a768](https://github.com/kevinand11/equipped/commit/e67a768e21a4d3720e85494be584d91260b31983))
+* implement FilterGroup + queryable behaviour + filter normalisation ([507a8b2](https://github.com/kevinand11/equipped/commit/507a8b2dba27a0ad491b6876bf18f42c7a17a198)), closes [#1](https://github.com/kevinand11/equipped/issues/1) [#5](https://github.com/kevinand11/equipped/issues/5)
+* orm adapters ([cc56149](https://github.com/kevinand11/equipped/commit/cc56149e5bde7fbc532eeede10b9bba2b7a68b20))
+* orm insert path + validation pipeline + OrmValidationError ([9337445](https://github.com/kevinand11/equipped/commit/93374453817848c1cb419c45ec2ae56f593ba85d)), closes [#3](https://github.com/kevinand11/equipped/issues/3) [#1](https://github.com/kevinand11/equipped/issues/1)
+* orm query ([c62f321](https://github.com/kevinand11/equipped/commit/c62f321108660b3843f6f38f81d8d597cb9a9236))
+* orm repo ([0755998](https://github.com/kevinand11/equipped/commit/0755998819384e84e5666c6d2f7d30f3b86fabb8))
+* orm schema ([a360b7e](https://github.com/kevinand11/equipped/commit/a360b7e3bf39a540eae2408cc78cc72abd51d9ea))
+* **orm/postgresql:** migrate PG adapter to defineAdapter shape (issue [#12](https://github.com/kevinand11/equipped/issues/12), PRD [#1](https://github.com/kevinand11/equipped/issues/1)) ([492e1c8](https://github.com/kevinand11/equipped/commit/492e1c8ef715be7ae7d91ccd723a5df684e78f75))
+* **orm:** add .required() modifier to OneBuilder with Req typestate ([e987ae9](https://github.com/kevinand11/equipped/commit/e987ae94c50a4e8d0e7e661f0fb0ad25989e1292))
+* **orm:** add adapter iteration primitive ([6c7ef2b](https://github.com/kevinand11/equipped/commit/6c7ef2b37068bce46d094c054b8f7f2b75728089))
+* **orm:** add AggregateBuilder with count-only end-to-end via in-memory ([e77e9da](https://github.com/kevinand11/equipped/commit/e77e9da81f5ea2ebd7ebb97868edcfb1a4266ab5))
+* **orm:** add canonical AggregateOpName type and aggregateOps capability ([a67605c](https://github.com/kevinand11/equipped/commit/a67605cc9a4eadaf68d23cb71ea6d23b698fcf5c))
+* **orm:** add EventLog foundations and atomic fire path ([9fe567e](https://github.com/kevinand11/equipped/commit/9fe567e02ee69ebec2fe7879233edf305aed95e4))
+* **orm:** add EventLog replay and rerun with per-event session isolation ([ac1ad61](https://github.com/kevinand11/equipped/commit/ac1ad6103883438059c6a26294be048324880048))
+* **orm:** add filter-only count terminal ([ff511be](https://github.com/kevinand11/equipped/commit/ff511be634112720ac4cb9506d2f13e9177e903c))
+* **orm:** add full Change algebra (10 remaining variants) + full validation + migrationId/changeIndex ([2ec765f](https://github.com/kevinand11/equipped/commit/2ec765f2be31264a3cefd64f242d6eba2c5885e0)), closes [#1](https://github.com/kevinand11/equipped/issues/1) [#1](https://github.com/kevinand11/equipped/issues/1) [#1](https://github.com/kevinand11/equipped/issues/1)
+* **orm:** add iteration options validation ([92bde6f](https://github.com/kevinand11/equipped/commit/92bde6f6ba54e2ed6b4ee84d658b7ab0e676ea18))
+* **orm:** add MigrationCodegen + introspect (in-memory adapter) ([5897662](https://github.com/kevinand11/equipped/commit/58976620009ac2bd27488dd30f004460b010f3dd))
+* **orm:** add migrations foundation tracer-bullet ([2c1602b](https://github.com/kevinand11/equipped/commit/2c1602b107fd4d4693246d26f7bc08d034dcf7e1)), closes [#103](https://github.com/kevinand11/equipped/issues/103)
+* **orm:** add Migrator opts (to/steps), status(), dry(), orphan detection + error phases ([ba680b6](https://github.com/kevinand11/equipped/commit/ba680b6e5dd4c74ea3d69b681e90b02088514c45))
+* **orm:** add Mongo adapter migration methods + structural narrowing fix ([3a60395](https://github.com/kevinand11/equipped/commit/3a603953e5301c722f2a985733251b5d7fe4ce5a))
+* **orm:** add MongoDB adapter aggregate pipeline compiler ([f027e64](https://github.com/kevinand11/equipped/commit/f027e647bbe51e0cbed32b80e957c3c26dec3637))
+* **orm:** add OrmAdapter abstract base class and Repo dispatch validator ([accff9f](https://github.com/kevinand11/equipped/commit/accff9f0260e6d473323e91c6bdf7b12d8056e84))
+* **orm:** add OrmNotFoundError class ([18addab](https://github.com/kevinand11/equipped/commit/18addab294c66850e525f6030fe850bb98b3eb1b))
+* **orm:** add paginated all-query envelope ([1defc89](https://github.com/kevinand11/equipped/commit/1defc89a33a0cd29634ab7ff41bf792d809e0c8e))
+* **orm:** add per-migration tx + cluster-safe lock to Migrator ([88d6752](https://github.com/kevinand11/equipped/commit/88d6752b95f2c6af55e9e9bd55bae53b8af7152d)), closes [#104](https://github.com/kevinand11/equipped/issues/104)
+* **orm:** add Postgres adapter migration implementation ([e6cde0c](https://github.com/kevinand11/equipped/commit/e6cde0c1bcbb77f797f37a3d812d8faffc6b9d3c))
+* **orm:** add read query-shape pagination validation ([d2f3b00](https://github.com/kevinand11/equipped/commit/d2f3b00a67ffe053eab12b04e2145f4d899c3e5c))
+* **orm:** complete AggregateBuilder surface (groupBy, aggregators, where/having) ([6bede84](https://github.com/kevinand11/equipped/commit/6bede84df409da31738f31cf4767cd871b2941f6))
+* **orm:** complete walking skeleton type safety + remove adapter cast gap ([0a04718](https://github.com/kevinand11/equipped/commit/0a04718f0a03993ead6bd010e51ab305a867aa87)), closes [#2](https://github.com/kevinand11/equipped/issues/2) [#2](https://github.com/kevinand11/equipped/issues/2) [#5](https://github.com/kevinand11/equipped/issues/5)
+* **orm:** export AggregateBuilder from public barrel ([2c312f7](https://github.com/kevinand11/equipped/commit/2c312f75bc60dd3025ff7852404a90d22e77053b))
+* **orm:** extend OrmValidationError with aggregate kind and alias carrier ([39e4006](https://github.com/kevinand11/equipped/commit/39e4006890b8ce446799d73f93122ee04fd32c36))
+* **orm:** filter-based mutations + deleteByPk + raw escape hatch ([5bbf877](https://github.com/kevinand11/equipped/commit/5bbf87742198709c513bf6f61fb3795798f8d9a2)), closes [#6](https://github.com/kevinand11/equipped/issues/6) [#1](https://github.com/kevinand11/equipped/issues/1)
+* **orm:** implement JSON adapter migrations ([6b9ae13](https://github.com/kevinand11/equipped/commit/6b9ae132131b5776bc55c7dc0c680f606e94823d))
+* **orm:** implement PostgreSQL adapter aggregate compiler ([3a06688](https://github.com/kevinand11/equipped/commit/3a06688a7474119ae1497382e4af8d5fbdad519a))
+* **orm:** implement walking skeleton for defineSchema/defineAdapter/defineRepo ([2ab2c8e](https://github.com/kevinand11/equipped/commit/2ab2c8ea6ae5f8c3d299cf6d01e650ec32ce9d1e)), closes [#2](https://github.com/kevinand11/equipped/issues/2) [#2](https://github.com/kevinand11/equipped/issues/2)
+* **orm:** json adapter aggregate delegation to in-memory ([dedb42c](https://github.com/kevinand11/equipped/commit/dedb42cc381a5eafdb6eafff357201da3f0d9ffb))
+* **orm:** stream postgresql iteration through cursors ([ac18e17](https://github.com/kevinand11/equipped/commit/ac18e1757270dd77d21cae2f2e323003c888dd09))
+* **orm:** update path + op helpers + auto-bump + conflict rejection ([2ee0bfa](https://github.com/kevinand11/equipped/commit/2ee0bfa5d63dc60b62a0621adbfbf120ada3f0a6)), closes [#4](https://github.com/kevinand11/equipped/issues/4)
+* **orm:** upsert dual-path — schema-per-call upsertOne with insert+ops ([0d5f275](https://github.com/kevinand11/equipped/commit/0d5f27544a621916b4ed31753f56e854067203ff)), closes [#8](https://github.com/kevinand11/equipped/issues/8) [#1](https://github.com/kevinand11/equipped/issues/1)
+* projection ([eac52a3](https://github.com/kevinand11/equipped/commit/eac52a3ddd7a385f77f522de811e724852dfd14c))
+* raw command ([6a56326](https://github.com/kevinand11/equipped/commit/6a56326de92246f0d45ffe407fabd15aabbfcb1d))
+
+
+### Bug Fixes
+
+* align README with insert→create and repo.from→repo.on renames ([3378a84](https://github.com/kevinand11/equipped/commit/3378a84981919768eba0d6c0dad9328e95c683aa))
+* one relation return type ([17f05f2](https://github.com/kevinand11/equipped/commit/17f05f273112ac18c85ad3fb3edb8c76dd341e0f))
+* **orm:** drop past-last pagination neighbors ([6ff12da](https://github.com/kevinand11/equipped/commit/6ff12daa0224e180902e7ca6c56625597203d174))
+* **orm:** honor batch size in non-postgres iteration ([acd605a](https://github.com/kevinand11/equipped/commit/acd605acd62bcb3aaeae9fea1b8f7dc489d0a386))
+* **orm:** move ssl into postgresqlConnectionPipe with v.defaults ([a5aafe8](https://github.com/kevinand11/equipped/commit/a5aafe8ac41f90534de8f7ac9a6d2afc54f8f1f3))
+* **orm:** narrow deleteOne fallback to PK filter and remove dead ordering getters ([0e56628](https://github.com/kevinand11/equipped/commit/0e56628074b8245f0ed10862ef577e6dc27e61fd))
+* **orm:** remove unnecessary type cast in schema.pk() ([1cbda00](https://github.com/kevinand11/equipped/commit/1cbda00421223e00a5260eacd62a8f5d583dda23))
+* **orm:** restore direct iterate generator ([bc8a33b](https://github.com/kevinand11/equipped/commit/bc8a33be0884bad22f73d2dbeb6d699d7ac0ba16))
+* **orm:** validate explicit undefined read limits ([3d7c85f](https://github.com/kevinand11/equipped/commit/3d7c85f2c99827cfe0fbf879dc8a14448aa94c12))
+* **postgresql:** use pg-cursor type package ([b6971c7](https://github.com/kevinand11/equipped/commit/b6971c7bed83b61772f58f5d8bd24281b5fc4fe8))
+* pr cleanup ([cc306b6](https://github.com/kevinand11/equipped/commit/cc306b697c242110409703cb67f7c2849ece445d))
+* resolve merge conflict with feature/orm ([e00169a](https://github.com/kevinand11/equipped/commit/e00169a9377a6418f7168f525a06df18c4a8006f))
+* resolve merge conflicts with feature/orm (static-factory refactor) ([6ed7369](https://github.com/kevinand11/equipped/commit/6ed7369efa838ff0e9b54dd139658de5efe84154))
+
+
+* bump version to 6.0.0 for breaking-change lockdown ([927b04a](https://github.com/kevinand11/equipped/commit/927b04a8a39ae06e41f89883183769f81fbecdbf)), closes [#45](https://github.com/kevinand11/equipped/issues/45) [#45](https://github.com/kevinand11/equipped/issues/45) [#46](https://github.com/kevinand11/equipped/issues/46) [#47](https://github.com/kevinand11/equipped/issues/47) [#48](https://github.com/kevinand11/equipped/issues/48) [#54](https://github.com/kevinand11/equipped/issues/54)
+* **orm:** consolidate query.ts into filter.ts + query-options.ts ([f96b3b0](https://github.com/kevinand11/equipped/commit/f96b3b051d673f2c62833daa62c9b3c1e631ff5e))
+* **orm:** delete Adapter.from builder; finalize class-based narrowing ([cec1fa0](https://github.com/kevinand11/equipped/commit/cec1fa0b9785d72f9f62bb1c9aaba6cc75f123df))
+* **orm:** delete legacy src/audit/ EventAudit module ([e99d042](https://github.com/kevinand11/equipped/commit/e99d042eb339f58b1f6a40178b03d184a6ef0312))
+
 ### [5.2.9](https://github.com/kevinand11/equipped/compare/v5.2.8...v5.2.9) (2026-03-21)
 
 

package/README.md

@@ -4,7 +4,7 @@ Equipped is a comprehensive, batteries-included, and opinionated full-stack fram
 
 ## Core Features
 
--   **All-in-One**: Integrated server (Fastify/Express), database (MongoDB), caching (Redis), job queue (Bull/Redis), and event bus (Kafka/RabbitMQ).
+-   **All-in-One**: Integrated server (Fastify/Express), typed ORM (adapter-agnostic), caching (Redis), job queue (Bull/Redis), and event bus (Kafka/RabbitMQ).
 -   **Type-Safe**: End-to-end type safety from environment variables and configuration to database models and API routes.
 -   **Modular & Opinionated**: Sensible defaults and a modular design allow you to enable only the features you need, while providing a clear structure for your application.
 -   **Lifecycle Management**: Coordinated startup and shutdown hooks (`setup`, `start`, `close`) ensure graceful initialization and termination of all components.
@@ -84,7 +84,7 @@ The `Instance` class is the heart of an Equipped application. It's a singleton t
 
 -   **`Instance.create(envsPipe, settings)`**: Initializes the singleton instance. It must be called only once. It validates environment variables and settings before creating the instance.
 -   **`Instance.get()`**: Retrieves the active instance. Throws an error if `create` has not been called.
--   **`Instance.on(event, callback, order)`**: Registers a lifecycle hook.
+-   **`Instance.on(event, callback, options?)`**: Registers a lifecycle hook.
     -   `setup`: Runs once before `start`. Ideal for setting up connections or listeners.
     -   `start`: Runs after `setup`. The primary phase for starting services.
     -   `close`: Runs when the application is shutting down (e.g., via `SIGINT`).
@@ -198,46 +198,374 @@ router.post('/upload')({
 });
 ```
 
-## Database (MongoDB)
+## ORM
 
-Equipped provides a powerful abstraction layer for MongoDB, including type-safe queries, models, and change streams.
+Equipped ships a typed, capability-aware ORM built on the stack **Schema → Relations → Adapter → Repo**. The package ships no database drivers — adapters (including the in-tree MongoDB and PostgreSQL adapters) declare exactly what they support, and the Repo's TypeScript surface narrows to match. Calling a method the adapter doesn't implement is a compile error, not a runtime throw.
+
+### Defining a Schema
+
+A Schema describes a single document shape — name, primary key, data fields, and optional computed fields. Schemas are adapter-agnostic and carry `valleyed` pipes for validation.
 
 ```typescript
-// 1. Define a model and an entity class
-class UserEntity extends DataClass {
-    constructor(data: PipeOutput<typeof UserEntity.schema>) {
-        super(data);
-    }
-    static schema = v.object({
-        _id: v.string(),
-        name: v.string(),
-        email: v.string().pipe(v.email()),
-        createdAt: v.number(),
-        updatedAt: v.number(),
-    });
+import { Schema } from 'equipped/orm'
+
+const UserSchema = Schema.from('users')
+    .pk('id', v.string(), () => crypto.randomUUID())
+    .field('email', v.string())
+    .field('name', v.string())
+    .field('age', v.number())
+    .field('orgId', v.string())
+    .field('tags', v.array(v.string()))
+    .field('bio', v.optional(v.string()), { onCreate: () => undefined })
+    .field('createdAt', v.number(), { onCreate: () => Date.now() })
+    .field('updatedAt', v.number(), {
+        onCreate: () => Date.now(),
+        onUpdate: () => Date.now(),
+    })
+    .build()
+```
+
+-   **`pk(name, pipe, generator)`** — declares the primary key. The generator runs on create.
+-   **`field(name, pipe, opts?)`** — declares a data field. Optional `onCreate` / `onUpdate` generators auto-inject values.
+-   **`computed(name, deps, pipe, compute)`** — declares a derived field computed from persisted dependencies.
+
+Fields with `onUpdate` generators auto-bump on every update unless the update explicitly touches that field.
+
+### Defining Relations
+
+Relations live in a separate artifact from the schema. They wire `hasMany` / `hasOne` / `belongsTo` descriptors using schema-tagged Field references as foreign keys.
+
+```typescript
+import { Relations, Schema } from 'equipped/orm'
+
+const PostSchema = Schema.from('posts')
+    .pk('id', v.string(), () => crypto.randomUUID())
+    .field('title', v.string())
+    .field('userId', v.string())
+    .build()
+
+const ProfileSchema = Schema.from('profiles')
+    .pk('id', v.string(), () => crypto.randomUUID())
+    .field('bio', v.string())
+    .field('userId', v.string())
+    .build()
+
+const OrgSchema = Schema.from('orgs')
+    .pk('id', v.string(), () => crypto.randomUUID())
+    .field('name', v.string())
+    .build()
+
+const UserRelations = Relations.from(UserSchema)
+    .hasMany('posts', PostSchema.fields.userId)
+    .hasOne('profile', ProfileSchema.fields.userId)
+    .belongsTo('org', UserSchema.fields.orgId, OrgSchema)
+    .build()
+```
+
+-   **`hasMany(name, fk)`** — one-to-many. The FK lives on the target schema; target is inferred from the FK's phantom schema tag.
+-   **`hasOne(name, fk)`** — one-to-one. Same FK-driven inference as `hasMany`.
+-   **`belongsTo(name, fk, target, references?)`** — many-to-one. The FK lives on the source schema.
+-   **FK type-safety** — FKs must be `Field` instances (not raw strings), and pointing a string FK at a number PK is a compile error.
+-   **Self-referential** — works without special casing: `belongsTo('manager', src.fields.managerId, UserSchema)`.
+-   **Many-to-many** — modelled via an explicit join schema with two `belongsTo` relations.
+
+### Defining an Adapter
+
+An Adapter declares capabilities via three closed canonical sets and four optional behaviour bags, then implements the methods for each bag it declares.
+
+```typescript
+import { Adapter } from 'equipped/orm'
+
+const adapter = Adapter.from<{ table: string }>()
+    .supportedFieldTypes('string', 'number', 'boolean', 'null', 'object', 'array', 'date')
+    .queryableOps('eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn')
+    .updateOps('set', 'inc', 'mul')
+    .lifecycle({
+        connect: async () => { /* open pool */ },
+        disconnect: async () => { /* close pool */ },
+    })
+    .crud({
+        findByPk: async (schema, config, pk) => { /* ... */ },
+        createMany: async (schema, config, data) => { /* ... */ },
+        updateByPk: async (schema, config, pk, ops) => { /* ... */ },
+        deleteByPk: async (schema, config, pk) => { /* ... */ },
+        raw: async (schema, config, command, params) => { /* ... */ },
+    })
+    .queryable({
+        findMany: async (schema, config, filter, options) => { /* ... */ },
+        updateMany: async (schema, config, filter, data) => { /* ... */ },
+        deleteMany: async (schema, config, filter) => { /* ... */ },
+        upsertOne: async (schema, config, filter, create, ops) => { /* ... */ },
+    })
+    .transactional({
+        session: async (fn) => { /* ... */ },
+    })
+    .build()
+```
+
+#### Capability Declarations
+
+| Declaration | Values |
+|---|---|
+| `supportedFieldTypes` | `string`, `number`, `boolean`, `null`, `object`, `array`, `date` |
+| `queryableOps` | `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn`, `like`, `exists`, `notExists`, `contains`, `notContains` |
+| `updateOps` | `set`, `inc`, `mul`, `min`, `max`, `unset`, `push`, `pull`, `patch` |
+
+Adapters subset these sets — they cannot extend them. Extension requires a package version bump.
+
+#### Behaviour Bags
+
+| Bag | Methods | Purpose |
+|---|---|---|
+| `lifecycle` | `connect`, `disconnect` | Connection management |
+| `crud` | `findByPk`, `createMany`, `updateByPk`, `deleteByPk`, `raw` | PK-keyed and raw operations |
+| `queryable` | `findMany`, `updateMany`, `deleteMany`, `upsertOne` | Filter-based operations |
+| `transactional` | `session` | Transaction support |
+
+Every bag and every method within a bag is independently optional. An adapter that only declares `crud` with `findByPk` is a valid read-only, PK-only adapter.
+
+**Co-required pair**: `.queryable()` requires `.queryableOps()` to have been called with a non-empty list. Calling `.queryable()` without it is both a compile error and a runtime throw.
+
+**No-emulation rule**: the framework never silently emulates a missing op or behaviour client-side. If the adapter doesn't declare it, the Repo method doesn't exist at the type level. Adapter-specific power lives in `raw` only.
+
+The in-tree adapters live under `src/orm/adapters/` — see their individual READMEs for session nesting behaviour and upsert-compatible filter shapes:
+-   [MongoDB adapter](src/orm/adapters/mongodb/README.md)
+-   [PostgreSQL adapter](src/orm/adapters/postgresql/README.md)
+
+### Defining a Repo
+
+A Repo wraps an adapter and provides the schema-per-call surface. One Repo handles all schemas — no registry, no per-schema derivation.
+
+```typescript
+import { Repo } from 'equipped/orm'
+
+const repo = Repo.from(adapter)
+    .resolve((schema) => ({ table: schema.name }))
+    .build()
+```
+
+-   **`Repo.from(adapter)`** — starts the builder, binding the adapter.
+-   **`.resolve(fn)`** — maps schema → adapter config. Called once.
+
+### Repository API
+
+All CRUD goes through `repo.on(Schema)`, which returns a `SchemaRef` that branches into `.one()` (single document) or `.all()` (collection). The Repo's only consumer-facing methods are `on(schema)`, `resolve(transform, fn)`, and `session(fn)`.
+
+```typescript
+// Create
+const user = await repo.on(UserSchema).one().create({ email: 'a@b.com', name: 'Alice' })
+const users = await repo.on(UserSchema).all().create([
+    { email: 'a@b.com', name: 'Alice' },
+    { email: 'b@c.com', name: 'Bob' },
+])
+
+// Read by PK
+const found = await repo.on(UserSchema).one().id('u1').find()
+
+// Read a stable paginated envelope. Use deterministic ordering for stable pages.
+const page = await repo.on(UserSchema).all()
+    .where((q) => q.eq('name', 'Alice'))
+    .orderBy('createdAt', 'desc')
+    .page(3)
+    .limit(10)
+    .paginate()
+
+console.log(page.items) // page documents
+console.log(page.pages) // { current, start, last, previous, next }
+console.log(page.docs) // { limit, total, count }
+
+// Select specific fields
+const partial = await repo.on(UserSchema).all()
+    .select(['id', 'name'])
+    .find()
+
+// Preload relations
+const withPosts = await repo.on(UserSchema).one().id('u1')
+    .preload([UserRelations.posts, UserRelations.org])
+    .find()
+
+// Iterate a bounded query one document at a time
+for await (const user of repo.on(UserSchema).all()
+    .where((q) => q.eq('active', true))
+    .orderBy('createdAt', 'desc')
+    .limit(100)
+    .iterate()) {
+    console.log(user.email)
 }
+// .iterate() is query iteration over the current result set. It is not a
+// realtime stream, change feed, CDC listener, watch, or subscription API.
+
+// Update
+const updated = await repo.on(UserSchema).one().id('u1').update({ name: 'New Name' })
+const allUpdated = await repo.on(UserSchema).all()
+    .where((q) => q.eq('name', 'Old'))
+    .update({ name: 'New' })
+
+// Upsert
+const upserted = await repo.on(UserSchema).one()
+    .where((q) => q.eq('email', 'a@b.com'))
+    .upsert({ create: { email: 'a@b.com', name: 'Alice' } })
+
+// Delete
+const deleted = await repo.on(UserSchema).one().id('u1').delete()
+const allDeleted = await repo.on(UserSchema).all()
+    .where((q) => q.eq('name', 'ToDelete'))
+    .delete()
+
+// Raw
+const raw = await repo.on(UserSchema).raw('SELECT * FROM users')
+```
 
-// 2. Configure the database in settings
-// dbs: { types: { mongo: { type: 'mongo', uri: envs.MONGO_URI } } }
-
-// 3. Access the table through the instance
-const users = instance.dbs.mongo.use<PipeOutput<typeof UserEntity.schema>, UserEntity>({
-    db: 'main-db',
-    col: 'users',
-    mapper: (e) => new UserEntity(e),
-    // Optional: Listen for database changes
-    change: {
-        created: async ({ after }) => console.log(`User created: ${after.name}`),
-        updated: async ({ after }) => console.log(`User updated: ${after.name}`),
-        deleted: async ({ before }) => console.log(`User deleted: ${before.name}`),
-    }
-});
+Builder snapshots are immutable — branching from a base builder does not mutate the original.
 
-// 4. Use the table methods
-const newUser = await users.insertOne({ name: 'Jane Doe', email: 'jane@example.com' });
-const foundUser = await users.findById(newUser._id);
+**Transactions** (gated by `transactional.session`):
+
+```typescript
+const result = await repo.session(async () => {
+    const user = await repo.on(UserSchema).one().create({ email: 'a@b.com', name: 'Alice' })
+    await repo.on(PostSchema).one().create({ title: 'Hello', userId: user.id })
+    return user.id
+})
+// Throw inside the callback → automatic rollback
+```
+
+#### Method Gating
+
+Builder methods are gated by the adapter's capability declarations. Methods whose bag or sub-method isn't declared collapse to `never` at the type level:
+
+| Builder method | Required adapter capability |
+|---|---|
+| `schemaRef.raw()` | `crud.raw` |
+| `one().update()` / `all().update()` | `queryable.updateMany` |
+| `one().delete()` / `all().delete()` | `queryable.deleteMany` |
+| `all().iterate()` | `queryable.iterateMany` |
+| `one().upsert()` | `queryable.upsertOne` |
+| `repo.session()` | `transactional.session` |
+
+A schema with a field type not in `supportedFieldTypes` resolves to `never` in the schema argument position — the call won't compile.
+
+### Filters (Query API)
+
+The `.where()` builder step accepts a factory `(q) => q.op(field, value)` that builds a `FilterGroup`. Every method on `FilterGroup` maps to one of the 13 canonical filter ops:
+
+| Op | Signature | Description |
+|---|---|---|
+| `eq` | `q.eq(field, value)` | Equal |
+| `ne` | `q.ne(field, value)` | Not equal |
+| `gt` | `q.gt(field, value)` | Greater than |
+| `gte` | `q.gte(field, value)` | Greater than or equal |
+| `lt` | `q.lt(field, value)` | Less than |
+| `lte` | `q.lte(field, value)` | Less than or equal |
+| `in` | `q.in(field, values)` | In array |
+| `notIn` | `q.notIn(field, values)` | Not in array |
+| `like` | `q.like(field, pattern)` | Substring match |
+| `exists` | `q.exists(field)` | Field is non-null |
+| `notExists` | `q.notExists(field)` | Field is null/undefined (its own op, not a boolean form of `exists`) |
+| `contains` | `q.contains(field, values)` | Array contains subset |
+| `notContains` | `q.notContains(field, values)` | Array does not contain subset |
+
+Structural combinators build compound filters:
+
+```typescript
+// AND — all conditions must match
+q.and([
+    (g) => g.gt('age', 18),
+    (g) => g.eq('active', true),
+])
+
+// OR — any condition matches
+q.or([
+    (g) => g.eq('role', 'admin'),
+    (g) => g.eq('role', 'superadmin'),
+])
+```
+
+Filters can reference fields by name (string) or by schema-tagged Field reference (`UserSchema.fields.email`). Empty `and([])` / `or([])` throws at builder time. Unknown fields throw `OrmValidationError` at the Repo-entry boundary.
+
+Filter ops are gated per-adapter: the `FilterGroup` passed to a Repo method only exposes ops declared in the adapter's `queryableOps`. Undeclared ops are `never` at the type level.
+
+### Update Operations
+
+The `.update()` and `.upsert()` builder methods accept typed update data. Atomic update op helpers are exported from `equipped/orm`:
+
+| Op | Helper | Target |
+|---|---|---|
+| `set` | `set<Schema>({ field: value })` | Any field (partial) |
+| `inc` | `inc<Schema>(field, value)` | Numeric fields |
+| `mul` | `mul<Schema>(field, value)` | Numeric fields |
+| `min` | `min<Schema>(field, value)` | Comparable fields |
+| `max` | `max<Schema>(field, value)` | Comparable fields |
+| `unset` | `unset<Schema>(field)` | Optional fields |
+| `push` | `push<Schema>(field, value)` | Array fields |
+| `pull` | `pull<Schema>(field, value)` | Array fields |
+| `patch` | `patch<Schema>(field, value)` | Object fields |
+
+```typescript
+import { IncOp } from 'equipped/orm'
+
+await repo.on(UserSchema).one().id('u1').update({
+    name: 'Alice',
+    age: new IncOp('age', 1),
+})
+```
+
+-   Conflicting ops on the same field (e.g. setting and incrementing `views`) throw `OrmValidationError` with `kind: 'conflicting-ops'`.
+-   Only `set` values are pipe-validated; atomic op operands are not.
+-   Op availability is gated by the adapter's `updateOps` declaration — undeclared ops resolve to `never`.
+
+### Context & Multi-tenancy
+
+`repo.resolve(transform, fn)` scopes a block of queries with an explicit config override. It uses `AsyncLocalStorage` internally — transforms are visible to all queries within `fn`, including preload sub-queries and queries inside sessions. Parallel calls do not bleed into each other.
+
+```typescript
+import { type ConfigTransform, Repo } from 'equipped/orm'
+
+type MyConfig = { table: string; tenantPrefix?: string }
+
+const repo = Repo.from(adapter)
+    .resolve((schema) => ({ table: schema.name }))
+    .build()
+
+// Per-request scope entry
+app.use((req, res, next) => {
+    const tenantId = req.headers['x-tenant-id']
+    repo.resolve(
+        (config) => ({ ...config, tenantPrefix: tenantId }),
+        next,
+    )
+})
+```
+
+**How it works**: `repo.resolve(transform, fn)` pushes a `ConfigTransform` onto the ALS context for the duration of `fn`. The transform is applied to the base config (from the builder's `.resolve()`) before the adapter receives it. Nested `repo.resolve()` calls compose — inner transforms see the outer-transformed config.
+
+**Patterns**:
+
+-   **Hono / Express middleware**: call `repo.resolve(transform, next)` in middleware to scope all downstream queries.
+-   **Explicit per-operation**: wrap a single operation for ad-hoc config overrides.
+
+**Footgun mitigations**: without a `repo.resolve()` scope, all queries run with the base config. To fail loud on missing tenant context, have your transform throw when the expected value is absent.
+
+### Builder-chain Pattern Overview
+
+All declarative artifact construction (`Schema.from()`, `Relations.from()`, `Adapter.from()`, `Repo.from()`) uses a uniform **static-factory builder-chain** pattern:
+
+```typescript
+const artifact = X.from(args)
+    .stepA(...)
+    .stepB(...)
+    .stepC(...)
+    .build()
 ```
 
+**Rules**:
+
+-   **Once-per-step**: each builder step can be called at most once. Duplicate calls are compile errors via a uniqueness guard (`K extends keyof Acc ? never : K`).
+-   **Per-step coherence**: each step validates its own constraints at the call site. For example, `.queryable()` requires `.queryableOps()` to have been called first with a non-empty list.
+-   **Omission-equals-empty**: a step not called means the artifact doesn't declare that capability. Op-list fields default to `readonly []`; behaviours default to absent.
+-   **Name-parity convention**: builder method names match the capability names they declare (`.queryableOps()` declares `queryableOps`, `.crud()` declares `crud`, etc.).
+
+This pattern applies only to **definitions** (static artifact construction). **Operations** (Repo method calls, `repo.session()`, op helpers like `set()`) use direct function calls.
+
 ## Caching (Redis)
 
 A simple and effective caching layer backed by Redis is available on the instance.