@actsecurity/iam-lens 0.1.156

package/dist/cjs/whoCan/WhoCanMainThreadWorker.d.ts

@@ -0,0 +1,73 @@
+import { type JobResult } from '@actsecurity/job';
+import { IamCollectClient } from '../collect/client.js';
+import { type S3AbacOverride } from '../utils/s3Abac.js';
+import { PullBasedJobRunner } from '../workers/JobRunner.js';
+import { type LightRequestAnalysis } from './requestAnalysis.js';
+import { type WhoCanAllowed, type WhoCanDenyDetail } from './whoCan.js';
+import { type WhoCanExecutionResult, type WhoCanWorkItem } from './WhoCanWorker.js';
+/**
+ * A work item tagged with its owning request ID, used by the main-thread
+ * runner so that simulation results can be routed back to the correct request.
+ */
+export interface TaggedWhoCanWorkItem extends WhoCanWorkItem {
+    /** The request ID this work item belongs to. */
+    requestId: string;
+}
+/**
+ * Properties attached to each job so the requestId survives through to onComplete.
+ */
+interface MainThreadJobProperties {
+    /** The request ID this job belongs to. */
+    requestId: string;
+    /** Whether deny details should be collected for this work item's request. */
+    collectDenyDetails: boolean;
+}
+/**
+ * Dequeues the next tagged work item from the processor's FIFO scheduler.
+ *
+ * @returns the next tagged work item, or undefined if none are ready.
+ */
+export type DequeueWork = () => TaggedWhoCanWorkItem | undefined;
+/**
+ * Called when a simulation completes (allowed, denied, or error). Routes
+ * the result back to the processor by requestId.
+ *
+ * @param requestId - The request this result belongs to.
+ * @param result - The simulation result (fulfilled with WhoCanAllowed or undefined, or rejected).
+ */
+export type OnSimulationResult = (requestId: string, result: JobResult<WhoCanAllowed | undefined, Record<string, unknown>>) => void;
+/**
+ * Checks whether deny details should be included for a denied simulation.
+ *
+ * @param requestId - The request this check belongs to.
+ * @param lightAnalysis - The light analysis for the denied simulation.
+ * @returns true if deny details should be collected and delivered.
+ */
+export type OnCheckDenyDetails = (requestId: string, lightAnalysis: LightRequestAnalysis) => boolean;
+/**
+ * Called when deny details are ready to be delivered.
+ *
+ * @param requestId - The request this detail belongs to.
+ * @param detail - The deny detail record.
+ */
+export type OnDenyDetail = (requestId: string, detail: WhoCanDenyDetail) => void;
+/**
+ * Creates a main-thread simulation runner that pulls tagged work items from
+ * the processor's FIFO scheduler and routes results back by requestId.
+ *
+ * The requestId is threaded through the job's properties so it is available
+ * in onComplete without needing the workerId.
+ *
+ * @param dequeueWork - Function to dequeue the next tagged work item.
+ * @param onSimulationResult - Callback for simulation results.
+ * @param onCheckDenyDetails - Callback to check whether to collect deny details.
+ * @param onDenyDetail - Callback for deny detail delivery.
+ * @param collectClient - The IAM collect client for fetching policy data.
+ * @param s3AbacOverride - Optional override for S3 ABAC when checking S3 Bucket access.
+ * @param collectGrantDetails - Whether to collect grant details for allowed simulations.
+ * @param concurrency - The number of concurrent simulations to run on the main thread. Defaults to 50.
+ * @returns a PullBasedJobRunner that processes tagged whoCan work items.
+ */
+export declare function createMainThreadStreamingWorkQueue(dequeueWork: DequeueWork, onSimulationResult: OnSimulationResult, onCheckDenyDetails: OnCheckDenyDetails, onDenyDetail: OnDenyDetail, collectClient: IamCollectClient, s3AbacOverride: S3AbacOverride | undefined, collectGrantDetails: boolean, concurrency?: number): PullBasedJobRunner<WhoCanExecutionResult, MainThreadJobProperties, TaggedWhoCanWorkItem>;
+export {};
+//# sourceMappingURL=WhoCanMainThreadWorker.d.ts.map

