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

package/dist/esm/Plugin.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The plugin object: a plain record produced by a factory function.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}. The shipped consumer is the
+ * assembled cell host in `@smthrs/agent`;
+ * durable-core policy continues to use Effect services and constructor
+ * options rather than plugin lifecycle hooks.
+ *
+ * @since 1.0.0-rc.0
+ */
+import type * as Layer from "effect/Layer";
+import type { FlowsConfig } from "./Config.ts";
+import type { FlowsHooks } from "./index.ts";
+/**
+ * Conditional-inclusion predicate, mirroring Vite's `apply`.
+ *
+ * `"engine"` and `"harness"` select the matching plugin-kernel host. The
+ * assembled cell host resolves as `"harness"`; this does not make `"engine"` an
+ * engine-lifecycle hook registration.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type Apply = "engine" | "harness" | ((config: FlowsConfig) => boolean);
+/**
+ * A flows plugin.
+ *
+ * Generic over the hook interface so a harness can hold plugins typed against
+ * its augmented `FlowsHooks` without any inheritance machinery.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface FlowsPlugin<H = FlowsHooks> {
+    /** Required, unique. Convention: `flows-plugin-<thing>`. */
+    readonly name: string;
+    /**
+     * Semantic identity folded into sealed cache keys. Required when the host
+     * declares a cache environment. `Action.CacheEnvironment` is complete by
+     * contract, so a versionless composition is refused instead of claiming an
+     * ambiguous cross-run identity.
+     */
+    readonly version?: string | undefined;
+    /** Ordering group; omitted means `"normal"`. */
+    readonly enforce?: "pre" | "post" | undefined;
+    /** Conditional inclusion. */
+    readonly apply?: Apply | undefined;
+    /** Services this plugin contributes to the engine environment. */
+    readonly layer?: Layer.Layer<never, any, any> | undefined;
+    /** Typed hooks; only keys declared in the hook interface compile. */
+    readonly hooks?: Partial<H> | undefined;
+}
+/**
+ * What a `plugins` array may contain: plugins, falsy entries, and arrays nested
+ * up to `Resolve.maximumPluginDepth`: so a preset is just a function returning
+ * plugins.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type PluginInput<H = FlowsHooks> = FlowsPlugin<H> | false | null | undefined | ReadonlyArray<PluginInput<H>>;
+/**
+ * Identity constructor that pins a plugin literal to `FlowsPlugin` so excess
+ * hook keys are rejected at the definition site.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const make: <H = FlowsHooks>(plugin: FlowsPlugin<H>) => FlowsPlugin<H>;
+//# sourceMappingURL=Plugin.d.ts.map

package/dist/esm/Plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin.d.ts","sourceRoot":"","sources":["../../src/Plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;;;;;;;;GASG;AACH,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,CAAC,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAA;AAE7E;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,UAAU;IACzC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,gDAAgD;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAAA;IAC7C,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAA;IAClC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,SAAS,CAAA;IACzD,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;CACxC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,UAAU,IAClC,WAAW,CAAC,CAAC,CAAC,GACd,KAAK,GACL,IAAI,GACJ,SAAS,GACT,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,GAAG,UAAU,EAAE,QAAQ,WAAW,CAAC,CAAC,CAAC,KAAG,WAAW,CAAC,CAAC,CAAW,CAAA"}

package/dist/esm/Plugin.js

@@ -0,0 +1,20 @@
+/**
+ * The plugin object: a plain record produced by a factory function.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}. The shipped consumer is the
+ * assembled cell host in `@smthrs/agent`;
+ * durable-core policy continues to use Effect services and constructor
+ * options rather than plugin lifecycle hooks.
+ *
+ * @since 1.0.0-rc.0
+ */
+/**
+ * Identity constructor that pins a plugin literal to `FlowsPlugin` so excess
+ * hook keys are rejected at the definition site.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const make = (plugin) => plugin;
+//# sourceMappingURL=Plugin.js.map

package/dist/esm/Plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin.js","sourceRoot":"","sources":["../../src/Plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8DH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAiB,MAAsB,EAAkB,EAAE,CAAC,MAAM,CAAA","sourcesContent":["/**\n * The plugin object: a plain record produced by a factory function.\n *\n * The public package contract is documented at\n * {@link https://smithers.sh/docs/reference/api/plugin}. The shipped consumer is the\n * assembled cell host in `@smthrs/agent`;\n * durable-core policy continues to use Effect services and constructor\n * options rather than plugin lifecycle hooks.\n *\n * @since 1.0.0-rc.0\n */\n\nimport type * as Layer from \"effect/Layer\"\nimport type { FlowsConfig } from \"./Config.ts\"\nimport type { FlowsHooks } from \"./index.ts\"\n\n/**\n * Conditional-inclusion predicate, mirroring Vite's `apply`.\n *\n * `\"engine\"` and `\"harness\"` select the matching plugin-kernel host. The\n * assembled cell host resolves as `\"harness\"`; this does not make `\"engine\"` an\n * engine-lifecycle hook registration.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Apply = \"engine\" | \"harness\" | ((config: FlowsConfig) => boolean)\n\n/**\n * A flows plugin.\n *\n * Generic over the hook interface so a harness can hold plugins typed against\n * its augmented `FlowsHooks` without any inheritance machinery.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface FlowsPlugin<H = FlowsHooks> {\n  /** Required, unique. Convention: `flows-plugin-<thing>`. */\n  readonly name: string\n  /**\n   * Semantic identity folded into sealed cache keys. Required when the host\n   * declares a cache environment. `Action.CacheEnvironment` is complete by\n   * contract, so a versionless composition is refused instead of claiming an\n   * ambiguous cross-run identity.\n   */\n  readonly version?: string | undefined\n  /** Ordering group; omitted means `\"normal\"`. */\n  readonly enforce?: \"pre\" | \"post\" | undefined\n  /** Conditional inclusion. */\n  readonly apply?: Apply | undefined\n  /** Services this plugin contributes to the engine environment. */\n  readonly layer?: Layer.Layer<never, any, any> | undefined\n  /** Typed hooks; only keys declared in the hook interface compile. */\n  readonly hooks?: Partial<H> | undefined\n}\n\n/**\n * What a `plugins` array may contain: plugins, falsy entries, and arrays nested\n * up to `Resolve.maximumPluginDepth`: so a preset is just a function returning\n * plugins.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type PluginInput<H = FlowsHooks> =\n  | FlowsPlugin<H>\n  | false\n  | null\n  | undefined\n  | ReadonlyArray<PluginInput<H>>\n\n/**\n * Identity constructor that pins a plugin literal to `FlowsPlugin` so excess\n * hook keys are rejected at the definition site.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const make = <H = FlowsHooks>(plugin: FlowsPlugin<H>): FlowsPlugin<H> => plugin\n"]}

