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

package/dist/esm/internal/Boundary.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Inert JSON admission for plugin configuration and cache identity.
+ *
+ * Reflection is descriptor-only: accessors never execute, hostile proxies are
+ * refused, and accepted values are detached before they are frozen.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+import * as BoundedJson from "@smthrs/canonical/BoundedJson";
+/**
+ * Strict JSON value accepted by the boundary.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export type Json = BoundedJson.Json;
+/**
+ * Resource bounds for one admitted tree.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export type Limits = BoundedJson.StrictLimits;
+/**
+ * Successful admission.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export interface AdmissionSuccess {
+    readonly ok: true;
+    readonly value: Json;
+}
+/**
+ * Refusal with a stable value path.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export interface AdmissionFailure {
+    readonly ok: false;
+    readonly path: string;
+    readonly complaint: string;
+}
+/**
+ * Result of inert JSON admission.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export type Admission = AdmissionSuccess | AdmissionFailure;
+/**
+ * Default configuration bounds.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export declare const defaultLimits: Limits;
+/**
+ * Tests whether a string contains paired UTF-16 surrogate units.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export declare const isWellFormedText: (value: string) => boolean;
+/**
+ * Copies one strict JSON tree under explicit resource bounds.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export declare const admit: (input: unknown, limits?: Limits) => Admission;
+/**
+ * Admits only a JSON record at the root.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export declare const record: (input: unknown, limits?: Limits) => AdmissionSuccess | AdmissionFailure;
+/**
+ * Merges two independently admitted records, retaining unchanged subtrees.
+ * Both operands must come from successful admission, and the patch must be a
+ * fresh copy: their trees must be disjoint. Each output branch then comes from
+ * at most one location in either tree, preserving the no-repeated-reference
+ * invariant without walking retained subtrees. Limits apply to the result.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export declare const mergeRecords: (base: {
+    readonly [key: string]: Json;
+}, patch: {
+    readonly [key: string]: Json;
+}, limits?: Limits) => Admission;
+//# sourceMappingURL=Boundary.d.ts.map

package/dist/esm/internal/Boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Boundary.d.ts","sourceRoot":"","sources":["../../../src/internal/Boundary.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,WAAW,MAAM,+BAA+B,CAAA;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAA;AAEnC;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,WAAW,CAAC,YAAY,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;IACjB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG,gBAAgB,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,MAO1B,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,OAA+B,CAAA;AA4EhF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,OAAO,EAAE,SAAQ,MAAsB,KAAG,SAatE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GACjB,OAAO,OAAO,EACd,SAAQ,MAAsB,KAC7B,gBAAgB,GAAG,gBAKrB,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACtC,OAAO;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACvC,SAAQ,MAAsB,KAC7B,SA4CF,CAAA"}

package/dist/esm/internal/Boundary.js

@@ -0,0 +1,162 @@
+/**
+ * Inert JSON admission for plugin configuration and cache identity.
+ *
+ * Reflection is descriptor-only: accessors never execute, hostile proxies are
+ * refused, and accepted values are detached before they are frozen.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+import * as BoundedJson from "@smthrs/canonical/BoundedJson";
+/**
+ * Default configuration bounds.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const defaultLimits = Object.freeze({
+    maxBytes: 1024 * 1024,
+    maxDepth: 64,
+    maxMembers: 4_096,
+    maxNodes: 8_192,
+    maxStringBytes: 64 * 1024,
+    maxKeyBytes: 1_024
+});
+/**
+ * Tests whether a string contains paired UTF-16 surrogate units.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const isWellFormedText = (value) => value.isWellFormed();
+const childPath = (path, key) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+const encodedStringBytes = (value) => BoundedJson.encodedStringBytes(value);
+// Paths contain only well-formed text and JSON-escaped keys. Count their JSON
+// bytes without encoding the whole path, reserving quotes and a truncation marker.
+const boundedPath = (path) => {
+    let bytes = 2 + 3;
+    let prefix = "";
+    for (const character of path) {
+        const point = character.codePointAt(0);
+        bytes += character === "\"" || character === "\\"
+            ? 2
+            : point <= 0x7f
+                ? 1
+                : point <= 0x7ff
+                    ? 2
+                    : point <= 0xffff
+                        ? 3
+                        : 4;
+        if (bytes > 192)
+            return `${prefix}...`;
+        prefix += character;
+    }
+    return path;
+};
+// Only detached containers constructed here enter this map. Mutable caller
+// objects and Object.freeze alone never establish admission.
+const snapshots = new WeakMap();
+const scalarTotals = (bytes) => ({ bytes, members: 0, nodes: 1, depth: 0 });
+const total = (entries) => {
+    const totals = { bytes: 2 + Math.max(0, entries.size - 1), members: entries.size, nodes: 1, depth: 1 };
+    for (const entry of entries.values()) {
+        totals.bytes += entry.keyBytes + entry.totals.bytes;
+        totals.members += entry.totals.members;
+        totals.nodes += entry.totals.nodes;
+        totals.depth = Math.max(totals.depth, 1 + entry.totals.depth);
+    }
+    return totals;
+};
+const remember = (value) => {
+    const entries = new Map();
+    for (const [key, child] of Object.entries(value)) {
+        entries.set(key, {
+            keyBytes: Array.isArray(value) ? 0 : encodedStringBytes(key) + 1,
+            totals: typeof child === "object" && child !== null ?
+                snapshots.get(child).totals
+                : scalarTotals(typeof child === "string" ? encodedStringBytes(child) : String(child).length)
+        });
+    }
+    snapshots.set(value, { totals: total(entries), entries });
+};
+/**
+ * Copies one strict JSON tree under explicit resource bounds.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const admit = (input, limits = defaultLimits) => {
+    const result = BoundedJson.admitStrict(input, limits, {
+        ordinaryRecords: true,
+        boundedText: true,
+        onContainer: remember
+    });
+    return result.ok ? result : {
+        ...result,
+        path: boundedPath(result.path),
+        complaint: result.complaint === "must be dense and have no extra properties"
+            ? "must be a dense array with no extra properties" :
+            result.complaint
+    };
+};
+/**
+ * Admits only a JSON record at the root.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const record = (input, limits = defaultLimits) => {
+    const admitted = admit(input, limits);
+    return admitted.ok && (admitted.value === null || Array.isArray(admitted.value) || typeof admitted.value !== "object")
+        ? { ok: false, path: "$", complaint: "must be a JSON record" }
+        : admitted;
+};
+/**
+ * Merges two independently admitted records, retaining unchanged subtrees.
+ * Both operands must come from successful admission, and the patch must be a
+ * fresh copy: their trees must be disjoint. Each output branch then comes from
+ * at most one location in either tree, preserving the no-repeated-reference
+ * invariant without walking retained subtrees. Limits apply to the result.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const mergeRecords = (base, patch, limits = defaultLimits) => {
+    const merge = (left, right, path) => {
+        const entries = new Map(snapshots.get(left).entries);
+        const result = { ...left };
+        for (const [key, entry] of snapshots.get(right).entries) {
+            const previous = left[key];
+            const next = right[key];
+            if (typeof previous === "object" && previous !== null && !Array.isArray(previous) &&
+                typeof next === "object" && next !== null && !Array.isArray(next)) {
+                const merged = merge(previous, next, childPath(path, key));
+                if (!merged.ok)
+                    return merged;
+                result[key] = merged.value;
+                entries.set(key, { keyBytes: entry.keyBytes, totals: snapshots.get(merged.value).totals });
+            }
+            else {
+                result[key] = next;
+                entries.set(key, entry);
+            }
+        }
+        const totals = total(entries);
+        const complaint = totals.members > limits.maxMembers ?
+            `exceeds the ${limits.maxMembers}-member limit`
+            : totals.nodes > limits.maxNodes ?
+                `exceeds the ${limits.maxNodes}-node limit`
+                : totals.bytes > limits.maxBytes ?
+                    `exceeds the ${limits.maxBytes}-byte limit`
+                    : totals.depth > limits.maxDepth ?
+                        `exceeds the depth limit of ${limits.maxDepth}`
+                        : undefined;
+        if (complaint !== undefined)
+            return { ok: false, path: boundedPath(path), complaint };
+        Object.freeze(result);
+        snapshots.set(result, { totals, entries });
+        return { ok: true, value: result };
+    };
+    return merge(base, patch, "$");
+};
+//# sourceMappingURL=Boundary.js.map

package/dist/esm/internal/Boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Boundary.js","sourceRoot":"","sources":["../../../src/internal/Boundary.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Inert JSON admission for plugin configuration and cache identity.\n *\n * Reflection is descriptor-only: accessors never execute, hostile proxies are\n * refused, and accepted values are detached before they are frozen.\n *\n * @private\n * @since 1.0.0-rc.0\n */\n\nimport * as BoundedJson from \"@smthrs/canonical/BoundedJson\"\n\n/**\n * Strict JSON value accepted by the boundary.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nexport type Json = BoundedJson.Json\n\n/**\n * Resource bounds for one admitted tree.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nexport type Limits = BoundedJson.StrictLimits\n\n/**\n * Successful admission.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nexport interface AdmissionSuccess {\n  readonly ok: true\n  readonly value: Json\n}\n\n/**\n * Refusal with a stable value path.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nexport interface AdmissionFailure {\n  readonly ok: false\n  readonly path: string\n  readonly complaint: string\n}\n\n/**\n * Result of inert JSON admission.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nexport type Admission = AdmissionSuccess | AdmissionFailure\n\n/**\n * Default configuration bounds.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nexport const defaultLimits: Limits = Object.freeze({\n  maxBytes: 1024 * 1024,\n  maxDepth: 64,\n  maxMembers: 4_096,\n  maxNodes: 8_192,\n  maxStringBytes: 64 * 1024,\n  maxKeyBytes: 1_024\n})\n\n/**\n * Tests whether a string contains paired UTF-16 surrogate units.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nexport const isWellFormedText = (value: string): boolean => value.isWellFormed()\n\nconst childPath = (path: string, key: string): string =>\n  /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`\n\nconst encodedStringBytes = (value: string): number => BoundedJson.encodedStringBytes(value)!\n\n// Paths contain only well-formed text and JSON-escaped keys. Count their JSON\n// bytes without encoding the whole path, reserving quotes and a truncation marker.\nconst boundedPath = (path: string): string => {\n  let bytes = 2 + 3\n  let prefix = \"\"\n  for (const character of path) {\n    const point = character.codePointAt(0)!\n    bytes += character === \"\\\"\" || character === \"\\\\\"\n      ? 2\n      : point <= 0x7f\n      ? 1\n      : point <= 0x7ff\n      ? 2\n      : point <= 0xffff\n      ? 3\n      : 4\n    if (bytes > 192) return `${prefix}...`\n    prefix += character\n  }\n  return path\n}\n\ninterface Totals {\n  bytes: number\n  members: number\n  nodes: number\n  depth: number\n}\n\ninterface Entry {\n  readonly keyBytes: number\n  readonly totals: Totals\n}\n\ninterface Snapshot {\n  readonly totals: Totals\n  readonly entries: Map<string, Entry>\n}\n\n// Only detached containers constructed here enter this map. Mutable caller\n// objects and Object.freeze alone never establish admission.\nconst snapshots = new WeakMap<object, Snapshot>()\n\nconst scalarTotals = (bytes: number): Totals => ({ bytes, members: 0, nodes: 1, depth: 0 })\n\nconst total = (entries: ReadonlyMap<string, Entry>): Totals => {\n  const totals: Totals = { bytes: 2 + Math.max(0, entries.size - 1), members: entries.size, nodes: 1, depth: 1 }\n  for (const entry of entries.values()) {\n    totals.bytes += entry.keyBytes + entry.totals.bytes\n    totals.members += entry.totals.members\n    totals.nodes += entry.totals.nodes\n    totals.depth = Math.max(totals.depth, 1 + entry.totals.depth)\n  }\n  return totals\n}\n\nconst remember = (value: ReadonlyArray<Json> | { readonly [key: string]: Json }): void => {\n  const entries = new Map<string, Entry>()\n  for (const [key, child] of Object.entries(value)) {\n    entries.set(key, {\n      keyBytes: Array.isArray(value) ? 0 : encodedStringBytes(key) + 1,\n      totals: typeof child === \"object\" && child !== null ?\n        snapshots.get(child)!.totals\n        : scalarTotals(typeof child === \"string\" ? encodedStringBytes(child) : String(child).length)\n    })\n  }\n  snapshots.set(value, { totals: total(entries), entries })\n}\n\n/**\n * Copies one strict JSON tree under explicit resource bounds.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nexport const admit = (input: unknown, limits: Limits = defaultLimits): Admission => {\n  const result = BoundedJson.admitStrict(input, limits, {\n    ordinaryRecords: true,\n    boundedText: true,\n    onContainer: remember\n  })\n  return result.ok ? result : {\n    ...result,\n    path: boundedPath(result.path),\n    complaint: result.complaint === \"must be dense and have no extra properties\"\n      ? \"must be a dense array with no extra properties\" :\n      result.complaint\n  }\n}\n\n/**\n * Admits only a JSON record at the root.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nexport const record = (\n  input: unknown,\n  limits: Limits = defaultLimits\n): AdmissionSuccess | AdmissionFailure => {\n  const admitted = admit(input, limits)\n  return admitted.ok && (admitted.value === null || Array.isArray(admitted.value) || typeof admitted.value !== \"object\")\n    ? { ok: false, path: \"$\", complaint: \"must be a JSON record\" }\n    : admitted\n}\n\n/**\n * Merges two independently admitted records, retaining unchanged subtrees.\n * Both operands must come from successful admission, and the patch must be a\n * fresh copy: their trees must be disjoint. Each output branch then comes from\n * at most one location in either tree, preserving the no-repeated-reference\n * invariant without walking retained subtrees. Limits apply to the result.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nexport const mergeRecords = (\n  base: { readonly [key: string]: Json },\n  patch: { readonly [key: string]: Json },\n  limits: Limits = defaultLimits\n): Admission => {\n  const merge = (\n    left: { readonly [key: string]: Json },\n    right: { readonly [key: string]: Json },\n    path: string\n  ): Admission => {\n    const entries = new Map(snapshots.get(left)!.entries)\n    const result = { ...left }\n    for (const [key, entry] of snapshots.get(right)!.entries) {\n      const previous = left[key]\n      const next = right[key]!\n      if (\n        typeof previous === \"object\" && previous !== null && !Array.isArray(previous) &&\n        typeof next === \"object\" && next !== null && !Array.isArray(next)\n      ) {\n        const merged = merge(\n          previous as { readonly [key: string]: Json },\n          next as { readonly [key: string]: Json },\n          childPath(path, key)\n        )\n        if (!merged.ok) return merged\n        result[key] = merged.value\n        entries.set(key, { keyBytes: entry.keyBytes, totals: snapshots.get(merged.value as object)!.totals })\n      } else {\n        result[key] = next\n        entries.set(key, entry)\n      }\n    }\n    const totals = total(entries)\n    const complaint = totals.members > limits.maxMembers ?\n      `exceeds the ${limits.maxMembers}-member limit`\n      : totals.nodes > limits.maxNodes ?\n      `exceeds the ${limits.maxNodes}-node limit`\n      : totals.bytes > limits.maxBytes ?\n      `exceeds the ${limits.maxBytes}-byte limit`\n      : totals.depth > limits.maxDepth ?\n      `exceeds the depth limit of ${limits.maxDepth}`\n      : undefined\n    if (complaint !== undefined) return { ok: false, path: boundedPath(path), complaint }\n    Object.freeze(result)\n    snapshots.set(result, { totals, entries })\n    return { ok: true, value: result }\n  }\n  return merge(base, patch, \"$\")\n}\n"]}

