Evidence rules, probe usage, cleanup commands, and environment values
This document holds the stable operating procedures for Rackspace schema snapshots. Record every result in the status record.
Store only safe conclusions in the status record. The local probe stores raw evidence in an operator-selected directory outside the repository.
Raw evidence includes:
SHOW GRANTS output.The evidence directory must use mode 0700. Each report must use mode 0600. Put the report's
safe evidence ID and SHA-256 hash in the status tables. Do not commit the path or report contents.
Each probe report uses canonical UTF-8 JSON with schema ID rackspace-schema-probe/v1, stable key
order, and one final newline. Each platform report uses schema ID rackspace-schema-platform/v1.
File names contain only the evidence type or environment, UTC timestamp, and random evidence UUID.
An evidence ID has this safe form: rackspace:<type>:<uuid>:sha256:<hex>. It includes the
complete SHA-256 hash but no sensitive identifier. Use that ID in every status table.
A persistent report contains server facts, account names, grants, certificate details, object inventory, manifests, hashes, and normalized differences. It must not contain passwords, tokens, encryption keys, connection URLs, or complete generated DDL.
The application never uploads or serves probe reports. The administrator download route serves only encrypted review artifacts from deployed refresh operations.
The root command is pnpm rackspace:probe. It runs on an operator laptop through the approved VPN
path. Step 0 builds the probe and runs the complete discovery procedure.
The probe module lives behind the server-only ./probe entry of @concourse/rsdb. It accepts
explicit connection values and paths. It does not read application environment variables, prompt
users, or write logs. The root command owns TTY input and local evidence files.
The command requires an interactive TTY. It accepts non-sensitive choices through visible prompts. By default, it receives hosts, database names, user names, passwords, and other sensitive identifiers through masked prompts that accept pasted values.
For repeat runs, the command accepts one protected JSON file through --config <absolute-path>.
The path is the only config value in the command arguments. The command does not read connection
values from environment variables or implicit environment files. It restores terminal echo after
success, errors, and handled signals.
The operator selects one absolute evidence directory outside the repository. The command creates
that directory with mode 0700 and each report with mode 0600. It rejects relative paths,
repository paths, symlinks that resolve into the repository, and existing unsafe permissions.
The command generates the report UUID before the first connection. It hashes the final report bytes with SHA-256 and prints only the safe evidence ID and local path after the write.
The command creates each temporary workspace with mode 0700 and each file with mode 0600. It
pauses for local review. After exact operator confirmation, it removes the temporary workspace. It
also removes temporary plaintext after an error or handled termination signal.
The command prints the exact temporary path at startup. A forced process kill can prevent cleanup.
Use one config file for QA, production, the local fixture, and platform recording. The command validates the exact file structure before target selection. It rejects missing keys, extra keys, invalid live values, and relative protected paths. It defers the fixture value checks until the operator selects the local fixture.
The file must contain these exact keys:
{
"schemaId": "rackspace-schema-probe-config/v1",
"evidenceDirectory": "/absolute/protected/evidence-directory",
"qa": {
"host": "qa.mysql.example.com",
"port": 3306,
"database": "qa_database",
"operator": {
"username": "qa_operator",
"password": "replace-with-password"
},
"snapshot": {
"username": "qa_snapshot",
"password": "replace-with-password"
},
"runtime": {
"username": "qa_runtime",
"password": "replace-with-password"
}
},
"production": {
"host": "production.mysql.example.com",
"port": 3306,
"database": "production_database",
"operator": {
"username": "production_operator",
"password": "replace-with-password"
},
"snapshot": {
"username": "production_snapshot",
"password": "replace-with-password"
},
"runtime": {
"username": "production_runtime",
"password": "replace-with-password"
}
},
"fixture": {
"image": "mysql:8.4.6@sha256:replace-with-64-lowercase-hex-characters",
"expectedVersion": "replace-with-exact-VERSION()-value",
"expectedVersionComment": "replace-with-exact-@@version_comment-value"
},
"platform": {
"rackspaceInspectionPath": "/absolute/protected/rackspace-inspection.json"
}
}Create the file outside the repository. Set its mode before the run:
chmod 600 /absolute/path/rackspace-probe.json
pnpm rackspace:probe --config /absolute/path/rackspace-probe.jsonThe config path must resolve outside the repository. The config must be a regular file that the
current user owns. It must use mode 0600, have one hard link, contain no more than 64 KiB, use
valid UTF-8, and not be a symbolic link. The command opens and reads it once.
The config file is the only source for reusable values during that run. The command does not merge
it with prompts, environment values, or another file. It still prompts for the target, temporary
workspace review, and exact cleanup confirmation. A run without --config keeps the full masked
prompt flow.
If the config schema is invalid, the error lists every invalid JSON path and its required format. The error does not show the supplied values.
QA, production, and platform runs accept unfinished string values in the fixture object. A
version-only image tag is valid at this stage. Before a fixture run, add the image digest and the
exact live version values. Fixture mode rejects empty values and mutable image tags before it starts
the container.
The report does not contain the config file or its path. Before the command writes a report, it scans the final bytes for the config path, every config password, and each constructed connection URL. Provider tokens, report IDs, cleanup hashes, and confirmation phrases do not belong in the config.
Run pnpm rackspace:probe without connection arguments or connection environment values. Add
--config <absolute-path> to use the protected config instead of the value prompts. The command
requires an interactive terminal and uses Clack for all interactive choices.
Host names, database names, account names, passwords, and protected paths use masked prompts. The port and exact removal phrases use visible text prompts. All prompts share one abort signal and the same input and output streams. A cancellation or handled termination signal aborts the active prompt before temporary cleanup. The command restores the terminal raw mode before it returns.
The QA and production modes require public certificate validation. They do not provide a switch to disable TLS. The non-TLS connection is private to the disposable fixture.
Use these accounts for each QA and production probe:
SHOW CREATE access.The probe never creates an account or changes a grant. It never issues an application-data write or a DDL statement. The operator creates the snapshot and runtime accounts through a separate manual procedure. The security document defines the account boundaries.
Use pnpm rackspace:probe --record-platform to record read-only Rackspace, Vercel, and GitHub
inspection results in a protected platform report. This mode never changes external state.
The command prompts for an absolute evidence directory and one protected Rackspace inspection
file. Use pnpm rackspace:probe --record-platform --config <absolute-path> to read those two values
from the protected config. The inspection file must be a regular 0600 file outside the
repository. The command runs only fixed Vercel and GitHub read operations. It removes token values
from each child environment and uses no shell. A missing API or malformed response becomes an
unavailable fact. It is not treated as proof that a resource is absent.
The platform report records available evidence for the Vercel project, Connect, Blob, Static IP, Fluid Compute, and Workflow. It also records GitHub repository settings, rulesets, required checks, and automatic branch deletion.
Select Local fixture from pnpm rackspace:probe after live discovery supplies the exact MySQL
version facts. Before you start, run a Docker-compatible container runtime.
The fixture prompts require:
tag@sha256:digest form. The command has no image default.VERSION() value from live discovery.@@version_comment value from live discovery.The disposable container creates one representative database and one unrelated database. The representative database includes tables, a view, a foreign key, a trigger, a procedure, a function, an event, and mixed-case identifiers. It creates separate operator, snapshot, and runtime accounts with the documented grant boundaries.
The fixture proves that the snapshot account cannot read or write base-table data. It proves that
the runtime account can use DML in a rolled-back transaction and cannot use DDL or change grants.
The command stops the container and removes its resources in a finally block. The normal test
task does not start Testcontainers. Run the real fixture only after live discovery supplies the
immutable image and exact version values.
The probe never removes a persistent report automatically. The local cleanup mode accepts one exact report path and its recorded SHA-256 hash. It removes only a regular report file that this probe created. It rejects directories, recursive removal, repository paths, symlinks, and hash mismatches.
Use pnpm rackspace:probe --cleanup-report <absolute-path> --sha256 <hash>. The command shows the
resolved file and requires exact interactive confirmation before removal.
The application never removes a persistent review artifact or Git branch automatically. Approval, rejection, expiry, or terminal failure starts a seven-day cleanup target. Missing that target does not remove the resource.
The administrator page shows retained artifact count, total bytes, age, state, cleanup target, and eligibility. Cleanup requires a terminal operation. An approved artifact cannot be removed while publication is in progress.
Artifact cleanup requires a fresh, non-impersonated systemAdmin session and the exact operation
ID. A fresh administrator action issues a random, single-use cleanup authorization for one
operation. The application stores only its SHA-256 hash. The authorization expires after five
minutes and enters the command through a masked, paste-enabled prompt.
Use the administrator action or pnpm rackspace:cleanup --operation <operationId>. The command
calls the same application cleanup route. It lists eligible resources and uses a dry run by
default. Add --execute for removal. It does not accept Turso, Blob, GitHub, Vercel, or Rackspace
credentials through a prompt, argument, or environment variable.
Artifact cleanup removes only the Blob object. It keeps immutable Turso metadata, hashes, review decisions, and audit events. A repeated cleanup request reconciles the recorded result.
For Blob cleanup, the route consumes the authorization and writes the cleanup intent with its audit event in one transaction. Then it removes the exact Blob. A second transaction records completion and its audit event. If the route stops after Blob removal, a later authorized request reconciles the intent. An absent Blob is valid only for the operation's exact locator.
Keep an old encryption key while any retained artifact names that version.
An orphan branch is eligible only after its operation is terminal and the operation owns the exact branch head.
Do not use GitHub's REST delete-ref endpoint for branch cleanup. It has no conditional expected-head input. The administrator page creates the cleanup authorization and shows the exact local command.
The local command obtains GitHub authentication from the existing Git credential helper. It never
receives a GitHub token through a prompt, argument, or environment variable. It uses the fixed
HTTPS URL for conveyal/concourse, sanitizes credential environment variables, and disables
interactive credential prompts. If the credential helper is unavailable, stop and keep the branch.
The command deletes the complete branch ref with an empty source refspec and
--force-with-lease=<full-ref>:<recorded-commit>. It uses no other refspec. If the remote head
changed, the push must fail and preserve the branch. The force-with-lease option guards deletion
only. The command never updates a reference.
After a successful deletion, the command calls the application route. The route confirms that the exact ref is absent before it records completion and its audit event.
Record every completed cleanup in the status record.
Configure these values only in the Production environment of the concourse Vercel project:
RACKSPACE_MYSQL_HOST=
RACKSPACE_MYSQL_PORT=
RACKSPACE_TRACER_DATABASE=
RACKSPACE_SNAPSHOT_USERNAME=
RACKSPACE_SNAPSHOT_PASSWORD=
RACKSPACE_RUNTIME_USERNAME=
RACKSPACE_RUNTIME_PASSWORD=
RACKSPACE_SCHEMA_ARTIFACT_KEYS=
BLOB_READ_WRITE_TOKEN=
VERCEL_CONNECT_CONFIGURATION_ID=RACKSPACE_SCHEMA_ARTIFACT_KEYS contains comma-separated version:base64-key entries with no
whitespace. A version must match [a-z0-9][a-z0-9_-]{0,31}. Each decoded key is 32 bytes. The
first key encrypts new artifacts.
Keep an old key until no retained artifact names its version. Record each key owner, creation date, rotation date, and retirement date in the credential custody table without recording the key value.
Evidence rules, probe usage, cleanup commands, and environment values
This document holds the stable operating procedures for Rackspace schema snapshots. Record every result in the status record.
Store only safe conclusions in the status record. The local probe stores raw evidence in an operator-selected directory outside the repository.
Raw evidence includes:
SHOW GRANTS output.The evidence directory must use mode 0700. Each report must use mode 0600. Put the report's
safe evidence ID and SHA-256 hash in the status tables. Do not commit the path or report contents.
Each probe report uses canonical UTF-8 JSON with schema ID rackspace-schema-probe/v1, stable key
order, and one final newline. Each platform report uses schema ID rackspace-schema-platform/v1.
File names contain only the evidence type or environment, UTC timestamp, and random evidence UUID.
An evidence ID has this safe form: rackspace:<type>:<uuid>:sha256:<hex>. It includes the
complete SHA-256 hash but no sensitive identifier. Use that ID in every status table.
A persistent report contains server facts, account names, grants, certificate details, object inventory, manifests, hashes, and normalized differences. It must not contain passwords, tokens, encryption keys, connection URLs, or complete generated DDL.
The application never uploads or serves probe reports. The administrator download route serves only encrypted review artifacts from deployed refresh operations.
The root command is pnpm rackspace:probe. It runs on an operator laptop through the approved VPN
path. Step 0 builds the probe and runs the complete discovery procedure.
The probe module lives behind the server-only ./probe entry of @concourse/rsdb. It accepts
explicit connection values and paths. It does not read application environment variables, prompt
users, or write logs. The root command owns TTY input and local evidence files.
The command requires an interactive TTY. It accepts non-sensitive choices through visible prompts. By default, it receives hosts, database names, user names, passwords, and other sensitive identifiers through masked prompts that accept pasted values.
For repeat runs, the command accepts one protected JSON file through --config <absolute-path>.
The path is the only config value in the command arguments. The command does not read connection
values from environment variables or implicit environment files. It restores terminal echo after
success, errors, and handled signals.
The operator selects one absolute evidence directory outside the repository. The command creates
that directory with mode 0700 and each report with mode 0600. It rejects relative paths,
repository paths, symlinks that resolve into the repository, and existing unsafe permissions.
The command generates the report UUID before the first connection. It hashes the final report bytes with SHA-256 and prints only the safe evidence ID and local path after the write.
The command creates each temporary workspace with mode 0700 and each file with mode 0600. It
pauses for local review. After exact operator confirmation, it removes the temporary workspace. It
also removes temporary plaintext after an error or handled termination signal.
The command prints the exact temporary path at startup. A forced process kill can prevent cleanup.
Use one config file for QA, production, the local fixture, and platform recording. The command validates the exact file structure before target selection. It rejects missing keys, extra keys, invalid live values, and relative protected paths. It defers the fixture value checks until the operator selects the local fixture.
The file must contain these exact keys:
{
"schemaId": "rackspace-schema-probe-config/v1",
"evidenceDirectory": "/absolute/protected/evidence-directory",
"qa": {
"host": "qa.mysql.example.com",
"port": 3306,
"database": "qa_database",
"operator": {
"username": "qa_operator",
"password": "replace-with-password"
},
"snapshot": {
"username": "qa_snapshot",
"password": "replace-with-password"
},
"runtime": {
"username": "qa_runtime",
"password": "replace-with-password"
}
},
"production": {
"host": "production.mysql.example.com",
"port": 3306,
"database": "production_database",
"operator": {
"username": "production_operator",
"password": "replace-with-password"
},
"snapshot": {
"username": "production_snapshot",
"password": "replace-with-password"
},
"runtime": {
"username": "production_runtime",
"password": "replace-with-password"
}
},
"fixture": {
"image": "mysql:8.4.6@sha256:replace-with-64-lowercase-hex-characters",
"expectedVersion": "replace-with-exact-VERSION()-value",
"expectedVersionComment": "replace-with-exact-@@version_comment-value"
},
"platform": {
"rackspaceInspectionPath": "/absolute/protected/rackspace-inspection.json"
}
}Create the file outside the repository. Set its mode before the run:
chmod 600 /absolute/path/rackspace-probe.json
pnpm rackspace:probe --config /absolute/path/rackspace-probe.jsonThe config path must resolve outside the repository. The config must be a regular file that the
current user owns. It must use mode 0600, have one hard link, contain no more than 64 KiB, use
valid UTF-8, and not be a symbolic link. The command opens and reads it once.
The config file is the only source for reusable values during that run. The command does not merge
it with prompts, environment values, or another file. It still prompts for the target, temporary
workspace review, and exact cleanup confirmation. A run without --config keeps the full masked
prompt flow.
If the config schema is invalid, the error lists every invalid JSON path and its required format. The error does not show the supplied values.
QA, production, and platform runs accept unfinished string values in the fixture object. A
version-only image tag is valid at this stage. Before a fixture run, add the image digest and the
exact live version values. Fixture mode rejects empty values and mutable image tags before it starts
the container.
The report does not contain the config file or its path. Before the command writes a report, it scans the final bytes for the config path, every config password, and each constructed connection URL. Provider tokens, report IDs, cleanup hashes, and confirmation phrases do not belong in the config.
Run pnpm rackspace:probe without connection arguments or connection environment values. Add
--config <absolute-path> to use the protected config instead of the value prompts. The command
requires an interactive terminal and uses Clack for all interactive choices.
Host names, database names, account names, passwords, and protected paths use masked prompts. The port and exact removal phrases use visible text prompts. All prompts share one abort signal and the same input and output streams. A cancellation or handled termination signal aborts the active prompt before temporary cleanup. The command restores the terminal raw mode before it returns.
The QA and production modes require public certificate validation. They do not provide a switch to disable TLS. The non-TLS connection is private to the disposable fixture.
Use these accounts for each QA and production probe:
SHOW CREATE access.The probe never creates an account or changes a grant. It never issues an application-data write or a DDL statement. The operator creates the snapshot and runtime accounts through a separate manual procedure. The security document defines the account boundaries.
Use pnpm rackspace:probe --record-platform to record read-only Rackspace, Vercel, and GitHub
inspection results in a protected platform report. This mode never changes external state.
The command prompts for an absolute evidence directory and one protected Rackspace inspection
file. Use pnpm rackspace:probe --record-platform --config <absolute-path> to read those two values
from the protected config. The inspection file must be a regular 0600 file outside the
repository. The command runs only fixed Vercel and GitHub read operations. It removes token values
from each child environment and uses no shell. A missing API or malformed response becomes an
unavailable fact. It is not treated as proof that a resource is absent.
The platform report records available evidence for the Vercel project, Connect, Blob, Static IP, Fluid Compute, and Workflow. It also records GitHub repository settings, rulesets, required checks, and automatic branch deletion.
Select Local fixture from pnpm rackspace:probe after live discovery supplies the exact MySQL
version facts. Before you start, run a Docker-compatible container runtime.
The fixture prompts require:
tag@sha256:digest form. The command has no image default.VERSION() value from live discovery.@@version_comment value from live discovery.The disposable container creates one representative database and one unrelated database. The representative database includes tables, a view, a foreign key, a trigger, a procedure, a function, an event, and mixed-case identifiers. It creates separate operator, snapshot, and runtime accounts with the documented grant boundaries.
The fixture proves that the snapshot account cannot read or write base-table data. It proves that
the runtime account can use DML in a rolled-back transaction and cannot use DDL or change grants.
The command stops the container and removes its resources in a finally block. The normal test
task does not start Testcontainers. Run the real fixture only after live discovery supplies the
immutable image and exact version values.
The probe never removes a persistent report automatically. The local cleanup mode accepts one exact report path and its recorded SHA-256 hash. It removes only a regular report file that this probe created. It rejects directories, recursive removal, repository paths, symlinks, and hash mismatches.
Use pnpm rackspace:probe --cleanup-report <absolute-path> --sha256 <hash>. The command shows the
resolved file and requires exact interactive confirmation before removal.
The application never removes a persistent review artifact or Git branch automatically. Approval, rejection, expiry, or terminal failure starts a seven-day cleanup target. Missing that target does not remove the resource.
The administrator page shows retained artifact count, total bytes, age, state, cleanup target, and eligibility. Cleanup requires a terminal operation. An approved artifact cannot be removed while publication is in progress.
Artifact cleanup requires a fresh, non-impersonated systemAdmin session and the exact operation
ID. A fresh administrator action issues a random, single-use cleanup authorization for one
operation. The application stores only its SHA-256 hash. The authorization expires after five
minutes and enters the command through a masked, paste-enabled prompt.
Use the administrator action or pnpm rackspace:cleanup --operation <operationId>. The command
calls the same application cleanup route. It lists eligible resources and uses a dry run by
default. Add --execute for removal. It does not accept Turso, Blob, GitHub, Vercel, or Rackspace
credentials through a prompt, argument, or environment variable.
Artifact cleanup removes only the Blob object. It keeps immutable Turso metadata, hashes, review decisions, and audit events. A repeated cleanup request reconciles the recorded result.
For Blob cleanup, the route consumes the authorization and writes the cleanup intent with its audit event in one transaction. Then it removes the exact Blob. A second transaction records completion and its audit event. If the route stops after Blob removal, a later authorized request reconciles the intent. An absent Blob is valid only for the operation's exact locator.
Keep an old encryption key while any retained artifact names that version.
An orphan branch is eligible only after its operation is terminal and the operation owns the exact branch head.
Do not use GitHub's REST delete-ref endpoint for branch cleanup. It has no conditional expected-head input. The administrator page creates the cleanup authorization and shows the exact local command.
The local command obtains GitHub authentication from the existing Git credential helper. It never
receives a GitHub token through a prompt, argument, or environment variable. It uses the fixed
HTTPS URL for conveyal/concourse, sanitizes credential environment variables, and disables
interactive credential prompts. If the credential helper is unavailable, stop and keep the branch.
The command deletes the complete branch ref with an empty source refspec and
--force-with-lease=<full-ref>:<recorded-commit>. It uses no other refspec. If the remote head
changed, the push must fail and preserve the branch. The force-with-lease option guards deletion
only. The command never updates a reference.
After a successful deletion, the command calls the application route. The route confirms that the exact ref is absent before it records completion and its audit event.
Record every completed cleanup in the status record.
Configure these values only in the Production environment of the concourse Vercel project:
RACKSPACE_MYSQL_HOST=
RACKSPACE_MYSQL_PORT=
RACKSPACE_TRACER_DATABASE=
RACKSPACE_SNAPSHOT_USERNAME=
RACKSPACE_SNAPSHOT_PASSWORD=
RACKSPACE_RUNTIME_USERNAME=
RACKSPACE_RUNTIME_PASSWORD=
RACKSPACE_SCHEMA_ARTIFACT_KEYS=
BLOB_READ_WRITE_TOKEN=
VERCEL_CONNECT_CONFIGURATION_ID=RACKSPACE_SCHEMA_ARTIFACT_KEYS contains comma-separated version:base64-key entries with no
whitespace. A version must match [a-z0-9][a-z0-9_-]{0,31}. Each decoded key is 32 bytes. The
first key encrypts new artifacts.
Keep an old key until no retained artifact names its version. Record each key owner, creation date, rotation date, and retirement date in the credential custody table without recording the key value.