@cldmv/slothlet-types 3.18.2 → 3.20.0

package/lib/factories/component-base.d.mts

@@ -171,5 +171,48 @@ export class ComponentBase {
         moduleID?: string | undefined;
         error?: Error | undefined;
     }): Promise<void>;
+    /**
+     * Emit the public `impl:collision` lifecycle event (#441).
+     * @param {object} data - Collision payload (every field is passed explicitly by the call site).
+     * @param {string} data.apiPath - Dot-notation api path where the collision resolved.
+     * @param {"dropped"|"replaced"|"merged"|"stacked"} data.resolution - What became of the two
+     *   writers: `dropped` (incoming discarded, `owner` retained), `replaced` (incoming won, `owner`
+     *   shadowed), `merged` (namespace nodes combined, both retained), `stacked` (both run as a
+     *   routine stack under `stackRoutines`).
+     * @param {string|null} data.incoming - moduleID of the arriving writer (`null` when unknown).
+     * @param {string|null} data.owner - moduleID of the writer that already held the path (`null`
+     *   when unknown).
+     * @param {"value"|"namespace"} data.kind - Whether the colliding contribution is a value leaf
+     *   or a namespace node.
+     * @param {string|null} data.collisionMode - The mode that resolved it (`skip`/`warn`/`replace`/
+     *   `merge`/`merge-replace`), or `null` where a mode is not meaningful (e.g. `stacked`).
+     * @returns {void}
+     * @package
+     *
+     * @description
+     * Unlike `impl:created` — which fires post-placement for the path WINNER only, so a leaf a merge
+     * discards is never announced — `impl:collision` fires for the collision itself and carries BOTH
+     * writers, so a consumer can observe a silently dropped or shadowed leaf regardless of nesting.
+     *
+     * Fire-and-forget by design: `emit()` isolates each handler's errors and never rejects (mirroring
+     * the `impl:created` re-emit in `src/slothlet.mjs`), so a collision-decision site can announce the
+     * event without awaiting subscriber code inline and without any unhandled rejection escaping.
+     * Synchronous subscribers still run during this call (before `emit()` yields), so an observer that
+     * collects events sees them by the time the composing `await` resolves.
+     *
+     * @example
+     * this.emitImplCollision({
+     *   apiPath: "shared.alpha", resolution: "dropped", incoming: "pkgB_x", owner: "pkgA_y",
+     *   kind: "value", collisionMode: "merge"
+     * });
+     */
+    emitImplCollision({ apiPath, resolution, incoming, owner, kind, collisionMode }: {
+        apiPath: string;
+        resolution: "dropped" | "replaced" | "merged" | "stacked";
+        incoming: string | null;
+        owner: string | null;
+        kind: "value" | "namespace";
+        collisionMode: string | null;
+    }): void;
     #private;
 }

package/lib/handlers/lifecycle.d.mts

@@ -19,7 +19,7 @@ export class Lifecycle extends ComponentBase {
     maxLogSize: number;
     /**
      * Subscribe to lifecycle event
-     * @param {string} event - Event name (impl:created, impl:changed, impl:removed, materialized:complete, path:collision)
+     * @param {string} event - Event name (impl:created, impl:changed, impl:collision, impl:removed, materialized:complete)
      * @param {Function} handler - Event handler function(eventData)
      * @returns {Function} Unsubscribe function
      * @public

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

@@ -1,3 +1,17 @@
+/**
+ * Call/construct metadata threaded into a function condition's second argument so a rule can
+ * authorize on the resource named in the call itself, not just ambient context (#455).
+ *
+ * Provided only at the call and construct enforcement gates — where the invocation's arguments
+ * exist. Read gating, hook gating, event delivery, the internal `slothlet.*` control surface, and
+ * silent queries evaluate conditions with `callMeta === null`, so a function condition that reads
+ * `callMeta.args` must guard for its absence (or the rule must only match targets that always gate
+ * at a call/construct site).
+ *
+ * @typedef {object} PermissionCallMeta
+ * @property {Array<*>|null} args - Arguments the target leaf was called/constructed with, or null.
+ * @property {string|null} target - Concrete (post-glob) target api path of the gated call.
+ */
 /**
  * Manages access control rules for API path invocations.
  * Rules are glob-pattern-based (same syntax as hooks: *, **, ?, {a,b}, !negation).
@@ -151,13 +165,16 @@ export class PermissionManager extends ComponentBase {
      * @param {string|null} [callerFilePath=null] - Caller's source file path (for self-call bypass).
      * @param {string|null} [targetFilePath=null] - Target's source file path (for self-call bypass).
      * @param {object|null} [runtimeContext=null] - Per-request ALS context for condition evaluation.
+     * @param {PermissionCallMeta|null} [callMeta=null] - Call/construct metadata (#455): `{ args, target }`
+     *   from the invocation, forwarded to function conditions as their second argument. Null for reads,
+     *   hooks, the internal control surface, and silent queries.
      * @returns {boolean} True if access is allowed.
      * @example
      * if (!pm.enforceAccess("payments.charge", "db.write", "/src/pay.mjs", "/src/db.mjs")) {
      *   throw new SlothletError("PERMISSION_DENIED", { caller, target });
      * }
      */
-    enforceAccess(callerPath: string, targetPath: string, callerFilePath?: string | null, targetFilePath?: string | null, runtimeContext?: object | null): boolean;
+    enforceAccess(callerPath: string, targetPath: string, callerFilePath?: string | null, targetFilePath?: string | null, runtimeContext?: object | null, callMeta?: PermissionCallMeta | null): boolean;
     /**
      * Enforce whether a caller may register or fire a hook of `hookType` on `hookPath`.
      *
@@ -352,4 +369,24 @@ export class PermissionManager extends ComponentBase {
     private debug;
     #private;
 }
+/**
+ * Call/construct metadata threaded into a function condition's second argument so a rule can
+ * authorize on the resource named in the call itself, not just ambient context (#455).
+ *
+ * Provided only at the call and construct enforcement gates — where the invocation's arguments
+ * exist. Read gating, hook gating, event delivery, the internal `slothlet.*` control surface, and
+ * silent queries evaluate conditions with `callMeta === null`, so a function condition that reads
+ * `callMeta.args` must guard for its absence (or the rule must only match targets that always gate
+ * at a call/construct site).
+ */
+export type PermissionCallMeta = {
+    /**
+     * - Arguments the target leaf was called/constructed with, or null.
+     */
+    args: Array<any> | null;
+    /**
+     * - Concrete (post-glob) target api path of the gated call.
+     */
+    target: string | null;
+};
 import { ComponentBase } from "#factories/component-base";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cldmv/slothlet-types",
-	"version": "3.18.2",
+	"version": "3.20.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.18.2"
+		"@cldmv/slothlet": "3.20.0"
 	},
 	"peerDependenciesMeta": {
 		"@cldmv/slothlet": {