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

package/dist/esm/Config.js

@@ -0,0 +1,160 @@
+/**
+ * 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.js";
+import { PluginError } from "./PluginError.js";
+/**
+ * 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;
+const admittedConfigs = 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)
+}));
+/**
+ * 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;
+/**
+ * Admits the detached, recursively frozen configuration handed to plugins.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const ResolvedConfig = configurationSchema;
+const reservedRootKeys = new Set(["engine", "retry", "store", "plugins"]);
+const invalid = (path, complaint) => new 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;
+};
+/**
+ * Empty defaults. Engine policy is deliberately not defaulted here.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const defaults = 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, patch) => {
+    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;
+    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 = (value) => {
+    const admitted = Boundary.admit(value);
+    if (!admitted.ok)
+        throw invalid(admitted.path, admitted.complaint);
+    return admitted.value;
+};
+/**
+ * Admits a raw pre-resolution configuration as an immutable snapshot.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const snapshot = (config) => Effect.try({ try: () => snapshotRecord(config), catch: (cause) => cause });
+/**
+ * Decodes the post-waterfall configuration into its final immutable form.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const resolve = (config) => snapshot(config);
+//# sourceMappingURL=Config.js.map

package/dist/esm/Config.js.map

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

package/dist/esm/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/esm/Hooks.d.ts.map

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

package/dist/esm/Hooks.js

@@ -0,0 +1,56 @@
+/**
+ * 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
+ */
+/**
+ * Runtime catalog of the shared kernel's hook names and kinds.
+ *
+ * The type system cannot enumerate an augmentable interface, so this constant
+ * is what the `unknown_hook` guard checks against. A host passes its own
+ * superset to {@link resolve}. The cell harness adds only the hooks it
+ * dispatches; lifecycle and engine-policy hooks do not belong here.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+const sharedHooks = Object.create(null);
+Object.defineProperties(sharedHooks, {
+    config: { value: "waterfall", enumerable: true },
+    configResolved: { value: "parallel", enumerable: true }
+});
+/**
+ * Frozen runtime catalog for the shared configuration hooks.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const engineHooks = Object.freeze(sharedHooks);
+/**
+ * Normalizes a hook entry to its handler.
+ *
+ * @category utils
+ * @since 1.0.0-rc.0
+ */
+export const handlerOf = (entry) => typeof entry === "function"
+    ? entry
+    : entry.handler;
+/**
+ * Reads the per-hook `order` of a hook entry.
+ *
+ * @category utils
+ * @since 1.0.0-rc.0
+ */
+export const orderOf = (entry) => typeof entry === "function" ? undefined : entry.order;
+//# sourceMappingURL=Hooks.js.map

