@afora/core 0.0.2 → 0.0.4

package/README.md

@@ -10,14 +10,17 @@ afora is not a general-purpose validator. It is for code that models a domain, a
 - **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`, an OpenAPI 3.1 document, or MCP tools, with problem+json errors and masked responses.
+- **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 and on Drizzle ORM with `@afora/drizzle`.
 
 ## Install
 
 ```bash
-bun add @afora/core   # or: npm install @afora/core
+bun add @afora/core typebox   # or: npm install @afora/core typebox
 ```
 
-Requirements: [Bun](https://bun.sh) >= 1.4.4 or Node.js >= 22. The package ships ESM with TypeScript declarations; TypeScript >= 5.5 is an optional peer dependency.
+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 })`).
 
@@ -34,795 +37,274 @@ configure({ hasher, idGenerator: () => myUuidV7() }); // both optional; `resetRu
 
 ## Quick start
 
-A `User` record created from an HTTP body through Standard Schema, saved by a repository that reads `User.options.unique`, returned with its password masked; and an error that keeps the layers it crossed. This is the code of `examples/interop/quickstart.ts`, run by `bun run test:interop` (there the import is the local source instead of `"@afora/core"`).
+A `User` entity with a sensitive key and a unique key, a repository, a use case written as steps, 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:
+
+```bash
+bun add @afora/core @afora/hono hono typebox
+```
+
+Save this as `quickstart.ts` and run `bun quickstart.ts`. It is the code of `examples/interop/quickstart.ts`, run by `bun run test:interop` (there the imports resolve to the local sources).
 
 ```ts
-import { sValidator } from "@hono/standard-validator";
-import { Hono } from "hono";
 import {
 	blueprintOf,
+	commandOf,
 	ExceptionLayers,
+	entityOf,
 	exceptionOf,
-	guard,
-	listOf,
+	outputOf,
 	Password,
-	recordOf,
-	type StandardSchemaV1,
+	repositoryOf,
+	useCaseOf,
 } from "@afora/core";
+import { hono } from "@afora/hono";
 
-// Domain: a record with invariants, a sensitive key and unique intent
-const Address = blueprintOf((ctx) => ({ street: ctx.string, zip: ctx.string }));
-
-const UserBlueprint = blueprintOf((ctx) => ({
-	email: ctx.email, // trimmed and lowercased
-	slug: ctx.slug, // slugified; unique by declaration
-	password: ctx.password, // only an argon2 hash is accepted; always masked
-	address: Address,
-	tags: listOf(ctx.string, { maxItems: 5 }),
-}));
-
-export class User extends recordOf(UserBlueprint, {
-	unique: ["email"], // `slug` is unique already, as a Slug
-	change: ["password"], // generates change.password(value)
-}) {}
+// Entity: invariants, a sensitive key and a unique key
+export class User extends entityOf(
+	blueprintOf((ctx) => ({
+		name: ctx.text,
+		email: ctx.email, // trimmed and lowercased
+		password: ctx.password, // only an argon2 hash is accepted; always masked
+	})),
+	{ unique: ["email"] },
+) {}
 
-// Input: the HTTP body carries a plain password, which never enters the record
-const SignUpBody = blueprintOf((ctx) => ({
-	email: ctx.email,
-	slug: ctx.slug,
-	plainPassword: ctx.string,
-	address: Address,
-	tags: listOf(ctx.string, { maxItems: 5 }),
-}));
+// Repository: only the actions you choose; the provider is in memory by default
+const Users = repositoryOf({
+	entity: User,
+	actions: ["findByEmail", "create"],
+});
 
-// Repository: enforces what User.options.unique declares
 const UserAlreadyExists = exceptionOf({
-	layer: ExceptionLayers.Repository,
+	layer: ExceptionLayers.UseCase,
 	name: "UserAlreadyExists",
-	message: "A user with this email or slug already exists.",
+	message: "A user with this email already exists.",
 });
 
-class UserRepository {
-	readonly #users: User[] = [];
-
-	save(user: User): User {
-		for (const key of User.options.unique) {
-			if (this.#users.some((saved) => saved[key] === user[key])) {
-				throw new UserAlreadyExists({ source: "UserRepository" });
-			}
-		}
-		this.#users.push(user);
-		return user;
-	}
-}
-
-// Use case and HTTP route
-const users = new UserRepository();
-
-async function signUp({ plainPassword, ...data }: SignUpData) {
-	const password = await Password.hash(plainPassword);
-	return users.save(new User({ ...data, password: password.value }));
-}
-
-export const app = new Hono().post(
-	"/users",
-	sValidator("json", SignUpBody), // any Standard Schema consumer works the same
-	async (c) => {
-		const user = await signUp(c.req.valid("json"));
-		return c.json(user.toJSON(), 201); // the password comes out masked
-	},
-);
-
-// Errors keep the layers they crossed
-export function changePassword(user: User, value: string) {
-	return guard(
-		{ layer: ExceptionLayers.Output, source: "PATCH /password" },
-		() =>
-			guard({ layer: ExceptionLayers.UseCase, source: "ChangePassword" }, () =>
-				user.change.password(value),
-			),
-	);
+async function hashPassword(plain: string) {
+	return (await Password.hash(plain)).value;
 }
 
-type SignUpData = StandardSchemaV1.InferOutput<typeof SignUpBody>;
-```
-
-What it does:
-
-```ts
-// POST /users with { email: "  Jane@Example.COM ", slug: "Olá Mundo", plainPassword: "Str0ng!Pass", ... }
-// 201 { "email": "jane@example.com", "slug": "ola-mundo", "password": "********", ... }
-// the same slug again: UserAlreadyExists (layer "repository"), thrown by the repository
-
-// a body with email "nope" and tags "x": 400 from the validator, with the issues
-// [{ path: ["email"], code: "invalid_value", ... }, { path: ["tags"], code: "invalid_type", ... }]
-
-changePassword(user, "plain text"); // not an argon2 hash, so it throws; exception.trace is:
-// property:password -> record:User -> use-case:ChangePassword -> output:PATCH /password
-```
-
-## Standard Schema
-
-Every field implements Standard Schema V1 (`vendor: "afora"`), so any library that takes one (Hono, tRPC, TanStack Form...) takes it as is. `validate` is synchronous, never throws for an invalid value, and reports every issue with its `path` (e.g. `["addresses", 0, "zip"]`).
-
-| Field                                                              | `~standard.validate` gives                                                         |
-| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
-| property class (`Slug`, `propertyOf`, `optionalOf(Property)`)      | the handled value: `Slug` turns `"Olá Mundo"` into `"ola-mundo"`                   |
-| blueprint (and `optionalOf(blueprint)`, which accepts `undefined`) | the handled object, nested records as instances                                    |
-| list (`listOf`)                                                    | a frozen array of the handled items                                                |
-| record class (`recordOf`, subclasses included)                     | an instance of the class; a plain object for a nested record field becomes one too |
-
-```ts
-import { sValidator } from "@hono/standard-validator";
-import { FieldApi, FormApi } from "@tanstack/form-core"; // see examples/interop for the full setup
-import { initTRPC } from "@trpc/server";
-import { Hono } from "hono";
-import { blueprintOf, Email, listOf, recordOf } from "@afora/core";
-
-const Address = blueprintOf((ctx) => ({ street: ctx.string, zip: ctx.string }));
-const UserBlueprint = blueprintOf((ctx) => ({
-	name: ctx.string,
-	email: ctx.email,
-	slug: ctx.slug,
-	addresses: listOf(Address),
-}));
-class User extends recordOf(UserBlueprint) {}
-
-// Hono: `c.req.valid("json")` is the handled object; an invalid body is a 400 with the issues
-new Hono().post("/users", sValidator("json", UserBlueprint), (c) =>
-	c.json(c.req.valid("json")),
-);
-
-// tRPC: the resolver gets a `User`; an invalid input is `BAD_REQUEST`, its cause holding the issues
-const t = initTRPC.create();
-t.procedure.input(User).mutation(({ input }) => input.name);
-
-// TanStack Form: a property validates a field, a blueprint validates the form
-new FieldApi({ form, name: "email", validators: { onChange: Email } });
-new FormApi({ defaultValues, validators: { onChange: UserBlueprint } });
-```
-
-Without a framework, `safeParse` (on properties, blueprints and record classes) takes `unknown` and returns `{ value }` or `{ issues }`, never both and never throwing for an invalid value:
-
-```ts
-const result = UserBlueprint.safeParse(body);
-if (result.issues) {
-	for (const issue of result.issues) {
-		console.log(issue.path, issue.code, issue.message); // ["addresses", 0, "zip"] "invalid_value" ...
-	}
-} else {
-	result.value; // handled and frozen
-}
-```
-
-`code` is one of `required`, `invalid_type`, `invalid_value`, `undeclared_key`, `too_few_items`, `too_many_items` and `not_record`; `source` names who rejected the value, and for a property issue `cause` keeps the exception it raised.
-
-`Record.safeParse` builds the instance through the class constructor, so a subclass that normalizes its input, or throws its own exception, is honored: what `new User(value)` accepts, `User.safeParse(value)` accepts, and an error thrown by the constructor becomes an issue (code `invalid_value`, path `[]`) instead of escaping. An instance of the class is returned as it is.
-
-The input type is that of the blueprint (a record field takes an instance or a plain object). `StandardSchemaV1.InferOutput<typeof User>` is the instance type of the class `recordOf` returns. For a subclass that adds members (`class User extends recordOf(...) { get initials() {} }`) that is the base record instance type, because TypeScript cannot type the statics of a subclass; at runtime the value is an instance of the subclass, so narrow it with `instanceof User`. Each class has one stable `~standard` object.
-
-The real-library tests (Hono, tRPC, TanStack Form) are in `examples/interop`: `bun run test:interop`.
-
-## OpenAPI
-
-`toOpenAPI` turns any field (a property, blueprint, list, record or entity) into an OpenAPI 3.1 schema, which is plain JSON Schema. Given named models, it gives the `components` of a document, and a record named among them is a `$ref` wherever another model holds it:
-
-```ts
-import { blueprintOf, entityOf, toOpenAPI } from "@afora/core";
-
-const User = entityOf(
-	blueprintOf((ctx) => ({
-		name: ctx.text({ max: 80, description: "Full name" }),
-		email: ctx.email({ examples: ["jane@example.com"] }),
-		password: ctx.password,
+// Use case: the steps are data, so they can also live in an afora.json
+class Register extends useCaseOf({
+	name: "Register",
+	blueprint: blueprintOf((ctx) => ({
+		name: ctx.text,
+		email: ctx.email,
+		plainPassword: ctx.string,
 	})),
-);
-const Post = entityOf(
-	blueprintOf((ctx) => ({ title: ctx.text, author: User })),
-);
-
-toOpenAPI(User); // { type: "object", properties: { id: {..., readOnly: true }, ... } }
-
-const document = {
-	openapi: "3.1.0",
-	info: { title: "Blog", version: "1.0.0" },
-	paths: {},
-	components: toOpenAPI({ User, Post }), // Post.author is { $ref: "#/components/schemas/User" }
-};
-```
-
-What `Property.with` (or `ctx.<property>(options)`) gives, `description`, `examples`, bounds and the rest, is kept. Sensitive keys (`Password`, `options.sensitive`) are `writeOnly`, the identity of an entity (`id`, `createdAt`, `updatedAt`, `deletedAt`) is `readOnly`, optional keys are left out of `required`, and every object has `additionalProperties: false`, since blueprints reject undeclared keys. Records not named among the models are inline; `refPrefix` changes where a `$ref` points (`"#/components/schemas/"` by default). A model that is not a field throws `InvalidOpenAPIModel`.
-
-## Concepts
-
-### Properties
-
-A property is a class that validates and normalizes one value, through `preHandle -> validation -> afterHandle`; the current step is exposed on `property.definition[State]`.
+	response: blueprintOf(() => ({ user: User })),
+	dependencies: { users: Users },
+	errors: [UserAlreadyExists],
+	steps: [
+		{ find: "users.findByEmail", args: ["$input.email"], as: "existing" },
+		{ ensure: "absent", value: "$existing", error: UserAlreadyExists },
+		{
+			run: "hashPassword",
+			fn: hashPassword,
+			args: ["$input.plainPassword"],
+			as: "hash",
+		},
+		{
+			build: User,
+			values: { name: "$input.name", email: "$input.email", password: "$hash" },
+			as: "user",
+		},
+		{ create: "users", value: "$user", as: "saved" },
+		{ return: { user: "$saved" } },
+	],
+}) {}
 
