@cldmv/slothlet-types 3.16.3 → 3.17.0

package/lib/handlers/event-manager.d.mts

@@ -0,0 +1,77 @@
+/**
+ * Instance-wide event manager (#407).
+ * @extends ComponentBase
+ * @public
+ */
+export class EventManager extends ComponentBase {
+    /**
+     * Where this component mounts on the Slothlet instance (`slothlet.handlers.eventManager`).
+     * @type {string}
+     */
+    static slothletProperty: string;
+    /**
+     * @param {object} slothlet - Slothlet instance.
+     */
+    constructor(slothlet: object);
+    /**
+     * Subscribe a listener to an event. The subscriber's granted delivery level is resolved from the
+     * event-rule pool against its own identity and returned so the caller knows whether it will
+     * receive payloads.
+     *
+     * @param {string} event - Event name to subscribe to.
+     * @param {Function} listener - Listener, called `(payload, meta)` on emit. At `notify`, `payload`
+     *   is `undefined`; `meta` is `{ event, at, instanceID }`.
+     * @param {object} [options={}] - Options.
+     * @param {boolean} [options.once=false] - Remove the subscription after its first delivery.
+     * @returns {{ level: "deny"|"notify"|"allow", off: Function }} The granted level and an unsubscribe
+     *   function. At `deny` the listener is not registered and `off` is a no-op.
+     * @throws {SlothletError} INVALID_ARGUMENT for a non-string event or non-function listener.
+     * @public
+     */
+    public on(event: string, listener: Function, options?: {
+        once?: boolean | undefined;
+    }): {
+        level: "deny" | "notify" | "allow";
+        off: Function;
+    };
+    /**
+     * Subscribe for a single delivery, then auto-unsubscribe. Shorthand for `on(event, listener, { once: true })`.
+     * @param {string} event - Event name.
+     * @param {Function} listener - Listener.
+     * @param {object} [options={}] - Options (merged with `once: true`).
+     * @returns {{ level: "deny"|"notify"|"allow", off: Function }} The granted level and unsubscribe.
+     * @public
+     */
+    public once(event: string, listener: Function, options?: object): {
+        level: "deny" | "notify" | "allow";
+        off: Function;
+    };
+    /**
+     * Remove a specific listener from an event.
+     * @param {string} event - Event name.
+     * @param {Function} listener - The listener reference passed to `on`/`once`.
+     * @returns {boolean} True if a matching subscription was removed.
+     * @public
+     */
+    public off(event: string, listener: Function): boolean;
+    /**
+     * Emit an event to its subscribers. NOT gated — any caller may emit; the three-level policy is
+     * enforced per subscriber at delivery. Async, fire-and-forget, per-listener error isolation:
+     * a throwing listener surfaces a `SlothletWarning` and never affects the others or the emitter.
+     *
+     * @param {string} event - Event name.
+     * @param {*} [payload] - Domain payload, delivered only to `allow`-level subscribers.
+     * @returns {Promise<void>} Resolves once all listeners (including async) have settled.
+     * @throws {SlothletError} INVALID_ARGUMENT for a non-string event.
+     * @public
+     */
+    public emit(event: string, payload?: any): Promise<void>;
+    /**
+     * Tear down all subscriptions. Called from `Slothlet.shutdown()`.
+     * @returns {void}
+     * @public
+     */
+    public shutdown(): void;
+    #private;
+}
+import { ComponentBase } from "#factories/component-base";

package/lib/handlers/permission-manager.d.mts

@@ -39,7 +39,7 @@ export class PermissionManager extends ComponentBase {
         caller: string;
         target: string;
         effect: string;
-    }, ownerModuleID?: string | null, ruleId?: string | null): string;
+    }, ownerModuleID?: string | null, ruleId?: string | null, layer?: null): string;
     /**
      * Remove a permission rule by ID.
      * A module cannot remove rules it owns (immutability).
@@ -52,6 +52,65 @@ export class PermissionManager extends ComponentBase {
      * pm.removeRule("perm-3", "mod_other");
      */
     removeRule(ruleId: string, callerModuleID?: string | null): boolean;