package/dist/cjs/whoCan/WhoCanMainThreadWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WhoCanMainThreadWorker.d.ts","sourceRoot":"","sources":["../../../src/whoCan/WhoCanMainThreadWorker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACvE,OAAO,EAAiB,KAAK,qBAAqB,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAElG;;;GAGG;AACH,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,UAAU,uBAAuB;IAC/B,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAA;IAEjB,6EAA6E;IAC7E,kBAAkB,EAAE,OAAO,CAAA;CAC5B;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,oBAAoB,GAAG,SAAS,CAAA;AAEhE;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,SAAS,CAAC,aAAa,GAAG,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KAClE,IAAI,CAAA;AAET;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,oBAAoB,KAAK,OAAO,CAAA;AAEpG;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,KAAK,IAAI,CAAA;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kCAAkC,CAChD,WAAW,EAAE,WAAW,EACxB,kBAAkB,EAAE,kBAAkB,EACtC,kBAAkB,EAAE,kBAAkB,EACtC,YAAY,EAAE,YAAY,EAC1B,aAAa,EAAE,gBAAgB,EAC/B,cAAc,EAAE,cAAc,GAAG,SAAS,EAC1C,mBAAmB,EAAE,OAAO,EAC5B,WAAW,GAAE,MAAW,4FAoEzB"}

package/dist/cjs/whoCan/WhoCanMainThreadWorker.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMainThreadStreamingWorkQueue = createMainThreadStreamingWorkQueue;
+const JobRunner_js_1 = require("../workers/JobRunner.js");
+const requestAnalysis_js_1 = require("./requestAnalysis.js");
+const WhoCanWorker_js_1 = require("./WhoCanWorker.js");
+/**
+ * Creates a main-thread simulation runner that pulls tagged work items from
+ * the processor's FIFO scheduler and routes results back by requestId.
+ *
+ * The requestId is threaded through the job's properties so it is available
+ * in onComplete without needing the workerId.
+ *
+ * @param dequeueWork - Function to dequeue the next tagged work item.
+ * @param onSimulationResult - Callback for simulation results.
+ * @param onCheckDenyDetails - Callback to check whether to collect deny details.
+ * @param onDenyDetail - Callback for deny detail delivery.
+ * @param collectClient - The IAM collect client for fetching policy data.
+ * @param s3AbacOverride - Optional override for S3 ABAC when checking S3 Bucket access.
+ * @param collectGrantDetails - Whether to collect grant details for allowed simulations.
+ * @param concurrency - The number of concurrent simulations to run on the main thread. Defaults to 50.
+ * @returns a PullBasedJobRunner that processes tagged whoCan work items.
+ */
+function createMainThreadStreamingWorkQueue(dequeueWork, onSimulationResult, onCheckDenyDetails, onDenyDetail, collectClient, s3AbacOverride, collectGrantDetails, concurrency = 50) {
+    return new JobRunner_js_1.PullBasedJobRunner(concurrency, async () => {
+        return dequeueWork();
+    }, (taggedItem) => {
+        const { requestId, ...workItem } = taggedItem;
+        return {
+            properties: { requestId, collectDenyDetails: workItem.collectDenyDetails },
+            execute: async (context) => {
+                return (0, WhoCanWorker_js_1.executeWhoCan)(workItem, collectClient, {
+                    s3AbacOverride,
+                    collectDenyDetails: workItem.collectDenyDetails,
+                    collectGrantDetails,
+                    strictContextKeys: workItem.strictContextKeys
+                });
+            }
+        };
+    }, async (result) => {
+        const { requestId, collectDenyDetails } = result.properties;
+        if (result.status === 'fulfilled') {
+            const executionResult = result.value;
+            if (executionResult.type === 'allowed') {
+                onSimulationResult(requestId, {
+                    status: 'fulfilled',
+                    value: executionResult.allowed,
+                    properties: {}
+                });
+            }
+            else {
+                // Denied — handle deny details BEFORE reporting the simulation result,
+                // because onSimulationResult may trigger request completion checks.
+                const hasDetails = executionResult.type === 'denied_single' || executionResult.type === 'denied_wildcard';
+                if (collectDenyDetails && hasDetails) {
+                    const lightAnalysis = (0, requestAnalysis_js_1.toLightRequestAnalysis)(executionResult);
+                    const shouldInclude = onCheckDenyDetails(requestId, lightAnalysis);
+                    if (shouldInclude) {
+                        onDenyDetail(requestId, (0, requestAnalysis_js_1.convertToDenialDetails)(executionResult));
+                    }
+                }
+                // Now report the denied simulation result (may trigger completion check)
+                onSimulationResult(requestId, {
+                    status: 'fulfilled',
+                    value: undefined,
+                    properties: {}
+                });
+            }
+        }
+        else {
+            // Error case
+            onSimulationResult(requestId, {
+                status: 'rejected',
+                reason: result.reason,
+                properties: {}
+            });
+        }
+    });
+}
+//# sourceMappingURL=WhoCanMainThreadWorker.js.map

