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

package/docs/troubleshooting.md

@@ -0,0 +1,180 @@
+---
+title: "Troubleshooting"
+description: "Every PluginError code the kernel reports, what causes it, and what to change, plus the failures that are silent by design."
+---
+
+Every refusal this package makes is a `PluginError` with a `code` from a closed
+set. Find the code and read its section. The full error schema is in the
+[API reference](./api.md).
+
+Most errors carry `plugin`, `hook`, and `path` alongside the message. Read
+`path` first: it is a diagnostic dollar-path into the value the kernel refused,
+not an RFC 6901 JSON Pointer. `$` is the input, `.config` an identifier
+property, `[2]` an array index, and `["not an identifier"]` any other key,
+JSON-quoted. So `$[2].hooks.config` is the third plugin's `config` entry and
+`$options.parallelConcurrency` is an option.
+
+## duplicate_name
+
+**What happened.** Two selected plugins have the same name. Names compare as
+exact Unicode strings with no normalization, so this is a real collision, not a
+spelling variant.
+
+**What to change.** Rename one, or exclude one with
+[`apply`](./guides/select-plugins.md). The kernel refuses rather than letting
+the last one win, because last-wins turns a duplicated preset into a silently
+dropped plugin.
+
+## unknown_hook
+
+**What happened.** A selected plugin declares a hook name that is not in the
+host's runtime catalog. The error names the plugin and the hook.
+
+**What to change.** If the hook is yours to add, list it in the catalog you pass
+as `Resolve.Options.hooks` and augment `FlowsHooks` to match. See
+[Declare hooks for your host](./guides/host-your-own-hooks.md). If the hook
+belongs to a different host, give the plugin an `apply` selector so this host
+does not select it.
+
+Passing no catalog means the shared one: `config` and `configResolved` only.
+
+## hook_kind_mismatch
+
+**What happened.** The runtime catalog and the kind actually run disagree.
+At startup, `Options.hooks` labelled `config` with a kind other than
+`waterfall`, or `configResolved` with a kind other than `parallel`; the path
+names the entry, such as `$options.hooks.config`. At dispatch, a method was
+called for a hook the catalog declares with a different kind, which only a cast
+around the typed dispatcher can reach, or for a hook a hand-built `Resolved`
+gave handlers without declaring it in `kinds`. In every case no handler ran.
+
+**What to change.** Make the catalog agree with the hook interface: spread
+`engineHooks` for the shared hooks and write each of your own hooks with the
+kind its type declares. `HookCatalog<H>` refuses a wrong kind for a declared
+name at compile time.
+
+## invalid_plugin
+
+**What happened.** A plugin, preset, option, or hook entry has a shape the
+kernel will not accept. Common causes, each reported at its own path:
+
+- A hook entry that is `undefined` or `null`. Declarations must be callable, so
+  a conditionally built hook is refused rather than skipped.
+- An unknown property on a plugin record or on the options object.
+- A name or version that is empty, whitespace only, longer than 256 UTF-16 code
+  units, or not well-formed text.
+- `enforce` or `order` that is not `"pre"` or `"post"`.
+- `apply` that is not `"engine"`, `"harness"`, or a function.
+- `layer` that is not an Effect `Layer`.
+- A preset array that is sparse, cyclic, repeated, or carries extra properties.
+- An accessor, a symbol key, or a non-enumerable property anywhere in the
+  record.
+
+**What to change.** Read `path`, fix that value. To omit an optional hook, leave
+the key out of the `hooks` record instead of setting it to `undefined`.
+
+## apply_failed
+
+**What happened.** An `apply` predicate threw. The raw failure is not retained,
+because a predicate runs before the kernel has anywhere safe to put an arbitrary
+value.
+
+**What to change.** Make the predicate total. It receives the pre-resolution
+configuration and must return a boolean without reading anything it cannot
+guarantee is there. A predicate that returns a non-boolean fails with
+`invalid_plugin` instead.
+
+## config_invalid
+
+**What happened.** A configuration value is not bounded strict JSON, or it uses
+a reserved root key. This covers the pre-resolution config, any patch a `config`
+handler returned, and the merged result.
+
+**What to change.** Read `path`. The frequent causes:
+
+- `$.engine`, `$.retry`, `$.store`, or `$.plugins`: rename the namespace. The
+  kernel does not apply those policies and refuses to look like it does.
+- An `undefined` member: omit the key, or write `null`. `{ endpoint: undefined }`
+  fails at `$.endpoint` rather than resolving to `{}`.
+- A `Date`, `Map`, class instance, or non-finite number: encode it as JSON, or
+  keep it in a service instead of in configuration.
+- `__proto__`, `constructor`, or `prototype` as a key at any depth.
+- A tree over 1 MiB, 64 deep, 4,096 members, or 8,192 values. See
+  [Configuration](./concepts/configuration.md) for the whole list.
+
+When a `config` handler returned the offending patch, the error also carries
+that plugin and hook.
+
+## cache_environment_invalid
+
+**What happened.** You declared `cacheEnvironment` and the kernel could not
+build a complete identity from it. Either a selected plugin has no `version`, or
+the environment does not match the `Action.CacheEnvironment` schema.
+
+**What to change.** Add a `version` to every selected plugin, or drop
+`cacheEnvironment` and let sealed keys stay run-local. Both are correct; a bare
+plugin name folded into a cross-run cache key is not. See
+[Declare a cache identity](./guides/cache-identity.md).
+
+## invalid_hook_result
+
+**What happened.** A `first` hook handler returned something other than an
+`Option`. The error names the plugin and the hook.
+
+**What to change.** Return `Option.some(value)` to answer and `Option.none()` to
+pass. A `first` hook stops at the first `some`, so returning a bare value would
+make "no opinion" indistinguishable from "the answer is undefined".
+
+## resource_limit
+
+**What happened.** The plugin input, the handler count, or a concurrency option
+exceeded a published bound: 256 plugins, 1,024 handlers, 4,096 input nodes, 64
+nested preset arrays, or a `parallelConcurrency` outside 1 through 256.
+
+**What to change.** Split the composition, or raise nothing: these bounds are
+fixed. A list this large is usually a preset included twice or an array building
+itself in a loop. The [limits table](./concepts/resolution.md) has each bound
+and the export that names it.
+
+## hook_failed
+
+**What happened.** A handler failed, defected, threw synchronously, or returned
+something that is not an Effect. The error names the plugin and the hook, and
+the original failure is on `cause`.
+
+**What to change.** Fix the handler. Where it surfaces depends on the kind: a
+`sequential`, `first`, or `waterfall` hook fails the caller and stops dispatch
+at that handler, while a `parallel` hook returns the error and keeps going. See
+[Hook kinds](./concepts/hook-kinds.md).
+
+## layer_failed
+
+**What happened.** A plugin's layer failed while it was being built. The error
+names the plugin, with the layer's own failure on `cause`.
+
+**What to change.** Fix the layer's acquisition, or make the plugin conditional
+so it is not selected in compositions where its dependencies are absent. The
+failure arrives when something provides `kernel.layer`, not when `Kernel.make`
+returns.
+
+## Failures that are silent by design
+
+**A `configResolved` handler failed and nothing happened.** Parallel observers
+are lossy on purpose: their failures are collected, not raised. Read
+`kernel.observerErrors` and log them. A composition that ignores that array
+cannot tell a working observer from a broken one.
+
+**A plugin was dropped and no error was reported.** Exclusion is not a failure.
+`apply: "harness"` under the default `target: "engine"` drops the plugin
+silently, which is exactly what a shared preset needs. Check
+`kernel.plugins.resolved.plugins` for what was actually selected, and pass
+`{ target: "harness" }` if your host is a harness.
+
+**A hook never runs even though it resolved.** The kernel dispatches only the
+config lifecycle. Every other hook runs when the host calls the dispatcher for
+it, so a hook in the catalog that no host code dispatches is a handler nobody
+calls.
+
+**Mutating a plugin or a config object after startup changed nothing.**
+Resolution copies everything it accepts. Dispatch reads the kernel's own frozen
+records, never yours. Change the input and resolve again.

