libpetri 2.12.1 → 3.0.0

package/README.md

@@ -1,172 +1,83 @@
-# libpetri
+# libpetri for TypeScript
 
-TypeScript implementation of a **Coloured Time Petri Net** (CTPN) engine with bitmap-based execution, formal verification via Z3, and DOT/Graphviz visualization.
+[![npm](https://img.shields.io/npm/v/libpetri)](https://www.npmjs.com/package/libpetri)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6-blue)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](https://github.com/debe/libpetri/blob/main/LICENSE)
 
-## Architecture
+The TypeScript 6 implementation of libpetri: typed Coloured Time Petri Nets for Promise-based applications, with modular composition, two execution backends, observability, DOT export, and formal verification.
 
-```
-src/
-├── core/          # Net definition: places, transitions, arcs, timing, output specs
-├── runtime/       # Async bitmap-based executor, marking, compiled net
-├── event/         # Event store and net event types (discriminated union)
-├── export/        # DOT (Graphviz) diagram exporter
-└── verification/  # SMT-based property verification (Z3)
-```
-
-### Core (`src/core/`)
-
-Immutable net definitions with typed, colored tokens.
-
-| Type | Description |
-|------|-------------|
-| `Place<T>` | Typed token container (phantom type for compile-time safety) |
-| `EnvironmentPlace<T>` | External event injection point |
-| `Transition` | Arc specs, timing, priority, guards, action binding |
-| `PetriNet` | Immutable net definition; `bindActions()` separates structure from runtime behavior |
-| `Out` | Discriminated union for output specs: `and`, `xor`, `place`, `timeout`, `forward-input` |
-| `In` | Input arc specs with cardinality: `one`, `exactly`, `all`, `at-least` |
-| `Timing` | TPN firing intervals: `immediate`, `deadline`, `delayed`, `window`, `exact` |
-| `TransitionAction` | `(ctx: TransitionContext) => Promise<void>` — async action bound to a transition |
-
-### Runtime (`src/runtime/`)
-
-Async single-threaded executor using bitmap-based enablement tracking.
-
-| Type | Description |
-|------|-------------|
-| `BitmapNetExecutor` | Main executor — dirty-set tracking, priority scheduling, deadline enforcement |
-| `CompiledNet` | Precomputed bitmap masks and reverse indices for O(W) enablement checks |
-| `Marking` | Mutable FIFO token state per place |
-
-Key performance features:
-- `Uint32Array` bitmaps for place marking and transition dirty sets
-- Kernighan's bit-trick for dirty set iteration
-- Pre-allocated buffers to reduce GC pressure
-- Precomputed reverse index (place → affected transitions)
-
-### Event (`src/event/`)
-
-Observable execution events as a discriminated union (`NetEvent`).
-
-Event types: `execution-started`, `execution-completed`, `transition-enabled`, `transition-started`, `transition-completed`, `transition-failed`, `transition-timed-out`, `action-timed-out`, `token-added`, `token-removed`, `log-message`, `marking-snapshot`.
-
-`InMemoryEventStore` captures events; `noopEventStore()` is a zero-cost singleton for production.
-
-### Export (`src/export/`)
-
-`dotExport(net, config)` generates DOT (Graphviz) diagram syntax with proper Petri net visual conventions, including arc types (inhibitor, read, reset), timing annotations, and priority labels.
-
-### Verification (`src/verification/`)
+See the [project README](https://github.com/debe/libpetri#why-a-petri-net) for the motivation and an order workflow using every arc type, concurrent actions, and timeout routing.
 
-SMT-based formal verification using Z3. Encodes the Petri net as an integer linear program and checks reachability properties.
+## Install
 
-Supported properties:
-- **Deadlock freedom** — no reachable state where all transitions are disabled
-- **Mutual exclusion** — two places never both hold tokens simultaneously
-- **Place bounds** — token count in a place never exceeds a limit
-- **Unreachability** — a marking is never reachable
-
-Also computes **P-invariants** (Farkas variant) and supports IC3/PDR-style incremental verification.
-
-### ν-nets (`src/runtime/`)
+```bash
+npm install libpetri
+```
 
-Correlated fork/join by identity. A `MatchSpec` declares a `value → NameId` key projection over a transition's input places; a fork mints a fresh opaque name via `ctx.freshName()` into the token payload, and a join consumes only the sibling tokens that project to the same name. The deterministic `(oldest-timestamp, then name)` tie-break is byte-identical across implementations (NU-022), and an incremental matcher keeps correlated-join drain at O(N log N). A bounded `Budget` place is the decidability lever for verification.
+libpetri is ESM-only. The core runtime has no browser-only assumption; optional viewer and documentation entry points declare their own peer dependencies.
 
-## Quick Start
+## Quick start
 
 ```typescript
-import { place, PetriNet, Transition, one, outPlace, tokenOf, BitmapNetExecutor } from 'libpetri';
+import {
+  BitmapNetExecutor, PetriNet, Transition,
+  one, outPlace, place, tokenOf,
+} from 'libpetri';
 
-// Define places
 const input = place<string>('input');
 const output = place<string>('output');
 
-// Define transition
-const process = Transition.builder('process')
+const uppercase = Transition.builder('uppercase')
   .inputs(one(input))
   .outputs(outPlace(output))
   .action(async (ctx) => {
-    const value = ctx.input(input);
-    ctx.output(output, value.toUpperCase());
+    ctx.output(output, ctx.input(input).toUpperCase());
   })
   .build();
 
-// Build net
-const net = PetriNet.builder('Example').transition(process).build();
-
-// Execute
+const net = PetriNet.builder('example').transition(uppercase).build();
 const executor = new BitmapNetExecutor(
   net,
   new Map([[input, [tokenOf('hello')]]]),
 );
-const marking = await executor.run();
-console.log(marking.peekTokens(output)); // [Token { value: 'HELLO' }]
-```
 
-## Modular composition
-
-Build large nets by reusing open-net fragments. A `SubnetDef` is a structurally
-complete `PetriNet` plus a typed `Interface` of **ports** (typed places) and
-**channels** (transitions). Instantiating renames every internal element with a
-`prefix/name`; composing into a host substitutes port places and merges
-channel transitions.
+const result = await executor.run();
+console.log(result.peekFirst(output)?.value); // HELLO
+```
 
-```typescript
-import { PetriNet, SubnetDef, FusionSet, place } from 'libpetri';
-
-const items = place<string>('items');
-const slots = place<string>('slots');
-const put = place<string>('put');
-const get = place<string>('get');
-
-const buffer = SubnetDef.builder<void>('Buffer')
-  .place(items).place(slots)
-  .transition(enqueue).transition(dequeue)
-  .inputPort('put', put)
-  .outputPort('get', get)
-  .build();
+## Execution and concurrency
 
-const b1 = buffer.instantiate('b1').bindActions({ enqueue: enqueueImpl, dequeue: fork() });
-const b2 = buffer.instantiate('b2').bindActions({ enqueue: enqueueImpl, dequeue: fork() });
+`BitmapNetExecutor` is the reference implementation. `PrecompiledNetExecutor` compiles the same net into flat arrays, opcode streams, and priority-partitioned ready queues for production hot paths.
 
-const producerToB1 = place<string>('p1_to_b1');
-const b1ToB2 = place<string>('b1_to_b2');
-const b2ToConsumer = place<string>('b2_to_c');
+The orchestrator owns the marking and invokes ready actions without awaiting earlier actions first. Promise continuations therefore overlap naturally, while marking updates remain serialized. CPU-heavy synchronous code still blocks the JavaScript event loop; move it to a worker or external service.
 
-const net = PetriNet.builder('Pipeline')
-  .compose(b1, (bind) =>
-    bind.bindPort('put', producerToB1).bindPort('get', b1ToB2))
-  .compose(b2, (bind) =>
-    bind.bindPort('put', b1ToB2).bindPort('get', b2ToConsumer))
-  .fuse(FusionSet.of('sharedSlots', b1.port<string>('slots'), b2.port<string>('slots')))
-  .build();
-```
+Use places and transitions for coordination rather than hiding concurrency inside `Promise.all`: the net can then visualize, trace, replay, and verify the fan-out and join.
 
-Composition produces a flat `PetriNet`. Ports merge places by structural
-rewrite; channels (`bindChannel`) merge transitions with arc union, timing
-intersection, and caller-wins identity. `FusionSet` declares N-ary place
-equivalence applied **after** all `compose(...)` calls, regardless of
-registration order. Per-instance action overrides are supplied via
-`Instance.bindActions({ originalName: action })`. See
-[`spec/11-modular-composition.md`](../spec/11-modular-composition.md).
+## Package entry points
 
-## Verification Example
+| Import | Purpose |
+|---|---|
+| `libpetri` | Core model, runtime, events, and composition |
+| `libpetri/export` | DOT mapping and rendering |
+| `libpetri/verification` | Structural analysis, state classes, and Z3-backed SMT verification |
+| `libpetri/debug` | Debug protocol and session archives |
+| `libpetri/viewer` | Interactive DOT/SVG viewer |
+| `libpetri/doclet` | TypeDoc integration |
 
-```typescript
-import { SmtVerifier, deadlockFree } from 'libpetri/verification';
+The model supports input, output, read, inhibitor, and reset arcs; immediate, deadline, delayed, window, and exact timing; AND/XOR/timeout routing; environment places; reusable subnets; place fusion; and ν-net identity correlation.
 
-const result = await SmtVerifier.forNet(net)
-  .initialMarking(m => m.tokens(input, 1))
-  .property(deadlockFree())
-  .verify();
+## Build and test
 
-console.log(result.verdict); // { type: 'proven', method: 'structural' }
+```bash
+npm install
+npm run build
+npm run check
+npm test
 ```
 
-## Build & Test
+## Project links
 
-```bash
-npm run build    # Build with tsup
-npm run check    # Type-check with tsc --noEmit
-npm test         # Run tests with vitest
-```
+- [Language-agnostic specification](https://github.com/debe/libpetri/blob/main/spec/00-index.md)
+- [Lean soundness and backend-refinement proofs](https://github.com/debe/libpetri/blob/main/lean/README.md)
+- [Changelog](https://github.com/debe/libpetri/blob/main/CHANGELOG.md)
+- [Apache License 2.0](https://github.com/debe/libpetri/blob/main/LICENSE)

package/dist/{chunk-V3WTQRHC.js → chunk-5W6SVYPD.js}

@@ -3,6 +3,55 @@ import {
   latest
 } from "./chunk-ATT7U5H5.js";
 
+// src/core/in.ts
+function one(place) {
+  return { type: "one", place };
+}
+function exactly(count, place) {
+  if (count < 1) {
+    throw new Error(`count must be >= 1, got: ${count}`);
+  }
+  return { type: "exactly", place, count };
+}
+function all(place) {
+  return { type: "all", place };
+}
+function atLeast(minimum, place) {
+  if (minimum < 1) {
+    throw new Error(`minimum must be >= 1, got: ${minimum}`);
+  }
+  return { type: "at-least", place, minimum };
+}
+function requiredCount(spec) {
+  switch (spec.type) {
+    case "one":
+      return 1;
+    case "exactly":
+      return spec.count;
+    case "all":
+      return 1;
+    case "at-least":
+      return spec.minimum;
+  }
+}
+function consumptionCount(spec, available) {
+  if (available < requiredCount(spec)) {
+    throw new Error(
+      `Cannot consume from '${spec.place.name}': available=${available}, required=${requiredCount(spec)}`
+    );
+  }
+  switch (spec.type) {
+    case "one":
+      return 1;
+    case "exactly":
+      return spec.count;
+    case "all":
+      return available;
+    case "at-least":
+      return available;
+  }
+}
+
 // src/core/out.ts
 function and(...children) {
   if (children.length === 0) {
@@ -97,6 +146,80 @@ function crossProduct(a, b) {
   return result;
 }
 
+// src/core/transition-action.ts
+function passthrough() {
+  return PASSTHROUGH;
+}
+var PASSTHROUGH = async () => {
+};
+function isPassthrough(action) {
+  return action === PASSTHROUGH;
+}
+function transform(fn) {
+  return async (ctx) => {
+    const result = fn(ctx);
+    for (const outputPlace of ctx.outputPlaces()) {
+      ctx.output(outputPlace, result);
+    }
+  };
+}
+function fork() {
+  return transform((ctx) => {
+    const inputPlaces = ctx.inputPlaces();
+    if (inputPlaces.size !== 1) {
+      throw new Error(`Fork requires exactly 1 input place, found ${inputPlaces.size}`);
+    }
+    const inputPlace = inputPlaces.values().next().value;
+    return ctx.input(inputPlace);
+  });
+}
+function transformFrom(inputPlace, fn) {
+  return transform((ctx) => fn(ctx.input(inputPlace)));
+}
+function transformAsync(fn) {
+  return async (ctx) => {
+    const result = await fn(ctx);
+    for (const outputPlace of ctx.outputPlaces()) {
+      ctx.output(outputPlace, result);
+    }
+  };
+}
+function produce(place, value) {
+  return async (ctx) => {
+    ctx.output(place, value);
+  };
+}
+function withTimeout(action, timeoutMs, timeoutPlace2, timeoutValue) {
+  return (ctx) => {
+    return new Promise((resolve, reject) => {
+      let completed = false;
+      const timer = setTimeout(() => {
+        if (!completed) {
+          completed = true;
+          ctx.output(timeoutPlace2, timeoutValue);
+          resolve();
+        }
+      }, timeoutMs);
+      action(ctx).then(
+        () => {
+          if (!completed) {
+            completed = true;
+            clearTimeout(timer);
+            resolve();
+          }
+        },
+        (err) => {
+          if (!completed) {
+            completed = true;
+            clearTimeout(timer);
+            reject(err);
+          }
+        }
+      );
+    });
+  };
+}
+
 // src/verification/marking-state.ts
 var MARKING_STATE_KEY = /* @__PURE__ */ Symbol("MarkingState.internal");
 var MarkingState = class _MarkingState {
@@ -1400,6 +1523,17 @@ var StateClass = class {
   }
 };
 
+// src/core/internal/output-action-check.ts
+function requireOutputProducingActions(net) {
+  for (const t of net.transitions) {
+    if (t.outputSpec !== null && isPassthrough(t.action)) {
+      throw new Error(
+        `Transition '${t.name}' declares an output spec but carries passthrough(), which produces no tokens. Every firing would fail output validation (IO-015) and the declared output would never arrive. Bind an action that produces it \u2014 fork() moves the input token across \u2014 or drop the output spec if the transition is meant to be a sink.`
+      );
+    }
+  }
+}
+
 // src/verification/analysis/state-class-graph.ts
 var StateClassGraph = class _StateClassGraph {
   net;
@@ -1430,8 +1564,13 @@ var StateClassGraph = class _StateClassGraph {
       }
     }
   }
-  /** Builds the state class graph for a Time Petri Net. */
+  /**
+   * Builds the state class graph for a Time Petri Net.
+   *
+   * @throws Error if the net violates CORE-043 — analysis rejects the same nets execution rejects.
+   */
   static build(net, initialMarking, maxClasses, environmentPlaces, environmentMode) {
+    requireOutputProducingActions(net);
     const envMode = environmentMode ?? ignore();
     const envPlaces = /* @__PURE__ */ new Set();
     if (environmentPlaces) {
@@ -1644,18 +1783,8 @@ function inputRequiredCount(spec) {
       return spec.minimum;
   }
 }
-function inputConsumeCount(spec) {
-  switch (spec.type) {
-    case "one":
-      return 1;
-    case "exactly":
-      return spec.count;
-    case "all":
-      return 1;
-    // Analysis: consume minimum (1 token)
-    case "at-least":
-      return spec.minimum;
-  }
+function inputConsumeCount(spec, available) {
+  return consumptionCount(spec, available);
 }
 function checkPlaceEnabled(place, required, marking, environmentPlaces, environmentMode) {
   if (!environmentPlaces.has(place)) {
@@ -1673,7 +1802,11 @@ function checkPlaceEnabled(place, required, marking, environmentPlaces, environm
 function fireTransition(marking, transition, outputPlaces, environmentPlaces, environmentMode) {
   const builder = MarkingState.builder().copyFrom(marking);
   for (const spec of transition.inputSpecs) {
-    const toConsume = inputConsumeCount(spec);
+    const available = marking.tokens(spec.place);
+    if (available < inputRequiredCount(spec)) {
+      continue;
+    }
+    const toConsume = inputConsumeCount(spec, available);
     consumeFromPlace(builder, spec.place, toConsume, environmentPlaces, environmentMode);
   }
   for (const arc of transition.resets) {
@@ -2298,11 +2431,11 @@ var NameMarking = class _NameMarking {
     return syms ? [...syms.keys()] : [];
   }
   liveSymbols() {
-    const all = /* @__PURE__ */ new Set();
+    const all2 = /* @__PURE__ */ new Set();
     for (const syms of this.perPlace.values()) {
-      for (const s of syms.keys()) all.add(s);
+      for (const s of syms.keys()) all2.add(s);
     }
-    return [...all];
+    return [...all2];
   }
   /**
    * Symmetry-canonical key over `colouredOrder` (the finiteness mechanism). Two
@@ -2775,8 +2908,11 @@ var SmtVerifier = class _SmtVerifier {
   }
   /**
    * Runs the verification pipeline.
+   *
+   * @throws Error if the net violates CORE-043 — verification rejects the same nets execution rejects.
    */
   async verify() {
+    requireOutputProducingActions(this.net);
     const start = performance.now();
     const report = [];
     report.push("=== IC3/PDR SAFETY VERIFICATION ===\n");
@@ -2982,7 +3118,7 @@ var SmtVerifier = class _SmtVerifier {
           report.push("=== RESULT ===\n");
           report.push(`PROVEN (IC3/PDR): ${propDesc}`);
           report.push("  Z3 Spacer proved no reachable state violates the property.");
-          report.push("  NOTE: Verification ignores timing constraints and JS guards.");
+          report.push("  NOTE: Verification ignores timing constraints.");
           report.push("  An untimed proof is STRONGER than a timed one (timing only restricts behavior).");
           return this.applyNuGuard(buildResult(
             {
@@ -3015,7 +3151,6 @@ var SmtVerifier = class _SmtVerifier {
           }
           report.push("\n  WARNING: This counterexample is in UNTIMED semantics.");
           report.push("  It may be spurious if timing constraints prevent this sequence.");
-          report.push("  JS guards are also ignored in this analysis.");
           return this.applyNuGuard(buildResult(
             { type: "violated" },
             report.join("\n"),
@@ -3159,6 +3294,12 @@ function isViolated(result) {
 }
 
 export {
+  one,
+  exactly,
+  all,
+  atLeast,
+  requiredCount,
+  consumptionCount,
   and,
   andPlaces,
   xor,
@@ -3169,6 +3310,14 @@ export {
   forwardInput,
   allPlaces,
   enumerateBranches,
+  passthrough,
+  isPassthrough,
+  transform,
+  fork,
+  transformFrom,
+  transformAsync,
+  produce,
+  withTimeout,
   MarkingState,
   MarkingStateBuilder,
   deadlockFree,
@@ -3199,10 +3348,11 @@ export {
   encode,
   DBM,
   StateClass,
+  requireOutputProducingActions,
   StateClassGraph,
   decode,
   SmtVerifier,
   isProven,
   isViolated
 };
-//# sourceMappingURL=chunk-V3WTQRHC.js.map
+//# sourceMappingURL=chunk-5W6SVYPD.js.map