lda-wf/docs/historical/superpowers/plans/2026-05-17-nested-authoring-state-projection.md

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 StateFields
  • 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 StateFields 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