@smthrs/plugin 0.0.0-stage → 1.0.0-rc.13

package/docs/concepts/configuration.md

@@ -0,0 +1,111 @@
+---
+title: "Configuration"
+description: "The config waterfall and the JSON boundary it enforces: plugin-owned namespaces, reserved root keys, deep merge semantics, admission rules, and the published size limits."
+sidebar:
+  order: 3
+---
+
+Configuration is the one lifecycle the kernel owns. It is two hooks: `config`,
+a waterfall in which each plugin may return a patch, and `configResolved`, a
+parallel observer that sees the frozen result. `Kernel.make` runs both.
+
+## Configuration is a namespace map, not a policy surface
+
+A configuration is a flat record whose root keys name plugin-owned namespaces.
+Each namespace holds JSON, and the kernel never interprets it: the plugin that
+owns a namespace is the only code that knows what its contents mean.
+
+Four root keys are refused with `config_invalid`: `engine`, `retry`, `store`,
+and `plugins`. The kernel does not apply retry, storage, concurrency, cache,
+wait, journal, or ownership policy, and accepting those names would imply that
+setting them changes something. Those policies stay on the Effect service or
+constructor option that applies them.
+
+## The waterfall merges patches
+
+Each `config` handler receives the accumulated configuration and returns a
+partial to merge, or nothing:
+
+```ts
+import { type FlowsPlugin, make } from "@smthrs/plugin"
+import * as Effect from "effect/Effect"
+
+const plugin: FlowsPlugin = make({
+  name: "flows-plugin-endpoint",
+  hooks: {
+    config: (config) =>
+      config["endpoint"] === undefined
+        ? Effect.succeed({ endpoint: { url: "https://example.test" } })
+        : Effect.void
+  }
+})
+```
+
+`Config.merge` is the merge function `Kernel.make` uses. Records merge key by
+key, recursively. Every other JSON value, including an array, replaces the
+previous value wholesale:
+
+```ts
+Config.merge({ a: { b: 1, c: 2 } }, { a: { c: 3, d: 4 } }) // { a: { b: 1, c: 3, d: 4 } }
+Config.merge({ a: [1] }, { a: [2] }) // { a: [2] }
+Config.merge({ a: { b: 1 } }, { a: 5 }) // { a: 5 }
+```
+
+Both operands and the merged result are admitted, so no handler in the chain
+ever observes a value that breaks the rules below, even when each individual
+patch was within them.
+
+## What the boundary admits
+
+Configuration is strict JSON, copied before any plugin observes it and frozen
+recursively afterward. The following are refused with `config_invalid` and the
+path of the offending value:
+
+- Cycles and repeated object references.
+- Sparse arrays, arrays with extra properties, and array subclasses.
+- Accessors, symbol keys, non-enumerable properties, and exotic prototypes.
+- Non-finite numbers, unpaired surrogates, and non-JSON values such as `Date`
+  and `Map`.
+- The prototype-control keys `__proto__`, `constructor`, and `prototype`, at
+  every depth.
+- `undefined` members.
+
+The last one is a decision worth naming. `{ endpoint: undefined }` fails at
+`$.endpoint` instead of resolving to `{}`. A silent drop hid a typo behind a
+value the next handler never saw. To leave something unset, omit the key or
+write `null`.
+
+Admission reads a value through `Reflect.ownKeys`, `Object.getPrototypeOf`, and
+one property descriptor per key. An accessor is never called, so a proxy sees a
+bounded number of traps and only the data those traps return is copied. A trap
+that throws refuses the whole tree.
+
+## Size limits
+
+| Limit                           | Value | Export                        |
+| ------------------------------- | ----- | ----------------------------- |
+| Encoded bytes per configuration | 1 MiB | `Config.maximumConfigBytes`   |
+| Container nesting depth         | 64    | `Config.maximumConfigDepth`   |
+| Aggregate members               | 4,096 | `Config.maximumConfigMembers` |
+| Aggregate values                | 8,192 | `Config.maximumConfigNodes`   |
+
+Strings are limited to 64 KiB of encoded JSON and keys to 1 KiB. A tree over any
+bound fails with `config_invalid`, and because the merged result is admitted
+too, a chain of small patches cannot add up past them.
+
+## configResolved is a lossy observer boundary
+
+After the waterfall settles, `Kernel.make` decodes and freezes the result, then
+runs every `configResolved` handler in parallel. Those handlers are observers:
+their success values are discarded, and their failures do not fail startup.
+Read them from `kernel.observerErrors` and log them at your own boundary:
+
+```ts
+const kernel = await Effect.runPromise(Kernel.make([plugin]))
+for (const error of kernel.observerErrors) {
+  console.warn(`plugin ${error.plugin} failed to observe the config: ${error.code}`)
+}
+```
+
+Dropping them on the floor is the one thing to avoid. A plugin whose observer
+fails silently looks configured and is not.

