rigscope 0.0.0-stage → 0.1.1

package/docs/releasing.md

@@ -0,0 +1,154 @@
+# Releasing Rigscope
+
+The first public version, `0.1.0`, is published on
+[npm](https://www.npmjs.com/package/rigscope). Source and issues are on
+[GitHub](https://github.com/Triet1402/rigscope). The package includes MIT licensing,
+dependency notices, the security policy and [release notes](../CHANGELOG.md).
+
+The commands below use `0.1.0` as an example. For a new release, substitute its
+new version everywhere; do not attempt to republish `0.1.0`. Documentation edits
+can be committed and pushed to GitHub independently. The published archive and
+its bundled documentation stay unchanged; ship updated package documentation
+with the next version. Keep each release tag on the revision used to build it.
+
+## Recommended release order
+
+1. Update the version, docs, release notes and repository metadata. Commit them.
+2. Push the source to GitHub and run the manual CI workflow on that revision.
+   CI runs manually; pushes and pull requests do not trigger it.
+3. Build one npm archive from the final revision. Retain it, its SHA-256 checksum
+   and verification results. Test and publish that archive without rebuilding it.
+4. Run the publish dry run, check the npm account, and publish the verified archive.
+5. Verify the registry version and install it into a disposable test installation.
+   Check sign-in, fresh telemetry and the installed command.
+6. Tag the exact source revision as `v0.1.0`, push the tag, and create a GitHub
+   Release with the release notes, verified archive and checksum. Announce it
+   after the registry installation works.
+
+For subsequent releases, update the package and lockfile versions together
+(for example, `npm version patch --no-git-tag-version`), update the release notes,
+and repeat the same sequence. A published name/version cannot be overwritten,
+so a correction after publication needs a new version. Prereleases should use
+an explicit tag such as `next`; ordinary `rigscope upgrade` follows `latest`.
+
+## Build the final archive
+
+Run from the source checkout with Linux and Node.js 26+:
+
+```sh
+npm ci
+npm run typecheck
+mkdir -p out/release
+npm pack --pack-destination out/release
+```
+
+`npm pack` runs `prepack`, which regenerates dependency notices, builds fresh
+runtime/UI artifacts and verifies them. If notice generation changes a tracked
+file, include that change in the release commit before producing the final
+archive. Reuse the archive for every check below. Replace `0.1.0` in these
+commands when releasing another version.
+
+## Verify the exact archive
+
+```sh
+node scripts/verify-package.cjs ./out/release/rigscope-0.1.0.tgz
+npm run verify:installed -- --archive ./out/release/rigscope-0.1.0.tgz
+npm test
+node scripts/test-runtime.cjs
+node scripts/test.cjs --suite development
+```
+
+Package inspection verifies the built CLI/runtime/UI and excludes source tests,
+Git data, private environment files and caches. Inspect the file list for
+unexpected state, databases, credentials or logs. Installed-package verification
+uses production dependencies in a temporary directory, audits the resolved
+dependency tree and checks the CLI version plus authenticated sign-in/History.
+
+The following opt-in checks require a working Linux systemd user manager. They
+create disposable installations with separate state, launchers, ports and unit
+names, then remove their services. They do not select an existing installation.
+
+```sh
+RIGSCOPE_TEST_ARCHIVE="$PWD/out/release/rigscope-0.1.0.tgz" \
+  node --import tsx --test tests/cli-install.integration.ts
+node scripts/verify-operations.cjs ./out/release/rigscope-0.1.0.tgz
+```
+
+These cover installation, pairing, independent component controls, bootstrap
+removal, retained-data reinstall, upgrade/rollback, failed-start recovery and
+offline password recovery. Runtime tests additionally cover authenticated HTTPS,
+SSE, collector connections, persistence and reconnect behavior in isolated setups.
+
+On the reference host with 48 logical cores, two RTX 3090s and an ASPEED adapter,
+run the hardware-specific test explicitly:
+
+```sh
+RIGSCOPE_REAL_HW=1 node --import tsx --test tests/sampling-real.test.ts
+```
+
+That test reads the actual host and is skipped by default. Its exact inventory
+assertions are specific to that rig; it is not a portable hardware test.
+
+Record the final checksum after verification:
+
+```sh
+cd out/release
+sha256sum rigscope-0.1.0.tgz > SHA256SUMS
+sha256sum --check SHA256SUMS
+```
+
+Keep the source revision, archive checksum, check results and any skips together.
+Record boot enablement separately from an actual reboot. Physical laptop testing
+and synthetic scale workloads are separate evidence; see
+[hardware support](installation.md#hardware) and [scale validation](scale-validation.md).
+
+## Publish dry run and publication
+
+Run these commands from the source checkout. Sign in interactively if needed,
+then verify the account and preview the exact archive:
+
+```sh
+npm login --registry=https://registry.npmjs.org
+npm whoami --registry=https://registry.npmjs.org
+npm publish ./out/release/rigscope-0.1.0.tgz --access public --tag latest \
+  --registry=https://registry.npmjs.org --dry-run
+```
+
+The dry run checks the package without publishing. It does not verify permission
+to publish or complete two-factor authentication.
+
+When releasing, this command actually publishes the verified archive publicly:
+
+```sh
+npm publish ./out/release/rigscope-0.1.0.tgz --access public --tag latest \
+  --registry=https://registry.npmjs.org
+npm view rigscope@0.1.0 version dist.integrity --registry=https://registry.npmjs.org
+```
+
+Then use `npx --yes rigscope@0.1.0 install` with a disposable `--state-dir`, an
+unused `--port` and an isolated `XDG_BIN_HOME` for the registry installation
+check. Uninstall that test installation afterward. Use the same isolation
+settings for all test commands so the check does not select a real installation.
+
+The public quick start uses `npx --yes rigscope@latest install --boot` and the
+installed `rigscope upgrade`. Archive commands remain available for downloaded
+releases and testing before publication. Users do not need a global npm
+installation of Rigscope.
+
+GitHub Actions trusted publishing can automate later releases. Configure it for
+the actual repository and publishing workflow; the current CI workflow only
+verifies and does not publish. See npm's
+[publishing documentation](https://docs.npmjs.com/cli/commands/npm-publish/) and
+[trusted publishing guide](https://docs.npmjs.com/trusted-publishers/).
+
+## Alternative manifest archives
+
+`npm run package:release` creates an operations `.tar.gz` with a hashed manifest.
+It is a separate format from the npm `.tgz`. The low-level installer validates
+size/hash and required artifacts before activation. Production dependencies must
+be installed in the staged release; activation never silently runs npm or service
+commands. See [operations](operations.md#low-level-manifest-archive-workflow) and
+[system installation](system-installation.md).
+
+Configuration, database schema and wire-protocol revisions are internal
+compatibility checks, independent of the application package version.

package/docs/scale-acceptance.json

@@ -0,0 +1,412 @@
+{
+  "tool": "rigscope-scale-harness",
+  "synthetic": true,
+  "disclaimer": "Synthetic bounded workload on an isolated temporary hub/database, not a capacity, latency, or hardware guarantee. Values depend on this host, disk, Node version, payload, cadence, viewer count and concurrent activity.",
+  "generatedAt": "2026-11-04T00:57:26.376Z",
+  "node": "v26.13.0",
+  "host": {
+    "platform": "linux",
+    "release": "7.3.0-9-generic",
+    "arch": "x64",
+    "cpuModel": "AMD EPYC 7402P 24-Core Processor",
+    "logicalCores": 48,
+    "totalMemoryBytes": 130351214592,
+    "loadAverage": [
+      0.56,
+      0.78,
+      0.79
+    ],
+    "node": "v26.13.0"
+  },
+  "command": "npx tsx scripts/scale-harness.ts --case fleet-75m-churn --machines 75 --viewers 8 --sse-clients 4 --churn-machines 15 --churn-every-ms 3000 --duration-ms 8000 --json-out docs/scale-acceptance.json",
+  "suite": [
+    {
+      "name": "fleet-75m-churn",
+      "description": "75 machines with collector reconnect/replay churn and SSE reconnect/reset churn.",
+      "machines": 75,
+      "durationMs": 8000,
+      "sampleIntervalMs": 1000,
+      "recordsPerBatch": 1,
+      "viewers": 8,
+      "sseClients": 4,
+      "slowSseClients": 0,
+      "slowSsePauseAfterMs": 0,
+      "slowSsePauseMs": 0,
+      "historyIntervalMs": 1000,
+      "historyMetricSet": "standard",
+      "churnEveryMs": 3000,
+      "churnMachines": 15,
+      "replayRecords": 20
+    }
+  ],
+  "cases": [
+    {
+      "name": "fleet-75m-churn",
+      "description": "75 machines with collector reconnect/replay churn and SSE reconnect/reset churn.",
+      "config": {
+        "name": "fleet-75m-churn",
+        "description": "75 machines with collector reconnect/replay churn and SSE reconnect/reset churn.",
+        "machines": 75,
+        "durationMs": 8000,
+        "sampleIntervalMs": 1000,
+        "recordsPerBatch": 1,
+        "viewers": 8,
+        "sseClients": 4,
+        "slowSseClients": 0,
+        "slowSsePauseAfterMs": 0,
+        "slowSsePauseMs": 0,
+        "historyIntervalMs": 1000,
+        "historyMetricSet": "standard",
+        "churnEveryMs": 3000,
+        "churnMachines": 15,
+        "replayRecords": 20,
+        "warmupMs": 1500,
+        "maxCollectorConnections": 100,
+        "databaseBudgetBytes": 536870912
+      },
+      "host": {
+        "platform": "linux",
+        "release": "7.3.0-9-generic",
+        "arch": "x64",
+        "cpuModel": "AMD EPYC 7402P 24-Core Processor",
+        "logicalCores": 48,
+        "totalMemoryBytes": 130351214592,
+        "loadAverage": [
+          0.56,
+          0.78,
+          0.79
+        ],
+        "node": "v26.13.0"
+      },
+      "authorization": {
+        "anonymousDenied": true,
+        "scopedHistory": true,
+        "scopedSnapshot": true,
+        "scopedReset": true
+      },
+      "ingestion": {
+        "recordsSent": 930,
+        "recordsAccepted": 930,
+        "recordsRejected": 0,
+        "replayRecordsSent": 600,
+        "replayRecordsAccepted": 600,
+        "retryAcks": 0,
+        "unackedLiveRecords": 0,
+        "sendErrors": 0,
+        "ackLatencyMs": {
+          "count": 930,
+          "min": 9.86,
+          "avg": 37.89,
+          "p50": 33.83,
+          "p95": 63.44,
+          "p99": 114.87,
+          "max": 152.07
+        },
+        "sampleToCommitLagMs": {
+          "count": 930,
+          "min": 10,
+          "avg": 37.91,
+          "p50": 34,
+          "p95": 63,
+          "p99": 115,
+          "max": 152
+        },
+        "messagesSent": 1065,
+        "backpressureSkips": 0,
+        "connects": 105,
+        "reconnects": 30,
+        "reconnectFailures": 0,
+        "collectorRecoveryMs": {
+          "count": 30,
+          "min": 65.97,
+          "avg": 124.94,
+          "p50": 130.34,
+          "p95": 182.2,
+          "p99": 185.7,
+          "max": 185.7
+        }
+      },
+      "history": {
+        "queries": 69,
+        "ok": 69,
+        "rateLimited": 0,
+        "errors": 0,
+        "latencyMs": {
+          "count": 69,
+          "min": 3.88,
+          "avg": 11.5,
+          "p50": 9.6,
+          "p95": 26.22,
+          "p99": 30.96,
+          "max": 30.96
+        },
+        "series": {
+          "count": 69,
+          "min": 4,
+          "avg": 4,
+          "p50": 4,
+          "p95": 4,
+          "p99": 4,
+          "max": 4
+        },
+        "points": {
+          "count": 69,
+          "min": 8,
+          "avg": 32.87,
+          "p50": 24,
+          "p95": 92,
+          "p99": 100,
+          "max": 100
+        },
+        "truncated": 0,
+        "tiers": {
+          "raw": 69
+        }
+      },
+      "stream": {
+        "clients": 4,
+        "slowClients": 0,
+        "events": 52,
+        "snapshots": 4,
+        "updates": 40,
+        "resets": 8,
+        "bytes": 7695647,
+        "eventLagMs": {
+          "count": 52,
+          "min": 108,
+          "avg": 315.27,
+          "p50": 162,
+          "p95": 842,
+          "p99": 848,
+          "max": 848
+        },
+        "normalEventLagMs": {
+          "count": 52,
+          "min": 108,
+          "avg": 315.27,
+          "p50": 162,
+          "p95": 842,
+          "p99": 848,
+          "max": 848
+        },
+        "slowEventLagMs": {
+          "count": 0,
+          "min": 0,
+          "avg": 0,
+          "p50": 0,
+          "p95": 0,
+          "p99": 0,
+          "max": 0
+        },
+        "firstEventMs": {
+          "count": 12,
+          "min": 4.69,
+          "avg": 10.82,
+          "p50": 10.29,
+          "p95": 22.7,
+          "p99": 22.7,
+          "max": 22.7
+        },
+        "reconnects": 8,
+        "resetsAfterReconnect": 8,
+        "slowPauses": 0,
+        "slowDrops": 0,
+        "sseRecoveryMs": {
+          "count": 8,
+          "min": 4.7,
+          "avg": 7.93,
+          "p50": 8.14,
+          "p95": 12.54,
+          "p99": 12.54,
+          "max": 12.54
+        }
+      },
+      "hub": {
+        "baseline": {
+          "pid": 4068661,
+          "uptimeMs": 2411.99,
+          "hubRunId": "590bcb13-33c0-4678-bad4-c4e6151e4c15",
+          "eventLoopDelayMs": {
+            "p50": 10.11,
+            "p95": 11.13,
+            "p99": 28.85,
+            "max": 44.53
+          },
+          "eventLoopUtilization": 0.1224,
+          "cpuPercent": 37,
+          "cpuMs": {
+            "user": 726.22,
+            "system": 101.19
+          },
+          "rssBytes": 159789056,
+          "rssPeakBytes": 159789056,
+          "heapUsedBytes": 19570600,
+          "database": {
+            "bytes": 2746680,
+            "walBytes": 2509112,
+            "mainBytes": 237568
+          },
+          "store": {
+            "queuedRecords": 0,
+            "queuedBatches": 0,
+            "lastFlushMs": 1793753832716,
+            "lastFlushDurationMs": 2,
+            "committedRecords": 150,
+            "duplicateRecords": 0,
+            "rejectedRecords": 0,
+            "writeFailures": 0,
+            "lastWriteError": null,
+            "diskFullFailures": 0,
+            "dbBytes": 2746680,
+            "dbWalBytes": 2509112,
+            "dbBytesLimit": 536870912,
+            "retention": {
+              "lastRunAtMs": 0,
+              "lastRunDurationMs": 0,
+              "deletedRows": 0,
+              "pressure": false,
+              "effectiveRawCutoffMs": null,
+              "physicalBytes": 2746680,
+              "physicalLimitBytes": 536870912,
+              "physicalPressure": false,
+              "walBytes": 2509112
+            }
+          },
+          "liveClients": 0,
+          "sessions": 9,
+          "connectedMachines": 75,
+          "configuredMachines": 75
+        },
+        "window": {
+          "pid": 4068661,
+          "uptimeMs": 10431.17,
+          "hubRunId": "590bcb13-33c0-4678-bad4-c4e6151e4c15",
+          "eventLoopDelayMs": {
+            "p50": 10.11,
+            "p95": 16.25,
+            "p99": 34.18,
+            "max": 38.34
+          },
+          "eventLoopUtilization": 0.1453,
+          "cpuPercent": 17.3,
+          "cpuMs": {
+            "user": 1228.81,
+            "system": 157.98
+          },
+          "rssBytes": 179965952,
+          "rssPeakBytes": 179965952,
+          "heapUsedBytes": 17027672,
+          "database": {
+            "bytes": 7939784,
+            "walBytes": 4511432,
+            "mainBytes": 3428352
+          },
+          "store": {
+            "queuedRecords": 0,
+            "queuedBatches": 0,
+            "lastFlushMs": 1793753840710,
+            "lastFlushDurationMs": 24,
+            "committedRecords": 1380,
+            "duplicateRecords": 0,
+            "rejectedRecords": 0,
+            "writeFailures": 0,
+            "lastWriteError": null,
+            "diskFullFailures": 0,
+            "dbBytes": 7939784,
+            "dbWalBytes": 4511432,
+            "dbBytesLimit": 536870912,
+            "retention": {
+              "lastRunAtMs": 0,
+              "lastRunDurationMs": 0,
+              "deletedRows": 0,
+              "pressure": false,
+              "effectiveRawCutoffMs": null,
+              "physicalBytes": 7939784,
+              "physicalLimitBytes": 536870912,
+              "physicalPressure": false,
+              "walBytes": 4511432
+            }
+          },
+          "liveClients": 4,
+          "sessions": 9,
+          "connectedMachines": 75,
+          "configuredMachines": 75
+        },
+        "final": {
+          "pid": 4068661,
+          "uptimeMs": 13434.61,
+          "hubRunId": "590bcb13-33c0-4678-bad4-c4e6151e4c15",
+          "eventLoopDelayMs": {
+            "p50": 10.11,
+            "p95": 10.6,
+            "p99": 24.99,
+            "max": 38.24
+          },
+          "eventLoopUtilization": 0.0646,
+          "cpuPercent": 8.37,
+          "cpuMs": {
+            "user": 208.87,
+            "system": 42.59
+          },
+          "rssBytes": 181145600,
+          "rssPeakBytes": 181145600,
+          "heapUsedBytes": 20405600,
+          "database": {
+            "bytes": 8095528,
+            "walBytes": 4527912,
+            "mainBytes": 3567616
+          },
+          "store": {
+            "queuedRecords": 0,
+            "queuedBatches": 0,
+            "lastFlushMs": 1793753842709,
+            "lastFlushDurationMs": 23,
+            "committedRecords": 1530,
+            "duplicateRecords": 0,
+            "rejectedRecords": 0,
+            "writeFailures": 0,
+            "lastWriteError": null,
+            "diskFullFailures": 0,
+            "dbBytes": 8095528,
+            "dbWalBytes": 4527912,
+            "dbBytesLimit": 536870912,
+            "retention": {
+              "lastRunAtMs": 0,
+              "lastRunDurationMs": 0,
+              "deletedRows": 0,
+              "pressure": false,
+              "effectiveRawCutoffMs": null,
+              "physicalBytes": 8095528,
+              "physicalLimitBytes": 536870912,
+              "physicalPressure": false,
+              "walBytes": 4527912
+            }
+          },
+          "liveClients": 4,
+          "sessions": 9,
+          "connectedMachines": 75,
+          "configuredMachines": 75
+        },
+        "databaseGrowth": {
+          "bytes": 5348848,
+          "walBytes": 2018800,
+          "mainBytes": 3330048
+        }
+      },
+      "elapsedMs": 8006.82,
+      "artifacts": {
+        "directory": "/tmp/rigscope-scale-gc3kVr",
+        "kept": false,
+        "configPath": "/tmp/rigscope-scale-gc3kVr/hub-config.json",
+        "databasePath": "/tmp/rigscope-scale-gc3kVr/scale.sqlite"
+      }
+    }
+  ],
+  "limitations": [
+    "Collector payload values and cadence are synthetic; the hub, database, auth, SSE and History paths are real modules.",
+    "The hub child and all load generators share one host; the hub event loop is single-threaded, while load processes can use other cores. This is not distributed load.",
+    "History queries are synchronous on the hub event loop, so 'concurrent' viewers model overlapping HTTP requests, not parallel SQLite readers.",
+    "The measurement never contacts the live service; it uses a fresh temporary database and loopback ephemeral port.",
+    "A passing case is evidence for this host and workload, not an unlimited-capacity or latency guarantee."
+  ]
+}