hexok 1.0.1 → 2.1.0

package/dist/use-case.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Application service. Pass ports through the constructor.
+ * `execute` is required; the compiler errors on the class when it is missing.
+ * Declare the input and output on `execute` — those are the types callers see.
+ * A refusal throws an {@link Errors} catalog member. The application catches it.
+ *
+ * ```ts
+ * class CreateUser extends UseCase('user.create') {
+ *   constructor(private readonly users: UserRepository) { super() }
+ *   async execute(input: { email: string }): Promise<{ id: string }> {
+ *     return { id: input.email }
+ *   }
+ * }
+ * ```
+ */
+export declare function UseCase<const Token extends string>(token: Token): (abstract new () => {
+    /** Nominal marker. Each `UseCase(...)` call is a distinct class. */
+    readonly "__#private@#brand": true;
+    /**
+     * Required. Annotate `input` and the return type on the subclass;
+     * callers of the subclass see those types.
+     */
+    execute(input: unknown): Promise<unknown>;
+}) & {
+    /** Use-case name. Literal type of the string passed to {@link UseCase}. */
+    readonly token: Token;
+};
+type ReservedKey = 'token' | 'prototype' | 'name' | 'length';
+/** A bag that uses a reserved class static fails on that property. */
+type ReservedOk<S> = {
+    [K in keyof S]: K extends ReservedKey ? never : S[K];
+};
+type NoStatics = Record<never, never>;
+/** Static bag minus names that would overwrite the class constructor. */
+type Statics<S> = Omit<S, ReservedKey>;
+/**
+ * Family of use cases that receive a caller context on `execute`.
+ * Returns a factory: a token, or a token and statics when `Spec` has keys.
+ * `execute` is required; annotate it on the subclass — callers see those types.
+ * A guard and hooks, when set, run around that method.
+ * Statics are application data copied onto the class. The application validates `input`.
+ * {@link UseCase.GuardParameters} reads the guard's call off the factory.
+ * {@link UseCase.Ctx} reads that call's context type.
+ * {@link context} returns that factory. {@link ContextFactory.guard} and
+ * {@link ContextFactory.hooks} return it again.
+ *
+ * ```ts
+ * const ApiUseCase = UseCase.context<
+ *   ApiContext,
+ *   { input: StandardSchemaV1; permission: string }
+ * >()
+ *   .guard((call) => {
+ *     if (call.ctx.sessionId.length < 1 || call.spec.permission.length < 1) {
+ *       throw new Error('unauthorized')
+ *     }
+ *   })
+ *   .hooks({
+ *     preExecute: () => ({ started: Date.now() }),
+ *     postExecute(_call, state) {
+ *       void state.started
+ *     },
+ *   })
+ *
+ * class FindUsers extends ApiUseCase('user.find', {
+ *   input: z.object({ query: z.string() }),
+ *   permission: 'users.read',
+ * }) {
+ *   constructor(private readonly users: UserRepository) { super() }
+ *   async execute(
+ *     ctx: UseCase.Ctx<typeof ApiUseCase>,
+ *     input: { query: string },
+ *   ): Promise<User[]> {
+ *     return this.users.search(input.query)
+ *   }
+ * }
+ * ```
+ */
+export declare namespace UseCase {
+    /**
+     * Call passed to a {@link context} guard.
+     * `ctx` is the per-call context. `spec` is the static contract.
+     * `token` is the use-case name. `input` is the argument passed to `execute`.
+     *
+     * ```ts
+     * type Call = UseCase.GuardParameters<typeof ApiUseCase>
+     * ```
+     */
+    type GuardParameters<Factory> = Factory extends GuardParametersSlot<infer Ctx, infer Spec> ? Call<Ctx, Spec> : never;
+    /**
+     * Context type of a {@link context} factory.
+     * Pass the factory. A subclass, and a plain {@link UseCase} class, are `never`.
+     *
+     * ```ts
+     * async execute(
+     *   ctx: UseCase.Ctx<typeof ApiUseCase>,
+     *   input: { query: string },
+     * ): Promise<User[]> {}
+     * ```
+     */
+    type Ctx<Factory> = GuardParameters<Factory>['ctx'];
+    /**
+     * Factory returned by {@link context}.
+     * An exported const infers this type.
+     * `guard` and `hooks` return the same factory.
+     */
+    interface ContextFactory<Ctx, Spec = NoStatics> extends ReturnType<typeof buildContext<Ctx, Spec>> {
+        /**
+         * Runs after guards already registered, and before `execute`.
+         * Returns the same factory.
+         */
+        guard(guard: (call: Call<Ctx, Spec>) => void | Promise<void>): ContextFactory<Ctx, Spec>;
+        /**
+         * Lifecycle around `execute`. The value returned from `preExecute` is the
+         * `state` argument of `postExecute`, `onCatch`, and `onFinally`.
+         * A second call throws when this factory already has hooks.
+         */
+        hooks<State = void>(definition: HookDefinition<Ctx, Spec, State>): ContextFactory<Ctx, Spec>;
+    }
+    /**
+     * Family factory. Pass the context type.
+     * The argument is a settings object with no keys yet.
+     */
+    function context<Ctx, Spec = NoStatics>(config?: ContextConfig): unknown extends Ctx ? 'Pass a type argument: UseCase.context<Ctx>()' : ContextFactory<Ctx, Spec>;
+}
+/** Values a guard and the hooks share for one invocation. */
+type Call<Ctx, Spec> = {
+    readonly ctx: Ctx;
+    readonly spec: Spec;
+    readonly token: string;
+    /** The `input` argument the caller passed to `execute`. */
+    readonly input: unknown;
+};
+type Performed<Ctx, Spec> = Call<Ctx, Spec> & {
+    readonly result: unknown;
+};
+type Caught<Ctx, Spec> = Call<Ctx, Spec> & {
+    readonly error: unknown;
+};
+type Settled<Ctx, Spec> = (Call<Ctx, Spec> & {
+    readonly status: 'success';
+    readonly result: unknown;
+}) | (Call<Ctx, Spec> & {
+    readonly status: 'failure';
+    readonly error: unknown;
+});
+/** Settings for {@link UseCase.context}. There are none yet. */
+type ContextConfig = Record<string, never>;
+type ContextGuard<Ctx, Spec> = (call: Call<Ctx, Spec>) => void | Promise<void>;
+type HookDefinition<Ctx, Spec, State> = {
+    preExecute?: (call: Call<Ctx, Spec>) => State | Promise<State>;
+    postExecute?: (call: Performed<Ctx, Spec>, state: Awaited<State>) => void | Promise<void>;
+    onCatch?: (call: Caught<Ctx, Spec>, state: Awaited<State> | undefined) => void | Promise<void>;
+    onFinally?: (call: Settled<Ctx, Spec>, state: Awaited<State> | undefined) => void | Promise<void>;
+};
+/** Hooks stored on one factory. State is erased after `.hooks()` checks it. */
+type StoredHooks<Ctx, Spec> = {
+    preExecute?: (call: Call<Ctx, Spec>) => unknown;
+    postExecute?: (call: Performed<Ctx, Spec>, state: unknown) => void | Promise<void>;
+    onCatch?: (call: Caught<Ctx, Spec>, state: unknown) => void | Promise<void>;
+    onFinally?: (call: Settled<Ctx, Spec>, state: unknown) => void | Promise<void>;
+};
+/** Type-only mark. Absent at runtime. Same symbol in {@link UseCase.GuardParameters}. */
+declare const guardParameters: unique symbol;
+type GuardParametersSlot<Ctx, Spec> = {
+    readonly [guardParameters]?: (call: Call<Ctx, Spec>) => void;
+};
+declare function buildContext<Ctx, Spec = NoStatics>(options?: {
+    guard?: ContextGuard<Ctx, Spec>;
+    hooks?: StoredHooks<Ctx, Spec>;
+}): (<const Token extends string, const S extends [keyof Spec] extends [never] ? NoStatics : Spec>(token: Token, ...args: [keyof Spec] extends [never] ? [] : [statics: ReservedOk<S> & Spec]) => ((abstract new () => {
+    /** Nominal marker. Each factory call is a distinct class. */
+    readonly "__#private@#brand": true;
+    /**
+     * Required. Annotate `ctx`, `input`, and the return type on the subclass.
+     * A guard and hooks run around this method when set.
+     */
+    execute(ctx: Ctx, input: unknown): Promise<unknown>;
+}) & {
+    /** Use-case name. Literal type of the string passed to the factory. */
+    readonly token: Token;
+}) & ([keyof Spec] extends [never] ? NoStatics : Statics<S>)) & GuardParametersSlot<Ctx, Spec>;
+export {};
+//# sourceMappingURL=use-case.d.ts.map

