libpetri 1.5.0 → 1.7.0

package/dist/debug/index.d.ts

@@ -1,6 +1,6 @@
 import { Writable } from 'node:stream';
-import { a as PetriNet, b as Transition, T as Token } from '../petri-net-C3Jy5HCt.js';
-import { E as EventStore, N as NetEvent } from '../event-store-Y8q_wapJ.js';
+import { a as PetriNet, b as Transition, T as Token } from '../petri-net-DrTpTRNy.js';
+import { E as EventStore, N as NetEvent } from '../event-store-DePCZb33.js';
 
 /**
  * Commands sent from debug UI client to server via WebSocket.
@@ -34,6 +34,8 @@ type DebugCommand = {
     readonly type: 'listSessions';
     readonly limit?: number;
     readonly activeOnly?: boolean;
+    /** Optional tag filter (AND semantics). Empty or missing matches all. (libpetri 1.6.0+) */
+    readonly tagFilter?: Readonly<Record<string, string>>;
 } | {
     readonly type: 'seek';
     readonly sessionId: string;
@@ -94,6 +96,12 @@ interface SessionSummary {
     readonly startTime: string;
     readonly active: boolean;
     readonly eventCount: number;
+    /** User-defined session tags. Empty object if none. (libpetri 1.6.0+) */
+    readonly tags?: Readonly<Record<string, string>>;
+    /** ISO-8601 end time, present only for completed sessions. (libpetri 1.6.0+) */
+    readonly endTime?: string;
+    /** Session duration in milliseconds, present only for completed sessions. (libpetri 1.6.0+) */
+    readonly durationMs?: number;
 }
 interface TokenInfo {
     readonly id: string | null;
@@ -320,6 +328,15 @@ interface DebugSession {
     readonly startTime: number;
     readonly active: boolean;
     readonly importedStructure: NetStructure | null;
+    /** Stamped on first `complete()`. Undefined while the session is active. (libpetri 1.6.0+) */
+    readonly endTime?: number;
+    /**
+     * Per-session tag storage, mutated in place by the registry. The reference is
+     * readonly but the underlying object is not — prefer
+     * {@link DebugSessionRegistry.tag}/{@link DebugSessionRegistry.tagsFor}
+     * over direct access.
+     */
+    readonly tags: Record<string, string>;
 }
 /** Builds the net structure from a session's stored place and transition info. */
 declare function buildNetStructure(session: DebugSession): NetStructure;
@@ -333,26 +350,54 @@ declare class DebugSessionRegistry {
     /**
      * 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: string, net: PetriNet): DebugSession;
+    register(sessionId: string, net: PetriNet, tags?: Readonly<Record<string, string>>): DebugSession;
     /**
      * 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: string): void;
-    /** Removes a session from the registry. */
+    /** Removes a session from the registry. Tags die with the session. */
     remove(sessionId: string): DebugSession | undefined;
     /** Returns a session by ID. */
     getSession(sessionId: string): DebugSession | undefined;
+    /**
+     * 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: string, key: string, value: string): void;
+    /**
+     * 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: string): Readonly<Record<string, string>>;
     /** Lists sessions, ordered by start time (most recent first). */
-    listSessions(limit: number): readonly DebugSession[];
+    listSessions(limit: number, tagFilter?: Readonly<Record<string, string>>): readonly DebugSession[];
     /** Lists only active sessions. */
-    listActiveSessions(limit: number): readonly DebugSession[];
+    listActiveSessions(limit: number, tagFilter?: Readonly<Record<string, string>>): readonly DebugSession[];
     /** Total number of sessions. */
     get size(): number;
     /**
      * 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: string, netName: string, dotDiagram: string, structure: NetStructure, eventStore: DebugEventStore, startTime: number): DebugSession;
+    registerImported(sessionId: string, netName: string, dotDiagram: string, structure: NetStructure, eventStore: DebugEventStore, startTime: number, endTime?: number, tags?: Readonly<Record<string, string>>): DebugSession;
+    /** AND-match: all filter entries must exactly match the session's tags. */
+    private matchesTagFilter;
     /** Notifies all completion listeners. Exceptions are caught and logged. */
     private notifyCompletionListeners;
     /** Evicts oldest inactive sessions if at capacity. */
@@ -388,6 +433,7 @@ declare class DebugProtocolHandler {
     /** Handles a command from a connected client. */
     handleCommand(clientId: string, command: DebugCommand): void;
     private handleListSessions;
+    private toProtocolSummary;
     private handleSubscribe;
     private subscribeLive;
     private subscribeReplay;
@@ -468,19 +514,101 @@ declare class DebugAwareEventStore implements EventStore {
 
 /**
  * Metadata header for a session archive file.
+ *
+ * Discriminated union across format versions so callers can pattern-match on
+ * `archive.version` to access v2-only fields with type narrowing:
+ *
+ * ```ts
+ * const archive = reader.readMetadata(bytes);
+ * if (archive.version === 2) {
+ *   console.log(archive.tags, archive.endTime, archive.metadata.hasErrors);
+ * }
+ * ```
+ *
+ * ## Version contract
+ *
+ * - **v1** (libpetri 1.5.x–1.6.x): original format. Header carries `sessionId`,
+ *   `netName`, `dotDiagram`, `startTime`, `eventCount`, and net `structure`.
+ * - **v2** (libpetri 1.7.0+): adds `endTime`, user-defined `tags`, and pre-computed
+ *   {@link SessionMetadata} (event-type histogram, first/last event timestamps,
+ *   hasErrors). Events inside v2 archives are serialized the same way as in v1 —
+ *   only the header is enriched.
+ *
+ * The {@link SessionArchiveReader} peeks the `version` field via a lenient JSON
+ * parse and dispatches to the correct concrete type. Both v1 and v2 archives
+ * remain readable and may coexist in the same storage bucket.
  */
 
-interface SessionArchive {
-    readonly version: number;
+/** Common fields shared by v1 and v2 archive headers. */
+interface SessionArchiveBase {
     readonly sessionId: string;
     readonly netName: string;
     readonly dotDiagram: string;
+    /** ISO-8601 instant the session started. */
     readonly startTime: string;
     readonly eventCount: number;
     readonly structure: NetStructure;
 }
-/** Current archive format version. */
-declare const CURRENT_VERSION = 1;
+/** Legacy v1 archive header (libpetri 1.5.x–1.6.x). */
+interface SessionArchiveV1 extends SessionArchiveBase {
+    readonly version: 1;
+}
+/**
+ * v2 archive header (libpetri 1.7.0+). Adds end time, tags, and pre-computed
+ * metadata so listing tools and samplers can filter/aggregate without scanning
+ * the event body.
+ */
+interface SessionArchiveV2 extends SessionArchiveBase {
+    readonly version: 2;
+    /** ISO-8601 instant the session ended. Undefined for sessions archived while still active. */
+    readonly endTime?: string;
+    /** User-defined session tags (e.g., `{channel: "voice"}`). Always present; may be empty. */
+    readonly tags: Readonly<Record<string, string>>;
+    /** Pre-computed aggregate stats. Always present; `emptyMetadata()` for no-event sessions. */
+    readonly metadata: SessionMetadata;
+}
+/**
+ * Discriminated union of all supported archive header versions.
+ *
+ * Type-narrowing example:
+ * ```ts
+ * if (archive.version === 2) {
+ *   // TS knows archive is SessionArchiveV2 here — tags / endTime / metadata typed.
+ * }
+ * ```
+ */
+type SessionArchive = SessionArchiveV1 | SessionArchiveV2;
+/** Version written by default by {@link SessionArchiveWriter.write} (latest supported). */
+declare const CURRENT_VERSION = 2;
+/**
+ * Pre-computed aggregate statistics attached to a v2 session archive header.
+ *
+ * Computed once during archive write by a single-pass scan of the event store.
+ * Readers can answer `hasErrors`, histogram, and first/last timestamp queries
+ * without iterating the event stream — enabling cheap triage, sampling, and
+ * listing of many archives.
+ *
+ * For v1 archives (no pre-computed metadata), callers can recompute on-demand
+ * via {@link computeMetadata}.
+ */
+interface SessionMetadata {
+    /**
+     * Count of events per `NetEvent` subtype name (PascalCase, matching the
+     * wire format used by `NetEventInfo.type` — e.g. `TransitionStarted -> 412`).
+     * Keys are stored in alphabetical order for deterministic JSON output.
+     */
+    readonly eventTypeHistogram: Readonly<Record<string, number>>;
+    /** ISO-8601 timestamp of the oldest event, or undefined if the session had no events. */
+    readonly firstEventTime?: string;
+    /** ISO-8601 timestamp of the newest event, or undefined if the session had no events. */
+    readonly lastEventTime?: string;
+    /**
+     * True if the session contains at least one error-signal event
+     * (`TransitionFailed`, `TransitionTimedOut`, `ActionTimedOut`, or
+     * a `LogMessage` at level `ERROR`).
+     */
+    readonly hasErrors: boolean;
+}
 
 /**
  * File-system backed storage for session archives.
@@ -501,21 +629,58 @@ declare class FileSessionArchiveStorage implements SessionArchiveStorage {
  * Writes a debug session to a length-prefixed binary archive format.
  *
  * Format (inside gzip):
- * [4 bytes: metadata JSON length][N bytes: metadata JSON]
- * [4 bytes: event JSON length][N bytes: event JSON]
+ * `[4 bytes: metadata JSON length][N bytes: metadata JSON]`
+ * `[4 bytes: event JSON length][N bytes: event JSON]`
  * ...
  * (EOF terminates the stream)
+ *
+ * ## Format selection
+ *
+ * `write()` defaults to {@link CURRENT_VERSION} (v2 as of libpetri 1.7.0).
+ * Callers that need to emit legacy archives — compatibility tests or readers
+ * pinned to libpetri ≤ 1.6.1 — can call `writeV1()`. v2 archives cost one extra
+ * pass over the event store to pre-compute {@link SessionMetadata}; the savings
+ * at read time (no event scan needed for hasErrors / histogram queries) pay it
+ * back the first time a caller lists or samples a bucket of sessions.
  */
 
 declare class SessionArchiveWriter {
     /**
-     * Writes a complete session archive and returns the compressed bytes.
+     * Writes a complete session archive in the current format (v2 as of 1.7.0)
+     * and returns the compressed bytes.
      */
     write(session: DebugSession): Buffer;
+    /**
+     * 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: DebugSession): Buffer;
+    /**
+     * 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: DebugSession): Buffer;
+    /**
+     * 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.
+     */
+    private writeFramed;
 }
 
 /**
  * Reads session archives from length-prefixed binary format.
+ *
+ * Handles both v1 (libpetri 1.5.x–1.6.x) and v2 (libpetri 1.7.0+) archives via
+ * a lenient "version probe": parse the header JSON once, switch on the
+ * `version` field, narrow to the correct concrete type, and normalize missing
+ * optional fields to their defaults. Events inside the body use the same wire
+ * format across versions, so the event read path is shared.
  */
 
 interface ImportedSession {

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 = 2;
+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,25 @@ 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()
+      };
+    }
+    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;
@@ -341,8 +357,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 +375,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 +384,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 +410,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 +447,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 +462,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) {
@@ -754,15 +818,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 +1095,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 +1507,105 @@ 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 (v2 as of 1.7.0)
+   * and returns the compressed bytes.
    */
   write(session) {
-    const structure = buildNetStructure(session);
-    const metadata = {
-      version: CURRENT_VERSION,
+    return this.writeV2(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);
+  }
+  /**
+   * 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 +1616,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));
   }
 };