package/dist/esm/PluginError.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The single typed failure of the plugin kernel.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}; D14 in
+ * `docs/pages/design-decisions.md` bounds it to host-owned cell hooks.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * Closed set of plugin-system failure codes.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const PluginErrorCode: Schema.Literals<readonly ["duplicate_name", "unknown_hook", "hook_kind_mismatch", "invalid_plugin", "apply_failed", "config_invalid", "cache_environment_invalid", "invalid_hook_result", "resource_limit", "hook_failed", "layer_failed"]>;
+/**
+ * Closed set of plugin-system failure codes.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type PluginErrorCode = typeof PluginErrorCode.Type;
+declare const PluginError_base: Schema.Class<PluginError, Schema.TaggedStruct<"flows/plugin/PluginError", {
+    readonly code: Schema.Literals<readonly ["duplicate_name", "unknown_hook", "hook_kind_mismatch", "invalid_plugin", "apply_failed", "config_invalid", "cache_environment_invalid", "invalid_hook_result", "resource_limit", "hook_failed", "layer_failed"]>;
+    readonly message: Schema.String;
+    readonly plugin: Schema.optional<Schema.String>;
+    readonly hook: Schema.optional<Schema.String>;
+    readonly path: Schema.optional<Schema.String>;
+    readonly cause: Schema.optional<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Failure raised by plugin resolution, hook dispatch, config execution, or
+ * layer construction.
+ *
+ * Parallel observer failures never fail the caller; they are returned from
+ * `Plugins.parallel` with this same shape so they can be journalled on the
+ * lossy telemetry channel.
+ *
+ * `cause` is the plugin's unredacted failure and may hold secrets; hosts
+ * redact it before logging, persisting, or transmitting the error.
+ *
+ * @category errors
+ * @since 1.0.0-rc.0
+ */
+export declare class PluginError extends PluginError_base {
+}
+export {};
+//# sourceMappingURL=PluginError.d.ts.map