package/dist/esm/Hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Hooks.js","sourceRoot":"","sources":["../../src/Hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAuJH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,GAAwD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;AAC5F,MAAM,CAAC,gBAAgB,CAAC,WAAW,EAAE;IACnC,MAAM,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE;IAChD,cAAc,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE;CACxD,CAAC,CAAA;AACF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAGnB,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;AAE/B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAc,EAAoC,EAAE,CAC5E,OAAO,KAAK,KAAK,UAAU;IACzB,CAAC,CAAC,KAAyC;IAC3C,CAAC,CAAE,KAAsD,CAAC,OAAO,CAAA;AAErE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAc,EAA8B,EAAE,CACpE,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,KAA6B,CAAC,KAAK,CAAA","sourcesContent":["/**\n * The typed hook surface: hook kinds, the hook entry shape, and the shared\n * kernel's base hook catalog.\n *\n * The public package contract is documented at\n * {@link https://smithers.sh/docs/reference/api/plugin}. The shared catalog is limited to\n * `config` and `configResolved`;\n * `@smthrs/agent` adds only `cellRegistry`, `cellFlows`, and\n * `cellModelRequest`. Durable-core lifecycle policy is not a hook catalog.\n *\n * `FlowsHooks` is **open for augmentation, closed for dispatch**: a host\n * declares its hooks with `declare module \"@smthrs/plugin\"`, supplies the\n * matching runtime catalog, and dispatches only that bounded set.\n *\n * @since 1.0.0-rc.0\n */\n\nimport type * as Effect from \"effect/Effect\"\n\n/**\n * Dispatch semantics of a hook, fixed by the core.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type HookKind = \"sequential\" | \"parallel\" | \"first\" | \"waterfall\"\n\ndeclare const HookTypeId: unique symbol\n\n/**\n * Phantom carrier that records a hook's kind and handler type in the type\n * system without adding anything at runtime.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface HookMeta<K extends HookKind, F> {\n  readonly [HookTypeId]?: { readonly kind: K; readonly handler: F }\n}\n\n/**\n * The object form of a hook entry: Vite's per-hook ordering object, verbatim.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface HookObject<F> {\n  readonly order?: \"pre\" | \"post\" | undefined\n  readonly handler: F\n}\n\n/**\n * A hook entry is either the bare handler or `{ order?, handler }`.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type HookEntry<K extends HookKind, F> = (F | HookObject<F>) & HookMeta<K, F>\n\n/**\n * Every handler runs, in resolved order, one at a time.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type SequentialHook<F> = HookEntry<\"sequential\", F>\n\n/**\n * Every handler runs concurrently; results are ignored and failures are\n * returned to the caller rather than failing it.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type ParallelHook<F> = HookEntry<\"parallel\", F>\n\n/**\n * Handlers run in order until one returns `Option.some`.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type FirstHook<F> = HookEntry<\"first\", F>\n\n/**\n * Each handler receives the previous handler's output.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type WaterfallHook<F> = HookEntry<\"waterfall\", F>\n\n/**\n * Extracts the declared kind of a hook entry type.\n *\n * @category type-level\n * @since 1.0.0-rc.0\n */\nexport type KindOf<T> = T extends HookMeta<infer K, any> ? K : never\n\n/**\n * The runtime catalog a host supplies for a hook interface: each hook name\n * mapped to its kind. A name declared in `H` must carry the kind its type\n * declares. Names outside `H` are admitted with any kind, because the type\n * system cannot enumerate an augmentable interface; resolution checks them\n * at runtime and dispatch refuses a kind that disagrees with the catalog.\n *\n * @category type-level\n * @since 1.0.0-rc.0\n */\nexport type HookCatalog<H> =\n  & { readonly [K in keyof H & string]?: KindOf<H[K]> }\n  & { readonly [name: string]: HookKind | undefined }\n\n/**\n * Extracts the handler type of a hook entry type.\n *\n * @category type-level\n * @since 1.0.0-rc.0\n */\nexport type HandlerOf<T> = T extends HookMeta<any, infer F> ? F : never\n\n/**\n * Selects the hook names of a given kind from a hook interface.\n *\n * @category type-level\n * @since 1.0.0-rc.0\n */\nexport type KeysOfKind<H, K extends HookKind> =\n  & {\n    [P in keyof H]: KindOf<H[P]> extends K ? P : never\n  }[keyof H]\n  & string\n\n/**\n * Extracts the positional argument tuple accepted by a hook entry.\n *\n * @category type-level\n * @since 1.0.0-rc.0\n */\nexport type ArgsOf<T> = HandlerOf<T> extends (...args: infer A) => any ? A : never\n\n/**\n * Extracts the Effect returned by a hook entry.\n *\n * @category type-level\n * @since 1.0.0-rc.0\n */\nexport type ReturnOf<T> = HandlerOf<T> extends (...args: any) => infer R ? R : never\n\n/**\n * Extracts the success value returned by a hook entry's Effect.\n *\n * @category type-level\n * @since 1.0.0-rc.0\n */\nexport type SuccessOf<T> = ReturnOf<T> extends Effect.Effect<infer A, any, any> ? A : never\n\n/**\n * Extracts the context required by a hook entry's Effect.\n *\n * @category type-level\n * @since 1.0.0-rc.0\n */\nexport type ContextOf<T> = ReturnOf<T> extends Effect.Effect<any, any, infer R> ? R : never\n\n/**\n * Runtime catalog of the shared kernel's hook names and kinds.\n *\n * The type system cannot enumerate an augmentable interface, so this constant\n * is what the `unknown_hook` guard checks against. A host passes its own\n * superset to {@link resolve}. The cell harness adds only the hooks it\n * dispatches; lifecycle and engine-policy hooks do not belong here.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nconst sharedHooks: { config: \"waterfall\"; configResolved: \"parallel\" } = Object.create(null)\nObject.defineProperties(sharedHooks, {\n  config: { value: \"waterfall\", enumerable: true },\n  configResolved: { value: \"parallel\", enumerable: true }\n})\n/**\n * Frozen runtime catalog for the shared configuration hooks.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const engineHooks: Readonly<{\n  readonly config: \"waterfall\"\n  readonly configResolved: \"parallel\"\n}> = Object.freeze(sharedHooks)\n\n/**\n * Normalizes a hook entry to its handler.\n *\n * @category utils\n * @since 1.0.0-rc.0\n */\nexport const handlerOf = (entry: unknown): (...args: Array<any>) => unknown =>\n  typeof entry === \"function\"\n    ? entry as (...args: Array<any>) => unknown\n    : (entry as HookObject<(...args: Array<any>) => unknown>).handler\n\n/**\n * Reads the per-hook `order` of a hook entry.\n *\n * @category utils\n * @since 1.0.0-rc.0\n */\nexport const orderOf = (entry: unknown): \"pre\" | \"post\" | undefined =>\n  typeof entry === \"function\" ? undefined : (entry as HookObject<unknown>).order\n"]}