package/docs/concepts/hook-kinds.md

@@ -0,0 +1,107 @@
+---
+title: "Hook kinds"
+description: "The four dispatch shapes a hook can declare, what each promises about ordering, results, and failure, and how the type-level kind and the runtime catalog stay in agreement."
+sidebar:
+  order: 1
+---
+
+A hook is a name with a fixed dispatch shape. The shape is called its **kind**,
+and the kernel fixes the four kinds: `sequential`, `parallel`, `first`, and
+`waterfall`. A host picks a kind when it declares a hook, and that choice
+decides how many handlers run, in what order, what the caller gets back, and
+what a failing handler does to the caller.
+
+## A hook entry is a handler or an ordering object
+
+A plugin declares a hook either as a bare function or as Vite's per-hook
+ordering object:
+
+```ts
+import { type FlowsPlugin, make } from "@smthrs/plugin"
+import * as Effect from "effect/Effect"
+
+const bare: FlowsPlugin = make({
+  name: "flows-plugin-bare",
+  hooks: { configResolved: () => Effect.void }
+})
+
+const ordered: FlowsPlugin = make({
+  name: "flows-plugin-ordered",
+  hooks: { configResolved: { order: "pre", handler: () => Effect.void } }
+})
+```
+
+Both forms are the same handler to the dispatcher. `Hooks.handlerOf` and
+`Hooks.orderOf` read either one. `undefined` and `null` are refused rather than
+skipped, so a conditionally built plugin fails at startup with a path instead of
+silently declaring nothing.
+
+## What each kind promises
+
+| Kind         | Which handlers run                                                             | What the caller receives                                                            | What a failing handler does                                                                                    |
+| ------------ | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `sequential` | Every handler, in resolved order, one at a time. No two overlap.               | An array of every handler's success value, in resolved order.                       | Stops dispatch at that handler and fails the caller with `hook_failed`.                                        |
+| `parallel`   | Every handler, concurrently, bounded by `parallelConcurrency` (16 by default). | An array of `PluginError`, in resolved handler order. Success values are discarded. | Nothing. The failure is returned, and the caller never fails.                                                  |
+| `first`      | Handlers in resolved order until one answers `Option.some`.                    | That `Option`, or `Option.none()` when no handler answered.                         | Stops dispatch and fails the caller with `hook_failed`. A non-`Option` value fails with `invalid_hook_result`. |
+| `waterfall`  | Every handler, each one seeing the value the previous handler produced.        | The final value.                                                                    | Stops dispatch and fails the caller with `hook_failed`.                                                        |
+
+Choose by what the caller needs. Use `sequential` when every handler must run
+and the caller reads every answer. Use `parallel` for observers whose failure is
+not the caller's problem. Use `first` when the first plugin with an opinion
+wins and the host has its own default for silence. Use `waterfall` when each
+handler transforms a value the next one sees.
+
+## Waterfall handlers return a patch, not the whole value
+
+A waterfall dispatch takes a merge function alongside the initial value, and the
+merge decides what a handler's answer means:
+
+```ts
+const merged = kernel.plugins.waterfall("config", initial, Config.merge)
+const replaced = kernel.plugins.waterfall("tools", initial, (_previous, next) => next)
+```
+
+`Config.merge` deep-merges each returned patch into the accumulated
+configuration, which is what makes the `config` hook a patch protocol. A host
+that wants replacement passes `(_previous, next) => next`, which is what the
+Smithers agent host in [`@smthrs/agent`](/api/agent) does for its registry,
+flow, and model-request waterfalls. A handler that returns `undefined` (an
+`Effect.void` handler) leaves the value untouched: the merge is not called at
+all.
+
+## The kind lives in the type and in the catalog
+
+`SequentialHook`, `ParallelHook`, `FirstHook`, and `WaterfallHook` are phantom
+carriers. They add nothing at runtime; they record the kind and the handler
+signature in the type system so the dispatcher's methods can accept only the
+hook names of their own kind:
+
+```ts
+declare module "@smthrs/plugin" {
+  interface FlowsHooks {
+    readonly toolCall: SequentialHook<(ctx: ToolCallContext) => Effect.Effect<Option.Option<ToolOverride>>>
+  }
+}
+```
+
+Calling `dispatcher.parallel("toolCall", ctx)` does not compile, because
+`KeysOfKind<FlowsHooks, "parallel">` does not contain `toolCall`.
+
+The type system cannot enumerate an augmentable interface, so the kernel also
+needs the same information at runtime. That is the hook catalog a host passes as
+`Resolve.Options.hooks`: a record from hook name to kind, typed as
+`HookCatalog<H>` so a name the interface declares cannot carry another kind.
+It is what the `unknown_hook` guard checks a plugin against, and it is what
+[Declare hooks for your host](../guides/host-your-own-hooks.md) walks through.
+Resolution keeps the admitted catalog as `Resolved.kinds`, refuses a catalog
+that labels `config` or `configResolved` with another kind, and every dispatch
+method refuses a hook whose catalog kind differs from its own with
+`hook_kind_mismatch` before running a handler.
+
+## Cancellation is fiber interruption
+
+Nothing in the dispatcher threads an `AbortSignal`. Interrupting the fiber that
+runs a dispatch interrupts the handler in flight, runs its finalizers, and skips
+every handler that had not started, for both `sequential` and bounded `parallel`
+dispatch. A handler that needs cleanup writes it with `Effect.onInterrupt` or
+`Effect.acquireRelease` like any other Effect.

