wavekit 0.5.5__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavekit
-Version: 0.5.5
+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
 
@@ -40,11 +47,14 @@ Description-Content-Type: text/markdown
 pip install wavekit
 ```
 
-**Note**: To read FSDB files, ensure the `VERDI_HOME` environment variable is set before installation.
+**Note**: To read FSDB files, the Verdi runtime library (`libNPI.so`) must be available at runtime. Configure via:
+- `WAVEKIT_NPI_LIB` — direct path to `libNPI.so`
+- `VERDI_HOME` — Verdi installation directory (searches `$VERDI_HOME/share/NPI/lib/...`)
+- `LD_LIBRARY_PATH` — system library search path
 
 ## 🚀 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
 
@@ -157,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()
@@ -195,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_HOME`. |
+| `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. |
@@ -258,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. |
@@ -274,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.5 → 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
 
@@ -19,11 +25,14 @@
 pip install wavekit
 ```
 
-**Note**: To read FSDB files, ensure the `VERDI_HOME` environment variable is set before installation.
+**Note**: To read FSDB files, the Verdi runtime library (`libNPI.so`) must be available at runtime. Configure via:
+- `WAVEKIT_NPI_LIB` — direct path to `libNPI.so`
+- `VERDI_HOME` — Verdi installation directory (searches `$VERDI_HOME/share/NPI/lib/...`)
+- `LD_LIBRARY_PATH` — system library search path
 
 ## 🚀 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
 
@@ -136,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()
@@ -174,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_HOME`. |
+| `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. |
@@ -237,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. |
@@ -253,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.6.0/build.py

@@ -0,0 +1,38 @@
+import numpy as np
+from Cython.Build import cythonize
+from setuptools import Extension, setup
+
+extensions = [
+    Extension(
+        'src.wavekit.readers.value_change',
+        sources=['src/wavekit/readers/value_change.pyx'],
+        include_dirs=[np.get_include()],
+        extra_compile_args=['-fpic', '-O3', '-march=native'],
+        extra_link_args=['-O3', '-march=native'],
+        language='c++',
+    ),
+    Extension(
+        'src.wavekit.readers.fsdb.npi_fsdb_reader',
+        sources=['src/wavekit/readers/fsdb/npi_fsdb_reader.pyx'],
+        include_dirs=[np.get_include()],
+        libraries=['dl'],
+        extra_compile_args=['-fpic', '-O3', '-march=native'],
+        extra_link_args=['-O3', '-march=native'],
+        language='c++',
+    ),
+]
+
+setup(
+    ext_modules=cythonize(
+        extensions,
+        compiler_directives={
+            'language_level': 3,
+            'embedsignature': True,
+            'boundscheck': False,
+            'wraparound': False,
+            'cdivision': True,
+            'nonecheck': False,
+        },
+    ),
+    script_args=['build_ext', '--inplace'],
+)

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "wavekit"
-version = "0.5.5"
+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.5 → 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,35 +37,35 @@ __all__ = [
     'MatchResult',
     'MatchStatus',
     'PatternError',
+    'Channel',
     'has_fsdb_support',
 ]
 
-# Detect if FSDB support is available (compiled with VERDI_HOME)
-import importlib.util
-
-_fsdb_available = (
-    importlib.util.find_spec('.readers.fsdb.npi_fsdb_reader', package=__name__) is not None
-)
-
-
-def has_fsdb_support() -> bool:
-    """Check if FsdbReader is available in the current installation."""
-    return _fsdb_available
-
+try:
+    from .readers.fsdb.npi_fsdb_reader import fsdb_runtime_available as _fsdb_runtime_available
+    from .readers.fsdb.reader import FsdbReader as FsdbReader
+except Exception as _fsdb_import_error:
+    _fsdb_available = False
 
-class _FsdbReaderStub:
-    """Placeholder that raises an error when FsdbReader is used without Verdi support."""
+    def has_fsdb_support() -> bool:
+        """Check whether the Verdi FSDB runtime is available."""
+        return False
 
-    def __init__(self, *args, **kwargs):
-        raise RuntimeError(
-            'FsdbReader requires Verdi to be installed and configured.\n\n'
-            '1. Set VERDI_HOME environment variable to your Verdi installation path.\n'
-            '2. Reinstall wavekit:\n'
-            '    pip install --force-reinstall --no-cache-dir --no-deps wavekit'
-        )
+    class _FsdbReaderStub:
+        """Placeholder that raises an error when the Verdi FSDB runtime is unavailable."""
 
+        def __init__(self, *args, **kwargs):
+            raise RuntimeError(
+                'FsdbReader requires the Verdi FSDB runtime (libNPI.so).\n\n'
+                'Set WAVEKIT_NPI_LIB to the library path, set VERDI_HOME to the Verdi '
+                'installation directory, or ensure libNPI.so is in LD_LIBRARY_PATH.\n\n'
+                f'Import error: {_fsdb_import_error}'  # noqa: F821
+            )
 
-if _fsdb_available:
-    from .readers.fsdb.reader import FsdbReader as FsdbReader
-else:
     FsdbReader = _FsdbReaderStub  # type: ignore[assignment]
+else:
+    _fsdb_available = True
+
+    def has_fsdb_support() -> bool:
+        """Check whether the Verdi FSDB runtime is available right now."""
+        return _fsdb_runtime_available()

{wavekit-0.5.5 → 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.5 → 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: