WEPPcloud
UserSummary Docs

← Back to usersum index

RQ Controller State Orchestration Reads

Status: Complete (closed 2026-04-10 18:08 UTC) Timezone: UTC (all dates/times in this package documentation use UTC unless explicitly stated otherwise).

Overview

This package implemented the run-scoped orchestration read surfaces that let agents drive WEPPcloud workflows deterministically without UI scraping. It delivered /pipeline and /readiness for existing runid/config contexts with canonical step identity, state transitions, invalidation lineage, and next-action semantics.

Objectives

  • Implement run-scoped orchestration read endpoints in rq-engine:
    • GET /api/runs/{runid}/{config}/pipeline
    • GET /api/runs/{runid}/{config}/readiness
  • Enforce contract-aligned step/state semantics (step_id, operation_id, status/state machine, can_run_now, invalidation lineage).
  • Ensure payloads are deterministic and config/mod-aware for baseline and disturbed runs.
  • Add/extend OpenAPI and route-level tests plus frozen artifact/checklist guards for the new endpoints.

Scope

This package delivered orchestration-read route implementation, contract-aligned payload builders, and required tests/docs/checklist updates.

Included

  • New rq-engine orchestration-read routes for pipeline/readiness.
  • Router-registration and OpenAPI metadata updates.
  • Pipeline/readiness payload assembly from run state with contract-required fields.
  • Contract and route tests for auth, payload shape, state transitions, deterministic next-action selection, and review-identified regressions.
  • Frozen artifact updates:
    • docs/work-packages/20260208_rq_engine_agent_usability/artifacts/endpoint_inventory_freeze_20260208.md
    • docs/work-packages/20260208_rq_engine_agent_usability/artifacts/route_contract_checklist_20260208.md

Explicitly Out of Scope

  • Endpoint schema/default surfaces for core operations (20260410_rq_controller_state_schema_defaults).
  • Geospatial/upload metadata contracts (20260410_rq_controller_state_geospatial_uploads).
  • Error catalog/progress/outputs surfaces (20260410_rq_controller_state_errors_progress_outputs).
  • Auth-concurrency/idempotency rollout enforcement (20260410_rq_controller_state_auth_concurrency).

Stakeholders

  • Primary: rq-engine maintainers and agent-interface implementers.
  • Reviewers: API contract/schema maintainers.
  • Security Reviewer: independent security subagent review required by package gate.
  • Informed: downstream owners for roadmap packages 4-8.

Success Criteria

  • /pipeline and /readiness are implemented and exposed under rq-engine /api/runs/{runid}/{config}.
  • Step identity and status fields align with the contract core vocabulary and state-machine semantics.
  • next_actionable_steps is deterministic for baseline and disturbed configs given equivalent state.
  • Frozen endpoint inventory/checklist artifacts include the orchestration read routes.
  • Required validation gates pass (code, QA, security, docs) with no unresolved medium/high findings.

Dependencies

Prerequisites

  • docs/work-packages/20260410_rq_controller_state_foundation/ (complete)
  • docs/work-packages/20260410_rq_controller_state_setup_discovery/ (complete)
  • Canonical route artifacts:
    • docs/work-packages/20260208_rq_engine_agent_usability/artifacts/endpoint_inventory_freeze_20260208.md
    • docs/work-packages/20260208_rq_engine_agent_usability/artifacts/route_contract_checklist_20260208.md

Blocks

  • 20260410_rq_controller_state_schema_defaults
  • 20260410_rq_controller_state_geospatial_uploads
  • 20260410_rq_controller_state_errors_progress_outputs
  • 20260410_rq_controller_state_auth_concurrency
  • 20260410_rq_controller_state_contract_cutover

Timeline Estimate

  • Expected duration: 1-2 focused sessions
  • Complexity: High
  • Risk level: High