package/dist/use-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-case.d.ts","sourceRoot":"","sources":["../src/use-case.ts"],"names":[],"mappings":"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"}

package/dist/use-case.js

@@ -0,0 +1,221 @@
+/**
+ * Application service. Pass ports through the constructor.
+ * `execute` is required; the compiler errors on the class when it is missing.
+ * Declare the input and output on `execute` — those are the types callers see.
+ * A refusal throws an {@link Errors} catalog member. The application catches it.
+ *
+ * ```ts
+ * class CreateUser extends UseCase('user.create') {
+ *   constructor(private readonly users: UserRepository) { super() }
+ *   async execute(input: { email: string }): Promise<{ id: string }> {
+ *     return { id: input.email }
+ *   }
+ * }
+ * ```
+ */
+export function UseCase(token) {
+    class UseCaseClass {
+        /** Use-case name. Literal type of the string passed to {@link UseCase}. */
+        static token = token;
+        /** Nominal marker. Each `UseCase(...)` call is a distinct class. */
+        #brand = true;
+        constructor() {
+            void this.#brand;
+        }
+    }
+    return UseCaseClass;
+}
+const RESERVED_STATICS = new Set([
+    'token',
+    'prototype',
+    'name',
+    'length',
+]);
+/**
+ * Family of use cases that receive a caller context on `execute`.
+ * Returns a factory: a token, or a token and statics when `Spec` has keys.
+ * `execute` is required; annotate it on the subclass — callers see those types.
+ * A guard and hooks, when set, run around that method.
+ * Statics are application data copied onto the class. The application validates `input`.
+ * {@link UseCase.GuardParameters} reads the guard's call off the factory.
+ * {@link UseCase.Ctx} reads that call's context type.
+ * {@link context} returns that factory. {@link ContextFactory.guard} and
+ * {@link ContextFactory.hooks} return it again.
+ *
+ * ```ts
+ * const ApiUseCase = UseCase.context<
+ *   ApiContext,
+ *   { input: StandardSchemaV1; permission: string }
+ * >()
+ *   .guard((call) => {
+ *     if (call.ctx.sessionId.length < 1 || call.spec.permission.length < 1) {
+ *       throw new Error('unauthorized')
+ *     }
+ *   })
+ *   .hooks({
+ *     preExecute: () => ({ started: Date.now() }),
+ *     postExecute(_call, state) {
+ *       void state.started
+ *     },
+ *   })
+ *
+ * class FindUsers extends ApiUseCase('user.find', {
+ *   input: z.object({ query: z.string() }),
+ *   permission: 'users.read',
+ * }) {
+ *   constructor(private readonly users: UserRepository) { super() }
+ *   async execute(
+ *     ctx: UseCase.Ctx<typeof ApiUseCase>,
+ *     input: { query: string },
+ *   ): Promise<User[]> {
+ *     return this.users.search(input.query)
+ *   }
+ * }
+ * ```
+ */
+(function (UseCase) {
+    /**
+     * Family factory. Pass the context type.
+     * The argument is a settings object with no keys yet.
+     */
+    function context(config) {
+        void config;
+        return bindFactory({});
+    }
+    UseCase.context = context;
+})(UseCase || (UseCase = {}));
+function storedHooks(definition) {
+    if (definition.preExecute === undefined &&
+        definition.postExecute === undefined &&
+        definition.onCatch === undefined &&
+        definition.onFinally === undefined) {
+        return undefined;
+    }
+    return definition;
+}
+function composeGuard(current, next) {
+    if (current === undefined)
+        return next;
+    return async (call) => {
+        await current(call);
+        await next(call);
+    };
+}
+function bindFactory(slots) {
+    const factory = buildContext(slots);
+    Object.defineProperty(factory, 'guard', {
+        configurable: true,
+        enumerable: false,
+        writable: true,
+        value: (guard) => bindFactory({
+            ...slots,
+            guard: composeGuard(slots.guard, guard),
+        }),
+    });
+    Object.defineProperty(factory, 'hooks', {
+        configurable: true,
+        enumerable: false,
+        writable: true,
+        value: (definition) => {
+            const hooks = storedHooks(definition);
+            if (slots.hooks !== undefined && hooks !== undefined) {
+                throw new Error('hexok: UseCase hooks are already set');
+            }
+            return bindFactory({
+                ...slots,
+                ...(hooks !== undefined ? { hooks } : {}),
+            });
+        },
+    });
+    return factory;
+}
+function buildContext(options) {
+    const guard = options?.guard;
+    const hooks = options?.hooks;
+    const factory = function family(token, ...args) {
+        // Conditional rest tuple: index 0 is the statics bag, or absent.
+        const statics = bagOf(args);
+        const spec = (statics ?? {});
+        class Runtime {
+            /** Use-case name. Literal type of the string passed to the factory. */
+            static token = token;
+            /** Nominal marker. Each factory call is a distinct class. */
+            #brand = true;
+            constructor() {
+                void this.#brand;
+                if (guard === undefined && hooks === undefined)
+                    return;
+                installExecute(this, token, guard, hooks, spec);
+            }
+        }
+        if (statics !== undefined)
+            assignStatics(Runtime, statics);
+        return Runtime;
+    };
+    return factory;
+}
+function bagOf(args) {
+    const value = args[0];
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    return value;
+}
+function assignStatics(target, statics) {
+    const copy = {};
+    const record = statics;
+    for (const key of Object.keys(statics)) {
+        if (RESERVED_STATICS.has(key))
+            continue;
+        copy[key] = record[key];
+    }
+    Object.assign(target, copy);
+}
+function installExecute(instance, token, guard, hooks, spec) {
+    const prototype = Object.getPrototypeOf(instance);
+    // Own property would shadow this and recurse.
+    const execute = prototype.execute;
+    Object.defineProperty(instance, 'execute', {
+        configurable: true,
+        writable: true,
+        value: async (ctx, input) => {
+            const call = { ctx, spec, token, input };
+            if (guard !== undefined)
+                await guard(call);
+            // Local to this invocation. Overlapping execute calls must not share it.
+            let state;
+            let succeeded = false;
+            let result;
+            let caught;
+            let failed = false;
+            try {
+                if (hooks?.preExecute !== undefined) {
+                    state = await hooks.preExecute(call);
+                }
+                result = await execute.call(instance, ctx, input);
+                if (hooks?.postExecute !== undefined) {
+                    await hooks.postExecute({ ...call, result }, state);
+                }
+                succeeded = true;
+                return result;
+            }
+            catch (error) {
+                failed = true;
+                caught = error;
+                if (hooks?.onCatch !== undefined) {
+                    await hooks.onCatch({ ...call, error }, state);
+                }
+                throw error;
+            }
+            finally {
+                if (hooks?.onFinally !== undefined) {
+                    const settled = succeeded
+                        ? { ...call, status: 'success', result }
+                        : { ...call, status: 'failure', error: caught };
+                    if (failed || succeeded)
+                        await hooks.onFinally(settled, state);
+                }
+            }
+        },
+    });
+}
+//# sourceMappingURL=use-case.js.map