package/dist/cjs/whoCan/WhoCanMainThreadWorker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WhoCanMainThreadWorker.js","sourceRoot":"","sources":["../../../src/whoCan/WhoCanMainThreadWorker.ts"],"names":[],"mappings":";;AAqFA,gFA4EC;AA9JD,0DAA4D;AAC5D,6DAI6B;AAE7B,uDAAkG;AA0DlG;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,kCAAkC,CAChD,WAAwB,EACxB,kBAAsC,EACtC,kBAAsC,EACtC,YAA0B,EAC1B,aAA+B,EAC/B,cAA0C,EAC1C,mBAA4B,EAC5B,cAAsB,EAAE;IAExB,OAAO,IAAI,iCAAkB,CAK3B,WAAW,EACX,KAAK,IAAI,EAAE;QACT,OAAO,WAAW,EAAE,CAAA;IACtB,CAAC,EACD,CAAC,UAAU,EAAE,EAAE;QACb,MAAM,EAAE,SAAS,EAAE,GAAG,QAAQ,EAAE,GAAG,UAAU,CAAA;QAC7C,OAAO;YACL,UAAU,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,QAAQ,CAAC,kBAAkB,EAAE;YAC1E,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;gBACzB,OAAO,IAAA,+BAAa,EAAC,QAAQ,EAAE,aAAa,EAAE;oBAC5C,cAAc;oBACd,kBAAkB,EAAE,QAAQ,CAAC,kBAAkB;oBAC/C,mBAAmB;oBACnB,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;iBAC9C,CAAC,CAAA;YACJ,CAAC;SACF,CAAA;IACH,CAAC,EACD,KAAK,EAAE,MAAM,EAAE,EAAE;QACf,MAAM,EAAE,SAAS,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAAC,UAAU,CAAA;QAE3D,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,MAAM,eAAe,GAAG,MAAM,CAAC,KAAK,CAAA;YACpC,IAAI,eAAe,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvC,kBAAkB,CAAC,SAAS,EAAE;oBAC5B,MAAM,EAAE,WAAW;oBACnB,KAAK,EAAE,eAAe,CAAC,OAAO;oBAC9B,UAAU,EAAE,EAAE;iBACf,CAAC,CAAA;YACJ,CAAC;iBAAM,CAAC;gBACN,uEAAuE;gBACvE,oEAAoE;gBACpE,MAAM,UAAU,GACd,eAAe,CAAC,IAAI,KAAK,eAAe,IAAI,eAAe,CAAC,IAAI,KAAK,iBAAiB,CAAA;gBAExF,IAAI,kBAAkB,IAAI,UAAU,EAAE,CAAC;oBACrC,MAAM,aAAa,GAAG,IAAA,2CAAsB,EAAC,eAAe,CAAC,CAAA;oBAC7D,MAAM,aAAa,GAAG,kBAAkB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAA;oBAElE,IAAI,aAAa,EAAE,CAAC;wBAClB,YAAY,CAAC,SAAS,EAAE,IAAA,2CAAsB,EAAC,eAAe,CAAC,CAAC,CAAA;oBAClE,CAAC;gBACH,CAAC;gBAED,yEAAyE;gBACzE,kBAAkB,CAAC,SAAS,EAAE;oBAC5B,MAAM,EAAE,WAAW;oBACnB,KAAK,EAAE,SAAS;oBAChB,UAAU,EAAE,EAAE;iBACf,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;aAAM,CAAC;YACN,aAAa;YACb,kBAAkB,CAAC,SAAS,EAAE;gBAC5B,MAAM,EAAE,UAAU;gBAClB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,UAAU,EAAE,EAAE;aACf,CAAC,CAAA;QACJ,CAAC;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/cjs/whoCan/WhoCanProcessor.d.ts