package/dist/esm/Kernel.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Startup: resolve the plugin list, run the config pipeline, hand back a
+ * dispatcher, a frozen config, and the merged layer.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}, with the shipped host catalog in
+ * `packages/smithers/agent/src/CellPlugin.ts`. D14 in
+ * `docs/pages/design-decisions.md` keeps durable policy outside these hooks.
+ *
+ * Order of operations, per the spec:
+ *
+ * 1. flatten / filter / validate / order the plugin list;
+ * 2. `config` waterfall: each plugin may return a partial to deep-merge;
+ * 3. decode and freeze into a `ResolvedConfig` (`config_invalid` on failure);
+ * 4. `configResolved` parallel: observers capture the final config;
+ * 5. plugin `layer`s merge left-to-right.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Effect from "effect/Effect";
+import type * as Layer from "effect/Layer";
+import type { FlowsConfig, ResolvedConfig } from "./Config.ts";
+import type { ContextOf } from "./Hooks.ts";
+import type { FlowsHooks } from "./index.ts";
+import type { PluginInput } from "./Plugin.ts";
+import type { PluginError } from "./PluginError.ts";
+import * as Plugins from "./Plugins.ts";
+import * as Resolve from "./Resolve.ts";
+/**
+ * Everything startup produces from a plugin list and a raw config.
+ *
+ * `observerErrors` carries `configResolved` failures: parallel observers are
+ * lossy by contract, so they are reported rather than fatal.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Kernel<H = FlowsHooks> {
+    readonly plugins: Plugins.Service<H>;
+    readonly config: ResolvedConfig;
+    readonly layer: Layer.Layer<any, PluginError, any>;
+    readonly observerErrors: ReadonlyArray<PluginError>;
+}
+type HookAt<H, K extends string> = K extends keyof H ? H[K] : never;
+/**
+ * The services a hook interface's `config` hook requires at startup. `never`
+ * for the shared `FlowsHooks`, whose startup hooks are context-free.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type ConfigContext<H> = ContextOf<HookAt<H, "config">>;
+/**
+ * The services a hook interface's startup hooks require: the union of the
+ * `config` and `configResolved` requirements. `Kernel.make` cannot supply
+ * them itself, so they surface in its Effect and the caller provides them.
+ *
+ * @category type-level
+ * @since 1.0.0-rc.0
+ */
+export type StartupContext<H> = ConfigContext<H> | ContextOf<HookAt<H, "configResolved">>;
+/**
+ * Snapshots the config before dispatching the `config` waterfall, then
+ * admits the result as a frozen `ResolvedConfig`.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const runConfig: <H = FlowsHooks>(plugins: Plugins.Service<H>, config: FlowsConfig) => Effect.Effect<ResolvedConfig, PluginError, ConfigContext<H>>;
+/**
+ * Resolves plugins, executes the config pipeline, and merges plugin layers.
+ * The positional `config` is the kernel's only pre-resolution configuration;
+ * the options object cannot declare a second source, and a `config` key
+ * supplied anyway fails with `invalid_plugin` at `$options.config`.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const make: <H = FlowsHooks>(input: PluginInput<NoInfer<H>>, config?: FlowsConfig, options?: Omit<Resolve.Options<NoInfer<H>>, "config">) => Effect.Effect<Kernel<H>, PluginError, StartupContext<H>>;
+export {};
+//# sourceMappingURL=Kernel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Kernel.d.ts","sourceRoot":"","sources":["../../src/Kernel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC;;;;;;;;GAQG;AACH,MAAM,WAAW,MAAM,CAAC,CAAC,GAAG,UAAU;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;IACpC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,CAAC,CAAA;IAClD,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;CACpD;AAED,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAA;AAEnE;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAA;AAE7D;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAA;AAEzF;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,GAAG,UAAU,EACtC,SAAS,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAC3B,QAAQ,WAAW,KAClB,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,CAS1D,CAAA;AAEJ;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,GAAG,UAAU,EACjC,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAC9B,SAAQ,WAAgB,EACxB,UAAS,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAM,KACxD,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC,CAgBtD,CAAA"}

package/dist/esm/Kernel.js

@@ -0,0 +1,58 @@
+/**
+ * Startup: resolve the plugin list, run the config pipeline, hand back a
+ * dispatcher, a frozen config, and the merged layer.
+ *
+ * The public package contract is documented at
+ * {@link https://smithers.sh/docs/reference/api/plugin}, with the shipped host catalog in
+ * `packages/smithers/agent/src/CellPlugin.ts`. D14 in
+ * `docs/pages/design-decisions.md` keeps durable policy outside these hooks.
+ *
+ * Order of operations, per the spec:
+ *
+ * 1. flatten / filter / validate / order the plugin list;
+ * 2. `config` waterfall: each plugin may return a partial to deep-merge;
+ * 3. decode and freeze into a `ResolvedConfig` (`config_invalid` on failure);
+ * 4. `configResolved` parallel: observers capture the final config;
+ * 5. plugin `layer`s merge left-to-right.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Effect from "effect/Effect";
+import * as Config from "./Config.js";
+import * as Plugins from "./Plugins.js";
+import * as Resolve from "./Resolve.js";
+/**
+ * Snapshots the config before dispatching the `config` waterfall, then
+ * admits the result as a frozen `ResolvedConfig`.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const runConfig = (plugins, config) => Effect.gen(function* () {
+    const initial = yield* Config.snapshot(config);
+    const merged = yield* plugins.waterfall("config", initial, Config.merge);
+    return yield* Config.resolve(merged);
+});
+/**
+ * Resolves plugins, executes the config pipeline, and merges plugin layers.
+ * The positional `config` is the kernel's only pre-resolution configuration;
+ * the options object cannot declare a second source, and a `config` key
+ * supplied anyway fails with `invalid_plugin` at `$options.config`.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const make = (input, config = {}, options = {}) => Effect.gen(function* () {
+    const initial = yield* Config.snapshot(config);
+    const resolved = yield* Resolve.resolve(input, options, initial);
+    const dispatcher = Plugins.make(resolved);
+    const frozen = yield* runConfig(dispatcher, initial);
+    const observerErrors = yield* dispatcher.parallel("configResolved", frozen);
+    return Object.freeze({
+        plugins: dispatcher,
+        config: frozen,
+        layer: Resolve.layer(resolved),
+        observerErrors
+    });
+});
+//# sourceMappingURL=Kernel.js.map

package/dist/esm/Kernel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Kernel.js","sourceRoot":"","sources":["../../src/Kernel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAKrC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAuCvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,OAA2B,EAC3B,MAAmB,EAC2C,EAAE,CAChE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IAC9C,MAAM,MAAM,GAAG,KAAK,CAAC,CAAE,OAAO,CAAC,SAIgC,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IAChG,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;AACtC,CAAC,CAAC,CAAA;AAEJ;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAClB,KAA8B,EAC9B,SAAsB,EAAE,EACxB,UAAuD,EAAE,EACC,EAAE,CAC5D,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IAC9C,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,OAAO,CAAI,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IACnE,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAI,QAAQ,CAAC,CAAA;IAC5C,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,SAAS,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;IACpD,MAAM,cAAc,GAAG,KAAK,CAAC,CAAE,UAAU,CAAC,QAG+B,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAA;IACnG,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,OAAO,EAAE,UAAU;QACnB,MAAM,EAAE,MAAM;QACd,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC9B,cAAc;KACf,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA","sourcesContent":["/**\n * Startup: resolve the plugin list, run the config pipeline, hand back a\n * dispatcher, a frozen config, and the merged layer.\n *\n * The public package contract is documented at\n * {@link https://smithers.sh/docs/reference/api/plugin}, with the shipped host catalog in\n * `packages/smithers/agent/src/CellPlugin.ts`. D14 in\n * `docs/pages/design-decisions.md` keeps durable policy outside these hooks.\n *\n * Order of operations, per the spec:\n *\n * 1. flatten / filter / validate / order the plugin list;\n * 2. `config` waterfall: each plugin may return a partial to deep-merge;\n * 3. decode and freeze into a `ResolvedConfig` (`config_invalid` on failure);\n * 4. `configResolved` parallel: observers capture the final config;\n * 5. plugin `layer`s merge left-to-right.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Effect from \"effect/Effect\"\nimport type * as Layer from \"effect/Layer\"\nimport type { FlowsConfig, ResolvedConfig } from \"./Config.ts\"\nimport * as Config from \"./Config.ts\"\nimport type { ContextOf } from \"./Hooks.ts\"\nimport type { FlowsHooks } from \"./index.ts\"\nimport type { PluginInput } from \"./Plugin.ts\"\nimport type { PluginError } from \"./PluginError.ts\"\nimport * as Plugins from \"./Plugins.ts\"\nimport * as Resolve from \"./Resolve.ts\"\n\n/**\n * Everything startup produces from a plugin list and a raw config.\n *\n * `observerErrors` carries `configResolved` failures: parallel observers are\n * lossy by contract, so they are reported rather than fatal.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Kernel<H = FlowsHooks> {\n  readonly plugins: Plugins.Service<H>\n  readonly config: ResolvedConfig\n  readonly layer: Layer.Layer<any, PluginError, any>\n  readonly observerErrors: ReadonlyArray<PluginError>\n}\n\ntype HookAt<H, K extends string> = K extends keyof H ? H[K] : never\n\n/**\n * The services a hook interface's `config` hook requires at startup. `never`\n * for the shared `FlowsHooks`, whose startup hooks are context-free.\n *\n * @category type-level\n * @since 1.0.0-rc.0\n */\nexport type ConfigContext<H> = ContextOf<HookAt<H, \"config\">>\n\n/**\n * The services a hook interface's startup hooks require: the union of the\n * `config` and `configResolved` requirements. `Kernel.make` cannot supply\n * them itself, so they surface in its Effect and the caller provides them.\n *\n * @category type-level\n * @since 1.0.0-rc.0\n */\nexport type StartupContext<H> = ConfigContext<H> | ContextOf<HookAt<H, \"configResolved\">>\n\n/**\n * Snapshots the config before dispatching the `config` waterfall, then\n * admits the result as a frozen `ResolvedConfig`.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const runConfig = <H = FlowsHooks>(\n  plugins: Plugins.Service<H>,\n  config: FlowsConfig\n): Effect.Effect<ResolvedConfig, PluginError, ConfigContext<H>> =>\n  Effect.gen(function*() {\n    const initial = yield* Config.snapshot(config)\n    const merged = yield* (plugins.waterfall as unknown as (\n      hook: string,\n      initial: FlowsConfig,\n      merge: (previous: FlowsConfig, patch: unknown) => FlowsConfig\n    ) => Effect.Effect<FlowsConfig, PluginError, ConfigContext<H>>)(\"config\", initial, Config.merge)\n    return yield* Config.resolve(merged)\n  })\n\n/**\n * Resolves plugins, executes the config pipeline, and merges plugin layers.\n * The positional `config` is the kernel's only pre-resolution configuration;\n * the options object cannot declare a second source, and a `config` key\n * supplied anyway fails with `invalid_plugin` at `$options.config`.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const make = <H = FlowsHooks>(\n  input: PluginInput<NoInfer<H>>,\n  config: FlowsConfig = {},\n  options: Omit<Resolve.Options<NoInfer<H>>, \"config\"> = {}\n): Effect.Effect<Kernel<H>, PluginError, StartupContext<H>> =>\n  Effect.gen(function*() {\n    const initial = yield* Config.snapshot(config)\n    const resolved = yield* Resolve.resolve<H>(input, options, initial)\n    const dispatcher = Plugins.make<H>(resolved)\n    const frozen = yield* runConfig(dispatcher, initial)\n    const observerErrors = yield* (dispatcher.parallel as unknown as (\n      hook: string,\n      value: ResolvedConfig\n    ) => Effect.Effect<ReadonlyArray<PluginError>, never, StartupContext<H>>)(\"configResolved\", frozen)\n    return Object.freeze({\n      plugins: dispatcher,\n      config: frozen,\n      layer: Resolve.layer(resolved),\n      observerErrors\n    })\n  })\n"]}