fpstreams 2.4.1__tar.gz → 2.5.0__tar.gz

{fpstreams-2.4.1 → fpstreams-2.5.0}/CHANGELOG.md

@@ -1,9 +1,221 @@
 # Changelog
 
-This file records user-visible and compatibility-relevant changes in fpstreams 2,
+This file records user-visible and compatibility-relevant changes in fpstreams,
 including changed defaults.
 
-## Unreleased
+## 2.5.0
+
+Version 2.5.0 includes an intentional static typing incompatibility: `Collectors.averaging()` now
+returns `object` in type annotations rather than incorrectly promising `float`.
+Runtime arithmetic is unchanged. Use `Collectors.averaging_with()` for explicit
+accumulator and result types, or narrow the legacy result before use.
+
+Dynamic `reduce()` remains dynamically typed. For an explicit accumulator
+contract, use an annotated `Flow.fold()` result or `AsyncFlow.fold_async()`.
+The migration examples are in the collecting and async flow reference pages;
+2.5.0 does not claim to solve automatic `reduce()` inference.
+
+### Added
+
+- `AsyncFlow.fold_async()` provides an explicit asynchronous state contract.
+  Use annotated `Flow.fold()` or `AsyncFlow.fold_async()` results when migrating
+  dynamic `reduce()` calls to a declared accumulator type.
+- `Collectors.averaging_with()` accepts typed accumulation, division, and empty
+  result callbacks for numeric types and custom arithmetic.
+- `Rows.drop_nulls(missing="raise")` propagates lookup failures. Callable
+  selectors can define actual absence by returning `None`; the default
+  `missing="legacy"` preserves historical lookup handling.
+- `Collectors.averaging()` now declares its result as `object`, replacing the
+  inaccurate `float` annotation. Runtime arithmetic is unchanged; migrate typed
+  consumers to `averaging_with()` or narrow the result explicitly.
+- `Flow.chunk()` and `AsyncFlow.chunk()` accept `strict=True` to reject an
+  incomplete final batch during consumption. The `batch` aliases also support it.
+- `Collectors.frequencies()` counts hashable inputs in first-encounter order and
+  composes with synchronous, asynchronous, and grouped collectors.
+- `Collectors.mode()` finds the most frequent hashable value in sync, async,
+  and grouped collection, with first-encountered tie breaking.
+- Extend experimental free-threaded core-concurrency CI to Python 3.15t alongside
+  3.14t. Check that native import keeps the GIL disabled, and keep optional adapter
+  dependencies out of these jobs through the shared `test-core` group.
+- Add standard CPython 3.15 to the runtime and consumer typing CI matrices.
+  The frozen data-adapter environment now uses pandas 3.0.6 and PyArrow 26.0.0
+  with Python 3.15 wheels.
+- Runnable resource-ownership examples cover early termination, callback errors,
+  and caller cancellation. CI executes their documented code without optional extras.
+- `Collectors.statistics(selector, ddof=0)` computes count, mean, variance, and
+  standard deviation with one selection and conversion per valid item.
+- Optional `fpstreams[sketch]` collectors provide KLL approximate quantiles and
+  HLL approximate distinct counts through the existing sync, async, and grouped
+  reduction interfaces. Exact collectors keep their existing behavior.
+- `Flow.rolling_statistics(size, selector=..., ddof=0)` and its async equivalent
+  emit count, mean, and variance for recent items, including warmup windows.
+  They reuse `map_accum`, with independent state for every evaluation.
+- `Rows.explain().to_dict(include_field_dependencies=True)` exports static field dependencies.
+  Direct projections, computed columns, renames, and supported relational
+  operations retain source identities; unsupported operations report unknown
+  dependencies. Value inputs and row selection inputs are reported separately.
+
+### Performance
+
+- Use C-backed batching for eligible strict retained-list chunks and exact
+  generator, map, and filter cursors on Python 3.12+. Python 3.11 and custom
+  cursors retain their iterator path.
+- Reduce intermediate generator calls in legacy Gatherers and selected-field
+  `Rows.drop_nulls()` while preserving lookup errors and short-circuiting.
+- Use an optional Rust numeric window state for rolling statistics. Selection
+  and numeric conversion remain in Python. Explicit Python execution and
+  extensions without this capability retain the reference implementation.
+
+### Fixed
+
+- Preserve the original custom-key hash exception in synchronous and asynchronous
+  per-key reductions, frequency counts, Pair collection, and in-memory Python
+  joins and grouping on CPython 3.14 and 3.15. Keep hash calls, raw key identity, and source cleanup unchanged.
+
+- Reuse each compiled scalar stage's validated fingerprint for the physical-plan
+  cache instead of encoding the same expression again. Row expressions remain
+  outside structural caches.
+
+- NumPy filter planning checks numeric classes by identity, preserving Python
+  fallback for custom integer types whose metaclasses define hashing or equality.
+- Materializing deep `RowExpr` maps and filters skips the unused structural
+  fingerprint and reaches the iterative evaluator when direct compilation is bounded.
+- Row-expression effect analysis visits shared IR nodes once. Evaluation still
+  executes each occurrence, including repeated selectors and callbacks.
+
+- Close the iterator returned by custom Rows/Flow iteration in `to_columns()`
+  after exhaustion or conversion failure, preserving the primary error.
+- Respect custom row iteration in `arrow_batches()` with default or explicit
+  schemas. Check iteration at consumption time while retaining eligible native
+  paths and bounded batch conversion.
+
+- Finish a cancelled child's cleanup before propagating cancellation of its drain
+  waiter. Repeated caller cancellation no longer interrupts that cleanup or lets
+  timeout operators close the source before its pending pull has stopped.
+
+- Preserve each result when a shared row-expression node is evaluated more than
+  once. Stateful callbacks and dynamic selectors now agree with direct evaluation
+  in the iterative fallback, including nested lazy operands.
+
+- Convert Arrow extension columns on pandas 2.0 without the dataframe interchange
+  protocol when copying is allowed. Keep conversion lazy and exclude index columns.
+- Preserve zero-column row counts in Polars output, including bounded batches,
+  on the declared minimum Polars version.
+
+- Keep generated row and scalar functions compatible with Python 3.11 AST types.
+
+- Reject NaN async durations before opening a source or starting work. Zero stays
+  valid for `interval` and `debounce`. An invalid timer rearm preserves its
+  existing timer task.
+
+- Normalize integer counts for `merge_map` concurrency and synchronous parallel
+  workers/buffers before execution. Noninteger values raise `TypeError`, and later
+  mutation of an integer-like configuration object cannot change the stored limit.
+
+- Require integer capacities for plan and kernel caches, normalizing integer-like
+  values once so later mutation cannot change the configured bound.
+
+- Accept inner async iterators without an `aclose` hook in `merge_map` and
+  `switch_map`. Optional hooks may return an awaitable or a synchronous value;
+  cleanup retains the hook selected when the inner opens.
+
+- Close the owned outer source when `switch_map` cannot submit its first pull
+  task, retaining the submission error and any source cleanup diagnostics.
+  Root ownership also covers unstarted intermediate stages and sync-to-async
+  adapters without consuming an item or repeating source close.
+
+- Drain existing scope tasks before closing upstream resources when a task factory
+  rejects the cleanup task. The original submission error remains observable.
+
+- Preserve JSON Lines record boundaries when disabling the byte limit. Managed
+  paths now use LF/CRLF framing in both modes; borrowed text handles retain the
+  caller's newline handling.
+
+- Require an initial BOM for nonempty JSON Lines input using generic UTF-16/32
+  codecs, consistently across byte-limit modes. Explicit byte-order codecs
+  continue to support data without a BOM.
+
+- Handle UTF-8 signatures consistently across bounded and unbounded JSON Lines
+  sources. A signature before a later record is no longer silently discarded.
+
+- Wait for in-flight asynchronous file operations before completing cancellation
+  or closing their handles, including cancellation during file acquisition.
+
+- Preserve asynchronous file read errors and caller cancellation when file close
+  also fails. Close failures still propagate after exhaustion or early termination.
+
+- Preserve serialization errors when text writer and source cleanup also fail.
+  Atomic CSV, JSON, and JSON Lines exports keep the previous destination on failure.
+
+- Preserve checkpoint callback failures when staging cleanup or lock-file close also
+  fails. Retries verify and reuse entries published before a later cleanup error.
+
+- Clarify how asynchronous `reduce`, `reduce_right`, and `fold_right` resolve
+  reducer results while preserving initial values and singleton items unchanged.
+
+- Preserve operation errors and continue closing owned resources when a cleanup
+  exception raises while formatting its message.
+
+- Preserve element and fallback types for synchronous and asynchronous `first`,
+  `last`, `find`, and `nth` results. Calls without a default retain the element type.
+
+- Retain annotated container Collector results for `Any` input elements and
+  infer awaited callable results in async collection. Optional-collector
+  forwarding and named results keep their existing contracts.
+- Preserve inferred Collector element/result types for direct container factories
+  while retaining explicit `Collectors[int]` construction. Per-key collection
+  keeps the collector state type; input variance reflects consumption.
+- Reject non-real numeric scalars such as NumPy `complex64` before converting
+  statistical inputs or quantile ranks to floats. Decimal, Fraction, and real
+  NumPy scalar inputs keep their existing support.
+- Concurrent async mapping can emit completed results while the source is still
+  waiting to produce another item. With concurrency above one, a reader task
+  also counts against the query's task limit.
+- `map_async()` normalizes `buffer` through the integer-index protocol when the
+  pipeline is built, rejecting noninteger bounds before opening the source.
+- Python and Rust variance calculations retain small differences in data with a
+  large common offset. Existing nonfinite-input policies remain unchanged.
+- `Flow.to_async()` preserves its item type, and `Flow.pairs()` preserves tuple
+  key and value types. Dynamic pair inputs keep their existing runtime support.
+- Native integer and floating-point range endpoints periodically check Python
+  signals during long scans.
+- Reuse native range bounds for periodic signal checks, avoiding a separate
+  per-item countdown while preserving the 4096-input check interval.
+
+### Changed
+
+- Retained primitive Arrow sources with a complete compatible columnar prefix
+  collect directly into `to_list()`, preserving conversion and cleanup hooks.
+- Optional field-dependency export reuses each computed-column analysis within
+  its step while preserving opaque-expression short circuiting.
+
+- Keep performance runners and their regression fixtures local to maintainers.
+  Public source distributions and CI retain library checks without benchmark
+  components or hosted timing jobs.
+- Consolidate internal async execution, pair execution, semantic analysis,
+  relational planning, terminal helpers, Arrow planning/execution, pair planning,
+  and I/O into domain packages. Public
+  imports remain unchanged; private implementation paths have moved.
+- Release excess native numeric vector capacity before constructing list, tuple,
+  or set results, reducing overlapping temporary storage.
+- Read row-stage metadata without a shared registry lock. Registration and
+  reclamation remain synchronized, with weak owner and executable-code checks.
+- Reuse expression analysis within each field-dependency export. Spill partition
+  writes consume their existing byte buffers without an intermediate copy.
+- Guarded Arrow projections can retain builtin scalar and list columns after
+  full buffer validation. Unsupported nested types retain row conversion.
+- Plan reasons distinguish representation selection from terminal execution.
+- Separate Arrow numeric reductions and retained sorting from batch dispatch,
+  preserving the existing execution entry points and live callback bindings.
+- Document the existing v2 `compact()` difference between Flow and AsyncFlow;
+  use `filter_none()` to retain falsey values other than `None` in both domains.
+- Correct CSV scan documentation: query projection follows conversion of all
+  caller-visible columns. Explicit Arrow conversion options can restrict the
+  reader's columns.
+- Release qualification reuses CI before building distributions. New Python
+  3.11 adapter jobs exercise `lowest-direct` and `highest` dependency resolutions;
+  Windows and macOS smoke selections include async cancellation and executor
+  ownership paths. Hosted qualification results remain to be established.
 
 ## 2.4.1 - 2026-10-18
 