package/dist/esm/PluginError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginError.d.ts","sourceRoot":"","sources":["../../src/PluginError.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,eAAe,6OAY1B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;;;;;;;;;AAEzD;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAY,SAAQ,gBAO/B;CAAG"}

package/dist/esm/PluginError.js

@@ -0,0 +1,53 @@
+/**
+ * The single typed failure of the plugin kernel.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}; D14 in
+ * `docs/pages/design-decisions.md` bounds it to host-owned cell hooks.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * Closed set of plugin-system failure codes.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const PluginErrorCode = Schema.Literals([
+    "duplicate_name",
+    "unknown_hook",
+    "hook_kind_mismatch",
+    "invalid_plugin",
+    "apply_failed",
+    "config_invalid",
+    "cache_environment_invalid",
+    "invalid_hook_result",
+    "resource_limit",
+    "hook_failed",
+    "layer_failed"
+]);
+/**
+ * Failure raised by plugin resolution, hook dispatch, config execution, or
+ * layer construction.
+ *
+ * Parallel observer failures never fail the caller; they are returned from
+ * `Plugins.parallel` with this same shape so they can be journalled on the
+ * lossy telemetry channel.
+ *
+ * `cause` is the plugin's unredacted failure and may hold secrets; hosts
+ * redact it before logging, persisting, or transmitting the error.
+ *
+ * @category errors
+ * @since 1.0.0-rc.0
+ */
+export class PluginError extends Schema.TaggedError()("flows/plugin/PluginError", {
+    code: PluginErrorCode,
+    message: Schema.String,
+    plugin: Schema.optional(Schema.String),
+    hook: Schema.optional(Schema.String),
+    path: Schema.optional(Schema.String),
+    cause: Schema.optional(Schema.Unknown)
+}) {
+}
+//# sourceMappingURL=PluginError.js.map

package/dist/esm/PluginError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginError.js","sourceRoot":"","sources":["../../src/PluginError.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC7C,gBAAgB;IAChB,cAAc;IACd,oBAAoB;IACpB,gBAAgB;IAChB,cAAc;IACd,gBAAgB;IAChB,2BAA2B;IAC3B,qBAAqB;IACrB,gBAAgB;IAChB,aAAa;IACb,cAAc;CACf,CAAC,CAAA;AAUF;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,WAAY,SAAQ,MAAM,CAAC,WAAW,EAAe,CAAC,0BAA0B,EAAE;IAC7F,IAAI,EAAE,eAAe;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACpC,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC;CACvC,CAAC;CAAG","sourcesContent":["/**\n * The single typed failure of the plugin kernel.\n *\n * The public package contract is documented at\n * {@link https://smithers.sh/docs/reference/api/plugin}; D14 in\n * `docs/pages/design-decisions.md` bounds it to host-owned cell hooks.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Schema from \"effect/Schema\"\n\n/**\n * Closed set of plugin-system failure codes.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const PluginErrorCode = Schema.Literals([\n  \"duplicate_name\",\n  \"unknown_hook\",\n  \"hook_kind_mismatch\",\n  \"invalid_plugin\",\n  \"apply_failed\",\n  \"config_invalid\",\n  \"cache_environment_invalid\",\n  \"invalid_hook_result\",\n  \"resource_limit\",\n  \"hook_failed\",\n  \"layer_failed\"\n])\n\n/**\n * Closed set of plugin-system failure codes.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type PluginErrorCode = typeof PluginErrorCode.Type\n\n/**\n * Failure raised by plugin resolution, hook dispatch, config execution, or\n * layer construction.\n *\n * Parallel observer failures never fail the caller; they are returned from\n * `Plugins.parallel` with this same shape so they can be journalled on the\n * lossy telemetry channel.\n *\n * `cause` is the plugin's unredacted failure and may hold secrets; hosts\n * redact it before logging, persisting, or transmitting the error.\n *\n * @category errors\n * @since 1.0.0-rc.0\n */\nexport class PluginError extends Schema.TaggedError<PluginError>()(\"flows/plugin/PluginError\", {\n  code: PluginErrorCode,\n  message: Schema.String,\n  plugin: Schema.optional(Schema.String),\n  hook: Schema.optional(Schema.String),\n  path: Schema.optional(Schema.String),\n  cause: Schema.optional(Schema.Unknown)\n}) {}\n"]}

