libpetri 2.13.0 → 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-7VJ5CYUU.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) {
@@ -1734,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)) {
@@ -1763,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) {
@@ -2388,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
@@ -3075,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(
             {
@@ -3108,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"),
@@ -3252,6 +3294,12 @@ function isViolated(result) {
 }
 
 export {
+  one,
+  exactly,
+  all,
+  atLeast,
+  requiredCount,
+  consumptionCount,
   and,
   andPlaces,
   xor,
@@ -3307,4 +3355,4 @@ export {
   isProven,
   isViolated
 };
-//# sourceMappingURL=chunk-7VJ5CYUU.js.map
+//# sourceMappingURL=chunk-5W6SVYPD.js.map