package/dist/esm/internal/mergePluginLayers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Effect layer composition for a resolved plugin list.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+import { Action } from "@smthrs/flow";
+import * as Layer from "effect/Layer";
+import type { FlowsPlugin } from "../Plugin.ts";
+import { PluginError } from "../PluginError.ts";
+/**
+ * Merges plugin layers left-to-right, wrapping each build failure as
+ * `layer_failed`, then seals the cache environment: it is supplied beneath
+ * the plugin layers and overrides anything they output, and an absent
+ * declaration stays absent.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export declare const mergePluginLayers: <H>(plugins: ReadonlyArray<FlowsPlugin<H>>, cacheEnvironment: Action.CacheEnvironment | undefined) => Layer.Layer<any, PluginError, any>;
+//# sourceMappingURL=mergePluginLayers.d.ts.map

package/dist/esm/internal/mergePluginLayers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mergePluginLayers.d.ts","sourceRoot":"","sources":["../../../src/internal/mergePluginLayers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAErC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,EACjC,SAAS,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EACtC,kBAAkB,MAAM,CAAC,gBAAgB,GAAG,SAAS,KACpD,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,CA+BnC,CAAA"}

package/dist/esm/internal/mergePluginLayers.js

@@ -0,0 +1,41 @@
+/**
+ * Effect layer composition for a resolved plugin list.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+import { Action } from "@smthrs/flow";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { PluginError } from "../PluginError.js";
+/**
+ * Merges plugin layers left-to-right, wrapping each build failure as
+ * `layer_failed`, then seals the cache environment: it is supplied beneath
+ * the plugin layers and overrides anything they output, and an absent
+ * declaration stays absent.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const mergePluginLayers = (plugins, cacheEnvironment) => {
+    const layers = plugins.flatMap((plugin) => plugin.layer
+        ? [
+            Layer.catchCause(plugin.layer, (cause) => Layer.effectDiscard(Effect.fail(new PluginError({
+                code: "layer_failed",
+                message: `plugin "${plugin.name}" failed to build its layer`,
+                plugin: plugin.name,
+                cause
+            }))))
+        ]
+        : []);
+    const merged = (layers.length === 0
+        ? Layer.empty
+        : layers.reduce((accumulated, next) => Layer.provideMerge(next, accumulated)));
+    // The sealed environment is provided beneath the plugin layers so they can
+    // read it, then merged last so it overrides any plugin output. An absent
+    // declaration is sealed as `undefined`, so no plugin layer can declare or
+    // replace the composition's cache identity.
+    const environment = Layer.succeed(Action.CurrentCacheEnvironment)(cacheEnvironment);
+    return Layer.merge(Layer.provideMerge(merged, environment), environment);
+};
+//# sourceMappingURL=mergePluginLayers.js.map

package/dist/esm/internal/mergePluginLayers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mergePluginLayers.js","sourceRoot":"","sources":["../../../src/internal/mergePluginLayers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,OAAsC,EACtC,gBAAqD,EACjB,EAAE;IACtC,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CACxC,MAAM,CAAC,KAAK;QACV,CAAC,CAAC;YACA,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CACvC,KAAK,CAAC,aAAa,CACjB,MAAM,CAAC,IAAI,CACT,IAAI,WAAW,CAAC;gBACd,IAAI,EAAE,cAAc;gBACpB,OAAO,EAAE,WAAW,MAAM,CAAC,IAAI,6BAA6B;gBAC5D,MAAM,EAAE,MAAM,CAAC,IAAI;gBACnB,KAAK;aACN,CAAC,CACH,CACF,CAAuC;SAC3C;QACD,CAAC,CAAC,EAAE,CACP,CAAA;IACD,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;QACjC,CAAC,CAAC,KAAK,CAAC,KAAK;QACb,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAuC,CAAA;IACtH,2EAA2E;IAC3E,yEAAyE;IACzE,0EAA0E;IAC1E,4CAA4C;IAC5C,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,uBAAuB,CAAC,CAAC,gBAAgB,CAIjF,CAAA;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,WAAW,CAAC,CAAA;AAC1E,CAAC,CAAA","sourcesContent":["/**\n * Effect layer composition for a resolved plugin list.\n *\n * @private\n * @since 1.0.0-rc.0\n */\n\nimport { Action } from \"@smthrs/flow\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport type { FlowsPlugin } from \"../Plugin.ts\"\nimport { PluginError } from \"../PluginError.ts\"\n\n/**\n * Merges plugin layers left-to-right, wrapping each build failure as\n * `layer_failed`, then seals the cache environment: it is supplied beneath\n * the plugin layers and overrides anything they output, and an absent\n * declaration stays absent.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nexport const mergePluginLayers = <H>(\n  plugins: ReadonlyArray<FlowsPlugin<H>>,\n  cacheEnvironment: Action.CacheEnvironment | undefined\n): Layer.Layer<any, PluginError, any> => {\n  const layers = plugins.flatMap((plugin) =>\n    plugin.layer\n      ? [\n        Layer.catchCause(plugin.layer, (cause) =>\n          Layer.effectDiscard(\n            Effect.fail(\n              new PluginError({\n                code: \"layer_failed\",\n                message: `plugin \"${plugin.name}\" failed to build its layer`,\n                plugin: plugin.name,\n                cause\n              })\n            )\n          )) as Layer.Layer<any, PluginError, any>\n      ]\n      : []\n  )\n  const merged = (layers.length === 0\n    ? Layer.empty\n    : layers.reduce((accumulated, next) => Layer.provideMerge(next, accumulated))) as Layer.Layer<any, PluginError, any>\n  // The sealed environment is provided beneath the plugin layers so they can\n  // read it, then merged last so it overrides any plugin output. An absent\n  // declaration is sealed as `undefined`, so no plugin layer can declare or\n  // replace the composition's cache identity.\n  const environment = Layer.succeed(Action.CurrentCacheEnvironment)(cacheEnvironment) as unknown as Layer.Layer<\n    any,\n    PluginError,\n    any\n  >\n  return Layer.merge(Layer.provideMerge(merged, environment), environment)\n}\n"]}

