@afora/core 0.0.9 → 0.0.12

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset=".github/assets/afora-banner-dark.png">
-    <img alt="afora — Model the domain. Keep the invariants." src=".github/assets/afora-banner-light.png" width="100%">
+    <img alt="afora — Simple to write. Built to hold." src=".github/assets/afora-banner-light.png" width="100%">
   </picture>
 </p>
 
@@ -10,7 +10,7 @@
   <a href="https://github.com/afora-framework/core/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/afora-framework/core/actions/workflows/ci.yml/badge.svg?branch=main"></a>
   <a href="https://www.npmjs.com/package/@afora/core"><img alt="npm provenance" src="https://img.shields.io/badge/npm-provenance-2ea44f?logo=npm"></a>
   <a href="https://standardschema.dev"><img alt="Standard Schema V1" src="https://img.shields.io/badge/Standard%20Schema-V1-3178c6"></a>
-  <img alt="Bun >= 1.4.4 and Node >= 22" src="https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.4.4%20%7C%20Node%20%E2%89%A5%2022-555">
+  <img alt="Bun >= 1.4.4 and Node >= 22" src="https://img.shields.io/badge/runtime-Bun%20%3E%3D%201.4.4%20%7C%20Node%20%3E%3D%2022-555">
   <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/afora-framework/core"></a>
 </p>
 
@@ -23,47 +23,42 @@
   <a href="https://github.com/afora-framework/core/discussions">Discussions</a>
 </p>
 
-**A backend an agent can write without breaking its guarantees.** With afora the whole application is data: an `afora.json` declares the entities, repositories, use cases, commands and HTTP API, [`@afora/codegen`](packages/codegen/README.md) turns it into TypeScript you review and commit, [`@afora/mcp`](packages/mcp/README.md) lets an agent write it, and `extractSpec(app)` gives the spec back from code written by hand. Whoever writes the spec or the code, the runtime keeps the invariants: sensitive fields are masked, undeclared keys are rejected, unique keys are enforced and business errors become problem+json with the right status.
+<h3 align="center">Simple to write. Built to hold.</h3>
 
-### 30 seconds: from afora.json to a running API
+**afora is a domain-first framework for TypeScript backends.** You declare what your entities, use cases and API are, and the runtime keeps the guarantees that are easy to forget: secrets stay masked, unknown fields are rejected, unique keys hold and business errors get the right status. Whoever writes the code, you or your agent, it holds.
 
