Operations

Create the protected configuration

Create one JSON file outside the repository:

{
  "schemaId": "rackspace-local-generation-config/v1",
  "sourceEnvironment": "production",
  "host": "<reviewed Rackspace host>",
  "port": 3306,
  "username": "<shared runtime account>",
  "password": "<shared runtime password>",
  "useTls": false
}

The file must:

• be owned by the current user.
• be a regular file with mode 0600 and one hard link.
• have no symlink in its path.
• have no secret material in its name.

CAUTION: Do not put this file or its values in Git, an environment file, a shell argument other than the --config path, or a support message.

Generate a snapshot

1. Connect the laptop to the approved VPN.

2. Run the generation command from an interactive terminal:

   pnpm rackspace:schema generate --config <absolute-config-path>

3. When the command shows the list of visible databases, type part of a name to filter the list, and select a database. The list then shows again with Done first. Select more databases, or select Done. To skip the list, add --database <name> once for each database.

4. When the command asks, confirm that the selected databases are the intended Production sources.

5. Review the safe summaries before you approve the worktree change.

The command validates MySQL 8.0.33 and the exact reviewed grants. It discovers every visible non-system database, omits a name that cannot map to a repository directory, and shows the rest in a searchable binary-ordered list. The list has no default. A database that you name with --database must be in the same visible set.

For each selected database, the command does two complete generation passes. It compares all stable output and DDL, compiles the generated TypeScript, scans for protected values, and runs zero-row checks. If the two passes differ, the command stops and installs nothing.

The command installs every changed directory and the registry as one transaction. It does not create or modify a Git branch, commit, or pull request.

Verify the repository

After each generated change, run the credential-free verifier and the merge gate:

pnpm rackspace:schema verify
pnpm verify

The first command validates every receipt, generated file hash, required layout, registry entry, and generated TypeScript module. A byte-identical generation run keeps the existing receipt and does not change its timestamp.

Run the Preview connection check

1. Sign in to the exact Preview deployment as a fresh, non-impersonated system administrator.
2. Open /admin/rackspace.
3. Start the connection check.

The check selects mi_property_value_qa and proves the endpoint, the transport, the authentication, the exact grants, the database selection, and a zero-row query. The application records an audit-intent event before it connects and a sanitized result event afterward. Preview does not verify a generated schema.

Run the Production deployed verification

1. Sign in to the exact Production deployment as a fresh, non-impersonated system administrator.
2. Open /admin/rackspace.
3. Select Verify deployed registry.

The action creates one report with the current deployment ID, commit SHA, and an immutable copy of the registry. The browser then calls one server action per database in registry order. Each action records an audit intent, runs the bounded read-only check, validates the safe result, and saves it before the browser requests the next database. The browser stops after the first failed result or when the report is complete. It cannot select a subset or retry a database automatically.

Each database request uses a 45-second database limit, a 5-second per-query limit, and a single connection in the pool. The route has a one-minute platform target. A platform timeout can leave a report incomplete when no failure was saved and the request ends before its result is saved. A deployment or commit change stops the next request. Starting again creates a new report from the first registry entry.

If an administrator has more than one tab open, read-only requests can overlap. MySQL access runs outside application database transactions. Concurrent requests for one report position keep the first saved result. Later duplicates return the saved report without replacing its results.

The report uses rackspace-verification-report/v1 and includes the ordered registry snapshot, saved results, deployment ID, commit SHA, timestamps, and the derived incomplete, passed, or failed outcome. A saved failure makes the report failed even when later registry entries are not checked. Otherwise, an unfinished report is incomplete; a fully passing report is passed. Reloading /admin/rackspace reads the newest saved report and displays every registry entry, marking unsaved entries as not checked.

Rollback compatibility

The baseline creates one rackspace_verification_report table. Roll back only to code that supports the current database schema. If a rollback needs another schema, restore a backup or use a reviewed recovery procedure. Changing project environment variables does not remove credentials from existing deployments.

Recover from a failed generation

A failure names the failed stage and a safe error code. Successful cleanup preserves the original failure stage. Syntax errors include a generated file label and, for TypeScript, its line and zero-based column. The command omits source text and raw parser or formatter messages.

contracts.ts defines each error code and its message. The GENERATED_* codes identify a generated-file error: missing layout, invalid TypeScript, malformed snapshot JSON, or a formatter that did not start or that failed.

A handled local error, a termination signal, a connection-close error, or a temporary-cleanup error restores the selected generated tree and the registry. A power loss or an uncatchable process kill can leave an incomplete worktree transaction.

If a generation run ends without a handled exit:

1. Stop. Do not start another generation run.
2. Inspect git status and git diff.
3. Restore the affected generated paths with Git.

Registry change acceptance

For each registry change, inspect the complete generated tree, receipt, and registry diff. Run the focused package, application, integration, boundary, and documentation checks. Run pnpm verify and check the required CI jobs for the exact commit.

Check that the trusted Preview deployment is healthy and records a successful QA connection check. Check that the merged Production deployment has the expected commit SHA. Start a full-registry verification with a fresh, non-impersonated system administrator. The saved report must contain one safe result per registry entry, in order, with the deployment ID and commit SHA.