hexok 1.0.1 → 2.1.0

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`.