@cldmv/slothlet-types 3.15.2 → 3.16.0

package/lib/handlers/context-async.d.mts

@@ -1,32 +1,99 @@
+/**
+ * AsyncLocalStorage-based context manager for async runtime
+ * Uses ALS for full context isolation across async operations
+ * @public
+ */
 export class AsyncContextManager {
     als: any;
     instances: Map<any, any>;
-    registerEventEmitterContextChecker(): void;
-    initialize(instanceID: any, config?: {}): {
-        instanceID: any;
-        self: {};
-        context: {};
-        config: {};
-        createdAt: number;
-    };
-    runInContext(instanceID: any, fn: any, thisArg: any, args: any, currentWrapper: any, rawErrors?: boolean): any;
-    getContext(): any;
-    tryGetContext(instanceID: any): any;
-    getCallerIdentity(instanceID: any): {
-        currentWrapper: any;
-        callerWrapper: any;
+    /**
+     * Register the EventEmitter context checker
+     * Must be called AFTER EventEmitter patching is enabled
+     * @public
+     */
+    public registerEventEmitterContextChecker(): void;
+    /**
+     * Initialize context for a new instance
+     * @param {string} instanceID - Unique instance identifier
+     * @param {Object} config - Instance configuration
+     * @returns {Object} Created context store
+     * @public
+     */
+    public initialize(instanceID: string, config?: Object): Object;
+    /**
+     * Run function with instance context active
+     * @param {string} instanceID - Instance to run in context of
+     * @param {Function} fn - Function to execute
+     * @param {*} thisArg - this binding for function
+     * @param {Array} args - Arguments to pass to function
+     * @param {Object} [currentWrapper] - Current wrapper being executed (for metadata.self())
+     * @param {boolean} [rawErrors=false] - When `true`, let a non-SlothletError thrown by
+     *   `fn` propagate unchanged instead of wrapping it as `CONTEXT_EXECUTION_FAILED`. Used
+     *   for framework callbacks (`lockCaller`, pinned hooks) where the caller expects the
+     *   original error type/code/status.
+     * @returns {*} Result of function execution
+     * @public
+     */
+    public runInContext(instanceID: string, fn: Function, thisArg: any, args: any[], currentWrapper?: Object, rawErrors?: boolean): any;
+    /**
+     * Get current active context
+     * @returns {Object} Current context store
+     * @throws {SlothletError} If no active context
+     * @public
+     */
+    public getContext(): Object;
+    /**
+     * Try to get context (returns undefined instead of throwing)
+     *
+     * @param {string} [instanceID] - When provided, resolve the store scoped to this instance rather
+     *   than to the active async flow. The active ALS store is used only when it belongs to this
+     *   instance (its own store or a child scope of it); otherwise this instance has no active flow
+     *   and its own base store is returned, so host-level checks (e.g. the `TRUSTED_ROOT` read-gate
+     *   exemption) evaluate against the right instance. AsyncLocalStorage propagates across `await`,
+     *   so a leaf that boots a second `slothlet()` would otherwise carry its own store into the
+     *   nested instance's construction (#290). Omit for the legacy "active flow store" behavior.
+     * @returns {Object|undefined} Current context store or undefined
+     * @public
+     */
+    public tryGetContext(instanceID?: string): Object | undefined;
+    /**
+     * Resolve the caller identity for the executing async flow.
+     *
+     * Counterpart to the live manager's accessor of the same name, so enforcement can ask for
+     * identity without knowing which runtime it is on. No disambiguation is needed here:
+     * `runInContext` publishes a fresh execution store into AsyncLocalStorage, so the store this
+     * returns already belongs to the calling flow and cannot be another call's.
+     *
+     * @param {string} [instanceID] - When provided, resolve identity from THIS instance's own store
+     *   rather than from the active async flow. AsyncLocalStorage propagates across `await`, so an
+     *   outer leaf booting this nested instance would otherwise be seen as its caller; scoping to the
+     *   instance's own store reports no caller for that nested boot (base store has none) while still
+     *   returning the real caller when this instance's own flow is active (#290). Omit for the legacy
+     *   "active flow caller" behavior.
+     * @returns {{currentWrapper: object, callerWrapper: object}|undefined} Identity, or undefined
+     *   when there is no active context.
+     * @public
+     */
+    public getCallerIdentity(instanceID?: string): {
+        currentWrapper: object;
+        callerWrapper: object;
     } | undefined;
-    cleanup(instanceID: any): void;
-    getDiagnostics(): {
-        type: string;
-        activeStore: any;
-        instances: {
-            id: any;
-            createdAt: any;
-            contextKeys: string[];
-            selfKeys: string[];
-        }[];
-    };
+    /**
+     * Cleanup instance context
+     * @param {string} instanceID - Instance to cleanup
+     * @public
+     */
+    public cleanup(instanceID: string): void;
+    /**
+     * Get diagnostic information
+     * @returns {Object} Diagnostic data
+     * @public
+     */
+    public getDiagnostics(): Object;
     #private;
 }
+/**
+ * Singleton async context manager
+ * @public
+ */
 export const asyncContextManager: AsyncContextManager;

package/lib/handlers/context-live.d.mts

@@ -1,37 +1,124 @@
+/**
+ * Live bindings context manager (direct global state)
+ * Uses direct instance tracking without AsyncLocalStorage overhead.
+ *
+ * Concurrency boundary: the active instance is tracked in a single global field
+ * ({@link LiveContextManager#currentInstanceID}), so this manager isolates *sequential*
+ * `run()`/`scope()` calls (each restores the prior instance on exit) but NOT *interleaved*
+ * concurrent calls on the same instance — across an `await`, a sibling `run()` overwrites the
+ * global and a resumed callback reads the wrong context. True per-async-flow isolation requires
+ * AsyncLocalStorage (see {@link module:@cldmv/slothlet/handlers/context-async}); the live manager
+ * is the deliberate trade-off for environments without `node:async_hooks` (browser/worker, see
+ * #123) and for the lowest-overhead single-flow case. See docs/CONTEXT-PROPAGATION.md.
+ * @public
+ */
 export class LiveContextManager {
     instances: Map<any, any>;
     currentInstanceID: any;
-    getCallerIdentity(instanceID: any): {
-        currentWrapper: any;
-        callerWrapper: any;
-        unresolved?: undefined;
-    } | {
-        currentWrapper: null;
-        callerWrapper: any;
-        unresolved: boolean;
+    /**
+     * Resolve the caller identity for the call that is executing right now.
+     *
+     * Enforcement asks for identity through here rather than reading `store.currentWrapper`
+     * directly, because that field can only name one call. Two paths:
+     *
+     * - **At most one call suspended** — the field is necessarily that call's (or a synchronous
+     *   nested call's, which set it on the way in), so it is returned as-is. This is the ordinary
+     *   case and costs nothing.
+     * - **Two or more suspended** — the field names whichever entered last, so a call resuming
+     *   from its `await` would read another module's identity and inherit its rights. The true
+     *   caller is taken from the call stack instead: the gated access happens synchronously inside
+     *   the caller's own function body, so its frame is on the stack. Interleaving can scramble a
+     *   shared field; it cannot scramble the stack, since each flow has its own.
+     *
+     * Only the suspended calls are candidates, so this never needs a global file→module index —
+     * and when the stack matches none of them (or matches ambiguously), identity is reported as
+     * unresolved so enforcement fails closed rather than guessing.
+     *
+     * Live runtime only. The async manager scopes identity per flow with AsyncLocalStorage and has
+     * no such ambiguity.
+     *
+     * @param {string} [instanceID] - When provided, resolve identity from THIS instance's own store
+     *   rather than from whichever instance is globally active. The manager is a singleton shared by
+     *   every instance, so the global `currentInstanceID` can point at a different `slothlet()` at the
+     *   moment this instance's access is enforced — either an outer leaf mid-boot of this nested
+     *   instance (its base store has no caller → treated as uncalled) or a concurrent sibling that
+     *   transiently overwrote the global while this instance's own call is parked at an `await` (its
+     *   store still holds the in-flight caller → resolved and enforced). Scoping the store keeps both
+     *   correct; a bare `currentInstanceID` read conflates them (#290). Omit for the legacy behavior.
+     * @returns {{currentWrapper: object|null, callerWrapper: object, unresolved?: boolean}|undefined}
+     *   Identity for the executing call, or undefined when there is no active context.
+     * @public
+     */
+    public getCallerIdentity(instanceID?: string): {
+        currentWrapper: object | null;
+        callerWrapper: object;
+        unresolved?: boolean;
     } | undefined;
-    registerEventEmitterContextChecker(): void;
-    initialize(instanceID: any, config?: {}): {
-        instanceID: any;
-        self: {};
-        context: {};
-        config: {};
-        createdAt: number;
-    };
-    runInContext(instanceID: any, fn: any, thisArg: any, args: any, currentWrapper: any, rawErrors?: boolean): any;
-    getContext(): any;
-    tryGetContext(instanceID: any): any;
-    cleanup(instanceID: any): void;
-    getDiagnostics(): {
-        type: string;
-        currentInstanceID: any;
-        instances: {
-            id: any;
-            createdAt: any;
-            contextKeys: string[];
-            selfKeys: string[];
-        }[];
-    };
+    /**
+     * Register the EventEmitter context checker
+     * Must be called AFTER EventEmitter patching is enabled
+     * @public
+     */
+    public registerEventEmitterContextChecker(): void;
+    /**
+     * Initialize context for a new instance
+     * @param {string} instanceID - Unique instance identifier
+     * @param {Object} config - Instance configuration
+     * @returns {Object} Created context store
+     * @public
+     */
+    public initialize(instanceID: string, config?: Object): Object;
+    /**
+     * Run function with instance context active (live mode)
+     * @param {string} instanceID - Instance to run in context of
+     * @param {Function} fn - Function to execute
+     * @param {*} thisArg - this binding for function
+     * @param {Array} args - Arguments to pass to function
+     * @param {Object} [currentWrapper] - Current wrapper being executed (for metadata.self())
+     * @param {boolean} [rawErrors=false] - When `true`, let a non-SlothletError thrown by
+     *   `fn` propagate unchanged instead of wrapping it as `CONTEXT_EXECUTION_FAILED`. Used
+     *   for framework callbacks (`lockCaller`, pinned hooks) where the caller expects the
+     *   original error type/code/status.
+     * @returns {*} Result of function execution
+     * @public
+     */
+    public runInContext(instanceID: string, fn: Function, thisArg: any, args: any[], currentWrapper?: Object, rawErrors?: boolean): any;
+    /**
+     * Get current active context
+     * @returns {Object} Current context store
+     * @throws {SlothletError} If no active context
+     * @public
+     */
+    public getContext(): Object;
+    /**
+     * Try to get context (returns undefined instead of throwing)
+     *
+     * @param {string} [instanceID] - When provided, resolve the store scoped to this instance rather
+     *   than to the globally-active one. If the active flow belongs to this instance (base or a
+     *   `run()`/`scope()` child) its store is returned; otherwise the instance has no active flow and
+     *   its own base store is returned, so host-level checks (e.g. the `TRUSTED_ROOT` read-gate
+     *   exemption) evaluate against the right instance instead of an unrelated ambient caller (#290).
+     *   Omit for the legacy "globally-active store" behavior.
+     * @returns {Object|undefined} Current context store or undefined
+     * @public
+     */
+    public tryGetContext(instanceID?: string): Object | undefined;
+    /**
+     * Cleanup instance context
+     * @param {string} instanceID - Instance to cleanup
+     * @public
+     */
+    public cleanup(instanceID: string): void;
+    /**
+     * Get diagnostic information
+     * @returns {Object} Diagnostic data
+     * @public
+     */
+    public getDiagnostics(): Object;
     #private;
 }
+/**
+ * Singleton live context manager
+ * @public
+ */
 export const liveContextManager: LiveContextManager;

package/lib/handlers/framework-internals.d.mts

@@ -1,3 +1,34 @@
-export function isFrameworkInternal(obj: any): boolean;
-export function isFrameworkMarkerKey(key: any): boolean;
+/**
+ * Whether `key` is one of slothlet's reserved dispatcher marker keys.
+ *
+ * The immutable read view over `FRAMEWORK_MARKER_KEYS` — importers can test membership but
+ * cannot add keys and broaden the read-gate exemption.
+ *
+ * @param {string} key - Property name to test.
+ * @returns {boolean} True when `key` is a reserved framework marker key.
+ * @internal
+ * @example
+ * if (isFrameworkInternal(wrapper) && isFrameworkMarkerKey(leafKey)) return { allowed: true };
+ */
+export function isFrameworkMarkerKey(key: string): boolean;
+/**
+ * Brand an object as slothlet-internal so reads of its `FRAMEWORK_MARKER_KEYS` are exempt from
+ * the module-private host gate. No-op for non-objects.
+ *
+ * @param {*} obj - The object (or function) slothlet created / stamped with a marker key.
+ * @returns {*} The same `obj`, for call-site chaining.
+ * @internal
+ * @example
+ * const dispatcher = markFrameworkInternal(new Proxy(target, handlers));
+ */
 export function markFrameworkInternal(obj: any): any;
+/**
+ * Whether `obj` is a branded slothlet-internal object (see {@link markFrameworkInternal}).
+ *
+ * @param {*} obj - Candidate object.
+ * @returns {boolean} True when `obj` was branded by the framework.
+ * @internal
+ * @example
+ * if (isFrameworkInternal(sourceApi)) markFrameworkInternal(resolveWrapper(targetApi));
+ */
+export function isFrameworkInternal(obj: any): boolean;