WEPPcloud
UserSummary Docs

← Back to usersum index

RQ Controller State Auth and Concurrency

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

Overview

This package enforces the auth and write-safety contract for controller-state surfaces so autonomous agents can execute safely under concurrent mutation. It hardens read-scope rollout (rq:read), accepted-auth parity, optimistic concurrency preconditions, and idempotency behavior alignment across descriptors, OpenAPI, and live routes.

Objectives

  • Enforce rq:read rollout semantics and planned rq:status alias sunset behavior for read-only controller-state surfaces.
  • Align accepted_auth and auth_requirements metadata with actual route behavior.
  • Implement/finish optimistic concurrency preconditions (X-Run-State-Match / expected run-state revision semantics where contract requires).
  • Implement/finish idempotency behavior and descriptor parity for mutating operations that declare idempotency support.
  • Add/extend OpenAPI and route-level tests plus frozen artifact/checklist guards for all auth/concurrency changes.

Scope

This package delivers auth rollout enforcement, concurrency/idempotency behavior alignment, and required tests/docs/checklist updates.

Included

  • Route-level auth scope enforcement updates for controller-state surfaces.
  • Descriptor/auth metadata parity updates for setup/run-scoped endpoint catalogs and schema payloads.
  • Optimistic concurrency precondition enforcement and canonical conflict responses.
  • Idempotency policy behavior alignment where declared supported.
  • OpenAPI metadata and tests for auth/concurrency/idempotency semantics.
  • 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

  • Final contract freeze/cutover reconciliation (20260410_rq_controller_state_contract_cutover).

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 final cutover package.

Success Criteria

  • Auth scope behavior for controller-state surfaces matches contract rollout rules (rq:read with explicit compatibility boundaries).
  • Descriptor accepted_auth / auth_requirements matches live route behavior and OpenAPI metadata.
  • Concurrency precondition behavior (including conflict responses) is enforced where required.
  • Idempotency behavior matches declared policy metadata where supported.
  • Required validation gates pass (code, QA, security, docs) with no unresolved medium/high findings.

Dependencies

Prerequisites

  • docs/work-packages/20260410_rq_controller_state_setup_discovery/ (complete)
  • docs/work-packages/20260410_rq_controller_state_orchestration_reads/ (complete)
  • docs/work-packages/20260410_rq_controller_state_schema_defaults/ (complete)
  • docs/work-packages/20260410_rq_controller_state_errors_progress_outputs/ (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_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: This package changes auth/scope and mutation-safety semantics; it directly affects authorization boundaries and concurrent write safety.
  • Security review artifact: docs/work-packages/20260410_rq_controller_state_auth_concurrency/artifacts/2026-04-10_security_review.md

Required Validation Gates

Code Gate

  • Implement/extend auth-concurrency/idempotency route and contract tests.
  • Update OpenAPI metadata/tests for auth/scope/concurrency/idempotency semantics.
  • Update frozen endpoint inventory/checklist artifacts and contract-rule guards.
  • Required commands:
    • wctl run-pytest tests/microservices/test_rq_engine_auth_concurrency_routes.py --maxfail=1
    • wctl run-pytest tests/microservices/test_rq_engine_auth.py tests/microservices/test_rq_engine_session_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, concurrency-conflict behavior, and idempotency replay semantics.
  • 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

  • Auth scope rollout enforcement and metadata parity updates.
  • Concurrency precondition enforcement and conflict contract coverage.
  • Idempotency behavior alignment where declared supported.
  • Updated OpenAPI/frozen inventory/checklist artifacts and guard tests.
  • Updated package lifecycle docs and archived ExecPlan on closure.
  • Completed security review artifact and reviewer/QA/security finding dispositions.

Kickoff Prompt

  • Archived ExecPlan: docs/work-packages/20260410_rq_controller_state_auth_concurrency/prompts/completed/rq_controller_state_auth_concurrency_execplan.md