libpetri 1.8.5 → 2.1.0

package/dist/petri-net-BDrj4XZE.d.ts

@@ -0,0 +1,1461 @@
+/**
+ * An immutable token carrying a typed value through the Petri net.
+ *
+ * Tokens flow from place to place as transitions fire, carrying typed
+ * payloads that represent the state of a computation or workflow.
+ */
+interface Token<T> {
+    readonly value: T;
+    /** Epoch milliseconds when the token was created. */
+    readonly createdAt: number;
+    /**
+     * JSON-friendly projection of the token value, populated by
+     * {@link SessionArchiveReader} when hydrating a v3 archive so replay
+     * consumers see the same structured shape the writer emitted. Live tokens
+     * (produced by {@link tokenOf} / {@link tokenAt}) leave this `undefined`;
+     * the runtime ignores it. See [EVT-025](../../../spec/08-events-observability.md)
+     * AC5. (libpetri 1.8.0+)
+     */
+    readonly structured?: unknown;
+}
+/** Creates a token with the given value and current timestamp. */
+declare function tokenOf<T>(value: T): Token<T>;
+/**
+ * Returns a unit token (marker with no meaningful value).
+ * Used for pure control flow where presence matters but data doesn't.
+ * Returns a cached singleton whose `value` is `null`.
+ */
+declare function unitToken(): Token<null>;
+/** Creates a token with a specific timestamp (for testing/replay). */
+declare function tokenAt<T>(value: T, createdAt: number): Token<T>;
+/** Checks if this is the singleton unit token. */
+declare function isUnit(token: Token<unknown>): boolean;
+
+/**
+ * A typed place in the Petri Net that holds tokens of a specific type.
+ *
+ * Places are the "state containers" of a Petri net. They hold tokens that
+ * represent data or resources flowing through the net.
+ *
+ * Places use name-based equality (matching Java record semantics).
+ * Internally use `Map<string, ...>` keyed by `place.name` for O(1) lookups.
+ */
+interface Place<T> {
+    readonly name: string;
+    /** Phantom field to carry the type parameter. Never set at runtime. */
+    readonly _phantom?: T;
+}
+/**
+ * An environment place that accepts external token injection.
+ * Wraps a regular Place and marks it for external event injection.
+ */
+interface EnvironmentPlace<T> {
+    readonly place: Place<T>;
+}
+/** Creates a typed place. */
+declare function place<T>(name: string): Place<T>;
+/** Creates an environment place (external event injection point). */
+declare function environmentPlace<T>(name: string): EnvironmentPlace<T>;
+
+/**
+ * Arc types connecting places to transitions in the Petri net.
+ *
+ * | Arc Type  | Requires Token? | Consumes? | Effect                   |
+ * |-----------|-----------------|-----------|--------------------------|
+ * | Input     | Yes             | Yes       | Token consumed on fire   |
+ * | Output    | No              | No        | Token produced on complete|
+ * | Inhibitor | No (blocks)     | No        | Disables transition      |
+ * | Read      | Yes             | No        | Token remains            |
+ * | Reset     | No              | Yes (all) | All tokens removed       |
+ */
+type Arc = ArcInput | ArcOutput | ArcInhibitor | ArcRead | ArcReset;
+interface ArcInput<T = any> {
+    readonly type: 'input';
+    readonly place: Place<T>;
+    readonly guard?: (value: T) => boolean;
+}
+interface ArcOutput<T = any> {
+    readonly type: 'output';
+    readonly place: Place<T>;
+}
+interface ArcInhibitor<T = any> {
+    readonly type: 'inhibitor';
+    readonly place: Place<T>;
+}
+interface ArcRead<T = any> {
+    readonly type: 'read';
+    readonly place: Place<T>;
+}
+interface ArcReset<T = any> {
+    readonly type: 'reset';
+    readonly place: Place<T>;
+}
+/** Input arc: consumes token from place when transition fires. */
+declare function inputArc<T>(place: Place<T>, guard?: (value: T) => boolean): ArcInput<T>;
+/** Output arc: produces token to place when transition fires. */
+declare function outputArc<T>(place: Place<T>): ArcOutput<T>;
+/** Inhibitor arc: blocks transition if place has tokens. */
+declare function inhibitorArc<T>(place: Place<T>): ArcInhibitor<T>;
+/** Read arc: requires token without consuming. */
+declare function readArc<T>(place: Place<T>): ArcRead<T>;
+/** Reset arc: removes all tokens from place when firing. */
+declare function resetArc<T>(place: Place<T>): ArcReset<T>;
+/** Returns the place this arc connects to. */
+declare function arcPlace(arc: Arc): Place<any>;
+/** Checks if an input arc has a guard predicate. */
+declare function hasGuard(arc: ArcInput): boolean;
+/** Checks if a token value matches an input arc's guard. */
+declare function matchesGuard<T>(arc: ArcInput<T>, value: T): boolean;
+
+/**
+ * Input specification with cardinality and optional guard predicate.
+ * CPN-compliant: cardinality determines how many tokens to consume,
+ * guard filters which tokens are eligible.
+ *
+ * Inputs are always AND-joined (all must be satisfied to enable transition).
+ * XOR on inputs is modeled via multiple transitions (conflict).
+ */
+type In = InOne | InExactly | InAll | InAtLeast;
+interface InOne<T = any> {
+    readonly type: 'one';
+    readonly place: Place<T>;
+    readonly guard?: (value: T) => boolean;
+}
+interface InExactly<T = any> {
+    readonly type: 'exactly';
+    readonly place: Place<T>;
+    readonly count: number;
+    readonly guard?: (value: T) => boolean;
+}
+interface InAll<T = any> {
+    readonly type: 'all';
+    readonly place: Place<T>;
+    readonly guard?: (value: T) => boolean;
+}
+interface InAtLeast<T = any> {
+    readonly type: 'at-least';
+    readonly place: Place<T>;
+    readonly minimum: number;
+    readonly guard?: (value: T) => boolean;
+}
+/** Consume exactly 1 token (standard CPN semantics). Optional guard filters eligible tokens. */
+declare function one<T>(place: Place<T>, guard?: (value: T) => boolean): InOne<T>;
+/** Consume exactly N tokens (batching). Optional guard filters eligible tokens. */
+declare function exactly<T>(count: number, place: Place<T>, guard?: (value: T) => boolean): InExactly<T>;
+/** Consume all available tokens (must be 1+). Optional guard filters eligible tokens. */
+declare function all<T>(place: Place<T>, guard?: (value: T) => boolean): InAll<T>;
+/** Wait for N+ tokens, consume all when enabled. Optional guard filters eligible tokens. */
+declare function atLeast<T>(minimum: number, place: Place<T>, guard?: (value: T) => boolean): InAtLeast<T>;
+/** Returns the minimum number of tokens required to enable. */
+declare function requiredCount(spec: In): number;
+/**
+ * Returns the actual number of tokens to consume given the available count.
+ * - One: always consumes 1
+ * - Exactly: always consumes exactly count
+ * - All: consumes all available
+ * - AtLeast: consumes all available (when enabled, i.e., >= minimum)
+ */
+declare function consumptionCount(spec: In, available: number): number;
+
+/**
+ * Output specification with explicit split semantics.
+ * Supports composite structures (XOR of ANDs, AND of XORs, etc.)
+ *
+ * - And: ALL children must receive tokens
+ * - Xor: EXACTLY ONE child receives token
+ * - Place: Leaf node representing a single output place
+ * - Timeout: Timeout branch that activates if action exceeds duration
+ * - ForwardInput: Forward consumed input to output on timeout
+ */
+type Out = OutAnd | OutXor | OutPlace | OutTimeout | OutForwardInput;
+interface OutAnd {
+    readonly type: 'and';
+    readonly children: readonly Out[];
+}
+interface OutXor {
+    readonly type: 'xor';
+    readonly children: readonly Out[];
+}
+interface OutPlace {
+    readonly type: 'place';
+    readonly place: Place<any>;
+}
+interface OutTimeout {
+    readonly type: 'timeout';
+    /** Timeout duration in milliseconds. */
+    readonly afterMs: number;
+    readonly child: Out;
+}
+interface OutForwardInput {
+    readonly type: 'forward-input';
+    readonly from: Place<any>;
+    readonly to: Place<any>;
+}
+/**
+ * AND-split: all children must receive tokens.
+ *
+ * @example
+ * ```ts
+ * // AND of XOR branches: one of (A,B) AND one of (C,D)
+ * and(xorPlaces(placeA, placeB), xorPlaces(placeC, placeD))
+ *
+ * // AND with a fixed place + XOR branch
+ * and(outPlace(always), xorPlaces(left, right))
+ * ```
+ */
+declare function and(...children: Out[]): OutAnd;
+/** AND-split from places: all places must receive tokens. */
+declare function andPlaces(...places: Place<any>[]): OutAnd;
+/** XOR-split: exactly one child receives token. */
+declare function xor(...children: Out[]): OutXor;
+/** XOR-split from places: exactly one place receives token. */
+declare function xorPlaces(...places: Place<any>[]): OutXor;
+/** Leaf output spec for a single place. */
+declare function outPlace(p: Place<any>): OutPlace;
+/** Timeout output: activates if action exceeds duration. */
+declare function timeout(afterMs: number, child: Out): OutTimeout;
+/** Timeout output pointing to a single place. */
+declare function timeoutPlace(afterMs: number, p: Place<any>): OutTimeout;
+/** Forward consumed input value to output place on timeout. */
+declare function forwardInput(from: Place<any>, to: Place<any>): OutForwardInput;
+/** Collects all leaf places from this output spec (flattened). */
+declare function allPlaces(out: Out): Set<Place<any>>;
+/**
+ * Enumerates all possible output branches for structural analysis.
+ *
+ * - AND = single branch containing all child places (Cartesian product)
+ * - XOR = one branch per alternative child
+ * - Nested = Cartesian product for AND, union for XOR
+ */
+declare function enumerateBranches(out: Out): ReadonlyArray<ReadonlySet<Place<any>>>;
+
+/**
+ * Firing timing specification for transitions.
+ *
+ * Based on classical Time Petri Net (TPN) semantics:
+ * - Transition CANNOT fire before earliest time (lower bound)
+ * - Transition MUST fire by deadline OR become disabled (upper bound)
+ *
+ * All durations are in milliseconds.
+ */
+type Timing = TimingImmediate | TimingDeadline | TimingDelayed | TimingWindow | TimingExact;
+interface TimingImmediate {
+    readonly type: 'immediate';
+}
+interface TimingDeadline {
+    readonly type: 'deadline';
+    /** Deadline in milliseconds. Must be positive. */
+    readonly byMs: number;
+}
+interface TimingDelayed {
+    readonly type: 'delayed';
+    /** Minimum delay in milliseconds. Must be non-negative. */
+    readonly afterMs: number;
+}
+interface TimingWindow {
+    readonly type: 'window';
+    /** Earliest firing time in milliseconds. Must be non-negative. */
+    readonly earliestMs: number;
+    /** Latest firing time in milliseconds. Must be >= earliestMs. */
+    readonly latestMs: number;
+}
+interface TimingExact {
+    readonly type: 'exact';
+    /** Exact firing time in milliseconds. Must be non-negative. */
+    readonly atMs: number;
+}
+/** ~100 years in milliseconds, used for "unconstrained" intervals. */
+declare const MAX_DURATION_MS: number;
+/** Immediate firing: can fire as soon as enabled, no deadline. [0, inf) */
+declare function immediate(): TimingImmediate;
+/** Immediate with deadline: can fire immediately, must fire by deadline. [0, by] */
+declare function deadline(byMs: number): TimingDeadline;
+/** Delayed firing: must wait, then can fire anytime. [after, inf) */
+declare function delayed(afterMs: number): TimingDelayed;
+/** Time window: can fire within [earliest, latest]. */
+declare function window(earliestMs: number, latestMs: number): TimingWindow;
+/** Exact timing: fires at precisely the specified time. [at, at] */
+declare function exact(atMs: number): TimingExact;
+/** Returns the earliest time (ms) the transition can fire after enabling. */
+declare function earliest(timing: Timing): number;
+/** Returns the latest time (ms) by which the transition must fire. */
+declare function latest(timing: Timing): number;
+/** Returns true if this timing has a finite deadline. */
+declare function hasDeadline(timing: Timing): boolean;
+
+/**
+ * Consumed input tokens bound to their source places.
+ *
+ * Passed to TransitionAction as the `input` parameter, providing
+ * type-safe read access to tokens consumed from input places.
+ */
+declare class TokenInput {
+    private readonly tokens;
+    /** Add a token (used by executor when firing transition). */
+    add<T>(place: Place<T>, token: Token<T>): this;
+    /** Get all tokens for a place. */
+    getAll<T>(place: Place<T>): readonly Token<T>[];
+    /** Get the first token for a place. Throws if no tokens. */
+    get<T>(place: Place<T>): Token<T>;
+    /** Get the first token's value for a place. Throws if no tokens. */
+    value<T>(place: Place<T>): T;
+    /** Get all token values for a place. */
+    values<T>(place: Place<T>): readonly T[];
+    /** Get token count for a place. */
+    count(place: Place<any>): number;
+    /** Check if any tokens exist for a place. */
+    has(place: Place<any>): boolean;
+}
+
+/**
+ * An output entry: place + token pair.
+ */
+interface OutputEntry {
+    readonly place: Place<any>;
+    readonly token: Token<any>;
+}
+/**
+ * Collects output tokens produced by a transition action.
+ */
+declare class TokenOutput {
+    private readonly _entries;
+    /** Add a value to an output place (creates token with current timestamp). */
+    add<T>(place: Place<T>, value: T): this;
+    /** Add a pre-existing token to an output place. */
+    addToken<T>(place: Place<T>, token: Token<T>): this;
+    /** Returns all collected outputs. */
+    entries(): readonly OutputEntry[];
+    /** Check if any outputs were produced. */
+    isEmpty(): boolean;
+    /** Returns the set of place names that received tokens. */
+    placesWithTokens(): Set<string>;
+}
+
+/** Callback for emitting log messages from transition actions. */
+type LogFn = (level: string, message: string, error?: Error) => void;
+/**
+ * Context provided to transition actions.
+ *
+ * Provides filtered access based on structure:
+ * - Input places (consumed tokens)
+ * - Read places (context tokens, not consumed)
+ * - Output places (where to produce tokens)
+ *
+ * Enforces the structure contract — actions can only access places
+ * declared in the transition's structure.
+ */
+declare class TransitionContext {
+    private readonly rawInput;
+    private readonly _rawOutput;
+    private readonly allowedInputs;
+    private readonly allowedReads;
+    private readonly allowedOutputs;
+    private readonly _inputPlaces;
+    private readonly _readPlaces;
+    private readonly _outputPlaces;
+    private readonly _transitionName;
+    private readonly executionCtx;
+    private readonly _logFn?;
+    constructor(transitionName: string, rawInput: TokenInput, rawOutput: TokenOutput, inputPlaces: ReadonlySet<Place<any>>, readPlaces: ReadonlySet<Place<any>>, outputPlaces: ReadonlySet<Place<any>>, executionContext?: Map<string, unknown>, logFn?: LogFn);
+    /** Get single consumed input value. Throws if place not declared or multiple tokens. */
+    input<T>(place: Place<T>): T;
+    /** Get all consumed input values for a place. */
+    inputs<T>(place: Place<T>): readonly T[];
+    /** Get consumed input token with metadata. */
+    inputToken<T>(place: Place<T>): Token<T>;
+    /** Returns declared input places (consumed). */
+    inputPlaces(): ReadonlySet<Place<any>>;
+    private requireInput;
+    /** Get read-only context value. Throws if place not declared as read. */
+    read<T>(place: Place<T>): T;
+    /** Get all read-only context values for a place. */
+    reads<T>(place: Place<T>): readonly T[];
+    /** Returns declared read places (context, not consumed). */
+    readPlaces(): ReadonlySet<Place<any>>;
+    private requireRead;
+    /**
+     * Add one or more output values to the same place in a single call.
+     *
+     * Validates the place once, then appends each value to the output
+     * collector. Calling with zero values is a no-op.
+     *
+     * @example
+     *   ctx.output(outPlace, 'a', 'b', 'c');
+     *   ctx.output(outPlace, ...someArray);
+     *
+     * @throws if place not declared as output.
+     */
+    output<T>(place: Place<T>, ...values: T[]): this;
+    /**
+     * Add one or more pre-built output tokens to the same place in a single call.
+     *
+     * Validates the place once, then appends each token. Calling with zero
+     * tokens is a no-op.
+     *
+     * @throws if place not declared as output.
+     */
+    outputToken<T>(place: Place<T>, ...tokens: Token<T>[]): this;
+    /** Returns declared output places. */
+    outputPlaces(): ReadonlySet<Place<any>>;
+    private requireOutput;
+    /** Returns the transition name. */
+    transitionName(): string;
+    /** Retrieves an execution context object by key. */
+    executionContext<T>(key: string): T | undefined;
+    /** Checks if an execution context object of the given key is present. */
+    hasExecutionContext(key: string): boolean;
+    /** Emits a structured log message into the event store. */
+    log(level: string, message: string, error?: Error): void;
+    /** @internal Used by BitmapNetExecutor to collect outputs after action completion. */
+    rawOutput(): TokenOutput;
+}
+
+/**
+ * The action executed when a transition fires.
+ * Receives a TransitionContext providing filtered I/O and structure access.
+ */
+type TransitionAction = (ctx: TransitionContext) => Promise<void>;
+/**
+ * Identity action: produces no outputs.
+ *
+ * Returns a stable singleton reference (cached on first call). Reference
+ * stability is relied on by {@link import('./internal/subnet-rewriter.js')
+ * .composeActions} during channel composition (MOD-021) to short-circuit a
+ * passthrough-on-both-sides merge to passthrough — saving a microtask hop
+ * and matching the Java implementation's behaviour where both transitions'
+ * default actions collapse to the builder's own passthrough default.
+ */
+declare function passthrough(): TransitionAction;
+/**
+ * Transform action: applies function to context, copies result to ALL output places.
+ *
+ * @example
+ * ```ts
+ * const action = transform(ctx => ctx.input(inputPlace).toUpperCase());
+ * // Result is copied to every declared output place
+ * ```
+ */
+declare function transform(fn: (ctx: TransitionContext) => unknown): TransitionAction;
+/**
+ * Fork action: copies single input token to all outputs.
+ * Requires exactly one input place (derived from structure).
+ */
+declare function fork(): TransitionAction;
+/**
+ * Transform with explicit input place.
+ */
+declare function transformFrom<I>(inputPlace: Place<I>, fn: (value: I) => unknown): TransitionAction;
+/**
+ * Async transform: applies async function, copies result to all outputs.
+ */
+declare function transformAsync(fn: (ctx: TransitionContext) => Promise<unknown>): TransitionAction;
+/** Produce action: produces a single token with the given value to the specified place. */
+declare function produce<T>(place: Place<T>, value: T): TransitionAction;
+/**
+ * Wraps an action with timeout handling.
+ * If the action completes within the timeout, normal completion.
+ * If the timeout expires, the timeoutValue is produced to the timeoutPlace.
+ *
+ * @example
+ * ```ts
+ * const action = withTimeout(
+ *   async (ctx) => { ctx.output(resultPlace, await fetchData()); },
+ *   5000,
+ *   timeoutPlace,
+ *   'timed-out',
+ * );
+ * ```
+ */
+declare function withTimeout<T>(action: TransitionAction, timeoutMs: number, timeoutPlace: Place<T>, timeoutValue: T): TransitionAction;
+
+/**
+ * A transition in the Time Petri Net that transforms tokens.
+ *
+ * Transitions use identity-based equality (===) — each instance is unique
+ * regardless of name. The name is purely a label for display/debugging/export.
+ */
+declare class Transition {
+    readonly name: string;
+    readonly inputSpecs: readonly In[];
+    readonly outputSpec: Out | null;
+    readonly inhibitors: readonly ArcInhibitor[];
+    readonly reads: readonly ArcRead[];
+    readonly resets: readonly ArcReset[];
+    readonly timing: Timing;
+    readonly actionTimeout: OutTimeout | null;
+    readonly action: TransitionAction;
+    readonly priority: number;
+    private readonly _inputPlaces;
+    private readonly _readPlaces;
+    private readonly _outputPlaces;
+    /** @internal Use {@link Transition.builder} to create instances. */
+    constructor(key: symbol, name: string, inputSpecs: readonly In[], outputSpec: Out | null, inhibitors: readonly ArcInhibitor[], reads: readonly ArcRead[], resets: readonly ArcReset[], timing: Timing, action: TransitionAction, priority: number);
+    /** Returns set of input places — consumed tokens. */
+    inputPlaces(): ReadonlySet<Place<any>>;
+    /** Returns set of read places — context tokens, not consumed. */
+    readPlaces(): ReadonlySet<Place<any>>;
+    /** Returns set of output places — where tokens are produced. */
+    outputPlaces(): ReadonlySet<Place<any>>;
+    /** Returns true if this transition has an action timeout. */
+    hasActionTimeout(): boolean;
+    toString(): string;
+    static builder(name: string): TransitionBuilder;
+}
+declare class TransitionBuilder {
+    private readonly _name;
+    private readonly _inputSpecs;
+    private _outputSpec;
+    private readonly _inhibitors;
+    private readonly _reads;
+    private readonly _resets;
+    private _timing;
+    private _action;
+    private _priority;
+    constructor(name: string);
+    /** Add input specifications with cardinality. */
+    inputs(...specs: In[]): this;
+    /** Set the output specification (composite AND/XOR structure). */
+    outputs(spec: Out): this;
+    /** Add inhibitor arc. */
+    inhibitor(place: Place<any>): this;
+    /** Add inhibitor arcs. */
+    inhibitors(...places: Place<any>[]): this;
+    /** Add read arc. */
+    read(place: Place<any>): this;
+    /** Add read arcs. */
+    reads(...places: Place<any>[]): this;
+    /** Add reset arc. */
+    reset(place: Place<any>): this;
+    /** Add reset arcs. */
+    resets(...places: Place<any>[]): this;
+    /** Set timing specification. */
+    timing(timing: Timing): this;
+    /** Set the transition action. */
+    action(action: TransitionAction): this;
+    /** Set the priority (higher fires first). */
+    priority(priority: number): this;
+    build(): Transition;
+}
+
+/**
+ * Advisory direction metadata for an interface place.
+ *
+ * Per **MOD-004**, direction is metadata only — it does NOT constrain arc flow
+ * at runtime. Token movement is governed by arcs declared per CORE-030..CORE-035.
+ */
+type PortDirection = 'input' | 'output' | 'inout';
+/**
+ * A typed interface place exposed for composition, per **MOD-003**.
+ *
+ * Direction is advisory metadata only (per **MOD-004**); the underlying
+ * `Place<T>` reference is what is rewired at compose time.
+ */
+interface Port<T = unknown> {
+    /** Port name, unique within the {@link Interface}. */
+    readonly name: string;
+    /** Direction (advisory). */
+    readonly direction: PortDirection;
+    /** The body place exposed by this port. */
+    readonly place: Place<T>;
+}
+/**
+ * An interface transition exposed for synchronous fusion with a caller-side
+ * transition, per **MOD-005**.
+ *
+ * The only present variant in this scaffolding is the synchronous channel.
+ * The interface is left structurally open for future channel kinds without
+ * breaking existing pattern matches on `name`/`transition`.
+ */
+interface Channel {
+    /** Channel name, unique within the channel namespace. */
+    readonly name: string;
+    /** The body transition exposed by this channel. */
+    readonly transition: Transition;
+}
+/**
+ * Immutable declaration of a subnet's **interface**: the set of {@link Port}
+ * (interface places) and {@link Channel} (interface transitions) exposed for
+ * composition with an enclosing net.
+ *
+ * Specified by `spec/11-modular-composition.md` requirements **MOD-003**
+ * (port declaration) and **MOD-005** (channel declaration). Validation rules
+ * per **MOD-006** are enforced by `SubnetDef.builder()` at subnet build
+ * time; this class itself enforces only port/channel name uniqueness within
+ * its respective namespaces (used both by `SubnetDef` and by hand-built
+ * interfaces fed into `SubnetDef.fromNet`).
+ */
+declare class Interface {
+    readonly ports: ReadonlyMap<string, Port<unknown>>;
+    readonly channels: ReadonlyMap<string, Channel>;
+    /** @internal Use {@link Interface.builder} to create instances. */
+    constructor(key: symbol, ports: ReadonlyMap<string, Port<unknown>>, channels: ReadonlyMap<string, Channel>);
+    /** Looks up a port by name. Returns undefined when absent. */
+    port<T = unknown>(name: string): Port<T> | undefined;
+    /** Looks up a channel by name. Returns undefined when absent. */
+    channel(name: string): Channel | undefined;
+    /**
+     * Looks up a port by name and returns its underlying place, narrowed to
+     * `Place<T>`. Returns undefined when the port does not exist.
+     *
+     * Note: TypeScript erases generics at runtime, so unlike Java's
+     * `portPlaceAs(name, Class<T>)` this method cannot verify the token type at
+     * runtime — the caller is trusted to supply the correct `T`. Per **MOD-022**,
+     * type compatibility is enforced at compile time only in TypeScript.
+     */
+    placeAs<T>(name: string): Place<T> | undefined;
+    static builder(): InterfaceBuilder;
+}
+declare class InterfaceBuilder {
+    private readonly _ports;
+    private readonly _channels;
+    /** Add a pre-built port (rejects duplicate names). */
+    port(port: Port<unknown>): this;
+    /** Add an input port (advisory direction). */
+    inputPort<T>(name: string, place: Place<T>): this;
+    /** Add an output port (advisory direction). */
+    outputPort<T>(name: string, place: Place<T>): this;
+    /** Add an in-out port (advisory direction). */
+    inoutPort<T>(name: string, place: Place<T>): this;
+    /** Add a pre-built channel (rejects duplicate names). */
+    channel(channel: Channel): this;
+    /** Declare a synchronous channel by name + transition (rejects duplicate names). */
+    channel(name: string, transition: Transition): this;
+    /** @internal Bulk-add ports already validated by the caller. */
+    portsAll(ports: Iterable<Port<unknown>>): this;
+    /** @internal Bulk-add channels already validated by the caller. */
+    channelsAll(channels: Iterable<Channel>): this;
+    build(): Interface;
+}
+
+/**
+ * Safety properties that can be verified via IC3/PDR.
+ *
+ * Each property is encoded as an error condition: if a reachable state
+ * violates the property, Spacer finds a counterexample. If no violation
+ * is reachable, the property is proven.
+ */
+type SmtProperty = DeadlockFree | MutualExclusion | PlaceBound | Unreachable;
+/** Deadlock-freedom: no reachable marking has all transitions disabled. */
+interface DeadlockFree {
+    readonly type: 'deadlock-free';
+}
+/** Mutual exclusion: two places never have tokens simultaneously. */
+interface MutualExclusion {
+    readonly type: 'mutual-exclusion';
+    readonly p1: Place<any>;
+    readonly p2: Place<any>;
+}
+/** Place bound: a place never exceeds a given token count. */
+interface PlaceBound {
+    readonly type: 'place-bound';
+    readonly place: Place<any>;
+    readonly bound: number;
+}
+/** Unreachability: the given places never all have tokens simultaneously. */
+interface Unreachable {
+    readonly type: 'unreachable';
+    readonly places: ReadonlySet<Place<any>>;
+}
+declare function deadlockFree(): DeadlockFree;
+declare function mutualExclusion(p1: Place<any>, p2: Place<any>): MutualExclusion;
+declare function placeBound(place: Place<any>, bound: number): PlaceBound;
+declare function unreachable(places: ReadonlySet<Place<any>>): Unreachable;
+/** Human-readable description of a property. */
+declare function propertyDescription(prop: SmtProperty): string;
+
+/**
+ * Immutable snapshot of a Petri net marking for state space analysis.
+ *
+ * Maps places (by name) to integer token counts. Only stores places with count > 0.
+ * Used for invariant computation and structural verification, not runtime execution.
+ */
+declare class MarkingState {
+    private readonly tokenCounts;
+    private readonly placesByName;
+    /** @internal Use {@link MarkingState.builder} or {@link MarkingState.empty} to create instances. */
+    constructor(key: symbol, tokenCounts: Map<string, number>, placesByName: Map<string, Place<any>>);
+    /** Returns the token count for a place (0 if absent). */
+    tokens(place: Place<any>): number;
+    /** Checks if a place has at least one token. */
+    hasTokens(place: Place<any>): boolean;
+    /** Checks if any of the given places has tokens. */
+    hasTokensInAny(places: Iterable<Place<any>>): boolean;
+    /** Returns all places with tokens > 0. */
+    placesWithTokens(): Place<any>[];
+    /** Returns the total number of tokens. */
+    totalTokens(): number;
+    /** Checks if no tokens exist anywhere. */
+    isEmpty(): boolean;
+    toString(): string;
+    static empty(): MarkingState;
+    static builder(): MarkingStateBuilder;
+}
+declare class MarkingStateBuilder {
+    private readonly tokenCounts;
+    private readonly placesByName;
+    /** Sets the token count for a place. */
+    tokens(place: Place<any>, count: number): this;
+    /** Adds tokens to a place. */
+    addTokens(place: Place<any>, count: number): this;
+    /** Removes tokens from a place. Throws if insufficient. */
+    removeTokens(place: Place<any>, count: number): this;
+    /** Copies all token counts from another marking state. */
+    copyFrom(other: MarkingState): this;
+    build(): MarkingState;
+}
+
+/**
+ * A P-invariant (place invariant) of a Petri net.
+ *
+ * A P-invariant is a vector y such that y^T * C = 0, where C is the
+ * incidence matrix. This means that for any reachable marking M:
+ * sum(y_i * M_i) = constant, where constant = sum(y_i * M0_i).
+ *
+ * P-invariants provide structural bounds on places and are used as
+ * strengthening lemmas for the IC3/PDR engine.
+ */
+interface PInvariant {
+    /** Weight vector (one entry per place index). */
+    readonly weights: readonly number[];
+    /** The invariant value sum(y_i * M0_i). */
+    readonly constant: number;
+    /** Set of place indices where weight != 0. */
+    readonly support: ReadonlySet<number>;
+}
+declare function pInvariant(weights: number[], constant: number, support: Set<number>): PInvariant;
+declare function pInvariantToString(inv: PInvariant): string;
+
+/**
+ * Verification verdict.
+ */
+type Verdict = Proven | Violated | Unknown;
+/** Property proven safe. No reachable state violates it. */
+interface Proven {
+    readonly type: 'proven';
+    readonly method: string;
+    readonly inductiveInvariant: string | null;
+}
+/** Property violated. A counterexample trace is available. */
+interface Violated {
+    readonly type: 'violated';
+}
+/** Could not determine. */
+interface Unknown {
+    readonly type: 'unknown';
+    readonly reason: string;
+}
+/**
+ * Solver statistics.
+ */
+interface SmtStatistics {
+    readonly places: number;
+    readonly transitions: number;
+    readonly invariantsFound: number;
+    readonly structuralResult: string;
+}
+/**
+ * Result of SMT-based verification.
+ */
+interface SmtVerificationResult {
+    readonly verdict: Verdict;
+    readonly report: string;
+    readonly invariants: readonly PInvariant[];
+    readonly discoveredInvariants: readonly string[];
+    readonly counterexampleTrace: readonly MarkingState[];
+    readonly counterexampleTransitions: readonly string[];
+    readonly elapsedMs: number;
+    readonly statistics: SmtStatistics;
+}
+declare function isProven(result: SmtVerificationResult): boolean;
+declare function isViolated(result: SmtVerificationResult): boolean;
+
+/**
+ * Token-source supplier used by the verification harness to seed a synthetic
+ * environment place for a given input port, per
+ * `spec/11-modular-composition.md` requirement **MOD-051** AC #3.
+ *
+ * The supplier's presence is what bounds the input behavior in the synthetic
+ * harness; it is invoked once at synthetic-net construction time so that
+ * supplier-side errors surface eagerly, not at verification time. The
+ * concrete token value is not consumed by the verifier itself (which operates
+ * on the integer marking projection per [VER-004]); it merely materialises
+ * the seed token type and surfaces user errors.
+ */
+type TokenSupplier = () => Token<unknown>;
+/**
+ * Harness driving local property verification of a subnet definition per
+ * `spec/11-modular-composition.md` requirement **MOD-051**.
+ *
+ * The harness is a value carrier consumed by
+ * {@link import('../core/subnet-def.js').SubnetDef.verify}. It supplies the
+ * three pieces of information needed to wrap a subnet in a synthetic
+ * enclosing net for verification:
+ *
+ * 1. A {@link params} value of the subnet's parameter type.
+ * 2. A {@link portInputGenerators} map from **input port name** (original /
+ *    pre-prefix) to a {@link TokenSupplier}. The supplier's presence is what
+ *    bounds the input behavior in the synthetic harness; the supplier is
+ *    invoked at synthetic-net construction time when the harness wires up the
+ *    {@link import('../core/place.js').EnvironmentPlace} associated with the
+ *    port.
+ * 3. A set of {@link properties} to check (per [VER-002] /
+ *    {@link SmtProperty}).
+ *
+ * Each entry in {@link portInputGenerators} MUST correspond to an input or
+ * in-out port declared on the subnet's interface. Output-only ports never
+ * appear in the generator map; instead, the harness wires them to a synthetic
+ * observation place visible to the verifier.
+ *
+ * The map and property collection accept either the canonical
+ * `Map`/`ReadonlySet` form or a plain `Record`/`readonly array` for ergonomic
+ * inline construction; `SubnetDef.verify` normalises both.
+ *
+ * @typeParam P parameter type carried through to the subnet under test
+ */
+interface VerificationHarness<P = void> {
+    /**
+     * Parameter value supplied to
+     * {@link import('../core/subnet-def.js').SubnetDef.instantiate} for the
+     * system-under-test instance. Use `undefined` (or `null`) for `P = void`.
+     */
+    readonly params: P;
+    /**
+     * Map (or `Record`) from **input port name** to a {@link TokenSupplier} that
+     * seeds the synthetic environment place for that port. Output-only ports
+     * MUST NOT appear; in-out ports MUST appear (mirrors the Java harness).
+     */
+    readonly portInputGenerators: ReadonlyMap<string, TokenSupplier> | Readonly<Record<string, TokenSupplier>>;
+    /**
+     * Safety properties to check on the synthetic enclosing net per
+     * {@link SmtProperty}. An empty collection is permitted but yields an empty
+     * {@link VerificationResult.perProperty}.
+     */
+    readonly properties: ReadonlySet<SmtProperty> | readonly SmtProperty[];
+}
+/**
+ * Aggregated outcome of a
+ * {@link import('../core/subnet-def.js').SubnetDef.verify} invocation per
+ * `spec/11-modular-composition.md` requirement **MOD-051**.
+ *
+ * The verifier is invoked once per {@link SmtProperty} declared in the
+ * harness; each invocation produces an {@link SmtVerificationResult}. This
+ * record carries the per-property results plus the synthetic enclosing net
+ * that was constructed for verification (useful for diagnostic output and
+ * tooling to render the harness wiring).
+ */
+interface VerificationResult {
+    /**
+     * The synthetic enclosing net assembled by `SubnetDef.verify(...)`: the
+     * renamed body of the subnet under test, with each input port bound to a
+     * synthetic environment place and each output port bound to a synthetic
+     * observation place.
+     */
+    readonly syntheticNet: PetriNet;
+    /**
+     * Per-property verification results, in the iteration order of the
+     * harness's {@link VerificationHarness.properties} collection.
+     */
+    readonly perProperty: ReadonlyMap<SmtProperty, SmtVerificationResult>;
+    /**
+     * Returns true when every property in the harness was proven safe.
+     * An empty harness (no properties) returns `true` vacuously.
+     */
+    allProven(): boolean;
+    /**
+     * Returns true when at least one property was violated (counter-example
+     * found).
+     */
+    anyViolated(): boolean;
+}
+
+/**
+ * An open Petri net fragment paired with a declared {@link Interface}, per
+ * `spec/11-modular-composition.md` requirement **MOD-001**.
+ *
+ * A subnet definition is the reusable unit of composition. It carries:
+ * - A {@link name} (used as the originating-def label in `SubnetInstance` per [MOD-041]);
+ * - A {@link body} — a structurally complete `PetriNet` per [CORE-040];
+ * - An {@link iface} — the set of exposed ports and channels per [MOD-003] / [MOD-005].
+ *
+ * `SubnetDef` is the open variant of the {@link Subnet} discriminated union
+ * defined in `subnet.ts` per **MOD-002**.
+ *
+ * The {@link SubnetDef.fromNet} retrofit factory per **MOD-014** wraps an
+ * existing closed `PetriNet` plus an `Interface` into an unparameterised
+ * `SubnetDef<void>`, applying the same per-element validation as the
+ * builder's `build()`.
+ *
+ * @typeParam P parameter type carried through to `Instance.params`
+ *               (use `void` for unparameterised subnets)
+ */
+declare class SubnetDef<P = void> {
+    readonly name: string;
+    readonly body: PetriNet;
+    readonly iface: Interface;
+    /** @internal Use {@link SubnetDef.builder} or {@link SubnetDef.fromNet} to create instances. */
+    constructor(key: symbol, name: string, body: PetriNet, iface: Interface);
+    /**
+     * Produces a renamed module instance per **MOD-010**, **MOD-011**, **MOD-012**,
+     * and **MOD-030**.
+     *
+     * The rename pass walks every place and transition of the body net,
+     * substituting each name with `prefix + "/" + originalName`, and rebuilds
+     * every arc with rewritten place references. Transition timing, priority,
+     * and action are carried through by reference (action sharing per
+     * [MOD-030]). The renamed body is itself a structurally valid `PetriNet`
+     * per [CORE-040]; per-instance state isolation per [MOD-012] is a
+     * structural consequence of distinct prefixed names.
+     *
+     * ## Prefix validation
+     *
+     * The `"/"` character is reserved as the prefix separator (per [MOD-010]).
+     * User-supplied prefixes MUST NOT contain `"/"`; nested instantiation is
+     * performed by the future `PetriNetBuilder.compose(...)` mechanism (per
+     * [MOD-013]). A prefix containing `"/"` raises an `Error`.
+     *
+     * @param prefix the rename prefix (non-empty, must not contain `"/"`)
+     * @param params the parameter value carried through to `Instance.params`
+     *               (may be omitted when `P` is `void`)
+     * @throws when `prefix` is empty or contains `"/"`
+     */
+    instantiate(prefix: string, params?: P): Instance<P>;
+    /**
+     * Verifies safety properties of this subnet definition **in isolation** per
+     * **MOD-051**, by wrapping it in a synthetic enclosing net where each input
+     * port is fed by an {@link EnvironmentPlace} (token-source per the harness
+     * generator) and each output port is observed via a synthetic place. The
+     * standard {@link SmtVerifier} (per [MOD-050]) is invoked once per property
+     * declared in the harness; the resulting per-property outcomes are
+     * aggregated into a {@link VerificationResult}.
+     *
+     * ## Synthetic-net construction
+     *
+     * The synthetic enclosing net is built by:
+     * 1. Instantiating this `SubnetDef` with the prefix `"sut"` (system-under-test)
+     *    and `harness.params`.
+     * 2. For each input or in-out port on the interface, looking up the
+     *    harness generator by port name, allocating a synthetic
+     *    {@link Place}`<unknown>` of the same conceptual token type as the
+     *    port, wrapping it in an {@link EnvironmentPlace}, and binding the
+     *    port to that synthetic place via
+     *    {@link import('./petri-net.js').PetriNetBuilder.compose}. The supplier
+     *    is invoked once at construction time to materialize the seed token —
+     *    its presence is what bounds the input behavior under analysis. **If
+     *    the harness map is missing a generator for a required input or in-out
+     *    port, an `Error` is thrown.**
+     * 3. For each output or in-out port, allocating a synthetic observation
+     *    {@link Place}`<unknown>` and binding the port to it via the same
+     *    `compose(...)` call. The verifier inspects this place's reachability
+     *    / marking through the standard property APIs ({@link SmtProperty}).
+     * 4. Building the resulting flat {@link PetriNet} per [MOD-023] (the
+     *    verifier is composition-unaware per [MOD-050]).
+     *
+     * ## Per-property invocation
+     *
+     * Each {@link SmtProperty} in the harness is verified independently against
+     * the same synthetic net. The synthetic environment places are passed
+     * through to the verifier so that places driven by the harness generators
+     * are treated under the verifier's environment-analysis semantics rather
+     * than as ordinary sink places.
+     *
+     * @param harness the verification harness — supplies parameters, input-port
+     *                token generators, and the property set
+     * @returns a {@link VerificationResult} aggregating per-property
+     *          {@link SmtVerificationResult}s
+     * @throws when an input or in-out port is missing a harness generator
+     */
+    verify(harness: VerificationHarness<P>): Promise<VerificationResult>;
+    static builder<P = void>(name: string): SubnetDefBuilder<P>;
+    /**
+     * Retrofit utility per **MOD-014**: wraps an existing closed {@link PetriNet}
+     * plus an {@link Interface} into an unparameterised `SubnetDef<void>`.
+     *
+     * Validation per **MOD-014** / **MOD-006** is enforced before the result is
+     * constructed:
+     * - Every port's underlying `Place` must be present in `net.places`.
+     * - Every channel's underlying `Transition` must be present in `net.transitions`.
+     * - Port and channel name uniqueness is re-validated defensively (the
+     *   `Interface` builder already enforces this; hand-built `Interface`
+     *   values bypass that path).
+     *
+     * The resulting subnet definition is unparameterised (parameter type is `void`).
+     *
+     * @throws when a port place is not in `net.places`, a channel transition is
+     *         not in `net.transitions`, or port/channel names are not unique.
+     */
+    static fromNet(net: PetriNet, iface: Interface): SubnetDef<void>;
+}
+/**
+ * Fluent builder for {@link SubnetDef}.
+ *
+ * Validation per **MOD-006** is enforced at {@link build}:
+ * - Every port's underlying place must be in the body net.
+ * - Every channel's underlying transition must be in the body net.
+ * - Port names must be unique within the port namespace.
+ * - Channel names must be unique within the channel namespace.
+ */
+declare class SubnetDefBuilder<P = void> {
+    private readonly _name;
+    private readonly _bodyBuilder;
+    private readonly _ports;
+    private readonly _channels;
+    constructor(name: string);
+    transition(transition: Transition): this;
+    transitions(...transitions: Transition[]): this;
+    place<T>(place: Place<T>): this;
+    inputPort<T>(name: string, place: Place<T>): this;
+    outputPort<T>(name: string, place: Place<T>): this;
+    inoutPort<T>(name: string, place: Place<T>): this;
+    channel(name: string, transition: Transition): this;
+    build(): SubnetDef<P>;
+}
+
+/**
+ * Lightweight, debug-UI-facing descriptor of one composed subnet instance,
+ * per `spec/11-modular-composition.md` requirement **MOD-041**.
+ *
+ * Created by `Instance.descriptor()` after a subnet has been instantiated and
+ * (eventually) composed into an enclosing net. The descriptor is consumed by
+ * the debug protocol's `Subscribed` response so clients can render collapsed
+ * subnet clusters, per-instance highlighting, and "show only this instance"
+ * filters in the debug UI.
+ *
+ * This interface carries only structural metadata — it is observability-only
+ * and does not affect runtime behaviour of the composed flat net.
+ */
+interface SubnetInstance {
+    /** The instantiation prefix (e.g. `"buf1"` or `"outer/inner"` for nested instances). */
+    readonly prefix: string;
+    /** The originating subnet definition's name (null when not available). */
+    readonly defName: string | null;
+    /** Full prefixed transition names belonging to this instance. */
+    readonly transitions: readonly string[];
+    /** Full prefixed place names exposed as ports. */
+    readonly exposedPlaces: readonly string[];
+    /** The parameter value supplied at instantiation. */
+    readonly params: unknown;
+    /** The parent instance prefix when this is a nested instance, otherwise null. */
+    readonly parentPrefix: string | null;
+}
+
+/**
+ * A typed module instance produced by {@link SubnetDef.instantiate}, per
+ * `spec/11-modular-composition.md` requirements **MOD-010** (creation),
+ * **MOD-011** (typed handle map), **MOD-012** (per-instance state isolation),
+ * and **MOD-030** (action binding).
+ *
+ * An instance carries:
+ * - The {@link prefix} used to rename body elements (per [MOD-010] separator `"/"`);
+ * - A reference to the originating {@link SubnetDef};
+ * - The renamed body — a structurally valid `PetriNet` per [CORE-040];
+ * - Typed lookup handles for ports and channels keyed by their **original**
+ *   (pre-prefix) names;
+ * - The `params` value supplied at instantiation.
+ *
+ * **Scaffolding status**: this class ships in scaffolding form. The
+ * {@link bindActions} method throws `Error("not implemented")` until the
+ * `instantiate` rename pass lands in the next task. Direct accessors are
+ * wired up so downstream code can take dependencies on the API shape today.
+ *
+ * @typeParam P parameter type (use `void` for unparameterised subnets)
+ */
+declare class Instance<P = void> {
+    readonly prefix: string;
+    readonly def: SubnetDef<P>;
+    readonly renamedBody: PetriNet;
+    readonly portHandles: ReadonlyMap<string, Place<unknown>>;
+    readonly channelHandles: ReadonlyMap<string, Transition>;
+    readonly params: P;
+    /**
+     * @internal Use {@link SubnetDef.instantiate} (or the internal factory
+     * {@link __createInstance}) to create instances.
+     */
+    constructor(key: symbol, prefix: string, def: SubnetDef<P>, renamedBody: PetriNet, portHandles: ReadonlyMap<string, Place<unknown>>, channelHandles: ReadonlyMap<string, Transition>, params: P);
+    /**
+     * Returns the renamed {@link Place} corresponding to the named port.
+     *
+     * The port name is the **original** (pre-prefix) name as declared in the
+     * subnet's `Interface`. Per **MOD-022**, TypeScript enforces token-type
+     * compatibility at compile time only; this method does not validate `T`
+     * at runtime. A missing name raises an `Error`.
+     *
+     * @throws when the port name is unknown
+     */
+    port<T>(name: string): Place<T>;
+    /**
+     * Returns the renamed {@link Transition} corresponding to the named channel.
+     *
+     * @throws when the channel name is unknown
+     */
+    channel(name: string): Transition;
+    /**
+     * Returns the debug-UI descriptor for this instance per **MOD-041**.
+     */
+    descriptor(): SubnetInstance;
+    /**
+     * Produces a derived instance whose specified transitions (named by their
+     * **original**, pre-prefix names) carry the supplied actions per **MOD-030**.
+     *
+     * For each entry `[originalName, action]`, the renamed body is searched for
+     * the transition whose name equals `prefix + "/" + originalName`. The
+     * resulting instance shares the original `def`, `prefix`, `params`, and
+     * port/channel handle topology — only the renamed body is rebuilt with new
+     * actions. Per **MOD-030**, calling `bindActions` on one instance does NOT
+     * affect the actions held by other instances of the same `def`.
+     *
+     * Unrecognised original names raise an `Error` so typos surface eagerly.
+     */
+    bindActions(actionsByOriginalName: Record<string, TransitionAction>): Instance<P>;
+}
+
+/**
+ * Typed binding builder for {@link PetriNetBuilder.compose}, per
+ * `spec/11-modular-composition.md` requirements **MOD-020** (composition
+ * operation) and **MOD-022** (type compatibility).
+ *
+ * `ComposeBindings` is a write-only collector: callers register port and
+ * channel bindings against an instance's interface, and the host builder
+ * consumes the recorded mappings as it merges the instance into the
+ * enclosing net.
+ *
+ * ## Port bindings (MOD-020, MOD-022)
+ *
+ * {@link bindPort} merges an interface port with a caller-side place. The
+ * port name is the **original** (pre-prefix) name declared in the subnet's
+ * `Interface`; the caller place takes the port's slot in the resulting net.
+ * Token-type compatibility is enforced at compile time only in TypeScript
+ * (per [MOD-022]) — the typed `bindPort<T>` signature is the safety
+ * mechanism. TypeScript erases generics at runtime, so a misuse via `as`
+ * casts is structurally undetectable.
+ *
+ * ## Channel bindings (MOD-021)
+ *
+ * {@link bindChannel} records a synchronous channel binding: at compose time
+ * the named instance-side interface transition is **merged** with the
+ * supplied caller-side {@link Transition} into one transition in the
+ * resulting flat net. Channel composition is implemented in task #13; until
+ * then `compose(...)` raises an `Error` when any channel binding is present.
+ *
+ * ## Identity
+ *
+ * Instances are produced by {@link PetriNetBuilder.compose} and supplied to
+ * the caller's callback. The constructor is symbol-guarded to prevent
+ * direct construction.
+ */
+declare class ComposeBindings {
+    private readonly _portBindings;
+    private readonly _channelBindings;
+    /**
+     * @internal Use {@link PetriNetBuilder.compose} — instances are produced
+     * by the host builder and supplied to the caller's callback.
+     */
+    constructor(key: symbol);
+    /**
+     * Binds the named interface port to the given caller place per **MOD-020**.
+     *
+     * The port name is the **original** (pre-prefix) name declared in the
+     * subnet's `Interface`. The typed `<T>` parameter ensures the caller
+     * place's token type matches the interface port's token type at compile
+     * time per [MOD-022]; TypeScript does not validate the type at runtime
+     * because generics are erased.
+     *
+     * @throws when `portName` is already bound on this builder
+     */
+    bindPort<T>(portName: string, callerPlace: Place<T>): this;
+    /**
+     * Records a synchronous channel binding per **MOD-021**: at compose time,
+     * the instance-side renamed channel transition is merged with
+     * `callerTransition` into a single transition in the resulting flat net.
+     *
+     * **Status**: channel composition is implemented in task #13. Recording a
+     * channel binding here is permitted, but `compose(...)` currently raises
+     * an `Error` when any channel binding is present.
+     *
+     * @throws when `channelName` is already bound on this builder
+     */
+    bindChannel(channelName: string, callerTransition: Transition): this;
+    /** Returns an unmodifiable view of the recorded port bindings. */
+    portBindings(): ReadonlyMap<string, Place<unknown>>;
+    /** Returns an unmodifiable view of the recorded channel bindings. */
+    channelBindings(): ReadonlyMap<string, Transition>;
+}
+
+/**
+ * A declaration that N typed places are to be treated as a single canonical
+ * place in the resulting flat {@link import('./petri-net.js').PetriNet}, per
+ * `spec/11-modular-composition.md` requirements **MOD-060** (fusion set
+ * declaration) and **MOD-061** (fusion resolution at build).
+ *
+ * Fusion is **orthogonal to subnet composition**: composition merges places
+ * via port-binding (one instance port place ↔ one caller place per binding);
+ * fusion merges N places at once via N-ary equivalence, applied **after** all
+ * `compose(...)` calls have flattened subnet instances into the enclosing
+ * {@link import('./petri-net.js').PetriNetBuilder}. Fusion is the mechanism
+ * for modeling shared cross-instance state — e.g., a global rate limiter
+ * shared by three instances of a leaky-bucket subnet — without expressing the
+ * shared resource as an interface port on every subnet.
+ *
+ * ## Canonical member
+ *
+ * The **first declared member** is the canonical place; the others are
+ * non-canonical and get substituted away at
+ * {@link import('./petri-net.js').PetriNetBuilder.build} time. The canonical
+ * member's name and identity survive into the resulting flat net;
+ * non-canonical members do not appear in the built net's place set.
+ *
+ * ## Token-type homogeneity (MOD-060)
+ *
+ * All members of a fusion set MUST share the same token type. **In
+ * TypeScript** this is enforced at **compile time only** (via the typed
+ * `<T>` parameter on {@link FusionSetBuilder.member} and the typed varargs of
+ * {@link FusionSet.of}); per the TS-specific MOD-022 clause, no runtime
+ * `tokenType` introspection exists because Place carries only a phantom
+ * generic. The Java implementation enforces the same invariant at runtime.
+ *
+ * ## Single-member sets
+ *
+ * A fusion set with a single member is degenerate but allowed: it is a no-op
+ * at fusion-resolution time (the canonical member maps to itself, no
+ * substitution occurs). This matches the structural semantics of an N-ary
+ * equivalence with N=1.
+ *
+ * ## Identity
+ *
+ * `FusionSet` is immutable after construction. The {@link members} array is
+ * frozen; iteration order is the declaration order, with the first element
+ * guaranteed to be the canonical member.
+ *
+ * @see import('./petri-net.js').PetriNetBuilder.fuse
+ */
+declare class FusionSet {
+    readonly name: string;
+    readonly members: readonly Place<unknown>[];
+    /** @internal Use {@link FusionSet.builder} or {@link FusionSet.of} to create instances. */
+    constructor(key: symbol, name: string, members: readonly Place<unknown>[]);
+    /**
+     * Returns the canonical member — by convention, the first declared member.
+     * The canonical place's identity survives into the resulting flat net.
+     */
+    get canonical(): Place<unknown>;
+    /**
+     * Returns all members **except** the canonical member, in declaration order.
+     * These are the places that get substituted away at
+     * {@link import('./petri-net.js').PetriNetBuilder.build} time.
+     *
+     * For a single-member (degenerate) set, returns an empty array.
+     */
+    nonCanonical(): readonly Place<unknown>[];
+    toString(): string;
+    /** Returns a fresh {@link FusionSetBuilder} with the given human-readable name. */
+    static builder(name: string): FusionSetBuilder;
+    /**
+     * Convenience factory: builds a fusion set whose first member is `first`
+     * (the canonical) and whose remaining members are `rest`, all sharing the
+     * type `<T>`.
+     *
+     * The varargs form ensures static-type homogeneity at the call site (the
+     * TypeScript compiler checks every `rest` entry is a `Place<T>`).
+     */
+    static of<T>(name: string, first: Place<T>, ...rest: Place<T>[]): FusionSet;
+}
+/**
+ * Fluent builder for {@link FusionSet}.
+ *
+ * Members are appended in call order; the first member becomes the canonical
+ * place. The typed `<T>` parameter on {@link member} is for compile-time
+ * guidance only — TypeScript erases generics at runtime, so no homogeneity
+ * check happens here.
+ */
+declare class FusionSetBuilder {
+    private readonly _name;
+    private readonly _members;
+    constructor(name: string);
+    /**
+     * Appends a member to the fusion set. The first member becomes the canonical
+     * place per the convention documented on {@link FusionSet}.
+     *
+     * The `<T>` parameter is for compile-time guidance only: callers writing
+     * typed code at the same call site benefit from the compiler checking
+     * `Place<T>` at each member.
+     */
+    member<T>(place: Place<T>): this;
+    /**
+     * Builds the immutable {@link FusionSet}. Validates that the set has at
+     * least one member; the empty set is rejected as malformed per **MOD-060**.
+     * Single-member sets are accepted as a structurally degenerate no-op.
+     */
+    build(): FusionSet;
+}
+
+/**
+ * Immutable definition of a Time Petri Net structure.
+ *
+ * A PetriNet is a reusable definition that can be executed multiple times
+ * with different initial markings. Places are auto-collected from transitions.
+ */
+declare class PetriNet {
+    readonly name: string;
+    readonly places: ReadonlySet<Place<any>>;
+    readonly transitions: ReadonlySet<Transition>;
+    /** @internal Use {@link PetriNet.builder} to create instances. */
+    constructor(key: symbol, name: string, places: ReadonlySet<Place<any>>, transitions: ReadonlySet<Transition>);
+    /**
+     * Creates a new PetriNet with actions bound to transitions by name.
+     * Unbound transitions keep passthrough action.
+     */
+    bindActions(actionBindings: Map<string, TransitionAction> | Record<string, TransitionAction>): PetriNet;
+    /**
+     * Creates a new PetriNet with actions bound via a resolver function.
+     */
+    bindActionsWithResolver(actionResolver: (name: string) => TransitionAction): PetriNet;
+    static builder(name: string): PetriNetBuilder;
+}
+declare class PetriNetBuilder {
+    private readonly _name;
+    private readonly _places;
+    private readonly _transitions;
+    private readonly _fusionSets;
+    constructor(name: string);
+    /** Add an explicit place. */
+    place(place: Place<any>): this;
+    /** Add explicit places. */
+    places(...places: Place<any>[]): this;
+    /** Add a transition (auto-collects places from arcs). */
+    transition(transition: Transition): this;
+    /** Add transitions (auto-collects places from arcs). */
+    transitions(...transitions: Transition[]): this;
+    /**
+     * Composes a subnet {@link Instance} into this builder per **MOD-020**
+     * (composition operation), **MOD-021** (channel composition), **MOD-022**
+     * (type compatibility), and **MOD-023** (composition produces a flat net).
+     *
+     * Two overloads are supported:
+     *
+     * 1. **Map / Record overload** — the runtime-checked form. Pass a
+     *    `Map<string, Place<unknown>>` or a `Record<string, Place<unknown>>`
+     *    keyed by the subnet's **original** (pre-prefix) port names. No
+     *    channel bindings are recorded by this overload.
+     *
+     * 2. **Callback overload** — the typed form. Pass a callback receiving a
+     *    fresh {@link ComposeBindings}; register port bindings via
+     *    `bindings.bindPort<T>(name, place)` so TypeScript checks each
+     *    binding's token type at compile time per [MOD-022]. Synchronous
+     *    channels may be merged with caller-side transitions via
+     *    `bindings.bindChannel(name, t)` per [MOD-021].
+     *
+     * For each port binding `(portName -> callerPlace)`, the instance's
+     * renamed port place is substituted with the caller place at every arc
+     * in the instance's renamed body via the `subnet-rewriter` module.
+     * Internal (non-port) places of the instance flow through with their
+     * prefixed names. Composition is **eager** — the rewrite happens here,
+     * not at `build()` (per [MOD-020] AC #5).
+     *
+     * For each channel binding `(channelName -> callerTransition)`, the
+     * instance's renamed channel transition and the caller-side transition
+     * are merged into one transition in the resulting flat net per [MOD-021].
+     * If the caller-side transition has not been added to this builder yet,
+     * it is added implicitly during the merge step.
+     *
+     * @throws when a port name is unknown on the instance's interface, when a
+     *         channel name is unknown on the interface, or when caller- and
+     *         instance-side transition timings conflict (per [MOD-021]).
+     */
+    compose(instance: Instance<unknown>, portMappings: ReadonlyMap<string, Place<unknown>> | Record<string, Place<unknown>>): this;
+    compose(instance: Instance<unknown>, bind: (b: ComposeBindings) => void): this;
+    /**
+     * @internal Shared compose implementation: validates port and channel
+     * bindings, builds the place-substitution map, walks every renamed-body
+     * transition through {@link substitutePlaces}, applies channel merges per
+     * [MOD-021], and adds the resulting transitions to this builder.
+     *
+     * ## Channel-merge flow ([MOD-021])
+     *
+     * 1. Collect rewritten instance transitions into a working `Map<string,
+     *    Transition>` keyed by prefixed transition name (deferred — not yet
+     *    added to the builder's transition set).
+     * 2. For each channel binding, resolve the renamed instance-side
+     *    transition through `instance.channel(channelName)`, then look up its
+     *    rewritten counterpart in the working map by name.
+     * 3. Replace the working-map entry with a {@link mergeTransitions} result
+     *    that fuses caller-side + instance-side; remove the rewritten
+     *    instance-side entry. Also replace (or add) the caller-side
+     *    transition in this builder's transition set with the same merged
+     *    result, indexed under the caller's name slot.
+     * 4. Add the surviving (un-merged) entries to this builder.
+     *
+     * The deferral matters: writing the rewritten instance transitions to the
+     * builder eagerly would force a second "remove-then-replace" pass to
+     * apply the channel merges, complicating the place-collection invariants.
+     * Collecting first and merging second keeps the builder's transition set
+     * finalized exactly once.
+     *
+     * Keying the working map by prefixed transition name (rather than by
+     * Transition reference) is also robust against a prior
+     * {@link Instance.bindActions} call that may have rebuilt the renamed-body
+     * transitions, breaking identity equality between the body and the
+     * channel-handle map — but the prefixed names remain stable.
+     */
+    private composeInternal;
+    /**
+     * Registers one or more {@link FusionSet} declarations on this builder, per
+     * **MOD-060** (fusion set declaration) and **MOD-061** (fusion resolution
+     * at build).
+     *
+     * Fusion is **orthogonal to subnet composition**: fuse sets are accumulated
+     * here and applied during {@link build} **after** all `compose(...)` calls
+     * have flattened subnet instances into the builder's transition set.
+     * Registration order is irrelevant to semantics — `fuse(set)` BEFORE
+     * `compose(...)` and `fuse(set)` AFTER `compose(...)` both apply at the
+     * same point in the build pipeline.
+     *
+     * ## Validation
+     *
+     * Cross-set overlap (a place appearing in two fusion sets) is detected at
+     * {@link build} and reported as an `Error` naming the offending place and
+     * both sets.
+     *
+     * Two overloads are supported:
+     *
+     * 1. **Spread overload** — pass one or more pre-built {@link FusionSet}
+     *    values (e.g., from `FusionSet.of(...)` or
+     *    `FusionSet.builder(...).build()`).
+     * 2. **Sugar overload** — pass a callback receiving a fresh
+     *    {@link FusionSetBuilder} named after the enclosing net; register
+     *    members via `b.member(place)`. Equivalent to
+     *    `FusionSet.builder('<netName>-fusion').<callback>.build()` followed by
+     *    `fuse(...)` on the result.
+     */
+    fuse(...sets: FusionSet[]): this;
+    fuse(declarer: (b: FusionSetBuilder) => void): this;
+    /**
+     * Builds the immutable {@link PetriNet}, applying fusion resolution (per
+     * **MOD-061**) AFTER all transition/composition accumulation:
+     *
+     * 1. Detect overlapping fusion sets — a single place declared in two sets
+     *    is rejected with an `Error`.
+     * 2. Build the `non-canonical → canonical` substitution map across all
+     *    sets, keyed by non-canonical place name (matching the rewriter's
+     *    Map<string, Place<unknown>> convention — TypeScript Place identity is
+     *    name-based per `runtime/compiled-net.ts`).
+     * 3. Walk every transition through {@link applyFusion} to rewrite arc place
+     *    references.
+     * 4. Re-derive the place set from the rewritten transitions plus any
+     *    caller-declared standalone places, dropping non-canonical members.
+     *    Caller-declared standalone places that happen to be non-canonical
+     *    members are also dropped.
+     *
+     * If no fusion sets were registered, the build is the trivial
+     * `new PetriNet(...)` — the fusion machinery has no per-build cost when
+     * unused.
+     *
+     * @throws when two fusion sets share a place
+     */
+    build(): PetriNet;
+    /**
+     * @internal Fusion-resolution pass per **MOD-061**. Split out from
+     * {@link build} so the no-fusion fast path stays trivial.
+     */
+    private buildWithFusion;
+}
+
+export { and as $, type Arc as A, SubnetDefBuilder as B, type Channel as C, type SubnetInstance as D, type EnvironmentPlace as E, FusionSet as F, type Timing as G, type TimingDeadline as H, type In as I, type TimingDelayed as J, type TimingExact as K, type LogFn as L, MAX_DURATION_MS as M, type TimingImmediate as N, type Out as O, PetriNet as P, type TimingWindow as Q, TokenInput as R, SubnetDef as S, type Token as T, TokenOutput as U, type TransitionAction as V, TransitionBuilder as W, type VerificationHarness as X, type VerificationResult as Y, all as Z, allPlaces as _, type Place as a, placeBound as a$, andPlaces as a0, arcPlace as a1, atLeast as a2, consumptionCount as a3, deadline as a4, delayed as a5, earliest as a6, enumerateBranches as a7, environmentPlace as a8, exact as a9, transformFrom as aA, unitToken as aB, window as aC, withTimeout as aD, xor as aE, xorPlaces as aF, MarkingState as aG, type PInvariant as aH, MarkingStateBuilder as aI, type SmtProperty as aJ, type SmtVerificationResult as aK, type DeadlockFree as aL, type MutualExclusion as aM, type PlaceBound as aN, type Proven as aO, type SmtStatistics as aP, type TokenSupplier as aQ, type Unknown as aR, type Unreachable as aS, type Verdict as aT, type Violated as aU, deadlockFree as aV, isProven as aW, isViolated as aX, mutualExclusion as aY, pInvariant as aZ, pInvariantToString as a_, exactly as aa, fork as ab, forwardInput as ac, hasDeadline as ad, hasGuard as ae, immediate as af, inhibitorArc as ag, inputArc as ah, isUnit as ai, latest as aj, matchesGuard as ak, one as al, outPlace as am, outputArc as an, passthrough as ao, place as ap, produce as aq, readArc as ar, requiredCount as as, resetArc as at, timeout as au, timeoutPlace as av, tokenAt as aw, tokenOf as ax, transform as ay, transformAsync as az, Transition as b, propertyDescription as b0, unreachable as b1, TransitionContext as c, type ArcInhibitor as d, type ArcInput as e, type ArcOutput as f, type ArcRead as g, type ArcReset as h, ComposeBindings as i, FusionSetBuilder as j, type InAll as k, type InAtLeast as l, type InExactly as m, type InOne as n, Instance as o, Interface as p, InterfaceBuilder as q, type OutAnd as r, type OutForwardInput as s, type OutPlace as t, type OutTimeout as u, type OutXor as v, type OutputEntry as w, PetriNetBuilder as x, type Port as y, type PortDirection as z };