{fpstreams-2.4.1 → fpstreams-2.5.0}/PKG-INFO

@@ -1,16 +1,19 @@
 Metadata-Version: 2.4
 Name: fpstreams
-Version: 2.4.1
+Version: 2.5.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
+Requires-Dist: typing-extensions>=4.12 ; python_full_version < '3.13'
+Requires-Dist: datasketches>=5.2,<6 ; extra == 'all'
 Requires-Dist: hypothesis>=6.138,<7 ; extra == 'all'
 Requires-Dist: pytest>=9.0.3,<10 ; extra == 'all'
 Requires-Dist: pytest-cov>=7,<8 ; extra == 'all'
@@ -27,6 +30,7 @@ Requires-Dist: pandas>=2 ; extra == 'data'
 Requires-Dist: pyarrow>=16 ; extra == 'data'
 Requires-Dist: polars>=1.34 ; extra == 'polars'
 Requires-Dist: pyarrow>=16 ; extra == 'polars'
+Requires-Dist: datasketches>=5.2,<6 ; extra == 'sketch'
 Requires-Dist: hypothesis>=6.138,<7 ; extra == 'test'
 Requires-Dist: pytest>=9.0.3,<10 ; extra == 'test'
 Requires-Dist: pytest-cov>=7,<8 ; extra == 'test'
