libpetri 0.4.1 → 0.5.1

package/dist/debug/index.js

@@ -9,1021 +9,1075 @@ function eventFilterAll() {
   return { eventTypes: null, transitionNames: null, placeNames: null };
 }
 
-// src/debug/marking-cache.ts
-var SNAPSHOT_INTERVAL = 256;
-var MarkingCache = class {
-  _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, targetIndex) {
-    if (targetIndex <= 0) {
-      return computeState([]);
-    }
-    this.ensureCachedUpTo(events, targetIndex);
-    if (this._snapshots.length === 0) {
-      return computeState(events.slice(0, targetIndex));
-    }
-    const snapshotSlot = Math.min(Math.floor(targetIndex / SNAPSHOT_INTERVAL), this._snapshots.length) - 1;
-    if (snapshotSlot < 0) {
-      return computeState(events.slice(0, targetIndex));
-    }
-    const snapshotEventIndex = (snapshotSlot + 1) * SNAPSHOT_INTERVAL;
-    if (snapshotEventIndex === targetIndex) {
-      return this._snapshots[snapshotSlot];
-    }
-    return replayDelta(this._snapshots[snapshotSlot], events.slice(snapshotEventIndex, targetIndex));
+// src/debug/place-analysis.ts
+var PlaceAnalysis = class _PlaceAnalysis {
+  _data;
+  constructor(data) {
+    this._data = data;
   }
-  /** Invalidates the cache. */
-  invalidate() {
-    this._snapshots.length = 0;
+  get data() {
+    return this._data;
   }
-  /** Extends the snapshot cache to cover at least up to the given event index. */
-  ensureCachedUpTo(events, targetIndex) {
-    const neededSnapshots = Math.floor(targetIndex / SNAPSHOT_INTERVAL);
-    while (this._snapshots.length < neededSnapshots) {
-      const nextSnapshotIndex = (this._snapshots.length + 1) * SNAPSHOT_INTERVAL;
-      if (nextSnapshotIndex > events.length) break;
-      if (this._snapshots.length === 0) {
-        this._snapshots.push(computeState(events.slice(0, nextSnapshotIndex)));
-      } else {
-        const prevSnapshotIndex = this._snapshots.length * SNAPSHOT_INTERVAL;
-        const delta = events.slice(prevSnapshotIndex, nextSnapshotIndex);
-        this._snapshots.push(replayDelta(this._snapshots[this._snapshots.length - 1], delta));
+  isStart(placeName) {
+    const info = this._data.get(placeName);
+    return info != null && !info.hasIncoming;
+  }
+  isEnd(placeName) {
+    const info = this._data.get(placeName);
+    return info != null && !info.hasOutgoing;
+  }
+  /** Build place analysis from a PetriNet. */
+  static from(net) {
+    const data = /* @__PURE__ */ new Map();
+    function ensure(place) {
+      let info = data.get(place.name);
+      if (!info) {
+        info = { tokenType: "unknown", hasIncoming: false, hasOutgoing: false };
+        data.set(place.name, info);
+      }
+      return info;
+    }
+    for (const transition of net.transitions) {
+      for (const input of transition.inputSpecs) {
+        const info = ensure(input.place);
+        info.hasOutgoing = true;
+      }
+      if (transition.outputSpec) {
+        const outputPlaces = collectOutputPlaces(transition.outputSpec);
+        for (const place of outputPlaces) {
+          const info = ensure(place);
+          info.hasIncoming = true;
+        }
+      }
+      for (const inh of transition.inhibitors) {
+        ensure(inh.place);
+      }
+      for (const read of transition.reads) {
+        const info = ensure(read.place);
+        info.hasOutgoing = true;
+      }
+      for (const reset of transition.resets) {
+        ensure(reset.place);
       }
     }
+    return new _PlaceAnalysis(data);
   }
 };
-function replayDelta(base, delta) {
-  const marking = /* @__PURE__ */ new Map();
-  for (const [key, value] of base.marking) {
-    marking.set(key, [...value]);
+function collectOutputPlaces(out) {
+  const spec = out;
+  switch (spec.type) {
+    case "place":
+      return spec.place ? [spec.place] : [];
+    case "and":
+    case "xor":
+      return (spec.children ?? []).flatMap((c) => collectOutputPlaces(c));
+    case "timeout":
+      return spec.child ? collectOutputPlaces(spec.child) : [];
+    case "forward-input":
+      return spec.to ? [spec.to] : [];
+    default:
+      return [];
   }
-  const enabled = new Set(base.enabledTransitions);
-  const inFlight = new Set(base.inFlightTransitions);
-  applyEvents(marking, enabled, inFlight, delta);
-  return toImmutableState(marking, enabled, inFlight);
 }
 
-// src/debug/net-event-converter.ts
-function toEventInfo(event, compact = false) {
-  switch (event.type) {
-    case "execution-started":
-      return {
-        type: "ExecutionStarted",
-        timestamp: new Date(event.timestamp).toISOString(),
-        transitionName: null,
-        placeName: null,
-        details: { netName: event.netName, executionId: event.executionId }
-      };
-    case "execution-completed":
-      return {
-        type: "ExecutionCompleted",
-        timestamp: new Date(event.timestamp).toISOString(),
-        transitionName: null,
-        placeName: null,
-        details: {
-          netName: event.netName,
-          executionId: event.executionId,
-          totalDurationMs: event.totalDurationMs
-        }
-      };
-    case "transition-enabled":
-      return {
-        type: "TransitionEnabled",
-        timestamp: new Date(event.timestamp).toISOString(),
-        transitionName: event.transitionName,
-        placeName: null,
-        details: {}
-      };
-    case "transition-clock-restarted":
-      return {
-        type: "TransitionClockRestarted",
-        timestamp: new Date(event.timestamp).toISOString(),
-        transitionName: event.transitionName,
-        placeName: null,
-        details: {}
-      };
-    case "transition-started":
-      return {
-        type: "TransitionStarted",
-        timestamp: new Date(event.timestamp).toISOString(),
-        transitionName: event.transitionName,
-        placeName: null,
-        details: {
-          consumedTokens: event.consumedTokens.map((t) => compact ? compactTokenInfo(t) : tokenInfo(t))
-        }
-      };
-    case "transition-completed":
-      return {
-        type: "TransitionCompleted",
-        timestamp: new Date(event.timestamp).toISOString(),
-        transitionName: event.transitionName,
-        placeName: null,
-        details: {
-          producedTokens: event.producedTokens.map((t) => compact ? compactTokenInfo(t) : tokenInfo(t)),
-          durationMs: event.durationMs
-        }
-      };
-    case "transition-failed":
-      return {
-        type: "TransitionFailed",
-        timestamp: new Date(event.timestamp).toISOString(),
-        transitionName: event.transitionName,
-        placeName: null,
-        details: {
-          errorMessage: event.errorMessage,
-          exceptionType: event.exceptionType
-        }
-      };
-    case "transition-timed-out":
-      return {
-        type: "TransitionTimedOut",
-        timestamp: new Date(event.timestamp).toISOString(),
-        transitionName: event.transitionName,
-        placeName: null,
-        details: {
-          deadlineMs: event.deadlineMs,
-          actualDurationMs: event.actualDurationMs
-        }
-      };
-    case "action-timed-out":
-      return {
-        type: "ActionTimedOut",
-        timestamp: new Date(event.timestamp).toISOString(),
-        transitionName: event.transitionName,
-        placeName: null,
-        details: { timeoutMs: event.timeoutMs }
-      };
-    case "token-added":
-      return {
-        type: "TokenAdded",
-        timestamp: new Date(event.timestamp).toISOString(),
-        transitionName: null,
-        placeName: event.placeName,
-        details: {
-          token: compact ? compactTokenInfo(event.token) : tokenInfo(event.token)
-        }
-      };
-    case "token-removed":
-      return {
-        type: "TokenRemoved",
-        timestamp: new Date(event.timestamp).toISOString(),
-        transitionName: null,
-        placeName: event.placeName,
-        details: {
-          token: compact ? compactTokenInfo(event.token) : tokenInfo(event.token)
-        }
-      };
-    case "marking-snapshot":
-      return {
-        type: "MarkingSnapshot",
-        timestamp: new Date(event.timestamp).toISOString(),
-        transitionName: null,
-        placeName: null,
-        details: {
-          marking: convertMarking(event.marking, compact)
+// src/debug/debug-event-store.ts
+var DEFAULT_MAX_EVENTS = 1e4;
+var DebugEventStore = class {
+  _events = [];
+  _subscribers = /* @__PURE__ */ new Set();
+  _sessionId;
+  _maxEvents;
+  _eventCount = 0;
+  _evictedCount = 0;
+  constructor(sessionId, maxEvents = DEFAULT_MAX_EVENTS) {
+    if (maxEvents <= 0) throw new Error(`maxEvents must be positive, got: ${maxEvents}`);
+    this._sessionId = sessionId;
+    this._maxEvents = maxEvents;
+  }
+  get sessionId() {
+    return this._sessionId;
+  }
+  get maxEvents() {
+    return this._maxEvents;
+  }
+  /** Total events appended (including evicted). */
+  eventCount() {
+    return this._eventCount;
+  }
+  /** Number of events evicted from the store. */
+  evictedCount() {
+    return this._evictedCount;
+  }
+  // ======================== EventStore Implementation ========================
+  append(event) {
+    this._events.push(event);
+    this._eventCount++;
+    while (this._events.length > this._maxEvents) {
+      this._events.shift();
+      this._evictedCount++;
+    }
+    if (this._subscribers.size > 0) {
+      const subscribers = [...this._subscribers];
+      queueMicrotask(() => {
+        for (const sub of subscribers) {
+          try {
+            sub(event);
+          } catch (e) {
+            console.warn("Subscriber threw exception during event broadcast", e);
+          }
         }
-      };
-    case "log-message": {
-      const details = {
-        loggerName: event.logger,
-        level: event.level,
-        message: event.message
-      };
-      if (event.error != null) details["throwable"] = event.error;
-      if (event.errorMessage != null) details["throwableMessage"] = event.errorMessage;
-      return {
-        type: "LogMessage",
-        timestamp: new Date(event.timestamp).toISOString(),
-        transitionName: event.transitionName,
-        placeName: null,
-        details
-      };
+      });
     }
   }
-}
-function tokenInfo(token) {
-  const value = token.value;
-  const type = value != null ? typeof value === "object" ? value.constructor.name : typeof value : "null";
-  const fullValue = value != null ? String(value) : "null";
-  return {
-    id: null,
-    type,
-    value: fullValue,
-    timestamp: new Date(token.createdAt).toISOString()
-  };
-}
-function compactTokenInfo(token) {
-  const value = token.value;
-  const type = value != null ? typeof value === "object" ? value.constructor.name : typeof value : "null";
-  return {
-    id: null,
-    type,
-    value: null,
-    timestamp: new Date(token.createdAt).toISOString()
-  };
-}
-function convertMarking(marking, compact = false) {
-  const result = {};
-  const mapper = compact ? compactTokenInfo : tokenInfo;
-  for (const [name, tokens] of marking) {
-    result[name] = tokens.map(mapper);
+  events() {
+    return this._events;
+  }
+  isEnabled() {
+    return true;
+  }
+  size() {
+    return this._events.length;
   }
-  return result;
-}
-
-// src/debug/debug-protocol-handler.ts
-var BATCH_SIZE = 500;
-var DebugProtocolHandler = class {
-  _sessionRegistry;
-  _clients = /* @__PURE__ */ new Map();
-  constructor(sessionRegistry) {
-    this._sessionRegistry = sessionRegistry;
+  isEmpty() {
+    return this._events.length === 0;
   }
-  /** Registers a new client connection. */
-  clientConnected(clientId, sink) {
-    this._clients.set(clientId, new ClientState(sink));
+  // ======================== Live Tailing ========================
+  /** Subscribe to receive events as they occur. */
+  subscribe(listener) {
+    this._subscribers.add(listener);
+    return {
+      cancel: () => {
+        this._subscribers.delete(listener);
+      },
+      isActive: () => this._subscribers.has(listener)
+    };
   }
-  /** Cleans up when a client disconnects. */
-  clientDisconnected(clientId) {
-    const state = this._clients.get(clientId);
-    this._clients.delete(clientId);
-    if (state) state.subscriptions.cancelAll();
+  /** Number of active subscribers. */
+  subscriberCount() {
+    return this._subscribers.size;
   }
-  /** Handles a command from a connected client. */
-  handleCommand(clientId, command) {
-    const clientState = this._clients.get(clientId);
-    if (!clientState) return;
-    try {
-      switch (command.type) {
-        case "listSessions":
-          this.handleListSessions(clientState, command);
-          break;
-        case "subscribe":
-          this.handleSubscribe(clientState, command);
-          break;
-        case "unsubscribe":
-          this.handleUnsubscribe(clientState, command);
-          break;
-        case "seek":
-          this.handleSeek(clientState, command);
-          break;
-        case "playbackSpeed":
-          this.handlePlaybackSpeed(clientState, command);
-          break;
-        case "filter":
-          this.handleSetFilter(clientState, command);
-          break;
-        case "pause":
-          this.handlePause(clientState, command);
-          break;
-        case "resume":
-          this.handleResume(clientState, command);
-          break;
-        case "stepForward":
-          this.handleStepForward(clientState, command);
-          break;
-        case "stepBackward":
-          this.handleStepBackward(clientState, command);
-          break;
-        case "setBreakpoint":
-          this.handleSetBreakpoint(clientState, command);
-          break;
-        case "clearBreakpoint":
-          this.handleClearBreakpoint(clientState, command);
-          break;
-        case "listBreakpoints":
-          this.handleListBreakpoints(clientState, command);
-          break;
-      }
-    } catch (e) {
-      this.sendError(clientState, "COMMAND_ERROR", e instanceof Error ? e.message : String(e), null);
-    }
+  // ======================== Historical Replay ========================
+  /** Returns events starting from a specific index. */
+  eventsFrom(fromIndex) {
+    const adjustedSkip = Math.max(0, fromIndex - this._evictedCount);
+    if (adjustedSkip <= 0) return this._events;
+    return this._events.slice(adjustedSkip);
   }
-  // ======================== Command Handlers ========================
-  handleListSessions(client, cmd) {
-    const limit = cmd.limit ?? 50;
-    const sessions = cmd.activeOnly ? this._sessionRegistry.listActiveSessions(limit) : this._sessionRegistry.listSessions(limit);
-    const summaries = sessions.map((s) => ({
-      sessionId: s.sessionId,
-      netName: s.netName,
-      startTime: new Date(s.startTime).toISOString(),
-      active: s.active,
-      eventCount: s.eventStore.eventCount()
-    }));
-    this.send(client, { type: "sessionList", sessions: summaries });
+  /** Returns all events since the specified timestamp. */
+  eventsSince(from) {
+    return this._events.filter((e) => e.timestamp >= from);
   }
-  handleSubscribe(client, cmd) {
-    const debugSession = this._sessionRegistry.getSession(cmd.sessionId);
-    if (!debugSession) {
-      this.sendError(client, "SESSION_NOT_FOUND", `Session not found: ${cmd.sessionId}`, cmd.sessionId);
-      return;
-    }
-    const eventStore = debugSession.eventStore;
-    client.subscriptions.cancel(cmd.sessionId);
-    const events = eventStore.events();
-    const computed = computeState(events);
-    const structure = buildNetStructure(debugSession);
-    this.send(client, {
-      type: "subscribed",
-      sessionId: cmd.sessionId,
-      netName: debugSession.netName,
-      dotDiagram: debugSession.dotDiagram,
-      structure,
-      currentMarking: mapToRecord(computed.marking),
-      enabledTransitions: computed.enabledTransitions,
-      inFlightTransitions: computed.inFlightTransitions,
-      eventCount: eventStore.eventCount(),
-      mode: cmd.mode
+  /** Returns events within a time range. */
+  eventsBetween(from, to) {
+    return this._events.filter((e) => e.timestamp >= from && e.timestamp < to);
+  }
+  /**
+   * Returns an iterator over all retained events.
+   * Useful for archive writers that need zero-copy traversal.
+   */
+  [Symbol.iterator]() {
+    return this._events[Symbol.iterator]();
+  }
+  // ======================== Lifecycle ========================
+  /** Close the store (no-op in JS, but matches Java interface). */
+  close() {
+    this._subscribers.clear();
+  }
+};
+
+// src/debug/debug-session-registry.ts
+function buildNetStructure(session) {
+  if (session.importedStructure) {
+    return session.importedStructure;
+  }
+  const places = session.places;
+  if (!places) {
+    return { places: [], transitions: [] };
+  }
+  const placeInfos = [];
+  for (const [name, info] of places.data) {
+    placeInfos.push({
+      name,
+      graphId: `p_${sanitize(name)}`,
+      tokenType: info.tokenType,
+      isStart: !info.hasIncoming,
+      isEnd: !info.hasOutgoing,
+      isEnvironment: false
     });
-    const fromIndex = cmd.fromIndex ?? 0;
-    if (cmd.mode === "live") {
-      this.subscribeLive(client, cmd.sessionId, debugSession, fromIndex);
-    } else {
-      this.subscribeReplay(client, cmd.sessionId, debugSession, fromIndex);
-    }
   }
-  subscribeLive(client, sessionId, debugSession, fromIndex) {
-    const eventStore = debugSession.eventStore;
-    let eventIndex = fromIndex;
-    const historicalEvents = eventStore.eventsFrom(fromIndex);
-    if (historicalEvents.length > 0) {
-      const filtered = historicalEvents.filter((e) => client.subscriptions.matchesFilter(sessionId, e)).map((e) => toEventInfo(e));
-      this.sendInBatches(client, sessionId, fromIndex, filtered);
-      eventIndex = fromIndex + historicalEvents.length;
-    }
-    const subscription = eventStore.subscribe((event) => {
-      if (!client.subscriptions.isPaused(sessionId) && client.subscriptions.matchesFilter(sessionId, event)) {
-        const eventInfo = toEventInfo(event);
-        const idx = eventIndex++;
-        const hitBreakpoint = client.subscriptions.checkBreakpoints(sessionId, event);
-        if (hitBreakpoint) {
-          client.subscriptions.setPaused(sessionId, true);
-          this.send(client, {
-            type: "breakpointHit",
-            sessionId,
-            breakpointId: hitBreakpoint.id,
-            event: eventInfo,
-            eventIndex: idx
-          });
-        }
-        this.send(client, { type: "event", sessionId, index: idx, event: eventInfo });
-      }
+  const transitionInfos = [];
+  for (const t of session.transitions) {
+    transitionInfos.push({
+      name: t.name,
+      graphId: `t_${sanitize(t.name)}`
     });
-    client.subscriptions.addSubscription(sessionId, subscription, eventIndex);
   }
-  subscribeReplay(client, sessionId, debugSession, fromIndex) {
-    const eventStore = debugSession.eventStore;
-    const events = eventStore.eventsFrom(fromIndex);
-    const converted = events.map((e) => toEventInfo(e));
-    this.sendInBatches(client, sessionId, fromIndex, converted);
-    const eventIndex = fromIndex + events.length;
-    client.subscriptions.addSubscription(sessionId, null, eventIndex);
-    client.subscriptions.setPaused(sessionId, true);
+  return { places: placeInfos, transitions: transitionInfos };
+}
+var DebugSessionRegistry = class {
+  _sessions = /* @__PURE__ */ new Map();
+  _maxSessions;
+  _eventStoreFactory;
+  _completionListeners;
+  constructor(maxSessions = 50, eventStoreFactory, completionListeners) {
+    this._maxSessions = maxSessions;
+    this._eventStoreFactory = eventStoreFactory ?? ((id) => new DebugEventStore(id));
+    this._completionListeners = completionListeners ? [...completionListeners] : [];
   }
-  handleUnsubscribe(client, cmd) {
-    client.subscriptions.cancel(cmd.sessionId);
-    this.send(client, { type: "unsubscribed", sessionId: cmd.sessionId });
+  /**
+   * Registers a new debug session for the given Petri net.
+   * Generates DOT diagram and extracts net structure.
+   */
+  register(sessionId, net) {
+    const dotDiagram = dotExport(net);
+    const places = PlaceAnalysis.from(net);
+    const eventStore = this._eventStoreFactory(sessionId);
+    const session = {
+      sessionId,
+      netName: net.name,
+      dotDiagram,
+      places,
+      transitions: net.transitions,
+      eventStore,
+      startTime: Date.now(),
+      active: true,
+      importedStructure: null
+    };
+    this.evictIfNecessary();
+    this._sessions.set(sessionId, session);
+    return session;
   }
-  handleSeek(client, cmd) {
-    const debugSession = this._sessionRegistry.getSession(cmd.sessionId);
-    if (!debugSession) {
-      this.sendError(client, "SESSION_NOT_FOUND", "Session not found", cmd.sessionId);
-      return;
+  /**
+   * Marks a session as completed (no longer active) and notifies completion listeners.
+   */
+  complete(sessionId) {
+    const session = this._sessions.get(sessionId);
+    if (session) {
+      const completed = { ...session, active: false };
+      this._sessions.set(sessionId, completed);
+      this.notifyCompletionListeners(completed);
     }
-    const events = debugSession.eventStore.events();
-    const targetTs = new Date(cmd.timestamp).getTime();
-    let targetIndex = 0;
-    for (let i = 0; i < events.length; i++) {
-      if (events[i].timestamp >= targetTs) {
-        targetIndex = i;
-        break;
-      }
-      targetIndex = i + 1;
+  }
+  /** Removes a session from the registry. */
+  remove(sessionId) {
+    const removed = this._sessions.get(sessionId);
+    if (removed) {
+      this._sessions.delete(sessionId);
+      removed.eventStore.close();
     }
-    client.subscriptions.setEventIndex(cmd.sessionId, targetIndex);
-    const computed = client.subscriptions.computeStateAt(cmd.sessionId, events, targetIndex);
-    this.send(client, {
-      type: "markingSnapshot",
-      sessionId: cmd.sessionId,
-      marking: mapToRecord(computed.marking),
-      enabledTransitions: computed.enabledTransitions,
-      inFlightTransitions: computed.inFlightTransitions
-    });
+    return removed;
+  }
+  /** Returns a session by ID. */
+  getSession(sessionId) {
+    return this._sessions.get(sessionId);
+  }
+  /** Lists sessions, ordered by start time (most recent first). */
+  listSessions(limit) {
+    return [...this._sessions.values()].sort((a, b) => b.startTime - a.startTime).slice(0, limit);
   }
-  handlePlaybackSpeed(client, cmd) {
-    client.subscriptions.setSpeed(cmd.sessionId, cmd.speed);
-    this.send(client, {
-      type: "playbackStateChanged",
-      sessionId: cmd.sessionId,
-      paused: client.subscriptions.isPaused(cmd.sessionId),
-      speed: cmd.speed,
-      currentIndex: client.subscriptions.getEventIndex(cmd.sessionId)
-    });
+  /** Lists only active sessions. */
+  listActiveSessions(limit) {
+    return [...this._sessions.values()].filter((s) => s.active).sort((a, b) => b.startTime - a.startTime).slice(0, limit);
   }
-  handleSetFilter(client, cmd) {
-    client.subscriptions.setFilter(cmd.sessionId, cmd.filter);
-    this.send(client, { type: "filterApplied", sessionId: cmd.sessionId, filter: cmd.filter });
+  /** Total number of sessions. */
+  get size() {
+    return this._sessions.size;
   }
-  handlePause(client, cmd) {
-    client.subscriptions.setPaused(cmd.sessionId, true);
-    this.send(client, {
-      type: "playbackStateChanged",
-      sessionId: cmd.sessionId,
-      paused: true,
-      speed: client.subscriptions.getSpeed(cmd.sessionId),
-      currentIndex: client.subscriptions.getEventIndex(cmd.sessionId)
-    });
+  /**
+   * Registers an imported (archived) session as an inactive, read-only session.
+   */
+  registerImported(sessionId, netName, dotDiagram, structure, eventStore, startTime) {
+    this.evictIfNecessary();
+    const session = {
+      sessionId,
+      netName,
+      dotDiagram,
+      places: null,
+      transitions: /* @__PURE__ */ new Set(),
+      eventStore,
+      startTime,
+      active: false,
+      importedStructure: structure
+    };
+    this._sessions.set(sessionId, session);
+    return session;
   }
-  handleResume(client, cmd) {
-    client.subscriptions.setPaused(cmd.sessionId, false);
-    this.send(client, {
-      type: "playbackStateChanged",
-      sessionId: cmd.sessionId,
-      paused: false,
-      speed: client.subscriptions.getSpeed(cmd.sessionId),
-      currentIndex: client.subscriptions.getEventIndex(cmd.sessionId)
+  /** Notifies all completion listeners. Exceptions are caught and logged. */
+  notifyCompletionListeners(session) {
+    for (const listener of this._completionListeners) {
+      try {
+        listener(session);
+      } catch (e) {
+        console.warn(`Session completion listener failed for ${session.sessionId}`, e);
+      }
+    }
+  }
+  /** Evicts oldest inactive sessions if at capacity. */
+  evictIfNecessary() {
+    if (this._sessions.size < this._maxSessions) return;
+    const candidates = [...this._sessions.values()].sort((a, b) => {
+      if (a.active !== b.active) return a.active ? 1 : -1;
+      return a.startTime - b.startTime;
     });
+    for (const candidate of candidates) {
+      if (this._sessions.size < this._maxSessions) break;
+      const evicted = this._sessions.get(candidate.sessionId);
+      if (evicted) {
+        this._sessions.delete(candidate.sessionId);
+        evicted.eventStore.close();
+      }
+    }
   }
-  handleStepForward(client, cmd) {
-    const debugSession = this._sessionRegistry.getSession(cmd.sessionId);
-    if (!debugSession) {
-      this.sendError(client, "SESSION_NOT_FOUND", `Session not found: ${cmd.sessionId}`, cmd.sessionId);
-      return;
+};
+
+// src/debug/marking-cache.ts
+var SNAPSHOT_INTERVAL = 256;
+var MarkingCache = class {
+  _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, targetIndex) {
+    if (targetIndex <= 0) {
+      return computeState([]);
     }
-    const events = debugSession.eventStore.events();
-    const currentIndex = client.subscriptions.getEventIndex(cmd.sessionId);
-    if (currentIndex < events.length) {
-      const event = events[currentIndex];
-      this.send(client, {
-        type: "event",
-        sessionId: cmd.sessionId,
-        index: currentIndex,
-        event: toEventInfo(event)
-      });
-      client.subscriptions.setEventIndex(cmd.sessionId, currentIndex + 1);
+    this.ensureCachedUpTo(events, targetIndex);
+    if (this._snapshots.length === 0) {
+      return computeState(events.slice(0, targetIndex));
     }
-  }
-  handleStepBackward(client, cmd) {
-    const debugSession = this._sessionRegistry.getSession(cmd.sessionId);
-    if (!debugSession) {
-      this.sendError(client, "SESSION_NOT_FOUND", `Session not found: ${cmd.sessionId}`, cmd.sessionId);
-      return;
+    const snapshotSlot = Math.min(Math.floor(targetIndex / SNAPSHOT_INTERVAL), this._snapshots.length) - 1;
+    if (snapshotSlot < 0) {
+      return computeState(events.slice(0, targetIndex));
     }
-    let currentIndex = client.subscriptions.getEventIndex(cmd.sessionId);
-    if (currentIndex > 0) {
-      currentIndex--;
-      client.subscriptions.setEventIndex(cmd.sessionId, currentIndex);
-      const events = debugSession.eventStore.events();
-      const computed = client.subscriptions.computeStateAt(cmd.sessionId, events, currentIndex);
-      this.send(client, {
-        type: "markingSnapshot",
-        sessionId: cmd.sessionId,
-        marking: mapToRecord(computed.marking),
-        enabledTransitions: computed.enabledTransitions,
-        inFlightTransitions: computed.inFlightTransitions
-      });
+    const snapshotEventIndex = (snapshotSlot + 1) * SNAPSHOT_INTERVAL;
+    if (snapshotEventIndex === targetIndex) {
+      return this._snapshots[snapshotSlot];
     }
+    return replayDelta(this._snapshots[snapshotSlot], events.slice(snapshotEventIndex, targetIndex));
   }
-  handleSetBreakpoint(client, cmd) {
-    client.subscriptions.addBreakpoint(cmd.sessionId, cmd.breakpoint);
-    this.send(client, { type: "breakpointSet", sessionId: cmd.sessionId, breakpoint: cmd.breakpoint });
-  }
-  handleClearBreakpoint(client, cmd) {
-    client.subscriptions.removeBreakpoint(cmd.sessionId, cmd.breakpointId);
-    this.send(client, { type: "breakpointCleared", sessionId: cmd.sessionId, breakpointId: cmd.breakpointId });
-  }
-  handleListBreakpoints(client, cmd) {
-    const breakpoints = client.subscriptions.getBreakpoints(cmd.sessionId);
-    this.send(client, { type: "breakpointList", sessionId: cmd.sessionId, breakpoints });
-  }
-  // ======================== Helper Methods ========================
-  send(client, response) {
-    client.sink(response);
-  }
-  sendError(client, code, message, sessionId) {
-    this.send(client, { type: "error", code, message, sessionId });
+  /** Invalidates the cache. */
+  invalidate() {
+    this._snapshots.length = 0;
   }
-  sendInBatches(client, sessionId, startIndex, events) {
-    if (events.length === 0) {
-      this.send(client, { type: "eventBatch", sessionId, startIndex, events: [], hasMore: false });
-      return;
-    }
-    for (let i = 0; i < events.length; i += BATCH_SIZE) {
-      const end = Math.min(i + BATCH_SIZE, events.length);
-      const chunk = events.slice(i, end);
-      const hasMore = end < events.length;
-      this.send(client, { type: "eventBatch", sessionId, startIndex: startIndex + i, events: chunk, hasMore });
+  /** Extends the snapshot cache to cover at least up to the given event index. */
+  ensureCachedUpTo(events, targetIndex) {
+    const neededSnapshots = Math.floor(targetIndex / SNAPSHOT_INTERVAL);
+    while (this._snapshots.length < neededSnapshots) {
+      const nextSnapshotIndex = (this._snapshots.length + 1) * SNAPSHOT_INTERVAL;
+      if (nextSnapshotIndex > events.length) break;
+      if (this._snapshots.length === 0) {
+        this._snapshots.push(computeState(events.slice(0, nextSnapshotIndex)));
+      } else {
+        const prevSnapshotIndex = this._snapshots.length * SNAPSHOT_INTERVAL;
+        const delta = events.slice(prevSnapshotIndex, nextSnapshotIndex);
+        this._snapshots.push(replayDelta(this._snapshots[this._snapshots.length - 1], delta));
+      }
     }
   }
 };
-function computeState(events) {
+function replayDelta(base, delta) {
   const marking = /* @__PURE__ */ new Map();
-  const enabled = /* @__PURE__ */ new Set();
-  const inFlight = /* @__PURE__ */ new Set();
-  applyEvents(marking, enabled, inFlight, events);
+  for (const [key, value] of base.marking) {
+    marking.set(key, [...value]);
+  }
+  const enabled = new Set(base.enabledTransitions);
+  const inFlight = new Set(base.inFlightTransitions);
+  applyEvents(marking, enabled, inFlight, delta);
   return toImmutableState(marking, enabled, inFlight);
 }
-function applyEvents(marking, enabled, inFlight, events) {
-  for (const event of events) {
-    switch (event.type) {
-      case "token-added": {
-        let tokens = marking.get(event.placeName);
-        if (!tokens) {
-          tokens = [];
-          marking.set(event.placeName, tokens);
+
+// src/debug/net-event-converter.ts
+function toEventInfo(event, compact = false) {
+  switch (event.type) {
+    case "execution-started":
+      return {
+        type: "ExecutionStarted",
+        timestamp: new Date(event.timestamp).toISOString(),
+        transitionName: null,
+        placeName: null,
+        details: { netName: event.netName, executionId: event.executionId }
+      };
+    case "execution-completed":
+      return {
+        type: "ExecutionCompleted",
+        timestamp: new Date(event.timestamp).toISOString(),
+        transitionName: null,
+        placeName: null,
+        details: {
+          netName: event.netName,
+          executionId: event.executionId,
+          totalDurationMs: event.totalDurationMs
+        }
+      };
+    case "transition-enabled":
+      return {
+        type: "TransitionEnabled",
+        timestamp: new Date(event.timestamp).toISOString(),
+        transitionName: event.transitionName,
+        placeName: null,
+        details: {}
+      };
+    case "transition-clock-restarted":
+      return {
+        type: "TransitionClockRestarted",
+        timestamp: new Date(event.timestamp).toISOString(),
+        transitionName: event.transitionName,
+        placeName: null,
+        details: {}
+      };
+    case "transition-started":
+      return {
+        type: "TransitionStarted",
+        timestamp: new Date(event.timestamp).toISOString(),
+        transitionName: event.transitionName,
+        placeName: null,
+        details: {
+          consumedTokens: event.consumedTokens.map((t) => compact ? compactTokenInfo(t) : tokenInfo(t))
+        }
+      };
+    case "transition-completed":
+      return {
+        type: "TransitionCompleted",
+        timestamp: new Date(event.timestamp).toISOString(),
+        transitionName: event.transitionName,
+        placeName: null,
+        details: {
+          producedTokens: event.producedTokens.map((t) => compact ? compactTokenInfo(t) : tokenInfo(t)),
+          durationMs: event.durationMs
+        }
+      };
+    case "transition-failed":
+      return {
+        type: "TransitionFailed",
+        timestamp: new Date(event.timestamp).toISOString(),
+        transitionName: event.transitionName,
+        placeName: null,
+        details: {
+          errorMessage: event.errorMessage,
+          exceptionType: event.exceptionType
         }
-        tokens.push(tokenInfo(event.token));
-        break;
-      }
-      case "token-removed": {
-        const tokens = marking.get(event.placeName);
-        if (tokens && tokens.length > 0) tokens.shift();
-        break;
-      }
-      case "marking-snapshot": {
-        marking.clear();
-        const converted = convertMarking(event.marking);
-        for (const [key, value] of Object.entries(converted)) {
-          marking.set(key, [...value]);
+      };
+    case "transition-timed-out":
+      return {
+        type: "TransitionTimedOut",
+        timestamp: new Date(event.timestamp).toISOString(),
+        transitionName: event.transitionName,
+        placeName: null,
+        details: {
+          deadlineMs: event.deadlineMs,
+          actualDurationMs: event.actualDurationMs
         }
-        break;
-      }
-      case "transition-enabled":
-        enabled.add(event.transitionName);
-        break;
-      case "transition-started":
-        enabled.delete(event.transitionName);
-        inFlight.add(event.transitionName);
-        break;
-      case "transition-completed":
-        inFlight.delete(event.transitionName);
-        break;
-      case "transition-failed":
-        inFlight.delete(event.transitionName);
-        break;
-      case "transition-timed-out":
-        inFlight.delete(event.transitionName);
-        break;
-      case "action-timed-out":
-        inFlight.delete(event.transitionName);
-        break;
-      default:
-        break;
+      };
+    case "action-timed-out":
+      return {
+        type: "ActionTimedOut",
+        timestamp: new Date(event.timestamp).toISOString(),
+        transitionName: event.transitionName,
+        placeName: null,
+        details: { timeoutMs: event.timeoutMs }
+      };
+    case "token-added":
+      return {
+        type: "TokenAdded",
+        timestamp: new Date(event.timestamp).toISOString(),
+        transitionName: null,
+        placeName: event.placeName,
+        details: {
+          token: compact ? compactTokenInfo(event.token) : tokenInfo(event.token)
+        }
+      };
+    case "token-removed":
+      return {
+        type: "TokenRemoved",
+        timestamp: new Date(event.timestamp).toISOString(),
+        transitionName: null,
+        placeName: event.placeName,
+        details: {
+          token: compact ? compactTokenInfo(event.token) : tokenInfo(event.token)
+        }
+      };
+    case "marking-snapshot":
+      return {
+        type: "MarkingSnapshot",
+        timestamp: new Date(event.timestamp).toISOString(),
+        transitionName: null,
+        placeName: null,
+        details: {
+          marking: convertMarking(event.marking, compact)
+        }
+      };
+    case "log-message": {
+      const details = {
+        loggerName: event.logger,
+        level: event.level,
+        message: event.message
+      };
+      if (event.error != null) details["throwable"] = event.error;
+      if (event.errorMessage != null) details["throwableMessage"] = event.errorMessage;
+      return {
+        type: "LogMessage",
+        timestamp: new Date(event.timestamp).toISOString(),
+        transitionName: event.transitionName,
+        placeName: null,
+        details
+      };
     }
   }
 }
-function toImmutableState(marking, enabled, inFlight) {
-  const resultMarking = /* @__PURE__ */ new Map();
-  for (const [key, value] of marking) {
-    resultMarking.set(key, [...value]);
-  }
+function tokenInfo(token) {
+  const value = token.value;
+  const type = value != null ? typeof value === "object" ? value.constructor.name : typeof value : "null";
+  const fullValue = value != null ? String(value) : "null";
   return {
-    marking: resultMarking,
-    enabledTransitions: [...enabled],
-    inFlightTransitions: [...inFlight]
+    id: null,
+    type,
+    value: fullValue,
+    timestamp: new Date(token.createdAt).toISOString()
   };
 }
-function buildNetStructure(debugSession) {
-  const places = debugSession.places;
-  const transitions = debugSession.transitions;
-  const placeInfos = [...places.data.entries()].map(([name, info]) => ({
-    name,
-    graphId: `p_${sanitize(name)}`,
-    tokenType: info.tokenType,
-    isStart: !info.hasIncoming,
-    isEnd: !info.hasOutgoing,
-    isEnvironment: false
-  }));
-  const transitionInfos = [...transitions].map((t) => ({
-    name: t.name,
-    graphId: `t_${sanitize(t.name)}`
-  }));
-  return { places: placeInfos, transitions: transitionInfos };
+function compactTokenInfo(token) {
+  const value = token.value;
+  const type = value != null ? typeof value === "object" ? value.constructor.name : typeof value : "null";
+  return {
+    id: null,
+    type,
+    value: null,
+    timestamp: new Date(token.createdAt).toISOString()
+  };
 }
-function mapToRecord(map) {
+function convertMarking(marking, compact = false) {
   const result = {};
-  for (const [key, value] of map) {
-    result[key] = value;
+  const mapper = compact ? compactTokenInfo : tokenInfo;
+  for (const [name, tokens] of marking) {
+    result[name] = tokens.map(mapper);
   }
   return result;
 }
-var ClientState = class {
-  sink;
-  subscriptions = new SubscriptionState();
-  constructor(sink) {
-    this.sink = sink;
-  }
-};
-var SubscriptionState = class {
-  _sessionSubs = /* @__PURE__ */ new Map();
-  addSubscription(sessionId, subscription, eventIndex) {
-    this._sessionSubs.set(sessionId, {
-      subscription,
-      eventIndex,
-      markingCache: new MarkingCache(),
-      breakpoints: /* @__PURE__ */ new Map(),
-      paused: false,
-      speed: 1,
-      filter: null
-    });
-  }
-  cancel(sessionId) {
-    const sub = this._sessionSubs.get(sessionId);
-    if (sub?.subscription) sub.subscription.cancel();
-    this._sessionSubs.delete(sessionId);
-  }
-  cancelAll() {
-    for (const sub of this._sessionSubs.values()) {
-      if (sub.subscription) sub.subscription.cancel();
-    }
-    this._sessionSubs.clear();
-  }
-  isPaused(sessionId) {
-    return this._sessionSubs.get(sessionId)?.paused ?? false;
-  }
-  setPaused(sessionId, paused) {
-    const sub = this._sessionSubs.get(sessionId);
-    if (sub) sub.paused = paused;
-  }
-  getSpeed(sessionId) {
-    return this._sessionSubs.get(sessionId)?.speed ?? 1;
-  }
-  setSpeed(sessionId, speed) {
-    const sub = this._sessionSubs.get(sessionId);
-    if (sub) sub.speed = speed;
-  }
-  getEventIndex(sessionId) {
-    return this._sessionSubs.get(sessionId)?.eventIndex ?? 0;
-  }
-  setEventIndex(sessionId, index) {
-    const sub = this._sessionSubs.get(sessionId);
-    if (sub) sub.eventIndex = index;
+
+// src/debug/debug-protocol-handler.ts
+var BATCH_SIZE = 500;
+var DebugProtocolHandler = class {
+  _sessionRegistry;
+  _clients = /* @__PURE__ */ new Map();
+  constructor(sessionRegistry) {
+    this._sessionRegistry = sessionRegistry;
   }
-  computeStateAt(sessionId, events, targetIndex) {
-    const sub = this._sessionSubs.get(sessionId);
-    if (sub) return sub.markingCache.computeAt(events, targetIndex);
-    return computeState(events.slice(0, targetIndex));
+  /** Registers a new client connection. */
+  clientConnected(clientId, sink) {
+    this._clients.set(clientId, new ClientState(sink));
   }
-  setFilter(sessionId, filter) {
-    const sub = this._sessionSubs.get(sessionId);
-    if (sub) sub.filter = filter;
+  /** Cleans up when a client disconnects. */
+  clientDisconnected(clientId) {
+    const state = this._clients.get(clientId);
+    this._clients.delete(clientId);
+    if (state) state.subscriptions.cancelAll();
   }
-  matchesFilter(sessionId, event) {
-    const sub = this._sessionSubs.get(sessionId);
-    if (!sub?.filter) return true;
-    const filter = sub.filter;
-    if (filter.eventTypes && filter.eventTypes.length > 0) {
-      const eventType = eventTypeToName(event);
-      if (!filter.eventTypes.includes(eventType)) return false;
-    }
-    if (filter.transitionNames && filter.transitionNames.length > 0) {
-      const name = extractTransitionName(event);
-      if (!name || !filter.transitionNames.includes(name)) return false;
-    }
-    if (filter.placeNames && filter.placeNames.length > 0) {
-      const name = extractPlaceName(event);
-      if (!name || !filter.placeNames.includes(name)) return false;
+  /** Handles a command from a connected client. */
+  handleCommand(clientId, command) {
+    const clientState = this._clients.get(clientId);
+    if (!clientState) return;
+    try {
+      switch (command.type) {
+        case "listSessions":
+          this.handleListSessions(clientState, command);
+          break;
+        case "subscribe":
+          this.handleSubscribe(clientState, command);
+          break;
+        case "unsubscribe":
+          this.handleUnsubscribe(clientState, command);
+          break;
+        case "seek":
+          this.handleSeek(clientState, command);
+          break;
+        case "playbackSpeed":
+          this.handlePlaybackSpeed(clientState, command);
+          break;
+        case "filter":
+          this.handleSetFilter(clientState, command);
+          break;
+        case "pause":
+          this.handlePause(clientState, command);
+          break;
+        case "resume":
+          this.handleResume(clientState, command);
+          break;
+        case "stepForward":
+          this.handleStepForward(clientState, command);
+          break;
+        case "stepBackward":
+          this.handleStepBackward(clientState, command);
+          break;
+        case "setBreakpoint":
+          this.handleSetBreakpoint(clientState, command);
+          break;
+        case "clearBreakpoint":
+          this.handleClearBreakpoint(clientState, command);
+          break;
+        case "listBreakpoints":
+          this.handleListBreakpoints(clientState, command);
+          break;
+      }
+    } catch (e) {
+      this.sendError(clientState, "COMMAND_ERROR", e instanceof Error ? e.message : String(e), null);
     }
-    return true;
-  }
-  addBreakpoint(sessionId, breakpoint) {
-    const sub = this._sessionSubs.get(sessionId);
-    if (sub) sub.breakpoints.set(breakpoint.id, breakpoint);
   }
-  removeBreakpoint(sessionId, breakpointId) {
-    const sub = this._sessionSubs.get(sessionId);
-    if (sub) sub.breakpoints.delete(breakpointId);
+  // ======================== Command Handlers ========================
+  handleListSessions(client, cmd) {
+    const limit = cmd.limit ?? 50;
+    const sessions = cmd.activeOnly ? this._sessionRegistry.listActiveSessions(limit) : this._sessionRegistry.listSessions(limit);
+    const summaries = sessions.map((s) => ({
+      sessionId: s.sessionId,
+      netName: s.netName,
+      startTime: new Date(s.startTime).toISOString(),
+      active: s.active,
+      eventCount: s.eventStore.eventCount()
+    }));
+    this.send(client, { type: "sessionList", sessions: summaries });
   }
-  getBreakpoints(sessionId) {
-    const sub = this._sessionSubs.get(sessionId);
-    return sub ? [...sub.breakpoints.values()] : [];
+  handleSubscribe(client, cmd) {
+    const debugSession = this._sessionRegistry.getSession(cmd.sessionId);
+    if (!debugSession) {
+      this.sendError(client, "SESSION_NOT_FOUND", `Session not found: ${cmd.sessionId}`, cmd.sessionId);
+      return;
+    }
+    const eventStore = debugSession.eventStore;
+    client.subscriptions.cancel(cmd.sessionId);
+    const events = eventStore.events();
+    const computed = computeState(events);
+    const structure = buildNetStructure(debugSession);
+    this.send(client, {
+      type: "subscribed",
+      sessionId: cmd.sessionId,
+      netName: debugSession.netName,
+      dotDiagram: debugSession.dotDiagram,
+      structure,
+      currentMarking: mapToRecord(computed.marking),
+      enabledTransitions: computed.enabledTransitions,
+      inFlightTransitions: computed.inFlightTransitions,
+      eventCount: eventStore.eventCount(),
+      mode: cmd.mode
+    });
+    const fromIndex = cmd.fromIndex ?? 0;
+    if (cmd.mode === "live") {
+      this.subscribeLive(client, cmd.sessionId, debugSession, fromIndex);
+    } else {
+      this.subscribeReplay(client, cmd.sessionId, debugSession, fromIndex);
+    }
   }
-  checkBreakpoints(sessionId, event) {
-    const sub = this._sessionSubs.get(sessionId);
-    if (!sub || sub.breakpoints.size === 0) return null;
-    for (const bp of sub.breakpoints.values()) {
-      if (!bp.enabled) continue;
-      if (matchesBreakpoint(bp, event)) return bp;
+  subscribeLive(client, sessionId, debugSession, fromIndex) {
+    const eventStore = debugSession.eventStore;
+    let eventIndex = fromIndex;
+    const historicalEvents = eventStore.eventsFrom(fromIndex);
+    if (historicalEvents.length > 0) {
+      const filtered = historicalEvents.filter((e) => client.subscriptions.matchesFilter(sessionId, e)).map((e) => toEventInfo(e));
+      this.sendInBatches(client, sessionId, fromIndex, filtered);
+      eventIndex = fromIndex + historicalEvents.length;
     }
-    return null;
+    const subscription = eventStore.subscribe((event) => {
+      if (!client.subscriptions.isPaused(sessionId) && client.subscriptions.matchesFilter(sessionId, event)) {
+        const eventInfo = toEventInfo(event);
+        const idx = eventIndex++;
+        const hitBreakpoint = client.subscriptions.checkBreakpoints(sessionId, event);
+        if (hitBreakpoint) {
+          client.subscriptions.setPaused(sessionId, true);
+          this.send(client, {
+            type: "breakpointHit",
+            sessionId,
+            breakpointId: hitBreakpoint.id,
+            event: eventInfo,
+            eventIndex: idx
+          });
+        }
+        this.send(client, { type: "event", sessionId, index: idx, event: eventInfo });
+      }
+    });
+    client.subscriptions.addSubscription(sessionId, subscription, eventIndex);
   }
-};
-function eventTypeToName(event) {
-  const map = {
-    "execution-started": "ExecutionStarted",
-    "execution-completed": "ExecutionCompleted",
-    "transition-enabled": "TransitionEnabled",
-    "transition-clock-restarted": "TransitionClockRestarted",
-    "transition-started": "TransitionStarted",
-    "transition-completed": "TransitionCompleted",
-    "transition-failed": "TransitionFailed",
-    "transition-timed-out": "TransitionTimedOut",
-    "action-timed-out": "ActionTimedOut",
-    "token-added": "TokenAdded",
-    "token-removed": "TokenRemoved",
-    "marking-snapshot": "MarkingSnapshot",
-    "log-message": "LogMessage"
-  };
-  return map[event.type] ?? event.type;
-}
-function extractTransitionName(event) {
-  switch (event.type) {
-    case "transition-enabled":
-    case "transition-clock-restarted":
-    case "transition-started":
-    case "transition-completed":
-    case "transition-failed":
-    case "transition-timed-out":
-    case "action-timed-out":
-    case "log-message":
-      return event.transitionName;
-    default:
-      return null;
+  subscribeReplay(client, sessionId, debugSession, fromIndex) {
+    const eventStore = debugSession.eventStore;
+    const events = eventStore.eventsFrom(fromIndex);
+    const converted = events.map((e) => toEventInfo(e));
+    this.sendInBatches(client, sessionId, fromIndex, converted);
+    const eventIndex = fromIndex + events.length;
+    client.subscriptions.addSubscription(sessionId, null, eventIndex);
+    client.subscriptions.setPaused(sessionId, true);
   }
-}
-function extractPlaceName(event) {
-  switch (event.type) {
-    case "token-added":
-    case "token-removed":
-      return event.placeName;
-    default:
-      return null;
+  handleUnsubscribe(client, cmd) {
+    client.subscriptions.cancel(cmd.sessionId);
+    this.send(client, { type: "unsubscribed", sessionId: cmd.sessionId });
   }
-}
-function matchesBreakpoint(bp, event) {
-  switch (bp.type) {
-    case "TRANSITION_ENABLED":
-      return event.type === "transition-enabled" && (bp.target === null || bp.target === event.transitionName);
-    case "TRANSITION_START":
-      return event.type === "transition-started" && (bp.target === null || bp.target === event.transitionName);
-    case "TRANSITION_COMPLETE":
-      return event.type === "transition-completed" && (bp.target === null || bp.target === event.transitionName);
-    case "TRANSITION_FAIL":
-      return event.type === "transition-failed" && (bp.target === null || bp.target === event.transitionName);
-    case "TOKEN_ADDED":
-      return event.type === "token-added" && (bp.target === null || bp.target === event.placeName);
-    case "TOKEN_REMOVED":
-      return event.type === "token-removed" && (bp.target === null || bp.target === event.placeName);
-    default:
-      return false;
+  handleSeek(client, cmd) {
+    const debugSession = this._sessionRegistry.getSession(cmd.sessionId);
+    if (!debugSession) {
+      this.sendError(client, "SESSION_NOT_FOUND", "Session not found", cmd.sessionId);
+      return;
+    }
+    const events = debugSession.eventStore.events();
+    const targetTs = new Date(cmd.timestamp).getTime();
+    let targetIndex = 0;
+    for (let i = 0; i < events.length; i++) {
+      if (events[i].timestamp >= targetTs) {
+        targetIndex = i;
+        break;
+      }
+      targetIndex = i + 1;
+    }
+    client.subscriptions.setEventIndex(cmd.sessionId, targetIndex);
+    const computed = client.subscriptions.computeStateAt(cmd.sessionId, events, targetIndex);
+    this.send(client, {
+      type: "markingSnapshot",
+      sessionId: cmd.sessionId,
+      marking: mapToRecord(computed.marking),
+      enabledTransitions: computed.enabledTransitions,
+      inFlightTransitions: computed.inFlightTransitions
+    });
   }
-}
-
-// src/debug/debug-event-store.ts
-var DEFAULT_MAX_EVENTS = 1e4;
-var DebugEventStore = class {
-  _events = [];
-  _subscribers = /* @__PURE__ */ new Set();
-  _sessionId;
-  _maxEvents;
-  _eventCount = 0;
-  _evictedCount = 0;
-  constructor(sessionId, maxEvents = DEFAULT_MAX_EVENTS) {
-    if (maxEvents <= 0) throw new Error(`maxEvents must be positive, got: ${maxEvents}`);
-    this._sessionId = sessionId;
-    this._maxEvents = maxEvents;
+  handlePlaybackSpeed(client, cmd) {
+    client.subscriptions.setSpeed(cmd.sessionId, cmd.speed);
+    this.send(client, {
+      type: "playbackStateChanged",
+      sessionId: cmd.sessionId,
+      paused: client.subscriptions.isPaused(cmd.sessionId),
+      speed: cmd.speed,
+      currentIndex: client.subscriptions.getEventIndex(cmd.sessionId)
+    });
   }
-  get sessionId() {
-    return this._sessionId;
+  handleSetFilter(client, cmd) {
+    client.subscriptions.setFilter(cmd.sessionId, cmd.filter);
+    this.send(client, { type: "filterApplied", sessionId: cmd.sessionId, filter: cmd.filter });
   }
-  get maxEvents() {
-    return this._maxEvents;
+  handlePause(client, cmd) {
+    client.subscriptions.setPaused(cmd.sessionId, true);
+    this.send(client, {
+      type: "playbackStateChanged",
+      sessionId: cmd.sessionId,
+      paused: true,
+      speed: client.subscriptions.getSpeed(cmd.sessionId),
+      currentIndex: client.subscriptions.getEventIndex(cmd.sessionId)
+    });
   }
-  /** Total events appended (including evicted). */
-  eventCount() {
-    return this._eventCount;
+  handleResume(client, cmd) {
+    client.subscriptions.setPaused(cmd.sessionId, false);
+    this.send(client, {
+      type: "playbackStateChanged",
+      sessionId: cmd.sessionId,
+      paused: false,
+      speed: client.subscriptions.getSpeed(cmd.sessionId),
+      currentIndex: client.subscriptions.getEventIndex(cmd.sessionId)
+    });
   }
-  /** Number of events evicted from the store. */
-  evictedCount() {
-    return this._evictedCount;
+  handleStepForward(client, cmd) {
+    const debugSession = this._sessionRegistry.getSession(cmd.sessionId);
+    if (!debugSession) {
+      this.sendError(client, "SESSION_NOT_FOUND", `Session not found: ${cmd.sessionId}`, cmd.sessionId);
+      return;
+    }
+    const events = debugSession.eventStore.events();
+    const currentIndex = client.subscriptions.getEventIndex(cmd.sessionId);
+    if (currentIndex < events.length) {
+      const event = events[currentIndex];
+      this.send(client, {
+        type: "event",
+        sessionId: cmd.sessionId,
+        index: currentIndex,
+        event: toEventInfo(event)
+      });
+      client.subscriptions.setEventIndex(cmd.sessionId, currentIndex + 1);
+    }
   }
-  // ======================== EventStore Implementation ========================
-  append(event) {
-    this._events.push(event);
-    this._eventCount++;
-    while (this._events.length > this._maxEvents) {
-      this._events.shift();
-      this._evictedCount++;
+  handleStepBackward(client, cmd) {
+    const debugSession = this._sessionRegistry.getSession(cmd.sessionId);
+    if (!debugSession) {
+      this.sendError(client, "SESSION_NOT_FOUND", `Session not found: ${cmd.sessionId}`, cmd.sessionId);
+      return;
     }
-    if (this._subscribers.size > 0) {
-      const subscribers = [...this._subscribers];
-      queueMicrotask(() => {
-        for (const sub of subscribers) {
-          try {
-            sub(event);
-          } catch (e) {
-            console.warn("Subscriber threw exception during event broadcast", e);
-          }
-        }
+    let currentIndex = client.subscriptions.getEventIndex(cmd.sessionId);
+    if (currentIndex > 0) {
+      currentIndex--;
+      client.subscriptions.setEventIndex(cmd.sessionId, currentIndex);
+      const events = debugSession.eventStore.events();
+      const computed = client.subscriptions.computeStateAt(cmd.sessionId, events, currentIndex);
+      this.send(client, {
+        type: "markingSnapshot",
+        sessionId: cmd.sessionId,
+        marking: mapToRecord(computed.marking),
+        enabledTransitions: computed.enabledTransitions,
+        inFlightTransitions: computed.inFlightTransitions
       });
     }
   }
-  events() {
-    return this._events;
+  handleSetBreakpoint(client, cmd) {
+    client.subscriptions.addBreakpoint(cmd.sessionId, cmd.breakpoint);
+    this.send(client, { type: "breakpointSet", sessionId: cmd.sessionId, breakpoint: cmd.breakpoint });
   }
-  isEnabled() {
-    return true;
+  handleClearBreakpoint(client, cmd) {
+    client.subscriptions.removeBreakpoint(cmd.sessionId, cmd.breakpointId);
+    this.send(client, { type: "breakpointCleared", sessionId: cmd.sessionId, breakpointId: cmd.breakpointId });
   }
-  size() {
-    return this._events.length;
+  handleListBreakpoints(client, cmd) {
+    const breakpoints = client.subscriptions.getBreakpoints(cmd.sessionId);
+    this.send(client, { type: "breakpointList", sessionId: cmd.sessionId, breakpoints });
   }
-  isEmpty() {
-    return this._events.length === 0;
+  // ======================== Helper Methods ========================
+  send(client, response) {
+    client.sink(response);
   }
-  // ======================== Live Tailing ========================
-  /** Subscribe to receive events as they occur. */
-  subscribe(listener) {
-    this._subscribers.add(listener);
-    return {
-      cancel: () => {
-        this._subscribers.delete(listener);
-      },
-      isActive: () => this._subscribers.has(listener)
-    };
+  sendError(client, code, message, sessionId) {
+    this.send(client, { type: "error", code, message, sessionId });
   }
-  /** Number of active subscribers. */
-  subscriberCount() {
-    return this._subscribers.size;
+  sendInBatches(client, sessionId, startIndex, events) {
+    if (events.length === 0) {
+      this.send(client, { type: "eventBatch", sessionId, startIndex, events: [], hasMore: false });
+      return;
+    }
+    for (let i = 0; i < events.length; i += BATCH_SIZE) {
+      const end = Math.min(i + BATCH_SIZE, events.length);
+      const chunk = events.slice(i, end);
+      const hasMore = end < events.length;
+      this.send(client, { type: "eventBatch", sessionId, startIndex: startIndex + i, events: chunk, hasMore });
+    }
   }
-  // ======================== Historical Replay ========================
-  /** Returns events starting from a specific index. */
-  eventsFrom(fromIndex) {
-    const adjustedSkip = Math.max(0, fromIndex - this._evictedCount);
-    if (adjustedSkip <= 0) return this._events;
-    return this._events.slice(adjustedSkip);
+};
+function computeState(events) {
+  const marking = /* @__PURE__ */ new Map();
+  const enabled = /* @__PURE__ */ new Set();
+  const inFlight = /* @__PURE__ */ new Set();
+  applyEvents(marking, enabled, inFlight, events);
+  return toImmutableState(marking, enabled, inFlight);
+}
+function applyEvents(marking, enabled, inFlight, events) {
+  for (const event of events) {
+    switch (event.type) {
+      case "token-added": {
+        let tokens = marking.get(event.placeName);
+        if (!tokens) {
+          tokens = [];
+          marking.set(event.placeName, tokens);
+        }
+        tokens.push(tokenInfo(event.token));
+        break;
+      }
+      case "token-removed": {
+        const tokens = marking.get(event.placeName);
+        if (tokens && tokens.length > 0) tokens.shift();
+        break;
+      }
+      case "marking-snapshot": {
+        marking.clear();
+        const converted = convertMarking(event.marking);
+        for (const [key, value] of Object.entries(converted)) {
+          marking.set(key, [...value]);
+        }
+        break;
+      }
+      case "transition-enabled":
+        enabled.add(event.transitionName);
+        break;
+      case "transition-started":
+        enabled.delete(event.transitionName);
+        inFlight.add(event.transitionName);
+        break;
+      case "transition-completed":
+        inFlight.delete(event.transitionName);
+        break;
+      case "transition-failed":
+        inFlight.delete(event.transitionName);
+        break;
+      case "transition-timed-out":
+        inFlight.delete(event.transitionName);
+        break;
+      case "action-timed-out":
+        inFlight.delete(event.transitionName);
+        break;
+      default:
+        break;
+    }
   }
-  /** Returns all events since the specified timestamp. */
-  eventsSince(from) {
-    return this._events.filter((e) => e.timestamp >= from);
+}
+function toImmutableState(marking, enabled, inFlight) {
+  const resultMarking = /* @__PURE__ */ new Map();
+  for (const [key, value] of marking) {
+    resultMarking.set(key, [...value]);
   }
-  /** Returns events within a time range. */
-  eventsBetween(from, to) {
-    return this._events.filter((e) => e.timestamp >= from && e.timestamp < to);
+  return {
+    marking: resultMarking,
+    enabledTransitions: [...enabled],
+    inFlightTransitions: [...inFlight]
+  };
+}
+function mapToRecord(map) {
+  const result = {};
+  for (const [key, value] of map) {
+    result[key] = value;
   }
-  // ======================== Lifecycle ========================
-  /** Close the store (no-op in JS, but matches Java interface). */
-  close() {
-    this._subscribers.clear();
+  return result;
+}
+var ClientState = class {
+  sink;
+  subscriptions = new SubscriptionState();
+  constructor(sink) {
+    this.sink = sink;
   }
 };
-
-// src/debug/place-analysis.ts
-var PlaceAnalysis = class _PlaceAnalysis {
-  _data;
-  constructor(data) {
-    this._data = data;
-  }
-  get data() {
-    return this._data;
-  }
-  isStart(placeName) {
-    const info = this._data.get(placeName);
-    return info != null && !info.hasIncoming;
+var SubscriptionState = class {
+  _sessionSubs = /* @__PURE__ */ new Map();
+  addSubscription(sessionId, subscription, eventIndex) {
+    this._sessionSubs.set(sessionId, {
+      subscription,
+      eventIndex,
+      markingCache: new MarkingCache(),
+      breakpoints: /* @__PURE__ */ new Map(),
+      paused: false,
+      speed: 1,
+      filter: null
+    });
   }
-  isEnd(placeName) {
-    const info = this._data.get(placeName);
-    return info != null && !info.hasOutgoing;
+  cancel(sessionId) {
+    const sub = this._sessionSubs.get(sessionId);
+    if (sub?.subscription) sub.subscription.cancel();
+    this._sessionSubs.delete(sessionId);
   }
-  /** Build place analysis from a PetriNet. */
-  static from(net) {
-    const data = /* @__PURE__ */ new Map();
-    function ensure(place) {
-      let info = data.get(place.name);
-      if (!info) {
-        info = { tokenType: "unknown", hasIncoming: false, hasOutgoing: false };
-        data.set(place.name, info);
-      }
-      return info;
-    }
-    for (const transition of net.transitions) {
-      for (const input of transition.inputSpecs) {
-        const info = ensure(input.place);
-        info.hasOutgoing = true;
-      }
-      if (transition.outputSpec) {
-        const outputPlaces = collectOutputPlaces(transition.outputSpec);
-        for (const place of outputPlaces) {
-          const info = ensure(place);
-          info.hasIncoming = true;
-        }
-      }
-      for (const inh of transition.inhibitors) {
-        ensure(inh.place);
-      }
-      for (const read of transition.reads) {
-        const info = ensure(read.place);
-        info.hasOutgoing = true;
-      }
-      for (const reset of transition.resets) {
-        ensure(reset.place);
-      }
+  cancelAll() {
+    for (const sub of this._sessionSubs.values()) {
+      if (sub.subscription) sub.subscription.cancel();
     }
-    return new _PlaceAnalysis(data);
+    this._sessionSubs.clear();
+  }
+  isPaused(sessionId) {
+    return this._sessionSubs.get(sessionId)?.paused ?? false;
   }
-};
-function collectOutputPlaces(out) {
-  const spec = out;
-  switch (spec.type) {
-    case "place":
-      return spec.place ? [spec.place] : [];
-    case "and":
-    case "xor":
-      return (spec.children ?? []).flatMap((c) => collectOutputPlaces(c));
-    case "timeout":
-      return spec.child ? collectOutputPlaces(spec.child) : [];
-    case "forward-input":
-      return spec.to ? [spec.to] : [];
-    default:
-      return [];
+  setPaused(sessionId, paused) {
+    const sub = this._sessionSubs.get(sessionId);
+    if (sub) sub.paused = paused;
   }
-}
-
-// src/debug/debug-session-registry.ts
-var DebugSessionRegistry = class {
-  _sessions = /* @__PURE__ */ new Map();
-  _maxSessions;
-  _eventStoreFactory;
-  constructor(maxSessions = 50, eventStoreFactory) {
-    this._maxSessions = maxSessions;
-    this._eventStoreFactory = eventStoreFactory ?? ((id) => new DebugEventStore(id));
+  getSpeed(sessionId) {
+    return this._sessionSubs.get(sessionId)?.speed ?? 1;
   }
-  /**
-   * Registers a new debug session for the given Petri net.
-   * Generates DOT diagram and extracts net structure.
-   */
-  register(sessionId, net) {
-    const dotDiagram = dotExport(net);
-    const places = PlaceAnalysis.from(net);
-    const eventStore = this._eventStoreFactory(sessionId);
-    const session = {
-      sessionId,
-      netName: net.name,
-      dotDiagram,
-      places,
-      transitions: net.transitions,
-      eventStore,
-      startTime: Date.now(),
-      active: true
-    };
-    this.evictIfNecessary();
-    this._sessions.set(sessionId, session);
-    return session;
+  setSpeed(sessionId, speed) {
+    const sub = this._sessionSubs.get(sessionId);
+    if (sub) sub.speed = speed;
   }
-  /** Marks a session as completed (no longer active). */
-  complete(sessionId) {
-    const session = this._sessions.get(sessionId);
-    if (session) {
-      this._sessions.set(sessionId, { ...session, active: false });
-    }
+  getEventIndex(sessionId) {
+    return this._sessionSubs.get(sessionId)?.eventIndex ?? 0;
   }
-  /** Removes a session from the registry. */
-  remove(sessionId) {
-    const removed = this._sessions.get(sessionId);
-    if (removed) {
-      this._sessions.delete(sessionId);
-      removed.eventStore.close();
-    }
-    return removed;
+  setEventIndex(sessionId, index) {
+    const sub = this._sessionSubs.get(sessionId);
+    if (sub) sub.eventIndex = index;
   }
-  /** Returns a session by ID. */
-  getSession(sessionId) {
-    return this._sessions.get(sessionId);
+  computeStateAt(sessionId, events, targetIndex) {
+    const sub = this._sessionSubs.get(sessionId);
+    if (sub) return sub.markingCache.computeAt(events, targetIndex);
+    return computeState(events.slice(0, targetIndex));
   }
-  /** Lists sessions, ordered by start time (most recent first). */
-  listSessions(limit) {
-    return [...this._sessions.values()].sort((a, b) => b.startTime - a.startTime).slice(0, limit);
+  setFilter(sessionId, filter) {
+    const sub = this._sessionSubs.get(sessionId);
+    if (sub) sub.filter = filter;
   }
-  /** Lists only active sessions. */
-  listActiveSessions(limit) {
-    return [...this._sessions.values()].filter((s) => s.active).sort((a, b) => b.startTime - a.startTime).slice(0, limit);
+  matchesFilter(sessionId, event) {
+    const sub = this._sessionSubs.get(sessionId);
+    if (!sub?.filter) return true;
+    const filter = sub.filter;
+    if (filter.eventTypes && filter.eventTypes.length > 0) {
+      const eventType = eventTypeToName(event);
+      if (!filter.eventTypes.includes(eventType)) return false;
+    }
+    if (filter.transitionNames && filter.transitionNames.length > 0) {
+      const name = extractTransitionName(event);
+      if (!name || !filter.transitionNames.includes(name)) return false;
+    }
+    if (filter.placeNames && filter.placeNames.length > 0) {
+      const name = extractPlaceName(event);
+      if (!name || !filter.placeNames.includes(name)) return false;
+    }
+    return true;
   }
-  /** Total number of sessions. */
-  get size() {
-    return this._sessions.size;
+  addBreakpoint(sessionId, breakpoint) {
+    const sub = this._sessionSubs.get(sessionId);
+    if (sub) sub.breakpoints.set(breakpoint.id, breakpoint);
   }
-  /** Evicts oldest inactive sessions if at capacity. */
-  evictIfNecessary() {
-    if (this._sessions.size < this._maxSessions) return;
-    const candidates = [...this._sessions.values()].sort((a, b) => {
-      if (a.active !== b.active) return a.active ? 1 : -1;
-      return a.startTime - b.startTime;
-    });
-    for (const candidate of candidates) {
-      if (this._sessions.size < this._maxSessions) break;
-      const evicted = this._sessions.get(candidate.sessionId);
-      if (evicted) {
-        this._sessions.delete(candidate.sessionId);
-        evicted.eventStore.close();
-      }
+  removeBreakpoint(sessionId, breakpointId) {
+    const sub = this._sessionSubs.get(sessionId);
+    if (sub) sub.breakpoints.delete(breakpointId);
+  }
+  getBreakpoints(sessionId) {
+    const sub = this._sessionSubs.get(sessionId);
+    return sub ? [...sub.breakpoints.values()] : [];
+  }
+  checkBreakpoints(sessionId, event) {
+    const sub = this._sessionSubs.get(sessionId);
+    if (!sub || sub.breakpoints.size === 0) return null;
+    for (const bp of sub.breakpoints.values()) {
+      if (!bp.enabled) continue;
+      if (matchesBreakpoint(bp, event)) return bp;
     }
+    return null;
   }
 };
+function eventTypeToName(event) {
+  const map = {
+    "execution-started": "ExecutionStarted",
+    "execution-completed": "ExecutionCompleted",
+    "transition-enabled": "TransitionEnabled",
+    "transition-clock-restarted": "TransitionClockRestarted",
+    "transition-started": "TransitionStarted",
+    "transition-completed": "TransitionCompleted",
+    "transition-failed": "TransitionFailed",
+    "transition-timed-out": "TransitionTimedOut",
+    "action-timed-out": "ActionTimedOut",
+    "token-added": "TokenAdded",
+    "token-removed": "TokenRemoved",
+    "marking-snapshot": "MarkingSnapshot",
+    "log-message": "LogMessage"
+  };
+  return map[event.type] ?? event.type;
+}
+function extractTransitionName(event) {
+  switch (event.type) {
+    case "transition-enabled":
+    case "transition-clock-restarted":
+    case "transition-started":
+    case "transition-completed":
+    case "transition-failed":
+    case "transition-timed-out":
+    case "action-timed-out":
+    case "log-message":
+      return event.transitionName;
+    default:
+      return null;
+  }
+}
+function extractPlaceName(event) {
+  switch (event.type) {
+    case "token-added":
+    case "token-removed":
+      return event.placeName;
+    default:
+      return null;
+  }
+}
+function matchesBreakpoint(bp, event) {
+  switch (bp.type) {
+    case "TRANSITION_ENABLED":
+      return event.type === "transition-enabled" && (bp.target === null || bp.target === event.transitionName);
+    case "TRANSITION_START":
+      return event.type === "transition-started" && (bp.target === null || bp.target === event.transitionName);
+    case "TRANSITION_COMPLETE":
+      return event.type === "transition-completed" && (bp.target === null || bp.target === event.transitionName);
+    case "TRANSITION_FAIL":
+      return event.type === "transition-failed" && (bp.target === null || bp.target === event.transitionName);
+    case "TOKEN_ADDED":
+      return event.type === "token-added" && (bp.target === null || bp.target === event.placeName);
+    case "TOKEN_REMOVED":
+      return event.type === "token-removed" && (bp.target === null || bp.target === event.placeName);
+    default:
+      return false;
+  }
+}
 
 // src/debug/debug-aware-event-store.ts
 var DebugAwareEventStore = class {
@@ -1058,6 +1112,249 @@ var DebugAwareEventStore = class {
   }
 };
 
+// src/debug/archive/session-archive.ts
+var CURRENT_VERSION = 1;
+
+// src/debug/archive/file-session-archive-storage.ts
+import { mkdir, readdir, readFile, stat, writeFile } from "fs/promises";
+import { join, normalize, resolve } from "path";
+import { Writable } from "stream";
+var EXTENSION = ".archive.gz";
+var FileSessionArchiveStorage = class {
+  _directory;
+  constructor(directory) {
+    this._directory = resolve(directory);
+  }
+  async storeStreaming(sessionId, writer) {
+    const target = this.archivePath(sessionId);
+    const dir = join(target, "..");
+    await mkdir(dir, { recursive: true });
+    const chunks = [];
+    const writable = new Writable({
+      write(chunk, _encoding, callback) {
+        chunks.push(chunk);
+        callback();
+      }
+    });
+    await writer(writable);
+    await writeFile(target, Buffer.concat(chunks));
+  }
+  async list(limit, prefix) {
+    try {
+      await stat(this._directory);
+    } catch {
+      return [];
+    }
+    const results = [];
+    let prefixDirs;
+    try {
+      prefixDirs = await readdir(this._directory);
+    } catch {
+      return [];
+    }
+    for (const prefixDir of prefixDirs) {
+      const prefixPath = join(this._directory, prefixDir);
+      try {
+        const s = await stat(prefixPath);
+        if (!s.isDirectory()) continue;
+      } catch {
+        continue;
+      }
+      if (prefix && prefixDir.length === 1 && prefixDir[0] !== prefix[0]) continue;
+      let files;
+      try {
+        files = await readdir(prefixPath);
+      } catch {
+        continue;
+      }
+      for (const file of files) {
+        if (!file.endsWith(EXTENSION)) continue;
+        const sessionId = file.slice(0, -EXTENSION.length);
+        if (prefix && !sessionId.startsWith(prefix)) continue;
+        const filePath = join(prefixPath, file);
+        try {
+          const fileStat = await stat(filePath);
+          const relativePath = join(prefixDir, file);
+          results.push({
+            sessionId,
+            key: relativePath,
+            sizeBytes: fileStat.size,
+            lastModified: fileStat.mtimeMs
+          });
+        } catch {
+        }
+      }
+    }
+    results.sort((a, b) => b.lastModified - a.lastModified);
+    return results.slice(0, limit);
+  }
+  async retrieve(sessionId) {
+    const path = this.archivePath(sessionId);
+    try {
+      return await readFile(path);
+    } catch {
+      throw new Error(`Archive not found for session: ${sessionId}`);
+    }
+  }
+  isAvailable() {
+    return true;
+  }
+  archivePath(sessionId) {
+    if (!sessionId || !sessionId.trim()) {
+      throw new Error(`Invalid session ID: ${sessionId}`);
+    }
+    const prefix = sessionId[0];
+    const resolved = normalize(join(this._directory, prefix, sessionId + EXTENSION));
+    if (!resolved.startsWith(this._directory)) {
+      throw new Error(`Session ID escapes archive directory: ${sessionId}`);
+    }
+    return resolved;
+  }
+};
+
+// src/debug/archive/session-archive-writer.ts
+import { gzipSync } from "zlib";
+var SessionArchiveWriter = class {
+  /**
+   * Writes a complete session archive and returns the compressed bytes.
+   */
+  write(session) {
+    const structure = buildNetStructure(session);
+    const metadata = {
+      version: CURRENT_VERSION,
+      sessionId: session.sessionId,
+      netName: session.netName,
+      dotDiagram: session.dotDiagram,
+      startTime: new Date(session.startTime).toISOString(),
+      eventCount: session.eventStore.eventCount(),
+      structure
+    };
+    const parts = [];
+    const metaBytes = Buffer.from(JSON.stringify(metadata), "utf-8");
+    const metaLen = Buffer.alloc(4);
+    metaLen.writeUInt32BE(metaBytes.length);
+    parts.push(metaLen, metaBytes);
+    for (const event of session.eventStore) {
+      const eventInfo = toEventInfo(event);
+      const eventBytes = Buffer.from(JSON.stringify(eventInfo), "utf-8");
+      const eventLen = Buffer.alloc(4);
+      eventLen.writeUInt32BE(eventBytes.length);
+      parts.push(eventLen, eventBytes);
+    }
+    const raw = Buffer.concat(parts);
+    return gzipSync(raw);
+  }
+};
+
+// src/debug/archive/session-archive-reader.ts
+import { gunzipSync } from "zlib";
+var MAX_EVENT_SIZE = 10 * 1024 * 1024;
+var SessionArchiveReader = class {
+  /** Reads only the metadata header from an archive. */
+  readMetadata(compressed) {
+    const data = gunzipSync(compressed);
+    const metaLen = data.readUInt32BE(0);
+    const metaJson = data.subarray(4, 4 + metaLen).toString("utf-8");
+    const metadata = JSON.parse(metaJson);
+    if (metadata.version !== CURRENT_VERSION) {
+      throw new Error(`Unsupported archive version: ${metadata.version} (expected ${CURRENT_VERSION})`);
+    }
+    return metadata;
+  }
+  /** Reads the full archive: metadata + all events into a DebugEventStore. */
+  readFull(compressed) {
+    const data = gunzipSync(compressed);
+    let offset = 0;
+    const metaLen = data.readUInt32BE(offset);
+    offset += 4;
+    const metaJson = data.subarray(offset, offset + metaLen).toString("utf-8");
+    offset += metaLen;
+    const metadata = JSON.parse(metaJson);
+    if (metadata.version !== CURRENT_VERSION) {
+      throw new Error(`Unsupported archive version: ${metadata.version} (expected ${CURRENT_VERSION})`);
+    }
+    const eventStore = new DebugEventStore(metadata.sessionId, Number.MAX_SAFE_INTEGER);
+    while (offset < data.length) {
+      if (offset + 4 > data.length) break;
+      const eventLen = data.readUInt32BE(offset);
+      offset += 4;
+      if (eventLen <= 0 || eventLen > MAX_EVENT_SIZE) {
+        throw new Error(`Invalid event size: ${eventLen}`);
+      }
+      if (offset + eventLen > data.length) break;
+      const eventJson = data.subarray(offset, offset + eventLen).toString("utf-8");
+      offset += eventLen;
+      const eventInfo = JSON.parse(eventJson);
+      const netEvent = eventInfoToNetEvent(eventInfo);
+      eventStore.append(netEvent);
+    }
+    return { metadata, eventStore };
+  }
+};
+function eventInfoToNetEvent(info) {
+  const timestamp = new Date(info.timestamp).getTime();
+  const d = info.details;
+  switch (info.type) {
+    case "ExecutionStarted":
+      return { type: "execution-started", timestamp, netName: d["netName"], executionId: d["executionId"] };
+    case "ExecutionCompleted":
+      return { type: "execution-completed", timestamp, netName: d["netName"], executionId: d["executionId"], totalDurationMs: d["totalDurationMs"] };
+    case "TransitionEnabled":
+      return { type: "transition-enabled", timestamp, transitionName: info.transitionName };
+    case "TransitionClockRestarted":
+      return { type: "transition-clock-restarted", timestamp, transitionName: info.transitionName };
+    case "TransitionStarted": {
+      const tokens = d["consumedTokens"].map((t) => infoToToken(t));
+      return { type: "transition-started", timestamp, transitionName: info.transitionName, consumedTokens: tokens };
+    }
+    case "TransitionCompleted": {
+      const tokens = d["producedTokens"].map((t) => infoToToken(t));
+      return { type: "transition-completed", timestamp, transitionName: info.transitionName, producedTokens: tokens, durationMs: d["durationMs"] };
+    }
+    case "TransitionFailed":
+      return { type: "transition-failed", timestamp, transitionName: info.transitionName, errorMessage: d["errorMessage"], exceptionType: d["exceptionType"] };
+    case "TransitionTimedOut":
+      return { type: "transition-timed-out", timestamp, transitionName: info.transitionName, deadlineMs: d["deadlineMs"], actualDurationMs: d["actualDurationMs"] };
+    case "ActionTimedOut":
+      return { type: "action-timed-out", timestamp, transitionName: info.transitionName, timeoutMs: d["timeoutMs"] };
+    case "TokenAdded": {
+      const t = d["token"];
+      return { type: "token-added", timestamp, placeName: info.placeName, token: infoToToken(t) };
+    }
+    case "TokenRemoved": {
+      const t = d["token"];
+      return { type: "token-removed", timestamp, placeName: info.placeName, token: infoToToken(t) };
+    }
+    case "MarkingSnapshot": {
+      const markingData = d["marking"];
+      const marking = /* @__PURE__ */ new Map();
+      for (const [place, tokens] of Object.entries(markingData)) {
+        marking.set(place, tokens.map((t) => infoToToken(t)));
+      }
+      return { type: "marking-snapshot", timestamp, marking };
+    }
+    case "LogMessage":
+      return {
+        type: "log-message",
+        timestamp,
+        transitionName: info.transitionName,
+        logger: d["loggerName"],
+        level: d["level"],
+        message: d["message"],
+        error: d["throwable"] ?? null,
+        errorMessage: d["throwableMessage"] ?? null
+      };
+    default:
+      return { type: "transition-enabled", timestamp, transitionName: info.transitionName ?? "unknown" };
+  }
+}
+function infoToToken(t) {
+  return {
+    value: t.value,
+    createdAt: t.timestamp ? new Date(t.timestamp).getTime() : Date.now()
+  };
+}
+
 // src/debug/index.ts
 async function debugUiAssetPath() {
   const dynamicImport = Function("m", "return import(m)");
@@ -1067,14 +1364,19 @@ async function debugUiAssetPath() {
   return nodePath.join(thisDir, "..", "debug-ui");
 }
 export {
+  CURRENT_VERSION,
   DEFAULT_MAX_EVENTS,
   DebugAwareEventStore,
   DebugEventStore,
   DebugProtocolHandler,
   DebugSessionRegistry,
+  FileSessionArchiveStorage,
   MarkingCache,
   PlaceAnalysis,
   SNAPSHOT_INTERVAL,
+  SessionArchiveReader,
+  SessionArchiveWriter,
+  buildNetStructure,
   compactTokenInfo,
   convertMarking,
   debugUiAssetPath,