libpetri 1.5.1 → 1.8.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-D-GN9g_D.js';
+import { E as EventStore, N as NetEvent } from '../event-store-BnyHh3TF.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,11 +96,29 @@ 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;
     readonly type: string;
+    /**
+     * `String(value)` form — stable display field that the bundled debug UI relies on.
+     * Always populated unless compact mode strips values.
+     */
     readonly value: string | null;
+    /**
+     * Structured JSON representation of the token value when the value is a plain
+     * JSON-friendly object / enum-like string / primitive. Populated alongside `value`
+     * (not instead of) so LLM-facing consumers can project typed fields without parsing
+     * the stringified form. Omitted from the wire when absent.
+     * (libpetri 1.8.0+)
+     */
+    readonly structured?: unknown;
     readonly timestamp: string | null;
 }
 interface NetEventInfo {
@@ -320,6 +340,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 +362,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 +445,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;
@@ -441,7 +499,23 @@ declare class MarkingCache {
 
 /** Converts a NetEvent to a serializable NetEventInfo. */
 declare function toEventInfo(event: NetEvent, compact?: boolean): NetEventInfo;
-/** Converts a Token to serializable TokenInfo with full value. */
+/**
+ * Converts a Token to a serializable {@link TokenInfo}.
+ *
+ * @remarks
+ * The emitted `type` is `value.constructor.name` for objects and `typeof value`
+ * for primitives — a *simple name*, not a fully-qualified type identifier.
+ * TypeScript has no portable FQN, so cross-language replay from TypeScript
+ * archives into a Java reader loses the original type identity (Java's
+ * `Class.forName` will fail on simple names) and falls through to the
+ * `Token<JsonNode>` graceful-degradation path. The `structured` payload
+ * survives intact across languages.
+ *
+ * The v3 archive body format described in [EVT-025](../../../spec/08-events-observability.md)
+ * always emits `structured` alongside `value` so the bundled debug UI keeps
+ * rendering while LLM-facing consumers get typed fields. See {@link structuredValue}
+ * for the projection rules.
+ */
 declare function tokenInfo(token: Token<unknown>): TokenInfo;
 /** Converts a Token to compact TokenInfo (type only, no value). */
 declare function compactTokenInfo(token: Token<unknown>): TokenInfo;
@@ -468,19 +542,115 @@ 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.x): adds `endTime`, user-defined `tags`, and pre-computed
+ *   {@link SessionMetadata}. Events inside v2 archives use the legacy `toString`-based
+ *   token format — types are erased on disk.
+ * - **v3** (libpetri 1.8.0+): same header shape as v2. Differs in the event body —
+ *   token values are serialized with a `structured` JSON payload in addition to the
+ *   legacy `value` string, so consumers that understand the original shape can
+ *   surface typed fields without parsing the `toString` form.
+ *
+ * The {@link SessionArchiveReader} peeks the `version` field via a lenient JSON
+ * parse and dispatches to the correct concrete type. All three versions 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;
+}
+/**
+ * v3 archive header (libpetri 1.8.0+). Structurally identical to `SessionArchiveV2`;
+ * the version bump signals that the event body carries `structured` token payloads
+ * alongside the legacy `value` string.
+ */
+interface SessionArchiveV3 extends SessionArchiveBase {
+    readonly version: 3;
+    readonly endTime?: string;
+    readonly tags: Readonly<Record<string, string>>;
+    readonly metadata: SessionMetadata;
+}
+/**
+ * Discriminated union of all supported archive header versions.
+ *
+ * Type-narrowing example:
+ * ```ts
+ * if (archive.version >= 2) {
+ *   // TS knows archive has tags / endTime / metadata here.
+ * }
+ * ```
+ */
+type SessionArchive = SessionArchiveV1 | SessionArchiveV2 | SessionArchiveV3;
+/** Version written by default by {@link SessionArchiveWriter.write} (latest supported). */
+declare const CURRENT_VERSION = 3;
+/**
+ * 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 +671,73 @@ 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} (v3 as of libpetri 1.8.0).
+ * Callers that need to emit legacy archives — compatibility tests or readers
+ * pinned to older libpetri versions — can call `writeV1()` or `writeV2()`.
+ *
+ * Note: all writers now emit the v3 token body format (structured alongside
+ * value-string) regardless of header version. A 1.8.0+ writer cannot produce
+ * byte-for-byte 1.7.x event bodies.
+ *
+ * Cross-language note: the `type` field in each serialized `TokenInfo` is
+ * `value.constructor.name` — a simple name, not an FQN. Replaying a TypeScript
+ * archive through the Java reader therefore cannot reconstruct the original
+ * typed token (Java needs an FQN to `Class.forName`); Java falls through to
+ * `Token<JsonNode>` preserving the `structured` JSON payload. See
+ * {@link tokenInfo} for the full asymmetry and the [EVT-025](../../../../spec/08-events-observability.md)
+ * spec entry for the full wire-format contract.
  */
 
 declare class SessionArchiveWriter {
     /**
-     * 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: 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;
+    /**
+     * 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: 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 {