hexok 2.0.0 → 2.1.0

package/README.md

@@ -6,4 +6,13 @@ Import them from `hexok`. There is no HTTP layer and no composition root in this
 
 `UseCase.context<Ctx, Spec>()` is a family factory for a per-call context, optional guards, optional hooks, and required statics. The optional argument is a settings object with no keys yet. Pass nothing. `{}` is allowed. `guard` and `hooks` are methods, not fields of that object. A missing `<Ctx>` type argument is a type error. `Spec` defaults to no required statics. `.guard(fn)` and `.hooks(def)` each return the same factory. Order does not matter. Either may be omitted. Another `.guard()` runs after guards already registered. A second `.hooks()` throws `hexok: UseCase hooks are already set` when the factory is created, if the first registration had at least one callback. An empty `.hooks({})` does not register hooks and does not wrap `execute`. The call is `{ ctx, spec, token, input }`. `input` is the argument passed to `execute`. The method receives that same value. Hexok does not validate it. `UseCase.GuardParameters<typeof Factory>` is that call. `UseCase.Ctx<typeof Factory>` is that `ctx`. Pass the factory. `.hooks` infers the value returned from `preExecute` as the `state` argument of `postExecute`, `onCatch`, and `onFinally`. If `preExecute` is omitted, that state is `void`. `postExecute` also receives `result`. `onFinally` receives `status: 'success'` with `result`, or `status: 'failure'` with `error`. The pipeline is guard (outside try), `preExecute`, the method, `postExecute`, `onCatch` then rethrow, `onFinally`. A guard throw does not enter the hooks. A throw inside `onCatch` replaces the error after `onFinally` sees the original one. `UseCase(token)` still has `execute(input)`.
 
+## Agent skill
+
+This package's repository includes an agent skill named `hexok`. It walks a feature from the user story through entities, use cases, events, adapters, the gateway, and where handlers run. Install it from GitHub. `npx skills update` refreshes that install from GitHub.
+
+```bash
+npx skills add crobinson42/hexok
+npx skills update
+```
+
 The root [README](../../README.md) shows the shape. Tokens and schemas are arguments of each primitive, so they cannot be forgotten. `execute`, `handle`, and port methods are abstract, so a missing method is a compiler error on the class. `start`, `stop`, `parse`, and `set` are concrete methods you can override.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hexok",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "TypeScript primitives for hexagonal software: Schema, Entity, UseCase, Port, Adapter, Mapper, Event, EventCatalog, EventHandler, and Errors.",
   "type": "module",
   "license": "MIT",
@@ -35,7 +35,8 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "tsc -b",

