docs: record workflow contract manifest
This commit is contained in:
@@ -1,92 +0,0 @@
|
||||
# Task 2 Report
|
||||
|
||||
## Scope
|
||||
|
||||
Implemented fail-closed contract and `$ref` validation for
|
||||
`wf_contract_manifest.manifest_from_openrpc()` without changing the Task 1
|
||||
public interface. JSON Schema keywords remain opaque; validation is limited to
|
||||
the OpenRPC envelope, normalized operation/component values, and their `$ref`
|
||||
graph.
|
||||
|
||||
## TDD Evidence
|
||||
|
||||
- Added tests for unsupported OpenRPC versions, malformed envelopes, duplicate
|
||||
methods, malformed dotted names, invalid parameters, invalid result shapes,
|
||||
and non-component success results.
|
||||
- Added tests for external, unsupported-local, unsupported-component,
|
||||
dangling, and escaped component references.
|
||||
- Added a passing nested schema reference case while retaining the existing
|
||||
error-component reference assertion.
|
||||
- Ran the new tests before implementation: 10 cases failed for the intended
|
||||
missing validation behaviors; existing Task 1 coverage remained green.
|
||||
|
||||
## Implementation
|
||||
|
||||
- Pins `$.openrpc` to `1.2.6`.
|
||||
- Rejects duplicate method names at the later method path.
|
||||
- Uses the strict `malformed dotted method name` diagnostic.
|
||||
- Requires success results to be exactly a local `components/schemas` `$ref`
|
||||
object.
|
||||
- Walks every operation parameter/result/error and every normalized component,
|
||||
recursively inspecting only `$ref` values.
|
||||
- Rejects external refs, unsupported namespaces, escaped component keys, and
|
||||
dangling refs; forward refs are accepted after the complete manifest is
|
||||
assembled.
|
||||
|
||||
## Verification
|
||||
|
||||
```text
|
||||
39 passed in 0.10s
|
||||
ruff check: All checks passed!
|
||||
basedpyright --level error: 0 errors, 0 warnings, 0 notes
|
||||
git diff --check: passed (only Git line-ending warnings)
|
||||
```
|
||||
|
||||
## Commit
|
||||
|
||||
The Task 2 commit is recorded by the final response after the final verification
|
||||
and scope audit.
|
||||
|
||||
## Concerns
|
||||
|
||||
None identified.
|
||||
|
||||
## Task 2 Review Fixes
|
||||
|
||||
### Findings Addressed
|
||||
|
||||
1. Reference validation now runs against operations in original source order,
|
||||
and reports `$.methods[index]...` paths before deterministic lexical sorting.
|
||||
A regression test uses the source order `workflow.zeta.run`, then
|
||||
`workflow.alpha.inspect`, and asserts the exact later ref path.
|
||||
2. Success result validation now checks raw mapping keys before `_schema()`
|
||||
removes `title`, so a valid `$ref` plus an extra `title` is rejected.
|
||||
3. The malformed-contract mutation table now uses the typed
|
||||
`DocumentMutation` Protocol instead of an `Any` mutation annotation.
|
||||
|
||||
### TDD Evidence
|
||||
|
||||
- Review regression tests were run before implementation: 2 failed as
|
||||
intended, one for the title-stripping acceptance and one for the sorted
|
||||
operation path.
|
||||
- After implementation, all 41 focused normalization tests passed.
|
||||
|
||||
### Fix Verification
|
||||
|
||||
```text
|
||||
.venv\Scripts\python.exe -m pytest tests\wf_contract_manifest\test_normalize.py -n 0 -q
|
||||
41 passed in 0.13s
|
||||
|
||||
.venv\Scripts\ruff.exe check src\wf_contract_manifest tests\wf_contract_manifest
|
||||
All checks passed!
|
||||
|
||||
.venv\Scripts\basedpyright.exe --level error src\wf_contract_manifest tests\wf_contract_manifest
|
||||
0 errors, 0 warnings, 0 notes
|
||||
|
||||
git diff --check
|
||||
passed (only Git line-ending warnings)
|
||||
```
|
||||
|
||||
### Fix Concerns
|
||||
|
||||
None identified.
|
||||
@@ -1,43 +0,0 @@
|
||||
# Task 4 Report
|
||||
|
||||
## Scope
|
||||
|
||||
Implemented the workflow contract manifest module CLI and checked in the manifest artifact required by Task 4.
|
||||
|
||||
Created:
|
||||
|
||||
- `src/wf_contract_manifest/__main__.py`
|
||||
- `tests/wf_contract_manifest/test_cli.py`
|
||||
- `contracts/workflow-api.manifest.json`, generated by `python -m wf_contract_manifest write`
|
||||
|
||||
The CLI supports only the module commands `write` and `check`; no project script was added.
|
||||
|
||||
## TDD Evidence
|
||||
|
||||
The CLI tests were written before the production module. The required RED run failed during collection with:
|
||||
|
||||
`ModuleNotFoundError: No module named 'wf_contract_manifest.__main__'`
|
||||
|
||||
After implementing the module CLI, the CLI test file passed with `3 passed`.
|
||||
|
||||
## Verification
|
||||
|
||||
- CLI tests: `3 passed`
|
||||
- All manifest tests: `51 passed`
|
||||
- Ruff: `All checks passed!`
|
||||
- basedpyright: `0 errors, 0 warnings, 0 notes`
|
||||
- `git diff --check`: passed
|
||||
- Module generation: wrote `contracts/workflow-api.manifest.json`
|
||||
- Module drift check: checked the generated manifest successfully
|
||||
- Independent bounded JSON assertions:
|
||||
- operations: `70`
|
||||
- component schemas: `126`
|
||||
- component errors: `1`
|
||||
- first method: `workflow.admin.auth.delete`
|
||||
- last method: `workflow.sources.list`
|
||||
|
||||
## Review And Concerns
|
||||
|
||||
The CLI follows the exact Task 4 interface and catches the manifest, drift, and value errors specified by the brief. The generated JSON was not hand-edited. No Task 4 concerns remain.
|
||||
|
||||
The worktree contained a pre-existing staged deletion of `.superpowers/sdd/task-2-report.md`; it was preserved and excluded from the Task 4 staging set.
|
||||
@@ -59,23 +59,21 @@
|
||||
|
||||
## TypeScript JSON-RPC coverage
|
||||
|
||||
- [ ] `@lda/workflow-rpc` models only the 12 operations needed by the current
|
||||
console explorer. It omits typed access to capabilities, source
|
||||
inspect/diagnose, artifact save/delete/create, deployment save/delete, every
|
||||
draft operation, and source-registry/admin operations already exposed by the
|
||||
Python JSON-RPC server.
|
||||
- [ ] Python JSON-RPC models and the Effect RPC schemas are maintained by hand
|
||||
with no parity check or generated contract. Add an operation-inventory test
|
||||
or a code-generation seam so server additions cannot silently remain absent
|
||||
from TypeScript.
|
||||
- A 2026-07-30 spike confirmed that `fastapi-jsonrpc` already exports a
|
||||
complete OpenRPC document for all 70 registered methods. Request payloads
|
||||
retain useful Pydantic schemas, so OpenRPC is a viable transport input.
|
||||
- All 70 JSON-RPC methods now expose named transport-neutral success-result
|
||||
schemas, including connections, events, and secret-safe auth admin results.
|
||||
No success result collapses to a generic object. The next contract-parity
|
||||
step can consume OpenRPC through a small transport-neutral manifest rather
|
||||
than adding more Python result DTOs.
|
||||
- [ ] TypeScript JSON-RPC parity remains incomplete: `@lda/workflow-rpc` models
|
||||
only the 12 operations needed by the current console explorer. It omits typed
|
||||
access to capabilities, source inspect/diagnose, artifact save/delete/create,
|
||||
deployment save/delete, every draft operation, and source-registry/admin
|
||||
operations already exposed by the Python JSON-RPC server.
|
||||
- All 70 Python methods now have named OpenRPC success schemas, including
|
||||
connections, events, and secret-safe auth admin results. No success result
|
||||
collapses to a generic object.
|
||||
- `contracts/workflow-api.manifest.json` is the checked transport-neutral
|
||||
inventory, and `python -m wf_contract_manifest check` is the drift gate.
|
||||
- The manifest does not authorize callers: browser authorization, operation
|
||||
metadata, and the 12 current Effect RPC implementations remain authored
|
||||
boundaries.
|
||||
- The next slice is generated TypeScript operation names/raw types plus a
|
||||
fail-closed representative JSON Schema-to-Effect translator.
|
||||
- The stock `@open-rpc/generator` TypeScript client is not suitable here. It
|
||||
exhausted a 4 GB Node heap on the full contract and emitted invalid dotted
|
||||
class members plus `any` results for a minimal `workflow.health` contract.
|
||||
|
||||
@@ -737,6 +737,13 @@ stable.
|
||||
|
||||
## Recently Completed Platform Milestones
|
||||
|
||||
- Completed: the composed Python OpenRPC contract now has a checked,
|
||||
transport-neutral manifest with a deterministic drift gate. Design:
|
||||
[`workflow contract manifest design`](superpowers/specs/2026-08-01-workflow-contract-manifest-design.md).
|
||||
Artifact: [`workflow-api.manifest.json`](../contracts/workflow-api.manifest.json).
|
||||
Generated TypeScript operation names/raw types and a fail-closed
|
||||
representative JSON Schema-to-Effect translator are the next contract-parity
|
||||
slice; TypeScript parity is not complete.
|
||||
- `WorkflowApiSurface` is the protocol-neutral workflow operation contract.
|
||||
- `wf_transport_rpc_http` exposes local/static and MCP-backed `WorkflowServer`
|
||||
over JSON-RPC HTTP.
|
||||
|
||||
@@ -28,6 +28,7 @@ For verified Python 3.14 dependency constraints and their removal criteria, see
|
||||
| `wf_sources_mcp` | MCP-as-upstream-source implementation: ids, registry DTOs, auth/catalog stores, discovery, SDK client/facade, runtime pool, wrappers. | `wf_server`, broker glue, MCP source tests. |
|
||||
| `wf_mcp` | MCP frontend/compatibility package: legacy `wf-mcp` entrypoints, broker glue, proxy/admin tools, and shims while extraction continues. | Compatibility callers and MCP transport work. |
|
||||
| `wf_cli` | Command-line frontend over local or remote workflow APIs. | Humans, scripts, agent skills. |
|
||||
| `wf_contract_manifest` | Tooling that normalizes the composed workflow OpenRPC document into the checked transport-neutral contract manifest and detects drift. | Contract generation, tests, and future TypeScript generators. |
|
||||
| `@lda/presentation-sync` | Shared, bounded wire contract for ephemeral LAN presentation rooms. | Browser `@lda/console` and Hono `@lda/web-server`. |
|
||||
|
||||
The TypeScript presentation synchronization boundary is deliberately narrow.
|
||||
@@ -65,6 +66,8 @@ can continue to reach a loopback-only workflow RPC server.
|
||||
- `wf-mcp`: legacy/special-purpose MCP script from `pyproject.toml`.
|
||||
- `wf-rpc-server`: preferred durable workflow server script for CLI/API clients,
|
||||
implemented by `wf_server.cli`.
|
||||
- `python -m wf_contract_manifest write|check`: regenerate or verify
|
||||
`contracts/workflow-api.manifest.json` from the real composed workflow server.
|
||||
- `wf_mcp.broker.WfMcpService.get_catalog()`: backend MCP catalog snapshots.
|
||||
- `wf_mcp.broker.WfMcpService.get_planner_catalog()`: backend snapshots plus
|
||||
broker-local workflow sources such as `wf.std` and `wf.mcp`.
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
from wf_contract_manifest import (
|
||||
DEFAULT_MANIFEST_PATH,
|
||||
check_manifest,
|
||||
generate_manifest,
|
||||
)
|
||||
|
||||
|
||||
def test_committed_manifest_matches_the_python_workflow_contract() -> None:
|
||||
check_manifest(generate_manifest(), DEFAULT_MANIFEST_PATH)
|
||||
Reference in New Issue
Block a user