libpetri 0.4.1 → 0.5.1

package/dist/debug/index.d.ts

@@ -1,5 +1,6 @@
 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';
+import { Writable } from 'node:stream';
 
 /**
  * Commands sent from debug UI client to server via WebSocket.
@@ -242,10 +243,21 @@ declare class DebugEventStore implements EventStore {
     eventsSince(from: number): readonly NetEvent[];
     /** Returns events within a time range. */
     eventsBetween(from: number, to: number): readonly NetEvent[];
+    /**
+     * Returns an iterator over all retained events.
+     * Useful for archive writers that need zero-copy traversal.
+     */
+    [Symbol.iterator](): Iterator<NetEvent>;
     /** Close the store (no-op in JS, but matches Java interface). */
     close(): void;
 }
 
+/**
+ * Listener notified when a debug session completes.
+ */
+
+type SessionCompletionListener = (session: DebugSession) => void;
+
 /**
  * Registry for managing Petri net debug sessions.
  * TypeScript port of Java's DebugSessionRegistry.
@@ -255,24 +267,30 @@ interface DebugSession {
     readonly sessionId: string;
     readonly netName: string;
     readonly dotDiagram: string;
-    readonly places: PlaceAnalysis;
+    readonly places: PlaceAnalysis | null;
     readonly transitions: ReadonlySet<Transition>;
     readonly eventStore: DebugEventStore;
     readonly startTime: number;
     readonly active: boolean;
+    readonly importedStructure: NetStructure | null;
 }
+/** Builds the net structure from a session's stored place and transition info. */
+declare function buildNetStructure(session: DebugSession): NetStructure;
 type EventStoreFactory = (sessionId: string) => DebugEventStore;
 declare class DebugSessionRegistry {
     private readonly _sessions;
     private readonly _maxSessions;
     private readonly _eventStoreFactory;
-    constructor(maxSessions?: number, eventStoreFactory?: EventStoreFactory);
+    private readonly _completionListeners;
+    constructor(maxSessions?: number, eventStoreFactory?: EventStoreFactory, completionListeners?: SessionCompletionListener[]);
     /**
      * 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). */
+    /**
+     * Marks a session as completed (no longer active) and notifies completion listeners.
+     */
     complete(sessionId: string): void;
     /** Removes a session from the registry. */
     remove(sessionId: string): DebugSession | undefined;
@@ -284,6 +302,12 @@ declare class DebugSessionRegistry {
     listActiveSessions(limit: number): readonly DebugSession[];
     /** Total number of sessions. */
     get size(): number;
+    /**
+     * Registers an imported (archived) session as an inactive, read-only session.
+     */
+    registerImported(sessionId: string, netName: string, dotDiagram: string, structure: NetStructure, eventStore: DebugEventStore, startTime: number): DebugSession;
+    /** Notifies all completion listeners. Exceptions are caught and logged. */
+    private notifyCompletionListeners;
     /** Evicts oldest inactive sessions if at capacity. */
     private evictIfNecessary;
 }
@@ -390,6 +414,87 @@ declare class DebugAwareEventStore implements EventStore {
     get debugStore(): DebugEventStore;
 }
 
+/**
+ * Metadata header for a session archive file.
+ */
+
+interface SessionArchive {
+    readonly version: number;
+    readonly sessionId: string;
+    readonly netName: string;
+    readonly dotDiagram: string;
+    readonly startTime: string;
+    readonly eventCount: number;
+    readonly structure: NetStructure;
+}
+/** Current archive format version. */
+declare const CURRENT_VERSION = 1;
+
+/**
+ * Storage backend interface for session archives.
+ */
+
+interface ArchivedSessionSummary {
+    readonly sessionId: string;
+    readonly key: string;
+    readonly sizeBytes: number;
+    readonly lastModified: number;
+}
+type OutputStreamConsumer = (out: Writable) => Promise<void>;
+interface SessionArchiveStorage {
+    storeStreaming(sessionId: string, writer: OutputStreamConsumer): Promise<void>;
+    list(limit: number, prefix?: string): Promise<readonly ArchivedSessionSummary[]>;
+    retrieve(sessionId: string): Promise<Buffer>;
+    isAvailable(): boolean;
+}
+
+/**
+ * File-system backed storage for session archives.
+ * Uses Node.js fs/promises — no external dependencies.
+ */
+
+declare class FileSessionArchiveStorage implements SessionArchiveStorage {
+    private readonly _directory;
+    constructor(directory: string);
+    storeStreaming(sessionId: string, writer: OutputStreamConsumer): Promise<void>;
+    list(limit: number, prefix?: string): Promise<readonly ArchivedSessionSummary[]>;
+    retrieve(sessionId: string): Promise<Buffer>;
+    isAvailable(): boolean;
+    private archivePath;
+}
+
+/**
+ * Writes a debug session to a length-prefixed binary archive format.
+ *
+ * Format (inside gzip):
+ * [4 bytes: metadata JSON length][N bytes: metadata JSON]
+ * [4 bytes: event JSON length][N bytes: event JSON]
+ * ...
+ * (EOF terminates the stream)
+ */
+
+declare class SessionArchiveWriter {
+    /**
+     * Writes a complete session archive and returns the compressed bytes.
+     */
+    write(session: DebugSession): Buffer;
+}
+
+/**
+ * Reads session archives from length-prefixed binary format.
+ */
+
+interface ImportedSession {
+    readonly metadata: SessionArchive;
+    readonly eventStore: DebugEventStore;
+}
+declare class SessionArchiveReader {
+    /** Reads only the metadata header from an archive. */
+    readMetadata(compressed: Buffer): SessionArchive;
+    /** Reads the full archive: metadata + all events into a DebugEventStore. */
+    readFull(compressed: Buffer): ImportedSession;
+}
+
 /**
  * Debug infrastructure for Petri net execution visualization.
  *
@@ -405,4 +510,4 @@ declare class DebugAwareEventStore implements EventStore {
  */
 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 };
+export { type ArchivedSessionSummary, type BreakpointConfig, type BreakpointType, CURRENT_VERSION, type ComputedState, DEFAULT_MAX_EVENTS, DebugAwareEventStore, type DebugCommand, DebugEventStore, DebugProtocolHandler, type DebugResponse, type DebugSession, DebugSessionRegistry, type EventFilter, type EventStoreFactory, FileSessionArchiveStorage, type ImportedSession, MarkingCache, type NetEventInfo, type NetStructure, type OutputStreamConsumer, PlaceAnalysis, type PlaceAnalysisInfo, type PlaceInfo, type ResponseSink, SNAPSHOT_INTERVAL, type SessionArchive, SessionArchiveReader, type SessionArchiveStorage, SessionArchiveWriter, type SessionCompletionListener, type SessionSummary, type Subscription, type SubscriptionMode, type TokenInfo, type TransitionInfo, buildNetStructure, compactTokenInfo, convertMarking, debugUiAssetPath, eventFilterAll, toEventInfo, tokenInfo };