package/dist/esm/internal/snapshotCacheEnvironment.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cache identity admission for a resolved plugin list.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+import { Action } from "@smthrs/flow";
+import * as Effect from "effect/Effect";
+import type { FlowsPlugin } from "../Plugin.ts";
+import { PluginError } from "../PluginError.ts";
+/**
+ * Admits a caller cache environment and prepends one escaped `name@version`
+ * identity per plugin, in resolved order. An absent input stays absent.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export declare const snapshotCacheEnvironment: <H>(input: unknown, plugins: ReadonlyArray<FlowsPlugin<H>>) => Effect.Effect<Action.CacheEnvironment | undefined, PluginError>;
+//# sourceMappingURL=snapshotCacheEnvironment.d.ts.map

package/dist/esm/internal/snapshotCacheEnvironment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotCacheEnvironment.d.ts","sourceRoot":"","sources":["../../../src/internal/snapshotCacheEnvironment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AACrC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAO/C;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,EACxC,OAAO,OAAO,EACd,SAAS,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,KACrC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,gBAAgB,GAAG,SAAS,EAAE,WAAW,CAgDhE,CAAA"}

package/dist/esm/internal/snapshotCacheEnvironment.js

@@ -0,0 +1,63 @@
+/**
+ * Cache identity admission for a resolved plugin list.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+import { Action } from "@smthrs/flow";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { PluginError } from "../PluginError.js";
+import * as Boundary from "./Boundary.js";
+const escapePluginIdentityPart = (value) => 
+// Percent must be escaped first so literal escape-looking text remains distinct from the `@` escape added next.
+value.replaceAll("%", "%25").replaceAll("@", "%40");
+/**
+ * Admits a caller cache environment and prepends one escaped `name@version`
+ * identity per plugin, in resolved order. An absent input stays absent.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const snapshotCacheEnvironment = (input, plugins) => {
+    if (input === undefined)
+        return Effect.succeed(undefined);
+    const pluginIdentities = [];
+    for (const plugin of plugins) {
+        if (plugin.version === undefined) {
+            return Effect.fail(new PluginError({
+                code: "cache_environment_invalid",
+                message: `cache environment requires a version for plugin "${plugin.name}"`,
+                path: "$.version",
+                plugin: plugin.name
+            }));
+        }
+        pluginIdentities.push(`${escapePluginIdentityPart(plugin.name)}@${escapePluginIdentityPart(plugin.version)}`);
+    }
+    const admitted = Boundary.record(input);
+    if (!admitted.ok) {
+        return Effect.fail(new PluginError({
+            code: "cache_environment_invalid",
+            message: `cache environment ${admitted.complaint}`,
+            path: `$options.cacheEnvironment${admitted.path.slice(1)}`
+        }));
+    }
+    return Schema.decodeUnknownEffect(Action.CacheEnvironment)(admitted.value).pipe(Effect.mapError(() => new PluginError({
+        code: "cache_environment_invalid",
+        message: "cache environment does not match the complete cache identity schema",
+        path: "$options.cacheEnvironment"
+    })), Effect.map((environment) => {
+        const capabilities = {};
+        for (const name of Object.keys(environment.capabilities)) {
+            Object.defineProperty(capabilities, name, {
+                value: Object.freeze([...environment.capabilities[name]]),
+                enumerable: true
+            });
+        }
+        return Object.freeze({
+            layers: Object.freeze([...pluginIdentities, ...environment.layers]),
+            capabilities: Object.freeze(capabilities)
+        });
+    }));
+};
+//# sourceMappingURL=snapshotCacheEnvironment.js.map

package/dist/esm/internal/snapshotCacheEnvironment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotCacheEnvironment.js","sourceRoot":"","sources":["../../../src/internal/snapshotCacheEnvironment.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Cache identity admission for a resolved plugin list.\n *\n * @private\n * @since 1.0.0-rc.0\n */\n\nimport { Action } from \"@smthrs/flow\"\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport type { FlowsPlugin } from \"../Plugin.ts\"\nimport { PluginError } from \"../PluginError.ts\"\nimport * as Boundary from \"./Boundary.ts\"\n\nconst escapePluginIdentityPart = (value: string): string =>\n  // Percent must be escaped first so literal escape-looking text remains distinct from the `@` escape added next.\n  value.replaceAll(\"%\", \"%25\").replaceAll(\"@\", \"%40\")\n\n/**\n * Admits a caller cache environment and prepends one escaped `name@version`\n * identity per plugin, in resolved order. An absent input stays absent.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nexport const snapshotCacheEnvironment = <H>(\n  input: unknown,\n  plugins: ReadonlyArray<FlowsPlugin<H>>\n): Effect.Effect<Action.CacheEnvironment | undefined, PluginError> => {\n  if (input === undefined) return Effect.succeed(undefined)\n  const pluginIdentities: Array<string> = []\n  for (const plugin of plugins) {\n    if (plugin.version === undefined) {\n      return Effect.fail(\n        new PluginError({\n          code: \"cache_environment_invalid\",\n          message: `cache environment requires a version for plugin \"${plugin.name}\"`,\n          path: \"$.version\",\n          plugin: plugin.name\n        })\n      )\n    }\n    pluginIdentities.push(`${escapePluginIdentityPart(plugin.name)}@${escapePluginIdentityPart(plugin.version)}`)\n  }\n  const admitted = Boundary.record(input)\n  if (!admitted.ok) {\n    return Effect.fail(\n      new PluginError({\n        code: \"cache_environment_invalid\",\n        message: `cache environment ${admitted.complaint}`,\n        path: `$options.cacheEnvironment${admitted.path.slice(1)}`\n      })\n    )\n  }\n  return Schema.decodeUnknownEffect(Action.CacheEnvironment)(admitted.value).pipe(\n    Effect.mapError(() =>\n      new PluginError({\n        code: \"cache_environment_invalid\",\n        message: \"cache environment does not match the complete cache identity schema\",\n        path: \"$options.cacheEnvironment\"\n      })\n    ),\n    Effect.map((environment) => {\n      const capabilities: Record<string, ReadonlyArray<string>> = {}\n      for (const name of Object.keys(environment.capabilities)) {\n        Object.defineProperty(capabilities, name, {\n          value: Object.freeze([...environment.capabilities[name]!]),\n          enumerable: true\n        })\n      }\n      return Object.freeze({\n        layers: Object.freeze([...pluginIdentities, ...environment.layers]),\n        capabilities: Object.freeze(capabilities)\n      })\n    })\n  )\n}\n"]}

