libpetri 1.1.0 → 1.3.1

package/dist/index.d.ts

@@ -304,6 +304,210 @@ declare class BitmapNetExecutor implements PetriNetExecutor {
     private emitEvent;
 }
 
+/**
+ * @module precompiled-net
+ *
+ * Flat-array precompiled representation of a PetriNet for high-performance execution.
+ *
+ * **Design**: Compiles from a `CompiledNet`, converting all per-transition data into
+ * flat typed arrays indexed by transition ID (tid) or place ID (pid). Eliminates Map
+ * lookups and object traversals from the hot path.
+ *
+ * **Sparse enablement**: Each transition's needs/inhibitor masks are classified as
+ * empty (-2), single-word (>=0), or multi-word (-1). Single-word masks avoid inner
+ * loops entirely; multi-word uses precomputed sparse indices to skip zero words.
+ *
+ * **Opcode programs**: Input consumption is compiled to compact opcode sequences
+ * (CONSUME_ONE, CONSUME_N, CONSUME_ALL, CONSUME_ATLEAST, RESET) that the executor
+ * dispatches without inspecting In spec objects.
+ *
+ * @see CompiledNet for the base bitmap representation
+ * @see PrecompiledNetExecutor for the executor that uses this representation
+ */
+
+/**
+ * Immutable precompiled representation of a Petri net.
+ *
+ * All data is stored in flat typed arrays indexed by tid/pid for cache-friendly,
+ * branch-free access on the hot path. Compiled once, reused across executions.
+ */
+declare class PrecompiledNet {
+    readonly compiled: CompiledNet;
+    readonly placeCount: number;
+    readonly transitionCount: number;
+    readonly wordCount: number;
+    /** Places indexed by pid — avoids compiled.place(pid) indirection on hot path. */
+    readonly places: readonly Place<any>[];
+    /** Per-transition consume opcode sequences. */
+    readonly consumeOps: readonly (readonly number[])[];
+    /** Per-transition read-arc place IDs. */
+    readonly readOps: readonly (readonly number[])[];
+    readonly needsMask: readonly Uint32Array[];
+    readonly inhibitorMask: readonly Uint32Array[];
+    readonly needsSingleWordIndex: Int8Array;
+    readonly needsSingleWordMask: Uint32Array;
+    readonly needsSparseIndices: readonly (readonly number[])[];
+    readonly needsSparseMasks: readonly (readonly number[])[];
+    readonly inhibitorSingleWordIndex: Int8Array;
+    readonly inhibitorSingleWordMask: Uint32Array;
+    readonly inhibitorSparseIndices: readonly (readonly number[])[];
+    readonly inhibitorSparseMasks: readonly (readonly number[])[];
+    readonly earliestMs: Float64Array;
+    readonly latestMs: Float64Array;
+    readonly hasDeadline: Uint8Array;
+    readonly priorities: Int32Array;
+    readonly transitionToPriorityIndex: Uint32Array;
+    readonly priorityLevels: readonly number[];
+    readonly distinctPriorityCount: number;
+    /** -2=no spec, -1=complex, >=0=single output place ID. */
+    readonly simpleOutputPlaceId: Int32Array;
+    readonly inputPlaceCount: Uint32Array;
+    readonly inputPlaceMaskWords: readonly Uint32Array[];
+    readonly placeToTransitions: readonly (readonly number[])[];
+    readonly consumptionPlaceIds: readonly (readonly number[])[];
+    readonly cardinalityChecks: readonly (CardinalityCheck | null)[];
+    readonly hasGuards: readonly boolean[];
+    readonly allImmediate: boolean;
+    readonly allSamePriority: boolean;
+    readonly anyDeadlines: boolean;
+    private constructor();
+    static compile(net: PetriNet): PrecompiledNet;
+    static compileFrom(compiled: CompiledNet): PrecompiledNet;
+    /**
+     * Three-case sparse enablement check:
+     * 1. Empty mask (needsSingleWordIndex == -2): always passes
+     * 2. Single-word mask (>=0): one comparison
+     * 3. Multi-word mask (-1): iterate precomputed sparse indices
+     */
+    canEnableSparse(tid: number, snapshot: Uint32Array): boolean;
+}
+
+/**
+ * @module precompiled-net-executor
+ *
+ * High-performance executor for Typed Coloured Time Petri Nets.
+ *
+ * **Architecture**: Uses `PrecompiledNet` for all transition/place data, replacing
+ * Map lookups and object traversals with typed-array indexing. Token storage uses
+ * simple per-place arrays, leveraging V8's optimized small-array shift/push.
+ *
+ * **Execution loop**: Same 5-phase structure as `BitmapNetExecutor`:
+ * 1. Process completed transitions — drain completionQueue, validate outputs
+ * 2. Process external events — inject tokens from EnvironmentPlaces
+ * 3. Update dirty transitions — sparse enablement via `canEnableSparse()`
+ * 4. Enforce deadlines — gated by `anyDeadlines` flag
+ * 5. Fire ready transitions — opcode dispatch or priority-queue path
+ *
+ * **Key optimizations over BitmapNetExecutor**:
+ * - Opcode-based consumption (switch on int vs object dispatch)
+ * - Cached place references (avoids compiled.place(pid) indirection)
+ * - Sparse enablement masks (skip zero words)
+ * - Lazy Marking sync (arrays are sole source of truth during execution)
+ * - Flat-array in-flight tracking (no Map overhead)
+ *
+ * @see PrecompiledNet for the precompiled data representation
+ * @see BitmapNetExecutor for the reference implementation
+ */
+
+interface PrecompiledNetExecutorOptions {
+    eventStore?: EventStore;
+    environmentPlaces?: Set<EnvironmentPlace<any>>;
+    longRunning?: boolean;
+    executionContextProvider?: (transitionName: string, consumed: Token<any>[]) => Map<string, unknown>;
+    /** Skip output spec validation for trusted actions (CONC-026). */
+    skipOutputValidation?: boolean;
+    /** Reuse a precompiled program (avoids recompilation). */
+    program?: PrecompiledNet;
+}
+/**
+ * High-performance executor using `PrecompiledNet`.
+ *
+ * Implements `PetriNetExecutor` with the same semantics as `BitmapNetExecutor`
+ * but with flat-array optimizations for lower per-transition overhead.
+ */
+declare class PrecompiledNetExecutor implements PetriNetExecutor {
+    private readonly program;
+    private readonly eventStore;
+    private readonly environmentPlaces;
+    private readonly longRunning;
+    private readonly executionContextProvider?;
+    private readonly skipOutputValidation;
+    private readonly startMs;
+    private readonly eventStoreEnabled;
+    /** Per-place token arrays, indexed by pid. */
+    private readonly tokenQueues;
+    private readonly markingBitmap;
+    private readonly dirtyBitmap;
+    private readonly dirtyScanBuffer;
+    private readonly enabledAtMs;
+    private readonly inFlightFlags;
+    private readonly enabledFlags;
+    private readonly transitionWords;
+    private enabledTransitionCount;
+    private readonly inFlightPromises;
+    private readonly inFlightContexts;
+    private readonly inFlightConsumed;
+    private readonly inFlightStartMs;
+    private readonly inFlightResolves;
+    private readonly inFlightErrors;
+    private inFlightCount;
+    private readonly pendingResetWords;
+    private hasPendingResets;
+    private readonly completionQueue;
+    private readonly externalQueue;
+    private wakeUpResolve;
+    private readonly markingSnapBuffer;
+    private readonly firingSnapBuffer;
+    private readonly awaitPromises;
+    private readonly racePromises;
+    private readonly readyBuffer;
+    private running;
+    private closed;
+    private marking;
+    constructor(net: PetriNet, initialTokens: Map<Place<any>, Token<any>[]>, options?: PrecompiledNetExecutorOptions);
+    private markTransitionDirty;
+    private markDirty;
+    private setMarkingBit;
+    private clearMarkingBit;
+    run(timeoutMs?: number): Promise<Marking>;
+    private executeLoop;
+    inject<T>(envPlace: EnvironmentPlace<T>, token: Token<T>): Promise<boolean>;
+    injectValue<T>(envPlace: EnvironmentPlace<T>, value: T): Promise<boolean>;
+    private initializeMarkingBitmap;
+    private markAllDirty;
+    private shouldTerminate;
+    private updateDirtyTransitions;
+    private enforceDeadlines;
+    private canEnable;
+    private countMatching;
+    private removeFirstMatching;
+    private hasInputFromResetPlace;
+    private fireReadyTransitions;
+    /**
+     * Fast path for nets where all transitions are immediate and same priority.
+     * Simple linear scan matching BitmapNetExecutor's pattern.
+     */
+    private fireReadyImmediate;
+    private fireReadyGeneral;
+    private fireTransition;
+    private fireTransitionGuarded;
+    private updateBitmapAfterConsumption;
+    private processCompletedTransitions;
+    private processExternalEvents;
+    private drainPendingExternalEvents;
+    private awaitWork;
+    private millisUntilNextTimedTransition;
+    private wakeUp;
+    private hasDirtyBits;
+    private syncMarkingFromQueues;
+    getMarking(): Marking;
+    private snapshotMarking;
+    isQuiescent(): boolean;
+    executionId(): string;
+    close(): void;
+    private emitEvent;
+}
+
 /**
  * Error thrown when a transition's output doesn't satisfy its declared Out spec.
  */
@@ -348,4 +552,4 @@ declare function validateOutSpec(tName: string, spec: Out, producedPlaceNames: S
  */
 declare function produceTimeoutOutput(context: TransitionContext, timeoutChild: Out): void;
 
-export { BitmapNetExecutor, type BitmapNetExecutorOptions, type CardinalityCheck, CompiledNet, EnvironmentPlace, EventStore, type GuardSpec, Marking, Out, OutViolationError, PetriNet, type PetriNetExecutor, Place, Token, Transition, TransitionContext, clearBit, containsAll, intersects, produceTimeoutOutput, setBit, testBit, validateOutSpec };
+export { BitmapNetExecutor, type BitmapNetExecutorOptions, type CardinalityCheck, CompiledNet, EnvironmentPlace, EventStore, type GuardSpec, Marking, Out, OutViolationError, PetriNet, type PetriNetExecutor, Place, PrecompiledNet, PrecompiledNetExecutor, type PrecompiledNetExecutorOptions, Token, Transition, TransitionContext, clearBit, containsAll, intersects, produceTimeoutOutput, setBit, testBit, validateOutSpec };