WEPPcloud
UserSummary Docs

← Back to usersum index

RQ Controller State Schema and Defaults

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

Overview

This package implements the schema/default read surfaces that let agents discover controller and operation constraints directly from rq-engine for an existing runid/config. It covers controller schema/hints/templates plus run-scoped endpoint schema/defaults with run-resolved constraints and defaults.

Objectives

  • Implement run-scoped controller metadata surfaces:
    • GET /api/runs/{runid}/{config}/controllers
    • GET /api/runs/{runid}/{config}/controllers/{controller}/schema
    • GET /api/runs/{runid}/{config}/controllers/{controller}/hints
    • GET /api/runs/{runid}/{config}/controllers/{controller}/templates
  • Implement run-scoped endpoint schema/default surfaces:
    • GET /api/runs/{runid}/{config}/endpoints
    • GET /api/runs/{runid}/{config}/endpoints/{operation_id}/schema
    • GET /api/runs/{runid}/{config}/endpoints/{operation_id}/defaults
  • Enforce contract-aligned metadata semantics including constraint_mode, predicate grammar fields (required_if, available_if), and run-resolved defaults context.
  • Add/extend OpenAPI and route-level tests plus frozen artifact/checklist guards for the new endpoints.

Scope

This package delivers schema/default route implementation, contract-aligned payload builders, and required tests/docs/checklist updates.

Included

  • New rq-engine schema/default route module(s) for controller and endpoint metadata reads.
  • Router registration and OpenAPI metadata updates.
  • Deterministic metadata payload assembly for baseline and disturbed configs.
  • Contract and route tests for auth, payload shape, predicate grammar fields, and run-resolved constraint/default behavior.
  • 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

  • Geospatial/upload metadata contracts (20260410_rq_controller_state_geospatial_uploads).
  • Operation error catalogs/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 5-8.

Success Criteria

  • Controller and endpoint schema/default surfaces are implemented and exposed under rq-engine /api/runs/{runid}/{config}.
  • Core metadata fields align with contract expectations (constraint_mode, required_if, available_if, run-resolved defaults context).
  • Schema/default payloads are deterministic for equivalent baseline and disturbed run states.
  • Frozen endpoint inventory/checklist artifacts include all new schema/default 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_orchestration_reads/ (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_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: New run-scoped metadata surfaces expose controller and operation constraints/defaults used for autonomous execution planning; requires explicit run-access and data-disclosure review.
  • Security review artifact: docs/work-packages/20260410_rq_controller_state_schema_defaults/artifacts/2026-04-10_security_review.md

Required Validation Gates

Code Gate

  • Implement/extend schema/default routes and contract tests.
  • Update OpenAPI metadata/tests for schema/default endpoints.
  • Update frozen endpoint inventory/checklist artifacts and contract-rule guards.
  • Required commands:
    • wctl run-pytest tests/microservices/test_rq_engine_schema_defaults_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 sensitive-field disclosure implications.
  • No unresolved medium/high security findings at handoff.

Docs Gate

  • Run wctl doc-lint on changed schema/package/tracker/prompt/security docs 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

  • Schema/default route implementation in rq-engine for controller and endpoint metadata reads.
  • Schema/default tests and OpenAPI contract updates.
  • Updated frozen inventory/checklist artifacts for new agent-facing routes.
  • Updated package lifecycle docs and archived ExecPlan on closure.
  • Completed security review artifact and reviewer/QA/security finding dispositions.

Closure Notes

  • Implemented run-scoped schema/default routes:
    • GET /api/runs/{runid}/{config}/controllers
    • GET /api/runs/{runid}/{config}/controllers/{controller}/schema
    • GET /api/runs/{runid}/{config}/controllers/{controller}/hints
    • GET /api/runs/{runid}/{config}/controllers/{controller}/templates
    • GET /api/runs/{runid}/{config}/endpoints
    • GET /api/runs/{runid}/{config}/endpoints/{operation_id}/schema
    • GET /api/runs/{runid}/{config}/endpoints/{operation_id}/defaults
  • Registered schema/default router in wepppy/microservices/rq_engine/__init__.py and added deterministic payload builders in wepppy/microservices/rq_engine/schema_defaults_routes.py.
  • Updated and extended coverage:
    • tests/microservices/test_rq_engine_schema_defaults_routes.py
    • tests/microservices/test_rq_engine_openapi_contract.py
    • tools/rq_engine_contract_rules.py
    • frozen artifacts in docs/work-packages/20260208_rq_engine_agent_usability/artifacts/
  • Resolved reviewer-discovered parity defects between metadata and actual handlers (climate default integer typing, upload-SBS disturbed-mod gating, operation schema/default parity for soils/wepp/session-token surfaces).
  • Completed independent reviewer, qa_reviewer, and security_reviewer gates with no unresolved medium/high findings.
  • Archived active ExecPlan to:
    • docs/work-packages/20260410_rq_controller_state_schema_defaults/prompts/completed/rq_controller_state_schema_defaults_execplan.md
    • outcome note: docs/work-packages/20260410_rq_controller_state_schema_defaults/prompts/completed/rq_controller_state_schema_defaults_execplan_outcome.md

Kickoff Prompt (Archived)

  • docs/work-packages/20260410_rq_controller_state_schema_defaults/prompts/completed/rq_controller_state_schema_defaults_execplan.md