package/package.json

@@ -1,6 +1,182 @@
 {
   "name": "@smthrs/plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "1.0.0-rc.13",
+  "license": "MIT",
+  "smthrs": {
+    "group": "agent"
+  },
+  "description": "Vite-style typed plugin kernel for flows: hooks, resolution, and config execution",
+  "homepage": "https://github.com/smithersai/smithers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smithersai/smithers.git",
+    "directory": "packages/smithers/agent/plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/smithersai/smithers/issues"
+  },
+  "tags": [
+    "typescript",
+    "effect",
+    "plugin",
+    "hooks"
+  ],
+  "keywords": [
+    "typescript",
+    "effect",
+    "plugin",
+    "hooks"
+  ],
+  "engines": {
+    "node": ">=26.4.0"
+  },
+  "sideEffects": [],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./internal/*": null,
+    "./*/index": null,
+    "./Config": {
+      "import": {
+        "types": "./dist/esm/Config.d.ts",
+        "default": "./dist/esm/Config.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Config.d.ts",
+        "default": "./dist/cjs/Config.js"
+      }
+    },
+    "./Hooks": {
+      "import": {
+        "types": "./dist/esm/Hooks.d.ts",
+        "default": "./dist/esm/Hooks.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Hooks.d.ts",
+        "default": "./dist/cjs/Hooks.js"
+      }
+    },
+    "./Kernel": {
+      "import": {
+        "types": "./dist/esm/Kernel.d.ts",
+        "default": "./dist/esm/Kernel.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Kernel.d.ts",
+        "default": "./dist/cjs/Kernel.js"
+      }
+    },
+    "./Plugin": {
+      "import": {
+        "types": "./dist/esm/Plugin.d.ts",
+        "default": "./dist/esm/Plugin.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Plugin.d.ts",
+        "default": "./dist/cjs/Plugin.js"
+      }
+    },
+    "./PluginError": {
+      "import": {
+        "types": "./dist/esm/PluginError.d.ts",
+        "default": "./dist/esm/PluginError.js"
+      },
+      "require": {
+        "types": "./dist/cjs/PluginError.d.ts",
+        "default": "./dist/cjs/PluginError.js"
+      }
+    },
+    "./Plugins": {
+      "import": {
+        "types": "./dist/esm/Plugins.d.ts",
+        "default": "./dist/esm/Plugins.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Plugins.d.ts",
+        "default": "./dist/cjs/Plugins.js"
+      }
+    },
+    "./Resolve": {
+      "import": {
+        "types": "./dist/esm/Resolve.d.ts",
+        "default": "./dist/esm/Resolve.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Resolve.d.ts",
+        "default": "./dist/cjs/Resolve.js"
+      }
+    },
+    "./index": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/package.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
+  "dependencies": {
+    "@smthrs/canonical": "1.0.0-rc.13",
+    "@smthrs/flow": "1.0.0-rc.13"
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.2",
+    "@effect/vitest": "4.0.5",
+    "@eslint/js": "9.39.5",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "dprint": "0.57.1",
+    "effect": "4.0.5",
+    "esbuild": "0.28.2",
+    "eslint": "9.39.5",
+    "eslint-import-resolver-typescript": "4.4.5",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-jsdoc": "64.3.4",
+    "eslint-plugin-unicorn": "65.0.0",
+    "madge": "8.0.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.69.0",
+    "vitest": "5.0.0"
+  },
+  "peerDependencies": {
+    "effect": "4.0.5"
+  },
+  "scripts": {
+    "lint": "eslint src examples --max-warnings=0 && dprint check",
+    "format": "dprint fmt",
+    "build": "node scripts/build.mjs",
+    "check": "tsc -b tsconfig.json && tsc -p tsconfig.test.json --noEmit",
+    "circular": "node scripts/circular.mjs",
+    "test": "vitest",
+    "coverage": "vitest --coverage"
+  }
 }