package/dist/esm/Plugins.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The dispatcher: a plain service over a resolved plugin list, generic over the
+ * hook interface.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}. Each host holds an instance over its
+ * augmented `FlowsHooks` and may dispatch only the runtime catalog it supplied.
+ * The shipped cell host owns the three
+ * waterfalls declared in `packages/smithers/agent/src/CellPlugin.ts`; there is
+ * no engine-wide lifecycle dispatcher.
+ *
+ * Cancellation is fiber interruption via scope closure; nothing here threads an
+ * `AbortSignal`.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { ArgsOf, ContextOf, KeysOfKind, SuccessOf } from "./Hooks.ts";
+import type { FlowsHooks } from "./index.ts";
+import { PluginError } from "./PluginError.ts";
+import { type HandlerRecord, type Resolved } from "./Resolve.ts";
+/**
+ * The dispatch surface.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Service<H = FlowsHooks> {
+    /** The resolved list this dispatcher walks. */
+    readonly resolved: Resolved<H>;
+    /** Frozen, ordered handler records for a hook. */
+    readonly handlers: (hook: string) => ReadonlyArray<HandlerRecord>;
+    /** Runs every handler in resolved order, one at a time. */
+    readonly sequential: <K extends KeysOfKind<H, "sequential">>(hook: K, ...args: ArgsOf<H[K]>) => Effect.Effect<ReadonlyArray<SuccessOf<H[K]>>, PluginError, ContextOf<H[K]>>;
+    /**
+     * Runs every handler concurrently, ignoring results. Never fails: handler
+     * failures are returned so the caller can report them at its own boundary.
+     */
+    readonly parallel: <K extends KeysOfKind<H, "parallel">>(hook: K, ...args: ArgsOf<H[K]>) => Effect.Effect<ReadonlyArray<PluginError>, never, ContextOf<H[K]>>;
+    /** Runs handlers in order until one returns `Option.some`. */
+    readonly first: <K extends KeysOfKind<H, "first">>(hook: K, ...args: ArgsOf<H[K]>) => Effect.Effect<SuccessOf<H[K]>, PluginError, ContextOf<H[K]>>;
+    /** Threads a value through every handler, merging each returned patch. */
+    readonly waterfall: <K extends KeysOfKind<H, "waterfall">>(hook: K, initial: ArgsOf<H[K]>[0], merge: (previous: ArgsOf<H[K]>[0], patch: Exclude<SuccessOf<H[K]>, void>) => ArgsOf<H[K]>[0]) => Effect.Effect<ArgsOf<H[K]>[0], PluginError, ContextOf<H[K]>>;
+}
+/**
+ * Builds a dispatcher over an already resolved plugin list.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const make: <H = FlowsHooks>(resolved: Resolved<H>) => Service<H>;
+/**
+ * A dispatcher with no plugins at all.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const makeNoop: <H = FlowsHooks>() => Service<H>;
+declare const Plugins_base: Context.ServiceClass<Plugins, "flows/plugin/Plugins", Service<FlowsHooks>>;
+/**
+ * The shared dispatcher, as a service tag.
+ *
+ * This tag holds one dispatcher over the process-wide augmented `FlowsHooks`.
+ * `declare module "@smthrs/plugin"` augmentation is the supported extension
+ * mechanism for values placed in the tag. A host typed against a separate hook
+ * interface holds its `Service<H>` directly, as `@smthrs/agent` does, and does
+ * not use this tag or its layers.
+ *
+ * @category context
+ * @since 1.0.0-rc.0
+ */
+export declare class Plugins extends Plugins_base {
+}
+/**
+ * Layer providing a dispatcher over an already resolved plugin list.
+ *
+ * This layer targets the shared augmented `FlowsHooks` catalog only. A host
+ * with a separate hook interface holds its `Service<H>` directly.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layer: (resolved: Resolved) => Layer.Layer<Plugins>;
+/**
+ * Layer providing a dispatcher with no plugins.
+ *
+ * This layer targets the shared augmented `FlowsHooks` catalog only. A host
+ * with a separate hook interface holds its `Service<H>` directly.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export declare const layerNoop: Layer.Layer<Plugins>;
+export {};
+//# sourceMappingURL=Plugins.d.ts.map

package/dist/esm/Plugins.d.ts.map

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

package/dist/esm/Plugins.js

@@ -0,0 +1,190 @@
+/**
+ * The dispatcher: a plain service over a resolved plugin list, generic over the
+ * hook interface.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}. Each host holds an instance over its
+ * augmented `FlowsHooks` and may dispatch only the runtime catalog it supplied.
+ * The shipped cell host owns the three
+ * waterfalls declared in `packages/smithers/agent/src/CellPlugin.ts`; there is
+ * no engine-wide lifecycle dispatcher.
+ *
+ * Cancellation is fiber interruption via scope closure; nothing here threads an
+ * `AbortSignal`.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as ImmutableMap from "@smthrs/canonical/ReadonlyMap";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { engineHooks } from "./Hooks.js";
+import { PluginError } from "./PluginError.js";
+import { defaultParallelConcurrency } from "./Resolve.js";
+const empty = Object.freeze([]);
+// The typed catalog and the runtime catalog can only drift when a host casts
+// around `KeysOfKind`; refuse before any handler runs rather than execute a
+// hook under semantics its declaration never promised.
+// A hook the catalog does not declare dispatches as empty, unless a
+// hand-built resolution registered handlers for it: those have no declared
+// kind to honor, so they are refused too.
+const kindMismatch = (resolved, hook, kind, handlers) => {
+    if (!Object.hasOwn(resolved.kinds, hook)) {
+        if (handlers.length === 0)
+            return undefined;
+        return new PluginError({
+            code: "hook_kind_mismatch",
+            message: `hook "${hook}" has handlers but is not declared in the runtime catalog`,
+            hook
+        });
+    }
+    const declared = resolved.kinds[hook];
+    if (declared === kind)
+        return undefined;
+    return new PluginError({
+        code: "hook_kind_mismatch",
+        message: `hook "${hook}" is declared ${JSON.stringify(declared)} in the runtime catalog but was dispatched as ${JSON.stringify(kind)}`,
+        hook
+    });
+};
+const runHandler = (record, args) => {
+    const onCause = (cause) => Effect.fail(new PluginError({
+        code: "hook_failed",
+        message: `hook "${record.hook}" failed in plugin "${record.plugin}"`,
+        plugin: record.plugin,
+        hook: record.hook,
+        cause
+    }));
+    return Effect.sync(() => record.handler(...args)).pipe(Effect.catchCause(onCause), Effect.flatMap((result) => Effect.isEffect(result)
+        ? result.pipe(Effect.catchCause(onCause))
+        : Effect.fail(new PluginError({
+            code: "hook_failed",
+            message: `hook "${record.hook}" in plugin "${record.plugin}" returned a non-Effect (${typeof result})`,
+            plugin: record.plugin,
+            hook: record.hook
+        }))));
+};
+/**
+ * Builds a dispatcher over an already resolved plugin list.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const make = (resolved) => {
+    const handlers = (hook) => resolved.handlers.get(hook) ?? empty;
+    const sequential = ((hook, ...args) => Effect.gen(function* () {
+        const mismatch = kindMismatch(resolved, hook, "sequential", handlers(hook));
+        if (mismatch !== undefined)
+            return yield* Effect.fail(mismatch);
+        const results = [];
+        for (const record of handlers(hook)) {
+            results.push(yield* runHandler(record, args));
+        }
+        return results;
+    }));
+    const parallel = ((hook, ...args) => {
+        const mismatch = kindMismatch(resolved, hook, "parallel", handlers(hook));
+        if (mismatch !== undefined)
+            return Effect.succeed([mismatch]);
+        return Effect.forEach(handlers(hook), (record) => runHandler(record, args).pipe(Effect.match({ onFailure: (error) => [error], onSuccess: () => [] })), { concurrency: resolved.parallelConcurrency }).pipe(Effect.map((chunks) => chunks.flat()));
+    });
+    const first = ((hook, ...args) => Effect.gen(function* () {
+        const mismatch = kindMismatch(resolved, hook, "first", handlers(hook));
+        if (mismatch !== undefined)
+            return yield* Effect.fail(mismatch);
+        for (const record of handlers(hook)) {
+            const result = yield* runHandler(record, args);
+            if (!Option.isOption(result)) {
+                return yield* Effect.fail(new PluginError({
+                    code: "invalid_hook_result",
+                    message: `first hook "${record.hook}" in plugin "${record.plugin}" did not return an Option`,
+                    plugin: record.plugin,
+                    hook: record.hook
+                }));
+            }
+            if (Option.isSome(result))
+                return result;
+        }
+        return Option.none();
+    }));
+    const waterfall = ((hook, initial, merge) => Effect.gen(function* () {
+        const mismatch = kindMismatch(resolved, hook, "waterfall", handlers(hook));
+        if (mismatch !== undefined)
+            return yield* Effect.fail(mismatch);
+        let value = initial;
+        for (const record of handlers(hook)) {
+            const patch = yield* runHandler(record, [value]);
+            if (patch !== undefined) {
+                value = yield* Effect.try({
+                    try: () => merge(value, patch),
+                    catch: (cause) => cause instanceof PluginError
+                        ? new PluginError({
+                            code: cause.code,
+                            message: cause.message,
+                            plugin: record.plugin,
+                            hook: record.hook,
+                            path: cause.path,
+                            cause
+                        })
+                        : new PluginError({
+                            code: "config_invalid",
+                            message: `waterfall hook "${record.hook}" in plugin "${record.plugin}" returned an invalid patch`,
+                            plugin: record.plugin,
+                            hook: record.hook,
+                            cause
+                        })
+                });
+            }
+        }
+        return value;
+    }));
+    return Object.freeze({ resolved, handlers, sequential, parallel, first, waterfall });
+};
+/**
+ * A dispatcher with no plugins at all.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const makeNoop = () => make(Object.freeze({
+    plugins: Object.freeze([]),
+    handlers: ImmutableMap.make(),
+    kinds: engineHooks,
+    parallelConcurrency: defaultParallelConcurrency
+}));
+/**
+ * The shared dispatcher, as a service tag.
+ *
+ * This tag holds one dispatcher over the process-wide augmented `FlowsHooks`.
+ * `declare module "@smthrs/plugin"` augmentation is the supported extension
+ * mechanism for values placed in the tag. A host typed against a separate hook
+ * interface holds its `Service<H>` directly, as `@smthrs/agent` does, and does
+ * not use this tag or its layers.
+ *
+ * @category context
+ * @since 1.0.0-rc.0
+ */
+export class Plugins extends Context.Service()("flows/plugin/Plugins") {
+}
+/**
+ * Layer providing a dispatcher over an already resolved plugin list.
+ *
+ * This layer targets the shared augmented `FlowsHooks` catalog only. A host
+ * with a separate hook interface holds its `Service<H>` directly.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layer = (resolved) => Layer.succeed(Plugins)(make(resolved));
+/**
+ * Layer providing a dispatcher with no plugins.
+ *
+ * This layer targets the shared augmented `FlowsHooks` catalog only. A host
+ * with a separate hook interface holds its `Service<H>` directly.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layerNoop = Layer.succeed(Plugins)(makeNoop());
+//# sourceMappingURL=Plugins.js.map

package/dist/esm/Plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugins.js","sourceRoot":"","sources":["../../src/Plugins.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The dispatcher: a plain service over a resolved plugin list, generic over the\n * hook interface.\n *\n * The public package contract is documented at\n * {@link https://smithers.sh/docs/reference/api/plugin}. Each host holds an instance over its\n * augmented `FlowsHooks` and may dispatch only the runtime catalog it supplied.\n * The shipped cell host owns the three\n * waterfalls declared in `packages/smithers/agent/src/CellPlugin.ts`; there is\n * no engine-wide lifecycle dispatcher.\n *\n * Cancellation is fiber interruption via scope closure; nothing here threads an\n * `AbortSignal`.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as ImmutableMap from \"@smthrs/canonical/ReadonlyMap\"\nimport type * as Cause from \"effect/Cause\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Option from \"effect/Option\"\nimport type { ArgsOf, ContextOf, HookKind, KeysOfKind, SuccessOf } from \"./Hooks.ts\"\nimport { engineHooks } from \"./Hooks.ts\"\nimport type { FlowsHooks } from \"./index.ts\"\nimport { PluginError } from \"./PluginError.ts\"\nimport { defaultParallelConcurrency, type HandlerRecord, type Resolved } from \"./Resolve.ts\"\n\nconst empty: ReadonlyArray<HandlerRecord> = Object.freeze([])\n\n// The typed catalog and the runtime catalog can only drift when a host casts\n// around `KeysOfKind`; refuse before any handler runs rather than execute a\n// hook under semantics its declaration never promised.\n// A hook the catalog does not declare dispatches as empty, unless a\n// hand-built resolution registered handlers for it: those have no declared\n// kind to honor, so they are refused too.\nconst kindMismatch = (\n  resolved: Resolved<unknown>,\n  hook: string,\n  kind: HookKind,\n  handlers: ReadonlyArray<HandlerRecord>\n): PluginError | undefined => {\n  if (!Object.hasOwn(resolved.kinds, hook)) {\n    if (handlers.length === 0) return undefined\n    return new PluginError({\n      code: \"hook_kind_mismatch\",\n      message: `hook \"${hook}\" has handlers but is not declared in the runtime catalog`,\n      hook\n    })\n  }\n  const declared = resolved.kinds[hook]\n  if (declared === kind) return undefined\n  return new PluginError({\n    code: \"hook_kind_mismatch\",\n    message: `hook \"${hook}\" is declared ${JSON.stringify(declared)} in the runtime catalog but was dispatched as ${\n      JSON.stringify(kind)\n    }`,\n    hook\n  })\n}\n\nconst runHandler = (\n  record: HandlerRecord,\n  args: ReadonlyArray<unknown>\n): Effect.Effect<unknown, PluginError, any> => {\n  const onCause = (cause: Cause.Cause<unknown>) =>\n    Effect.fail(\n      new PluginError({\n        code: \"hook_failed\",\n        message: `hook \"${record.hook}\" failed in plugin \"${record.plugin}\"`,\n        plugin: record.plugin,\n        hook: record.hook,\n        cause\n      })\n    )\n\n  return Effect.sync(() => record.handler(...args)).pipe(\n    Effect.catchCause(onCause),\n    Effect.flatMap((result) =>\n      Effect.isEffect(result)\n        ? result.pipe(Effect.catchCause(onCause))\n        : Effect.fail(\n          new PluginError({\n            code: \"hook_failed\",\n            message: `hook \"${record.hook}\" in plugin \"${record.plugin}\" returned a non-Effect (${typeof result})`,\n            plugin: record.plugin,\n            hook: record.hook\n          })\n        )\n    )\n  )\n}\n\n/**\n * The dispatch surface.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Service<H = FlowsHooks> {\n  /** The resolved list this dispatcher walks. */\n  readonly resolved: Resolved<H>\n  /** Frozen, ordered handler records for a hook. */\n  readonly handlers: (hook: string) => ReadonlyArray<HandlerRecord>\n  /** Runs every handler in resolved order, one at a time. */\n  readonly sequential: <K extends KeysOfKind<H, \"sequential\">>(\n    hook: K,\n    ...args: ArgsOf<H[K]>\n  ) => Effect.Effect<ReadonlyArray<SuccessOf<H[K]>>, PluginError, ContextOf<H[K]>>\n  /**\n   * Runs every handler concurrently, ignoring results. Never fails: handler\n   * failures are returned so the caller can report them at its own boundary.\n   */\n  readonly parallel: <K extends KeysOfKind<H, \"parallel\">>(\n    hook: K,\n    ...args: ArgsOf<H[K]>\n  ) => Effect.Effect<ReadonlyArray<PluginError>, never, ContextOf<H[K]>>\n  /** Runs handlers in order until one returns `Option.some`. */\n  readonly first: <K extends KeysOfKind<H, \"first\">>(\n    hook: K,\n    ...args: ArgsOf<H[K]>\n  ) => Effect.Effect<SuccessOf<H[K]>, PluginError, ContextOf<H[K]>>\n  /** Threads a value through every handler, merging each returned patch. */\n  readonly waterfall: <K extends KeysOfKind<H, \"waterfall\">>(\n    hook: K,\n    initial: ArgsOf<H[K]>[0],\n    merge: (previous: ArgsOf<H[K]>[0], patch: Exclude<SuccessOf<H[K]>, void>) => ArgsOf<H[K]>[0]\n  ) => Effect.Effect<ArgsOf<H[K]>[0], PluginError, ContextOf<H[K]>>\n}\n\n/**\n * Builds a dispatcher over an already resolved plugin list.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const make = <H = FlowsHooks>(resolved: Resolved<H>): Service<H> => {\n  const handlers = (hook: string): ReadonlyArray<HandlerRecord> => resolved.handlers.get(hook) ?? empty\n\n  const sequential = ((hook: string, ...args: Array<unknown>) =>\n    Effect.gen(function*() {\n      const mismatch = kindMismatch(resolved, hook, \"sequential\", handlers(hook))\n      if (mismatch !== undefined) return yield* Effect.fail(mismatch)\n      const results: Array<unknown> = []\n      for (const record of handlers(hook)) {\n        results.push(yield* runHandler(record, args))\n      }\n      return results\n    })) as Service<H>[\"sequential\"]\n\n  const parallel = ((hook: string, ...args: Array<unknown>) => {\n    const mismatch = kindMismatch(resolved, hook, \"parallel\", handlers(hook))\n    if (mismatch !== undefined) return Effect.succeed([mismatch])\n    return Effect.forEach(\n      handlers(hook),\n      (record) =>\n        runHandler(record, args).pipe(\n          Effect.match({ onFailure: (error) => [error], onSuccess: () => [] as Array<PluginError> })\n        ),\n      { concurrency: resolved.parallelConcurrency }\n    ).pipe(Effect.map((chunks) => chunks.flat()))\n  }) as Service<H>[\"parallel\"]\n\n  const first = ((hook: string, ...args: Array<unknown>) =>\n    Effect.gen(function*() {\n      const mismatch = kindMismatch(resolved, hook, \"first\", handlers(hook))\n      if (mismatch !== undefined) return yield* Effect.fail(mismatch)\n      for (const record of handlers(hook)) {\n        const result = yield* runHandler(record, args)\n        if (!Option.isOption(result)) {\n          return yield* Effect.fail(\n            new PluginError({\n              code: \"invalid_hook_result\",\n              message: `first hook \"${record.hook}\" in plugin \"${record.plugin}\" did not return an Option`,\n              plugin: record.plugin,\n              hook: record.hook\n            })\n          )\n        }\n        if (Option.isSome(result)) return result\n      }\n      return Option.none()\n    })) as unknown as Service<H>[\"first\"]\n\n  const waterfall =\n    ((hook: string, initial: unknown, merge: (previous: unknown, patch: unknown) => unknown) =>\n      Effect.gen(function*() {\n        const mismatch = kindMismatch(resolved, hook, \"waterfall\", handlers(hook))\n        if (mismatch !== undefined) return yield* Effect.fail(mismatch)\n        let value = initial\n        for (const record of handlers(hook)) {\n          const patch = yield* runHandler(record, [value])\n          if (patch !== undefined) {\n            value = yield* Effect.try({\n              try: () => merge(value, patch),\n              catch: (cause) =>\n                cause instanceof PluginError\n                  ? new PluginError({\n                    code: cause.code,\n                    message: cause.message,\n                    plugin: record.plugin,\n                    hook: record.hook,\n                    path: cause.path,\n                    cause\n                  })\n                  : new PluginError({\n                    code: \"config_invalid\",\n                    message: `waterfall hook \"${record.hook}\" in plugin \"${record.plugin}\" returned an invalid patch`,\n                    plugin: record.plugin,\n                    hook: record.hook,\n                    cause\n                  })\n            })\n          }\n        }\n        return value\n      })) as Service<H>[\"waterfall\"]\n\n  return Object.freeze({ resolved, handlers, sequential, parallel, first, waterfall })\n}\n\n/**\n * A dispatcher with no plugins at all.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const makeNoop = <H = FlowsHooks>(): Service<H> =>\n  make<H>(Object.freeze({\n    plugins: Object.freeze([]),\n    handlers: ImmutableMap.make<string, ReadonlyArray<HandlerRecord>>(),\n    kinds: engineHooks,\n    parallelConcurrency: defaultParallelConcurrency\n  }))\n\n/**\n * The shared dispatcher, as a service tag.\n *\n * This tag holds one dispatcher over the process-wide augmented `FlowsHooks`.\n * `declare module \"@smthrs/plugin\"` augmentation is the supported extension\n * mechanism for values placed in the tag. A host typed against a separate hook\n * interface holds its `Service<H>` directly, as `@smthrs/agent` does, and does\n * not use this tag or its layers.\n *\n * @category context\n * @since 1.0.0-rc.0\n */\nexport class Plugins extends Context.Service<Plugins, Service>()(\"flows/plugin/Plugins\") {}\n\n/**\n * Layer providing a dispatcher over an already resolved plugin list.\n *\n * This layer targets the shared augmented `FlowsHooks` catalog only. A host\n * with a separate hook interface holds its `Service<H>` directly.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layer = (resolved: Resolved): Layer.Layer<Plugins> => Layer.succeed(Plugins)(make(resolved))\n\n/**\n * Layer providing a dispatcher with no plugins.\n *\n * This layer targets the shared augmented `FlowsHooks` catalog only. A host\n * with a separate hook interface holds its `Service<H>` directly.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layerNoop: Layer.Layer<Plugins> = Layer.succeed(Plugins)(makeNoop())\n"]}