-```ts
-import { Type } from "typebox";
-import { propertyOf } from "@afora/core";
-
-const Name = propertyOf({
-	name: "name",
-	schema: Type.String({ minLength: 3 }),
-	preHandle: (value) => value.trim(),
-	default: "Jane", // used by Name.demo()
+// Command: the execution boundary (here, one transaction per call)
+const Accounts = commandOf({
+	name: "Accounts",
+	useCases: { register: Register },
+	transaction: true,
 });
 
-new Name("  Alice ").value; // "Alice"
-new Name("a"); // throws: Invalid value for property "name": ...
-Name.demo().value; // "Jane"
-```
-
-Pass `optional: true` to accept `undefined`, `sensitive: true` to have records mask it (as `Password` does) and `unique: true` to have records list its key in `options.unique` (as `Slug` does). `Std` ships `Id`, `Slug`, `Email`, `Phone`, `Url`, `Ip`, `Password`, strings, numbers, booleans and date properties.
-
-`Property.with(options)` gives a subclass narrowed and documented by `options`. In a blueprint, every property of the context can be called for the same thing, as `ctx.number({ min: 1 })`; used as it is, `ctx.number` is still the class:
-
-```ts
-import { blueprintOf, Integer } from "@afora/core";
-
-const Age = Integer.with({ min: 0, max: 150, description: "In years" });
-
-const Product = blueprintOf((ctx) => ({
-	name: ctx.text({ max: 80, description: "Shown in the catalog" }),
-	price: ctx.number({ min: 1, examples: [1990] }),
-	sku: ctx.string({ pattern: /^[A-Z]{3}-\d{4}$/, examples: ["MUG-0001"] }),
-	stock: ctx.optional.integer({ min: 0 }),
-	status: ctx.enumOf(["draft", "published"]).with({ deprecated: true }),
-}));
-
-Product.schema.toString(); // JSON Schema, with each description, example and bound
-```
-
-Every property takes `title`, `description`, `examples`, `deprecated`, `readOnly` and `writeOnly`, which go to its JSON Schema as they are (for OpenAPI and other docs) and change nothing in validation, and `default`, its demo value, which is not written to the schema; without `default`, the first of `examples` is the demo. Strings also take `min` and `max` (`minLength`/`maxLength`) and `pattern` (a string or a `RegExp`, whose flags are not kept); numbers and integers take `min`, `max`, `exclusiveMin`, `exclusiveMax` and `multipleOf`. Constraints only narrow a property: `ctx.text({ min: 0 })` keeps the `minLength: 1` of `Text`, and a pattern given to `Phone` is checked along with its own, under `allOf`. Handlers, flags (`sensitive`, `unique`) and statics are kept, so `ctx.id({ description })` still has `generate()` and `ctx.slug({ max: 40 })` is still unique. Factories such as `ctx.enumOf` return a class, so use `.with` on what they return.
-
-`enumOf` declares a property that holds one of a list of strings or numbers; its demo is the first value unless `default` is given. In a blueprint it is `ctx.enumOf`:
-
-```ts
-import { blueprintOf, enumOf } from "@afora/core";
-
-const Status = enumOf(["draft", "published"], { name: "status" });
-
-new Status("draft").value; // "draft", typed "draft" | "published"
-new Status("archived"); // throws: Invalid value for property "status": ...
-
-const Post = blueprintOf((ctx) => ({
-	status: ctx.enumOf(["draft", "published"]),
-	tags: ctx.listOf(ctx.enumOf(["news", "tech"]), { minItems: 1 }),
-	level: ctx.optionalOf(ctx.enumOf([1, 2, 3])), // or ctx.enumOf([1, 2, 3], { optional: true })
-}));
-```
-
-### Blueprints
-
-A blueprint picks properties from `Std` and its sources, plugins or other blueprints. A key can also hold another blueprint, validated as a nested object, and `join` merges blueprints:
-
-```ts
-import { blueprintOf, listOf, optionalOf } from "@afora/core";
-
-const Address = blueprintOf((ctx) => ({ street: ctx.string, zip: ctx.string }));
-const Timestamps = blueprintOf((ctx) => ({ createdAt: ctx.createdAt }));
-
-const User = blueprintOf((ctx) => ({
-	name: ctx.string,
-	address: Address, // nested object
-	billing: optionalOf(Address), // optional nested object
-	addresses: listOf(Address), // array of nested objects
-	tags: listOf(ctx.string, { maxItems: 5 }), // array of values
-}));
-
-const Admin = blueprintOf([User], (ctx) => ({
-	name: ctx.name, // picked from User
-	role: ctx.string,
-}));
-
-const Customer = User.join(Timestamps); // every field of both
-```
-
-`ctx.optional.*` and `ctx.list.*` mirror every field: `ctx.list.string` is `listOf(ctx.string)` and `ctx.list.optional.string` an optional list of strings. Every context also has `ctx.listOf`, `ctx.optionalOf` and `ctx.propertyOf`, the same functions as the exports, to make fields inline: `ctx.listOf(ctx.string, { maxItems: 5 })`, `ctx.optionalOf(Address)`. `optional`, `list`, `listOf`, `optionalOf` and `propertyOf` are reserved, so no plugin can declare them. Factories such as `ctx.enumOf` are not mirrored under `optional` and `list`, which would lose their literal types; wrap what they return in `ctx.listOf` or `ctx.optionalOf`.
-
-`join` takes any number of blueprints (`A.join(B, C)` is `A.join(B).join(C)`); a later one replaces a key of an earlier one, like plugins do. `listOf` takes a property, a blueprint or another list, and `optionalOf` makes it an optional key.
-
-`blueprintOf` is `blueprintBuilderOf(Std)`. To build blueprints from other properties, without `Std`, make a builder of your own:
-
-```ts
-import { blueprintBuilderOf, blueprintPluginOf } from "@afora/core";
-
-const contentBlueprintOf = blueprintBuilderOf(
-	blueprintPluginOf("content", { title: Title, body: Body }),
-);
-const Post = contentBlueprintOf((ctx) => ({
-	title: ctx.title,
-	body: ctx.body,
-}));
-```
-
-A plugin can also take factories, functions that make a field from their arguments, as `Std` does with `enumOf`: `blueprintPluginOf("content", { title: Title }, { enumOf })` gives `ctx.enumOf`. A factory replaces a field with the same name.
-
-### Slicing
-
-`sliceOf(blueprint, selector)` gives a new blueprint with only the fields `selector` names, recursively into nested blueprints, records and lists. Optional fields stay optional and lists stay lists. A property is kept with its flags (`sensitive`, `unique`, ...); a nested record stays a record, with the `sensitive`, `unique` and `change` keys it declares among the keys kept, so it still masks its sensitive keys and is still `writeOnly` in `toOpenAPI`. The selector is a mask, `true` keeping a field whole and an object keeping only its keys, or a blueprint or record class, whose keys, at any depth, are the mask.
-
-```ts
-import { sliceOf, sliceValue } from "@afora/core";
-
-const Card = sliceOf(Person, { name: true, address: { city: true } });
-const Same = sliceOf(Person, CardBlueprint); // keys of another blueprint or record class
-```
-
-A nested record or entity the selector names whole (`true`, or the same class in a blueprint or record selector) is kept as it is. One sliced to some of its keys becomes a plain record of those keys, not an entity: its identity keys (`id`, `createdAt`, ...) are in it only if the selector names them, and it has no events, `destroy` or plugin members. A sliced record field still accepts an instance of the original record.
-
-A key the blueprint does not have is a type error and throws `UndeclaredBlueprintProperty`. The types `SliceMask` and `ValueMask` describe a selector mask, and `SlicedBlueprint` and `SlicedValue` the results.
-
-`sliceValue(value, selector)` does the same to data: it strips the keys the selector does not name, through objects and lists, and does not validate. A record instance is read by its `toJSON`, so what is sensitive stays masked; a plain object is copied as it is. A key missing from the value is left out.
-
-```ts
-sliceValue(post, { title: true, author: { name: true } }); // { title, author: { name } }
-```
-
-### Records
-
-A record implements a blueprint: it keeps the blueprint and a value of its shape, each key handled by its field (at any depth) and read as a member of the record (`user.name`). Its constructor takes the value inferred from the blueprint (and throws on an invalid one), the protected `set` changes one key, and `onSet` declares the side effect of a change to each key:
-
-```ts
-import { recordOf, type RecordEffects } from "@afora/core";
-
-class User extends recordOf(UserBlueprint) {
-	protected override onSet(): RecordEffects<User> {
-		return {
-			name: (value, previous) => console.log(`${previous} -> ${value}`),
-		};
-	}
-}
-
-const user = new User({
-	name: " Jane ",
-	address: { street: "Main St", zip: "01310-100" },
+// Output: the commands as an HTTP API with an OpenAPI document
+const Api = outputOf({
+	name: "Api",
+	commands: [Accounts],
+	statuses: { UserAlreadyExists: 409 },
+	pipe: [
+		hono({
+			basePath: "/api",
+			docs: {
+				path: "/openapi.json",
+				info: { title: "Accounts", version: "1.0.0" },
+			},
+		}),
+	],
 });
-user.name; // "Jane"
-user.blueprint; // UserBlueprint
-```
 