package/skills/hexok/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: hexok
+description: >
+  Build application features with the hexok primitives. Use when the task adds
+  or changes a user story, entity, schema, use case, port, adapter, event,
+  event handler, gateway, or background worker in a project that depends on
+  hexok. Follow its thought, research, and plan steps, and read the primitive
+  reference it names before writing that primitive.
+license: MIT
+metadata:
+  short-description: Build features with hexok
+---
+
+# Hexok
+
+Import primitives from `hexok`. The application owns HTTP, RPC, websockets, gRPC, the object graph, brokers, ack, retry, and consumer groups.
+
+The running shape is a person who creates a blog post and publishes it. Subscribers are emailed afterward. Use the application's real story. The blog is only the shape.
+
+## Concepts
+
+Read the reference before writing that concept. Each file is the supporting documentation for one primitive.
+
+| Concept | Reference | Place |
+| --- | --- | --- |
+| Schema | [references/schema.md](references/schema.md) | Domain. The shape of stored data and event payloads. |
+| Entity | [references/entity.md](references/entity.md) | Domain. One stored thing and its rules. |
+| Error | [references/error.md](references/error.md) | Domain. Named refusals, the error map, and `CodedError` `VALIDATION`. |
+| Event | [references/event.md](references/event.md) | Domain. A fact the use case records. |
+| EventCatalog | [references/event-catalog.md](references/event-catalog.md) | Domain. The set of events, and the conversion to a wire message. |
+| UseCase | [references/use-case.md](references/use-case.md) | Application. One caller action. `UseCase.context` is in that file. |
+| Port | [references/port.md](references/port.md) | Application. The contract a use case or handler calls. |
+| EventHandler | [references/event-handler.md](references/event-handler.md) | Application. Work that follows one event. |
+| Adapter | [references/adapter.md](references/adapter.md) | Interface adapter. The current implementation of one port. |
+| Mapper | [references/mapper.md](references/mapper.md) | Interface adapter. Read it when the stored document is not the domain props. |
+
+Dependencies point inward. Domain code does not import a database client, a queue, an HTTP library, or a mail SDK. Use cases and handlers depend on ports. Adapters implement ports. A gateway calls use cases.
+
+## How to build a feature
+
+Walk the steps below three times, in this order, before you edit files.
+
+1. **Thought.** State one user story: who acts, and what they can do. Example: as a user I can create a blog post and publish it. Name the actions a caller can invoke on their own. Creating a draft and publishing it are two use cases when both are reachable. One use case is enough when the caller can only publish.
+2. **Research.** Search the codebase for that story. Note the entity, schema, error catalog, use case, ports, events, handlers, adapters, gateway route, and worker entry that already exist.
+3. **Plan.** Write a short plan in the step order below. Mark each item `exists` or `add`. A step with nothing to add is `none`. Then implement in that same order.
+
+When the task is only a plan, stop after the plan. When the task is to build the feature, implement the plan after it is written. Read the matching reference at the start of each step you implement.
+
+### 1. User story
+
+Write the story in one sentence. That sentence is the feature. Later files, tokens, and routes should be recognizable as parts of it.
+
+### 2. Entities and schemas
+
+Identify what the story persists. Define the schema, then the entity, when they are not already there.
+
+A blog post is an id, a title, a body, and whether it is published. The schema is that shape. The entity holds the rules, such as refusing a blank title or a second publish. Read [references/schema.md](references/schema.md) and [references/entity.md](references/entity.md). Add catalog members used by those rules while you are here. Read [references/error.md](references/error.md).
+
+### 3. Use cases and ports
+
+Define each use case as one action, and the ports that action calls, when they are not already there.
+
+Saving a post is a port. Publishing an event is a different port. The use case receives both in its constructor and calls them from `execute`. It does not import a driver. Read [references/use-case.md](references/use-case.md) and [references/port.md](references/port.md).
+
+Use `UseCase(token)` when `execute` only needs the input. Use `UseCase.context<Ctx>()` when every call in the family carries the same extra facts, such as a trace id, the actor, or the caller IP. Share one family across the gateway's use cases.
+
+### 3.b. Side effects
+
+Identify work that is a consequence of the story and is outside the use case's job. Emailing subscribers after a post is published is that kind of work. Indexing and heavy computation are too.
+
+When that work exists and the event does not, define the event and register it on a catalog. Give the use case an event-publisher port and publish the event instance at the end of `execute`, after the entity rule has run and the save has succeeded. Read [references/event.md](references/event.md) and [references/event-catalog.md](references/event-catalog.md).
+
+When the story has no consequence beyond its own write, this step is `none`. Do not add an event so the step looks complete.
+
+### 3.c. Event handlers
+
+When step 3.b named a side effect, implement the handler if it does not exist. The handler takes its own ports in the constructor. `handle` receives the event. Emailing subscribers loads addresses through a subscriber port and sends mail through a mail port. Read [references/event-handler.md](references/event-handler.md).
+
+The handler does not subscribe itself. Subscription belongs to the adapter in step 4.
+
+### 4. Adapters
+
+List every port a use case or handler calls, including repositories, the event publisher, the event subscription, and outbound ports such as email. Implement each missing port as an adapter.
+
+An adapter is the concrete port: memory while sketching, a database in the API, a fake in a test, a broker when a worker runs elsewhere. Swapping it changes the composition root. `execute` stays put. Read [references/adapter.md](references/adapter.md).
+
+Read [references/mapper.md](references/mapper.md) when the stored document is a different shape from the domain props. Persisting `toProps()` as JSON needs no mapper.
+
+The publisher adapter accepts `EventInstance<typeof Catalog>`. It sends `Catalog.message(event)` when the transport stores bytes. The subscription adapter runs `Catalog.parse` and then `handle`. Ack, retry, prefetch, and consumer groups stay on that adapter.
+
+### 5. Gateway
+
+Identify how a caller outside the process reaches the use case. The common surface is HTTP in an RPC shape: one path per use case, such as `POST /posts` and `POST /posts/:id/publish`. REST, websockets, and gRPC are the same kind of edge when the story needs them.
+
+Use the HTTP library the application already depends on. Express, Hono, and Koa are all suitable. Add one only when the application has none.
+
+The route builds the call context, calls `execute`, and maps failures to the reply. A missing entity is a 404. `CodedError` code `VALIDATION` is a 400 and `data.issues` names the fields. A catalog conflict, such as an already published post, is a 409. The catalog does not contain status codes.
+
+Construct adapters, call `start`, and construct use cases in the entry point. A use case instance is long-lived. Context is an argument to `execute`, not a field set per request.
+
+### 6. Where handlers run
+
+Skip this step when there is no handler.
+
+Decide whether each handler shares the API process. Share it when the work is small, or when no adapter can publish in one process and subscribe in another.
+
+Add a background-worker entry point when the handler does heavy work and a distributed publish/subscribe adapter exists. The API entry publishes. The worker entry starts the subscription adapter, registers the handlers, and runs them. The two processes use the same catalog. The worker parses the wire message, then calls `handle`.
+
+Do not add a broker only to create a second process. Do not move the handler's work back into `execute`.
+
+## Conventions
+
+- Tokens are factory arguments: `Entity('Post', PostSchema)`, `UseCase('post.publish')`, `Port('PostRepository')`, `Event('post.published', PostSchema)`, `EventCatalog('blog', { postPublished })`, `EventHandler('email.subscribers', PostPublished)`, `Errors('blog', { ... })`. A subclass does not redeclare the token.
+- `execute`, `handle`, port methods, and a mapper's `fromSource` and `toSource` are methods on the class. The compiler reports a missing one. `start`, `stop`, `parse`, and `set` already exist and may be overridden.
+- A use case throws a catalog member when the story refuses. Schema checks throw `CodedError` with code `VALIDATION`. Catch both at the gateway or the worker.
+- Call catalog factories without `new`: `BlogError.BlankTitle()`.
+- Check use-case input in a guard or in the first lines of `execute`. A schema stored on a `UseCase.context` static bag is application data. Hexok does not run it.
+- Annotate `execute` on the subclass. Callers see that annotation. On a context family, the parameters are `(ctx, input)` and `ctx` is `UseCase.Ctx<typeof Factory>`.
+- Publish `new PostPublished(payload)`. Compare events with `instanceof` or `event.token`. The catalog map key (`postPublished`) and the event token (`post.published`) are different strings.
+- After a successful driver write, the adapter calls `commit()` on the entity. The mapper does not commit.
+- Tests construct the use case with adapters of the same ports. A test of the story does not need a live broker.
+- Put one concept in one file. A practical layout is `schemas/`, `entities/`, `errors/`, `events/`, `ports/`, `use-cases/`, `handlers/`, `adapters/`, an HTTP entry, and a worker entry when step 6 splits a process.
+- Zod, Valibot, and ArkType are passed straight to the primitives. A TypeBox 1 schematic goes through `@hexok/typebox` (`typebox(schema)` or `typeboxDecode(schema)`) before it reaches `Schema`, `Entity`, or `Event`.
+
+## When a primitive changes
+
+A change to primitive behavior updates the matching file under `references/` in the same change. `npx skills update` refreshes installed copies from the GitHub repository.

package/skills/hexok/references/adapter.md

