libpetri 2.13.0 → 3.0.1

package/README.md

@@ -1,172 +1,131 @@
-# 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/`)
+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.
 
-Observable execution events as a discriminated union (`NetEvent`).
+## Install
 
-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/`)
-
-SMT-based formal verification using Z3. Encodes the Petri net as an integer linear program and checks reachability properties.
-
-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' }]
+
+const result = await executor.run();
+console.log(result.peekFirst(output)?.value); // HELLO
 ```
 
-## Modular composition
+## Execution and concurrency
+
+`BitmapNetExecutor` is the reference implementation. `PrecompiledNetExecutor` compiles the same net into flat arrays, opcode streams, and priority-partitioned ready queues for production hot paths.
+
+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.
+
+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.
 
-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.
+## Package entry points
+
+| 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, the canonical renderer |
+| `libpetri/render-dom` | Thin compatibility wrapper over `libpetri/viewer` |
+| `libpetri/doclet` | TypeDoc integration |
+
+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.
+
+## Visualization
+
+`libpetri/viewer` is the canonical renderer. It lays nodes out with ELK, routes edges orthogonally, and draws the result through Graphviz `nop2`, then adds pan/zoom, cluster collapse, subnet toggling, and filtering. Every first-party surface uses it: the debug UI, the TypeDoc plugin here, the Java javadoc taglet, and the Rust docgen all embed the same bundle, so a net looks the same whichever port documented it.
 
 ```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();
+import { dotExport } from 'libpetri/export';
+import { mount } from 'libpetri/viewer';
 
-const b1 = buffer.instantiate('b1').bindActions({ enqueue: enqueueImpl, dequeue: fork() });
-const b2 = buffer.instantiate('b2').bindActions({ enqueue: enqueueImpl, dequeue: fork() });
+const handle = await mount(dotExport(net), document.getElementById('diagram')!, {
+  chrome: true,
+});
+handle.fit();
+```
 
-const producerToB1 = place<string>('p1_to_b1');
-const b1ToB2 = place<string>('b1_to_b2');
-const b2ToConsumer = place<string>('b2_to_c');
+The viewer is browser-only and declares `@viz-js/viz`, `panzoom`, and `elkjs` as optional peer dependencies, so a headless runtime install does not pull in a rendering stack. Install all three wherever you mount it:
 
-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();
+```bash
+npm install @viz-js/viz panzoom elkjs
 ```
 
-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).
+Without `elkjs` the default layout throws and names the missing peer; `mount(dot, el, { layout: 'graphviz' })` falls back to stock Graphviz layout, which is the one supported way to render without it.
 
-## Verification Example
+Not every path through the package produces the same picture:
 
-```typescript
-import { SmtVerifier, deadlockFree } from 'libpetri/verification';
+| Path | Layout | Edges |
+|---|---|---|
+| `mount()` from `libpetri/viewer` | ELK placement, ELK routes via `nop2` | orthogonal |
+| `renderDotToContainer()` from `libpetri/render-dom` | delegates to `mount()` | orthogonal |
+| the TypeDoc plugin | embeds the viewer, mounts client-side | orthogonal |
+| `dotToSvg()` from `libpetri/doclet` | stock Graphviz `dot` | diagonal splines |
+| `dotExport()` piped to your own `dot -Tsvg` | stock Graphviz `dot` | diagonal splines |
+
+If a diagram renders with diagonal edges where you expected right angles, it went through one of the bottom two rows, or through a viewer bundle older than 2.10.5. Generated doc pages record which one drew them in `data-libpetri-viewer` on the diagram container.
 
-const result = await SmtVerifier.forNet(net)
-  .initialMarking(m => m.tokens(input, 1))
-  .property(deadlockFree())
-  .verify();
+### TypeDoc plugin
 
-console.log(result.verdict); // { type: 'proven', method: 'structural' }
+Register the plugin and declare the block tag it reads:
+
+```json
+{
+  "plugin": ["libpetri/doclet"],
+  "blockTags": ["@petrinet"]
+}
 ```
 
-## Build & Test
+An `@petrinet` tag on a symbol that builds or exposes a net renders that net as a diagram in the generated page, with the DOT source in a collapsible block underneath. The viewer bundle is inlined into the HTML, so the output is self-contained and works offline with no `dot` binary and no network access.
+
+## Build and test
 
 ```bash
-npm run build    # Build with tsup
-npm run check    # Type-check with tsc --noEmit
-npm test         # Run tests with vitest
+npm install
+npm run build
+npm run check
+npm test
 ```
+
+## Project links
+
+- [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)