Security Impact and Review Gate

  • Security impact triage: high
  • Dedicated security review required: yes
  • Triage rationale: Adds new agent-facing run-scoped endpoints that expose orchestration state and readiness decisions; requires explicit review of run-access boundaries, auth/scope parity, and state disclosure constraints.
  • Security review artifact: docs/work-packages/20260410_rq_controller_state_orchestration_reads/artifacts/2026-04-10_security_review.md

Required Validation Gates

Code Gate

  • Implement/extend orchestration-read route and contract tests.
  • Update OpenAPI metadata/tests for orchestration-read endpoints.
  • Update frozen endpoint inventory/checklist artifacts and contract-rule guards.
  • Required commands:
    • wctl run-pytest tests/microservices/test_rq_engine_orchestration_read_routes.py --maxfail=1
    • wctl run-pytest tests/microservices/test_rq_engine_openapi_contract.py --maxfail=1
    • python tools/check_endpoint_inventory.py
    • python tools/check_route_contract_checklist.py
    • wctl run-pytest tests/tools/test_endpoint_inventory_guard.py tests/tools/test_route_contract_checklist_guard.py --maxfail=1

QA Gate

  • Run independent reviewer and qa_reviewer subagent passes.
  • Capture findings and dispositions in package tracker.
  • No unresolved medium/high QA findings at handoff.

Security Gate

  • Complete artifacts/2026-04-10_security_review.md using template guidance.
  • Run independent security_reviewer subagent pass.
  • Explicitly review auth/scope/session/CSRF and run-state disclosure implications.
  • No unresolved medium/high security findings at handoff.

Docs Gate

  • Run wctl doc-lint on changed package/tracker/prompt/security docs, frozen artifacts, and PROJECT_TRACKER.md.

References

  • docs/schemas/rq-controller-state-contract.md
  • docs/schemas/rq-engine-agent-api-contract.md
  • docs/work-packages/README.md
  • docs/prompt_templates/codex_exec_plans.md
  • docs/prompt_templates/security_review_template.md
  • wepppy/microservices/rq_engine/AGENTS.md
  • PROJECT_TRACKER.md

Deliverables

  • Orchestration-read route implementation in rq-engine (/pipeline, /readiness).
  • Orchestration-read tests and OpenAPI contract updates.
  • Updated frozen inventory/checklist artifacts for new agent-facing routes.
  • Updated package lifecycle docs and archived ExecPlan.
  • Completed security review artifact and reviewer/QA/security finding dispositions.

Closure Notes

  • Implemented run-scoped orchestration reads:
    • GET /api/runs/{runid}/{config}/pipeline
    • GET /api/runs/{runid}/{config}/readiness
  • Added deterministic payload synthesis with stable issue joins, invalidation lineage, and next-action prioritization.
  • Hardened review-driven edge handling:
    • dedicated RunConfigMismatchError (404 only for config mismatch)
    • canonical 500 for non-not-found value failures
    • UTC normalization for naive timestamps
    • deterministic empty-timeline updated_at
    • recursive child-job status/ended-at folding for fan-out queue trees
  • Expanded orchestration route tests to cover auth denial, malformed paths, completion fallback, revision sensitivity, redaction, baseline/disturbed determinism, roads/swat completion semantics, and child-tree status precedence.
  • Completed independent reviewer, qa_reviewer, and security_reviewer passes; no unresolved medium/high QA or security findings remain.
  • Archived active ExecPlan to:
    • docs/work-packages/20260410_rq_controller_state_orchestration_reads/prompts/completed/rq_controller_state_orchestration_reads_execplan.md
    • outcome note: docs/work-packages/20260410_rq_controller_state_orchestration_reads/prompts/completed/rq_controller_state_orchestration_reads_execplan_outcome.md

Follow-up Work

  • 20260410_rq_controller_state_schema_defaults
  • 20260410_rq_controller_state_geospatial_uploads
  • 20260410_rq_controller_state_errors_progress_outputs
  • 20260410_rq_controller_state_auth_concurrency