@@ -0,0 +1,66 @@
+# Adapter
+
+An adapter is a port with its methods filled in. Pass the port class to `Adapter` and implement every abstract method. `start` and `stop` are already there for connecting and disconnecting.
+
+```ts
+class InMemoryPosts extends Adapter(PostRepository) {
+  override async get(id: string): Promise<Post> {
+    /* … */
+  }
+  override async save(post: Post): Promise<void> {
+    /* … */
+  }
+}
+```
+
+## Why it exists
+
+The use case asks a `PostRepository` to save. Something has to actually keep the post: a `Map` while you sketch the feature, a database when the API runs, a fake in a test that records the calls. Those are adapters of one port. Swapping them changes the constructor arguments at the composition root, and `execute` stays put.
+
+`start` and `stop` give a connection a home that is still outside the use case. The process opens the database before it serves traffic, and closes it when it shuts down.
+
+## How to use it
+
+An in-memory repository is enough to walk the publish story. The API process can later substitute a database class that extends the same port. The composition root constructs the adapter, starts it, and hands it to `PublishPost`.
+
+```ts
+class InMemoryPosts extends Adapter(PostRepository) {
+  private readonly rows = new Map<string, ReturnType<Post['toProps']>>();
+
+  override async get(id: string): Promise<Post> {
+    const props = this.rows.get(id);
+    if (props === undefined) throw BlogError.PostMissing({ id });
+    return Post.restore(props);
+  }
+
+  override async save(post: Post): Promise<void> {
+    this.rows.set(post.props.id, post.toProps());
+    post.commit();
+  }
+}
+
+const posts = new InMemoryPosts();
+await posts.start();
+const publishPost = new PublishPost(posts, events);
+```
+
+Store `toProps()` (or a mapped document) and rebuild with `restore` on the way out. Call `commit()` after the write succeeds.
+
+The defaults of `start` and `stop` resolve immediately, so an in-memory adapter can leave them alone. A database adapter overrides `start` to connect and `stop` to disconnect. The application calls them. The use case calls `get` and `save`.
+
+A publisher adapter accepts the catalog instance and, on a real transport, sends `BlogEvents.message(event)`. A subscription adapter owns the consumer loop. It parses with `BlogEvents.parse`, then calls each subscribed handler. It does not hide handler errors. Ack, retry, prefetch, and consumer groups live here, and only when the broker has them.
+
+One adapter implements one port. A second port is a second class.
+
+## API
+
+`Adapter(PortClass)` returns an abstract class that extends that port. Implement the port's methods. The compiler reports a missing one on the class.
+
+| Member | Role |
+| --- | --- |
+| `token` | The port's token. An adapter keeps it and cannot replace it. |
+| Port methods | Implement each abstract method from the port. |
+| `start()` | Called by the application before the adapter is used. Override it to connect. The default resolves immediately. |
+| `stop()` | Called by the application when it is finished with the adapter. Override it to disconnect. The default resolves immediately. |
+
+`InMemoryPosts.token` is `PostRepository.token`.

package/skills/hexok/references/entity.md

@@ -0,0 +1,74 @@
+# Entity
+
+An entity is one thing the software stores and changes, such as a blog post. Pair a name with a schema, then add methods for the rules. Callers build an instance with `create`, `restore`, or `parse`, change it through those methods, and read the props back out when it is time to save.
+
+```ts
+class Post extends Entity('Post', PostSchema) {}
+```
+
+`schema` is a Standard Schema or a Schema class.
+
+## Why it exists
+
+A post has data and rules. The data is an id, a title, a body, and whether it is published. A rule says that publishing records `publishedAt`, and that a blank title is refused. The entity keeps both on one object.
+
+The schema runs when the post is created from typed props, when unknown input is parsed, and again when a method writes. A failed write restores the previous props. The instance remembers whether it is new and which fields changed, so a repository can save it without a second copy of those rules.
+
+## How to use it
+
+Publishing is a method on the entity. The use case loads the post, calls the method, and saves. The method refuses a blank title with a catalog error, then updates the draft.
+
+```ts
+class Post extends Entity('Post', PostSchema) {
+  publish(now: Date): this {
+    if (this.props.title.trim() === '') throw BlogError.BlankTitle();
+    if (this.props.published) throw BlogError.AlreadyPublished();
+    return this.set((draft) => {
+      draft.published = true;
+      draft.publishedAt = now;
+    });
+  }
+}
+
+const post = Post.create({
+  id: 'p1',
+  title: 'Hello',
+  body: 'First post',
+  published: false,
+});
+post.publish(new Date());
+await posts.save(post);
+```
+
+`create` checks the props and marks the post new. A repository loading a stored row uses `restore`, which keeps those props and treats the post as already saved. A request body is untyped, so the edge uses `parse`: the schema runs, and the post is treated as existing.
+
+Read `props` for the current data. Write only through `set` or a method that calls it. `toProps()` is the frozen snapshot you persist or return from a use case.
+
+The adapter calls `commit()` after the driver write succeeds. That is what clears `isNew` and the dirty set. The use case does not commit, and a mapper does not commit.
+
+## API
+
+`Entity(token, schema)` returns the class you extend. `token` is a string literal.
+
+| Member | Role |
+| --- | --- |
+| `Post.token` | The name you passed in. |
+| `Post.schema` | The Standard Schema used by `create`, `parse`, `set`, and `validate`. |
+| `Post.create(props)` | Check `props` and return a new instance. `isNew` stays true until `commit`. |
+| `Post.restore(props)` | Build an instance from stored props. The schema waits until `validate` or a writing `set`. `isNew` is false. |
+| `Post.parse(value)` | Check an unknown value, then build an instance the way `restore` does. `isNew` is false. |
+| `props` | The current data, typed read-only. Change it with `set`. |
+| `set(draft => …)` | Copy-on-write edit. A write runs the schema. A failed check restores the previous props and throws. |
+| `validate()` | Run the schema when this instance has not already passed. A passed instance returns itself. |
+| `commit()` | Treat the current props as the saved original. `isNew` becomes false. |
+| `isNew` | True after `create`, until `commit`. |
+| `isValidated` | True after `create`, `parse`, a writing `set`, or `validate`. False after `restore` until one of those runs. |
+| `original` | Props from before the first change on a restored instance. `undefined` while the instance is clean, and while a created instance has not been committed. |
+| `isDirty()` | True when the post is new, or a shallow field differs from the saved original. |
+| `getChangedKeys()` | Shallow keys that differ. `{ deep: true }` returns dotted paths. |
+| `toProps()` | A deep-frozen snapshot for saving or returning. Reused until the next `set`. |
+| `toJSON()` | The same snapshot as `toProps()`. |
+
+A schema failure throws `CodedError` with code `VALIDATION` and the message `hexok: Post validation failed`. A domain rule throws a member of the error catalog.
+
+`DeepReadonly<T>` is the type of `props`, `original`, and `toProps()`. `Date` values stay `Date`. `EntityInstance` is the props-only instance type.

package/skills/hexok/references/error.md