@@ -40,6 +44,7 @@ Provides-Extra: arrow
 Provides-Extra: async
 Provides-Extra: data
 Provides-Extra: polars
+Provides-Extra: sketch
 Provides-Extra: test
 License-File: LICENSE
 Summary: Lazy Python pipelines for iterables and records, with bounded async concurrency.
@@ -53,21 +58,33 @@ Project-URL: Changelog, https://github.com/steventimes/fpstreams/blob/master/CHA
 Project-URL: Documentation, https://steventimes.github.io/fpstreams/
 Project-URL: Homepage, https://github.com/steventimes/fpstreams
 
+![fpstreams — Lazy Python pipelines. Explicit resource ownership.](.github/readme/banner.svg)
+
 # fpstreams
 
+[Install](#install) · [Quick start](#quick-start) · [Examples](#what-is-in-v2) · [Engines](#execution-engines) · [Documentation](https://steventimes.github.io/fpstreams/)
+
+| Work with | Start with | Execution |
+| --- | --- | --- |
+| Values and records | `flow()` | Lazy synchronous pipelines |
+| Async inputs and calls | `aflow()` | Bounded concurrent work |
+| Key/value data | `pairs()` | Per-key collection and aggregation |
+
 [![CI](https://github.com/steventimes/fpstreams/actions/workflows/ci.yml/badge.svg)](https://github.com/steventimes/fpstreams/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/fpstreams.svg)](https://pypi.org/project/fpstreams/)
 [![Python](https://img.shields.io/pypi/pyversions/fpstreams.svg)](https://pypi.org/project/fpstreams/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/steventimes/fpstreams/blob/master/LICENSE)
+[![XERJ Corpus Hub contributor](https://hub.xerj.org/contributors/steventimes/badge.svg)](https://hub.xerj.org/contributors/steventimes)
 
 [Documentation](https://steventimes.github.io/fpstreams/) · [Browser playground](https://steventimes.github.io/fpstreams/playground/) · [Changelog](https://github.com/steventimes/fpstreams/blob/master/CHANGELOG.md) · [Contributing](https://github.com/steventimes/fpstreams/blob/master/CONTRIBUTING.md)
 
-Lazy Python pipelines for iterables and records, with bounded async concurrency.
+Process Python objects and async inputs with lazy pipelines, bounded concurrent
+work, and explicit resource cleanup.
 
 Python 3.11 or newer is required.
 
-The current stable release is [2.4.1](https://github.com/steventimes/fpstreams/releases/tag/v2.4.1).
-This maintenance release reorganizes planner and execution internals with no public API changes.
+[Version 2.4.1](https://github.com/steventimes/fpstreams/releases/tag/v2.4.1)
+reorganizes planner and execution internals with no public API changes.
 Version 2.4.0 added stateful pipeline operations, composed aggregation, shared execution
 limits, file recovery, and versioned execution metadata. See the
 [changelog](https://github.com/steventimes/fpstreams/blob/master/CHANGELOG.md) for its scope and the
@@ -76,9 +93,21 @@ for batch and executor examples. The
 [roadmap](https://steventimes.github.io/fpstreams/roadmap/#next-development-steps)
 lists the next optimization candidates and their acceptance criteria.
 
+Version 2.5.0 preserves custom-key hash errors in per-key reductions, Pair
+collection, and in-memory Python joins and grouping on Python 3.14 and 3.15.
+
+The [2.5.0 changes](CHANGELOG.md#250) include a static averaging type correction
+with an explicit migration path. This version adds
+[typed asynchronous folds](fpstreams/docs/reference/async_flow.md#explicit-asynchronous-accumulator-contract-250),
+[explicit averaging operations](fpstreams/docs/reference/collecting.md#explicit-averaging-operations-250),
+and an opt-in [strict lookup policy for null filtering](fpstreams/docs/reference/rows.md#null-filtering-and-lookup-failures-250).
+These APIs are not in 2.4.1. `Flow.reduce` still returns `Any` to type checkers,
+including with an annotated callback. See the [reduce guide](fpstreams/docs/reference/flow.md#reduce-types)
+for migration examples and [contributor checks](CONTRIBUTING.md#run-the-checks) for validation.
+
 ## Install
 
-Install the latest stable release:
+Install fpstreams from PyPI:
 
 ~~~bash
 python -m pip install fpstreams
@@ -97,48 +126,47 @@ python -m pip install "fpstreams[data]"    # NumPy, pandas, and PyArrow
 python -m pip install "fpstreams[polars]"  # Polars and PyArrow
 ~~~
 
-## Editor support
+## Quick start
 
-fpstreams includes inline type annotations, docstrings, and the `py.typed` marker.
-Select the Python interpreter where fpstreams is installed in your editor to get
-method completions, parameter hints, and hover documentation.
+Pass an iterable to `flow()` and consume the result:
 
-Version 2.2.1 fixes `rows` factory completion and keeps core
-iterable element types when optional data adapters are absent. For example,
-`flow([1, 2, 3])` is inferred as `Flow[int]`.
+~~~python
+from fpstreams import flow
 
-## Quick start
+result = flow([1, 2, 3]).filter(lambda value: value > 1).map(lambda value: value * 10).to_list()
+assert result == [20, 30]
+~~~
+
+Use [async pipelines](#asynchronous-pipelines) for asynchronous callbacks and
+[record pipelines](#record-pipelines) for grouping. The
+[engine guide](#execution-engines) helps diagnose execution routes;
+[resource limits](#resource-and-file-safety-controls) apply when processing larger inputs.
 
-This example filters paid orders, groups them by region, and reports both the
-number of orders and their revenue:
+### Close an owned iterator
+
+This pipeline takes three matching values and closes its generator before returning.
+The generator prints when its `finally` block runs, so cleanup is visible:
 
 ~~~python
-from fpstreams import agg, col, flow
+from fpstreams import flow
 
-orders = [
-    {"region": "eu", "status": "paid", "amount": 24},
-    {"region": "us", "status": "paid", "amount": 20},
-    {"region": "eu", "status": "cancelled", "amount": 99},
-    {"region": "eu", "status": "paid", "amount": 24},
-]
 
-result = (
-    flow(orders)
-    .filter(col("status") == "paid")
-    .group_by("region")
-    .aggregate(
-        orders=agg.count(),
-        revenue=agg.sum("amount"),
-    )
-    .sort_by("region")
-    .to_list()
-)
+def numbers():
+    try:
+        yield from range(10)
+    finally:
+        print("source closed")
 
+
+result = flow(numbers()).filter(lambda value: value % 2 == 0).take(3).to_list()
 print(result)
-# [{'region': 'eu', 'orders': 2, 'revenue': 48},
-#  {'region': 'us', 'orders': 1, 'revenue': 20}]
+# source closed
+# [0, 2, 4]
 ~~~
 
+See [record pipelines](#record-pipelines) for grouped aggregation, or
+[asynchronous pipelines](#asynchronous-pipelines) for concurrent calls.
+
 ## When to use fpstreams
 
 For a short, local transformation, a comprehension is often enough. fpstreams
@@ -174,10 +202,11 @@ standard Arrow/dataframe protocol routing, retained NumPy execution, and new
 async queue, prefetch, window, and numeric terminal APIs. See the
 [changelog](https://github.com/steventimes/fpstreams/blob/master/CHANGELOG.md) for the release summary.
 
-Release testing covers standard CPython 3.11 through 3.14. Free-threaded
-CPython 3.14t is exercised by an experimental, non-blocking job that builds the
-native extension; it is not currently a release-wheel target, and unsupported
-fast paths fall back conservatively.
+The CI matrix targets standard CPython 3.11 through 3.15.
+Free-threaded CPython 3.14t and 3.15t are included in an
+experimental, non-blocking CI matrix that builds the native extension and checks
+core concurrency contracts. These builds are not release-wheel targets;
+optional adapter compatibility is outside this matrix.
 
 ### Value pipelines
 
@@ -275,7 +304,9 @@ record column. Explicit Flow factories cover Arrow, equal-length named columns,
 NumPy arrays, dataframe, Polars, typed CSV, and Parquet inputs. The `rows`
 namespace continues to provide compatibility CSV, JSONL, SQLite, DB-API, and
 record-oriented output methods. CSV and JSONL
-inputs accept paths, caller-owned open handles, or replayable opener functions:
+inputs accept paths, caller-owned open handles, or replayable opener functions.
+The following example needs `fpstreams[arrow]` and an `accounts.parquet` file
+with `id`, `status`, and `balance` columns:
 
 ~~~python
 from fpstreams import col, flow
@@ -324,6 +355,8 @@ asyncio.run(main())
 
 Async iterators consumed by a pipeline are closed, and tasks created by the
 pipeline are cancelled, when it finishes, errors, times out, or short-circuits.
+Mappers must cooperate with cancellation so cleanup can finish. Offload blocking
+work explicitly rather than running it directly inside an async mapper.
 
 ### Key/value pipelines
 
@@ -366,8 +399,13 @@ assert plan["data_movement"] == {
 You can request an engine explicitly when testing parity or diagnosing a plan:
 
 ~~~python
+from fpstreams import flow, item
+
+pipeline = flow([1, 2, 3]).map(item * 2)
 python_result = pipeline.with_engine("python").to_list()
 native_result = pipeline.with_engine("native").to_list()
+
+assert python_result == native_result == [2, 4, 6]
 ~~~
 
 Use `run_with_report()` to get a terminal's value, recorded route, and query-owned
@@ -417,11 +455,23 @@ finish. The defaults are 100,000 rows and 64 MiB per partition, 100,000 matches
 per key, 1,000,000 output rows, and three repartition levels.
 
 ~~~python
-from fpstreams import SpillLimits, rows
+from fpstreams import SpillLimits, agg, rows
+
+accounts = [{"id": 1, "account_id": "a"}, {"id": 2, "account_id": "a"}]
+balances = [{"id": 1, "balance": 10}, {"id": 2, "balance": 20}]
 
 limits = SpillLimits(max_output_rows=250_000, max_matches_per_key=10_000)
-result = rows(left).join(right, on="id", partitions=32, limits=limits)
-grouped = rows(records).group_by("account_id").spill(partitions=32, limits=limits)
+joined = rows(accounts).join(balances, on="id", partitions=32, limits=limits).to_list()
+grouped = (
+    rows(accounts)
+    .group_by("account_id")
+    .spill(partitions=32, limits=limits)
+    .aggregate(count=agg.count())
+    .to_list()
+)
+
+assert sorted((row["id"], row["balance"]) for row in joined) == [(1, 10), (2, 20)]
+assert grouped == [{"account_id": "a", "count": 2}]
 ~~~
 
 Exceeding a configured partition, match, state, record, or output limit raises
@@ -446,8 +496,31 @@ only for trusted local input when an unlimited record is intentional.
   once during construction and treated as one-shot; a PyArrow
   `RecordBatchReader` is also one-shot.
 - `flow.defer(factory)` opens a fresh source for every execution.
-- Terminal operations close owned iterators, database cursors, temporary files,
-  and asynchronous tasks, including on errors and early termination.
+- Terminal operations release owned iterators, database cursors, and temporary
+  files, including on errors and early termination. Async execution also cancels
+  and awaits tasks it creates. File adapters distinguish owned resources from
+  caller-owned handles; see the [I/O reference](https://steventimes.github.io/fpstreams/reference/io/).
+
+## Editor support
+
+fpstreams includes inline type annotations, docstrings, and the `py.typed` marker.
+Select the Python interpreter where fpstreams is installed in your editor to get
+method completions, parameter hints, and hover documentation.
+
+Version 2.2.1 fixes `rows` factory completion and keeps core
+iterable element types when optional data adapters are absent. For example,
+`flow([1, 2, 3])` is inferred as `Flow[int]`.
+
+## Coding-agent guidance
+
+The [Flow](fpstreams/docs/reference/flow.md#reduce-types),
+[async Flow](fpstreams/docs/reference/async_flow.md#explicit-asynchronous-accumulator-contract-250),
+and [Collector](fpstreams/docs/reference/collecting.md#explicit-averaging-operations-250)
+references describe entry points, typed reductions, and migration contracts.
+An independently supplied fpstreams usage skill must match the installed library
+version and its API documentation. The skill is distributed separately from
+the PyPI wheel and sdist. Neither a package install nor its presence in a
+checkout registers it with an agent.
 
 ## v1 compatibility
 
@@ -471,25 +544,20 @@ uv sync --extra arrow --extra data --extra polars \
 uv run maturin develop --release
 uv run pytest -W error --cov=src/fpstreams --cov-branch --cov-report=term-missing
 uv run coverage report
-uv run ruff check src tests scripts benchmarks benchmark.py
-uv run ruff format --check src tests scripts benchmarks benchmark.py
+uv run ruff check src tests scripts
+uv run ruff format --check src tests scripts
 uv run mypy src/fpstreams
 cargo test --manifest-path rust/Cargo.toml
 uv run python scripts/build_browser_wheel.py
 uv run mkdocs build --strict -f fpstreams/mkdocs.yml
 ~~~
 
-Run `./run_benchmark.sh` for the configurable benchmark matrix. Its settings are
-kept at the top of the script, including input size, repeats, presets, case
-filters, and optional JSON output. Competitive mode checks equivalent tasks
-against Python, NumPy, and pandas and prints the percentage difference.
+Performance measurements are maintained locally. Benchmark tools and raw reports
+are not part of the public source distribution or GitHub Actions.
 
 The source tree is organized by domain under `src/fpstreams/`: `streams`,
 `planning`, `execution`, `collecting`, `tabular`, `expressions`, and `primitives`.
 Small top-level modules are compatibility facades, not duplicate implementations.
-The [Chinese code-reading guide](https://github.com/steventimes/fpstreams/blob/master/CODE_READING_GUIDE.zh-CN.md)
-walks through the main sync, relational, spill, native, and async execution paths
-in those domains.
 
 Contributions are welcome. The
 [contributing guide](https://github.com/steventimes/fpstreams/blob/master/CONTRIBUTING.md)