wavekit 0.5.6__tar.gz → 0.6.0__tar.gz

{wavekit-0.5.6 → wavekit-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavekit
-Version: 0.5.6
+Version: 0.6.0
 Summary: a fundamental package for digital circuit waveform analysis
 License-File: LICENSE
 Author: cxzzzz
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: numpy (>=2.0.0,<3.0.0)
+Requires-Dist: pylibfst (>=0.2.1,<0.3.0)
 Requires-Dist: pytest (>=8.2.2,<9.0.0)
 Requires-Dist: vcdvcd (>=2.3.5,<3.0.0)
 Project-URL: Repository, https://github.com/cxzzzz/wavekit
@@ -24,15 +25,21 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/cxzzzz/wavekit/actions/workflows/python-package.yml/badge.svg)](https://github.com/cxzzzz/wavekit/actions/workflows/python-package.yml)
 [![PyPI version](https://img.shields.io/pypi/v/wavekit.svg)](https://pypi.org/project/wavekit/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/wavekit.svg)](https://pypi.org/project/wavekit/)
+[![Downloads](https://img.shields.io/pypi/dm/wavekit.svg)](https://pypi.org/project/wavekit/)
 [![License](https://img.shields.io/github/license/cxzzzz/wavekit.svg)](LICENSE)
 
-**Wavekit** is a fundamental Python library for digital waveform analysis. By seamlessly converting VCD and FSDB data into Numpy arrays, it empowers engineers to perform high-performance signal processing, protocol analysis, and automated verification with ease.
+English | [中文](README_ZH.md)
+
+**Wavekit** is a fundamental Python library for digital waveform analysis. By seamlessly converting VCD, FST, and FSDB data into Numpy arrays, it empowers engineers to perform high-performance signal processing, protocol analysis, and automated verification with ease.
+
+> 🤖 **AI Integration**: [wavekit-mcp](https://github.com/cxzzzz/wavekit-mcp) — MCP server for AI-assisted waveform analysis. Let AI load signals and run pattern matching — no manual coding required.
 
 ## ✨ Features
 
-- **High Performance & Easy Loading**: Cython-optimized VCD/FSDB parsers with Numpy-backed storage for speed and memory efficiency, plus flexible batch signal extraction via brace expansion, integer ranges, and regular expressions.
+- **Flexible Signal Extraction**: Flexible batch signal extraction via brace expansion, integer ranges, and regular expressions — load groups of related signals in one call.
 - **Rich Analysis Tools**: Numpy-like API for arithmetic, masking, bit-field manipulation, edge detection, and time/cycle slicing — compose complex signal queries in just a few lines.
 - **Pattern Matching**: NFA-based temporal pattern engine that scans waveforms in a single pass to extract protocol transactions, measure latencies, and detect timing violations.
+- **High-Performance Parsing & Storage**: VCD, FST, and FSDB readers with Numpy-backed storage for fast loading and memory efficiency, handling large simulation files with ease.
 
 ## 📦 Installation
 
@@ -47,7 +54,7 @@ pip install wavekit
 
 ## 🚀 Quick Start
 
-> The examples below use placeholder filenames such as `sim.vcd`. Replace them with the path to your own VCD or FSDB file, and adjust signal paths to match your design hierarchy.
+> The examples below use placeholder filenames such as `sim.vcd`. Replace them with the path to your own VCD, FST, or FSDB file, and adjust signal paths to match your design hierarchy.
 
 ### 1. Batch Signal Extraction
 
@@ -160,7 +167,7 @@ print(f"Read data: {valid.captures['rdata'].value}")
 **AXI Write Burst (multi-beat)**
 
 ```python
-beat = Pattern().wait(wvalid & wready).capture("beats[]", wdata)
+beat = Pattern().wait(wvalid & wready).capture("beats", wdata, mode="list")
 
 result = (
     Pattern()
@@ -198,7 +205,7 @@ print(f"Stall durations: {stalls.duration.value} cycles")
 
 | Method | Description |
 |--------|-------------|
-| `VcdReader(file)` / `FsdbReader(file)` | Open a waveform file. Use as a context manager. `FsdbReader` requires Verdi runtime (`WAVEKIT_NPI_LIB`, `VERDI_HOME`, or `LD_LIBRARY_PATH`). |
+| `VcdReader(file)` / `FstReader(file)` / `FsdbReader(file)` | Open a waveform file. Use as a context manager. `FsdbReader` requires Verdi runtime (`WAVEKIT_NPI_LIB`, `VERDI_HOME`, or `LD_LIBRARY_PATH`). |
 | `reader.load_waveform(signal, clock, ...)` | Load one signal sampled on every clock edge. Returns `Waveform`. |
 | `reader.load_matched_waveforms(pattern, clock_pattern, ...)` | Batch-load signals matching a brace/regex pattern. Returns `dict[tuple, Waveform]`. |
 | `reader.eval(expr, clock, mode='single'\|'zip', ...)` | Evaluate an arithmetic expression with embedded signal paths. |
@@ -261,15 +268,33 @@ A `Waveform` wraps three parallel numpy arrays (`.value`, `.clock`, `.time`). Al
 | `wave.rising_edge()` | True at 0→1 transitions |
 | `wave.falling_edge()` | True at 1→0 transitions |
 
+**Relative time access**
+
+| Method | Description |
+|--------|-------------|
+| `wave.relative(offset, pad, pad_value)` | Shift by *offset* cycles (positive = future, negative = past) |
+| `wave.ahead(n, pad, pad_value)` | Look *n* cycles into the future (shorthand for `relative(n)`) |
+| `wave.back(n, pad, pad_value)` | Look *n* cycles into the past (shorthand for `relative(-n)`) |
+
+`pad` controls boundary handling: `'repeat'` (default) pads with the first/last value, `'value'` pads with a given `pad_value`.
+
+```python
+# Rising edge detection
+rising = (wave == 0) & wave.ahead()
+
+# Compare current vs 3 cycles ago
+changed = wave != wave.back(3)
+```
+
 ---
 
 ### Pattern
 
 | Method | Description |
 |--------|-------------|
-| `.wait(cond, guard=None, channel=None)` | Block until `cond` is True. `guard` is checked each waiting cycle. `channel` enforces FIFO ordering among concurrent instances. |
-| `.delay(n, guard=None)` | Advance `n` cycles. `delay(0)` is a no-op. |
-| `.capture(name, signal)` | Record signal value at current cycle. `name[]` appends to a list. |
+| `.wait(cond, *, require=None, channel=None, tick=True)` | Block until `cond` is True. `require` is checked each waiting cycle (failure → `REQUIRE_VIOLATED`). `channel` binds the wait to a shared FIFO consumer group (see [Channels](#channels) below). `tick=False` matches on the current cycle without consuming it. |
+| `.delay(n, *, require=None)` | Advance `n` cycles. `delay(0)` is a no-op. `require` must hold every cycle. |
+| `.capture(name, signal, *, mode='last')` | Record signal value at current cycle. `mode='last'` (default) overwrites; `'first'` keeps the first write; `'list'` appends to a list. |
 | `.require(cond)` | Assert condition; fail with `REQUIRE_VIOLATED` if False. |
 | `.loop(body, *, until=None, when=None)` | `until`: do-while (exit when True after body). `when`: while (exit when False before body). |
 | `.repeat(body, n)` | Execute body exactly `n` times. `n` may be a callable. |
@@ -277,6 +302,34 @@ A `Waveform` wraps three parallel numpy arrays (`.value`, `.clock`, `.time`). Al
 | `.timeout(max_cycles)` | Terminate unfinished instances with `TIMEOUT`. |
 | `.match(start_cycle=None, end_cycle=None)` | Run the engine; return `MatchResult`. |
 
+**Channels**
+
+A `Channel` is an identity object representing a shared FIFO consumer group: at most one in-flight pattern instance may consume per cycle. Each `wait()` step has its own implicit channel, so multiple instances of the same pattern automatically serialize one-per-cycle on that step. Pass an explicit `Channel` (or `callable(index, captures) -> Channel`) when you need to override the default serialization — typically when events arrive on physically parallel buses (multi-bank memory, multi-lane retire) and several instances should consume *concurrently* by routing each to its own per-key channel.
+
+```python
+from collections import defaultdict
+from wavekit import Channel, Pattern
+
+# Multi-bank cache: each bank has its own response port, so two banks
+# can return data in the *same* cycle. Without partitioning, the default
+# serialization rule would force one instance to wait an extra cycle.
+# A per-bank Channel lets each in-flight read consume from its own bank.
+banks = defaultdict(Channel)
+
+result = (
+    Pattern()
+    .wait(req_valid)
+    .capture('bank', req_addr & 1)
+    .wait(
+        lambda i, cap: bank_valid[cap['bank']].value[i],
+        channel=lambda i, cap: banks[cap['bank']],
+    )
+    .capture('rdata',
+        lambda i, cap: bank_data[cap['bank']].value[i])
+    .match()
+)
+```
+
 **`MatchResult`**
 
 | Field | Description |

{wavekit-0.5.6 → wavekit-0.6.0}/README.md

@@ -3,15 +3,21 @@
 [![CI](https://github.com/cxzzzz/wavekit/actions/workflows/python-package.yml/badge.svg)](https://github.com/cxzzzz/wavekit/actions/workflows/python-package.yml)
 [![PyPI version](https://img.shields.io/pypi/v/wavekit.svg)](https://pypi.org/project/wavekit/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/wavekit.svg)](https://pypi.org/project/wavekit/)
+[![Downloads](https://img.shields.io/pypi/dm/wavekit.svg)](https://pypi.org/project/wavekit/)
 [![License](https://img.shields.io/github/license/cxzzzz/wavekit.svg)](LICENSE)
 
-**Wavekit** is a fundamental Python library for digital waveform analysis. By seamlessly converting VCD and FSDB data into Numpy arrays, it empowers engineers to perform high-performance signal processing, protocol analysis, and automated verification with ease.
+English | [中文](README_ZH.md)
+
+**Wavekit** is a fundamental Python library for digital waveform analysis. By seamlessly converting VCD, FST, and FSDB data into Numpy arrays, it empowers engineers to perform high-performance signal processing, protocol analysis, and automated verification with ease.
+
+> 🤖 **AI Integration**: [wavekit-mcp](https://github.com/cxzzzz/wavekit-mcp) — MCP server for AI-assisted waveform analysis. Let AI load signals and run pattern matching — no manual coding required.
 
 ## ✨ Features
 
-- **High Performance & Easy Loading**: Cython-optimized VCD/FSDB parsers with Numpy-backed storage for speed and memory efficiency, plus flexible batch signal extraction via brace expansion, integer ranges, and regular expressions.
+- **Flexible Signal Extraction**: Flexible batch signal extraction via brace expansion, integer ranges, and regular expressions — load groups of related signals in one call.
 - **Rich Analysis Tools**: Numpy-like API for arithmetic, masking, bit-field manipulation, edge detection, and time/cycle slicing — compose complex signal queries in just a few lines.
 - **Pattern Matching**: NFA-based temporal pattern engine that scans waveforms in a single pass to extract protocol transactions, measure latencies, and detect timing violations.
+- **High-Performance Parsing & Storage**: VCD, FST, and FSDB readers with Numpy-backed storage for fast loading and memory efficiency, handling large simulation files with ease.
 
 ## 📦 Installation
 
@@ -26,7 +32,7 @@ pip install wavekit
 
 ## 🚀 Quick Start
 
-> The examples below use placeholder filenames such as `sim.vcd`. Replace them with the path to your own VCD or FSDB file, and adjust signal paths to match your design hierarchy.
+> The examples below use placeholder filenames such as `sim.vcd`. Replace them with the path to your own VCD, FST, or FSDB file, and adjust signal paths to match your design hierarchy.
 
 ### 1. Batch Signal Extraction
 
@@ -139,7 +145,7 @@ print(f"Read data: {valid.captures['rdata'].value}")
 **AXI Write Burst (multi-beat)**
 
 ```python
-beat = Pattern().wait(wvalid & wready).capture("beats[]", wdata)
+beat = Pattern().wait(wvalid & wready).capture("beats", wdata, mode="list")
 
 result = (
     Pattern()
@@ -177,7 +183,7 @@ print(f"Stall durations: {stalls.duration.value} cycles")
 
 | Method | Description |
 |--------|-------------|
-| `VcdReader(file)` / `FsdbReader(file)` | Open a waveform file. Use as a context manager. `FsdbReader` requires Verdi runtime (`WAVEKIT_NPI_LIB`, `VERDI_HOME`, or `LD_LIBRARY_PATH`). |
+| `VcdReader(file)` / `FstReader(file)` / `FsdbReader(file)` | Open a waveform file. Use as a context manager. `FsdbReader` requires Verdi runtime (`WAVEKIT_NPI_LIB`, `VERDI_HOME`, or `LD_LIBRARY_PATH`). |
 | `reader.load_waveform(signal, clock, ...)` | Load one signal sampled on every clock edge. Returns `Waveform`. |
 | `reader.load_matched_waveforms(pattern, clock_pattern, ...)` | Batch-load signals matching a brace/regex pattern. Returns `dict[tuple, Waveform]`. |
 | `reader.eval(expr, clock, mode='single'\|'zip', ...)` | Evaluate an arithmetic expression with embedded signal paths. |
@@ -240,15 +246,33 @@ A `Waveform` wraps three parallel numpy arrays (`.value`, `.clock`, `.time`). Al
 | `wave.rising_edge()` | True at 0→1 transitions |
 | `wave.falling_edge()` | True at 1→0 transitions |
 
+**Relative time access**
+
+| Method | Description |
+|--------|-------------|
+| `wave.relative(offset, pad, pad_value)` | Shift by *offset* cycles (positive = future, negative = past) |
+| `wave.ahead(n, pad, pad_value)` | Look *n* cycles into the future (shorthand for `relative(n)`) |
+| `wave.back(n, pad, pad_value)` | Look *n* cycles into the past (shorthand for `relative(-n)`) |
+
+`pad` controls boundary handling: `'repeat'` (default) pads with the first/last value, `'value'` pads with a given `pad_value`.
+
+```python
+# Rising edge detection
+rising = (wave == 0) & wave.ahead()
+
+# Compare current vs 3 cycles ago
+changed = wave != wave.back(3)
+```
+
 ---
 
 ### Pattern
 
 | Method | Description |
 |--------|-------------|
-| `.wait(cond, guard=None, channel=None)` | Block until `cond` is True. `guard` is checked each waiting cycle. `channel` enforces FIFO ordering among concurrent instances. |
-| `.delay(n, guard=None)` | Advance `n` cycles. `delay(0)` is a no-op. |
-| `.capture(name, signal)` | Record signal value at current cycle. `name[]` appends to a list. |
+| `.wait(cond, *, require=None, channel=None, tick=True)` | Block until `cond` is True. `require` is checked each waiting cycle (failure → `REQUIRE_VIOLATED`). `channel` binds the wait to a shared FIFO consumer group (see [Channels](#channels) below). `tick=False` matches on the current cycle without consuming it. |
+| `.delay(n, *, require=None)` | Advance `n` cycles. `delay(0)` is a no-op. `require` must hold every cycle. |
+| `.capture(name, signal, *, mode='last')` | Record signal value at current cycle. `mode='last'` (default) overwrites; `'first'` keeps the first write; `'list'` appends to a list. |
 | `.require(cond)` | Assert condition; fail with `REQUIRE_VIOLATED` if False. |
 | `.loop(body, *, until=None, when=None)` | `until`: do-while (exit when True after body). `when`: while (exit when False before body). |
 | `.repeat(body, n)` | Execute body exactly `n` times. `n` may be a callable. |
@@ -256,6 +280,34 @@ A `Waveform` wraps three parallel numpy arrays (`.value`, `.clock`, `.time`). Al
 | `.timeout(max_cycles)` | Terminate unfinished instances with `TIMEOUT`. |
 | `.match(start_cycle=None, end_cycle=None)` | Run the engine; return `MatchResult`. |
 
+**Channels**
+
+A `Channel` is an identity object representing a shared FIFO consumer group: at most one in-flight pattern instance may consume per cycle. Each `wait()` step has its own implicit channel, so multiple instances of the same pattern automatically serialize one-per-cycle on that step. Pass an explicit `Channel` (or `callable(index, captures) -> Channel`) when you need to override the default serialization — typically when events arrive on physically parallel buses (multi-bank memory, multi-lane retire) and several instances should consume *concurrently* by routing each to its own per-key channel.
+
+```python
+from collections import defaultdict
+from wavekit import Channel, Pattern
+
+# Multi-bank cache: each bank has its own response port, so two banks
+# can return data in the *same* cycle. Without partitioning, the default
+# serialization rule would force one instance to wait an extra cycle.
+# A per-bank Channel lets each in-flight read consume from its own bank.
+banks = defaultdict(Channel)
+
+result = (
+    Pattern()
+    .wait(req_valid)
+    .capture('bank', req_addr & 1)
+    .wait(
+        lambda i, cap: bank_valid[cap['bank']].value[i],
+        channel=lambda i, cap: banks[cap['bank']],
+    )
+    .capture('rdata',
+        lambda i, cap: bank_data[cap['bank']].value[i])
+    .match()
+)
+```
+
 **`MatchResult`**
 
 | Field | Description |

{wavekit-0.5.6 → wavekit-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "wavekit"
-version = "0.5.6"
+version = "0.6.0"
 description = "a fundamental package for digital circuit waveform analysis"
 authors = ["cxzzzz <cxz19961010@outlook.com>"]
 readme = "README.md"
@@ -12,6 +12,7 @@ include = ["src/wavekit/**/*.so"]
 python = "^3.9"
 numpy = "^2.0.0"
 vcdvcd = "^2.3.5"
+pylibfst = "^0.2.1"
 pytest = "^8.2.2"
 
 [tool.poetry.group.dev.dependencies]

{wavekit-0.5.6 → wavekit-0.6.0}/src/wavekit/__init__.py

@@ -13,10 +13,12 @@ try:
 except metadata.PackageNotFoundError:
     __version__ = 'unknown'
 
+from .pattern import Channel as Channel
 from .pattern import MatchResult as MatchResult
 from .pattern import MatchStatus as MatchStatus
 from .pattern import Pattern as Pattern
 from .pattern import PatternError as PatternError
+from .readers.fst.reader import FstReader as FstReader
 from .readers.vcd.reader import VcdReader as VcdReader
 from .scope import Scope as Scope
 from .signal import Signal as Signal
@@ -27,6 +29,7 @@ __all__ = [
     'Waveform',
     'VcdReader',
     'FsdbReader',
+    'FstReader',
     'Scope',
     'Signal',
     'SignalCompositeType',
@@ -34,6 +37,7 @@ __all__ = [
     'MatchResult',
     'MatchStatus',
     'PatternError',
+    'Channel',
     'has_fsdb_support',
 ]
 

{wavekit-0.5.6 → wavekit-0.6.0}/src/wavekit/pattern/__init__.py

@@ -4,5 +4,6 @@ from .dsl import Pattern as Pattern
 from .engine import PatternError as PatternError
 from .result import MatchResult as MatchResult
 from .result import MatchStatus as MatchStatus
+from .steps import Channel as Channel
 
-__all__ = ['Pattern', 'MatchResult', 'MatchStatus', 'PatternError']
+__all__ = ['Pattern', 'MatchResult', 'MatchStatus', 'PatternError', 'Channel']

{wavekit-0.5.6 → wavekit-0.6.0}/src/wavekit/pattern/dsl.py

@@ -3,8 +3,10 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from .steps import (
+    _VALID_CAPTURE_MODES,
     BranchStep,
     CaptureStep,
+    ChannelValue,
     DelayStep,
     LoopStep,
     RepeatStep,
@@ -15,7 +17,7 @@ from .steps import (
 
 if TYPE_CHECKING:
     from .result import MatchResult
-    from .steps import Condition, IntValue, SignalValue
+    from .steps import CaptureMode, Condition, IntValue, SignalValue
 
 
 class Pattern:
@@ -43,25 +45,73 @@ class Pattern:
     def wait(
         self,
         cond: Condition,
-        guard: Condition | None = None,
-        channel: str | None = None,
+        *,
+        require: Condition | None = None,
+        channel: ChannelValue | None = None,
+        tick: bool = True,
     ) -> Pattern:
         """Block until *cond* becomes True.
 
+        By default each ``wait()`` step has its own private FIFO consumer
+        group: when multiple in-flight instances reach this step, only one
+        (the oldest) advances per cycle.  Pass an explicit :class:`Channel`
+        via ``channel=`` to share the consumer group across multiple wait
+        steps (e.g., for AXI request/response pairing).
+
         Parameters
         ----------
         cond:
             Waveform (static) or ``callable(index, captures) -> bool`` (dynamic).
-        guard:
-            Must remain True every cycle while waiting; violation terminates
-            the instance with ``REQUIRE_VIOLATED``.
+        require:
+            Optional condition that must hold every cycle while waiting.
+            Violation terminates the instance with ``REQUIRE_VIOLATED``.
         channel:
-            Named channel for FIFO event-consumption (see channel docs).
+            Explicit :class:`Channel` (or ``callable(index, captures) -> Channel``
+            for dynamic key-based partitioning) that binds this wait to a
+            shared FIFO consumer group.  ``None`` (default) uses an implicit
+            per-step channel.
+        tick:
+            When ``True`` (default), a successful match advances time by one
+            cycle before the next step is evaluated.  When ``False`` the next
+            step evaluates on the **same** cycle (zero-cycle wait), useful
+            for measuring intervals like ``valid → valid & ready``.
+
+        Examples
+        --------
+        Static channel shared between request and response steps::
+
+            rsp_chan = Channel()
+            (Pattern()
+                .wait(req)
+                .wait(rsp, channel=rsp_chan))
+
+        Dynamic per-ID partitioning for AXI out-of-order reads::
+
+            from collections import defaultdict
+            chans = defaultdict(Channel)
+            (Pattern()
+                .wait(arvalid & arready)
+                .capture('arid', arid)
+                .wait(
+                    lambda i, cap: bool((rvalid & rready)[i]) and rid[i] == cap['arid'],
+                    channel=lambda i, cap: chans[cap['arid']],
+                ))
+
+        Zero-cycle wait::
+
+            (Pattern()
+                .wait(valid)
+                .wait(valid & ready, tick=False))   # measures latency in same-cycle case
         """
-        self._steps.append(WaitStep(cond=cond, guard=guard, channel=channel))
+        self._steps.append(WaitStep(cond=cond, require=require, channel=channel, tick=tick))
         return self
 
-    def delay(self, n: IntValue, guard: Condition | None = None) -> Pattern:
+    def delay(
+        self,
+        n: IntValue,
+        *,
+        require: Condition | None = None,
+    ) -> Pattern:
         """Block for exactly *n* cycles.
 
         Parameters
@@ -69,25 +119,43 @@ class Pattern:
         n:
             Static ``int`` (>= 0) or ``callable(index, captures) -> int``.
             ``delay(0)`` is an epsilon step (no cycle consumed).
-        guard:
-            Must remain True during the delay; violation terminates
-            the instance with ``REQUIRE_VIOLATED``.
+        require:
+            Optional condition that must hold every cycle during the delay.
+            Violation terminates the instance with ``REQUIRE_VIOLATED``.
         """
         if isinstance(n, int) and n < 0:
             raise ValueError(f'delay() requires n >= 0, got {n}')
-        self._steps.append(DelayStep(n=n, guard=guard))
+        self._steps.append(DelayStep(n=n, require=require))
         return self
 
     # ------------------------------------------------------------------
     # Epsilon steps
     # ------------------------------------------------------------------
 
-    def capture(self, name: str, signal: SignalValue) -> Pattern:
+    def capture(
+        self,
+        name: str,
+        signal: SignalValue,
+        *,
+        mode: CaptureMode = 'last',
+    ) -> Pattern:
         """Record a signal value at the current cycle.
 
-        Use ``name[]`` to append to a list (for use inside loop/repeat).
+        Parameters
+        ----------
+        name:
+            Capture key.
+        signal:
+            Waveform (static) or ``callable(index, captures) -> Any``.
+        mode:
+            * ``'last'`` (default) – ``cap[name]`` holds the most recent value
+            * ``'first'`` – ``cap[name]`` holds the first value; subsequent
+              writes are ignored
+            * ``'list'`` – ``cap[name]`` is a list, each write appends
         """
-        self._steps.append(CaptureStep(name=name, signal=signal))
+        if mode not in _VALID_CAPTURE_MODES:
+            raise ValueError(f'capture mode must be one of {_VALID_CAPTURE_MODES}, got {mode!r}')
+        self._steps.append(CaptureStep(name=name, signal=signal, mode=mode))
         return self
 
     def require(self, cond: Condition) -> Pattern:
@@ -166,10 +234,6 @@ class Pattern:
     ) -> MatchResult:
         """Run the pattern engine and return a :class:`MatchResult`.
 
-        If the first step is a ``wait``, its condition is used as the trigger
-        (only fork instances when the condition is True).  Otherwise, an
-        instance is forked on every cycle.
-
         Parameters
         ----------
         start_cycle:

{wavekit-0.5.6 → wavekit-0.6.0}/src/wavekit/pattern/engine.py

@@ -10,6 +10,7 @@ from .result import MatchResult, MatchStatus
 from .steps import (
     BranchStep,
     CaptureStep,
+    Channel,
     Condition,
     DelayStep,
     LoopStep,
@@ -58,8 +59,26 @@ def _eval_signal(signal, index: int, captures: dict) -> Any:
     raise TypeError(f'Invalid signal type: {type(signal)}')
 
 
+def _eval_channel(channel, index: int, captures: dict) -> Channel | None:
+    """Resolve a channel parameter to a :class:`Channel` instance (or ``None``).
+
+    Static :class:`Channel` instances are returned as-is.  Callables are
+    invoked with ``(index, captures)`` and must return a :class:`Channel`.
+    """
+    if channel is None:
+        return None
+    if isinstance(channel, Channel):
+        return channel
+    if callable(channel):
+        result = channel(index, captures)
+        if not isinstance(result, Channel):
+            raise TypeError(f'channel callable must return a Channel instance, got {type(result)}')
+        return result
+    raise TypeError(f'Invalid channel type: {type(channel)}')
+
+
 # ---------------------------------------------------------------------------
-# Waveform collection & validation
+# Waveform & channel collection
 # ---------------------------------------------------------------------------
 
 
@@ -70,11 +89,11 @@ def _collect_waveforms(steps: list[Step]) -> list[Waveform]:
         if isinstance(step, WaitStep):
             if isinstance(step.cond, Waveform):
                 result.append(step.cond)
-            if isinstance(step.guard, Waveform):
-                result.append(step.guard)
+            if isinstance(step.require, Waveform):
+                result.append(step.require)
         elif isinstance(step, DelayStep):
-            if isinstance(step.guard, Waveform):
-                result.append(step.guard)
+            if isinstance(step.require, Waveform):
+                result.append(step.require)
         elif isinstance(step, CaptureStep):
             if isinstance(step.signal, Waveform):
                 result.append(step.signal)
@@ -122,10 +141,13 @@ def _validate_waveforms(waveforms: list[Waveform]) -> None:
 class PatternEngine:
     """NFA-style engine that scans a time axis and runs pattern instances."""
 
+    _next_epoch: int = 0
+
     def __init__(self, pattern) -> None:
         self._steps: list[Step] = pattern._steps
         self._timeout_cycles: int | None = pattern._timeout_cycles
-        self._consumed_channels: set[str] = set()
+        PatternEngine._next_epoch += 1
+        self._epoch: int = PatternEngine._next_epoch
 
     def run(
         self,
@@ -138,12 +160,18 @@ class PatternEngine:
         ref_wf = waveforms[0]
         n = len(ref_wf.value)
 
+        # Channel consumption is keyed on (engine epoch, cycle), so stale
+        # state from a previous run() is automatically invalidated — no
+        # explicit reset is needed for either static or dynamic channels.
+
         # ---- determine trigger mode ----
-        # If first step is a WaitStep, use its cond as trigger and skip it on fork.
-        # Otherwise, fork an instance every cycle.
+        # If the first step is a plain WaitStep without an explicit channel,
+        # use its cond as the fork trigger and skip it on entry.  Wait steps
+        # with an explicit channel must go through normal step processing so
+        # the channel is consumed correctly.
         skip_first_wait = False
         trigger: Condition | None = None
-        if self._steps and isinstance(self._steps[0], WaitStep):
+        if self._steps and isinstance(self._steps[0], WaitStep) and self._steps[0].channel is None:
             trigger = self._steps[0].cond
             skip_first_wait = True
 
@@ -170,9 +198,6 @@ class PatternEngine:
         completed: list[Instance] = []
 
         for t in range(start_idx, end_idx):
-            # Reset per-cycle channel consumption tracking (oldest instance wins)
-            self._consumed_channels = set()
-
             # Tick all active instances in creation order (oldest first)
             still_active: list[Instance] = []
             for inst in active:
@@ -245,8 +270,9 @@ class PatternEngine:
         """Advance the instance, consuming at most *blocking_budget* blocking steps.
 
         Instances are always processed oldest-first within a cycle, so the first
-        instance to reach a channel WaitStep wins and marks the channel consumed
-        in ``self._consumed_channels``; later instances see it as blocked.
+        instance to reach a wait step on a given channel wins; later instances
+        see the channel marked consumed for this ``(epoch, cycle)`` and remain
+        blocked for the cycle.
         """
         epsilon_count = 0
 
@@ -280,21 +306,31 @@ class PatternEngine:
             # -- blocking steps --
 
             if isinstance(step, WaitStep):
-                # Channel check: only the first instance to reach this channel
-                # this cycle may advance; later instances are blocked.
-                channel_free = step.channel is None or step.channel not in self._consumed_channels
-                if blocking_budget > 0 and channel_free and _eval_bool(step.cond, t, inst.captures):
-                    if step.channel is not None:
-                        self._consumed_channels.add(step.channel)
+                eff_channel = _eval_channel(step.channel, t, inst.captures) or step._auto_channel
+                channel_free = (
+                    eff_channel._consumed_epoch != self._epoch or eff_channel._consumed_at != t
+                )
+
+                # tick=True needs blocking budget and consumes a cycle on
+                # match; tick=False is gate-free and stays in the same cycle.
+                if (
+                    (not step.tick or blocking_budget > 0)
+                    and channel_free
+                    and _eval_bool(step.cond, t, inst.captures)
+                ):
+                    eff_channel._consumed_epoch = self._epoch
+                    eff_channel._consumed_at = t
                     frame.step_idx += 1
-                    blocking_budget -= 1
+                    if step.tick:
+                        blocking_budget -= 1
                     continue
-                # Still waiting — check guard
-                if step.guard is not None and not _eval_bool(step.guard, t, inst.captures):
+
+                # Still waiting — check require condition
+                if step.require is not None and not _eval_bool(step.require, t, inst.captures):
                     inst.status = MatchStatus.REQUIRE_VIOLATED
                     inst.end_cycle = int(ref_wf.clock[t])
                     return
-                return  # wait for next tick (budget exhausted or channel blocked)
+                return  # wait for next tick (budget exhausted, channel busy, or cond false)
 
             if isinstance(step, DelayStep):
                 if step.remaining is None:
@@ -306,7 +342,7 @@ class PatternEngine:
                     continue
                 if blocking_budget <= 0:
                     return
-                if step.guard is not None and not _eval_bool(step.guard, t, inst.captures):
+                if step.require is not None and not _eval_bool(step.require, t, inst.captures):
                     inst.status = MatchStatus.REQUIRE_VIOLATED
                     inst.end_cycle = int(ref_wf.clock[t])
                     return
@@ -321,13 +357,15 @@ class PatternEngine:
             # -- epsilon steps --
 
             if isinstance(step, CaptureStep):
-                name = step.name
                 val = _eval_signal(step.signal, t, inst.captures)
-                if name.endswith('[]'):
-                    key = name[:-2]
-                    inst.captures.setdefault(key, []).append(val)
+                if step.mode == 'last':
+                    inst.captures[step.name] = val
+                elif step.mode == 'first':
+                    inst.captures.setdefault(step.name, val)
+                elif step.mode == 'list':
+                    inst.captures.setdefault(step.name, []).append(val)
                 else:
-                    inst.captures[name] = val
+                    raise PatternError(f'Unknown capture mode: {step.mode!r}')
                 frame.step_idx += 1
                 continue