0004: Rackspace verification simplification

• ID: PRD-0004
• Status: Accepted
• Decision maker: Trevor Gerhardt
• Scope: apps/concourse, packages/db, packages/contracts, packages/rsdb
• Product owner: Concourse maintainers
• Design owner: Concourse maintainers
• Engineering owner: Concourse maintainers
• Last reviewed: 2026-09-25
• Related issues or projects: #155
• Related designs: N/A
• Related ADRs: ADR-0006
• Related user documentation: Rackspace operations

Summary

Production Rackspace verification uses one authenticated server action per registry database. The application saves each result before the browser requests the next database, stops after the first failure, and shows the saved report after a reload. Removing Vercel Workflow, operation status APIs, and step storage reduces the moving parts for this single read-only use case.

User problem and evidence

System administrators need a trustworthy answer about whether the deployed Production schemas match the committed registry. The previous durable Workflow design added retries, leases, polling, and provider state for a path that is used only occasionally and can be bounded per database. Issue #155 records the simplification request and approved scope.

Goals and success measures

Non-goals

• Retry a timed-out or failed database automatically.
• Resume an incomplete report after a reload.
• Preserve old operation rows; no deployed verification data needs migration.
• Change the Rackspace MySQL verifier or local snapshot generation flow.

Users and use cases

Use case: Verify the deployed registry

• Actor: Fresh, non-impersonated system administrator
• Need: Check every committed Production database schema
• Goal: See a durable, safe report with enough progress and failure detail to act

Requirements

PRD-0004-US-01: Start a verification report

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As an administrator, I want to start a Production registry check, so that I can compare the deployment with committed snapshots.
• Requirement: Create a report with deployment identity, commit SHA, timestamps, and an immutable registry snapshot.
• Done when:
  • The action requires a fresh, non-impersonated system administrator.
  • The report begins with an empty ordered result list and incomplete outcome.

PRD-0004-US-02: Save sequential database results

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As an administrator, I want each database result saved before the next check, so that a timeout does not erase completed work.
• Requirement: Run one bounded verification request at a time in registry order and append the sanitized result atomically.
• Done when:
  • A duplicate position is idempotent and a skipped position is rejected.
  • A deployment or commit change prevents the next request.
  • A failed result is saved as failed, even when the report is still a partial registry prefix, and stops later database requests.

PRD-0004-US-03: Read a partial or complete report

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As an administrator, I want to reload the page and see saved progress, so that I can understand what completed.
• Requirement: Show the newest report, its registry, each saved result, and the derived outcome.
• Done when:
  • Unsaved registry entries show as not checked.
  • A report is failed when any saved result fails, passed when every registry result passes, and incomplete only while no saved result has failed and the registry is not exhausted.
  • Starting again creates a new report from the first registry entry.

PRD-0004-US-04: Handle request interruption

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As an administrator, I want an interrupted request to leave saved results intact, so that I can distinguish completed checks from work that needs a new run.
• Requirement: Keep the report incomplete when a platform timeout, network error, or persistence error prevents the current result from being saved.
• Done when:
  • The browser stops issuing requests after an action error and tells the administrator to reload.
  • A new verification starts a new report and never resumes the interrupted report automatically.

Implementation

Concourse starts an app-local verification report and requests each registry database in order. The report saves an immutable registry snapshot and each safe result. Reload shows the saved prefix. A failed result stops the sequence. Rackspace operations documents the deployed checks.

Experience and content

• Entry point: /admin/rackspace on a Production deployment.
• Loading: The button is disabled while the current server action is running.
• Progress: The panel lists the registry in order and labels missing results as Not checked.
• Success: The panel shows Passed after every registry result passes.
• Failure: The panel shows the saved failed database and stops the sequence.
• Access: Fresh, non-impersonated system administrators only.
• Accessibility: Use the existing admin panel semantics and visible status text; no polling-only state.

Constraints and dependencies

• Each database request targets 45 seconds, with 5-second query and 10-second connection limits.
• The Next.js route has a 60-second platform target; a cutoff can leave the report incomplete.
• @concourse/rsdb remains independent of application persistence and owns verification meaning.
• Persistence and audit writes remain in @concourse/db and the application.

User documentation

• Audience: System administrators and operators
• Tasks to explain: Start a Production check, read partial progress, interpret outcomes
• Agreed terms: Verification report, registry, not checked, incomplete, passed, failed
• Examples or screenshots needed: N/A
• Published documentation: Rackspace operations

Revision history

• 2026-09-25 — PRD-0004-US-01 through PRD-0004-US-04: Replace the delivery notes with a summary of the current implementation, and accept the implemented stories. PR #168

References

• Issue #155