@@ -0,0 +1,400 @@
+import { type TopLevelConfig } from '@actsecurity/iam-collect';
+import { type ClientFactoryPlugin } from '../collect/collect.js';
+import { type S3AbacOverride } from '../utils/s3Abac.js';
+import { type LightRequestAnalysis } from './requestAnalysis.js';
+import { type WhoCanPrincipalScope, type WhoCanResponse } from './whoCan.js';
+import { type WorkerBootstrapPlugin } from './workerBootstrapPlugin.js';
+export type { WorkerBootstrapPlugin } from './workerBootstrapPlugin.js';
+/**
+ * Configuration for creating a WhoCanProcessor. These settings are fixed
+ * for the lifetime of the processor and baked into worker threads at creation time.
+ */
+export interface WhoCanProcessorConfig {
+    /** The collect configurations for loading IAM data. */
+    collectConfigs: TopLevelConfig[];
+    /** The AWS partition to use (e.g. 'aws', 'aws-cn'). */
+    partition: string;
+    tuning?: {
+        /**
+         * The number of worker threads to use beyond the main thread. Defaults to number of CPUs - 1.
+         */
+        workerThreads?: number;
+        /**
+         * The concurrency level for processing simulations on the main thread. Defaults to 50.
+         */
+        mainThreadConcurrency?: number;
+        /**
+         * The concurrency level for processing simulations on worker threads.
+         * This is the value for EACH worker.
+         * Defaults to 50.
+         */
+        perWorkerConcurrency?: number;
+        /**
+         * The concurrency level for the shared preparation queue (account/principal fetches
+         * across all active requests). Defaults to min(50, max(1, number of CPUs * 2)).
+         */
+        preparationConcurrency?: number;
+        /**
+         * The maximum number of requests that may be actively expanded into scenarios
+         * at once. Later requests remain as lightweight entries in pendingRequests.
+         * Defaults to 30.
+         */
+        maxRequestsInProgress?: number;
+    };
+    /** Optional plugin to wrap the collect client with a custom implementation. */
+    clientFactoryPlugin?: ClientFactoryPlugin;
+    /**
+     * Optional plugin that runs once per worker thread at startup before any work
+     * is processed. Use this for loading instrumentation, initializing logging
+     * context, or other worker-lifetime setup. If the bootstrap function throws,
+     * the worker fails and the processor surfaces the error.
+     */
+    workerBootstrapPlugin?: WorkerBootstrapPlugin;
+    /** An override for S3 ABAC being enabled when checking access to S3 Bucket resources. */
+    s3AbacOverride?: S3AbacOverride;
+    /** Whether workers should collect grant details for allowed simulations. */
+    collectGrantDetails?: boolean;
+    /**
+     * Async callback invoked when a request settles (succeeds or fails). The processor
+     * awaits this callback before removing the request from active state and admitting
+     * the next pending request. This allows consumers to perform async work with backpressure.
+     *
+     * @param event - The settlement event containing the request ID, original request,
+     *   status, and either the result or the error.
+     */
+    onRequestSettled: (event: WhoCanSettledEvent) => Promise<void>;
+    /**
+     * Optional async callback invoked when an `onRequestSettled` callback throws or rejects.
+     * If this callback itself throws, the error is silently ignored. If not provided, a
+     * warning is logged indicating that a settlement callback failed with no handler defined.
+     *
+     * @param event - The settlement event that was being delivered when the error occurred.
+     * @param error - The error thrown by the `onRequestSettled` callback.
+     */
+    onSettlementFailure?: (event: WhoCanSettledEvent, error: Error) => Promise<void>;
+    /**
+     * Whether the processor should ignore an existing principal index. Use this with testing.
+     */
+    ignorePrincipalIndex?: boolean;
+}
+/**
+ * Request parameters that vary per whoCan call on a processor.
+ */
+export interface WhoCanProcessorRequest {
+    /** The ARN of the resource to check access for. */
+    resource?: string;
+    /** The account ID the resource belongs to. */
+    resourceAccount?: string;
+    /** The actions to check access for. */
+    actions: string[];
+    /** Whether to sort the results for consistent output. */
+    sort?: boolean;
+    /**
+     * Optional callback to filter which denied simulations should include detailed
+     * denial analysis. If provided, deny details are collected for this request.
+     * If the callback returns true for a given denial, the full deny details are
+     * included in the response. If omitted, no deny details are collected for this request.
+     *
+     * @param details - A lightweight summary of the denied simulation.
+     * @returns true to include full deny details for this denial.
+     */
+    denyDetailsCallback?: (details: LightRequestAnalysis) => boolean;
+    /** Optional scope to limit the set of principals tested. */
+    principalScope?: WhoCanPrincipalScope;
+    /** Optional context keys to consider strict when running simulations. */
+    strictContextKeys?: string[];
+}
+/**
+ * Event delivered to the onRequestSettled callback when a request completes
+ * (either successfully or with an error).
+ */
+export type WhoCanSettledEvent = WhoCanSettledSuccess | WhoCanSettledError;
+/**
+ * Settlement event for a successfully completed request.
+ */
+export interface WhoCanSettledSuccess {
+    /** Discriminator for the settlement outcome. */
+    status: 'fulfilled';
+    /** The unique ID assigned when the request was enqueued. */
+    requestId: string;
+    /** The original request that was enqueued. */
+    request: WhoCanProcessorRequest;
+    /** The whoCan result for this request. */
+    result: WhoCanResponse;
+}
+/**
+ * Settlement event for a request that failed during preparation or simulation.
+ */
+export interface WhoCanSettledError {
+    /** Discriminator for the settlement outcome. */
+    status: 'rejected';
+    /** The unique ID assigned when the request was enqueued. */
+    requestId: string;
+    /** The original request that was enqueued. */
+    request: WhoCanProcessorRequest;
+    /** The error that caused the request to fail. */
+    error: Error;
+}
+/**
+ * A queue-first bulk processor that accepts many whoCan requests, expands
+ * scenarios on the main thread, and feeds a shared simulation scheduler used
+ * by worker threads and an optional main-thread runner.
+ *
+ * Results are delivered through the {@link WhoCanProcessorConfig.onRequestSettled}
+ * callback as each request completes — they are not stored inside the processor.
+ *
+ * Use {@link enqueueWhoCan} to submit requests, then {@link waitForIdle} to
+ * wait for all work to complete. Call {@link shutdown} when done to terminate
+ * worker threads.
+ */
+export declare class WhoCanProcessor {
+    private workers;
+    private collectClient;
+    private config;
+    private isShutdown;
+    private workersDead;
+    private pendingRequests;
+    private activeRequestOrder;
+    private requestStates;
+    private admissionPumpRunning;
+    private draining;
+    private preparationQueue;
+    private idleWaiters;
+    private mainThreadWorker;
+    private fatalError?;
+    private shutdownPromise?;
+    private constructor();
+    /**
+     * Waits for every worker to post a `{ type: 'ready' }` message. If any
+     * worker fails (error, non-zero exit, or explicit `startupError` message)
+     * the remaining workers are terminated and the returned promise rejects.
+     *
+     * @param workers - The worker instances to wait on.
+     */
+    private static awaitWorkersReady;
+    /**
+     * Creates a new WhoCanProcessor with worker threads, a shared cache, and
+     * lifetime-scoped message routing. The processor is ready to accept requests
+     * immediately after creation.
+     *
+     * @param config - The configuration for the processor, including collect configs,
+     *   partition, simulation options, tuning, and the onRequestSettled callback.
+     * @returns a new WhoCanProcessor instance
+     */
+    static create(config: WhoCanProcessorConfig): Promise<WhoCanProcessor>;
+    /**
+     * Enqueues a whoCan request for processing. Returns a unique request ID
+     * that will appear in the corresponding {@link WhoCanSettledEvent}.
+     *
+     * This method never activates a request directly — it appends to
+     * pendingRequests and signals the admission pump.
+     *
+     * @param request - The whoCan request parameters.
+     * @returns the unique request ID assigned to this request.
+     * @throws if the processor is shut down or draining via waitForIdle.
+     */
+    enqueueWhoCan(request: WhoCanProcessorRequest): string;
+    /**
+     * Returns a promise that resolves when all pending and active work has
+     * completed and all onRequestSettled callbacks have finished.
+     *
+     * While draining, new calls to {@link enqueueWhoCan} will throw. Once
+     * the drain completes, the processor re-opens for new enqueues.
+     *
+     * @returns a promise that resolves when idle, or rejects if a worker crashes.
+     */
+    waitForIdle(): Promise<void>;
+    /**
+     * Shuts down the processor by rejecting all pending requests, waiting for
+     * active requests to settle, and terminating all worker threads.
+     *
+     * This method is idempotent — calling it multiple times is safe.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Internal shutdown implementation. Rejects pending requests, waits for
+     * active requests to drain, then terminates workers.
+     */
+    private executeShutdown;
+    /**
+     * Installs lifetime-scoped message, error, and exit listeners on all workers.
+     * Message listeners route simulation results and deny-detail checks to the
+     * correct request state using requestId. Error/exit listeners detect crashes
+     * and mark the processor as fatally failed.
+     */
+    private installLifetimeWorkerListeners;
+    /**
+     * Routes a message from a worker thread to the appropriate handler based
+     * on message type and requestId.
+     *
+     * @param msg - The message received from the worker.
+     * @param worker - The worker that sent the message.
+     */
+    private handleWorkerMessage;
+    /**
+     * Creates the main-thread simulation runner if mainThreadConcurrency > 0.
+     * The runner pulls from the FIFO scheduler and routes results by requestId.
+     */
+    private createMainThreadRunner;
+    /**
+     * Dequeues the next simulation scenario using FIFO request priority.
+     * Prefers the oldest active request that has ready scenarios. If the oldest
+     * is temporarily empty (still preparing), falls back to the next request
+     * with ready scenarios so cores do not idle.
+     *
+     * @returns the next work item, or undefined if no scenarios are ready.
+     */
+    private dequeueNextScenario;
+    /**
+     * Notifies all simulation consumers (workers and main thread) that new
+     * work may be available in the scheduler.
+     */
+    private notifySimulationConsumers;
+    /**
+     * Wakes the admission pump to process pending requests. If the pump is
+     * already running, this is a no-op — the running pump will pick up new
+     * pending requests on its next iteration.
+     */
+    private wakeAdmissionPump;
+    /**
+     * The admission pump loop. Drains pendingRequests into active processing
+     * up to maxRequestsInProgress. Only one instance of this loop runs at a time,
+     * guarded by admissionPumpRunning.
+     */
+    private runAdmissionPump;
+    /**
+     * Creates a fresh RequestState for an admitted request.
+     *
+     * @param submitted - The submitted request to create state for.
+     * @returns the new RequestState.
+     */
+    private createRequestState;
+    /**
+     * Enqueues the root preparation job for a request. This job performs resource
+     * account resolution, resource policy lookup, action expansion, principal scope
+     * handling, and then enqueues follow-up preparation jobs to enumerate principals.
+     *
+     * @param state - The request state to prepare.
+     */
+    private enqueueRootPreparation;
+    /**
+     * Executes the root preparation for a request: resolves the resource account,
+     * fetches the resource policy, expands actions, determines which accounts and
+     * principals to check, and enqueues follow-up preparation jobs.
+     *
+     * @param state - The request state to prepare.
+     */
+    private executeRootPreparation;
+    /**
+     * Handles a simulation result from a worker or the main thread runner.
+     * Routes the result to the correct request state and checks for completion.
+     *
+     * @param requestId - The ID of the request this result belongs to.
+     * @param result - The simulation job result.
+     */
+    private handleSimulationResult;
+    /**
+     * Handles a checkDenyDetails request from a worker thread. Looks up the
+     * request's denyDetailsCallback and responds.
+     *
+     * @param requestId - The ID of the request.
+     * @param checkId - The unique check ID for this deny-details round trip.
+     * @param lightAnalysis - The light analysis to pass to the callback.
+     * @param worker - The worker to respond to.
+     */
+    private handleCheckDenyDetails;
+    /**
+     * Handles a deny details result from a worker thread. Decrements the
+     * pending deny-details counter and checks for request completion.
+     *
+     * @param requestId - The ID of the request.
+     * @param denyDetail - The deny detail to store.
+     */
+    private handleDenyDetailsResult;
+    /**
+     * Checks whether a request has completed all preparation and simulation work.
+     * If so, settles the request as successful.
+     *
+     * @param state - The request state to check.
+     */
+    private checkRequestCompletion;
+    /**
+     * Settles a request as successful: builds the WhoCanResponse, awaits
+     * onRequestSettled, removes the request from active state, and wakes
+     * the admission pump.
+     *
+     * @param state - The request state to settle.
+     */
+    private settleRequestAsSuccess;
+    /**
+     * Settles a request as failed: invokes onRequestSettled with the error
+     * immediately, but keeps the request in active state until all in-flight
+     * work drains (created === completed). Late results for settled requests
+     * are discarded but still counted so the drain completes.
+     *
+     * @param state - The request state to settle.
+     * @param error - The error that caused the failure.
+     */
+    private settleRequestAsError;
+    /**
+     * Invokes the onRequestSettled callback and routes any errors through
+     * {@link handleSettlementFailure}.
+     *
+     * @param event - The settlement event to deliver.
+     */
+    private invokeSettledCallback;
+    /**
+     * Awaits the onRequestSettled callback, then removes the request from
+     * active state and wakes the admission pump. Used for successful settlements
+     * where all work is already complete.
+     *
+     * @param state - The request state being settled.
+     * @param event - The settlement event to deliver.
+     */
+    private invokeSettledCallbackAndCleanup;
+    /**
+     * Checks whether a settled request has fully drained: the onRequestSettled
+     * callback has been awaited, all preparation jobs have finished, all
+     * simulation results have been received, and all deny-detail round trips
+     * have completed. Only then is the request removed from active state.
+     *
+     * @param state - The request state to check.
+     */
+    private checkRequestDrain;
+    /**
+     * Removes a request from active state, wakes the admission pump to fill
+     * the freed slot, and checks if the processor is now idle.
+     *
+     * @param state - The request state to remove.
+     */
+    private removeFromActiveState;
+    /**
+     * Returns true if the processor has no pending, active, or in-flight work.
+     *
+     * @returns true if fully idle.
+     */
+    private isIdle;
+    /**
+     * Checks whether the processor has become idle and resolves or rejects the
+     * waitForIdle promise if so.
+     */
+    private checkIdle;
+    /**
+     * Handles an error thrown by the `onRequestSettled` callback. If the
+     * `onSettlementFailure` callback is defined, it is invoked with the event
+     * and error; any error it throws is silently ignored. If not defined, a
+     * warning is logged.
+     *
+     * @param event - The settlement event that was being delivered.
+     * @param err - The raw error thrown by the `onRequestSettled` callback.
+     */
+    private handleSettlementFailure;
+    /**
+     * Handles an unexpected worker failure by marking the processor as dead,
+     * terminating remaining workers, and rejecting all active and pending requests.
+     *
+     * @param error - The error that caused the worker failure.
+     */
+    private handleWorkerFailure;
+}
+//# sourceMappingURL=WhoCanProcessor.d.ts.map

package/dist/cjs/whoCan/WhoCanProcessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WhoCanProcessor.d.ts","sourceRoot":"","sources":["../../../src/whoCan/WhoCanProcessor.ts"],"names":[],"mappings":"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"}