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

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# @smthrs/plugin
+
+## [Unreleased]
+
+## [1.0.0-rc.0] - 2026-09-01
+
+### Added
+
+- Added the public typed plugin kernel, bounded host hook catalogs, stable
+  ordering, configuration waterfalls, observer dispatch, and layer composition.
+- Added complete `cacheEnvironment` identity for cross-run sealed reuse and a
+  package-owned generated API contract.
+- Added the optional plugin `version` field and folded selected `name@version`
+  identities into every declared cache environment.
+- Added stable runtime validation errors with value paths and published plugin,
+  handler, preset, configuration, and parallel-concurrency bounds.
+
+### Changed
+
+- Configuration now contains only plugin-owned strict JSON namespaces. Removed
+  the inert `engine`, `retry`, `store`, and `plugins` keys; runtime policy stays
+  at the Effect service or constructor that applies it.
+- Resolution now snapshots plugin records, hook entries, config, and cache
+  identity before dispatch. The public handler catalog has no mutation methods.
+- Parallel observers run at bounded concurrency, and first hooks refuse a
+  non-`Option` result instead of silently skipping it.
+- Declaring a cache environment now requires every selected plugin to provide a
+  bounded non-empty version.
+
+### Fixed
+
+- Rejected prototype-control keys, accessors, exotic objects, sparse arrays,
+  cycles, malformed runtime plugins, and inherited hook names. A proxy is read
+  through descriptor reflection alone, so only the data its traps return is
+  copied and no accessor or trap result can place behavior in an admitted value.
+- Bounded the merged output of `Config.merge`, so two individually valid
+  operands can no longer synthesize a config beyond the published byte, node,
+  member, and depth limits for a later `config` handler to observe.
+- Checked host-catalog hook names after `apply` selection again, so a shared
+  preset carrying harness-only plugins resolves under a bare engine kernel.
+  Plugin, option, and hook-entry shapes are still validated before selection,
+  and the handler bound now counts the handlers the kernel dispatches rather
+  than the handlers of plugins `apply` dropped.
+- Prevented plugins that omit a prototype-named hook from registering the
+  corresponding `Object.prototype` member as a handler.
+- Kept plugin-built sealed keys run-local while complete capability identity is
+  unknown and detached declared identity from later caller mutation.
+
+### Breaking Changes
+
+- Trimmed the published `engineHooks` catalog to the configuration lifecycle.
+  Removed hook names no longer resolve through that constant.
+- First hooks now refuse a non-`Option` result instead of silently skipping it.
+- Removed the `Config.RetryConfig` and `Config.EngineConfig` schemas and their
+  matching types. Both were root exports through `export * as Config`.
+- Retyped `Config.FlowsConfig` and `Config.ResolvedConfig` from
+  `Schema.StructWithRest` over an engine and retry struct to
+  `Schema.Record(Schema.String, Schema.Json)`. Configuration that declared those
+  policy keys now fails with `config_invalid`: `Kernel.make([], { engine: {} })`
+  refuses at path `$.engine`.
+- Narrowed `Config.merge` from `<A>(base: A, patch: unknown) => A` to
+  `(base: FlowsConfig, patch: unknown) => FlowsConfig`, and `Config.deepFreeze`
+  from `<A>(value: A) => A` to `<A extends ConfigValue>(value: A) => A`.
+- Configuration refuses an `undefined` member instead of dropping it.
+  `{ ns: { a: 1, b: undefined } }` fails `config_invalid` at path `$.ns.b`, and
+  `Config.merge({ a: 1 }, { a: undefined })` now throws that error where it
+  previously returned `{ a: 1 }`. Omit the key, or write `null`.
+- Refuses a whitespace-only plugin `name` or `version`, and a declared hook
+  entry whose value is `undefined`. All three previously resolved.
+- Cache identity percent-escapes `%` and `@` in each `name@version` layer
+  entry, so two compositions can no longer collide on one sealed identity.
+  Existing sealed entries whose plugin names or versions contain either
+  character change identity once.
+
+## [0.1.0] - 2026-08-05
+
+### Added
+
+- Added the first Vite-style typed plugin prototype.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# `@smthrs/plugin`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+This package declares `effect` as a `^4.0.4` peer dependency. Install one
+`effect` release in that range so all Smithers packages share one Effect
+runtime.
+
+**Documentation:** https://github.com/smithersai/smithers/tree/main/packages/smithers/agent/plugin/docs
+
+A typed, bounded plugin kernel for Effect programs: Vite's plugin model, with
+hooks that are ordinary Effects, ordering that follows Vite's rules exactly, and
+a resolution boundary that copies every value a caller hands it.
+
+```bash
+npm install @smthrs/plugin@next effect
+```
+
+```ts
+import { type FlowsPlugin, Kernel } from "@smthrs/plugin"
+import { Effect } from "effect"
+
+const feature: FlowsPlugin = {
+  name: "flows-plugin-feature",
+  hooks: {
+    config: () => Effect.succeed({ feature: { enabled: true } }),
+    configResolved: (config) => Effect.log(`feature enabled: ${config["feature"] !== undefined}`)
+  }
+}
+
+const kernel = await Effect.runPromise(Kernel.make([feature]))
+```
+
+`kernel.config` is the frozen configuration every plugin agreed on,
+`kernel.plugins` dispatches hooks, `kernel.layer` is every plugin's services
+merged in resolved order, and `kernel.observerErrors` holds the failures that
+`configResolved` observers reported without failing startup.
+
+## The hook catalog is yours
+
+The kernel owns one catalog of its own, the two-step config lifecycle. Every
+other hook belongs to a host: declare it with TypeScript module augmentation,
+hand the kernel the matching runtime catalog, and dispatch that catalog and
+nothing else. `FlowsHooks` is open for augmentation and closed for dispatch.
+
+```ts
+declare module "@smthrs/plugin" {
+  interface FlowsHooks {
+    readonly toolCall: SequentialHook<(ctx: ToolCallContext) => Effect.Effect<Option.Option<ToolOverride>>>
+  }
+}
+```
+
+The shipped host is the Smithers agent loop in
+[`@smthrs/agent`](https://github.com/smithersai/smithers/tree/main/packages/smithers/agent/docs), which adds three waterfalls to the
+kernel's two hooks and dispatches them around each frame of an agent cell. Both
+packages sit under the `smthrs` command line,
+[`@smthrs/cli`](https://github.com/smithersai/smithers/tree/main/packages/smithers/docs).
+
+## What it does not do
+
+This is not an engine lifecycle registry. Retry, storage, concurrency, cache,
+wait, journal, and ownership policy stay on the Effect service or constructor
+option that applies them, and configuration refuses the root keys `engine`,
+`retry`, `store`, and `plugins` so that a configuration file cannot imply
+otherwise.
+
+## Bounded by construction
+
+Plugin names compare as exact Unicode and are never normalized. Resolution
+validates every plugin record and hook entry before `apply` filtering, checks
+hook names against the host catalog for the plugins it selected, snapshots
+plugin records and hook objects, and exposes an immutable handler-map facade.
+Configuration and cache identity are detached, bounded, strict JSON snapshots:
+an `undefined` member is refused, not dropped. Mutating a caller's objects after
+startup cannot change dispatch or sealed cache keys.
+
+## Documentation
+
+- [Quickstart](https://github.com/smithersai/smithers/blob/main/packages/smithers/agent/plugin/docs/quickstart.md): build a host with a hook
+  of its own and run it.
+- [Hook kinds](https://github.com/smithersai/smithers/blob/main/packages/smithers/agent/plugin/docs/concepts/hook-kinds.md),
+  [Resolution](https://github.com/smithersai/smithers/blob/main/packages/smithers/agent/plugin/docs/concepts/resolution.md), and
+  [Configuration](https://github.com/smithersai/smithers/blob/main/packages/smithers/agent/plugin/docs/concepts/configuration.md): the model
+  behind the kernel.
+- [API reference](https://github.com/smithersai/smithers/blob/main/packages/smithers/agent/plugin/docs/api.md): every export, with
+  signatures and limits.
+- [Troubleshooting](https://github.com/smithersai/smithers/blob/main/packages/smithers/agent/plugin/docs/troubleshooting.md): every error
+  code, what causes it, and what to change.

package/dist/cjs/Config.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 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 { PluginError } from "./PluginError.ts";
+/**
+ * Maximum encoded bytes accepted for one plugin configuration.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumConfigBytes: number;
+/**
+ * Maximum nesting accepted for one plugin configuration.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumConfigDepth: number;
+/**
+ * Maximum aggregate members accepted for one plugin configuration.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumConfigMembers: number;
+/**
+ * Maximum aggregate values accepted for one plugin configuration.
+ *
+ * @category limits
+ * @since 1.0.0-rc.0
+ */
+export declare const maximumConfigNodes: number;
+/**
+ * One value accepted in a plugin-owned configuration namespace.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const ConfigValue: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+/**
+ * One value accepted in a plugin-owned configuration namespace.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type ConfigValue = typeof ConfigValue.Type;
+/**
+ * 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 declare const FlowsConfig: Schema.decodeTo<Schema.declare<Readonly<Record<string, Schema.Json>>, Readonly<Record<string, Schema.Json>>>, Schema.Unknown, never, never>;
+/**
+ * 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 declare const ResolvedConfig: Schema.decodeTo<Schema.declare<Readonly<Record<string, Schema.Json>>, Readonly<Record<string, Schema.Json>>>, Schema.Unknown, never, never>;
+/**
+ * The decoded form of {@link ResolvedConfig}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type ResolvedConfig = typeof ResolvedConfig.Type;
+/**
+ * Empty defaults. Engine policy is deliberately not defaulted here.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const defaults: ResolvedConfig;
+/**
+ * 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 declare const merge: (base: FlowsConfig, patch: unknown) => FlowsConfig;
+/**
+ * Copies and freezes one JSON value without retaining caller-owned objects.
+ *
+ * @category utils
+ * @since 1.0.0-rc.0
+ */
+export declare const deepFreeze: <A extends ConfigValue>(value: A) => A;
+/**
+ * Admits a raw pre-resolution configuration as an immutable snapshot.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const snapshot: (config: unknown) => Effect.Effect<FlowsConfig, PluginError>;
+/**
+ * Decodes the post-waterfall configuration into its final immutable form.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const resolve: (config: unknown) => Effect.Effect<ResolvedConfig, PluginError>;
+//# sourceMappingURL=Config.d.ts.map

package/dist/cjs/Config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Config.d.ts","sourceRoot":"","sources":["../../src/Config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAIvC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAAkC,CAAA;AAEjE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAAkC,CAAA;AAEjE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,QAAoC,CAAA;AAErE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAAkC,CAAA;AAEjE;;;;;GAKG;AACH,eAAO,MAAM,WAAW,sDAAc,CAAA;AAEtC;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAwBjD;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,6IAAsB,CAAA;AAE9C;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,6IAAsB,CAAA;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAyBvD;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,cAAmC,CAAA;AAE1D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,GAAI,MAAM,WAAW,EAAE,OAAO,OAAO,KAAG,WAUzD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,WAAW,EAAE,OAAO,CAAC,KAAG,CAI5D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAI,QAAQ,OAAO,KAAG,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,WAAW,CACU,CAAA;AAE3F;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,QAAQ,OAAO,KAAG,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,WAAW,CAAqB,CAAA"}

package/dist/cjs/Config.js

@@ -0,0 +1,115 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Config_exports = {};
+__export(Config_exports, {
+  ConfigValue: () => ConfigValue,
+  FlowsConfig: () => FlowsConfig,
+  ResolvedConfig: () => ResolvedConfig,
+  deepFreeze: () => deepFreeze,
+  defaults: () => defaults,
+  maximumConfigBytes: () => maximumConfigBytes,
+  maximumConfigDepth: () => maximumConfigDepth,
+  maximumConfigMembers: () => maximumConfigMembers,
+  maximumConfigNodes: () => maximumConfigNodes,
+  merge: () => merge,
+  resolve: () => resolve,
+  snapshot: () => snapshot
+});
+module.exports = __toCommonJS(Config_exports);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var SchemaGetter = __toESM(require("effect/SchemaGetter"), 1);
+var SchemaIssue = __toESM(require("effect/SchemaIssue"), 1);
+var Boundary = __toESM(require("./internal/Boundary.js"), 1);
+var import_PluginError = require("./PluginError.js");
+const maximumConfigBytes = Boundary.defaultLimits.maxBytes;
+const maximumConfigDepth = Boundary.defaultLimits.maxDepth;
+const maximumConfigMembers = Boundary.defaultLimits.maxMembers;
+const maximumConfigNodes = Boundary.defaultLimits.maxNodes;
+const ConfigValue = Schema.Json;
+const admittedConfigs = /* @__PURE__ */ new WeakSet();
+const configurationSchema = Schema.Unknown.pipe(
+  Schema.decodeTo(
+    Schema.declare(
+      (value) => typeof value === "object" && value !== null && admittedConfigs.has(value)
+    ),
+    {
+      decode: SchemaGetter.transformEffect(
+        (value) => Effect.try({
+          try: () => snapshotRecord(value),
+          catch: (cause) => {
+            const error = cause;
+            return new SchemaIssue.InvalidValue({ message: `${error.path}: ${error.message}` });
+          }
+        })
+      ),
+      encode: SchemaGetter.transform((value) => value)
+    }
+  )
+);
+const FlowsConfig = configurationSchema;
+const ResolvedConfig = configurationSchema;
+const reservedRootKeys = /* @__PURE__ */ new Set(["engine", "retry", "store", "plugins"]);
+const invalid = (path, complaint) => new import_PluginError.PluginError({
+  code: "config_invalid",
+  message: `plugin configuration ${complaint}`,
+  path
+});
+const snapshotRecord = (input, reuse = true) => {
+  if (reuse && typeof input === "object" && input !== null && admittedConfigs.has(input)) return input;
+  const admitted = Boundary.record(input);
+  if (!admitted.ok) throw invalid(admitted.path, admitted.complaint);
+  const record = admitted.value;
+  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;
+};
+const defaults = snapshotRecord({});
+const merge = (base, patch) => {
+  const safeBase = snapshotRecord(base);
+  if (patch === void 0) return safeBase;
+  const safePatch = snapshotRecord(patch, false);
+  const merged = Boundary.mergeRecords(safeBase, safePatch);
+  if (!merged.ok) throw invalid(merged.path, merged.complaint);
+  const record = merged.value;
+  admittedConfigs.add(record);
+  return record;
+};
+const deepFreeze = (value) => {
+  const admitted = Boundary.admit(value);
+  if (!admitted.ok) throw invalid(admitted.path, admitted.complaint);
+  return admitted.value;
+};
+const snapshot = (config) => Effect.try({ try: () => snapshotRecord(config), catch: (cause) => cause });
+const resolve = (config) => snapshot(config);
+//# sourceMappingURL=Config.js.map

package/dist/cjs/Config.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Config.ts"],
+  "sourcesContent": ["/**\n * Bounded JSON configuration consumed and produced by the plugin kernel.\n *\n * Configuration is an extension namespace, not an engine-policy surface.\n * Durable retry, concurrency, and storage policy stay on their owning Effect\n * services and constructor options. Every accepted value is copied before any\n * plugin observes it, then frozen recursively.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport * as SchemaGetter from \"effect/SchemaGetter\"\nimport * as SchemaIssue from \"effect/SchemaIssue\"\nimport * as Boundary from \"./internal/Boundary.ts\"\nimport { PluginError } from \"./PluginError.ts\"\n\n/**\n * Maximum encoded bytes accepted for one plugin configuration.\n *\n * @category limits\n * @since 1.0.0-rc.0\n */\nexport const maximumConfigBytes = Boundary.defaultLimits.maxBytes\n\n/**\n * Maximum nesting accepted for one plugin configuration.\n *\n * @category limits\n * @since 1.0.0-rc.0\n */\nexport const maximumConfigDepth = Boundary.defaultLimits.maxDepth\n\n/**\n * Maximum aggregate members accepted for one plugin configuration.\n *\n * @category limits\n * @since 1.0.0-rc.0\n */\nexport const maximumConfigMembers = Boundary.defaultLimits.maxMembers\n\n/**\n * Maximum aggregate values accepted for one plugin configuration.\n *\n * @category limits\n * @since 1.0.0-rc.0\n */\nexport const maximumConfigNodes = Boundary.defaultLimits.maxNodes\n\n/**\n * One value accepted in a plugin-owned configuration namespace.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const ConfigValue = Schema.Json\n\n/**\n * One value accepted in a plugin-owned configuration namespace.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type ConfigValue = typeof ConfigValue.Type\n\nconst admittedConfigs = new WeakSet<object>()\n\nconst configurationSchema = Schema.Unknown.pipe(\n  Schema.decodeTo(\n    Schema.declare<Readonly<Record<string, ConfigValue>>>((value): value is Readonly<Record<string, ConfigValue>> =>\n      typeof value === \"object\" && value !== null && admittedConfigs.has(value)\n    ),\n    {\n      decode: SchemaGetter.transformEffect((value) =>\n        Effect.try({\n          try: () => snapshotRecord(value),\n          catch: (cause) => {\n            const error = cause as PluginError\n            return new SchemaIssue.InvalidValue({ message: `${error.path}: ${error.message}` })\n          }\n        })\n      ),\n      encode: SchemaGetter.transform((value) => value)\n    }\n  )\n)\n\n/**\n * Admits pre-resolution configuration as a detached, recursively frozen snapshot.\n *\n * Keys name plugin-owned namespaces. `engine`, `retry`, `store`, and\n * `plugins` are refused because accepting those names would imply policy the\n * plugin kernel does not own or apply.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const FlowsConfig = configurationSchema\n\n/**\n * The decoded form of {@link FlowsConfig}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type FlowsConfig = typeof FlowsConfig.Type\n\n/**\n * Admits the detached, recursively frozen configuration handed to plugins.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const ResolvedConfig = configurationSchema\n\n/**\n * The decoded form of {@link ResolvedConfig}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type ResolvedConfig = typeof ResolvedConfig.Type\n\nconst reservedRootKeys = new Set([\"engine\", \"retry\", \"store\", \"plugins\"])\n\nconst invalid = (path: string, complaint: string): PluginError =>\n  new PluginError({\n    code: \"config_invalid\",\n    message: `plugin configuration ${complaint}`,\n    path\n  })\n\nconst snapshotRecord = (input: unknown, reuse = true): Readonly<Record<string, ConfigValue>> => {\n  if (reuse && typeof input === \"object\" && input !== null && admittedConfigs.has(input)) return input as ResolvedConfig\n  const admitted = Boundary.record(input)\n  if (!admitted.ok) throw invalid(admitted.path, admitted.complaint)\n  const record = admitted.value as Readonly<Record<string, ConfigValue>>\n  for (const key of Object.keys(record)) {\n    if (reservedRootKeys.has(key)) {\n      throw invalid(`$.${key}`, \"uses a runtime-policy key that the plugin kernel does not own\")\n    }\n  }\n  admittedConfigs.add(record)\n  return record\n}\n\n/**\n * Empty defaults. Engine policy is deliberately not defaulted here.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const defaults: ResolvedConfig = snapshotRecord({})\n\n/**\n * Copies and deep-merges a configuration patch over a base configuration.\n *\n * Records merge key-by-key and every other JSON value replaces wholesale.\n * Raw operands are admitted; known snapshots retain unchanged subtrees.\n * Cached subtree totals enforce merged output bounds. Unsafe property names,\n * accessors, cycles, exotic prototypes, and aggregate values outside the\n * resource limits fail with `config_invalid`.\n *\n * @category combinators\n * @since 1.0.0-rc.0\n */\nexport const merge = (base: FlowsConfig, patch: unknown): FlowsConfig => {\n  const safeBase = snapshotRecord(base)\n  if (patch === undefined) return safeBase\n  // Even a known patch is copied so its tree cannot alias the retained base.\n  const safePatch = snapshotRecord(patch, false)\n  const merged = Boundary.mergeRecords(safeBase, safePatch)\n  if (!merged.ok) throw invalid(merged.path, merged.complaint)\n  const record = merged.value as ResolvedConfig\n  admittedConfigs.add(record)\n  return record\n}\n\n/**\n * Copies and freezes one JSON value without retaining caller-owned objects.\n *\n * @category utils\n * @since 1.0.0-rc.0\n */\nexport const deepFreeze = <A extends ConfigValue>(value: A): A => {\n  const admitted = Boundary.admit(value)\n  if (!admitted.ok) throw invalid(admitted.path, admitted.complaint)\n  return admitted.value as A\n}\n\n/**\n * Admits a raw pre-resolution configuration as an immutable snapshot.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const snapshot = (config: unknown): Effect.Effect<FlowsConfig, PluginError> =>\n  Effect.try({ try: () => snapshotRecord(config), catch: (cause) => cause as PluginError })\n\n/**\n * Decodes the post-waterfall configuration into its final immutable form.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const resolve = (config: unknown): Effect.Effect<ResolvedConfig, PluginError> => snapshot(config)\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,aAAwB;AACxB,aAAwB;AACxB,mBAA8B;AAC9B,kBAA6B;AAC7B,eAA0B;AAC1B,yBAA4B;AAQrB,MAAM,qBAAqB,SAAS,cAAc;AAQlD,MAAM,qBAAqB,SAAS,cAAc;AAQlD,MAAM,uBAAuB,SAAS,cAAc;AAQpD,MAAM,qBAAqB,SAAS,cAAc;AAQlD,MAAM,cAAc,OAAO;AAUlC,MAAM,kBAAkB,oBAAI,QAAgB;AAE5C,MAAM,sBAAsB,OAAO,QAAQ;AAAA,EACzC,OAAO;AAAA,IACL,OAAO;AAAA,MAA+C,CAAC,UACrD,OAAO,UAAU,YAAY,UAAU,QAAQ,gBAAgB,IAAI,KAAK;AAAA,IAC1E;AAAA,IACA;AAAA,MACE,QAAQ,aAAa;AAAA,QAAgB,CAAC,UACpC,OAAO,IAAI;AAAA,UACT,KAAK,MAAM,eAAe,KAAK;AAAA,UAC/B,OAAO,CAAC,UAAU;AAChB,kBAAM,QAAQ;AACd,mBAAO,IAAI,YAAY,aAAa,EAAE,SAAS,GAAG,MAAM,IAAI,KAAK,MAAM,OAAO,GAAG,CAAC;AAAA,UACpF;AAAA,QACF,CAAC;AAAA,MACH;AAAA,MACA,QAAQ,aAAa,UAAU,CAAC,UAAU,KAAK;AAAA,IACjD;AAAA,EACF;AACF;AAYO,MAAM,cAAc;AAgBpB,MAAM,iBAAiB;AAU9B,MAAM,mBAAmB,oBAAI,IAAI,CAAC,UAAU,SAAS,SAAS,SAAS,CAAC;AAExE,MAAM,UAAU,CAAC,MAAc,cAC7B,IAAI,+BAAY;AAAA,EACd,MAAM;AAAA,EACN,SAAS,wBAAwB,SAAS;AAAA,EAC1C;AACF,CAAC;AAEH,MAAM,iBAAiB,CAAC,OAAgB,QAAQ,SAAgD;AAC9F,MAAI,SAAS,OAAO,UAAU,YAAY,UAAU,QAAQ,gBAAgB,IAAI,KAAK,EAAG,QAAO;AAC/F,QAAM,WAAW,SAAS,OAAO,KAAK;AACtC,MAAI,CAAC,SAAS,GAAI,OAAM,QAAQ,SAAS,MAAM,SAAS,SAAS;AACjE,QAAM,SAAS,SAAS;AACxB,aAAW,OAAO,OAAO,KAAK,MAAM,GAAG;AACrC,QAAI,iBAAiB,IAAI,GAAG,GAAG;AAC7B,YAAM,QAAQ,KAAK,GAAG,IAAI,+DAA+D;AAAA,IAC3F;AAAA,EACF;AACA,kBAAgB,IAAI,MAAM;AAC1B,SAAO;AACT;AAQO,MAAM,WAA2B,eAAe,CAAC,CAAC;AAclD,MAAM,QAAQ,CAAC,MAAmB,UAAgC;AACvE,QAAM,WAAW,eAAe,IAAI;AACpC,MAAI,UAAU,OAAW,QAAO;AAEhC,QAAM,YAAY,eAAe,OAAO,KAAK;AAC7C,QAAM,SAAS,SAAS,aAAa,UAAU,SAAS;AACxD,MAAI,CAAC,OAAO,GAAI,OAAM,QAAQ,OAAO,MAAM,OAAO,SAAS;AAC3D,QAAM,SAAS,OAAO;AACtB,kBAAgB,IAAI,MAAM;AAC1B,SAAO;AACT;AAQO,MAAM,aAAa,CAAwB,UAAgB;AAChE,QAAM,WAAW,SAAS,MAAM,KAAK;AACrC,MAAI,CAAC,SAAS,GAAI,OAAM,QAAQ,SAAS,MAAM,SAAS,SAAS;AACjE,SAAO,SAAS;AAClB;AAQO,MAAM,WAAW,CAAC,WACvB,OAAO,IAAI,EAAE,KAAK,MAAM,eAAe,MAAM,GAAG,OAAO,CAAC,UAAU,MAAqB,CAAC;AAQnF,MAAM,UAAU,CAAC,WAAgE,SAAS,MAAM;",
+  "names": []
+}

package/dist/cjs/Hooks.d.ts

@@ -0,0 +1,176 @@
+/**
+ * The typed hook surface: hook kinds, the hook entry shape, and the shared
+ * kernel's base hook catalog.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}. The shared catalog is limited to
+ * `config` and `configResolved`;
+ * `@smthrs/agent` adds only `cellRegistry`, `cellFlows`, and
+ * `cellModelRequest`. Durable-core lifecycle policy is not a hook catalog.
+ *
+ * `FlowsHooks` is **open for augmentation, closed for dispatch**: a host
+ * declares its hooks with `declare module "@smthrs/plugin"`, supplies the
+ * matching runtime catalog, and dispatches only that bounded set.
+ *
+ * @since 1.0.0-rc.0
+ */
+import type * as Effect from "effect/Effect";
+/**
+ * Dispatch semantics of a hook, fixed by the core.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type HookKind = "sequential" | "parallel" | "first" | "waterfall";
+declare const HookTypeId: unique symbol;
+/**
+ * Phantom carrier that records a hook's kind and handler type in the type
+ * system without adding anything at runtime.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface HookMeta<K extends HookKind, F> {
+    readonly [HookTypeId]?: {
+        readonly kind: K;
+        readonly handler: F;
+    };
+}
+/**
+ * The object form of a hook entry: Vite's per-hook ordering object, verbatim.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface HookObject<F> {
+    readonly order?: "pre" | "post" | undefined;
+    readonly handler: F;
+}
+/**
+ * A hook entry is either the bare handler or `{ order?, handler }`.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type HookEntry<K extends HookKind, F> = (F | HookObject<F>) & HookMeta<K, F>;
+/**
+ * Every handler runs, in resolved order, one at a time.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type SequentialHook<F> = HookEntry<"sequential", F>;
+/**
+ * Every handler runs concurrently; results are ignored and failures are
+ * returned to the caller rather than failing it.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type ParallelHook<F> = HookEntry<"parallel", F>;
+/**
+ * Handlers run in order until one returns `Option.some`.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type FirstHook<F> = HookEntry<"first", F>;
+/**
+ * Each handler receives the previous handler's output.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type WaterfallHook<F> = HookEntry<"waterfall", F>;
+/**
+ * Extracts the declared kind of a hook entry type.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type KindOf<T> = T extends HookMeta<infer K, any> ? K : never;
+/**
+ * The runtime catalog a host supplies for a hook interface: each hook name
+ * mapped to its kind. A name declared in `H` must carry the kind its type
+ * declares. Names outside `H` are admitted with any kind, because the type
+ * system cannot enumerate an augmentable interface; resolution checks them
+ * at runtime and dispatch refuses a kind that disagrees with the catalog.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type HookCatalog<H> = {
+    readonly [K in keyof H & string]?: KindOf<H[K]>;
+} & {
+    readonly [name: string]: HookKind | undefined;
+};
+/**
+ * Extracts the handler type of a hook entry type.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type HandlerOf<T> = T extends HookMeta<any, infer F> ? F : never;
+/**
+ * Selects the hook names of a given kind from a hook interface.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type KeysOfKind<H, K extends HookKind> = {
+    [P in keyof H]: KindOf<H[P]> extends K ? P : never;
+}[keyof H] & string;
+/**
+ * Extracts the positional argument tuple accepted by a hook entry.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type ArgsOf<T> = HandlerOf<T> extends (...args: infer A) => any ? A : never;
+/**
+ * Extracts the Effect returned by a hook entry.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type ReturnOf<T> = HandlerOf<T> extends (...args: any) => infer R ? R : never;
+/**
+ * Extracts the success value returned by a hook entry's Effect.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type SuccessOf<T> = ReturnOf<T> extends Effect.Effect<infer A, any, any> ? A : never;
+/**
+ * Extracts the context required by a hook entry's Effect.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type ContextOf<T> = ReturnOf<T> extends Effect.Effect<any, any, infer R> ? R : never;
+/**
+ * Frozen runtime catalog for the shared configuration hooks.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const engineHooks: Readonly<{
+    readonly config: "waterfall";
+    readonly configResolved: "parallel";
+}>;
+/**
+ * Normalizes a hook entry to its handler.
+ *
+ * @category utils
+ * @since 1.0.0-rc.0
+ */
+export declare const handlerOf: (entry: unknown) => (...args: Array<any>) => unknown;
+/**
+ * Reads the per-hook `order` of a hook entry.
+ *
+ * @category utils
+ * @since 1.0.0-rc.0
+ */
+export declare const orderOf: (entry: unknown) => "pre" | "post" | undefined;
+export {};
+//# sourceMappingURL=Hooks.d.ts.map

package/dist/cjs/Hooks.d.ts.map

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