@@ -0,0 +1,140 @@
+# Error
+
+An error catalog is the named set of refusals the application throws. Define it with `Errors`, giving the catalog a name and one entry per code. Call sites throw a member. The edge catches the catalog and decides what a caller sees.
+
+```ts
+class BlogError extends Errors('blog', {
+  BlankTitle: { message: 'Title is blank' },
+  AlreadyPublished: { message: 'Post is already published' },
+}) {}
+```
+
+The shape of each entry is an error map. A failed schema check is a different failure: `CodedError` with code `VALIDATION`.
+
+## Why it exists
+
+Publishing can refuse for reasons the caller can act on. The title is blank. The post is already published. The trace id is missing. A catalog gives each refusal a stable code, a message, and, when the caller needs a value back, a payload such as the post id.
+
+The catalog stays a list of domain facts. Mapping `BlankTitle` to an HTTP status, an RPC code, or a queue retry lives in the gateway or the worker.
+
+## How to use it
+
+The entity throws. The use case lets the error travel. The gateway matches and chooses the reply.
+
+```ts
+class Post extends Entity('Post', PostSchema) {
+  publish(now: Date): this {
+    if (this.props.title.trim() === '') throw BlogError.BlankTitle();
+    if (this.props.published) throw BlogError.AlreadyPublished();
+    return this.set((draft) => {
+      draft.published = true;
+      draft.publishedAt = now;
+    });
+  }
+}
+
+try {
+  await publishPost.execute({ id });
+} catch (error) {
+  if (!BlogError.is(error)) throw error;
+  return BlogError.match(error, {
+    BlankTitle: () => reply(400, error.message),
+    AlreadyPublished: () => reply(409, error.message),
+  });
+}
+```
+
+Call the member. `BlogError.BlankTitle()` uses the catalog message. `BlogError.BlankTitle('Title cannot be empty')` replaces it for this throw. `new BlogError.BlankTitle()` throws `TypeError`, because the member is a factory.
+
+`UseCase`, `Entity`, `Port`, `Adapter`, `Schema`, `Mapper`, `Event`, `EventCatalog`, and `EventHandler` do not take an error map. There is no `error()` method on those classes.
+
+## Error map
+
+The object passed to `Errors` is the error map. Each key is a code. Each value is an `ErrorDef`: an optional `message`, and an optional `data` Standard Schema. `ErrorMap` and `ErrorDef` are exported because declaration emit names them.
+
+```ts
+class BlogError extends Errors('blog', {
+  BlankTitle: { message: 'Title is blank' },
+  TraceIdMissing: {},
+  PostMissing: {
+    message: 'Post was not found',
+    data: z.object({ id: z.string() }),
+  },
+}) {}
+
+throw BlogError.BlankTitle();
+throw BlogError.TraceIdMissing();
+throw BlogError.PostMissing({ id: 'p1' });
+throw BlogError.PostMissing('No post p1', { id: 'p1' });
+```
+
+`TraceIdMissing` omits `message`, so the factory's fallback text is the code, `'TraceIdMissing'`. `PostMissing` requires `{ id: string }` because that is the schema's output. The `data` schema types the argument. The factory stores the value it was given and does not validate it. Run the schema yourself before the throw when a bad payload should fail as a schema check.
+
+| Entry | Call |
+| --- | --- |
+| No `data` | `Code()` or `Code(message)`. |
+| `data` whose output is an object or number | `Code(data)` or `Code(message, data)`. |
+| `data` whose output is a string | One argument is the payload. The message is first only when the payload follows it: `Code(message, data)`. |
+
+Keys `is`, `match`, `prototype`, and `token` are reserved. Defining one of them throws `hexok: error code "<code>" is reserved`.
+
+## Catalog API
+
+`Errors(token, defs)` returns the class you extend. `token` is the catalog name.
+
+| Member | Role |
+| --- | --- |
+| `BlogError.token` | The catalog name. |
+| `BlogError.BlankTitle(...)` | Builds that member. You throw the return value. |
+| `BlogError.is(error)` | True when `error` is a member of this catalog. Narrows to the union of members. |
+| `BlogError.match(error, cases)` | Runs the handler for `error.code`. Every code in the catalog is required. A code that is missing at runtime throws `hexok: unmatched blog.<code>`. |
+| `error.catalog` | The catalog token. |
+| `error.code` | The member code, such as `'BlankTitle'`. |
+| `error.message` | The catalog message, or the override passed at the call. |
+| `error.data` | The payload, or `undefined` when the definition has no `data` schema. |
+| `error.name` | `` `${token}.${code}` ``, such as `'blog.BlankTitle'`. |
+
+The message on the returned error keeps the literal you passed, including a template literal. `is` and `match` type `message` as `string`, because one code can be thrown with the catalog text or an override.
+
+`instanceof BlogError` is the same catalog check as `is`. `is` is what narrows the union so `match` and `code` see each member.
+
+## Coded error
+
+A coded error is a failure identified by a `code` string, with a message and an optional payload. Schema checks throw one whose code is `VALIDATION`. Application refusals use the catalog.
+
+```ts
+new CodedError({
+  code: 'VALIDATION',
+  message: 'hexok: Post validation failed',
+  data: { issues },
+});
+```
+
+Checking a shape and refusing a story are different events. `Post.parse` can reject a body that has no title. `post.publish()` can reject a post that is already live. The gateway shows field errors from `data.issues` and matches catalog members on their own codes.
+
+```ts
+try {
+  const post = Post.parse(body);
+  await posts.save(post);
+} catch (error) {
+  if (error instanceof CodedError && error.code === 'VALIDATION') {
+    return reply(400, error.data);
+  }
+  throw error;
+}
+```
+
+The same error is thrown by `Schema.parse`, entity `create`, `parse`, a writing `set`, or `validate`, `Event.parse`, and `EventCatalog.parse` when the payload schema rejects the message. `Entity.restore` does not validate. The next writing `set`, or an explicit `validate()`, can throw.
+
+| Member | Role |
+| --- | --- |
+| `new CodedError({ code, message?, data? })` | `message` defaults to `code`. `data` is set only when the argument object has a `data` key. |
+| `error.code` | The code. Schema checks use `'VALIDATION'`. |
+| `error.message` | The message. Schema checks use `` `hexok: ${token} validation failed` ``. |
+| `error.data` | Optional payload. For a schema check it is `{ issues }` when the schema reported issues. |
+| `error.name` | `'CodedError'`. |
+| `validationError(message, issues?)` | Builds a `CodedError<'VALIDATION'>`. Passes `data: { issues }` when `issues` is present. |
+
+An issue is a Standard Schema issue: a `message` and an optional `path`. An async schema throws a plain `Error` with the message `hexok: async schemas belong at the application edge`.
+
+`ok`, `fail`, and `Result` are exported for application code that already returns a result. Entity methods, `execute`, and `handle` throw. They do not return `Result`.

package/skills/hexok/references/event-catalog.md