package/docs/concepts/resolution.md

@@ -0,0 +1,132 @@
+---
+title: "Resolution"
+description: "How a plugin list becomes an ordered immutable catalog: the order of the checks, Vite's two-level ordering rule, exact-Unicode names, the copies the kernel takes, and the published limits."
+sidebar:
+  order: 2
+---
+
+Resolution is the step between "here is an array of plugins" and "here is a
+dispatcher". It happens once, at startup, and everything it produces is a copy
+the kernel owns. `Resolve.resolve` does the work; `Kernel.make` calls it for
+you.
+
+## The order of the checks
+
+The steps run in this order, and the order is part of the contract:
+
+1. **Snapshot the options.** `target`, `hooks`, `parallelConcurrency`,
+   `cacheEnvironment`, and `config` are read through property descriptors. An
+   unknown option key is `invalid_plugin`.
+2. **Flatten the input.** Nested arrays flatten within the depth and node
+   limits, and `false`, `null`, and `undefined` entries drop. Array length must
+   fit the remaining node budget, including queued entries, before keys are
+   enumerated or element descriptors are read. A preset is therefore just a
+   function that returns plugins.
+3. **Validate every plugin record.** Each plugin, each hook entry, and each
+   ordering object is checked for shape and copied. This happens _before_
+   `apply` filtering, so an excluded plugin cannot hide a malformed one.
+4. **Filter by `apply`.** A literal `"engine"` or `"harness"` is compared with
+   the host's `target`. A predicate is called with the pre-resolution config.
+5. **Check hook names against the host catalog.** This happens _after_
+   selection, so a shared preset can carry `apply: "harness"` plugins with
+   harness-only hooks and still resolve under a bare engine kernel.
+6. **Reject duplicate names.** Two selected plugins with the same name fail with
+   `duplicate_name` rather than the last one silently winning.
+7. **Order the list and build the handler map.**
+8. **Decode the cache environment**, when the host declared one. See
+   [Declare a cache identity](../guides/cache-identity.md).
+
+## Ordering follows Vite exactly
+
+Ordering has two levels, and they are applied in the opposite order from the one
+most readers expect.
+
+`enforce` sorts the plugin list once, into `pre`, then normal, then `post`,
+stably within each group. That sorted list is the resolved plugin order, and it
+is the order `kernel.layer` merges layers in.
+
+The per-hook `order` then re-partitions that list, for one hook only. A handler
+declared `{ order: "pre", handler }` runs ahead of every normal-order handler
+even when its plugin is `enforce: "post"`:
+
+```ts
+const plugins = [
+  make({ name: "post-plugin-pre-hook", enforce: "post", hooks: { configResolved: { order: "pre", handler } } }),
+  make({ name: "pre-plugin-post-hook", enforce: "pre", hooks: { configResolved: { order: "post", handler } } })
+]
+// configResolved runs post-plugin-pre-hook first.
+```
+
+Ties keep the resolved plugin order. Because the per-hook `order` applies to one
+hook, a plugin can be early for one hook and late for another. See
+[Control the order handlers run in](../guides/order-handlers.md) for how to pick
+between the two levers.
+
+## Names compare as exact Unicode
+
+A plugin name is a bounded, non-empty, control-free, well-formed string of at
+most 256 UTF-16 code units, and it is never normalized. Two canonically
+equivalent spellings are two different plugins, and a name that is only
+whitespace is refused. The same rules apply to `version` and to hook names in a
+host catalog and to keys declared in a plugin's `hooks` record. Invalid
+plugin-declared hook names fail with `invalid_plugin` before `apply` filtering,
+using the bounded path `.hooks[N]`, where `N` is the key's zero-based index.
+
+The naming convention is `flows-plugin-<thing>`, following Vite's
+`vite-plugin-<thing>`. The kernel does not enforce it.
+
+## Everything is copied
+
+The resolved catalog owns every record it exposes. Dispatch never reads a
+caller-owned map, plugin record, hook object, config value, or cache identity:
+
+- Plugin records and hook objects are copied into frozen objects.
+- The handler list for each hook is a frozen array of frozen records, each one
+  carrying its plugin name and hook name for attribution.
+- `Resolved.handlers` is a read-only map facade with no `set`, `delete`, or
+  `clear`.
+- The configuration `apply` predicates see is a snapshot taken before the first
+  predicate runs.
+
+Reflection is descriptor-only. Accessors are never executed, an exotic prototype
+is refused, and a hostile proxy observes a bounded number of traps whose return
+values are copied rather than retained. Mutating a plugin object after startup
+changes nothing about dispatch.
+
+## Limits
+
+One kernel accepts:
+
+| Limit                                                       | Value | Export                               |
+| ----------------------------------------------------------- | ----- | ------------------------------------ |
+| Plugins                                                     | 256   | `Resolve.maximumPlugins`             |
+| Hook handlers                                               | 1,024 | `Resolve.maximumHandlers`            |
+| Input nodes, including arrays and dropped entries           | 4,096 | `Resolve.maximumPluginInputNodes`    |
+| Nested preset-array depth                                   | 64    | `Resolve.maximumPluginDepth`         |
+| Plugin, version, and hook name length, in UTF-16 code units | 256   | `Resolve.maximumPluginNameLength`    |
+| Parallel observers at once, by default                      | 16    | `Resolve.defaultParallelConcurrency` |
+| Parallel observers at once, at most                         | 256   | `Resolve.maximumParallelConcurrency` |
+
+Exceeding a count or depth limit fails with `resource_limit` and the path of the
+offending entry or preset array. Invalid names fail with `invalid_plugin`.
+The handler bound counts the handlers the kernel dispatches, so a plugin whose
+hooks were filtered out costs nothing against it.
+
+Resolution diagnostics truncate property and unknown-hook key text after 64
+UTF-16 code units, appending `...`. Paths use dot notation for identifiers and
+JSON-quoted brackets for other keys; unknown-hook messages also JSON-quote the
+key. The `hook` error field retains the complete, validated hook identity.
+
+Configuration and cache-identity JSON admission also bounds strings and diagnostic paths:
+
+| Limit                                                        | Value             |
+| ------------------------------------------------------------ | ----------------- |
+| One JSON-encoded string, including quotes and escapes        | 64 KiB            |
+| One JSON-encoded property name, including quotes and escapes | 1 KiB             |
+| Refusal path, as a JSON-encoded string                       | At most 192 bytes |
+
+String and key lengths are checked before scanning or encoding oversized text.
+Oversized or ill-formed property names use the parent path plus `[key:N]`, where
+`N` is the zero-based index in the record's own-key order. Longer refusal paths
+retain a prefix ending in `...`; truncation preserves Unicode characters and
+accounts for JSON escaping. Short paths for admitted keys keep their usual shape.