-A second argument describes the keys:
+export const api = Api.build();
 
-```ts
-class Account extends recordOf(AccountBlueprint, {
-	sensitive: ["token"], // masked in toJSON; a sensitive property (Password) always is, at any depth
-	unique: ["email"], // listed for repositories to enforce; a unique property (Slug) key always is
-	change: ["password"], // generates a typed change.password(value)
-}) {}
-
-Account.options; // { sensitive: ["token", "password"], unique: ["email"], change: ["password"] }
-new Account(value).change.password(hash); // same as set("password", hash), returns the record
+if (import.meta.main) Bun.serve({ fetch: api.fetch });
 ```
 
-Keys are resolved in the order of the blueprint.
-
-**Masking.** A key holding a property declared `sensitive`, such as `Password` (optional, or a list of them), is always sensitive. `toJSON` (and so `JSON.stringify`) replaces each leaf of a sensitive value (strings, numbers, booleans; objects and lists leaf by leaf) with `MASK` (`"********"`, the same whatever the length, so none leaks), and does the same for every `sensitive` property at any depth, inside nested blueprints and lists too. Reading a key still gives the real value (`account.password` is the hash, for `verify` and repositories).
-
-**Uniqueness.** A key holding a property declared `unique`, such as `Slug` (optional or not), is always unique; a list of them is not, since uniqueness applies to a key's value. `unique` only records the intent: a record never compares itself with other records, so two records with the same `email` both build. `options.unique` names the keys a repository (or a unique index in the database) must enforce. `Slug` slugifies its value: `"  Olá Mundo! "` becomes `"ola-mundo"`.
-
-**Changes.** The keys are read-only and only change through `set`, which only the record itself (or a `change.<key>` method) can call. `set` validates the value, stores it, then runs `onSetAll(change)` and then the effect of the key in `onSet`. `change` is `{ key, value, previous }`, and checking `change.key` narrows the rest (annotate it as `RecordChange<User>`).
-
-**Rejections.** An invalid value throws in the `Record` layer, naming the key in `details` (e.g. `{ key: "address.zip" }`). So does a key the blueprint does not declare, at any depth, with `UndeclaredRecordProperty` (e.g. `{ key: "addresses.0.extra" }`): the value is rejected, never trimmed. A key cannot take the name of a member of the record (`blueprint`, `options`, `set`, `toJSON`, `onSet`, `onSetAll` or, when the record has `change` keys, `change`), nor of one every object inherits (`toString`, `valueOf`, `hasOwnProperty`, `__proto__`... all of `Object.prototype`, listed in `RESERVED_RECORD_KEYS`): `recordOf` throws `ReservedRecordKey`. Nor can a class extending the record declare a member with the name of a key, which would hide it: its first record throws `ReservedRecordKey`.
-
-**Spread caveat.** The value of a record lives in a `WeakMap`, and each key is a getter on the record's prototype, not an own property. So `Object.keys(user)` is `["blueprint", "options"]` and `{ ...user }` holds no key of the blueprint. For plain data use `user.toJSON()` (frozen, sensitive values masked), or `blueprint.safeParse(value)` to handle plain input into a plain object. To build a record from another one, pass a plain object of its keys, not the record itself, whose `blueprint` and `options` would be undeclared keys.
-
-### Entities
-
-An entity is a record with identity, ready to persist. `entityOf` takes a blueprint and the options of `recordOf`, and adds four keys to it, from `std`:
-
-- `id`: an `Id` (UUID v7), generated when the value has none and always listed in `options.unique`.
-- `createdAt`: generated as now when the value has none.
-- `updatedAt`: absent until the first change, then set to now by each `set` or `change.<key>`, before `onSetAll` and `onSet` run.
-- `deletedAt`: set by `destroy()`, which then runs `onDestroy`. A destroyed entity (`isDeleted`) no longer changes: `set`, `change.<key>` and `destroy` throw `DeletedEntity`.
-
-```ts
-import { blueprintOf, entityOf, listOf, optionalOf } from "@afora/core";
+What it does:
 
-class User extends entityOf(
-	blueprintOf((ctx) => ({ name: ctx.string })),
-	{ change: ["name"] },
-) {}
+```
+POST /api/accounts/register  { "name": "Ana", "email": "  Ana@Example.COM ", "plainPassword": "Str0ng!Pass" }
+-> 200 { "user": { "id": "...", "name": "Ana", "email": "ana@example.com", "password": "********", ... } }
 
