79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
# Reducer Capabilities Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Replace `merge_strategy` with named pure reducer references across core and authoring, using `wf.std.replace` as the default reducer.
|
|
|
|
**Architecture:** Introduce a small reducer registry in `wf_core`, register the current three built-ins as reducers, and have state writes resolve every declared reducer name through that registry. Keep undeclared state paths using default replace semantics. Migrate `wf_authoring.state_field()` and all state metadata/tests/docs to reducer names in the same pass so there is one merge concept in the codebase.
|
|
|
|
**Tech Stack:** Python, Pydantic, pytest, existing `wf_core` runtime and `wf_authoring` schema projection.
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
- Modify `src/wf_core/models/schemas.py`
|
|
- replace `merge_strategy` with `reducer`
|
|
- Replace/refactor `src/wf_core/runtime/ops/merges.py`
|
|
- reducer callable type
|
|
- built-in reducer functions
|
|
- default reducer registry
|
|
- reducer application helper
|
|
- Modify `src/wf_core/runtime/ops/state.py`
|
|
- resolve reducer names from state fields
|
|
- use default replace reducer for undeclared paths
|
|
- Modify `src/wf_authoring/schemas.py`
|
|
- expose `state_field(reducer=...)`
|
|
- project reducer metadata through flattened state paths
|
|
- Modify tests under `tests/core/`, `tests/authoring/`, and `tests/rewrite/`
|
|
- migrate old metadata
|
|
- add unknown reducer coverage
|
|
- Update docs mentioning `merge_strategy`
|
|
|
|
## Tasks
|
|
|
|
### Task 1: Pin Reducer Semantics
|
|
|
|
- [ ] Add tests proving:
|
|
- `StateField(type="string")` defaults to `wf.std.replace`
|
|
- `wf.std.append` preserves append behavior
|
|
- `wf.std.merge_object` preserves shallow object merge behavior
|
|
- unknown reducer names fail clearly
|
|
- exact nested state paths still use their own reducer
|
|
- [ ] Run focused core tests and confirm failure before implementation.
|
|
|
|
### Task 2: Replace Core Merge Strategy With Reducers
|
|
|
|
- [ ] Replace `merge_strategy` on `StateField` with `reducer`.
|
|
- [ ] Add reducer functions for `wf.std.replace`, `wf.std.append`, and `wf.std.merge_object`.
|
|
- [ ] Add a registry lookup path that raises for unknown reducer names.
|
|
- [ ] Update `write_state_value()` to resolve declared reducers and use `wf.std.replace` for undeclared paths.
|
|
- [ ] Run focused core tests and confirm reducer behavior is green.
|
|
|
|
### Task 3: Migrate Authoring
|
|
|
|
- [ ] Change `StateFieldMetadata` and `state_field()` to use `reducer`.
|
|
- [ ] Preserve nested metadata projection under reducer names.
|
|
- [ ] Update authoring/rewrite fixtures from `merge_strategy=` to `reducer=`.
|
|
- [ ] Run focused authoring tests and confirm they pass.
|
|
|
|
### Task 4: Update Docs
|
|
|
|
- [ ] Replace docs that describe `merge_strategy` with reducer terminology.
|
|
- [ ] Update examples to show reducer names, including the default replace reducer.
|
|
- [ ] Keep the design point that reducers are pure and source-owned.
|
|
|
|
### Task 5: Verify
|
|
|
|
- [ ] Run `uv run --with pytest pytest tests/core tests/authoring tests/rewrite -q`
|
|
- [ ] Run `uv run --with pytest pytest -q`
|
|
- [ ] Run `uv run basedpyright --level error`
|
|
|
|
## Non-Goals
|
|
|
|
- custom user-authored reducer registration through MCP/platform sources
|
|
- reducer parameters/configuration
|
|
- async reducers
|
|
- parallel foreach
|
|
- compatibility shims for `merge_strategy`
|