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

package/dist/esm/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The bounded cell-host plugin kernel: typed hooks, resolution and ordering,
+ * and the config pipeline.
+ *
+ * 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`. Durable
+ * engine extension remains dependency injection; this package does not expose
+ * an engine-wide lifecycle registry.
+ *
+ * @since 1.0.0-rc.0
+ */
+import type * as Effect from "effect/Effect";
+import type { FlowsConfig, ResolvedConfig } from "./Config.ts";
+import type { ParallelHook, WaterfallHook } from "./Hooks.ts";
+/**
+ * The shared kernel's base hook catalog.
+ *
+ * Declared here, in the package entry point, so that the documented
+ * augmentation specifier works: an interface can only be augmented in the
+ * module that declares it:
+ *
+ * ```ts
+ * declare module "@smthrs/plugin" {
+ *   interface FlowsHooks {
+ *     toolCall: SequentialHook<(ctx: ToolCallContext) => Effect.Effect<Option.Option<ToolOverride>>>
+ *   }
+ * }
+ * ```
+ *
+ * Closed for dispatch, open for augmentation: the kernel dispatches only the
+ * config lifecycle below; a host supplies and dispatches its own catalog over
+ * the same augmented interface.
+ *
+ * Both startup hooks are context-free: `Kernel.make` runs them before any
+ * plugin layer exists and supplies no services of its own, so a handler that
+ * needs a service provides it inside the hook. A host whose startup hooks do
+ * require services declares a separate hook interface, and `Kernel.make` then
+ * surfaces those requirements as `Kernel.StartupContext<H>`.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface FlowsHooks {
+    readonly config: WaterfallHook<(config: FlowsConfig) => Effect.Effect<Partial<FlowsConfig> | void, any, never>>;
+    readonly configResolved: ParallelHook<(config: ResolvedConfig) => Effect.Effect<void, any, never>>;
+}
+/**
+ * @since 1.0.0-rc.0
+ * @category config
+ */
+export * as Config from "./Config.ts";
+/**
+ * @since 1.0.0-rc.0
+ * @category hooks
+ */
+export * from "./Hooks.ts";
+/**
+ * @since 1.0.0-rc.0
+ * @category startup
+ */
+export * as Kernel from "./Kernel.ts";
+/**
+ * @since 1.0.0-rc.0
+ * @category models
+ */
+export * from "./Plugin.ts";
+/**
+ * @since 1.0.0-rc.0
+ * @category errors
+ */
+export * from "./PluginError.ts";
+/**
+ * @since 1.0.0-rc.0
+ * @category dispatch
+ */
+export * as Plugins from "./Plugins.ts";
+/**
+ * @since 1.0.0-rc.0
+ * @category resolution
+ */
+export * as Resolve from "./Resolve.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,MAAM,EAAE,WAAW,KAAK,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAA;IAC/G,QAAQ,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC,MAAM,EAAE,cAAc,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAA;CACnG;AAED;;;GAGG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;GAGG;AACH,cAAc,YAAY,CAAA;AAE1B;;;GAGG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;GAGG;AACH,cAAc,aAAa,CAAA;AAE3B;;;GAGG;AACH,cAAc,kBAAkB,CAAA;AAEhC;;;GAGG;AACH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC;;;GAGG;AACH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA"}

package/dist/esm/index.js

@@ -0,0 +1,48 @@
+/**
+ * The bounded cell-host plugin kernel: typed hooks, resolution and ordering,
+ * and the config pipeline.
+ *
+ * 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`. Durable
+ * engine extension remains dependency injection; this package does not expose
+ * an engine-wide lifecycle registry.
+ *
+ * @since 1.0.0-rc.0
+ */
+/**
+ * @since 1.0.0-rc.0
+ * @category config
+ */
+export * as Config from "./Config.js";
+/**
+ * @since 1.0.0-rc.0
+ * @category hooks
+ */
+export * from "./Hooks.js";
+/**
+ * @since 1.0.0-rc.0
+ * @category startup
+ */
+export * as Kernel from "./Kernel.js";
+/**
+ * @since 1.0.0-rc.0
+ * @category models
+ */
+export * from "./Plugin.js";
+/**
+ * @since 1.0.0-rc.0
+ * @category errors
+ */
+export * from "./PluginError.js";
+/**
+ * @since 1.0.0-rc.0
+ * @category dispatch
+ */
+export * as Plugins from "./Plugins.js";
+/**
+ * @since 1.0.0-rc.0
+ * @category resolution
+ */
+export * as Resolve from "./Resolve.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuCH;;;GAGG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;GAGG;AACH,cAAc,YAAY,CAAA;AAE1B;;;GAGG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAErC;;;GAGG;AACH,cAAc,aAAa,CAAA;AAE3B;;;GAGG;AACH,cAAc,kBAAkB,CAAA;AAEhC;;;GAGG;AACH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AAEvC;;;GAGG;AACH,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA","sourcesContent":["/**\n * The bounded cell-host plugin kernel: typed hooks, resolution and ordering,\n * and the config pipeline.\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`. Durable\n * engine extension remains dependency injection; this package does not expose\n * an engine-wide lifecycle registry.\n *\n * @since 1.0.0-rc.0\n */\n\nimport type * as Effect from \"effect/Effect\"\nimport type { FlowsConfig, ResolvedConfig } from \"./Config.ts\"\nimport type { ParallelHook, WaterfallHook } from \"./Hooks.ts\"\n\n/**\n * The shared kernel's base hook catalog.\n *\n * Declared here, in the package entry point, so that the documented\n * augmentation specifier works: an interface can only be augmented in the\n * module that declares it:\n *\n * ```ts\n * declare module \"@smthrs/plugin\" {\n *   interface FlowsHooks {\n *     toolCall: SequentialHook<(ctx: ToolCallContext) => Effect.Effect<Option.Option<ToolOverride>>>\n *   }\n * }\n * ```\n *\n * Closed for dispatch, open for augmentation: the kernel dispatches only the\n * config lifecycle below; a host supplies and dispatches its own catalog over\n * the same augmented interface.\n *\n * Both startup hooks are context-free: `Kernel.make` runs them before any\n * plugin layer exists and supplies no services of its own, so a handler that\n * needs a service provides it inside the hook. A host whose startup hooks do\n * require services declares a separate hook interface, and `Kernel.make` then\n * surfaces those requirements as `Kernel.StartupContext<H>`.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface FlowsHooks {\n  readonly config: WaterfallHook<(config: FlowsConfig) => Effect.Effect<Partial<FlowsConfig> | void, any, never>>\n  readonly configResolved: ParallelHook<(config: ResolvedConfig) => Effect.Effect<void, any, never>>\n}\n\n/**\n * @since 1.0.0-rc.0\n * @category config\n */\nexport * as Config from \"./Config.ts\"\n\n/**\n * @since 1.0.0-rc.0\n * @category hooks\n */\nexport * from \"./Hooks.ts\"\n\n/**\n * @since 1.0.0-rc.0\n * @category startup\n */\nexport * as Kernel from \"./Kernel.ts\"\n\n/**\n * @since 1.0.0-rc.0\n * @category models\n */\nexport * from \"./Plugin.ts\"\n\n/**\n * @since 1.0.0-rc.0\n * @category errors\n */\nexport * from \"./PluginError.ts\"\n\n/**\n * @since 1.0.0-rc.0\n * @category dispatch\n */\nexport * as Plugins from \"./Plugins.ts\"\n\n/**\n * @since 1.0.0-rc.0\n * @category resolution\n */\nexport * as Resolve from \"./Resolve.ts\"\n"]}

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,23 @@
+/**
+ * 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. A
+ * versionless plugin is refused at the dollar-path it was admitted from.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export declare const snapshotCacheEnvironment: <H>(input: unknown, plugins: ReadonlyArray<{
+    readonly plugin: FlowsPlugin<H>;
+    readonly path: string;
+}>) => 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;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,EACxC,OAAO,OAAO,EACd,SAAS,aAAa,CAAC;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,KACjF,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,gBAAgB,GAAG,SAAS,EAAE,WAAW,CAgDhE,CAAA"}

package/dist/esm/internal/snapshotCacheEnvironment.js

@@ -0,0 +1,64 @@
+/**
+ * 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. A
+ * versionless plugin is refused at the dollar-path it was admitted from.
+ *
+ * @private
+ * @since 1.0.0-rc.0
+ */
+export const snapshotCacheEnvironment = (input, plugins) => {
+    if (input === undefined)
+        return Effect.succeed(undefined);
+    const pluginIdentities = [];
+    for (const { path, 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: `${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. A\n * versionless plugin is refused at the dollar-path it was admitted from.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nexport const snapshotCacheEnvironment = <H>(\n  input: unknown,\n  plugins: ReadonlyArray<{ readonly plugin: FlowsPlugin<H>; readonly path: string }>\n): Effect.Effect<Action.CacheEnvironment | undefined, PluginError> => {\n  if (input === undefined) return Effect.succeed(undefined)\n  const pluginIdentities: Array<string> = []\n  for (const { path, 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: `${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"]}