-const user = new User({ name: "Jane" });
-user.id; // "019a…" (UUID v7)
-user.updatedAt; // undefined
-user.change.name("Ann").updatedAt; // now
-user.destroy().isDeleted; // true
+the same email again
+-> 409 application/problem+json  { "title": "UserAlreadyExists", "layer": "use-case", ... }
 
-// Loaded from a database: the identity given is validated and kept
-new User({ id, createdAt, updatedAt, deletedAt, name: "Jane" });
+{ "name": "Ana", "email": "nope" }
+-> 400 application/problem+json  { ..., "issues": [{ "path": ["email"], ... }, { "path": ["plainPassword"], ... }] }
 
-// As any record, an entity is a field of a record or of another entity
-class Post extends entityOf(
-	blueprintOf((ctx) => ({
-		title: ctx.string,
-		author: User,
-		reviewer: optionalOf(User),
-		coauthors: listOf(User),
-	})),
-) {}
-new Post({ title: "Hi", author: { name: "Jane" }, coauthors: [user] }); // author gets its own id
+GET /openapi.json -> the OpenAPI 3.1 document of the route
 ```
 
-The identity keys are read-only: `set` throws `ImmutableEntityKey` for them, and they get no `change.<key>` method. The blueprint cannot declare them, nor the members of an entity (`destroy`, `isDeleted`, `equals`, `onDestroy`, `emit`, `pullEvents`): `entityOf` throws `ReservedEntityKey`. `user.equals(other)` compares entities of the same declaration by `id`. `isEntityClass` and `isEntity` tell entities apart from records. `entityBuilderOf({ identity, generateId, now })` makes an `entityOf` with your own identity fields and clock.
-
-Entities can queue domain events for an external consumer. `eventOf` accepts an entity class (including subclasses) and an async handler returning `Promise<void>`. Definitions are immutable; incompatible entity instances are rejected when emitting.
-
-```ts
-import {
-	blueprintOf,
-	entityOf,
-	eventOf,
-	type EventDefinition,
-} from "@afora/core";
+### The same app as an afora.json
 