@@ -0,0 +1,57 @@
+# EventCatalog
+
+An event catalog is the set of events one publisher and its subscribers share. Name the catalog and pass a map of event classes. The map key is the name in a serialized message. The event's own token stays the name on the class.
+
+```ts
+class BlogEvents extends EventCatalog('blog', {
+  postPublished: PostPublished,
+}) {}
+```
+
+## Why it exists
+
+A use case has a `PostPublished` object. A queue, a log, or another process needs something it can store: a key and a payload. The catalog is the agreement on which events exist, and the two conversions between those forms. `message` turns an instance into `{ key, payload }`. `parse` turns that message back into the event class, checking the payload with the event's schema.
+
+The map key and the event token are different strings on purpose. `postPublished` is the name in the catalog and on the wire message. `post.published` is the token on the class, the same string passed to `Event`.
+
+## How to use it
+
+The publisher port accepts any instance from the catalog. The adapter that talks to a transport calls `message` on the way out and `parse` on the way in. A handler then receives the event object.
+
+```ts
+abstract class BlogEventPublisher extends Port('BlogEventPublisher') {
+  abstract publish(event: EventInstance<typeof BlogEvents>): Promise<void>;
+}
+
+const message = BlogEvents.message(new PostPublished(post.toProps()));
+// { key: 'postPublished', payload: { id, title, body, published } }
+
+const event = BlogEvents.parse(message);
+await emailSubscribers.handle(event);
+```
+
+`publish` takes the instance union. A generic `publish<K>(key, payload)` does not keep the payload paired with the key inside the method. The use case publishes the instance. The adapter converts it.
+
+`BlogEvents.get('postPublished').token` is `'post.published'`.
+
+Narrow one entry when a function handles a single key: `EventInstance<typeof BlogEvents, 'postPublished'>` and `EventMessage<typeof BlogEvents, 'postPublished'>`.
+
+A port parameter typed as the catalog class does not check event key or payload, because a catalog instance has no fields. Use `typeof BlogEvents` when the type you need is the static side.
+
+## API
+
+`EventCatalog(token, events)` returns the class you extend. `token` is a string literal. `events` is a map of event classes. Duplicate event tokens throw `hexok: duplicate event "<token>" in catalog "<name>"` when the class is defined. The map is frozen on the catalog.
+
+| Member | Role |
+| --- | --- |
+| `BlogEvents.token` | The catalog name. |
+| `BlogEvents.events` | The map you passed in. |
+| `BlogEvents.get(name)` | The class registered under that map key. An unknown key throws `hexok: event "<name>" is not in catalog "blog"`. |
+| `BlogEvents.message(event)` | `{ key, payload }` for an instance of a class in this catalog. `key` is the map key. An event from elsewhere throws `hexok: event "<token>" is not in catalog "blog"`. |
+| `BlogEvents.parse(value)` | Checks a `{ key, payload }` message and returns the event instance. |
+
+`parse` throws `hexok: catalog "blog" expected { key, payload }` when `value` lacks a string `key` or a `payload`. An unknown key throws `hexok: event "<key>" is not in catalog "blog"`. A payload the event schema rejects throws `CodedError` `VALIDATION` from that event's `parse`.
+
+`EventInstance<typeof BlogEvents>` is the union of event instances in the catalog. Each instance carries its token. `EventMessage<typeof BlogEvents>` is the matching `{ key, payload }` union. The second type argument keeps one entry. `key` on a message is the map key. The event token is `BlogEvents.get(message.key).token`, and `event.token` on the instance.
+
+Narrow a handler or a switch with `event.token` or `instanceof`. Indexing a handler map by `event.token` does not narrow the payload. A `never` default on the whole event reports an unhandled catalog entry.

package/skills/hexok/references/event-handler.md

@@ -0,0 +1,56 @@
+# EventHandler
+
+An event handler is the work that follows one event. Name the handler and pass the event class. `handle` receives an instance of that event. Ports, such as a mail sender, arrive through the constructor.
+
+```ts
+class EmailSubscribers extends EventHandler('email.subscribers', PostPublished) {}
+```
+
+The application subscribes the handler. An in-process dispatcher or a queue worker calls `handle` once it has the event. The handler does not subscribe itself.
+
+## Why it exists
+
+The use case that publishes a post is finished once the post is saved and the event is published. Emailing every subscriber can be slow, and it can run in another process. The handler is that second story. It stays tied to one event class, so `event.payload` is the published post and the compiler notices a handler pointed at a different event.
+
+## How to use it
+
+`EmailSubscribers` loads the subscriber list and sends one mail per address. The published post is `event.payload`.
+
+```ts
+class EmailSubscribers extends EventHandler('email.subscribers', PostPublished) {
+  constructor(
+    private readonly subscribers: SubscriberDirectory,
+    private readonly mail: MailSender,
+  ) {
+    super();
+  }
+
+  async handle(event: PostPublished): Promise<void> {
+    const addresses = await this.subscribers.list();
+    for (const address of addresses) {
+      await this.mail.send(address, event.payload.title);
+    }
+  }
+}
+```
+
+Annotate `event` with `PostPublished`. An unannotated `handle(event)` is implicit `any`. Keep `handle` a method.
+
+A process that shares the API's memory can pass the instance straight to `handle`. A worker in another process reads a catalog message, runs `BlogEvents.parse`, and then calls `handle` with the result. Subscription, ack, and retry belong to that adapter.
+
+One handler is bound to one event class. A second event is a second handler.
+
+A static field such as `groupId` is yours to read when you subscribe the handler. Hexok does not read it. Same group string is one competing consumer set only for a real broker. Different groups each receive the event. An in-memory adapter may ignore the group.
+
+## API
+
+`EventHandler(token, event)` returns the class you extend. `token` is a string literal, the handler's name. `event` is an event class.
+
+| Member | Role |
+| --- | --- |
+| `EmailSubscribers.token` | The name you passed in. |
+| `EmailSubscribers.event` | The event class this handler receives. |
+| `handle(event)` | Required. Annotate `event` with that class. Return `void` or `Promise<void>`. |
+| `constructor` | Receive ports here and call `super()`. |
+
+The compiler reports a missing `handle`. The factory records the token and the event class. It takes no consumer-group argument.

package/skills/hexok/references/event.md