package/docs/README.md

@@ -0,0 +1,131 @@
+---
+title: "@smthrs/plugin"
+description: "A typed, bounded plugin kernel for Effect programs: Vite-style hooks and ordering, a config waterfall, and a resolution boundary that copies every value a caller hands it."
+---
+
+`@smthrs/plugin` lets a TypeScript program accept plugins written by other
+people. You name the extension points your program offers, a plugin author
+hands you a plain record of handlers, and the kernel turns that list into an
+ordered, immutable catalog you dispatch against.
+
+It is Vite's plugin model, typed end to end and bounded at every edge: a plugin
+is a plain record, a hook is an ordinary [Effect](https://effect.website),
+ordering follows Vite's rules exactly, and no value a caller passes in survives
+as a live reference into dispatch.
+
+## What it solves
+
+An extensible program has to answer five questions before its first plugin
+runs: which plugins are selected, what order their handlers run in, what a
+handler may return, what a failing handler does to the caller, and whether a
+plugin can change any of that after startup. This package answers all five, and
+refuses the input that would leave one of them undecided:
+
+- **Selection** is the `apply` field: a host target, or a predicate over the
+  configuration.
+- **Order** is Vite's rule kept verbatim. `enforce` sorts the plugin list once,
+  and a per-hook `order` re-partitions it for a single hook.
+- **Result and failure** come from the hook's kind. `sequential`, `parallel`,
+  `first`, and `waterfall` each promise something different, and the kind is
+  checked in the type system and again against the host's runtime catalog.
+- **Change after startup** is not possible. Resolution copies every plugin
+  record, hook object, and configuration value it accepts, so dispatch never
+  reads memory a caller still holds.
+
+Reach for it when you are the host: you have a composition, you want other
+people's code inside it at named points, and you would rather refuse a
+malformed plugin at startup with an error code and a value path than debug it
+in production.
+
+## The hook catalog is yours
+
+The kernel owns one catalog of its own, the two-step config lifecycle (`config`
+and `configResolved`). Every other hook belongs to a host. You declare your
+hooks with TypeScript module augmentation, hand the kernel the matching runtime
+catalog, and dispatch that catalog and nothing else. The `FlowsHooks` interface
+is open for augmentation and closed for dispatch, so another host augmenting
+the same interface still dispatches only the hooks it supplied.
+
+A plugin author writes a record with a `name` and some `hooks`. There is no base
+class, no registration call, and no inheritance.
+
+## Install
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+Node.js 26.4.0 or later is required. For the runtime requirements, the import
+forms, and the subpaths the export map blocks, see
+[Installation](./installation.md).
+
+## The shortest real example
+
+A plugin contributes a configuration namespace, and a second hook reads the
+resolved result back:
+
+```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.make` gives you four things:
+
+- `kernel.config` is the frozen, deeply copied configuration every plugin
+  agreed on.
+- `kernel.plugins` dispatches hooks.
+- `kernel.layer` is every plugin's Effect services merged in resolved order.
+- `kernel.observerErrors` holds the failures that `configResolved` observers
+  reported without failing startup.
+
+## Where this sits in Smithers
+
+This package is the mechanism, not a host: on its own it dispatches only the
+config lifecycle. The shipped host is [`@smthrs/agent`](/api/agent), the
+Smithers agent loop, which augments `FlowsHooks` with three waterfall hooks of
+its own (`cellRegistry`, `cellFlows`, and `cellModelRequest`), passes the
+matching runtime catalog with `target: "harness"`, and dispatches them around
+each frame of an agent cell. If you want to extend the Smithers agent rather
+than build a host of your own, read that package first: its hooks are the ones
+your plugin declares, and this package explains what those hooks promise.
+
+Both sit under the `smthrs` command line, [`@smthrs/cli`](/api/cli), which runs
+and inspects the durable flows a Smithers installation is made of. Start there
+for the whole picture.
+
+The kernel depends on [`@smthrs/flow`](/api/flow) for the
+`Action.CacheEnvironment` schema used to
+[declare a cache identity](./guides/cache-identity.md), and
+[`@smthrs/canonical`](/api/canonical) for immutable catalog maps.
+
+## What this package does not do
+
+The kernel 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. Configuration refuses the root keys
+`engine`, `retry`, `store`, and `plugins` so that a configuration file cannot
+imply otherwise.
+
+## Where to go next
+
+- [Installation](./installation.md) for the runtime requirements, the import
+  forms, and the subpaths that are not public.
+- [Quickstart](./quickstart.md) to build a host with its own hook, run it, and
+  read a typed result.
+- [Hook kinds](./concepts/hook-kinds.md) for what each of the four dispatch
+  shapes promises.
+- [Resolution](./concepts/resolution.md) for how a plugin list becomes an
+  ordered, immutable catalog.
+- [Configuration](./concepts/configuration.md) for the config waterfall and the
+  JSON boundary it enforces.
+- [API reference](./api.md) for every export, with signatures and limits.
+- [Troubleshooting](./troubleshooting.md) for each `PluginError` code, what
+  causes it, and what to change.