package/src/Config.ts

@@ -0,0 +1,207 @@
+/**
+ * Bounded JSON configuration consumed and produced by the plugin kernel.
+ *
+ * Configuration is an extension namespace, not an engine-policy surface.
+ * Durable retry, concurrency, and storage policy stay on their owning Effect
+ * services and constructor options. Every accepted value is copied before any
+ * plugin observes it, then frozen recursively.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as SchemaGetter from "effect/SchemaGetter"
+import * as SchemaIssue from "effect/SchemaIssue"
+import * as Boundary from "./internal/Boundary.ts"
+import { PluginError } from "./PluginError.ts"
+
+/**
+ * Maximum encoded bytes accepted for one plugin configuration.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export const maximumConfigBytes = Boundary.defaultLimits.maxBytes
+
+/**
+ * Maximum nesting accepted for one plugin configuration.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export const maximumConfigDepth = Boundary.defaultLimits.maxDepth
+
+/**
+ * Maximum aggregate members accepted for one plugin configuration.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export const maximumConfigMembers = Boundary.defaultLimits.maxMembers
+
+/**
+ * Maximum aggregate values accepted for one plugin configuration.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export const maximumConfigNodes = Boundary.defaultLimits.maxNodes
+
+/**
+ * One value accepted in a plugin-owned configuration namespace.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const ConfigValue = Schema.Json
+
+/**
+ * One value accepted in a plugin-owned configuration namespace.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type ConfigValue = typeof ConfigValue.Type
+
+const admittedConfigs = new WeakSet<object>()
+
+const configurationSchema = Schema.Unknown.pipe(
+  Schema.decodeTo(
+    Schema.declare<Readonly<Record<string, ConfigValue>>>((value): value is Readonly<Record<string, ConfigValue>> =>
+      typeof value === "object" && value !== null && admittedConfigs.has(value)
+    ),
+    {
+      decode: SchemaGetter.transformEffect((value) =>
+        Effect.try({
+          try: () => snapshotRecord(value),
+          catch: (cause) => {
+            const error = cause as PluginError
+            return new SchemaIssue.InvalidValue({ message: `${error.path}: ${error.message}` })
+          }
+        })
+      ),
+      encode: SchemaGetter.transform((value) => value)
+    }
+  )
+)
+
+/**
+ * Admits pre-resolution configuration as a detached, recursively frozen snapshot.
+ *
+ * Keys name plugin-owned namespaces. `engine`, `retry`, `store`, and
+ * `plugins` are refused because accepting those names would imply policy the
+ * plugin kernel does not own or apply.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const FlowsConfig = configurationSchema
+
+/**
+ * The decoded form of {@link FlowsConfig}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type FlowsConfig = typeof FlowsConfig.Type
+
+/**
+ * Admits the detached, recursively frozen configuration handed to plugins.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const ResolvedConfig = configurationSchema
+
+/**
+ * The decoded form of {@link ResolvedConfig}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type ResolvedConfig = typeof ResolvedConfig.Type
+
+const reservedRootKeys = new Set(["engine", "retry", "store", "plugins"])
+
+const invalid = (path: string, complaint: string): PluginError =>
+  new PluginError({
+    code: "config_invalid",
+    message: `plugin configuration ${complaint}`,
+    path
+  })
+
+const snapshotRecord = (input: unknown, reuse = true): Readonly<Record<string, ConfigValue>> => {
+  if (reuse && typeof input === "object" && input !== null && admittedConfigs.has(input)) return input as ResolvedConfig
+  const admitted = Boundary.record(input)
+  if (!admitted.ok) throw invalid(admitted.path, admitted.complaint)
+  const record = admitted.value as Readonly<Record<string, ConfigValue>>
+  for (const key of Object.keys(record)) {
+    if (reservedRootKeys.has(key)) {
+      throw invalid(`$.${key}`, "uses a runtime-policy key that the plugin kernel does not own")
+    }
+  }
+  admittedConfigs.add(record)
+  return record
+}
+
+/**
+ * Empty defaults. Engine policy is deliberately not defaulted here.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const defaults: ResolvedConfig = snapshotRecord({})
+
+/**
+ * Copies and deep-merges a configuration patch over a base configuration.
+ *
+ * Records merge key-by-key and every other JSON value replaces wholesale.
+ * Raw operands are admitted; known snapshots retain unchanged subtrees.
+ * Cached subtree totals enforce merged output bounds. Unsafe property names,
+ * accessors, cycles, exotic prototypes, and aggregate values outside the
+ * resource limits fail with `config_invalid`.
+ *
+ * @category combinators
+ * @since 1.0.0-rc.0
+ */
+export const merge = (base: FlowsConfig, patch: unknown): FlowsConfig => {
+  const safeBase = snapshotRecord(base)
+  if (patch === undefined) return safeBase
+  // Even a known patch is copied so its tree cannot alias the retained base.
+  const safePatch = snapshotRecord(patch, false)
+  const merged = Boundary.mergeRecords(safeBase, safePatch)
+  if (!merged.ok) throw invalid(merged.path, merged.complaint)
+  const record = merged.value as ResolvedConfig
+  admittedConfigs.add(record)
+  return record
+}
+
+/**
+ * Copies and freezes one JSON value without retaining caller-owned objects.
+ *
+ * @category utils
+ * @since 1.0.0-rc.0
+ */
+export const deepFreeze = <A extends ConfigValue>(value: A): A => {
+  const admitted = Boundary.admit(value)
+  if (!admitted.ok) throw invalid(admitted.path, admitted.complaint)
+  return admitted.value as A
+}
+
+/**
+ * Admits a raw pre-resolution configuration as an immutable snapshot.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const snapshot = (config: unknown): Effect.Effect<FlowsConfig, PluginError> =>
+  Effect.try({ try: () => snapshotRecord(config), catch: (cause) => cause as PluginError })
+
+/**
+ * Decodes the post-waterfall configuration into its final immutable form.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const resolve = (config: unknown): Effect.Effect<ResolvedConfig, PluginError> => snapshot(config)