diff --git a/Data/Engine/CURRENT_STAGE.md b/Data/Engine/CURRENT_STAGE.md index d478102..30cf14b 100644 --- a/Data/Engine/CURRENT_STAGE.md +++ b/Data/Engine/CURRENT_STAGE.md @@ -59,9 +59,11 @@ - 11.2 Provide repository/service hooks for fetching artifacts or repo heads; add resilience logging. - 11.3 Commit after integration tests (or mocked unit tests) confirm API workflows. -12. Final parity verification -- 12.1 Stand up Engine end-to-end in a staging environment, exercising enrollment, token refresh, agent connections, and jobs. -- 12.2 Document any divergences and address them with follow-up commits. -- 12.3 Once satisfied, coordinate cut-over steps (switch entrypoint, deprecate legacy server) as a future initiative. -- Documentation and test coverage for this phase now live in `Data/Engine/README.md` and `Data/Engine/tests/` to guide the - remaining staging work. +[IN PROGRESS] 12. Final parity verification +- 12.1 Follow the staging playbook in `Data/Engine/STAGING_GUIDE.md` to stand up the Engine end-to-end and exercise enrollment, + token refresh, agent connections, GitHub integration, and scheduler flows. +- 12.2 Record any divergences in the staging guide’s table and address them with follow-up commits before cut-over. +- 12.3 Once parity is confirmed, coordinate entrypoint switching (point deployment at `Data/Engine/bootstrapper.py`) and plan + the legacy server deprecation. +- Supporting documentation and unit tests live in `Data/Engine/README.md`, `Data/Engine/STAGING_GUIDE.md`, and + `Data/Engine/tests/` to guide the remaining staging work. diff --git a/Data/Engine/README.md b/Data/Engine/README.md index 18de81a..1b9d433 100644 --- a/Data/Engine/README.md +++ b/Data/Engine/README.md @@ -130,13 +130,16 @@ The service container now wires `github_service`, giving other interfaces and ba ## Final parity checklist Step 12 tracks the final integration work required before switching over to the -Engine entrypoint: +Engine entrypoint. Use the detailed playbook in +[`Data/Engine/STAGING_GUIDE.md`](./STAGING_GUIDE.md) to coordinate each +staging run: 1. Stand up the Engine in a staging environment and exercise enrollment, token refresh, scheduler operations, and the agent real-time channel side-by-side with the legacy server. -2. Capture any behavioural differences uncovered during staging and file them - for follow-up fixes before the cut-over. +2. Capture any behavioural differences uncovered during staging using the + divergence table in the staging guide and file them for follow-up fixes + before the cut-over. 3. When satisfied with parity, coordinate the entrypoint swap (point production tooling at `Data/Engine/bootstrapper.py`) and plan the deprecation of `Data/Server`. diff --git a/Data/Engine/STAGING_GUIDE.md b/Data/Engine/STAGING_GUIDE.md new file mode 100644 index 0000000..60ae3b5 --- /dev/null +++ b/Data/Engine/STAGING_GUIDE.md @@ -0,0 +1,116 @@ +# Engine Staging & Parity Guide + +This guide supports Step 12 of the migration plan by walking operators through +standing up the Engine alongside the legacy server, validating core workflows, +and documenting any behavioural gaps before switching the production entrypoint +to `Data/Engine/bootstrapper.py`. + +## 1. Prerequisites + +- Python 3.11 or later available on the host. +- A clone of the Borealis repository with the Engine tree checked out. +- Access to the legacy runtime assets (certificates, TLS bundle, etc.). +- Optional: a staging agent install for end-to-end WebSocket validation. + +Ensure the SQLite database lives at `/database.db` and that the +Engine migrations have already run (they execute automatically when the +`BOREALIS_ENGINE_AUTO_MIGRATE` environment variable is left at its default +`true`). + +## 2. Launching the Engine in staging mode + +1. Open a terminal at the project root. +2. Set any environment overrides required for the test scenario (for example, + `BOREALIS_DEBUG=true` to surface verbose logging, or + `BOREALIS_CORS_ALLOWED_ORIGINS=https://localhost:3000` when pairing with the + React UI). +3. Run the Engine entrypoint: + + ```bash + python Data/Engine/bootstrapper.py + ``` + +4. Verify `Logs/Server/engine.log` is created and that the startup entries are + timestamped `-engine-`. + +Keep the legacy server running in a separate process if comparative testing is +required; they do not share global state. + +## 3. Feature validation checklist + +Work through the following areas and tick each box once verified. Capture any +issues in the log table in §4. + +### Authentication and tokens + +- [ ] `POST /api/agent/token/refresh` returns a new access token when supplied a + valid refresh token + DPoP proof. +- [ ] Invalid DPoP proofs or revoked refresh tokens yield the expected HTTP 401 + responses and structured error payloads. +- [ ] Device last-seen metadata updates inside the database after a successful + refresh. + +### Enrollment + +- [ ] `POST /api/agent/enroll/request` produces an enrollment ticket with the + correct expiration and retry counters. +- [ ] `POST /api/agent/enroll/poll` transitions an approved device into an + authenticated state and returns the TLS bundle. +- [ ] Audit logging for approvals lands in `Logs/Server/engine.log`. + +### Job management + +- [ ] `POST /api/jobs` (or UI equivalent) creates a scheduled job and returns a + manifest identifier. +- [ ] `GET /api/jobs/` surfaces the stored manifest with normalized + schedules and environment variables. +- [ ] Job lifecycle events arrive over the `job_management` Socket.IO namespace + when a job transitions between `pending`, `running`, and `completed`. + +### Real-time agents + +- [ ] Agents connecting to the `agents` namespace appear in the realtime roster + with accurate hostname, username, and fingerprint details. +- [ ] Screenshot broadcasts relay from agents to the UI without residual cache + bleed-through after disconnects. +- [ ] Macro execution responses round-trip through Socket.IO and reach the + initiating client. + +### GitHub integration + +- [ ] `GET /api/repo/current_hash` reflects the latest branch head and caches + repeated calls. +- [ ] `POST /api/github/token` persists a new token and survives Engine restarts + (confirm via database inspection). +- [ ] The background refresher logs rate-limit warnings instead of raising + uncaught exceptions when the GitHub API throttles requests. + +## 4. Recording divergences + +Use the table below to document behavioural differences or bugs uncovered during +staging. This artifact should accompany the staging run summary so follow-up +fixes can be triaged quickly. + +| Area | Legacy Behaviour | Engine Behaviour | Notes / Links | +| --- | --- | --- | --- | +| Authentication | | | | +| Enrollment | | | | +| Scheduler | | | | +| Realtime | | | | +| GitHub | | | | +| Other | | | | + +## 5. Cut-over readiness + +Once every checklist item passes and no critical divergences remain: + +1. Update `Data/Engine/CURRENT_STAGE.md` with the completion date for Step 12. +2. Coordinate with the operator to switch deployment scripts to + `Data/Engine/bootstrapper.py`. +3. Plan a rollback strategy (typically re-launching the legacy server) should + issues appear immediately after the cut-over. +4. Archive the filled divergence table alongside Engine logs for historical + traceability. + +Document the results in project tracking tools before moving on to deprecating +`Data/Server`.