@@ -0,0 +1,53 @@
+# Event
+
+An event is a fact the application records, such as "this post was published." Name it and give it the schema of its payload. `new` stores a payload you already typed. `parse` checks an unknown value and then constructs the event.
+
+```ts
+class PostPublished extends Event('post.published', PostSchema) {}
+```
+
+Register the class on an event catalog when a publisher and a subscriber need to agree on the set. An event handler performs the work that follows from one event.
+
+## Why it exists
+
+Publishing a post saves the post. Emailing subscribers is a consequence, and it is a different story: it can fail, retry, and run in another process without changing whether the post is published. The event is the fact the use case records. The handler is where the email happens. The payload schema keeps that fact the same shape on both sides.
+
+## How to use it
+
+The use case constructs the event from the post it just saved and hands it to a publisher port. The handler later reads `event.payload`.
+
+```ts
+class PostPublished extends Event('post.published', PostSchema) {}
+
+await events.publish(
+  new PostPublished({
+    id: post.props.id,
+    title: post.props.title,
+    body: post.props.body,
+    published: true,
+  }),
+);
+```
+
+`new PostPublished(...)` trusts that object. When the payload arrives as unknown JSON, the boundary uses `PostPublished.parse(value)`, or the catalog's `parse` for a `{ key, payload }` message.
+
+The string `'post.published'` is the event's token. A catalog map key, such as `postPublished`, is a separate name.
+
+## API
+
+`Event(token, schema)` returns the class. `token` is a string literal. `schema` is a Standard Schema or a Schema class. A Schema class is stored as its definition.
+
+| Member | Role |
+| --- | --- |
+| `PostPublished.token` | The name you passed in. |
+| `PostPublished.schema` | The payload schema. |
+| `new PostPublished(payload)` | Stores `payload`. The constructor expects the schema's output type. |
+| `PostPublished.parse(value)` | Checks `value` and returns an instance of the class you called it on. |
+| `event.token` | The same literal as the static token. |
+| `event.payload` | The payload. |
+
+A rejected `parse` throws `CodedError` with code `VALIDATION` and the message `hexok: post.published validation failed`.
+
+Override `parse` when the boundary needs to preprocess the value. `parse` uses the class it was called on, so a catalog `parse` still returns the registered subclass and `instanceof` holds.
+
+Callers tell two event classes apart with `instanceof` or by comparing `event.token`. Two classes that share a schema stay assignable to each other until the instance token separates them. Prefer the catalog's `EventInstance` union on a publisher port so the port accepts every event in the set.

package/skills/hexok/references/mapper.md

@@ -0,0 +1,77 @@
+# Mapper
+
+A mapper translates the value a port speaks into the document an adapter stores, and back. Use one when those shapes differ: `_id` instead of `id`, a GeoJSON point instead of a `[lat, lng]` pair, a driver row instead of entity props. Persisting `toProps()` as JSON needs no mapper.
+
+The mapper is stateless. Domain code does not import the stored schema. The adapter owns the mapper and calls it. The adapter commits the entity after the driver write succeeds. The mapper does not commit.
+
+```ts
+class MongoUser extends Mapper('mongo.User', User, mongoUserSchema) {
+  protected fromSource(user: User) {
+    const props = user.toProps();
+    const [lat, lng] = props.location;
+    return {
+      _id: props.id,
+      name: props.name,
+      location: { type: 'Point' as const, coordinates: [lng, lat] },
+    };
+  }
+
+  protected toSource(doc: { _id: string; name: string; location: { coordinates: [number, number] } }) {
+    const [lng, lat] = doc.location.coordinates;
+    return { id: doc._id, name: doc.name, location: [lat, lng] };
+  }
+}
+```
+
+Extend `Mapper(...)`, not `MapperClass`. Export a named class. An anonymous class expression cannot emit the protected methods.
+
+## Why it exists
+
+The domain port stays in domain types. Each adapter has its own stored shape. One mapper keeps that translation next to the adapter, so `execute` still calls `posts.save(post)` and never sees `_id` or coordinate order.
+
+## How to use it
+
+`fromSource` feeds `toModel`. `toSource` feeds `fromModel`. The adapter calls the public pair.
+
+```ts
+class MongoUsers extends Adapter(UserRepository) {
+  constructor(private readonly users: MongoUser) {
+    super();
+  }
+
+  override async save(user: User): Promise<void> {
+    const doc = this.users.toModel(user);
+    await this.collection.updateOne({ _id: doc._id }, { $set: doc }, { upsert: true });
+    user.commit();
+  }
+
+  override async get(id: string): Promise<User | null> {
+    const doc = await this.collection.findOne({ _id: id });
+    if (doc === null) return null;
+    return this.users.fromModel(doc);
+  }
+}
+```
+
+The source argument is an Entity class, a Schema class, or a raw Standard Schema. The same primitive covers a schema or a plain object, not only an entity.
+
+Checks are off unless the factory or that call passes `{ validate: true }`. A call overrides the factory.
+
+- Off: `toModel` returns the `fromSource` draft unchecked. `fromModel` uses `Entity.restore` or returns a schema draft as given, so `isValidated` stays false.
+- On: both directions run the stored schema. An entity load uses `parse`. A stored-schema failure throws `CodedError` `VALIDATION` with the mapper token. An entity parse failure uses the entity token.
+
+## API
+
+`Mapper(token, source, storedSchema, options?)` returns the class you extend. `token` is a string literal. `options` is `{ validate?: boolean }`.
+
+| Member | Role |
+| --- | --- |
+| `fromSource(source)` | Protected. Required. Entity source receives the instance. A schema source receives its output. Return the stored draft. |
+| `toSource(model)` | Protected. Required. Receives the stored output. Return entity props, or the source schema's output. |
+| `toModel(source, options?)` | Public. Adapters call this. Do not override. |
+| `fromModel(value, options?)` | Public. Adapters call this. Do not override. |
+| `token` | The name passed to `Mapper`. |
+| `schema` | The stored Standard Schema. A Schema class is stored as its definition. |
+| `source` | The entity, Schema class, or Standard Schema this mapper reads and builds. |
+
+`MapperClass` is exported so an exported subclass's `.d.ts` can name the base and keep `fromSource` and `toSource` protected. A protected constructor on the subclass makes `new Subclass()` a type error. Leave the constructor public.

package/skills/hexok/references/port.md