package/dist/use-case.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-case.js","sourceRoot":"","sources":["../src/use-case.ts"],"names":[],"mappings":"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"}

package/dist/{core/schema.d.ts → validate.d.ts}

@@ -16,4 +16,4 @@ export type Infer<S extends StandardSchemaV1> = NonNullable<S['~standard']['type
  * ```
  */
 export declare function validate<S extends StandardSchemaV1>(schema: S, value: unknown): Result<Infer<S>, 'VALIDATION'>;
-//# sourceMappingURL=schema.d.ts.map
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,kDAAkD;AAClD,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,gBAAgB,IAAI,WAAW,CACzD,CAAC,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CACxB,CAAC,QAAQ,CAAC,CAAC;AAEZ;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,gBAAgB,EACjD,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,OAAO,GACb,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAShC"}

package/dist/{core/schema.js → validate.js}

@@ -25,4 +25,4 @@ export function validate(schema, value) {
 function isPromise(value) {
     return typeof value.then === 'function';
 }
-//# sourceMappingURL=schema.js.map
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,EAAE,EAAe,MAAM,aAAa,CAAC;AAQpD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,QAAQ,CACtB,MAAS,EACT,KAAc;IAEd,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACnD,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC,KAAiB,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,SAAS,CAChB,KAE6C;IAE7C,OAAO,OAAQ,KAA0B,CAAC,IAAI,KAAK,UAAU,CAAC;AAChE,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hexok",
-  "version": "1.0.1",
-  "description": "A TypeScript kit for writing a clean-architecture backend as ordinary classes.",
+  "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",
   "sideEffects": false,
@@ -28,34 +28,15 @@
     "access": "public"
   },
   "exports": {
-    "./core": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js"
-    },
-    "./domain": {
-      "types": "./dist/domain/index.d.ts",
-      "import": "./dist/domain/index.js"
-    },
-    "./app": {
-      "types": "./dist/app/index.d.ts",
-      "import": "./dist/app/index.js"
-    },
-    "./infra": {
-      "types": "./dist/infra/index.d.ts",
-      "import": "./dist/infra/index.js"
-    },
-    "./runtime": {
-      "types": "./dist/runtime/index.d.ts",
-      "import": "./dist/runtime/index.js"
-    },
-    "./testing": {
-      "types": "./dist/testing/index.d.ts",
-      "import": "./dist/testing/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
     "./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.