package/docs/guides/cache-identity.md

@@ -0,0 +1,106 @@
+---
+title: "Declare a cache identity for sealed steps"
+description: "Supply Action.CacheEnvironment so a composition's sealed cache keys are shareable across runs, and understand why every selected plugin then needs a version."
+sidebar:
+  order: 5
+---
+
+Skip this guide unless your host runs on the Smithers durable engine, which is
+what reads the identity described here. Everything else in this package works
+without it.
+
+A sealed step in the [durable engine](/api/engine) is content-addressed: the
+same call replays one recorded result instead of paying the provider again.
+That is only safe when the key covers the composition the result was computed
+under. Swap a model plugin and keep the key, and the run is served a stale
+answer computed by a different composition.
+
+The kernel is where a host says what its composition is. Declaring
+`cacheEnvironment` folds every selected plugin's identity into the environment
+that keys sealed steps. Omitting it keeps sealed keys local to the run.
+
+## Omitting it is the honest default
+
+```ts
+import { Kernel, make } from "@smthrs/plugin"
+
+const kernel = Kernel.make([make({ name: "flows-plugin-model-sonnet" })])
+```
+
+`Action.CurrentCacheEnvironment` resolves to `undefined` under this kernel's
+layer, which is the engine's "nothing was declared" state. Sealed keys are
+pinned to the current execution, so nothing is shared and nothing is wrong. Use
+this until you can state the composition's whole identity.
+
+## Declaring it requires the complete identity
+
+Pass the additional layer identities your host built outside the plugin list and
+the capability envelope the composition actually holds:
+
+```ts
+const kernel = Kernel.make(
+  [make({ name: "flows-plugin-model-sonnet", version: "1.4.0" })],
+  {},
+  { cacheEnvironment: { layers: ["Host=node"], capabilities: { fs: ["/workspace/**"] } } }
+)
+// CurrentCacheEnvironment:
+// { layers: ["flows-plugin-model-sonnet@1.4.0", "Host=node"], capabilities: { fs: ["/workspace/**"] } }
+```
+
+The kernel prepends each selected plugin as `name@version`, in resolved order,
+ahead of the layers you supplied. Change a plugin's version and the declared
+layers change, so the sealed keys change with it.
+
+`Action.CacheEnvironment` is complete by contract: it is the whole authority and
+composition envelope, not a hint. Supply the capabilities the composition really
+grants. A result computed under a broad envelope must not be served to a run
+with an attenuated one.
+
+## Every selected plugin needs a version
+
+Declaring a cache environment makes `version` required on every plugin the
+kernel selected:
+
+```ts
+const refused = Kernel.make(
+  [make({ name: "flows-plugin-model-sonnet" })],
+  {},
+  { cacheEnvironment: { layers: [], capabilities: {} } }
+)
+// Fails with PluginError { code: "cache_environment_invalid", plugin: "flows-plugin-model-sonnet", path: "$[0].version" }
+```
+
+A versionless plugin is refused rather than folded in as a bare name, because a
+bare name claims that two different builds of that plugin are the same
+composition. The refusal names the plugin, so the fix is to add its version or
+to drop the cache environment.
+
+## Identity is injective
+
+Both halves of `name@version` escape `%` first and then `@`, so the joined
+string can be split back apart:
+
+| Plugin name        | Version | Layer entry            |
+| ------------------ | ------- | ---------------------- |
+| `flows-plugin-a`   | `1.0.0` | `flows-plugin-a@1.0.0` |
+| `flows-plugin-a@b` | `c`     | `flows-plugin-a%40b@c` |
+| `flows-plugin-a`   | `b@c`   | `flows-plugin-a@b%40c` |
+| `@smthrs/x`        | `1.0.0` | `%40smthrs/x@1.0.0`    |
+
+An ordinary identity stays readable, and two compositions that differ only in
+where the delimiter fell never collapse onto one sealed identity.
+
+## The value is copied before the engine sees it
+
+Resolution decodes the environment against the `Action.CacheEnvironment` schema,
+copies and freezes every layer entry, capability name, and capability array, and
+only then provides it. Invalid or mutable caller data never reaches
+`Action.CurrentCacheEnvironment`. A malformed environment fails with
+`cache_environment_invalid` and the option path.
+
+## Plugins cannot replace it
+
+The kernel layer seals `Action.CurrentCacheEnvironment` after merging plugin
+layers. A plugin layer that provides `Action.layerCacheEnvironment` is
+overridden by the declared environment, or by `undefined` when the host
+declared none, so no plugin can forge or declare the composition's identity.