@@ -0,0 +1,58 @@
+# Port
+
+A port is the contract a use case or an event handler calls. Name it with `Port` and declare the methods the caller needs. An adapter is the class that implements those methods.
+
+```ts
+abstract class PostRepository extends Port('PostRepository') {
+  abstract get(id: string): Promise<Post>;
+  abstract save(post: Post): Promise<void>;
+}
+```
+
+## Why it exists
+
+Publishing a post has to save the post and announce the fact. Those are two different jobs, and each can be done more than one way: memory in a test, a database in the API, a broker when a worker lives in another process. The use case names the jobs. The port is the name. The adapter is the current way the job is done, and it can be replaced without editing `execute`.
+
+## How to use it
+
+`PublishPost` asks a `PostRepository` for the post and asks a `BlogEventPublisher` to take the published-post event. It never imports a database client or a queue.
+
+```ts
+abstract class BlogEventPublisher extends Port('BlogEventPublisher') {
+  abstract publish(event: EventInstance<typeof BlogEvents>): Promise<void>;
+}
+
+class PublishPost extends UseCase('post.publish') {
+  constructor(
+    private readonly posts: PostRepository,
+    private readonly events: BlogEventPublisher,
+  ) {
+    super();
+  }
+
+  async execute(input: { id: string }): Promise<{ id: string }> {
+    const post = await this.posts.get(input.id);
+    post.publish(new Date());
+    await this.posts.save(post);
+    await this.events.publish(new PostPublished(post.toProps()));
+    return { id: post.props.id };
+  }
+}
+```
+
+The methods are whatever this seam needs. A repository offers `get` and `save`. A publisher offers `publish`. A mail port offers `send`. A subscription port offers `subscribe`. Keep publishing and subscribing as two ports. `start` and `stop` stay on the adapter. The use case depends on the port class, and the composition root passes an adapter.
+
+Search for an existing port before adding one. A second seam is a second `Port(...)` call, even when the method names match.
+
+## API
+
+`Port(token)` returns an abstract class. `token` is a string literal.
+
+| Member | Role |
+| --- | --- |
+| `PostRepository.token` | The name you passed in. |
+| Methods you declare | The contract. Mark them `abstract`. A subclass that leaves one unimplemented is a compile error. |
+
+Each `Port(...)` call is its own class, with its own nominal identity. A class with the same method names is a different type. Extend one port. One class cannot extend two ports.
+
+The adapter reuses this token. `InMemoryPosts.token` is `'PostRepository'` when `InMemoryPosts` extends `Adapter(PostRepository)`. An adapter cannot redeclare a different literal.

package/skills/hexok/references/schema.md

