libpetri 1.5.1 → 1.8.0

package/dist/debug/index.js

@@ -118,7 +118,11 @@ var DebugEventStore = class {
 };
 
 // src/debug/archive/session-archive.ts
-var CURRENT_VERSION = 1;
+var CURRENT_VERSION = 3;
+var MIN_SUPPORTED_VERSION = 1;
+function emptyMetadata() {
+  return { eventTypeHistogram: {}, hasErrors: false };
+}
 
 // src/debug/archive/session-archive-reader.ts
 var MAX_EVENT_SIZE = 10 * 1024 * 1024;
@@ -128,11 +132,7 @@ var SessionArchiveReader = class {
     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;
+    return parseHeader(metaJson);
   }
   /** Reads the full archive: metadata + all events into a DebugEventStore. */
   readFull(compressed) {
@@ -142,10 +142,7 @@ var SessionArchiveReader = class {
     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 metadata = parseHeader(metaJson);
     const eventStore = new DebugEventStore(metadata.sessionId, Number.MAX_SAFE_INTEGER);
     while (offset < data.length) {
       if (offset + 4 > data.length) break;
@@ -164,6 +161,33 @@ var SessionArchiveReader = class {
     return { metadata, eventStore };
   }
 };
+function parseHeader(metaJson) {
+  const raw = JSON.parse(metaJson);
+  switch (raw.version) {
+    case 1:
+      return raw;
+    case 2: {
+      const v2 = raw;
+      return {
+        ...v2,
+        tags: v2.tags ?? {},
+        metadata: v2.metadata ?? emptyMetadata()
+      };
+    }
+    case 3: {
+      const v3 = raw;
+      return {
+        ...v3,
+        tags: v3.tags ?? {},
+        metadata: v3.metadata ?? emptyMetadata()
+      };
+    }
+    default:
+      throw new Error(
+        `Unsupported archive version: ${raw.version} (reader supports ${MIN_SUPPORTED_VERSION}..${CURRENT_VERSION})`
+      );
+  }
+}
 function eventInfoToNetEvent(info) {
   const timestamp = new Date(info.timestamp).getTime();
   const d = info.details;
@@ -222,10 +246,8 @@ function eventInfoToNetEvent(info) {
   }
 }
 function infoToToken(t) {
-  return {
-    value: t.value,
-    createdAt: t.timestamp ? new Date(t.timestamp).getTime() : Date.now()
-  };
+  const createdAt = t.timestamp ? new Date(t.timestamp).getTime() : Date.now();
+  return t.structured === void 0 ? { value: t.value, createdAt } : { value: t.value, createdAt, structured: t.structured };
 }
 
 // src/debug/place-analysis.ts
@@ -341,8 +363,12 @@ var DebugSessionRegistry = class {
   /**
    * Registers a new debug session for the given Petri net.
    * Generates DOT diagram and extracts net structure.
+   *
+   * @param sessionId unique session id
+   * @param net the Petri net being executed
+   * @param tags optional user-defined tags (libpetri 1.6.0+) — e.g. `{channel: 'voice'}`
    */
-  register(sessionId, net) {
+  register(sessionId, net, tags) {
     const dotDiagram = dotExport(net);
     const places = PlaceAnalysis.from(net);
     const eventStore = this._eventStoreFactory(sessionId);
@@ -355,7 +381,8 @@ var DebugSessionRegistry = class {
       eventStore,
       startTime: Date.now(),
       active: true,
-      importedStructure: null
+      importedStructure: null,
+      tags: tags ? { ...tags } : {}
     };
     this.evictIfNecessary();
     this._sessions.set(sessionId, session);
@@ -363,16 +390,20 @@ var DebugSessionRegistry = class {
   }
   /**
    * Marks a session as completed (no longer active) and notifies completion listeners.
+   *
+   * <p>Stamps `endTime = Date.now()` on the first completion. Idempotent: subsequent
+   * calls preserve the existing endTime. (libpetri 1.6.0+)
    */
   complete(sessionId) {
     const session = this._sessions.get(sessionId);
     if (session) {
-      const completed = { ...session, active: false };
+      const endTime = session.endTime ?? Date.now();
+      const completed = { ...session, active: false, endTime };
       this._sessions.set(sessionId, completed);
       this.notifyCompletionListeners(completed);
     }
   }
-  /** Removes a session from the registry. */
+  /** Removes a session from the registry. Tags die with the session. */
   remove(sessionId) {
     const removed = this._sessions.get(sessionId);
     if (removed) {
@@ -385,13 +416,36 @@ var DebugSessionRegistry = class {
   getSession(sessionId) {
     return this._sessions.get(sessionId);
   }
+  /**
+   * Sets or overwrites a single tag on a session. (libpetri 1.6.0+)
+   *
+   * Tags accumulate until the session is removed. Setting a key that already
+   * exists replaces its value.
+   *
+   * If `sessionId` is not a currently-registered session the call is a no-op.
+   * A tag write that races with {@link remove} is harmless — the write lands on
+   * the now-orphaned session object and is garbage collected along with it.
+   */
+  tag(sessionId, key, value) {
+    const session = this._sessions.get(sessionId);
+    if (!session) return;
+    session.tags[key] = value;
+  }
+  /**
+   * Returns a snapshot of the tags attached to a session. Returns an empty
+   * object if the session has no tags or does not exist. (libpetri 1.6.0+)
+   */
+  tagsFor(sessionId) {
+    const session = this._sessions.get(sessionId);
+    return session ? { ...session.tags } : {};
+  }
   /** 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);
+  listSessions(limit, tagFilter) {
+    return [...this._sessions.values()].filter((s) => this.matchesTagFilter(s, tagFilter)).sort((a, b) => b.startTime - a.startTime).slice(0, limit);
   }
   /** Lists only active sessions. */
-  listActiveSessions(limit) {
-    return [...this._sessions.values()].filter((s) => s.active).sort((a, b) => b.startTime - a.startTime).slice(0, limit);
+  listActiveSessions(limit, tagFilter) {
+    return [...this._sessions.values()].filter((s) => s.active).filter((s) => this.matchesTagFilter(s, tagFilter)).sort((a, b) => b.startTime - a.startTime).slice(0, limit);
   }
   /** Total number of sessions. */
   get size() {
@@ -399,8 +453,11 @@ var DebugSessionRegistry = class {
   }
   /**
    * Registers an imported (archived) session as an inactive, read-only session.
+   *
+   * @param endTime when the original session ended (libpetri 1.6.0+)
+   * @param tags user-defined tags attached to the imported session (libpetri 1.6.0+)
    */
-  registerImported(sessionId, netName, dotDiagram, structure, eventStore, startTime) {
+  registerImported(sessionId, netName, dotDiagram, structure, eventStore, startTime, endTime, tags) {
     this.evictIfNecessary();
     const session = {
       sessionId,
@@ -411,11 +468,24 @@ var DebugSessionRegistry = class {
       eventStore,
       startTime,
       active: false,
-      importedStructure: structure
+      importedStructure: structure,
+      endTime,
+      tags: tags ? { ...tags } : {}
     };
     this._sessions.set(sessionId, session);
     return session;
   }
+  /** AND-match: all filter entries must exactly match the session's tags. */
+  matchesTagFilter(session, filter) {
+    if (!filter) return true;
+    const keys = Object.keys(filter);
+    if (keys.length === 0) return true;
+    const tags = session.tags;
+    for (const key of keys) {
+      if (tags[key] !== filter[key]) return false;
+    }
+    return true;
+  }
   /** Notifies all completion listeners. Exceptions are caught and logged. */
   notifyCompletionListeners(session) {
     for (const listener of this._completionListeners) {
@@ -646,12 +716,30 @@ 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 {
+  const info = {
     id: null,
     type,
     value: fullValue,
     timestamp: new Date(token.createdAt).toISOString()
   };
+  const structured = structuredValue(value);
+  return structured === void 0 ? info : { ...info, structured };
+}
+function structuredValue(value) {
+  if (value == null) return void 0;
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean") return value;
+  if (t === "bigint") return String(value);
+  if (t === "symbol" || t === "function") return void 0;
+  try {
+    const cloned = JSON.parse(JSON.stringify(value));
+    if (cloned && typeof cloned === "object" && !Array.isArray(cloned) && Object.keys(cloned).length === 0) {
+      return void 0;
+    }
+    return cloned;
+  } catch {
+    return void 0;
+  }
 }
 function compactTokenInfo(token) {
   const value = token.value;
@@ -754,15 +842,22 @@ var DebugProtocolHandler = class {
   // ======================== 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) => ({
+    const sessions = cmd.activeOnly ? this._sessionRegistry.listActiveSessions(limit, cmd.tagFilter) : this._sessionRegistry.listSessions(limit, cmd.tagFilter);
+    const summaries = sessions.map((s) => this.toProtocolSummary(s));
+    this.send(client, { type: "sessionList", sessions: summaries });
+  }
+  toProtocolSummary(s) {
+    const tags = this._sessionRegistry.tagsFor(s.sessionId);
+    return {
       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 });
+      eventCount: s.eventStore.eventCount(),
+      tags: Object.keys(tags).length > 0 ? tags : void 0,
+      endTime: s.endTime !== void 0 ? new Date(s.endTime).toISOString() : void 0,
+      durationMs: s.endTime !== void 0 ? s.endTime - s.startTime : void 0
+    };
   }
   handleSubscribe(client, cmd) {
     const debugSession = this._sessionRegistry.getSession(cmd.sessionId);
@@ -1024,13 +1119,7 @@ var DebugProtocolHandler = class {
   }
   broadcastSessionList() {
     const sessions = this._sessionRegistry.listSessions(50);
-    const summaries = sessions.map((s) => ({
-      sessionId: s.sessionId,
-      netName: s.netName,
-      startTime: new Date(s.startTime).toISOString(),
-      active: s.active,
-      eventCount: s.eventStore.eventCount()
-    }));
+    const summaries = sessions.map((s) => this.toProtocolSummary(s));
     const response = { type: "sessionList", sessions: summaries };
     for (const clientState of this._clients.values()) {
       try {
@@ -1442,23 +1531,126 @@ var FileSessionArchiveStorage = class {
 
 // src/debug/archive/session-archive-writer.ts
 import { gzipSync } from "zlib";
+
+// src/debug/archive/session-metadata.ts
+function computeMetadata(events) {
+  const raw = {};
+  let first;
+  let last;
+  let hasErrors = false;
+  for (const event of events) {
+    const typeName = toEventInfo(event).type;
+    raw[typeName] = (raw[typeName] ?? 0) + 1;
+    if (first === void 0) first = event.timestamp;
+    last = event.timestamp;
+    if (isErrorEvent(event)) hasErrors = true;
+  }
+  const histogram = {};
+  for (const key of Object.keys(raw).sort()) {
+    histogram[key] = raw[key];
+  }
+  return {
+    eventTypeHistogram: histogram,
+    firstEventTime: first !== void 0 ? new Date(first).toISOString() : void 0,
+    lastEventTime: last !== void 0 ? new Date(last).toISOString() : void 0,
+    hasErrors
+  };
+}
+function isErrorEvent(event) {
+  switch (event.type) {
+    case "transition-failed":
+    case "transition-timed-out":
+    case "action-timed-out":
+      return true;
+    case "log-message":
+      return event.level.toUpperCase() === "ERROR";
+    default:
+      return false;
+  }
+}
+
+// src/debug/archive/session-archive-writer.ts
 var SessionArchiveWriter = class {
   /**
-   * Writes a complete session archive and returns the compressed bytes.
+   * Writes a complete session archive in the current format (v3 as of 1.8.0)
+   * and returns the compressed bytes.
    */
   write(session) {
-    const structure = buildNetStructure(session);
-    const metadata = {
-      version: CURRENT_VERSION,
+    return this.writeV3(session);
+  }
+  /**
+   * Writes a session in the legacy v1 format. Use only for compatibility
+   * testing or when producing archives for consumers pinned to libpetri ≤ 1.6.1.
+   */
+  writeV1(session) {
+    const header = {
+      version: 1,
       sessionId: session.sessionId,
       netName: session.netName,
       dotDiagram: session.dotDiagram,
       startTime: new Date(session.startTime).toISOString(),
       eventCount: session.eventStore.eventCount(),
-      structure
+      structure: buildNetStructure(session)
     };
+    return this.writeFramed(header, session);
+  }
+  /**
+   * Writes a session in the v2 format — richer header with `endTime`, `tags`,
+   * and pre-computed {@link SessionMetadata}.
+   *
+   * Two passes over the event store: one to compute metadata, one to serialize
+   * events. `DebugEventStore` stores events in a plain readonly array and its
+   * `[Symbol.iterator]()` returns a fresh array iterator each call, so both
+   * passes walk the same sequence from the start.
+   */
+  writeV2(session) {
+    const metadata = computeMetadata(session.eventStore);
+    const header = {
+      version: 2,
+      sessionId: session.sessionId,
+      netName: session.netName,
+      dotDiagram: session.dotDiagram,
+      startTime: new Date(session.startTime).toISOString(),
+      endTime: session.endTime !== void 0 ? new Date(session.endTime).toISOString() : void 0,
+      eventCount: session.eventStore.eventCount(),
+      // Snapshot of tags at archive-write time — record the state that was
+      // current when the session was archived, not whatever happens on the
+      // live session afterwards.
+      tags: { ...session.tags },
+      metadata,
+      structure: buildNetStructure(session)
+    };
+    return this.writeFramed(header, session);
+  }
+  /**
+   * Writes a session in the v3 format — same header shape as v2, with version=3
+   * signalling that token payloads carry a `structured` field alongside the
+   * legacy `value` string (see {@link tokenInfo}).
+   */
+  writeV3(session) {
+    const metadata = computeMetadata(session.eventStore);
+    const header = {
+      version: 3,
+      sessionId: session.sessionId,
+      netName: session.netName,
+      dotDiagram: session.dotDiagram,
+      startTime: new Date(session.startTime).toISOString(),
+      endTime: session.endTime !== void 0 ? new Date(session.endTime).toISOString() : void 0,
+      eventCount: session.eventStore.eventCount(),
+      tags: { ...session.tags },
+      metadata,
+      structure: buildNetStructure(session)
+    };
+    return this.writeFramed(header, session);
+  }
+  /**
+   * Shared framing logic: length-prefixed header JSON, then length-prefixed
+   * event JSON, then gzip. Both v1 and v2 archives use the identical event
+   * wire format, so the body loop is version-agnostic.
+   */
+  writeFramed(header, session) {
     const parts = [];
-    const metaBytes = Buffer.from(JSON.stringify(metadata), "utf-8");
+    const metaBytes = Buffer.from(JSON.stringify(header), "utf-8");
     const metaLen = Buffer.alloc(4);
     metaLen.writeUInt32BE(metaBytes.length);
     parts.push(metaLen, metaBytes);
@@ -1469,8 +1661,7 @@ var SessionArchiveWriter = class {
       eventLen.writeUInt32BE(eventBytes.length);
       parts.push(eventLen, eventBytes);
     }
-    const raw = Buffer.concat(parts);
-    return gzipSync(raw);
+    return gzipSync(Buffer.concat(parts));
   }
 };