# Quant OS public status operations

The repository is the source of truth for the public status page. A deployment
contains exactly:

```text
/srv/www/quant-os/
  releases/<git-sha>/
    index.html
    status-data.js
  status -> releases/<git-sha>
```

Deployment invariants:

1. run `python3 tools/build_public_status.py --check` and the full local suite;
2. deploy from a clean, pushed commit and name the release with that full SHA;
3. acquire the web-root deployment lock and copy into a same-filesystem
   `.incoming-<sha>` directory;
4. require exactly two regular, non-symlink payload files and compare local and
   staged SHA-256 for both;
5. atomically rename the verified incoming directory to the immutable release;
6. create a temporary relative symlink and activate it with one atomic rename;
7. install [`nginx/quant-os-static.conf`](nginx/quant-os-static.conf), run
   `nginx -t`, then reload;
8. verify the canonical page, generated JavaScript, cache header and all legacy
   redirects from a public client;
9. keep the previous release for rollback.

The server-side deploy and activation are executable and fail closed:

```bash
ops/deploy_static_status.sh <full-git-sha> <staged-status-dir>
ops/activate_static_status.sh <previous-full-git-sha>
```

The first command rejects a symlinked source root, symlink payloads,
directories and any third source entry,
holds `.status-deploy.lock` across staging and activation, verifies both
SHA-256 values, atomically promotes `.incoming-<sha>`, and refuses to overwrite
an existing release. Promoted payload files and their release directory are
owner read-only. The second command is the rollback/activation primitive;
when called directly it takes the same lock and switches only a relative
symlink. A stale lock or incoming directory means a prior process may have
crashed: inspect it and confirm no deploy is running before removing it.

Nginx is deliberately two-stage:

1. include `nginx/quant-os-static.conf` in the existing HTTPS server block,
   run `nginx -t`, reload, and verify `/quant-os/status/`;
2. only then include `nginx/quant-os-legacy-redirects-302.conf`, preserving the
   existing broad `/quants-strategies/` route for other projects;
3. after an observation period and a separate production change, replace the
   302 include with `quant-os-legacy-redirects-308.conf`.

Rollback only changes the `status` symlink to the previously verified release
and reloads no application state. The page is a static, redacted build-time
snapshot; it must never contain credentials, local paths, market data, account
identifiers, positions or fills.