WEPPcloud
UserSummary Docs

← Back to usersum index

RQ Controller State Geospatial and Upload Metadata

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

Overview

This package implements run-scoped geospatial metadata and upload-file contract metadata so agents can choose valid first-step watershed parameters and validate upload payloads before submit. It adds /geospatial-metadata and hardens upload operation metadata semantics for format, CRS, extent, resolution, value-class constraints, and upload size limits.

Objectives

  • Implement GET /api/runs/{runid}/{config}/geospatial-metadata with run-resolved coverage/default/context fields.
  • Implement upload metadata contract fields for:
    • rq_engine_upload_dem
    • rq_engine_upload_cli
    • rq_engine_upload_sbs
    • rq_engine_upload_cover_transform
  • Enforce contract-aligned file metadata semantics (content type, extension, size, CRS, extent coverage, resolution, and value semantics).
  • Add/extend OpenAPI and route-level tests plus frozen artifact/checklist guards for all new/updated surfaces.

Scope

This package delivers geospatial metadata route implementation, upload metadata payload hardening, and required tests/docs/checklist updates.

Included

  • Geospatial metadata route implementation under rq-engine:
    • GET /api/runs/{runid}/{config}/geospatial-metadata
  • Upload operation descriptor/schema/default payload hardening for DEM/CLI/SBS/cover-transform operations.
  • Live upload handler size-limit enforcement (max_bytes) and regression tests.
  • Contract and route tests for auth, payload shape, parity across metadata surfaces, and geospatial/upload metadata 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

  • Operation error catalog, async progress, and 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 6-8.

Success Criteria

  • /api/runs/{runid}/{config}/geospatial-metadata is implemented and exposed with contract-aligned fields.
  • Upload operation metadata for DEM/CLI/SBS/cover-transform includes machine-checkable file constraints.
  • Geospatial/upload metadata payloads are deterministic for equivalent run state.
  • Frozen endpoint inventory/checklist artifacts include new/updated geospatial/upload contract rows.
  • 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_schema_defaults/ (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_errors_progress_outputs
  • 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: Upload metadata semantics and geospatial defaults influence file validation and route selection; disclosure and validation-contract boundaries must be reviewed explicitly.
  • Security review artifact: docs/work-packages/20260410_rq_controller_state_geospatial_uploads/artifacts/2026-04-10_security_review.md

Required Validation Gates

Code Gate

  • wctl run-pytest tests/microservices/test_rq_engine_geospatial_upload_metadata_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

  • Independent reviewer and qa_reviewer passes completed.
  • Findings dispositioned in package tracker.
  • No unresolved medium/high QA findings at handoff.

Security Gate

  • Security artifact completed and reviewed by security_reviewer.
  • Auth/scope/session, upload metadata disclosure, and validation-contract implications reviewed.
  • No unresolved medium/high security findings at handoff.

Docs Gate

  • wctl doc-lint run 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

  • Geospatial metadata route implementation in rq-engine.
  • Upload metadata schema/default contract hardening for core upload operations.
  • Geospatial/upload tests and OpenAPI contract updates.
  • Updated frozen inventory/checklist artifacts for new/updated agent-facing routes.
  • Updated package lifecycle docs and archived ExecPlan outcome.
  • Completed security review artifact and reviewer/QA/security finding dispositions.

Closure Notes

  • Implemented GET /api/runs/{runid}/{config}/geospatial-metadata with canonical auth/error boundaries and deterministic fallbacks.
  • Hardened upload descriptor/schema/default metadata for:
    • rq_engine_upload_dem
    • rq_engine_upload_cli
    • rq_engine_upload_sbs
    • rq_engine_upload_cover_transform
  • Added and enforced live upload max_bytes limits for DEM/CLI/SBS/cover-transform routes.
  • Added parity helpers/tests for climate mode, soils mode, and watershed defaults across metadata surfaces.
  • Updated endpoint inventory and route-contract checklist freeze artifacts plus guard rule coverage.
  • Completed independent reviewer, qa_reviewer, and security_reviewer re-reviews; no unresolved medium/high findings.
  • Archived active ExecPlan to:
    • docs/work-packages/20260410_rq_controller_state_geospatial_uploads/prompts/completed/rq_controller_state_geospatial_uploads_execplan.md
    • outcome note: docs/work-packages/20260410_rq_controller_state_geospatial_uploads/prompts/completed/rq_controller_state_geospatial_uploads_execplan_outcome.md

Follow-up Work

  • 20260410_rq_controller_state_errors_progress_outputs
  • 20260410_rq_controller_state_auth_concurrency