wf reorg 5

docs/project_map.md

@@ -0,0 +1,62 @@
+# Project Map
+
+This repository has three main packages plus examples and tests.
+
+## Packages
+
+| Package | Purpose | Usual callers |
+| --- | --- | --- |
+| `wf_core` | Deterministic workflow kernel: models, validation, runtime, run state, traces, interrupts, foreach, and path/state operations. | Runtime users, `wf_authoring`, workflow adapters. |
+| `wf_authoring` | Ergonomic workflow construction: `@node`, `NodeSpec`, builder DSL, conditions, path helpers, reusable ops, subgraph nodes. | Humans, tests, future LLM workflow builders. |
+| `wf_mcp` | MCP integration: SDK adapters, broker/proxy runtime, storage, config control, transparent proxy, and workflow wrappers for discovered tools. | MCP-facing CLI/server code and future UI/control surfaces. |
+
+## Important Entry Points
+
+- `wf_core`: public kernel facade for common runtime/model imports.
+- `wf_core.runtime`: `execute_workflow`, `resume_workflow`, `step_workflow`,
+  and async variants.
+- `wf_core.models`: concrete Pydantic workflow model package.
+- `wf_core.validation`: structural workflow validation.
+- `wf_authoring`: public authoring facade.
+- `wf_authoring.WorkflowBuilder`: graph construction.
+- `wf_authoring.node`: typed Python function to `NodeSpec`.
+- `wf_mcp`: public MCP facade.
+- `wf-mcp`: CLI script from `pyproject.toml`.
+
+## Examples
+
+`examples/demo_workflow.py` contains the declared demo workflow and demo node
+registry used by `main.py` and workflow tests. It is intentionally outside
+`wf_core` so the kernel package does not carry fixture/demo code.
+
+## Tests
+
+- `tests/authoring`: builder, node decorator, ops, async runtime, subgraph, and
+  demo workflow comparisons.
+- `tests/wf_mcp`: MCP SDK adapter, broker, transparent proxy, storage, CLI, and
+  naming behavior.
+- `tests/rewrite`: local rewrite/port experiments that should keep exercising
+  real user ergonomics.
+- `tests/fixtures`: test-only helper servers and fixtures.
+
+## Verification Commands
+
+```powershell
+uv run --with pytest pytest -q
+uv run ruff check src tests main.py examples
+uv run basedpyright src\wf_core tests\authoring tests\rewrite examples main.py --level error
+```
+
+Use `uv run --env-file .env --with pytest pytest -q` when live MCP-backed tests
+need local environment configuration.
+
+## Where To Add Things
+
+- Add new executable workflow semantics in `wf_core.runtime` / `wf_core.runtime.ops`.
+- Add new graph/model syntax in `wf_core.models`, then validate it in
+  `wf_core.validation`.
+- Add author convenience helpers in `wf_authoring`, not `wf_core`.
+- Add MCP transport/proxy/config behavior in `wf_mcp` concern packages.
+- Add runnable examples in `examples`.
+- Add test-only servers or helpers in `tests/fixtures`.
+

docs/schema_validation.md

@@ -0,0 +1,64 @@
+# Schema Validation Boundary
+
+`wf_core` uses `SchemaRef` to carry JSON-schema-like shapes on workflow input,
+node input, node output, and workflow output. The current runtime does not
+implement full JSON Schema validation.
+
+## Current Behavior
+
+`wf_core.runtime.ops.schemas.validate_payload_against_schema` currently checks:
+
+- if `schema.type == "object"`, the payload must be a `dict`
+- required top-level keys must be present
+
+It does not currently check:
+
+- property value types, such as `string`, `boolean`, `array`, or nested objects
+- array item schemas
+- `additionalProperties`
+- formats, enums, minimums, maximums, unions, discriminators, or nested required
+  fields
+- whether a schema is valid JSON Schema
+
+This means schema fields are mostly contracts for authoring, planning,
+documentation, and mapping validation today. They are not yet strong runtime
+guards.
+
+## Why This Matters
+
+The engine currently looks stricter than it is. A node can return a required
+field with the wrong type and pass runtime validation as long as the field is
+present. That is acceptable during early design work, but it is a real product
+boundary before workflows are generated by an LLM or backed by arbitrary MCP
+tools.
+
+## Intended Seam
+
+The schema adapter should live behind:
+
+```text
+wf_core.runtime.ops.schemas.validate_payload_against_schema
+```
+
+Callers should not choose or invoke the validation backend directly. The runtime
+should keep one small validation interface and hide whether the implementation
+uses Pydantic, `jsonschema`, a generated model cache, or a stricter custom
+adapter.
+
+## Future Requirements
+
+- Validate workflow input, node input, node output, and final workflow output
+  with the same semantics.
+- Return errors that name the failing boundary and path.
+- Avoid silently accepting unsupported schema features once schemas are
+  user/LLM-authored.
+- Keep schema validation separate from graph structure validation.
+- Keep `wf_authoring` free to generate schemas from Pydantic models without
+  making the core runtime depend on authoring internals.
+
+## Non-Goals For Now
+
+- Do not add ad hoc type checks throughout runtime state operations.
+- Do not let each node wrapper invent separate validation behavior.
+- Do not conflate graph validation with payload validation.
+

docs/wf_core_architecture.md

@@ -62,6 +62,13 @@ raising at the first failure.
 - `wf_core.__init__` should stay a curated public facade, not a dump of runtime
   internals.
 
+## Schema Validation
+
+Payload schema validation is intentionally isolated behind
+`wf_core.runtime.ops.schemas.validate_payload_against_schema`. That function is
+not a full JSON Schema engine today; see `docs/schema_validation.md` for the
+current limits and intended adapter seam.
+
 ## What This Cleanup Does Not Solve Yet
 
 - Foreach is still serial-only. Parallel foreach needs an explicit scheduling
@@ -72,3 +79,5 @@ raising at the first failure.
 - Runtime errors are still ordinary exceptions plus failed run status. A richer
   error payload can be added later, but should be designed as part of trace/run
   state rather than scattered exceptions.
+- Payload schema validation is still shallow. The runtime checks object payloads
+  and required top-level keys, not full JSON Schema semantics.