-```bash
-bun add @afora/core @afora/hono hono typebox && bun add -d @afora/codegen
-bunx afora-codegen generate afora.json --stages ./stages.ts   # writes src/domain/*.ts
-bun src/server.ts
-```
-
-With the [quick start's `afora.json`](#the-same-app-as-an-aforajson) and three small files written by hand (the hashing function, the `hono` stage catalog and the server, shown there), that is the whole API: a `User` with a masked password and a unique email, a use case written as steps, problem+json errors and an OpenAPI document. The same app written by hand in TypeScript is the [quick start](#quick-start), and the [afora.json guide](docs/afora-json.md) covers the whole spec.
+Model the domain; the runtime keeps the invariants. Built on [TypeBox](https://github.com/sinclairzx81/typebox), with [Standard Schema](https://standardschema.dev) on every field, on Bun and Node.
 
 ## Why afora
 
-An HTTP backend written by an agent (or in a hurry) tends to break the same few guarantees. In afora each one is a mechanism of the runtime, not a convention the code has to remember:
+An HTTP backend written by an agent (or in a hurry) tends to break the same few guarantees. In afora each one is part of the runtime, not a convention the code has to remember:
 
-| What usually breaks                            | What afora does                                                                                                                                                                                         |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| A password hash or token ends up in a response | A property declared `sensitive` (`Password`) is masked by `toJSON()` at any depth, so no serializer can leak it ([records](docs/records.md)).                                                           |
-| Extra fields in a request body are accepted    | Records reject undeclared keys at any depth (issue code `undeclared_key`), and the HTTP sink answers 400 ([Standard Schema](docs/standard-schema.md)).                                                  |
-| A business error is returned as a 500          | Exceptions know their layer; an output maps them to problem+json with a status (404, 409, 401, 422 for the errors a use case declares) and hides the detail of a real 500 ([outputs](docs/outputs.md)). |
-| A duplicate email is written twice             | `unique` keys are enforced by the repository and its provider, and a violation is a 409 ([repositories](docs/repositories.md)).                                                                         |
+| What usually breaks                            | What afora does                                                                                                         |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| A password hash or token ends up in a response | A `sensitive` property is masked by `toJSON()` at any depth, so no serializer can leak it ([records](docs/records.md)). |
+| Extra fields in a request body are accepted    | Undeclared keys are rejected at any depth, and the API answers 400 ([Standard Schema](docs/standard-schema.md)).        |
+| A business error is returned as a 500          | Errors know their layer and become problem+json with the right status ([outputs](docs/outputs.md)).                     |
+| A duplicate email is written twice             | `unique` keys are enforced by the repository, and a violation is a 409 ([repositories](docs/repositories.md)).          |
+| One user reads or changes another user's data  | A use case declares its `access` (scopes, owner), and every output enforces it before it runs ([access](docs/auth.md)). |
 
-[`examples/agent-built`](examples/agent-built/README.md) checks these four invariants on the running API of a ticketing backend built only through the MCP server, and of a Hono + Zod baseline written from the same brief. In the committed run both hold all four, but the afora one wrote no code for any of them: the spec declares the fields and errors, and the runtime does the rest. Scripted runs that measure how often each approach holds them across independent agent runs are in the example, waiting to be run with an API key.
+[`examples/agent-built`](examples/agent-built/README.md) checks these five on the running API of a ticketing backend an agent built through the MCP server, next to a Hono + Zod baseline written from the same brief. Both hold them; the afora one wrote no code for any of them.
 
-afora is not a general-purpose validator. It models a domain on [TypeBox](https://github.com/sinclairzx81/typebox), and every field plugs into the validators your framework already accepts through [Standard Schema](https://standardschema.dev).
+## For you and your agent
 
-## Features
+**Developer experience**
 
-- **Records with invariants.** Properties (`Email`, `Slug`, `Password`, your own) validate and normalize every value; blueprints compose them; a record (`class User extends recordOf(...)`) holds the handled value and rejects undeclared keys at any depth.
-- **Sensitive data masking.** A property declared `sensitive` (`Password`) is masked by `toJSON()` at any depth, so `JSON.stringify(user)` cannot leak it.
-- **Entities, repositories and use cases.** `entityOf` adds identity, timestamps and domain events; `repositoryOf` generates typed `findBy<Key>` methods for the keys in `options.unique` and enforces them; use cases inject repositories and environments and can override them per call.
-- **Typed change namespace and side effects.** `change: ["password"]` generates `change.password(value)` (also destructurable, as `const { change } = user`), which re-validates the value and runs `onSetAll` and `onSet`.
-- **Exceptions that know their layer.** Each error carries a layer (`Property`, `Record`, `UseCase`, `Output`...) and a `trace` that grows as it goes up.
-- **Standard Schema V1 on every field.** Properties, blueprints, lists and record classes work as is in Hono, tRPC and TanStack Form, and `safeParse` never throws for an invalid value.
-- **Commands and outputs.** `commandOf` groups use cases behind one execution boundary (context, transactions, event policies); `outputOf` turns commands into operations and pipes them to a sink: an HTTP API with `@afora/hono`, WebSocket messages with `@afora/ws`, an OpenAPI 3.1 document, or MCP tools, with problem+json errors and masked responses.
-- **Routes and access on the use case.** A use case says where it is served (`route`, or `@Route("GET", "/posts/{slug}")`) and who may call it (`access`, or `@Access({ scopes: [...] })`), next to its input; the blueprint stays the only description of the input, and every server and transport enforces the access before the use case runs. `resourceOf(Posts, { path: "/posts" })` is a whole CRUD. See the [tutorial](docs/tutorial.md).
-- **Any server.** The same output runs on [Hono](packages/hono/README.md), [Fastify](packages/fastify/README.md), [Express](packages/express/README.md) or [Elysia](packages/elysia/README.md), with that server's own middlewares: they share one compiled route table and one contract test suite ([HTTP providers](docs/providers.md)).
-- **Standard use cases.** `commandOf({ useCases: (ctx) => ({ create: ctx.create(Posts), publish: ctx.publish(Posts) }) })` picks ready-made use cases that follow the repository and its entity: the actions it declares, its record plugins and the properties of its keys ([docs](docs/std-use-cases.md)).
-- **The whole application in JSON.** An `afora.json` generates the code (`@afora/codegen`), use cases included, as data (steps), and `extractSpec(app)` gives back the `afora.json` of an application written by hand.
-- **Repositories on any store.** A provider contract with typed queries, soft deletion and transactions, a runner-agnostic kit to test one (`@afora/core/testing`), in memory by default, on Drizzle ORM with `@afora/drizzle` and on DynamoDB with `@afora/dynamodb`.
+- **Four declarations to a CRUD API:** an entity, a repository, a command and an output ([overview](docs/README.md)).
+- **Types that follow the model:** inputs and responses are inferred, `findByEmail` exists because `email` is unique, and `user.change.password()` because you allowed it.
+- **Fits what you already use:** every field is a Standard Schema, so Hono, tRPC and TanStack Form take it as is.
+- **Any server, any store:** [Hono](packages/hono/README.md), [Fastify](packages/fastify/README.md), [Express](packages/express/README.md) or [Elysia](packages/elysia/README.md); in memory, [Drizzle](packages/drizzle/README.md) or [DynamoDB](packages/dynamodb/README.md).
+- **Errors you can read:** each one names its layer and carries the trace of the layers it crossed ([exceptions](docs/exceptions.md)).
+
+**Agent experience**
+
+- **The application is data:** an `afora.json` declares the entities, the use cases (as steps), the commands and the HTTP API ([guide](docs/afora-json.md)).
+- **An MCP server to write it:** [`@afora/mcp`](packages/mcp/README.md) lets an agent read the catalog, edit and validate the spec, generate the code and see its TypeScript diagnostics.
+- **Code you review:** [`@afora/codegen`](packages/codegen/README.md) turns the spec into the TypeScript you would write by hand, committed; `extractSpec(app)` gives the spec back from code written by hand.
+- **The runtime holds what the agent forgets:** the five rows above, with no code written for them. `examples/blog` is a whole API generated from one `afora.json`.
 
 ## Install
 
@@ -71,24 +66,11 @@ afora is not a general-purpose validator. It models a domain on [TypeBox](https:
 bun add @afora/core typebox   # or: npm install @afora/core typebox
 ```
 
-Requirements: [Bun](https://bun.sh) >= 1.4.4 or Node.js >= 22. TypeBox (`typebox`, version `^1`) is a required peer dependency, shared with your application and afora's companion packages. The package ships ESM with TypeScript declarations; TypeScript >= 5.5 is an optional peer dependency.
-
-`Password` hashes with argon2id: with `Bun.password` on Bun, with native `node:crypto` argon2 on a Node that has it (24.7+), and otherwise it throws `PasswordHasherRequired` until you call `configure({ hasher })`. `Id.generate()` makes a portable, monotonic UUID v7 on any runtime. afora imports no `node:crypto` (or `Buffer`) at load, so it loads in browsers and Workers; the native hasher is looked up on first use through `process.getBuiltinModule` (Node 22.3+). The native hasher derives argon2 version 19 only; a hash of another version throws `UnsupportedPasswordHash` (verify it with `Bun.password`, or `configure({ hasher })`).
-
-```ts
-import { configure, type PasswordHasher } from "@afora/core";
-
-const hasher: PasswordHasher = {
-	hash: (plain) => myArgon2.hash(plain),
-	verify: (plain, hash) => myArgon2.verify(plain, hash),
-	verifySync: (plain, hash) => myArgon2.verifySync(plain, hash), // optional; `Password.verifySync` throws without it
-};
-configure({ hasher, idGenerator: () => myUuidV7() }); // both optional; `resetRuntime()` restores the defaults
-```
+Bun >= 1.4.4 or Node.js >= 22; it also loads in browsers and Workers. TypeBox (`typebox`, `^1`) is a peer dependency. How passwords are hashed and ids made on each runtime, and how to replace them with `configure`: [Runtime](docs/runtime.md).
 
 ## Quick start
 
-A `User` entity with a sensitive key and a unique key, a repository, a use case written as steps that says where it is served, a command that wraps it in a transaction, and an output that serves the command as an HTTP API with an OpenAPI document. Install what it uses:
+A `User` with a masked password and a unique email, a use case written as steps, a transaction, and an HTTP API with an OpenAPI document. Install what it uses:
 
 ```bash
 bun add @afora/core @afora/hono hono typebox
@@ -148,6 +130,7 @@ class Register extends useCaseOf({
 	response: blueprintOf(() => ({ user: User })),
 	dependencies: { users: Users },
 	errors: [UserAlreadyExists],
+	strictSteps: true, // TypeScript checks every reference, arg and the return
 	steps: [
 		{ find: "users.findByEmail", args: ["$input.email"], as: "existing" },
 		{ ensure: "absent", value: "$existing", error: UserAlreadyExists },
@@ -155,6 +138,7 @@ class Register extends useCaseOf({
 			run: "hashPassword",
 			fn: hashPassword,
 			args: ["$input.plainPassword"],
+			params: blueprintOf((ctx) => ({ plain: ctx.string })),
 			as: "hash",
 		},
 		{
@@ -212,7 +196,12 @@ GET /openapi.json -> the OpenAPI 3.1 document of the route
 
 ### The same app as an afora.json
 
-Everything above, except the hashing function, is data, so it can be written as an `afora.json` and generated. `@afora/codegen` writes the TypeScript you would have written by hand (the classes above, plus an `applicationOf`), committed and reviewable. This is `examples/interop/quickstart.afora.json`, which the same test validates and generates.
+Everything above except the hashing function is data, so it can be written as an `afora.json`. `@afora/codegen` turns it into the same TypeScript, committed and reviewable, and `@afora/mcp` lets an agent write it.
+
+<details>
+<summary>The <code>afora.json</code>, the three hand-written files and the commands</summary>
+
+This is `examples/interop/quickstart.afora.json`, which the same test validates and generates.
 
 ```json
 {
@@ -264,6 +253,7 @@ Everything above, except the hashing function, is data, so it can be written as
 						"run": "hashPassword",
 						"fn": { "import": "../hash-password.ts#hashPassword" },
 						"args": ["$input.plainPassword"],
+						"params": { "fields": { "plain": "string" } },
 						"as": "hash"
 					},
 					{
@@ -328,6 +318,7 @@ bunx afora-codegen generate afora.json --stages ./stages.ts   # writes src/domai
 
 and serve the application from `src/server.ts` (`bun src/server.ts`):
 
+<!-- docs:code skip: src/server.ts of examples/interop/from-json; ./domain is what afora-codegen generates from the afora.json above -->
 ```ts
 import { App } from "./domain/index.ts";
 
@@ -341,164 +332,46 @@ These three files are `examples/interop/from-json`, which `bun run test:interop`
 
 `generate` writes one file per kind (`entities.ts`, `repositories.ts`, `use-cases.ts`, `commands.ts`, `outputs.ts`...), an `application.ts` and an `index.ts`, each starting with a banner saying not to edit it. `afora-codegen extract` goes the other way and gives the `afora.json` of an `Application`. The guide is in [docs/afora-json.md](docs/afora-json.md).
 
-## What you get
+</details>
 
-Each concept has a page in [docs/](docs/README.md), in the order they build on one another:
+## Learn more
 
-- [Properties](docs/properties.md): one validated and normalized value, with flags for `sensitive` and `unique`.
-- [Blueprints](docs/blueprints.md): an object shape built from properties, lists, optionals and nested blueprints.
-- [Records](docs/records.md): a class that holds the handled value, masks sensitive keys and generates `change.<key>`; plugins; experimental slicing.
-- [Entities](docs/entities.md): a record with identity, timestamps, `destroy()` and domain events.
-- [Repositories](docs/repositories.md): typed async methods for an entity, queries, soft deletion, providers, transactions and relations.
-- [Schema evolution](docs/schema-evolution.md): `fill`, `renamedFrom`, `schemaVersion` with `upgrade` steps and `previousNames`, so old rows are still read; `app.migrate` to rewrite them, and a schema lock checked in CI and on `start`.
-- [Use cases](docs/use-cases.md): the Command pattern with method injection, written as code or as steps.
-- [Commands](docs/commands.md): use cases under operation names, with a context, a transaction and an event policy.
-- [Outputs](docs/outputs.md): commands through stages into a sink, such as an HTTP API or an OpenAPI document.
-- [Applications](docs/applications.md): a named, checked manifest of every declaration, and `describe()`.
-- [Exceptions](docs/exceptions.md): errors that know their layer and keep a trace.
-- [Environments](docs/environments.md): validated environment variables.
-- [Standard Schema](docs/standard-schema.md), [OpenAPI](docs/openapi.md) and the [afora.json guide](docs/afora-json.md).
-
-## Standard Schema
-
-Every field (a property, blueprint, list or record class) implements Standard Schema V1 (`vendor: "afora"`), so Hono, tRPC, TanStack Form and any other library that takes one takes it as is. `validate` is synchronous, never throws for an invalid value and reports every issue with its `path`. Without a framework, `safeParse` returns `{ value }` or `{ issues }`. See [docs/standard-schema.md](docs/standard-schema.md); the real-library tests are in `examples/interop`.
+- [Tutorial](docs/tutorial.md): an API built step by step, and [coming from Hono + Zod](docs/coming-from-hono-zod.md).
+- [Concepts](docs/README.md), in the order they build on one another: property → blueprint → record → entity → repository → use case → command → output → application.
+- [The afora.json guide](docs/afora-json.md) and the [MCP server](packages/mcp/README.md).
+- [API reference](docs/reference/api.md), [FAQ](docs/faq.md) and [troubleshooting](docs/troubleshooting.md).
 
 ## Packages
 
-| Package                                                    | What it does                                                                                                                                                  |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`@afora/core`](https://www.npmjs.com/package/@afora/core) | Properties, blueprints, records, entities, repositories, use cases, commands and outputs (this repository's root).                                            |
-| [`@afora/codegen`](packages/codegen/README.md)             | Generates afora code from an `afora.json`, and extracts the `afora.json` of an `Application` back.                                                            |
-| [`@afora/mcp`](packages/mcp/README.md)                     | An MCP server that lets an agent build a domain with `@afora/codegen`.                                                                                        |
-| [`@afora/hono`](packages/hono/README.md)                   | A `hono` sink for outputs: serves the operations as a Hono app, with problem+json errors, masked responses, signed webhooks and an optional OpenAPI document. |
-| [`@afora/fastify`](packages/fastify/README.md)             | A `fastify` sink: the same operations, options and behavior on Fastify.                                                                                       |
-| [`@afora/express`](packages/express/README.md)             | An `express` sink: the same on Express 5.                                                                                                                     |
-| [`@afora/elysia`](packages/elysia/README.md)               | An `elysia` sink: the same on Elysia.                                                                                                                         |
-| [`@afora/ws`](packages/ws/README.md)                       | A `websocket` sink: operations over JSON messages on any runtime, with topic subscriptions that `publishEvents` feeds with domain events.                     |
-| [`@afora/drizzle`](packages/drizzle/README.md)             | A repository provider on Drizzle ORM (SQLite and Postgres) that passes the provider contract kit.                                                             |
-| [`@afora/dynamodb`](packages/dynamodb/README.md)           | A repository provider on one DynamoDB table (single-table layout, unique keys as marker items) that passes the provider contract kit on DynamoDB Local.       |
-
-## Example
-
-`examples/blog` is a blog (users with the `authenticatable` plugin, posts with soft deletion, every use case a [standard one](docs/std-use-cases.md), a Hono API on Drizzle and SQLite) whose whole `src/domain` is generated from one `afora.json` by `@afora/codegen`. Only the database, the schema, the provider (made from a `Database` environment with `providerFrom` when the server calls `App.start()`, and named `database` in the `providers` of the spec) and the server are hand-written. Its tests check that the committed code is what the spec generates, drive the API end to end and extract the spec back from the application: `bun run test:blog`.
-
-`examples/agent-built` is an event ticketing API (organizers, events with a capacity, tickets) built only through the `@afora/mcp` tools from a written brief, with the tool calls committed and replayed byte for byte, and an evaluation of four invariants on its running API and on a Hono + Zod baseline: `bun run test:agent-built`. See [its write-up](examples/agent-built/README.md).
+| Package                                                    | What it does                                                      |
+| ---------------------------------------------------------- | ----------------------------------------------------------------- |
+| [`@afora/core`](https://www.npmjs.com/package/@afora/core) | The framework: from properties to outputs (this repository).      |
+| [`@afora/codegen`](packages/codegen/README.md)             | `afora.json` to TypeScript, and an application back to its spec.  |
+| [`@afora/mcp`](packages/mcp/README.md)                     | An MCP server that lets an agent build the domain.                |
+| [`@afora/hono`](packages/hono/README.md)                   | Serves the operations on Hono, with an optional OpenAPI document. |
+| [`@afora/fastify`](packages/fastify/README.md)             | The same on Fastify.                                              |
+| [`@afora/express`](packages/express/README.md)             | The same on Express 5.                                            |
+| [`@afora/elysia`](packages/elysia/README.md)               | The same on Elysia.                                               |
+| [`@afora/ws`](packages/ws/README.md)                       | Operations and domain events over WebSocket.                      |
+| [`@afora/drizzle`](packages/drizzle/README.md)             | Repositories on Drizzle ORM (SQLite and Postgres).                |
+| [`@afora/dynamodb`](packages/dynamodb/README.md)           | Repositories on one DynamoDB table.                               |
+| [`@afora/otel`](packages/otel/README.md)                   | OpenTelemetry spans per command, use case and repository call.    |
 
 ## Performance
 
-`bun run bench` times afora next to TypeBox (compiled), Ajv, Typia, Zod 4, Valibot, ArkType, Effect Schema, Yup and Joi on seven scenarios (a flat object, a nested one, the body of an API request, a list of 1,000 items, a union, six levels of nesting, and a flat object with nothing to transform), with valid and invalid input, on Bun and on Node. Every library declares the same rules, rejects undeclared keys and collects every error, and is checked before it is timed; each row is timed by a process of its own, after a warm-up, in three rounds. The tables are in [`bench/RESULTS.md`](bench/RESULTS.md) and the method in [`bench/README.md`](bench/README.md). Absolute numbers depend on the machine, so read the ratios.
+afora validates and transforms faster than Zod 4 on most of the fourteen measured cases; checkers that compile and do not transform (TypeBox, Ajv, Typia) are faster still. The method, every case and the trade-offs are in [Performance](docs/performance.md).
 
 <!-- bench:start -->
 
 ![Validations per second on the body of an API request, Node v24.22.2](bench/results/chart.svg)
 
-Time of each library as a multiple of afora `blueprint.safeParse` on the same case: above 1.00x it is slower than afora, below it is faster. TypeBox, Ajv and Typia only check, they do not transform. afora 0.0.8, Bun 1.4.4 and Node v24.22.2, AMD EPYC 9V45 96-Core Processor; generated from `bench/results/latest.json`.
-
-| Node 24                                                  |    afora | TypeBox |   Ajv | Typia |   Zod | Valibot | ArkType | Effect Schema |    Yup |    Joi |
-| -------------------------------------------------------- | -------: | ------: | ----: | ----: | ----: | ------: | ------: | ------------: | -----: | -----: |
-| Small flat object, valid                                 | 299.5 ns |   0.13x | 0.14x | 0.15x | 1.23x |   1.97x |  10.30x |         2.74x | 12.44x |  8.25x |
-| Small flat object, invalid                               | 474.6 ns |   9.50x | 0.13x | 0.58x | 3.22x |   2.71x |  27.57x |         4.04x | 68.43x |  7.66x |
-| Nested user (address, 5 tags max, 10 addresses), valid   |  2036 ns |   0.12x | 0.17x | 0.13x | 1.27x |   1.02x |  14.85x |         3.24x | 22.52x |  6.67x |
-| Nested user (address, 5 tags max, 10 addresses), invalid |  2688 ns |   9.83x | 0.15x | 0.83x | 1.84x |   1.21x |  21.43x |         3.46x | 38.49x |  6.84x |
-| API request body (an order with 5 items), valid          |  2518 ns |   0.35x | 0.35x | 0.24x | 1.21x |   1.16x |   9.55x |         2.46x | 17.06x |  5.63x |
-| API request body (an order with 5 items), invalid        |  3540 ns |   5.17x | 0.12x | 0.86x | 1.90x |   1.10x |  14.67x |         2.50x | 30.63x |  5.11x |
-| List of 1,000 items, valid                               | 152.4 µs |   0.06x | 0.10x | 0.06x | 0.67x |   2.34x |  20.61x |         3.96x | 27.77x |  7.40x |
-| List of 1,000 items, invalid                             | 155.5 µs |  20.58x | 0.10x | 0.18x | 0.72x |   2.35x |  26.62x |         3.70x | 28.82x |  7.43x |
-| Union of 4 variants (12 events), valid                   | 579.7 ns |   0.47x | 0.59x | 0.51x | 3.90x |  14.54x |   1.54x |        13.42x | 91.04x | 94.11x |
-| Union of 4 variants (12 events), invalid                 |  55.0 µs |   0.64x | 0.01x | 0.03x | 0.09x |   0.19x |   0.34x |         0.17x |  1.44x |  1.69x |
-| 6 levels of nesting, valid                               | 829.3 ns |   0.06x | 0.09x | 0.06x | 0.78x |   1.13x |  14.16x |         4.12x | 19.31x |  5.65x |
-| 6 levels of nesting, invalid                             | 971.4 ns |  21.55x | 0.10x | 1.69x | 1.99x |   1.72x |  27.50x |         5.35x | 52.46x |  7.37x |
-| Small flat object, checks only, valid                    | 177.6 ns |   0.23x | 0.24x | 0.25x | 0.82x |   2.68x |   0.44x |         2.34x | 18.10x | 12.73x |
-| Small flat object, checks only, invalid                  | 424.3 ns |  10.48x | 0.15x | 0.68x | 2.94x |   2.85x |  22.80x |         3.92x | 74.92x |  8.39x |
-
-| Bun                                                      |    afora | TypeBox |   Ajv | Typia |   Zod | Valibot | ArkType | Effect Schema |    Yup |    Joi |
-| -------------------------------------------------------- | -------: | ------: | ----: | ----: | ----: | ------: | ------: | ------------: | -----: | -----: |
-| Small flat object, valid                                 | 195.7 ns |   0.15x | 0.18x | 0.17x | 1.63x |   0.95x |  10.95x |         2.58x | 22.27x | 10.44x |
-| Small flat object, invalid                               | 426.1 ns |   7.87x | 0.21x | 1.26x | 1.62x |   0.97x |  16.14x |         2.50x | 39.07x |  8.12x |
-| Nested user (address, 5 tags max, 10 addresses), valid   |  3154 ns |   0.05x | 0.08x | 0.03x | 0.93x |   0.41x |   4.73x |         1.35x | 16.66x |  3.81x |
-| Nested user (address, 5 tags max, 10 addresses), invalid |  2260 ns |   8.15x | 0.16x | 0.99x | 1.64x |   0.91x |  13.57x |         2.40x | 39.16x |  6.88x |
-| API request body (an order with 5 items), valid          |  2355 ns |   0.19x | 0.21x | 0.32x | 1.34x |   0.68x |   5.08x |         1.83x | 21.04x |  4.97x |
-| API request body (an order with 5 items), invalid        |  2456 ns |   5.33x | 0.13x | 1.13x | 2.06x |   0.97x |  11.38x |         2.24x | 38.34x |  7.81x |
-| List of 1,000 items, valid                               | 185.7 µs |   0.02x | 0.05x | 0.01x | 1.05x |   0.45x |   7.61x |         1.53x | 29.36x |  5.07x |
-| List of 1,000 items, invalid                             |  92.7 µs |  23.63x | 0.12x | 0.45x | 2.25x |   0.96x |  23.45x |         3.00x | 65.59x | 11.20x |
-| Union of 4 variants (12 events), valid                   |  1627 ns |   0.11x | 0.14x | 0.20x | 1.83x |   1.97x |   0.26x |         2.06x | 39.17x | 27.28x |
-| Union of 4 variants (12 events), invalid                 |  41.8 µs |   0.64x | 0.01x | 0.04x | 0.10x |   0.11x |   0.21x |         0.11x |  1.81x |  2.01x |
-| 6 levels of nesting, valid                               | 528.2 ns |   0.02x | 0.10x | 0.06x | 1.98x |   1.54x |  11.94x |         2.87x | 39.56x |  7.63x |
-| 6 levels of nesting, invalid                             | 838.9 ns |  17.86x | 0.09x | 1.60x | 1.74x |   1.59x |  18.13x |         3.09x | 53.04x |  7.92x |
-| Small flat object, checks only, valid                    | 110.1 ns |   0.28x | 0.35x | 0.29x | 1.83x |   0.92x |   0.34x |         1.91x | 33.82x | 15.15x |
-| Small flat object, checks only, invalid                  | 414.7 ns |   7.74x | 0.21x | 1.25x | 1.52x |   0.86x |  11.63x |         2.06x | 39.99x |  7.60x |
+afora 0.0.11 on Bun 1.4.4, Node v22.23.4 and Node v24.22.2, AMD EPYC 9V74 80-Core Processor; generated from `bench/results/latest.json`. Every case, runtime and library, and how it is measured: [Performance](docs/performance.md).
 
 <!-- bench:end -->
 
-What the table says, for `blueprint.safeParse`, on a GitHub runner (AMD EPYC, Linux, Bun 1.4.4 and Node 24). The table is of afora at commit `8c4395e`; what changed after it is said where it applies.
-
-- **Against Zod 4.** On Bun, faster in 12 of the 14 cases, by 1.05x to 2.25x; Zod 4 is ahead on the valid nested object (7%). On Node, faster in 9 of the 14, by 1.2x to 3.9x; Zod 4 is ahead on the list of 1,000 items (1.4x to 1.5x), on the valid deep object (1.3x) and on the valid flat object with nothing to transform (1.2x). The invalid union is told apart below.
-- **Against Valibot.** On Node afora is faster in 13 of the 14 cases, by 1.02x to 2.9x outside the valid union (14.5x). On Bun it is the other way: Valibot is ahead in 11 of them, within 15% on small objects and by 1.5x to 2.4x on the valid nested object, the valid API body and the valid list, and afora is ahead on the valid union (2x) and the deep object (1.5x to 1.6x).
-- **Against Effect Schema, Joi and Yup.** Faster in every case but the invalid union: 1.35x to 5.4x Effect Schema, 3.8x to 15x Joi and 12x to 75x Yup, and more than that on the valid union (up to 13x, 94x and 91x).
-- **Against ArkType.** Faster wherever a value is transformed or rejected, by 4.7x to 28x, because its morphs and its errors take a slower path. With nothing to transform and a valid value, ArkType is 2.3x to 3x faster than afora, and 3.8x on the valid union on Bun.
-- **An invalid union.** In the table it takes about 10x the time of Zod 4: TypeBox `Errors` reported every variant of the union for each rejected value. Since then a property whose schema is a discriminated union tells a rejected value by the variant it names, without `Errors`, and takes about 0.5x the time of Zod 4 on Bun (measured on an Apple M2; the table follows at the next measurement). Valid values of the same union are 1.8x to 3.9x faster than Zod 4.
-- **Floor.** The checkers that compile and do not transform (TypeBox, Ajv, Typia) are 3x to 9x faster than afora on a valid small object, and 10x to 70x on the larger ones. afora builds on TypeBox. On invalid input afora is 5x to 24x faster than TypeBox `Errors` (outside the union), and Ajv stays 5x to 11x ahead.
-- **Records and entities.** `Record.safeParse`, which also creates the instance, takes 1.0x to 2.1x the time of `blueprint.safeParse` on Bun and up to 4x on Node. `Entity.safeParse` also makes an id and the time stamps, which on a small object is most of its time: 5x to 13x `blueprint.safeParse` on the flat object in the table, 1.0x to 4.7x on the larger ones; since then it takes about three quarters of that on a small object, for not checking again the id and the date it has just made. `new Record(value)` throws on invalid input, which costs an exception with its trace (2x to 6x `blueprint.safeParse` on Bun, 2.5x to 13x on Node); use `safeParse` where invalid input is expected.
-- **Bundle and cold start.** afora is a framework with one entry point: validating one object bundles to 100 kB gzipped (Zod 4: 24 kB, Valibot: 1.7 kB) and takes 40 ms to load, build and run once in a new Node process (85 ms on Bun; Zod 4: 7 to 8 ms).
-
-What afora does that the fast rows do not all do: a pipeline per property (`preHandle`, schema check, `afterHandle`), where a property with a handler has the shape of the value checked first, so handlers only see the right types; objects walked key by key instead of one compiled function; frozen results; every issue with `code`, `path` and `source`; and, for `Record.safeParse` and `new Record`, creating the instance. If you validate bulk data in a hot path and need none of that, a compiled checker alone is an order of magnitude faster.
-
-CI keeps it there: `bun run bench:guard` times `blueprint.safeParse` and Zod 4 `safeParse` on the fourteen cases and fails when afora is over the limit of a case as a multiple of Zod 4 (1.15x unless `bench/guard.limits.ts` states another, with the reason).
-
-## Comparison
-
-A rough guide, not a verdict. "Partial" means it is possible but not what the library is for.
-
-|                             | afora                                          | Zod 4               | Valibot        | Effect Schema                      |
-| --------------------------- | ---------------------------------------------- | ------------------- | -------------- | ---------------------------------- |
-| Standard Schema V1          | yes, on every field                            | yes                 | yes            | yes                                |
-| Transforms                  | yes (`preHandle`, `afterHandle`)               | yes                 | yes            | yes                                |
-| Domain entities / classes   | yes (records with change methods and effects)  | no                  | no             | partial (`Schema.Class`)           |
-| Sensitive masking           | yes (`sensitive`, in `toJSON`)                 | no                  | no             | partial (`Redacted`)               |
-| Layered errors with a trace | yes (`ExceptionLayers`, `trace`)               | no                  | no             | partial (tagged errors, no layers) |
-| Runtime speed               | slower; see Performance                        | faster              | faster         | not measured here                  |
-| Bundle size                 | not measured; depends on TypeBox and `slugify` | larger than Valibot | small, modular | larger                             |
-| Ecosystem and maturity      | new, small                                     | very large          | large          | large, in the Effect ecosystem     |
-
-Where the others win: Zod and Valibot are faster, have far larger ecosystems and documentation, and have integrations and code generators for most tools; Valibot is modular and small; Effect Schema fits a codebase already built on Effect. afora gives up those to model entities, masking and layers in the type you already validate with.
-
 ## Contributing
 
-Read [CONTRIBUTING.md](CONTRIBUTING.md) for the setup, the checks and how releases work. Issues open from a template: bug report, feature request, or feedback from building on afora. Questions go to [Discussions](https://github.com/afora-framework/core/discussions); security issues go through [SECURITY.md](SECURITY.md), never a public issue.
-
-Commits follow [Conventional Commits](https://www.conventionalcommits.org) (`feat(repository): …`, `fix: …`), checked by commitlint in a Husky `commit-msg` hook; the `pre-commit` hook runs Biome and Knip. CI runs lint, Knip, type checks, unit and interop tests, the build and the Node smoke test on every push and pull request. A pull request that bumps the version in `package.json`, once merged to `main`, publishes to npm with provenance and creates the tag and the GitHub release.
-
-Scripts:
-
-```bash
-bun install
-bun test              # unit tests
-bun check             # type check
-bun run test:types    # build, then type-check the packed package on TypeScript, bundler and nodenext resolution
-bun run test:type-perf # build, then budget the editor cost per edit and snapshot hovers, completions and errors
-bun run test:api      # build, then snapshot the public surface (exports and declarations) and the afora.json schema
-bun run test:interop  # Hono, tRPC and TanStack Form tests (examples/interop), including the quick start
-bun run test:blog     # the generated blog (examples/blog): drift, API and extraction
-bun run test:agent-built # the agent-built example (examples/agent-built): drift, replay, API and the invariant evaluation
-bun run smoke         # build, then run the package on plain Node
-bun run bench         # benchmark against TypeBox, Ajv, Typia, Zod, Valibot, ArkType, Effect Schema, Yup and Joi
-bun run lint          # biome lint
-bun run knip          # unused files, exports and dependencies
-bun run fmt           # biome format + fix
-bun run build         # build dist/ (ESM + .d.ts)
-bun run test:codegen  # tests of packages/codegen
-bun run test:mcp      # tests of packages/mcp
-bun run test:hono     # tests of packages/hono
-bun run test:fastify  # tests of packages/fastify (also test:express, test:elysia)
-bun run test:ws       # tests of packages/ws
-bun run test:drizzle  # tests of packages/drizzle (SQLite and PGlite)
-bun run test:dynamodb # tests of packages/dynamodb (DynamoDB Local, with DYNAMODB_ENDPOINT)
-bun run build:packages # build the core, then packages/codegen, packages/mcp, packages/hono, packages/fastify, packages/express, packages/elysia, packages/ws, packages/drizzle and packages/dynamodb
-```
-
-## Versioning
-
-What is stable, what may break and how deprecations work is in [VERSIONING.md](VERSIONING.md).
+Read [CONTRIBUTING.md](CONTRIBUTING.md) for the setup, the checks and how releases work. Questions go to [Discussions](https://github.com/afora-framework/core/discussions); security issues go through [SECURITY.md](SECURITY.md), never a public issue. What is stable and how deprecations work is in [VERSIONING.md](VERSIONING.md).
 
 ## License
 

package/dist/adapters.js

@@ -1,56 +1,32 @@
-import {
-  coerceTextValues2,
-  HTTP_OPTION_KEYS2,
-  httpOptionsIssue2,
-  compileRoutes2
-} from "./index-y280ew0k.js";
-import {
-  schemaLockOf2,
-  diffSchemas2,
-  schemaLockProblemsOf2,
-  statusOf2,
-  PROBLEM_MEDIA_TYPE2,
-  problemOf2,
-  outputValueOf2,
-  ROUTE_OPTION_KEYS2,
-  routeOptionsIssue2,
-  requestIdHeaderOf2,
-  operationRoutes2
-} from "./index-hg1z2s2v.js";
-import {
-  Demo2,
-  Kind2,
-  RESERVED_RECORD_KEYS2,
-  ENTITY_IDENTITY_KEYS2,
-  RESERVED_ENTITY_KEYS2,
-  SCHEMA_VERSION_KEY2,
-  sinkOf2,
-  stageKindOf2,
-  stageCatalogOf2
-} from "./index-xegv6a1p.js";
 export {
-  Demo2 as Demo,
-  ENTITY_IDENTITY_KEYS2 as ENTITY_IDENTITY_KEYS,
-  HTTP_OPTION_KEYS2 as HTTP_OPTION_KEYS,
-  Kind2 as Kind,
-  PROBLEM_MEDIA_TYPE2 as PROBLEM_MEDIA_TYPE,
-  RESERVED_ENTITY_KEYS2 as RESERVED_ENTITY_KEYS,
-  RESERVED_RECORD_KEYS2 as RESERVED_RECORD_KEYS,
-  ROUTE_OPTION_KEYS2 as ROUTE_OPTION_KEYS,
-  SCHEMA_VERSION_KEY2 as SCHEMA_VERSION_KEY,
-  coerceTextValues2 as coerceTextValues,
-  compileRoutes2 as compileRoutes,
-  diffSchemas2 as diffSchemas,
-  httpOptionsIssue2 as httpOptionsIssue,
-  operationRoutes2 as operationRoutes,
-  outputValueOf2 as outputValueOf,
-  problemOf2 as problemOf,
-  requestIdHeaderOf2 as requestIdHeaderOf,
-  routeOptionsIssue2 as routeOptionsIssue,
-  schemaLockOf2 as schemaLockOf,
-  schemaLockProblemsOf2 as schemaLockProblemsOf,
-  sinkOf2 as sinkOf,
-  stageCatalogOf2 as stageCatalogOf,
-  stageKindOf2 as stageKindOf,
-  statusOf2 as statusOf
-};
+  diffSchemas,
+  schemaLockOf,
+  schemaLockProblemsOf
+} from "./core/application/schema.js";
+export {
+  ENTITY_IDENTITY_KEYS,
+  RESERVED_ENTITY_KEYS
+} from "./core/entity/abstract-entity.js";
+export { coerceTextValues } from "./core/output/coerce.js";
+export {
+  compileRoutes,
+  HTTP_OPTION_KEYS,
+  httpOptionsIssue
+} from "./core/output/http.js";
+export {
+  operationRoutes,
+  ROUTE_OPTION_KEYS,
+  requestIdHeaderOf,
+  routeOptionsIssue
+} from "./core/output/openapi-sink.js";
+export {
+  outputValueOf,
+  PROBLEM_MEDIA_TYPE,
+  problemOf
+} from "./core/output/problem.js";
+export { sinkOf, stageCatalogOf, stageKindOf } from "./core/output/stage.js";
+export { statusOf } from "./core/output/status.js";
+export { RESERVED_RECORD_KEYS } from "./core/record/abstract-record.js";
+export { SCHEMA_VERSION_KEY } from "./core/repository/state.js";
+export { Demo } from "./core/symbols/demo.js";
+export { Kind } from "./core/symbols/kind.js";

package/dist/core/application/application.d.ts

@@ -15,6 +15,36 @@ export declare function isApplication(value: unknown): value is AnyApplication;
  * under one name (or one object under two names) throw `ApplicationConflict`.
  * `describe()` gives the graph. With a `provider` (or that of the last
  * application extended that has one), `repositories` are bound to it.
+ *
+ * @throws {@link DuplicateApplicationDeclaration} when one object is registered under two names.
+ * @throws {@link ApplicationConflict} when extended applications register different objects under one name.
+ * @throws {@link InvalidApplicationDeclaration} when a declaration is not of the kind its collection holds.
+ * @throws {@link UnregisteredApplicationReference} when a registered declaration holds one that is not registered.
+ *
+ * @example
+ * ```ts
+ * import {
+ * 	applicationOf,
+ * 	blueprintOf,
+ * 	entityOf,
+ * 	inMemoryProvider,
+ * 	repositoryOf,
+ * } from "@afora/core";
+ *
+ * class User extends entityOf(blueprintOf((ctx) => ({ name: ctx.string }))) {}
+ * const Users = repositoryOf({ entity: User, actions: ["create"] });
+ *
+ * const Blog = applicationOf({
+ * 	name: "blog",
+ * 	entities: { User },
+ * 	repositories: { Users },
+ * 	provider: inMemoryProvider(), // the default of its repositories
+ * });
+ *
+ * await Blog.start();
+ * await Blog.repositories.Users.create({ name: "Ana" });
+ * await Blog.stop();
+ * ```
  */
 export declare function applicationOf<const Name extends string, const Extended extends readonly AnyApplication[] = readonly [], const Properties extends ApplicationCollections["properties"] = Record<never, never>, const Blueprints extends ApplicationCollections["blueprints"] = Record<never, never>, const Records extends ApplicationCollections["records"] = Record<never, never>, const Entities extends ApplicationCollections["entities"] = Record<never, never>, const Environments extends ApplicationCollections["environments"] = Record<never, never>, const Repositories extends ApplicationCollections["repositories"] = Record<never, never>, const UseCases extends ApplicationCollections["useCases"] = Record<never, never>, const Commands extends ApplicationCollections["commands"] = Record<never, never>, const Outputs extends ApplicationCollections["outputs"] = Record<never, never>, const Exceptions extends ApplicationCollections["exceptions"] = Record<never, never>>(settings: ApplicationSettings<Name, Extended, {
     properties: Properties;