package/docs/guides/contribute-services.md

@@ -0,0 +1,84 @@
+---
+title: "Contribute services from a plugin"
+description: "Attach an Effect layer to a plugin, understand the merge order and what happens when two plugins provide the same tag, and handle a layer that fails to build."
+sidebar:
+  order: 4
+---
+
+A hook lets a plugin answer a question the host asks. A `layer` lets a plugin
+add a service the rest of the composition can ask for. Declare both on the same
+record when a plugin needs both.
+
+## Attach a layer
+
+```ts
+import { Kernel, make } from "@smthrs/plugin"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+
+class Clock extends Context.Service<Clock, { readonly now: () => number }>()("example/Clock") {}
+
+const clock = make({
+  name: "flows-plugin-clock",
+  layer: Layer.succeed(Clock)({ now: () => Date.now() })
+})
+
+const program = Effect.gen(function*() {
+  const kernel = yield* Kernel.make([clock])
+  return yield* Clock.pipe(
+    Effect.map((service) => service.now()),
+    Effect.provide(kernel.layer)
+  )
+})
+```
+
+`kernel.layer` is every selected plugin's layer merged into one. A plugin with
+no `layer` contributes nothing, and a plugin list with no layers at all produces
+an empty layer that is still safe to provide.
+
+The value must be an Effect `Layer`. Anything else fails resolution with
+`invalid_plugin` at `$.layer`, before the layer is ever built.
+
+## Merge order follows resolved plugin order
+
+Layers merge left to right in the resolved plugin order, so a service an earlier
+plugin provides is visible to a later plugin's layer. `enforce: "pre"` is
+therefore how a plugin makes sure its service is available to the plugins that
+need it. See [Control the order handlers run in](./order-handlers.md).
+
+When two plugins provide the same service tag, the later resolved plugin wins.
+There is no collision error: last one in resolved order is the value the
+composition sees. If two plugins genuinely conflict, decide it with `enforce`,
+or with [`apply`](./select-plugins.md) so only one of them is selected.
+
+## Handle a layer that fails to build
+
+A layer's failure is wrapped as `layer_failed`, attributed to the plugin, with
+the original cause on `cause`:
+
+```ts
+const failing = make({
+  name: "flows-plugin-remote",
+  layer: Layer.effectDiscard(Effect.fail("no credentials"))
+})
+
+const build = Effect.gen(function*() {
+  const kernel = yield* Kernel.make([failing])
+  return yield* Effect.void.pipe(Effect.provide(kernel.layer))
+})
+// Fails with PluginError { code: "layer_failed", plugin: "flows-plugin-remote" }
+```
+
+The failure arrives when the layer is built, not when the kernel is made:
+`Kernel.make` validates that the value is a layer and composes it, and building
+is the caller's step. A composition that never provides `kernel.layer` never
+sees the failure.
+
+## Layers are not the place for engine policy
+
+A plugin layer contributes services to the composition the host assembled. It is
+not a way to reach into durable execution policy: retry, storage, concurrency,
+cache, wait, journal, and ownership stay on the components that apply them, and
+the kernel refuses configuration keys that would suggest otherwise. Contribute a
+service; let the host decide what to do with it.

