libpetri 1.7.0 → 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-DrTpTRNy.js';
-import { E as EventStore, N as NetEvent } from '../event-store-DePCZb33.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.
@@ -106,7 +106,19 @@ interface SessionSummary {
 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 {
@@ -487,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;
@@ -529,14 +557,17 @@ declare class DebugAwareEventStore implements EventStore {
  *
  * - **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.
+ * - **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. Both v1 and v2 archives
- * remain readable and may coexist in the same storage bucket.
+ * parse and dispatches to the correct concrete type. All three versions coexist
+ * in the same storage bucket.
  */
 
 /** Common fields shared by v1 and v2 archive headers. */
@@ -567,19 +598,30 @@ interface SessionArchiveV2 extends SessionArchiveBase {
     /** 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 is SessionArchiveV2 here — tags / endTime / metadata typed.
+ * if (archive.version >= 2) {
+ *   // TS knows archive has tags / endTime / metadata here.
  * }
  * ```
  */
-type SessionArchive = SessionArchiveV1 | SessionArchiveV2;
+type SessionArchive = SessionArchiveV1 | SessionArchiveV2 | SessionArchiveV3;
 /** Version written by default by {@link SessionArchiveWriter.write} (latest supported). */
-declare const CURRENT_VERSION = 2;
+declare const CURRENT_VERSION = 3;
 /**
  * Pre-computed aggregate statistics attached to a v2 session archive header.
  *
@@ -636,17 +678,26 @@ declare class FileSessionArchiveStorage implements SessionArchiveStorage {
  *
  * ## Format selection
  *
- * `write()` defaults to {@link CURRENT_VERSION} (v2 as of libpetri 1.7.0).
+ * `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 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.
+ * 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 in the current format (v2 as of 1.7.0)
+     * Writes a complete session archive in the current format (v3 as of 1.8.0)
      * and returns the compressed bytes.
      */
     write(session: DebugSession): Buffer;
@@ -665,6 +716,12 @@ declare class SessionArchiveWriter {
      * 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

package/dist/debug/index.js

@@ -118,7 +118,7 @@ var DebugEventStore = class {
 };
 
 // src/debug/archive/session-archive.ts
-var CURRENT_VERSION = 2;
+var CURRENT_VERSION = 3;
 var MIN_SUPPORTED_VERSION = 1;
 function emptyMetadata() {
   return { eventTypeHistogram: {}, hasErrors: false };
@@ -174,6 +174,14 @@ function parseHeader(metaJson) {
         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})`
@@ -238,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
@@ -710,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;
@@ -1548,11 +1572,11 @@ function isErrorEvent(event) {
 // src/debug/archive/session-archive-writer.ts
 var SessionArchiveWriter = class {
   /**
-   * Writes a complete session archive in the current format (v2 as of 1.7.0)
+   * Writes a complete session archive in the current format (v3 as of 1.8.0)
    * and returns the compressed bytes.
    */
   write(session) {
-    return this.writeV2(session);
+    return this.writeV3(session);
   }
   /**
    * Writes a session in the legacy v1 format. Use only for compatibility
@@ -1598,6 +1622,27 @@ var SessionArchiveWriter = class {
     };
     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