wavekit 0.7.0a1__tar.gz → 0.7.1__tar.gz

{wavekit-0.7.0a1 → wavekit-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavekit
-Version: 0.7.0a1
+Version: 0.7.1
 Summary: a fundamental package for digital circuit waveform analysis
 License-File: LICENSE
 Author: cxzzzz
@@ -30,29 +30,29 @@ Description-Content-Type: text/markdown
 
 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.
+**wavekit** is a high-performance Python library for digital waveform analysis. It loads VCD, FST, and FSDB signals into NumPy-backed `Waveform` objects, and builds on them with efficient signal processing, protocol analysis, and automated verification APIs.
 
-> 🤖 **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.
+> 🤖 **AI integration**: [wavekit-mcp](https://github.com/cxzzzz/wavekit-mcp) provides an MCP server for AI-assisted waveform analysis: load signals and run pattern matching from AI tools without hand-written scripts.
 
-## ✨ Features
+## Features
 
-- **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**: Unified temporal pattern runtime 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.
+- **Batch signal extraction**: use brace expansion, integer ranges, regex, and wildcards to load related signals in one call.
+- **Rich analysis API**: use NumPy-style arithmetic, masking, bit slicing, edge detection, and time/cycle slicing to build signal queries in a few lines.
+- **Temporal pattern matching**: use declarative and programmable Pattern APIs to extract protocol transactions, measure handshake latency, and detect timeout or hang failures.
+- **High-performance waveform processing**: read VCD, FST, and FSDB files into compact NumPy-backed arrays for fast loading and efficient memory use.
 
-## 📦 Installation
+## Installation
 
 ```bash
 pip install wavekit
 ```
 
 **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
+- `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
+## Quick start
 
 > 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.
 
@@ -64,17 +64,16 @@ Use brace expansion or regular expressions to load multiple related signals in o
 from wavekit import VcdReader
 
 with VcdReader("jtag.vcd") as f:
-    # Brace expansion: load J_state and J_next in one call
-    # Returns: { ('state',): Waveform, ('next',): Waveform }
+    # Keys contain BraceCapture objects whose groups are ("state",) / ("next",).
     waves = f.load_matched_waveforms(
         "tb.u0.J_{state,next}[3:0]",
-        clock_pattern="tb.tck",
+        clock_path="tb.tck",
     )
 
-    # Regex mode (@ prefix): capture groups become dict keys
+    # /regex/ is the canonical regex syntax; groups are stored by RegexCapture.
     waves = f.load_matched_waveforms(
-        r"tb.u0.@J_([a-z]+)",
-        clock_pattern="tb.tck",
+        r"tb.u0./J_([a-z]+)/",
+        clock_path="tb.tck",
     )
 ```
 
@@ -82,7 +81,7 @@ with VcdReader("jtag.vcd") as f:
 
 ### 2. Signal Analysis
 
-Waveforms support Numpy-style arithmetic, masking, and edge detection out of the box.
+Waveforms support NumPy-style arithmetic, masking, and edge detection.
 
 ```python
 import numpy as np
@@ -141,8 +140,7 @@ with VcdReader("fifo_tb.vcd") as f:
         clock="fifo_tb.clk",
     )
 
-    # Zip mode: brace patterns expand per key, evaluated once per match
-    # Returns: { (0,): Waveform, (1,): Waveform, (2,): Waveform, (3,): Waveform }
+    # Zip mode: brace patterns expand per typed CaptureKey and evaluate per match.
     occupancies = f.eval(
         "tb.fifo_{0..3}.w_ptr[2:0] - tb.fifo_{0..3}.r_ptr[2:0]",
         clock="tb.clk",
@@ -154,19 +152,24 @@ with VcdReader("fifo_tb.vcd") as f:
 
 ### 4. Pattern Matching
 
-`Pattern` scans a waveform and extracts all matching transactions — a request/response pair, a burst, a stall interval, or any other repeating timing pattern.
+`Pattern` scans a waveform and extracts matching transactions, such as a request/response pair, a burst, a stall interval, or another repeating timing pattern.
 
-There are two ways to describe a pattern:
+Choose the form that matches the transaction shape:
 
-- **Declarative** — chain steps like `.wait()`, `.consume()`, `.capture()`, `.loop()`. Best for fixed transaction flows.
-- **Programmable** — pass a handler function to `Pattern(...)`. Best for dynamic branches, per-ID routing, and other complex flows.
+- **Declarative**: use `.wait()`, `.consume()`, `.capture()`, and `.loop()` steps to describe fixed flows.
+- **Programmable**: use a normal Python function when the flow depends on waveform values, such as dynamic branches or per-ID routing.
+
+In declarative patterns, the first blocking step selects transaction start cycles; later blocking steps describe timing within each matched transaction.
+
+`match(pattern)` returns `MatchRecords`, while `collect(body)` returns a Python `list` of extracted values.
 
 #### Declarative examples
 
 **AXI-Lite read latency**
 
 ```python
-from wavekit import VcdReader, Pattern
+from wavekit import VcdReader
+from wavekit.pattern import Pattern, match, collect
 
 with VcdReader("axi_tb.vcd") as f:
     clk     = "tb.clk"
@@ -176,16 +179,17 @@ with VcdReader("axi_tb.vcd") as f:
     rready  = f.load_waveform("tb.dut.rready",      clock=clk)
     rdata   = f.load_waveform("tb.dut.rdata[31:0]", clock=clk)
 
-    result = (
-        Pattern(timeout=256)
+    pattern = (
+        Pattern()
         .wait(arvalid & arready)   # AR handshake → transaction starts
         .wait(rvalid  & rready)    # R  handshake → transaction ends
         .capture("rdata", rdata)
-        .match()
     )
+    result = match(pattern)
 
     ok = result.filter_ok()
-    print(f"Read latencies (cycles): {ok.duration.value}")
+    latency = ok.end.clock - ok.start.clock
+    print(f"Read latencies (cycles): {latency}")
     print(f"Read data: {ok.captures['rdata'].value}")
 ```
 
@@ -194,13 +198,12 @@ with VcdReader("axi_tb.vcd") as f:
 ```python
 beat = Pattern().consume(wvalid & wready, channel="w").capture("beats", wdata, mode="list")
 
-result = (
+pattern = (
     Pattern()
     .wait(awvalid & awready)   # AW handshake → burst starts
     .loop(beat, until=wlast)   # collect each beat until wlast
-    .timeout(512)
-    .match()
 )
+result = match(pattern)
 
 for i, inst in enumerate(result.filter_ok()):
     print(f"Burst {i}: {len(inst.captures['beats'])} beats")
@@ -211,57 +214,81 @@ for i, inst in enumerate(result.filter_ok()):
 ```python
 stall = valid & (ready == 0)
 
-result = (
+pattern = (
     Pattern()
     .wait(stall.rising_edge())             # stall begins
     .loop(Pattern().delay(1), when=stall)  # keep waiting until stall ends
-    .match()
 )
+result = match(pattern)
 
 stalls = result.filter_ok()
-print(f"Stall durations: {stalls.duration.value} cycles")
+stall_cycles = stalls.duration.value - 1
+print(f"Stall durations: {stall_cycles} cycles")
 ```
 
 #### Programmable example
 
-**Out-of-order AXI reads by ID**
+**DMA-style command stream**
 
-When R beats from different IDs interleave on the bus, match each AR to its response beats by `arid` and collect results as Python dicts.
+Use programmable control flow when a command's opcode changes the following timing shape.
 
 ```python
-arfire = arvalid & arready   # precompute outside the handler
-rfire = rvalid & rready
-
-async def read_burst(ctx):
-    if ctx.value(arfire):
-        my_id = ctx.value(arid)
-        beats = []
-
-        while True:
-            await ctx.consume(
-                lambda: ctx.value(rfire) and ctx.value(rid) == my_id,
-                channel=("r", my_id),
-            )
-            beats.append(int(ctx.value(rdata)))
-            if ctx.value(rlast):
-                break
-
-        return {"arid": my_id, "beats": beats}
+cmd_fire = cmd_valid & cmd_ready   # precompute outside the handler
+w_fire = w_valid & w_ready
+rsp_fire = rsp_valid & rsp_ready
+r_fire = r_valid & r_ready
+
+OP_READ = 0
+OP_WRITE = 1
+
+def read_dma_cmd(ctx):
+    if not ctx.value(cmd_fire):
+        return None
+
+    op = int(ctx.value(cmd_op))
+    addr = int(ctx.value(cmd_addr))
+    length = int(ctx.value(cmd_len))
+
+    if op == OP_WRITE:
+        data = []
+        for _ in range(length):
+            ctx.consume(w_fire, channel="wdata")
+            data.append(int(ctx.value(w_data)))
+
+        ctx.consume(rsp_fire, channel="rsp")
+        return {
+            "op": "write",
+            "addr": addr,
+            "data": data,
+            "status": int(ctx.value(rsp_status)),
+        }
+
+    if op == OP_READ:
+        ctx.consume(rsp_fire, channel="rsp")
+        data = []
+        for _ in range(length):
+            ctx.consume(r_fire, channel="rdata")
+            data.append(int(ctx.value(r_data)))
+
+        return {"op": "read", "addr": addr, "data": data}
+
+    ctx.require(False, message=f"unknown DMA op {op}")
     return None
 
-records = Pattern(read_burst, timeout=64).collect()
+commands = collect(read_dma_cmd)
+print(f"Captured {len(commands)} commands")
 ```
 
 Some tips for programmable patterns:
 
-- Precompute fixed waveform expressions (like `fire = valid & ready`) outside
-  the handler function so they aren't rebuilt every cycle.
-- Start the handler with `if ctx.value(fire): ...` and `return None`
-  otherwise — this tells the runtime which cycles begin a transaction.
+- Precompute fixed waveform expressions, such as `fire = valid & ready`, outside the handler so they are not rebuilt every cycle.
+- Start the handler with `if ctx.value(fire): ...` to test whether the current cycle starts a transaction, and `return None` otherwise.
+- Use `ctx.try_consume(...)` for non-blocking polling or arbitration between candidate channels. For a linear burst, `ctx.consume(...)` is more direct.
+- Add `timeout=<cycles>` only when a blocking step needs a wait bound. In `match()`, timeout becomes `MatchStatus.Timeout(...)`; in `collect()`, it raises `PatternError`.
 
 ---
 
-## 📖 API Reference
+## API reference
 
 ### Reader
 
@@ -270,22 +297,35 @@ Some tips for programmable patterns:
 | `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_unknown_mask(signal, clock, ...)` | **Experimental.** Load X/Z bit presence as an unsigned mask `Waveform`. |
-| `reader.load_matched_waveforms(pattern, clock_pattern, ...)` | Batch-load signals matching a brace/regex pattern. Returns `dict[tuple, Waveform]`. |
-| `reader.load_matched_unknown_masks(pattern, clock_pattern, ...)` | **Experimental.** Batch-load X/Z masks for matched signals. Returns `dict[tuple, Waveform]`. |
+| `reader.load_matched_waveforms(signal_path, clock_path, ...)` | Batch-load matching signals. Returns `dict[CaptureKey, Waveform]`. |
+| `reader.load_matched_unknown_masks(signal_path, clock_path, ...)` | **Experimental.** Batch-load X/Z masks for matched signals. Returns `dict[CaptureKey, Waveform]`. |
 | `reader.eval(expr, clock, mode='single'\|'zip', ...)` | Evaluate an arithmetic expression with embedded signal paths. |
-| `reader.get_matched_signals(pattern)` | Resolve a pattern to signal paths without loading data. |
-| `reader.top_scope_list()` | Return root `Scope` nodes of the signal hierarchy. |
-
-**Pattern syntax** used in signal paths:
-
-| Syntax | Example | Effect |
-|--------|---------|--------|
-| `{a,b,c}` | `sig_{read,write}` | Enumerate named variants |
-| `{N..M}` | `fifo_{0..3}.ptr` | Integer range |
-| `{N..M..step}` | `lane_{0..6..2}` | Stepped range |
-| `@<regex>` | `@([a-z]+)_valid` | Regex with capture groups |
-| `$ModName` | `tb.$fifo_unit.ptr` | Match a direct-child scope by module/definition name (FSDB only) |
-| `$$ModName` | `tb.$$fifo_unit.ptr` | Match any-depth descendant scope by module/definition name (FSDB only) |
+| `reader.get_matched_signals(path)` | Resolve a query to `Signal` objects without loading data. |
+| `reader.get_matched_scopes(path)` | Resolve a query to `Scope` objects. |
+| `reader.top_scopes` | Immutable tuple of root `Scope` nodes. |
+| `has_fsdb_support()` | Report whether the Verdi FSDB runtime is currently available. |
+
+### Signal path patterns
+
+| Syntax | Example | Effect | Capture in result key |
+|--------|---------|--------|-----------------------|
+| Plain name | `tb.dut.valid` | Exact-name match | None |
+| `{a,b,c}` | `sig_{read,write}` | Enumerate named variants | `BraceCapture(path=..., groups=...)` |
+| `{N..M}` | `fifo_{0..3}.ptr` | Integer range | `BraceCapture(path=..., groups=...)` |
+| `{N..M..step}` | `lane_{0..6..2}` | Stepped range | `BraceCapture(path=..., groups=...)` |
+| `/<regex>/` | `/([a-z]+)_valid/` | Canonical regex syntax with capture groups | `RegexCapture(path=..., groups=...)` |
+| `@<regex>` | `@([a-z]+)_valid` | Legacy-compatible regex syntax | `RegexCapture(path=..., groups=...)` |
+| `*` / `**` | `tb.*.valid` / `tb.**.valid` | Single-level / recursive wildcard | `WildcardCapture(path=...)` |
+| `$ModName` | `tb.$fifo_unit.ptr` | Match a direct-child scope by module/definition name (FSDB only) | `ExactCapture(path=..., definition=...)` |
+| `$$ModName` | `tb.$$fifo_unit.ptr` | Match any-depth descendant scope by module/definition name (FSDB only) | `ExactCapture(path=..., definition=...)` |
+
+`$` and `$$` are path-step modifiers: they can combine with exact names, brace
+expansion, regex, and a trailing range selector in the same query.
+For example: `tb.$/fifo_(in|out)/.data_{0..3}[7:0]`.
+
+Matched-reader and hierarchy query APIs return dictionaries keyed by
+`CaptureKey = tuple[Capture, ...]`. Exact-name components are omitted, so a
+fully exact query uses key `()`.
 
 ---
 
@@ -311,7 +351,8 @@ A `Waveform` wraps three parallel numpy arrays (`.value`, `.clock`, `.time`). Al
 | Method | Description |
 |--------|-------------|
 | `wave.map(fn, width, signed)` | Element-wise transform |
-| `wave.unique_consecutive()` | Remove consecutive duplicates |
+| `wave.unique_consecutive()` | Remove consecutive duplicate values |
+| `wave.compress()` | Compact a waveform while preserving value changes and the final sample |
 | `wave.downsample(chunk, fn)` | Aggregate into chunks |
 | `wave.as_signed()` / `wave.as_unsigned()` | Reinterpret signedness |
 
@@ -358,28 +399,25 @@ changed = wave != wave.back(3)
 
 | API | Description |
 |-----|-------------|
-| `Pattern(timeout=..., max_active=...)` | Create a Declarative Pattern. Add steps with builder methods, then call `.match()`. |
-| `Pattern(async_fn, timeout=..., max_active=...)` | Create a Programmable Pattern. The async function receives `ctx`. |
-| `.match(start_cycle=None, end_cycle=None)` | Run the pattern and return `MatchResult`. In a Programmable Pattern, return `ctx.OK` for success and `None` to skip. |
-| `.collect(start_cycle=None, end_cycle=None)` | Programmable Pattern only. Collect each non-`None` Python return value. |
+| `Pattern()` | Create a declarative Pattern. Add steps with builder methods; execution options live on `match()` / `collect()`. |
+| `match(pattern_or_body, *, axis=None, timeout=None, timeout_message=None, start_cycle=None, end_cycle=None)` | Run a declarative Pattern or programmable check body and return `MatchRecords`. Check bodies return `ctx.OK` or `None`. |
+| `collect(body, *, axis=None, timeout=None, timeout_message=None, start_cycle=None, end_cycle=None)` | Run a programmable extraction body and collect each non-`None` Python return value. |
 
 **Declarative Steps**
 
 | Method | Description |
 |--------|-------------|
-| `.wait(cond, *, require=None)` | Block until `cond` is True without consuming the event. Resumes in the same cycle when already true; use `.delay(1)` for next-cycle behavior. `require` is checked each waiting cycle (failure → `REQUIRE_VIOLATED`). |
-| `.consume(cond, channel, *, require=None)` | Block until `cond` is True and this instance can exclusively consume from `channel`. Resumes in the same cycle on success. Use this for FIFO request/response pairing and per-key routing. |
-| `.delay(n, *, require=None)` | Advance `n` cycles. `delay(0)` is a no-op. `require` must hold every cycle. |
+| `.wait(cond, *, require=None, require_message=None)` | Block until `cond` is True without consuming the event. Resumes in the same cycle when already true; use `.delay(1)` for next-cycle behavior. `require` is checked each waiting cycle (failure → `MatchStatus.RequireViolated`). |
+| `.consume(cond, channel, *, require=None, require_message=None)` | Block until `cond` is True and this instance can exclusively consume from `channel`. Resumes in the same cycle on success. Use this for request/response pairing and per-key routing. |
+| `.delay(n, *, require=None, require_message=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. |
+| `.require(cond)` | Assert condition; fail with `MatchStatus.RequireViolated` 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. |
 | `.branch(cond, true_body, false_body)` | Conditional branch. |
-| `.timeout(max_cycles)` | Terminate unfinished instances with `TIMEOUT`. |
 
 The same time and ownership operations are available inside Programmable
-Patterns as `await ctx.wait(...)`, `await ctx.consume(...)`, and
-`await ctx.delay(...)`.
+patterns as `ctx.wait(...)`, `ctx.consume(...)`, and `ctx.delay(...)`.
 
 **Programmable Context**
 
@@ -388,38 +426,40 @@ Patterns as `await ctx.wait(...)`, `await ctx.consume(...)`, and
 | `ctx.value(waveform, offset=0)` | Read a scalar value at the current sample plus optional offset. |
 | `ctx.cycle(waveform, offset=0)` | Read the cycle number at the current sample plus optional offset. |
 | `ctx.time(waveform, offset=0)` | Read the timestamp at the current sample plus optional offset. |
-| `await ctx.wait(cond, require=None)` | Observe cycles until `cond` is true; does not consume the event. |
-| `await ctx.consume(cond, channel, require=None)` | Wait for `cond` and exclusively consume from `channel`. |
-| `await ctx.delay(n, require=None)` | Advance `n` cycles. |
-| `ctx.capture(name, value, mode='last')` | Record a capture for programmable `.match()`. |
-| `ctx.OK` | Return from programmable `.match()` to record a successful match. |
+| `ctx.wait(cond, require=None, require_message=None)` | Observe cycles until `cond` is true; does not consume the event. |
+| `ctx.consume(cond, channel, require=None, require_message=None)` | Wait for `cond` and exclusively consume from `channel`. |
+| `ctx.try_consume(cond, channel)` | Poll `channel` without blocking. Returns `True` only when both the condition and channel are available. |
+| `ctx.delay(n, require=None, require_message=None)` | Advance `n` cycles. |
+| `ctx.capture(name, value, mode='last')` | Record a capture for programmable `match()`. |
+| `ctx.OK` | Return from programmable `match()` to record a successful match. |
 
 **Dynamic callbacks**
 
-Declarative callbacks use `callable(index, captures)`. `index` is the absolute
-waveform sample index; it is not rebased when `match(start_cycle=...)` is used.
+Callback arguments depend on whether the callback is used in the declarative API or the programmable API:
+
+- In declarative APIs such as `Pattern().wait(...)` and `Pattern().consume(...)`, callbacks receive `(index, captures)`.
+- In programmable functions, callbacks passed to methods such as `ctx.wait(...)` and `ctx.consume(...)` take no arguments. If they need the current index, captures, or signal values, close over `ctx`.
 
 **Channels and consume vs. wait**
 
-When multiple in-flight instances are waiting for the same kind of event, plain
-`wait()` won't pair each request with its own response — every instance sees
-every event. `consume()` solves this: it hands the event to exactly one instance
-per cycle, in FIFO order.
+`wait()` is observational: every matching instance can see the same event.
+`consume()` adds ownership: only one instance can claim a given `(channel, cycle)`.
+On the same channel, matches with earlier start cycles claim available events first.
 
-A `Channel` is the FIFO queue that `consume()` uses. Pass a `Channel` object, a
-hashable key, or a dynamic callback to `consume(..., channel=...)`. All
-instances sharing the same channel key consume from the same queue.
+A `Channel` is an identity token for consume ownership. Pass a `Channel` object,
+a hashable key, or a dynamic callback to `consume(..., channel=...)`. All
+instances sharing the same channel key compete for the same logical channel.
 
 ```python
 from collections import defaultdict
-from wavekit import Channel, Pattern
+from wavekit.pattern import Channel, Pattern, match
 
-# Multi-bank cache: each bank has its own response port, so two banks
-# can return data in the *same* cycle. A per-bank Channel lets each in-flight
-# read consume from its own bank while preserving FIFO order within that bank.
+# Multi-bank cache: each bank has its own response port, so two banks can return
+# data in the same cycle. Per-bank channels let independent requests consume
+# independent response streams.
 banks = defaultdict(Channel)
 
-result = (
+pattern = (
     Pattern()
     .wait(req_valid)
     .capture('bank', req_addr & 1)
@@ -429,27 +469,30 @@ result = (
     )
     .capture('rdata',
         lambda i, cap: bank_data[cap['bank']].value[i])
-    .match()
 )
+result = match(pattern)
 ```
 
-**`MatchResult`**
+**`MatchRecords`**
 
 | Field | Description |
 |-------|-------------|
-| `.start` / `.end` | Start and end cycle of each match (both inclusive). |
-| `.duration` | `end - start + 1` cycles. |
-| `.status` | `MatchStatus.OK`, `TIMEOUT`, or `REQUIRE_VIOLATED`. |
+| `.start` / `.end` | Point Waveforms. `.value` is the waveform-array sample index, `.clock` is the absolute cycle, and `.time` is the simulation timestamp. End is inclusive. |
+| `.duration` | `end.value - start.value + 1` sampled cycles. |
+| `.status` | `MatchStatus.OK()`, `MatchStatus.Timeout(...)`, or `MatchStatus.RequireViolated(...)`. |
 | `.captures` | `dict[str, Waveform]` of captured values. |
-| `.ok` | Boolean Waveform where `status == MatchStatus.OK`. |
-| `.failed` | Boolean Waveform where `status != MatchStatus.OK`. |
+| `.ok` | Boolean Waveform where `status == MatchStatus.OK()`. |
+| `.failed` | Boolean Waveform where `status != MatchStatus.OK()`. |
 | `.filter_ok()` | Return only `OK` matches. |
-| `.filter_status(status)` | Return only matches with the given `MatchStatus` or integer status. |
+| `.filter_status(status_class)` | Return only matches with the given status class, such as `MatchStatus.Timeout`. |
 | `.filter_failed()` | Return only non-OK matches. |
 
+`MatchRecords[i]` returns a single `MatchRecord`, and slices return another
+`MatchRecords` batch.
+
 ---
 
-## 🛠️ Development
+## Development
 
 This project uses [Poetry](https://python-poetry.org/) for dependency management and packaging.
 
@@ -497,9 +540,9 @@ poetry run ruff format .
 poetry run mypy .
 ```
 
-## 🤝 Contributing
+## Contributing
 
-Contributions are welcome! Please open an issue to discuss a bug or feature request before submitting a pull request. When contributing code, make sure all tests pass and the linter reports no errors:
+Issues and pull requests are welcome. Before sending a pull request, run the tests and format checks:
 
 ```bash
 poetry run pytest
@@ -507,7 +550,7 @@ poetry run ruff check .
 poetry run ruff format --check .
 ```
 
-## 📄 License
+## License
 
 This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.