+    /**
+     * Add an event rule (#407). Separate three-level construct from {@link addRule}: `effect` is
+     * "deny" | "notify" | "allow". Matched most-specific-wins with the same layered tiebreak; the
+     * EventManager uses it to resolve each subscriber's delivery level.
+     *
+     * @param {object} rule - The event-rule definition.
+     * @param {string} rule.caller - Glob matching the SUBSCRIBER's api path.
+     * @param {string} rule.event - Glob matching the event name.
+     * @param {"deny"|"notify"|"allow"} rule.effect - Delivery level.
+     * @param {object|Function|Array<object|Function>} [rule.condition] - Optional condition(s).
+     * @param {string|null} [ownerModuleID=null] - Owning module id ("__builtin__" for framework).
+     * @param {string|null} [ruleId=null] - Optional rule id to reuse (for reload replay).
+     * @param {string|null} [layer=null] - Explicit precedence layer; derived from ownerModuleID when null.
+     * @returns {string} The rule id.
+     * @throws {SlothletError} INVALID_PERMISSION_RULE if the rule is malformed.
+     * @example
+     * pm.addEventRule({ caller: "orders.**", event: "orders.*", effect: "allow" }, "mod_orders", null, "manifest");
+     */
+    addEventRule(rule: {
+        caller: string;
+        event: string;
+        effect: "deny" | "notify" | "allow";
+        condition?: object | Function | (object | Function)[] | undefined;
+    }, ownerModuleID?: string | null, ruleId?: string | null, layer?: string | null): string;
+    /**
+     * Remove an event rule by id. A module cannot remove an event rule it owns (immutability),
+     * mirroring {@link removeRule}.
+     *
+     * @param {string} ruleId - The event-rule id.
+     * @param {string|null} [callerModuleID=null] - Module id attempting removal.
+     * @returns {boolean} True if a rule was removed.
+     * @throws {SlothletError} PERMISSION_SELF_MODIFY if the caller owns the rule.
+     */
+    removeEventRule(ruleId: string, callerModuleID?: string | null): boolean;
+    /**
+     * Resolve the delivery level for a subscriber/event pair (#407): "deny" | "notify" | "allow".
+     * Most-specific-wins with the layered tiebreak (see {@link RULE_LAYER_RANK}); falls back to the
+     * base default (`permissions.events.default`, built-in "notify") when no rule matches. A host
+     * subscription (no module caller) is trusted like a host-initiated call and always resolves "allow".
+     *
+     * @param {string|null} subscriberPath - The subscribing module's api path, or null for the host.
+     * @param {string} eventName - The event name being subscribed to / emitted.
+     * @param {object|null} [runtimeContext=null] - Per-request ALS context for condition evaluation.
+     * @returns {"deny"|"notify"|"allow"} The resolved delivery level.
+     */
+    resolveEventLevel(subscriberPath: string | null, eventName: string, runtimeContext?: object | null): "deny" | "notify" | "allow";
+    /**
+     * Monotonic epoch that changes on every event-rule mutation. The EventManager caches resolved
+     * levels against it and re-resolves only when it changes.
+     * @returns {number} The current event-rules epoch.
+     */
+    get eventRulesEpoch(): number;
+    /**
+     * Whether any event rule carries a condition. When false, a resolved subscriber level depends
+     * only on the rule set and can be safely cached against {@link eventRulesEpoch}; when true, the
+     * level can vary with the per-request context and must be re-resolved on each emit.
+     * @returns {boolean} True if at least one event rule has a condition.
+     */
+    get hasConditionalEventRules(): boolean;
     /**
      * Silent query: check whether a caller path is allowed to access a target path.
      * Never emits lifecycle or debug events — use {@link enforceAccess} at actual enforcement points.

package/lib/handlers/routine-manager.d.mts

@@ -317,6 +317,37 @@ export class RoutineManager extends ComponentBase {
      * @public
      */
     public runPath(apiPath: string, args?: any[], routine?: object): Promise<any>;
+    /**
+     * Run ONE contributor at an exact api path, selected by its `moduleID` (#400 — the mechanism
+     * behind `api.<path>.<name>.for(key)`). Unlike {@link runPath}, this deliberately does NOT apply
+     * the `stackRoutines` owner-filter: selecting a specific co-owner by key is the whole point, so a
+     * contributor that would lose the shared-path collision still runs when addressed directly. The
+     * contributor runs in its own extent + identity via {@link #runEntries}, exactly as a normal
+     * stacked/cascade run does — so `self.*` and permission checks resolve against that contributor.
+     * @param {string} apiPath - Exact composed api path.
+     * @param {string} key - The contributor's `moduleID`.
+     * @param {Array} [args] - Arguments forwarded to the selected contributor.
+     * @param {object} [routine] - The routine config the selector was built for; entries are filtered
+     *   by {@link #matches} so a different routine sharing the same exact apiPath isn't selected.
+     * @returns {Promise<*>} The selected contributor's return value.
+     * @throws {SlothletError} `INVALID_ARGUMENT` when no contributor with `moduleID === key` matches
+     *   this routine at this path; `ROUTINE_FAILED` when the selected contributor throws.
+     * @public
+     */
+    public runPathFor(apiPath: string, key: string, args?: any[], routine?: object): Promise<any>;
+    /**
+     * List the `moduleID`s of every contributor to a routine at an exact api path, in registration
+     * order (#400 — the mechanism behind `api.<path>.<name>.contributors`). Symmetry with
+     * `versioning.list(path)`: it lets a host discover which co-owners it can address via
+     * {@link runPathFor} / `.for(key)`. Enumerates every contribution regardless of the
+     * `stackRoutines` owner-filter, since `.for(key)` can address any of them.
+     * @param {string} apiPath - Exact composed api path.
+     * @param {object} [routine] - The routine config; entries are filtered by {@link #matches} so a
+     *   different routine sharing the same exact apiPath isn't counted.
+     * @returns {string[]} The contributors' `moduleID`s at this path, in registration order.
+     * @public
+     */
+    public contributorsAt(apiPath: string, routine?: object): string[];
     /**
      * Run the root cascade for a routine: every matching contribution anywhere, grouped by exact
      * api path — with `stackRoutines: true`, contributors colliding at the same path all run
@@ -396,10 +427,11 @@ export class RoutineManager extends ComponentBase {
     public runStartupModeRoutines(): Promise<void>;
     /**
      * Overwrite every currently-known matching api path's slot on the live api tree with its
-     * stacked callable, and (re)attach every configured routine's root cascade at the api root and
-     * under `api.slothlet` (using the routine's `name` verbatim as the property key — a dotted or
-     * `^`-prefixed name is reachable via bracket notation, e.g. `api.slothlet["admin.initialize"]`,
-     * `api["^ext.*.initialize"]`; only a bare name gets clean dot-notation access).
+     * stacked callable, and (re)attach every configured routine's root cascade at the api root
+     * (using the routine's `name` verbatim as the property key — a dotted or `^`-prefixed name is
+     * reachable via bracket notation, e.g. `api["^ext.*.initialize"]`; only a bare name gets clean
+     * dot-notation access). A routine configured with `cascade: false` (#400) gets no root cascade.
+     * The cascade lives only at the root `api.<name>`, never mirrored onto `api.slothlet.*` (#399).
      *
      * @description
      * Safe to call repeatedly — at the end of initial `load()`, again after every

package/lib/helpers/config.d.mts

@@ -242,12 +242,13 @@ export class Config extends ComponentBase {
      * a root cascade runs every matching contribution anywhere, ordered per the entry's `order`.
      * See `docs/LIFECYCLE.md` ("Routines") for the full contract.
      *
-     * Each entry normalizes to `{ name, mode, recursive, order }` — `recursive` and `order` are
-     * always present on the normalized output, even when the raw entry omitted them:
-     * - `"name"` (string, no `:`) → `{ name, mode: "manual", recursive: false, order: "mount" }`.
-     * - `"name:mode"` (string, split once on the first `:`) → `{ name, mode, recursive: false, order: <mode-defaulted> }`.
-     * - `{ name, mode?, recursive?, order? }` (object) → `mode` defaults to `"manual"`, `recursive` to
-     *   `false`, and `order` to {@link DEFAULT_ROUTINE_ORDER_BY_MODE}`[mode]` when each is omitted.
+     * Each entry normalizes to `{ name, mode, recursive, order, cascade }` — `recursive`, `order` and
+     * `cascade` are always present on the normalized output, even when the raw entry omitted them:
+     * - `"name"` (string, no `:`) → `{ name, mode: "manual", recursive: false, order: "mount", cascade: true }`.
+     * - `"name:mode"` (string, split once on the first `:`) → `{ name, mode, recursive: false, order: <mode-defaulted>, cascade: true }`.
+     * - `{ name, mode?, recursive?, order?, cascade? }` (object) → `mode` defaults to `"manual"`, `recursive`
+     *   to `false`, `order` to {@link DEFAULT_ROUTINE_ORDER_BY_MODE}`[mode]`, and `cascade` to `true` when each
+     *   is omitted. `cascade: false` (#400) suppresses the root `api.<name>()` run-all cascade for that routine.
      *
      * Providing `routines` at all REPLACES {@link DEFAULT_ROUTINES} — that is the off-switch
      * (`routines: []` disables every routine). Omitting the option keeps the built-in defaults.
@@ -258,8 +259,8 @@ export class Config extends ComponentBase {
      * normalizes to an equivalent list — same values, always freshly-built objects (never the same
      * references) — so `reload()` can safely re-feed it.
      *
-     * @param {undefined|null|Array<string|{name: string, mode?: string, recursive?: boolean, order?: string}>} routines - Raw `routines` option.
-     * @returns {Array<{name: string, mode: "manual"|"startup"|"shutdown"|"destroy", recursive: boolean, order: "mount"|"depth"}>} Normalized routines list.
+     * @param {undefined|null|Array<string|{name: string, mode?: string, recursive?: boolean, order?: string, cascade?: boolean}>} routines - Raw `routines` option.
+     * @returns {Array<{name: string, mode: "manual"|"startup"|"shutdown"|"destroy", recursive: boolean, order: "mount"|"depth", cascade: boolean}>} Normalized routines list.
      * @throws {SlothletError} INVALID_CONFIG when the shape is invalid, a name is empty/reserved/an invalid glob, or a mode/order is unrecognized.
      * @public
      *
@@ -283,11 +284,13 @@ export class Config extends ComponentBase {
         mode?: string;
         recursive?: boolean;
         order?: string;
+        cascade?: boolean;
     }>): Array<{
         name: string;
         mode: "manual" | "startup" | "shutdown" | "destroy";
         recursive: boolean;
         order: "mount" | "depth";
+        cascade: boolean;
     }>;
     /**
      * Normalize permissions configuration.

package/lib/helpers/pattern-matcher.d.mts

@@ -1,7 +1,9 @@
 /**
  * Compile a glob pattern into a matcher function.
  * Supports: * (any chars except .), ** (any chars including .), ? (single char),
- * {a,b} brace expansion, !pattern negation
+ * {a,b} brace expansion, !pattern whole-pattern negation, and !(a|b) scoped exclusion —
+ * a per-segment complement matching any single segment except the listed literal alternatives
+ * (e.g. `admin.!(initialize)` matches `admin.start` but not `admin.initialize`).
  *
  * @param {string} pattern - Glob pattern
  * @param {object} [options={}] - Options

package/lib/helpers/utilities.d.mts

@@ -38,8 +38,10 @@ export class Utilities extends ComponentBase {
      * Strategy:
      * 1. Try `structuredClone` — fast and spec-correct for plain data.
      * 2. Fall back to a manual recursive copy for Proxies, callables, and other
-     *    non-serialisable objects; errors on individual property clones are swallowed
-     *    and the original reference is retained for that key.
+     *    non-serialisable objects. Callables (functions / callable Proxies) are kept
+     *    BY REFERENCE — they cannot be reconstructed from a property copy — while the
+     *    surrounding data is still deep-cloned; errors on individual property clones are
+     *    swallowed and the original reference is retained for that key.
      *
      * @param {unknown} obj - Value to clone.
      * @returns {unknown} Deep clone of `obj`.

package/lib/processors/flatten.d.mts

@@ -78,7 +78,7 @@ export class Flatten extends ComponentBase {
     };
     /**
      * Build category-level flattening decisions.
-     * Implements conditions C10-C33 from buildCategoryDecisions().
+     * Implements conditions C10-C24 from buildCategoryDecisions().
      * @param {object} options - Category options
      * @param {string} options.categoryName - Category name
      * @param {object} options.mod - Module exports

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cldmv/slothlet-types",
-	"version": "3.16.3",
+	"version": "3.17.0",
 	"description": "TypeScript declaration files (.d.mts) for @cldmv/slothlet. Install alongside @cldmv/slothlet for editor and type-checker support.",
 	"keywords": [
 		"slothlet",
@@ -79,7 +79,7 @@
 		"LICENSE"
 	],
 	"peerDependencies": {
-		"@cldmv/slothlet": "3.16.3"
+		"@cldmv/slothlet": "3.17.0"
 	},
 	"peerDependenciesMeta": {
 		"@cldmv/slothlet": {

package/slothlet.d.mts

@@ -156,13 +156,14 @@ export type SlothletOptions = {
      */
     collectLifecycleHooks?: boolean | undefined;
     /**
-     * - Stackable lifecycle routines (#341). Every mounted module exporting a function matching a configured routine name is composed into one callable at its exact composed api path, plus a root cascade (`self.<name>()`, i.e. `api.<name>()`) that runs every matching contribution anywhere. Entries: `"name"` (mode `"manual"`), `"name:mode"`, or `{ name, mode?, recursive?, order? }` (`recursive`/`order` only settable via the object form). `name` is mount-relative by default (a bare name matches only a mount's own top level; a dotted name matches a fixed relative sub-path, or with `recursive: true` any depth within the mount); a `^`-prefixed name is root-anchored, matched via glob (`*`, `**`, `{}`, `!`) against the full api path, crossing mount boundaries. `order` (`"mount"` | `"depth"`, mode-defaulted) controls the root cascade's grouping order. Providing `routines` at all REPLACES the built-in defaults (`slothlet.defaults.routines`: `initialize` → `startup`, `shutdown` → `shutdown`) — spread `slothlet.defaults.routines` to extend them instead, or pass `[]` to disable every routine. Every configured routine is always wrapped and directly callable regardless of `autoRoutines`. Whether two or more contributors colliding at the identical api path all run is governed by `stackRoutines` (#365), independent of `collisionMode` — by default only the single contribution that actually owns that path runs, matching ordinary collision behavior. A throwing contributor doesn't stop the chain — every contributor runs (best-effort), and one aggregate `ROUTINE_FAILED` error is thrown afterward if any failed. See [LIFECYCLE.md](docs/LIFECYCLE.md#routines).
+     * - Stackable lifecycle routines (#341). Every mounted module exporting a function matching a configured routine name is composed into one callable at its exact composed api path, plus a root cascade (`self.<name>()`, i.e. `api.<name>()`) that runs every matching contribution anywhere. Entries: `"name"` (mode `"manual"`), `"name:mode"`, or `{ name, mode?, recursive?, order?, cascade? }` (`recursive`/`order`/`cascade` only settable via the object form). `name` is mount-relative by default (a bare name matches only a mount's own top level; a dotted name matches a fixed relative sub-path, or with `recursive: true` any depth within the mount); a `^`-prefixed name is root-anchored, matched via glob (`*`, `**`, `{}`, `!`) against the full api path, crossing mount boundaries. `order` (`"mount"` | `"depth"`, mode-defaulted) controls the root cascade's grouping order. `cascade` (default `true`) controls whether the root `api.<name>()` run-all cascade is created at all — set `cascade: false` (#400) for a per-entity lifecycle routine, where the host must invoke exactly one co-owner by key via `api.<path>.<name>.for(moduleID)(...)` rather than a run-all; every stacked path also exposes `api.<path>.<name>.contributors` (the moduleIDs present there). `.for(key)` runs that one contributor in its own extent/identity with the args passed straight through, and bypasses the `stackRoutines` owner-filter so a specific co-owner runs even if it lost the shared-path collision. Providing `routines` at all REPLACES the built-in defaults (`slothlet.defaults.routines`: `initialize` → `startup`, `shutdown` → `shutdown`) — spread `slothlet.defaults.routines` to extend them instead, or pass `[]` to disable every routine. Every configured routine is always wrapped and directly callable regardless of `autoRoutines`. Whether two or more contributors colliding at the identical api path all run is governed by `stackRoutines` (#365), independent of `collisionMode` — by default only the single contribution that actually owns that path runs, matching ordinary collision behavior. A throwing contributor doesn't stop the chain — every contributor runs (best-effort), and one aggregate `ROUTINE_FAILED` error is thrown afterward if any failed. See [LIFECYCLE.md](docs/LIFECYCLE.md#routines).
      */
     routines?: (string | {
         name: string;
         mode?: ("manual" | "startup" | "shutdown" | "destroy");
         recursive?: boolean;
         order?: ("mount" | "depth");
+        cascade?: boolean;
     })[] | undefined;
     /**
      * - The non-deprecated replacement for `collectLifecycleHooks`. TEMPORARY v3-compat default (#341): `false` for now, so a project upgrading sees no behavior change from a pre-existing nested leaf that happens to share a routine's name (e.g. `shutdown`) — it stays stacked and directly callable, but does not start auto-firing. When `true`, every `mode: "startup"` routine's cascade runs at the end of compose, and every `mode: "shutdown"`/`"destroy"` routine's cascade runs on the corresponding dispose call. Planned to default to `true` in v4 (`collectLifecycleHooks` removed at the same time) — see [LIFECYCLE.md](docs/LIFECYCLE.md#routines).