-const UserBlueprint = blueprintOf((ctx) => ({ name: ctx.string }));
-class User extends entityOf(UserBlueprint, {
-	change: ["name"],
-	onCreate: () => UserCreated,
-	onUpdate: () => [UserUpdated],
-	onDelete: () => UserDeleted,
-}) {
-	announce(): void {
-		this.emit(UserUpdated);
-	}
-}
+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.
 
-// The annotation breaks TypeScript's circular inference through the base class.
-// The handler parameter is still inferred as User.
-const UserCreated: EventDefinition = eventOf(
-	"user.created",
-	User,
-	async (user) => {
-		console.log(user.id);
+```json
+{
+	"version": 1,
+	"name": "accounts",
+	"output": { "dir": "src/domain" },
+	"provider": "inMemory",
+	"entities": {
+		"User": {
+			"fields": { "name": "text", "email": "email", "password": "password" },
+			"unique": ["email"]
+		}
 	},
-);
-const UserUpdated: EventDefinition = eventOf(
-	"user.updated",
-	User,
-	async (user) => {
-		console.log(user.name);
+	"repositories": {
+		"Users": { "entity": "User", "actions": ["findByEmail", "create"] }
 	},
-);
-const UserDeleted: EventDefinition = eventOf(
-	"user.deleted",
-	User,
-	async (user) => {
-		console.log(user.deletedAt);
+	"exceptions": {
+		"UserAlreadyExists": {
+			"layer": "use-case",
+			"message": "A user with this email already exists."
+		}
 	},
-);
-
-const user = new User({ name: "Jane" });
-user.change.name("Ann");
-user.announce();
-for (const event of user.pullEvents()) {
-	await event.handle();
-}
-```
-
-`emit` is protected and synchronous: it queues without executing the handler. `pullEvents()` immediately empties that instance's queue and returns occurrences with `name`, `entity`, and `handle(): Promise<void>`, in emission order, including duplicates. Each occurrence references the original entity and sees its state when handled, without making a snapshot. Events are excluded from `toJSON()` and JSON serialization. Records have no event API.
-
-Each lifecycle option accepts a definition, a readonly list, or a function returning either. Functions are resolved only during their cycle, so definitions may follow the entity class but must exist before constructing instances. `onCreate` queues after base construction and validation only when **both** input `id` and `createdAt` are `undefined`. Supplying either identity field, as when loading persisted data, suppresses creation; parsing plain input follows the same rule. `onUpdate` queues after each valid `set` (including `change.<key>` and equal values) stores the value and `updatedAt`, before `onSetAll` and `onSet`. `onDelete` queues after `deletedAt` is stored, before `onDestroy`. Invalid operations and repeated deletion do not queue lifecycle events. If an existing hook throws after a mutation, its queued events remain.
-
-The consuming layer decides when to drain and execute events. `handle()` propagates handler failures and can be called more than once. There is no automatic execution, dispatcher, retry, or execution-once guarantee.
-
-
-### Plugins
-
-A plugin carries keys, options and behavior that records and entities share, with no identity of its own. It is made from a record class: the keys of its blueprint, its `sensitive`, `unique` and `change` keys, the methods and getters its class declares, and its `onSet` and `onSetAll`. A record or an entity lists plugins in `options.plugins`, and gets all of that:
-
-```ts
-import {
-	blueprintOf,
-	entityOf,
-	hasPlugin,
-	recordOf,
-	recordPluginOf,
-	type RecordEffects,
-} from "@afora/core";
-
-class SluggedRecord extends recordOf(
-	blueprintOf((ctx) => ({ slug: ctx.slug })), // Slug: always unique
-	{ change: ["slug"] },
-) {
-	get path(): string {
-		return `/${this.slug}`;
-	}
-
-	protected override onSet(): RecordEffects<SluggedRecord> {
-		return { slug: (value) => console.log(`moved to /${value}`) };
-	}
-}
-
-export const Slugged = recordPluginOf("slugged", SluggedRecord, {
-	version: "1.0.0",
-});
-
-class Post extends entityOf(
-	blueprintOf((ctx) => ({ title: ctx.string })),
-	{ plugins: [Slugged] },
-) {}
-
-const post = new Post({ title: "Hi", slug: "Olá Mundo" });
-post.path; // "/ola-mundo"
-post.change.slug("hello"); // sets updatedAt, then logs "moved to /hello"
-Post.options.unique; // ["id", "slug"]: repositories get findBySlug
-hasPlugin(post, Slugged); // true, and narrows post to the plugin's record
-```
-
-- **Behavior.** The plugin's methods run on the record they are applied to, so `this.set` is that record's (an entity's sets `updatedAt` and queues `onUpdate`). Its `onSetAll` and `onSet` effects run for changes to its keys, before those of the record. The constructor of the plugin's class does not run for the record, and its methods cannot use private (`#`) members.
-- **Conflicts.** A plugin key or member cannot be one the record, or another plugin, already has (an entity's identity included): declaring the record throws `RecordPluginConflict`. Nor can two different plugins share a name. A plugin's class cannot replace a member every record has (`toJSON`, `set`...), and cannot be an entity (plugins have no identity): `recordPluginOf` throws `InvalidRecordPlugin`.
-- **Composition.** A plugin's class can declare plugins itself: they are applied with it, each once, and listed in `plugin.requires`. `Post.plugins` lists them all.
-- **Tracking.** `hasPlugin(value, plugin)` (or `plugin.is(value)`) tells a record, an entity or a class of them having the plugin, through `requires` and subclasses too. `hasPlugin(value, "slugged")` checks by name. `pluginsOf(value)` lists them.
-
-**Standard plugins.** `recordOf` and `entityOf` pick from the plugins of `StdRecordPlugins` when `options.plugins` is a function, the way `blueprintOf` picks from `Std`:
-
-```ts
-class Article extends entityOf(
-	blueprintOf((ctx) => ({ title: ctx.string })),
-	{
-		plugins: (ctx) => [ctx.publishable, ctx.taggable, ctx.ownable],
+	"useCases": {
+		"Register": {
+			"input": {
+				"fields": {
+					"name": "text",
+					"email": "email",
+					"plainPassword": "string"
+				}
+			},
+			"response": { "fields": { "user": "User" } },
+			"dependencies": { "users": "Users" },
+			"errors": ["UserAlreadyExists"],
+			"implementation": {
+				"steps": [
+					{
+						"find": "users.findByEmail",
+						"args": ["$input.email"],
+						"as": "existing"
+					},
+					{
+						"ensure": "absent",
+						"value": "$existing",
+						"error": "UserAlreadyExists"
+					},
+					{
+						"run": "hashPassword",
+						"fn": { "import": "../hash-password.ts#hashPassword" },
+						"args": ["$input.plainPassword"],
+						"as": "hash"
+					},
+					{
+						"build": "User",
+						"values": {
+							"name": "$input.name",
+							"email": "$input.email",
+							"password": "$hash"
+						},
+						"as": "user"
+					},
+					{ "create": "users", "value": "$user", "as": "saved" },
+					{ "return": { "user": "$saved" } }
+				]
+			}
+		}
 	},
-) {}
-```
-
-| Plugin            | Keys                                     | Adds                                             |
-| ----------------- | ---------------------------------------- | ------------------------------------------------ |
-| `publishable`     | `publishedAt?`                           | `publish(at?)`, `unpublish()`, `isPublished`     |
-| `archivable`      | `archivedAt?`                            | `archive(at?)`, `restore()`, `isArchived`        |
-| `taggable`        | `tags?` (strings)                        | `tag(...tags)`, `untag(...tags)`, `hasTag(tag)`  |
-| `ownable`         | `ownerId` (an `Id`)                      | `isOwnedBy(id)`, `transferTo(id)`                |
-| `authenticatable` | `email` (unique), `password` (sensitive) | `change.password(hash)`, `verifyPassword(plain)` |
-
-Your own catalog is `recordPluginCatalogOf(Slugged, ...StdRecordPlugins.list)`, given to `recordBuilderOf(catalog)` or to `entityBuilderOf({ ..., plugins: [catalog] })`. A later catalog replaces a plugin of an earlier one that has the same name.
-
-**Serialization.** A plugin is a descriptor in JSON (`plugin.toJSON()`): its name, version, keys, `sensitive`, `unique` and `change` keys, member names and requirements. Methods are listed by name, never serialized as code, so a catalog resolves a descriptor back to the plugin that implements it:
-
-```ts
-const json = JSON.stringify(Post.plugins);
-// [{"kind":"record-plugin","name":"slugged","version":"1.0.0","keys":["slug"],...}]
-
-const plugins = catalog.resolveAll(JSON.parse(json));
-class Rebuilt extends entityOf(PostBlueprint, { plugins }) {}
-
-catalog.resolve("slugged"); // by name
-catalog.resolve("slugged@1.0.0"); // by name and version
-```
-
-`resolve` throws `UnknownRecordPlugin` when the catalog has no plugin of that name. It throws `IncompatibleRecordPlugin` when the catalog's plugin does not satisfy the reference: a different major version (minor, below `1.0.0`), an older version, or keys, options, members or requirements the descriptor lists that it no longer has. Typing is lost once plugins go through JSON, since they are only known at runtime.
-
-### UseCases
-
-`useCaseOf` declares an abstract operation with input and response blueprints and a collection of concrete UseCase classes as dependencies. This combines the **Command** pattern (an instance holds the operation's arguments) with **method injection** (dependency functions are supplied to `execute`).
-
-```ts
-import { blueprintOf, entityOf, useCaseOf } from "@afora/core";
-
-const UserInput = blueprintOf((ctx) => ({ name: ctx.string }));
-class User extends entityOf(UserInput) {}
-const UserResponse = blueprintOf(() => ({ user: User }));
-
-class CreateUser extends useCaseOf({
-	name: "CreateUser",
-	blueprint: UserInput,
-	response: UserResponse,
-}) {
-	override async execute() {
-		return { user: new User(this.input) };
-	}
-}
-
-class RegisterUser extends useCaseOf({
-	name: "RegisterUser",
-	blueprint: UserInput,
-	dependencies: { createUser: CreateUser },
-	response: UserResponse,
-}) {
-	override async execute({ createUser = this.dependencies.createUser } = {}) {
-		return await createUser(this.input);
+	"commands": {
+		"Accounts": { "useCases": { "register": "Register" }, "transaction": true }
+	},
+	"outputs": {
+		"Api": {
+			"commands": ["Accounts"],
+			"statuses": { "UserAlreadyExists": 409 },
+			"pipe": [
+				{
+					"sink": "hono",
+					"options": {
+						"basePath": "/api",
+						"docs": {
+							"path": "/openapi.json",
+							"info": { "title": "Accounts", "version": "1.0.0" }
+						}
+					}
+				}
+			]
+		}
 	}
 }
-
-const operation = new RegisterUser({ name: "Ana" });
-const { user } = await operation.execute();
-for (const event of operation.pullEvents()) await event.handle();
-
-// Partial overrides replace direct dependencies; other dependencies resolve normally.
-await new RegisterUser({ name: "Ana" }).execute({
-	createUser: async (input) => ({ user: new User(input) }),
-});
 ```
 
-The constructor validates its arguments and exposes their parsed values as read-only `this.input`. Implement `execute` as an async prototype method, not an arrow-function field. It must return the value shape of the response blueprint, including record/entity instances for those fields. The framework wraps the method automatically to validate the response and collect events; no `super.execute()` call is needed. Each instance allows one execution attempt, including failures; concurrent or subsequent calls reject with `UseCaseAlreadyExecuted`.
-
-Dependencies default to `{}`. Each dependency function creates a fresh child, resolves its dependencies and returns its validated response. Await all dependency calls before returning. Functions are usable only during execution. Use the destructured defaults shown above to keep both no-argument calls and partial overrides inferred in TypeScript. `execute(deps = this.dependencies)` also supports no-argument calls, but its inferred override type requires the complete dependency map. During execution, `this.dependencies` exposes the resolved functions, including overrides. Overrides apply only to direct dependencies, and their inputs and responses are validated against the declared child. There is no global container.
-
-Events from managed children move to the parent when each child finishes, including on failure and when the parent's response omits the child result. Then the validated parent response is traversed through declared records, entities, nested blueprints and lists. Repeated object references are visited once; separately emitted duplicate events are preserved. Child events follow completion order, followed by remaining response events. No handlers run automatically. `pullEvents()` immediately drains the queue, which remains available after failure. Invalid responses are not drained. Overrides contribute events from their returned entities; hidden operations inside an override must expose their events separately.
-
-`UseCaseInput`, `UseCaseResponse` and `UseCaseDependencies` extract a declaration's types. `isUseCase` identifies instances; `isUseCaseClass` identifies concrete declarations with a prototype `execute`. UseCases carry their own kind and cannot be used as fields of ordinary data blueprints. Validation errors carry `details.issues`; errors crossing an execution boundary preserve their cause and gain a `UseCase` trace frame using the declared name.
-
-### Repositories
-
-`repositoryOf` makes a repository of an entity with the methods you choose: `findBy<Key>` for a unique key (`id`, a key in `options.unique`, or one holding a `unique` property such as `Slug`), giving the entity or `undefined`; `findManyBy<Key>` for any key that is not unique, giving a list (a unique key has `findBy<Key>` instead, so `findManyByEmail` is rejected by type and at declaration); `create`, `update`, `delete` and `count`. Every method is async.
-
-```ts
-import {
-	blueprintOf,
-	entityOf,
-	environmentOf,
-	repositoryOf,
-	RepositoryOf,
-} from "@afora/core";
-
-class User extends entityOf(
-	blueprintOf((ctx) => ({
-		name: ctx.string,
-		email: ctx.email,
-		slug: ctx.slug,
-	})),
-	{ unique: ["email"] },
-) {}
-
-const Users = repositoryOf({
-	entity: User,
-	actions: [
-		"findById",
-		"findByEmail",
-		"findBySlug",
-		"findManyByName",
-		"create",
-		"update",
-		"delete",
-		"count",
-	],
-});
-
-const user = await Users.create({
-	name: "Ana",
-	email: "ana@example.com",
-	slug: "ana",
-});
-await Users.findByEmail("ana@example.com"); // User | undefined
-await Users.findManyByName("Ana"); // User[]
-// repositoryOf({ entity: User, actions: ["findByName"] }) does not compile, and throws: name is not unique
-```
-
-`create` takes an entity or the input that builds one. `delete` takes an entity or an id, calls `destroy()` (so `onDelete` is queued) and gives the entity. Entities read back are rebuilt from their stored value, with their identity, so they do not queue `onCreate` again.
-
-**Providers.** A repository reads and writes through an `IRepositoryProvider`: `findOne`, `findMany`, `insert`, `update`, `remove` and `count`, on plain unmasked values, each getting a `context` with the `entity`, the repository `name`, its `unique` keys and `env`. A provider enforces `context.unique` (`RepositoryUniqueViolation`) and rejects an unknown id on `update` and `remove` (`RepositoryEntityNotFound`). By default each repository gets its own `inMemoryProvider()`; repositories given the same provider share the table of their entity. `repositoryOf` checks that the provider has the methods its actions call.
-
-**Environments.** `environmentOf(blueprint)` reads the declared variables from `process.env` (or `{ source }`), validates them on the first `load()` and keeps the value; a missing or rejected variable throws `InvalidEnvironment`. Pass one, or a list (merged in order), as `environmentDependencies`: the provider gets them as `context.env`, read on the first call, not on declaration.
-
-```ts
-const Database = environmentOf(
-	blueprintOf((ctx) => ({ DATABASE_URL: ctx.url })),
-);
-const Posts = repositoryOf({
-	entity: Post,
-	actions: ["findById"],
-	provider: postgres,
-	environmentDependencies: [Database],
-});
-```
-
-A variable is converted when its property does not take a string: to `true` or `false` (from `"true"` and `"false"`) for a boolean, and to a number for a number, e.g. `PORT: ctx.integer` reads `"3000"` as `3000`, and `DEBUG: ctx.boolean` reads `"true"` as `true`. A property that takes a string keeps the variable as is, so `"10"` stays a string for `ctx.string`. A value that does not convert is left for the blueprint to reject.
-
-**References.** An entity a record holds (as a field, in a list, in a blueprint, or in a record that is not an entity) is stored as its id, not as a copy, and loaded back when the record is read, so it is always current. List the repositories that load them in `relations`: one for each entity class held, at any depth (the class itself, or a subclass). A missing, extra, duplicated or invalid relation throws `InvalidRepositoryDeclaration`. A stored id with no entity throws `InvalidRepositoryData`, caused by `RepositoryEntityNotFound`, even in an optional field. Reads load by batch (one `findIn` of the provider for each relation, when it has one, or a `findOne` for each distinct id), and the same id is the same instance within a read. Writes do not cascade: the entity is not checked or saved, so persist it through its own repository. Entities loaded this way do not queue `onCreate` again, and a use case collects the events of an entity only when it goes through that entity's own repository. `findBy<Key>` and `findManyBy<Key>` take the entity or its id (a list of them for a list field).
-
-```ts
-class PasswordRecovery extends entityOf(
-	blueprintOf((ctx) => ({ user: User, token: ctx.string })),
-	{ unique: ["token"] },
-) {}
-
-const Recoveries = repositoryOf({
-	entity: PasswordRecovery,
-	actions: ["findByToken", "findManyByUser", "create"],
-	relations: [Users], // stored as { user: "<id>", token: "..." }
-});
-
-await Recoveries.findManyByUser(user); // or findManyByUser(user.id)
-```
-
-**Extending.** `RepositoryOf(repository)` is the class of a repository, to extend. Its instances share the entity, actions, provider and environment of the repository, and can use the protected `provider`, `context`, `env`, `dataOf(entity)`, and the async `hydrate(data)` and `hydrateMany(list)`, which also load the entities a stored value holds. `create`, `update`, `delete` and `count` are overridden as methods. `findBy<Key>` and `findManyBy<Key>` are named after the entity's keys, so TypeScript types them as properties: override them with a field, which can still call `super`.
+The `run` step names a function written by hand, imported relative to the output directory. Put it in `src/hash-password.ts`:
 
 ```ts
-class UsersRepository extends RepositoryOf(Users) {
-	override findByEmail = async (email: string) =>
-		super.findByEmail(email.trim().toLowerCase());
-
-	override async create(...args: Parameters<typeof Users.create>) {
-		const user = await super.create(...args);
-		// ...
-		return user;
-	}
+import { Password } from "@afora/core";
 
-	async countAll() {
-		return this.provider.count(this.context);
-	}
+export async function hashPassword(plain: string) {
+	return (await Password.hash(plain)).value;
 }
 ```
 
-As a type, `RepositoryOf<typeof User, ["findById", "create"]>` is the repository with those methods.
-
-**In use cases.** A repository (or an instance of a class extending one) and an environment are dependencies of a use case, next to other use cases. The use case gets the repository's methods, usable only during execution; the events of the entities they take and give move to the use case. In a class extending a repository, the methods call each other through the use case too (`this.create` inside `revokeAllOf`): their events move to it, and what `execute` replaces is replaced there as well. Only the events of entities of the repository's own class move; the entities it holds (`post.author`) leave theirs to their own repository. Two limits: `#private` members do not work in the methods the use case calls, and an arrow field calling `this.other` does not go through the use case (`super.other` does); a repository used by importing it is not tracked. It gets an environment's variables. `execute` replaces some methods of a repository with an object, and an environment with variables its blueprint accepts.
+Then generate, telling codegen where the `hono` stage comes from, and serve the application:
 
-```ts
-class Register extends useCaseOf({
-	name: "Register",
-	blueprint: UserInput,
-	response: UserResponse,
-	dependencies: { users: Users, database: Database },
-}) {
-	override async execute({ users = this.dependencies.users } = {}) {
-		return { user: await users.create(this.input) };
-	}
-}
+```bash
+bun add -d @afora/codegen
+bunx afora-codegen generate afora.json --stages @afora/hono   # writes src/domain/*.ts
 ```
 
-### Applications
-
-`applicationOf` gathers the declarations of an app in one named, immutable manifest, so everything runs in one context and can be inspected:
-
 ```ts
-const Blog = applicationOf({
-	name: "blog",
-	properties: { Age, Status },
-	blueprints: { Address },
-	entities: { User, Post },
-	environments: { Database },
-	repositories: { Users, Posts },
-	provider: inMemoryProvider(), // the default of the repositories that declared none
-});
+import { App } from "./src/domain";
 
-Blog.entities.User; // the declarations, by name
-Blog.repositories.Users; // typed; bound to Blog's provider
-Blog.repository(Users); // the same, from the original
+Bun.serve({ fetch: App.outputs.Api.build().fetch });
 ```
 
-It checks the set as a whole when declared: one object under two names (`DuplicateApplicationDeclaration`), an entity or record held at any depth (fields, lists, optionals, nested blueprints) that is not registered (`UnregisteredApplicationReference`), and a repository whose entity, `relations` or `environmentDependencies` are not (`UnregisteredRepositoryDependency`). A declaration of the wrong kind throws `InvalidApplicationDeclaration`.
+`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).
 
-`extends: [Auth]`, or `Blog.extend(Billing)`, which returns a new application, inherits declarations; the extended ones stay usable alone and are never changed. The same object under the same name is registered once; one name for different objects, or one object under two names, throws `ApplicationConflict` naming both origins. References may cross applications (a `Post` of `Blog` holding the `User` of `Auth`), and validation runs on the resolved set.
+## What you get
 
-Repositories are module-level and may be shared, so an application does not change them: `app.repositories.Users` shares the declaration of `Users` but reads and writes through the `provider` of the application (or of the last application it extends that has one), unless `Users` declared its own. Two applications with different providers do not share data. Without a `provider`, `app.repositories.Users` is `Users` itself, and records, entities and repositories work the same outside any application.
+Each concept has a page in [docs/](docs/README.md), in the order they build on one another:
 
-`app.describe()` gives a JSON-serializable graph, with the `from` of each declaration (the application that registered it): properties (name, flags, JSON Schema and `lineage`), blueprints, records and entities (fields, `options`, plugin descriptors), environments, and repositories (entity, actions, `relations` and `environments` by name). A field is a reference by name (`{ kind: "entity", ref: "User" }`) when it holds a registered declaration. A property's `lineage` comes from `propertyLineageOf(Property)`: `Integer.with({ min: 0 })` is `{ kind: "refined", base, options }`, `optionalOf` is `{ kind: "optional", base }` and `enumOf` is `{ kind: "factory", factory: "enumOf", args: { values } }`. A root property (declared with `propertyOf`) has no lineage and is identified by its `name`; one with custom handlers is described with what is known (name and schema), never an error.
+- [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.
+- [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).
 
-### Exceptions
+## Standard Schema
 
-Every error the library raises is an `Exception` that knows its `layer` (`ExceptionLayers`: `Schema`, `Property`, `Blueprint`, `Record`, `Entity`, `UseCase`, `Repository`, `Environment`, `Event`, `Command`, `Output`), its `name` and its `source` (who raised it). Passing it up keeps the whole `trace`:
+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`.
 
-```ts
-import {
-	ExceptionLayers,
-	exceptionOf,
-	guard,
-	InvalidPropertyValue,
-} from "@afora/core";
-
-const UserNotCreated = exceptionOf({
-	layer: ExceptionLayers.UseCase,
-	name: "UserNotCreated",
-	message: "Could not create the user.",
-});
+## Packages
 
-guard(
-	{ layer: ExceptionLayers.UseCase, source: "CreateUser" },
-	() => new Name(input).value,
-	(exception, pass) => {
-		if (exception.is(InvalidPropertyValue)) return "Jane"; // resolve it here
-		return pass(); // or send it up, with this layer added to the trace
-	},
-);
+`@afora/codegen` generates afora code from an `afora.json` (and extracts the `afora.json` of an `Application` back), and `@afora/mcp` is an MCP server that lets an agent build a domain with it: see [packages/codegen](packages/codegen/README.md) and [packages/mcp](packages/mcp/README.md). `@afora/hono` is a `hono` sink for outputs: it serves the operations as a Hono app, with problem+json errors, masked responses and an optional OpenAPI document ([packages/hono](packages/hono/README.md)). `@afora/drizzle` is a repository provider on Drizzle ORM (SQLite and Postgres) that passes the provider contract kit: see [packages/drizzle](packages/drizzle/README.md).
 
-// or wrap it in an exception of your own
-throw new UserNotCreated({ source: "CreateUser", cause: exception });
-```
+## Example
 
-`exception.trace` lists each step from the origin, `exception.origin` is the first one raised, and `toJSON()`/`toString()` print all of it.
+`examples/blog` is a blog (users with the `authenticatable` plugin, posts with soft deletion, use cases written as steps, 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()`), a password hashing function 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`.
 
 ## Performance
 
@@ -851,18 +333,21 @@ A rough guide, not a verdict. "Partial" means it is possible but not what the li
 
 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.
 
-## Packages
+## Contributing
 
-`@afora/codegen` generates afora code from an `afora.json` (and extracts the `afora.json` of an `Application` back), and `@afora/mcp` is an MCP server that lets an agent build a domain with it: see [packages/codegen](packages/codegen/README.md) and [packages/mcp](packages/mcp/README.md).
+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. Pushing a `v*` tag that matches `package.json` publishes to npm with provenance.
 
-## Scripts
+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 smoke         # build, then run the package on plain Node
 bun run bench         # benchmark against TypeBox, Zod, Valibot and ArkType
 bun run lint          # biome lint
@@ -871,12 +356,14 @@ 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 build:packages # build the core, then packages/codegen and packages/mcp
+bun run test:hono     # tests of packages/hono
+bun run test:drizzle  # tests of packages/drizzle (SQLite and PGlite)
+bun run build:packages # build the core, then packages/codegen, packages/mcp, packages/hono and packages/drizzle
 ```
 
-## Contributing
+## Versioning
 
-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. Pushing a `v*` tag that matches `package.json` publishes to npm with provenance.
+What is stable, what may break and how deprecations work is in [VERSIONING.md](VERSIONING.md).
 
 ## License