libpetri 0.3.2

package/dist/index.d.ts

@@ -0,0 +1,498 @@
+import { P as Place, T as Token, a as PetriNet, b as Transition, E as EnvironmentPlace, c as TransitionContext, O as Out } from './petri-net-C3Jy5HCt.js';
+export { A as Arc, d as ArcInhibitor, e as ArcInput, f as ArcOutput, g as ArcRead, h as ArcReset, I as In, i as InAll, j as InAtLeast, k as InExactly, l as InOne, L as LogFn, M as MAX_DURATION_MS, m as OutAnd, n as OutForwardInput, o as OutPlace, p as OutTimeout, q as OutXor, r as OutputEntry, s as PetriNetBuilder, t as Timing, u as TimingDeadline, v as TimingDelayed, w as TimingExact, x as TimingImmediate, y as TimingWindow, z as TokenInput, B as TokenOutput, C as TransitionAction, D as TransitionBuilder, F as all, G as allPlaces, H as and, J as andPlaces, K as arcPlace, N as atLeast, Q as consumptionCount, R as deadline, S as delayed, U as earliest, V as enumerateBranches, W as environmentPlace, X as exact, Y as exactly, Z as fork, _ as forwardInput, $ as hasDeadline, a0 as hasGuard, a1 as immediate, a2 as inhibitorArc, a3 as inputArc, a4 as isUnit, a5 as latest, a6 as matchesGuard, a7 as one, a8 as outPlace, a9 as outputArc, aa as passthrough, ab as place, ac as produce, ad as readArc, ae as requiredCount, af as resetArc, ag as timeout, ah as timeoutPlace, ai as tokenAt, aj as tokenOf, ak as transform, al as transformAsync, am as transformFrom, an as unitToken, ao as window, ap as withTimeout, aq as xor, ar as xorPlaces } from './petri-net-C3Jy5HCt.js';
+
+/**
+ * @module marking
+ *
+ * Mutable token state (marking) of a running Petri net.
+ *
+ * Tokens per place are stored in FIFO arrays (push to end, shift from front).
+ * Not thread-safe — all mutation occurs from the single-threaded orchestrator.
+ *
+ * For typical nets (≤10 tokens per place), Array.shift() is faster than a deque
+ * due to cache locality. Only optimize if profiling shows a bottleneck.
+ */
+
+/** Anything that carries a place reference and an optional guard predicate. */
+interface GuardSpec<T = any> {
+    readonly place: Place<T>;
+    readonly guard?: (value: T) => boolean;
+}
+/**
+ * Mutable marking (token state) of a Petri Net during execution.
+ *
+ * Tokens in each place are maintained in FIFO order (array: push to end, shift from front).
+ * Not thread-safe — all access must be from the orchestrator.
+ */
+declare class Marking {
+    /** Place name -> FIFO queue of tokens. */
+    private readonly tokens;
+    /** Place name -> Place reference (for inspection). */
+    private readonly placeRefs;
+    static empty(): Marking;
+    static from(initial: Map<Place<any>, Token<any>[]>): Marking;
+    addToken<T>(place: Place<T>, token: Token<T>): void;
+    /** Removes and returns the oldest token. Returns null if empty. */
+    removeFirst<T>(place: Place<T>): Token<T> | null;
+    /** Removes and returns all tokens from a place. */
+    removeAll<T>(place: Place<T>): Token<T>[];
+    /**
+     * Removes and returns the first token whose value satisfies the guard predicate.
+     *
+     * Performs a linear scan of the place's FIFO queue. If no guard is provided,
+     * behaves like `removeFirst()`. If a guard is provided, skips non-matching
+     * tokens and splices the first match out of the queue (O(n) worst case).
+     */
+    removeFirstMatching(spec: GuardSpec): Token<any> | null;
+    /** Check if any token matches a guard predicate. */
+    hasMatchingToken(spec: GuardSpec): boolean;
+    /**
+     * Counts tokens in a place whose values satisfy the guard predicate.
+     *
+     * If no guard is provided, returns the total token count (O(1)).
+     * With a guard, performs a linear scan over all tokens (O(n)).
+     * Used by the executor for enablement checks on guarded `all`/`at-least` inputs.
+     */
+    countMatching(spec: GuardSpec): number;
+    /**
+     * Returns tokens in a place. **Returns a live reference** to the internal
+     * array — callers must not mutate it. Copy with `[...peekTokens(p)]` if
+     * mutation or snapshot semantics are needed.
+     */
+    peekTokens<T>(place: Place<T>): readonly Token<T>[];
+    /** Returns the oldest token without removing it. */
+    peekFirst<T>(place: Place<T>): Token<T> | null;
+    /** Checks if a place has any tokens. */
+    hasTokens(place: Place<any>): boolean;
+    /** Returns the number of tokens in a place. */
+    tokenCount(place: Place<any>): number;
+    toString(): string;
+}
+
+/**
+ * @module compiled-net
+ *
+ * Integer-indexed, precomputed representation of a PetriNet for bitmap-based execution.
+ *
+ * **Precomputation strategy**: At compile time, all places and transitions are assigned
+ * stable integer IDs. Input/inhibitor arcs are converted to Uint32Array bitmasks (one per
+ * transition), enabling O(W) enablement checks via bitwise AND where W = ceil(numPlaces/32).
+ *
+ * **Why bitmaps**: JS bitwise operators work natively on 32-bit integers. Using Uint32Array
+ * with 32-bit words (WORD_SHIFT=5) avoids BigInt overhead while keeping enablement checks
+ * branch-free and cache-friendly. For a typical 50-place net, W=2 words per mask.
+ *
+ * **Reverse index**: A place-to-transitions mapping enables the dirty set pattern —
+ * when a place's marking changes, only affected transitions are re-evaluated.
+ */
+
+interface CardinalityCheck {
+    readonly placeIds: readonly number[];
+    readonly requiredCounts: readonly number[];
+}
+/**
+ * Integer-indexed, precomputed representation of a PetriNet for bitmap-based execution.
+ *
+ * Uses Uint32Array masks with 32-bit words (JS bitwise ops work on 32-bit ints natively).
+ */
+declare class CompiledNet {
+    readonly net: PetriNet;
+    readonly placeCount: number;
+    readonly transitionCount: number;
+    readonly wordCount: number;
+    private readonly _placesById;
+    private readonly _transitionsById;
+    private readonly _placeIndex;
+    private readonly _transitionIndex;
+    private readonly _needsMask;
+    private readonly _inhibitorMask;
+    private readonly _placeToTransitions;
+    private readonly _consumptionPlaceIds;
+    private readonly _cardinalityChecks;
+    private readonly _hasGuards;
+    private constructor();
+    static compile(net: PetriNet): CompiledNet;
+    place(pid: number): Place<any>;
+    transition(tid: number): Transition;
+    placeId(place: Place<any>): number;
+    transitionId(t: Transition): number;
+    affectedTransitions(pid: number): readonly number[];
+    consumptionPlaceIds(tid: number): readonly number[];
+    cardinalityCheck(tid: number): CardinalityCheck | null;
+    hasGuards(tid: number): boolean;
+    /**
+     * Two-phase bitmap enablement check for a transition:
+     * 1. **Presence check**: verifies all required places (inputs + reads) have tokens
+     *    via `containsAll(snapshot, needsMask)`.
+     * 2. **Inhibitor check**: verifies no inhibitor places have tokens
+     *    via `!intersects(snapshot, inhibitorMask)`.
+     *
+     * This is a necessary but not sufficient condition — cardinality and guard checks
+     * are performed separately by the executor for transitions that pass this fast path.
+     */
+    canEnableBitmap(tid: number, markingSnapshot: Uint32Array): boolean;
+}
+declare function setBit(arr: Uint32Array, bit: number): void;
+declare function clearBit(arr: Uint32Array, bit: number): void;
+declare function testBit(arr: Uint32Array, bit: number): boolean;
+/** Checks if all bits in mask are set in snapshot. */
+declare function containsAll(snapshot: Uint32Array, mask: Uint32Array): boolean;
+/** Checks if any bit in mask is set in snapshot. */
+declare function intersects(snapshot: Uint32Array, mask: Uint32Array): boolean;
+
+/**
+ * Events emitted during Petri Net execution.
+ * Discriminated union capturing all observable state changes.
+ */
+type NetEvent = ExecutionStarted | ExecutionCompleted | TransitionEnabled | TransitionClockRestarted | TransitionStarted | TransitionCompleted | TransitionFailed | TransitionTimedOut | ActionTimedOut | TokenAdded | TokenRemoved | LogMessage | MarkingSnapshot;
+interface ExecutionStarted {
+    readonly type: 'execution-started';
+    readonly timestamp: number;
+    readonly netName: string;
+    readonly executionId: string;
+}
+interface ExecutionCompleted {
+    readonly type: 'execution-completed';
+    readonly timestamp: number;
+    readonly netName: string;
+    readonly executionId: string;
+    readonly totalDurationMs: number;
+}
+interface TransitionEnabled {
+    readonly type: 'transition-enabled';
+    readonly timestamp: number;
+    readonly transitionName: string;
+}
+interface TransitionClockRestarted {
+    readonly type: 'transition-clock-restarted';
+    readonly timestamp: number;
+    readonly transitionName: string;
+}
+interface TransitionStarted {
+    readonly type: 'transition-started';
+    readonly timestamp: number;
+    readonly transitionName: string;
+    readonly consumedTokens: readonly Token<unknown>[];
+}
+interface TransitionCompleted {
+    readonly type: 'transition-completed';
+    readonly timestamp: number;
+    readonly transitionName: string;
+    readonly producedTokens: readonly Token<unknown>[];
+    readonly durationMs: number;
+}
+interface TransitionFailed {
+    readonly type: 'transition-failed';
+    readonly timestamp: number;
+    readonly transitionName: string;
+    readonly errorMessage: string;
+    readonly exceptionType: string;
+    /** Original stack trace, if available. */
+    readonly stack?: string;
+}
+/**
+ * Emitted when a transition exceeds its deadline (upper time bound) without firing.
+ * Classical TPN semantics: transition is forcibly disabled by the executor in
+ * `updateDirtyTransitions()` when elapsed time exceeds `latest(timing)`.
+ */
+interface TransitionTimedOut {
+    readonly type: 'transition-timed-out';
+    readonly timestamp: number;
+    readonly transitionName: string;
+    /** The deadline that was exceeded, in milliseconds from enablement. */
+    readonly deadlineMs: number;
+    /** Actual time elapsed since enablement, in milliseconds. */
+    readonly actualDurationMs: number;
+}
+interface ActionTimedOut {
+    readonly type: 'action-timed-out';
+    readonly timestamp: number;
+    readonly transitionName: string;
+    readonly timeoutMs: number;
+}
+interface TokenAdded {
+    readonly type: 'token-added';
+    readonly timestamp: number;
+    readonly placeName: string;
+    readonly token: Token<unknown>;
+}
+interface TokenRemoved {
+    readonly type: 'token-removed';
+    readonly timestamp: number;
+    readonly placeName: string;
+    readonly token: Token<unknown>;
+}
+interface LogMessage {
+    readonly type: 'log-message';
+    readonly timestamp: number;
+    readonly transitionName: string;
+    readonly logger: string;
+    readonly level: string;
+    readonly message: string;
+    readonly error: string | null;
+    readonly errorMessage: string | null;
+}
+/**
+ * Snapshot of the full marking (token state) at a point in time.
+ * Emitted at two points during execution:
+ * 1. After initialization (before the main loop) — captures the initial marking
+ * 2. Before the execution-completed event — captures the final marking
+ */
+interface MarkingSnapshot {
+    readonly type: 'marking-snapshot';
+    readonly timestamp: number;
+    /** Place name -> tokens in that place at snapshot time. Only non-empty places are included. */
+    readonly marking: ReadonlyMap<string, readonly Token<unknown>[]>;
+}
+/** Extracts transition name from events that have one. Returns null otherwise. */
+declare function eventTransitionName(event: NetEvent): string | null;
+/** Checks if the event is a failure type. */
+declare function isFailureEvent(event: NetEvent): boolean;
+
+/**
+ * Storage for events emitted during Petri net execution.
+ */
+interface EventStore {
+    /** Appends an event to the store. */
+    append(event: NetEvent): void;
+    /** Returns all events in chronological order. */
+    events(): readonly NetEvent[];
+    /** Whether this store is enabled (false = skip event creation). */
+    isEnabled(): boolean;
+    /** Number of events captured. */
+    size(): number;
+    /** Whether no events have been captured. */
+    isEmpty(): boolean;
+}
+/** Returns events matching a predicate. */
+declare function filterEvents(store: EventStore, predicate: (e: NetEvent) => boolean): NetEvent[];
+/** Returns events of a specific type. */
+declare function eventsOfType<T extends NetEvent['type']>(store: EventStore, type: T): Extract<NetEvent, {
+    type: T;
+}>[];
+/** Returns all events for a specific transition. */
+declare function transitionEvents(store: EventStore, transitionName: string): NetEvent[];
+/** Returns all failure events. */
+declare function failures(store: EventStore): NetEvent[];
+declare class InMemoryEventStore implements EventStore {
+    private readonly _events;
+    append(event: NetEvent): void;
+    events(): readonly NetEvent[];
+    isEnabled(): boolean;
+    size(): number;
+    isEmpty(): boolean;
+    /** Clears all stored events. */
+    clear(): void;
+}
+/** Returns a no-op event store that discards all events. */
+declare function noopEventStore(): EventStore;
+/** Creates a new in-memory event store. */
+declare function inMemoryEventStore(): InMemoryEventStore;
+
+/**
+ * Interface for Petri net executors.
+ */
+interface PetriNetExecutor {
+    /** Run the net until quiescence or timeout. */
+    run(timeoutMs?: number): Promise<Marking>;
+    /** Inject an external token. Returns true if accepted. */
+    inject<T>(place: EnvironmentPlace<T>, token: Token<T>): Promise<boolean>;
+    /** Shut down the executor. */
+    close(): void;
+}
+
+/**
+ * @module bitmap-net-executor
+ *
+ * Async bitmap-based executor for Typed Coloured Time Petri Nets.
+ *
+ * **Execution loop phases** (per cycle):
+ * 1. Process completed transitions — collect outputs, validate against Out specs
+ * 2. Process external events — inject tokens from EnvironmentPlaces
+ * 3. Update dirty transitions — re-evaluate enablement for transitions whose
+ *    input/inhibitor/read places changed (bitmap-based dirty set tracking)
+ * 4. Fire ready transitions — sorted by priority (desc) then FIFO enablement time
+ * 5. Await work — sleep until an action completes, a timer fires, or an external event arrives
+ *
+ * **Concurrency model**: Single-threaded JS event loop. No locks or CAS needed.
+ * Multiple transitions execute concurrently via Promises (actions return Promise<void>).
+ * Only the orchestrator mutates marking state — actions communicate via TokenOutput.
+ *
+ * **Bitmap strategy**: Places are tracked as bits in Uint32Array words. Enablement
+ * checks use bitwise AND/OR for O(W) where W = ceil(numPlaces/32). A dirty set
+ * bitmap tracks which transitions need re-evaluation, avoiding O(T) scans per cycle.
+ *
+ * @see CompiledNet for the precomputed bitmap masks and reverse indices
+ */
+
+interface BitmapNetExecutorOptions {
+    eventStore?: EventStore;
+    environmentPlaces?: Set<EnvironmentPlace<any>>;
+    longRunning?: boolean;
+    /** Provides execution context data for each transition firing. */
+    executionContextProvider?: (transitionName: string, consumed: Token<any>[]) => Map<string, unknown>;
+}
+/**
+ * Async bitmap-based executor for Coloured Time Petri Nets.
+ *
+ * Single-threaded JS model: no CAS needed, direct array writes.
+ * Actions return Promise<void> — multiple in-flight actions are naturally concurrent.
+ *
+ * @remarks
+ * **Deadline enforcement**: Transitions with finite deadlines (`deadline`, `window`, `exact`)
+ * are checked in `enforceDeadlines()`, called from the main loop only when `hasAnyDeadlines`
+ * is true (precomputed at construction). If a transition has been enabled longer than
+ * `latest(timing)`, it is forcibly disabled and a `TransitionTimedOut` event is emitted.
+ * The `awaitWork()` timer also schedules wake-ups for approaching deadlines, not just
+ * earliest firing times.
+ *
+ * **Constructor precomputation**: `hasAnyDeadlines`, `allImmediate`/`allSamePriority`,
+ * and `eventStoreEnabled` are computed once to avoid per-cycle overhead. Safe because
+ * `isEnabled()` is constant and timing/priority are immutable on Transition.
+ */
+declare class BitmapNetExecutor implements PetriNetExecutor {
+    private readonly compiled;
+    private readonly marking;
+    private readonly eventStore;
+    private readonly environmentPlaces;
+    private readonly longRunning;
+    private readonly executionContextProvider?;
+    private readonly startMs;
+    private readonly hasAnyDeadlines;
+    private readonly allImmediate;
+    private readonly allSamePriority;
+    private readonly eventStoreEnabled;
+    private readonly markedPlaces;
+    private readonly dirtySet;
+    private readonly markingSnapBuffer;
+    private readonly dirtySnapBuffer;
+    private readonly firingSnapBuffer;
+    private readonly enabledAtMs;
+    private readonly inFlightFlags;
+    private readonly enabledFlags;
+    /** Precomputed: 1 if transition has a finite deadline, 0 otherwise. */
+    private readonly hasDeadlineFlags;
+    private enabledTransitionCount;
+    private readonly inFlight;
+    private readonly inFlightPromises;
+    private readonly awaitPromises;
+    private readonly completionQueue;
+    private readonly externalQueue;
+    private wakeUpResolve;
+    private readonly readyBuffer;
+    private readonly pendingResetPlaces;
+    private readonly transitionInputPlaceNames;
+    private running;
+    private closed;
+    constructor(net: PetriNet, initialTokens: Map<Place<any>, Token<any>[]>, options?: BitmapNetExecutorOptions);
+    run(timeoutMs?: number): Promise<Marking>;
+    private executeLoop;
+    inject<T>(envPlace: EnvironmentPlace<T>, token: Token<T>): Promise<boolean>;
+    /** Convenience: inject a raw value (creates token with current timestamp). */
+    injectValue<T>(envPlace: EnvironmentPlace<T>, value: T): Promise<boolean>;
+    private initializeMarkedBitmap;
+    private markAllDirty;
+    private shouldTerminate;
+    private updateDirtyTransitions;
+    /**
+     * Checks all enabled transitions with finite deadlines. If a transition has been
+     * enabled longer than `latest(timing)`, it is forcibly disabled and a
+     * `TransitionTimedOut` event is emitted. Classical TPN semantics require transitions
+     * to either fire within their window or become disabled.
+     *
+     * A 1ms tolerance is applied to account for timer jitter and microtask scheduling
+     * delays. Without this, exact-timed transitions (where earliest == latest) would
+     * almost always be disabled before they can fire.
+     */
+    private enforceDeadlines;
+    private canEnable;
+    private hasInputFromResetPlace;
+    private fireReadyTransitions;
+    /**
+     * Fast path for nets where all transitions are immediate and same priority.
+     * Skips timing checks, sorting, and snapshot buffer — just scan and fire.
+     *
+     * Uses live `markedPlaces` instead of a snapshot. Safe because
+     * `updateBitmapAfterConsumption()` synchronously updates the bitmap before the next
+     * iteration. For equal-priority immediate transitions, tid scan order satisfies
+     * FIFO-by-enablement-time (all enabled in the same cycle).
+     */
+    private fireReadyImmediate;
+    private fireReadyGeneral;
+    private fireTransition;
+    private updateBitmapAfterConsumption;
+    private processCompletedTransitions;
+    private processExternalEvents;
+    private drainPendingExternalEvents;
+    /**
+     * Suspends the executor until work is available. Composes up to 3 promise sources
+     * into a single Promise.race: (1) any in-flight action completing, (2) external
+     * event injection via wakeUp(), (3) timer for the next delayed transition's earliest
+     * firing time. This avoids busy-waiting while remaining responsive to all event types.
+     *
+     * **Microtask flush**: Before building Promise.race, yields via `await Promise.resolve()`
+     * to drain the microtask queue. Sync actions complete via `.then()` microtask; this
+     * yield lets those fire, avoiding ~5 allocations when work is already available.
+     * After the yield, re-checks queues and `this.closed` for close-during-yield safety.
+     */
+    private awaitWork;
+    private millisUntilNextTimedTransition;
+    private wakeUp;
+    /** Returns true if any transition needs re-evaluation. O(W) where W = ceil(transitions/32). */
+    private hasDirtyBits;
+    private markDirty;
+    private markTransitionDirty;
+    getMarking(): Marking;
+    /** Builds a snapshot of the current marking for event emission. */
+    private snapshotMarking;
+    isQuiescent(): boolean;
+    executionId(): string;
+    close(): void;
+    private emitEvent;
+}
+
+/**
+ * Error thrown when a transition's output doesn't satisfy its declared Out spec.
+ */
+declare class OutViolationError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * @module executor-support
+ *
+ * Output validation and timeout production for the Petri net executor.
+ *
+ * **Output validation algorithm**: Recursively walks the declared Out spec tree,
+ * checking that the action's produced tokens match the structure:
+ * - Place/ForwardInput: place must be in the produced set
+ * - AND: all children must be satisfied (conjunction)
+ * - XOR: exactly 1 child must be satisfied (throws OutViolationError for 0 or 2+)
+ * - Timeout: delegates to child spec
+ *
+ * Returns the set of "claimed" place names on success, or null if unsatisfied.
+ *
+ * **Timeout production**: When an action exceeds its timeout, produces default
+ * tokens to the timeout branch's output places, enabling the net to continue.
+ */
+
+/**
+ * Recursively validates that a transition's output satisfies its declared Out spec.
+ *
+ * @returns the set of claimed place names, or null if not satisfied
+ * @throws OutViolationError if a structural violation is detected (e.g. XOR with 0 or 2+ branches)
+ */
+declare function validateOutSpec(tName: string, spec: Out, producedPlaceNames: Set<string>): Set<string> | null;
+/**
+ * Produces default tokens to the timeout branch's output places when an action
+ * exceeds its timeout. Walks the Out spec tree recursively:
+ *
+ * - **Place**: produces `null` (the timeout sentinel value).
+ * - **ForwardInput**: forwards the consumed input token to the output place.
+ * - **AND**: recurses into all children (all branches get tokens).
+ * - **XOR**: disallowed — timeout cannot choose a branch non-deterministically.
+ * - **Timeout**: disallowed — nested timeouts would create ambiguous recovery paths.
+ */
+declare function produceTimeoutOutput(context: TransitionContext, timeoutChild: Out): void;
+
+export { type ActionTimedOut, BitmapNetExecutor, type BitmapNetExecutorOptions, type CardinalityCheck, CompiledNet, EnvironmentPlace, type EventStore, type ExecutionCompleted, type ExecutionStarted, type GuardSpec, InMemoryEventStore, type LogMessage, Marking, type MarkingSnapshot, type NetEvent, Out, OutViolationError, PetriNet, type PetriNetExecutor, Place, Token, type TokenAdded, type TokenRemoved, Transition, type TransitionClockRestarted, type TransitionCompleted, TransitionContext, type TransitionEnabled, type TransitionFailed, type TransitionStarted, type TransitionTimedOut, clearBit, containsAll, eventTransitionName, eventsOfType, failures, filterEvents, inMemoryEventStore, intersects, isFailureEvent, noopEventStore, produceTimeoutOutput, setBit, testBit, transitionEvents, validateOutSpec };