package/docs/guides/host-your-own-hooks.md

@@ -0,0 +1,129 @@
+---
+title: "Declare hooks for your host"
+description: "Add extension points of your own: augment FlowsHooks, supply the matching runtime catalog, resolve for your target, and dispatch only what you declared."
+sidebar:
+  order: 1
+---
+
+The kernel dispatches two hooks of its own. Every other extension point is
+yours to declare. Adding one takes three pieces that must agree: a type
+declaration, a runtime catalog entry, and a dispatch call.
+
+## Declare the hooks in the type system
+
+Augment `FlowsHooks` in the root module. The specifier must be
+`"@smthrs/plugin"`, because that is where the interface is declared:
+
+```ts
+import type { ParallelHook, WaterfallHook } from "@smthrs/plugin"
+import type * as Effect from "effect/Effect"
+
+interface Prompt {
+  readonly system: ReadonlyArray<string>
+}
+
+interface Session {
+  readonly id: string
+}
+
+declare module "@smthrs/plugin" {
+  interface FlowsHooks {
+    /** Rewrites the prompt before the host sends it. */
+    readonly promptRewrite: WaterfallHook<(prompt: Prompt) => Effect.Effect<Prompt | void>>
+    /** Observes the start of a session. */
+    readonly sessionStart: ParallelHook<(session: Session) => Effect.Effect<void>>
+  }
+}
+```
+
+Pick the kind deliberately: it decides what the caller gets back and what a
+failing handler does. See [Hook kinds](../concepts/hook-kinds.md).
+
+## Supply the matching runtime catalog
+
+The type system cannot enumerate an augmentable interface, so the kernel needs
+the same names again as data. Spread `engineHooks` so the config lifecycle stays
+available to plugins:
+
+```ts
+import { engineHooks } from "@smthrs/plugin"
+
+export const hooks = Object.freeze(
+  {
+    ...engineHooks,
+    promptRewrite: "waterfall",
+    sessionStart: "parallel"
+  } as const
+)
+```
+
+This catalog is what the `unknown_hook` guard checks a plugin against. A plugin
+that declares a hook you did not list fails at startup with the plugin name, the
+hook name, and the path, rather than declaring a handler nobody will ever call.
+
+## Resolve for your host
+
+Pass the catalog, and pass `target: "harness"` unless your host is the engine:
+
+```ts
+import { type FlowsHooks, Kernel, type PluginInput } from "@smthrs/plugin"
+import type { FlowsConfig } from "@smthrs/plugin/Config"
+
+export const makeKernel = (plugins: PluginInput<FlowsHooks> = [], config: FlowsConfig = {}) =>
+  Kernel.make<FlowsHooks>(plugins, config, { target: "harness", hooks })
+```
+
+`target` defaults to `"engine"`, so a plugin declared `apply: "harness"` is
+dropped by a bare `Kernel.make`. See
+[Include a plugin conditionally](./select-plugins.md).
+
+## Dispatch only what you declared
+
+Give each hook a named dispatch function, so callers do not repeat the merge
+function and the hook name:
+
+```ts
+import type * as Plugins from "@smthrs/plugin/Plugins"
+
+export const rewritePrompt = (plugins: Plugins.Service<FlowsHooks>, initial: Prompt) =>
+  plugins.waterfall("promptRewrite", initial, (_previous, next) => next)
+
+export const sessionStarted = (plugins: Plugins.Service<FlowsHooks>, session: Session) =>
+  plugins.parallel("sessionStart", session)
+```
+
+Dispatch is closed: the kernel runs only the catalog you supplied, and a
+dispatcher method accepts only hook names of its own kind. Nothing dispatches a
+hook on your behalf.
+
+## When to use a standalone interface instead
+
+Module augmentation gives one process-wide catalog. That is the right shape for
+a host that owns its process, and it is what the shared `Plugins` service tag
+and its layers hold.
+
+A host that must not widen the shared catalog declares its own interface and
+carries the dispatcher itself:
+
+```ts
+import type { SequentialHook } from "@smthrs/plugin"
+import * as Plugins from "@smthrs/plugin/Plugins"
+import * as Resolve from "@smthrs/plugin/Resolve"
+import * as Effect from "effect/Effect"
+
+interface IsolatedHooks {
+  readonly isolated: SequentialHook<(value: number) => Effect.Effect<number>>
+}
+
+const program = Effect.gen(function*() {
+  const resolved = yield* Resolve.resolve<IsolatedHooks>(
+    { name: "flows-plugin-double", hooks: { isolated: (value) => Effect.succeed(value * 2) } },
+    { hooks: { isolated: "sequential" } }
+  )
+  return yield* Plugins.make<IsolatedHooks>(resolved).sequential("isolated", 21)
+})
+```
+
+A `Plugins.Service<IsolatedHooks>` held directly does not use the shared
+`Plugins` tag, `Plugins.layer`, or `Plugins.layerNoop`. Those three target the
+augmented `FlowsHooks` catalog only.