libpetri 0.3.4 → 0.4.0

package/dist/debug/index.d.ts

@@ -0,0 +1,408 @@
+import { a as PetriNet, b as Transition, T as Token } from '../petri-net-C3Jy5HCt.js';
+import { E as EventStore, N as NetEvent } from '../event-store-Y8q_wapJ.js';
+
+/**
+ * Commands sent from debug UI client to server via WebSocket.
+ * TypeScript port of Java's DebugCommand sealed interface.
+ */
+type SubscriptionMode = 'live' | 'replay';
+type BreakpointType = 'TRANSITION_ENABLED' | 'TRANSITION_START' | 'TRANSITION_COMPLETE' | 'TRANSITION_FAIL' | 'TOKEN_ADDED' | 'TOKEN_REMOVED';
+interface BreakpointConfig {
+    readonly id: string;
+    readonly type: BreakpointType;
+    readonly target: string | null;
+    readonly enabled: boolean;
+}
+interface EventFilter {
+    readonly eventTypes: readonly string[] | null;
+    readonly transitionNames: readonly string[] | null;
+    readonly placeNames: readonly string[] | null;
+}
+type DebugCommand = {
+    readonly type: 'subscribe';
+    readonly sessionId: string;
+    readonly mode: SubscriptionMode;
+    readonly fromIndex?: number;
+} | {
+    readonly type: 'unsubscribe';
+    readonly sessionId: string;
+} | {
+    readonly type: 'listSessions';
+    readonly limit?: number;
+    readonly activeOnly?: boolean;
+} | {
+    readonly type: 'seek';
+    readonly sessionId: string;
+    readonly timestamp: string;
+} | {
+    readonly type: 'playbackSpeed';
+    readonly sessionId: string;
+    readonly speed: number;
+} | {
+    readonly type: 'filter';
+    readonly sessionId: string;
+    readonly filter: EventFilter;
+} | {
+    readonly type: 'pause';
+    readonly sessionId: string;
+} | {
+    readonly type: 'resume';
+    readonly sessionId: string;
+} | {
+    readonly type: 'stepForward';
+    readonly sessionId: string;
+} | {
+    readonly type: 'stepBackward';
+    readonly sessionId: string;
+} | {
+    readonly type: 'setBreakpoint';
+    readonly sessionId: string;
+    readonly breakpoint: BreakpointConfig;
+} | {
+    readonly type: 'clearBreakpoint';
+    readonly sessionId: string;
+    readonly breakpointId: string;
+} | {
+    readonly type: 'listBreakpoints';
+    readonly sessionId: string;
+};
+declare function eventFilterAll(): EventFilter;
+
+/**
+ * Responses sent from server to debug UI client via WebSocket.
+ * TypeScript port of Java's DebugResponse sealed interface.
+ */
+
+interface SessionSummary {
+    readonly sessionId: string;
+    readonly netName: string;
+    readonly startTime: string;
+    readonly active: boolean;
+    readonly eventCount: number;
+}
+interface TokenInfo {
+    readonly id: string | null;
+    readonly type: string;
+    readonly value: string | null;
+    readonly timestamp: string | null;
+}
+interface NetEventInfo {
+    readonly type: string;
+    readonly timestamp: string;
+    readonly transitionName: string | null;
+    readonly placeName: string | null;
+    readonly details: Record<string, unknown>;
+}
+interface PlaceInfo {
+    readonly name: string;
+    readonly graphId: string;
+    readonly tokenType: string;
+    readonly isStart: boolean;
+    readonly isEnd: boolean;
+    readonly isEnvironment: boolean;
+}
+interface TransitionInfo {
+    readonly name: string;
+    readonly graphId: string;
+}
+interface NetStructure {
+    readonly places: readonly PlaceInfo[];
+    readonly transitions: readonly TransitionInfo[];
+}
+type DebugResponse = {
+    readonly type: 'sessionList';
+    readonly sessions: readonly SessionSummary[];
+} | {
+    readonly type: 'subscribed';
+    readonly sessionId: string;
+    readonly netName: string;
+    readonly dotDiagram: string;
+    readonly structure: NetStructure;
+    readonly currentMarking: Record<string, readonly TokenInfo[]>;
+    readonly enabledTransitions: readonly string[];
+    readonly inFlightTransitions: readonly string[];
+    readonly eventCount: number;
+    readonly mode: string;
+} | {
+    readonly type: 'unsubscribed';
+    readonly sessionId: string;
+} | {
+    readonly type: 'event';
+    readonly sessionId: string;
+    readonly index: number;
+    readonly event: NetEventInfo;
+} | {
+    readonly type: 'eventBatch';
+    readonly sessionId: string;
+    readonly startIndex: number;
+    readonly events: readonly NetEventInfo[];
+    readonly hasMore: boolean;
+} | {
+    readonly type: 'markingSnapshot';
+    readonly sessionId: string;
+    readonly marking: Record<string, readonly TokenInfo[]>;
+    readonly enabledTransitions: readonly string[];
+    readonly inFlightTransitions: readonly string[];
+} | {
+    readonly type: 'playbackStateChanged';
+    readonly sessionId: string;
+    readonly paused: boolean;
+    readonly speed: number;
+    readonly currentIndex: number;
+} | {
+    readonly type: 'filterApplied';
+    readonly sessionId: string;
+    readonly filter: EventFilter;
+} | {
+    readonly type: 'breakpointHit';
+    readonly sessionId: string;
+    readonly breakpointId: string;
+    readonly event: NetEventInfo;
+    readonly eventIndex: number;
+} | {
+    readonly type: 'breakpointList';
+    readonly sessionId: string;
+    readonly breakpoints: readonly BreakpointConfig[];
+} | {
+    readonly type: 'breakpointSet';
+    readonly sessionId: string;
+    readonly breakpoint: BreakpointConfig;
+} | {
+    readonly type: 'breakpointCleared';
+    readonly sessionId: string;
+    readonly breakpointId: string;
+} | {
+    readonly type: 'error';
+    readonly code: string;
+    readonly message: string;
+    readonly sessionId: string | null;
+};
+
+/**
+ * Analyze places for start/end/environment classification.
+ * TypeScript port of Java's PlaceAnalysis.
+ */
+
+interface PlaceAnalysisInfo {
+    readonly tokenType: string;
+    readonly hasIncoming: boolean;
+    readonly hasOutgoing: boolean;
+}
+declare class PlaceAnalysis {
+    private readonly _data;
+    constructor(data: ReadonlyMap<string, PlaceAnalysisInfo>);
+    get data(): ReadonlyMap<string, PlaceAnalysisInfo>;
+    isStart(placeName: string): boolean;
+    isEnd(placeName: string): boolean;
+    /** Build place analysis from a PetriNet. */
+    static from(net: PetriNet): PlaceAnalysis;
+}
+
+/**
+ * EventStore with live tailing and historical replay.
+ * TypeScript port of Java's DebugEventStore.
+ *
+ * Node.js simplifications: single-threaded, no locks needed,
+ * synchronous Set<Function> for subscribers, microtask broadcast.
+ */
+
+/** Handle for managing a live event subscription. */
+interface Subscription {
+    cancel(): void;
+    isActive(): boolean;
+}
+/** Default maximum events to retain before evicting oldest. */
+declare const DEFAULT_MAX_EVENTS = 10000;
+declare class DebugEventStore implements EventStore {
+    private readonly _events;
+    private readonly _subscribers;
+    private readonly _sessionId;
+    private readonly _maxEvents;
+    private _eventCount;
+    private _evictedCount;
+    constructor(sessionId: string, maxEvents?: number);
+    get sessionId(): string;
+    get maxEvents(): number;
+    /** Total events appended (including evicted). */
+    eventCount(): number;
+    /** Number of events evicted from the store. */
+    evictedCount(): number;
+    append(event: NetEvent): void;
+    events(): readonly NetEvent[];
+    isEnabled(): boolean;
+    size(): number;
+    isEmpty(): boolean;
+    /** Subscribe to receive events as they occur. */
+    subscribe(listener: (event: NetEvent) => void): Subscription;
+    /** Number of active subscribers. */
+    subscriberCount(): number;
+    /** Returns events starting from a specific index. */
+    eventsFrom(fromIndex: number): readonly NetEvent[];
+    /** Returns all events since the specified timestamp. */
+    eventsSince(from: number): readonly NetEvent[];
+    /** Returns events within a time range. */
+    eventsBetween(from: number, to: number): readonly NetEvent[];
+    /** Close the store (no-op in JS, but matches Java interface). */
+    close(): void;
+}
+
+/**
+ * Registry for managing Petri net debug sessions.
+ * TypeScript port of Java's DebugSessionRegistry.
+ */
+
+interface DebugSession {
+    readonly sessionId: string;
+    readonly netName: string;
+    readonly dotDiagram: string;
+    readonly places: PlaceAnalysis;
+    readonly transitions: ReadonlySet<Transition>;
+    readonly eventStore: DebugEventStore;
+    readonly startTime: number;
+    readonly active: boolean;
+}
+type EventStoreFactory = (sessionId: string) => DebugEventStore;
+declare class DebugSessionRegistry {
+    private readonly _sessions;
+    private readonly _maxSessions;
+    private readonly _eventStoreFactory;
+    constructor(maxSessions?: number, eventStoreFactory?: EventStoreFactory);
+    /**
+     * Registers a new debug session for the given Petri net.
+     * Generates DOT diagram and extracts net structure.
+     */
+    register(sessionId: string, net: PetriNet): DebugSession;
+    /** Marks a session as completed (no longer active). */
+    complete(sessionId: string): void;
+    /** Removes a session from the registry. */
+    remove(sessionId: string): DebugSession | undefined;
+    /** Returns a session by ID. */
+    getSession(sessionId: string): DebugSession | undefined;
+    /** Lists sessions, ordered by start time (most recent first). */
+    listSessions(limit: number): readonly DebugSession[];
+    /** Lists only active sessions. */
+    listActiveSessions(limit: number): readonly DebugSession[];
+    /** Total number of sessions. */
+    get size(): number;
+    /** Evicts oldest inactive sessions if at capacity. */
+    private evictIfNecessary;
+}
+
+/**
+ * Framework-agnostic handler for the Petri net debug protocol.
+ * TypeScript port of Java's DebugProtocolHandler.
+ *
+ * Manages debug subscriptions, event filtering, breakpoints, and replay
+ * for connected clients. Decoupled from any specific WebSocket framework
+ * via the ResponseSink type.
+ */
+
+/** Callback for sending responses to a connected client. */
+type ResponseSink = (response: DebugResponse) => void;
+/** Computed state from replaying events. */
+interface ComputedState {
+    readonly marking: ReadonlyMap<string, readonly TokenInfo[]>;
+    readonly enabledTransitions: readonly string[];
+    readonly inFlightTransitions: readonly string[];
+}
+declare class DebugProtocolHandler {
+    private readonly _sessionRegistry;
+    private readonly _clients;
+    constructor(sessionRegistry: DebugSessionRegistry);
+    /** Registers a new client connection. */
+    clientConnected(clientId: string, sink: ResponseSink): void;
+    /** Cleans up when a client disconnects. */
+    clientDisconnected(clientId: string): void;
+    /** Handles a command from a connected client. */
+    handleCommand(clientId: string, command: DebugCommand): void;
+    private handleListSessions;
+    private handleSubscribe;
+    private subscribeLive;
+    private subscribeReplay;
+    private handleUnsubscribe;
+    private handleSeek;
+    private handlePlaybackSpeed;
+    private handleSetFilter;
+    private handlePause;
+    private handleResume;
+    private handleStepForward;
+    private handleStepBackward;
+    private handleSetBreakpoint;
+    private handleClearBreakpoint;
+    private handleListBreakpoints;
+    private send;
+    private sendError;
+    private sendInBatches;
+}
+
+/**
+ * Caches computed state snapshots at periodic intervals for efficient seek/step.
+ * TypeScript port of Java's MarkingCache.
+ */
+
+/** Number of events between cached snapshots. */
+declare const SNAPSHOT_INTERVAL = 256;
+declare class MarkingCache {
+    private readonly _snapshots;
+    /**
+     * Computes the state at the given event index, using cached snapshots
+     * to minimize the number of events that need to be replayed.
+     *
+     * @param events the full event list for the session
+     * @param targetIndex event index to compute state at (exclusive upper bound)
+     */
+    computeAt(events: readonly NetEvent[], targetIndex: number): ComputedState;
+    /** Invalidates the cache. */
+    invalidate(): void;
+    /** Extends the snapshot cache to cover at least up to the given event index. */
+    private ensureCachedUpTo;
+}
+
+/**
+ * Converts CTPN NetEvent instances to serializable DebugResponse types.
+ * TypeScript port of Java's NetEventConverter.
+ */
+
+/** Converts a NetEvent to a serializable NetEventInfo. */
+declare function toEventInfo(event: NetEvent, compact?: boolean): NetEventInfo;
+/** Converts a Token to serializable TokenInfo with full value. */
+declare function tokenInfo(token: Token<unknown>): TokenInfo;
+/** Converts a Token to compact TokenInfo (type only, no value). */
+declare function compactTokenInfo(token: Token<unknown>): TokenInfo;
+/** Converts a marking map to serializable form. */
+declare function convertMarking(marking: ReadonlyMap<string, readonly Token<unknown>[]>, compact?: boolean): Record<string, readonly TokenInfo[]>;
+
+/**
+ * EventStore that delegates to both a primary store and a debug store.
+ * TypeScript port of Java's DebugAwareEventStore.
+ */
+
+declare class DebugAwareEventStore implements EventStore {
+    private readonly _primary;
+    private readonly _debugStore;
+    constructor(primary: EventStore, debugStore: DebugEventStore);
+    append(event: NetEvent): void;
+    events(): readonly NetEvent[];
+    isEnabled(): boolean;
+    size(): number;
+    isEmpty(): boolean;
+    /** Returns the underlying debug store for subscription management. */
+    get debugStore(): DebugEventStore;
+}
+
+/**
+ * Debug infrastructure for Petri net execution visualization.
+ *
+ * Provides a framework-agnostic debug protocol handler, event store with
+ * live tailing, session registry, and marking cache for efficient replay.
+ *
+ * @module debug
+ */
+
+/**
+ * Returns the path to the bundled debug UI assets directory.
+ * Requires Node.js — resolves relative to this module's location.
+ */
+declare function debugUiAssetPath(): Promise<string>;
+
+export { type BreakpointConfig, type BreakpointType, type ComputedState, DEFAULT_MAX_EVENTS, DebugAwareEventStore, type DebugCommand, DebugEventStore, DebugProtocolHandler, type DebugResponse, type DebugSession, DebugSessionRegistry, type EventFilter, type EventStoreFactory, MarkingCache, type NetEventInfo, type NetStructure, PlaceAnalysis, type PlaceAnalysisInfo, type PlaceInfo, type ResponseSink, SNAPSHOT_INTERVAL, type SessionSummary, type Subscription, type SubscriptionMode, type TokenInfo, type TransitionInfo, compactTokenInfo, convertMarking, debugUiAssetPath, eventFilterAll, toEventInfo, tokenInfo };