@@ -0,0 +1,47 @@
+# Schema
+
+A schema names a shape and checks values against it. Pass the name and a [Standard Schema](https://standardschema.dev) to `Schema`. `parse` returns the schema output, or throws when the value does not fit.
+
+```ts
+class PostSchema extends Schema('Post', postSchema) {}
+```
+
+Zod, Valibot, ArkType, and any other Standard Schema library are passed straight through. `@hexok/typebox` adapts a TypeBox 1 schematic first: `typebox(schema)` infers `Static`, and `typeboxDecode(schema)` infers `StaticDecode` and decodes. Decode is a second function. Entity and event construction use the non-decoding wrapper.
+
+## Why it exists
+
+A post is an id, a title, a body, and a published flag. That shape shows up on the entity, on the event that says the post was published, and at the edge where a request body arrives. One named schema is the definition those sites share. The name is what appears in the failure message, so a rejected post is distinguishable from a rejected subscriber.
+
+## How to use it
+
+Define the post once. The entity and the published-post event both take `PostSchema`. At a trust boundary, `parse` turns unknown JSON into the typed output.
+
+```ts
+const post = PostSchema.parse({
+  id: 'p1',
+  title: 'Hello',
+  body: 'First post',
+  published: false,
+});
+```
+
+`post.title` is a string because the schema says so. A missing title throws a coded error whose code is `VALIDATION` and whose message is `hexok: Post validation failed`.
+
+An entity or an event can take the Standard Schema directly, without this class. Use `Schema` when you want the name, `parse`, and a place to customize the check.
+
+## API
+
+`Schema(token, definition)` returns the class you extend. `token` is a string literal. `definition` is a Standard Schema.
+
+| Member | Role |
+| --- | --- |
+| `PostSchema.token` | The name you passed in. |
+| `PostSchema.definition` | The Standard Schema this class wraps. |
+| `PostSchema.parse(value)` | Check `value` and return the schema output. |
+| `PostSchema.check(value)` | The same check. Overrides of `parse` call this when they want the default result. |
+
+A rejected value throws `CodedError` with code `VALIDATION`. `data.issues` is the Standard Schema issue list when the schema reported one. Each issue has a `message` and an optional `path`.
+
+Override `parse` to preprocess or postprocess. Override `check` when the check itself should change.
+
+`InferSchema<S>` is the output type of a Schema class or a raw Standard Schema. `SchemaSource` is that input. Both are exported from `hexok`. An async schema throws `Error` with the message `hexok: async schemas belong at the application edge`.

package/skills/hexok/references/use-case.md

@@ -0,0 +1,164 @@
+# UseCase
+
+A use case is one thing a caller can do: publish a post, save a draft, subscribe an email address. Name it with `UseCase` and write the story in `execute`. The ports it needs arrive through the constructor.
+
+```ts
+class PublishPost extends UseCase('post.publish') {}
+```
+
+When every call in a family carries the same extra context, such as a trace id or the caller IP, use `UseCase.context` below. Plain `UseCase(token)` has `execute(input)` and never wraps that method.
+
+## Why it exists
+
+Publishing a post is a story with a beginning and an end. Load the post, apply the publish rule, save it, and announce that it was published. The use case is that story in one place. Saving and announcing stay behind ports, so the story reads the same when the database or the event transport changes. A refusal throws an error-catalog member. The application catches it at the edge.
+
+## How to use it
+
+`PublishPost` receives the repository and the event publisher. `execute` is the story. Callers see the input and return types you annotate.
+
+```ts
+class PublishPost extends UseCase('post.publish') {
+  constructor(
+    private readonly posts: PostRepository,
+    private readonly events: BlogEventPublisher,
+  ) {
+    super();
+  }
+
+  async execute(input: { id: string }): Promise<{ id: string }> {
+    const post = await this.posts.get(input.id);
+    post.publish(new Date());
+    await this.posts.save(post);
+    await this.events.publish(new PostPublished(post.toProps()));
+    return { id: post.props.id };
+  }
+}
+```
+
+The application constructs `PublishPost` with concrete adapters and calls `execute` from a gateway. One action is one class and one token. A caller who can save a draft and later publish it gets `SavePost` (`post.save`) and `PublishPost` (`post.publish`).
+
+Declare `execute` as a method. A class field, or an assignment after `super()`, is the wrong shape. The class is incomplete until `execute` exists, and the compiler reports the missing method.
+
+`execute` receives the input you declare and returns what you declare. Checking that input is the application's job: a guard on a context family, or the first lines of `execute`. Hexok does not validate `execute` and does not read a static key named `input`.
+
+## API
+
+`UseCase(token)` returns the class you extend. `token` is a string literal, such as `'post.publish'`.
+
+| Member | Role |
+| --- | --- |
+| `PublishPost.token` | The name you passed in. |
+| `execute(input)` | Required. Annotate the input and the return type on the subclass. |
+| `constructor` | Receive ports here and call `super()`. |
+
+A subclass of plain `UseCase(token)` takes one argument. Adding a context argument there is a type error. Reach for the family factory instead.
+
+## UseCase.context
+
+`UseCase.context` builds a family of use cases that share one kind of call. Every member receives a context argument. The family can refuse a call in a guard or observe it with hooks. Each member still has its own token, its own ports, and its own `execute`.
+
+Use it when the call carries something the story should see, such as a trace id or the actor who published the post. Putting that bag on `execute` as a first argument keeps it out of the post payload. The use case instance stays long-lived. The gateway builds a new context per request.
+
+```ts
+type ApiContext = { traceId: string };
+
+const ApiUseCase = UseCase.context<ApiContext>().guard((call) => {
+  if (call.ctx.traceId.length < 1) throw BlogError.TraceIdMissing();
+});
+
+class PublishPost extends ApiUseCase('post.publish') {
+  constructor(
+    private readonly posts: PostRepository,
+    private readonly events: BlogEventPublisher,
+  ) {
+    super();
+  }
+
+  async execute(
+    ctx: UseCase.Ctx<typeof ApiUseCase>,
+    input: { id: string },
+  ): Promise<{ id: string }> {
+    const post = await this.posts.get(input.id);
+    post.publish(new Date());
+    await this.posts.save(post);
+    await this.events.publish(new PostPublished(post.toProps()));
+    return { id: post.props.id };
+  }
+}
+
+await new PublishPost(posts, events).execute({ traceId: 'req-1' }, { id: 'p1' });
+```
+
+A member that needs a static contract, such as a permission string or an input schema the application will read, declares that contract as the second type argument. The schema is data the guard can read. Validating the input stays in the guard or in `execute`.
+
+```ts
+const ActorUseCase = UseCase.context<
+  { traceId: string; actorId: string },
+  { permission: string }
+>().guard((call) => {
+  if (call.spec.permission.length < 1) throw BlogError.Forbidden();
+});
+
+class PublishPost extends ActorUseCase('post.publish', {
+  permission: 'posts.publish',
+}) {
+  async execute(
+    ctx: UseCase.Ctx<typeof ActorUseCase>,
+    input: { id: string },
+  ): Promise<{ id: string }> {
+    return { id: input.id };
+  }
+}
+```
+
+### Factory
+
+`UseCase.context<Ctx, Spec>(config?)` returns a factory. `Ctx` is required. Omitting it makes the return type the string `'Pass a type argument: UseCase.context<Ctx>()'`. `Spec` defaults to an empty contract, so a member is `Factory(token)` only.
+
+`config` accepts no keys yet. Call `UseCase.context<Ctx>()` or `UseCase.context<Ctx>({})`. `guard` and `hooks` are methods on the factory, not fields of that object.
+
+`.guard(fn)` and `.hooks(def)` each return the factory again, so the calls can sit in either order and either one can be left off. A further `.guard()` runs after guards already registered. A second `.hooks()` that includes at least one callback throws `hexok: UseCase hooks are already set` when the factory is created. An empty `.hooks({})` adds no callbacks and does not wrap `execute`.
+
+When `Spec` has keys, the member is `Factory(token, statics)` and the bag has to satisfy `Spec`. Those entries are copied onto the class as statics. Literals stay narrow. The names `token`, `prototype`, `name`, and `length` stay on the class. Passing one of them is a type error.
+
+`execute` is still required. Annotate `ctx` and `input` on the subclass. A member with no input omits the second parameter. Declare `execute` as a method. Assigning it as a class field, or replacing it after `super()`, skips the guard and the hooks.
+
+When the family has no guard and no hooks, `execute` stays unwrapped so a missing method is still a class-site error.
+
+`UseCase.Ctx<typeof ApiUseCase>` is the context type. Pass the factory from `UseCase.context`. A subclass, and a plain `UseCase(token)` class, resolve to `never`. Annotate member `execute` parameters with it. A guard passed into the factory names `ctx` and `spec` from the application's own types. A function passed into the factory must not mention `UseCase.Ctx` or `UseCase.GuardParameters` of that still-inferred factory.
+
+### The call
+
+A guard and `preExecute` receive `{ ctx, spec, token, input }`.
+
+| Field | Meaning |
+| --- | --- |
+| `ctx` | The context the caller passed. |
+| `spec` | The static contract, typed as `Spec`. A guard sees `permission: string` even when one member passed the literal `'posts.publish'`. |
+| `token` | This member's token. |
+| `input` | The second argument the caller passed to `execute`. Typed `unknown`. The method receives that same value. |
+
+`UseCase.GuardParameters<typeof ApiUseCase>` is that call. `UseCase.Ctx<typeof ApiUseCase>` is `ctx`.
+
+Family hook `input` stays `unknown` on purpose. One factory hook is checked against every member. `SavePost` and `SubscribeToPosts` do not share an input type. Member annotations are what callers of that class see. Read `ctx` and `spec` in a family hook. Input-field logic belongs on `execute` or in a guard that already knows the member.
+
+### Guards
+
+A guard is `(call) => void | Promise<void>`. Guards run before `execute`, and outside the hook `try`. A throw from a guard skips `preExecute`, `postExecute`, `onCatch`, and `onFinally`. A zero-argument guard typechecks. A one-argument guard receives the call, not the bare context.
+
+### Hooks
+
+`.hooks(definition)` registers one set of callbacks for the family. `State` is inferred from `preExecute`'s return. It is `void` when `preExecute` is omitted. Later hooks receive `Awaited<State>`. `onCatch` and `onFinally` receive `Awaited<State> | undefined` because `preExecute` may have thrown or been omitted.
+
+| Hook | When it runs | Extra fields |
+| --- | --- | --- |
+| `preExecute(call)` | After the guards, before the method. | Its return value is `state` for the later hooks. |
+| `postExecute(call, state)` | After the method returns. | `call.result` is the method's return value. |
+| `onCatch(call, state)` | When `preExecute`, the method, or `postExecute` throws. | `call.error` is that error. The return value is ignored. The original error is thrown again. |
+| `onFinally(call, state)` | After a successful return or a caught failure. | `call.status` is `'success'` with `result`, or `'failure'` with `error`. |
+
+The pipeline is: guards, then `preExecute`, then the method with the caller's argument, then `postExecute`, then `onCatch` which rethrows, then `onFinally`. `postExecute` runs only after `preExecute` returns. `onFinally` always runs for attempts that entered the hooks. State is local to that invocation. Overlapping `execute` calls do not share it.
+
+The method receives the caller's input, and the caller receives the method's return value. Hooks do not replace either one. Record success in `postExecute` and the failure in `onCatch`. Finish a span in `onFinally`, which runs for both outcomes. A throw inside `onCatch` replaces the error after `onFinally` has seen the original one.
+
+There is no `around` hook. Leave `AsyncLocalStorage` to the application.