56 lines
2.6 KiB
Markdown
56 lines
2.6 KiB
Markdown
# Nested Authoring State Projection 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:** Let `wf_authoring` project nested authored state schemas into the flat exact-path state-field index that `wf_core` now supports.
|
|
|
|
**Architecture:** Keep authored JSON Schema nested for users and LLM clients. Add a focused flattening helper for state-field projection only, emitting both parent object paths and descendant paths. Resolve nested `BaseModel` metadata by authored path where available, while leaving non-`BaseModel` authored types schema-capable with default merge metadata.
|
|
|
|
**Tech Stack:** Python, Pydantic, pytest, existing `wf_authoring` schema adapter.
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
- Modify `src/wf_authoring/schemas.py`
|
|
- flatten nested schema properties into exact-path `StateField`s
|
|
- gather nested `BaseModel` metadata by authored path
|
|
- Modify `tests/authoring/helpers.py`
|
|
- add nested state models used by tests
|
|
- Modify `tests/authoring/test_schemas.py`
|
|
- pin nested projection behavior and nested metadata
|
|
- Update `docs/core_state_mapping_and_merge.md`
|
|
- note that authoring now projects nested authored models into the flat core index
|
|
|
|
## Tasks
|
|
|
|
### Task 1: Pin Nested Projection
|
|
|
|
- [ ] Add tests proving:
|
|
- nested authored state keeps parent and child declarations
|
|
- nested child metadata such as `append` lands on the exact child path
|
|
- parent object declaration remains independent from child declarations
|
|
- [ ] Run the focused authoring tests and confirm they fail under current top-level-only projection.
|
|
|
|
### Task 2: Implement Projection Helpers
|
|
|
|
- [ ] Add a schema-walking helper that yields `(path, property_schema)` for parent and descendant properties.
|
|
- [ ] Add nested `BaseModel` metadata traversal keyed by dotted path.
|
|
- [ ] Update `state_schema_from()` to build `StateField`s from the flattened path stream.
|
|
- [ ] Keep JSON Schema generation unchanged; flatten only the core `StateSchema.fields` index.
|
|
- [ ] Run the focused authoring tests and confirm they pass.
|
|
|
|
### Task 3: Document and Verify
|
|
|
|
- [ ] Update the core state mapping doc with the authoring projection rule.
|
|
- [ ] Run `uv run --with pytest pytest tests/authoring -q`
|
|
- [ ] Run `uv run --with pytest pytest -q`
|
|
- [ ] Run `uv run basedpyright --level error`
|
|
|
|
## Non-Goals
|
|
|
|
- custom metadata support for every Pydantic-supported type form
|
|
- changing `SchemaRef` shape
|
|
- reducer registries
|
|
- automatic deep merge behavior
|